@pzy560117/codex-harness 0.1.9 → 0.1.11

package/package-source/docs/codex-harness-engineering/templates/runtime/feature-task-reference.json

@@ -0,0 +1,363 @@
+{
+  "metadata": {
+    "purpose": "feature_impl / release / archive 任务参考模板。不要把本文件直接当运行中的 task.json；它用于在 PLAN-001 之后生成真实任务。",
+    "usage": [
+      "先保留 INIT-001、ANALYSIS-001、TESTCASE-001、PLAN-001 作为 seed queue。",
+      "后续真实实现任务从本文件的 template 中复制，再替换 requirement_ids、owned_paths、context_files、test_command、evidence 和 source_case_ids。",
+      "不要把多个高风险域、多个主 requirement_ids、或长期前后端混合 story 原样保留下来。"
+    ]
+  },
+  "feature_impl_template": {
+    "id": "USX-001",
+    "description": "实现一个可独立验收的真实用户故事",
+    "task_kind": "feature_impl",
+    "phase": "usx",
+    "gate_profile": "spec_required",
+    "required_truth_sources": [
+      "product",
+      "design",
+      "plan",
+      "architecture",
+      "testing",
+      "repo_context"
+    ],
+    "priority": 20,
+    "dependencies": [
+      "PLAN-001"
+    ],
+    "passes": false,
+    "story_id": "USX",
+    "story_priority": "P0/P1/P2",
+    "independent_test": "替换为该故事的独立验证方式，例如一个最短闭环页面或一条完整 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 完成",
+      "单个 feature_impl 默认不超过 3 条主 requirement_ids；订单、支付、库存、RBAC 不要和其他主故事捆绑；前端和后端不要长期混在同一个 story"
+    ],
+    "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-USX-001"
+          ],
+          "behavior": "<replace-with-one-new-or-changed-usx-behavior>",
+          "test_files": [
+            "<replace-with-usx-focused-test-file>"
+          ],
+          "command": "<replace-with-usx-focused-test-command>",
+          "expected_failure": "<replace-with-usx-error-or-assertion-that-proves-behavior-missing>",
+          "evidence": "artifacts/tdd/USX-001/red.log"
+        },
+        "green": {
+          "command": "<replace-with-same-usx-focused-test-command>",
+          "evidence": "artifacts/tdd/USX-001/green.log"
+        },
+        "refactor_guard": {
+          "command": "<replace-with-usx-affected-tests-or-development-validation>",
+          "evidence": "artifacts/tdd/USX-001/refactor.log"
+        },
+        "coverage": {
+          "command": "<replace-with-usx-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-USX-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-USX-FULLCHAIN-001"
+        ],
+        "fresh_evidence_required": true
+      },
+      "release_impact": [
+        "USX 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_CRITERIA.md",
+      "docs/testing/ACCEPTANCE_EXAMPLES.md",
+      "docs/testing/NATURAL_LANGUAGE_TEST_CASES.md",
+      "docs/testing/REGRESSION_PLAN.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-usx-owned-path-1>/",
+      "<replace-with-usx-owned-path-2>/"
+    ],
+    "requirement_ids": [
+      "FR-REPLACE-USX-001",
+      "FR-REPLACE-USX-002"
+    ],
+    "produces_artifacts": [
+      "<replace-with-usx-primary-artifact>",
+      "<replace-with-usx-test-evidence>"
+    ],
+    "execution": {
+      "mode": "single"
+    },
+    "steps": [
+      "把 USX 标题、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 全部替换为真实内容",
+      "模块归属：<replace-with-module-owner>",
+      "文件改动清单：<replace-with-file-list>",
+      "复用内容：<replace-with-reused-code-or-docs>",
+      "新增内容：<replace-with-new-code-or-docs>",
+      "不改内容：<replace-with-explicit-non-goals>",
+      "风险点：<replace-with-key-risks>",
+      "测试范围：<replace-with-affected-tests-and-full-chain-scope>",
+      "仅实现一个可单独交付的用户故事，并同步补齐其 affected tests 与必要文档",
+      "运行与 USX 对应的真实验证命令，必须包含开发验证和代码完成后的故事级验收链路，并记录可回溯证据"
+    ],
+    "test_command": "powershell -NoProfile -ExecutionPolicy Bypass -File .\\tools\\harness\\verify.ps1 -Commands @('<replace-with-project-fitness-check>', '<replace-with-affected-tests>', 'git diff --check')",
+    "acceptance": [
+      "USX 能作为独立增量演示或独立验收",
+      "USX 满足架构约束 truth source，不以测试替身冒充声明交付路径",
+      "USX 的 tdd_contract 和验收链路均能回溯到 NATURAL_LANGUAGE_TEST_CASES.md 中的自然语言用例",
+      "USX 的开发验证和故事级验收链路均通过，且验收证据能进入 RELEASE-001",
+      "USX 的 Requirement IDs、测试映射和证据路径完整可追溯"
+    ]
+  },
+  "release_template": {
+    "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": [
+      "<replace-with-implemented-story-task-ids>"
+    ],
+    "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": [
+          "<replace-with-story-order>"
+        ],
+        "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\\verify.ps1",
+    "acceptance": [
+      "跨故事完整主流程验证通过，或有明确 blocked 说明与后续处置",
+      "P0/P1 回归、契约/API、E2E/视觉或等价系统级验证均有 fresh evidence",
+      "交付所需的测试与视觉证据完整可追溯"
+    ]
+  },
+  "archive_template": {
+    "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 状态"
+    ]
+  }
+}