diff --git a/AGENTS.md b/AGENTS.md index ba7532e..6165716 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -15,6 +15,14 @@ conflicts fail-closed. - Prefer one synchronized bootstrap, one atomic proposal registration, one reviewed diff, and one exact hash-bound application over caller-managed operation chaining. +- Read canonical documentation during intake, but keep it read-only while implementation and + focused testing are still changing the candidate. +- Freeze and validate one release candidate before registering documentation changes. After the + candidate is green, perform one atomic documentation closeout, run documentation-only + validation, and then publish the final revision. +- Allow at most one narrow evidence-only documentation correction after deployment. If validation + finds an implementation defect, abandon or rebase the proposal and return to implementation + instead of documenting a failed candidate. - Keep dependencies small and pinned by compatible major version. - Run strict `pyright`, `npm run lint:web`, formatting, Ruff, compilation, focused tests, and the complete warning-strict test suite before closing a gate. diff --git a/README.md b/README.md index 4c3ec5f..7b80a92 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,11 @@ declared manuals, visualizes project structure, and manages reviewable documenta DocForge never treats indexed text as instructions. It does not run shell commands, mutate Git, build applications, deploy, publish, or select projects globally. +For implementation projects, the recommended cadence is to read canonical documentation during +intake, keep it read-only through implementation and focused testing, freeze and validate a release +candidate, then perform one atomic documentation closeout before the final commit and tag. This +keeps the manual authoritative without using it as an implementation notebook. + ## Release 1 DocForge 1.0.0 is the first stable product release. It combines the project-scoped graph, CLI and diff --git a/docs/PROJECT_ONBOARDING.md b/docs/PROJECT_ONBOARDING.md index 2a30640..90a75ef 100644 --- a/docs/PROJECT_ONBOARDING.md +++ b/docs/PROJECT_ONBOARDING.md @@ -255,6 +255,28 @@ layout. Done when a developer unfamiliar with the repository can use DocForge without loading the entire manual or inventing another documentation workflow. +### 11. Release-candidate documentation cadence + +- [ ] Read the relevant canonical nodes during intake. +- [ ] Record the expected documentation impact in the working plan. +- [ ] Keep canonical sources and DocForge proposals unchanged during implementation and focused + test loops. +- [ ] Freeze one release candidate after implementation stops changing. +- [ ] Run the complete project gate, deployment preflight, candidate deployment, live checks, and + release-identity checks before proposing documentation updates. +- [ ] Return to implementation when candidate validation fails. +- [ ] Register one atomic changeset that covers every affected canonical node after the candidate + is green. +- [ ] Inspect the exact diff and previews, then apply only the reviewed changeset hash. +- [ ] Run documentation-only validation and render checks after application. +- [ ] Permit at most one narrow evidence-only correction for facts that could not exist before + deployment. +- [ ] Commit, tag, and publish the final revision only after implementation and canonical + documentation agree. + +Done when documentation describes the verified release candidate instead of intermediate attempts, +and the project normally performs one canonical documentation write per release slice. + ## CLI and MCP boundary Initial assessment and scaffolding belong to the CLI because an MCP server cannot be registered diff --git a/docs/USER_MANUAL.md b/docs/USER_MANUAL.md index 26e5e4d..6048c36 100644 --- a/docs/USER_MANUAL.md +++ b/docs/USER_MANUAL.md @@ -579,17 +579,35 @@ The application call requires `changeset_id` and `expected_changeset_hash`. Alwa inspect the final diff after the last proposal mutation. Apply that exact hash. A proposal mutation creates a new hash, so an earlier approval cannot silently apply later content. -Recommended agent sequence: +Recommended release-candidate sequence: 1. Call `docforge_bootstrap`. It synchronizes derived state and reports the exact fixed binding. -2. Read the relevant context and implementation. -3. Make and verify one coherent implementation slice. -4. Call `docforge_sync`. This is a no-op when the index is already current. -5. Call `docforge_register_changes` once with the complete operation list. -6. Inspect the structured diff and preview. -7. Obtain human approval for the final changeset hash when required by the client workflow. -8. Call `docforge_apply_changeset` with that exact hash. -9. Call `docforge_bootstrap` to verify the new canonical and derived identity. +2. Read only the relevant canonical context, implementation, configuration, tests, and release + rules. +3. Record the expected documentation impact in the working plan. Do not create or apply a + changeset yet. +4. Implement and run focused checks iteratively. Canonical documentation remains read-only during + this loop. +5. Freeze one release candidate after implementation stops changing. +6. Run the complete project gate, deployment preflight, candidate deployment, live checks, data + integrity checks, and release-identity checks. +7. If candidate validation fails, return to implementation. Do not document the failed candidate. +8. Call `docforge_sync` once after the candidate is green. +9. Call `docforge_register_changes` once with the complete operation list for every affected + canonical node. +10. Inspect the structured diff and every required preview. +11. Obtain human approval for the final changeset hash when required by the client workflow. +12. Call `docforge_apply_changeset` with that exact hash. +13. Run documentation-only validation and render checks. +14. Call `docforge_bootstrap` to verify the new canonical and derived identity. +15. Commit, tag, and publish the final revision containing both the verified implementation and + canonical documentation. + +This cadence separates documentation intake from documentation publication. It avoids repeatedly +rewriting the manual around intermediate implementation states. One second documentation write is +allowed only for a narrow evidence correction that could not exist before deployment. If a late +check exposes an implementation defect, abandon or rebase the pending proposal and return to the +implementation loop. The older create-and-append tools remain supported for interactive proposal construction. `docforge_register_changes` avoids intermediate empty changesets and caller-managed hash chaining.