@peterxiaoyang/superspec 0.1.44 → 0.1.46

package/dist/install.js

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { SUPERSPEC_VERSION } from "./version.js";
+import { DEFAULT_WORKFLOW_RISK, WORKFLOW_CONFIG_PATH } from "./workflow_config.js";
 export const WORKFLOW_SKILLS = [
     "superspec-explore",
     "superspec-propose",
@@ -247,6 +248,16 @@ function ensureOpenSpecChineseContext(projectRoot) {
     writeFileSync(configPath, next);
     return OPENSPEC_CONFIG_PATH;
 }
+function ensureWorkflowConfig(projectRoot) {
+    const configPath = join(projectRoot, WORKFLOW_CONFIG_PATH);
+    mkdirSync(dirname(configPath), { recursive: true });
+    if (!existsSync(configPath)) {
+        // install/update 是显式迁移动作：为以后各轮写入 normal 默认值。
+        // 未执行安装的旧项目仍由 workflowRiskForProject 保守回放 strict。
+        writeFileSync(configPath, JSON.stringify({ workflow: { mode: DEFAULT_WORKFLOW_RISK } }, null, 2) + "\n");
+    }
+    return WORKFLOW_CONFIG_PATH;
+}
 const AGENTS_MD_PATH = "AGENTS.md";
 const SUPERSPEC_AGENTS_START = "<!-- SUPERSPEC:AGENTS:START -->";
 const SUPERSPEC_AGENTS_END = "<!-- SUPERSPEC:AGENTS:END -->";
@@ -304,6 +315,7 @@ export function installProject(projectRoot, options = {}) {
             prompts: copyPrompts(templateRoot, projectRoot),
             agents: copyAgents(templateRoot, projectRoot),
             config: ensureCodexConfig(projectRoot),
+            workflow_config: ensureWorkflowConfig(projectRoot),
             agents_md: ensureAgentsMd(projectRoot, agentsMdTemplate),
             openspec_config: ensureOpenSpecChineseContext(projectRoot),
         },

package/dist/next.d.ts

@@ -1,3 +1,3 @@
 import type { NextOutput } from "./types.ts";
 /** next 命令：读 snapshot，返回唯一可执行路径 */
-export declare function next(projectRoot: string, change: string, changeRoot: string, defaultRisk?: "minimal" | "normal" | "strict"): NextOutput;
+export declare function next(projectRoot: string, change: string, changeRoot: string, defaultRisk?: import("./review.ts").ReviewRisk): NextOutput;

package/dist/next.js

@@ -3,6 +3,7 @@ import { rebuildSnapshot } from "./sync.js";
 import { readEvents } from "./store.js";
 import { requiredJobActions } from "./job_action.js";
 import { planNextStep } from "./phase_plan.js";
+import { workflowRiskForProject } from "./workflow_config.js";
 function requiredJobsOutput(state, change, jobs, reason) {
     return {
         state,
@@ -14,12 +15,6 @@ function requiredJobsOutput(state, change, jobs, reason) {
 function transitionCommand(change, name, extra = "") {
     return `superspec transition ${name} --change "${change}"${extra ? " " + extra : ""}`;
 }
-function riskFlag(risk) {
-    return risk === "strict" ? "" : `--risk ${risk}`;
-}
-function riskArg(risk) {
-    return risk ? riskFlag(risk) : "";
-}
 function formatTransitionArgs(plan) {
     if (plan.taskId)
         return `--task ${plan.taskId}`;
@@ -32,7 +27,7 @@ function formatTransitionArgs(plan) {
     if (plan.reopen?.reason === "review_finding") {
         return `--to propose --review-finding ${plan.reopen.jobId}#${plan.reopen.findingId} --reason "根据代码审查问题 ${plan.reopen.findingId} 回到计划阶段"`;
     }
-    return riskArg(plan.risk);
+    return "";
 }
 function toNextOutput(change, plan) {
     switch (plan.kind) {
@@ -58,7 +53,7 @@ function toNextOutput(change, plan) {
     }
 }
 /** next 命令：读 snapshot，返回唯一可执行路径 */
-export function next(projectRoot, change, changeRoot, defaultRisk = "strict") {
+export function next(projectRoot, change, changeRoot, defaultRisk = workflowRiskForProject(projectRoot)) {
     const snapshot = rebuildSnapshot(projectRoot, change, changeRoot);
     const events = readEvents(projectRoot, change);
     const plannedNextStep = planNextStep({ projectRoot, change, changeRoot, events, snapshot, mode: { kind: "risk", risk: defaultRisk } });

package/dist/openspec.d.ts

@@ -4,6 +4,19 @@ export interface OpenSpecProbe {
     changeExists: boolean;
     error?: string;
 }
+export interface OpenSpecStrictValidation {
+    /** 调用方已经按冻结 profile 决定是否执行 strict validation。 */
+    checked: boolean;
+    ok: boolean;
+    message: string;
+}
 export declare function probeOpenSpec(projectRoot: string, change?: string): OpenSpecProbe;
 export declare function openspecStatus(projectRoot: string, change: string): string;
+/**
+ * 计划阶段的原生 OpenSpec 结构 gate。
+ *
+ * 调用方已通过冻结的 planning profile 确认应执行 strict validation。这里不再
+ * 读取实时 config.yaml，避免计划就绪后环境变化导致准入标准漂移。
+ */
+export declare function validateOpenSpecChange(projectRoot: string, change: string): OpenSpecStrictValidation;
 export declare function changeRoot(projectRoot: string, change: string): string;

package/dist/openspec.js

@@ -36,6 +36,34 @@ export function openspecStatus(projectRoot, change) {
         return "sha256:unknown";
     }
 }
+/**
+ * 计划阶段的原生 OpenSpec 结构 gate。
+ *
+ * 调用方已通过冻结的 planning profile 确认应执行 strict validation。这里不再
+ * 读取实时 config.yaml，避免计划就绪后环境变化导致准入标准漂移。
+ */
+export function validateOpenSpecChange(projectRoot, change) {
+    validateChange(change);
+    try {
+        execFileSync("openspec", ["validate", change, "--type", "change", "--strict", "--no-interactive"], {
+            cwd: projectRoot,
+            encoding: "utf8",
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        return { checked: true, ok: true, message: "OpenSpec 原生结构校验通过" };
+    }
+    catch (error) {
+        const failure = error;
+        const stdout = typeof failure.stdout === "string" ? failure.stdout : failure.stdout?.toString("utf8") ?? "";
+        const stderr = typeof failure.stderr === "string" ? failure.stderr : failure.stderr?.toString("utf8") ?? "";
+        const detail = [stdout, stderr].map(value => value.trim()).filter(Boolean).join("；");
+        return {
+            checked: true,
+            ok: false,
+            message: `OpenSpec strict 校验失败${detail ? `：${detail}` : "；请确认 openspec CLI 可用并修复 proposal/specs 结构"}`,
+        };
+    }
+}
 export function changeRoot(projectRoot, change) {
     return join(projectRoot, "openspec", "changes", change);
 }

package/dist/phase_confirmation.d.ts

@@ -20,7 +20,13 @@ export interface PhaseConfirmationDecision {
     scope: string;
     answer: string;
     decision: PhaseDecision;
+    review_risk: ReviewRisk;
 }
+/**
+ * 阶段确认不是 mode 的输入。它只读取当前 planning/apply round 的冻结快照；
+ * 仍处于 Explore/Propose 时才从项目配置获取候选 mode。
+ */
+export declare function workflowRiskForPhaseConfirmation(projectRoot: string, events: Event[], snapshot: Snapshot): ReviewRisk;
 export declare function isPhaseConfirmationScope(value: unknown): value is string;
 export declare function phaseConfirmationForBoundary(projectRoot: string, events: Event[], snapshot: Snapshot, boundary: PhaseBoundary, risk?: ReviewRisk): PhaseConfirmation | null;
 export declare function phaseConfirmationForCurrentState(projectRoot: string, events: Event[], snapshot: Snapshot, risk?: ReviewRisk): PhaseConfirmation | null;

package/dist/phase_confirmation.js

@@ -3,6 +3,7 @@ import { historicalProposeReadyRoles, reviewEvidenceDigest, reviewGateRoleResolu
 import { EXPLORE_DISCOVERY_REVIEW_GATE, PROPOSE_FINAL_REVIEW_GATE } from "./review_job_gates.js";
 import { changeRoot as openspecChangeRoot } from "./openspec.js";
 import { findLatestEvent, sha256Text } from "./store.js";
+import { hasFrozenWorkflowModeForProposeRound, workflowRiskForProject, workflowRiskForState, } from "./workflow_config.js";
 export const PHASE_CONFIRMATION_SCOPE_PREFIX = "phase_confirmation:";
 function latestTransition(events, predicate) {
     return findLatestEvent(events, "transition_commit", event => predicate(event.payload));
@@ -25,7 +26,7 @@ const SPECS = {
             },
         ],
         scopePrefix: `${PHASE_CONFIRMATION_SCOPE_PREFIX}explore_to_propose`,
-        epoch: events => latestTransition(events, payload => payload.from_state === "init" && payload.to_state === "explore"),
+        epoch: events => latestTransition(events, payload => payload.to_state === "explore" && payload.from_state !== "explore"),
     },
     propose_to_apply: {
         state: "propose_ready",
@@ -66,9 +67,18 @@ function boundaryForState(state) {
     }
 }
 function ordinaryReviewRolesForBoundary(events, boundary, gate, risk) {
-    return boundary === "propose_to_apply"
-        ? historicalProposeReadyRoles(events)
-        : gate.requiredRolesForRisk(risk);
+    // 历史 plan 没有冻结 mode，当时的 gate 只能按实际创建过的角色回放。
+    if (boundary === "propose_to_apply" && !hasFrozenWorkflowModeForProposeRound(events)) {
+        return historicalProposeReadyRoles(events);
+    }
+    return gate.requiredRolesForRisk(risk);
+}
+/**
+ * 阶段确认不是 mode 的输入。它只读取当前 planning/apply round 的冻结快照；
+ * 仍处于 Explore/Propose 时才从项目配置获取候选 mode。
+ */
+export function workflowRiskForPhaseConfirmation(projectRoot, events, snapshot) {
+    return workflowRiskForState(events, snapshot.state, workflowRiskForProject(projectRoot));
 }
 function materialDigest(projectRoot, events, snapshot, boundary, risk) {
     const head = currentGitHead(projectRoot);
@@ -105,6 +115,7 @@ function materialDigest(projectRoot, events, snapshot, boundary, risk) {
             .sort((left, right) => `${left.gate_id}\u0000${left.role}\u0000${left.job_id}`.localeCompare(`${right.gate_id}\u0000${right.role}\u0000${right.job_id}`))
         : [];
     return sha256Text(JSON.stringify({
+        review_risk: risk,
         documents,
         tasks_structure_digest: snapshot.tasks_structure_digest,
         accepted_jobs: acceptedJobs,
@@ -121,14 +132,13 @@ function materialDigest(projectRoot, events, snapshot, boundary, risk) {
 function phaseRecordArgv(change) {
     return ["superspec", "record", "user-decision", "--change", change, "--input", "-"];
 }
-function nextArgv(change, risk) {
+function nextArgv(change, _risk) {
     return [
         "superspec",
         "transition",
         "next",
         "--change",
         change,
-        ...(risk === "strict" ? [] : ["--risk", risk]),
     ];
 }
 function buildActions(change, boundary, scope, question, specs, risk) {
@@ -220,6 +230,11 @@ export function latestAcceptedPhaseDecision(events, confirmation) {
         scope: confirmation.scope,
         answer: payload.answer,
         decision: payload.phase_confirmation.decision,
+        review_risk: payload.phase_confirmation.review_risk === "minimal" ||
+            payload.phase_confirmation.review_risk === "normal" ||
+            payload.phase_confirmation.review_risk === "strict"
+            ? payload.phase_confirmation.review_risk
+            : "strict",
     };
 }
 export function isPhaseAdvanceAuthorized(events, confirmation) {
@@ -237,6 +252,7 @@ export function phaseConfirmationCommitPayload(confirmation, decision) {
             material_digest: confirmation.material_digest,
             scope: confirmation.scope,
             decision_event_id: decision.event.event_id,
+            review_risk: decision.review_risk,
         },
     };
 }

package/dist/phase_plan.d.ts

@@ -1,5 +1,5 @@
 import type { ReviewGateRule } from "./review_job_gates.ts";
-import type { AcceptedMaterialFollowupContinuation, AskUser, Event, Job, JobRole, State } from "./types.ts";
+import type { AcceptedMaterialFollowupContinuation, AskUser, Event, ExecutionPolicy, Job, JobRole, PlanningValidationProfile, State } from "./types.ts";
 import type { Snapshot } from "./types.ts";
 import type { ReviewRisk } from "./review.ts";
 export type TransitionName = "explore" | "propose-ready" | "start-apply" | "task-start" | "task-complete" | "review-ready" | "reopen" | "accept";
@@ -83,11 +83,20 @@ export interface ApplyPendingTaskStatus {
     needsCompletionEvent: string[];
     completedByEvent: string[];
 }
+export declare function executionPolicyForRisk(risk: ReviewRisk): ExecutionPolicy;
+export declare function executionPolicyForCurrentRound(events: Event[]): ExecutionPolicy;
 export declare function proposalDocsBaseline(changeRoot: string): Record<string, string>;
+export declare function discoveryDocsBaseline(changeRoot: string): Record<string, string>;
 export declare function latestAcceptedProposalBaseline(events: Event[]): Record<string, string> | null;
 export declare function latestReopenProposeBaseline(events: Event[]): Record<string, string> | null;
+export declare function latestReopenExploreBaseline(events: Event[]): Record<string, string> | null;
 export declare function proposalDocsChangedSinceBaseline(changeRoot: string, baseline: Record<string, string>): boolean;
+export declare function discoveryDocsChangedSinceBaseline(changeRoot: string, baseline: Record<string, string>): boolean;
 export declare function pendingTaskIds(changeRoot: string): string[];
+/** 当前 Apply round 的规则版本；缺失版本的历史 event 保持 v1 回放。 */
+export declare function executionRequirementVersionForCurrentRound(events: Event[]): 1 | 2;
+/** 新 planning round 在进入 propose 时冻结当前 OpenSpec 校验契约。 */
+export declare function planningValidationProfileForNewRound(projectRoot: string): PlanningValidationProfile;
 export declare function applyRequirementModeForCurrentRound(events: Event[]): boolean;
 export declare function pendingTaskStatusForApply(changeRoot: string, events: Event[]): ApplyPendingTaskStatus;
 export declare function formatPendingTaskMessage(ids: string[], action: string): string;