Handbook
Documentation operating cadence (Hydration v2)
How the governed documentation intelligence layer runs day to day. Every cadence maps to concrete script invocations from the forge-platform root; none of them auto-promote — human reviewer decision manifests gate all…
Updated
Per build (every site rebuild / deploy)
| Step | Command |
|---|---|
| Emit source map | automatic — every generator writes website/docs_source_map.json |
| Docs-quality artifacts | python3 scripts/site_docs_artifacts.py --site-root <site>/website --site-name <site> (also run by deploy-websites.sh) |
| Scorecard + delta | python3 scripts/docs_scorecard.py (prints build-to-build delta; regressions, stale claims, and link rot append to the backlog) |
| Quality gates | python3 scripts/check_quality_gates.py (G1–G8; check_foundation.py runs the registry-scope gates on every foundation check) |
Per change signal (continuous ingest)
| Step | Command |
|---|---|
| Canonical repo changes | python3 scripts/adapters/adapter_markdown_repo.py |
| Design doc status transitions | python3 scripts/adapters/adapter_design_doc.py |
| External signals (T3/T4) | python3 scripts/adapters/adapter_external_note.py --source-id … --observed … --detail … |
| Search misses (log import) | python3 scripts/adapters/adapter_search_log.py --log … --source-id … |
| Plan responses | python3 scripts/hydration_planner.py (11-decision enum; conflicts block with a report) |
Unregistered sources quarantine automatically; quarantined events never plan.
Weekly content council (~30 min)
python3 scripts/hydration_cycle.py— full PDCA pass; read the cycle summary.- Review open plans in
docs-governance/plans/— approve, reject, or hold each. - Review conflict reports in
docs-governance/conflicts/— pick a winning source, update claims, unblock. - Triage
docs-governance/rehydration_backlog.jsonlopen items; close or schedule. - Record decisions as reviewer decision manifests where promotion follows.
Per release cycle
- Rerun claim extraction over changed strategic pages:
python3 scripts/extract_claims.py … python3 scripts/detect_drift.py— seed/page/claim drift after the release.- Promote approved packs:
python3 scripts/promote_hydration_pack.py --dry-run→ review output → run without--dry-run. - Rebuild + deploy affected sites (
./deploy-websites.shfrom the workspace root prints the scorecard delta in its summary).
Quarterly journey and prune audit
python3 scripts/agent_retrieval_eval.py— retrieval misses per persona.- Review
docs-governance/plans/archive-proposals/(generated byhydration_cycle.pyfor pages unreviewed > 365 days) — archive, merge, or rehydrate via manifests. - Refresh
persona_journey_map.yamlstages/journeys against real usage. - Re-run
python3 scripts/check_page_contract.py --pilot --strictand expand the contract-enforced page set.
Trust boundary (unchanged)
Scripts observe, plan, and report. Humans decide truth: claim status transitions, promotions, archives, and conflict resolutions all require a recorded reviewer decision.