@peterxiaoyang/superspec 0.1.38 → 0.1.40

package/dist/code_review.js

@@ -1,93 +1,22 @@
 // SuperSpec code-reviewer gate helpers.
-import { execFileSync } from "node:child_process";
-import { existsSync, readdirSync, statSync } from "node:fs";
-import { join, extname } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import { findLatestEvent, sha256File, sha256Text } from "./store.js";
 import { REVIEW_CODE_REVIEW_GATE } from "./review_job_gates.js";
+import { codeFileContentSha, currentGitHead, diffFingerprints, dirtyCodePaths, gitLines, isCodeLikePath, projectHasReadableDirectory, walkCodeFiles, } from "./git_state.js";
+import { parseExecutionRequirements, parseTestContractEntries } from "./format.js";
 export const CODE_REVIEW_REPAIR_SCOPE_PREFIX = "code_reviewer_report_repair:";
 export const CODE_REVIEW_DECISION_SCOPE_PREFIX = "code_review_decision:";
+export const TEST_COVERAGE_EXEMPTION_SCOPE_PREFIX = "test_coverage_exemption:";
 export const CODE_REVIEW_DECISION_ANSWER_LABELS = {
     reopen_propose: "回到计划阶段",
     reopen_apply: "回到实现阶段",
     dismiss: "驳回该问题",
 };
-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"]);
-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, "/");
-}
-function gitChangedPaths(projectRoot) {
-    try {
-        const output = execFileSync("git", ["-C", projectRoot, "status", "--porcelain", "--untracked-files=all"], {
-            encoding: "utf8",
-            stdio: ["ignore", "pipe", "ignore"],
-        });
-        const paths = output
-            .split("\n")
-            .map(line => line.trimEnd())
-            .filter(Boolean)
-            .map(line => normalizeGitPath(line.slice(3)))
-            .filter(Boolean);
-        return { ok: true, paths: [...new Set(paths)].sort() };
-    }
-    catch (err) {
-        return { ok: false, reason: err instanceof Error ? err.message : "git status 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());
-}
-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 scanCodeChanges(projectRoot) {
-    const git = gitChangedPaths(projectRoot);
+    const git = dirtyCodePaths(projectRoot);
     if (!git.ok) {
-        const paths = existsSync(projectRoot) && statSync(projectRoot).isDirectory()
+        const paths = projectHasReadableDirectory(projectRoot)
             ? walkCodeFiles(projectRoot).sort()
             : [];
         return {
@@ -105,8 +34,168 @@ export function scanCodeChanges(projectRoot) {
         reason: paths.length > 0 ? "检测到代码类改动" : "没有代码类改动",
     };
 }
+export function currentCodeReviewWorkingPaths(projectRoot, events, extraIgnoredPaths = []) {
+    const ignored = new Set(extraIgnoredPaths.map(path => path.replace(/\\/g, "/")));
+    for (const path of knownCodeReviewReportPaths(projectRoot, events))
+        ignored.add(path);
+    return scanCodeChanges(projectRoot).paths.filter(path => !ignored.has(path));
+}
+function uniqSorted(paths) {
+    return [...new Set(paths)].filter(isCodeLikePath).sort();
+}
+function normalizeKnownPath(path) {
+    return path.trim().replace(/\\/g, "/");
+}
+export function knownCodeReviewReportPaths(projectRoot, events) {
+    const paths = new Set();
+    for (const ev of events) {
+        if (ev.event_type !== "job_accepted" && ev.event_type !== "job_rejected")
+            continue;
+        const payload = ev.payload;
+        if (payload.role !== "code-reviewer")
+            continue;
+        if (typeof payload.report_digest !== "string" || payload.report_digest.trim() === "")
+            continue;
+        if (typeof payload.report_path === "string" && payload.report_path.trim() !== "") {
+            const reportPath = normalizeKnownPath(payload.report_path);
+            if (sha256File(join(projectRoot, reportPath)) === payload.report_digest) {
+                paths.add(reportPath);
+            }
+        }
+    }
+    return paths;
+}
+function excludeKnownPaths(paths, ignored) {
+    if (ignored.size === 0)
+        return paths;
+    return paths.filter(path => !ignored.has(path));
+}
+function firstStartApplyHead(events) {
+    for (const ev of events) {
+        if (ev.event_type !== "transition_commit")
+            continue;
+        const payload = ev.payload;
+        if (payload.transition !== "start-apply")
+            continue;
+        if (!Object.prototype.hasOwnProperty.call(payload, "apply_start_head")) {
+            return { present: false, head: null, reason: "missing_apply_start_head" };
+        }
+        return {
+            present: true,
+            head: typeof payload.apply_start_head === "string" ? payload.apply_start_head : null,
+            reason: typeof payload.apply_start_head_reason === "string" ? payload.apply_start_head_reason : "missing_apply_start_head",
+        };
+    }
+    return { present: false, head: null, reason: "没有 apply_start_head" };
+}
+function latestReviewedHead(events) {
+    for (let i = events.length - 1; i >= 0; i--) {
+        const ev = events[i];
+        if (ev.event_type !== "transition_commit")
+            continue;
+        const payload = ev.payload;
+        const gate = payload.code_review_gate;
+        if (!gate)
+            continue;
+        if (gate.decision === "passed") {
+            if (typeof gate.current_head !== "string" || gate.current_head.trim() === "")
+                continue;
+            return { present: true, head: gate.current_head };
+        }
+        if (gate.decision === "skipped") {
+            if (typeof gate.head !== "string" || gate.head.trim() === "")
+                continue;
+            return { present: true, head: gate.head };
+        }
+    }
+    return { present: false, head: null };
+}
+export function selectCodeReviewBase(events) {
+    const reviewed = latestReviewedHead(events);
+    if (reviewed.present)
+        return { base_head: reviewed.head, kind: "reviewed", reason: "latest_code_review_gate" };
+    const firstStart = firstStartApplyHead(events);
+    if (!firstStart.present)
+        return { base_head: null, kind: "history_missing", reason: firstStart.reason };
+    if (firstStart.head == null)
+        return { base_head: null, kind: "empty_tree", reason: firstStart.reason };
+    return { base_head: firstStart.head, kind: "start_apply", reason: "first_start_apply" };
+}
+function scanCodeReviewScopeFromBase(projectRoot, base, ignoredPaths = new Set()) {
+    const currentHead = currentGitHead(projectRoot);
+    let scopeReliable = true;
+    let scopeReason = base.kind === "history_missing" ? base.reason : "ok";
+    let committedPaths = [];
+    if (base.kind !== "history_missing") {
+        if (base.base_head && currentHead.head) {
+            const diff = gitLines(projectRoot, ["diff", "--name-only", `${base.base_head}..HEAD`]);
+            if (diff.ok)
+                committedPaths = excludeKnownPaths(uniqSorted(diff.lines), ignoredPaths);
+            else {
+                scopeReliable = false;
+                scopeReason = `git diff ${base.base_head}..HEAD failed: ${diff.reason}`;
+                committedPaths = null;
+            }
+        }
+        else if (base.kind === "empty_tree" && currentHead.head) {
+            const tree = gitLines(projectRoot, ["ls-tree", "-r", "--name-only", "HEAD"]);
+            if (tree.ok)
+                committedPaths = excludeKnownPaths(uniqSorted(tree.lines), ignoredPaths);
+            else {
+                scopeReliable = false;
+                scopeReason = `git ls-tree HEAD failed: ${tree.reason}`;
+                committedPaths = null;
+            }
+        }
+    }
+    const staged = gitLines(projectRoot, ["diff", "--name-only", "--cached"]);
+    const unstaged = gitLines(projectRoot, ["diff", "--name-only"]);
+    const untracked = gitLines(projectRoot, ["ls-files", "--others", "--exclude-standard"]);
+    if (!staged.ok || !unstaged.ok || !untracked.ok) {
+        scopeReliable = false;
+        scopeReason = [scopeReason, !staged.ok ? staged.reason : "", !unstaged.ok ? unstaged.reason : "", !untracked.ok ? untracked.reason : ""]
+            .filter(Boolean)
+            .join("; ");
+    }
+    const worktreePaths = excludeKnownPaths(uniqSorted([...(staged.ok ? staged.lines : []), ...(unstaged.ok ? unstaged.lines : [])]), ignoredPaths);
+    const untrackedPaths = excludeKnownPaths(uniqSorted(untracked.ok ? untracked.lines : []), ignoredPaths);
+    const fallbackPaths = projectHasReadableDirectory(projectRoot)
+        ? excludeKnownPaths(walkCodeFiles(projectRoot).sort(), ignoredPaths)
+        : [];
+    const reviewPaths = committedPaths == null || !scopeReliable
+        ? uniqSorted([...fallbackPaths, ...worktreePaths, ...untrackedPaths])
+        : uniqSorted([...committedPaths, ...worktreePaths, ...untrackedPaths]);
+    return {
+        base_head: base.base_head,
+        current_head: currentHead.head,
+        scope_reliable: scopeReliable,
+        scope_reason: scopeReason || base.reason,
+        committed_paths: committedPaths,
+        worktree_paths: worktreePaths,
+        untracked_paths: untrackedPaths,
+        review_paths: reviewPaths,
+    };
+}
+export function scanCodeReviewScope(projectRoot, events) {
+    return scanCodeReviewScopeFromBase(projectRoot, selectCodeReviewBase(events), knownCodeReviewReportPaths(projectRoot, events));
+}
+export function scanCodeChangesForReview(projectRoot, events) {
+    const scope = scanCodeReviewScope(projectRoot, events);
+    const hasCodeChanges = !scope.scope_reliable ||
+        scope.committed_paths == null ||
+        scope.committed_paths.length > 0 ||
+        scope.worktree_paths.length > 0 ||
+        scope.untracked_paths.length > 0;
+    return {
+        reliable: scope.scope_reliable,
+        hasCodeChanges,
+        paths: scope.review_paths,
+        reason: hasCodeChanges ? "检测到代码类改动" : "没有代码类改动",
+        scope,
+    };
+}
 export function codeReviewBoundFiles(projectRoot, paths) {
-    return paths.map(path => ({ path, sha: sha256File(join(projectRoot, path)) ?? "sha256:missing" }));
+    return paths.map(path => ({ path, sha: codeFileContentSha(projectRoot, path) ?? "sha256:missing" }));
 }
 function samePathSet(left, right) {
     const a = [...new Set(left)].sort();
@@ -116,13 +205,32 @@ function samePathSet(left, right) {
 export function codeReviewJobStaleReason(projectRoot, job, currentPaths) {
     if (!isCodeReviewerJob(job))
         return null;
+    const frozenScope = job.packet_context?.code_review_scope;
+    if (frozenScope) {
+        const currentHead = currentGitHead(projectRoot);
+        if (frozenScope.current_head !== currentHead.head) {
+            return `代码审查创建后的 HEAD 已变化（原记录：${frozenScope.current_head ?? "<none>"}；当前：${currentHead.head ?? "<none>"}）`;
+        }
+        const currentWorkingPaths = currentPaths ?? scanCodeChanges(projectRoot).paths;
+        const frozenWorkingPaths = uniqSorted([...frozenScope.worktree_paths, ...frozenScope.untracked_paths]);
+        if (!samePathSet(frozenWorkingPaths, currentWorkingPaths)) {
+            return `代码审查范围已变化：工作区范围已变化（原范围：${frozenWorkingPaths.join(", ") || "<none>"}；当前范围：${currentWorkingPaths.join(", ") || "<none>"}）`;
+        }
+        for (const bound of job.boundFiles) {
+            const currentSha = codeFileContentSha(projectRoot, bound.path) ?? "sha256:missing";
+            if (currentSha !== bound.sha) {
+                return `代码审查范围内的文件 ${bound.path} 已变化（原记录：${bound.sha}；当前：${currentSha}）`;
+            }
+        }
+        return null;
+    }
     const scanPaths = currentPaths ?? scanCodeChanges(projectRoot).paths;
     const boundPaths = job.boundFiles.map(file => file.path);
     if (!samePathSet(boundPaths, scanPaths)) {
         return `代码审查范围已变化（原范围：${boundPaths.join(", ") || "<none>"}；当前范围：${scanPaths.join(", ") || "<none>"}）`;
     }
     for (const bound of job.boundFiles) {
-        const currentSha = sha256File(join(projectRoot, bound.path)) ?? "sha256:missing";
+        const currentSha = codeFileContentSha(projectRoot, bound.path) ?? "sha256:missing";
         if (currentSha !== bound.sha) {
             return `代码审查范围内的文件 ${bound.path} 已变化（原记录：${bound.sha}；当前：${currentSha}）`;
         }
@@ -132,6 +240,196 @@ export function codeReviewJobStaleReason(projectRoot, job, currentPaths) {
 export function codeReviewPacketDigest(input) {
     return sha256Text(JSON.stringify(input));
 }
+export function codeReviewPacketContext(changeRoot, projectRoot, scope, events) {
+    const taskExecutionIndex = taskExecutionIndexFromEvents(projectRoot, events);
+    // changed_paths 未知（快照缺失）或不完整（committed 段 diff 失败）的 task
+    // 都进入 unknown_attribution_tasks，提示 code-reviewer 扩大对照范围
+    const unknownAttributionTasks = taskExecutionIndex
+        .filter(item => item.changed_paths == null || item.changed_paths_partial_reason != null)
+        .map(item => item.task_id)
+        .sort();
+    const attributedPaths = new Set();
+    for (const item of taskExecutionIndex) {
+        for (const path of item.changed_paths ?? [])
+            attributedPaths.add(path);
+    }
+    return {
+        code_review_scope: scope,
+        coverage_exemption_refs: coverageExemptionRefs(changeRoot, events),
+        task_execution_index: taskExecutionIndex,
+        unattributed_paths: scope.review_paths.filter(path => !attributedPaths.has(path)).sort(),
+        unknown_attribution_tasks: unknownAttributionTasks,
+    };
+}
+export function effectiveCoverageExemptionRefsFromEvents(events) {
+    const latest = new Map();
+    for (const ev of events) {
+        if (ev.event_type !== "user_decision_recorded")
+            continue;
+        const payload = ev.payload;
+        if (payload.accepted === false)
+            continue;
+        if (typeof payload.scope !== "string" || !payload.scope.startsWith(TEST_COVERAGE_EXEMPTION_SCOPE_PREFIX))
+            continue;
+        const testId = payload.scope.slice(TEST_COVERAGE_EXEMPTION_SCOPE_PREFIX.length);
+        if (!/^TEST-[A-Za-z0-9_-]+$/.test(testId))
+            continue;
+        if (typeof payload.answer !== "string" || payload.answer.trim() === "")
+            continue;
+        latest.set(testId, {
+            test_id: testId,
+            event_id: ev.event_id,
+            event_digest: ev.event_digest,
+            answer: payload.answer.trim(),
+        });
+    }
+    return [...latest.values()].sort((a, b) => a.test_id.localeCompare(b.test_id));
+}
+function currentTaskDeclaredTestIds(changeRoot) {
+    const tasksPath = join(changeRoot, "tasks.md");
+    if (!existsSync(tasksPath))
+        return new Set();
+    return new Set(parseExecutionRequirements(readFileSync(tasksPath, "utf8")).flatMap(item => item.contract.tests));
+}
+function currentTestContractIds(changeRoot) {
+    const testContractPath = join(changeRoot, ".superspec", "artifacts", "test-contract.md");
+    if (!existsSync(testContractPath))
+        return [];
+    const parsed = parseTestContractEntries(readFileSync(testContractPath, "utf8"));
+    return parsed.ok ? parsed.entries.map(entry => entry.test_id).sort() : [];
+}
+export function missingCoverageExemptionTestIds(changeRoot, events) {
+    const declared = currentTaskDeclaredTestIds(changeRoot);
+    const effective = new Set(effectiveCoverageExemptionRefsFromEvents(events).map(ref => ref.test_id));
+    return currentTestContractIds(changeRoot)
+        .filter(testId => !declared.has(testId) && !effective.has(testId))
+        .sort();
+}
+function coverageExemptionRefs(changeRoot, events) {
+    const declared = currentTaskDeclaredTestIds(changeRoot);
+    const unbound = new Set(currentTestContractIds(changeRoot).filter(testId => !declared.has(testId)));
+    return effectiveCoverageExemptionRefsFromEvents(events)
+        .filter(ref => unbound.has(ref.test_id))
+        .sort((a, b) => a.test_id.localeCompare(b.test_id));
+}
+function boundaryFromPayload(payload) {
+    const boundary = payload.boundary_snapshot;
+    if (!boundary || typeof boundary !== "object" || Array.isArray(boundary))
+        return null;
+    const obj = boundary;
+    if (!Array.isArray(obj.dirty_files))
+        return null;
+    if (typeof obj.dirty_files_reason === "string")
+        return null;
+    return {
+        head: typeof obj.head === "string" ? obj.head : null,
+        ...(typeof obj.head_reason === "string" ? { head_reason: obj.head_reason } : {}),
+        dirty_files: obj.dirty_files,
+    };
+}
+function changedPathsBetweenSnapshots(projectRoot, start, completed) {
+    if (!start || !completed)
+        return null;
+    // 两端 dirty_files 用共享指纹原语对比，再过滤出代码类路径
+    const changed = new Set(diffFingerprints(start.dirty_files, completed.dirty_files).filter(isCodeLikePath));
+    let partialReason = null;
+    if (start.head && completed.head && start.head !== completed.head) {
+        const diff = gitLines(projectRoot, ["diff", "--name-only", `${start.head}..${completed.head}`]);
+        if (diff.ok) {
+            // 方案要求 committed 段只收代码文件，uniqSorted 内含 isCodeLikePath 过滤
+            for (const path of uniqSorted(diff.lines))
+                changed.add(path);
+        }
+        else {
+            // diff 失败不丢弃 dirty 侧的确定事实，只标记 committed 段缺失
+            partialReason = `git diff ${start.head}..${completed.head} failed: ${diff.reason}`;
+        }
+    }
+    return { paths: [...changed].sort(), partial_reason: partialReason };
+}
+function testEvidenceForAttempt(events, attempt) {
+    const declaredTests = attempt.contract_mode === true ? attempt.contract?.tests ?? [] : [];
+    const eventsByTest = new Map();
+    for (const ev of events) {
+        if (ev.event_type !== "test_run_recorded")
+            continue;
+        const payload = ev.payload;
+        if (payload.attempt_id !== attempt.attempt_id || typeof payload.test_id !== "string")
+            continue;
+        if (declaredTests.length > 0 && !declaredTests.includes(payload.test_id))
+            continue;
+        const list = eventsByTest.get(payload.test_id) ?? [];
+        list.push(ev);
+        eventsByTest.set(payload.test_id, list);
+    }
+    const testIds = declaredTests.length > 0 ? declaredTests : [...eventsByTest.keys()].sort();
+    const evidence = [];
+    for (const testId of testIds) {
+        let red = null;
+        let green = null;
+        let pairedRed = null;
+        for (const ev of eventsByTest.get(testId) ?? []) {
+            const payload = ev.payload;
+            if (payload.semantic_status === "expected_failure" && typeof payload.exit_code === "number" && payload.exit_code !== 0) {
+                if (!red)
+                    red = ev;
+                continue;
+            }
+            const isGreen = (payload.semantic_status === "expected_success" || payload.semantic_status === "characterization_pass") && payload.exit_code === 0;
+            if (isGreen && !green) {
+                green = ev;
+                pairedRed = red;
+            }
+        }
+        if (!green && !pairedRed)
+            continue;
+        evidence.push({
+            test_id: testId,
+            ...(pairedRed ? { red_event_ref: pairedRed.event_id, red_event_digest: pairedRed.event_digest } : {}),
+            ...(green ? { green_event_ref: green.event_id, green_event_digest: green.event_digest } : {}),
+        });
+    }
+    return evidence.sort((a, b) => String(a.test_id).localeCompare(String(b.test_id)));
+}
+function taskExecutionIndexFromEvents(projectRoot, events) {
+    const attempts = new Map();
+    const entries = [];
+    for (const ev of events) {
+        if (ev.event_type === "task_started") {
+            const attempt = ev.payload;
+            if (typeof attempt.attempt_id === "string") {
+                attempts.set(attempt.attempt_id, {
+                    attempt,
+                    boundary: boundaryFromPayload(ev.payload),
+                });
+            }
+        }
+        else if (ev.event_type === "task_completed") {
+            const payload = ev.payload;
+            if (typeof payload.task_id !== "string" || typeof payload.attempt_id !== "string")
+                continue;
+            const started = attempts.get(payload.attempt_id);
+            const attempt = started?.attempt;
+            const effectiveContract = attempt?.contract_mode === true ? attempt.contract ?? null : null;
+            const changedResult = changedPathsBetweenSnapshots(projectRoot, started?.boundary ?? null, boundaryFromPayload(ev.payload));
+            entries.push({
+                task_id: payload.task_id,
+                attempt_id: payload.attempt_id,
+                changed_paths: changedResult ? changedResult.paths : null,
+                ...(changedResult?.partial_reason ? { changed_paths_partial_reason: changedResult.partial_reason } : {}),
+                contract: effectiveContract,
+                declared_tests: effectiveContract?.tests ?? [],
+                scope_note: payload.scope_note && typeof payload.scope_note === "object" && !Array.isArray(payload.scope_note)
+                    ? payload.scope_note
+                    : null,
+                test_evidence: attempt ? testEvidenceForAttempt(events, attempt) : [],
+                task_completed_event_ref: ev.event_id,
+            });
+        }
+    }
+    entries.sort((a, b) => a.task_id.localeCompare(b.task_id) || a.attempt_id.localeCompare(b.attempt_id));
+    return entries;
+}
 function isCodeReviewerJob(job) {
     return job.role === "code-reviewer" && REVIEW_CODE_REVIEW_GATE.isJobForGate(job);
 }
@@ -322,3 +620,96 @@ export function latestApplyDoneToReviewGate(events) {
 export function requiresFinalVerifierForCurrentReview(events) {
     return latestApplyDoneToReviewGate(events) != null;
 }
+function findJobInEvents(events, jobId) {
+    for (const ev of events) {
+        if (ev.event_type !== "transition_commit")
+            continue;
+        const jobs = ev.payload.new_jobs ?? [];
+        const job = jobs.find(item => item.job_id === jobId);
+        if (job)
+            return job;
+    }
+    return null;
+}
+function latestApplyDoneToReviewGatePayload(events) {
+    for (let i = events.length - 1; i >= 0; i--) {
+        const ev = events[i];
+        if (ev.event_type !== "transition_commit")
+            continue;
+        const payload = ev.payload;
+        if (payload.transition !== "review-ready" || payload.from_state !== "apply_done" || payload.to_state !== "review")
+            continue;
+        const gate = payload.code_review_gate;
+        if (!gate || (gate.decision !== "passed" && gate.decision !== "skipped"))
+            return null;
+        return {
+            decision: gate.decision,
+            ...(typeof gate.job_id === "string" ? { job_id: gate.job_id } : {}),
+            ...(typeof gate.current_head === "string" || gate.current_head === null ? { current_head: gate.current_head } : {}),
+            ...(typeof gate.head === "string" || gate.head === null ? { head: gate.head } : {}),
+        };
+    }
+    return null;
+}
+export function computeCodeStateCheck(projectRoot, events, ignoredCodePaths = []) {
+    const gate = latestApplyDoneToReviewGatePayload(events);
+    const currentHead = currentGitHead(projectRoot);
+    const baselineHead = gate?.decision === "passed" ? gate.current_head ?? null : gate?.head ?? null;
+    const changed = new Set();
+    const ignored = new Set(ignoredCodePaths);
+    const reviewedJob = gate?.decision === "passed" && gate.job_id ? findJobInEvents(events, gate.job_id) : null;
+    for (const ev of events) {
+        if (ev.event_type !== "job_accepted" && ev.event_type !== "job_rejected")
+            continue;
+        const payload = ev.payload;
+        if (typeof payload.report_path === "string")
+            ignored.add(payload.report_path);
+    }
+    let scopeReason = gate ? "ok" : "missing_code_review_gate";
+    if (baselineHead && currentHead.head && baselineHead !== currentHead.head) {
+        const diff = gitLines(projectRoot, ["diff", "--name-only", `${baselineHead}..HEAD`]);
+        if (diff.ok) {
+            for (const path of uniqSorted(diff.lines))
+                changed.add(path);
+        }
+        else {
+            scopeReason = `git diff ${baselineHead}..HEAD failed: ${diff.reason}`;
+        }
+    }
+    else if (!baselineHead && gate && currentHead.head) {
+        const tree = gitLines(projectRoot, ["ls-tree", "-r", "--name-only", "HEAD"]);
+        if (tree.ok) {
+            for (const path of uniqSorted(tree.lines))
+                changed.add(path);
+        }
+        else {
+            scopeReason = `git ls-tree HEAD failed: ${tree.reason}`;
+        }
+    }
+    // bound 基线与当前磁盘状态共用 {path,status,sha256} 指纹原语对比：
+    // 基线是 code review 时点的 bound 文件指纹；当前侧取 bound 路径与脏代码文件的并集。
+    // gate skipped 时基线为空，任何脏代码文件都会作为差异列出。
+    const baselineFingerprints = (reviewedJob?.boundFiles ?? [])
+        .map(bound => ({ path: bound.path, status: "modified", sha256: bound.sha }));
+    const baselinePaths = new Set(baselineFingerprints.map(file => file.path));
+    // ignored（审查报告文件等）只豁免 bound 集合之外的新脏文件，bound 文件本身的变化仍需暴露
+    const currentPaths = new Set([
+        ...baselinePaths,
+        ...scanCodeChanges(projectRoot).paths.filter(path => !ignored.has(path)),
+    ]);
+    // 缺失文件用与 bound 基线一致的 "sha256:missing" 占位：review 时点就缺失、现在仍缺失的文件不算差异
+    const currentFingerprints = [...currentPaths].map(path => ({
+        path,
+        status: "modified",
+        sha256: codeFileContentSha(projectRoot, path) ?? "sha256:missing",
+    }));
+    for (const path of diffFingerprints(baselineFingerprints, currentFingerprints))
+        changed.add(path);
+    return {
+        baseline_head: baselineHead,
+        current_head: currentHead.head,
+        head_matches: baselineHead === currentHead.head,
+        changed_paths: [...changed].filter(isCodeLikePath).sort(),
+        scope_reason: scopeReason,
+    };
+}

package/dist/format.d.ts

@@ -1,5 +1,14 @@
+import type { ExecutionContract } from "./types.ts";
 /** 从 discovery.md 提取"待确认问题"段内的未确认项数量 */
 export declare function countDiscoveryOpenQuestions(content: string): number;
+export interface DiscoveryChainCoverageCheck {
+    ok: boolean;
+    message: string;
+    present: boolean;
+}
+export declare function splitMarkdownTableRow(line: string): string[];
+/** 轻量校验 discovery.md 的链路五要素段。只校验结构和阻塞未知，不判断业务真假。 */
+export declare function validateDiscoveryChainCoverage(content: string): DiscoveryChainCoverageCheck;
 /** 完整校验 discovery.md：存在 + 非空 + 无未确认问题 */
 export declare function validateDiscovery(changeRoot: string): {
     ok: boolean;
@@ -22,18 +31,51 @@ export interface ParsedTask {
     tddRequired: boolean;
     noTddReason: string | null;
 }
+export interface ParsedExecutionRequirement {
+    taskId: string;
+    lineIdx: number;
+    contract: ExecutionContract;
+    errors: string[];
+}
+export interface TestContractEntry {
+    test_id: string;
+    scenario: string;
+    invariant: string;
+}
+export type TestContractParseResult = {
+    ok: true;
+    entries: TestContractEntry[];
+} | {
+    ok: false;
+    entries: [];
+    message: string;
+};
 /** 解析 tasks.md 的全部任务行 */
 export declare function parseTasksMd(content: string): ParsedTask[];
+export declare function hasTaskBoundExecutionRequirements(content: string): boolean;
+export declare function parseExecutionRequirements(content: string): ParsedExecutionRequirement[];
+export declare function orphanExecutionRequirementErrors(content: string): string[];
+export declare function executionRequirementForTask(content: string, taskId: string): ParsedExecutionRequirement | null;
+export declare function adoptedContractForTask(content: string, taskId: string, contractMode: boolean): {
+    parsed: ParsedExecutionRequirement | null;
+    contract: ExecutionContract | null;
+};
+export declare function isReviewFixTaskId(taskId: string): boolean;
+export declare function isCharacterizationTask(task: ParsedTask): boolean;
+export declare function parseTestContractEntries(content: string): TestContractParseResult;
+export interface ExecutionRequirementValidation {
+    ok: boolean;
+    mode: boolean;
+    contracts: ParsedExecutionRequirement[];
+    errors: string[];
+}
+export declare function validateExecutionRequirements(content: string, testContractContent: string | null): ExecutionRequirementValidation;
 /** 返回未完成任务 */
 export declare function pendingTasksInContent(content: string): ParsedTask[];
 /** 在 tasks.md 中按 taskId 精确查找任务（词边界，不误判子串） */
 export declare function findTaskInLines(lines: string[], taskId: string): number;
 /** tasks.md 结构指纹（复选框归一化） */
 export declare function tasksStructureDigest(content: string, sha256Text: (s: string) => string): string;
-export declare function validateTestRunInput(tr: Record<string, unknown>): {
-    ok: boolean;
-    message: string;
-};
 export declare function validateUserDecision(d: Record<string, unknown>): {
     ok: boolean;
     message: string;