@peterxiaoyang/superspec 0.1.3 → 0.1.4

package/dist/src/cli.js

@@ -8,13 +8,13 @@ export function main(argv = process.argv.slice(2)) {
             return argparseExit;
         args = parse_argv(argv);
         const [decision] = dispatch(args);
-        printDecision(decision, { command: args.command });
+        printDecision(decision, { command: args.command, format: args.format });
         return decision.allowed ? 0 : 1;
     }
     catch (err) {
         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,6 +1,8 @@
+import { type DecisionOutputFormat } from "./util.ts";
 export type ParsedArgs = {
     command: string;
     change: string;
+    format?: DecisionOutputFormat;
     artifact?: string;
     gate?: string;
     task_id?: string;

package/dist/src/cli_args.js

@@ -1,4 +1,5 @@
 import { command_zh } from "./i18n.js";
+import { GuardError, parseDecisionOutputFormat } from "./util.js";
 const SIMPLE_COMMANDS = [
     "status",
     "recompute",
@@ -35,7 +36,7 @@ function requiredBooleanFlags(command) {
     return command === "init" ? ["--create"] : [];
 }
 function optionalBooleanFlags(command) {
-    return command === "recompute" ? ["--force-unlock", "--rebuild-corrupt"] : [];
+    return ["--user-facing", ...(command === "recompute" ? ["--force-unlock", "--rebuild-corrupt"] : [])];
 }
 function rootUsage() {
     return `usage: superspec_guard [-h]\n                     {${COMMAND_LIST}}\n                     ...\n`;
@@ -51,6 +52,7 @@ function commandUsage(command) {
     const usageFlags = [
         "[-h]",
         ...requiredValueFlags(command).map((flag) => `${flag} ${flag.slice(2).replace(/-/g, "_").toUpperCase()}`),
+        "[--format {json,agent,user}]",
         ...requiredBooleanFlags(command),
         ...optionalBooleanFlags(command),
     ];
@@ -66,6 +68,7 @@ function commandHelp(command) {
     for (const flag of requiredBooleanFlags(command)) {
         lines.push(`  ${flag}\n`);
     }
+    lines.push("  --format {json,agent,user}\n");
     for (const flag of optionalBooleanFlags(command)) {
         lines.push(`  ${flag}\n`);
     }
@@ -108,37 +111,51 @@ 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");
+    for (const value of formatValues)
+        parseDecisionOutputFormat(value);
+    const selectedFormat = hasFlag(args, "--user-facing")
+        ? "user"
+        : (formatValues.length > 0 ? formatValues[formatValues.length - 1] : "json");
+    const format = parseDecisionOutputFormat(selectedFormat);
     const change = getValue("--change");
     if (!change)
         throw new 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 === "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 +163,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/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;
     }
 }

package/dist/src/util.d.ts

@@ -39,6 +39,8 @@ export type Decision = {
     trust_warnings_zh?: string[];
     workflow_terms_zh?: WorkflowTermHint[];
 };
+export type DecisionOutputFormat = "json" | "agent" | "user";
+export type AgentWorkflowAction = "continue" | "fix_artifacts" | "ask_user_confirmation" | "collect_review_evidence" | "collect_test_evidence" | "repair_evidence" | "rerun_check" | "inspect_diagnostics";
 export type TaskInfo = {
     task_id: string;
     checked: boolean;
@@ -82,6 +84,7 @@ export declare const GATE_ROUTE: Record<string, string>;
 export declare class GuardError extends Error {
 }
 export declare const runtime: JsonMap;
+export declare function parseDecisionOutputFormat(raw: string): DecisionOutputFormat;
 export declare function reason(code: string, message: string, refs?: string[] | null): Reason;
 export declare function pinned_ref_key(item: JsonMap): string;
 export declare function trustWarnings(): string[];
@@ -99,8 +102,16 @@ export declare function block(change: string, gate: string, reasons: Reason[], o
 export declare function decorateDecision(decision: JsonMap, opts?: {
     command?: string;
 }): JsonMap;
+export declare function workflowActionForReasonCodes(reasonCodes: string[], allowed?: boolean): AgentWorkflowAction;
+export declare function renderAgentDecision(decision: JsonMap, opts?: {
+    command?: string;
+}): JsonMap;
+export declare function renderUserFacingDecision(decision: JsonMap, opts?: {
+    command?: string;
+}): string;
 export declare function printDecision(decision: JsonMap, opts?: {
     command?: string;
+    format?: DecisionOutputFormat;
 }): void;
 export declare function runCommand(cmd: string, args: string[], opts?: {
     cwd?: string;

package/dist/src/util.js

@@ -236,6 +236,11 @@ export const GATE_ROUTE = {
 export class GuardError extends Error {
 }
 export const runtime = {};
+export function parseDecisionOutputFormat(raw) {
+    if (raw === "json" || raw === "agent" || raw === "user")
+        return raw;
+    throw new GuardError("--format 只允许 json、agent 或 user");
+}
 export function reason(code, message, refs = null) {
     const zh = reason_zh(code);
     return { code, message, refs: refs ?? [], label_zh: zh.label_zh, hint_zh: zh.hint_zh };
@@ -370,8 +375,217 @@ function sanitizeDecisionForOutput(decision) {
         actions,
     };
 }
+function userFacingLine(value) {
+    return String(value ?? "").replace(/\s+/gu, " ").trim();
+}
+const SAFE_TEXT_REPLACEMENTS = [
+    [/\bneeds_user_decision_pending\b/giu, "等待用户确认"],
+    [/\bneeds_user_decision\b/giu, "等待用户确认"],
+    [/\buser_review_decision\b/giu, "用户确认记录"],
+    [/\bmain_review_digest\b/giu, "审查问题记录"],
+    [/\breview_standing_authorization\b/giu, "长期授权记录"],
+    [/\bdecision_scope_key\b/giu, "确认范围"],
+    [/\bfinding_uid\b/giu, "问题标识"],
+    [/\bexport\s+function\s+[A-Za-z_$][\w$]*\s*\([^)]*\)/gu, "内部实现细节"],
+    [/\bfunction\s+[A-Za-z_$][\w$]*\s*\([^)]*\)/gu, "内部实现细节"],
+    [/\b[A-Za-z_$][\w$]*\s*\([^)]*\)/gu, "内部调用细节"],
+    [/裁决/gu, "确认"],
+];
+function safeDisplayText(value) {
+    let out = userFacingLine(value);
+    for (const [pattern, replacement] of SAFE_TEXT_REPLACEMENTS)
+        out = out.replace(pattern, replacement);
+    return out;
+}
+function fallbackReasonForWorkflowAction(action) {
+    const fallbacks = {
+        continue: "当前检查已通过。",
+        ask_user_confirmation: "需要用户确认后才能继续。",
+        collect_review_evidence: "需要补齐审查或验证复核记录。",
+        collect_test_evidence: "需要补齐测试或校验证据。",
+        fix_artifacts: "需要修正方案、任务或证据结构。",
+        repair_evidence: "需要修复证据记录。",
+        rerun_check: "需要重新运行当前检查。",
+        inspect_diagnostics: "需要查看诊断输出后处理。",
+    };
+    return fallbacks[action];
+}
+function safeReasonText(_item, action = "inspect_diagnostics") {
+    return fallbackReasonForWorkflowAction(action);
+}
+const WORKFLOW_ACTION_BY_REASON = [
+    [new Set([
+            "needs_user_decision_pending",
+            "user_decision_unbound",
+            "missing_review_digest",
+            "missing_human_confirmation",
+            "apply_isolation_unconfirmed",
+            "scope_expansion_unconfirmed",
+            "finding_unresolved",
+            "round_budget_exhausted",
+        ]), "ask_user_confirmation"],
+    [new Set([
+            "missing_source_guidance",
+            "missing_verification_review",
+            "missing_final_verification_review",
+            "missing_roles",
+            "missing_native_subagent_evidence",
+            "missing_invariant_review",
+            "missing_test_contract_review",
+            "missing_architect_review",
+            "missing_critic_review",
+            "missing_test-engineer_review",
+            "missing_code-reviewer_review",
+            "missing_verifier_review",
+            "missing_main_adjudication",
+            "proposal_reviewed_failed",
+            "review_not_ready",
+            "missing_proposal_review",
+        ]), "collect_review_evidence"],
+    [new Set([
+            "missing_red_evidence",
+            "missing_green_evidence",
+            "missing_characterization",
+            "test_contract_not_honored",
+            "validate_failed",
+            "missing_final_tests",
+            "verify_failure_unconfirmed",
+        ]), "collect_test_evidence"],
+    [new Set([
+            "missing_discovery",
+            "missing_proposal",
+            "missing_design",
+            "missing_tasks",
+            "invalid_task_graph",
+            "invalid_business_invariants",
+            "review_finding_invalid",
+            "review_digest_invalid",
+            "user_decision_invalid",
+            "human_confirmation_invalid",
+            "standing_authorization_invalid",
+            "evidence_unknown_kind",
+            "evidence_missing_field",
+            "artifact_update_required",
+            "rereview_required",
+        ]), "fix_artifacts"],
+    [new Set([
+            "state_concurrent_update",
+            "state_fingerprint_stale",
+        ]), "rerun_check"],
+    [new Set([
+            "state_corrupt",
+            "openspec_cli_unavailable",
+            "openspec_native_surface_missing",
+            "dirty_worktree_unavailable",
+            "guard_error",
+            "guard_internal_error",
+            "unknown_gate",
+            "unknown_artifact",
+            "not_openspec_artifact",
+        ]), "inspect_diagnostics"],
+];
+export function workflowActionForReasonCodes(reasonCodes, allowed = false) {
+    if (allowed)
+        return "continue";
+    const codes = new Set(reasonCodes);
+    for (const [matches, action] of WORKFLOW_ACTION_BY_REASON) {
+        for (const code of matches) {
+            if (codes.has(code))
+                return action;
+        }
+    }
+    return "inspect_diagnostics";
+}
+function summaryForWorkflowAction(action, allowed) {
+    if (allowed || action === "continue")
+        return "当前检查已通过，可以继续下一步。";
+    const summaries = {
+        ask_user_confirmation: "当前阶段需要用户确认一个范围或处理方式选择后才能继续。",
+        collect_review_evidence: "当前阶段缺少必要审查或验证复核记录，补齐后再继续。",
+        collect_test_evidence: "当前阶段缺少测试或校验证据，补齐后再继续。",
+        fix_artifacts: "当前阶段的方案、任务或证据结构需要修正后再继续。",
+        repair_evidence: "当前证据记录需要修复后再继续。",
+        rerun_check: "当前检查需要在输入稳定后重新运行。",
+        inspect_diagnostics: "当前检查需要查看诊断输出后处理。",
+    };
+    return summaries[action];
+}
+function nextStepsForWorkflowAction(action, allowed) {
+    if (allowed || action === "continue")
+        return ["继续执行下一步。"];
+    const steps = {
+        ask_user_confirmation: ["向用户展示待确认的问题与选项，记录选择后重新运行检查。"],
+        collect_review_evidence: ["补齐所需审查或验证复核记录，然后重新运行检查。"],
+        collect_test_evidence: ["补齐失败/通过测试或校验证据，然后重新运行检查。"],
+        fix_artifacts: ["修正相关方案、任务或证据结构，然后重新运行检查。"],
+        repair_evidence: ["修复证据记录中的结构或引用问题，然后重新运行检查。"],
+        rerun_check: ["等待输入稳定后重新运行当前检查。"],
+        inspect_diagnostics: ["使用诊断输出查看内部细节，再按对应问题处理。"],
+    };
+    return steps[action];
+}
+const DIAGNOSTIC_HINT = "需要排查内部细节时使用 --format json。";
+export function renderAgentDecision(decision, opts = {}) {
+    const decorated = sanitizeDecisionForOutput(decorateDecision(decision, opts));
+    const reasons = Array.isArray(decorated.block_reasons) ? decorated.block_reasons : [];
+    const reasonCodes = reasons.map((item) => String(item.code ?? ""));
+    const allowed = Boolean(decorated.allowed);
+    const workflowAction = workflowActionForReasonCodes(reasonCodes, allowed);
+    const renderedReasons = reasons.map((item) => safeReasonText(item, workflowAction)).filter(Boolean);
+    return {
+        allowed,
+        status: allowed ? "allowed" : "blocked",
+        workflow_action: workflowAction,
+        stage_label_zh: safeDisplayText(decorated.gate_label_zh) || "当前阶段",
+        check_label_zh: safeDisplayText(decorated.command_label_zh) || "当前检查",
+        summary_zh: safeDisplayText(summaryForWorkflowAction(workflowAction, allowed)),
+        reasons_zh: renderedReasons.length > 0 ? renderedReasons : undefined,
+        next_steps_zh: nextStepsForWorkflowAction(workflowAction, allowed).map(safeDisplayText),
+        diagnostic_hint: DIAGNOSTIC_HINT,
+    };
+}
+export function renderUserFacingDecision(decision, opts = {}) {
+    const decorated = sanitizeDecisionForOutput(decorateDecision(decision, opts));
+    const agentView = renderAgentDecision(decorated, opts);
+    const gate = safeDisplayText(decorated.gate_label_zh) || "当前检查";
+    const command = safeDisplayText(decorated.command_label_zh);
+    const lines = [];
+    if (decorated.allowed) {
+        lines.push(`检查通过：${gate}。`);
+    }
+    else {
+        lines.push(`暂时不能继续：${gate}。`);
+    }
+    if (command && command !== gate) {
+        lines.push(`检查项：${command}。`);
+    }
+    const reasons = Array.isArray(decorated.block_reasons) ? decorated.block_reasons : [];
+    if (!decorated.allowed && reasons.length > 0) {
+        lines.push("原因：");
+        for (const item of reasons) {
+            const reasonText = safeReasonText(item, agentView.workflow_action);
+            lines.push(`- ${reasonText}`);
+        }
+    }
+    const nextActions = Array.isArray(agentView.next_steps_zh) ? agentView.next_steps_zh.map(safeDisplayText).filter(Boolean) : [];
+    if (nextActions.length > 0) {
+        lines.push("下一步：");
+        for (const action of nextActions)
+            lines.push(`- ${action}`);
+    }
+    lines.push(`诊断：${DIAGNOSTIC_HINT}`);
+    return `${lines.join("\n")}\n`;
+}
 export function printDecision(decision, opts = {}) {
     const decorated = decorateDecision(decision, opts);
+    if (opts.format === "user") {
+        process.stdout.write(renderUserFacingDecision(decorated, opts));
+        return;
+    }
+    if (opts.format === "agent") {
+        process.stdout.write(`${JSON.stringify(renderAgentDecision(decorated, opts), null, 2)}\n`);
+        return;
+    }
     process.stdout.write(`${JSON.stringify(sanitizeDecisionForOutput(decorated), null, 2)}\n`);
 }
 export function runCommand(cmd, args, opts = {}) {

package/dist/superspec.js

@@ -30,16 +30,16 @@ function help() {
         "  version     print SuperSpec CLI version",
         "",
         "examples:",
-        "  superspec init --scope project",
+        "  superspec init --scope project --format agent",
         "  superspec init --scope user",
-        "  superspec guard check-init --change <change>",
+        "  superspec guard check-init --change <change> --format agent",
         "  superspec doctor",
         "",
     ].join("\n");
 }
 function updateHelp() {
     return [
-        "usage: superspec update [--scope {project,user}] [--path PATH] [--codex-home PATH] [--local-only]",
+        "usage: superspec update [--scope {project,user}] [--path PATH] [--codex-home PATH] [--format {json,agent,user}] [--local-only]",
         "",
         "updates the global SuperSpec CLI from npm, then updates manifest-managed SuperSpec surfaces.",
         "",
@@ -49,6 +49,7 @@ function updateHelp() {
         "  --user, --global        equivalent to --scope user",
         "  --path PATH             project root for project scope (default: current directory)",
         "  --codex-home PATH       Codex user home for user scope (default: $CODEX_HOME or ~/.codex)",
+        "  --format {json,agent,user} output format; use agent for workflow consumption",
         "  --local-only            skip npm self-update and use the currently installed package",
         "  -h, --help              show this help",
         "",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peterxiaoyang/superspec",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "SuperSpec workflow package: guard runtime, generic workflow templates, and Codex adapter payload.",
   "repository": {
     "type": "git",

package/templates/workflow/skills/superspec-apply/SKILL.md

@@ -16,6 +16,8 @@ metadata:
 - 对话窗口里的解释、总结、提问和下一步说明必须使用中文；除命令、路径、字段名、代码标识符外，不要夹带英文说明词。
 - 对话窗口、AskUserQuestion 文案、进度更新和最终总结不得裸露内部证据种类、字段名或 reason code；用户确认记录、审查问题记录、审查轮次编号、问题唯一标识等都只用中文业务说法。原始协议名只允许写在证据 JSON、代码、测试、精确命令输出或用户明确要求的诊断片段中。
 - 本 skill 文档中的内部协议名只用于落盘证据或运行 guard；写给用户时必须先翻译成中文业务动作，例如“记录用户确认”“记录审查问题”“完成最终审查判断”。
+- 用户可见文案不得使用“裁决”描述用户动作；统一说“确认”“范围取舍”“处理方式选择”或“用户确认记录”。
+- 普通 workflow 命令使用 `--format agent` 读取 guard/init 输出；`--format json` 只用于诊断 evidence/schema/guard 内部，不得作为默认模型上下文或直接转述给用户。
 - 向用户转述 guard / review 输出时，不要直接贴英文 `message`、`next_allowed_actions` 或英文模板标题；应改写为中文，并仅在需要定位内部协议时保留英文 code/command 于反引号中。
 
 ## 命令执行 / Shell
@@ -53,7 +55,7 @@ metadata:
 2. 当 dirty worktree、untracked files 或 branch state 需要确认时，使用 AskUserQuestion 处理分支状态。
 3. 验证 apply readiness：
    ```text
-   superspec guard check-apply-ready --change "<change>"
+   superspec guard check-apply-ready --change "<change>" --format agent
    ```
 4. 获取 native apply context 和 task list：
    ```text
@@ -65,21 +67,21 @@ metadata:
    - 若 `request_changes_route:"reopen_tasks"`，读取 `reopen_task_ids`，逐个判断当前 task 所处阶段：
      - 如果该 task 仍是 `[x]`，说明还处于首次回退前；先由主流程基于本轮 review 的结构化 output 写出该 task 的 `task_reopen` evidence 与配套 `status:"superseded"` evidence，形成完整 reopen package，再执行：
      ```text
-     superspec guard check-task-reopen --change "<change>" --task-id "<task-id>"
+     superspec guard check-task-reopen --change "<change>" --task-id "<task-id>" --format agent
      ```
        只有该 guard `allow` 后，才允许把对应 task 从 `- [x]` 改为 `- [ ]`，并把它重新纳入本轮 apply。
      - 如果该 task 已经是 `[ ]`，且当前 `tasks.md` 已匹配授权后的 `after_tasks_sha256`，说明它已经处于合法 reopened apply；此时直接续跑 `check-task-edit -> RED/GREEN -> check-task-complete`，不要重复创建 `task_reopen`，也不要再次执行 pre-revert `check-task-reopen`。
    - 若 `request_changes_route:"change_update"`，停止 apply，回 propose / change update；不要试图通过 reopen 继续实现。
 6. 对每个 pending task（包括刚刚合法 reopen 的 task），在任何实现编辑前执行任务编辑前检查（`check-task-edit`）：
    ```text
-   superspec guard check-task-edit --change "<change>" --task-id "<task-id>"
+   superspec guard check-task-edit --change "<change>" --task-id "<task-id>" --format agent
    ```
 7. 在 runtime/business implementation edits 前产出 RED evidence，除非有允许的 `no_tdd_reason` 或处于现状锁定测试模式（`characterization mode`）。这里的 `characterization` 指“先把当前真实行为测出来并锁住，重构后保持一致”。RED/GREEN evidence 必须引用 task 的 `test_refs`，并在 task 声明 `invariant_refs` 时同步记录 `invariant_refs`。若 task 来自 reopen，本轮 successor GREEN / alternative verification / manual verification 必须携带同一 `reopen_id`。
 8. 按 native dynamic instruction 和 `contextFiles` 指引，实现最小 task scope。
 9. 产出 GREEN evidence，保留 `test_id`、`invariant_refs`、命令、输出摘要和 raw log ref；raw log ref 指向原始输出文件，evidence 中只写必要摘要，不复制完整日志。
 10. 勾选 task 前执行任务完成检查（`check-task-complete`）：
    ```text
-   superspec guard check-task-complete --change "<change>" --task-id "<task-id>"
+   superspec guard check-task-complete --change "<change>" --task-id "<task-id>" --format agent
    ```
    然后按 native apply semantics 将 task 从 `- [ ]` 改为 `- [x]`。
 11. 如果该 task 来自 reopen，在重新勾回 `[x]` 后写入 `kind:"task_reopen_resolved"` evidence，关闭本轮 reopen 授权；不要复用旧 reopen 生命周期。reopen 只授权：

package/templates/workflow/skills/superspec-archive/SKILL.md

@@ -16,6 +16,8 @@ metadata:
 - 对话窗口里的解释、确认、总结和下一步说明必须使用中文；除命令、路径、字段名、代码标识符外，不要夹带英文说明词。
 - 对话窗口、AskUserQuestion 文案、进度更新和最终总结不得裸露内部证据种类、字段名或 reason code；用户确认记录、审查问题记录、审查轮次编号、问题唯一标识等都只用中文业务说法。原始协议名只允许写在证据 JSON、代码、测试、精确命令输出或用户明确要求的诊断片段中。
 - 本 skill 文档中的内部协议名只用于落盘证据或运行 guard；写给用户时必须先翻译成中文业务动作，例如“记录用户确认”“记录审查问题”“完成最终审查判断”。
+- 用户可见文案不得使用“裁决”描述用户动作；统一说“确认”“范围取舍”“处理方式选择”或“用户确认记录”。
+- 普通 workflow 命令使用 `--format agent` 读取 guard/init 输出；`--format json` 只用于诊断 evidence/schema/guard 内部，不得作为默认模型上下文或直接转述给用户。
 - 向用户转述 guard / archive 输出时，不要直接贴英文 `message`、`next_allowed_actions` 或英文模板标题；应改写为中文，并仅在需要定位内部协议时保留英文 code/command 于反引号中。
 
 ## 命令执行 / Shell
@@ -44,7 +46,7 @@ metadata:
 1. 对 `archive_ready` 最终确认使用 AskUserQuestion，等待明确选择。记录 archive-scoped human-confirmation evidence。当前 v1 不询问也不使用 `--skip-specs`；若 change 不应同步 specs，应先回到 propose/change update 调整 OpenSpec 包，而不是在 archive 阶段跳过。
 2. 检查 archive readiness 并生成 preservation manifest：
    ```text
-   superspec guard check-archive-ready --change "<change>"
+   superspec guard check-archive-ready --change "<change>" --format agent
    ```
    生成的 manifest 是 archive 前证据快照，必须能追踪 business-invariants、test-contract 和对应 invariant review evidence 的 sha256。
 3. 运行 native OpenSpec archive（移动 change、同步 delta->main specs、执行 validation）：
@@ -53,7 +55,7 @@ metadata:
    ```
 4. 根据 manifest 验证 archived `.superspec/` preservation：
    ```text
-   superspec guard check-archived --change "<change>"
+   superspec guard check-archived --change "<change>" --format agent
    ```
 
 遇到任何 guard `block` 就停止。

package/templates/workflow/skills/superspec-explore/SKILL.md

@@ -16,6 +16,8 @@ metadata:
 - 对话窗口里的解释、问题说明、总结、提问和下一步说明必须使用中文；除命令、路径、字段名、代码标识符外，不要夹带英文说明词。
 - 对话窗口、AskUserQuestion 文案、进度更新和最终总结不得裸露内部证据种类、字段名或 reason code；用户确认记录、审查问题记录、审查轮次编号、问题唯一标识等都只用中文业务说法。原始协议名只允许写在证据 JSON、代码、测试、精确命令输出或用户明确要求的诊断片段中。
 - 本 skill 文档中的内部协议名只用于落盘证据或运行 guard；写给用户时必须先翻译成中文业务动作，例如“记录用户确认”“记录审查问题”“完成最终审查判断”。
+- 用户可见文案不得使用“裁决”描述用户动作；统一说“确认”“范围取舍”“处理方式选择”或“用户确认记录”。
+- 普通 workflow 命令使用 `--format agent` 读取 guard/init 输出；`--format json` 只用于诊断 evidence/schema/guard 内部，不得作为默认模型上下文或直接转述给用户。
 - 向用户转述 guard / review 输出时，不要直接贴英文 `message`、`next_allowed_actions` 或英文模板标题；应改写为中文，并仅在需要定位内部协议时保留英文 code/command 于反引号中。
 
 ## 命令执行 / Shell
@@ -64,12 +66,12 @@ metadata:
 
 1. 确保项目级 SuperSpec surfaces 已存在：
    ```text
-   superspec init --scope project
+   superspec init --scope project --format agent
    ```
 2. 创建或打开 native OpenSpec change root，然后确认 change-scoped guard readiness 并拉取 native context：
    ```text
    openspec new change "<change>"   # 仅当该 change 不存在时执行
-   superspec guard check-init --change "<change>"
+   superspec guard check-init --change "<change>" --format agent
    openspec list --json
    openspec status --change "<change>" --json   # changeRoot / artifactPaths / actionContext for grounding
    ```
@@ -85,7 +87,7 @@ metadata:
 9. 对探索结论、范围边界和进入 propose 的授权使用 AskUserQuestion，并等待明确选择；记录探索阶段人工确认 evidence（JSON 中为 `gate:"explore_complete"`、`kind:"human_confirmation"`、`created_by:"user"`），`confirmed_refs` 固定记录用户确认过的探索记录。
 10. 运行进入阶段前检查（`check-enter`），验证 explore completion：
    ```text
-   superspec guard check-enter --change "<change>" --gate explore_complete
+   superspec guard check-enter --change "<change>" --gate explore_complete --format agent
    ```
 
 遇到任何 guard `block` 就停止。用户确认相关阻塞原因包括：缺少审查问题记录（`missing_review_digest`）、等待用户确认（`needs_user_decision_pending`）、历史 finding 未处理完（`finding_unresolved`）、用户确认未绑定（`user_decision_unbound`）、缺少 finding 问题清单（`ledger_injection_missing`）、审查轮次已达上限（`round_budget_exhausted`）等。它们的唯一合法出路是回到确认循环或升级给用户，不允许绕过。

package/templates/workflow/skills/superspec-propose/SKILL.md

@@ -16,6 +16,8 @@ metadata:
 - 对话窗口里的解释、问题说明、总结、提问和下一步说明必须使用中文；除命令、路径、字段名、代码标识符外，不要夹带英文说明词。
 - 对话窗口、AskUserQuestion 文案、进度更新和最终总结不得裸露内部证据种类、字段名或 reason code；用户确认记录、审查问题记录、审查轮次编号、问题唯一标识等都只用中文业务说法。原始协议名只允许写在证据 JSON、代码、测试、精确命令输出或用户明确要求的诊断片段中。
 - 本 skill 文档中的内部协议名只用于落盘证据或运行 guard；写给用户时必须先翻译成中文业务动作，例如“记录用户确认”“记录审查问题”“完成最终审查判断”。
+- 用户可见文案不得使用“裁决”描述用户动作；统一说“确认”“范围取舍”“处理方式选择”或“用户确认记录”。
+- 普通 workflow 命令使用 `--format agent` 读取 guard/init 输出；`--format json` 只用于诊断 evidence/schema/guard 内部，不得作为默认模型上下文或直接转述给用户。
 - 向用户转述 guard / review 输出时，不要直接贴英文 `message`、`next_allowed_actions` 或英文模板标题；应改写为中文，并仅在需要定位内部协议时保留英文 code/command 于反引号中。
 
 ## 命令执行 / Shell
@@ -53,7 +55,7 @@ metadata:
 
 1. 运行前置门禁检查（`check-enter`），确认探索阶段已经完成；该 gate 必须包含用户对探索结论和进入 propose 的明确确认，若 guard block 则停止并回到 explore 补确认：
    ```text
-   superspec guard check-enter --change "<change>" --gate explore_complete
+   superspec guard check-enter --change "<change>" --gate explore_complete --format agent
    ```
 2. 从 OpenSpec 获取方案文件生成顺序：
    ```text
@@ -72,28 +74,28 @@ metadata:
    - 主流程记录审查问题记录，给每个 finding 写处理结果：关键 findings（范围、非目标、验收标准、业务语义、设计边界）必须进入用户确认并停下来，用 AskUserQuestion 把原文和 A/B/C/D 选项展示给用户，拿到用户确认后才能继续；发现探索记录不完整时 route 用 `return_explore` 回 explore，不得自行补范围。
    - 修订 `proposal.md` 后必须重跑 `critic`（新一轮 round），直到 clean round + digest 通过，然后验证：
    ```text
-   superspec guard check-enter --change "<change>" --gate propose.proposal_reviewed
+   superspec guard check-enter --change "<change>" --gate propose.proposal_reviewed --format agent
    ```
    guard 未通过前不要开始编写 `specs/**` 或 `design.md`（两者的入口门禁都是 `proposal_reviewed`）。
 5. 设计说明 `design.md` 编写后：获取 `architect`、`critic`、`test-engineer` 的 native-subagent review evidence（带 `review_round_id` `design_complete-r<N>` + `findings[]` + 全量 pinned target：`proposal.md` + `design.md` + `specs/**/*.md` + 探索记录）。主流程记录审查问题记录；关键问题必须停下来向用户说明并等待用户确认，按用户确认改 design/specs 后 supersede 旧轮并重审。对于设计选项选择和最终设计确认，使用 AskUserQuestion 并等待明确选择；记录 human-confirmation evidence，然后验证：
    ```text
-   superspec guard check-enter --change "<change>" --gate propose.design_reviewed
+   superspec guard check-enter --change "<change>" --gate propose.design_reviewed --format agent
    ```
 6. 需求规格 `specs/**` 和设计说明 `design.md` 编写后、测试契约 `test-contract.md` 编写前：起草业务约束 `.superspec/artifacts/business-invariants.md`。每条 `INV-*` 必须有 statement、scope、source anchors、acceptance_refs、risk_refs、confidence、enforcement_level、test_refs_or_review_only_reason；记录 rejected candidates，防止把当前实现习惯误升格为业务真相。获取 `critic` + `test-engineer` review evidence（带 `review_round_id` `invariants_reviewed-r<N>` + `findings[]` + pinned target：business-invariants + design + specs glob）。主流程记录审查问题记录；关键业务语义问题必须进入用户确认，不得把实现习惯静默升格为 invariant 真相。然后验证：
    ```text
-   superspec guard check-enter --change "<change>" --gate propose.invariants_reviewed
+   superspec guard check-enter --change "<change>" --gate propose.invariants_reviewed --format agent
    ```
 7. 业务约束 `business-invariants.md` 完成后、任务清单 `tasks.md` 编写前：起草测试契约 `.superspec/artifacts/test-contract.md`，覆盖 specs 中每个 `#### Scenario` 和命中本 change scope 的 hard `INV-*`，包含 TEST ids、关联 INV ids、预期 RED reasons、预期 GREEN criteria 和 commands。获取 `test-engineer` + `critic` review evidence（带 `review_round_id` `test_contract_drafted-r<N>` + `findings[]` + pinned target：test-contract + invariants + design + specs glob）。主流程记录审查问题记录；验收标准变更等关键问题必须用户确认。然后验证：
    ```text
-   superspec guard check-enter --change "<change>" --gate propose.test_plan_drafted
+   superspec guard check-enter --change "<change>" --gate propose.test_plan_drafted --format agent
    ```
-8. 通过 `openspec instructions tasks` 编写任务清单 `tasks.md` 时：为每个 task 补充 `requirement_refs`、`invariant_refs`（必须是 business-invariants `INV-*` ids 的子集）、`test_refs`（必须是 test-contract TEST ids 的子集）、`read_scope`、`write_scope`、dependencies、TDD metadata，以及需要时的 parallel group。若 reviewer 对 task 映射提出 round-tagged findings，走 `tasks_complete-r<N>` 确认循环（pinned target：tasks + test-contract + invariants + design + specs glob）；验收标准问题 route 用 `return_test_contract_drafted`，映射问题用 `stay_same_gate_fix`。对于任务审查确认，使用 AskUserQuestion 并等待明确选择；按披露循环记录用户裁决和审查问题处理结果，然后验证：
+8. 通过 `openspec instructions tasks` 编写任务清单 `tasks.md` 时：为每个 task 补充 `requirement_refs`、`invariant_refs`（必须是 business-invariants `INV-*` ids 的子集）、`test_refs`（必须是 test-contract TEST ids 的子集）、`read_scope`、`write_scope`、dependencies、TDD metadata，以及需要时的 parallel group。若 reviewer 对 task 映射提出 round-tagged findings，走 `tasks_complete-r<N>` 确认循环（pinned target：tasks + test-contract + invariants + design + specs glob）；验收标准问题 route 用 `return_test_contract_drafted`，映射问题用 `stay_same_gate_fix`。对于任务审查确认，使用 AskUserQuestion 并等待明确选择；按披露循环记录用户确认和审查问题处理结果，然后验证：
    ```text
-   superspec guard check-enter --change "<change>" --gate propose.tasks_mapped
+   superspec guard check-enter --change "<change>" --gate propose.tasks_mapped --format agent
    ```
 9. 验证 apply readiness：
    ```text
-   superspec guard check-apply-ready --change "<change>"
+   superspec guard check-apply-ready --change "<change>" --format agent
    ```
 
 遇到任何 guard `block` 就停止。

package/templates/workflow/skills/superspec-review/SKILL.md

@@ -18,6 +18,8 @@ metadata:
 - 对话窗口里的解释、审查结论、验证结论、提问和下一步说明必须使用中文；除命令、路径、字段名、代码标识符外，不要夹带英文说明词。
 - 对话窗口、AskUserQuestion 文案、进度更新和最终总结不得裸露内部证据种类、字段名或 reason code；用户确认记录、审查问题记录、审查轮次编号、问题唯一标识等都只用中文业务说法。原始协议名只允许写在证据 JSON、代码、测试、精确命令输出或用户明确要求的诊断片段中。
 - 本 skill 文档中的内部协议名只用于落盘证据或运行 guard；写给用户时必须先翻译成中文业务动作，例如“记录用户确认”“记录审查问题”“完成最终审查判断”。
+- 用户可见文案不得使用“裁决”描述用户动作；统一说“确认”“范围取舍”“处理方式选择”或“用户确认记录”。
+- 普通 workflow 命令使用 `--format agent` 读取 guard/init 输出；`--format json` 只用于诊断 evidence/schema/guard 内部，不得作为默认模型上下文或直接转述给用户。
 - 向用户转述 guard / review / verification 输出时，不要直接贴英文 `message`、`next_allowed_actions`、`Summary`、`Justification`、`PASS/FAIL` 等模板词；应改写为中文，并仅在需要定位内部协议时保留英文 code/command 于反引号中。
 
 ## 命令执行 / Shell
@@ -55,7 +57,7 @@ metadata:
 Review 前必须确认这些 SuperSpec distribution files 存在；缺失、无效或当前 Codex surface 无法从它们启动 native subagents 时，review gate 必须 block：
 
 ```text
-superspec guard check-init --change "<change>"
+superspec guard check-init --change "<change>" --format agent
 ```
 
 Required project-scope files: `.codex/agents/code-reviewer.toml`、`.codex/prompts/code-reviewer.md`、`.codex/agents/architect.toml`、`.codex/prompts/architect.md`、`.codex/agents/critic.toml`、`.codex/prompts/critic.md`、`.codex/agents/verifier.toml`、`.codex/prompts/verifier.md`。
@@ -64,7 +66,7 @@ Required project-scope files: `.codex/agents/code-reviewer.toml`、`.codex/promp
 
 1. 检查 review readiness：
    ```text
-   superspec guard check-review-ready --change "<change>"
+   superspec guard check-review-ready --change "<change>" --format agent
    ```
 2. 从 guard decision、`git diff`、OpenSpec artifacts、tasks、business invariants、test contract、RED/GREEN 摘要和 live role output 摘要构建审查范围；不要默认打开完整 `.superspec/evidence/**/*.json`。
 3. 运行 repo-local review guidance：
@@ -105,7 +107,7 @@ Required project-scope files: `.codex/agents/code-reviewer.toml`、`.codex/promp
    - `request_changes` 只负责给出结构化回退方向，不直接修改 task checkbox。
 8. 仅在 allow path 检查 review completion：
    ```text
-   superspec guard check-review-complete --change "<change>"
+   superspec guard check-review-complete --change "<change>" --format agent
    ```
    - 只有最终 allow path 才应执行并通过这一步。
    - 如果本轮 `main_adjudication.review_decision:"request_changes"`，则本轮 review 的正确出口是停止并回到对应路由；不要把 `request_changes` 轮次伪装成 `review_complete`。