@peterxiaoyang/superspec 0.1.3 → 0.1.5

package/dist/src/packet_schema.d.ts

@@ -0,0 +1,55 @@
+export type PacketOutputFormat = "agent" | "prompt";
+export type PinnedRef = {
+    root: "repo" | "change";
+    path: string;
+    blob_sha: string;
+};
+export type FindingSelector = {
+    evidence_id: string;
+    finding_uid: string;
+    evidence_ref: PinnedRef;
+};
+export type DecisionSelector = {
+    evidence_id: string;
+    decision_scope_key: string;
+    evidence_ref: PinnedRef;
+};
+export type WorkflowPacket = {
+    stage: string;
+    current_gate: string;
+    task_id?: string;
+    status: "allowed" | "blocked";
+    top_blockers?: string[];
+    blocker_count?: number;
+    has_more_blockers?: boolean;
+    next_action: string;
+    next_command?: string;
+    openspec_cli_surfaces?: string[];
+    must_read_refs: PinnedRef[];
+    must_read_verbatim_findings?: FindingSelector[];
+    must_read_verbatim_decisions?: DecisionSelector[];
+    diagnostic_command?: string;
+};
+export type ReviewPacket = {
+    consumer: "role" | "main-thread";
+    gate: string;
+    role: string;
+    round: number;
+    target_refs: PinnedRef[];
+    source_refs: PinnedRef[];
+    required_load_refs?: PinnedRef[];
+    required_claim_ids?: string[];
+    must_read_verbatim_findings?: FindingSelector[];
+    must_read_verbatim_decisions?: DecisionSelector[];
+    required_output_kind: string;
+    output_contract_fields: string[];
+    required_review_scope?: string[];
+    stop_conditions: string[];
+};
+export type PacketDispatchResult = {
+    output_format: "agent";
+    payload: WorkflowPacket | ReviewPacket;
+} | {
+    output_format: "prompt";
+    payload: string;
+};

package/dist/src/packet_schema.js

@@ -0,0 +1 @@
+export {};

package/dist/src/project_init.js

@@ -1,8 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
-import { REQUIRED_SUPERSPEC_AGENT_ROLES, REQUIRED_OPENSPEC_CODEX_SKILLS, REQUIRED_OPENSPEC_MIN_VERSION, block, commandExists, openspec_cli_probe, reason, read_agent_toml_name, read_skill_frontmatter_name, runCommand, } from "./core.js";
+import { REQUIRED_SUPERSPEC_AGENT_ROLES, REQUIRED_OPENSPEC_MIN_VERSION, block, commandExists, openspec_cli_probe, reason, read_agent_toml_name, } from "./core.js";
 import { install_workflow } from "./install_engine.js";
-import { system_failure_zh } from "./i18n.js";
 export const OPENSPEC_NPM_PACKAGE = "@fission-ai/openspec";
 export const OPENSPEC_INSTALL_DOC_URL = "https://github.com/Fission-AI/OpenSpec#readme";
 const ROLE_DESCRIPTIONS = {
@@ -12,9 +11,6 @@ const ROLE_DESCRIPTIONS = {
     "code-reviewer": "代码 / 规格 / 安全审查",
     verifier: "最终完成证据与验证审查",
 };
-function commandFailure(proc) {
-    return system_failure_zh((proc.error?.message ?? (proc.stderr || proc.stdout)).trim(), proc.status !== null && proc.status !== undefined ? `命令执行失败（退出状态码 ${proc.status}）。` : "命令执行失败，请查看终端日志后重试。");
-}
 function renderCommand(cmd, args) {
     return [cmd, ...args].join(" ");
 }
@@ -59,20 +55,6 @@ export function openspec_cli_requirement_message(probe, opts = {}) {
     }
     return `${probe.message}。请先安装或升级 @fission-ai/openspec >= ${REQUIRED_OPENSPEC_MIN_VERSION}（${OPENSPEC_INSTALL_DOC_URL}），然后重新运行 \`superspec init --scope project\`。`;
 }
-function openspecSkillProblems(repoRoot) {
-    const skillsRoot = join(repoRoot, ".codex", "skills");
-    const problems = [];
-    for (const name of REQUIRED_OPENSPEC_CODEX_SKILLS) {
-        const skillPath = join(skillsRoot, name, "SKILL.md");
-        if (!existsSync(skillPath) || !statSync(skillPath).isFile()) {
-            problems.push(name);
-            continue;
-        }
-        if (read_skill_frontmatter_name(skillPath) !== name)
-            problems.push(name);
-    }
-    return problems.sort();
-}
 function writeSuperSpecAgent(repoRoot, name) {
     const filePath = join(repoRoot, ".codex", "agents", `${name}.toml`);
     mkdirSync(join(repoRoot, ".codex", "agents"), { recursive: true });
@@ -105,38 +87,14 @@ function writeSuperSpecPrompt(repoRoot, name) {
     ].join("\n"), "utf8");
     return filePath;
 }
-function ensureOpenSpecCodex(repoRoot, actions) {
+function ensureOpenSpecCliSurface(repoRoot, actions) {
     const probe = openspec_cli_probe({ cwd: repoRoot });
-    if (!probe.ok)
-        return [openspec_cli_requirement_message(probe, { cwd: repoRoot })];
-    let problems = openspecSkillProblems(repoRoot);
-    if (problems.length === 0) {
-        actions.push({ action: "openspec_codex_skills", status: "ok" });
-        return [];
-    }
-    const init = runCommand("openspec", ["init", "--tools", "codex", "."], { cwd: repoRoot, timeout: 60_000 });
-    actions.push({
-        action: "openspec init --tools codex .",
-        status: init.status === 0 ? "updated" : "failed",
-        refs: problems,
-        detail: init.status === 0 ? undefined : commandFailure(init),
-    });
-    if (init.error || init.status !== 0)
-        return [`openspec init 执行失败：${commandFailure(init)}`];
-    problems = openspecSkillProblems(repoRoot);
-    if (problems.length === 0)
-        return [];
-    const update = runCommand("openspec", ["update", "--force", "."], { cwd: repoRoot, timeout: 60_000 });
     actions.push({
-        action: "openspec update --force .",
-        status: update.status === 0 ? "updated" : "failed",
-        refs: problems,
-        detail: update.status === 0 ? undefined : commandFailure(update),
+        action: "openspec_cli_surface",
+        status: probe.ok ? "ok" : "failed",
+        detail: probe.message,
     });
-    if (update.error || update.status !== 0)
-        return [`openspec update 执行失败：${commandFailure(update)}`];
-    problems = openspecSkillProblems(repoRoot);
-    return problems.length === 0 ? [] : [`OpenSpec 配套技能文件仍然缺失或无效：${problems.join(", ")}`];
+    return probe.ok ? [] : [openspec_cli_requirement_message(probe, { cwd: repoRoot })];
 }
 function ensureSuperSpecRoles(repoRoot, actions) {
     const problems = [];
@@ -182,7 +140,7 @@ export function project_init(repoRootRaw = process.cwd(), opts = {}) {
     const repoRoot = resolve(repoRootRaw);
     const actions = [];
     const problems = [
-        ...ensureOpenSpecCodex(repoRoot, actions),
+        ...ensureOpenSpecCliSurface(repoRoot, actions),
         ...ensureSuperSpecWorkflow(repoRoot, actions, opts.force === true),
         ...ensureSuperSpecRoles(repoRoot, actions),
     ];

package/dist/src/util.d.ts

@@ -39,6 +39,9 @@ export type Decision = {
     trust_warnings_zh?: string[];
     workflow_terms_zh?: WorkflowTermHint[];
 };
+export type DecisionOutputFormat = "json" | "agent" | "user";
+export type PacketOutputFormat = "agent" | "prompt";
+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;
@@ -70,10 +73,10 @@ export declare const TASK_REOPEN_RESOLVED_REQUIRED_FIELDS: readonly ["reopen_evi
 export declare const TASK_REOPEN_INVALIDITY_CLASSES: readonly ["insufficient_completion_evidence"];
 export declare const FORBIDDEN_FIELDS: Set<string>;
 export declare const OPENSPEC_ARTIFACTS: Set<string>;
-export declare const REQUIRED_OPENSPEC_CODEX_SKILLS: readonly ["openspec-explore", "openspec-propose", "openspec-apply-change", "openspec-archive-change"];
+export declare const REQUIRED_OPENSPEC_CODEX_SKILLS: readonly [];
 export declare const REQUIRED_SUPERSPEC_WORKFLOW_SKILLS: readonly ["superspec-explore", "superspec-propose", "superspec-apply", "superspec-review", "superspec-archive"];
 export declare const REQUIRED_SUPERSPEC_AGENT_ROLES: readonly ["architect", "critic", "test-engineer", "code-reviewer", "verifier"];
-export declare const REQUIRED_OPENSPEC_CLI_SURFACES: readonly [readonly ["instructions", "--help"], readonly ["archive", "--help"], readonly ["validate", "--help"], readonly ["status", "--help"]];
+export declare const REQUIRED_OPENSPEC_CLI_SURFACES: readonly [readonly ["list", "--help"], readonly ["instructions", "--help"], readonly ["archive", "--help"], readonly ["validate", "--help"], readonly ["status", "--help"]];
 export declare const ARTIFACT_ENTER_GATE: Record<string, string>;
 export declare const ROUTE_ORDER: Record<string, number>;
 export declare const ROUTE_ALIASES: Record<string, string>;
@@ -82,6 +85,10 @@ 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 parsePacketOutputFormat(raw: string, opts?: {
+    allowPrompt?: boolean;
+}): PacketOutputFormat;
 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,9 +106,21 @@ 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 printPacket(payload: JsonMap | string, opts: {
+    format: PacketOutputFormat;
 }): void;
+export declare function printPacketError(code: string, message: string): void;
 export declare function runCommand(cmd: string, args: string[], opts?: {
     cwd?: string;
     timeout?: number;

package/dist/src/util.js

@@ -146,12 +146,10 @@ export const FORBIDDEN_FIELDS = new Set([
     "artifact_status",
 ]);
 export const OPENSPEC_ARTIFACTS = new Set(["proposal", "specs", "design", "tasks"]);
-export const REQUIRED_OPENSPEC_CODEX_SKILLS = [
-    "openspec-explore",
-    "openspec-propose",
-    "openspec-apply-change",
-    "openspec-archive-change",
-];
+// Compatibility export for callers that imported the old repo-local OpenSpec bridge list.
+// Phase 4 makes the OpenSpec CLI surface the runtime truth, so no repo-local OpenSpec skills are
+// required by SuperSpec init or health checks.
+export const REQUIRED_OPENSPEC_CODEX_SKILLS = [];
 // D4 (audit G-2): SuperSpec's own workflow skills are part of the init health surface — a deleted
 // or renamed superspec-* skill must be visible at check-init, not discovered mid-workflow.
 export const REQUIRED_SUPERSPEC_WORKFLOW_SKILLS = [
@@ -169,6 +167,7 @@ export const REQUIRED_SUPERSPEC_AGENT_ROLES = [
     "verifier",
 ];
 export const REQUIRED_OPENSPEC_CLI_SURFACES = [
+    ["list", "--help"],
     ["instructions", "--help"],
     ["archive", "--help"],
     ["validate", "--help"],
@@ -236,6 +235,18 @@ 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 parsePacketOutputFormat(raw, opts = {}) {
+    if (raw === "agent")
+        return raw;
+    if (opts.allowPrompt && raw === "prompt")
+        return raw;
+    throw new GuardError(opts.allowPrompt ? "--format 只允许 agent 或 prompt" : "--format 只允许 agent");
+}
 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,10 +381,231 @@ 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 printPacket(payload, opts) {
+    if (opts.format === "prompt") {
+        process.stdout.write(String(payload));
+        if (!String(payload).endsWith("\n"))
+            process.stdout.write("\n");
+        return;
+    }
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+}
+export function printPacketError(code, message) {
+    process.stdout.write(`${JSON.stringify({ status: "error", error_code: code, message }, null, 2)}\n`);
+}
 export function runCommand(cmd, args, opts = {}) {
     const platform = opts.platform ?? process.platform;
     const invocation = platform === "win32" ? windowsCommandInvocation(cmd, args, opts.cwd) : { cmd, args };

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.5",
   "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_cli.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_packet_measure.test.ts tests/test_real_openspec_smoke.test.ts tests/test_superspec_cli.test.ts tests/test_superspec_guard_output.test.ts tests/test_superspec_guard_core.test.ts tests/test_superspec_guard_review.test.ts tests/test_superspec_guard_request_reopen.test.ts tests/test_superspec_guard_archive.test.ts tests/test_superspec_guard_packet.test.ts tests/test_superspec_guard_disclosure.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/prompts/architect.md

@@ -1,120 +1,27 @@
 ---
-description: "架构与诊断顾问（深度、只读）"
-argument-hint: "任务说明"
+description: "架构与边界审查角色"
+argument-hint: "任务说明或 review-packet prompt_ref"
 ---
-<identity>
-你是 Architect（Oracle）。你基于文件证据做诊断、分析和建议。你只读，不修改文件。
-</identity>
 
-<language>
-- 所有用户可见输出必须使用简体中文。
-- 命令、路径、JSON/schema 字段、代码标识符、gate 名称、任务/测试 id、协议字面值在需要精确表达时保持原样。
-- 最终文本不要使用英文分节标题，例如 "Summary"、"Analysis"、"Root Cause"、"Recommendations"；整份报告用中文写。
-- 转述工作流或 guard 概念时，用中文解释，不要直接粘贴英文模板原句。
-</language>
-
-<constraints>
-<scope_guard>
-- Never write or edit files.
-- Never judge code you have not opened.
-- Never give generic advice detached from this codebase.
-- Acknowledge uncertainty instead of speculating.
-</scope_guard>
-
-<ask_gate>
-- Default to outcome-first, evidence-dense analysis; add depth only when it materially improves the result, evidence, or stop condition.
-- Treat newer user task updates as local overrides for the active analysis thread while preserving earlier non-conflicting constraints.
-- Ask only when the next step materially changes scope or requires a business decision.
-</ask_gate>
-</constraints>
-
-<execution_loop>
-1. 先收集上下文。
-2. 形成假设。
-3. 用代码事实交叉验证。
-4. 返回摘要、根因、建议和取舍。
-
-<success_criteria>
-- 每条重要结论都要附 file:line 证据。
-- 要指出根因，而不只是症状。
-- 建议必须具体且可执行。
-- 必须说明取舍。
-- 在 ralplan 共识审查中，要包含反论、张力和综合方案。
-- 在 `superspec-review` 中，要输出基于来源证据的架构 guidance 和升级点；最终判断由主流程完成，不由本角色直接下判。
-</success_criteria>
-
-<verification_loop>
-- 默认投入强度：高。
-- 当诊断和建议已经有证据支撑时停止。
-- 在分析真正落地前持续阅读。
-- 如果是 ralplan 共识审查，要明确写出取舍张力与综合方案。
-</verification_loop>
-
-<tool_persistence>
-只要 file:line 证据还缺失，就不要停在“看起来合理”的猜测上。
-</tool_persistence>
-</execution_loop>
-
-<tools>
-- 并行使用 Glob/Grep/Read。
-- 当诊断会因此更扎实时，再使用诊断工具和 git 历史。
-- 如果需要更宽的审查范围，就向上汇报，不要自行横向改派。
-</tools>
+# Architect
 
-<style>
-<output_contract>
-默认最终输出形态：结果优先、证据密集；直接给出结论、支撑证据、验证或引用状态，以及停止条件，不要铺垫。
+## 角色身份
 
-## 结论摘要
-[2-3 句：发现了什么、主建议是什么]
+你是 Architect。你审查系统边界、接口契约、数据流、长期维护风险、回滚难度和设计取舍。你提供架构 guidance，不替代主流程做最终判断。
 
-## 分析
-[详细发现，带 file:line 引用]
+## 读写边界
 
-## 根因
-[根本问题，而非表面症状]
+- 默认只读；不要修改文件。
+- 不评价没有打开或没有被 packet/source refs 指向的材料。
+- 如果需要扩大审查范围，向主流程说明缺口，不要自行改派或改代码。
 
-## 建议
-1. [最高优先级] - [工作量] - [影响]
-2. [下一优先级] - [工作量] - [影响]
+## SuperSpec Packet 规则
 
-## 主流程判断建议
-- 关键架构判断
-- 建议直接加载的 source refs
-- 建议升级或后续动作
+在 `superspec-review` 或 disclosure review 中，先读取主流程提供的 `review-packet` 或 `prompt_ref`。以 packet 中的 `target_refs`、`source_refs`、`required_output_kind`、`output_contract_fields`、`required_review_scope` 和 `stop_conditions` 为准；不要依赖本 prompt 记忆输出 schema。
 
-## 取舍
-| 方案 | 优点 | 代价 |
-|------|------|------|
-| A | ... | ... |
-| B | ... | ... |
+## 输出风格
 
-## 共识补充（仅 ralplan 审查）
-- **最强反论：** [对首选方向最强的反对论证]
-- **取舍张力：** [不能忽略的真实张力]
-- **综合方案（若可行）：** [如何保留竞争方案的优点]
-
-## 引用
-- `path/to/file.ts:42` - [该处证明了什么]
-- `path/to/other.ts:108` - [该处证明了什么]
-</output_contract>
-
-<scenario_handling>
-- **正确示例：** 用户在你已经定位到高概率根因后说 `continue`。继续补齐缺失的 file:line 证据。
-
-- **正确示例：** 分析完成后，用户说 `make a PR`。把它当成下游流程上下文，而不是稀释分析深度的理由。
-
-- **正确示例：** 用户说 `merge if CI green`。把它当成后续操作条件，而不是跳过剩余证据的理由。
-
-- **错误示例：** 用户说 `continue`，你却重新开始分析，或把之前已经拿到的证据丢掉。
-</scenario_handling>
-
-<final_checklist>
-- 我是否在下结论前读过代码？
-- 每个关键发现是否都附了 file:line 证据？
-- 根因是否说清楚了？
-- 建议是否足够具体可执行？
-- 我是否说明了取舍？
-- 如果这是 ralplan 共识审查，我是否包含了反论、张力与综合方案？
-</final_checklist>
-</style>
+- 所有用户可见输出必须使用简体中文。
+- 命令、路径、JSON/schema 字段、gate 名称、任务/测试 id、代码标识符保留原文。
+- 结论先行，按严重度列出问题，给出文件/行号证据。
+- 无阻塞问题时明确写“无阻塞问题”，并列残余风险或未验证项。