docs(governance): start standalone OpenSpec change for doc lifecycle traceability - #126
Conversation
…c lifecycle Context:\nPR #113 confirmed that cross-project documentation governance philosophy should be handled in a dedicated follow-up change instead of being mixed into runtime rebase work.\n\nWhat this commit includes:\n- creates OpenSpec change \n- adds proposal defining scoped governance objectives: aggregation entry, frontmatter contract, active/archive indexing, and machine-checkable checkpoints\n- adds technical design covering decisions, risks, migration strategy, and non-goals\n- adds capability specs:\n - new capability: \n - modified capability: \n- adds implementation task breakdown (12 tasks) to drive follow-up execution in small verifiable steps\n\nRationale:\nThis commit intentionally starts with governance contracts and execution plan artifacts only, so the follow-up implementation PR can proceed under explicit OpenSpec requirements with traceable acceptance criteria.\n\nVerification:\n- openspec status --change enhance-doc-governance-traceability --json\n- openspec instructions apply --change enhance-doc-governance-traceability --json\n- openspec validate --changes enhance-doc-governance-traceability
Context: A follow-up review highlighted that the standalone governance change mentioned automated checkpoints but did not explicitly encode the “SOP skillization” requirement raised in PR #113. Updates in this commit: - proposal: adds explicit scope for skillizing governance lifecycle stages (kickoff/execution/completion/verification) - design: adds a dedicated decision for checkpoint-to-skill mapping and skill-based governance execution semantics - specs: - documentation-lifecycle-traceability: adds requirement that key SOP stages MUST be represented by callable skills - design-reconstructability-governance: adds requirement to maintain auditable checkpoint-skill mappings - tasks: adds a dedicated SOP skillization workstream and renumbers pilot tasks accordingly Verification: - openspec validate --changes enhance-doc-governance-traceability - openspec status --change enhance-doc-governance-traceability --json
|
Follow-up updated: explicitly added SOP skillization into the OpenSpec contract. Included in latest commit
This addresses the missing explicit mention for "SOP -> skill" raised from the PR #113 discussion context. |
…ll execution model
Context:
The governance follow-up needed to explicitly cover directory unification, document-type lifecycle control, OpenSpec/default collaboration semantics, TODO fallback semantics, and reusable skill-based execution so documentation does not drift into ad-hoc patterns.
What changed:
- Added unified documentation management model:
- docs/governance/Documentation_Management_Model.md
- defines directory taxonomy, document-type placement rules, lifecycle dependency chain,
OpenSpec default mode, TODO fallback mode, frontmatter contract, checkpoint-skill mapping,
and effectiveness criteria
- Added feature aggregation layer:
- docs/features/README.md
- docs/features/enhance-doc-governance-traceability.md
- docs/features/archive/.gitkeep
- Added unified governance skill:
- .codex/skills/documentation-lifecycle-governance/SKILL.md
- Updated standards and navigation docs to align with the new model:
- AGENTS.md
- docs/agent_rules.md
- docs/README.md
- docs/guides/Development_Constraints.md
- docs/guides/Documentation_First_Development_SOP.md
- docs/design/Design_Reconstructability_Traceability_Matrix.md
- docs/todos/README.md
- Expanded OpenSpec change contract to include:
- directory taxonomy unification
- explicit OpenSpec-vs-fallback collaboration
- lifecycle dependency requirement
- status single-source-of-truth requirement
OpenSpec artifacts updated:
- openspec/changes/enhance-doc-governance-traceability/proposal.md
- openspec/changes/enhance-doc-governance-traceability/design.md
- openspec/changes/enhance-doc-governance-traceability/specs/documentation-lifecycle-traceability/spec.md
- openspec/changes/enhance-doc-governance-traceability/specs/design-reconstructability-governance/spec.md
- openspec/changes/enhance-doc-governance-traceability/tasks.md
Verification:
- openspec validate --changes enhance-doc-governance-traceability
- openspec status --change enhance-doc-governance-traceability --json
|
Extended the change to cover the full governance scope discussed:
Key new governance docs:
OpenSpec artifacts were updated accordingly and revalidated:
|
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 1f24c57aa4
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| - `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 openspec/changes/enhance-doc-governance-traceability/ prefix, so anyone (or any script) resolving them from the repo root gets non-existent paths. This breaks the traceability goal of the aggregation doc because proposal/design/tasks are resolvable while specs are not, and it can cause automated evidence/link checks to fail for this change.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed. Updated spec links in the feature aggregation entry to repository-root-resolvable paths:
- docs/features/enhance-doc-governance-traceability.md lines 20-21
Commit: ba0d70d
|
|
||
| ## 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 (SHOULD), but the same change set defines governance traceability around machine-checkable metadata and CI checks for missing required fields; keeping this as optional lets contributors legitimately omit the key mapping metadata and weakens the enforceability of the lifecycle contract. Tightening this to a mandatory requirement (or explicitly scoping exceptions) would keep the contract consistent and auditable.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed. Frontmatter requirement was tightened from SHOULD to MUST in the governance model:
- docs/governance/Documentation_Management_Model.md line 63
Commit: ba0d70d
…workflow skills Introduce two explicit governance skills to separate concerns and align with PR feedback: - add documentation-management for taxonomy/path/frontmatter/archive controls - add documentation-workflow for lifecycle checkpoints, OpenSpec-default flow, TODO fallback, and evidence sync - keep documentation-lifecycle-governance as a compatibility wrapper that delegates to the two new skills Update governance standards and OpenSpec artifacts to codify the two-skill requirement and checkpoint mapping: - AGENTS + guides + governance model + agent rules now reference dual-skill execution - feature aggregation anchor updated to both skills plus legacy wrapper - proposal/design/spec/tasks now require at least two governance skills and reflect the new mapping contract Validation evidence: - openspec validate --changes enhance-doc-governance-traceability - openspec status --change enhance-doc-governance-traceability --json
|
根据 review 反馈，文档治理 skill 已从单入口拆分为双技能并已推送：
同时已同步更新：
校验：
|
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: f1a8cfc620
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| - `specs/documentation-lifecycle-traceability/spec.md` | ||
| - `specs/design-reconstructability-governance/spec.md` |
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 specs/... paths that do not exist from the repository root, unlike the proposal/design/tasks links in the same section. In practice, reviewers or any path-based checker cannot resolve these entries to the actual OpenSpec files, which breaks the "single aggregation entry" navigation goal for this change and makes evidence lookup brittle.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed. Spec artifact references now point to real repository paths in the aggregation doc:
- docs/features/enhance-doc-governance-traceability.md lines 20-21
Commit: ba0d70d
…kill Apply governance model refinement from review feedback: - remove as a separate compatibility skill - merge lifecycle-governance responsibilities into - rename to to reflect that the second skill governs delivery workflow rather than document-only operations Synchronize standards and OpenSpec artifacts to the new two-skill contract: - update AGENTS, constraints, SOP, agent rules, and feature anchors - update checkpoint-to-skill mapping in Documentation_Management_Model - update proposal/design/spec/tasks to require + Validation evidence: - openspec validate --changes enhance-doc-governance-traceability - openspec status --change enhance-doc-governance-traceability --json
|
按你的最新意见已完成调整并推送：
验证：
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 0c76984be5
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| - update linked design/gap/TODO docs and implementation evidence per completed task | ||
|
|
||
| 3. verification | ||
| - run required checks (`openspec validate`, `openspec status`, tests, and repo doc checks) |
There was a problem hiding this comment.
The verification checkpoint unconditionally requires openspec validate and openspec status, but this skill also defines a TODO fallback mode specifically for cases where OpenSpec is unavailable. In fallback environments this makes verification impossible to complete and blocks the documented lifecycle from reaching completion/archive. Please make the required commands mode-aware (OpenSpec checks in OpenSpec mode, fallback-equivalent checks in TODO mode).
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed with mode-aware verification. The workflow now separates OpenSpec-mode checks from TODO-fallback checks:
- .codex/skills/development-workflow/SKILL.md lines 44-45
Commit: 34a9a9d
|
|
||
| 3. Enforce governance metadata | ||
| - ensure frontmatter exists for governance-tracked docs | ||
| - required keys: `change_ids`, `doc_kind`, `topics`, `created`, `updated`, `status` |
There was a problem hiding this comment.
The metadata contract makes change_ids mandatory for all governance-tracked docs, but the same change introduces a TODO fallback mode that starts from docs/features/<topic-slug>.md when 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.
Fixed by making metadata contract mode-aware for fallback.
- documentation-management: fallback keys defined (topic_slug + mode: todo_fallback) and migration rule to add change_ids
- .codex/skills/documentation-management/SKILL.md lines 32-34
- governance model fallback exception documented
- docs/governance/Documentation_Management_Model.md line 80
Commit: 34a9a9d
- docs/governance/Documentation_Management_Model.md line 80
Refine the two-skill governance model after alignment review against the documentation-first SOP and PR discussion context. Key updates: - strengthen development-workflow trigger conditions and scope boundaries - encode mandatory SOP kickoff gates in the workflow skill (design-first, gap analysis, TODO before implementation) - tighten execution-sync/verification/completion steps to mirror SOP and DoD checkpoints - make frontmatter contract mandatory in Documentation_Management_Model - fix OpenSpec spec links in feature aggregation entry to repository-root paths Validation evidence: - openspec validate --changes enhance-doc-governance-traceability - openspec status --change enhance-doc-governance-traceability --json
|
完成一轮“skill 触发条件 + 工作流程”对齐检查（基于现有 SOP 和当前 PR comment 上下文），并已补齐不一致项：
验证：
如需我继续，我可以下一步直接把 PR 上未 resolve 的 review thread 对应点逐条回帖标注已修复位置。 |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: ba0d70deab
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| ```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 (docs/design/) but the required frontmatter enum only allows feature|analysis|todo|standard|temporary, so a checker that enforces this rule cannot represent design artifacts without mislabeling them or failing validation. This conflicts with the same change set’s documentation-management skill, which explicitly classifies design as a document kind, and will break machine-traceability for design updates unless design (and any other governed kinds) is added or explicitly exempted.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed. Added design to the doc_kind contract enum:
- docs/governance/Documentation_Management_Model.md line 68
Commit: 34a9a9d
| - run `documentation-management` to validate type/path/frontmatter baseline | ||
|
|
||
| 2. execution-sync | ||
| - execute in small increments: TODO item -> OpenSpec task -> implementation -> evidence |
There was a problem hiding this comment.
This step requires TODO item -> OpenSpec task -> implementation -> evidence for every run, but the same skill defines a todo_fallback mode for when OpenSpec is unavailable. In that environment there is no OpenSpec task to update, so checkpoint 2 becomes non-executable and teams cannot follow the documented lifecycle without violating the skill. Split execution-sync expectations by mode so fallback can proceed with TODO-only tracking until migration.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed with mode-aware execution-sync.
- OpenSpec mode uses TODO -> OpenSpec task -> implementation -> evidence
- TODO fallback mode uses TODO -> implementation -> evidence + migration mapping
- .codex/skills/development-workflow/SKILL.md lines 38-40
Commit: 34a9a9d
…vs-openspec boundary Resolve remaining governance review gaps and clarify source-of-truth boundaries. Changes in skills: - development-workflow now uses mode-aware execution-sync and verification checkpoints - development-workflow now defines mode-aware completion behavior for OpenSpec and TODO fallback - documentation-management now defines mode-aware metadata keys for OpenSpec and TODO fallback Changes in governance docs: - Documentation_Management_Model now includes design in doc_kind metadata contract - Documentation_Management_Model now declares TODO fallback exception for change_ids before migration - Documentation_Management_Model now defines source-of-truth boundary: docs as canonical full record, OpenSpec as execution trace - Documentation_First_Development_SOP now explicitly states docs are canonical and OpenSpec outcomes must be written back to docs Validation evidence: - openspec validate --changes enhance-doc-governance-traceability - openspec status --change enhance-doc-governance-traceability --json
|
补充一轮对齐（已推送
并已逐条回复当前 review threads，对应问题均给出修复位置。当前这些 thread 在最新代码上都变为 outdated。 |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 34a9a9d085
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| - treat OpenSpec artifacts as execution records; keep canonical outcomes written in `docs/**` | ||
|
|
||
| 2. TODO fallback mode (only if OpenSpec unavailable) | ||
| - create `docs/features/<topic-slug>.md` with `mode: todo_fallback` |
There was a problem hiding this comment.
topic_slug in TODO fallback instructions
The fallback workflow here only tells contributors to set mode: todo_fallback, but the same change’s metadata contract requires topic_slug for TODO fallback documents (.codex/skills/documentation-management/SKILL.md, required keys for fallback mode). In environments following this workflow verbatim, fallback feature docs can be created without the required key and then fail later validation/checkpoint steps once metadata checks are enforced.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed. TODO fallback instruction now requires topic_slug together with mode: todo_fallback.
.codex/skills/development-workflow/SKILL.md:26
Commit:6c54b36
| - 理由：A 与现有治理流程天然对齐，避免并行编号体系导致维护成本上升。 | ||
|
|
||
| ### Decision 2: frontmatter 合约采用“最小必填 + 可扩展字段” | ||
| - 必填：`feature_ids`（或 `change_ids`）、`topics`、`doc_kind`、`created`。 |
There was a problem hiding this comment.
change_ids
This decision leaves the primary linkage field as feature_ids (or change_ids), but the governance contract introduced in this same commit defines OpenSpec-mode metadata with change_ids as the required key (docs/governance/Documentation_Management_Model.md and .codex/skills/documentation-management/SKILL.md). Keeping both names valid creates a split contract that will produce non-uniform docs and brittle automation when CI/scripts enforce one schema.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed. Frontmatter primary key contract is now standardized to change_ids in OpenSpec mode, with explicit fallback-mode required keys.
openspec/changes/enhance-doc-governance-traceability/design.md:32-33- Also removed the stale open-question wording that reintroduced
feature_idsambiguity:.../design.md:92
Commits:6c54b36,afd84b1
…Spec slicing Align governance workflow with the clarified execution model: - analysis/gap + master TODO backlog come first for bug/feature/refactor - docs updates are treated as OpenSpec inputs, not post-hoc artifacts - OpenSpec is used as slice-level execution tracking and can span multiple change-ids for one large initiative - docs remain the canonical full record; openspec remains process trace Updated standards and skills: - SOP restructured to analysis -> master TODO -> docs update -> OpenSpec slicing -> execution -> verification -> archive - Development_Constraints and AGENTS sequence aligned to master-TODO-first slicing workflow - development-workflow skill now enforces mode-aware slice execution against master TODO - documentation-management skill now requires planning-to-execution mapping for TODO subset coverage - Documentation_Management_Model now documents slicing policy and optional todo_ids/mode metadata OpenSpec contract updates: - proposal/design updated with source-of-truth boundary and multi-change slicing decisions - specs updated with mandatory requirements for analysis-first input and TODO-to-change slice mapping - tasks expanded with boundary/slicing alignment and mapping-check coverage Validation evidence: - openspec validate --changes enhance-doc-governance-traceability - openspec status --change enhance-doc-governance-traceability --json
|
根据最新流程反馈，已将治理模型更新为“analysis-first + master-TODO-first + OpenSpec slicing”： 核心调整（commit
同步更新：
验证：
|
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 99279ce3ff
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| 仅在 OpenSpec 不可用（工具/环境受限）时使用： | ||
| 1. 先完成分析 + 总体 TODO 主清单 + docs 基线更新。 | ||
| 2. 创建 `docs/features/<topic-slug>.md`，并在 frontmatter 声明 `mode: todo_fallback`。 |
There was a problem hiding this comment.
topic_slug in fallback feature-doc frontmatter steps
The fallback SOP currently tells contributors to set only mode: todo_fallback when creating docs/features/<topic-slug>.md, but the governance contract for fallback mode requires topic_slug as a mandatory key before a change_ids exists (docs/governance/Documentation_Management_Model.md, fallback note). In no-OpenSpec environments, following this SOP verbatim will produce feature docs that later fail governance metadata checks or migration tooling once frontmatter validation is enforced.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed. SOP fallback step now explicitly requires both mode: todo_fallback and topic_slug in frontmatter.
docs/guides/Documentation_First_Development_SOP.md:132
Commit:6c54b36
|
|
||
| 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 docs/features/<change-id>.md, but the same governance model later mandates TODO fallback creation as docs/features/<topic-slug>.md when OpenSpec is unavailable. Keeping both as unconditional requirements creates an internal contract conflict, so any path-based checker or reviewer using section 3 as the source of truth can incorrectly reject valid fallback docs.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed. Feature-doc placement rule is now mode-aware to remove the naming conflict:
- OpenSpec mode:
docs/features/<change-id>.md - TODO fallback mode:
docs/features/<topic-slug>.mdwithmode: todo_fallback+topic_slug docs/governance/Documentation_Management_Model.md:35-37
Commit:6c54b36
Address new PR #126 review feedback by making TODO fallback metadata and path rules explicit and consistent across skill, SOP, governance model, and OpenSpec design docs. Key updates: - Require topic_slug alongside mode: todo_fallback in development-workflow skill fallback instructions. - Mirror the same requirement in Documentation-First SOP fallback sequence. - Make Documentation Management Model feature-doc placement mode-aware (OpenSpec by change-id, fallback by topic-slug) while preserving single-source status semantics. - Standardize OpenSpec mode frontmatter contract to change_ids and define fallback-required fields plus migration expectation. Rationale: reviewers flagged ambiguity between change-id and topic-slug paths plus mixed feature_ids/change_ids language. This commit removes ambiguity and ensures deterministic governance behavior in both OpenSpec and fallback workflows.
Update the remaining open-question wording in the governance traceability design so it no longer re-opens a resolved schema decision. Key changes: - Replace the old 'feature_ids or change_ids' question with a migration-focused question now that change_ids is standardized as the primary key. Rationale: keeps the design internally consistent with the metadata contract and avoids conflicting guidance during review and future automation work.
|
Updated with follow-up fixes for the latest review threads:
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: afd84b1c61
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| 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 feature aggregation before design, but the same commit’s SOP flow requires design/gov docs updates before entering the change-slice aggregation workflow (Step 3 before Step 4 in docs/guides/Documentation_First_Development_SOP.md). Because this model is the declared source for checkpoint automation, the reversed order can cause CI/rules to enforce a workflow that conflicts with the documented SOP and create false process failures.
Useful? React with 👍 / 👎.
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.
docs/governance/Documentation_Management_Model.md:55- Updated chain:
standards -> design update -> gap analysis -> master TODO -> feature aggregation -> execution -> evidence -> review/merge gate -> archive
Commit:cb2230f
|
|
||
| - 引入“按变更聚合”的文档治理基线：每个治理变更都有单一聚合文档入口，统一挂接相关设计、讨论、TODO 与证据。 | ||
| - 统一 `docs/` 目录结构分层（标准/设计/治理/特性聚合/分析TODO/临时/归档），并明确各类型文档放置规则。 | ||
| - 定义并落地文档 `frontmatter` 最小字段合约（如 `feature_ids` / `topics` / `doc_kind` / `created`），用于机器可检索追溯。 |
There was a problem hiding this comment.
This proposal still describes the frontmatter key as feature_ids, while the governance model and feature doc contract in this same change standardize on change_ids. Leaving both names in the change artifacts reintroduces schema ambiguity for downstream CI/frontmatter automation and makes it unclear which key implementers should enforce.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed. Proposal frontmatter contract wording now uses change_ids consistently.
openspec/changes/enhance-doc-governance-traceability/proposal.md:9
Commit:cb2230f
|
看完 PR #126（ 你这次已经吸纳到位的点（明确对齐）
我们和你哲学的关键差异（也是我们想补的视角）你现在的叙事更偏：
猫猫咖啡的叙事更偏：
我们建议把“真相”拆成三类，并在治理里写清楚各自用途：
你现在把 normative truth 做得很强，但 evidence truth 目前主要是“要求要有”，还没变成强制产物与强制校验。 我们建议你下一步补上的三块（可落地、可自动化）1) 把 Evidence 变成一等公民（不是口头要求）建议在
这能显著降低“文档看起来完整，但其实没验证”的治理空转。 2) 把 Review/Merge Gate 纳入治理模型（减少流程灰区）你现在把 建议你在治理模型里明确两件事：
这套做完，团队协作会明显更稳，因为“能不能合入”不再靠记忆/口头。 3) 把你写的 MUST 真的接入 CI（最小闭环先落地）你在
先从“能自动抓到 80% 漂移”的简单检查做起，比一次性做完所有规则更稳。 总体结论：PR #126 方向是对的，而且已经把“skill 化 SOP + docs/openspec 边界 + taxonomy/frontmatter”这几个关键点写进契约了。 |
…rkflow Align governance skills and contracts with latest PR feedback by treating CI as a full governance gate (not skill-only) and by promoting evidence/review records to first-class artifacts. Key changes: - Fix lifecycle dependency order to match SOP: standards -> design -> gap -> master TODO -> feature aggregation -> execution -> evidence -> review/merge gate -> archive. - Standardize proposal frontmatter wording to change_ids and remove remaining schema ambiguity in the proposal layer. - Extend development-workflow skill with required Evidence block schema, review-merge-gate checkpoint, and explicit CI scope checks (metadata, links, evidence completeness, TODO/change mapping, checkpoint mapping). - Extend documentation-management skill with mailbox classification (temporary_coordination vs audit_evidence), retention rules, and CI-scope guidance beyond skill-file checks. - Update governance model with truth-layer semantics (normative/operational/evidence), mode-aware workflow steps, mailbox metadata contract, review-merge-gate mapping, and expanded CI minimum checks. - Update OpenSpec specs to encode the same lifecycle order and CI-scope requirements, including review/merge gate evidence retention. - Backfill the active feature aggregation doc with structured evidence sections (commands/results/behavior/risk/rollback/review links). Rationale: this removes remaining SOP-model mismatches, resolves new review comments, and prevents future drift where governance checks are reduced to skill-presence-only validation.
|
Follow-up aligned to the latest long feedback (commit
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: cb2230f4c3
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| - kickoff | ||
| - execution-sync | ||
| - verification | ||
| - completion-archive | ||
|
|
There was a problem hiding this comment.
The mandatory checkpoint list here omits review-merge-gate, even though this same change requires review/merge audit evidence in docs/governance/Documentation_Management_Model.md and implements that checkpoint in .codex/skills/development-workflow/SKILL.md. If teams/agents follow the SOP as written, they can complete verification -> completion-archive without recording review-request/thread/merge-decision evidence, which breaks the intended governance traceability and can leave CI policy implementations inconsistent.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed. SOP mandatory checkpoint list now includes review-merge-gate to align with governance model + workflow skill contracts.
docs/guides/Documentation_First_Development_SOP.md:150
Commit:7a618b6
…rategy Promote evidence truth from guideline language to enforceable repository contract by adding a dedicated strategy document, wiring an initial structural CI gate, and synchronizing governance/SOP/skills/OpenSpec references. Key changes: - Added docs/guides/Evidence_Truth_Implementation_Strategy.md with phased implementation plan (structural gate -> semantic checks -> merge policy coupling). - Added scripts/ci/check_governance_evidence_truth.sh to enforce active feature-doc evidence structure, mode-aware frontmatter keys, artifact path resolvability, and review-link presence. - Wired the new gate into .github/workflows/ci-gate.yml as governance-evidence-truth job. - Updated governance standards and execution guides (AGENTS, Development_Constraints, Documentation_First_Development_SOP, docs/README, docs/features/README, docs/agent_rules) to require and reference the evidence-truth contract and gate command. - Updated OpenSpec proposal/spec/tasks to encode the new evidence-truth strategy and CI gate command as part of change scope. - Refreshed feature aggregation evidence section to include the new gate command result. Rationale: PR feedback requested evidence truth to be concretely operationalized. This commit provides deterministic, auditable, and automatable enforcement rather than relying on narrative review discipline.
|
Follow-up for the latest evidence-truth feedback is now landed in What was solidified beyond wording:
Verification executed:
@codex review |
|
Codex Review: Didn't find any major issues. Can't wait for the next one! ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
…y into documentation-management skill Refine governance guidance after review feedback to avoid over-specifying implementation commands in AGENTS and to clarify skill ownership boundaries for evidence-truth governance. Key changes: - AGENTS now references governance contracts ( and ) instead of directly naming a concrete script command. - documentation-management skill adds an authoritative-inputs section and explicitly states it is the single execution entry for both governance model and evidence-truth strategy, avoiding unnecessary evidence-only skill splitting. Rationale: AGENTS should remain stable policy guidance, while concrete implementation details belong to skills/guides/CI. Evidence-truth and documentation governance currently share one cohesive responsibility domain, so merging into documentation-management is simpler and less error-prone than creating a third skill.
|
Follow-up refinement pushed in
Reasoning: AGENTS should stay stable/policy-level; concrete command details stay in skills/guides/CI. Current evidence-truth responsibilities are still cohesive with documentation governance and do not justify a separate skill yet. |
… references Apply two governance alignment updates requested in review follow-up. Key changes: - AGENTS.md now keeps only high-level documentation-first policy and removes explicit references to Documentation_Management_Model, Evidence_Truth_Implementation_Strategy, and concrete skill/script declarations. - Added mirrored governance skills to .claude and .gemini skill catalogs: - documentation-management - development-workflow - Mirrored files are copied from the current .codex skill definitions to keep agent runtimes behaviorally consistent across Codex, Claude, and Gemini work modes. Rationale: AGENTS should remain policy-oriented while concrete execution contracts live in skills and CI gates; multi-agent directories must stay synchronized to avoid divergent workflow behavior.
|
Synced as requested in
|
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b50f758a55
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| # Ensure OpenSpec artifact references are resolvable from repository root. | ||
| while IFS= read -r path; do | ||
| if [[ -n "$path" && "$path" =~ ^(openspec|docs)/ ]]; then |
There was a problem hiding this comment.
The OpenSpec artifact resolver only checks paths that start with openspec/ or docs/, so malformed entries like specs/... are silently ignored instead of being failed. That means this gate can pass even when a feature doc contains non-resolvable artifact links from the repo root, which undermines the traceability check this script is intended to enforce.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed. Artifact path validation now checks every extracted path from ## OpenSpec Artifacts (no prefix-based skip), so malformed entries like specs/... fail deterministically.
scripts/ci/check_governance_evidence_truth.sh:160
Commit:7a618b6
| feature_docs=() | ||
| while IFS= read -r path; do | ||
| feature_docs+=("$path") | ||
| done < <(find docs/features -maxdepth 1 -type f -name '*.md' ! -name 'README.md' | sort) |
There was a problem hiding this comment.
This loop validates every docs/features/*.md file without considering frontmatter lifecycle status, but the governance contract defines these evidence requirements for active items. As soon as a draft aggregation doc is added (before review links and full evidence are expected), CI will fail with false positives, blocking normal progression from draft to active.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed. Evidence gating is now scoped to active feature docs via frontmatter status; non-active docs are explicitly skipped to avoid draft-stage false positives.
scripts/ci/check_governance_evidence_truth.sh:120scripts/ci/check_governance_evidence_truth.sh:129
Commit:7a618b6
|
Follow-up after pulling latest head ( What looks solid now
Small but important suggestion (phase-2 friendly)The current gate is intentionally structural (good). One potential future source of friction is YAML/frontmatter strictness:
Suggested next step (when you move to Phase 2 semantic checks): parse the frontmatter block explicitly (even a minimal parser for the first No need to expand scope in this PR; just flagging it so the rollout stays low-noise. |
Address the latest unresolved PR review threads by aligning SOP checkpoints and hardening the governance evidence gate behavior. Key changes: - Added to mandatory checkpoint list in Documentation_First_Development_SOP so SOP matches governance model and development-workflow skill. - Hardened scripts/ci/check_governance_evidence_truth.sh artifact-path validation: every extracted OpenSpec artifact path is now validated, eliminating silent skips for malformed relative entries (e.g., specs/... without repo-root prefix). - Scoped evidence enforcement to active feature docs by reading frontmatter status; non-active docs are skipped to avoid draft-stage false positives. - Added frontmatter parsing helpers and change_ids validation that supports both single-line and multiline YAML list formats, reducing formatting-related false negatives in future rollout phases. Rationale: this resolves active review findings while keeping the gate deterministic and compatible with documented lifecycle semantics.
|
Follow-up fixes for latest open review threads are in
Verification re-run:
@codex review |
|
Codex Review: Didn't find any major issues. More of your lovely PRs please. ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
Fix the newly failing governance intent gate and the latest review comment on checkpoint defaults. Changes: - rewrite dare_framework/checkpoint/defaults.py to remove imports from deleted checkpoint._internal modules - provide in-module legacy-compatible checkpoint symbols so the defaults facade remains importable - add regression test tests/unit/test_checkpoint_defaults.py to lock importable default exports - add missing Intent PR link to docs/features/p0-conformance-gate.md so governance-intent-gate can validate merged intent metadata for active governed docs Verification: - ../../.venv/bin/python -m pytest -q tests/unit/test_checkpoint_defaults.py (passed) - GOVERNANCE_INTENT_GATE_DIFF_RANGE='origin/main...HEAD' GOVERNANCE_INTENT_GATE_PR_STATE_FIXTURE='#126=merged,#172=merged' ./scripts/ci/check_governance_intent_gate.sh (passed) - ./scripts/ci/check_governance_traceability.sh (passed) - ./scripts/ci/check_governance_evidence_truth.sh (passed) - openspec validate p0-conformance-gate --type change --strict --json --no-interactive (valid)
…ation Address the latest PR #188 review comment on SessionContextContributor config loss. Root cause: - SessionContextContributor.serialize() called asdict(session_context) and then attempted asdict(serialized['config']) again. - For dataclass-backed contexts, the first asdict() already converted config to dict, so the second call raised and forced config to None. Changes: - only run asdict() for config when config is non-null and not already a dict - keep existing dict config payload untouched - extend tests/unit/test_checkpoint_defaults.py with a regression test that verifies config survives serialization Verification: - ../../.venv/bin/python -m pytest -q tests/unit/test_checkpoint_defaults.py (2 passed) - GOVERNANCE_INTENT_GATE_DIFF_RANGE='origin/main...HEAD' GOVERNANCE_INTENT_GATE_PR_STATE_FIXTURE='#126=merged,#172=merged' ./scripts/ci/check_governance_intent_gate.sh (passed) - ./scripts/ci/check_governance_traceability.sh (passed) - ./scripts/ci/check_governance_evidence_truth.sh (passed)
Address the latest review comment on selector-overlap coverage in scripts/ci/check_test_failure_ownership.py. Root cause: - overlap detection only tokenized selectors by - directory selectors like were treated as unrelated to descendant node selectors such as - this allowed cross-category ownership overlap to bypass validation Changes: - normalize selectors into path parts + pytest node parts - treat file_or_dir path prefix matches as overlapping when the prefix side has no node suffix - keep existing node-level overlap and parametrized node normalization behavior - add regression test for directory selector overlap in tests/unit/test_check_test_failure_ownership.py Verification: - ../../.venv/bin/python -m pytest -q tests/unit/test_check_test_failure_ownership.py (5 passed) - ../../.venv/bin/python scripts/ci/check_test_failure_ownership.py (passed) - ../../.venv/bin/python scripts/ci/p0_gate.py (PASS) - GOVERNANCE_INTENT_GATE_DIFF_RANGE='origin/main...HEAD' GOVERNANCE_INTENT_GATE_PR_STATE_FIXTURE='#126=merged,#172=merged' ./scripts/ci/check_governance_intent_gate.sh (passed) - ./scripts/ci/check_governance_traceability.sh (passed) - ./scripts/ci/check_governance_evidence_truth.sh (passed)
2 participants
Summary
Start the standalone follow-up promised in PR #113 for documentation governance philosophy work.
This PR intentionally bootstraps the OpenSpec change artifacts only (proposal/design/specs/tasks), so implementation can proceed in controlled, traceable tasks.
Why now
In PR #113,
zts212653raised governance-philosophy recommendations (aggregation entry, structured frontmatter, lifecycle checkpoints), and we explicitly agreed to handle them in a separate OpenSpec-driven PR.Included in this PR
enhance-doc-governance-traceabilityopenspec/changes/enhance-doc-governance-traceability/proposal.mdopenspec/changes/enhance-doc-governance-traceability/design.mdopenspec/changes/enhance-doc-governance-traceability/tasks.mdopenspec/changes/enhance-doc-governance-traceability/specs/documentation-lifecycle-traceability/spec.mdopenspec/changes/enhance-doc-governance-traceability/specs/design-reconstructability-governance/spec.mdScope
/opsx:applytask-by-task execution.Verification
openspec status --change enhance-doc-governance-traceability --jsonopenspec instructions apply --change enhance-doc-governance-traceability --jsonopenspec validate --changes enhance-doc-governance-traceability