@peterxiaoyang/superspec 0.1.40 → 0.1.42

package/dist/review.js

@@ -2,7 +2,7 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { docRef, sha256File, sha256Text } from "./store.js";
-import { REVIEW_FINAL_VERIFIER_GATE } from "./review_job_gates.js";
+import { EXPLORE_DISCOVERY_REVIEW_GATE_ID, PROPOSE_FINAL_REVIEW_GATE_ID, REVIEW_FINAL_VERIFIER_GATE, } from "./review_job_gates.js";
 import { computeCodeStateCheck, effectiveCoverageExemptionRefsFromEvents } from "./code_review.js";
 export const REVIEW_DOC_PATHS = [
     "proposal.md",
@@ -54,6 +54,108 @@ export function readReviewPolicyFromEvents(events) {
     }
     return null;
 }
+function reviewResultKind(value) {
+    return value === "invalid_report" || value === "non_actionable_report" || value === "review_failed"
+        ? value
+        : null;
+}
+function reviewCycleState(gate) {
+    if (gate.gate_id === EXPLORE_DISCOVERY_REVIEW_GATE_ID)
+        return "explore";
+    if (gate.gate_id === PROPOSE_FINAL_REVIEW_GATE_ID)
+        return "propose";
+    return null;
+}
+function currentReviewGateCycleStart(events, gate) {
+    const state = reviewCycleState(gate);
+    if (!state)
+        return null;
+    for (let i = events.length - 1; i >= 0; i--) {
+        const event = events[i];
+        if (event.event_type !== "transition_commit")
+            continue;
+        const payload = event.payload;
+        if (payload.to_state === state && payload.from_state !== state)
+            return i;
+    }
+    return 0;
+}
+function reviewTerminalResultsForGateRole(events, gate, role) {
+    const cycleStartIndex = currentReviewGateCycleStart(events, gate);
+    if (cycleStartIndex == null)
+        return [];
+    const jobsById = new Map();
+    for (let i = cycleStartIndex; i < events.length; i++) {
+        const event = events[i];
+        if (event.event_type !== "transition_commit")
+            continue;
+        const jobs = event.payload.new_jobs ?? [];
+        for (const job of jobs) {
+            if (job.role === role && gate.isJobForGate(job))
+                jobsById.set(job.job_id, job);
+        }
+    }
+    const results = [];
+    for (let i = cycleStartIndex; i < events.length; i++) {
+        const event = events[i];
+        if (event.event_type !== "job_accepted" && event.event_type !== "job_rejected")
+            continue;
+        const payload = event.payload;
+        if (typeof payload.job_id !== "string")
+            continue;
+        const job = jobsById.get(payload.job_id);
+        if (!job)
+            continue;
+        const findings = Array.isArray(payload.findings) ? payload.findings : undefined;
+        results.push({
+            job,
+            state: event.event_type === "job_accepted" ? "accepted" : "rejected",
+            ...(event.event_type === "job_rejected"
+                ? { result_kind: reviewResultKind(payload.result_kind) ?? (findings ? "review_failed" : "invalid_report") }
+                : {}),
+            ...(typeof payload.reason === "string" && payload.reason.trim() !== "" ? { reason: payload.reason } : {}),
+            ...(findings ? { findings } : {}),
+        });
+    }
+    return results;
+}
+export function latestReviewHistoryForGateRole(events, gate, role) {
+    const terminalResults = reviewTerminalResultsForGateRole(events, gate, role);
+    const latest = terminalResults.at(-1);
+    if (!latest || latest.state === "accepted")
+        return null;
+    const resultKind = latest.result_kind ?? "invalid_report";
+    const reason = latest.reason ?? (resultKind === "review_failed"
+        ? "报告结论为 fail，工作项未通过"
+        : "审查报告无效，工作项未通过");
+    if (resultKind === "review_failed" && latest.findings && latest.findings.length > 0) {
+        return {
+            result_kind: resultKind,
+            reason,
+            job_id: latest.job.job_id,
+            ...(latest.findings ? { findings: latest.findings } : {}),
+        };
+    }
+    for (let i = terminalResults.length - 2; i >= 0; i--) {
+        const previous = terminalResults[i];
+        if (previous.state === "accepted")
+            break;
+        if (previous.result_kind !== "review_failed" || !previous.findings || previous.findings.length === 0)
+            continue;
+        return {
+            result_kind: resultKind,
+            reason,
+            job_id: latest.job.job_id,
+            ...(previous.findings ? { findings: previous.findings } : {}),
+            findings_job_id: previous.job.job_id,
+        };
+    }
+    return {
+        result_kind: resultKind,
+        reason,
+        job_id: latest.job.job_id,
+    };
+}
 export function isReviewReadyVerifier(job) {
     return job.role === "verifier" && REVIEW_FINAL_VERIFIER_GATE.isJobForGate(job);
 }

package/dist/review_job_gates.d.ts

@@ -4,7 +4,8 @@ export interface ReviewGateRule {
     gate_id: ReviewJobGateId;
     created_from_transition: "explore" | "propose-ready" | "review-ready";
     allowedRoles: JobRole[];
-    reviewedDocPaths: string[];
+    reviewTargets: string[];
+    readOnlyRefs: string[];
     requiredRolesForRisk(risk: ReviewRisk): JobRole[];
     matchesOldJob(job: Job): boolean;
     isJobForGate(job: Job): boolean;

package/dist/review_job_gates.js

@@ -28,7 +28,8 @@ export const EXPLORE_DISCOVERY_REVIEW_GATE = makeReviewGateRule({
     gate_id: EXPLORE_DISCOVERY_REVIEW_GATE_ID,
     created_from_transition: "explore",
     allowedRoles: EXPLORE_DISCOVERY_REVIEW_ROLES,
-    reviewedDocPaths: [".superspec/artifacts/discovery.md"],
+    reviewTargets: [".superspec/artifacts/discovery.md"],
+    readOnlyRefs: [],
     requiredRolesForRisk(risk) {
         return reviewRolesForGate(EXPLORE_DISCOVERY_REVIEW_GATE_ID, risk);
     },
@@ -40,15 +41,15 @@ export const PROPOSE_FINAL_REVIEW_GATE = makeReviewGateRule({
     gate_id: PROPOSE_FINAL_REVIEW_GATE_ID,
     created_from_transition: "propose-ready",
     allowedRoles: PROPOSAL_REVIEW_ROLES,
-    reviewedDocPaths: [
+    reviewTargets: [
         "proposal.md",
         "tasks.md",
         "design.md",
         "specs/",
-        ".superspec/artifacts/discovery.md",
         ".superspec/artifacts/business-invariants.md",
         ".superspec/artifacts/test-contract.md",
     ],
+    readOnlyRefs: [".superspec/artifacts/discovery.md"],
     requiredRolesForRisk(risk) {
         return reviewRolesForGate(PROPOSE_FINAL_REVIEW_GATE_ID, risk);
     },
@@ -60,7 +61,8 @@ export const REVIEW_CODE_REVIEW_GATE = makeReviewGateRule({
     gate_id: REVIEW_CODE_REVIEW_GATE_ID,
     created_from_transition: "review-ready",
     allowedRoles: REVIEW_CODE_REVIEW_ROLES,
-    reviewedDocPaths: [],
+    reviewTargets: [],
+    readOnlyRefs: [],
     requiredRolesForRisk(risk) {
         return reviewRolesForGate(REVIEW_CODE_REVIEW_GATE_ID, risk);
     },
@@ -72,7 +74,8 @@ export const REVIEW_FINAL_VERIFIER_GATE = makeReviewGateRule({
     gate_id: REVIEW_FINAL_VERIFIER_GATE_ID,
     created_from_transition: "review-ready",
     allowedRoles: REVIEW_FINAL_VERIFIER_ROLES,
-    reviewedDocPaths: [],
+    reviewTargets: [],
+    readOnlyRefs: [],
     requiredRolesForRisk(risk) {
         return reviewRolesForGate(REVIEW_FINAL_VERIFIER_GATE_ID, risk);
     },

package/dist/task.js

@@ -3,6 +3,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { sha256Text, ensureChangeLayout, appendEvent, makeEvent, withLock, appendRawRecord, readEvents } from "./store.js";
 import { tasksStructureDigest as formatDigest } from "./format.js";
+import { RecordInputDecodingError, readRecordInputFile } from "./record_input.js";
 /** tasks.md 结构指纹（委托给 format.ts 统一实现） */
 export function tasksStructureDigestOf(changeRoot) {
     const p = join(changeRoot, "tasks.md");
@@ -144,7 +145,14 @@ export function recordTestRun(projectRoot, change, inputFile) {
         ensureChangeLayout(projectRoot, change);
         if (!existsSync(inputFile))
             return { accepted: false, message: `文件不存在：${inputFile}` };
-        return recordTestRunLoaded(projectRoot, change, readFileSync(inputFile, "utf8"));
+        try {
+            return recordTestRunLoaded(projectRoot, change, readRecordInputFile(inputFile));
+        }
+        catch (err) {
+            if (err instanceof RecordInputDecodingError)
+                return { accepted: false, message: err.message };
+            throw err;
+        }
     });
 }
 /** record test-run：从 JSON 内容登记测试运行记录 */

package/dist/transition.d.ts

@@ -42,6 +42,5 @@ export declare function reopen(projectRoot: string, change: string, changeRoot:
 }): TransitionResult;
 export declare function reviewReady(projectRoot: string, change: string, changeRoot: string, risk?: "minimal" | "normal" | "strict"): TransitionResult;
 export declare function accept(projectRoot: string, change: string, changeRoot: string): TransitionResult;
-export declare function archive(projectRoot: string, change: string, changeRoot: string): TransitionResult;
 export declare function taskComplete(projectRoot: string, change: string, changeRoot: string, taskId: string, inputContent?: string | null): TransitionResult;
 export {};

package/dist/transition.js

@@ -1,40 +1,48 @@
 // SuperSpec 流程引擎 — transition：提交协议 + 所有 transition 处理器
 import { join } from "node:path";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { ensureChangeLayout, readEvents, appendEvent, makeEvent, writeSnapshot, snapshotDigest, withLock, idempotencyKey, docRef, listMarkdownFiles, sha256File, sha256Text, } from "./store.js";
+import { ensureChangeLayout, readEvents, appendEvent, makeEvent, writeSnapshot, snapshotDigest, withLock, idempotencyKey, docRef, sha256Text, } from "./store.js";
 import { rebuildSnapshot } from "./sync.js";
 import { requiredJobActions } from "./job_action.js";
-import { assertCommitPayloadExtension, isFreshReviewVerifier, isReviewReadyVerifier, readReviewPolicyFromEvents, reviewBoundFiles, reviewEvidenceDigest, reviewPolicyForRisk, REVIEW_DOC_PATHS, } from "./review.js";
+import { assertCommitPayloadExtension, isFreshReviewVerifier, isReviewReadyVerifier, latestReviewHistoryForGateRole, readReviewPolicyFromEvents, reviewBoundFiles, reviewEvidenceDigest, reviewPolicyForRisk, REVIEW_DOC_PATHS, } from "./review.js";
 import { REVIEW_CODE_REVIEW_GATE_ID, REVIEW_FINAL_VERIFIER_GATE_ID, } from "./review_job_gates.js";
 import { codeReviewBoundFiles, codeReviewDecisionScope, codeReviewJobStaleReason, codeReviewPacketContext, codeReviewPacketDigest, collectCodeReviewGateFacts, computeCodeStateCheck, currentCodeReviewWorkingPaths, dismissedCodeReviewSummary, latestCodeReviewDecision, latestCodeReviewFailedStatus, missingCoverageExemptionTestIds, requiresFinalVerifierForCurrentReview, scanCodeChangesForReview, } from "./code_review.js";
 import { taskEvidenceReadiness } from "./task_evidence.js";
 import { adoptedContractForTask, findTaskInLines, isReviewFixTaskId, parseTasksMd, parseTestContractEntries, } from "./format.js";
-import { applyRequirementModeForCurrentRound, formatPendingTaskMessage, pendingTaskStatusForApply, planTransition, proposalDocsBaseline, } from "./phase_plan.js";
+import { applyRequirementModeForCurrentRound, blockingJobsForApplyDone, formatPendingTaskMessage, latestAcceptedProposalBaseline, pendingTaskStatusForApply, planTransition, proposalDocsBaseline, } from "./phase_plan.js";
+import { latestAcceptedPhaseDecision, phaseConfirmationCommitPayload, phaseConfirmationForBoundary, phaseConfirmationMissingMessage, } from "./phase_confirmation.js";
 import { currentGitHead, dirtyCodeFiles } from "./git_state.js";
 let transitionSeq = 0;
 function newTransitionId() { return `T-${Date.now()}-${++transitionSeq}`; }
 let jobSeq = 0;
 function newJobId(change, role) { return `JOB-${change.slice(0, 8)}-${role.slice(0, 4)}-${Date.now()}-${++jobSeq}`; }
-function createReviewJobsForGate(state, gate, roles, changeRoot, change, reason) {
+function createReviewJobsForGate(state, gate, roles, changeRoot, change, reason, events) {
     const newJobs = roles.map(role => {
-        // 目录路径（以 / 结尾）始终绑定聚合指纹：审查时不存在、审查后新建同样视为变化
-        const boundFiles = gate.reviewedDocPaths
-            .filter(p => p.endsWith("/") || existsSync(join(changeRoot, p)))
+        const boundPaths = [...new Set([...gate.reviewTargets, ...gate.readOnlyRefs])];
+        // 所有审查目标和只读引用都绑定时点指纹：单文件缺失使用 sha256:missing，目录缺失使用稳定空指纹。
+        const boundFiles = boundPaths
             .map(p => docRef(changeRoot, p));
+        const previousRejection = latestReviewHistoryForGateRole(events, gate, role);
         return {
             job_id: newJobId(change, role),
             role,
             state: "requested",
             gate_id: gate.gate_id,
             boundFiles,
+            ...(gate.reviewTargets.length > 0 ? { review_targets: [...gate.reviewTargets] } : {}),
+            ...(gate.readOnlyRefs.length > 0 ? { read_only_refs: [...gate.readOnlyRefs] } : {}),
             packet_digest: sha256Text(JSON.stringify({
                 role,
                 gate_id: gate.gate_id,
                 boundFiles,
+                review_targets: gate.reviewTargets,
+                read_only_refs: gate.readOnlyRefs,
                 created_from_transition: gate.created_from_transition,
+                ...(previousRejection ? { previous_rejection: previousRejection } : {}),
             })),
             created_from_transition: gate.created_from_transition,
             created_at: new Date().toISOString(),
+            ...(previousRejection ? { previous_rejection: previousRejection } : {}),
         };
     });
     return {
@@ -258,14 +266,17 @@ function evaluateApplyDoneCodeReviewGate(input) {
         const latest = facts.latestTerminal;
         if (latest?.state === "accepted") {
             const acceptedScope = latest.job.packet_context?.code_review_scope;
-            if (!hasFrozenCodeReviewCurrentHead(acceptedScope)) {
+            const staleReason = codeReviewJobStaleReason(input.projectRoot, latest.job, currentWorkingPaths);
+            if (staleReason || !hasFrozenCodeReviewCurrentHead(acceptedScope)) {
                 const { job, scanReason } = createCodeReviewerJob(input.change, input.projectRoot, input.changeRoot, input.events);
                 return {
                     fromState: "apply_done",
                     toState: "apply_done",
                     outcome: "job_created",
                     newJobs: [job],
-                    reason: `已接受代码审查工作项缺少冻结 current_head，重新创建代码审查工作项；${scanReason}`,
+                    reason: staleReason
+                        ? `已接受代码审查工作项不再匹配当前代码状态，重新创建代码审查工作项；${staleReason}；${scanReason}`
+                        : `已接受代码审查工作项缺少冻结 current_head，重新创建代码审查工作项；${scanReason}`,
                 };
             }
             return {
@@ -403,14 +414,35 @@ function evaluateFinalVerifierGate(input) {
     }
     return { skip: true, message: "已在 review 状态，最终验证仍然有效" };
 }
-function transitionPlanToDecision(snapshot, changeRoot, change, plan) {
+function authorizePhaseAdvance(input) {
+    const confirmation = phaseConfirmationForBoundary(input.projectRoot, input.events, input.snapshot, input.boundary);
+    const phaseDecision = confirmation
+        ? latestAcceptedPhaseDecision(input.events, confirmation)
+        : null;
+    if (!confirmation || phaseDecision?.decision !== "advance") {
+        return {
+            skip: true,
+            message: confirmation
+                ? phaseConfirmationMissingMessage(confirmation)
+                : `无法建立 ${input.boundary} 阶段确认范围`,
+        };
+    }
+    return {
+        ...input.decision,
+        commitPayload: {
+            ...(input.decision.commitPayload ?? {}),
+            ...phaseConfirmationCommitPayload(confirmation, phaseDecision),
+        },
+    };
+}
+function transitionPlanToDecision(snapshot, changeRoot, change, plan, events) {
     switch (plan.kind) {
         case "skip":
             return { skip: true, message: plan.message };
         case "blocked":
             return { blocked: true, reason: plan.reason, jobs: plan.jobs };
         case "create_gate_jobs":
-            return createReviewJobsForGate(snapshot.state, plan.gate, plan.roles, changeRoot, change, plan.reason);
+            return createReviewJobsForGate(snapshot.state, plan.gate, plan.roles, changeRoot, change, plan.reason, events);
         case "advance":
             return {
                 fromState: plan.fromState,
@@ -520,7 +552,7 @@ export function proposeReady(projectRoot, change, changeRoot, risk = "strict") {
                 snapshot,
                 mode: { kind: "risk", risk },
             });
-            return transitionPlanToDecision(snapshot, changeRoot, change, plan);
+            return transitionPlanToDecision(snapshot, changeRoot, change, plan, events);
         },
     });
 }
@@ -550,7 +582,7 @@ export function transitionExplore(projectRoot, change, changeRoot, risk = "stric
                 snapshot,
                 mode: { kind: "risk", risk },
             });
-            return transitionPlanToDecision(snapshot, changeRoot, change, plan);
+            return transitionPlanToDecision(snapshot, changeRoot, change, plan, events);
         },
     });
 }
@@ -568,7 +600,7 @@ export function startApply(projectRoot, change, changeRoot) {
                 snapshot,
                 mode: { kind: "risk", risk: "strict" },
             });
-            return transitionPlanToDecision(snapshot, changeRoot, change, plan);
+            return transitionPlanToDecision(snapshot, changeRoot, change, plan, events);
         },
     });
 }
@@ -718,6 +750,45 @@ export function reopen(projectRoot, change, changeRoot, to, reason, opts = {}) {
                     },
                 };
             }
+            if (to === "propose") {
+                if (snapshot.state !== "accepted") {
+                    return {
+                        skip: true,
+                        message: `当前状态 ${snapshot.state}，主动 reopen --to propose 只允许从 accepted 发起；apply_done 的代码审查问题请使用 --review-finding`,
+                    };
+                }
+                if (snapshot.open_jobs.length > 0) {
+                    return {
+                        blocked: true,
+                        reason: `状态未推进；accepted 仍有 ${snapshot.open_jobs.length} 个待完成工作项`,
+                        jobs: snapshot.open_jobs,
+                    };
+                }
+                const acceptedBaseline = latestAcceptedProposalBaseline(events);
+                const currentBaseline = proposalDocsBaseline(changeRoot);
+                // 旧版 accepted 事件的基线可能缺少后来纳入 Propose gate 的材料。保留其已冻结
+                // 的摘要，并用 reopen 当刻的摘要补齐缺项，确保本轮之后对任一审查目标的修改都能被检测。
+                const baselineNeedsBackfill = acceptedBaseline !== null && Object.keys(currentBaseline)
+                    .some(path => !Object.prototype.hasOwnProperty.call(acceptedBaseline, path));
+                const baselineDocs = acceptedBaseline
+                    ? Object.fromEntries(Object.entries(currentBaseline).map(([path, digest]) => [
+                        path,
+                        Object.prototype.hasOwnProperty.call(acceptedBaseline, path) ? acceptedBaseline[path] : digest,
+                    ]))
+                    : currentBaseline;
+                return {
+                    fromState: "accepted",
+                    toState: "propose",
+                    outcome: "advanced",
+                    reason: reason.trim(),
+                    commitPayload: {
+                        reopen_target: "propose",
+                        reopen_source: "accepted",
+                        baseline_source: acceptedBaseline ? (baselineNeedsBackfill ? "accepted_backfill" : "accepted") : "reopen_fallback",
+                        baseline_docs: baselineDocs,
+                    },
+                };
+            }
             if (to !== "apply")
                 return { skip: true, message: `reopen 当前只支持 --to apply 或 --to propose，不支持 ${to}` };
             if (snapshot.state !== "apply_done" && snapshot.state !== "review") {
@@ -767,13 +838,34 @@ export function reviewReady(projectRoot, change, changeRoot, risk = "strict") {
                 };
             }
             if (snapshot.state === "apply_done") {
-                return evaluateApplyDoneCodeReviewGate({
+                const blockingJobs = blockingJobsForApplyDone(projectRoot, events, snapshot);
+                if (blockingJobs.length > 0) {
+                    return {
+                        blocked: true,
+                        reason: `状态未推进；有 ${blockingJobs.length} 个待完成工作项`,
+                        jobs: blockingJobs,
+                    };
+                }
+                const codeReviewDecision = evaluateApplyDoneCodeReviewGate({
                     events,
                     projectRoot,
                     changeRoot,
                     change,
                     policyPayload,
                 });
+                if (!("skip" in codeReviewDecision) &&
+                    !("blocked" in codeReviewDecision) &&
+                    codeReviewDecision.fromState === "apply_done" &&
+                    codeReviewDecision.toState === "review") {
+                    return authorizePhaseAdvance({
+                        projectRoot,
+                        events,
+                        snapshot,
+                        boundary: "apply_to_review",
+                        decision: codeReviewDecision,
+                    });
+                }
+                return codeReviewDecision;
             }
             if (snapshot.state === "review") {
                 return evaluateFinalVerifierGate({
@@ -806,33 +898,7 @@ export function accept(projectRoot, change, changeRoot) {
                 snapshot,
                 mode: { kind: "risk", risk: "strict" },
             });
-            return transitionPlanToDecision(snapshot, changeRoot, change, plan);
-        },
-    });
-}
-// ===== archive =====
-export function archive(projectRoot, change, changeRoot) {
-    return commitTransition(projectRoot, change, changeRoot, {
-        name: "archive", idempotencyInputs: { phase: "archive" },
-        decide: (snapshot) => {
-            if (snapshot.state !== "accepted")
-                return { skip: true, message: `当前状态 ${snapshot.state}，需要 accepted` };
-            // 构建保全清单（Phase 4 简化版：记录文档指纹 + specs/）
-            const manifest = {};
-            const docPaths = ["proposal.md", "tasks.md", "design.md", ".superspec/artifacts/discovery.md", ".superspec/artifacts/business-invariants.md", ".superspec/artifacts/test-contract.md"];
-            for (const p of docPaths) {
-                manifest[p] = sha256File(join(changeRoot, p)) ?? "sha256:missing";
-            }
-            // specs/ 目录：递归收录 .md（覆盖 specs/<capability>/spec.md 布局）
-            const specsDir = join(changeRoot, "specs");
-            for (const rel of listMarkdownFiles(specsDir)) {
-                manifest[`specs/${rel}`] = sha256File(join(specsDir, rel)) ?? "sha256:missing";
-            }
-            return {
-                fromState: "accepted", toState: "archive", outcome: "advanced",
-                reason: "归档完成",
-                extraEvents: [{ type: "artifact_recorded", payload: { kind: "archive_preservation_manifest", manifest } }],
-            };
+            return transitionPlanToDecision(snapshot, changeRoot, change, plan, events);
         },
     });
 }

package/dist/types.d.ts

@@ -8,23 +8,28 @@ 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 {
+export interface ReviewPreviousRejection {
     result_kind: CodeReviewResultKind;
     reason: string;
     job_id: string;
+    findings?: unknown[];
+    findings_job_id?: string;
 }
+export type CodeReviewPreviousRejection = ReviewPreviousRejection;
 export interface Job {
     job_id: string;
     role: JobRole;
     state: JobState;
     gate_id?: ReviewJobGateId;
     boundFiles: Ref[];
+    review_targets?: string[];
+    read_only_refs?: string[];
     review_evidence_digest?: string;
     packet_digest: string;
     packet_context?: JobPacketContext;
     created_from_transition: string;
     created_at: string;
-    previous_rejection?: CodeReviewPreviousRejection;
+    previous_rejection?: ReviewPreviousRejection;
 }
 export interface ExecutionContract {
     tests: string[];
@@ -92,8 +97,10 @@ export interface JobPacket {
     gate_id?: ReviewJobGateId;
     recommended_agent?: string;
     boundFiles: Ref[];
+    review_targets?: string[];
+    read_only_refs?: string[];
     review_evidence_digest?: string;
-    previous_rejection?: CodeReviewPreviousRejection;
+    previous_rejection?: ReviewPreviousRejection;
     packet_context?: JobPacketContext;
     code_review_scope?: CodeReviewScope;
     coverage_exemption_refs?: CoverageExemptionRef[];
@@ -155,6 +162,15 @@ export interface TransitionCommitPayload {
         head?: string | null;
         reason?: "no_code_changes";
     };
+    phase_confirmation?: {
+        boundary: "explore_to_propose" | "propose_to_apply" | "apply_to_review" | "accepted_to_archive";
+        decision: "advance";
+        epoch_event_id: string;
+        material_digest: string;
+        scope: string;
+        decision_event_id: string;
+    };
+    accepted_baseline_docs?: Record<string, string>;
 }
 export interface Snapshot {
     change_id: string;
@@ -207,10 +223,47 @@ export interface MissingInput {
     expected: string;
     command_to_fix: string;
 }
+export type AskUserActionResume = {
+    kind: "next";
+    argv: string[];
+} | {
+    kind: "continue_current_phase";
+    instruction: string;
+    next_argv_after_completion: string[];
+} | {
+    kind: "stop";
+};
+export interface AskUserAction {
+    label: string;
+    selection: "exact_label";
+    reason: "none" | "required" | "optional";
+    reason_prompt?: string;
+    record_argv: string[];
+    record_input: {
+        scope: string;
+        question: string;
+        answer: string;
+        reason?: string;
+    };
+    resume: AskUserActionResume;
+}
 export interface AskUser {
     question: string;
     allowed_answers: string[];
     scope: string;
+    actions?: AskUserAction[];
+}
+export interface AcceptedMaterialFollowupContinuation {
+    kind: "accepted_material_followup";
+    trigger: "material_user_followup";
+    reason_source: "summarize_user_input";
+    reopen_argv_template: string[];
+    resume: {
+        kind: "continue_current_phase";
+        instruction: string;
+        next_argv_after_completion: string[];
+    };
+    plan_docs_changed_since_accept: boolean | null;
 }
 export type NextOutput = {
     state: State;
@@ -230,6 +283,7 @@ export type NextOutput = {
 } | {
     path: "done";
     reason: string;
+    continuation?: AcceptedMaterialFollowupContinuation;
 });
 export interface TransitionResult {
     transition: string;
@@ -243,8 +297,10 @@ export interface TransitionResult {
     details?: Record<string, unknown>;
 }
 export interface RecordResult {
-    event_type: EventType;
+    /** Undefined means the input was rejected before an event was written and may be corrected and resubmitted. */
+    event_type?: EventType;
     accepted: boolean;
     message: string;
     job_state?: JobState;
+    events_written?: number;
 }

package/package.json

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

package/templates/workflow/AGENTS.md

@@ -3,6 +3,8 @@
 
 即使用户没有显式调用 `superspec-*`，如果新输入像是在改变业务规则、产品口径、验收标准、示例规范、影响范围，或说明 PRD/文档/原型等需求源已更新，编辑代码前先提醒并做只读确认：这是实现偏差，还是需要先回 `superspec-propose` 更新计划文档；不要直接把这类自然语言当作 apply 授权。
 
+用户补充 SuperSpec 相关内容时，先确定对应 change，再按 next 返回处理；无法确定时只询问归属，不执行流转。内部命令由主流程完成，不交给用户。
+
 当用户显式调用 `$superspec-explore` 工作流时，视为已明确授权启动 `explore` subagent 做只读深扫；其他 `$superspec-*` 阶段仅在工作流引擎创建独立工作项时，视为授权启动对应 subagent。
 
 SuperSpec 创建的独立审查/验证工作项，视为已授权启动对应 subagent；无需再次询问用户。主会话不得自批这些工作项。

package/templates/workflow/prompts/architect.md

@@ -18,21 +18,22 @@ argument-hint: "本次架构审查说明"
 
 ## 计划 / 设计审查口径
 
-重点判断影响范围、技术决策和任务拆分是否能支撑后续实现，不把文档格式本身当成目标。
-
-- `proposal.md` 的 `## Impact` 应通过 `Area` / `Reason` 说明受影响区域和原因；只有泛目录、没有原因或把 `Area` 当路径白名单，应提出阻塞或风险
-- `design.md` 应记录每个代码影响型需求的实现方向，粒度到路线选择即可；只是复制影响范围、任务清单或代码步骤，说明设计边界不清
-- 关键路线未定且未进入 `## 待用户确认`，或 `tasks.md` 无法从 `design.md` 的方向推出，应判为设计缺口
-- 当 discovery 含 `## 输入数据来源核查` 时，审查 `数据来源` 是否追到目标字段或集合最后一次会改变形态的位置；停在 consumer、validator、DTO 名称或机械一跳上游，应提出阻塞或风险
-- 审查设计是否把输入完整性决策和 consumer 算法决策分开；把“数据是否加载完整”和“如何比较/计算”混成一个决策，应要求拆清
-- 相关 `IDC-xxx` 为 `未知阻塞` 时，设计不得 ready；`未知非阻塞` 必须说明为什么不影响验收，并绑定验收口径或反例
-- 当 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
+重点审查技术方案是否可落地、系统责任边界是否合理、关键设计契约是否充分。文档结构、跨文档登记和 task 格式由 Critic 主责；测试可验证性由 Test Engineer 主责。不要重复报告纯标题、空章节、复述、task ID / 顺序或 TEST 映射格式问题，但发现真实技术影响未登记时仍须直接报告。
+
+- `design.md` 的代码影响型能力应有技术上可行的实现路线，说明方案落在哪个系统责任边界，以及本次实际涉及的数据、接口、状态或控制流如何变化；缺少到实现者无法落地时必须 `verdict:"fail"`
+- 如果不同实现会产生不同的行为、字段组或数据语义、接口增量或兼容结果、状态转换、优先级、一致性、事务 / 幂等 / 并发、恢复结果或关键算法语义，design 必须明确对应绑定性契约；仍需实现者自行选择关键语义时必须失败。逐行代码、完整 SQL，以及以文件修改、task 执行或测试操作为对象的机械清单不属于 design；算法阶段、数据 / 控制流、状态转换和事务顺序可以有序表达
+- discovery / proposal / specs 中影响实现的事实和约束必须转成具体设计安排；只罗列材料、关键约束未进入方案，或方案建立在与已确认事实不符的假设上时，必须 `verdict:"fail"`
+- 声明复用现有链路时，应能确认复用对象、接入位置、本次差异和保持不变的语义；重复上游已有变形、增加双重兜底或改变持久化语义却没有明确理由时，应失败。改变已确认的规则变形或持久化语义时，不仅要说明理由和边界，还必须明确声明为本次目标，并与 proposal、specs 和 Impact 按适用范围完成对账
+- 多个功能点共享字段组、接口语义、状态机、优先级或一致性规则时，应形成统一契约；不同方案对同一契约给出冲突解释时，应失败
+- 关键路线未定且未进入 `## 待用户确认`，或 `tasks.md` 无法从实现方案和边界约束中技术性推出时，必须失败
+- 不按固定章节判定设计质量，也不要要求虚假替代方案或风险；但存在明显误走路线、非显然风险、共享契约、兼容、迁移、回滚或发布顺序约束却完全未说明时，必须失败。只有不影响方案落地和边界判定、但仍值得关注的问题才列为非阻塞风险
+- discovery 含 `## 输入数据来源核查` 时，数据来源必须追到目标字段或集合最后一次改变形态的位置；输入完整性方案与 consumer 获得完整输入后的算法方案必须分开说明
+- `IDC-xxx` 为 `未知阻塞` 时 design 不得 ready；为 `未知非阻塞` 时，理由必须在技术上成立，并绑定验收口径或反例
+- discovery 含 `## 链路五要素` 时，方案不得违背已确认的来源、规则变形、持久化语义、消费者或视图差异；确需重复防御或二次变形时必须说明原因和边界
+- 发现 Impact 未登记的真实系统边界、消费者、视图差异或用户 / 系统可观察行为影响时，应直接判为 Impact / design 对账缺口；纯测试脆弱性和实现复杂度不要求进入 Impact
+- 输入来源修复不得无说明地扩大相邻规则、查询、缓存或数据形态的语义
+- task 的 `设计` 引用应指向技术上可行的实现方案、共享契约或边界约束；`边界` 应保护具体系统行为、数据语义、外部接口或共享规则。引用存在但方案不可行、边界与 design / Impact 冲突或漏掉明显高风险边界时，应失败
+- task 分组应符合系统责任边界；高风险模块、跨入口行为或无法独立验证的大改动，应拆成可独立审查和验证的 task
 
 ## 输出风格