@peterxiaoyang/superspec 0.1.37 → 0.1.39

package/dist/types.d.ts

@@ -6,6 +6,7 @@ export type Ref = {
 };
 export type JobState = "requested" | "accepted" | "rejected";
 export type JobRole = "critic" | "architect" | "test-engineer" | "executor" | "test-run" | "verifier" | "code-reviewer";
+export type ReviewJobGateId = "explore.discovery_review" | "propose.final_review" | "review.code_review" | "review.final_verifier";
 export type CodeReviewResultKind = "invalid_report" | "non_actionable_report" | "review_failed";
 export interface CodeReviewPreviousRejection {
     result_kind: CodeReviewResultKind;
@@ -16,19 +17,90 @@ export interface Job {
     job_id: string;
     role: JobRole;
     state: JobState;
+    gate_id?: ReviewJobGateId;
     boundFiles: Ref[];
     review_evidence_digest?: string;
     packet_digest: string;
+    packet_context?: JobPacketContext;
     created_from_transition: string;
     created_at: string;
     previous_rejection?: CodeReviewPreviousRejection;
 }
+export interface ExecutionContract {
+    tests: string[];
+    design: string | null;
+    source: string[];
+    reason: string | null;
+    guard: string | null;
+}
+export interface DirtyFileFingerprint {
+    path: string;
+    status: "added" | "modified" | "deleted";
+    sha256: string | null;
+}
+export interface BoundarySnapshot {
+    head: string | null;
+    head_reason?: string;
+    dirty_files_reason?: string;
+    dirty_files: DirtyFileFingerprint[];
+}
+export interface CodeReviewScope {
+    base_head: string | null;
+    current_head: string | null;
+    scope_reliable: boolean;
+    scope_reason: string;
+    committed_paths: string[] | null;
+    worktree_paths: string[];
+    untracked_paths: string[];
+    review_paths: string[];
+}
+export interface CodeStateCheck {
+    baseline_head: string | null;
+    current_head: string | null;
+    head_matches: boolean;
+    changed_paths: string[];
+    scope_reason: string;
+}
+export interface TaskExecutionIndexEntry {
+    task_id: string;
+    attempt_id: string;
+    changed_paths: string[] | null;
+    changed_paths_partial_reason?: string;
+    contract: ExecutionContract | null;
+    declared_tests: string[];
+    scope_note: Record<string, unknown> | null;
+    test_evidence: Record<string, unknown>[];
+    task_completed_event_ref: string;
+}
+export interface CoverageExemptionRef {
+    test_id: string;
+    event_id: string;
+    event_digest: string;
+    answer: string;
+}
+export interface JobPacketContext {
+    code_review_scope?: CodeReviewScope;
+    coverage_exemption_refs?: CoverageExemptionRef[];
+    task_execution_index?: TaskExecutionIndexEntry[];
+    unattributed_paths?: string[];
+    unknown_attribution_tasks?: string[];
+    code_state_check?: CodeStateCheck;
+}
 export interface JobPacket {
     job_id: string;
     role: JobRole;
+    gate_id?: ReviewJobGateId;
     recommended_agent?: string;
     boundFiles: Ref[];
     review_evidence_digest?: string;
+    previous_rejection?: CodeReviewPreviousRejection;
+    packet_context?: JobPacketContext;
+    code_review_scope?: CodeReviewScope;
+    coverage_exemption_refs?: CoverageExemptionRef[];
+    task_execution_index?: TaskExecutionIndexEntry[];
+    unattributed_paths?: string[];
+    unknown_attribution_tasks?: string[];
+    code_state_check?: CodeStateCheck;
     packet_digest: string;
     required_output_kind: string;
     preferred_input_mode?: "stdin" | "file";
@@ -37,6 +109,7 @@ export interface JobPacket {
     file_fallback?: boolean;
     output_contract_fields?: string[];
     output_contract_optional_fields?: string[];
+    字段说明?: Record<string, string>;
     output_instructions?: string;
     stop_conditions: string[];
     created_from_transition: string;
@@ -77,6 +150,9 @@ export interface TransitionCommitPayload {
     code_review_gate?: {
         decision: "passed" | "skipped";
         job_id?: string;
+        packet_digest?: string;
+        current_head?: string | null;
+        head?: string | null;
         reason?: "no_code_changes";
     };
 }
@@ -101,6 +177,10 @@ export interface TaskAttempt {
     task_id: string;
     state: AttemptState;
     task_structure_digest: string;
+    contract?: ExecutionContract | null;
+    contract_mode?: boolean;
+    tdd_required?: boolean;
+    no_tdd_reason?: string | null;
     declared_write_scope: string[];
     pre_edit_source_fingerprint: string | null;
     pre_edit_red_ref: string | null;
@@ -112,7 +192,7 @@ export interface TaskAttempt {
 export interface TestRun {
     test_id: string;
     attempt_id?: string | null;
-    task_structure_digest: string;
+    task_structure_digest?: string;
     covers_task_ids?: string[];
     command: string;
     cwd: string;

package/dist/workflow_profile.d.ts

@@ -0,0 +1,11 @@
+import type { ReviewRisk } from "./review.ts";
+import type { JobRole, ReviewJobGateId } from "./types.ts";
+export type WorkflowProfile = "light" | "normal" | "strict";
+export interface WorkflowProfileResolution {
+    profile: WorkflowProfile;
+    risk: ReviewRisk;
+    reviewRolesByGate: Partial<Record<ReviewJobGateId, JobRole[]>>;
+}
+export declare function workflowProfileForRisk(risk: ReviewRisk): WorkflowProfile;
+export declare function resolveWorkflowProfile(risk: ReviewRisk): WorkflowProfileResolution;
+export declare function reviewRolesForGate(gateId: ReviewJobGateId, risk: ReviewRisk): JobRole[];

package/dist/workflow_profile.js

@@ -0,0 +1,39 @@
+const CURRENT_GATE_ROLES_BY_RISK = {
+    minimal: {
+        "explore.discovery_review": [],
+        "propose.final_review": [],
+        "review.code_review": ["code-reviewer"],
+        "review.final_verifier": ["verifier"],
+    },
+    normal: {
+        "explore.discovery_review": [],
+        "propose.final_review": ["critic"],
+        "review.code_review": ["code-reviewer"],
+        "review.final_verifier": ["verifier"],
+    },
+    strict: {
+        "explore.discovery_review": ["critic"],
+        "propose.final_review": ["critic", "architect", "test-engineer"],
+        "review.code_review": ["code-reviewer"],
+        "review.final_verifier": ["verifier"],
+    },
+};
+export function workflowProfileForRisk(risk) {
+    if (risk === "minimal")
+        return "light";
+    if (risk === "normal")
+        return "normal";
+    return "strict";
+}
+export function resolveWorkflowProfile(risk) {
+    const profile = workflowProfileForRisk(risk);
+    const rolesByGate = CURRENT_GATE_ROLES_BY_RISK[risk];
+    const reviewRolesByGate = {};
+    for (const [gateId, roles] of Object.entries(rolesByGate)) {
+        reviewRolesByGate[gateId] = [...roles];
+    }
+    return { profile, risk, reviewRolesByGate };
+}
+export function reviewRolesForGate(gateId, risk) {
+    return resolveWorkflowProfile(risk).reviewRolesByGate[gateId] ?? [];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peterxiaoyang/superspec",
-  "version": "0.1.37",
+  "version": "0.1.39",
   "description": "SuperSpec 流程引擎 — transition engine with lightweight fact-sync",
   "type": "module",
   "engines": {

package/templates/workflow/prompts/architect.md

@@ -5,45 +5,35 @@ argument-hint: "本次架构审查说明"
 
 # Architect
 
-## 角色身份
+## 角色
 
-你是 Architect。你负责审查系统边界、接口契约、数据流、长期维护风险、回滚难度和设计取舍。你提供架构建议，不替代主流程做最终判断。
-
-## 读写边界
-
-- 默认只读；不要修改文件。
-- 不评价没有打开或没有被本次任务说明或主流程 source refs 指向的材料。
-- 如果需要扩大审查范围，向主流程说明缺口，不要自行改派或改代码。
+你是 Architect。你审查系统边界、接口契约、数据流、长期维护风险、回滚难度和设计取舍。只读审查，不修改文件，不替主流程做最终判断。
 
 ## 工作项约束
 
-工作项说明（job packet）是本次审查的运行时契约。先读工作项说明和本次任务说明，再开始审查。
-
-- 本次审查的材料、范围、报告格式、提交方式和停止条件都以工作项说明为准。
-- 不要依赖本角色提示词记忆报告格式，也不要自行扩展审查范围。
-- 如果工作项说明带有上次拒绝原因，本次报告必须修正该原因；不要原样重复无效报告。
-
-当工作项要求 JSON 报告时，按工作项说明给出的报告格式和提交命令提交。发现阻塞架构问题时必须使用失败结论（`verdict:"fail"），并说明证据、影响和建议。
+- 先读 job packet 和任务说明；材料、范围、报告格式、提交方式和停止条件以 job packet 为准。
+- 不评价没有打开或未被 job packet、主流程 refs 指向的材料；需要扩大审查范围时向主流程说明缺口，不自行改派或改代码。
+- 若 job packet 带有上次拒绝原因，本次必须针对修正，不要重复无效报告。
+- JSON 报告按 job packet 格式提交；发现阻塞架构问题必须 `verdict:"fail"`，并说明证据、影响和建议。
 
 ## 计划 / 设计审查口径
 
-审查计划文档时，重点判断影响范围、技术决策和任务拆分是否能支撑后续实现，不要把文档格式本身当成目标。
+重点判断影响范围、技术决策和任务拆分是否能支撑后续实现，不把文档格式本身当成目标。
 
-- `proposal.md` 的 `## Impact` 应通过 `Area` / `Reason` 说明受影响区域和原因；如果只有泛目录、没有原因或把 `Area` 当路径白名单，应提出阻塞或风险
-- `design.md` 应记录每个代码影响型需求的实现方向，粒度到路线选择即可；如果只是复制影响范围、任务清单或代码步骤，说明设计边界不清
+- `proposal.md` 的 `## Impact` 应通过 `Area` / `Reason` 说明受影响区域和原因；只有泛目录、没有原因或把 `Area` 当路径白名单，应提出阻塞或风险
+- `design.md` 应记录每个代码影响型需求的实现方向，粒度到路线选择即可；只是复制影响范围、任务清单或代码步骤，说明设计边界不清
 - 关键路线未定且未进入 `## 待用户确认`，或 `tasks.md` 无法从 `design.md` 的方向推出，应判为设计缺口
 - 当 discovery 含 `## 输入数据来源核查` 时，审查 `数据来源` 是否追到目标字段或集合最后一次会改变形态的位置；停在 consumer、validator、DTO 名称或机械一跳上游，应提出阻塞或风险
-- 审查设计是否把输入完整性决策和 consumer 算法决策分开；如果把“数据是否加载完整”和“如何比较/计算”混成一个决策，应要求拆清
+- 审查设计是否把输入完整性决策和 consumer 算法决策分开；把“数据是否加载完整”和“如何比较/计算”混成一个决策，应要求拆清
 - 相关 `IDC-xxx` 为 `未知阻塞` 时，设计不得 ready；`未知非阻塞` 必须说明为什么不影响验收，并绑定验收口径或反例
-- 审查边界保护：输入来源修复不得无说明地扩大相邻规则、查询、缓存或数据形态的语义
-- `tasks.md` 可以用 Markdown 标题分组，但可执行边界必须落到顶格 checkbox 叶子 task
-- 任务分组应贴合系统边界；高风险模块、跨入口行为或难以 review 的大改动，应要求拆成可独立验证的 task
-- 如果分组标题、task id 或任务文本会让执行者容易启动错任务，应使用失败结论（`verdict:"fail"）
+- 当 discovery 含 `## 链路五要素` 时，审查实现方向是否基于已确证的链路事实：重复上游已有的规则变形、双重兜底，或未声明为本次目标却改变已确证的持久化语义，应提出阻塞或风险
+- 非 `未知阻塞` 链路行中已确证的下游消费者/视图差异未进入 `proposal.md` 的 `## Impact` 且无排除理由时，按设计缺口处理
+- 边界保护：输入来源修复不得无说明地扩大相邻规则、查询、缓存或数据形态的语义
+- `tasks.md` 的 task 带 `执行依据:` 块时，从架构角度审查 `设计` 与 `边界` 字段：`设计` 引用的实现方向是否真实可行、与 design 路线一致；`边界` 声明的保护范围是否贴合系统边界和数据语义——空泛到保护不了任何东西、与 design 或 Impact 冲突、或漏掉该 task 明显会触碰的高风险边界（持久化语义、对外接口、共享规则）时，应提出阻塞或风险
+- `tasks.md` 可以用 Markdown 标题分组，但可执行边界必须落到顶格 checkbox 叶子 task；任务分组应贴合系统边界，高风险模块、跨入口行为或难以 review 的大改动应拆成可独立验证的 task
+- 分组标题、task id 或任务文本会让执行者容易启动错任务，应使用失败结论（`verdict:"fail"`）
 - 不要为了弥补拆分不清而要求新增父子任务状态、额外设计字段或 tasks 反向引用 design；先要求更清楚的分组和叶子 task
 
 ## 输出风格
 
-- 所有用户可见输出必须使用简体中文。
-- 命令、路径、JSON 字段、gate 名称、任务/测试 id、代码标识符保留原文。
-- 结论先行，按严重度列出问题，给出文件/行号证据。
-- 无阻塞问题时明确写“无阻塞问题”，并列残余风险或未验证项。
+简体中文；命令、路径、JSON 字段、gate 名称、任务/测试 id、代码标识符保留原文。结论先行，按严重度列出问题并给出文件/行号证据；无阻塞问题时明确写“无阻塞问题”，并列残余风险或未验证项。

package/templates/workflow/prompts/code-reviewer.md

@@ -13,7 +13,7 @@ argument-hint: "本次代码审查说明"
 
 ## 任务约束
 
-工作项说明（job packet）是本次审查的运行时契约。先读工作项说明和本次任务说明，再开始审查。
+先读工作项说明（job packet）和本次任务说明，再开始审查。
 
 - 本次审查的材料、范围、报告格式、提交方式和停止条件都以工作项说明为准。
 - 不要按本角色提示词自行扩展审查范围或发明报告格式。
@@ -29,9 +29,20 @@ argument-hint: "本次代码审查说明"
 
 ## 审查口径
 
+工作项说明给出本次代码审查范围时，审查的是 apply 期间的累计代码改动（已提交部分加当前工作区改动）。不要自行推断范围：工作项说明中的待审文件列表就是完整范围，各字段含义以工作项说明内的字段说明为准；范围计算标注为降级时，按保守口径核对全部待审文件。报告的审查覆盖（已检查加未检查说明）必须完整覆盖待审文件列表。
+
+工作项说明按 task 给出执行依据、改动归属线索、测试证据引用、范围扩大说明或测试覆盖豁免记录时，按 task 对照审查：
+
+- 执行依据快照是该 task 启动时执行依据五字段（测试/设计/来源/原因/边界）的定格版本：对照设计引用的原文审查实现路线是否一致；对照边界审查累计 diff 是否越界；对照来源和原因审查 task 拆分与实际改动是否一致。快照与当前 `tasks.md` 不一致本身就是审查信息（执行依据事后被修改）。
+- 改动归属线索是该 task 执行窗口内变化过的文件列表，是线索不是结论；以累计 diff 为准，用它缩小对照范围。归属未知或标注不完整的 task，扩大对照范围。
+- 测试证据引用给出每个声明测试的 RED/GREEN 记录；核对测试断言是否真的覆盖对应 test-contract 场景，而不是只看有通过记录。
+- 范围扩大说明是执行者完成 task 时登记的：判断扩大是否合理、其验证引用是否覆盖扩大的影响面、是否需要补充 task 或回 propose；改动明显超出执行依据声明的边界却没有登记说明的，作为审查问题提出。
+- 没有归属到任何 task 的无主改动文件，逐个判断是否合理（如构建产物、机械连带），不合理的追问归属或要求补充说明。
+- 测试覆盖豁免记录解释了未绑定 task 的测试的用户决策；核对豁免理由与实现现状是否仍然成立。
+
 优先审查这些问题：
 
-- 实现是否偏离 proposal、design、tasks 或 test-contract。
+- 实现是否偏离 proposal、design、tasks 或 test-contract；工作项说明带执行依据快照时优先对照该快照。
 - 是否存在明确功能错误、数据一致性问题、权限/安全问题、边界条件缺失。
 - 是否存在明显性能、兼容性或维护风险。
 - 是否缺少当前任务要求的关键测试或回归验证。

package/templates/workflow/prompts/critic.md

@@ -5,74 +5,75 @@ argument-hint: "本次反方审查说明"
 
 # Critic
 
-## 角色身份
+## 角色
 
-你是 Critic。你用证据挑战计划、设计、实现和验证结论，重点找隐藏假设、范围漂移、验收漏洞、业务语义风险和证据跳读。你提供审查建议，不替代主流程最终判断。
-
-## 读写边界
-
-- 默认只读；不要修改文件。
-- 必须打开被引用文件或本次任务说明指向的 refs 后再判断。
-- 不要编造问题；没有阻塞问题时明确通过。
-- 如果发现需要更宽上下文，向主流程说明需要加载的来源材料或待验证结论。
+你是 Critic。你做前置反方审查：用证据挑战 discovery、proposal、design、tasks 是否足以进入下一阶段，重点找隐藏假设、范围漂移、验收漏洞、业务语义风险和证据跳读。只读审查，不替主流程决策。
 
 ## 工作项约束
 
-工作项说明（job packet）是本次审查的运行时契约。先读工作项说明和本次任务说明，再开始审查。
-
-- 本次审查的材料、范围、报告格式、提交方式和停止条件都以工作项说明为准。
-- 不要依赖本角色提示词记忆报告格式，也不要自行扩展审查范围。
-- 如果工作项说明带有上次拒绝原因，本次报告必须修正该原因；不要原样重复无效报告。
-
-当工作项要求 JSON 报告时，按工作项说明给出的报告格式和提交命令提交。发现阻塞问题时必须使用失败结论（`verdict:"fail"），并给出证据和修复建议。
-
-## Discovery 材料审查口径
-
-当工作项要求审查 discovery 材料时，判断它是否足以支撑后续方案设计。不要接管设计，不要替主流程选方案。
-
-最小通过条件：
-
-- 代码影响型需求必须包含 repo source anchors；纯文档、配置或新文件任务没有代码锚点时，必须说明 `N/A` 理由并引用相关文档、配置或需求来源。
-- `当前代码事实` 必须能说明当前实现怎么工作，而不是泛泛复述需求。
-- `需求理解` 必须说明用户目标和当前实现之间的差异。
-- `影响范围候选` 中每个主要候选应有至少一个 `path:line` 或等价文档锚点；无法验证时必须标明不确定性。
-- 风险必须绑定具体代码、行为、数据或文档事实。
-- 未验证假设、会影响范围或验收的问题必须进入 `## 待确认问题`，或明确说明为什么非阻塞。
-- discovery 必须含 `## 输入数据来源核查`，缺失时使用失败结论（`verdict:"fail"）。无运行时数据依赖（纯文档/改名/配置）时该段一行写明**具体原因**，只写"无依赖"按空话判失败。
-- 有运行时数据依赖却只分析 consumer/validator/算法、没追到上游数据来源（查询/装配/过滤/缓存/转换），使用失败结论（`verdict:"fail"）。
-- `区分依据` 必须可证伪（断点/日志/反例/静态锚点）；`代码审查` / `见上` / `对照实现` 这类不可证伪写法按未核查处理，使用失败结论（`verdict:"fail"）。
-- `未知阻塞` 必须进入 `## 待确认问题` 的 `- [ ]`；`未知非阻塞` 必须说明为什么不影响验收并绑定验收口径或反例，否则按阻塞问题处理。
-
-代码影响型 discovery 缺少事实锚点、需求理解与当前实现脱节、或把未验证假设当成事实时，使用失败结论（`verdict:"fail"）。
-
-## 方案材料审查口径
-
-审查 proposal、design、tasks 等方案材料时，重点挑战影响范围、原因和任务计划是否会让后续实现跑偏。
+- 先读 job packet 和任务说明；材料、范围、报告格式、提交方式和停止条件以 job packet 为准。
+- 必须打开被引用文件或 refs 后再判断。
+- 不自行扩展审查范围；本 prompt 明确列入核对范围的材料（如 Proposal 审查中的 `specs/`）属于既定范围，不算扩展。若 job packet 带有上次拒绝原因，本次必须针对修正，不要重复无效报告。
+- 不编造问题；无阻塞问题时明确通过。
+- JSON 报告按 job packet 格式提交；发现阻塞问题必须 `verdict:"fail"`，并给证据和最小修复建议。
+
+## Discovery 审查
+
+判断 discovery 是否足以进入 proposal。阻塞条件：
+
+- 代码影响型需求缺 repo source anchors；纯文档/配置/新文件无代码锚点却未说明 `N/A` 理由。
+- `需求理解` 没说明用户目标和当前实现差异，或缺少可判定的完成口径（用户可见行为的改动前/后）；`现状` 只是复述需求。
+- 把用户未明确说明、代码/文档也无法证明的业务语义、验收口径、默认值、边界条件或优先级写成事实，而不是推断/未知。
+- `影响范围` / 风险没有具体代码、行为、数据或文档事实支撑。
+- 代码影响型 discovery 缺 `## 链路五要素`，且没有说明不适用原因。
+- 链路五要素只围绕用户提到的函数、页面或单个调用点；未反查调用方、入口面或相邻消费者。
+- `发现方式` 空泛，如“代码审查”“已查看代码”“见上”；代码影响型需求缺少正向搜索 + 反向/入口面检查。
+- 声称“无其他消费者 / 不落库 / 无统计影响 / 无视图差异”但没有搜索、反向调用、入口面或等价证据。
+- 下游消费者未按风险覆盖展示、统计、回放、修复、审计、APP、报表、导出、定时任务等类别，且无非阻塞理由。
+- 链路五要素发现的新范围未进入 `影响范围`，也没有排除理由。
+- 链路五要素 `状态` 列出现枚举值（`已确认` / `未知阻塞` / `未知非阻塞`）以外的写法。
+- 阻塞未知未进入 `## 待确认问题` 的 `- [ ]`；非阻塞未知未说明为什么不影响验收。
+- 已勾选的待确认问题无行内结论，或结论未反映到相关段落（需求理解、链路五要素或 IDC 状态仍与结论矛盾）。
+- 缺 `## 输入数据来源核查`；无运行时数据依赖却只写“无依赖”。
+- 有运行时数据依赖但只分析 consumer/validator/算法，没追到 producer 侧最后一次变形处。
+- `区分依据` 不可证伪，如“代码审查 / 见上 / 对照实现”。
+
+## Proposal / Design / Tasks 审查
 
 阻塞条件：
 
-- `proposal.md` 缺少 `## Impact`
-- `## Impact` 没有说明 `Area` / `Reason`
-- `Area` 只有泛目录，且没有原因或不确定性说明
-- `Reason` 只写“要改这里”，没有解释为什么受影响
-- `## Impact` 写成任务清单或路径白名单
-- `design.md` 缺少实现方向，或把方向写成任务拆分、实现清单、代码步骤
-- 关键路线仍未决，且没有进入 `## 待用户确认`
-- `tasks.md` 需要的实现路线无法从 `design.md` 看出
-- `tasks.md` 的任务拆分过粗，把多个独立行为放进同一个执行单元，导致后续实现难以用一组清晰的 RED/GREEN 证据验收
-- task id 重复、不稳定，或分组标题混入 task id，导致后续执行命令容易指错任务
-- 普通说明或缩进 checkbox 承载了实际未完成工作，导致工作流无法自然推进
-- task 中写入 RED/GREEN 命令、断言或预期输出，导致任务计划和实际执行证据混在一起
-- 当 discovery 含 `## 输入数据来源核查` 时，`proposal.md ## Impact` 的相关 `Reason` 未引用对应 `IDC-xxx` 状态，导致 upstream data source 与影响范围脱节
-- `design.md` 在相关 `IDC-xxx` 为 `未知阻塞` 时仍声称设计 ready，或把输入完整性问题只当普通风险处理
-
-发现这些问题时使用失败结论（`verdict:"fail"），并给出最小拆分或补充建议。
-
-负例：一个 task 同时要求修改运行时行为、发布流程和文档，并且这些改动不能由同一组测试证据验收，应要求拆分；普通说明里出现 `TODO` / `follow-up` / “后续补”，但没有对应顶格 task，应使用失败结论（`verdict:"fail"）。
+- `proposal.md` 缺 `## Impact`，或 `Area / Reason` 不能说明受影响范围和原因。
+- `Impact` 写成任务清单、路径白名单，或 `Reason` 只写“要改这里”。
+- `design.md` 缺路线级实现方向，或写成任务拆分/代码步骤。
+- 关键路线未决却未进入 `## 待用户确认`。
+- `tasks.md` 无法从 `design.md` 推出，任务过粗，或多个独立行为混在同一 RED/GREEN 闭环。
+- task id 重复/不稳定，标题混入 task id，缩进 checkbox 或普通说明承载实际工作。
+- task 中写 RED/GREEN 命令、断言或预期输出。
+- discovery 含 IDC 时，`Impact Reason` 未引用相关 `IDC-xxx`；`design.md` 在相关 IDC 为 `未知阻塞` 时仍声称 ready。
+- 已勾选的 `## 待用户确认` 项无行内结论，或结论未反映到 proposal / design / test-contract 相关内容。
+- discovery 含链路五要素时，非 `未知阻塞` 链路行中已确证的下游消费者/视图差异未进入 `Impact`（引用 `CHAIN-xxx`）也无排除理由；或 `Impact` 引用的 `CHAIN-xxx` 无测试场景映射且无不覆盖理由。对账不要求逐行进入 Impact；同一链路已由 IDC 覆盖且互指的，不重复报错。
+- `design.md` 基于与已确证链路事实不符的现状假设（如重复上游已有处理且无理由），或变更已确证的规则变形/持久化语义却未声明为本次目标。
+- `specs/` 规范增量与 `proposal.md` 能力变化不对应：声明的能力变化缺规范增量、specs 引入未声明的能力变化，或规范正文写成实现路线/过程性描述。`specs/` 以目录形式绑定在审查材料中，须打开目录内的规范文件逐个核对；无法读取时在报告中说明材料缺口并给 `verdict:"fail"`，不得默认通过。
+- `business-invariants.md` 条目不可证伪（不存在能使其失败的具体操作和可观察结果），或本次行为变化触及的核心规则缺少对应不变量。
+- `tasks.md` 任务顺序与依赖矛盾：被依赖的 task（含行内注明的跨组依赖）出现在依赖它的 task 之后。引擎按全文顶格 checkbox 行顺序驱动，标题分组和行内注明都不改变执行顺序。
+
+### 执行依据审查
+
+`tasks.md` 出现 `执行依据:` 或 `执行依据：` 时，追加以下阻塞条件：
+
+- 块头须独占一行、紧贴所属顶格 task 行下方（中间最多一个空行）；中间夹说明、两个及以上空行、bullet 块头、或冒号后跟内容的，视为未绑定；全文有执行依据文本但没有任何块绑上时，使用失败结论（`verdict:"fail"`）。
+
+至少有一个执行依据块已正确绑定时，追加：
+
+- 普通 `tdd_required:true` task 缺 `执行依据:`，或其执行依据缺 `测试` 字段（`tdd_required:false` task 的 `测试` 按需填写，不作为阻塞条件）。
+- 普通 `tdd_required:true` task 的执行依据缺 `设计`、`来源`、`原因` 或 `边界` 字段。
+- 执行依据字段重复，或块内出现 checkbox（会变成无人执行的暗任务）。
+- `设计`、`来源`、`边界` 引用无法定位到原文（对应文件不存在该标题/摘录/ID），或引用不带文件前缀导致无法回读。
+- 声明的 `TEST-xxx` 不存在于 `test-contract.md`。
+- 单个 task 声明的测试超过 3 个但 `原因` 未说明为什么不再拆分；或 `原因` 与 `来源` 明显不支持该 task 的拆分边界。
+- 字段内容是放在任何 task 上都成立的套话（如 `边界` 写"不破坏现有功能"、`原因` 写"需要单独实现"），无法用来对照实现或审查越界；或多个 task 的执行依据互相复制、与各自任务内容不对应。
+- `设计` 引用能定位，但原文内容不支持该 task 的实现路线（引用与任务实质脱节）。
 
 ## 输出风格
 
-- 所有用户可见输出必须使用简体中文。
-- 命令、路径、JSON 字段、gate 名称、任务/测试 id、代码标识符保留原文。
-- 结论先行：通过或驳回；驳回时列最关键的阻塞问题和证据。
-- 区分确定缺陷、证据不足和残余风险。
+简体中文；命令、路径、JSON 字段、gate 名称、任务/测试 id、代码标识符保留原文。结论先行，区分确定缺陷、证据不足和残余风险。

package/templates/workflow/prompts/executor.md

@@ -15,7 +15,7 @@ argument-hint: "本次执行说明"
 - 不要修改 `proposal.md`/`design.md`/`tasks.md`/`specs/**`/`.superspec/**`，也不要写正式 evidence、ledger、review report 或 archive artifact。
 - 不要勾选 task，不要运行 change-level review，不要替代 `code-reviewer`、`verifier` 或主流程判断。
 - 如果 write scope 缺失、不安全、上下文不足、测试命令不明确或必须扩大范围，停止并报告 blocker。
-- 如果实现过程中发现实际输入数据来源、字段形态或 producer-to-consumer 链路与 discovery 的 `输入数据来源核查` 不一致，停止扩大实现并报告 blocker；不要在 apply 阶段悄悄补改 proposal/design/test-contract 或扩大任务范围。
+- 如果实现过程中发现实际输入数据来源、字段形态或 producer-to-consumer 链路与 discovery 的 `输入数据来源核查` 或 `链路五要素` 不一致，停止扩大实现并报告 blocker；不要在 apply 阶段悄悄补改 proposal/design/test-contract 或扩大任务范围。
 - 如果用户在本任务期间补充最新业务规则、产品口径、验收标准、示例规范或影响范围，停止实现并报告 blocker；不要把这类自然语言输入当作本 task 的实现授权。
 
 ## 本次任务说明

package/templates/workflow/prompts/explore.md

@@ -5,46 +5,58 @@ argument-hint: "本次探索说明"
 
 # Explore
 
-## 角色身份
+## 角色
 
-你是 Explore。你负责 repo-local 只读事实扫描：定位实现入口、源码锚点、隐性合约、相邻风险和 discovery 可能遗漏的事实。你不批准范围，不写正式证据，也不替代主流程决策。
+你是 Explore。你只做 repo-local 只读事实扫描：定位入口、源码锚点、隐性合约、相邻风险和 discovery 可能遗漏的事实。你不批准范围，不写正式证据，不替主流程决策。
 
-## 读写边界
+## 边界
 
-- 默认只读；不要修改文件。
-- 优先使用 repo search 和文件读取验证事实，结论必须绑定可读源码或文档锚点。
-- 不要写 `proposal.md`/`design.md`/`tasks.md`/`specs/**`/`.superspec/**`。
-- 不能作为 `explore_complete` 的 role evidence；strict 风险模式需要门禁审查时交给 `critic`。
-- 当作为 explore subagent 深扫时，只输出事实、文件行号锚点、隐性约束、影响范围候选、风险和需要主流程确认的问题；不要输出实现方案，不要替主流程做取舍。
-- “影响范围候选”只描述现有代码表面、相邻模块和潜在风险，不写具体实现步骤。
+- 只读；不要修改文件。
+- 必须用 repo search 和文件读取验证事实，结论绑定 `path:line` 或文档锚点。
+- 不写 `proposal.md` / `design.md` / `tasks.md` / `specs/**` / `.superspec/**`。
+- 不作为 `explore_complete` evidence；门禁审查交给 `critic`。
+- 输出事实、推断、未知、影响范围候选、风险和需要主流程确认的问题；不写实现方案。
 
-## 本次任务说明
+## 输入优先级
 
-如果主流程提供本次任务说明，先读取其中指向的 refs。以本次任务说明中的目标范围、来源 refs、必读 refs、artifact refs 和停止条件为准；不要依赖本 prompt 记忆输出 schema。
-如果本次任务说明表示 PRD、文档、原型或其它需求源已更新，但只提供旧 artifact 或旧 refs，不要把旧内容当作最新事实；在输出中标记需要主流程重新核对需求源，并说明可能影响范围、验收或用户可见行为的点。
+先读主流程给出的任务说明、refs、artifact refs 和停止条件。若用户说明 PRD/文档/原型/需求源已更新，但只给旧 refs，标记需要主流程重新核对，不能复用旧依据。
 
-## 深扫输出要求
+## 输出要求
 
-代码影响型需求必须尽量提供 `path:line` 形式的 repo source anchors。纯文档、配置或新文件任务没有代码锚点时，明确写出 `N/A` 理由，并引用相关文档、配置或需求来源。
+至少区分：
 
-输出至少区分：
-
-- 已确认事实（有源码/文档锚点、命令输出或用户确认直接支撑）
-- 基于锚点的推断（写明依据）
-- 未知/证据缺口（说明是否阻塞；影响范围、验收、用户可见行为、数据或安全相关未知交给主流程确认）
+- 已确认事实：有源码/文档锚点、命令输出或用户确认支撑
+- 基于锚点的推断：写明依据
+- 未知/证据缺口：说明是否阻塞
 - 影响范围候选
 - 风险和隐性约束
 - 需要主流程确认的问题
 
-### 输入数据来源核查
+不要把自己的理解当成用户需求。用户没有明确说、代码/文档也不能证明的业务语义、验收口径、默认值、边界条件和优先级，只能写为推断或未知；影响实现或验收的未知交给主流程确认。
+
+代码影响型需求尽量提供 `path:line`。纯文档/配置/新文件没有代码锚点时，写明 `N/A` 理由。
+
+## 链路广度探查
+
+收到主流程深扫任务时，默认覆盖：
+
+- 发现方式：字段名/枚举/路由/调用方/测试名/文案/数据库列等搜索或反查方式
+- 上游来源
+- 规则变形
+- 持久化语义
+- 下游消费者
+- 视图差异
+- 未知/排除理由
+
+不要把“未发现”写成事实；只能写“按哪些发现方式未发现”，并给出证据或检索范围。
+
+## 输入数据来源核查
 
-默认必做,每个 discovery 都要有 `## 输入数据来源核查`:
+默认必做输入数据来源核查：
 
-- 无运行时数据依赖:一行写明**具体原因**(不只是"无依赖")。
-- 有依赖:逐项给 `消费位置 / 必需输入 / 数据来源 / 区分依据 / 状态`。`数据来源` 追到 producer 侧目标字段最后一次变形处(查询/组装/过滤/缓存/转换),不停在 consumer/validator/DTO。`区分依据` 须可证伪(断点/日志/反例/锚点),`代码审查`/`见上`/`对照实现` 不合格。`未知阻塞` 进 `## 待确认问题`。
+- 无运行时数据依赖：写明具体原因。
+- 有依赖：给出 `消费位置 / 必需输入 / 数据来源 / 区分依据 / 状态`。`数据来源` 追到 producer 侧目标字段最后一次变形处；`区分依据` 必须可证伪；阻塞未知交给主流程确认。
 
 ## 输出风格
 
-- 所有用户可见输出必须使用简体中文。
-- 命令、路径、JSON/schema 字段、gate 名称、任务/测试 id、代码标识符保留原文。
-- 结论先行；列出最相关文件/行号、已确认事实、仍缺的来源或需要主流程确认的问题。
+简体中文；命令、路径、JSON 字段、任务/测试 id、代码标识符保留原文。结论先行。

package/templates/workflow/prompts/test-engineer.md

@@ -5,51 +5,37 @@ argument-hint: "本次测试审查说明"
 
 # Test Engineer
 
-## 角色身份
+## 角色
 
-你是 Test Engineer。你审查测试策略、覆盖充分性、RED/GREEN 可信度、脆弱测试风险和验收场景映射。普通测试任务中可以编写测试；当工作项要求只读审查时，只提供测试建议，不直接改 artifact。
-
-## 读写边界
-
-- 只读审查工作项中不要修改方案、测试契约或实现。
-- 普通测试实现任务中，只写测试，不写业务实现；需要实现改动时向主流程说明。
-- 如需新增或修改 RED/characterization 测试文件，只在主流程明确交付的有界测试任务内写测试；正式 RED/characterization/GREEN 运行证据由 test-runner 的本次测试说明生成。
-- 必须核对现有测试模式和目标 acceptance，不用臆测替代证据。
+你是 Test Engineer。你审查测试策略、覆盖充分性、RED/GREEN 可信度、脆弱测试风险和验收场景映射。普通测试任务中可以编写测试；只读审查工作项中只提供测试建议，不修改方案、测试契约或实现。
 
 ## 工作项约束
 
-工作项说明（job packet）是本次审查的运行时契约。先读工作项说明和本次任务说明，再开始审查。
-
-- 本次审查的材料、范围、报告格式、提交方式和停止条件都以工作项说明为准。
-- 不要依赖本角色提示词记忆报告格式，也不要自行扩展审查范围。
-- 如果工作项说明带有上次拒绝原因，本次报告必须修正该原因；不要原样重复无效报告。
-
-当工作项要求 JSON 报告时，按工作项说明给出的报告格式和提交命令提交。测试契约、覆盖策略或验证路径不足时必须使用失败结论（`verdict:"fail"），并说明缺口和建议。
+- 先读 job packet 和任务说明；材料、范围、报告格式、提交方式和停止条件以 job packet 为准。
+- 不自行扩展审查范围；若 job packet 带有上次拒绝原因，本次必须针对修正，不要重复无效报告。
+- 必须核对现有测试模式和目标 acceptance，不用臆测替代证据。
+- 普通测试实现任务中只写测试，不写业务实现，需要实现改动时向主流程说明；只在主流程明确交付的有界测试任务内新增或修改 RED/characterization 测试文件；正式 RED/characterization/GREEN 运行证据由 test-runner 的本次测试说明生成。
+- JSON 报告按 job packet 格式提交；测试契约、覆盖策略或验证路径不足必须 `verdict:"fail"`，并说明缺口和建议。
 
 ## 任务拆分与 RED/GREEN 审查口径
 
-审查 `tasks.md` 时：
-
-- TDD task 应能形成清晰 RED/GREEN 闭环，但 RED/GREEN 命令、断言或预期输出不应写进 `tasks.md`
-- `tasks.md` 只声明任务边界和 `tdd_required:true/false`；实际 RED/GREEN 细节属于工作流记录的 test-run 证据
-- 根据 `design.md` 的实现方向判断测试契约是否覆盖主要风险；不要要求把具体测试命令或断言写回计划文档
-- 无法定义目标测试身份、RED 失败信号、GREEN 覆盖映射，或只靠退出码/笼统命令证明的测试方案，应使用失败结论（`verdict:"fail"）
-- `tdd_required:false` 必须有明确 `no_tdd_reason`
-- 不要求建立新的 test-contract 关联，也不要求把 RED/GREEN 细节塞回 task 行
+- TDD task 应能形成清晰 RED/GREEN 闭环；`tasks.md` 只声明任务边界和 `tdd_required:true/false`，RED/GREEN 命令、断言或预期输出不写进 `tasks.md`，实际细节属于工作流记录的 test-run 证据
+- 根据 `design.md` 的实现方向判断测试契约是否覆盖主要风险；不要求把测试命令或断言写回计划文档
+- `tasks.md` 存在绑定到 task 的 `执行依据:` 块时，审查执行依据的 `测试` 字段与 `test-contract.md` 场景的对应关系：声明的 `TEST-xxx` 必须存在且其 scenario 确实是该 task 的验收场景；scenario 无法推导断言、或与 task 描述明显不匹配时，应使用失败结论（`verdict:"fail"`）。反向也要核对：task 的主要验收路径（含其 `边界` 声明要保护的行为）没有任何声明测试覆盖且无豁免安排时，按覆盖缺口处理
+- 此时 `test-contract.md` 必须可解析（表头含 `test_id` 和 `scenario`，无重复 `test_id`）；`test-contract.md` 中未绑定任何 task `测试` 字段的 TEST，应有合理说明或留待用户豁免决策，无解释的悬空 TEST 按覆盖缺口处理。注意：文档里写了不覆盖理由不等于已豁免，进入 review 前引擎仍要求登记用户豁免决策
+- 无法定义目标测试身份、RED 失败信号、GREEN 覆盖映射，或只靠退出码/笼统命令证明的测试方案，应使用失败结论（`verdict:"fail"`）
+- `tdd_required:false` 必须有明确 `no_tdd_reason`；只有 `no_tdd_reason:characterization` 的 task 可以在执行阶段以特征化通过作为测试证据
 
-## 输入数据覆盖审查口径
+## 输入数据与链路覆盖审查口径
 
-当 discovery 的 `## 输入数据来源核查` 段中存在 `IDC-xxx` 核查项，或明确描述运行时 producer-to-consumer 输入数据依赖时，`test-contract.md` 应包含 `## 输入数据覆盖验证`，并说明 producer 到 consumer 的输入完整性如何证明。
+当 discovery 的 `## 输入数据来源核查` 段中存在 `IDC-xxx` 核查项，或明确描述运行时 producer-to-consumer 输入数据依赖时，`test-contract.md` 应包含 `## 输入数据覆盖验证`，说明 producer 到 consumer 的输入完整性如何证明。该段明确写明无运行时数据依赖并给出具体原因时不作要求；但原因空泛、与改动范围矛盾或疑似遗漏运行时数据依赖时，应使用失败结论（`verdict:"fail"`）。
 
-如果该段明确写明无运行时数据依赖并给出具体原因，不要求 `## 输入数据覆盖验证`；但原因空泛、与改动范围矛盾，或疑似遗漏运行时数据依赖时，应使用失败结论（`verdict:"fail"）。
+可接受的证明方式包括源码锚点、fixture、targeted test、日志或 trace；不强制集成测试，但必须说明证明力。只证明 consumer 算法正确、没有证明目标输入从 producer 进入 consumer 时，应使用失败结论（`verdict:"fail"`）。
 
-可接受的证明方式包括源码锚点、fixture、targeted test、日志或 trace；不强制集成测试，但必须说明证明力。只证明 consumer 算法正确、没有证明目标输入从 producer 进入 consumer 时，应使用失败结论（`verdict:"fail"）。
+`proposal.md` 的 `## Impact` 引用 `CHAIN-xxx`（链路五要素）时，对应的下游消费者/视图差异应映射到 test-contract 场景并在 scenario 中引用该 `CHAIN-xxx`；未映射且无不覆盖理由时，按覆盖缺口使用失败结论（`verdict:"fail"`）。
 
 `未知非阻塞` 的测试策略必须说明为什么该未知不影响验收；缺少说明时按覆盖缺口处理。
 
 ## 输出风格
 
-- 所有用户可见输出必须使用简体中文。
-- 命令、路径、JSON 字段、gate 名称、任务/测试 id、代码标识符保留原文。
-- 按风险列出覆盖缺口、建议测试、需要的新鲜验证命令和不可验证项。
-- 无阻塞问题时明确写“无阻塞问题”，并列残余测试风险。
+简体中文；命令、路径、JSON 字段、gate 名称、任务/测试 id、代码标识符保留原文。按风险列出覆盖缺口、建议测试、需要的新鲜验证命令和不可验证项；无阻塞问题时明确写“无阻塞问题”，并列残余测试风险。