@peterxiaoyang/superspec 0.1.3 → 0.1.5

package/adapters/codex/agents/verifier.toml

@@ -3,117 +3,11 @@ name = "verifier"
 description = "Completion evidence, claim validation, test adequacy"
 model_reasoning_effort = "xhigh"
 developer_instructions = """
-<identity>
-You are Verifier. Prove or disprove completion with direct evidence.
-</identity>
+Role: Verifier. Prove or disprove completion claims with reproducible evidence; missing evidence is not a pass.
 
-<goal>
-Turn claims into reproducible proof or proof gaps by checking code, diffs, commands, diagnostics, tests, artifacts, and acceptance criteria. Missing evidence is a gap, not a pass, and the main thread remains responsible for final adjudication.
-</goal>
+Prompt binding: load `.codex/prompts/verifier.md` first, then read the provided `review-packet` or `prompt_ref`. The packet's refs, output kind, contract fields, review scope, and stop conditions override static prompt memory.
 
-<constraints>
-<scope_guard>
-- Verify claims against observable evidence; do not trust implementation summaries.
-- Distinguish failed behavior from unavailable or missing proof.
-- Prefer fresh command output when available.
-</scope_guard>
+Boundary: read-only. Check commands, test output, diff, artifacts, evidence refs, and acceptance criteria without editing files.
 
-<ask_gate>
-<!-- OMX:GUIDANCE:VERIFIER:CONSTRAINTS:START -->
-- Default reports to outcome-first, evidence-dense verdicts: name the claim, success criteria, validation evidence, gaps, and stop condition before adding process detail.
-- Keep collaboration style direct and concise; do not expand verification scope beyond what materially proves or disproves the claim.
-- For multi-step verification, start with a concise preamble that names the first check; keep intermediate updates brief and evidence-based.
-- AUTO-CONTINUE for clear, already-requested, low-risk, reversible, local inspect-test-verify work; keep inspecting, testing, and verifying without permission handoff.
-- ASK only for destructive, irreversible, credential-gated, external-production, or materially scope-changing actions, or when missing authority blocks progress.
-- On AUTO-CONTINUE branches, do not use permission-handoff phrasing; state the next verification action or evidence-backed verdict.
-- Use absolute language only for true invariants: safety, security, side-effect boundaries, required output fields, workflow state transitions, and product contracts.
-- Keep gathering evidence until the verdict is grounded or blocked by a missing acceptance target or unavailable proof source.
-- If correctness depends on additional tests, diagnostics, or inspection, keep using those tools until the verdict is grounded; stop once enough evidence proves the core claim.
-- More verification effort does not mean unrelated tool churn; gather the proof that matters, not every possible artifact.
-<!-- OMX:GUIDANCE:VERIFIER:CONSTRAINTS:END -->
-- Ask only when the acceptance target is materially unclear and cannot be derived from repo or task history.
-</ask_gate>
-</constraints>
-
-<execution_loop>
-1. State what must be proven.
-2. Inspect relevant files, diffs, outputs, and artifacts.
-3. Run or review the commands that directly prove the claim.
-4. Report proof status, evidence, gaps, risks, and any blocked proof source.
-</execution_loop>
-
-<success_criteria>
-- Acceptance criteria are checked directly.
-- Evidence is concrete and reproducible.
-- Missing proof is called out explicitly.
-- The verdict is grounded and actionable.
-</success_criteria>
-
-<verification_loop>
-<!-- OMX:GUIDANCE:VERIFIER:INVESTIGATION:START -->
-5) If a newer user instruction only changes the current verification target or report shape, apply that override locally without discarding earlier non-conflicting acceptance criteria; preserve traceability from each claim to evidence, validation command, or explicit proof gap.
-<!-- OMX:GUIDANCE:VERIFIER:INVESTIGATION:END -->
-Keep gathering the required evidence until the verdict is grounded or the proof source is unavailable.
-</verification_loop>
-
-<tools>
-Use Read/Grep/Glob for evidence, diagnostics/test/build commands for behavior, and diff/history inspection when scope depends on recent changes.
-</tools>
-
-<style>
-<output_contract>
-## Verdict
-- PASS / FAIL / PARTIAL
-
-## Evidence
-- `command or artifact` — result
-
-## Gaps
-- Missing or inconclusive proof
-
-## Risks
-- Remaining uncertainty or follow-up needed
-</output_contract>
-
-<scenario_handling>
-- If the user says `continue`, keep gathering the required evidence instead of restating a partial verdict.
-- If the user says `merge if CI green`, check relevant statuses, confirm they are green, and report the gate outcome.
-</scenario_handling>
-
-<stop_rules>
-Stop only when the verdict is evidence-backed or the needed proof source/authority is unavailable.
-</stop_rules>
-</style>
-
-<posture_overlay>
-
-You are operating in the frontier-orchestrator posture.
-- Prioritize intent classification before implementation.
-- Default to delegation and orchestration when specialists exist.
-- Treat the first decision as a routing problem: research vs planning vs implementation vs verification.
-- Challenge flawed user assumptions concisely before execution when the design is likely to cause avoidable problems.
-- Preserve explicit executor handoff boundaries: do not absorb deep implementation work when a specialized executor is more appropriate.
-
-</posture_overlay>
-
-<model_class_guidance>
-
-This role is tuned for standard-capability models.
-- Balance autonomy with clear boundaries.
-- Prefer explicit verification and narrow scope control over speculative reasoning.
-
-</model_class_guidance>
-
-<native_subagent_leaf_guard>
-
-Leaf native subagent: do not call Task, spawn_agent, or native child agents.
-Use local tools; report missing specialist coverage to the leader.
-
-</native_subagent_leaf_guard>
-
-## OMX Agent Metadata
-- role: verifier
-- posture: frontier-orchestrator
-- model_class: standard
-- routing_role: leader
+Output: concise Simplified Chinese. State pass, fail, partial, or evidence gap first; list evidence, gaps, residual risk, and stop conditions.
 """

package/dist/src/cli.js

@@ -1,20 +1,33 @@
 import { block, dispatch, GuardError, printDecision, reason } from "./core.js";
 import { emitArgparsePreamble, parse_argv } from "./cli_args.js";
+import { dispatch_packet, is_packet_command } from "./packet_render.js";
+import { printPacket, printPacketError } from "./util.js";
 export function main(argv = process.argv.slice(2)) {
     let args = null;
+    const rawCommand = argv[0] ?? "";
     try {
         const argparseExit = emitArgparsePreamble(argv);
         if (argparseExit !== null)
             return argparseExit;
         args = parse_argv(argv);
+        if (is_packet_command(args.command)) {
+            const result = dispatch_packet(args);
+            printPacket(result.payload, { format: result.output_format });
+            return 0;
+        }
         const [decision] = dispatch(args);
-        printDecision(decision, { command: args.command });
+        printDecision(decision, { command: args.command, format: args.format });
         return decision.allowed ? 0 : 1;
     }
     catch (err) {
+        if ((args && is_packet_command(args.command)) || is_packet_command(rawCommand)) {
+            const errCode = err instanceof GuardError ? "guard_error" : "guard_internal_error";
+            printPacketError(errCode, `${err.message}`);
+            return 2;
+        }
         const change = args?.change ?? "?";
         const errReason = err instanceof GuardError ? reason("guard_error", err.message) : reason("guard_internal_error", `${err.name}: ${err.message}`);
-        printDecision(block(change, "guard_error", [errReason]), { command: args?.command });
+        printDecision(block(change, "guard_error", [errReason]), { command: args?.command, format: args?.format });
         return 2;
     }
 }

package/dist/src/cli_args.d.ts

@@ -1,9 +1,15 @@
+import { type DecisionOutputFormat, type PacketOutputFormat } from "./util.ts";
 export type ParsedArgs = {
     command: string;
     change: string;
+    format?: DecisionOutputFormat;
+    packet_format?: PacketOutputFormat;
     artifact?: string;
     gate?: string;
     task_id?: string;
+    role?: string;
+    evidence_kind?: string;
+    round?: number;
     create?: boolean;
     force_unlock?: boolean;
     rebuild_corrupt?: boolean;

package/dist/src/cli_args.js

@@ -1,4 +1,6 @@
 import { command_zh } from "./i18n.js";
+import { GuardError, parseDecisionOutputFormat, parsePacketOutputFormat } from "./util.js";
+import { normalize_gate } from "./openspec.js";
 const SIMPLE_COMMANDS = [
     "status",
     "recompute",
@@ -18,9 +20,15 @@ const COMMANDS = [
     "check-task-reopen",
     "check-task-edit",
     "check-task-complete",
+    "workflow-packet",
+    "review-packet",
+    "ledger-render",
 ];
 const COMMAND_LIST = COMMANDS.join(",");
 const COMMAND_CHOICES = COMMANDS.map((item) => `'${item}'`).join(", ");
+function isPacketCommand(command) {
+    return command === "workflow-packet" || command === "review-packet" || command === "ledger-render";
+}
 function requiredValueFlags(command) {
     const flags = ["--change"];
     if (command === "check-artifact")
@@ -29,13 +37,42 @@ function requiredValueFlags(command) {
         flags.push("--gate");
     if (command === "check-task-reopen" || command === "check-task-edit" || command === "check-task-complete")
         flags.push("--task-id");
+    if (command === "workflow-packet")
+        flags.push("--gate");
+    if (command === "review-packet")
+        flags.push("--gate", "--role", "--round");
+    if (command === "ledger-render")
+        flags.push("--gate");
     return flags;
 }
 function requiredBooleanFlags(command) {
     return command === "init" ? ["--create"] : [];
 }
 function optionalBooleanFlags(command) {
-    return command === "recompute" ? ["--force-unlock", "--rebuild-corrupt"] : [];
+    if (isPacketCommand(command))
+        return [];
+    return ["--user-facing", ...(command === "recompute" ? ["--force-unlock", "--rebuild-corrupt"] : [])];
+}
+function optionalValueFlags(command) {
+    if (command === "workflow-packet")
+        return ["--task-id"];
+    if (command === "review-packet")
+        return ["--kind"];
+    if (command === "ledger-render")
+        return ["--round"];
+    return [];
+}
+function formatUsage(command) {
+    if (command === "workflow-packet")
+        return "--format {agent}";
+    if (command === "review-packet")
+        return "--format {agent,prompt}";
+    if (command === "ledger-render")
+        return null;
+    return "[--format {json,agent,user}]";
+}
+function requiresFormat(command) {
+    return command === "workflow-packet" || command === "review-packet";
 }
 function rootUsage() {
     return `usage: superspec_guard [-h]\n                     {${COMMAND_LIST}}\n                     ...\n`;
@@ -51,6 +88,8 @@ function commandUsage(command) {
     const usageFlags = [
         "[-h]",
         ...requiredValueFlags(command).map((flag) => `${flag} ${flag.slice(2).replace(/-/g, "_").toUpperCase()}`),
+        ...(formatUsage(command) ? [formatUsage(command)] : []),
+        ...optionalValueFlags(command).map((flag) => `[${flag} ${flag.slice(2).replace(/-/g, "_").toUpperCase()}]`),
         ...requiredBooleanFlags(command),
         ...optionalBooleanFlags(command),
     ];
@@ -66,6 +105,13 @@ function commandHelp(command) {
     for (const flag of requiredBooleanFlags(command)) {
         lines.push(`  ${flag}\n`);
     }
+    const formatToken = formatUsage(command);
+    if (formatToken)
+        lines.push(`  ${formatToken}\n`);
+    for (const flag of optionalValueFlags(command)) {
+        const metavariable = flag.slice(2).replace(/-/g, "_").toUpperCase();
+        lines.push(`  ${flag} ${metavariable}\n`);
+    }
     for (const flag of optionalBooleanFlags(command)) {
         lines.push(`  ${flag}\n`);
     }
@@ -75,7 +121,10 @@ function hasFlag(argv, flag) {
     return argv.includes(flag);
 }
 function missingRequiredFlags(command, args) {
-    return [...requiredValueFlags(command), ...requiredBooleanFlags(command)].filter((flag) => !hasFlag(args, flag));
+    const missing = [...requiredValueFlags(command), ...requiredBooleanFlags(command)].filter((flag) => !hasFlag(args, flag));
+    if (requiresFormat(command) && !hasFlag(args, "--format"))
+        missing.push("--format");
+    return missing;
 }
 export function emitArgparsePreamble(argv) {
     if (argv.length === 0) {
@@ -96,10 +145,12 @@ export function emitArgparsePreamble(argv) {
         process.stdout.write(commandHelp(command));
         return 0;
     }
-    const missing = missingRequiredFlags(command, args);
-    if (missing.length > 0) {
-        process.stderr.write(`${commandUsage(command)}superspec_guard ${command}：错误：缺少必填参数：${missing.join(", ")}\n`);
-        return 2;
+    if (!isPacketCommand(command)) {
+        const missing = missingRequiredFlags(command, args);
+        if (missing.length > 0) {
+            process.stderr.write(`${commandUsage(command)}superspec_guard ${command}：错误：缺少必填参数：${missing.join(", ")}\n`);
+            return 2;
+        }
     }
     return null;
 }
@@ -108,37 +159,112 @@ export function parse_argv(argv) {
         throw new Error("缺少命令");
     const command = argv[0];
     const args = argv.slice(1);
-    const getValue = (flag) => {
-        const idx = args.indexOf(flag);
-        if (idx === -1)
-            return undefined;
-        return args[idx + 1];
+    const getValues = (flag) => {
+        const values = [];
+        for (let idx = 0; idx < args.length; idx += 1) {
+            if (args[idx] !== flag)
+                continue;
+            const value = args[idx + 1];
+            if (value === undefined || value.startsWith("--"))
+                throw new GuardError(`${flag} 缺少取值`);
+            values.push(value);
+        }
+        return values;
     };
+    const getValue = (flag) => getValues(flag)[0];
+    const formatValues = getValues("--format");
+    const isPacketOutputCommand = command === "workflow-packet" || command === "review-packet";
+    const isPacketCommand = isPacketOutputCommand || command === "ledger-render";
+    const selectedPacketFormat = formatValues.length > 0 ? formatValues[formatValues.length - 1] : undefined;
+    if (isPacketOutputCommand) {
+        if (!selectedPacketFormat)
+            throw new GuardError("缺少必填参数 --format");
+        for (const value of formatValues)
+            parsePacketOutputFormat(value, { allowPrompt: command === "review-packet" });
+    }
+    else {
+        for (const value of formatValues)
+            parseDecisionOutputFormat(value);
+    }
+    const selectedFormat = hasFlag(args, "--user-facing")
+        ? "user"
+        : (formatValues.length > 0 ? formatValues[formatValues.length - 1] : "json");
+    const format = isPacketCommand ? undefined : parseDecisionOutputFormat(selectedFormat);
     const change = getValue("--change");
     if (!change)
-        throw new Error("缺少必填参数 --change");
+        throw new (isPacketCommand ? GuardError : Error)("缺少必填参数 --change");
     if (command === "init") {
         if (!hasFlag(args, "--create"))
             throw new Error("缺少必填参数 --create");
-        return { command, change, create: true };
+        return { command, change, format, create: true };
     }
     if (command === "check-artifact") {
         const artifact = getValue("--artifact");
         if (!artifact)
             throw new Error("缺少必填参数 --artifact");
-        return { command, change, artifact };
+        return { command, change, format, artifact };
     }
     if (command === "check-enter") {
         const gate = getValue("--gate");
         if (!gate)
             throw new Error("缺少必填参数 --gate");
-        return { command, change, gate };
+        return { command, change, format, gate };
+    }
+    if (command === "workflow-packet") {
+        const gate = getValue("--gate");
+        if (!gate)
+            throw new GuardError("缺少必填参数 --gate");
+        const normalizedGate = normalize_gate(gate);
+        const taskId = getValue("--task-id");
+        if ((normalizedGate === "task_edit" || normalizedGate === "task_complete" || normalizedGate === "task_reopen") && !taskId) {
+            throw new GuardError("workflow-packet 缺少必填参数 --task-id");
+        }
+        return { command, change, gate, task_id: taskId, packet_format: parsePacketOutputFormat(selectedPacketFormat, { allowPrompt: false }) };
+    }
+    if (command === "review-packet") {
+        const gate = getValue("--gate");
+        const role = getValue("--role");
+        const roundValue = getValue("--round");
+        const evidenceKind = getValue("--kind");
+        if (!gate)
+            throw new GuardError("缺少必填参数 --gate");
+        if (!role)
+            throw new GuardError("缺少必填参数 --role");
+        if (!roundValue)
+            throw new GuardError("缺少必填参数 --round");
+        if (evidenceKind !== undefined && evidenceKind !== "source_guidance" && evidenceKind !== "verification_review") {
+            throw new GuardError("--kind 只允许 source_guidance 或 verification_review");
+        }
+        const round = Number.parseInt(roundValue, 10);
+        if (!Number.isInteger(round) || round < 1)
+            throw new GuardError("--round 必须是大于等于 1 的整数");
+        return {
+            command,
+            change,
+            gate,
+            role,
+            evidence_kind: evidenceKind,
+            round,
+            packet_format: parsePacketOutputFormat(selectedPacketFormat, { allowPrompt: true }),
+        };
+    }
+    if (command === "ledger-render") {
+        const gate = getValue("--gate");
+        const roundValue = getValue("--round");
+        if (!gate)
+            throw new GuardError("缺少必填参数 --gate");
+        if (roundValue === undefined)
+            return { command, change, gate };
+        const round = Number.parseInt(roundValue, 10);
+        if (!Number.isInteger(round) || round < 1)
+            throw new GuardError("--round 必须是大于等于 1 的整数");
+        return { command, change, gate, round };
     }
     if (command === "check-task-reopen" || command === "check-task-edit" || command === "check-task-complete") {
         const taskId = getValue("--task-id");
         if (!taskId)
             throw new Error("缺少必填参数 --task-id");
-        return { command, change, task_id: taskId };
+        return { command, change, format, task_id: taskId };
     }
     const simple = new Set(SIMPLE_COMMANDS);
     if (!simple.has(command))
@@ -146,6 +272,7 @@ export function parse_argv(argv) {
     return {
         command,
         change,
+        format,
         force_unlock: command === "recompute" && hasFlag(args, "--force-unlock"),
         rebuild_corrupt: command === "recompute" && hasFlag(args, "--rebuild-corrupt"),
     };

package/dist/src/gates.d.ts

@@ -1,5 +1,5 @@
 import type { Decision, JsonMap, Reason } from "./util.ts";
-export declare function openspec_init_reasons(repoRoot: string): Reason[];
+export declare function openspec_init_reasons(_repoRoot: string): Reason[];
 export declare function superspec_workflow_skill_reasons(repoRoot: string): Reason[];
 export declare function superspec_agent_reasons(repoRoot: string): Reason[];
 export declare function openspec_cli_capability_reasons(): Reason[];

package/dist/src/gates.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join, relative } from "node:path";
-import { ARTIFACT_ENTER_GATE, MAIN_ADJUDICATION_DECISIONS, REQUEST_CHANGES_ROUTES, NO_TDD_REASONS, OPENSPEC_ARTIFACTS, FINAL_VERIFICATION_ROLES, REQUIRED_SUPERSPEC_AGENT_ROLES, REQUIRED_SUPERSPEC_WORKFLOW_SKILLS, REQUIRED_OPENSPEC_CODEX_SKILLS, REVIEW_GUIDANCE_ROLES, REVIEW_EVIDENCE_REQUIRED_FIELDS, TDD_MODES, VERIFY_EVIDENCE_REQUIRED_FIELDS, allow, block, isObject, reason, renderList, repr, pinned_ref_key, safe_within, sha256_text, runtime, toPosix, } from "./util.js";
+import { ARTIFACT_ENTER_GATE, MAIN_ADJUDICATION_DECISIONS, REQUEST_CHANGES_ROUTES, NO_TDD_REASONS, OPENSPEC_ARTIFACTS, FINAL_VERIFICATION_ROLES, REQUIRED_SUPERSPEC_AGENT_ROLES, REQUIRED_SUPERSPEC_WORKFLOW_SKILLS, REVIEW_GUIDANCE_ROLES, REVIEW_EVIDENCE_REQUIRED_FIELDS, TDD_MODES, VERIFY_EVIDENCE_REQUIRED_FIELDS, allow, block, isObject, reason, renderList, repr, pinned_ref_key, safe_within, sha256_text, runtime, toPosix, } from "./util.js";
 import { all_done, artifact_status_map, get_repo_root, is_done, normalize_gate, openspec_cli_probe } from "./openspec.js";
 import { read_agent_toml_name, read_skill_frontmatter_name, sidecar_business_invariants_path, sidecar_discovery_path, sidecar_test_contract_path } from "./paths.js";
 import { business_invariant_ids, business_invariant_validation_reasons, automated_hard_business_invariant_ids, evidence_invariant_refs, evidence_invariant_ref_reasons, evidence_test_contract_invariant_reasons, human_confirmation_business_invariant_ids, invariant_matrix_coverage_reasons, post_implementation_business_invariant_ids, red_green_invariant_ids, test_contract_invariant_ids, } from "./invariants.js";
@@ -330,24 +330,8 @@ function default_gate_next_actions(gate) {
             return [];
     }
 }
-export function openspec_init_reasons(repoRoot) {
-    const reasons = [];
-    reasons.push(...runtime.openspec_cli_capability_reasons());
-    const skillsRoot = join(repoRoot, ".codex", "skills");
-    const missing = REQUIRED_OPENSPEC_CODEX_SKILLS.filter((name) => !existsSync(join(skillsRoot, name, "SKILL.md")));
-    if (missing.length > 0) {
-        reasons.push(reason("openspec_init_missing", "OpenSpec native Codex skills are missing; run `openspec init --tools codex .` or `openspec update --force .` from the repository root", missing));
-    }
-    for (const name of REQUIRED_OPENSPEC_CODEX_SKILLS) {
-        const skillPath = join(skillsRoot, name, "SKILL.md");
-        if (!existsSync(skillPath))
-            continue;
-        const declared = read_skill_frontmatter_name(skillPath);
-        if (declared !== name) {
-            reasons.push(reason("openspec_native_surface_invalid", `OpenSpec native skill ${skillPath} has invalid front matter name ${repr(declared)}`, [skillPath]));
-        }
-    }
-    return reasons;
+export function openspec_init_reasons(_repoRoot) {
+    return runtime.openspec_cli_capability_reasons();
 }
 // D4 (audit G-2): check-init must notice when SuperSpec's own workflow skills are missing or
 // corrupted, otherwise a deleted .codex/skills/superspec-* surface stays invisible end to end.

package/dist/src/i18n.js

@@ -9,6 +9,9 @@ const COMMAND_ZH = {
     "check-task-reopen": { label_zh: "任务重开检查", hint_zh: "检查被审查打回的任务是否满足重开条件。" },
     "check-task-edit": { label_zh: "任务编辑前检查", hint_zh: "检查任务在开始实现前是否满足测试与范围前置条件。" },
     "check-task-complete": { label_zh: "任务完成检查", hint_zh: "检查任务在勾完成前是否满足 GREEN 或替代验证要求。" },
+    "workflow-packet": { label_zh: "流程数据包", hint_zh: "只读生成当前流程 gate 的紧凑执行数据包。" },
+    "review-packet": { label_zh: "审查数据包", hint_zh: "只读生成审查角色或主线程的最小任务包。" },
+    "ledger-render": { label_zh: "问题清单渲染", hint_zh: "渲染审查轮次的确定性问题清单文本。" },
     "check-review-ready": { label_zh: "进入审查前检查", hint_zh: "检查实现阶段是否已经处理完成，可以进入审查阶段。" },
     "check-review-complete": { label_zh: "审查完成检查", hint_zh: "检查审查阶段证据是否齐备并允许通过。" },
     "check-verify-ready": { label_zh: "验证完成检查", hint_zh: "检查最终验证证据是否完整。" },
@@ -583,10 +586,8 @@ export function action_status_zh(status) {
 }
 export function action_label_zh(action) {
     const exact = {
-        openspec_codex_skills: "检查 OpenSpec 配套技能文件",
+        openspec_cli_surface: "检查 OpenSpec CLI 能力",
         superspec_repo_local_roles: "检查 SuperSpec 本地角色与提示词",
-        "openspec init --tools codex .": "运行 OpenSpec 初始化命令",
-        "openspec update --force .": "运行 OpenSpec 更新命令",
     };
     if (exact[action])
         return exact[action];

package/dist/src/init_cli.d.ts

@@ -1,10 +1,11 @@
-import { runCommand, type OpenspecCliProbe } from "./core.ts";
+import { runCommand, type DecisionOutputFormat, type OpenspecCliProbe } from "./core.ts";
 import { type InstallScope } from "./install_engine.ts";
 type InitArgs = {
     path: string;
     codexHome: string;
     mode: "install" | "update" | "uninstall";
     scope: InstallScope | null;
+    format: DecisionOutputFormat;
     dryRun: boolean;
     force: boolean;
 };

package/dist/src/init_cli.js

@@ -1,4 +1,4 @@
-import { block, commandExists, GuardError, printDecision, reason, runCommand, openspec_cli_probe, REQUIRED_OPENSPEC_MIN_VERSION, } from "./core.js";
+import { block, commandExists, GuardError, printDecision, reason, runCommand, openspec_cli_probe, parseDecisionOutputFormat, REQUIRED_OPENSPEC_MIN_VERSION, } from "./core.js";
 import { forced_openspec_install_plan, project_init, recommended_openspec_install_plan } from "./project_init.js";
 import { install_workflow, uninstall_workflow, update_workflow } from "./install_engine.js";
 import { homedir } from "node:os";
@@ -6,21 +6,25 @@ import { resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { system_failure_zh } from "./i18n.js";
 function usage() {
-    return "usage: superspec init [-h] [--scope {project,user}] [--path PATH] [--codex-home PATH] [--create] [--update] [--uninstall] [--dry-run] [--force]\n";
+    return "usage: superspec init [-h] [--scope {project,user}] [--path PATH] [--codex-home PATH] [--format {json,agent,user}] [--create] [--update] [--uninstall] [--dry-run] [--force]\n";
 }
 function help() {
-    return `${usage()}\n可选参数：\n  -h, --help             显示帮助并退出\n  --scope {project,user} 安装到当前项目的 .codex 目录，或安装到用户级 Codex 目录（默认：project）\n  --project              等价于 --scope project\n  --user                 等价于 --scope user\n  --global               兼容别名，等价于 --user\n  --path PATH            --scope project 时使用的项目根目录（默认：当前目录）\n  --codex-home PATH      --scope user 时使用的 Codex 用户目录（默认：$CODEX_HOME 或 ~/.codex）\n  --create               兼容参数；init 默认就会创建缺失内容\n  --update               按 manifest 更新 SuperSpec 管理的文件；用户改动文件保留，新的版本写入 *.new\n  --uninstall            按 manifest 卸载 SuperSpec 管理的文件；.superspec 数据与既有/用户改动文件会保留\n  --dry-run              配合 --uninstall 时只预览将删除的文件，不实际修改\n  --force                安装时覆盖已有且内容不同的文件，并保留 *.bak 备份\n`;
+    return `${usage()}\n可选参数：\n  -h, --help             显示帮助并退出\n  --scope {project,user} 安装到当前项目的 .codex 目录，或安装到用户级 Codex 目录（默认：project）\n  --project              等价于 --scope project\n  --user                 等价于 --scope user\n  --global               兼容别名，等价于 --user\n  --path PATH            --scope project 时使用的项目根目录（默认：当前目录）\n  --codex-home PATH      --scope user 时使用的 Codex 用户目录（默认：$CODEX_HOME 或 ~/.codex）\n  --format {json,agent,user} 输出格式；json 用于诊断，agent/user 用于安全展示\n  --user-facing          等价于 --format user\n  --create               兼容参数；init 默认就会创建缺失内容\n  --update               按 manifest 更新 SuperSpec 管理的文件；用户改动文件保留，新的版本写入 *.new\n  --uninstall            按 manifest 卸载 SuperSpec 管理的文件；.superspec 数据与既有/用户改动文件会保留\n  --dry-run              配合 --uninstall 时只预览将删除的文件，不实际修改\n  --force                安装时覆盖已有且内容不同的文件，并保留 *.bak 备份\n`;
 }
 function parse_init_argv(argv) {
-    const getValue = (flag) => {
-        const idx = argv.indexOf(flag);
-        if (idx === -1)
-            return undefined;
-        const value = argv[idx + 1];
-        if (value === undefined || value.startsWith("--"))
-            throw new GuardError(`${flag} 缺少取值`);
-        return value;
+    const getValues = (flag) => {
+        const values = [];
+        for (let idx = 0; idx < argv.length; idx += 1) {
+            if (argv[idx] !== flag)
+                continue;
+            const value = argv[idx + 1];
+            if (value === undefined || value.startsWith("--"))
+                throw new GuardError(`${flag} 缺少取值`);
+            values.push(value);
+        }
+        return values;
     };
+    const getValue = (flag) => getValues(flag)[0];
     const update = argv.includes("--update");
     const uninstall = argv.includes("--uninstall");
     if (update && uninstall)
@@ -36,11 +40,19 @@ function parse_init_argv(argv) {
         scope = "user";
     if (argv.includes("--project"))
         scope = "project";
+    const formatValues = getValues("--format");
+    for (const value of formatValues)
+        parseDecisionOutputFormat(value);
+    const selectedFormat = argv.includes("--user-facing")
+        ? "user"
+        : (formatValues.length > 0 ? formatValues[formatValues.length - 1] : "json");
+    const format = parseDecisionOutputFormat(selectedFormat);
     return {
         path: resolve(getValue("--path") ?? process.cwd()),
         codexHome: resolve(getValue("--codex-home") ?? process.env.CODEX_HOME ?? joinHomeCodex()),
         mode: uninstall ? "uninstall" : update ? "update" : "install",
         scope,
+        format,
         dryRun: argv.includes("--dry-run"),
         force: argv.includes("--force"),
     };
@@ -149,7 +161,7 @@ function openspecPreflightBlocked(args, scope, installResult) {
         project_root: args.path,
         install_scope: scope,
         install_root: targetRoot,
-    }, { command: "init" });
+    }, { command: "init", format: args.format });
     return 1;
 }
 function run_init(args, scope) {
@@ -176,16 +188,17 @@ function run_init(args, scope) {
     }
     summary.install_scope = scope;
     summary.install_root = targetRoot;
-    printDecision(summary, { command: "init" });
+    printDecision(summary, { command: "init", format: args.format });
     return summary.allowed ? 0 : 1;
 }
 export function main_init(argv = process.argv.slice(2)) {
+    let args = null;
     try {
         if (argv.includes("-h") || argv.includes("--help")) {
             process.stdout.write(help());
             return 0;
         }
-        const args = parse_init_argv(argv);
+        args = parse_init_argv(argv);
         const scope = args.scope ?? "project";
         const openspecInstall = maybe_install_missing_openspec({ cwd: args.path, scope, mode: args.mode });
         if (openspecInstall === "failed" || openspecInstall === "skipped")
@@ -195,17 +208,18 @@ export function main_init(argv = process.argv.slice(2)) {
     catch (err) {
         const change = "project";
         const errReason = err instanceof GuardError ? reason("guard_error", err.message) : reason("guard_internal_error", `${err.name}: ${err.message}`);
-        printDecision(block(change, "guard_error", [errReason]), { command: "init" });
+        printDecision(block(change, "guard_error", [errReason]), { command: "init", format: args?.format });
         return 2;
     }
 }
 export async function main_init_async(argv = process.argv.slice(2)) {
+    let args = null;
     try {
         if (argv.includes("-h") || argv.includes("--help")) {
             process.stdout.write(help());
             return 0;
         }
-        const args = parse_init_argv(argv);
+        args = parse_init_argv(argv);
         const scope = args.scope ?? (canPrompt() ? await promptInstallScope() : "project");
         const openspecInstall = maybe_install_missing_openspec({ cwd: args.path, scope, mode: args.mode });
         if (openspecInstall === "failed" || openspecInstall === "skipped")
@@ -215,7 +229,7 @@ export async function main_init_async(argv = process.argv.slice(2)) {
     catch (err) {
         const change = "project";
         const errReason = err instanceof GuardError ? reason("guard_error", err.message) : reason("guard_internal_error", `${err.name}: ${err.message}`);
-        printDecision(block(change, "guard_error", [errReason]), { command: "init" });
+        printDecision(block(change, "guard_error", [errReason]), { command: "init", format: args?.format });
         return 2;
     }
 }