@peterxiaoyang/superspec 0.1.4 → 0.1.6

package/dist/src/gates.js

@@ -1,13 +1,14 @@
 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";
 import { evidence_test_id_reasons, declared_test_evidence_reasons, parse_spec_scenarios, parse_tasks, parse_test_contract_ids, parse_test_contract_records, red_green_test_ids, splitList, tasks_structure_hash, task_alternative_verification, task_test_evidence, task_test_refs, test_contract_covers_scenario, test_contract_invariant_refs_by_test, write_scope_conflict_reasons, } from "./tasks.js";
-import { duplicate_evidence_id_reasons, dangling_evidence_ref_reasons, final_verification_evidences, live_task_reopens, live_task_reopen_resolutions, live_pass, live_user_confirmations, pass_task_reopens, supersede_reasons, unresolved_live_task_reopens, validate_evidence_schema, verify_reference_reasons, } from "./evidence.js";
+import { duplicate_evidence_id_reasons, dangling_evidence_ref_reasons, find_pass, final_verification_evidences, live_task_reopens, live_task_reopen_resolutions, live_pass, live_user_confirmations, pass_task_reopens, supersede_reasons, unresolved_live_task_reopens, validate_evidence_schema, verify_reference_reasons, } from "./evidence.js";
 import { review_disclosure_reasons } from "./disclosure.js";
 import { archive_manifest_path } from "./archive.js";
+import { apply_worker_implementation_fingerprint, apply_worker_executor_input_ref_digest, compute_apply_worker_freshness, fingerprint_matches, pinned_artifact_ref_reasons as shared_pinned_artifact_ref_reasons, pre_edit_evidence_ref_reasons, read_pinned_artifact_json, worker_input_ref_digest, worker_test_run_reasons, } from "./apply_worker_chain.js";
 function action_list(...items) {
     return [...new Set(items.filter((item) => typeof item === "string" && item.length > 0))];
 }
@@ -330,24 +331,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.
@@ -1160,6 +1145,260 @@ export function check_task_edit(change, status, changeRoot, evidences, taskId) {
     }
     return allow(change, gate, { task_id: taskId });
 }
+function pinned_artifact_ref_matches(changeRoot, refItem, role, taskId, chainId, kind = "worker_report") {
+    return shared_pinned_artifact_ref_reasons(changeRoot, refItem, `${role}_ref`, { kind, role, taskId, chainId }).length === 0;
+}
+function executor_worker_test_run_refs_valid(changeRoot, ev, taskId, chainId) {
+    return worker_test_run_reasons(changeRoot, ev, taskId, chainId).length === 0;
+}
+function report_origin_matches(refItem, expected) {
+    return isObject(refItem) && typeof expected === "string" && refItem.origin_packet_fingerprint === expected;
+}
+function report_input_refs_match(refItem, refs) {
+    return isObject(refItem) && refItem.input_ref_digest === worker_input_ref_digest(refs);
+}
+function report_input_digest_matches(refItem, expectedDigest) {
+    return isObject(refItem) && refItem.input_ref_digest === expectedDigest;
+}
+function chain_green_ids(ev) {
+    if (Array.isArray(ev.green_test_run_evidence_refs)) {
+        return ev.green_test_run_evidence_refs.map(String).filter(Boolean).sort();
+    }
+    const greenId = isObject(ev.green_test_run_evidence_ref)
+        ? String(ev.green_test_run_evidence_ref.evidence_id ?? "")
+        : String(ev.green_test_run_evidence_ref ?? "");
+    return greenId ? [greenId] : [];
+}
+function active_pre_edit_input_refs(evidences, active) {
+    const preIds = Array.isArray(active.pre_edit_evidence_refs) ? active.pre_edit_evidence_refs.map(String) : [];
+    return preIds.map((evidenceId) => {
+        const ev = live_pass(evidences, { kind: "test_run" }).find((item) => String(item.evidence_id ?? "") === evidenceId);
+        return ev
+            ? { kind: "test_run", evidence_id: evidenceId, phase: ev.phase, semantic_status: ev.semantic_status }
+            : { kind: "test_run", evidence_id: evidenceId };
+    });
+}
+function closed_apply_worker_chain_valid(repoRoot, changeRoot, ev, evidences, taskId, chainId) {
+    const active = live_pass(evidences, { gate: "task_complete", kind: "apply_worker_chain", task_id: taskId })
+        .find((item) => item.chain_state === "active" && item.apply_worker_chain_id === chainId);
+    if (!active)
+        return false;
+    if (pre_edit_evidence_ref_reasons(evidences, active, taskId).length > 0)
+        return false;
+    if (!pinned_artifact_ref_matches(changeRoot, ev.executor_report_ref, "executor", taskId, chainId))
+        return false;
+    if (!pinned_artifact_ref_matches(changeRoot, ev.task_code_review_report_ref, "code-reviewer", taskId, chainId))
+        return false;
+    if (!pinned_artifact_ref_matches(changeRoot, ev.verifier_report_ref, "verifier", taskId, chainId))
+        return false;
+    if (!report_origin_matches(ev.executor_report_ref, active.executor_packet_fingerprint))
+        return false;
+    if (!report_input_digest_matches(ev.executor_report_ref, apply_worker_executor_input_ref_digest(evidences, active)))
+        return false;
+    if (!report_input_refs_match(ev.task_code_review_report_ref, [ev.executor_report_ref]))
+        return false;
+    if (typeof ev.observed_freshness_fingerprint !== "string" && !(isObject(ev.observed_freshness_fingerprint) && typeof ev.observed_freshness_fingerprint.fingerprint_digest === "string"))
+        return false;
+    const verifierReport = read_pinned_artifact_json(changeRoot, ev.verifier_report_ref);
+    const verifierObserved = verifierReport?.observed_freshness_fingerprint ?? (isObject(ev.verifier_report_ref) ? ev.verifier_report_ref.observed_freshness_fingerprint : undefined);
+    if (!fingerprint_matches(verifierObserved, ev.observed_freshness_fingerprint))
+        return false;
+    const greenIds = chain_green_ids(ev);
+    if (greenIds.length === 0)
+        return false;
+    const greenRuns = greenIds.map((greenId) => live_pass(evidences, { gate: "task_complete", kind: "test_run", task_id: taskId }).find((item) => (String(item.evidence_id ?? "") === greenId
+        && item.semantic_status === "expected_success"
+        && (item.phase === undefined || item.phase === "green")
+        && item.apply_execution_chain === "executor_worker"
+        && item.apply_worker_chain_id === chainId
+        && executor_worker_test_run_refs_valid(changeRoot, item, taskId, chainId)))).filter((item) => isObject(item));
+    if (greenRuns.length !== greenIds.length)
+        return false;
+    if (!report_input_refs_match(ev.verifier_report_ref, [
+        ev.executor_report_ref,
+        ev.task_code_review_report_ref,
+        ...greenRuns.map((green) => ({ kind: "test_run", evidence_id: String(green.evidence_id ?? ""), phase: green.phase, semantic_status: green.semantic_status })),
+        ...active_pre_edit_input_refs(evidences, active),
+    ]))
+        return false;
+    const currentFreshness = compute_apply_worker_freshness(repoRoot, changeRoot, evidences, taskId, chainId, {
+        executor_report_ref: ev.executor_report_ref,
+        task_code_review_report_ref: ev.task_code_review_report_ref,
+        green_test_run_evidence_ref: greenIds[0],
+        green_test_run_evidence_refs: greenIds,
+        verifier_report_ref: ev.verifier_report_ref,
+    });
+    if (Array.isArray(currentFreshness.unexpected_guard_owned_dirty_paths) && currentFreshness.unexpected_guard_owned_dirty_paths.length > 0)
+        return false;
+    if (Array.isArray(currentFreshness.protected_dirty_paths) && currentFreshness.protected_dirty_paths.length > 0)
+        return false;
+    if (!greenRuns.every((green) => fingerprint_matches(green.implementation_fingerprint, currentFreshness.implementation_fingerprint)))
+        return false;
+    if (!fingerprint_matches(isObject(ev.task_code_review_report_ref) ? ev.task_code_review_report_ref.observed_implementation_fingerprint : undefined, currentFreshness.implementation_fingerprint))
+        return false;
+    return fingerprint_matches(currentFreshness, verifierObserved);
+}
+function pinned_takeover_baseline_valid(changeRoot, refItem, taskId, chainId) {
+    return shared_pinned_artifact_ref_reasons(changeRoot, refItem, "serial_takeover_baseline_ref", { kind: "status_report", role: "verifier", taskId, chainId }).length === 0;
+}
+function abandoned_apply_worker_chain_valid(repoRoot, changeRoot, ev, active, taskId, chainId) {
+    if (!active)
+        return false;
+    if ("restored_implementation_fingerprint" in ev) {
+        const activeScope = Array.isArray(active.declared_task_write_scope) ? active.declared_task_write_scope.map(String).filter(Boolean) : [];
+        const current = apply_worker_implementation_fingerprint(repoRoot, changeRoot, [], { declaredTaskWriteScope: activeScope });
+        if (fingerprint_matches(ev.restored_implementation_fingerprint, active.source_implementation_fingerprint)
+            && fingerprint_matches(current, active.source_implementation_fingerprint))
+            return true;
+    }
+    if ("serial_takeover_baseline_ref" in ev) {
+        return pinned_takeover_baseline_valid(changeRoot, ev.serial_takeover_baseline_ref, taskId, chainId)
+            && Array.isArray(ev.successor_green_evidence_refs)
+            && ev.successor_green_evidence_refs.length > 0
+            && ev.successor_green_evidence_refs.every((item) => typeof item === "string" && item.length > 0);
+    }
+    return false;
+}
+function serial_completion_green(ev) {
+    return (ev.runner_origin === undefined || ev.runner_origin === "main-thread")
+        && ev.apply_execution_chain !== "executor_worker"
+        && typeof ev.apply_worker_chain_id !== "string";
+}
+function apply_worker_chain_completion_state(repoRoot, changeRoot, evidences, taskId) {
+    const chains = find_pass(evidences, { gate: "task_complete", kind: "apply_worker_chain", task_id: taskId });
+    const activeByChain = new Map();
+    const activeCounts = new Map();
+    for (const ev of chains) {
+        if (String(ev.chain_state ?? "") !== "active")
+            continue;
+        const chainId = String(ev.apply_worker_chain_id ?? "");
+        if (!chainId)
+            continue;
+        const bucket = activeCounts.get(chainId) ?? [];
+        bucket.push(ev);
+        activeCounts.set(chainId, bucket);
+        if (!activeByChain.has(chainId))
+            activeByChain.set(chainId, ev);
+    }
+    const chainIdsWithActive = new Set([...activeByChain.keys()]);
+    const chainIdsWithTerminal = new Set(chains
+        .filter((ev) => {
+        const chainId = String(ev.apply_worker_chain_id ?? "");
+        if (!chainId)
+            return false;
+        if (String(ev.chain_state ?? "") === "closed")
+            return closed_apply_worker_chain_valid(repoRoot, changeRoot, ev, evidences, taskId, chainId);
+        if (String(ev.chain_state ?? "") === "abandoned")
+            return abandoned_apply_worker_chain_valid(repoRoot, changeRoot, ev, activeByChain.get(chainId), taskId, chainId);
+        return false;
+    })
+        .map((ev) => String(ev.apply_worker_chain_id ?? ""))
+        .filter(Boolean));
+    const chainIdsWithOpenActive = new Set([...activeByChain.keys()].filter((chainId) => !chainIdsWithTerminal.has(chainId)));
+    const validClosedChainIds = new Set(chains
+        .filter((ev) => {
+        const chainId = String(ev.apply_worker_chain_id ?? "");
+        return chainId
+            && String(ev.chain_state ?? "") === "closed"
+            && closed_apply_worker_chain_valid(repoRoot, changeRoot, ev, evidences, taskId, chainId);
+    })
+        .map((ev) => String(ev.apply_worker_chain_id ?? ""))
+        .filter(Boolean));
+    const validClosedGreenEvidenceIds = new Set(chains
+        .filter((ev) => {
+        const chainId = String(ev.apply_worker_chain_id ?? "");
+        return chainId
+            && String(ev.chain_state ?? "") === "closed"
+            && closed_apply_worker_chain_valid(repoRoot, changeRoot, ev, evidences, taskId, chainId);
+    })
+        .flatMap(chain_green_ids));
+    const takeoverBaselines = [];
+    const reasons = [];
+    const duplicateActives = [...activeCounts.entries()]
+        .filter(([chainId]) => chainIdsWithOpenActive.has(chainId))
+        .map(([, items]) => items)
+        .filter((items) => items.length > 1)
+        .flatMap((items) => items.map((ev) => String(ev.evidence_id ?? ev.apply_worker_chain_id ?? "")))
+        .filter(Boolean)
+        .sort();
+    const openActiveValues = [...chainIdsWithOpenActive].map((chainId) => activeByChain.get(chainId)).filter((ev) => isObject(ev));
+    const parallelActives = openActiveValues.length > 1
+        ? openActiveValues.map((ev) => String(ev.evidence_id ?? ev.apply_worker_chain_id ?? "")).filter(Boolean).sort()
+        : [];
+    const activeConflicts = [...new Set([...duplicateActives, ...parallelActives])].sort();
+    if (activeConflicts.length > 0) {
+        reasons.push(reason("apply_worker_chain_active_conflict", `task ${taskId} has conflicting active apply worker chain markers: ${renderList(activeConflicts)}`, activeConflicts));
+    }
+    const terminalsByChain = new Map();
+    for (const ev of chains) {
+        const state = String(ev.chain_state ?? "");
+        if (state !== "closed" && state !== "abandoned")
+            continue;
+        const chainId = String(ev.apply_worker_chain_id ?? "");
+        if (!chainId)
+            continue;
+        const bucket = terminalsByChain.get(chainId) ?? [];
+        bucket.push(ev);
+        terminalsByChain.set(chainId, bucket);
+    }
+    const duplicateTerminals = [...terminalsByChain.values()]
+        .filter((items) => items.length > 1)
+        .flatMap((items) => items.map((ev) => String(ev.evidence_id ?? ev.apply_worker_chain_id ?? "")))
+        .filter(Boolean)
+        .sort();
+    if (duplicateTerminals.length > 0) {
+        reasons.push(reason("apply_worker_chain_terminal_conflict", `task ${taskId} has duplicate apply worker chain terminal markers: ${renderList(duplicateTerminals)}`, duplicateTerminals));
+    }
+    const invalidTerminals = chains
+        .filter((ev) => String(ev.chain_state ?? "") === "closed" || String(ev.chain_state ?? "") === "abandoned")
+        .filter((ev) => {
+        const chainId = String(ev.apply_worker_chain_id ?? "");
+        if (!chainId)
+            return true;
+        if (String(ev.chain_state ?? "") === "closed")
+            return !closed_apply_worker_chain_valid(repoRoot, changeRoot, ev, evidences, taskId, chainId);
+        const valid = abandoned_apply_worker_chain_valid(repoRoot, changeRoot, ev, activeByChain.get(chainId), taskId, chainId);
+        if (valid && isObject(ev.serial_takeover_baseline_ref)) {
+            const baseline = read_pinned_artifact_json(changeRoot, ev.serial_takeover_baseline_ref);
+            if (baseline?.implementation_fingerprint !== undefined) {
+                takeoverBaselines.push({
+                    fingerprint: baseline.implementation_fingerprint,
+                    successorGreenRefs: Array.isArray(ev.successor_green_evidence_refs) ? ev.successor_green_evidence_refs.map(String).filter(Boolean) : [],
+                });
+            }
+        }
+        return !valid;
+    })
+        .map((ev) => String(ev.evidence_id ?? ev.apply_worker_chain_id ?? ""))
+        .filter(Boolean)
+        .sort();
+    if (invalidTerminals.length > 0) {
+        reasons.push(reason("apply_worker_chain_terminal_invalid", `task ${taskId} has invalid apply worker chain terminal markers: ${renderList(invalidTerminals)}`, invalidTerminals));
+    }
+    for (const chainId of [...chainIdsWithOpenActive].sort()) {
+        if (!chainIdsWithTerminal.has(chainId)) {
+            reasons.push(reason("apply_worker_chain_active", `task ${taskId} has active apply worker chain and cannot use non-chain task completion: ${chainId}`, [chainId]));
+        }
+    }
+    for (const ev of evidences) {
+        if (!isObject(ev) || ev._invalid || ev.status !== "pass" || ev.task_id !== taskId)
+            continue;
+        const chainId = typeof ev.apply_worker_chain_id === "string" ? ev.apply_worker_chain_id : "";
+        if (!chainId)
+            continue;
+        if (!chainIdsWithActive.has(chainId)) {
+            reasons.push(reason("apply_worker_chain_missing_active", `task ${taskId} references apply_worker_chain_id=${repr(chainId)} without a matching active marker`, [chainId]));
+        }
+    }
+    if (duplicateTerminals.length > 0 || activeConflicts.length > 0) {
+        validClosedChainIds.clear();
+        validClosedGreenEvidenceIds.clear();
+    }
+    return { reasons, validClosedChainIds, validClosedGreenEvidenceIds, takeoverBaselines };
+}
+export function apply_worker_chain_lifecycle_reasons(repoRoot, changeRoot, evidences, taskId) {
+    return apply_worker_chain_completion_state(repoRoot, changeRoot, evidences, taskId).reasons;
+}
 export function check_task_complete(change, status, changeRoot, evidences, taskId) {
     const gate = "task_complete";
     const reasons = [];
@@ -1174,6 +1413,8 @@ export function check_task_complete(change, status, changeRoot, evidences, taskI
     const task = parse_tasks(changeRoot)[taskId];
     if (!task)
         return block(change, gate, [reason("unknown_task", `task ${taskId} not found`)], { task_id: taskId });
+    const workerChainState = apply_worker_chain_completion_state(get_repo_root(status), changeRoot, evidences, taskId);
+    reasons.push(...workerChainState.reasons);
     const reopenHistory = task_reopen_history(evidences, taskId);
     if (task.checked && reopenHistory.pass.length > 1) {
         reasons.push(reason("reopen_lifecycle_exhausted", `task ${taskId} has multiple task_reopen histories in this change; v1 allows at most one`, [taskId]));
@@ -1193,9 +1434,22 @@ export function check_task_complete(change, status, changeRoot, evidences, taskI
     if (!TDD_MODES.has(tddMode))
         reasons.push(reason("invalid_tdd_mode", `task ${taskId}: tdd_mode=${repr(tddMode)}`));
     if (tddRequired) {
-        const green = task_test_evidence(evidences, taskId, "expected_success", "task_complete");
+        const allGreen = task_test_evidence(evidences, taskId, "expected_success", "task_complete");
+        const green = workerChainState.validClosedGreenEvidenceIds.size > 0
+            ? allGreen.filter((ev) => (ev.apply_execution_chain === "executor_worker"
+                && workerChainState.validClosedChainIds.has(String(ev.apply_worker_chain_id ?? ""))
+                && workerChainState.validClosedGreenEvidenceIds.has(String(ev.evidence_id ?? ""))))
+            : workerChainState.takeoverBaselines.length > 0
+                ? allGreen.filter((ev) => serial_completion_green(ev) && workerChainState.takeoverBaselines.some((baseline) => (baseline.successorGreenRefs.includes(String(ev.evidence_id ?? ""))
+                    && fingerprint_matches(ev.implementation_fingerprint, baseline.fingerprint))))
+                : allGreen.filter(serial_completion_green);
         if (green.length === 0)
             reasons.push(reason("missing_green_evidence", `task ${taskId} requires GREEN evidence (expected_success) before completion`));
+        if (workerChainState.validClosedGreenEvidenceIds.size === 0 && workerChainState.takeoverBaselines.length > 0) {
+            if (green.length === 0) {
+                reasons.push(reason("apply_worker_chain_takeover_green_mismatch", `task ${taskId} requires declared successor serial GREEN evidence after takeover baseline with matching implementation fingerprint`));
+            }
+        }
         const declared = new Set(splitList(attrs.test_refs ?? ""));
         const declaredInvariants = new Set(splitList(attrs.invariant_refs ?? ""));
         if (declared.size === 0)

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/install_engine.d.ts

@@ -16,6 +16,11 @@ export type ManifestFileEntry = {
     managed: boolean;
     preexisting: boolean;
 };
+export type ManifestConfigPatchEntry = {
+    path: string;
+    retainedOnUninstall: boolean;
+    managed: boolean;
+};
 export type EngineAction = {
     action: string;
     status: "ok" | "created" | "updated" | "skipped" | "removed" | "would_remove" | "failed";
@@ -27,6 +32,8 @@ export type EngineResult = {
     problems: string[];
     manifest: JsonMap | null;
 };
+export declare const CODEX_NATIVE_AGENT_MAX_THREADS = 12;
+export declare const CODEX_NATIVE_AGENT_MAX_DEPTH = 1;
 export declare function load_install_map(packageRoot?: string): {
     mappings: InstallMapping[];
     problems: string[];
@@ -39,6 +46,16 @@ export declare function read_install_manifest(repoRoot: string, opts?: {
     problems: string[];
 };
 export declare function install_manifest_rel(scope?: InstallScope): string;
+export declare function codex_config_rel(scope?: InstallScope): string;
+export declare function merge_codex_config(text: string, opts?: {
+    force?: boolean;
+}): string;
+export declare function ensure_codex_config(repoRoot: string, scope?: InstallScope, opts?: {
+    force?: boolean;
+}): {
+    action: EngineAction;
+    problems: string[];
+};
 export declare function install_workflow(repoRoot: string, opts?: {
     force?: boolean;
     packageRoot?: string;

package/dist/src/install_engine.js

@@ -21,6 +21,14 @@ export const PACKAGE_ROOT = find_package_root(import.meta.url);
 export const PROJECT_INSTALL_MANIFEST_REL = join(".codex", "superspec", "install-manifest.json");
 export const USER_INSTALL_MANIFEST_REL = join("superspec", "install-manifest.json");
 export const INSTALL_MANIFEST_REL = PROJECT_INSTALL_MANIFEST_REL;
+export const CODEX_NATIVE_AGENT_MAX_THREADS = 12;
+export const CODEX_NATIVE_AGENT_MAX_DEPTH = 1;
+const CODEX_CONFIG_ENTRIES = [
+    { table: "features", key: "multi_agent", value: "true" },
+    { table: "features", key: "child_agents_md", value: "true" },
+    { table: "agents", key: "max_threads", value: String(CODEX_NATIVE_AGENT_MAX_THREADS) },
+    { table: "agents", key: "max_depth", value: String(CODEX_NATIVE_AGENT_MAX_DEPTH) },
+];
 function package_version(packageRoot) {
     try {
         const pkg = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
@@ -78,6 +86,15 @@ export function manifest_shape_problems(manifest) {
         problems.push("createdDirs malformed");
     if (!Array.isArray(manifest.dataGlobs) || manifest.dataGlobs.some((item) => typeof item !== "string" || !item))
         problems.push("dataGlobs malformed");
+    if (manifest.configPatch !== undefined) {
+        if (!isObject(manifest.configPatch)
+            || typeof manifest.configPatch.path !== "string"
+            || !manifest.configPatch.path
+            || manifest.configPatch.retainedOnUninstall !== true
+            || manifest.configPatch.managed !== false) {
+            problems.push("configPatch malformed");
+        }
+    }
     if (!Array.isArray(manifest.files)) {
         problems.push("files missing");
     }
@@ -128,6 +145,101 @@ function scoped_mappings(mappings, scope) {
         return scoped === null ? [] : [scoped];
     });
 }
+export function codex_config_rel(scope = "project") {
+    return scope === "user" ? "config.toml" : join(".codex", "config.toml");
+}
+function table_header_name(line) {
+    const match = /^\s*\[([A-Za-z0-9_.-]+)\]\s*(?:#.*)?$/u.exec(line);
+    return match?.[1] ?? null;
+}
+function is_any_table_header(line) {
+    return /^\s*\[[^\]]+\]\s*(?:#.*)?$/u.test(line);
+}
+function escape_regexp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function split_toml_lines(text) {
+    if (!text)
+        return [];
+    const lines = text.replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n");
+    if (lines[lines.length - 1] === "")
+        lines.pop();
+    return lines;
+}
+function ensure_toml_key(lines, table, key, value, overwriteExisting) {
+    let start = -1;
+    let end = lines.length;
+    for (let idx = 0; idx < lines.length; idx += 1) {
+        if (table_header_name(lines[idx]) !== table)
+            continue;
+        start = idx;
+        end = lines.length;
+        for (let next = idx + 1; next < lines.length; next += 1) {
+            if (!is_any_table_header(lines[next]))
+                continue;
+            end = next;
+            break;
+        }
+        break;
+    }
+    if (start === -1) {
+        if (lines.length > 0 && lines[lines.length - 1].trim() !== "")
+            lines.push("");
+        lines.push(`[${table}]`, `${key} = ${value}`);
+        return true;
+    }
+    const keyRe = new RegExp(`^\\s*${escape_regexp(key)}\\s*=`, "u");
+    const desired = `${key} = ${value}`;
+    for (let idx = start + 1; idx < end; idx += 1) {
+        if (!keyRe.test(lines[idx]))
+            continue;
+        if (lines[idx] === desired)
+            return false;
+        if (!overwriteExisting)
+            return false;
+        lines[idx] = desired;
+        return true;
+    }
+    let insertAt = end;
+    while (insertAt > start + 1 && lines[insertAt - 1].trim() === "")
+        insertAt -= 1;
+    lines.splice(insertAt, 0, desired);
+    return true;
+}
+export function merge_codex_config(text, opts = {}) {
+    const lines = split_toml_lines(text);
+    for (const entry of CODEX_CONFIG_ENTRIES) {
+        ensure_toml_key(lines, entry.table, entry.key, entry.value, opts.force === true);
+    }
+    return `${lines.join("\n")}\n`;
+}
+export function ensure_codex_config(repoRoot, scope = "project", opts = {}) {
+    const rel = codex_config_rel(scope);
+    const configPath = join(repoRoot, rel);
+    const existed = existsSync(configPath);
+    try {
+        const before = existed ? readFileSync(configPath, "utf8") : "";
+        const after = merge_codex_config(before, opts);
+        if (after === before)
+            return { action: { action: `configure ${rel}`, status: "ok" }, problems: [] };
+        mkdirSync(dirname(configPath), { recursive: true });
+        writeFileSync(configPath, after, "utf8");
+        return {
+            action: {
+                action: `configure ${rel}`,
+                status: existed ? "updated" : "created",
+                detail: `Codex native subagent concurrency set to ${CODEX_NATIVE_AGENT_MAX_THREADS}`,
+            },
+            problems: [],
+        };
+    }
+    catch (err) {
+        return {
+            action: { action: `configure ${rel}`, status: "failed" },
+            problems: [`Codex config update failed: ${err.message}`],
+        };
+    }
+}
 function write_install_manifest(repoRoot, packageRoot, files, createdDirs, scope) {
     const manifest = {
         superspecVersion: package_version(packageRoot),
@@ -138,6 +250,11 @@ function write_install_manifest(repoRoot, packageRoot, files, createdDirs, scope
         files,
         createdDirs: [...new Set(createdDirs)].sort(),
         dataGlobs: ["**/.superspec"],
+        configPatch: {
+            path: codex_config_rel(scope),
+            retainedOnUninstall: true,
+            managed: false,
+        },
     };
     const manifestPath = join(repoRoot, install_manifest_rel(scope));
     mkdirSync(dirname(manifestPath), { recursive: true });
@@ -212,8 +329,11 @@ export function install_workflow(repoRoot, opts = {}) {
             actions.push({ action: `install ${mapping.target}`, status: "skipped", detail: "pre-existing file with different content kept; rerun with --force to overwrite (backs up *.bak)" });
         }
     }
+    const configResult = ensure_codex_config(repoRoot, scope, { force: opts.force === true });
+    actions.push(configResult.action);
+    problems.push(...configResult.problems);
     const manifest = write_install_manifest(repoRoot, packageRoot, files, createdDirs, scope);
-    return { actions, problems: [], manifest };
+    return { actions, problems, manifest };
 }
 export function update_workflow(repoRoot, opts = {}) {
     const packageRoot = opts.packageRoot ?? PACKAGE_ROOT;
@@ -287,8 +407,11 @@ export function update_workflow(repoRoot, opts = {}) {
             actions.push({ action: `update ${prev.path}`, status: "skipped", detail: "no longer shipped but user-modified; kept" });
         }
     }
+    const configResult = ensure_codex_config(repoRoot, scope);
+    actions.push(configResult.action);
+    problems.push(...configResult.problems);
     const manifest = write_install_manifest(repoRoot, packageRoot, files, createdDirs, scope);
-    return { actions, problems: [], manifest };
+    return { actions, problems, manifest };
 }
 function remove_empty_created_dirs(repoRoot, createdDirs, actions) {
     const byDepth = [...new Set(createdDirs)].sort((a, b) => b.split("/").length - a.split("/").length);

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 {};