@ai-content-space/loopx 0.1.6 → 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
@@ -231,9 +227,12 @@ 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.
 
 ### build
@@ -268,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>/
@@ -386,6 +385,7 @@ 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 written after `plan` and regenerated by `loopx render`.
 
@@ -521,4 +521,4 @@ node src/cli.mjs status --json
 
 ## Version
 
-Current npm package version: `0.1.6`.
+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
@@ -233,9 +229,12 @@ 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 当前状态。
 
 ### build
@@ -279,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>/
@@ -397,6 +396,7 @@ 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`：plan 后写入、也可由 `loopx render` 重新生成的阅读入口。
 
@@ -532,4 +532,4 @@ node src/cli.mjs status --json
 
 ## 版本
 
-当前 npm 包版本：`0.1.6`。
+当前 npm 包版本：`0.1.7`。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ai-content-space/loopx",
   "type": "module",
-  "version": "0.1.6",
+  "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.6",
+  "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.6"
+  version: "0.1.7"
 argument-hint: "<workflow slug>"
 ---
 

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.6"
+  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.6"
+  version: "0.1.7"
 argument-hint: "[--no-deslop] <approved PRD path or workflow slug> | --from-review <review artifact path>"
 ---
 

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.6"
+  version: "0.1.7"
 ---
 
 # loopx Clarify

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.6"
+  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.6"
+  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.6"
+  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.6"
+  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`
@@ -183,6 +184,7 @@ The HTML files are derived reading views for human plan review. They are not can
 
 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
@@ -243,6 +245,8 @@ HTML:
 - `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:
@@ -257,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>
 
@@ -273,6 +278,7 @@ 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/`

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.6"
+  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.

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.6"
+  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.6"
+  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.6"
+  version: "0.1.7"
 argument-hint: "<workflow slug>"
 ---
 

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.6"
+  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.6"
+  version: "0.1.7"
 argument-hint: "[--no-deslop] <approved PRD path or workflow slug> | --from-review <review artifact path>"
 ---
 

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.6"
+  version: "0.1.7"
 ---
 
 # loopx Clarify

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.6"
+  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.6"
+  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.6"
+  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.6"
+  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`
@@ -183,6 +184,7 @@ The HTML files are derived reading views for human plan review. They are not can
 
 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
@@ -243,6 +245,8 @@ HTML:
 - `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:
@@ -257,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>
 
@@ -273,6 +278,7 @@ 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/`

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.6"
+  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.

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.6"
+  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.6"
+  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

@@ -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,
@@ -2994,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,
@@ -3039,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,
@@ -3074,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,