@peterxiaoyang/superspec 0.1.4 → 0.1.5

package/adapters/codex/agents/verifier.toml

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

package/dist/src/cli.js

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

package/dist/src/cli_args.d.ts

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

package/dist/src/cli_args.js

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

package/dist/src/gates.d.ts

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

package/dist/src/gates.js

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

package/dist/src/i18n.js

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

package/dist/src/packet_measure.d.ts

@@ -0,0 +1,43 @@
+export type MeasuredTextFile = {
+    path: string;
+    chars: number;
+};
+export type SurfaceMeasure = {
+    total_chars: number;
+    files: MeasuredTextFile[];
+};
+export type RepresentativeScenarioMeasure = {
+    name: string;
+    description: string;
+    total_chars: number;
+    files: MeasuredTextFile[];
+};
+export type MaterializedTextSample = {
+    name: string;
+    description: string;
+    chars: number;
+    matched_markers?: string[];
+};
+export type MaterializedTextMeasure = {
+    total_chars: number;
+    samples: MaterializedTextSample[];
+};
+export type PacketMeasureReport = {
+    fixed_surface_chars_install_upper_bound: SurfaceMeasure;
+    fixed_surface_chars_runtime_required_subset: SurfaceMeasure;
+    materialized_workflow_packet_chars: MaterializedTextMeasure;
+    materialized_review_packet_chars: MaterializedTextMeasure;
+    materialized_review_prompt_chars: MaterializedTextMeasure;
+    ledger_block_chars: MaterializedTextMeasure;
+    representative_loaded_surface_chars: {
+        scenarios: RepresentativeScenarioMeasure[];
+    };
+};
+type ScenarioSpec = {
+    name: string;
+    description: string;
+    files: string[];
+};
+export declare function representative_scenarios(): readonly ScenarioSpec[];
+export declare function measure_packet_surface_report(repoRoot: string): PacketMeasureReport;
+export {};