docs(governance): start standalone OpenSpec change for doc lifecycle traceability #126
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,30 @@ | ||
| --- | ||
| name: documentation-lifecycle-governance | ||
| description: Use when existing workflows reference a legacy single-entry documentation governance skill and you need a compatibility wrapper for management and workflow skills. | ||
| --- | ||
|
|
||
| # Documentation Lifecycle Governance | ||
|
|
||
| ## Purpose | ||
| This is a compatibility wrapper to preserve old references. | ||
|
|
||
| Use these two primary skills directly for new work: | ||
| - `documentation-management` | ||
| - `documentation-workflow` | ||
|
|
||
| ## Delegation contract | ||
|
|
||
| 1. Run `documentation-management` for: | ||
| - document classification and placement | ||
| - frontmatter and metadata checks | ||
| - archive path and retention policy enforcement | ||
|
|
||
| 2. Run `documentation-workflow` for: | ||
| - mode selection (OpenSpec default, TODO fallback) | ||
| - lifecycle checkpoints (`kickoff`, `execution-sync`, `verification`, `completion-archive`) | ||
| - evidence and status synchronization | ||
|
|
||
| 3. Compatibility guarantee: | ||
| - any workflow still invoking `documentation-lifecycle-governance` must execute the two skills above in this order: | ||
| 1) `documentation-management` | ||
| 2) `documentation-workflow` |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,42 @@ | ||
| --- | ||
| name: documentation-management | ||
| description: Use when classifying, creating, relocating, or archiving repository documents to enforce taxonomy, directory placement, and governance metadata contracts. | ||
| --- | ||
|
|
||
| # Documentation Management | ||
|
|
||
| ## When to use | ||
| Use this skill for documentation structure operations: | ||
| - create a new governance-tracked document | ||
| - move/rename documentation by type | ||
| - add or update frontmatter metadata | ||
| - archive completed documentation records | ||
|
|
||
| ## Core responsibilities | ||
|
|
||
| 1. Classify document kind | ||
| - `standard`, `design`, `feature`, `analysis`, `todo`, `temporary` | ||
|
|
||
| 2. Enforce type-to-path mapping | ||
| - `standard` -> `docs/guides/` or top-level governance rule docs | ||
| - `design` -> `docs/design/` | ||
| - `feature` -> `docs/features/` | ||
| - `analysis` / `todo` -> `docs/todos/` | ||
| - `temporary` -> `docs/mailbox/` | ||
| - archived assets -> `docs/features/archive/`, `docs/todos/archive/`, `docs/design/archive/` | ||
|
|
||
| 3. Enforce governance metadata | ||
| - ensure frontmatter exists for governance-tracked docs | ||
| - required keys: `change_ids`, `doc_kind`, `topics`, `created`, `updated`, `status` | ||
|
|
||
| 4. Enforce archive policy | ||
| - completed feature entries move to `docs/features/archive/` | ||
| - completed TODO/analysis entries move to `docs/todos/archive/` or be marked archived in index | ||
| - do not delete historical evidence unless explicitly approved | ||
|
|
||
| ## Output expectations | ||
| For each management action, provide: | ||
| - affected files | ||
| - old path -> new path mapping (if moved) | ||
| - metadata fields changed | ||
| - archive/lifecycle status change | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,49 @@ | ||
| --- | ||
| name: documentation-workflow | ||
| description: Use when executing documentation governance work to run lifecycle checkpoints, OpenSpec-default collaboration, TODO fallback, and evidence sync. | ||
| --- | ||
|
|
||
| # Documentation Workflow | ||
|
|
||
| ## When to use | ||
| Use this skill when documentation work must follow lifecycle checkpoints from kickoff to archive. | ||
|
|
||
| **REQUIRED SUB-SKILL:** `documentation-management` for classification, placement, metadata, and archive moves. | ||
|
|
||
| ## Collaboration mode selection | ||
|
|
||
| 1. OpenSpec mode (default) | ||
| - bind work to `openspec/changes/<change-id>/` | ||
| - maintain `docs/features/<change-id>.md` as the single status source | ||
|
|
||
| 2. TODO fallback mode (only if OpenSpec unavailable) | ||
| - create `docs/features/<topic-slug>.md` with `mode: todo_fallback` | ||
| - create dated gap/TODO pair in `docs/todos/` | ||
| - once OpenSpec is available, migrate fallback assets into an OpenSpec change | ||
|
|
||
| ## Lifecycle checkpoints | ||
|
|
||
| 1. kickoff | ||
| - confirm change/topic scope and collaboration mode | ||
| - create or refresh feature aggregation doc | ||
| - run `documentation-management` to validate type/path/frontmatter baseline | ||
|
|
||
| 2. execution-sync | ||
| - keep OpenSpec tasks, TODO status, and feature aggregation evidence aligned | ||
| - update linked design/gap/TODO docs per completed task | ||
|
|
||
| 3. verification | ||
| - run required checks (`openspec validate`, `openspec status`, and repo doc checks) | ||
| - verify status consistency: feature doc is source of truth, linked docs are non-conflicting | ||
|
|
||
| 4. completion-archive | ||
| - mark work done in feature aggregation and related ledgers | ||
| - run `documentation-management` archive actions | ||
| - ensure archived entries stay discoverable via index/evidence links | ||
|
|
||
| ## Output expectations | ||
| For each workflow run, report: | ||
| - mode used (`openspec` or `todo_fallback`) | ||
| - checkpoint completion (`kickoff`, `execution-sync`, `verification`, `completion-archive`) | ||
| - evidence commands executed | ||
| - unresolved risks or migration debt |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,22 @@ | ||
| # Feature Aggregation Docs | ||
|
|
||
| `docs/features/` stores one aggregation document per active change/topic. | ||
|
|
||
| ## Rules | ||
|
|
||
| 1. File naming | ||
| - OpenSpec mode: `docs/features/<change-id>.md` | ||
| - TODO fallback mode: `docs/features/<topic-slug>.md` | ||
|
|
||
| 2. Source of truth | ||
| - Aggregation document owns lifecycle status (`draft/active/done/archived`). | ||
| - Linked analysis/todo/design docs should not override this status. | ||
|
|
||
| 3. Required links | ||
| - OpenSpec artifacts (`proposal/design/specs/tasks`) or TODO fallback bundle | ||
| - Related design docs | ||
| - Gap analysis + TODO evidence | ||
| - Verification evidence (commands/results) | ||
|
|
||
| 4. Archive | ||
| - Move completed docs to `docs/features/archive/` after closeout. |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,36 @@ | ||
| --- | ||
| change_ids: ["enhance-doc-governance-traceability"] | ||
| doc_kind: feature | ||
| topics: ["documentation-governance", "traceability", "skills"] | ||
| created: 2026-02-28 | ||
| updated: 2026-02-28 | ||
| status: active | ||
| mode: openspec | ||
| --- | ||
|
|
||
| # Feature: enhance-doc-governance-traceability | ||
|
|
||
| ## Scope | ||
| Unify documentation management structure, lifecycle governance, and SOP-to-skill execution mapping. | ||
|
|
||
| ## OpenSpec Artifacts | ||
| - Proposal: `openspec/changes/enhance-doc-governance-traceability/proposal.md` | ||
| - Design: `openspec/changes/enhance-doc-governance-traceability/design.md` | ||
| - Specs: | ||
| - `specs/documentation-lifecycle-traceability/spec.md` | ||
| - `specs/design-reconstructability-governance/spec.md` | ||
|
There was a problem hiding this comment.
The spec artifact paths listed here are missing the Useful? React with 👍 / 👎.
Collaborator
Author
There was a problem hiding this comment. Fixed. Updated spec links in the feature aggregation entry to repository-root-resolvable paths:
There was a problem hiding this comment.
The feature aggregation doc is meant to be the traceability entry point, but the two spec references use Useful? React with 👍 / 👎.
Collaborator
Author
There was a problem hiding this comment. Fixed. Spec artifact references now point to real repository paths in the aggregation doc:
|
||
| - Tasks: `openspec/changes/enhance-doc-governance-traceability/tasks.md` | ||
|
|
||
| ## Governance Anchors | ||
| - `docs/governance/Documentation_Management_Model.md` | ||
| - `docs/guides/Documentation_First_Development_SOP.md` | ||
| - `.codex/skills/documentation-management/SKILL.md` | ||
| - `.codex/skills/documentation-workflow/SKILL.md` | ||
| - compatibility wrapper: `.codex/skills/documentation-lifecycle-governance/SKILL.md` | ||
|
|
||
| ## Evidence | ||
| - `openspec validate --changes enhance-doc-governance-traceability` | ||
| - `openspec status --change enhance-doc-governance-traceability --json` | ||
|
|
||
| ## Next Milestone | ||
| Implement tasks group 1-2 (taxonomy contract + standards alignment). | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,110 @@ | ||
| # Documentation Management Model | ||
|
|
||
| > Scope: Repository-wide documentation governance for design, analysis, feature lifecycle, standards, temporary notes, and archive. | ||
|
|
||
| ## 1. Governance Targets | ||
|
|
||
| The documentation system MUST satisfy both goals: | ||
| - Reconstructability: system behavior can be rebuilt from docs. | ||
| - Traceability: any active change can be traced end-to-end in minutes. | ||
|
|
||
| ## 2. Directory Taxonomy (Single Source) | ||
|
|
||
| | Layer | Path | Purpose | Lifecycle | | ||
| |---|---|---|---| | ||
| | Standards | `docs/guides/`, `docs/agent_rules.md`, `AGENTS.md` | Rules, constraints, SOP, collaboration protocol | stable + versioned | | ||
| | Design | `docs/design/` | Authoritative architecture/interface/module design | active + archived | | ||
| | Governance | `docs/governance/` | Governance model, branch rules, policy checkpoints | stable | | ||
| | Feature Aggregation | `docs/features/` | One aggregation doc per change/topic (single status source) | active -> archive | | ||
| | Analysis/TODO | `docs/todos/` | Gap analysis and execution TODO ledgers | active -> archive | | ||
| | Temporary | `docs/mailbox/` | Thread-local or short-lived communication artifacts | temporary -> archive/remove | | ||
| | Reference | `docs/appendix/` | Supporting references and non-normative materials | stable | | ||
| | Archives | `docs/design/archive/`, `docs/todos/archive/`, `docs/features/archive/` | Historical snapshots and closed records | immutable-ish | | ||
|
|
||
| ## 3. Document Types and Placement Rules | ||
|
|
||
| 1. Design docs: place under `docs/design/**`; must align with current implementation contract. | ||
| 2. Analysis docs: place under `docs/todos/` as dated gap analysis and TODO pairs. | ||
| 3. Feature docs: place under `docs/features/<change-id>.md`; this is the single source for feature/change status. | ||
|
There was a problem hiding this comment.
This placement rule requires feature docs to be named Useful? React with 👍 / 👎.
Collaborator
Author
There was a problem hiding this comment. Fixed. Feature-doc placement rule is now mode-aware to remove the naming conflict:
|
||
| 4. Standards docs: place under `docs/guides/` or top-level governance rule files. | ||
| 5. Temporary docs: place under `docs/mailbox/`; must be linked to an owner thread and cleanup plan. | ||
|
|
||
| ## 4. Lifecycle Dependencies | ||
|
|
||
| The default dependency chain is: | ||
|
|
||
| `standards -> feature aggregation -> design update -> gap analysis -> TODO -> execution -> evidence -> archive` | ||
|
There was a problem hiding this comment.
The canonical governance chain here requires Useful? React with 👍 / 👎.
Collaborator
Author
There was a problem hiding this comment. Fixed. Lifecycle dependency order is now aligned with SOP sequence and no longer places feature aggregation ahead of design/gap/TODO.
|
||
|
|
||
| Status transitions: | ||
| - `draft` -> `active` -> `done` -> `archived` | ||
| - only aggregation docs own lifecycle state; linked docs SHOULD NOT duplicate conflicting status values. | ||
|
|
||
| ## 5. Collaboration Modes | ||
|
|
||
| ### 5.1 OpenSpec Mode (Default) | ||
|
|
||
| Use this whenever OpenSpec is available: | ||
| 1. Create/continue `openspec/changes/<change-id>/`. | ||
| 2. Create/update `docs/features/<change-id>.md` and link proposal/design/specs/tasks. | ||
| 3. Execute tasks iteratively; write evidence into feature aggregation + TODO ledger. | ||
| 4. Verify with tests/checks; update docs consistency. | ||
| 5. Archive change and migrate feature doc to `docs/features/archive/` when complete. | ||
|
|
||
| ### 5.2 No-OpenSpec Fallback Mode (TODO-driven) | ||
|
|
||
| Use only when OpenSpec cannot be used (tooling/environment constraint): | ||
| 1. Create `docs/features/<topic-slug>.md` with `mode: todo_fallback` in frontmatter. | ||
| 2. Create dated gap/TODO pair in `docs/todos/`. | ||
| 3. Execute against TODO checklist with evidence updates per task. | ||
| 4. When OpenSpec becomes available, migrate fallback assets into an OpenSpec change and link migration evidence. | ||
|
|
||
| ## 6. Frontmatter Contract (Governance-tracked docs) | ||
|
|
||
| Governance-tracked docs SHOULD include frontmatter with: | ||
|
There was a problem hiding this comment.
This governance model makes frontmatter optional ( Useful? React with 👍 / 👎.
Collaborator
Author
There was a problem hiding this comment. Fixed. Frontmatter requirement was tightened from SHOULD to MUST in the governance model:
|
||
|
|
||
| ```yaml | ||
| --- | ||
| change_ids: ["<change-id>"] | ||
| doc_kind: feature|analysis|todo|standard|temporary | ||
|
There was a problem hiding this comment.
The governance contract marks design docs as in-scope ( Useful? React with 👍 / 👎.
Collaborator
Author
There was a problem hiding this comment. Fixed. Added design to the doc_kind contract enum:
|
||
| topics: ["..."] | ||
| created: YYYY-MM-DD | ||
| updated: YYYY-MM-DD | ||
| status: draft|active|done|archived | ||
| --- | ||
| ``` | ||
|
|
||
| Notes: | ||
| - `status` on non-aggregation docs is informational only. | ||
| - Aggregation doc is the status source of truth. | ||
|
|
||
| ## 7. Checkpoint-to-Skill Mapping | ||
|
|
||
| Required lifecycle checkpoints MUST be skillized: | ||
| - kickoff | ||
| - execution-sync | ||
| - verification | ||
| - completion-archive | ||
|
|
||
| Skill contract (minimum two skills): | ||
| - management skill: `.codex/skills/documentation-management/SKILL.md` | ||
| - workflow skill: `.codex/skills/documentation-workflow/SKILL.md` | ||
| - compatibility wrapper (legacy): `.codex/skills/documentation-lifecycle-governance/SKILL.md` | ||
|
|
||
| Checkpoint mapping: | ||
| - kickoff -> `documentation-workflow` (mode/scope) + `documentation-management` (baseline metadata/path) | ||
| - execution-sync -> `documentation-workflow` (evidence/status sync) + `documentation-management` (metadata consistency) | ||
| - verification -> `documentation-workflow` (gate/check commands + status conflict detection) | ||
| - completion-archive -> `documentation-workflow` (closure) + `documentation-management` (archive move and retention policy) | ||
|
|
||
| CI MUST validate: | ||
| - required skill files exist, | ||
| - checkpoint mapping is declared, | ||
| - required assets and linkages are present. | ||
|
|
||
| ## 8. Effectiveness Criteria | ||
|
|
||
| Governance is considered effective when: | ||
| - active change context can be located in <= 5 minutes, | ||
| - traceability mapping completeness >= 95%, | ||
| - stale/unlinked governance docs trend down each iteration, | ||
| - archive migration occurs within one iteration after completion. | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The metadata contract makes
change_idsmandatory for all governance-tracked docs, but the same change introduces a TODO fallback mode that starts fromdocs/features/<topic-slug>.mdwhen OpenSpec is unavailable (i.e., before a change-id exists). This creates a hard rule conflict: fallback docs cannot satisfy both instructions, and any future frontmatter gate will incorrectly fail valid fallback workflows. Add a defined fallback primary key (or an explicit temporary exception) until migration to OpenSpec assigns a change-id.Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Fixed by making metadata contract mode-aware for fallback.
Commit: 34a9a9d