docs(governance): start standalone OpenSpec change for doc lifecycle traceability

.claude/skills/development-workflow/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: development-workflow
+description: Use when executing change delivery work to run OpenSpec-default workflow checkpoints, TODO fallback, and evidence synchronization.
+---
+
+# Development Workflow
+
+## When to use
+Use this skill for any `bug` / `feature` / `refactor` delivery that must follow the repository documentation-first SOP.
+Invoke it before implementation starts and when closing the change lifecycle.
+
+Do not use this skill for document-only relocation/classification tasks; use `documentation-management` directly for those.
+
+**REQUIRED SUB-SKILL:** `documentation-management` for classification, placement, metadata, and archive moves.
+
+## Collaboration mode selection
+
+1. OpenSpec mode (default)
+- build from docs-first inputs: analysis + master TODO + updated design docs
+- bind one TODO slice to `openspec/changes/<change-id>/`
+- maintain `docs/features/<change-id>.md` as the single status source for that slice
+- treat OpenSpec artifacts as execution records; keep canonical outcomes written in `docs/**`
+
+2. TODO fallback mode (only if OpenSpec unavailable)
+- still start from analysis + master TODO + updated design docs
+- create `docs/features/<topic-slug>.md` with `mode: todo_fallback` and required `topic_slug` frontmatter
+- create dated gap/TODO pair in `docs/todos/`
+- once OpenSpec is available, migrate fallback assets into one or more OpenSpec slice changes
+
+## Required evidence block in feature aggregation doc
+
+Each active feature aggregation doc MUST contain an `## Evidence` section with at least:
+- commands executed (exact commands)
+- command results (pass/fail + key output summary)
+- behavior verification (happy path + changed error branch)
+- risks and rollback notes
+- review/merge-gate evidence links (review request, key review threads, merge gate result)
+
+Reference contract: `docs/guides/Evidence_Truth_Implementation_Strategy.md`.
+
+## Lifecycle checkpoints
+
+1. kickoff
+- classify request as `bug` / `feature` / `refactor`
+- choose collaboration mode (OpenSpec default, TODO fallback only when OpenSpec unavailable)
+- complete global analysis before execution
+- build/update a master TODO backlog that covers the full scope
+- update `docs/design/**` first (no implementation before design update)
+- create or refresh feature aggregation doc as the status source
+- initialize/refresh the required evidence block in feature aggregation doc before execution
+- for OpenSpec mode, select one TODO slice as current change scope
+- run `documentation-management` to validate type/path/frontmatter baseline
+
+2. execution-sync
+- OpenSpec mode: execute in small increments `TODO slice item -> OpenSpec task -> implementation -> evidence`
+- TODO fallback mode: execute in small increments `TODO item -> implementation -> evidence`, and record pending OpenSpec migration mapping
+- keep master TODO status and feature aggregation evidence aligned in all modes
+- after each completed task, update linked design/gap/TODO docs and implementation evidence
+- append command outputs and behavior-check results to the feature evidence block at task granularity
+- for large initiatives, continue by opening the next TODO slice in a new OpenSpec change instead of overloading one change
+
+3. verification
+- OpenSpec mode checks: `openspec validate`, `openspec status`, tests, and repo doc checks
+- TODO fallback mode checks: tests, repo doc checks, TODO ledger completeness, and migration debt note completeness
+- verify current OpenSpec slice only claims TODO items actually completed in this slice
+- verify coverage of interface contracts and error branches for changed behavior
+- verify status consistency: feature doc is source of truth, linked docs are non-conflicting
+- verify `docs/**` can stand alone as the current-state record without depending on OpenSpec internals
+- verify governance CI scope is complete (frontmatter by mode, link resolution, evidence block completeness, TODO->change mapping, checkpoint mapping)
+- verify feature evidence block includes commands, results, behavior verification, risks, rollback, and review links
+
+4. review-merge-gate
+- request review with explicit evidence links from the feature aggregation doc
+- process review feedback thread-by-thread and keep evidence section updated with fix commits
+- require explicit non-blocking merge gate signal (approval or equivalent repo policy signal) before archive
+- keep mailbox records linked: temporary coordination notes vs retained audit evidence
+
+5. completion-archive
+- mark work done in feature aggregation and related ledgers
+- run `documentation-management` archive actions
+- update TODO/archive indexes (for example `docs/todos/README.md` when applicable)
+- OpenSpec mode: complete OpenSpec archive when the change is finished
+- TODO fallback mode: archive fallback docs/ledgers and keep an explicit migration plan/status until OpenSpec migration is completed
+- if master TODO still has pending slices, keep initiative active and start next slice workflow
+- 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`, `review-merge-gate`, `completion-archive`)
+- evidence commands executed
+- evidence results summary (including changed happy path + error branch checks)
+- evidence file updates (design, TODO, OpenSpec tasks, feature aggregation)
+- review and merge-gate status
+- unresolved risks or migration debt

.claude/skills/documentation-management/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: documentation-management
+description: Use when classifying, creating, relocating, or archiving repository documents to enforce taxonomy, directory placement, and governance metadata contracts.
+---
+
+# Documentation Management
+
+## Authoritative inputs
+- `docs/governance/Documentation_Management_Model.md` defines repository governance contracts.
+- `docs/guides/Evidence_Truth_Implementation_Strategy.md` defines evidence-truth rollout and gate strategy.
+- This skill is the single execution entry for both documents; do not split them into a separate evidence-only skill unless responsibilities diverge beyond documentation governance.
+
+## 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
+
+This skill supersedes `documentation-lifecycle-governance` for documentation governance management responsibilities.
+
+## 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/` with mailbox class:
+  - `temporary_coordination`: short-lived thread notes, removable after cleanup
+  - `audit_evidence`: review/approval/decision evidence, retained and archived
+- archived assets -> `docs/features/archive/`, `docs/todos/archive/`, `docs/design/archive/`
+
+3. Enforce governance metadata
+- ensure frontmatter exists for governance-tracked docs
+- required keys (OpenSpec mode): `change_ids`, `doc_kind`, `topics`, `created`, `updated`, `status`
+- required keys (TODO fallback mode): `topic_slug`, `mode: todo_fallback`, `doc_kind`, `topics`, `created`, `updated`, `status`
+- required keys for mailbox docs: `owner_thread`, `cleanup_plan`, `mailbox_class`
+- when fallback assets are migrated into OpenSpec, add `change_ids` and retain `topic_slug` as historical linkage when useful
+
+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
+- `temporary_coordination` mailbox docs may be removed only after cleanup completion is recorded
+- `audit_evidence` mailbox docs MUST NOT be deleted; they must remain linked from feature evidence and archived as historical record
+- do not delete historical evidence unless explicitly approved
+
+5. Maintain lifecycle dependency definition
+- ensure documentation dependencies are explicit and consistent:
+  - `standards -> design update -> gap analysis -> master TODO -> feature aggregation -> execution evidence -> review/merge gate -> archive`
+
+6. Maintain planning-to-execution mapping
+- ensure master TODO ledger exists before execution slicing
+- for each OpenSpec change, record covered TODO subset (`todo_ids` or equivalent linkage)
+- prevent one change from claiming unrelated TODO scope
+- ensure review threads and merge-gate decisions are linked from feature evidence
+
+7. Keep CI gate scope complete (not skill-only)
+- enforce that CI checks include metadata, link resolution, evidence completeness, and TODO/change trace mapping
+- treat skill-file existence/mapping as one gate dimension, not the full governance gate
+- align checks and rollout with `docs/guides/Evidence_Truth_Implementation_Strategy.md`
+
+## Output expectations
+For each management action, provide:
+- affected files
+- old path -> new path mapping (if moved)
+- metadata fields changed
+- archive/lifecycle status change

.codex/skills/development-workflow/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: development-workflow
+description: Use when executing change delivery work to run OpenSpec-default workflow checkpoints, TODO fallback, and evidence synchronization.
+---
+
+# Development Workflow
+
+## When to use
+Use this skill for any `bug` / `feature` / `refactor` delivery that must follow the repository documentation-first SOP.
+Invoke it before implementation starts and when closing the change lifecycle.
+
+Do not use this skill for document-only relocation/classification tasks; use `documentation-management` directly for those.
+
+**REQUIRED SUB-SKILL:** `documentation-management` for classification, placement, metadata, and archive moves.
+
+## Collaboration mode selection
+
+1. OpenSpec mode (default)
+- build from docs-first inputs: analysis + master TODO + updated design docs
+- bind one TODO slice to `openspec/changes/<change-id>/`
+- maintain `docs/features/<change-id>.md` as the single status source for that slice
+- treat OpenSpec artifacts as execution records; keep canonical outcomes written in `docs/**`
+
+2. TODO fallback mode (only if OpenSpec unavailable)
+- still start from analysis + master TODO + updated design docs
+- create `docs/features/<topic-slug>.md` with `mode: todo_fallback` and required `topic_slug` frontmatter
+- create dated gap/TODO pair in `docs/todos/`
+- once OpenSpec is available, migrate fallback assets into one or more OpenSpec slice changes
+
+## Required evidence block in feature aggregation doc
+
+Each active feature aggregation doc MUST contain an `## Evidence` section with at least:
+- commands executed (exact commands)
+- command results (pass/fail + key output summary)
+- behavior verification (happy path + changed error branch)
+- risks and rollback notes
+- review/merge-gate evidence links (review request, key review threads, merge gate result)
+
+Reference contract: `docs/guides/Evidence_Truth_Implementation_Strategy.md`.
+
+## Lifecycle checkpoints
+
+1. kickoff
+- classify request as `bug` / `feature` / `refactor`
+- choose collaboration mode (OpenSpec default, TODO fallback only when OpenSpec unavailable)
+- complete global analysis before execution
+- build/update a master TODO backlog that covers the full scope
+- update `docs/design/**` first (no implementation before design update)
+- create or refresh feature aggregation doc as the status source
+- initialize/refresh the required evidence block in feature aggregation doc before execution
+- for OpenSpec mode, select one TODO slice as current change scope
+- run `documentation-management` to validate type/path/frontmatter baseline
+
+2. execution-sync
+- OpenSpec mode: execute in small increments `TODO slice item -> OpenSpec task -> implementation -> evidence`
+- TODO fallback mode: execute in small increments `TODO item -> implementation -> evidence`, and record pending OpenSpec migration mapping
+- keep master TODO status and feature aggregation evidence aligned in all modes
+- after each completed task, update linked design/gap/TODO docs and implementation evidence
+- append command outputs and behavior-check results to the feature evidence block at task granularity
+- for large initiatives, continue by opening the next TODO slice in a new OpenSpec change instead of overloading one change
+
+3. verification
+- OpenSpec mode checks: `openspec validate`, `openspec status`, tests, and repo doc checks
+- TODO fallback mode checks: tests, repo doc checks, TODO ledger completeness, and migration debt note completeness
+- verify current OpenSpec slice only claims TODO items actually completed in this slice
+- verify coverage of interface contracts and error branches for changed behavior
+- verify status consistency: feature doc is source of truth, linked docs are non-conflicting
+- verify `docs/**` can stand alone as the current-state record without depending on OpenSpec internals
+- verify governance CI scope is complete (frontmatter by mode, link resolution, evidence block completeness, TODO->change mapping, checkpoint mapping)
+- verify feature evidence block includes commands, results, behavior verification, risks, rollback, and review links
+
+4. review-merge-gate
+- request review with explicit evidence links from the feature aggregation doc
+- process review feedback thread-by-thread and keep evidence section updated with fix commits
+- require explicit non-blocking merge gate signal (approval or equivalent repo policy signal) before archive
+- keep mailbox records linked: temporary coordination notes vs retained audit evidence
+
+5. completion-archive
+- mark work done in feature aggregation and related ledgers
+- run `documentation-management` archive actions
+- update TODO/archive indexes (for example `docs/todos/README.md` when applicable)
+- OpenSpec mode: complete OpenSpec archive when the change is finished
+- TODO fallback mode: archive fallback docs/ledgers and keep an explicit migration plan/status until OpenSpec migration is completed
+- if master TODO still has pending slices, keep initiative active and start next slice workflow
+- 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`, `review-merge-gate`, `completion-archive`)
+- evidence commands executed
+- evidence results summary (including changed happy path + error branch checks)
+- evidence file updates (design, TODO, OpenSpec tasks, feature aggregation)
+- review and merge-gate status
+- unresolved risks or migration debt

.codex/skills/documentation-management/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: documentation-management
+description: Use when classifying, creating, relocating, or archiving repository documents to enforce taxonomy, directory placement, and governance metadata contracts.
+---
+
+# Documentation Management
+
+## Authoritative inputs
+- `docs/governance/Documentation_Management_Model.md` defines repository governance contracts.
+- `docs/guides/Evidence_Truth_Implementation_Strategy.md` defines evidence-truth rollout and gate strategy.
+- This skill is the single execution entry for both documents; do not split them into a separate evidence-only skill unless responsibilities diverge beyond documentation governance.
+
+## 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
+
+This skill supersedes `documentation-lifecycle-governance` for documentation governance management responsibilities.
+
+## 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/` with mailbox class:
+  - `temporary_coordination`: short-lived thread notes, removable after cleanup
+  - `audit_evidence`: review/approval/decision evidence, retained and archived
+- archived assets -> `docs/features/archive/`, `docs/todos/archive/`, `docs/design/archive/`
+
+3. Enforce governance metadata
+- ensure frontmatter exists for governance-tracked docs
+- required keys (OpenSpec mode): `change_ids`, `doc_kind`, `topics`, `created`, `updated`, `status`
+- required keys (TODO fallback mode): `topic_slug`, `mode: todo_fallback`, `doc_kind`, `topics`, `created`, `updated`, `status`
+- required keys for mailbox docs: `owner_thread`, `cleanup_plan`, `mailbox_class`
+- when fallback assets are migrated into OpenSpec, add `change_ids` and retain `topic_slug` as historical linkage when useful
+
+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
+- `temporary_coordination` mailbox docs may be removed only after cleanup completion is recorded
+- `audit_evidence` mailbox docs MUST NOT be deleted; they must remain linked from feature evidence and archived as historical record
+- do not delete historical evidence unless explicitly approved
+
+5. Maintain lifecycle dependency definition
+- ensure documentation dependencies are explicit and consistent:
+  - `standards -> design update -> gap analysis -> master TODO -> feature aggregation -> execution evidence -> review/merge gate -> archive`
+
+6. Maintain planning-to-execution mapping
+- ensure master TODO ledger exists before execution slicing
+- for each OpenSpec change, record covered TODO subset (`todo_ids` or equivalent linkage)
+- prevent one change from claiming unrelated TODO scope
+- ensure review threads and merge-gate decisions are linked from feature evidence
+
+7. Keep CI gate scope complete (not skill-only)
+- enforce that CI checks include metadata, link resolution, evidence completeness, and TODO/change trace mapping
+- treat skill-file existence/mapping as one gate dimension, not the full governance gate
+- align checks and rollout with `docs/guides/Evidence_Truth_Implementation_Strategy.md`
+
+## Output expectations
+For each management action, provide:
+- affected files
+- old path -> new path mapping (if moved)
+- metadata fields changed
+- archive/lifecycle status change