@peterxiaoyang/superspec 0.1.38 → 0.1.39

package/dist/format.js

@@ -16,23 +16,90 @@ function escapeRegex(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 function countOpenChecklistItemsInSection(content, headings) {
+    const sectionBody = sectionBodyByHeadings(content, headings);
+    if (sectionBody == null)
+        return 0;
+    // 数未确认项
+    const matches = sectionBody.match(/^\s*-\s+\[ \]/gm);
+    return matches ? matches.length : 0;
+}
+function sectionBodyByHeadings(content, headings) {
     const headingPattern = headings.map(escapeRegex).join("|");
     const sectionMatch = new RegExp(`^#{1,6}\\s*(?:${headingPattern})\\s*$`, "im").exec(content);
     if (!sectionMatch)
-        return 0;
+        return null;
     const sectionStart = sectionMatch.index + sectionMatch[0].length;
     // 截取到下一个标题或文件末尾
     const restContent = content.slice(sectionStart);
     const nextHeadingMatch = restContent.match(/^#{1,6}\s+/m);
-    const sectionBody = nextHeadingMatch ? restContent.slice(0, nextHeadingMatch.index) : restContent;
-    // 数未确认项
-    const matches = sectionBody.match(/^\s*-\s+\[ \]/gm);
-    return matches ? matches.length : 0;
+    return nextHeadingMatch ? restContent.slice(0, nextHeadingMatch.index) : restContent;
 }
 /** 从 discovery.md 提取"待确认问题"段内的未确认项数量 */
 export function countDiscoveryOpenQuestions(content) {
     return countOpenChecklistItemsInSection(content, ["待确认问题", "Open Questions", "Pending Questions"]);
 }
+const DISCOVERY_CHAIN_HEADINGS = ["链路五要素"];
+const DISCOVERY_CHAIN_REQUIRED_COLUMNS = [
+    "ID",
+    "发现方式",
+    "上游来源",
+    "规则变形",
+    "持久化语义",
+    "下游消费者",
+    "视图差异",
+    "未知/排除",
+    "证据",
+    "状态",
+];
+export function splitMarkdownTableRow(line) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("|") || !trimmed.endsWith("|"))
+        return [];
+    // GFM 表格中字面竖线写作 \|，按未转义竖线切分后还原
+    return trimmed.slice(1, -1).split(/(?<!\\)\|/).map(cell => cell.trim().replace(/\\\|/g, "|"));
+}
+function isMarkdownTableSeparator(line) {
+    return /^\s*\|?\s*:?-{3,}:?\s*(?:\|\s*:?-{3,}:?\s*)+\|?\s*$/.test(line);
+}
+/** 轻量校验 discovery.md 的链路五要素段。只校验结构和阻塞未知，不判断业务真假。 */
+export function validateDiscoveryChainCoverage(content) {
+    const sectionBody = sectionBodyByHeadings(content, DISCOVERY_CHAIN_HEADINGS);
+    if (sectionBody == null) {
+        // 兼容缺少链路五要素段的历史 discovery：不阻塞，实质要求由 critic 审查
+        return { ok: true, message: "discovery.md 未声明链路五要素", present: false };
+    }
+    const tableLines = sectionBody.split("\n").filter(line => line.trim().startsWith("|"));
+    if (tableLines.length < 2) {
+        return { ok: false, message: "链路五要素缺少 Markdown 表格", present: true };
+    }
+    const header = splitMarkdownTableRow(tableLines[0]);
+    if (header.length === 0 || !isMarkdownTableSeparator(tableLines[1])) {
+        return { ok: false, message: "链路五要素表格格式无效", present: true };
+    }
+    const missingColumns = DISCOVERY_CHAIN_REQUIRED_COLUMNS.filter(col => !header.includes(col));
+    if (missingColumns.length > 0) {
+        return { ok: false, message: `链路五要素缺少必需列：${missingColumns.join(", ")}`, present: true };
+    }
+    const rows = tableLines.slice(2).map(splitMarkdownTableRow).filter(cells => cells.length > 0);
+    if (rows.length === 0) {
+        return { ok: false, message: "链路五要素至少需要一行链路记录", present: true };
+    }
+    const statusIdx = header.indexOf("状态");
+    const requiredColumnIndexes = DISCOVERY_CHAIN_REQUIRED_COLUMNS.map(col => ({ col, idx: header.indexOf(col) }));
+    for (const [idx, cells] of rows.entries()) {
+        const rowNum = idx + 1;
+        for (const { col, idx: colIdx } of requiredColumnIndexes) {
+            if (!(cells[colIdx]?.trim())) {
+                return { ok: false, message: `链路五要素第 ${rowNum} 行缺少${col}`, present: true };
+            }
+        }
+        const status = cells[statusIdx]?.trim() ?? "";
+        if (status.includes("未知阻塞") && countDiscoveryOpenQuestions(content) === 0) {
+            return { ok: false, message: "链路五要素存在未知阻塞，但待确认问题中没有未解决项", present: true };
+        }
+    }
+    return { ok: true, message: "链路五要素就绪", present: true };
+}
 /** 完整校验 discovery.md：存在 + 非空 + 无未确认问题 */
 export function validateDiscovery(changeRoot) {
     const path = join(changeRoot, ".superspec", "artifacts", "discovery.md");
@@ -41,6 +108,9 @@ export function validateDiscovery(changeRoot) {
     const content = readFileSync(path, "utf8");
     if (!content.trim())
         return { ok: false, message: "discovery.md 为空", openCount: -1 };
+    const chainCoverage = validateDiscoveryChainCoverage(content);
+    if (!chainCoverage.ok)
+        return { ok: false, message: chainCoverage.message, openCount: -1 };
     const openCount = countDiscoveryOpenQuestions(content);
     if (openCount > 0)
         return { ok: false, message: `discovery.md 有 ${openCount} 个未确认问题`, openCount };
@@ -71,6 +141,21 @@ export function collectProposeOpenQuestions(changeRoot) {
     };
 }
 const TASK_LINE_RE = /^(- \[([ xX])\])\s+(\S+)/;
+// 块头独占一行（允许全角/半角冒号）；PREFIX 变体用于识别"块头带尾部内容/误加 bullet"的格式错误
+const EXECUTION_REQUIREMENT_LINE_RE = /^\s*执行依据[:：]\s*$/;
+const EXECUTION_REQUIREMENT_PREFIX_RE = /^\s*-?\s*执行依据[:：]/;
+const CONTRACT_FIELD_ALIASES = {
+    "测试": "tests",
+    "Tests": "tests",
+    "设计": "design",
+    "Design": "design",
+    "来源": "source",
+    "Source": "source",
+    "原因": "reason",
+    "Reason": "reason",
+    "边界": "guard",
+    "Guard": "guard",
+};
 /** 解析 tasks.md 的全部任务行 */
 export function parseTasksMd(content) {
     const lines = content.split("\n");
@@ -94,6 +179,221 @@ export function parseTasksMd(content) {
     }
     return tasks;
 }
+function isTopLevelTaskLine(line) {
+    return TASK_LINE_RE.test(line);
+}
+function splitSourceRefs(value) {
+    return value
+        .split(/[；;]/)
+        .map(item => item.trim())
+        .filter(Boolean);
+}
+function parseTestIds(value) {
+    const ids = value.match(/\bTEST-[A-Za-z0-9_-]+\b/g) ?? [];
+    return { ids: [...new Set(ids)].sort(), ok: ids.length > 0 || value.trim() === "" };
+}
+function emptyContract() {
+    return {
+        tests: [],
+        design: null,
+        source: [],
+        reason: null,
+        guard: null,
+    };
+}
+// 共享绑定判定：mode 判定与块解析都走这里，避免两处条件分裂。
+// 从 task 行往下最多跳过 1 个纯空行（AI 生成时的常见格式波动，意图无歧义，直接接受）；
+// 间隔更多空行或夹了其他内容的块不绑定，由孤儿检测报错。
+function executionRequirementHeaderIdx(lines, task) {
+    let index = task.lineIdx + 1;
+    if (index < lines.length && lines[index].trim() === "")
+        index += 1;
+    if (index < lines.length && EXECUTION_REQUIREMENT_LINE_RE.test(lines[index]))
+        return index;
+    return null;
+}
+function parseExecutionRequirementBlock(lines, task, headerIdx) {
+    const contract = emptyContract();
+    const errors = [];
+    const seen = new Set();
+    let index = headerIdx + 1;
+    while (index < lines.length) {
+        const line = lines[index];
+        if (isTopLevelTaskLine(line) || /^#{1,6}\s+/.test(line))
+            break;
+        if (/^\s*-\s+\[[ xX]\]/.test(line)) {
+            errors.push(`${task.taskId} 的执行依据内不能包含复选框`);
+        }
+        const fieldMatch = line.match(/^\s*-\s*(测试|Tests|设计|Design|来源|Source|原因|Reason|边界|Guard)\s*[:：]\s*(.*)$/);
+        if (fieldMatch) {
+            const key = CONTRACT_FIELD_ALIASES[fieldMatch[1]];
+            const value = fieldMatch[2].trim();
+            if (seen.has(key)) {
+                errors.push(`${task.taskId} 的执行依据字段重复：${fieldMatch[1]}`);
+            }
+            seen.add(key);
+            if (key === "tests") {
+                const parsed = parseTestIds(value);
+                if (!parsed.ok)
+                    errors.push(`${task.taskId} 的测试字段没有可解析的 TEST ID`);
+                contract.tests = parsed.ids;
+            }
+            else if (key === "source") {
+                contract.source = splitSourceRefs(value);
+            }
+            else {
+                contract[key] = value || null;
+            }
+        }
+        index += 1;
+    }
+    return { taskId: task.taskId, lineIdx: task.lineIdx, contract, errors };
+}
+export function hasTaskBoundExecutionRequirements(content) {
+    const lines = content.split("\n");
+    return parseTasksMd(content).some(task => executionRequirementHeaderIdx(lines, task) != null);
+}
+export function parseExecutionRequirements(content) {
+    const lines = content.split("\n");
+    const parsed = [];
+    for (const task of parseTasksMd(content)) {
+        const headerIdx = executionRequirementHeaderIdx(lines, task);
+        if (headerIdx != null)
+            parsed.push(parseExecutionRequirementBlock(lines, task, headerIdx));
+    }
+    return parsed;
+}
+// 孤儿执行依据检测：块头存在但没有绑定到任何 task（间隔过多空行、夹了其他内容、
+// 或块头带尾部文字导致整行不匹配）。这些块会被引擎静默忽略，必须显式报错阻断，
+// 否则全部悬空时契约模式静默失效（使用者是 AI，报错消息要给出可直接执行的修复动作）。
+export function orphanExecutionRequirementErrors(content) {
+    const lines = content.split("\n");
+    const boundHeaderIdx = new Set();
+    for (const task of parseTasksMd(content)) {
+        const headerIdx = executionRequirementHeaderIdx(lines, task);
+        if (headerIdx != null)
+            boundHeaderIdx.add(headerIdx);
+    }
+    const errors = [];
+    for (let i = 0; i < lines.length; i++) {
+        if (boundHeaderIdx.has(i))
+            continue;
+        if (EXECUTION_REQUIREMENT_LINE_RE.test(lines[i])) {
+            errors.push(`第 ${i + 1} 行的"执行依据:"没有绑定到任何 task（块头与 task 行之间最多允许一个空行），该块不会生效；请把它紧贴到所属 task 行下方`);
+        }
+        else if (EXECUTION_REQUIREMENT_PREFIX_RE.test(lines[i])) {
+            errors.push(`第 ${i + 1} 行的"执行依据:"块头格式无法识别；块头必须独占一行（不带 bullet、冒号后不带内容），字段写在下方的 bullet 行`);
+        }
+    }
+    return errors;
+}
+export function executionRequirementForTask(content, taskId) {
+    return parseExecutionRequirements(content).find(item => item.taskId === taskId) ?? null;
+}
+// 契约"解析"与"采纳"的统一出口：contract 非 null 当且仅当本轮是契约模式且该 task 有绑定块。
+// 消费方（attempt/details/packet）一律从这里取值，禁止各自组合 parsed 与 mode——
+// 否则 legacy 轮会输出"看似契约、实按 legacy 校验"的误导态。
+export function adoptedContractForTask(content, taskId, contractMode) {
+    const parsed = executionRequirementForTask(content, taskId);
+    return { parsed, contract: contractMode ? parsed?.contract ?? null : null };
+}
+export function isReviewFixTaskId(taskId) {
+    return taskId.startsWith("REVIEW-FIX-");
+}
+export function isCharacterizationTask(task) {
+    return task.tddRequired === false && task.noTddReason === "characterization";
+}
+export function parseTestContractEntries(content) {
+    const lines = content.split("\n");
+    const entries = [];
+    const seen = new Set();
+    let sawMatchingHeader = false;
+    for (let i = 0; i < lines.length - 1; i++) {
+        const header = splitMarkdownTableRow(lines[i]);
+        if (header.length === 0)
+            continue;
+        const normalizedHeader = header.map(cell => cell.trim().toLowerCase());
+        const testIdIdx = normalizedHeader.indexOf("test_id");
+        const scenarioIdx = normalizedHeader.indexOf("scenario");
+        if (testIdIdx < 0 || scenarioIdx < 0)
+            continue;
+        if (!isMarkdownTableSeparator(lines[i + 1]))
+            continue;
+        sawMatchingHeader = true;
+        const invariantIdx = normalizedHeader.indexOf("invariant");
+        for (let rowIndex = i + 2; rowIndex < lines.length; rowIndex++) {
+            const row = splitMarkdownTableRow(lines[rowIndex]);
+            if (row.length === 0)
+                break;
+            const testId = (row[testIdIdx] ?? "").trim();
+            if (!testId.startsWith("TEST-"))
+                continue;
+            if (seen.has(testId)) {
+                return { ok: false, entries: [], message: `test-contract.md 中 TEST ID 重复：${testId}` };
+            }
+            seen.add(testId);
+            entries.push({
+                test_id: testId,
+                scenario: (row[scenarioIdx] ?? "").trim(),
+                invariant: invariantIdx >= 0 ? (row[invariantIdx] ?? "").trim() : "",
+            });
+        }
+    }
+    if (!sawMatchingHeader)
+        return { ok: false, entries: [], message: "test-contract.md 缺少包含测试 ID（test_id）和场景（scenario）的表格" };
+    if (entries.length === 0)
+        return { ok: false, entries: [], message: "test-contract.md 没有 TEST-* 行" };
+    return { ok: true, entries };
+}
+export function validateExecutionRequirements(content, testContractContent) {
+    const mode = hasTaskBoundExecutionRequirements(content);
+    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 任务，执行依据缺少测试`);
+            }
+        }
+        if (contract && contract.contract.tests.length > 0) {
+            needsTestContract = true;
+            for (const testId of contract.contract.tests)
+                declaredTestIds.add(testId);
+        }
+    }
+    if (needsTestContract) {
+        if (testContractContent == null) {
+            errors.push("test-contract.md 不存在，无法校验执行依据测试引用");
+        }
+        else {
+            const parsed = parseTestContractEntries(testContractContent);
+            if (!parsed.ok) {
+                errors.push(parsed.message);
+            }
+            else {
+                const known = new Set(parsed.entries.map(entry => entry.test_id));
+                for (const testId of declaredTestIds) {
+                    if (!known.has(testId))
+                        errors.push(`执行依据引用了不存在的 TEST ID：${testId}`);
+                }
+            }
+        }
+    }
+    return { ok: errors.length === 0, mode, contracts, errors };
+}
 /** 返回未完成任务 */
 export function pendingTasksInContent(content) {
     return parseTasksMd(content).filter(task => !task.done);
@@ -116,7 +416,7 @@ export function findTaskInLines(lines, taskId) {
 export function tasksStructureDigest(content, sha256Text) {
     return sha256Text(content.replace(/- \[[xX]\]/g, "- [ ]"));
 }
-// ===== test-run JSON =====
+// ===== 测试运行 JSON =====
 //
 // 格式（apply skill 定义）：
 //   {
@@ -131,23 +431,8 @@ export function tasksStructureDigest(content, sha256Text) {
 //     "target_fingerprint": "sha256:..."
 //   }
 //
-// 引擎校验：test_id + task_structure_digest 必填，covers_task_ids 如存在必须是非空字符串数组，其余可选
-export function validateTestRunInput(tr) {
-    if (!tr.test_id)
-        return { ok: false, message: "缺少 test_id" };
-    if (!tr.task_structure_digest)
-        return { ok: false, message: "缺少 task_structure_digest" };
-    if (tr.covers_task_ids !== undefined) {
-        if (!Array.isArray(tr.covers_task_ids))
-            return { ok: false, message: "covers_task_ids 必须是字符串数组" };
-        if (tr.covers_task_ids.length === 0)
-            return { ok: false, message: "covers_task_ids 不能是空数组" };
-        if (!tr.covers_task_ids.every(item => typeof item === "string" && item.trim().length > 0)) {
-            return { ok: false, message: "covers_task_ids 不能包含空字符串或非字符串" };
-        }
-    }
-    return { ok: true, message: "" };
-}
+// 引擎校验：测试 ID（test_id）+ 任务结构指纹（task_structure_digest）必填，回归覆盖任务列表（covers_task_ids）如存在必须是非空字符串数组，其余可选
+//（实际校验内联在 task.ts recordTestRunLoaded：契约模式走 validateContractTestRunInput，legacy 模式内联必填校验）
 // ===== user-decision JSON =====
 //
 // 格式（explore skill 定义）：
@@ -157,12 +442,12 @@ export function validateTestRunInput(tr) {
 //     "answer": "yes"
 //   }
 //
-// 引擎校验：scope + answer 必填
+// 引擎校验：决策范围（scope）+ 答复内容（answer）必填
 export function validateUserDecision(d) {
     if (!d.scope)
-        return { ok: false, message: "决策文件缺少 scope" };
+        return { ok: false, message: "决策文件缺少决策范围（scope）" };
     if (!d.answer)
-        return { ok: false, message: "决策文件缺少 answer" };
+        return { ok: false, message: "决策文件缺少答复内容（answer）" };
     return { ok: true, message: "" };
 }
 // ===== business-invariants.md =====

package/dist/git_state.d.ts

@@ -0,0 +1,36 @@
+import type { DirtyFileFingerprint } from "./types.ts";
+export interface GitHeadResult {
+    head: string | null;
+    reason: string;
+}
+export declare function currentGitHead(projectRoot: string): GitHeadResult;
+export declare function normalizeGitPath(rawPath: string): string;
+export declare function gitLines(projectRoot: string, args: string[]): {
+    ok: true;
+    lines: string[];
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function isCodeLikePath(path: string): boolean;
+export declare function walkCodeFiles(root: string, dir?: string, out?: string[]): string[];
+export declare function codeFileContentSha(projectRoot: string, path: string): string | null;
+export declare function codeFileFingerprint(projectRoot: string, path: string, status: DirtyFileFingerprint["status"]): DirtyFileFingerprint;
+export declare function dirtyCodeFiles(projectRoot: string): {
+    ok: true;
+    files: DirtyFileFingerprint[];
+} | {
+    ok: false;
+    files: DirtyFileFingerprint[];
+    reason: string;
+};
+export declare function diffFingerprints(left: DirtyFileFingerprint[], right: DirtyFileFingerprint[]): string[];
+export declare function dirtyCodePaths(projectRoot: string): {
+    ok: true;
+    paths: string[];
+} | {
+    ok: false;
+    paths: string[];
+    reason: string;
+};
+export declare function projectHasReadableDirectory(projectRoot: string): boolean;

package/dist/git_state.js

@@ -0,0 +1,174 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, lstatSync, readdirSync, readlinkSync, statSync } from "node:fs";
+import { extname, join } from "node:path";
+import { sha256File, sha256Text } from "./store.js";
+const PROCESS_DOC_RE = /^(?:openspec\/changes\/[^/]+\/)?(?:proposal|design|tasks)\.md$/;
+const PROCESS_ARTIFACT_RE = /^(?:openspec\/changes\/[^/]+\/)?\.superspec\/artifacts\/(?:discovery|business-invariants|test-contract)\.md$/;
+const CODE_EXTENSIONS = new Set([
+    ".c", ".cc", ".cpp", ".cs", ".css", ".go", ".h", ".hpp", ".html", ".java", ".js", ".jsx",
+    ".json", ".kt", ".mjs", ".mts", ".php", ".py", ".rb", ".rs", ".scss", ".sh", ".sql",
+    ".swift", ".toml", ".ts", ".tsx", ".yaml", ".yml",
+]);
+const CODE_BASENAMES = new Set([
+    "Dockerfile", "Makefile", "package.json", "package-lock.json", "pnpm-lock.yaml", "yarn.lock",
+    "tsconfig.json", "tsconfig.build.json", "eslint.config.js", "vite.config.ts", "webpack.config.js",
+]);
+const WALK_SKIP_DIRS = new Set([".git", "node_modules", "dist", "build", ".superspec", ".omx"]);
+export function currentGitHead(projectRoot) {
+    try {
+        const head = execFileSync("git", ["-C", projectRoot, "rev-parse", "--verify", "HEAD"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        return { head: head || null, reason: head ? "ok" : "empty_head" };
+    }
+    catch (err) {
+        return {
+            head: null,
+            reason: err instanceof Error ? err.message : "git rev-parse failed",
+        };
+    }
+}
+export function normalizeGitPath(rawPath) {
+    const trimmed = rawPath.trim();
+    const unquoted = trimmed.startsWith('"') && trimmed.endsWith('"')
+        ? trimmed.slice(1, -1).replace(/\\"/g, '"')
+        : trimmed;
+    const renamed = unquoted.includes(" -> ") ? unquoted.split(" -> ").pop() ?? unquoted : unquoted;
+    return renamed.replace(/\\/g, "/");
+}
+export function gitLines(projectRoot, args) {
+    try {
+        const output = execFileSync("git", ["-C", projectRoot, ...args], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        return {
+            ok: true,
+            lines: output.split("\n").map(line => normalizeGitPath(line)).filter(Boolean),
+        };
+    }
+    catch (err) {
+        return { ok: false, reason: err instanceof Error ? err.message : "git command failed" };
+    }
+}
+function isProcessOrOrdinaryDoc(path) {
+    if (path.startsWith(".superspec/") || path.startsWith(".omx/"))
+        return true;
+    if (path.includes("/.superspec/") || path.includes("/.omx/"))
+        return true;
+    if (PROCESS_DOC_RE.test(path) || PROCESS_ARTIFACT_RE.test(path))
+        return true;
+    return extname(path).toLowerCase() === ".md";
+}
+export function isCodeLikePath(path) {
+    const normalized = path.replace(/\\/g, "/");
+    if (!normalized || isProcessOrOrdinaryDoc(normalized))
+        return false;
+    const base = normalized.split("/").pop() ?? normalized;
+    if (CODE_BASENAMES.has(base))
+        return true;
+    return CODE_EXTENSIONS.has(extname(base).toLowerCase());
+}
+export function walkCodeFiles(root, dir = root, out = []) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (entry.isDirectory()) {
+            if (WALK_SKIP_DIRS.has(entry.name))
+                continue;
+            walkCodeFiles(root, join(dir, entry.name), out);
+            continue;
+        }
+        if (!entry.isFile())
+            continue;
+        const full = join(dir, entry.name);
+        const rel = full.slice(root.length + 1).replace(/\\/g, "/");
+        if (isCodeLikePath(rel))
+            out.push(rel);
+    }
+    return out;
+}
+export function codeFileContentSha(projectRoot, path) {
+    try {
+        const full = join(projectRoot, path);
+        const stat = lstatSync(full);
+        if (stat.isSymbolicLink())
+            return sha256Text(readlinkSync(full));
+        return sha256File(full);
+    }
+    catch {
+        return null;
+    }
+}
+export function codeFileFingerprint(projectRoot, path, status) {
+    if (status === "deleted")
+        return { path, status, sha256: null };
+    return { path, status, sha256: codeFileContentSha(projectRoot, path) ?? "sha256:missing" };
+}
+function unquoteGitPath(path) {
+    return path.trim().replace(/^"|"$/g, "").replace(/\\"/g, '"').replace(/\\/g, "/");
+}
+export function dirtyCodeFiles(projectRoot) {
+    let output;
+    try {
+        output = execFileSync("git", ["-C", projectRoot, "status", "--porcelain", "--untracked-files=all"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+    }
+    catch (err) {
+        return {
+            ok: false,
+            files: [],
+            reason: err instanceof Error ? err.message : "git status failed",
+        };
+    }
+    const files = [];
+    for (const rawLine of output.split("\n")) {
+        if (!rawLine.trim())
+            continue;
+        const statusCode = rawLine.slice(0, 2);
+        const rawPath = rawLine.slice(3);
+        if (statusCode.includes("R") && rawPath.includes(" -> ")) {
+            const [oldRaw, newRaw] = rawPath.split(" -> ");
+            const oldPath = unquoteGitPath(oldRaw);
+            const newPath = unquoteGitPath(newRaw);
+            if (isCodeLikePath(oldPath))
+                files.push(codeFileFingerprint(projectRoot, oldPath, "deleted"));
+            if (isCodeLikePath(newPath))
+                files.push(codeFileFingerprint(projectRoot, newPath, "added"));
+            continue;
+        }
+        const normalizedPath = unquoteGitPath(rawPath);
+        if (!isCodeLikePath(normalizedPath))
+            continue;
+        const deleted = statusCode.includes("D");
+        const added = statusCode.includes("A") || statusCode === "??";
+        files.push(codeFileFingerprint(projectRoot, normalizedPath, deleted ? "deleted" : added ? "added" : "modified"));
+    }
+    files.sort((a, b) => a.path.localeCompare(b.path));
+    return { ok: true, files };
+}
+// 共享文件指纹原语：boundary_snapshot 与 code_state_check 的差异对比都走这里，
+// 语义统一为「path 相同且 status、sha256 都一致才算未变化」，结果按路径字典序稳定输出。
+export function diffFingerprints(left, right) {
+    const leftMap = new Map(left.map(file => [file.path, file]));
+    const rightMap = new Map(right.map(file => [file.path, file]));
+    const changed = [];
+    for (const path of new Set([...leftMap.keys(), ...rightMap.keys()])) {
+        const before = leftMap.get(path);
+        const after = rightMap.get(path);
+        if (!before || !after || before.status !== after.status || before.sha256 !== after.sha256) {
+            changed.push(path);
+        }
+    }
+    return changed.sort();
+}
+export function dirtyCodePaths(projectRoot) {
+    const dirty = dirtyCodeFiles(projectRoot);
+    if (!dirty.ok)
+        return { ok: false, paths: [], reason: dirty.reason };
+    return { ok: true, paths: [...new Set(dirty.files.map(file => file.path))].sort() };
+}
+export function projectHasReadableDirectory(projectRoot) {
+    return existsSync(projectRoot) && statSync(projectRoot).isDirectory();
+}

package/dist/job_validity.d.ts

@@ -10,6 +10,7 @@ export declare function invalidReasonForSnapshot(input: {
     job: Job;
     projectRoot: string;
     changeRoot: string;
+    events: Event[];
     currentReviewEvidenceDigest: string;
 }): string | null;
 export declare function invalidReasonForSubmittedReport(job: Job, context: SubmittedReportValidityContext): string | null;

package/dist/job_validity.js

@@ -1,5 +1,5 @@
 import { reviewEvidenceDigest, reviewVerifierStaleReason, } from "./review.js";
-import { codeReviewJobStaleReason, scanCodeChanges, } from "./code_review.js";
+import { codeReviewJobStaleReason, currentCodeReviewWorkingPaths, } from "./code_review.js";
 const MISSING_REVIEW_EVIDENCE_REASON = "最终验证工作项缺少执行证据版本";
 function reviewReadyVerifierWithoutEvidenceReason(job) {
     if (job.role === "verifier" &&
@@ -12,23 +12,26 @@ function reviewReadyVerifierWithoutEvidenceReason(job) {
 }
 export function invalidReasonForSnapshot(input) {
     if (input.job.role === "code-reviewer") {
-        return codeReviewJobStaleReason(input.projectRoot, input.job);
+        return codeReviewJobStaleReason(input.projectRoot, input.job, currentCodeReviewWorkingPaths(input.projectRoot, input.events));
     }
     const invalidReviewReadyVerifier = reviewReadyVerifierWithoutEvidenceReason(input.job);
     if (invalidReviewReadyVerifier)
         return invalidReviewReadyVerifier;
-    return reviewVerifierStaleReason(input.job, input.changeRoot, input.currentReviewEvidenceDigest);
+    return reviewVerifierStaleReason(input.job, input.changeRoot, input.currentReviewEvidenceDigest, input.projectRoot, input.events);
 }
 export function invalidReasonForSubmittedReport(job, context) {
     if (job.role === "code-reviewer") {
-        const ignored = new Set(context.ignoredCodePaths ?? []);
-        if (context.reportPath)
-            ignored.add(context.reportPath);
-        const currentPaths = scanCodeChanges(context.projectRoot).paths.filter(path => !ignored.has(path));
+        const currentPaths = currentCodeReviewWorkingPaths(context.projectRoot, context.events, [
+            ...(context.ignoredCodePaths ?? []),
+            ...(context.reportPath ? [context.reportPath] : []),
+        ]);
         return codeReviewJobStaleReason(context.projectRoot, job, currentPaths);
     }
     const invalidReviewReadyVerifier = reviewReadyVerifierWithoutEvidenceReason(job);
     if (invalidReviewReadyVerifier)
         return invalidReviewReadyVerifier;
-    return reviewVerifierStaleReason(job, context.changeRoot, reviewEvidenceDigest(context.events));
+    const ignored = new Set(context.ignoredCodePaths ?? []);
+    if (context.reportPath)
+        ignored.add(context.reportPath);
+    return reviewVerifierStaleReason(job, context.changeRoot, reviewEvidenceDigest(context.events), context.projectRoot, context.events, [...ignored]);
 }