@birdie_moblie/open_spec 2.1.7

package/dist/usage/parse.js

@@ -0,0 +1,345 @@
+import { sha256 } from '../shared/hash.js';
+export const object = (value) => value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+export const string = (value) => typeof value === 'string' && value ? value : null;
+export const number = (value) => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : null;
+export const zeroTokens = () => ({ input: 0, output: 0, cachedInput: 0, cacheWriteInput: 0, reasoningOutput: 0, total: 0 });
+export function sumTokens(values) {
+    return values.reduce((a, b) => ({ input: a.input + b.input, output: a.output + b.output, total: a.total + b.total,
+        cachedInput: a.cachedInput === null || b.cachedInput === null ? null : a.cachedInput + b.cachedInput,
+        cacheWriteInput: a.cacheWriteInput === null || b.cacheWriteInput === null ? null : a.cacheWriteInput + b.cacheWriteInput,
+        reasoningOutput: a.reasoningOutput === null || b.reasoningOutput === null ? null : a.reasoningOutput + b.reasoningOutput }), zeroTokens());
+}
+export function mergeClaudeTokens(a, b) {
+    const max = (x, y) => x === null ? y : y === null ? x : Math.max(x, y);
+    const complete = (value) => value.cachedInput !== null && value.cacheWriteInput !== null;
+    if (complete(a) !== complete(b)) {
+        // A partial stream can report provisional total input in input_tokens.
+        // Prefer the complete breakdown as a unit; do not add its cache to that total.
+        const chosen = complete(a) ? a : b;
+        const output = Math.max(a.output, b.output);
+        return { ...chosen, output, total: chosen.input + output };
+    }
+    const cachedInput = max(a.cachedInput, b.cachedInput);
+    const cacheWriteInput = max(a.cacheWriteInput, b.cacheWriteInput);
+    const input = Math.max(a.input - (a.cachedInput ?? 0) - (a.cacheWriteInput ?? 0), b.input - (b.cachedInput ?? 0) - (b.cacheWriteInput ?? 0)) + (cachedInput ?? 0) + (cacheWriteInput ?? 0);
+    const output = Math.max(a.output, b.output);
+    return { input, output, total: input + output, cachedInput, cacheWriteInput, reasoningOutput: max(a.reasoningOutput, b.reasoningOutput) };
+}
+export function parseUsageStream(file, text) {
+    const stream = { threadId: `unknown-${sha256(file).slice(0, 16)}`, parentThreadId: null, provider: 'codex', source: 'exec', file,
+        slices: [], issues: [], tools: new Set(), spawns: new Set(), epochs: 1, startedAt: null, endedAt: null, collabObserved: false, apiCalls: null, toolMessages: new Map() };
+    let model = null;
+    let effort = null;
+    let workerId = null;
+    let stepId = null;
+    let previous = null;
+    let terminal = false;
+    let execTurn = 0;
+    const completedTurns = new Map();
+    const seenSnapshots = new Set();
+    const claude = new Map();
+    const requests = new Map();
+    const requestCheckpoints = new Map();
+    const compactions = new Set();
+    let requestCheckpoint = null;
+    const issue = (code, line, severity = 'incomplete') => stream.issues.push({ code, severity, file, line });
+    const attribution = (value) => {
+        const source = typeof value === 'string' ? value : JSON.stringify(value) ?? '';
+        if (/worker\s+(accept|cancel)\b/.test(source)) {
+            workerId = null;
+            stepId = null;
+            return;
+        }
+        const packet = source.match(/\/workers\/(([A-Za-z0-9_.-]+)-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.packet\.json/);
+        if (packet) {
+            workerId = packet[1];
+            stepId = packet[2];
+        }
+        else {
+            const step = source.match(/worker\s+create\b[^\n]*?--step\s+["']?([A-Za-z0-9_.-]+)/);
+            if (step) {
+                stepId = step[1];
+                workerId = null;
+            }
+        }
+    };
+    const snapshot = (raw, line, timestamp) => {
+        const current = normalizeCodex(raw);
+        if (!current) {
+            issue('invalid_usage', line);
+            return;
+        }
+        if (number(raw.total_tokens) !== null && raw.total_tokens !== current.total)
+            issue('total_tokens_mismatch', line);
+        if (current.cachedInput !== null && current.cachedInput > current.input)
+            issue('cache_exceeds_input', line);
+        if (current.reasoningOutput !== null && current.reasoningOutput > current.output)
+            issue('reasoning_exceeds_output', line);
+        const key = JSON.stringify(current);
+        if (seenSnapshots.has(key)) {
+            if (previous && JSON.stringify(previous) !== key)
+                issue('ambiguous_snapshot_replay', line);
+            return;
+        }
+        if (previous && (current.input < previous.input || current.output < previous.output)) {
+            previous = null;
+            seenSnapshots.clear();
+            stream.epochs += 1;
+            issue('counter_reset', line, 'warning');
+        }
+        seenSnapshots.add(key);
+        const delta = previous ? subtractTokens(current, previous) : current;
+        previous = current;
+        if (delta.input === 0 && delta.output === 0)
+            return;
+        stream.slices.push({ key: `${stream.threadId}:${stream.epochs}:${line}`, threadId: stream.threadId, model, effort, workerId, stepId, timestamp, tokens: delta, file, line });
+    };
+    text.split('\n').forEach((lineText, index) => {
+        if (!lineText.trim())
+            return;
+        const line = index + 1;
+        let row;
+        try {
+            row = object(JSON.parse(lineText));
+        }
+        catch {
+            issue('malformed_jsonl', line);
+            return;
+        }
+        const timestamp = string(row.timestamp);
+        if (timestamp) {
+            stream.startedAt ??= timestamp;
+            stream.endedAt = timestamp;
+        }
+        const payload = object(row.payload);
+        if (row.type === 'session_meta') {
+            stream.source = 'rollout';
+            stream.threadId = string(payload.id) ?? stream.threadId;
+            const source = object(payload.source);
+            const subagent = object(source.subagent);
+            stream.parentThreadId = string(object(subagent.thread_spawn).parent_thread_id) ?? string(object(subagent.spawn).parent_thread_id);
+        }
+        if (row.type === 'thread.started')
+            stream.threadId = string(row.thread_id) ?? stream.threadId;
+        if (row.type === 'turn.started') {
+            terminal = false;
+            execTurn += 1;
+        }
+        if (row.type === 'event_msg' && payload.type === 'task_started')
+            terminal = false;
+        if (row.type === 'turn.completed' || (row.type === 'event_msg' && payload.type === 'task_complete'))
+            terminal = true;
+        if (row.type === 'turn_context') {
+            model = string(payload.model);
+            effort = string(payload.effort) ?? string(payload.reasoning_effort);
+        }
+        if (row.type === 'compacted') {
+            const id = string(payload.compaction_response_id);
+            if (id)
+                compactions.add(id);
+        }
+        if (row.type === 'token_usage_record') {
+            const id = string(payload.response_id);
+            const tokens = normalizeCodex(object(payload.usage));
+            if (!id || !tokens || payload.thread_id !== stream.threadId)
+                issue('invalid_request_usage', line);
+            else {
+                const checkpoint = normalizeCodex(object(payload.thread_token_usage));
+                const previousCheckpoint = requestCheckpoints.get(id);
+                if (checkpoint && previousCheckpoint) {
+                    if (!matchingTokens(checkpoint, previousCheckpoint))
+                        issue('conflicting_request_checkpoint', line);
+                    for (const key of ['cachedInput', 'cacheWriteInput', 'reasoningOutput'])
+                        previousCheckpoint[key] ??= checkpoint[key];
+                }
+                else if (checkpoint)
+                    requestCheckpoints.set(id, checkpoint);
+                const existing = requests.get(id);
+                if (existing && JSON.stringify(existing.tokens) !== JSON.stringify(tokens))
+                    issue('conflicting_request_usage', line);
+                else if (!existing) {
+                    requests.set(id, { key: id, threadId: stream.threadId, model, effort, workerId, stepId, timestamp, tokens, file, line });
+                    requestCheckpoint = checkpoint;
+                    if (tokens.cachedInput !== null && tokens.cachedInput > tokens.input)
+                        issue('cache_exceeds_input', line);
+                    if (tokens.reasoningOutput !== null && tokens.reasoningOutput > tokens.output)
+                        issue('reasoning_exceeds_output', line);
+                }
+            }
+        }
+        if (row.type === 'response_item') {
+            if (payload.type === 'function_call' || payload.type === 'custom_tool_call') {
+                const id = string(payload.call_id) ?? `${file}:${line}`;
+                stream.tools.add(id);
+                attribution(payload.arguments ?? payload.input ?? '');
+                if (string(payload.name)?.endsWith('spawn_agent'))
+                    stream.spawns.add(id);
+            }
+            if (payload.type === 'message' && payload.role === 'user')
+                attribution(payload.content);
+        }
+        if (row.type === 'event_msg' && payload.type === 'token_count' && object(payload.info).total_token_usage)
+            snapshot(object(object(payload.info).total_token_usage), line, timestamp);
+        if (row.type === 'turn.completed' && row.usage) {
+            // exec usage is a turn increment, unlike rollout total_token_usage snapshots.
+            const tokens = normalizeCodex(object(row.usage));
+            const key = JSON.stringify(tokens);
+            if (!tokens)
+                issue('invalid_usage', line);
+            else if (completedTurns.has(execTurn)) {
+                if (completedTurns.get(execTurn) !== key)
+                    issue('conflicting_turn_usage', line);
+            }
+            else {
+                completedTurns.set(execTurn, key);
+                if (tokens.cachedInput !== null && tokens.cachedInput > tokens.input)
+                    issue('cache_exceeds_input', line);
+                if (tokens.reasoningOutput !== null && tokens.reasoningOutput > tokens.output)
+                    issue('reasoning_exceeds_output', line);
+                stream.slices.push({ key: `${stream.threadId}:exec-turn:${execTurn}`, threadId: stream.threadId, model, effort, workerId, stepId, timestamp, tokens, file, line });
+            }
+        }
+        if (row.type === 'turn.failed') {
+            if (row.usage)
+                snapshot(object(row.usage), line, timestamp);
+            issue(row.usage ? 'failed_turn' : 'failed_turn_usage_unverified', line, row.usage ? 'warning' : 'incomplete');
+        }
+        if (row.method === 'model/rerouted' || payload.type === 'model_rerouted') {
+            model = string(object(row.params).toModel) ?? string(payload.to_model);
+            issue('model_rerouted', line);
+        }
+        const item = object(row.item);
+        if (row.type === 'item.completed' && ['command_execution', 'mcp_tool_call'].includes(String(item.type))) {
+            stream.tools.add(string(item.id) ?? `${file}:${line}`);
+            attribution(item.command ?? item.arguments ?? '');
+        }
+        if (String(item.type).includes('collab'))
+            stream.collabObserved = true;
+        const message = object(row.message);
+        if (row.type === 'assistant' && message.usage) {
+            stream.provider = 'claude';
+            stream.source = 'claude';
+            if (message.model === '<synthetic>') {
+                // Local interruption/compaction markers are not model calls. An API error
+                // with synthetic zero usage does not prove the failed request was free.
+                if (row.isApiErrorMessage === true)
+                    issue('claude_failed_request_usage_unverified', line);
+                else
+                    issue('claude_synthetic_message', line, 'warning');
+                return;
+            }
+            const session = string(row.sessionId) ?? stream.threadId;
+            const agent = string(row.agentId) ?? (file.includes('/subagents/') ? file.match(/agent-([^/]+)\.jsonl$/)?.[1] ?? null : null);
+            stream.threadId = agent ? `${session}::agent:${agent}` : session;
+            stream.parentThreadId = string(row.parentSessionId) ?? (agent ? session : null);
+            model = string(message.model) ?? model;
+            effort = string(row.effort) ?? string(row.reasoning_effort) ?? effort;
+            const id = string(message.id);
+            if (!id) {
+                issue('claude_message_id_missing', line);
+                return;
+            }
+            const usage = object(message.usage);
+            const previous = claude.get(id);
+            const raw = { ...(previous?.raw ?? {}) };
+            const inputKeys = ['input_tokens', 'cache_read_input_tokens', 'cache_creation_input_tokens'];
+            const completeInput = (value) => inputKeys.every((key) => number(value[key]) !== null);
+            if (completeInput(usage)) {
+                for (const key of inputKeys)
+                    raw[key] = usage[key];
+            }
+            else if (!completeInput(raw)) {
+                // Genuine partial deltas may omit unchanged fields. Preserve them until
+                // a complete tuple arrives, including an explicit downward correction.
+                for (const key of inputKeys)
+                    if (number(usage[key]) !== null)
+                        raw[key] = usage[key];
+            }
+            const output = number(usage.output_tokens);
+            if (output !== null)
+                raw.output_tokens = Math.max(number(raw.output_tokens) ?? 0, output);
+            claude.set(id, { raw, slice: previous?.slice ?? { key: id, threadId: stream.threadId, model, effort, workerId, stepId, timestamp, file, line } });
+            for (const block of Array.isArray(message.content) ? message.content : []) {
+                const tool = object(block);
+                if (tool.type !== 'tool_use')
+                    continue;
+                const toolId = string(tool.id) ?? `${file}:${line}`;
+                stream.tools.add(toolId);
+                stream.toolMessages.set(toolId, id);
+                attribution(tool.input);
+                if (['Agent', 'Task'].includes(String(tool.name)))
+                    stream.spawns.add(toolId);
+            }
+        }
+    });
+    if (stream.provider === 'claude') {
+        stream.slices = [];
+        for (const { raw, slice } of claude.values()) {
+            const input = number(raw.input_tokens);
+            const output = number(raw.output_tokens);
+            if (input === null || output === null) {
+                issue('invalid_usage', slice.line);
+                continue;
+            }
+            const cachedInput = number(raw.cache_read_input_tokens);
+            const cacheWriteInput = number(raw.cache_creation_input_tokens);
+            if (cachedInput === null || cacheWriteInput === null)
+                issue('claude_cache_fields_missing', slice.line);
+            const totalInput = input + (cachedInput ?? 0) + (cacheWriteInput ?? 0);
+            stream.slices.push({ ...slice, tokens: { input: totalInput, output, cachedInput, cacheWriteInput, reasoningOutput: null, total: totalInput + output } });
+        }
+    }
+    if (stream.threadId.startsWith('unknown-'))
+        stream.issues.push({ code: 'thread_id_missing', severity: 'incomplete', file });
+    if (stream.provider === 'codex' && !terminal)
+        stream.issues.push({ code: 'session_completion_unverified', severity: 'incomplete', file });
+    if (requests.size) {
+        const recorded = sumTokens([...requests.values()].map((slice) => slice.tokens));
+        const snapshots = sumTokens(stream.slices.map((slice) => slice.tokens));
+        const compactionSlices = [...compactions].flatMap((id) => requests.has(id) ? [requests.get(id)] : []);
+        // Some Codex versions exclude automatic compaction from legacy token_count
+        // snapshots, while response records and their thread checkpoint include it.
+        // Reconcile only an explicitly identified, fully accounted-for difference.
+        const reconciledCompaction = compactionSlices.length > 0 && compactionSlices.length === compactions.size
+            && requestCheckpoint !== null && matchingTokens(recorded, requestCheckpoint)
+            && matchingTokens(recorded, sumTokens([snapshots, ...compactionSlices.map((slice) => slice.tokens)]));
+        if (!stream.slices.length || (recorded.input === snapshots.input && recorded.output === snapshots.output) || reconciledCompaction) {
+            stream.slices = [...requests.values()];
+            stream.apiCalls = requests.size;
+            for (const slice of compactionSlices) {
+                slice.workerId = null;
+                slice.stepId = 'compaction';
+            }
+            if (reconciledCompaction)
+                stream.issues.push({ code: 'compaction_usage_reconciled', severity: 'warning', file });
+        }
+        else {
+            stream.issues.push({ code: 'request_snapshot_mismatch', severity: 'incomplete', file });
+            const input = Math.max(0, recorded.input - snapshots.input);
+            const output = Math.max(0, recorded.output - snapshots.output);
+            if (input || output)
+                stream.slices.push({ key: `${stream.threadId}:request-gap`, threadId: stream.threadId, model: null, effort: null,
+                    workerId: null, stepId: null, timestamp: null, file, line: 1, tokens: { input, output, total: input + output, cachedInput: null, cacheWriteInput: null, reasoningOutput: null } });
+        }
+    }
+    for (const slice of stream.slices)
+        slice.threadId = stream.threadId;
+    return stream;
+}
+function matchingTokens(a, b) {
+    return a.input === b.input && a.output === b.output
+        && ['cachedInput', 'cacheWriteInput', 'reasoningOutput'].every((key) => a[key] === null || b[key] === null || a[key] === b[key]);
+}
+function normalizeCodex(raw) {
+    const input = number(raw.input_tokens);
+    const output = number(raw.output_tokens);
+    if (input === null || output === null)
+        return null;
+    return { input, output, cachedInput: number(raw.cached_input_tokens), cacheWriteInput: number(raw.cache_write_input_tokens), reasoningOutput: number(raw.reasoning_output_tokens), total: input + output };
+}
+function subtractTokens(current, previous) {
+    const subtract = (a, b) => a === null || b === null || a < b ? null : a - b;
+    return { input: current.input - previous.input, output: current.output - previous.output, total: current.total - previous.total,
+        cachedInput: subtract(current.cachedInput, previous.cachedInput), cacheWriteInput: subtract(current.cacheWriteInput, previous.cacheWriteInput), reasoningOutput: subtract(current.reasoningOutput, previous.reasoningOutput) };
+}
+//# sourceMappingURL=parse.js.map

package/dist/usage/types.d.ts

@@ -0,0 +1,103 @@
+export interface Tokens {
+    input: number;
+    output: number;
+    cachedInput: number | null;
+    cacheWriteInput: number | null;
+    reasoningOutput: number | null;
+    total: number;
+}
+export interface UsageIssue {
+    code: string;
+    severity: 'warning' | 'incomplete';
+    file: string;
+    line?: number;
+    threadId?: string;
+}
+export interface UsageSlice {
+    key: string;
+    threadId: string;
+    model: string | null;
+    effort: string | null;
+    workerId: string | null;
+    stepId: string | null;
+    timestamp: string | null;
+    tokens: Tokens;
+    file: string;
+    line: number;
+    attribution?: 'event_window' | 'log_hint' | 'request_id' | 'unattributed';
+}
+export interface SessionUsage {
+    threadId: string;
+    parentThreadId: string | null;
+    provider: 'codex' | 'claude';
+    source: 'rollout' | 'exec' | 'claude';
+    files: string[];
+    models: string[];
+    efforts: string[];
+    tokens: Tokens;
+    usageObservations: number;
+    toolCalls: number;
+    spawnCalls: number;
+    epochs: number;
+    apiCalls: number | null;
+    startedAt: string | null;
+    endedAt: string | null;
+    elapsedMs: number | null;
+}
+export interface UsageReport {
+    version: 1;
+    changeName: string;
+    totals: Tokens;
+    sessions: SessionUsage[];
+    slices: UsageSlice[];
+    byStage: Array<{
+        stepId: string;
+        tokens: Tokens;
+        observations: number;
+    }>;
+    coverage: {
+        tokenComplete: boolean;
+        modelsKnown: boolean;
+        effortsKnown: boolean;
+        comparisonEligible: boolean;
+        issues: UsageIssue[];
+    };
+    cost: {
+        kind: 'actual' | 'estimated' | 'unavailable';
+        usd: number | null;
+        source: string | null;
+        complete: boolean;
+    };
+    counts: {
+        sessions: number;
+        usageObservations: number;
+        toolCalls: number;
+        apiCalls: number | null;
+    };
+}
+export interface UsageOptions {
+    changeName: string;
+    sessions: string[];
+    events?: string;
+    expectedModel?: string;
+    expectedEffort?: string;
+    rates?: RateCard;
+    billing?: Billing;
+}
+export interface RateCard {
+    source: string;
+    models: Record<string, {
+        inputPerMillion: number;
+        cachedInputPerMillion: number;
+        cacheWriteInputPerMillion?: number;
+        outputPerMillion: number;
+    }>;
+}
+export interface Billing {
+    source: string;
+    charges: Array<{
+        threadId: string;
+        usd: number;
+    }>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/usage/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/docs/getting-started.md

@@ -0,0 +1,20 @@
+# 快速开始
+
+1. 安装 Node.js 22 或 24。
+2. `openspec init --tools claude,codex,cursor --yes`，或先用 `--skip-plugins` 只建立项目配置。
+3. 在宿主中调用 `/opsx-propose` 描述目标。
+4. 审查 Gate-A 后调用 `/opsx-apply`。
+5. `/opsx-verify` 通过 Gate-C 后 `/opsx-archive`。
+
+`init --preset flutter-mobile --yes` 会按项目配置中的完整 Git SHA（或 `refs/tags/<tag>`）解析 marketplace，校验插件后调用 Claude/Codex 原生 marketplace 与 selector。项目 `openspec/marketplace-lock.json` 记录 resolved SHA、marketplace digest 和 plugin digest；adapter 合同来自插件 `plugin.json` 的 `extensions["org.openspec"]`，不写进 CLI。
+
+Claude 的 marketplace 与插件一律以 `--scope local` 安装，写入 `.claude/settings.local.json`（项目级、仅本人、不入库）：其中的 marketplace 路径是本机缓存的绝对路径，用 project scope 会随 `.claude/settings.json` 提交给团队成员。每位成员在自己机器上执行一次 `openspec init --yes` 即可；团队共享的是 `openspec/config.yaml` 与 `marketplace-lock.json`。
+
+初始化结果可能是：
+
+- `complete`：自动步骤全部完成。
+- `pending_user_action`：非 TTY 未确认，或 Cursor 需要在 Customize → Plugins 中完成；退出码 2。
+- `partial`：部分 marketplace/宿主操作失败；退出码 1，并聚合返回 `issues`。
+- `skipped`：显式使用 `--skip-plugins`，跳过清单写入 `openspec/.runtime/init.json`。
+
+测试和并行项目可设置 `OPENSPEC_HOME=/path/to/isolated/home`，避免读写真实用户 cache。`node openspec/install-cli.mjs --check` 校验 Node/npm 与项目钉住的精确 CLI 版本，`openspec doctor --json` 同时校验 installer metadata、宿主交付 digest，以及 config 声明的 marketplace/plugin lock 完整性。

package/docs/guides/configuration.md

@@ -0,0 +1,33 @@
+# 项目配置
+
+`openspec/config.yaml` 核心字段：
+
+- `schema`: 固定 `spec-product`
+- `taskCategories`: 覆盖或扩展默认分类 `ui` / `logic` / `api-codegen` / `test` / `infra`，每类可写 `notes`；设为 `null` 会删除对应默认分类。
+- `hooks`: 统一外挂，`stage` 严格为 `collect` | `parse` | `tech` | `plan` | `execute` | `verify`，`type` 严格为 `notes` | `skill` | `file` | `check` | `command`，并按 stage 校验可用组合与必填字段。`parse` / `tech` / `plan` 支持五种类型，collect 保留 adapter/skill，verify 支持 command/skill/file/check。
+- `verify.reviewScope` / `verify.failurePolicy`
+- `plugins` / `marketplaces`：宿主的 marketplace ref 与 `openspec/marketplace-lock.json` 是实际使用版本的权威记录，可在兼容范围内独立于 preset 升级；`plugins[].minVersion` 可选，声明最低插件版本，见 [插件能力迁移](plugin-migration.md#兼容检查)
+
+每个 plan task 必须给出当前有效的 `category`。Task 只接受软提示 `refScope`；`files` / `allowedDirs` 已移除，`refScope` 不构成写入沙箱。
+
+parse / tech / plan Worker packet 也携带 `initContext`：`rules` 为空，`hooks` 是该 stage 全部 hook 的 descriptor（notes 也算），回执规则与 code Worker 相同。这是把项目级约定（例如 `file` hook 指向的 UI 约定清单、spec 结构检查）送达 spec 与计划作者的唯一通道；required `file` 缺失时 Worker 应返回 `blocked`。plan packet 的 `planNotes` 只列各分类说明。
+
+code Worker packet 的 `initContext` 顺序固定：category notes、配置声明顺序中的匹配 execute Hook；task notes 仅在 `packet.task.notes`，不重复注入。Hook 未写 `taskCategories` 时匹配所有 task；空数组不匹配；包含当前 category 时匹配。五种 Hook 只传 descriptor：skill/file 不内联正文，command 由 Worker 调用 `openspec worker check` 执行并取得 CLI 回执；文字 passed 不能代替执行。
+
+execute Hook 的 `required` 默认 `true`。Worker 的 completed result 必须在 `executeHookResults` 中把每个 required Hook 报为 `passed`；未知 ID、重复 ID、缺失、failed 或 skipped 都会被拒收。optional Hook 可 failed/skipped 并写入事件。required skill/file 不可用时 Worker 应返回 `blocked`。
+
+verify `command` 由引擎直接启动子进程执行，不经 shell；需要管道或取反时可写 `sh -c '<script>' sh {files}`（`{files}` 必须是独立参数，`splitCommand` 支持单引号）。`command` 作用于**整个变更文件**而非变更行，所以只适合既有代码里不会出现合法命中的规则（如 analyze、test）；文案、颜色这类既有代码中大量合法存在的模式不要写成 grep，否则任何触及老文件的 task 都会误报，应交给 `check` 回执与审查类 `skill`。
+
+verify 每次创建独立 run。命令、skill/file/check evidence 和 QA report 都必须属于当前 run；required evidence 缺失、file digest 变化或旧 report 不会通过。`reviewScope` 先裁剪引擎 changed-set，`failurePolicy` 只控制 optional 失败，不能放行 required Hook。
+
+Config 为严格 schema：重复 Hook ID、重复 collect capability、未知 category 引用、旧 `context/rules`、可变 marketplace branch ref 都会报错。Preset 按 Hook ID 与 plugin selector 幂等合并，同一插件取较高的 `minVersion`；宿主已声明的 marketplace 保留自身的 repo 与 ref，preset 只补充宿主缺少的 marketplace。Preset 还可声明 `scaffold: [{ path, template, description }]`：`init --preset` 与 `preset apply` 会把 `presets/<template>` 复制到项目 `path`，只创建不覆盖；模板首行的 `<!-- openspec:fill-me -->` 标记未删除前，指向该文件的 `file` hook 不能回执 `passed`。
+
+`designRefs` 是 task-plan 的可选节点 id 数组，省略/空数组合法，非空项必须是非空字符串。`packet.refs.design` 提供设计来源 locator 与采集 artifact；详细格式与 status 提示见 [工作流](workflow.md#设计节点引用)。
+
+`verify` 的 optional `check` 若标 `category: todo`，始终仅提供信息，不被 failurePolicy 提升为阻塞；清单由 `openspec todo` 和 report.pendingWork 提供。其他 check 的原有 failurePolicy 不变。命令全量日志与 2KB 摘要见 [工作流](workflow.md#产物与待办)。
+
+插件 Hook 通过 `use: entry@marketplace` 引用根 manifest 的 `extensions.org.openspec.hooks`，首轮支持 skill/command；与 name/command/path 等内联实现互斥。`operation: preview` 切换为 source adapter 的预演入口。宿主 input 为 JSON 参数，inputFiles 为额外依赖文件路径；动态 --input 的顶层值优先。类型、阶段、重复 ID、损坏和缺失入口明确失败。详情及示例见[插件运行契约](../maintainers/plugin-runtime-contract.md)。
+
+已定制的宿主迁移使用精确差异，保留 Hook 的类型、command、required、参数、范围和顺序；同 ID 的 preset 合并是整项替换，不能用它覆盖宿主验收命令。
+
+parse/tech/plan 的 Hook 可用 capability 限定仅在当前来源账本包含该能力时适用；省略则应用于整个阶段。required tech command 只在适用时禁止 skipTech。

package/docs/guides/cost-benchmark.md

@@ -0,0 +1,88 @@
+# 用量分析与成本实验
+
+`tools/experiments/` 仅在源码仓库提供，不随 npm 或原生插件运行制品安装。业务夹具和专用工具由独立实验工程提供。
+
+## 独立 Claude 工作流验证入口
+
+`node tools/experiments/claude-propose-benchmark.mjs <config.json>` 是独立实验入口，只在获授权的有限批次中使用，不属于正常 Worker 调度。配置的 `model`、`effort` 冻结本次请求；必须显式给出，省略即拒绝启动。切换供应商后先核实当前配置，双方使用同一请求模型和 effort 重跑，不拿跨供应商历史运行计算收益。服务端返回名称与实际账单须分别记录；模型名不证明底层模型身份。
+
+已完成的 R0 可以作为后续 R1 修复轮次的固定参照，不必每轮付费重跑。复用前核对供应商/账户、请求模型与 effort、Claude/来源工具版本、业务与规则快照、入口提示、来源内容及统计口径；隔离路径可规范化后比较。纯实验记录器修复须独立证明不改变转发内容与权限。记录被复用运行的路径和摘要，保留其原始失败与质量缺口；候选仍按事实清单验收，不能以基线漏采为标准。
+
+模型、供应商、来源或其他影响执行的共同条件变化时，旧 R0 只作历史参考；需要收益判断则在匹配条件下建立新基线。实时来源在候选返回后再核对摘要，内容不同不计算优化收益。复用单次历史基线只能形成单轮比较，不能排除服务负载与随机性，也不能宣称稳定提速或实际账单节省。
+
+工作流 fixture 必须包含由被测包 `generateInstallCli` 生成、版本匹配的 `openspec/install-cli.mjs`，并将该文件纳入 `inputs` 摘要。这里只生成并核对文件，不执行安装，不覆盖项目配置。冻结业务输入、提示和转发脚本之后再启动；缺文件、版本不符或提示违反场景声明的歧义检查时，在调用 Claude 前失败。
+
+提示中的工具示例取自所选插件的真实命令，不用斜杠缩写让 Agent 猜测。
+
+`tools: ""` 的 MCP-only 小探针不执行工作流入口，因此不要求安装元数据；不能用这类探针替代完整工作流对照。入口检查可通过 `node --test test/benchmark/claude-preflight.check.mjs` 免费验证。实跑中的失败、试错、资料重写和收尾请求全部保留，来源保真通过不等于收益成立。
+
+`usage analyze` 与 `doctor --cost` 只读。`tools/experiments/cost-benchmark.mjs run|continue` 会启动真实模型会话，须由用户明确授权；不内置 token 或美元上限。原始提示词、源码和工具返回留在本地 JSONL，报告只给统计、问题和证据路径。
+
+## Apply 的真实设计对照
+
+`node tools/experiments/claude-apply-benchmark.mjs <config.json>` 为 apply 的独立实验入口，复用上述安装元数据、制品和输入摘要校验，按场景声明所需的外部适配器。它不属于正常 Worker 调度，也不修改用户全局模型或插件配置。
+
+- 配置必须显式给出 `stage: "apply"`、`model`、`effort`、`claudeBinary`、`expectedCompletedTaskIds` 和 `expectedNode`（`code` 或 `gate_b`）。`measurement` 记录页面及其 task 集合，公共准备单列。
+- 场景通过 scenario.requiredInputs 和 scenario.checks 声明冻结输入及启动前检查。脚本和断言归独立实验工程，不从宿主文件名推断工具链。成功摘要记入 request.pagePreflight；本地预检不代替编译与行为验收。
+- 用户选择完成页面后比较时使用 `usagePolicy: "observe"`：必须省略 turns、美元、请求数和 token 限制，不传相应 CLI 上限；用量缺失或监控异常记证据，不因此终止页面。可省略 `timeoutMs`；页面按任务完成或真实阻塞结束。
+- 只有获授权采用阈值停止时使用 `usagePolicy: "enforce"`（兼容旧配置的默认值）：冻结正数 `maxTurns`、`maxBudgetUsd`、`timeoutMs`，以及正整数 `maxObservedModelRequests`、`maxObservedInputTokens`、`maxSingleRequestInputTokens`。美元参数是 CLI 估值限制，不代表已取得账单或证明活动子任务已限流。
+- 保留生命周期 hooks；所需插件、MCP 服务和额外工具由 scenario.requiredPlugins、scenario.mcpServers 与 scenario.allowedTools 显式声明。
+- 本入口开放实现所需的本地工具及场景声明的额外工具；通过会话级 `apply-worker`（`model: "inherit"`）执行节点，控制提示指定该类型且不传模型覆盖，避免误选全局代理路由。一个 code task 的 scout / build / verify / repair 各派发一次该子代理，每次只传对应节点文件与少量路径。固定工具列表不是文件系统沙箱，输入/改动范围仍需核查。
+- 子进程设置 `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS=0`，避免 controller 结束后 CLI 的后台等待上限中断未完成 worker，并把实际环境覆盖写入 request。控制会话优先前台等待 Agent；已有后台任务用 `TaskOutput` 等待，不能仅派发就结束。该环境开关须随固定 Claude 版本验证，不修改全局配置。
+- 正式运行前验证实际 Worker 的 `get_design_context` 和 `get_screenshot`；注册成功或父会话 metadata 成功不能代替子 Worker 证据。保存原始失败，修复后在新输出目录重试。
+- 两侧从同一宿主/plan/决定及前置代码快照开始，真实设计请求、截图和返工计入各侧成本；核对设计内容/版本一致性，变化的来源不能作为可比样本。
+- runner 每秒读取本会话及原生子任务日志，按现有 message ID 去重规则合计请求与输入。仅 enforce 模式在达到用量限制、启动 60 秒无用量或监控失败时停止专属进程组并保存 `stopReason`；observe 模式持续记录。显式配置的运行超时、进程错误或本地输出缓冲超限另行报告。只能在用量回报后停止，可能超出一个或多个在途请求；不是账户美元硬上限。中断缺失的用量、缓存或最终费用保持 unknown，不自动续跑。
+- `run.json` 的完成标志只核验 CLI 退出、被测 OpenSpec 插件、场景要求的插件出现、目标节点、任务完成状态及未触发停止；它不是业务或视觉质量结论。另行审查原生日志中的真实 Figma 调用、子 Agent 模型、截图和行为测试。共用前置准备单列，完整 apply 成本仍须包含它。
+- 原生消息与 CLI `modelUsage` 的汇总分别保留，覆盖范围未核平时 `auxiliaryUsage` 为 null；不能把两者差额当辅助用量，更不能将负差额截成 0。缺失 CLI 汇总保持 null，`usageReconciliation` 明确记录未核平。
+- 离线入口检查：`node --test test/benchmark/claude-apply-preflight.check.mjs test/benchmark/claude-apply-process.check.mjs test/benchmark/apply-session-metrics.check.mjs`。该检查不启动模型，也不证明 Figma 已登录或目标文件有权限。
+- 运行结束后 `node tools/experiments/apply-session-metrics.mjs <run 目录>` 只读汇总会话级行为指标：控制会话 Read / 图片 Read / CLI 调用，各 Worker 阶段、首写前 Read、图片 Read、像素脚本、峰值单请求输入、≥200k 请求数、是否写出 result.json、与前序 Worker 的重复读取比例，并对照实验声明的目标给出逐项判定。图片与像素脚本按文件后缀和命令关键词识别，是启发式而非精确统计；`--json` 输出完整字段。
+
+## 用量口径
+
+```bash
+openspec usage analyze --change example \
+  --session /evidence/controller-rollout.jsonl /evidence/child-rollout.jsonl \
+  --session /evidence/exec.jsonl \
+  --expect-model gpt-6-astra --expect-effort high --format md
+```
+
+- Codex `input_tokens` 已包含缓存输入，输出已包含 reasoning；缓存写入、推理明细缺失时记 unknown。不要把明细再叠加。
+- 新版持久化日志有 `token_usage_record` 时按 `response_id` 去重，并与累计快照核对；旧版使用累计快照差分。快照重置分段，重复/冲突/尾部中断明确报告。
+- 自动压缩按 `compacted.compaction_response_id` 关联真实请求，计入总量并单列 `compaction` 阶段。部分客户端的旧 `token_count` 快照不包含该请求；只有逐请求合计等于请求记录中的线程累计值，且旧快照与已识别压缩用量之和完全解释差额时才接受这种差异，并报告 `compaction_usage_reconciled`。相同响应 ID 的累计值冲突和未解释的缺口仍阻止比较；完全相同的重复记录只计一次。
+- exec 的 `turn.completed.usage` 按每轮增量处理，不能当线程累计快照做差；这一语义与 [Codex 原生事件定义](https://github.com/openai/codex/blob/main/codex-rs/exec/src/exec_events.rs) 一致。多个恢复执行导出缺少稳定 turn ID 时必须补 rollout，不能据此宣称总量完整。
+- 同线程 rollout 优先于 exec 导出，重复文件/重复事件不重复收费。冲突时保留已知差额为未归属用量，并禁止比较。调用次数可由请求记录证明时才给数字；工具调用数、用量观测数独立统计。
+- 必须提供控制会话、全部实际子线程及独立执行、失败与重试日志。缺子线程、缺终止记录、计数歧义会使 `tokenComplete=false`。旧 exec JSON 缺模型/effort 时补持久化 rollout。
+- `--events <events.jsonl>` 可补充阶段归属。无法归属的消耗仍计入总量。启发式阶段归属不替代线程总量。
+- Claude 使用独立公式：input + cache read + cache creation。流式消息跨文件按 message ID 合并；完整输入/缓存分项覆盖临时输入值，不能逐字段取最大值后将临时总输入与最终缓存相加。完整分项尚未出现时保留部分字段并标记覆盖缺口；输出保留累计最大值。继承消息归属已知父级发起会话，tool-use ID 只计一次。反序导入不改变结果。父级关联不足时保留用量并报告归属缺口。synthetic 本地消息不算模型请求；synthetic API error 的零值不证明失败调用免费，记录为计量缺口。
+- `comparisonEligible` 只说明这批日志的用量/模型信息满足比较前提；不代表来源一致、隔离已证明、质量通过或降本达标。报告还须核对实验清单与质量证据。
+
+费用默认 `unavailable`。ChatGPT 登录不是逐次美元账单。传入有来源的实际账单 `--billing` 或指定费率 `--rates` 才计算；二者不要混为同一口径：
+
+```json
+{"source":"账单或费率文件的可核查位置","models":{"model-name":{"inputPerMillion":0,"cachedInputPerMillion":0,"cacheWriteInputPerMillion":0,"outputPerMillion":0}}}
+```
+
+以上零值仅展示字段，必须换成有依据的费率。账单格式为 `{"source":"...","charges":[{"threadId":"...","usd":1.23}]}`。模型/缓存/收费项缺失时 `complete=false`，不能宣布美元达标。
+
+## 场景配置与能力诊断
+
+专用工具、资源格式、模型、服务地址、检查脚本和质量断言由独立实验工程保存。新场景显式声明：
+
+```json
+{
+  "scenario": {
+    "requiredInputs": ["experiment/inputs.json", "scripts/check-inputs.mjs"],
+    "checks": [{"command": "node", "args": ["scripts/check-inputs.mjs", "experiment/inputs.json"]}],
+    "requiredPlugins": [],
+    "allowedTools": [],
+    "mcpServers": {},
+    "forbiddenPromptPatterns": []
+  }
+}
+```
+
+requiredInputs 必须包含在冻结 inputs 摘要中；checks 在启动模型前以 argv 执行，失败或超时终止启动。requiredPlugins 要求会话设置及运行回执都出现所选插件；mcpServers 将场景内命名服务绑定到明确 URL。提示歧义规则由场景给出 pattern/message，运行器不识别特定生成器命令。旧 pageInputManifest 配置需将原 manifest 和真实验证命令迁入场景，不能静默丢弃原检查。
+
+`doctor --cost` 从项目 plugins、解析成功的 use 引用及显式实验要求生成能力集合。额外能力通过重复 `--capability <name>` 或证据文件 requiredCapabilities 数组声明；没有选择的插件不报缺失。用量、探针文件摘要与隔离证据不足仍保持 gap。
+
+国际化翻译、增量合入与校验使用宿主选择的插件入口，检查历史值、完整语言覆盖、占位符和失败日志。插件实现、实验结论和真实宿主服务地址不由框架文档重复维护。