Special One Documentation Gate Workflow
This document is the detailed human-readable contract for the permanent automatic Documentation Helper startup gate.
The authoritative machine-readable contract lives in:
- `documentation/project/documentation-gate-policy.json`
The authoritative workflow entry points are:
- `AGENTS.md`
- `.agents/skills/grand-project-coordinator-ingestion/SKILL.md`
- `.agents/skills/grand-project-documentation-helper/SKILL.md`
Source-run IDs
- Use the exact verified Special One source-run identifier.
- The current known convention is `CMD-YYYYMMDD-NNN`.
- Do not invent synthetic round numbers.
- Do not assume identifiers are contiguous.
Source-run allocation guard
- Before a new Special One round is treated as started, the Coordinator must allocate a fresh source-run ID using the current date and the authoritative queue/ledger evidence.
- Inspect the command queue, ledger, and archive for existing IDs before assigning a candidate.
- Allocate the next unused `CMD-YYYYMMDD-NNN` sequence for the current date and register it before worker assignment.
- If the candidate already exists anywhere in authoritative evidence, stop startup and resolve the duplicate before proceeding.
- Do not silently reuse an issued, completed, failed, or historical source-run ID.
Automatic startup gate
Before each future Special One development round is treated as fully underway:
1. determine the current/new source-run identifier
2. determine the most recent completed prior source run
3. read the documentation round ledger
4. determine the latest documented source run
5. calculate the completed-run documentation backlog
6. invoke `MINION-10` automatically if backlog exists
7. process missing completed runs oldest to newest
8. validate each helper result, manifest, and ledger update
9. record the documentation gate result in structured run metadata and the final report
10. continue the development round
Explicit documentation requests
If the user asks to bring documentation current, update documentation, document the latest completed run, or equivalent:
- invoke `MINION-10` automatically
- calculate the backlog from the latest completed source run
- process missing completed runs oldest to newest
- return the new current-through state
Active-run exclusion
- Never document an active unfinished source run as completed project state.
- During an active run, document only through the latest completed prior source run.
Duplicate prevention
Before any real documentation update, check:
- exact source-run ID
- documentation round ledger
- existing manifests
- existing documentation update IDs
- existing human history files
- source-run fingerprint where available
- prior validation status
If the target already has a successful initial documentation update, return:
- `NO-OP - DOCUMENTATION ALREADY CURRENT`
If the records conflict, return:
- `DOCUMENTATION INCONSISTENCY - REVIEW REQUIRED`
Revision mode
A second documentation update for the same source run is allowed only when:
- the user explicitly requests a revision/correction; or
- a confirmed documentation defect requires correction
Revision behavior:
- preserve the original update
- preserve prior canonical document revisions
- create a new documentation update ID
- record the revision reason
- reference the prior update
- preserve audit history
Structured metadata
Each future Special One run must emit:
- `documentation_gate_status`
- `documentation_current_through_source_run`
- `documentation_target_source_runs`
- `documentation_helper_execution_ids`
- `documentation_update_ids`
- `documentation_manifest_paths`
- `documentation_changed_documents`
- `documentation_validation_status`
- `documentation_warnings`
- `documentation_review_items`
Canonical dashboard URL:
- `https://gpo.jamie.waltons.co.nz`