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

.codex/skills/documentation-lifecycle-governance/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: documentation-lifecycle-governance
+description: Use when creating, updating, relocating, or archiving repository docs to enforce taxonomy, lifecycle, and OpenSpec/TODO collaboration rules.
+---
+
+# Documentation Lifecycle Governance
+
+## When to use
+Use this skill when any documentation asset is created or modified.
+
+## Core workflow
+
+1. Classify the document type:
+- design / analysis / todo / feature / standard / temporary
+
+2. Place in the correct directory:
+- design -> `docs/design/`
+- analysis/todo -> `docs/todos/`
+- feature aggregation -> `docs/features/`
+- standard -> `docs/guides/` or governance rule files
+- temporary -> `docs/mailbox/`
+
+3. Link lifecycle dependencies:
+- standards -> feature -> design -> analysis -> TODO -> execution -> evidence -> archive
+
+4. Choose collaboration mode:
+- OpenSpec mode (default): bind doc to `openspec/changes/<change-id>/`
+- TODO fallback mode: use dated TODO bundle and add migration plan to OpenSpec
+
+5. Enforce governance metadata:
+- add/update frontmatter for governance-tracked docs
+- ensure aggregation document is the single status source
+
+6. Verify before completion:
+- run documentation checks (OpenSpec status/validate + repo doc checks)
+- ensure links and evidence paths are resolvable
+
+7. Archive policy:
+- move completed feature docs to `docs/features/archive/`
+- move completed TODO bundles to `docs/todos/archive/`
+- never delete historical evidence without explicit governance approval
+
+## Output expectations
+For each doc governance task, produce:
+- affected files list
+- lifecycle status transition
+- evidence commands executed
+- remaining open questions/risk

AGENTS.md

@@ -9,6 +9,10 @@
 - 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-lifecycle-governance/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:

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-lifecycle-governance/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,34 @@
+---
+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`
+- 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-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).

docs/governance/Documentation_Management_Model.md

@@ -0,0 +1,98 @@
+# 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.
+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`
+
+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:
+
+```yaml
+---
+change_ids: ["<change-id>"]
+doc_kind: feature|analysis|todo|standard|temporary
+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
+
+Implementation is defined by:
+- skill file: `.codex/skills/documentation-lifecycle-governance/SKILL.md`
+- CI checks that validate presence and linkage of required assets.
+
+## 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.

docs/guides/Development_Constraints.md

@@ -10,9 +10,12 @@
 
 ## 文档先行硬门禁（新增，强制）
 - Agent 开发必须先遵循 `docs/guides/` 约束，最低要求：`Development_Constraints.md` + `Documentation_First_Development_SOP.md`。
+- 文档管理方式必须遵循 `docs/governance/Documentation_Management_Model.md`（目录分层、文档类型放置、生命周期迁移）。
 - 所有代码开发以 `docs/design/` 全量最新设计为准；若实现与文档冲突，必须先更新文档再改代码。
 - 设计文档必须可独立重建实现：至少显式描述总体架构、核心流程、数据结构、关键接口、异常错误处理（详见 `docs/design/Design_Doc_Minimum_Standard.md`）。
 - 任何 Bug/新增 Feature/重构，必须先执行“文档更新 + gap 分析 + TODO 拆解”，再按 OpenSpec 流程逐项落地。
+- 默认采用 OpenSpec 协作；仅在 OpenSpec 不可用时允许 TODO-driven 回退模式，并必须在 OpenSpec 恢复后完成迁移回写。
+- 任何治理类文档任务必须使用统一技能流程（`.codex/skills/documentation-lifecycle-governance/SKILL.md`）或等价自动化流程。
 - 禁止“先写代码后补文档”；除紧急止血修复外，文档缺失视为任务未开始。紧急修复需在 24 小时内补齐文档与 gap 分析。
 
 ## 设计准则（高内聚、低耦合）

docs/guides/Documentation_First_Development_SOP.md

@@ -19,13 +19,15 @@
 ## 2. 产物规范（必须）
 
 - 设计文档：`docs/design/**`
+- 特性聚合文档：`docs/features/<change-id>.md`（状态单一真相源）
 - 设计质量标准：`docs/design/Design_Doc_Minimum_Standard.md`
 - 差异分析：`docs/todos/YYYY-MM-DD_<topic>_design_code_gap_analysis.md`
 - 执行清单：`docs/todos/YYYY-MM-DD_<topic>_design_code_gap_todo.md`
 - OpenSpec 变更：`openspec/changes/<change-id>/{proposal.md,design.md,tasks.md}`
 - 归档产物：分析文档、TODO 文档在完成后标记 `done/archived`，并补证据链接。
 - 可重建追踪矩阵：`docs/design/Design_Reconstructability_Traceability_Matrix.md`
 - 重建执行 SOP：`docs/guides/Design_Reconstruction_SOP.md`
+- 文档治理模型：`docs/governance/Documentation_Management_Model.md`
 
 ## 3. 标准流程（一步不可省）
 
@@ -96,3 +98,34 @@
    - 归档路径统一使用日期前缀（`YYYY-MM-DD-...`）。
    - 归档条目必须包含对应 OpenSpec change 路径与验证证据。
 4. 若连续两轮发现同类文档漂移，必须新增自动化校验并接入 CI。
+
+## 7. 协作模式（必须显式声明）
+
+### Mode A: OpenSpec 模式（默认）
+
+适用于 OpenSpec 可用场景，执行顺序如下：
+1. 建立/选择 `openspec/changes/<change-id>/`。
+2. 创建或更新 `docs/features/<change-id>.md`，并登记 proposal/design/specs/tasks 链接。
+3. 按 OpenSpec tasks 逐项执行，每个任务回写证据到 feature 聚合文档与 TODO 文档。
+4. 完成后执行 verify + archive，并迁移聚合文档到 `docs/features/archive/`。
+
+### Mode B: 无 OpenSpec 回退（TODO-driven）
+
+仅在 OpenSpec 不可用（工具/环境受限）时使用：
+1. 创建 `docs/features/<topic-slug>.md`，并在 frontmatter 声明 `mode: todo_fallback`。
+2. 创建日期化 gap/todo 文档对（`docs/todos/`）。
+3. 以 TODO 清单推进并持续回写 evidence。
+4. OpenSpec 可用后，必须补迁移：将 fallback 资产映射到新的 `openspec/changes/<change-id>/` 并记录迁移证据。
+
+## 8. SOP Skill 化（必须）
+
+SOP 关键阶段必须有可调用技能承载，并保持 checkpoint 与 skill 映射一致：
+- kickoff
+- execution-sync
+- verification
+- completion-archive
+
+当前统一技能入口：
+- `.codex/skills/documentation-lifecycle-governance/SKILL.md`
+
+若 SOP 与 skill 行为不一致，以规范文档更新 + skill 同步更新为同一任务，禁止只改其一。

docs/todos/README.md

@@ -52,7 +52,9 @@
 ## 5. 与其他文档的关系
 
 - 与 `docs/design/modules/*`：模块细节在模块文档，这里只保留跨模块视角。
-- 与 OpenSpec：执行任务拆解在 OpenSpec artifacts，这里只做方向与优先级治理。
+- 与 OpenSpec：执行任务拆解在 OpenSpec artifacts，这里只做方向与优先级治理（默认模式）。
+- 与 `docs/features/*`：每个治理/特性 change 的状态单一真相源在聚合文档，本目录负责分析与执行清单，不重复维护冲突状态。
 - 与 `docs/README.md`：由文档导航统一入口。
 - 与 `docs/guides/Documentation_First_Development_SOP.md`：必须遵循“gap 分析 -> TODO -> OpenSpec 执行 -> 回写/归档”的闭环流程。
+- 与 `docs/governance/Documentation_Management_Model.md`：目录分层、生命周期和回退协作模式以该模型为准。
 - 与 `docs/guides/Design_Reconstruction_SOP.md`：重建场景必须遵循该 SOP，并以追踪矩阵为验收入口。

openspec/changes/enhance-doc-governance-traceability/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-02-28