Doc-Lifecycle Design — canonical doc classes + creation→canonical→archive flow

Doc-Lifecycle Design — canonical doc classes + creation→canonical→archive flow

Authored S301a-8 (2026-06-05). Deliverable of TARGET-STATE-ARCHITECTURE.md §7 — the doc-creation WORKFLOW design that fixes the docs-site IA and the relocation set. Ratified decisions in §6 are Liam’s (this session); open items in §8.

Method (Liam’s framing): identify what the SDLC process actually needs — which doc classes, created when, by which step, living where, retired/archived how — then use the docs-site to enable that. Lifecycle first; IA follows; relocation set falls out.

---

1. The problem

docs/ grew organically: 15 top-level folders, ~900 files. Some are canonical living reference; some are per-task design history; some are session-transfer notes consumed once and never again; some are point-in-time evidence (audits, eval reports, UAT results) that fed a decision months ago. They are interleaved in one tree, which means:

• gitnexus/ccc index pollution (stale continuation prompts + workflow-evaluation corpus indexed alongside living docs);
• no retirement discipline — content is periodically hand-shovelled to an archive;
• the docs-site relocation question (“which folders move?”) was unanswerable because folders, not lifecycles, were the unit of decision.

2. SDLC production map — who creates what, when

Workflow step	Artefact produced	Class (§3)
Planner {N.1}	RESEARCH.md in the task spec dir	2
Planner {N.2}/{N.3}/{N.4}	PRODUCT.md / TECH.md / PLAN.md	2
Executor (behaviour-changing subtask)	updates to living reference/runbooks/ontology/etc.	1
Executor / Checker journals	<info added on …> blocks in the ledger	5
Checker (large sweeps)	standalone audit reports	4
Curator	roadmap/backlog/retro ledger writes	5
workflow-evaluator	efficiency/adjudication reports	4
UAT / eval runs	results docs + report JSONs	4
handoff	continuation prompt; retro entry; diary	3 / 5 / (external)
Orchestrator dispatch	cmux-briefs; OQ mailbox records	3
docubot / sync-source-docs	code→docs sync PRs to living docs	1
generators (stats, inventory, mirrors)	derived artefacts	6
(test inputs, not docs at all)	ITT/RFP template binaries etc.	7

3. The seven doc classes

#	Class	Lifecycle	Canonical home (target)
1	Canonical living reference — reference, runbooks, product-functionality, ontology, design, themes, handover-guides, durable test/e2e guides	Created/updated by Tasks; freshness-guarded (kpf:refresh-reference-docs, doc-freshness); retired explicitly to archive when superseded	Private docs-site spaces
2	Task-lifecycle docs — spec chain per ID-N (RESEARCH/PRODUCT/TECH/PLAN.md)	Created by Planner subtasks; living during the task; frozen at task close; kept forever (ratified §6.2). Research is {N.1} — the freestanding research/ folder dissolves	Private docs-site specs/ space
3	Session-transfer artefacts — continuation prompts, cmux-briefs, OQ records	Created at handoff/dispatch; consumed by the next session; value decays in days. Target model: scripted, not hand-authored (§7) — design DEFERRED to the workflow review	Interim: stay where they are (main repo / .claude/)
4	Point-in-time evidence — audits, workflow-evaluation corpus, UAT results, eval report JSONs, status/cutover reports	Write-once; feeds a decision (retro, backlog item, spec revision); rule: must terminate in a ledger reference, then archive	knowledge-hub-archive
5	Ledgers + mirrors — task-list/backlog/roadmap/retros JSON + per-record .md mirrors	Structured state, not prose docs. Substrate: ID-20 task-view patch server (replaces ledger-cli); mirrors become its render surface	Private docs-site repo, via ID-20
6	Generated/derived — codebase-stats, mcp-inventory, type-drift report	Regenerable ⇒ never canonical. Delete from docs/; baselines live as root dotfiles (.knip-baseline.json, .type-drift-baseline.json)	(none — deleted; target-state §3.6)
7	Test fixtures masquerading as docs — docs/testing/test-data/ ITT/RFP binaries	Not documentation: simulated client-file-server content (what a client drops for platform pickup). Feeds ID-80.2 forms-architecture work; disposition decided there	With the ingestion/test fixtures, per ID-80.2

Lifecycle rules

1. Class at birth. Every artefact a workflow step produces has a class assigned by the producing skill/template. Nothing lands in a generic folder.
2. Class 1/2 are the docs-site. Nothing else is site content.
3. Class 4 archive trigger = decision captured (ledger link exists), not age.
4. Class 3 is never canonical. It is workflow plumbing; the scripted model (§7) replaces hand-authoring; retention is a sweep, not curation.

4. Folder disposition (all 15 current docs/ folders)

Folder (files)	Class	Disposition
reference/ (273)	1 + 5 + 4	Living docs → docs-site reference/. Ledger JSONs + tasks/ backlog/ retros/ roadmap/ mirrors → ID-20 substrate. reference/workflow-evaluation/ → archive
runbooks/ (21)	1	→ docs-site runbooks/ (copied ✓)
product-functionality/ (35)	1	→ docs-site (copied ✓)
ontology/ (33)	1	→ docs-site (copied ✓); public repo keeps a sanitised subset only if needed by code/tests (target-state §2)
design/ (4)	1	→ docs-site (copied ✓)
themes/ (98)	1	→ docs-site (copied ✓); main-repo duplication ends once the bridge is proven (§6.3)
handover-guides/ (2)	1	→ docs-site (copied ✓)
specs/ (191)	2	→ docs-site specs/ (copied ✓). Keep forever. Legacy non-ID-N- dirs may bulk-archive
research/ (16)	2→4	Dissolves. Future research = {N.1} RESEARCH.md. Existing 16 files: any feeding live tasks stay until consumed; rest → archive
audits/ (29)	4	→ archive (after ledger-reference check)
workflow-evaluation/ (76)	4	→ archive (already ruled, target-state §3.4)
operations/ (9)	1/4 split	Durable procedures (re-ingestion-quality-protocol, blank-db-restore-matrix) → runbooks/; point-in-time (cutover-report-s182, status reviews, trackers) → archive. Folder dissolves
testing/ (21)	1/4/7 split	e2e/ durable guides → runbooks/ (private); uat/ results → archive; test-data/ → Class 7 per ID-80.2. Folder dissolves
continuation-prompts/ (116)	3	Interim: stays. Target per §7 workflow review; bulk history → archive at that point
generated/ (3)	6	Delete (target-state §3.6)

5. Docs-site IA consequence

Spaces = Class 1 + Class 2 only: reference/ runbooks/ product-functionality/ ontology/ design/ themes/ handover-guides/ specs/ (+ scaffolded decisions/ — reserve for ADRs; see §8 OQ-D).

Class 3/4/5/6/7 are not site content: archive repo, workflow homes, the ID-20 render surface, or deletion. This resolves the “which folders move” question that S301 §0.2.3 could not: folders were the wrong unit — lifecycle class is the unit.

6. Ratified decisions (Liam, S301a-8)

1. Continuation prompts / Class 3: do NOT bake the spec-dir CONTINUATION pattern (an ID-68-interim expedient — possibly itself a contributor to the S301a divergence). Instead: surface and investigate the previously-shared scripted-workflow repo before designing Class 3 → §7.
2. Closed-task specs: keep forever in the docs-site specs space. Only legacy pre-ID-convention dirs are bulk-archive candidates.
3. Public repo post-cutover: minimal docs. README + AGENTS.md + CLAUDE.md + harness-read files. No CONTRIBUTING.md. The specs/themes duplication in main ends once the KH_PRIVATE_DOCS_DIR bridge is proven. See §6.1 for the technical floor.
4. Test-data templates: platform-functionality fixtures (simulated client file-server content), not a privacy question. Tie disposition to ID-80.2 (forms extraction + storage architecture) — currently mis-outlined there; this feeds that re-scope.

6.1 The technical floor for “minimal public docs” (what genuinely must stay)

A file must stay in the public repo only if something reads it from the repo at runtime:

• Agent harness: README.md (GitHub landing), AGENTS.md, CLAUDE.md, .claude/** (skills/hooks/checks), .gitnexus/CLAUDE.md, .ast-dataflow/CLAUDE.md.
• CI gate inputs: .knip-baseline.json, .type-drift-baseline.json, reference-doc-paths.json — plus any test that asserts on docs/ paths (doc-freshness.test.ts, fixture-sync guards) must be reworked at cutover to target the bridge or move private. This is the relocation sweep’s job (target-state §6.7).
• Everything else — including e2e setup guides — moves private: agent sessions get context via the docs-site bridge; CI executes code, not prose. Liam’s “start at the docs-site” workflow assumption holds, with the harness-file exception above.

7. Class 3 — the scripted-artefact direction (deferred design)

Liam’s directive: recurring session artefacts (handoff/continuation, cmux-briefs) keep being hand-authored per session — the prior art is github.com/emeraldwalk/skills/tree/main/task-tracking (shared by Liam, researched 2026-05-29; fed the S279 friction cluster that became ID-65 ledger-CLI v3, now done). We adopted its task-management elements — script-only data integrity, scoped/minimal-diff writes, bulk-create, --file/stdin record input, self-sufficient-task discipline — into ledger-cli. Its scripts were explicitly deferred for future consideration: run_task_loop.sh (sequential claim→execute→complete orchestration loop over a task list, pluggable agent CLI), the next/claim cycle, commit-message generation from task records, and the mock-agent test harness. That deferred set is exactly the “scripted handoff” shape. The equivalent KH move:

• session-transfer state becomes commands over the ledger substrate (task-view patch server, ID-20) rather than free-form markdown;
• a “handoff” becomes a scripted state transition + generated summary, not a 75-line hand-written prompt;
• cmux-briefs template-generate from the dispatch record.

Action: wider workflow review — revisit the deferred emeraldwalk script set (orchestration loop, claim cycle, commit-message generation) against task-view’s patch server as the substrate; co-scope with the ID-20 sub-track. Until then continuation-prompts/cmux-briefs stay as-is (interim).

8. Open items

• OQ-A (ID-80.2): test-data fixture home + forms-architecture re-scope.
• OQ-B (workflow review): Class 3 scripted model — deferred emeraldwalk script set + ID-20 co-scope.
• OQ-C: archive-sweep mechanics for Class 4 (manual cadence vs handoff-step automation) — natural fit: the workflow review (§7).
• OQ-D: decisions/ space — adopt ADR practice (documentation-and-adrs skill) or drop the scaffold space.
• OQ-E: sanitised-ontology subset for public (does any code/test read ontology docs?) — relocation sweep answers.

9. Sequencing into ID-68 PRODUCT

This design supplies PRODUCT’s doc-class model (target-state §8). PRODUCT invariants to carry: the class taxonomy (§3), the lifecycle rules (§3.1–3.4), the public floor (§6.1), spaces=Class 1+2 (§5). The relocation set + docs-site IA work items derive from §4.