@peterxiaoyang/superspec 0.1.2 → 0.1.4

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

@@ -78,6 +78,7 @@ export const EVIDENCE_KINDS = new Set([
 // FIX-8 (audit A-5) adds the previously anchor-less human pause points:
 // apply isolation choice, apply-phase scope expansion, and verify-failure disposition.
 export const HUMAN_CONFIRMATION_GATES = new Set([
+    "explore_complete",
     "design_complete",
     "invariants_reviewed",
     "archive_ready",
@@ -215,8 +216,8 @@ export const GATE_ALIASES = {
     "propose.invariants_reviewed": "invariants_reviewed",
     "propose.test_plan_drafted": "test_contract_drafted",
     "propose.tasks_mapped": "tasks_complete",
-    "propose.apply_ready": "propose_complete",
-    apply_ready: "propose_complete",
+    "propose.apply_ready": "apply_ready",
+    apply_ready: "apply_ready",
 };
 export const GATE_ROUTE = {
     explore_complete: "explore",
@@ -227,6 +228,7 @@ export const GATE_ROUTE = {
     test_contract_honored: "propose",
     tasks_complete: "propose",
     propose_complete: "propose",
+    apply_ready: "propose",
     review_complete: "review",
     verify_complete: "review",
     archive_ready: "archive",
@@ -234,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 };
@@ -368,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.d.ts

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
 export * from "./src/init_cli.ts";
 export * from "./src/cli.ts";
+export * from "./src/doctor.ts";
+export * from "./src/self_update.ts";
 export declare function main_superspec(argv?: string[]): Promise<number>;

package/dist/superspec.js

@@ -3,8 +3,12 @@ import { realpathSync } from "node:fs";
 import { resolve } from "node:path";
 export * from "./src/init_cli.js";
 export * from "./src/cli.js";
+export * from "./src/doctor.js";
+export * from "./src/self_update.js";
 import { main } from "./src/cli.js";
+import { main_doctor, superspec_package_version } from "./src/doctor.js";
 import { main_init_async } from "./src/init_cli.js";
+import { update_self_then_rerun } from "./src/self_update.js";
 function realpathMaybe(filePath) {
     try {
         return realpathSync(filePath);
@@ -19,14 +23,35 @@ function help() {
         "",
         "commands:",
         "  init        install SuperSpec Codex surfaces (asks project/user; default project)",
-        "  update      update manifest-managed SuperSpec surfaces",
+        "  update      update SuperSpec CLI, then update manifest-managed surfaces",
         "  uninstall   remove manifest-managed SuperSpec surfaces",
         "  guard       run the SuperSpec guard command surface",
+        "  doctor      diagnose SuperSpec/OpenSpec/npm/PATH wiring",
+        "  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] [--format {json,agent,user}] [--local-only]",
+        "",
+        "updates the global SuperSpec CLI from npm, then updates manifest-managed SuperSpec surfaces.",
+        "",
+        "options:",
+        "  --scope {project,user}  update project .codex surfaces or user Codex home surfaces (default: project)",
+        "  --project               equivalent to --scope project",
+        "  --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",
         "",
     ].join("\n");
 }
@@ -36,14 +61,29 @@ export async function main_superspec(argv = process.argv.slice(2)) {
         process.stdout.write(help());
         return 0;
     }
+    if (command === "-v" || command === "--version" || command === "version") {
+        process.stdout.write(`${superspec_package_version()}\n`);
+        return 0;
+    }
     if (command === "init")
         return main_init_async(rest);
-    if (command === "update")
-        return main_init_async([...rest, "--update"]);
+    if (command === "update") {
+        if (rest.includes("-h") || rest.includes("--help")) {
+            process.stdout.write(updateHelp());
+            return 0;
+        }
+        const localOnly = rest.includes("--local-only") || rest.includes("--skip-self-update");
+        const updateArgs = rest.filter((arg) => arg !== "--local-only" && arg !== "--skip-self-update");
+        if (!localOnly)
+            return update_self_then_rerun({ args: updateArgs });
+        return main_init_async([...updateArgs, "--update"]);
+    }
     if (command === "uninstall")
         return main_init_async([...rest, "--uninstall"]);
     if (command === "guard")
         return main(rest);
+    if (command === "doctor")
+        return main_doctor(rest);
     // Convenience fallback: `superspec check-init ...` behaves like `superspec guard check-init ...`.
     if (command.startsWith("check-") || command === "status" || command === "recompute" || command === "init") {
         return main(argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peterxiaoyang/superspec",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "SuperSpec workflow package: guard runtime, generic workflow templates, and Codex adapter payload.",
   "repository": {
     "type": "git",
@@ -51,7 +51,7 @@
   "scripts": {
     "build": "node build.js",
     "typecheck": "tsc --noEmit",
-    "test": "node --test tests/test_install_engine.test.ts tests/test_real_openspec_smoke.test.ts tests/test_superspec_guard.test.ts tests/test_superspec_skills.test.ts",
+    "test": "node --test tests/test_install_engine.test.ts tests/test_real_openspec_smoke.test.ts tests/test_superspec_cli.test.ts tests/test_superspec_guard.test.ts tests/test_superspec_skills.test.ts",
     "prepack": "npm run build",
     "prepublishOnly": "npm run build",
     "pack:dry-run": "npm pack --dry-run"

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
@@ -23,6 +25,14 @@ metadata:
 - Windows PowerShell 中执行 npm 全局 bin 时，必须显式使用 `.cmd` shim：`superspec.cmd ...`、`openspec.cmd ...`；不要运行 `superspec.ps1` 或 `openspec.ps1`。
 - macOS、Linux、Git Bash、cmd.exe 或其他不会优先拦截 `.ps1` 的 shell 中，继续使用文档中的 `superspec ...`、`openspec ...` 命令。
 
+## 上下文读取纪律 / Context Budget
+
+- guard 可以在本地读取完整 `.superspec/evidence/**/*.json` 并重算判定；主流程默认不要打开完整 evidence JSON，除非正在排查 guard block、修复 schema，或用户明确要求诊断原文。
+- 主流程默认只读取 guard decision、当前 task 必要 artifact、OpenSpec instructions apply 返回的 `contextFiles`、native subagent `output_ref` 的摘要/结论段，以及 task RED/GREEN 所需的最小测试摘要。
+- raw log、长报告和历史 superseded evidence 默认只作为引用、hash 或摘要保留；不要把全文复制进对话上下文或新的 evidence。
+- RED/GREEN 仍按 task 的 `test_refs` 记录 gate-driving evidence；同一次命令输出可以作为共享 raw log 被引用，但不要仅凭聚合日志替代每个 task/test 所需的 RED/GREEN 证据字段。
+- 使用按运行合并建档的 `test_ids[]` 清单时，每个 claimed id 都必须出现在引用的 raw log 中；若当前 task gate 需要单个 `test_id` 覆盖，仍要补齐对应 gate-driving evidence。
+
 在 propose package 完成后使用本 skill 执行实现任务。**Task context、ordering 和 progress 来自 OpenSpec native apply instructions**（`openspec instructions apply`）；SuperSpec 为每个 task 包上一层 RED/GREEN guard checks。
 
 ## 边界 / Boundaries
@@ -41,11 +51,11 @@ metadata:
 
 ## 步骤 / Steps
 
-1. 对实现隔离（apply isolation）和执行模式（execution mode）使用 AskUserQuestion，并等待明确选择。
+1. 对实现隔离（apply isolation）和执行模式（execution mode）使用 AskUserQuestion，并等待明确选择；记录 `gate:"apply_isolation"` 的 `human_confirmation` evidence，必须包含 `confirmation_text`、`confirmed_refs` 和当前 `tasks_structure_hash`。
 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
@@ -57,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。
+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
@@ -23,6 +25,12 @@ metadata:
 - Windows PowerShell 中执行 npm 全局 bin 时，必须显式使用 `.cmd` shim：`superspec.cmd ...`、`openspec.cmd ...`；不要运行 `superspec.ps1` 或 `openspec.ps1`。
 - macOS、Linux、Git Bash、cmd.exe 或其他不会优先拦截 `.ps1` 的 shell 中，继续使用文档中的 `superspec ...`、`openspec ...` 命令。
 
+## 上下文读取纪律 / Context Budget
+
+- guard 可以在本地读取完整 `.superspec/evidence/**/*.json` 并重算 archive 判定；主流程默认不要打开完整 evidence JSON，除非正在排查 guard block、修复 preservation manifest，或用户明确要求诊断原文。
+- 主流程默认只读取 guard decision、archive preservation 摘要、OpenSpec archive 输出摘要，以及最终验证 archive 结果所需的最小 manifest 信息。
+- raw log、长报告和历史 superseded evidence 默认只作为引用、hash 或摘要保留；不要把全文复制进对话上下文或新的 evidence。
+
 仅在 `review_complete` passes（其中已经包含 final verification）后使用本 skill。
 
 ## 边界 / Boundaries
@@ -38,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）：
@@ -47,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
@@ -23,6 +25,14 @@ metadata:
 - Windows PowerShell 中执行 npm 全局 bin 时，必须显式使用 `.cmd` shim：`superspec.cmd ...`、`openspec.cmd ...`；不要运行 `superspec.ps1` 或 `openspec.ps1`。
 - macOS、Linux、Git Bash、cmd.exe 或其他不会优先拦截 `.ps1` 的 shell 中，继续使用文档中的 `superspec ...`、`openspec ...` 命令。
 
+## 上下文读取纪律 / Context Budget
+
+- guard 可以在本地读取完整 `.superspec/evidence/**/*.json` 并重算判定；主流程默认不要打开完整 evidence JSON，除非正在排查 guard block、修复 schema，或用户明确要求诊断原文。
+- 主流程默认只读取 guard decision、当前 gate 必要 artifact、OpenSpec instructions 返回的必要 context、native subagent `output_ref` 的摘要/结论段，以及用户确认所需的最小原文。
+- 当前轮披露循环所需的最小结构化字段必须读取，不能只看 `output_ref` 摘要；包括 role evidence 的 `findings[]`、`finding_uid`、`decision_scope_key`、逐字 `summary`、`target_refs`，以及本轮 digest 需要引用的 evidence id。
+- raw log、长报告和历史 superseded evidence 默认只作为引用、hash 或摘要保留；不要把全文复制进对话上下文或新的 evidence。
+- native subagent 的 `output_ref` 应指向简洁审查报告；原始命令输出或长日志放在 raw/report 文件中被引用，不作为默认阅读材料。
+
 在 init 之后、编写 OpenSpec proposal package 之前使用本 skill。
 
 ## 边界 / Boundaries
@@ -56,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
    ```
@@ -74,9 +84,10 @@ metadata:
    ```
 7. 在 `.superspec/evidence/discovery/` 记录 critic evidence，包含 `execution_mode:"native_subagent"`、`agent_role`、`agent_id`、`output_ref`、`source_anchors` 和 `target_refs`。
 8. 按确认循环处理 findings：写本轮审查问题记录；存在关键问题时**停下来向用户说明并等待用户确认**，再按用户确认更新探索记录 / 重跑 critic / 写新一轮记录，直到最新轮 clean 且问题清单里没有未处理完的问题。
-9. 运行进入阶段前检查（`check-enter`），验证 explore completion：
+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
@@ -23,6 +25,14 @@ metadata:
 - Windows PowerShell 中执行 npm 全局 bin 时，必须显式使用 `.cmd` shim：`superspec.cmd ...`、`openspec.cmd ...`；不要运行 `superspec.ps1` 或 `openspec.ps1`。
 - macOS、Linux、Git Bash、cmd.exe 或其他不会优先拦截 `.ps1` 的 shell 中，继续使用文档中的 `superspec ...`、`openspec ...` 命令。
 
+## 上下文读取纪律 / Context Budget
+
+- guard 可以在本地读取完整 `.superspec/evidence/**/*.json` 并重算判定；主流程默认不要打开完整 evidence JSON，除非正在排查 guard block、修复 schema，或用户明确要求诊断原文。
+- 主流程默认只读取 guard decision、当前 gate 必要 artifact、OpenSpec instructions 返回的必要 context、native subagent `output_ref` 的摘要/结论段，以及用户确认所需的最小原文。
+- 当前轮披露循环所需的最小结构化字段必须读取，不能只看 `output_ref` 摘要；包括 role evidence 的 `findings[]`、`finding_uid`、`decision_scope_key`、逐字 `summary`、`target_refs`，以及本轮 digest 需要引用的 evidence id。
+- raw log、长报告和历史 superseded evidence 默认只作为引用、hash 或摘要保留；不要把全文复制进对话上下文或新的 evidence。
+- native subagent 的 `output_ref` 应指向简洁审查报告；原始命令输出或长日志放在 raw/report 文件中被引用，不作为默认阅读材料。
+
 在 explore 完成后使用本 skill，用于把探索记录整理成可执行的正式方案包。OpenSpec 负责生成标准方案文件，具体写法必须通过它自带的指令（`openspec instructions`）获取；SuperSpec 负责在外层增加审查门禁（gates）、业务约束（`business-invariants.md`）、测试契约（`test-contract.md`）和任务元数据。
 
 ## 边界 / Boundaries
@@ -43,9 +53,9 @@ metadata:
 
 ## 步骤 / Steps
 
-1. 运行前置门禁检查（`check-enter`），确认探索阶段已经完成：
+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
@@ -64,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 并等待明确选择；记录 human-confirmation evidence，然后验证：
+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` 就停止。