Documentation and teaching as completion criteria
Janus treats documentation and teaching as part of delivering software. The implementation owner updates them within the originating task, without waiting for a separate reminder. This procedure applies to agents and human contributors.
When updates are required
Section titled “When updates are required”| Delivered work | Public documentation | Monastery |
|---|---|---|
| Sprint or milestone | Progress/release note describing delivered scope, tested version, evidence, and limitations; reconcile affected references. | Account for every solid feature delivered. |
| Substantial implementation | Update affected reference or architecture pages and examples. | Correct affected lessons. |
| Solid new feature | Reference documentation and a worked tutorial, including supported profiles/targets and costs. | Add a new lesson with verified examples. |
| Behavior correction | Correct affected documentation, diagnostics, and examples. | Correct existing lessons; add a lesson if a new concept is introduced. |
| Internal-only work | Summarize it at sprint/milestone closure; individual internal commits need no new API page. | Record why teaching is unaffected. |
| Partial/speculative feature | State its actual availability and limits. | Do not teach unimplemented behavior as available. |
A solid feature is a coherent capability demonstrated end to end on its advertised configuration, with acceptance tests and documented limitations. Parser support alone is insufficient. A usable slice still qualifies when its larger parent feature remains unfinished.
What a closeout records
Section titled “What a closeout records”Language changes require implementation/tests, operational specifications, public documentation, and teaching material. A closeout links the actual repository revisions, public pages, lesson identifiers, and validation results. Operational documents without independent Git history use their paths and report identifiers. Documentation updates report the compiler version actually tested; they do not require an invented version bump.
Prepared changes, integrated changes, and published pages have different states:
- Prepared: concrete local changes and their validation exist.
- Landed: changes have integrated into the intended branch, with commit references. A feature-branch commit alone does not establish publication.
- Published: the matching deployment succeeded and the affected public page was checked.
- Blocked: a named remaining action, reason, and owner are recorded.
- Not required: the relevant exemption is explained. New solid features cannot exempt their lesson, and closing milestones cannot exempt their note.
Required work remaining means implementation finished; propagation pending.
It prevents feature/milestone completion and, for missing source layers,
language-change promotion to testing. Prepared work can be handed off while
integration or publication is pending; the feature remains open.
The docs repository already has a Forgejo workflow that deploys qualifying
main updates to Cloudflare Pages. Contributors follow the existing merge
rules and verify deployment before claiming the website is updated. These
agent/review obligations do not themselves install a new cross-repository bot.
Teaching before the interactive engine
Section titled “Teaching before the interactive engine”Monastery remains in prelaunch mock mode through the first two hardening milestones. Its live engine is deferred; lesson creation is mandatory as solid features arrive. Mock output does not verify a Janus program.
Each new lesson includes a worked example, prediction, exercise, expected behavior, and relevant failure cases. It identifies the tested compiler version, profile, and environment. Reference solutions and rejection examples are checked with the native compiler or existing test harness, independently of the browser runner. Native-only and hardware-specific lessons state their requirements explicitly.
Public docs are validated with npm run build in their repository. Monastery
uses npm run test:content and npm run build. Those checks establish content
structure and site generation, not Janus execution correctness.
The alpha hardening roadmap schedules the engine prototype for milestone 3 and launch readiness for milestone 4. This is a readiness sequence, not a launch-date commitment.