@peterxiaoyang/superspec 0.1.11 → 0.1.13

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

@@ -10,7 +10,7 @@ metadata:
 
 ## 语言规则 / Language
 
-- 默认使用简体中文写人类可读内容；命令、路径、字段名、gate 名、task/test id、代码标识符保留原文。
+- 默认使用简体中文写人类可读内容；命令、路径、字段名、阶段门名、task/test id、代码标识符保留原文。
 - 用户可见文案不得使用“裁决”描述用户动作；统一说“确认”“范围取舍”“处理方式选择”或“用户确认记录”。
 - 不把内部证据种类、reason code、JSON 字段大全直接转述给用户；需要诊断时才引用原文。
 - 普通 workflow 命令使用 `--format agent`；`--format json` 只用于诊断，不作为默认上下文。
@@ -27,20 +27,20 @@ Review 合并实现审查、架构审查、SuperSpec critic、final verification
 ## 第一条必跑命令
 
 ```text
-superspec guard check-init --change "<change>" --format agent
+superspec check check-init --change "<change>" --format agent
 ```
 
 然后检查 review readiness：
 
 ```text
-superspec guard check-review-ready --change "<change>" --format agent
+superspec check check-review-ready --change "<change>" --format agent
 ```
 
-遇到任何 guard `block` 就停止。review 不直接回改 `tasks.md` checkbox。
+遇到任何返回状态为 `block` 就停止。review 不直接回改 `tasks.md` checkbox。
 
-## Repo-local Native Subagent 边界
+## 专用代理边界
 
-Review 必须使用 SuperSpec 分发包里的 repo-local native agents，不要调用全局 `$code-review`、OMX workflow、main-thread self-review 或普通 markdown 报告替代。
+Review 必须使用本仓库安装的 repo-local native agents（专用代理），不要调用全局 `$code-review`、OMX workflow、主线程自审或普通 markdown 报告替代。
 
 必需入口：
 
@@ -49,12 +49,12 @@ Review 必须使用 SuperSpec 分发包里的 repo-local native agents，不要
 - `.codex/agents/critic.toml` / `.codex/prompts/critic.md`
 - `.codex/agents/verifier.toml` / `.codex/prompts/verifier.md`
 
-每个 reviewer prompt 都先由 packet 生成：
+每个审查提示都先由检查命令产出：
 
 ```text
-superspec guard review-packet --change "<change>" --gate review_complete --role code-reviewer --round 1 --format prompt
-superspec guard review-packet --change "<change>" --gate review_complete --role architect --round 1 --format prompt
-superspec guard review-packet --change "<change>" --gate review_complete --role critic --round 1 --format prompt
+superspec check review-packet --change "<change>" --gate review_complete --role code-reviewer --round 1 --format prompt
+superspec check review-packet --change "<change>" --gate review_complete --role architect --round 1 --format prompt
+superspec check review-packet --change "<change>" --gate review_complete --role critic --round 1 --format prompt
 ```
 
 ## Final Verification 边界
@@ -65,11 +65,11 @@ superspec guard review-packet --change "<change>" --gate review_complete --role
 openspec validate "<change>"
 ```
 
-然后执行 test contract 要求的最终测试，启动 repo-local `verifier` 和 `critic` 做 verification review。verification prompt 也必须由 packet 生成：
+然后执行 test contract 要求的最终测试，启动本仓库 `verifier` 和 `critic` 做验证审查。验证提示也必须由检查命令产出：
 
 ```text
-superspec guard review-packet --change "<change>" --gate review_complete --role verifier --round 1 --format prompt
-superspec guard review-packet --change "<change>" --gate review_complete --role critic --round 1 --kind verification_review --format prompt
+superspec check review-packet --change "<change>" --gate review_complete --role verifier --round 1 --format prompt
+superspec check review-packet --change "<change>" --gate review_complete --role critic --round 1 --kind verification_review --format prompt
 ```
 
 verification 只提供 proof/gap，不替代主流程最终判断。
@@ -79,10 +79,10 @@ verification 只提供 proof/gap，不替代主流程最终判断。
 主线程写最终判断前读取：
 
 ```text
-superspec guard review-packet --change "<change>" --gate review_complete --role main-thread --round 1 --format agent
+superspec check review-packet --change "<change>" --gate review_complete --role main-thread --round 1 --format agent
 ```
 
-`review_complete` 是 allow-only gate。allow path 必须由唯一 `main_adjudication` 承载最终判断，作者边界固定为 `execution_mode:"direct"` + `created_by:"main-thread"`；它不能携带 `agent_role`、`agent_id`、`prompt_ref`。
+`review_complete` 是只允许通过的阶段检查。通过路径由主线程写本轮审查结论（主线程直接写，不携带代理字段）。
 
 `request_changes` 不是 review_complete allow。它必须写清 `request_changes_route`：
 
@@ -96,7 +96,7 @@ request-changes round 不生成 allow-path verification，也不调用 `check-re
 仅 allow path 运行：
 
 ```text
-superspec guard workflow-packet --change "<change>" --gate review_complete --format agent
+superspec check workflow-packet --change "<change>" --gate review_complete --format agent
 ```
 
-只有 packet allowed 后，才进入 `superspec-archive`。
+只有检查结果显示通过后，才进入 `superspec-archive`。

package/dist/src/packet_measure.d.ts

@@ -1,43 +0,0 @@
-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 {};

package/dist/src/packet_measure.js

@@ -1,382 +0,0 @@
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { dirname, join } from "node:path";
-import { load_install_map } from "./install_engine.js";
-import { dispatch_packet } from "./packet_render.js";
-import { GuardError, runtime, } from "./util.js";
-import { file_blob_sha } from "./git.js";
-const REPRESENTATIVE_SCENARIOS = [
-    {
-        name: "explore_complete",
-        description: "Package payload surface for discovery authoring plus proposal-entry critic review.",
-        files: [
-            "templates/workflow/skills/superspec-explore/SKILL.md",
-            "templates/workflow/prompts/critic.md",
-            "adapters/codex/agents/critic.toml",
-        ],
-    },
-    {
-        name: "proposal_reviewed",
-        description: "Package payload surface for proposal authoring and proposal critic review.",
-        files: [
-            "templates/workflow/skills/superspec-propose/SKILL.md",
-            "templates/workflow/prompts/critic.md",
-            "adapters/codex/agents/critic.toml",
-        ],
-    },
-    {
-        name: "design_complete",
-        description: "Package payload surface for design authoring and the architect/critic/test-engineer review bundle.",
-        files: [
-            "templates/workflow/skills/superspec-propose/SKILL.md",
-            "templates/workflow/prompts/architect.md",
-            "templates/workflow/prompts/critic.md",
-            "templates/workflow/prompts/test-engineer.md",
-            "adapters/codex/agents/architect.toml",
-            "adapters/codex/agents/critic.toml",
-            "adapters/codex/agents/test-engineer.toml",
-        ],
-    },
-    {
-        name: "test_contract_drafted",
-        description: "Package payload surface for test-contract authoring and its review lanes.",
-        files: [
-            "templates/workflow/skills/superspec-propose/SKILL.md",
-            "templates/workflow/prompts/critic.md",
-            "templates/workflow/prompts/test-engineer.md",
-            "adapters/codex/agents/critic.toml",
-            "adapters/codex/agents/test-engineer.toml",
-        ],
-    },
-    {
-        name: "apply_ready",
-        description: "Package payload surface for apply orchestration and bounded executor handoff.",
-        files: [
-            "templates/workflow/skills/superspec-apply/SKILL.md",
-            "templates/workflow/prompts/executor.md",
-            "adapters/codex/agents/executor.toml",
-        ],
-    },
-    {
-        name: "review_complete_allow",
-        description: "Package payload surface for merged review + final verification on the allow path.",
-        files: [
-            "templates/workflow/skills/superspec-review/SKILL.md",
-            "templates/workflow/prompts/code-reviewer.md",
-            "templates/workflow/prompts/architect.md",
-            "templates/workflow/prompts/critic.md",
-            "templates/workflow/prompts/verifier.md",
-            "adapters/codex/agents/code-reviewer.toml",
-            "adapters/codex/agents/architect.toml",
-            "adapters/codex/agents/critic.toml",
-            "adapters/codex/agents/verifier.toml",
-        ],
-    },
-    {
-        name: "archive_ready",
-        description: "Package payload surface for archive handoff after review passes.",
-        files: [
-            "templates/workflow/skills/superspec-archive/SKILL.md",
-        ],
-    },
-    {
-        name: "round2_reviewer_prompt",
-        description: "Package payload surface for a round>1 reviewer lane.",
-        files: [
-            "templates/workflow/prompts/critic.md",
-            "adapters/codex/agents/critic.toml",
-        ],
-    },
-    {
-        name: "request_changes_reopen_tasks",
-        description: "Package payload surface for a review round that routes back to apply via reopen_tasks.",
-        files: [
-            "templates/workflow/skills/superspec-review/SKILL.md",
-            "templates/workflow/prompts/code-reviewer.md",
-            "templates/workflow/prompts/architect.md",
-            "templates/workflow/prompts/critic.md",
-            "adapters/codex/agents/code-reviewer.toml",
-            "adapters/codex/agents/architect.toml",
-            "adapters/codex/agents/critic.toml",
-        ],
-    },
-    {
-        name: "task_reopen_to_resolved",
-        description: "Package payload surface for reopened apply work from revert through successor executor completion.",
-        files: [
-            "templates/workflow/skills/superspec-apply/SKILL.md",
-            "templates/workflow/prompts/executor.md",
-            "adapters/codex/agents/executor.toml",
-        ],
-    },
-    {
-        name: "scope_expansion",
-        description: "Package payload surface for apply-side user confirmation when task scope expands.",
-        files: [
-            "templates/workflow/skills/superspec-apply/SKILL.md",
-        ],
-    },
-];
-const MATERIALIZED_WORKFLOW_PACKET_SAMPLES = [
-    {
-        name: "apply_ready_blocked",
-        description: "workflow-packet agent output for apply_ready before all required evidence is present.",
-        args: { command: "workflow-packet", change: "demo-change", gate: "apply_ready", packet_format: "agent" },
-    },
-    {
-        name: "task_complete_blocked",
-        description: "workflow-packet agent output for a task-scoped apply completion packet.",
-        args: { command: "workflow-packet", change: "demo-change", gate: "task_complete", task_id: "TASK-001", packet_format: "agent" },
-    },
-];
-const MATERIALIZED_REVIEW_PACKET_SAMPLES = [
-    {
-        name: "proposal_reviewed_critic",
-        description: "review-packet agent output for a disclosure reviewer lane.",
-        args: { command: "review-packet", change: "demo-change", gate: "proposal_reviewed", role: "critic", round: 1, packet_format: "agent" },
-    },
-    {
-        name: "review_complete_verifier",
-        description: "review-packet agent output for the final verification lane.",
-        args: { command: "review-packet", change: "demo-change", gate: "review_complete", role: "verifier", round: 1, packet_format: "agent" },
-    },
-];
-const MATERIALIZED_REVIEW_PROMPT_SAMPLES = [
-    {
-        name: "proposal_reviewed_round2_critic",
-        description: "review-packet prompt output for a round>1 disclosure reviewer lane with ledger injection.",
-        args: { command: "review-packet", change: "demo-change", gate: "proposal_reviewed", role: "critic", round: 2, packet_format: "prompt" },
-        requiredMarkers: ["[SUPERSPEC-FINDING-LEDGER gate=proposal_reviewed findings=1]", "PROP-SCOPE-001", "proposal silently widens scope beyond discovery"],
-    },
-    {
-        name: "review_complete_critic_verification",
-        description: "review-packet prompt output for the critic verification_review lane.",
-        args: { command: "review-packet", change: "demo-change", gate: "review_complete", role: "critic", round: 1, evidence_kind: "verification_review", packet_format: "prompt" },
-    },
-];
-const LEDGER_BLOCK_SAMPLES = [
-    {
-        name: "proposal_reviewed_round2_ledger",
-        description: "ledger-render output used by round>1 reviewer prompts.",
-        args: { command: "ledger-render", change: "demo-change", gate: "proposal_reviewed", round: 2 },
-        requiredMarkers: ["[SUPERSPEC-FINDING-LEDGER gate=proposal_reviewed findings=1]", "PROP-SCOPE-001", "proposal silently widens scope beyond discovery"],
-    },
-];
-function ensureReadableTextFile(repoRoot, relPath) {
-    const absPath = join(repoRoot, relPath);
-    if (existsSync(absPath) && statSync(absPath).isFile()) {
-        return readFileSync(absPath, "utf8");
-    }
-    throw new GuardError(`packet_measure_missing_file: ${relPath}`);
-}
-function dedupePaths(paths) {
-    return [...new Set(paths)].sort();
-}
-function measuredFiles(repoRoot, relPaths) {
-    return dedupePaths(relPaths).map((relPath) => ({
-        path: relPath,
-        chars: ensureReadableTextFile(repoRoot, relPath).length,
-    }));
-}
-function measureSurface(repoRoot, relPaths) {
-    const files = measuredFiles(repoRoot, relPaths);
-    return {
-        total_chars: files.reduce((sum, item) => sum + item.chars, 0),
-        files,
-    };
-}
-function writeSyntheticText(repoRoot, relPath, text) {
-    const absPath = join(repoRoot, relPath);
-    mkdirSync(dirname(absPath), { recursive: true });
-    writeFileSync(absPath, text, "utf8");
-}
-function syntheticRef(root, relPath) {
-    return {
-        path: relPath,
-        blob_sha: file_blob_sha(join(root, relPath)),
-    };
-}
-function syntheticStatus(repoRoot, changeRoot) {
-    return {
-        changeRoot,
-        planningHome: { root: repoRoot },
-        schemaName: "spec-driven",
-        applyRequires: ["tasks"],
-        artifacts: ["proposal", "specs", "design", "tasks"].map((id) => ({ id, status: "done", missingDeps: [] })),
-    };
-}
-function materializeSyntheticEvidence(changeRoot, relPath, evidence) {
-    const absPath = join(changeRoot, relPath);
-    mkdirSync(dirname(absPath), { recursive: true });
-    writeFileSync(absPath, `${JSON.stringify(evidence, null, 2)}\n`, "utf8");
-    return { ...evidence, _path: relPath };
-}
-function syntheticDisclosureEvidences(changeRoot) {
-    const promptRef = ".superspec/reports/proposal-r1-critic-prompt.md";
-    const outputRef = ".superspec/reports/proposal-r1-critic.md";
-    mkdirSync(dirname(join(changeRoot, promptRef)), { recursive: true });
-    writeFileSync(join(changeRoot, promptRef), "critic prompt for proposal round 1\n", "utf8");
-    writeFileSync(join(changeRoot, outputRef), "critic found a scope issue\n", "utf8");
-    const finding = {
-        finding_id: "PROP-SCOPE-001",
-        finding_uid: "proposal_reviewed:EV-proposal-r1-critic:PROP-SCOPE-001",
-        finding_type: "blocker",
-        category: "scope",
-        material_categories: ["scope"],
-        decision_scope_key: "demo-change:proposal:hidden-scope",
-        summary: "proposal silently widens scope beyond discovery",
-    };
-    const targetRefs = [
-        syntheticRef(changeRoot, "proposal.md"),
-        syntheticRef(changeRoot, ".superspec/artifacts/discovery.md"),
-    ];
-    const review = materializeSyntheticEvidence(changeRoot, ".superspec/evidence/reviews/EV-proposal-r1-critic.json", {
-        schema_version: 1,
-        evidence_id: "EV-proposal-r1-critic",
-        change_id: "demo-change",
-        gate: "proposal_reviewed",
-        kind: "review",
-        created_at: "2026-06-08T00:00:00Z",
-        created_by: "measure",
-        status: "pass",
-        agent_role: "critic",
-        execution_mode: "native_subagent",
-        agent_id: "agent-critic",
-        prompt_ref: promptRef,
-        output_ref: outputRef,
-        source_anchors: [],
-        target_refs: targetRefs,
-        review_round_id: "proposal_reviewed-r1",
-        findings: [finding],
-    });
-    const digest = materializeSyntheticEvidence(changeRoot, ".superspec/evidence/reviews/EV-proposal-r1-digest.json", {
-        schema_version: 1,
-        evidence_id: "EV-proposal-r1-digest",
-        change_id: "demo-change",
-        gate: "proposal_reviewed",
-        kind: "main_review_digest",
-        created_at: "2026-06-08T00:01:00Z",
-        created_by: "main-thread",
-        status: "blocked",
-        review_round_id: "proposal_reviewed-r1",
-        target_refs: targetRefs,
-        source_review_evidence_refs: ["EV-proposal-r1-critic"],
-        previous_digest_refs: [],
-        finding_dispositions: [{
-                ...finding,
-                origin_review_evidence_id: "EV-proposal-r1-critic",
-                disposition: "needs_user_decision",
-                rationale: "material scope finding requires user confirmation",
-                route: "stay_same_gate_user_decision",
-                route_reason: "material scope finding requires user confirmation",
-            }],
-    });
-    return [review, digest];
-}
-function createMaterializedMeasureContext() {
-    const repoRoot = mkdtempSync(join(tmpdir(), "superspec-packet-measure-"));
-    const changeRoot = join(repoRoot, "openspec", "changes", "demo-change");
-    writeSyntheticText(repoRoot, "openspec/changes/demo-change/.superspec/artifacts/discovery.md", "discovery facts\n");
-    writeSyntheticText(repoRoot, "openspec/changes/demo-change/.superspec/artifacts/business-invariants.md", "## Business Invariants\n\n| id | description |\n| --- | --- |\n| INV-001 | Preserve behavior |\n");
-    writeSyntheticText(repoRoot, "openspec/changes/demo-change/.superspec/artifacts/test-contract.md", "## Test Contract\n\n| test_id | invariant_refs |\n| --- | --- |\n| TEST-001 | INV-001 |\n");
-    writeSyntheticText(repoRoot, "openspec/changes/demo-change/proposal.md", "proposal\n");
-    writeSyntheticText(repoRoot, "openspec/changes/demo-change/design.md", "design\n");
-    writeSyntheticText(repoRoot, "openspec/changes/demo-change/specs/demo/spec.md", "#### Scenario: Demo\n");
-    writeSyntheticText(repoRoot, "openspec/changes/demo-change/tasks.md", "- [ ] TASK-001 Implement\n  - invariant_refs: INV-001\n  - test_refs: TEST-001\n");
-    const evidences = syntheticDisclosureEvidences(changeRoot);
-    return {
-        repoRoot,
-        changeRoot,
-        status: syntheticStatus(repoRoot, changeRoot),
-        evidences,
-        cleanup: () => rmSync(repoRoot, { recursive: true, force: true }),
-    };
-}
-function withMaterializedMeasureRuntime(ctx, fn) {
-    const overrides = {
-        load_context: () => [ctx.status, ctx.repoRoot, ctx.changeRoot, ctx.evidences],
-        dirty_worktree_paths: () => [],
-        file_blob_sha,
-    };
-    const previous = new Map();
-    for (const [key, value] of Object.entries(overrides)) {
-        previous.set(key, { had: Object.prototype.hasOwnProperty.call(runtime, key), value: runtime[key] });
-        runtime[key] = value;
-    }
-    try {
-        return fn();
-    }
-    finally {
-        for (const [key, item] of previous) {
-            if (item.had)
-                runtime[key] = item.value;
-            else
-                delete runtime[key];
-        }
-    }
-}
-function packetOutputText(args) {
-    const result = dispatch_packet(args);
-    if (result.output_format === "prompt") {
-        const text = String(result.payload);
-        return text.endsWith("\n") ? text : `${text}\n`;
-    }
-    return `${JSON.stringify(result.payload, null, 2)}\n`;
-}
-function measureMaterializedSamples(specs) {
-    const ctx = createMaterializedMeasureContext();
-    try {
-        const samples = withMaterializedMeasureRuntime(ctx, () => specs.map((spec) => {
-            const text = packetOutputText(spec.args);
-            const missingMarkers = (spec.requiredMarkers ?? []).filter((marker) => !text.includes(marker));
-            if (missingMarkers.length > 0) {
-                throw new GuardError(`packet_measure_missing_marker: ${spec.name}: ${missingMarkers.join(", ")}`);
-            }
-            return {
-                name: spec.name,
-                description: spec.description,
-                chars: text.length,
-                ...(spec.requiredMarkers && spec.requiredMarkers.length > 0 ? { matched_markers: [...spec.requiredMarkers] } : {}),
-            };
-        }));
-        return {
-            total_chars: samples.reduce((sum, item) => sum + item.chars, 0),
-            samples,
-        };
-    }
-    finally {
-        ctx.cleanup();
-    }
-}
-function installPayloadSourcePaths(repoRoot) {
-    const { mappings, problems } = load_install_map(repoRoot);
-    if (problems.length > 0)
-        throw new GuardError(`packet_measure_install_map_invalid: ${problems.join("; ")}`);
-    return mappings
-        .filter((mapping) => mapping.kind === "skill" || mapping.kind === "prompt" || mapping.kind === "agent")
-        .map((mapping) => mapping.source);
-}
-export function representative_scenarios() {
-    return REPRESENTATIVE_SCENARIOS;
-}
-export function measure_packet_surface_report(repoRoot) {
-    const packagePayloadSourcePaths = installPayloadSourcePaths(repoRoot);
-    const fixedSurfaceInstallUpperBound = measureSurface(repoRoot, packagePayloadSourcePaths);
-    const fixedSurfaceRuntimeRequiredSubset = measureSurface(repoRoot, packagePayloadSourcePaths);
-    const scenarios = REPRESENTATIVE_SCENARIOS.map((scenario) => ({
-        name: scenario.name,
-        description: scenario.description,
-        ...measureSurface(repoRoot, scenario.files),
-    }));
-    return {
-        fixed_surface_chars_install_upper_bound: fixedSurfaceInstallUpperBound,
-        fixed_surface_chars_runtime_required_subset: fixedSurfaceRuntimeRequiredSubset,
-        materialized_workflow_packet_chars: measureMaterializedSamples(MATERIALIZED_WORKFLOW_PACKET_SAMPLES),
-        materialized_review_packet_chars: measureMaterializedSamples(MATERIALIZED_REVIEW_PACKET_SAMPLES),
-        materialized_review_prompt_chars: measureMaterializedSamples(MATERIALIZED_REVIEW_PROMPT_SAMPLES),
-        ledger_block_chars: measureMaterializedSamples(LEDGER_BLOCK_SAMPLES),
-        representative_loaded_surface_chars: {
-            scenarios,
-        },
-    };
-}