@pzy560117/codex-harness 0.1.0 → 0.1.2

package/package-source/docs/codex-harness-engineering/templates/runtime/project-task-template.json

@@ -0,0 +1,1047 @@
+{
+  "runtime": {
+    "driver": "powershell -NoProfile -ExecutionPolicy Bypass -File .\\tools\\harness\\tools/harness/codex-loop.ps1",
+    "trace_dir": "traces",
+    "agent": "codex",
+    "run_profile": ".codex\\task-run-profile.json",
+    "git": {
+      "require_clean_workspace": true,
+      "non_blocking_dirty_paths": []
+    },
+    "session": {
+      "mode": "fresh-process",
+      "carry_forward_summary": false
+    },
+    "subagents": {
+      "mode": "guided",
+      "allowed_roles": [
+        "explorer",
+        "readonly-research",
+        "docs-researcher",
+        "planner",
+        "architect",
+        "reviewer",
+        "stage1-reviewer",
+        "stage2-reviewer",
+        "security-reviewer",
+        "test-planner",
+        "failure-triage",
+        "visual-reviewer",
+        "harness-writer",
+        "docs-worker",
+        "frontend-worker",
+        "backend-worker",
+        "test-runner"
+      ],
+      "max_parallel_roles": 3
+    },
+    "handoff": {
+      "truth_sources": {
+        "architecture": [
+          "docs/architecture/constraints.md"
+        ]
+      }
+    },
+    "codex": {
+      "implementation_sandbox": "danger-full-access",
+      "review_sandbox": "danger-full-access",
+      "disable_hooks": false
+    }
+  },
+  "tasks": [
+    {
+      "id": "INIT-001",
+      "description": "锁定已确认 spec、初始 dev-plan 和 driver 接管边界",
+      "task_kind": "feature_plan",
+      "phase": "handoff",
+      "gate_profile": "spec_required",
+      "required_truth_sources": [
+        "product",
+        "plan"
+      ],
+      "priority": 1,
+      "dependencies": [],
+      "passes": false,
+      "context_files": [
+        "AGENTS.md",
+        "tools/harness/templates/project-task-template.json",
+        "docs/architecture/constraints.md",
+        "docs/product/prd-lite.md",
+        "docs/product/acceptance-criteria.md",
+        "docs/product/requirement-interface-matrix.md",
+        "plans/features/<feature-slug>.dev-plan.md",
+        "docs/testing/verify-matrix.md"
+      ],
+      "owned_paths": [
+        "docs/product/",
+        "docs/architecture/",
+        "docs/testing/",
+        "plans/"
+      ],
+      "requirement_ids": [
+        "META-HANDOFF-REPLACE"
+      ],
+      "produces_artifacts": [
+        "docs/testing/verify-matrix.md",
+        "docs/architecture/constraints.md",
+        "task.json"
+      ],
+      "execution": {
+        "mode": "single"
+      },
+      "steps": [
+        "把模板中的 <feature-slug>、用户故事标题、requirement_ids、owned_paths、context_files 和 test_command 全部替换成当前项目真实值",
+        "确认 task 依赖、优先级、execution.mode 和 non_blocking_dirty_paths 已与当前项目约束一致",
+        "确认架构约束 truth source 已明确交付形态、公开入口、数据边界、异步边界、测试替身策略、禁止实现和 Definition of Done；如项目不用默认路径，更新 runtime.handoff.truth_sources.architecture",
+        "确认当前 task.json 已经是正式任务队列，不再保留领域示例、smoke 占位或过期路径"
+      ],
+      "test_command": "git diff --check",
+      "acceptance": [
+        "任务队列只保留当前项目真实阶段与用户故事",
+        "架构约束 truth source 已成为后续实现任务的前置依据",
+        "plan 入口已经使用 plans/**/*.dev-plan.md 路径体系",
+        "后续任务不再依赖聊天补 requirement_ids、owned_paths 或验证命令"
+      ]
+    },
+    {
+      "id": "ANALYSIS-001",
+      "description": "补齐需求追溯、测试左移材料和 repo context 真相源",
+      "task_kind": "feature_research",
+      "phase": "analysis",
+      "gate_profile": "research_required",
+      "required_truth_sources": [
+        "product",
+        "plan"
+      ],
+      "priority": 5,
+      "dependencies": [
+        "INIT-001"
+      ],
+      "passes": false,
+      "context_files": [
+        "docs/product/prd-lite.md",
+        "docs/product/page-inventory.md",
+        "docs/product/state-matrix.yaml",
+        "docs/product/acceptance-criteria.md",
+        "docs/product/requirement-interface-matrix.md",
+        "docs/architecture/constraints.md",
+        "plans/features/<feature-slug>.dev-plan.md"
+      ],
+      "owned_paths": [
+        "docs/product/",
+        "docs/architecture/",
+        "docs/testing/",
+        "docs/context/"
+      ],
+      "requirement_ids": [
+        "REQ-REPLACE-ANALYSIS"
+      ],
+      "produces_artifacts": [
+        "docs/product/difficulty-research.md",
+        "docs/context/feature-pack.md",
+        "docs/context/repo-map.md",
+        "docs/context/architecture-brief.md",
+        "docs/architecture/constraints.md",
+        "docs/testing/ACCEPTANCE_CRITERIA.md",
+        "docs/testing/ACCEPTANCE_EXAMPLES.md",
+        "docs/testing/NATURAL_LANGUAGE_TEST_CASES.md",
+        "docs/testing/TRACEABILITY_MATRIX.md",
+        "docs/testing/TEST_DATA_MATRIX.md",
+        "docs/testing/test-matrix.md",
+        "docs/testing/verify-matrix.md",
+        "docs/testing/RISK_BASED_TEST_PLAN.md",
+        "docs/testing/REGRESSION_PLAN.md",
+        "docs/testing/EVIDENCE_PROTOCOL.md",
+        "docs/testing/failure-triage.md"
+      ],
+      "execution": {
+        "mode": "single"
+      },
+      "steps": [
+        "围绕已确认 spec 补齐页面清单、状态矩阵、边界条件、异常流和难点研究",
+        "先从 docs/ai/repo-map.md 或 docs/context/repo-map.md 进入代码结构，再补局部文件阅读；不要直接全仓盲扫",
+        "把 Requirement IDs 映射到界面、状态、接口、测试层级、测试数据和证据路径",
+        "输出可复用的代码理解摘要，至少包含入口、关键调用链、受影响文件、受影响测试和高风险点",
+        "把系统交付形态、公开入口、数据边界、异步边界、测试替身策略和禁止实现写入架构约束 truth source",
+        "生成后续设计和实现必须依赖的 feature-pack、repo-map、architecture-brief 与 testing truth source",
+        "如果任务涉及用户可见行为、路由、表单、权限、状态流转或关键业务闭环，补齐 docs/testing/e2e-plan.md 或同等 feature 级 E2E 计划"
+      ],
+      "test_command": "git diff --check",
+      "acceptance": [
+        "产品追溯和测试左移文档已补齐且可被后续任务直接消费",
+        "架构约束 truth source 足以让后续任务区分声明交付路径、领域原型和测试替身",
+        "repo_context 与 testing truth source 已达到后续 design / implement 阶段可用状态"
+      ]
+    },
+    {
+      "id": "TESTCASE-001",
+      "description": "基于 PRD 逐条生成自然语言测试用例并沉淀 TDD 种子",
+      "task_kind": "testcase_design",
+      "phase": "testcase",
+      "gate_profile": "spec_required",
+      "required_truth_sources": [
+        "product",
+        "testing"
+      ],
+      "priority": 6,
+      "dependencies": [
+        "ANALYSIS-001"
+      ],
+      "passes": false,
+      "context_files": [
+        "docs/product/prd-lite.md",
+        "docs/product/acceptance-criteria.md",
+        "docs/product/requirement-interface-matrix.md",
+        "docs/testing/ACCEPTANCE_CRITERIA.md",
+        "docs/testing/ACCEPTANCE_EXAMPLES.md",
+        "docs/testing/TRACEABILITY_MATRIX.md",
+        "docs/testing/TEST_DATA_MATRIX.md",
+        "docs/testing/RISK_BASED_TEST_PLAN.md",
+        "docs/testing/EVIDENCE_PROTOCOL.md"
+      ],
+      "owned_paths": [
+        "docs/testing/"
+      ],
+      "requirement_ids": [
+        "REQ-REPLACE-TESTCASE"
+      ],
+      "produces_artifacts": [
+        "docs/testing/NATURAL_LANGUAGE_TEST_CASES.md",
+        "docs/testing/TRACEABILITY_MATRIX.md",
+        "docs/testing/test-matrix.md",
+        "docs/testing/TEST_DATA_MATRIX.md",
+        "docs/testing/verify-matrix.md"
+      ],
+      "execution": {
+        "mode": "single"
+      },
+      "steps": [
+        "逐条读取 PRD / acceptance criteria / requirement-interface-matrix 中的需求和 Requirement IDs",
+        "为每条需求识别需求类型、优先级和风险因子，并按 NATURAL_LANGUAGE_TEST_CASES.md 的需求类型覆盖矩阵确定最少用例数",
+        "为每条 P0/P1 需求生成满足最小数量要求的自然语言测试用例，覆盖 happy path、边界、异常、权限、状态流转、并发或无副作用验证",
+        "为 P2 需求生成 1-2 条自然语言测试用例，或写明豁免原因、替代证据和 owner 批准人",
+        "为每条自然语言用例写清前置条件、测试数据、操作步骤、预期结果、Oracle、推荐测试层级、证据路径和 TDD RED 预期失败",
+        "在覆盖检查中记录需求类型、风险因子、矩阵基准用例数、风险加量、最终要求用例数、已写用例数和加量理由",
+        "把不适合作为 TDD RED 的自然语言用例映射到 story_full_chain、acceptance_validation、回归计划或 verify-matrix",
+        "把自然语言用例 ID 回填到 TRACEABILITY_MATRIX、test-matrix、TEST_DATA_MATRIX 和 verify-matrix，作为后续 tdd_contract 的来源"
+      ],
+      "test_command": "git diff --check",
+      "acceptance": [
+        "每条 P0/P1 PRD 需求均按需求类型覆盖矩阵满足最小自然语言测试用例数量",
+        "所有 PRD 需求均已分类；P2 需求已写 1-2 条自然语言测试用例或记录可信豁免原因、替代证据和 owner 批准人",
+        "自然语言用例已绑定 Requirement ID、PRD 来源、测试层级、测试数据、Oracle 和证据路径",
+        "覆盖检查已记录需求类型、优先级、风险因子、矩阵基准用例数、风险加量、最终要求用例数、已写用例数和风险加量理由",
+        "非 TDD 自然语言用例已映射到 story_full_chain、acceptance_validation、回归计划或 verify-matrix",
+        "TDD 候选用例已写明 RED 预期失败，可被 PLAN-001 转换为 feature_impl.qa_contract.tdd_contract",
+        "没有自然语言测试用例覆盖的 P0/P1 需求不得进入 feature_impl"
+      ]
+    },
+    {
+      "id": "DESIGN-001",
+      "description": "基于已确认需求与测试映射完成可编码设计规格",
+      "task_kind": "feature_design",
+      "phase": "design",
+      "gate_profile": "spec_required",
+      "required_truth_sources": [
+        "product",
+        "plan",
+        "testing",
+        "repo_context"
+      ],
+      "priority": 7,
+      "dependencies": [
+        "TESTCASE-001"
+      ],
+      "passes": false,
+      "context_files": [
+        "docs/product/prd-lite.md",
+        "docs/product/requirement-interface-matrix.md",
+        "docs/product/difficulty-research.md",
+        "docs/context/feature-pack.md",
+        "docs/context/repo-map.md",
+        "docs/context/architecture-brief.md",
+        "docs/testing/ACCEPTANCE_CRITERIA.md",
+        "docs/testing/ACCEPTANCE_EXAMPLES.md",
+        "docs/testing/NATURAL_LANGUAGE_TEST_CASES.md",
+        "docs/testing/TRACEABILITY_MATRIX.md",
+        "docs/testing/test-matrix.md",
+        "plans/features/<feature-slug>.dev-plan.md"
+      ],
+      "owned_paths": [
+        "docs/design/",
+        "docs/testing/",
+        "artifacts/visual-review/"
+      ],
+      "requirement_ids": [
+        "REQ-REPLACE-DESIGN"
+      ],
+      "produces_artifacts": [
+        "docs/design/design-brief.md",
+        "docs/design/component-map.md",
+        "docs/design/screen-states.md",
+        "docs/design/design-tokens.json",
+        "docs/design/ai-image-brief.md",
+        "docs/design/ui-image-review.md",
+        "docs/design/image-to-frontend-spec.md",
+        "docs/design/visual-parity-review.md"
+      ],
+      "execution": {
+        "mode": "single"
+      },
+      "steps": [
+        "输出页面结构、组件映射、关键状态、响应式与可访问性要求",
+        "把 Requirement IDs、交互路径、稳定测试选择器和视觉断言绑定到设计规格",
+        "明确后续实现需要的视觉参考、截图资产和验收边界"
+      ],
+      "test_command": "git diff --check",
+      "acceptance": [
+        "设计规格足以支撑实现而不再依赖口头补充",
+        "关键页面、状态和视觉断言已能回溯到需求与测试矩阵"
+      ]
+    },
+    {
+      "id": "PLAN-001",
+      "description": "把真相源收敛为可执行的实施计划和验证顺序",
+      "task_kind": "feature_plan",
+      "phase": "plan",
+      "gate_profile": "spec_required",
+      "required_truth_sources": [
+        "product",
+        "design",
+        "plan",
+        "architecture",
+        "testing",
+        "repo_context"
+      ],
+      "priority": 8,
+      "dependencies": [
+        "DESIGN-001"
+      ],
+      "passes": false,
+      "context_files": [
+        "docs/context/feature-pack.md",
+        "docs/context/repo-map.md",
+        "docs/context/architecture-brief.md",
+        "docs/architecture/constraints.md",
+        "docs/design/design-brief.md",
+        "docs/design/component-map.md",
+        "docs/testing/NATURAL_LANGUAGE_TEST_CASES.md",
+        "docs/testing/TRACEABILITY_MATRIX.md",
+        "docs/testing/TEST_DATA_MATRIX.md",
+        "docs/testing/test-matrix.md",
+        "docs/testing/verify-matrix.md",
+        "plans/features/<feature-slug>.dev-plan.md"
+      ],
+      "owned_paths": [
+        "plans/",
+        "docs/testing/",
+        "docs/context/"
+      ],
+      "requirement_ids": [
+        "REQ-REPLACE-PLAN"
+      ],
+      "produces_artifacts": [
+        "plans/features/<feature-slug>.dev-plan.md",
+        "docs/testing/verify-matrix.md"
+      ],
+      "execution": {
+        "mode": "single"
+      },
+      "steps": [
+        "把后续实现按用户故事顺序映射到 dev-plan、affected tests、验证命令和证据路径",
+        "把自然语言测试用例中的 TDD 候选转换为每个 feature_impl.qa_contract.tdd_contract，并保留 source_case_ids",
+        "把非 TDD 自然语言用例映射到 feature_impl.qa_contract.story_full_chain.source_case_ids、acceptance_validation.source_case_ids、回归计划或 verify-matrix",
+        "确认每个实现任务都已有 requirement_ids、owned_paths、context_files 和最小可行验收闭环",
+        "对涉及用户可见行为、路由、表单、权限、状态流转或关键业务闭环的任务，明确是否要求 docs/testing/e2e-plan.md，并把相关 E2E 命令写进 test_command 或 release 验证链路",
+        "确认每个 feature_impl 任务都携带 architecture_constraints、forbidden_implementations、tdd_contract 和项目真实可执行的 test_command",
+        "明确哪些故事必须串行，哪些依赖可在后续手工改成并行"
+      ],
+      "test_command": "git diff --check",
+      "acceptance": [
+        "dev-plan、verify-matrix 和 story 级执行顺序保持一致",
+        "每个 feature_impl 的 tdd_contract.red.source_case_ids 均能回溯到 NATURAL_LANGUAGE_TEST_CASES.md",
+        "每个 feature_impl 的非 TDD 自然语言用例均能回溯到 story_full_chain、acceptance_validation、回归计划或 verify-matrix",
+        "高风险用户可见任务已经明确是否需要 e2e-plan 与对应 E2E 证据",
+        "实现任务不会把测试替身、local-only adapter 或领域原型伪装成声明的交付路径",
+        "后续实现与 release 任务的验证边界已经明确且可执行"
+      ]
+    },
+    {
+      "id": "US1-001",
+      "description": "实现 US1 / MVP：将首个可独立验收的用户故事替换为真实业务标题",
+      "task_kind": "feature_impl",
+      "phase": "us1",
+      "gate_profile": "spec_required",
+      "required_truth_sources": [
+        "product",
+        "design",
+        "plan",
+        "architecture",
+        "testing",
+        "repo_context"
+      ],
+      "priority": 20,
+      "dependencies": [
+        "PLAN-001"
+      ],
+      "passes": false,
+      "story_id": "US1",
+      "story_priority": "P0/P1",
+      "independent_test": "替换为 US1 的独立验证方式，例如一个最短闭环页面或一条完整 API/业务路径",
+      "architecture_constraints": [
+        "delivery_shape=<replace-with-web_app|backend_service|monolith|frontend_app|cli|library|automation|data_pipeline|domain_prototype|other>",
+        "public_interfaces=<replace-with-http|grpc|graphql|mq|cli|ui-route|package-api|file-format|none>",
+        "persistence_boundary=<replace-with-database|browser_storage|filesystem|external-api|none>",
+        "test_double_policy=<replace-with-project-policy>"
+      ],
+      "forbidden_implementations": [
+        "禁止把测试替身、mock、fixture、local-only adapter 或领域原型作为声明交付路径完成",
+        "禁止只运行 git diff --check 就声明 feature_impl 完成",
+        "替换为当前项目最容易跑偏的具体禁止实现"
+      ],
+      "qa_contract": {
+        "source": [
+          "docs/testing/NATURAL_LANGUAGE_TEST_CASES.md",
+          "docs/testing/TRACEABILITY_MATRIX.md",
+          "docs/testing/test-matrix.md",
+          "docs/testing/verify-matrix.md"
+        ],
+        "required_layers": [
+          "unit_or_component",
+          "contract_or_api",
+          "story_full_chain",
+          "affected_regression"
+        ],
+        "tdd_contract": {
+          "policy": "required",
+          "red": {
+            "source_case_ids": [
+              "TC-REQ-REPLACE-US1-001"
+            ],
+            "behavior": "<replace-with-one-new-or-changed-us1-behavior>",
+            "test_files": [
+              "<replace-with-us1-focused-test-file>"
+            ],
+            "command": "<replace-with-us1-focused-test-command>",
+            "expected_failure": "<replace-with-us1-error-or-assertion-that-proves-behavior-missing>",
+            "evidence": "artifacts/tdd/US1-001/red.log"
+          },
+          "green": {
+            "command": "<replace-with-same-us1-focused-test-command>",
+            "evidence": "artifacts/tdd/US1-001/green.log"
+          },
+          "refactor_guard": {
+            "command": "<replace-with-us1-affected-tests-or-development-validation>",
+            "evidence": "artifacts/tdd/US1-001/refactor.log"
+          },
+          "coverage": {
+            "command": "<replace-with-us1-coverage-command-or-not-applicable>",
+            "minimum": "80% for business logic; 100% for critical logic"
+          },
+          "exemptions": []
+        },
+        "development_validation": {
+          "purpose": "coding-time feedback only; cannot replace acceptance_validation",
+          "commands": [
+            "<replace-with-affected-tests>",
+            "<replace-with-unit-or-component-tests>",
+            "<replace-with-contract-or-typecheck-or-lint>"
+          ],
+          "evidence": [
+            "<replace-with-development-test-log-or-report>"
+          ]
+        },
+        "story_full_chain": {
+          "source_case_ids": [
+            "TC-REQ-REPLACE-US1-FULLCHAIN-001"
+          ],
+          "entry": "<replace-with-user-visible-entry-or-public-api>",
+          "data": "<replace-with-seed-or-fixture-id-from-TEST_DATA_MATRIX>",
+          "action": "<replace-with-end-to-end-story-action>",
+          "oracles": [
+            "response_or_ui",
+            "database_or_state",
+            "side_effect_or_no_side_effect"
+          ],
+          "evidence": [
+            "<replace-with-request-response-or-screenshot>",
+            "<replace-with-db-diff-or-state-proof>",
+            "<replace-with-trace-log-or-event-proof>"
+          ],
+          "failure_mode": "<replace-with-negative-or-error-path-proof>"
+        },
+        "acceptance_validation": {
+          "purpose": "post-implementation user or business full-chain validation",
+          "must_run_after_implementation": true,
+          "source": "story_full_chain",
+          "source_case_ids": [
+            "TC-REQ-REPLACE-US1-FULLCHAIN-001"
+          ],
+          "fresh_evidence_required": true
+        },
+        "release_impact": [
+          "US1 evidence must feed RELEASE-001 cross-story flow"
+        ],
+        "exemptions": []
+      },
+      "context_files": [
+        "docs/product/prd-lite.md",
+        "docs/product/requirement-interface-matrix.md",
+        "docs/architecture/constraints.md",
+        "docs/context/feature-pack.md",
+        "docs/design/design-brief.md",
+        "docs/design/component-map.md",
+        "docs/design/screen-states.md",
+        "docs/testing/ACCEPTANCE_EXAMPLES.md",
+        "docs/testing/NATURAL_LANGUAGE_TEST_CASES.md",
+        "docs/testing/TRACEABILITY_MATRIX.md",
+        "docs/testing/TEST_STRATEGY.md",
+        "docs/testing/TEST_DATA_MATRIX.md",
+        "docs/testing/EVIDENCE_PROTOCOL.md",
+        "docs/testing/test-matrix.md",
+        "docs/testing/verify-matrix.md",
+        "plans/features/<feature-slug>.dev-plan.md"
+      ],
+      "owned_paths": [
+        "<replace-with-us1-owned-path-1>/",
+        "<replace-with-us1-owned-path-2>/"
+      ],
+      "requirement_ids": [
+        "FR-REPLACE-US1-001",
+        "FR-REPLACE-US1-002"
+      ],
+      "produces_artifacts": [
+        "<replace-with-us1-primary-artifact>",
+        "<replace-with-us1-test-evidence>"
+      ],
+      "execution": {
+        "mode": "single"
+      },
+      "steps": [
+        "把 US1 标题、requirement_ids、owned_paths、产物路径和独立验证方式替换为真实项目内容",
+        "把 qa_contract 中的 tdd_contract.source_case_ids、story_full_chain.source_case_ids、acceptance_validation.source_case_ids、入口、数据、动作、Oracle、证据、失败态和 release impact 全部替换为真实内容",
+        "仅实现首个可单独交付的用户故事，并同步补齐其 affected tests 与必要文档",
+        "运行与 US1 对应的真实验证命令，必须包含开发验证和代码完成后的故事级验收链路，并记录可回溯证据"
+      ],
+      "test_command": "powershell -NoProfile -ExecutionPolicy Bypass -File .\\tools\\harness\\tools/harness/verify.ps1 -Commands @('<replace-with-project-fitness-check>', '<replace-with-affected-tests>', 'git diff --check')",
+      "acceptance": [
+        "US1 能作为 MVP 独立演示或独立验收",
+        "US1 满足架构约束 truth source，不以测试替身冒充声明交付路径",
+        "US1 的 tdd_contract 和验收链路均能回溯到 NATURAL_LANGUAGE_TEST_CASES.md 中的自然语言用例",
+        "US1 的开发验证和故事级验收链路均通过，且验收证据能进入 RELEASE-001",
+        "US1 的 Requirement IDs、测试映射和证据路径完整可追溯"
+      ]
+    },
+    {
+      "id": "US2-001",
+      "description": "实现 US2：将第二个用户故事替换为真实业务标题",
+      "task_kind": "feature_impl",
+      "phase": "us2",
+      "gate_profile": "spec_required",
+      "required_truth_sources": [
+        "product",
+        "design",
+        "plan",
+        "architecture",
+        "testing",
+        "repo_context"
+      ],
+      "priority": 30,
+      "dependencies": [
+        "PLAN-001"
+      ],
+      "passes": false,
+      "story_id": "US2",
+      "story_priority": "P1/P2",
+      "independent_test": "替换为 US2 的独立验证方式；若与 US1 强依赖，请同步调整 dependencies",
+      "architecture_constraints": [
+        "delivery_shape=<replace-with-project-shape>",
+        "api_boundary=<replace-with-public-entry>",
+        "data_boundary=<replace-with-persistence-or-none>",
+        "test_double_policy=<replace-with-policy>"
+      ],
+      "forbidden_implementations": [
+        "禁止把测试替身、mock、fixture、local-only adapter 或领域原型作为声明交付路径完成",
+        "替换为 US2 的具体禁止实现"
+      ],
+      "qa_contract": {
+        "source": [
+          "docs/testing/NATURAL_LANGUAGE_TEST_CASES.md",
+          "docs/testing/TRACEABILITY_MATRIX.md",
+          "docs/testing/test-matrix.md",
+          "docs/testing/verify-matrix.md"
+        ],
+        "required_layers": [
+          "unit_or_component",
+          "contract_or_api",
+          "story_full_chain",
+          "affected_regression"
+        ],
+        "tdd_contract": {
+          "policy": "required",
+          "red": {
+            "source_case_ids": [
+              "TC-REQ-REPLACE-US2-001"
+            ],
+            "behavior": "<replace-with-one-new-or-changed-us2-behavior>",
+            "test_files": [
+              "<replace-with-us2-focused-test-file>"
+            ],
+            "command": "<replace-with-us2-focused-test-command>",
+            "expected_failure": "<replace-with-us2-error-or-assertion-that-proves-behavior-missing>",
+            "evidence": "artifacts/tdd/US2-001/red.log"
+          },
+          "green": {
+            "command": "<replace-with-same-us2-focused-test-command>",
+            "evidence": "artifacts/tdd/US2-001/green.log"
+          },
+          "refactor_guard": {
+            "command": "<replace-with-us2-affected-tests-or-development-validation>",
+            "evidence": "artifacts/tdd/US2-001/refactor.log"
+          },
+          "coverage": {
+            "command": "<replace-with-us2-coverage-command-or-not-applicable>",
+            "minimum": "80% for business logic; 100% for critical logic"
+          },
+          "exemptions": []
+        },
+        "development_validation": {
+          "purpose": "coding-time feedback only; cannot replace acceptance_validation",
+          "commands": [
+            "<replace-with-affected-tests>",
+            "<replace-with-unit-or-component-tests>",
+            "<replace-with-contract-or-typecheck-or-lint>"
+          ],
+          "evidence": [
+            "<replace-with-development-test-log-or-report>"
+          ]
+        },
+        "story_full_chain": {
+          "source_case_ids": [
+            "TC-REQ-REPLACE-US2-FULLCHAIN-001"
+          ],
+          "entry": "<replace-with-user-visible-entry-or-public-api>",
+          "data": "<replace-with-seed-or-fixture-id-from-TEST_DATA_MATRIX>",
+          "action": "<replace-with-end-to-end-story-action>",
+          "oracles": [
+            "response_or_ui",
+            "database_or_state",
+            "side_effect_or_no_side_effect"
+          ],
+          "evidence": [
+            "<replace-with-request-response-or-screenshot>",
+            "<replace-with-db-diff-or-state-proof>",
+            "<replace-with-trace-log-or-event-proof>"
+          ],
+          "failure_mode": "<replace-with-negative-or-error-path-proof>"
+        },
+        "acceptance_validation": {
+          "purpose": "post-implementation user or business full-chain validation",
+          "must_run_after_implementation": true,
+          "source": "story_full_chain",
+          "source_case_ids": [
+            "TC-REQ-REPLACE-US2-FULLCHAIN-001"
+          ],
+          "fresh_evidence_required": true
+        },
+        "release_impact": [
+          "US2 evidence must feed RELEASE-001 cross-story flow"
+        ],
+        "exemptions": []
+      },
+      "context_files": [
+        "docs/product/prd-lite.md",
+        "docs/product/requirement-interface-matrix.md",
+        "docs/architecture/constraints.md",
+        "docs/context/feature-pack.md",
+        "docs/design/design-brief.md",
+        "docs/design/component-map.md",
+        "docs/design/screen-states.md",
+        "docs/testing/ACCEPTANCE_EXAMPLES.md",
+        "docs/testing/NATURAL_LANGUAGE_TEST_CASES.md",
+        "docs/testing/TRACEABILITY_MATRIX.md",
+        "docs/testing/TEST_STRATEGY.md",
+        "docs/testing/TEST_DATA_MATRIX.md",
+        "docs/testing/EVIDENCE_PROTOCOL.md",
+        "docs/testing/test-matrix.md",
+        "docs/testing/verify-matrix.md",
+        "plans/features/<feature-slug>.dev-plan.md"
+      ],
+      "owned_paths": [
+        "<replace-with-us2-owned-path-1>/",
+        "<replace-with-us2-owned-path-2>/"
+      ],
+      "requirement_ids": [
+        "FR-REPLACE-US2-001",
+        "FR-REPLACE-US2-002"
+      ],
+      "produces_artifacts": [
+        "<replace-with-us2-primary-artifact>",
+        "<replace-with-us2-test-evidence>"
+      ],
+      "execution": {
+        "mode": "single"
+      },
+      "steps": [
+        "将 US2 占位内容替换为真实范围、路径、需求编号和验证命令",
+        "把 qa_contract 中的 tdd_contract.source_case_ids、story_full_chain.source_case_ids、acceptance_validation.source_case_ids、入口、数据、动作、Oracle、证据、失败态和 release impact 全部替换为真实内容",
+        "确保 US2 可作为独立增量交付，不把未确认范围混入同一任务",
+        "补齐 US2 的 affected tests、开发验证、代码完成后的故事级验收链路、回归说明和证据路径"
+      ],
+      "test_command": "powershell -NoProfile -ExecutionPolicy Bypass -File .\\tools\\harness\\tools/harness/verify.ps1 -Commands @('<replace-with-project-fitness-check>', '<replace-with-affected-tests>', 'git diff --check')",
+      "acceptance": [
+        "US2 范围清晰且不与其他故事混杂",
+        "US2 满足架构约束 truth source，不以测试替身冒充声明交付路径",
+        "US2 的 tdd_contract 和验收链路均能回溯到 NATURAL_LANGUAGE_TEST_CASES.md 中的自然语言用例",
+        "US2 的开发验证和故事级验收链路均通过，且验收证据能进入 RELEASE-001",
+        "US2 的实现、验证和证据链可独立审查"
+      ]
+    },
+    {
+      "id": "US3-001",
+      "description": "实现 US3：将第三个用户故事或跨端扩展故事替换为真实业务标题",
+      "task_kind": "feature_impl",
+      "phase": "us3",
+      "gate_profile": "spec_required",
+      "required_truth_sources": [
+        "product",
+        "design",
+        "plan",
+        "architecture",
+        "testing",
+        "repo_context"
+      ],
+      "priority": 40,
+      "dependencies": [
+        "PLAN-001"
+      ],
+      "passes": false,
+      "story_id": "US3",
+      "story_priority": "P2/P3",
+      "independent_test": "替换为 US3 的独立验证方式；如果不需要第三个故事，可删除该任务并重排优先级",
+      "architecture_constraints": [
+        "delivery_shape=<replace-with-project-shape>",
+        "api_boundary=<replace-with-public-entry>",
+        "data_boundary=<replace-with-persistence-or-none>",
+        "test_double_policy=<replace-with-policy>"
+      ],
+      "forbidden_implementations": [
+        "禁止把测试替身、mock、fixture、local-only adapter 或领域原型作为声明交付路径完成",
+        "替换为 US3 的具体禁止实现"
+      ],
+      "qa_contract": {
+        "source": [
+          "docs/testing/NATURAL_LANGUAGE_TEST_CASES.md",
+          "docs/testing/TRACEABILITY_MATRIX.md",
+          "docs/testing/test-matrix.md",
+          "docs/testing/verify-matrix.md"
+        ],
+        "required_layers": [
+          "unit_or_component",
+          "contract_or_api",
+          "story_full_chain",
+          "affected_regression"
+        ],
+        "tdd_contract": {
+          "policy": "required",
+          "red": {
+            "source_case_ids": [
+              "TC-REQ-REPLACE-US3-001"
+            ],
+            "behavior": "<replace-with-one-new-or-changed-us3-behavior>",
+            "test_files": [
+              "<replace-with-us3-focused-test-file>"
+            ],
+            "command": "<replace-with-us3-focused-test-command>",
+            "expected_failure": "<replace-with-us3-error-or-assertion-that-proves-behavior-missing>",
+            "evidence": "artifacts/tdd/US3-001/red.log"
+          },
+          "green": {
+            "command": "<replace-with-same-us3-focused-test-command>",
+            "evidence": "artifacts/tdd/US3-001/green.log"
+          },
+          "refactor_guard": {
+            "command": "<replace-with-us3-affected-tests-or-development-validation>",
+            "evidence": "artifacts/tdd/US3-001/refactor.log"
+          },
+          "coverage": {
+            "command": "<replace-with-us3-coverage-command-or-not-applicable>",
+            "minimum": "80% for business logic; 100% for critical logic"
+          },
+          "exemptions": []
+        },
+        "development_validation": {
+          "purpose": "coding-time feedback only; cannot replace acceptance_validation",
+          "commands": [
+            "<replace-with-affected-tests>",
+            "<replace-with-unit-or-component-tests>",
+            "<replace-with-contract-or-typecheck-or-lint>"
+          ],
+          "evidence": [
+            "<replace-with-development-test-log-or-report>"
+          ]
+        },
+        "story_full_chain": {
+          "source_case_ids": [
+            "TC-REQ-REPLACE-US3-FULLCHAIN-001"
+          ],
+          "entry": "<replace-with-user-visible-entry-or-public-api>",
+          "data": "<replace-with-seed-or-fixture-id-from-TEST_DATA_MATRIX>",
+          "action": "<replace-with-end-to-end-story-action>",
+          "oracles": [
+            "response_or_ui",
+            "database_or_state",
+            "side_effect_or_no_side_effect"
+          ],
+          "evidence": [
+            "<replace-with-request-response-or-screenshot>",
+            "<replace-with-db-diff-or-state-proof>",
+            "<replace-with-trace-log-or-event-proof>"
+          ],
+          "failure_mode": "<replace-with-negative-or-error-path-proof>"
+        },
+        "acceptance_validation": {
+          "purpose": "post-implementation user or business full-chain validation",
+          "must_run_after_implementation": true,
+          "source": "story_full_chain",
+          "source_case_ids": [
+            "TC-REQ-REPLACE-US3-FULLCHAIN-001"
+          ],
+          "fresh_evidence_required": true
+        },
+        "release_impact": [
+          "US3 evidence must feed RELEASE-001 cross-story flow"
+        ],
+        "exemptions": []
+      },
+      "context_files": [
+        "docs/product/prd-lite.md",
+        "docs/product/requirement-interface-matrix.md",
+        "docs/architecture/constraints.md",
+        "docs/context/feature-pack.md",
+        "docs/design/design-brief.md",
+        "docs/design/component-map.md",
+        "docs/design/screen-states.md",
+        "docs/testing/ACCEPTANCE_EXAMPLES.md",
+        "docs/testing/TRACEABILITY_MATRIX.md",
+        "docs/testing/TEST_STRATEGY.md",
+        "docs/testing/TEST_DATA_MATRIX.md",
+        "docs/testing/EVIDENCE_PROTOCOL.md",
+        "docs/testing/test-matrix.md",
+        "docs/testing/verify-matrix.md",
+        "plans/features/<feature-slug>.dev-plan.md"
+      ],
+      "owned_paths": [
+        "<replace-with-us3-owned-path-1>/",
+        "<replace-with-us3-owned-path-2>/"
+      ],
+      "requirement_ids": [
+        "FR-REPLACE-US3-001",
+        "FR-REPLACE-US3-002"
+      ],
+      "produces_artifacts": [
+        "<replace-with-us3-primary-artifact>",
+        "<replace-with-us3-test-evidence>"
+      ],
+      "execution": {
+        "mode": "single"
+      },
+      "steps": [
+        "将 US3 占位内容替换为真实故事标题、路径、需求编号和验证方式",
+        "把 qa_contract 中的 tdd_contract.source_case_ids、story_full_chain.source_case_ids、acceptance_validation.source_case_ids、入口、数据、动作、Oracle、证据、失败态和 release impact 全部替换为真实内容",
+        "只承接剩余优先级最高且可单独验收的增量，不把 release 收口动作混入本故事",
+        "完成 US3 的实现、测试映射、开发验证、代码完成后的故事级验收链路和证据沉淀"
+      ],
+      "test_command": "powershell -NoProfile -ExecutionPolicy Bypass -File .\\tools\\harness\\tools/harness/verify.ps1 -Commands @('<replace-with-project-fitness-check>', '<replace-with-affected-tests>', 'git diff --check')",
+      "acceptance": [
+        "US3 的增量边界和独立验收方式已明确",
+        "US3 满足架构约束 truth source，不以测试替身冒充声明交付路径",
+        "US3 的 tdd_contract 和验收链路均能回溯到 NATURAL_LANGUAGE_TEST_CASES.md 中的自然语言用例",
+        "US3 的开发验证和故事级验收链路均通过，且验收证据能进入 RELEASE-001",
+        "US3 的实现证据可直接服务最终 release 验证"
+      ]
+    },
+    {
+      "id": "RELEASE-001",
+      "description": "执行跨故事联调、回归验证、视觉检查和交付收口",
+      "task_kind": "release",
+      "phase": "verify",
+      "gate_profile": "release_required",
+      "required_truth_sources": [
+        "product",
+        "design",
+        "plan",
+        "testing",
+        "repo_context"
+      ],
+      "priority": 80,
+      "dependencies": [
+        "US1-001",
+        "US2-001",
+        "US3-001"
+      ],
+      "passes": false,
+      "qa_contract": {
+        "source": [
+          "docs/testing/NATURAL_LANGUAGE_TEST_CASES.md",
+          "docs/testing/TRACEABILITY_MATRIX.md",
+          "docs/testing/REGRESSION_PLAN.md",
+          "docs/testing/verify-matrix.md",
+          "docs/testing/EVIDENCE_PROTOCOL.md"
+        ],
+        "required_layers": [
+          "cross_story_full_chain",
+          "p0_p1_regression",
+          "contract_or_api",
+          "e2e_or_equivalent_system_test",
+          "visual_or_ui_state_review_when_applicable",
+          "failure_triage"
+        ],
+        "development_validation": {
+          "purpose": "release-task setup and affected checks only; cannot replace release_candidate acceptance",
+          "commands": [
+            "<replace-with-affected-regression-or-contract-checks>",
+            "<replace-with-build-or-typecheck-if-applicable>"
+          ],
+          "evidence": [
+            "<replace-with-release-precheck-log-or-report>"
+          ]
+        },
+        "cross_story_full_chain": {
+          "source_case_ids": [
+            "TC-REQ-REPLACE-RELEASE-001"
+          ],
+          "entry": "<replace-with-primary-user-or-system-entry>",
+          "flow": [
+            "US1",
+            "US2",
+            "US3"
+          ],
+          "oracles": [
+            "user_visible_result",
+            "api_contract",
+            "data_consistency",
+            "side_effects",
+            "audit_or_trace"
+          ],
+          "evidence": [
+            "docs/testing/verify-matrix.md",
+            "docs/testing/failure-triage.md",
+            "artifacts/"
+          ],
+          "failure_mode": "<replace-with-release-failure-path-proof>"
+        },
+        "acceptance_validation": {
+          "purpose": "post-implementation release-candidate validation from user or delivery perspective",
+          "must_run_after_all_story_tasks": true,
+          "source": "cross_story_full_chain",
+          "source_case_ids": [
+            "TC-REQ-REPLACE-RELEASE-001"
+          ],
+          "fresh_evidence_required": true
+        },
+        "exemptions": []
+      },
+      "context_files": [
+        "docs/context/feature-pack.md",
+        "docs/design/visual-parity-review.md",
+        "docs/testing/ACCEPTANCE_EXAMPLES.md",
+        "docs/testing/TRACEABILITY_MATRIX.md",
+        "docs/testing/TEST_STRATEGY.md",
+        "docs/testing/REGRESSION_PLAN.md",
+        "docs/testing/EVIDENCE_PROTOCOL.md",
+        "docs/testing/test-matrix.md",
+        "docs/testing/verify-matrix.md",
+        "docs/testing/failure-triage.md",
+        "plans/features/<feature-slug>.dev-plan.md"
+      ],
+      "owned_paths": [
+        "docs/testing/",
+        "docs/design/",
+        "artifacts/",
+        "tests/"
+      ],
+      "requirement_ids": [
+        "NFR-REPLACE-RELEASE",
+        "FR-REPLACE-END-TO-END"
+      ],
+      "produces_artifacts": [
+        "artifacts/visual-review/",
+        "docs/testing/failure-triage.md",
+        "traces/"
+      ],
+      "execution": {
+        "mode": "single"
+      },
+      "steps": [
+        "执行开发验证、P0/P1 回归、发布候选级跨故事整链路、端到端、视觉还原和必要契约校验",
+        "记录失败归因、修复建议、最终通过证据和剩余风险",
+        "确认 release 阶段只负责 fresh evidence，不在此阶段第一次补需求或测试范围"
+      ],
+      "test_command": "powershell -NoProfile -ExecutionPolicy Bypass -File .\\tools\\harness\\tools/harness/verify.ps1",
+      "acceptance": [
+        "跨故事完整主流程验证通过，或有明确 blocked 说明与后续处置",
+        "P0/P1 回归、契约/API、E2E/视觉或等价系统级验证均有 fresh evidence",
+        "交付所需的测试与视觉证据完整可追溯"
+      ]
+    },
+    {
+      "id": "ARCHIVE-001",
+      "description": "归档本轮交付知识、更新知识索引并标记可复用经验",
+      "task_kind": "archive",
+      "phase": "archive",
+      "gate_profile": "lightweight",
+      "required_truth_sources": [
+        "knowledge"
+      ],
+      "priority": 90,
+      "dependencies": [
+        "RELEASE-001"
+      ],
+      "passes": false,
+      "context_files": [
+        "docs/harness/knowledge-architecture.md",
+        "docs/harness/knowledge-import.md",
+        "docs/harness/knowledge-lint.md",
+        "docs/harness/team-knowledge-sync.md",
+        "docs/harness/rule-governance.md",
+        "docs/knowledge/knowledge-catalog.md",
+        "docs/knowledge/catalog.md",
+        "progress.txt",
+        "traces/"
+      ],
+      "owned_paths": [
+        "docs/knowledge/"
+      ],
+      "requirement_ids": [
+        "NFR-KNOWLEDGE-ARCHIVE"
+      ],
+      "produces_artifacts": [
+        "docs/knowledge/knowledge-catalog.md",
+        "docs/knowledge/catalog.md",
+        "docs/knowledge/"
+      ],
+      "execution": {
+        "mode": "single"
+      },
+      "knowledge_query_budget": {
+        "catalogs": 2,
+        "entries": 8
+      },
+      "steps": [
+        "读取本轮任务 trace、progress、review 输出和 failure triage，提取可复用的 decision、guideline、pitfall、process 或 model",
+        "新增或更新 docs/knowledge/ 下的知识条目，所有新增条目初始 maturity 默认为 draft",
+        "更新 knowledge-catalog.md 和 catalog.md，确保索引能按阶段和类型引导后续任务按需读取",
+        "输出 promotion、decay、conflict、merge 和 team sync candidates；成熟度提升、团队同步、冲突裁决和归档删除必须有明确 evidence",
+        "不要把一次性任务结论提升为 AGENTS.md 规则；只有 proven 级别或用户明确要求时才升级规则"
+      ],
+      "test_command": "git diff --check",
+      "acceptance": [
+        "本轮可复用知识已沉淀到 docs/knowledge/ 或明确说明没有可归档条目",
+        "knowledge-catalog.md 和 catalog.md 与新增或更新条目保持一致",
+        "可提升、可衰减、可团队同步、冲突和重复条目已有候选说明或明确无相关候选",
+        "归档任务没有修改业务实现或伪造 driver runtime 状态"
+      ]
+    }
+  ]
+}