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

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

@@ -0,0 +1,93 @@
+---
+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)
+
+## 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,65 @@
+---
+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
+
+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
+
+## Output expectations
+For each management action, provide:
+- affected files
+- old path -> new path mapping (if moved)
+- metadata fields changed
+- archive/lifecycle status change

AGENTS.md

@@ -9,6 +9,11 @@
 - Agent-driven development MUST follow documents under `docs/guides/` first, especially:
   - `docs/guides/Development_Constraints.md`
   - `docs/guides/Documentation_First_Development_SOP.md`
+- Documentation placement, lifecycle, and archive handling MUST follow:
+  - `docs/governance/Documentation_Management_Model.md`
+- Documentation governance tasks SHOULD use:
+  - `.codex/skills/documentation-management/SKILL.md`
+  - `.codex/skills/development-workflow/SKILL.md`
 - Code implementation MUST align with `docs/design/` as the latest full design source of truth.
 - If design and implementation diverge, update design docs first, then execute gap analysis before coding.
 - Every design doc that governs implementation MUST explicitly contain:
@@ -18,8 +23,8 @@
   - key interfaces
   - exception/error handling
 - For any bug fix, feature, or refactor, follow the SOP sequence:
-  1. update design docs
-  2. generate design-code gap analysis
-  3. derive TODO list from the analysis
-  4. execute fixes via OpenSpec workflow task-by-task
+  1. perform full-scope analysis and create a master TODO backlog
+  2. update design docs and governance docs (docs are canonical)
+  3. slice TODO backlog into one or more OpenSpec changes
+  4. execute fixes via OpenSpec workflow task-by-task per slice
   5. update TODO/evidence and archive analysis artifacts

docs/README.md

@@ -41,6 +41,8 @@
    ├── /CONTRIBUTING_AI.md (AI Agent 协作规范)
    ├── guides/Development_Constraints.md (开发约束清单)
    ├── guides/Documentation_First_Development_SOP.md (文档先行 SOP，Bug/Feature/Refactor 必走)
+   ├── governance/Documentation_Management_Model.md (文档目录分层、生命周期、OpenSpec/TODO 双模式协作)
+   ├── features/README.md (特性聚合文档规范与归档规则)
    └── design/Design_Doc_Minimum_Standard.md (设计文档最小完备标准)
 ```
 
@@ -91,6 +93,8 @@
 | `guides/Engineering_Practice_Guide_Sandbox_and_WORM.md` | 工程实践指南：沙箱执行隔离（seccomp/网络/镜像）、WORM 落地与核查 |
 | `guides/Development_Constraints.md` | 开发约束：架构不破坏、测试必备、日志/命名/复用/信任边界等硬性要求 |
 | `guides/Documentation_First_Development_SOP.md` | 文档先行 SOP：先设计文档、再 gap 分析、再 TODO、再 OpenSpec 修复、再归档 |
+| `governance/Documentation_Management_Model.md` | 文档管理模型：目录分层、文档类型规则、生命周期依赖、OpenSpec/无 OpenSpec 协作 |
+| `features/README.md` | 特性聚合文档规范：单一状态源、证据回写与归档迁移 |
 | `guides/Tool_Approval_Memory.md` | 工具审批记忆使用指南：pending/grant/deny/revoke、scope/matcher、持久化与接线方式 |
 
 ---
@@ -290,14 +294,26 @@ docs/
 │       ├── Interface_Layer_Design_v1.1_MCP_and_Builtin.md
 │       ├── ARCHITECTURE_COMPARISON.md
 │       └── ...（更多历史文档）
+├── features/
+│   ├── README.md
+│   ├── <change-id>.md（每个 change 一个聚合文档）
+│   └── archive/
+├── governance/
+│   ├── Documentation_Management_Model.md
+│   └── branch-protection.md
 ├── guides/
 │   ├── Development_Constraints.md
+│   ├── Documentation_First_Development_SOP.md
 │   └── Engineering_Practice_Guide_Sandbox_and_WORM.md
+├── todos/
+│   ├── YYYY-MM-DD_<topic>_design_code_gap_analysis.md
+│   ├── YYYY-MM-DD_<topic>_design_code_gap_todo.md
+│   └── archive/
 └── appendix/
     └── Appendix_Industrial_Security_and_Auditing.md
 ```
 
 ---
 
-*最后更新：2026-02-27*
+*最后更新：2026-02-28*
 *维护者：DARE Framework Team*

docs/agent_rules.md

@@ -8,6 +8,10 @@ These rules apply to all agent-generated changes in this repository.
 3. 不得修改公共接口/数据结构，除非任务明确且给出影响分析。
 4. 必须补测试或更新测试，并附上本地/CI 的测试证据。
 5. 任何跳过测试（skip/only/exclude）必须说明理由并经过 review。
+6. 文档治理任务必须遵循 `docs/governance/Documentation_Management_Model.md` 的目录分层与生命周期规则。
+7. 默认采用 OpenSpec 协作；OpenSpec 不可用时仅可使用 TODO-driven 回退模式，并需补迁移证据。
+8. 文档创建/迁移/归档时必须执行双技能流程：`.codex/skills/documentation-management/SKILL.md` + `.codex/skills/development-workflow/SKILL.md`。
+9. `docs/features/<change-id>.md` 是特性状态单一真相源，其他文档不得写冲突状态。
 
 ## Operating Notes
 - Keep diffs small to reduce merge conflicts in multi-agent parallel work.

docs/design/Design_Reconstructability_Traceability_Matrix.md

@@ -27,3 +27,11 @@
 1. `Plan->Execute` 的 `APPROVE_REQUIRED` 仍以 fail-fast 为主，需与 ToolLoop 语义统一。
 2. Hook payload schema 跨模块 contract 仍在收敛。
 3. 文档治理链路已建立，但自动化漂移校验需要持续补强。
+
+## Governance 聚合锚点（新增）
+
+> 说明：治理类 change 需要在本矩阵中补充 `feature aggregation` 锚点，确保从能力声明可直接跳转到变更级证据入口。
+
+| Capability | Feature Aggregation Anchor | OpenSpec Change |
+|---|---|---|
+| Documentation-first 治理闭环 | `docs/features/enhance-doc-governance-traceability.md` | `openspec/changes/enhance-doc-governance-traceability/` |

docs/features/README.md

@@ -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.

docs/features/enhance-doc-governance-traceability.md

@@ -0,0 +1,56 @@
+---
+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:
+  - `openspec/changes/enhance-doc-governance-traceability/specs/documentation-lifecycle-traceability/spec.md`
+  - `openspec/changes/enhance-doc-governance-traceability/specs/design-reconstructability-governance/spec.md`
+- 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/development-workflow/SKILL.md`
+
+## Evidence
+
+### Commands
+- `openspec validate --changes enhance-doc-governance-traceability`
+- `openspec status --change enhance-doc-governance-traceability --json`
+
+### Results
+- validate: passed (all changes validated).
+- status: `isComplete: true` for `enhance-doc-governance-traceability`.
+
+### Behavior Verification
+- Happy path: governance flow remains `analysis -> master TODO -> OpenSpec slice execution` with docs as canonical source.
+- Error/fallback path: TODO fallback metadata now requires `mode: todo_fallback` + `topic_slug`, with explicit migration back to OpenSpec.
+
+### Risks and Rollback
+- Risk: CI checks not yet fully implemented as scripts may leave policy drift windows.
+- Rollback: keep contract wording changes, temporarily downgrade new CI gate checks to warning if false positives block delivery.
+
+### Review and Merge Gate Links
+- Review request: `https://github.com/zts212653/Deterministic-Agent-Runtime-Engine/pull/126#issuecomment-3976690386`
+- Key owner feedback: `https://github.com/zts212653/Deterministic-Agent-Runtime-Engine/pull/126#issuecomment-3976707233`
+- Active fix threads:
+  - `https://github.com/zts212653/Deterministic-Agent-Runtime-Engine/pull/126#discussion_r2867257929`
+  - `https://github.com/zts212653/Deterministic-Agent-Runtime-Engine/pull/126#discussion_r2867257932`
+
+## Next Milestone
+Implement tasks group 1-2 (taxonomy contract + standards alignment).