@ai-content-space/loopx 0.1.5 → 0.1.7

package/README.md

@@ -121,18 +121,14 @@ loopx approve my-task --from build --to review
 loopx review my-task
 ```
 
-Complete an approved review:
-
-```bash
-loopx approve my-task --from review --to done
-```
-
 Archive accepted behavior into long-lived specs:
 
 ```text
 $archive my-task
 ```
 
+When review has approved the workflow and routed it to `done`, `$archive` consumes the pending `review -> done` completion transition before syncing specs. CLI-only operators can still run `loopx approve my-task --from review --to done` followed by `loopx archive my-task` explicitly.
+
 Check status:
 
 ```bash
@@ -140,7 +136,15 @@ loopx status my-task
 loopx status my-task --json
 ```
 
-Render derived HTML reading views:
+Planning also writes derived HTML reading views so the plan can be reviewed without another command:
+
+```text
+.loopx/workflows/my-task/view/index.html
+.loopx/workflows/my-task/view/plan.html
+.loopx/views/index.html
+```
+
+Regenerate derived HTML reading views at any time:
 
 ```bash
 loopx render my-task
@@ -174,7 +178,7 @@ loopx repair-install
 
 The CLI is primarily for runtime, debugging, status inspection, and maintenance. The normal Codex-facing product surface is the bundled skill set, for example `$clarify`, `$plan`, `$build`, `$review`, `$archive`, `$autopilot`, `$debug`, `$tdd`, `$verify`, `$go-style`, and `$kratos`.
 
-`loopx status` remains a CLI/runtime diagnostic command rather than a Codex skill. `loopx render` generates human-readable HTML views from existing runtime artifacts; without a slug it renders every non-legacy workflow plus the workspace index. Markdown and JSON remain the canonical machine-readable and editable sources.
+`loopx status` remains a CLI/runtime diagnostic command rather than a Codex skill. `loopx plan` automatically writes human-readable HTML views for the planned workflow and workspace index. `loopx render` regenerates those views from existing runtime artifacts; without a slug it renders every non-legacy workflow plus the workspace index. Markdown and JSON remain the canonical machine-readable and editable sources.
 
 ## Skill Routing and Governance
 
@@ -223,6 +227,11 @@ Main artifacts:
 - `.loopx/workflows/<slug>/architecture.md`
 - `.loopx/workflows/<slug>/development-plan.md`
 - `.loopx/workflows/<slug>/test-plan.md`
+- `.loopx/workflows/<slug>/requirement-traceability.md`
+
+After a successful plan run, loopx also writes derived reading views at `.loopx/workflows/<slug>/view/index.html`, `.loopx/workflows/<slug>/view/plan.html`, and `.loopx/views/index.html`. Use these for human review; keep Markdown and JSON as the editable sources of truth.
+
+`requirement-traceability.md` maps the original source requirements or PRD to the generated plan package, change delta, vertical slices, and tests. If explicit source coverage items or source requirement tables are not covered by the plan package, `plan` stays blocked before build approval.
 
 `spec-delta.md` uses requirement deltas: `## ADDED Requirements`, `## MODIFIED Requirements`, `## REMOVED Requirements`, and `## RENAMED Requirements`. ADDED and MODIFIED entries are full `### Requirement:` blocks with SHALL/MUST language and `#### Scenario:` examples, so archive can merge them into the current long-lived spec state.
 
@@ -258,13 +267,13 @@ The approved PRD, test spec, previous execution record, and workflow-local plan
 
 The user-facing review result is expected to be written in Chinese.
 
-If review approves the run, the workflow still requires an explicit `review -> done` approval. If review requests implementation changes, run `$build --from-review .loopx/workflows/<slug>/review-report.md`. Plan and clarify rollbacks still use `$plan <slug>` or `$clarify <slug>` when the review finding says the plan or requirements are wrong.
+If review approves the run and routes it to `done`, the normal Codex-facing next step is `$archive <slug>`; archive consumes the pending completion transition and then syncs specs. CLI-only operators may still explicitly run `loopx approve <slug> --from review --to done` before `loopx archive <slug>`. If review requests implementation changes, run `$build --from-review .loopx/workflows/<slug>/review-report.md`. Plan and clarify rollbacks still use `$plan <slug>` or `$clarify <slug>` when the review finding says the plan or requirements are wrong.
 
 The architecture-smell lane is part of review; it does not add a new stage. It records findings under `review-support/architecture-smell.json` and only blocks when module seams, testability, domain vocabulary, or plan architecture assumptions are materially wrong.
 
 ### archive
 
-`archive` consumes a completed workflow and syncs the approved `.loopx/changes/active/<change-id>/spec-delta.md` into long-lived domain specs under `.loopx/specs/`. The change folder is moved to:
+`archive` consumes a completed workflow, or a review-approved workflow whose only pending route is `done`, and syncs the approved `.loopx/changes/active/<change-id>/spec-delta.md` into long-lived domain specs under `.loopx/specs/`. The change folder is moved to:
 
 ```text
 .loopx/changes/archive/<change-id>/
@@ -367,7 +376,7 @@ loopx writes runtime state under `.loopx/` in the current project:
 
 `intake` contains immutable clarify snapshots for a specific request. `workflows` contains the active runtime working set. `changes` contains the proposed change delta for the current request. `specs` contains accepted long-lived behavior after archive.
 
-`views/` and `workflows/<slug>/view/` are derived HTML reading views generated by `loopx render`. They are for human review only and are safe to regenerate; agents and tooling should continue to read and update the Markdown and JSON artifacts.
+`views/` and `workflows/<slug>/view/` are derived HTML reading views written after `plan` and regenerated by `loopx render`. They are for human review only and are safe to regenerate; agents and tooling should continue to read and update the Markdown and JSON artifacts.
 
 ### Document Boundaries
 
@@ -376,8 +385,9 @@ Documents users normally need to watch:
 - `README.md` / `README.zh-CN.md`: product usage, commands, and runtime layout.
 - `.loopx/workflows/<slug>/spec.md`: the current requirement working copy.
 - `.loopx/workflows/<slug>/plan.md`, `architecture.md`, `development-plan.md`, and `test-plan.md`: the current task's plan, architecture, execution, and verification contract.
+- `.loopx/workflows/<slug>/requirement-traceability.md`: original requirement coverage gate used by plan, build, and review.
 - `.loopx/workflows/<slug>/execution-record.md` and `review-report.md`: execution evidence and review result.
-- `.loopx/views/index.html` and `.loopx/workflows/<slug>/view/index.html`: reading entrypoints generated by `loopx render`.
+- `.loopx/views/index.html` and `.loopx/workflows/<slug>/view/index.html`: reading entrypoints written after `plan` and regenerated by `loopx render`.
 
 Documents users may read and modify as workflow fact sources:
 
@@ -394,7 +404,7 @@ Documents and data the tools depend on, or generate as derived evidence:
 - `.loopx/intake/clarify-*.md`: immutable clarify snapshots for audit and traceability; do not treat them as long-lived specs.
 - `.loopx/changes/active/<change-id>/slices.json` and `artifact-graph.json`: structured planning data consumed by build/review/archive.
 - `.loopx/autopilot/<slug>/run.json` and `.loopx/build-active.json`: orchestration and stop-hook runtime state.
-- `.loopx/views/` and `.loopx/workflows/<slug>/view/`: derived HTML views; they can be deleted and regenerated with `loopx render`, and should not be edited as fact sources.
+- `.loopx/views/` and `.loopx/workflows/<slug>/view/`: derived HTML views; they are written after `plan`, can be deleted and regenerated with `loopx render`, and should not be edited as fact sources.
 
 ## Diagnostics and Repair
 
@@ -511,4 +521,4 @@ node src/cli.mjs status --json
 
 ## Version
 
-Current npm package version: `0.1.4`.
+Current npm package version: `0.1.7`.

package/README.zh-CN.md

@@ -123,18 +123,14 @@ loopx approve my-task --from build --to review
 loopx review my-task
 ```
 
-评审通过后完成工作流：
-
-```bash
-loopx approve my-task --from review --to done
-```
-
 把已接受行为归档到长期 specs：
 
 ```text
 $archive my-task
 ```
 
+当 review 已批准并路由到 `done` 时，`$archive` 会先消费 pending 的 `review -> done` 完成态，再同步 specs。纯 CLI 操作者仍然可以显式执行 `loopx approve my-task --from review --to done`，再执行 `loopx archive my-task`。
+
 查看状态：
 
 ```bash
@@ -142,7 +138,15 @@ loopx status my-task
 loopx status my-task --json
 ```
 
-生成派生 HTML 阅读视图：
+plan 完成后会自动写入派生 HTML 阅读视图，方便直接审阅计划：
+
+```text
+.loopx/workflows/my-task/view/index.html
+.loopx/workflows/my-task/view/plan.html
+.loopx/views/index.html
+```
+
+需要时也可以重新生成派生 HTML 阅读视图：
 
 ```bash
 loopx render my-task
@@ -176,7 +180,7 @@ loopx repair-install
 
 CLI 主要用于运行时、调试、状态观察和维护。日常面向 Codex 的主入口是同名 skills，例如 `$clarify`、`$plan`、`$build`、`$review`、`$archive`、`$autopilot`、`$debug`、`$tdd`、`$verify`、`$go-style`、`$kratos`。
 
-`loopx status` 仍然是 CLI/runtime 诊断命令，不作为单独 Codex skill 暴露。`loopx render` 会基于现有运行时产物生成给人阅读的 HTML 视图；不传 slug 时会渲染所有非 legacy workflow 和工作区首页。Markdown 和 JSON 仍然是机器可读、可编辑的事实源。
+`loopx status` 仍然是 CLI/runtime 诊断命令，不作为单独 Codex skill 暴露。`loopx plan` 会自动为当前计划 workflow 和工作区首页写入给人阅读的 HTML 视图。`loopx render` 会基于现有运行时产物重新生成这些视图；不传 slug 时会渲染所有非 legacy workflow 和工作区首页。Markdown 和 JSON 仍然是机器可读、可编辑的事实源。
 
 ## Skill 路由与治理
 
@@ -225,6 +229,11 @@ node scripts/verify-skills.mjs
 - `.loopx/workflows/<slug>/architecture.md`
 - `.loopx/workflows/<slug>/development-plan.md`
 - `.loopx/workflows/<slug>/test-plan.md`
+- `.loopx/workflows/<slug>/requirement-traceability.md`
+
+plan 成功后，loopx 还会写入派生阅读视图：`.loopx/workflows/<slug>/view/index.html`、`.loopx/workflows/<slug>/view/plan.html` 和 `.loopx/views/index.html`。这些视图用于人工审阅；Markdown 和 JSON 仍然是可编辑事实源。
+
+`requirement-traceability.md` 会把原始需求或 PRD 映射到生成的 plan package、change delta、vertical slices 和测试。若显式需求覆盖项或需求表格项没有被计划包覆盖，`plan` 会在 build approval 前保持 blocked。
 
 `spec-delta.md` 使用 requirement delta：`## ADDED Requirements`、`## MODIFIED Requirements`、`## REMOVED Requirements` 和 `## RENAMED Requirements`。ADDED / MODIFIED 必须是完整的 `### Requirement:` 块，包含 SHALL/MUST 约束和 `#### Scenario:` 场景，archive 才能把它们合并进长期 spec 当前状态。
 
@@ -269,13 +278,13 @@ $build --from-review .loopx/workflows/<slug>/review-report.md
 
 最终用户可见评审结果要求使用中文。
 
-如果评审通过，仍然需要显式批准 `review -> done`。如果评审要求修实现问题，则运行 `$build --from-review .loopx/workflows/<slug>/review-report.md`。只有当 review 明确指出计划或需求本身错误时，才回到 `$plan <slug>` 或 `$clarify <slug>`。
+如果评审通过并路由到 `done`，Codex 侧的正常下一步是 `$archive <slug>`；archive 会消费 pending 的完成态，然后同步 specs。纯 CLI 操作者仍然可以先显式执行 `loopx approve <slug> --from review --to done`，再执行 `loopx archive <slug>`。如果评审要求修实现问题，则运行 `$build --from-review .loopx/workflows/<slug>/review-report.md`。只有当 review 明确指出计划或需求本身错误时，才回到 `$plan <slug>` 或 `$clarify <slug>`。
 
 architecture-smell lane 是 review 的一部分，不会增加新阶段。它会把发现记录到 `review-support/architecture-smell.json`，只有当模块边界、可测试性、领域词汇或计划架构假设存在实质性错误时才阻断。
 
 ### archive
 
-`archive` 消费已完成工作流，并把 `.loopx/changes/active/<change-id>/spec-delta.md` 合并进 `.loopx/specs/` 下的长期领域规格。归档后的 change 目录会移动到：
+`archive` 消费已完成工作流，或 review 已批准且唯一 pending route 是 `done` 的工作流，并把 `.loopx/changes/active/<change-id>/spec-delta.md` 合并进 `.loopx/specs/` 下的长期领域规格。归档后的 change 目录会移动到：
 
 ```text
 .loopx/changes/archive/<change-id>/
@@ -378,7 +387,7 @@ loopx 在当前项目下写入 `.loopx/`：
 
 `intake` 保存一次需求的 clarify 快照；`workflows` 保存当前任务的运行时工作副本；`changes` 保存本次需求对长期行为的 change delta；`specs` 只保存 archive 后的长期领域行为契约。
 
-`views/` 和 `workflows/<slug>/view/` 是 `loopx render` 生成的派生 HTML 阅读视图，只服务于人的浏览和评审，可以随时重新生成；agent 和工具仍应读取、修改 Markdown 与 JSON 产物。
+`views/` 和 `workflows/<slug>/view/` 是 plan 后写入、也可由 `loopx render` 重新生成的派生 HTML 阅读视图，只服务于人的浏览和评审；agent 和工具仍应读取、修改 Markdown 与 JSON 产物。
 
 ### 文档关注边界
 
@@ -387,8 +396,9 @@ loopx 在当前项目下写入 `.loopx/`：
 - `README.md` / `README.zh-CN.md`：产品用法、命令和目录约定。
 - `.loopx/workflows/<slug>/spec.md`：当前需求工作副本。
 - `.loopx/workflows/<slug>/plan.md`、`architecture.md`、`development-plan.md`、`test-plan.md`：当前任务的计划、架构和验证约定。
+- `.loopx/workflows/<slug>/requirement-traceability.md`：plan、build、review 都会消费的原始需求覆盖门禁。
 - `.loopx/workflows/<slug>/execution-record.md`、`review-report.md`：执行证据和评审结论。
-- `.loopx/views/index.html` 与 `.loopx/workflows/<slug>/view/index.html`：由 `loopx render` 生成的阅读入口。
+- `.loopx/views/index.html` 与 `.loopx/workflows/<slug>/view/index.html`：plan 后写入、也可由 `loopx render` 重新生成的阅读入口。
 
 用户可以阅读和按流程修改的事实源文档：
 
@@ -405,7 +415,7 @@ loopx 在当前项目下写入 `.loopx/`：
 - `.loopx/intake/clarify-*.md`：clarify 快照，用于审计和追溯；不要当作长期 specs 修改。
 - `.loopx/changes/active/<change-id>/slices.json`、`artifact-graph.json`：计划结构化数据，build/review/archive 会消费。
 - `.loopx/autopilot/<slug>/run.json`、`.loopx/build-active.json`：编排和 stop-hook 运行态。
-- `.loopx/views/` 和 `.loopx/workflows/<slug>/view/`：HTML 派生视图，可删除后用 `loopx render` 重新生成，不应作为事实源编辑。
+- `.loopx/views/` 和 `.loopx/workflows/<slug>/view/`：HTML 派生视图，plan 后自动写入，可删除后用 `loopx render` 重新生成，不应作为事实源编辑。
 
 ## 安装诊断与修复
 
@@ -522,4 +532,4 @@ node src/cli.mjs status --json
 
 ## 版本
 
-当前 npm 包版本：`0.1.4`。
+当前 npm 包版本：`0.1.7`。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ai-content-space/loopx",
   "type": "module",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Skill-first loopx workflow product for Codex",
   "repository": {
     "type": "git",

package/plugins/loopx/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "loopx",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Skill-first loopx workflow product for Codex",
   "skills": "./skills/",
   "interface": {

package/plugins/loopx/skills/archive/SKILL.md

@@ -3,7 +3,7 @@ name: archive
 description: "Archives an approved loopx change delta into long-lived specs and writes an ADR candidate after done approval. Not for active builds or unapproved reviews."
 when_to_use: "archive, done workflow, spec delta, long-lived specs, ADR candidate, review approved, 归档, 同步规格"
 metadata:
-  version: "0.1.5"
+  version: "0.1.7"
 argument-hint: "<workflow slug>"
 ---
 
@@ -11,7 +11,7 @@ argument-hint: "<workflow slug>"
 
 ## Purpose
 
-Use `archive` after a loopx workflow has reached `done`. It syncs the accepted change delta into long-lived `.loopx/specs/` files, archives the change staging directory, and writes an advisory ADR candidate.
+Use `archive` after a loopx workflow has reached `done`, or immediately after an approved review that is waiting for `review -> done` completion. It syncs the accepted change delta into long-lived `.loopx/specs/` files, archives the change staging directory, and writes an advisory ADR candidate.
 
 The accepted delta is requirement-based, not a changelog block. Archive applies:
 
@@ -24,7 +24,7 @@ into the current long-lived `## Requirements` state for each target domain.
 
 ## Inputs
 
-- `<workflow slug>` for a completed loopx workflow
+- `<workflow slug>` for a completed loopx workflow, or for a review-approved workflow whose next route is `done`
 
 ## Behavior
 
@@ -34,9 +34,12 @@ Run:
 loopx archive <slug>
 ```
 
+If review already approved the workflow and the only pending transition is `review -> done`, this command consumes that completion transition before archiving. Do not ask the user to run a separate `loopx approve <slug> --from review --to done` command in that case.
+
 Then report in Chinese:
 
 - whether the change was archived
+- whether `review -> done` was consumed by archive
 - which long-lived spec files were updated
 - the archived change path
 - the ADR candidate path, if written
@@ -44,7 +47,7 @@ Then report in Chinese:
 
 ## Boundaries
 
-- Do not run archive before `review -> done` has been approved.
+- Do not run archive before review has approved the workflow and routed it to `done`.
 - Do not archive malformed requirement deltas. ADDED and MODIFIED entries must use `### Requirement:`, SHALL/MUST language, and at least one `#### Scenario:`.
 - Do not archive when `execution-record.md` declares non-empty `remaining_scope`, `completion_claim` other than `full`, or a mismatch between `planned_scope` and `implemented_scope`; route back to build/plan instead.
 - Do not edit implementation code.

package/plugins/loopx/skills/autopilot/SKILL.md

@@ -3,7 +3,7 @@ name: autopilot
 description: "Runs one bounded autonomous loopx orchestration over clarify, plan, build, and review while preserving canonical artifacts. Not for manual gate-by-gate control."
 when_to_use: "autopilot, autonomous loopx run, end-to-end workflow, run all stages, bounded orchestration, 自动执行, 全流程"
 metadata:
-  version: "0.1.5"
+  version: "0.1.7"
 argument-hint: "<workflow slug>"
 ---
 

package/plugins/loopx/skills/build/SKILL.md

@@ -3,7 +3,7 @@ name: build
 description: "Executes an approved loopx plan or review rework contract with evidence, verification, deslop, and regression gates. Not for unclear requirements or independent review."
 when_to_use: "build, implement approved plan, execute PRD, --from-review, review rework, implementation fixes, 执行, 实现, 修改"
 metadata:
-  version: "0.1.5"
+  version: "0.1.7"
 argument-hint: "[--no-deslop] <approved PRD path or workflow slug> | --from-review <review artifact path>"
 ---
 
@@ -200,6 +200,8 @@ These support artifacts are runtime aids only. They must not become new canonica
 <Final_Response_Contract>
 When `build` reaches review handoff readiness, the final response must include an explicit next skill command using the execution record path:
 
+Default review handoff after build readiness:
+
 ```text
 Next:
 $review .loopx/workflows/<slug>/execution-record.md

package/plugins/loopx/skills/clarify/SKILL.md

@@ -3,7 +3,7 @@ name: clarify
 description: "Clarifies ambiguous loopx work into requirements, non-goals, decision boundaries, and design-ready specs before planning. Not for already-approved plans or concrete implementation tasks."
 when_to_use: "clarify, requirements, ambiguous request, unclear scope, non-goals, decision boundaries, acceptance criteria, 需求澄清, 范围不清"
 metadata:
-  version: "0.1.5"
+  version: "0.1.7"
 ---
 
 # loopx Clarify
@@ -308,8 +308,11 @@ After the clarify spec is ready:
 
 Preferred explicit handoff contract:
 
-- Recommended invocation: `$plan <slug>`
-- Artifact-pinned invocation when needed: `$plan --direct .loopx/intake/clarify-<slug>-<timestamp>.md`
+- Default handoff after normal loopx clarify: `$plan <slug>`
+- Conditional artifact-pinned handoff: `$plan --direct <spec-path>`
+- Recommend `$plan --direct <spec-path>` when the user explicitly wants to plan from a specific requirements artifact, when the source is external/manual/legacy, or when multiple plausible spec files exist and the user has chosen one as the planning source of truth.
+- Do not use `$plan --direct` to work around unclear workflow state, missing approvals, or an uncertain slug; inspect or repair the loopx runtime state instead.
+- For the normal loopx clarify happy path, prefer `$plan <slug>` because the active workflow slug already anchors the clarify artifact and runtime state.
 - Consumer behavior: treat the clarify spec as the source of truth for intent, non-goals, decision boundaries, constraints, and design direction; do not reopen clarification by default
 
 `clarify` itself does not implement the feature. The handoff recommendation must name `plan` as the next workflow step.

package/plugins/loopx/skills/debug/SKILL.md

@@ -3,7 +3,7 @@ name: debug
 description: "Finds root cause for bugs, failing tests, build failures, regressions, and unexpected behavior before fixes. Not for new feature planning or routine code review."
 when_to_use: "debug, bug, test failure, build failure, regression, unexpected behavior, root cause, 报错, 失败, 回归, 排查"
 metadata:
-  version: "0.1.5"
+  version: "0.1.7"
 ---
 
 # Systematic Debugging

package/plugins/loopx/skills/go-style/SKILL.md

@@ -3,7 +3,7 @@ name: go-style
 description: "Applies loopx Go coding style for .go edits, tests, errors, context, naming, and interface boundaries. Not for non-Go code or Kratos-specific architecture by itself."
 when_to_use: "go-style, Go, golang, .go files, go tests, gofmt, idiomatic Go, Go style, Go 代码"
 metadata:
-  version: "0.1.5"
+  version: "0.1.7"
 ---
 
 # Go Style

package/plugins/loopx/skills/kratos/SKILL.md

@@ -3,7 +3,7 @@ name: kratos
 description: "Supports Go-Kratos microservices, proto/buf APIs, service/biz/data layers, middleware, auth, config, and troubleshooting. Not for generic Go style alone."
 when_to_use: "kratos, Go-Kratos, proto, buf, service layer, biz layer, data layer, middleware, auth, config, Kratos 微服务"
 metadata:
-  version: "0.1.5"
+  version: "0.1.7"
 ---
 
 # Kratos

package/plugins/loopx/skills/plan/SKILL.md

@@ -3,7 +3,7 @@ name: plan
 description: "Creates a consensus-first loopx plan package with Planner, Architect, and Critic review from an approved spec. Not for unresolved requirements or direct implementation."
 when_to_use: "plan, planning, consensus planning, PRD, architecture plan, test plan, approved clarify spec, 规划, 方案, 架构评审"
 metadata:
-  version: "0.1.5"
+  version: "0.1.7"
 argument-hint: "[--interactive] [--deliberate] [--direct <spec-path>] <clarified task or spec path>"
 ---
 
@@ -164,6 +164,7 @@ On approval, write canonical planning artifacts:
 - `.loopx/workflows/<slug>/architecture.md`
 - `.loopx/workflows/<slug>/development-plan.md`
 - `.loopx/workflows/<slug>/test-plan.md`
+- `.loopx/workflows/<slug>/requirement-traceability.md`
 - `.loopx/plans/prd-<slug>.md`
 - `.loopx/plans/test-spec-<slug>.md`
 - `.loopx/changes/active/<change-id>/proposal.md`
@@ -173,8 +174,17 @@ On approval, write canonical planning artifacts:
 - `.loopx/changes/active/<change-id>/slices.json`
 - `.loopx/changes/active/<change-id>/artifact-graph.json`
 
+Also generate derived HTML reading views:
+
+- `.loopx/workflows/<slug>/view/index.html`
+- `.loopx/workflows/<slug>/view/plan.html`
+- `.loopx/views/index.html`
+
+The HTML files are derived reading views for human plan review. They are not canonical fact sources; Markdown and JSON remain authoritative.
+
 The final plan must include:
 
+- a source-requirement coverage matrix that maps the original requirements/PRD to plan, architecture, slices, spec delta, and tests
 - ADR: Decision, Drivers, Alternatives considered, Why chosen, Consequences, Follow-ups
 - concrete implementation steps sized to the actual task
 - target long-lived spec domains and an OpenSpec-style requirements delta for archive
@@ -199,6 +209,24 @@ In `--interactive` mode, ask for the next lane:
 Without `--interactive`, report the approved plan and recommended next command, but do not launch execution.
 </Consensus_Workflow>
 
+<Final_Response_Contract>
+Default build handoff after an approved plan package:
+
+```text
+Next:
+$build .loopx/plans/prd-<slug>.md
+```
+
+Use the artifact-first PRD path because it pins build to the approved plan package. Do not emit `$build <slug>` as the primary handoff when `.loopx/plans/prd-<slug>.md` is known. If execution is not approved or plan gates remain blocked, state the blocker instead of emitting a build handoff.
+
+Also report the generated HTML reading entrypoint so the user can review the plan without running another command:
+
+```text
+HTML:
+.loopx/workflows/<slug>/view/index.html
+```
+</Final_Response_Contract>
+
 <Runtime_State_Machine>
 `plan` must keep the planning gate machine-checkable. Runtime state should track:
 
@@ -217,6 +245,8 @@ Without `--interactive`, report the approved plan and recommended next command,
 - `plan_acceptance_criteria_testable`: `true|false`
 - `plan_verification_steps_resolved`: `true|false`
 - `plan_execution_inputs_resolved`: `true|false`
+- `source_requirements_status`: `complete|partial`
+- `requirement_traceability_path`: `.loopx/workflows/<slug>/requirement-traceability.md`
 - `requested_transition`: remains explicit before build/autopilot
 
 The plan gate is blocked until:
@@ -231,6 +261,7 @@ The plan gate is blocked until:
 - acceptance criteria are testable
 - verification steps are concrete
 - execution inputs are fully mapped to concrete sources
+- source requirements are covered by `requirement-traceability.md`; uncovered original PRD requirements block build handoff
 - user approval exists for any execution transition
 </Runtime_State_Machine>
 
@@ -247,8 +278,10 @@ The plan gate is blocked until:
 Primary outputs:
 
 - approved plan package under `.loopx/workflows/<slug>/`
+- original source requirements and traceability matrix under `.loopx/workflows/<slug>/requirement-traceability.md`
 - canonical PRD and test spec under `.loopx/plans/`
 - change artifacts under `.loopx/changes/active/<change-id>/`
+- derived HTML reading views under `.loopx/workflows/<slug>/view/` and `.loopx/views/`
 - consensus review summary with Planner / Architect / Critic evidence
 - next-step recommendation
 

package/plugins/loopx/skills/review/SKILL.md

@@ -3,7 +3,7 @@ name: review
 description: "Reviews a loopx build execution record for acceptance, code risks, evidence quality, and architecture smells. Not for doing implementation work or replanning."
 when_to_use: "review, code review, acceptance, go no-go, execution-record, architecture smell, build complete, 审查, 验收"
 metadata:
-  version: "0.1.5"
+  version: "0.1.7"
 argument-hint: "<execution-record path or workflow slug>"
 ---
 
@@ -50,6 +50,7 @@ Use stable machine values only where they are commands, file paths, JSON/state f
 - Review should compare verification evidence against project-native commands recorded in `.loopx/config.json` when available, while still accepting stronger task-specific verification from the approved plan.
 - Review must include the architecture-smell lane as part of review evidence. This is not a new workflow stage and must not create extra user steps.
 - Review must compare the execution scope against the approved workflow scope. If `execution-record.md` declares non-empty `remaining_scope`, `completion_claim` other than `full`, or a mismatch between `planned_scope` and `implemented_scope`, review must return no-go and route to build or plan. A partial slice may be accepted as useful work, but it must not be approved as full workflow completion.
+- Review must compare implementation evidence against the original source requirements and `.loopx/workflows/<slug>/requirement-traceability.md`, not only against the generated plan. If the traceability matrix is missing, partial, or contradicted by code/tests, route to `review -> plan` or `review -> clarify` depending on whether the plan or requirements are wrong.
 - Code review findings should focus on real bugs, regressions, missing tests, broken contracts, security/data-integrity risks, and user-visible behavior gaps.
 - If code review finds blocking high or medium severity issues, return a no-go verdict and rollback guidance instead of approving completion.
 - If architecture-smell findings are only advisory, record them as warnings without blocking. Block only when module seams, testability, domain boundaries, duplicated rules, or plan architecture assumptions are materially wrong.
@@ -65,6 +66,8 @@ Every no-go review result must end with a concrete next command block.
 
 For implementation fixes:
 
+Default implementation-fix handoff:
+
 ```text
 Next:
 $build --from-review .loopx/workflows/<slug>/review-report.md

package/plugins/loopx/skills/tdd/SKILL.md

@@ -3,7 +3,7 @@ name: tdd
 description: "Guides feature and bugfix implementation through a failing test before production code and red-green-refactor discipline. Not for generated files or throwaway prototypes."
 when_to_use: "tdd, failing test first, feature implementation, bugfix, regression test, red green refactor, 测试先行"
 metadata:
-  version: "0.1.5"
+  version: "0.1.7"
 ---
 
 # Test-Driven Development (TDD)

package/plugins/loopx/skills/verify/SKILL.md

@@ -3,7 +3,7 @@ name: verify
 description: "Requires fresh verification evidence before claiming work is complete, fixed, passing, review-ready, or ready to commit. Not for speculative confidence or stale results."
 when_to_use: "verify, completion claim, fixed claim, tests pass, review-ready, commit, fresh evidence, 验证, 完成前检查"
 metadata:
-  version: "0.1.5"
+  version: "0.1.7"
 ---
 
 # Verification Before Completion

package/skills/archive/SKILL.md

@@ -3,7 +3,7 @@ name: archive
 description: "Archives an approved loopx change delta into long-lived specs and writes an ADR candidate after done approval. Not for active builds or unapproved reviews."
 when_to_use: "archive, done workflow, spec delta, long-lived specs, ADR candidate, review approved, 归档, 同步规格"
 metadata:
-  version: "0.1.5"
+  version: "0.1.7"
 argument-hint: "<workflow slug>"
 ---
 
@@ -11,7 +11,7 @@ argument-hint: "<workflow slug>"
 
 ## Purpose
 
-Use `archive` after a loopx workflow has reached `done`. It syncs the accepted change delta into long-lived `.loopx/specs/` files, archives the change staging directory, and writes an advisory ADR candidate.
+Use `archive` after a loopx workflow has reached `done`, or immediately after an approved review that is waiting for `review -> done` completion. It syncs the accepted change delta into long-lived `.loopx/specs/` files, archives the change staging directory, and writes an advisory ADR candidate.
 
 The accepted delta is requirement-based, not a changelog block. Archive applies:
 
@@ -24,7 +24,7 @@ into the current long-lived `## Requirements` state for each target domain.
 
 ## Inputs
 
-- `<workflow slug>` for a completed loopx workflow
+- `<workflow slug>` for a completed loopx workflow, or for a review-approved workflow whose next route is `done`
 
 ## Behavior
 
@@ -34,9 +34,12 @@ Run:
 loopx archive <slug>
 ```
 
+If review already approved the workflow and the only pending transition is `review -> done`, this command consumes that completion transition before archiving. Do not ask the user to run a separate `loopx approve <slug> --from review --to done` command in that case.
+
 Then report in Chinese:
 
 - whether the change was archived
+- whether `review -> done` was consumed by archive
 - which long-lived spec files were updated
 - the archived change path
 - the ADR candidate path, if written
@@ -44,7 +47,7 @@ Then report in Chinese:
 
 ## Boundaries
 
-- Do not run archive before `review -> done` has been approved.
+- Do not run archive before review has approved the workflow and routed it to `done`.
 - Do not archive malformed requirement deltas. ADDED and MODIFIED entries must use `### Requirement:`, SHALL/MUST language, and at least one `#### Scenario:`.
 - Do not archive when `execution-record.md` declares non-empty `remaining_scope`, `completion_claim` other than `full`, or a mismatch between `planned_scope` and `implemented_scope`; route back to build/plan instead.
 - Do not edit implementation code.

package/skills/autopilot/SKILL.md

@@ -3,7 +3,7 @@ name: autopilot
 description: "Runs one bounded autonomous loopx orchestration over clarify, plan, build, and review while preserving canonical artifacts. Not for manual gate-by-gate control."
 when_to_use: "autopilot, autonomous loopx run, end-to-end workflow, run all stages, bounded orchestration, 自动执行, 全流程"
 metadata:
-  version: "0.1.5"
+  version: "0.1.7"
 argument-hint: "<workflow slug>"
 ---
 

package/skills/build/SKILL.md

@@ -3,7 +3,7 @@ name: build
 description: "Executes an approved loopx plan or review rework contract with evidence, verification, deslop, and regression gates. Not for unclear requirements or independent review."
 when_to_use: "build, implement approved plan, execute PRD, --from-review, review rework, implementation fixes, 执行, 实现, 修改"
 metadata:
-  version: "0.1.5"
+  version: "0.1.7"
 argument-hint: "[--no-deslop] <approved PRD path or workflow slug> | --from-review <review artifact path>"
 ---
 
@@ -200,6 +200,8 @@ These support artifacts are runtime aids only. They must not become new canonica
 <Final_Response_Contract>
 When `build` reaches review handoff readiness, the final response must include an explicit next skill command using the execution record path:
 
+Default review handoff after build readiness:
+
 ```text
 Next:
 $review .loopx/workflows/<slug>/execution-record.md

package/skills/clarify/SKILL.md

@@ -3,7 +3,7 @@ name: clarify
 description: "Clarifies ambiguous loopx work into requirements, non-goals, decision boundaries, and design-ready specs before planning. Not for already-approved plans or concrete implementation tasks."
 when_to_use: "clarify, requirements, ambiguous request, unclear scope, non-goals, decision boundaries, acceptance criteria, 需求澄清, 范围不清"
 metadata:
-  version: "0.1.5"
+  version: "0.1.7"
 ---
 
 # loopx Clarify
@@ -308,8 +308,11 @@ After the clarify spec is ready:
 
 Preferred explicit handoff contract:
 
-- Recommended invocation: `$plan <slug>`
-- Artifact-pinned invocation when needed: `$plan --direct .loopx/intake/clarify-<slug>-<timestamp>.md`
+- Default handoff after normal loopx clarify: `$plan <slug>`
+- Conditional artifact-pinned handoff: `$plan --direct <spec-path>`
+- Recommend `$plan --direct <spec-path>` when the user explicitly wants to plan from a specific requirements artifact, when the source is external/manual/legacy, or when multiple plausible spec files exist and the user has chosen one as the planning source of truth.
+- Do not use `$plan --direct` to work around unclear workflow state, missing approvals, or an uncertain slug; inspect or repair the loopx runtime state instead.
+- For the normal loopx clarify happy path, prefer `$plan <slug>` because the active workflow slug already anchors the clarify artifact and runtime state.
 - Consumer behavior: treat the clarify spec as the source of truth for intent, non-goals, decision boundaries, constraints, and design direction; do not reopen clarification by default
 
 `clarify` itself does not implement the feature. The handoff recommendation must name `plan` as the next workflow step.

package/skills/debug/SKILL.md

@@ -3,7 +3,7 @@ name: debug
 description: "Finds root cause for bugs, failing tests, build failures, regressions, and unexpected behavior before fixes. Not for new feature planning or routine code review."
 when_to_use: "debug, bug, test failure, build failure, regression, unexpected behavior, root cause, 报错, 失败, 回归, 排查"
 metadata:
-  version: "0.1.5"
+  version: "0.1.7"
 ---
 
 # Systematic Debugging

package/skills/go-style/SKILL.md

@@ -3,7 +3,7 @@ name: go-style
 description: "Applies loopx Go coding style for .go edits, tests, errors, context, naming, and interface boundaries. Not for non-Go code or Kratos-specific architecture by itself."
 when_to_use: "go-style, Go, golang, .go files, go tests, gofmt, idiomatic Go, Go style, Go 代码"
 metadata:
-  version: "0.1.5"
+  version: "0.1.7"
 ---
 
 # Go Style

package/skills/kratos/SKILL.md

@@ -3,7 +3,7 @@ name: kratos
 description: "Supports Go-Kratos microservices, proto/buf APIs, service/biz/data layers, middleware, auth, config, and troubleshooting. Not for generic Go style alone."
 when_to_use: "kratos, Go-Kratos, proto, buf, service layer, biz layer, data layer, middleware, auth, config, Kratos 微服务"
 metadata:
-  version: "0.1.5"
+  version: "0.1.7"
 ---
 
 # Kratos

package/skills/plan/SKILL.md

@@ -3,7 +3,7 @@ name: plan
 description: "Creates a consensus-first loopx plan package with Planner, Architect, and Critic review from an approved spec. Not for unresolved requirements or direct implementation."
 when_to_use: "plan, planning, consensus planning, PRD, architecture plan, test plan, approved clarify spec, 规划, 方案, 架构评审"
 metadata:
-  version: "0.1.5"
+  version: "0.1.7"
 argument-hint: "[--interactive] [--deliberate] [--direct <spec-path>] <clarified task or spec path>"
 ---
 
@@ -164,6 +164,7 @@ On approval, write canonical planning artifacts:
 - `.loopx/workflows/<slug>/architecture.md`
 - `.loopx/workflows/<slug>/development-plan.md`
 - `.loopx/workflows/<slug>/test-plan.md`
+- `.loopx/workflows/<slug>/requirement-traceability.md`
 - `.loopx/plans/prd-<slug>.md`
 - `.loopx/plans/test-spec-<slug>.md`
 - `.loopx/changes/active/<change-id>/proposal.md`
@@ -173,8 +174,17 @@ On approval, write canonical planning artifacts:
 - `.loopx/changes/active/<change-id>/slices.json`
 - `.loopx/changes/active/<change-id>/artifact-graph.json`
 
+Also generate derived HTML reading views:
+
+- `.loopx/workflows/<slug>/view/index.html`
+- `.loopx/workflows/<slug>/view/plan.html`
+- `.loopx/views/index.html`
+
+The HTML files are derived reading views for human plan review. They are not canonical fact sources; Markdown and JSON remain authoritative.
+
 The final plan must include:
 
+- a source-requirement coverage matrix that maps the original requirements/PRD to plan, architecture, slices, spec delta, and tests
 - ADR: Decision, Drivers, Alternatives considered, Why chosen, Consequences, Follow-ups
 - concrete implementation steps sized to the actual task
 - target long-lived spec domains and an OpenSpec-style requirements delta for archive
@@ -199,6 +209,24 @@ In `--interactive` mode, ask for the next lane:
 Without `--interactive`, report the approved plan and recommended next command, but do not launch execution.
 </Consensus_Workflow>
 
+<Final_Response_Contract>
+Default build handoff after an approved plan package:
+
+```text
+Next:
+$build .loopx/plans/prd-<slug>.md
+```
+
+Use the artifact-first PRD path because it pins build to the approved plan package. Do not emit `$build <slug>` as the primary handoff when `.loopx/plans/prd-<slug>.md` is known. If execution is not approved or plan gates remain blocked, state the blocker instead of emitting a build handoff.
+
+Also report the generated HTML reading entrypoint so the user can review the plan without running another command:
+
+```text
+HTML:
+.loopx/workflows/<slug>/view/index.html
+```
+</Final_Response_Contract>
+
 <Runtime_State_Machine>
 `plan` must keep the planning gate machine-checkable. Runtime state should track:
 
@@ -217,6 +245,8 @@ Without `--interactive`, report the approved plan and recommended next command,
 - `plan_acceptance_criteria_testable`: `true|false`
 - `plan_verification_steps_resolved`: `true|false`
 - `plan_execution_inputs_resolved`: `true|false`
+- `source_requirements_status`: `complete|partial`
+- `requirement_traceability_path`: `.loopx/workflows/<slug>/requirement-traceability.md`
 - `requested_transition`: remains explicit before build/autopilot
 
 The plan gate is blocked until:
@@ -231,6 +261,7 @@ The plan gate is blocked until:
 - acceptance criteria are testable
 - verification steps are concrete
 - execution inputs are fully mapped to concrete sources
+- source requirements are covered by `requirement-traceability.md`; uncovered original PRD requirements block build handoff
 - user approval exists for any execution transition
 </Runtime_State_Machine>
 
@@ -247,8 +278,10 @@ The plan gate is blocked until:
 Primary outputs:
 
 - approved plan package under `.loopx/workflows/<slug>/`
+- original source requirements and traceability matrix under `.loopx/workflows/<slug>/requirement-traceability.md`
 - canonical PRD and test spec under `.loopx/plans/`
 - change artifacts under `.loopx/changes/active/<change-id>/`
+- derived HTML reading views under `.loopx/workflows/<slug>/view/` and `.loopx/views/`
 - consensus review summary with Planner / Architect / Critic evidence
 - next-step recommendation
 

package/skills/review/SKILL.md

@@ -3,7 +3,7 @@ name: review
 description: "Reviews a loopx build execution record for acceptance, code risks, evidence quality, and architecture smells. Not for doing implementation work or replanning."
 when_to_use: "review, code review, acceptance, go no-go, execution-record, architecture smell, build complete, 审查, 验收"
 metadata:
-  version: "0.1.5"
+  version: "0.1.7"
 argument-hint: "<execution-record path or workflow slug>"
 ---
 
@@ -50,6 +50,7 @@ Use stable machine values only where they are commands, file paths, JSON/state f
 - Review should compare verification evidence against project-native commands recorded in `.loopx/config.json` when available, while still accepting stronger task-specific verification from the approved plan.
 - Review must include the architecture-smell lane as part of review evidence. This is not a new workflow stage and must not create extra user steps.
 - Review must compare the execution scope against the approved workflow scope. If `execution-record.md` declares non-empty `remaining_scope`, `completion_claim` other than `full`, or a mismatch between `planned_scope` and `implemented_scope`, review must return no-go and route to build or plan. A partial slice may be accepted as useful work, but it must not be approved as full workflow completion.
+- Review must compare implementation evidence against the original source requirements and `.loopx/workflows/<slug>/requirement-traceability.md`, not only against the generated plan. If the traceability matrix is missing, partial, or contradicted by code/tests, route to `review -> plan` or `review -> clarify` depending on whether the plan or requirements are wrong.
 - Code review findings should focus on real bugs, regressions, missing tests, broken contracts, security/data-integrity risks, and user-visible behavior gaps.
 - If code review finds blocking high or medium severity issues, return a no-go verdict and rollback guidance instead of approving completion.
 - If architecture-smell findings are only advisory, record them as warnings without blocking. Block only when module seams, testability, domain boundaries, duplicated rules, or plan architecture assumptions are materially wrong.
@@ -65,6 +66,8 @@ Every no-go review result must end with a concrete next command block.
 
 For implementation fixes:
 
+Default implementation-fix handoff:
+
 ```text
 Next:
 $build --from-review .loopx/workflows/<slug>/review-report.md

package/skills/tdd/SKILL.md

@@ -3,7 +3,7 @@ name: tdd
 description: "Guides feature and bugfix implementation through a failing test before production code and red-green-refactor discipline. Not for generated files or throwaway prototypes."
 when_to_use: "tdd, failing test first, feature implementation, bugfix, regression test, red green refactor, 测试先行"
 metadata:
-  version: "0.1.5"
+  version: "0.1.7"
 ---
 
 # Test-Driven Development (TDD)

package/skills/verify/SKILL.md

@@ -3,7 +3,7 @@ name: verify
 description: "Requires fresh verification evidence before claiming work is complete, fixed, passing, review-ready, or ready to commit. Not for speculative confidence or stale results."
 when_to_use: "verify, completion claim, fixed claim, tests pass, review-ready, commit, fresh evidence, 验证, 完成前检查"
 metadata:
-  version: "0.1.5"
+  version: "0.1.7"
 ---
 
 # Verification Before Completion

package/src/cli.mjs

@@ -85,6 +85,8 @@ function printHumanStatus(status) {
     console.log(`plan_architect_review_status: ${status.state.plan_architect_review_status}`);
     console.log(`plan_critic_verdict: ${status.state.plan_critic_verdict}`);
     console.log(`plan_artifact_status: ${status.state.plan_docs_status}`);
+    console.log(`source_requirements_status: ${status.state.source_requirements_status ?? 'unknown'}`);
+    console.log(`requirement_traceability_path: ${status.state.requirement_traceability_path ?? '(none)'}`);
     console.log(`plan_blockers: ${Array.isArray(status.state.plan_blockers) && status.state.plan_blockers.length > 0 ? status.state.plan_blockers.join(', ') : '(none)'}`);
   }
   if (status.state?.current_stage === 'build') {

package/src/context-manifest.mjs

@@ -128,6 +128,8 @@ export async function generateBuildContextManifest({ cwd, root, state, slug }) {
     || (state.current_stage === 'review' && state.rollback_target === 'build');
   const rows = [
     row(cwd, { stage: 'build', kind: 'spec', path: join(root, 'spec.md'), reason: 'clarified_requirements', priority: 10 }),
+    row(cwd, { stage: 'build', kind: 'source-requirements', path: state.plan_source_spec_path || join(root, 'spec.md'), reason: 'original_requirements_source_of_truth', priority: 11 }),
+    row(cwd, { stage: 'build', kind: 'requirement-traceability', path: state.requirement_traceability_path || join(root, 'requirement-traceability.md'), reason: 'source_requirement_coverage_gate', priority: 12 }),
     row(cwd, { stage: 'build', kind: 'plan', path: join(root, 'plan.md'), reason: 'implementation_strategy', priority: 20 }),
     row(cwd, { stage: 'build', kind: 'architecture', path: join(root, 'architecture.md'), reason: 'architecture_constraints', priority: 21 }),
     row(cwd, { stage: 'build', kind: 'development-plan', path: join(root, 'development-plan.md'), reason: 'execution_steps', priority: 22 }),
@@ -150,6 +152,8 @@ export async function generateReviewContextManifest({ cwd, root, state, slug })
   const contextSetup = await inspectWorkspaceContext(cwd);
   const rows = [
     row(cwd, { stage: 'review', kind: 'execution-record', path: join(root, 'execution-record.md'), reason: 'execution_evidence', priority: 10 }),
+    row(cwd, { stage: 'review', kind: 'source-requirements', path: state.plan_source_spec_path || join(root, 'spec.md'), reason: 'original_requirements_source_of_truth', priority: 11 }),
+    row(cwd, { stage: 'review', kind: 'requirement-traceability', path: state.requirement_traceability_path || join(root, 'requirement-traceability.md'), reason: 'source_requirement_coverage_gate', priority: 12 }),
     row(cwd, { stage: 'review', kind: 'test-spec', path: state.test_spec_artifact_path || join(cwd, '.loopx', 'plans', `test-spec-${slug}.md`), reason: 'acceptance_tests', priority: 20 }),
     row(cwd, { stage: 'review', kind: 'prd', path: state.plan_artifact_path || join(cwd, '.loopx', 'plans', `prd-${slug}.md`), reason: 'requirements', priority: 21 }),
     row(cwd, { stage: 'review', kind: 'vertical-slices', path: state.change_artifact_paths?.slices || join(cwd, '.loopx', 'changes', 'active', state.change_id || `chg-${slug}`, 'slices.json'), reason: 'slice_verification_contract', priority: 22 }),

package/src/plan-runtime.mjs

@@ -364,6 +364,7 @@ export function createRealPlanAdapter({ model } = {}) {
         `Deliberate mode: ${Boolean(context.deliberateMode)}`,
         '',
         'Use Chinese for planText / architectureText / developmentPlanText / testPlanText.',
+        'Treat the source requirements/PRD as the source of truth. Explicitly cover every named event, field, processing mode, table row, and acceptance item that appears in the source, or clearly mark it out of scope with rationale.',
         'If previous review feedback is present, revise the plan to explicitly resolve it. Do not repeat the same plan unchanged.',
         'Do not ask questions. Do not wrap JSON in markdown.',
         '',

package/src/workflow.mjs

@@ -357,7 +357,7 @@ function buildWorkspaceReadme() {
     '- `workflows/<slug>/spec.md`',
     '- `workflows/<slug>/plan.md`, `architecture.md`, `development-plan.md`, and `test-plan.md`',
     '- `workflows/<slug>/execution-record.md` and `review-report.md`',
-    '- `views/index.html` and `workflows/<slug>/view/index.html` after `loopx render`',
+    '- `views/index.html` and `workflows/<slug>/view/index.html` after `loopx plan` or `loopx render`',
     '',
     'Documents users may read and edit as workflow fact sources:',
     '',
@@ -558,6 +558,16 @@ function dedupeStrings(items) {
   return [...new Set((items || []).map((item) => String(item || '').trim()).filter(Boolean))];
 }
 
+function slugKey(raw) {
+  return String(raw || '')
+    .trim()
+    .toLowerCase()
+    .replace(/[`'"*_#()[\]{}]/g, '')
+    .replace(/[^a-z0-9\u4e00-\u9fff]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 80) || 'requirement';
+}
+
 function bulletsFromSectionText(text, heading) {
   const pattern = new RegExp(`#{2,3} ${heading}\\n\\n([\\s\\S]*?)(?=\\n#{2,3} |$)`, 'i');
   const match = text.match(pattern);
@@ -572,6 +582,173 @@ function bulletsFromSectionText(text, heading) {
     .filter(Boolean);
 }
 
+function sectionBodyForHeadings(text, headingPatterns) {
+  const body = stripFrontmatter(text);
+  const headingPattern = /^#{2,4}\s+(.+?)\s*$/gm;
+  const headings = [...body.matchAll(headingPattern)];
+  for (let index = 0; index < headings.length; index += 1) {
+    const title = headings[index][1].trim();
+    if (!headingPatterns.some((pattern) => pattern.test(title))) {
+      continue;
+    }
+    const start = headings[index].index + headings[index][0].length;
+    const end = index + 1 < headings.length ? headings[index + 1].index : body.length;
+    return body.slice(start, end).trim();
+  }
+  return '';
+}
+
+function explicitCoverageItems(sourceText) {
+  const body = sectionBodyForHeadings(sourceText, [
+    /required\s+coverage/i,
+    /requirement\s+coverage/i,
+    /coverage\s+matrix/i,
+    /需求.*覆盖/,
+    /需求.*完整/,
+    /需求.*卡点/,
+  ]);
+  if (!body) {
+    return [];
+  }
+  return body
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => /^[-*]\s+/.test(line) || /^\d+[.)]\s+/.test(line))
+    .map((line) => line.replace(/^[-*]\s+/, '').replace(/^\d+[.)]\s+/, '').trim())
+    .filter(Boolean);
+}
+
+function markdownTableCoverageItems(sourceText) {
+  const items = [];
+  const lines = String(sourceText || '').split('\n');
+  let currentHeading = '';
+  for (const line of lines) {
+    const heading = line.match(/^#{2,4}\s+(.+?)\s*$/);
+    if (heading) {
+      currentHeading = heading[1].trim();
+      continue;
+    }
+    if (!line.trim().startsWith('|')) {
+      continue;
+    }
+    const cells = line.split('|').slice(1, -1).map((cell) => cell.trim()).filter(Boolean);
+    if (cells.length < 2 || cells.every((cell) => /^:?-{3,}:?$/.test(cell))) {
+      continue;
+    }
+    const first = cells[0].replace(/`/g, '').trim();
+    if (!first || /^(字段|事件类型|模块|维度|对象|处理环节|field|type|module)$/i.test(first)) {
+      continue;
+    }
+    if (
+      /事件|字段|处理模式|标准化|范围|任务|确认|下发|source|event|field|coverage|requirement/i.test(currentHeading)
+      || cells.some((cell) => /SHALL|MUST|Reuters|OCC|manual_|raw_snapshot|event_|处理|确认|下发|不自动/i.test(cell))
+    ) {
+      items.push(first);
+    }
+  }
+  return items;
+}
+
+function requirementHeadingCoverageItems(sourceText) {
+  return [...String(sourceText || '').matchAll(/^###\s+Requirement:\s*(.+?)\s*$/gim)]
+    .map((match) => match[1].trim())
+    .filter(Boolean);
+}
+
+function sourceRequirementItems(sourceText) {
+  return dedupeStrings([
+    ...explicitCoverageItems(sourceText),
+    ...markdownTableCoverageItems(sourceText),
+    ...requirementHeadingCoverageItems(sourceText),
+  ]).slice(0, 80);
+}
+
+function normalizedCoverageText(...parts) {
+  return parts.join('\n')
+    .toLowerCase()
+    .replace(/[`'"*_#()[\]{}]/g, '')
+    .replace(/\s+/g, ' ');
+}
+
+function sourceRequirementCovered(item, haystack) {
+  const raw = String(item || '').trim();
+  if (!raw) {
+    return true;
+  }
+  const compactNeedle = raw.toLowerCase().replace(/\s+/g, '');
+  const compactHaystack = haystack.replace(/\s+/g, '');
+  if (compactNeedle.length >= 2 && compactHaystack.includes(compactNeedle)) {
+    return true;
+  }
+  const tokens = raw
+    .toLowerCase()
+    .replace(/[`'"*_#()[\]{}]/g, ' ')
+    .split(/[^a-z0-9\u4e00-\u9fff]+/)
+    .map((token) => token.trim())
+    .filter((token) => token.length >= 2)
+    .filter((token) => !['the', 'and', 'for', 'with', 'from', 'this', 'that'].includes(token));
+  if (tokens.length === 0) {
+    return false;
+  }
+  return tokens.every((token) => haystack.includes(token));
+}
+
+async function writeRequirementTraceabilityArtifact({ root, sourceSpecPath, sourceText, plannerDraft, changeArtifactPaths }) {
+  const traceabilityPath = artifactPath(root, 'requirement-traceability.md');
+  const sourceItems = sourceRequirementItems(sourceText);
+  const specDeltaText = changeArtifactPaths?.specDelta && existsSync(changeArtifactPaths.specDelta)
+    ? await readFile(changeArtifactPaths.specDelta, 'utf8')
+    : '';
+  const slicesText = changeArtifactPaths?.slices && existsSync(changeArtifactPaths.slices)
+    ? await readFile(changeArtifactPaths.slices, 'utf8')
+    : '';
+  const haystack = normalizedCoverageText(
+    plannerDraft.planText,
+    plannerDraft.architectureText,
+    plannerDraft.developmentPlanText,
+    plannerDraft.testPlanText,
+    specDeltaText,
+    slicesText,
+  );
+  const rows = sourceItems.map((item) => ({
+    item,
+    status: sourceRequirementCovered(item, haystack) ? 'covered' : 'uncovered',
+  }));
+  const blockers = rows
+    .filter((row) => row.status !== 'covered')
+    .map((row) => `source_requirement_uncovered_${slugKey(row.item)}`);
+  const status = blockers.length > 0 ? 'partial' : 'complete';
+
+  await writeText(traceabilityPath, [
+    '# Source Requirements Traceability',
+    '',
+    `- source: ${sourceSpecPath}`,
+    `- status: ${status}`,
+    `- extracted_items: ${rows.length}`,
+    '',
+    '## Coverage Matrix',
+    '',
+    '| Source requirement | Status |',
+    '| --- | --- |',
+    ...(rows.length > 0
+      ? rows.map((row) => `| ${row.item.replace(/\|/g, '\\|')} | ${row.status} |`)
+      : ['| No explicit source coverage items detected | covered |']),
+    '',
+    '## Gate',
+    '',
+    ...(blockers.length > 0
+      ? blockers.map((blocker) => `- ${blocker}`)
+      : ['- complete']),
+  ].join('\n'));
+
+  return {
+    path: traceabilityPath,
+    status,
+    blockers,
+    itemCount: rows.length,
+  };
+}
+
 function frontmatterList(text, key) {
   if (!text.startsWith('---\n')) {
     return [];
@@ -1498,6 +1675,26 @@ async function readPlanCompletion(cwd, root, slug, state) {
   if (!state.test_spec_artifact_path || !existsSync(state.test_spec_artifact_path)) {
     blockers.push('missing_test_spec');
   }
+  if (!state.plan_source_spec_path || !existsSync(state.plan_source_spec_path)) {
+    blockers.push('missing_source_requirements');
+  }
+  if (!state.requirement_traceability_path || !existsSync(state.requirement_traceability_path)) {
+    blockers.push('missing_requirement_traceability');
+  }
+  if (state.source_requirements_status && state.source_requirements_status !== 'complete') {
+    if (state.requirement_traceability_path && existsSync(state.requirement_traceability_path)) {
+      const traceabilityText = await readFile(state.requirement_traceability_path, 'utf8');
+      blockers.push(
+        ...traceabilityText
+          .split('\n')
+          .map((line) => line.trim())
+          .filter((line) => line.startsWith('- source_requirement_'))
+          .map((line) => line.slice(2).trim()),
+      );
+    } else {
+      blockers.push(`source_requirements_${state.source_requirements_status}`);
+    }
+  }
   const workflowDocs = {
     plan: artifactPath(root, 'plan.md'),
     architecture: artifactPath(root, 'architecture.md'),
@@ -1520,6 +1717,7 @@ async function readPlanCompletion(cwd, root, slug, state) {
   return {
     blockers,
     docsStatus: blockers.some((blocker) => blocker.startsWith('missing_plan_artifact_') || blocker.startsWith('plan_artifact_not_chinese_')) ? 'partial' : 'complete',
+    sourceRequirementsStatus: blockers.some((blocker) => blocker === 'missing_source_requirements' || blocker === 'missing_requirement_traceability' || blocker.startsWith('source_requirement_') || blocker.startsWith('source_requirements_')) ? 'partial' : 'complete',
     changeArtifactsStatus: changeStatus.status,
     specDeltaStatus: changeStatus.specDeltaStatus,
     sliceArtifactsStatus: changeStatus.sliceArtifactsStatus,
@@ -2508,6 +2706,28 @@ async function refreshExecutionStatus(root, state) {
   };
 }
 
+async function renderPlanReadingViews(cwd, root, state, slug) {
+  try {
+    const { renderHtmlViews } = await import('./html-views.mjs');
+    const rendered = await renderHtmlViews(cwd, { slug });
+    return {
+      ...state,
+      html_view_status: 'written',
+      html_view_path: rendered.workflowViewPath,
+      workspace_view_path: rendered.workspaceViewPath,
+      html_view_error: null,
+    };
+  } catch (error) {
+    return {
+      ...state,
+      html_view_status: 'failed',
+      html_view_path: join(root, 'view', 'index.html'),
+      workspace_view_path: join(resolveWorkspaceRoot(cwd), 'views', 'index.html'),
+      html_view_error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
 export async function initWorkspace(cwd, { slug } = {}) {
   const workspaceRoot = resolveWorkspaceRoot(cwd);
   const projectConventions = await inspectProjectConventions(cwd);
@@ -2785,8 +3005,64 @@ export async function approveStage(cwd, slug, { from, to }) {
   return { root, state: next };
 }
 
+function isDoneRoute(value) {
+  return value === TRANSITIONS.REVIEW_TO_DONE || value === STAGES.DONE;
+}
+
+function canArchiveConsumePendingDoneApproval(state) {
+  if (state.current_stage !== STAGES.REVIEW) {
+    return false;
+  }
+  const reviewVerdict = String(state.review_verdict || '').trim().toLowerCase();
+  const reviewApproved = reviewVerdict === 'approve' || reviewVerdict === 'go';
+  const routesToDone = [
+    state.pending_user_decision,
+    state.requested_transition,
+    state.review_route,
+    state.requested_transition_after_review,
+  ].some(isDoneRoute);
+  const completionRequested = [
+    APPROVAL_STATES.REQUESTED,
+    APPROVAL_STATES.APPROVED,
+  ].includes(state.approval?.complete) || state.execution_approved === true || state.execution_approved_for_review === true;
+  return reviewApproved && routesToDone && completionRequested;
+}
+
+async function consumePendingDoneApprovalForArchive(cwd, root, state, slug) {
+  if (!canArchiveConsumePendingDoneApproval(state)) {
+    return { root, state, consumed: false };
+  }
+  const normalized = withRecommendedAction({
+    ...state,
+    review_verdict: 'approve',
+    pending_user_decision: TRANSITIONS.REVIEW_TO_DONE,
+    requested_transition: TRANSITIONS.NONE,
+    approval: {
+      ...state.approval,
+      review: APPROVAL_STATES.APPROVED,
+      complete: state.approval?.complete || APPROVAL_STATES.REQUESTED,
+    },
+  });
+  await writeState(root, normalized);
+  const done = await approveStage(cwd, slug, { from: STAGES.REVIEW, to: STAGES.DONE });
+  return {
+    root: done.root,
+    state: {
+      ...done.state,
+      archive_consumed_pending_done_approval: true,
+    },
+    consumed: true,
+  };
+}
+
 export async function archiveStage(cwd, slug) {
-  const { root, state, slug: normalized } = await loadWorkflowState(cwd, slug, { allowLegacy: false });
+  const loaded = await loadWorkflowState(cwd, slug, { allowLegacy: false });
+  const normalized = loaded.slug;
+  let root = loaded.root;
+  let state = loaded.state;
+  const doneApproval = await consumePendingDoneApprovalForArchive(cwd, root, state, normalized);
+  root = doneApproval.root;
+  state = doneApproval.state;
   if (state.current_stage !== STAGES.DONE || !state.completion_confirmed) {
     throw new Error('archive_requires_done_workflow');
   }
@@ -2916,6 +3192,13 @@ export async function planStage(cwd, slug, options = {}) {
     const changeId = state.change_id || changeIdForWorkflowSlug(normalized);
     const changeArtifactPaths = await writeChangeArtifacts(cwd, root, normalized, sourceText, plannerDraft, changeId);
     const changeArtifactStatus = await readChangeArtifactStatus(changeArtifactPaths);
+    const traceability = await writeRequirementTraceabilityArtifact({
+      root,
+      sourceSpecPath,
+      sourceText,
+      plannerDraft,
+      changeArtifactPaths,
+    });
 
     architectReview = await adapter.architect({
       cwd,
@@ -2961,6 +3244,9 @@ export async function planStage(cwd, slug, options = {}) {
       plan_review_history: reviewHistory,
       plan_artifact_path: artifactPaths.planPath,
       test_spec_artifact_path: artifactPaths.testSpecPath,
+      requirement_traceability_path: traceability.path,
+      source_requirements_status: traceability.status,
+      source_requirements_item_count: traceability.itemCount,
       change_id: normalizeSlug(changeId),
       change_artifacts_status: changeArtifactStatus.status,
       change_artifact_paths: changeArtifactPaths,
@@ -2996,6 +3282,7 @@ export async function planStage(cwd, slug, options = {}) {
     requested_transition: TRANSITIONS.NONE,
     plan_docs_status: completion.docsStatus,
     plan_docs_artifact_paths: null,
+    source_requirements_status: completion.sourceRequirementsStatus,
     change_artifacts_status: completion.changeArtifactsStatus,
     spec_delta_status: completion.specDeltaStatus,
     slice_artifacts_status: completion.sliceArtifactsStatus,
@@ -3004,7 +3291,9 @@ export async function planStage(cwd, slug, options = {}) {
     build_context_manifest_path: buildManifest?.path || buildContextManifestPath(root),
   });
   await writeState(root, next);
-  return { root, state: next, architectReview, criticReview };
+  const renderedNext = await renderPlanReadingViews(cwd, root, next, normalized);
+  await writeState(root, renderedNext);
+  return { root, state: renderedNext, architectReview, criticReview };
 }
 
 export async function buildStage(cwd, slug, options = {}) {