administrator/DocForge2
1
0
Fork 0
Code Issues Pull requests Projects Releases 2 Packages Wiki Activity Actions Pages

docs: adopt release-candidate closeout cadence

Browse source
This commit is contained in:
Andraxion 2026-07-28 18:23:11 -04:00
parent 7bc2ac1e3f
commit bb13258861
4 changed files with 62 additions and 9 deletions
Download patch file Download diff file Expand all files Collapse all files

22
docs/PROJECT_ONBOARDING.md
View file

@ -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

36
docs/USER_MANUAL.md
View file

@ -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.