@peterxiaoyang/superspec 0.1.44 → 0.1.46

package/README.md

@@ -131,7 +131,7 @@ superspec.cmd install
 
 你日常主要记住这四个入口就够了。
 
-CLI 不带 `--risk` 时默认走完整审查路径；需要轻量路径时显式传 `--risk normal` 或 `--risk minimal`。探索阶段会创建 `critic` 工作项审查需求澄清记录；计划阶段会创建 `critic`、`architect` 和 `test-engineer` 工作项后再进入实现准备。
+工作流档位由项目配置统一控制，不通过命令行临时指定。探索阶段会按配置创建相应审查工作项；计划阶段按同一档位创建 `critic`、`architect`、`test-engineer` 等必要审查后再进入实现准备。
 
 ## 它会多保存哪些记录
 
@@ -191,6 +191,18 @@ superspec install
 
 `superspec install` 会创建缺失的 `openspec/config.yaml`，或在没有顶层 `context` 时追加这段官方中文 context。如果文件已经有顶层 `context`，SuperSpec 不会覆盖它。
 
+它还会创建项目级 `.superspec/config.json`，用于统一设置整个工作流的默认档位：
+
+```json
+{
+  "workflow": {
+    "mode": "normal"
+  }
+}
+```
+
+可选值为 `minimal`、`normal`、`strict`。`next`、Explore、Propose、进入 Apply 和 Review 都读取此配置；`--risk` 不再是用户可用的工作流入口。已启动的 task attempt 和已经建立的审查策略仍按其事件快照执行，不会被中途改配置追溯改写。
+
 可以用下面的命令检查生成的 instructions 是否包含语言上下文：
 
 ```bash

package/dist/cli.js

@@ -13,6 +13,7 @@ import { recordTestRun, recordTestRunContent } from "./task.js";
 import { RecordInputDecodingError, decodeRecordInput } from "./record_input.js";
 import { probeOpenSpec, openspecStatus, changeRoot } from "./openspec.js";
 import { SUPERSPEC_VERSION } from "./version.js";
+import { WorkflowConfigError, workflowRiskForProject } from "./workflow_config.js";
 const PACKAGE_NAME = "@peterxiaoyang/superspec";
 const OPENSPEC_PACKAGE_NAME = "@fission-ai/openspec";
 const OPENSPEC_REQUIRED_VERSION = "1.4.1";
@@ -67,19 +68,15 @@ function proposeReadyExitCode(result) {
         return 0;
     return result.events_written === 0 && result.message.includes("不能") ? 1 : 0;
 }
-function parseReviewRisk(value) {
-    if (value == null)
-        return "strict";
-    if (value === "minimal" || value === "normal" || value === "strict")
-        return value;
-    return null;
-}
-function readReviewRisk(opts) {
-    const risk = parseReviewRisk(opts.risk);
-    if (!risk) {
-        console.error("--risk 只能是 minimal、normal 或 strict");
+function ensureWorkflowMode(projectRoot, _opts) {
+    try {
+        workflowRiskForProject(projectRoot);
+        return true;
+    }
+    catch (err) {
+        console.error(err instanceof WorkflowConfigError ? err.message : String(err));
+        return false;
     }
-    return risk;
 }
 function parseVersion(version) {
     const match = version.trim().match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/);
@@ -516,6 +513,7 @@ async function main(argv) {
 transition 子命令：
   init / explore / sync / next / propose-ready / start-apply
   task-start --task <T> / task-complete --task <T> [--input -]
+  reopen --to explore|propose|apply --reason <TEXT>
   reopen --to apply --reason <TEXT> [--review-fix <JOB#FINDING>]
   reopen --to propose --reason <TEXT> [--review-finding <JOB#FINDING>]
   review-ready / accept
@@ -640,16 +638,20 @@ jobs 子命令：
             }
             case "transition": {
                 const cr = changeRoot(projectRoot, change);
+                // mode 只能由项目配置和已冻结 round 快照决定；任何 transition 都不接受 --risk。
+                if (opts.risk !== undefined) {
+                    console.error("工作流模式由 .superspec/config.json 的 workflow.mode 控制，不支持 --risk");
+                    return 1;
+                }
                 switch (subcommand) {
                     case "init":
                         console.log(JSON.stringify(transitionInit(projectRoot, change, cr), null, 2));
                         return 0;
                     case "explore":
                         {
-                            const risk = readReviewRisk(opts);
-                            if (!risk)
+                            if (!ensureWorkflowMode(projectRoot, opts))
                                 return 1;
-                            console.log(JSON.stringify(transitionExplore(projectRoot, change, cr, risk), null, 2));
+                            console.log(JSON.stringify(transitionExplore(projectRoot, change, cr), null, 2));
                         }
                         return 0;
                     case "sync": {
@@ -664,18 +666,16 @@ jobs 子命令：
                         return 0;
                     }
                     case "next": {
-                        const risk = readReviewRisk(opts);
-                        if (!risk)
+                        if (!ensureWorkflowMode(projectRoot, opts))
                             return 1;
-                        const result = nextCmd(projectRoot, change, cr, risk);
+                        const result = nextCmd(projectRoot, change, cr);
                         console.log(JSON.stringify(result, null, 2));
                         return 0;
                     }
                     case "propose-ready": {
-                        const risk = readReviewRisk(opts);
-                        if (!risk)
+                        if (!ensureWorkflowMode(projectRoot, opts))
                             return 1;
-                        const result = proposeReady(projectRoot, change, cr, risk);
+                        const result = proposeReady(projectRoot, change, cr);
                         console.log(JSON.stringify(result, null, 2));
                         return proposeReadyExitCode(result);
                     }
@@ -740,10 +740,9 @@ jobs 子命令：
                         return transitionExitCode(result);
                     }
                     case "review-ready": {
-                        const risk = readReviewRisk(opts);
-                        if (!risk)
+                        if (!ensureWorkflowMode(projectRoot, opts))
                             return 1;
-                        const result = reviewReady(projectRoot, change, cr, risk);
+                        const result = reviewReady(projectRoot, change, cr);
                         console.log(JSON.stringify(result, null, 2));
                         return transitionExitCode(result);
                     }

package/dist/code_review.js

@@ -348,7 +348,9 @@ function changedPathsBetweenSnapshots(projectRoot, start, completed) {
     return { paths: [...changed].sort(), partial_reason: partialReason };
 }
 function testEvidenceForAttempt(events, attempt) {
-    const declaredTests = attempt.contract_mode === true ? attempt.contract?.tests ?? [] : [];
+    const declaredTests = attempt.contract_mode === true
+        ? attempt.required_evidence?.test_ids ?? attempt.contract?.tests ?? []
+        : [];
     const eventsByTest = new Map();
     for (const ev of events) {
         if (ev.event_type !== "test_run_recorded")
@@ -411,14 +413,17 @@ function taskExecutionIndexFromEvents(projectRoot, events) {
             const started = attempts.get(payload.attempt_id);
             const attempt = started?.attempt;
             const effectiveContract = attempt?.contract_mode === true ? attempt.contract ?? null : null;
+            const requiredEvidence = attempt?.required_evidence ?? null;
             const changedResult = changedPathsBetweenSnapshots(projectRoot, started?.boundary ?? null, boundaryFromPayload(ev.payload));
             entries.push({
                 task_id: payload.task_id,
                 attempt_id: payload.attempt_id,
+                execution_policy: attempt?.execution_policy ?? "tdd",
                 changed_paths: changedResult ? changedResult.paths : null,
                 ...(changedResult?.partial_reason ? { changed_paths_partial_reason: changedResult.partial_reason } : {}),
                 contract: effectiveContract,
-                declared_tests: effectiveContract?.tests ?? [],
+                required_evidence: requiredEvidence,
+                declared_tests: requiredEvidence?.test_ids ?? effectiveContract?.tests ?? [],
                 scope_note: payload.scope_note && typeof payload.scope_note === "object" && !Array.isArray(payload.scope_note)
                     ? payload.scope_note
                     : null,

package/dist/format.d.ts

@@ -1,4 +1,4 @@
-import type { ExecutionContract } from "./types.ts";
+import { type ExecutionContract, type ExecutionPolicy } from "./types.ts";
 /** 从 discovery.md 提取"待确认问题"段内的未确认项数量 */
 export declare function countDiscoveryOpenQuestions(content: string): number;
 export interface DiscoveryChainCoverageCheck {
@@ -35,6 +35,8 @@ export interface ParsedExecutionRequirement {
     taskId: string;
     lineIdx: number;
     contract: ExecutionContract;
+    /** 执行依据中实际出现的字段；用于区分“测试为空”和“遗漏测试字段”。 */
+    declaredFields: Array<keyof ExecutionContract>;
     errors: string[];
 }
 export interface TestContractEntry {
@@ -51,6 +53,11 @@ export type TestContractParseResult = {
 };
 /** 解析 tasks.md 的全部任务行 */
 export declare function parseTasksMd(content: string): ParsedTask[];
+/**
+ * tasks.md 的机械结构校验。任务是否拆分合理、顺序是否符合真实依赖仍由
+ * Critic/Architect 判断；这里仅拒绝引擎无法可靠驱动的格式。
+ */
+export declare function validateTasksDocument(content: string): string[];
 export declare function hasTaskBoundExecutionRequirements(content: string): boolean;
 export declare function parseExecutionRequirements(content: string): ParsedExecutionRequirement[];
 export declare function orphanExecutionRequirementErrors(content: string): string[];
@@ -62,13 +69,24 @@ export declare function adoptedContractForTask(content: string, taskId: string,
 export declare function isReviewFixTaskId(taskId: string): boolean;
 export declare function isCharacterizationTask(task: ParsedTask): boolean;
 export declare function parseTestContractEntries(content: string): TestContractParseResult;
+export interface ProposalImpactValidation {
+    ok: boolean;
+    message: string;
+}
+/** OpenSpec 项目的 proposal 采用固定 Impact 表格，供状态机进行纯结构校验。 */
+export declare function validateProposalImpact(content: string): ProposalImpactValidation;
 export interface ExecutionRequirementValidation {
     ok: boolean;
     mode: boolean;
     contracts: ParsedExecutionRequirement[];
     errors: string[];
 }
-export declare function validateExecutionRequirements(content: string, testContractContent: string | null): ExecutionRequirementValidation;
+/**
+ * 在已初始化的当前工作流中，把执行依据的文件/锚点可解析性作为状态机协议。
+ * “该材料是否足以支撑 task”仍然是 Critic/Architect 的语义判断。
+ */
+export declare function validateExecutionRequirementDocumentReferences(changeRoot: string, contracts: readonly ParsedExecutionRequirement[]): string[];
+export declare function validateExecutionRequirements(content: string, testContractContent: string | null, executionPolicy?: ExecutionPolicy, executionRequirementVersion?: 1 | 2): ExecutionRequirementValidation;
 /** 返回未完成任务 */
 export declare function pendingTasksInContent(content: string): ParsedTask[];
 /** 在 tasks.md 中按 taskId 精确查找任务（词边界，不误判子串） */

package/dist/format.js

@@ -1,9 +1,10 @@
 // SuperSpec 流程引擎 — format.ts：文档格式解析的唯一权威源
 //
-// 所有文档的格式定义和解析逻辑都在这里。skills 文案引用这里的格式。
-// 修改格式 = 修改这里 + 对应 skill。禁止在其它地方重复解析。
-import { readFileSync, existsSync } from "node:fs";
-import { join } from "node:path";
+// 所有可机械判定的文档协议、格式定义和解析逻辑都在这里。skills 只指导
+// 生成与语义判断，不得自行充当格式校验器或在其它地方重复解析。
+import { readFileSync, existsSync, realpathSync } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { GREEN_ONLY_NO_TDD_REASON } from "./types.js";
 // ===== discovery.md =====
 //
 // 格式（explore skill 定义）：
@@ -51,6 +52,7 @@ const DISCOVERY_CHAIN_REQUIRED_COLUMNS = [
     "证据",
     "状态",
 ];
+const DISCOVERY_CHAIN_STATUSES = new Set(["已确认", "未知阻塞", "未知非阻塞"]);
 export function splitMarkdownTableRow(line) {
     const trimmed = line.trim();
     if (!trimmed.startsWith("|") || !trimmed.endsWith("|"))
@@ -94,6 +96,9 @@ export function validateDiscoveryChainCoverage(content) {
             }
         }
         const status = cells[statusIdx]?.trim() ?? "";
+        if (!DISCOVERY_CHAIN_STATUSES.has(status)) {
+            return { ok: false, message: `链路五要素第 ${rowNum} 行状态必须是 已确认、未知阻塞 或 未知非阻塞`, present: true };
+        }
         if (status.includes("未知阻塞") && countDiscoveryOpenQuestions(content) === 0) {
             return { ok: false, message: "链路五要素存在未知阻塞，但待确认问题中没有未解决项", present: true };
         }
@@ -151,8 +156,11 @@ const CONTRACT_FIELD_ALIASES = {
     "Design": "design",
     "来源": "source",
     "Source": "source",
-    "原因": "reason",
-    "Reason": "reason",
+    // 原因是历史文档字段；新文档用验收，二者都归一为 acceptance。
+    "验收": "acceptance",
+    "Acceptance": "acceptance",
+    "原因": "acceptance",
+    "Reason": "acceptance",
     "边界": "guard",
     "Guard": "guard",
 };
@@ -179,6 +187,28 @@ export function parseTasksMd(content) {
     }
     return tasks;
 }
+/**
+ * tasks.md 的机械结构校验。任务是否拆分合理、顺序是否符合真实依赖仍由
+ * Critic/Architect 判断；这里仅拒绝引擎无法可靠驱动的格式。
+ */
+export function validateTasksDocument(content) {
+    const errors = [];
+    if (!/^#\s+Tasks\s*$/m.test(content))
+        errors.push("tasks.md 缺少顶级 # Tasks 标题");
+    const tasks = parseTasksMd(content);
+    const seen = new Set();
+    for (const task of tasks) {
+        if (seen.has(task.taskId))
+            errors.push(`tasks.md task ID 重复：${task.taskId}`);
+        seen.add(task.taskId);
+    }
+    for (const [index, line] of content.split("\n").entries()) {
+        if (/^\s+-\s+\[[ xX]\]\s+/.test(line)) {
+            errors.push(`tasks.md 第 ${index + 1} 行存在缩进 checkbox；只有顶格 checkbox 可以作为可执行 task`);
+        }
+    }
+    return errors;
+}
 function isTopLevelTaskLine(line) {
     return TASK_LINE_RE.test(line);
 }
@@ -197,7 +227,7 @@ function emptyContract() {
         tests: [],
         design: null,
         source: [],
-        reason: null,
+        acceptance: null,
         guard: null,
     };
 }
@@ -224,7 +254,7 @@ function parseExecutionRequirementBlock(lines, task, headerIdx) {
         if (/^\s*-\s+\[[ xX]\]/.test(line)) {
             errors.push(`${task.taskId} 的执行依据内不能包含复选框`);
         }
-        const fieldMatch = line.match(/^\s*-\s*(测试|Tests|设计|Design|来源|Source|原因|Reason|边界|Guard)\s*[:：]\s*(.*)$/);
+        const fieldMatch = line.match(/^\s*-\s*(测试|Tests|设计|Design|来源|Source|验收|Acceptance|原因|Reason|边界|Guard)\s*[:：]\s*(.*)$/);
         if (fieldMatch) {
             const key = CONTRACT_FIELD_ALIASES[fieldMatch[1]];
             const value = fieldMatch[2].trim();
@@ -247,7 +277,7 @@ function parseExecutionRequirementBlock(lines, task, headerIdx) {
         }
         index += 1;
     }
-    return { taskId: task.taskId, lineIdx: task.lineIdx, contract, errors };
+    return { taskId: task.taskId, lineIdx: task.lineIdx, contract, declaredFields: [...seen], errors };
 }
 export function hasTaskBoundExecutionRequirements(content) {
     const lines = content.split("\n");
@@ -325,15 +355,23 @@ export function parseTestContractEntries(content) {
             if (row.length === 0)
                 break;
             const testId = (row[testIdIdx] ?? "").trim();
-            if (!testId.startsWith("TEST-"))
-                continue;
+            const scenario = (row[scenarioIdx] ?? "").trim();
+            if (!testId) {
+                return { ok: false, entries: [], message: `test-contract.md 第 ${rowIndex + 1} 行缺少 test_id` };
+            }
+            if (!/^TEST-[A-Za-z0-9_-]+$/.test(testId)) {
+                return { ok: false, entries: [], message: `test-contract.md 中 TEST ID 格式无效：${testId}` };
+            }
             if (seen.has(testId)) {
                 return { ok: false, entries: [], message: `test-contract.md 中 TEST ID 重复：${testId}` };
             }
+            if (!scenario) {
+                return { ok: false, entries: [], message: `test-contract.md 中 ${testId} 缺少 scenario` };
+            }
             seen.add(testId);
             entries.push({
                 test_id: testId,
-                scenario: (row[scenarioIdx] ?? "").trim(),
+                scenario,
             });
         }
     }
@@ -343,28 +381,180 @@ export function parseTestContractEntries(content) {
         return { ok: false, entries: [], message: "test-contract.md 没有 TEST-* 行" };
     return { ok: true, entries };
 }
-export function validateExecutionRequirements(content, testContractContent) {
-    const mode = hasTaskBoundExecutionRequirements(content);
+/** OpenSpec 项目的 proposal 采用固定 Impact 表格，供状态机进行纯结构校验。 */
+export function validateProposalImpact(content) {
+    const body = sectionBodyByHeadings(content, ["Impact"]);
+    if (body == null)
+        return { ok: false, message: "proposal.md 缺少 ## Impact" };
+    const tableLines = body.split("\n").filter(line => line.trim().startsWith("|"));
+    if (tableLines.length < 3 || !isMarkdownTableSeparator(tableLines[1])) {
+        return { ok: false, message: "proposal.md 的 Impact 必须包含 Area / Reason 表格" };
+    }
+    const header = splitMarkdownTableRow(tableLines[0]).map(cell => cell.toLowerCase());
+    const areaIdx = header.indexOf("area");
+    const reasonIdx = header.indexOf("reason");
+    if (areaIdx < 0 || reasonIdx < 0) {
+        return { ok: false, message: "proposal.md 的 Impact 表格缺少 Area 或 Reason 列" };
+    }
+    const rows = tableLines.slice(2).map(splitMarkdownTableRow).filter(cells => cells.length > 0);
+    if (rows.length === 0)
+        return { ok: false, message: "proposal.md 的 Impact 表格至少需要一行" };
+    for (const [index, row] of rows.entries()) {
+        if (!row[areaIdx]?.trim() || !row[reasonIdx]?.trim()) {
+            return { ok: false, message: `proposal.md 的 Impact 第 ${index + 1} 行缺少 Area 或 Reason` };
+        }
+    }
+    return { ok: true, message: "proposal.md Impact 结构有效" };
+}
+function isQualifiedDocumentRef(value) {
+    const ref = value.trim();
+    return /^(?!\/)(?!.*(?:^|\/)\.\.(?:\/|$))[^\s#]+\.md#[^\s].*$/.test(ref);
+}
+function executionRequirementReferenceErrors(contract) {
+    const errors = [];
+    if (contract.contract.design && !isQualifiedDocumentRef(contract.contract.design)) {
+        errors.push(`${contract.taskId} 的设计必须使用 文件.md#标题 的可定位引用`);
+    }
+    for (const source of contract.contract.source) {
+        if (!isQualifiedDocumentRef(source)) {
+            errors.push(`${contract.taskId} 的来源必须使用 文件.md#标题 的可定位引用：${source}`);
+        }
+    }
+    return errors;
+}
+function parseQualifiedDocumentRef(value) {
+    const ref = value.trim();
+    const separator = ref.indexOf("#");
+    if (separator <= 0 || separator === ref.length - 1)
+        return null;
+    return { path: ref.slice(0, separator), anchor: ref.slice(separator + 1).trim() };
+}
+function isPathInside(root, target) {
+    const rel = relative(root, target);
+    return rel !== "" && !rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel);
+}
+function documentContainsAnchor(content, anchor) {
+    if (/^(?:TEST|CHAIN|IDC)-[A-Za-z0-9_-]+$/.test(anchor)) {
+        const token = new RegExp(`(?:^|[^A-Za-z0-9_-])${escapeRegex(anchor)}(?![A-Za-z0-9_-])`);
+        return token.test(content);
+    }
+    // 支持 Markdown ATX 标题可选的 closing sequence（`## Route ##`），但正文
+    // 中同名文字仍不能冒充可定位锚点。
+    const heading = new RegExp(`^#{1,6}[\\t ]+${escapeRegex(anchor)}(?:[\\t ]+#+)?[\\t ]*$`, "m");
+    return heading.test(content);
+}
+function documentAnchorParts(anchor) {
+    const parts = anchor.split(",").map(part => part.trim()).filter(Boolean);
+    return parts.length > 1 && parts.every(part => /^(?:TEST|CHAIN|IDC)-[A-Za-z0-9_-]+$/.test(part))
+        ? parts
+        : [anchor];
+}
+function canonicalDocumentRefPath(path) {
+    if (path === "discovery.md" || path === "test-contract.md") {
+        return join(".superspec", "artifacts", path);
+    }
+    return path;
+}
+/**
+ * 在已初始化的当前工作流中，把执行依据的文件/锚点可解析性作为状态机协议。
+ * “该材料是否足以支撑 task”仍然是 Critic/Architect 的语义判断。
+ */
+export function validateExecutionRequirementDocumentReferences(changeRoot, contracts) {
+    const root = resolve(changeRoot);
+    const realRoot = realpathSync(root);
+    const errors = [];
+    for (const contract of contracts) {
+        const refs = [contract.contract.design, ...contract.contract.source].filter((value) => Boolean(value));
+        for (const ref of refs) {
+            const parsed = parseQualifiedDocumentRef(ref);
+            if (!parsed)
+                continue; // 语法错误由 executionRequirementReferenceErrors 报告。
+            const target = resolve(root, canonicalDocumentRefPath(parsed.path));
+            if (!isPathInside(root, target)) {
+                errors.push(`${contract.taskId} 的引用越出 change 目录：${ref}`);
+                continue;
+            }
+            if (!existsSync(target)) {
+                errors.push(`${contract.taskId} 的引用文件不存在：${parsed.path}`);
+                continue;
+            }
+            // resolve/relative 只能识别字面 `..`，不能阻止 change 内的符号链接指向
+            // 外部文件；按真实路径再次校验，确保引用材料仍属于当前 change。
+            let realTarget;
+            try {
+                realTarget = realpathSync(target);
+            }
+            catch {
+                errors.push(`${contract.taskId} 的引用文件无法解析：${parsed.path}`);
+                continue;
+            }
+            if (!isPathInside(realRoot, realTarget)) {
+                errors.push(`${contract.taskId} 的引用越出 change 目录：${ref}`);
+                continue;
+            }
+            const targetContent = readFileSync(target, "utf8");
+            for (const anchor of documentAnchorParts(parsed.anchor)) {
+                if (!documentContainsAnchor(targetContent, anchor)) {
+                    errors.push(`${contract.taskId} 的引用锚点不存在：${parsed.path}#${anchor}`);
+                }
+            }
+        }
+    }
+    return errors;
+}
+export function validateExecutionRequirements(content, testContractContent, executionPolicy = "tdd", executionRequirementVersion = 2) {
+    const tasks = parseTasksMd(content);
+    // 历史 green-only task 在旧版本中用标记强制进入契约模式。保留该入口，
+    // 防止已生成但尚未执行的 change 在升级后静默退回无验证的 legacy 模式；
+    // 新 Propose 不再产生此标记。
+    const hasLegacyGreenOnlyTask = tasks.some(task => task.noTddReason === GREEN_ONLY_NO_TDD_REASON);
+    // v2 不允许“所有任务都没有执行依据”这一静默回退：新 Propose 的每个普通
+    // task 都必须显式声明五字段。v1 的缺失版本仍保留旧的按需契约语义。
+    const hasV2OrdinaryTask = executionRequirementVersion === 2 && tasks.some(task => !isReviewFixTaskId(task.taskId));
+    const mode = hasTaskBoundExecutionRequirements(content) || hasLegacyGreenOnlyTask || hasV2OrdinaryTask;
     const contracts = parseExecutionRequirements(content);
     // 孤儿检测必须在 mode=false 的 early return 之前：全部块都悬空时 mode=false，
     // 恰恰是最需要报错的场景（否则契约模式静默失效）
     const errors = [...orphanExecutionRequirementErrors(content), ...contracts.flatMap(item => item.errors)];
     if (!mode)
         return { ok: errors.length === 0, mode, contracts, errors };
-    const tasks = parseTasksMd(content);
     const contractsByTask = new Map(contracts.map(item => [item.taskId, item]));
     const declaredTestIds = new Set();
     let needsTestContract = false;
     for (const task of tasks) {
         const contract = contractsByTask.get(task.taskId);
-        if (task.tddRequired && !isReviewFixTaskId(task.taskId)) {
-            if (!contract) {
-                errors.push(`${task.taskId} 缺少执行依据`);
-                continue;
-            }
-            if (contract.contract.tests.length === 0) {
-                errors.push(`${task.taskId} 是普通 TDD 任务，执行依据缺少测试`);
-            }
+        const legacyGreenOnly = task.noTddReason === GREEN_ONLY_NO_TDD_REASON;
+        if (legacyGreenOnly && task.tddRequired) {
+            errors.push(`${task.taskId} 的 no_tdd_reason=${GREEN_ONLY_NO_TDD_REASON} 必须同时声明 tdd_required:false`);
+        }
+        if (legacyGreenOnly && executionPolicy !== "green_only") {
+            errors.push(`${task.taskId} 的 no_tdd_reason=${GREEN_ONLY_NO_TDD_REASON} 只允许用于 GREEN-only apply`);
+        }
+        // v2 是本次改造后的新计划：每个普通 task 必须声明完整五字段，
+        // `测试:` 可显式为空以表达非行为任务。旧计划只保持原 TDD 契约要求。
+        if (executionRequirementVersion === 2 && !isReviewFixTaskId(task.taskId) && !contract) {
+            errors.push(`${task.taskId} 缺少执行依据`);
+            continue;
+        }
+        if (executionRequirementVersion === 1 && task.tddRequired && !isReviewFixTaskId(task.taskId) && !contract) {
+            errors.push(`${task.taskId} 缺少执行依据`);
+            continue;
+        }
+        if (contract && executionRequirementVersion === 2) {
+            if (!contract.declaredFields.includes("tests"))
+                errors.push(`${task.taskId} 的执行依据缺少测试字段`);
+            if (!contract.contract.design)
+                errors.push(`${task.taskId} 的执行依据缺少设计`);
+            if (contract.contract.source.length === 0)
+                errors.push(`${task.taskId} 的执行依据缺少来源`);
+            if (!contract.contract.acceptance)
+                errors.push(`${task.taskId} 的执行依据缺少验收目标`);
+            if (!contract.contract.guard)
+                errors.push(`${task.taskId} 的执行依据缺少边界`);
+            errors.push(...executionRequirementReferenceErrors(contract));
+        }
+        if (contract && (executionRequirementVersion === 1 && task.tddRequired || legacyGreenOnly) && contract.contract.tests.length === 0) {
+            errors.push(`${task.taskId} 的执行依据缺少测试`);
         }
         if (contract && contract.contract.tests.length > 0) {
             needsTestContract = true;
@@ -450,11 +640,12 @@ export function validateUserDecision(d) {
 }
 // ===== test-contract.md =====
 //
-// 格式（propose skill 定义）：
+// 格式（状态机校验，propose skill 负责生成）：
 //   # Test Contract
 //   | test_id | scenario |
 //   |---|---|
 //   | TEST-001 | 注册时密码被加密 |
 //
-// 引擎行为：Phase 1-5 只校验文件存在性（轻量）。
-// 表格结构是 agent 指引，引擎不逐行解析。
+// 引擎行为：当 task 声明 TEST 时，状态机解析表格、TEST ID 和 scenario，
+// 并在 propose-ready / start-apply 阶段拒绝无效引用；测试语义和证明力仍由
+// Test Engineer 判断。

package/dist/git_state.d.ts

@@ -1,8 +1,13 @@
-import type { DirtyFileFingerprint } from "./types.ts";
+import type { BoundarySnapshot, DirtyFileFingerprint } from "./types.ts";
 export interface GitHeadResult {
     head: string | null;
     reason: string;
 }
+export interface JavaAutoStageResult {
+    status: "staged" | "skipped" | "failed";
+    files: string[];
+    reason?: string;
+}
 export declare function currentGitHead(projectRoot: string): GitHeadResult;
 export declare function normalizeGitPath(rawPath: string): string;
 export declare function gitLines(projectRoot: string, args: string[]): {
@@ -33,4 +38,10 @@ export declare function dirtyCodePaths(projectRoot: string): {
     paths: string[];
     reason: string;
 };
+/**
+ * 仅暂存当前 task 启动后新生成的生产 Java 文件。
+ * 不能安全归因的既有文件改动绝不自动 git add：它们可能包含用户或并行任务的未提交内容。
+ * 测试源码和常见测试类命名会被排除；没有可用的启动边界或 Git 状态异常时，不影响任务完成。
+ */
+export declare function stageProductionJavaFilesSince(projectRoot: string, before: BoundarySnapshot | null): JavaAutoStageResult;
 export declare function projectHasReadableDirectory(projectRoot: string): boolean;

package/dist/git_state.js

@@ -169,6 +169,51 @@ export function dirtyCodePaths(projectRoot) {
         return { ok: false, paths: [], reason: dirty.reason };
     return { ok: true, paths: [...new Set(dirty.files.map(file => file.path))].sort() };
 }
+function isJavaTestPath(path) {
+    const normalized = path.replace(/\\/g, "/");
+    const base = normalized.split("/").pop() ?? normalized;
+    return /(^|\/)src\/test\//i.test(normalized) ||
+        /(?:Test|Tests|TestCase|IT|ITCase)\.java$/i.test(base);
+}
+/**
+ * 仅暂存当前 task 启动后新生成的生产 Java 文件。
+ * 不能安全归因的既有文件改动绝不自动 git add：它们可能包含用户或并行任务的未提交内容。
+ * 测试源码和常见测试类命名会被排除；没有可用的启动边界或 Git 状态异常时，不影响任务完成。
+ */
+export function stageProductionJavaFilesSince(projectRoot, before) {
+    if (!before) {
+        return { status: "skipped", files: [], reason: "missing_task_start_boundary" };
+    }
+    const current = dirtyCodeFiles(projectRoot);
+    if (!current.ok) {
+        return { status: "failed", files: [], reason: current.reason };
+    }
+    const currentByPath = new Map(current.files.map(file => [file.path, file]));
+    const beforeByPath = new Map(before.dirty_files.map(file => [file.path, file]));
+    const files = diffFingerprints(before.dirty_files, current.files)
+        .filter(path => path.toLowerCase().endsWith(".java"))
+        .filter(path => !isJavaTestPath(path))
+        // "added" 且 task-start 边界不存在，才是可归因于本任务的新生成文件。
+        // 已有未跟踪文件或已有源码的任何修改一律不碰，避免把用户工作带入 index。
+        .filter(path => !beforeByPath.has(path) && currentByPath.get(path)?.status === "added")
+        .filter(path => currentByPath.get(path)?.status !== "deleted")
+        .sort();
+    if (files.length === 0)
+        return { status: "skipped", files: [], reason: "no_changed_production_java" };
+    try {
+        execFileSync("git", ["-C", projectRoot, "add", "--", ...files], {
+            stdio: ["ignore", "ignore", "pipe"],
+        });
+        return { status: "staged", files };
+    }
+    catch (err) {
+        return {
+            status: "failed",
+            files,
+            reason: err instanceof Error ? err.message : "git add failed",
+        };
+    }
+}
 export function projectHasReadableDirectory(projectRoot) {
     return existsSync(projectRoot) && statSync(projectRoot).isDirectory();
 }

package/dist/install.d.ts

@@ -10,6 +10,7 @@ export interface InstallResult {
         prompts: string[];
         agents: string[];
         config: string;
+        workflow_config: string;
         agents_md: string;
         openspec_config: string;
     };