@peterxiaoyang/superspec 0.1.10 → 0.1.12

package/dist/src/install_engine.js

@@ -29,6 +29,13 @@ const CODEX_CONFIG_ENTRIES = [
     { table: "agents", key: "max_threads", value: String(CODEX_NATIVE_AGENT_MAX_THREADS) },
     { table: "agents", key: "max_depth", value: String(CODEX_NATIVE_AGENT_MAX_DEPTH) },
 ];
+const HOOK_COMMAND = 'superspec-hook --change "$SUPERSPEC_CHANGE"';
+const LEGACY_FOUR_HOOK_MATRIX = [
+    { eventName: "PreToolUse", matcher: "Bash|apply_patch|Edit|Write|mcp__.*", statusMessage: "SuperSpec 写入策略检查" },
+    { eventName: "PostToolUse", matcher: "Bash", statusMessage: "SuperSpec 运行证据记录" },
+    { eventName: "SubagentStart", matcher: ".*", statusMessage: "SuperSpec 子智能体启动记录" },
+    { eventName: "SubagentStop", matcher: ".*", statusMessage: "SuperSpec 子智能体停止记录" },
+];
 function package_version(packageRoot) {
     try {
         const pkg = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
@@ -38,6 +45,51 @@ function package_version(packageRoot) {
         return "0.0.0";
     }
 }
+function has_exact_keys(value, keys) {
+    const actual = Object.keys(value).sort();
+    const expected = [...keys].sort();
+    return actual.length === expected.length && actual.every((key, idx) => key === expected[idx]);
+}
+function legacy_hook_entry_matches(entry, expected) {
+    if (!isObject(entry) || !has_exact_keys(entry, ["matcher", "hooks"]))
+        return false;
+    if (entry.matcher !== expected.matcher || !Array.isArray(entry.hooks) || entry.hooks.length !== 1)
+        return false;
+    const hook = entry.hooks[0];
+    return isObject(hook)
+        && has_exact_keys(hook, ["type", "command", "timeout", "statusMessage"])
+        && hook.type === "command"
+        && hook.command === HOOK_COMMAND
+        && hook.timeout === 120
+        && hook.statusMessage === expected.statusMessage;
+}
+function is_legacy_managed_four_hook_manifest(parsed) {
+    if (!isObject(parsed) || !has_exact_keys(parsed, ["superspec", "hooks"]))
+        return false;
+    if (!isObject(parsed.superspec) || !has_exact_keys(parsed.superspec, ["managed", "adapter_version", "strict_profile_default"]))
+        return false;
+    if (parsed.superspec.managed !== true
+        || parsed.superspec.adapter_version !== "superspec-hook@2"
+        || parsed.superspec.strict_profile_default !== "audit-only-until-r1-provenance-passes") {
+        return false;
+    }
+    if (!isObject(parsed.hooks) || !has_exact_keys(parsed.hooks, LEGACY_FOUR_HOOK_MATRIX.map((entry) => entry.eventName)))
+        return false;
+    return LEGACY_FOUR_HOOK_MATRIX.every((expected) => {
+        const entries = parsed.hooks[expected.eventName];
+        return Array.isArray(entries)
+            && entries.length === 1
+            && legacy_hook_entry_matches(entries[0], expected);
+    });
+}
+function target_is_legacy_managed_four_hook_manifest(targetAbs) {
+    try {
+        return is_legacy_managed_four_hook_manifest(JSON.parse(readFileSync(targetAbs, "utf8")));
+    }
+    catch {
+        return false;
+    }
+}
 export function load_install_map(packageRoot = PACKAGE_ROOT) {
     const mapPath = join(packageRoot, INSTALL_MAP_REL);
     if (!existsSync(mapPath))
@@ -315,6 +367,13 @@ export function install_workflow(repoRoot, opts = {}) {
             files.push({ path: mapping.target, sha256: sourceSha, managed: true, preexisting: false });
             actions.push({ action: `install ${mapping.target}`, status: "ok" });
         }
+        else if (mapping.kind === "hook" && target_is_legacy_managed_four_hook_manifest(targetAbs)) {
+            // Previous SuperSpec default hooks installed PreToolUse/PostToolUse. Re-init must migrate
+            // that unmodified managed baseline so old blocking hooks do not stay in the workflow.
+            copyFileSync(sourceAbs, targetAbs);
+            files.push({ path: mapping.target, sha256: sourceSha, managed: true, preexisting: false });
+            actions.push({ action: `install ${mapping.target}`, status: "updated", detail: "legacy managed four-hook manifest migrated to subagent-only manifest" });
+        }
         else if (opts.force) {
             copyFileSync(targetAbs, `${targetAbs}.bak`);
             copyFileSync(sourceAbs, targetAbs);
@@ -323,6 +382,11 @@ export function install_workflow(repoRoot, opts = {}) {
             files.push({ path: mapping.target, sha256: sourceSha, managed: true, preexisting: false });
             actions.push({ action: `install ${mapping.target}`, status: "updated", detail: `existing file backed up to ${mapping.target}.bak` });
         }
+        else if (mapping.kind === "hook") {
+            copyFileSync(sourceAbs, `${targetAbs}.new`);
+            files.push({ path: mapping.target, sha256: targetSha, managed: false, preexisting: true });
+            actions.push({ action: `install ${mapping.target}`, status: "skipped", detail: `pre-existing hooks manifest kept; current SuperSpec manifest written to ${mapping.target}.new` });
+        }
         else {
             // Pre-existing different file: never overwrite, never delete (DISTRIBUTION §5 red line).
             files.push({ path: mapping.target, sha256: targetSha, managed: false, preexisting: true });

package/dist/src/openspec.d.ts

@@ -27,6 +27,8 @@ export declare function all_done(status: JsonMap): boolean;
 export declare function openspec_floor_route(status: JsonMap): string;
 export declare function normalize_route_phase(route: string): string;
 export declare function normalize_gate(gate: string): string;
+export declare function authorized_supersede_target_ids(evidences: JsonMap[]): Set<string>;
+export declare function effective_superseded_ids(evidences: JsonMap[]): Set<string>;
 export declare function gate_route_phase(gate: string): string;
 export declare function effective_route_phase(status: JsonMap, requestedRoute: string, decision: JsonMap): string;
 export declare function status_fingerprint(status: JsonMap): string;

package/dist/src/openspec.js

@@ -188,6 +188,37 @@ export function normalize_route_phase(route) {
 export function normalize_gate(gate) {
     return GATE_ALIASES[gate] ?? gate;
 }
+export function authorized_supersede_target_ids(evidences) {
+    const byId = new Map();
+    for (const ev of evidences) {
+        if (!isObject(ev) || ev._invalid)
+            continue;
+        const id = typeof ev.evidence_id === "string" ? ev.evidence_id : "";
+        if (id && !byId.has(id))
+            byId.set(id, ev);
+    }
+    const out = new Set();
+    for (const ev of evidences) {
+        if (!isObject(ev) || ev._invalid || ev.status !== "superseded")
+            continue;
+        const targetId = typeof ev.supersedes === "string" ? ev.supersedes : "";
+        if (!targetId)
+            continue;
+        const target = byId.get(targetId);
+        if (!target)
+            continue;
+        if (target.status !== "pass")
+            continue;
+        const sameGate = normalize_gate(String(ev.gate ?? "")) === normalize_gate(String(target.gate ?? ""));
+        const supersedeReason = typeof ev.supersede_reason === "string" ? ev.supersede_reason.trim() : "";
+        if (sameGate || supersedeReason)
+            out.add(targetId);
+    }
+    return out;
+}
+export function effective_superseded_ids(evidences) {
+    return authorized_supersede_target_ids(evidences);
+}
 export function gate_route_phase(gate) {
     return GATE_ROUTE[normalize_gate(gate)] ?? "propose";
 }

package/dist/src/packet_render.d.ts

@@ -1,4 +1,5 @@
 import { type ParsedArgs } from "./cli_args.ts";
 import type { PacketDispatchResult } from "./packet_schema.ts";
+export declare function read_discovery_template(packageRoot?: string): string | null;
 export declare function dispatch_packet(args: ParsedArgs): PacketDispatchResult;
 export declare function is_packet_command(command: string): boolean;

package/dist/src/packet_render.js

@@ -2,17 +2,43 @@ import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { load_config, sidecar_business_invariants_path, sidecar_discovery_path, sidecar_test_contract_path } from "./paths.js";
 import {} from "./cli_args.js";
-import { CLAIM_ADJUDICATION_DECISIONS, FINDING_ADJUDICATION_DECISIONS, fingerprint_obj, GuardError, MAIN_ADJUDICATION_REQUIRED_FIELDS, MAIN_ADJUDICATION_DECISIONS, REQUEST_CHANGES_ROUTES, REVIEW_EVIDENCE_REQUIRED_FIELDS, ROLE_EVIDENCE_FIELDS, SOURCE_GUIDANCE_REQUIRED_FIELDS, VERIFY_EVIDENCE_REQUIRED_FIELDS, allow, block, deepEqual, isObject, reason, renderList, runtime, safe_within, sha256_text, } from "./util.js";
+import { CLAIM_ADJUDICATION_DECISIONS, FINDING_ADJUDICATION_DECISIONS, fingerprint_obj, GuardError, MAIN_ADJUDICATION_REQUIRED_FIELDS, MAIN_ADJUDICATION_DECISIONS, NO_TDD_REASONS, REQUEST_CHANGES_ROUTES, REVIEW_EVIDENCE_REQUIRED_FIELDS, ROLE_EVIDENCE_FIELDS, SOURCE_GUIDANCE_REQUIRED_FIELDS, VERIFY_EVIDENCE_REQUIRED_FIELDS, allow, block, deepEqual, isObject, reason, renderList, runtime, safe_within, sha256_text, } from "./util.js";
 import { artifact_status_map, gate_route_phase, get_change_root, get_repo_root, normalize_gate, openspec_status, openspec_status_shape_reasons, } from "./openspec.js";
-import { build_finding_ledger, enumerate_review_targets, render_finding_ledger, REVIEW_TARGETS_BY_GATE, review_round_number, } from "./disclosure.js";
+import { build_finding_ledger, enumerate_review_targets, FINDING_CATEGORIES, FINDING_TYPES, MATERIAL_CATEGORIES, render_finding_ledger, REVIEW_TARGETS_BY_GATE, review_round_number, } from "./disclosure.js";
 import { evidence_schema_guard, check_apply_ready, check_archive_ready, check_review_complete, check_superspec_gate, check_task_complete, check_task_edit, check_task_reopen, } from "./gates.js";
 import { final_verification_evidences, index_evidence, live_pass, live_user_confirmations } from "./evidence.js";
 import { file_blob_sha, dirty_worktree_paths } from "./git.js";
 import { preset_upgrade_reasons, preset_upgrade_required_from_context } from "./archive.js";
 import { state_corrupt_reasons, state_stale_reasons } from "./state.js";
-import { parse_tasks, resolve_test_contract_command, splitList, test_contract_invariant_refs_by_test } from "./tasks.js";
-import { APPLY_CODE_REVIEW_REPORT_REQUIRED_FIELDS, APPLY_EXECUTOR_REPORT_REQUIRED_FIELDS, APPLY_TEST_RUNNER_REPORT_REQUIRED_FIELDS, APPLY_VERIFIER_REPORT_REQUIRED_FIELDS, apply_worker_implementation_fingerprint, apply_worker_executor_input_ref_digest, apply_worker_protected_path_refs, compute_apply_worker_freshness, fingerprint_digest, 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";
+import { parse_tasks, resolve_test_contract_command, splitList, task_apply_execution_surface, task_apply_execution_surface_reasons, test_contract_invariant_refs_by_test, } from "./tasks.js";
+import { APPLY_CODE_REVIEW_REPORT_REQUIRED_FIELDS, APPLY_EXECUTOR_REPORT_REQUIRED_FIELDS, APPLY_TEST_RUNNER_REPORT_REQUIRED_FIELDS, APPLY_VERIFIER_REPORT_REQUIRED_FIELDS, apply_worker_implementation_fingerprint, apply_worker_executor_input_ref_digest, apply_worker_protected_path_refs, compute_apply_worker_freshness, fingerprint_digest, fingerprint_matches, pinned_artifact_ref_reasons as shared_pinned_artifact_ref_reasons, pre_edit_evidence_ref_reasons, pre_edit_worker_test_run_reasons, read_pinned_artifact_json, worker_input_ref_digest, worker_test_run_reasons, } from "./apply_worker_chain.js";
 import { apply_worker_chain_lifecycle_state } from "./apply_worker_chain_lifecycle.js";
+import { PACKAGE_ROOT } from "./install_engine.js";
+// B (template serving): discovery.md fill rules handed to the model alongside the template skeleton
+// so every model produces the same structure (instead of freehanding a section the gate then has to
+// parse heuristically). Kept here, not in the .md template, so they are versioned with the code that
+// depends on them (the open-questions checkbox convention consumed by discovery_open_question_count).
+const DISCOVERY_RULES = [
+    "按模板骨架填写 discovery.md，保留全部段落（调查范围 / 现有实现事实 / 隐性合约 / 风险与歧义 / 待确认问题 / Subagent Evidence），不得自创或删减段落骨架。",
+    "所有需要用户拍板的问题写进「## 待确认问题」段，每条用「- [ ]」；用户确认后改成「- [x]」或在项内写「已确认：」。",
+    "explore_complete 检查在该段仍有「- [ ]」或「仍需确认/待确认」项时不会通过。",
+    "段标题含「确认」字样即可被识别（待确认问题 / 需要用户确认的问题 等），不要改成无「确认」字样的标题。",
+];
+// Reads the canonical discovery template from the package. packageRoot is parameterized so tests can
+// inject an empty dir to exercise the "unreadable → omit field" path; PACKAGE_ROOT itself is a
+// module-load-time const and cannot be mocked. Returns null (not throws) when missing so a transient
+// read failure never turns the whole packet into an error response.
+export function read_discovery_template(packageRoot = PACKAGE_ROOT) {
+    const p = join(packageRoot, "templates", "sidecar", "discovery.md");
+    if (!existsSync(p) || !statSync(p).isFile())
+        return null;
+    try {
+        return readFileSync(p, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
 function load_packet_context(change) {
     if (typeof runtime.load_context === "function") {
         const [status, repoRoot, changeRoot, evidences] = runtime.load_context(change);
@@ -168,18 +194,18 @@ function evaluate_workflow_decision(ctx, gateRaw, taskId) {
 function gate_recheck_command(change, gate, taskId, diagnostic = false) {
     const format = diagnostic ? "json" : "agent";
     if (gate === "apply_ready")
-        return `superspec guard check-apply-ready --change "${change}" --format ${format}`;
+        return `superspec check check-apply-ready --change "${change}" --format ${format}`;
     if (gate === "review_complete")
-        return `superspec guard check-review-complete --change "${change}" --format ${format}`;
+        return `superspec check check-review-complete --change "${change}" --format ${format}`;
     if (gate === "archive_ready")
-        return `superspec guard check-archive-ready --change "${change}" --format ${format}`;
+        return `superspec check check-archive-ready --change "${change}" --format ${format}`;
     if (gate === "task_edit")
-        return `superspec guard check-task-edit --change "${change}" --task-id "${taskId ?? ""}" --format ${format}`;
+        return `superspec check check-task-edit --change "${change}" --task-id "${taskId ?? ""}" --format ${format}`;
     if (gate === "task_complete")
-        return `superspec guard check-task-complete --change "${change}" --task-id "${taskId ?? ""}" --format ${format}`;
+        return `superspec check check-task-complete --change "${change}" --task-id "${taskId ?? ""}" --format ${format}`;
     if (gate === "task_reopen")
-        return `superspec guard check-task-reopen --change "${change}" --task-id "${taskId ?? ""}" --format ${format}`;
-    return `superspec guard check-enter --change "${change}" --gate "${gate}" --format ${format}`;
+        return `superspec check check-task-reopen --change "${change}" --task-id "${taskId ?? ""}" --format ${format}`;
+    return `superspec check check-enter --change "${change}" --gate "${gate}" --format ${format}`;
 }
 function default_allowed_next_action(gate) {
     if (gate === "review_complete")
@@ -390,6 +416,14 @@ function workflow_packet(ctx, gateRaw, taskId) {
     const decisions = decision_selectors_for_gate(ctx, gate);
     if (decisions.length > 0)
         packet.must_read_verbatim_decisions = decisions;
+    // B (template serving): hand the model the discovery skeleton + fill rules so its output structure
+    // is uniform. Gate-scoped to explore_complete (the only gate that produces discovery.md).
+    if (gate === "explore_complete") {
+        const tpl = read_discovery_template();
+        if (tpl)
+            packet.discovery_template = tpl;
+        packet.discovery_rules = [...DISCOVERY_RULES];
+    }
     return packet;
 }
 function live_output_refs(changeRoot, evidences) {
@@ -428,7 +462,19 @@ function verification_output_fields() {
     return [...ROLE_EVIDENCE_FIELDS, ...VERIFY_EVIDENCE_REQUIRED_FIELDS, "scope_drift"];
 }
 function review_output_fields() {
-    return [...ROLE_EVIDENCE_FIELDS, "review_round_id", "findings", "acknowledged_accepted_deviation_uids"];
+    return [
+        ...ROLE_EVIDENCE_FIELDS,
+        "review_round_id format: <gate>-r<round>",
+        "findings[] object fields: finding_id, finding_uid, finding_type, category, summary",
+        "finding_uid format: <gate>:<evidence_id>:<finding_id>",
+        `finding_type values: ${renderList([...FINDING_TYPES].sort())}`,
+        `category values: ${renderList([...FINDING_CATEGORIES].sort())}`,
+        `material_categories values: ${renderList([...MATERIAL_CATEGORIES].sort())}`,
+        "decision_scope_key required when material_categories is non-empty",
+        "summary must be verbatim disclosure source text",
+        "acknowledged_accepted_deviation_uids must be a string array when present",
+        "findings[].supersedes_finding_uids must be a string array when present",
+    ];
 }
 function source_guidance_output_fields() {
     return [
@@ -617,6 +663,7 @@ function apply_worker_stop_conditions(kind) {
     if (kind === "apply_test") {
         return [
             "Stop after reporting the bounded test command result only.",
+            "Do not let the main thread run or forge formal RED/characterization/GREEN evidence.",
             "Do not change implementation files.",
             "Return raw logs as pinned artifact refs when output is long.",
         ];
@@ -705,7 +752,7 @@ function require_active_apply_worker_chain(ctx, taskId, blockers) {
         blockers.push(reason("missing_apply_worker_chain_active", `task ${taskId} requires an active apply_worker_chain marker before downstream worker packet generation`));
     }
     else {
-        blockers.push(...pre_edit_evidence_ref_reasons(ctx.evidences, active, taskId, "apply_worker_chain_active_invalid"));
+        blockers.push(...pre_edit_evidence_ref_reasons(ctx.changeRoot, ctx.evidences, active, taskId, "apply_worker_chain_active_invalid"));
     }
     return chainId;
 }
@@ -871,7 +918,7 @@ function validate_test_run_evidence_refs(ctx, refs, expected) {
     }
     return { refs: resolved, blockers };
 }
-function validate_active_apply_worker_chain_refs(ctx, refs, taskId, expectedChainId, expectedPacketFingerprint, expectedSourceImplementationFingerprint, expectedDeclaredTaskWriteScope, expectedPreEditEvidenceRefs) {
+function validate_active_apply_worker_chain_refs(ctx, refs, taskId, expectedChainId, expectedPacketFingerprint, expectedSourceImplementationFingerprint, expectedDeclaredTaskWriteScope, expectedPreEditEvidenceRefs, expectedActiveFields = {}) {
     if (refs.length === 0) {
         return {
             refs: [],
@@ -902,6 +949,11 @@ function validate_active_apply_worker_chain_refs(ctx, refs, taskId, expectedChai
         if (!deepEqual(stringList(value.pre_edit_evidence_refs), stringList(expectedPreEditEvidenceRefs))) {
             fieldBlockers.push(reason("apply_worker_chain_ref_invalid", `${ref}: pre_edit_evidence_refs mismatch`, [ref]));
         }
+        for (const field of ["pre_edit_proof_kind", "apply_execution_surface", "tdd_required", "no_tdd_reason"]) {
+            if (field in expectedActiveFields && !deepEqual(value[field], expectedActiveFields[field])) {
+                fieldBlockers.push(reason("apply_worker_chain_ref_invalid", `${ref}: ${field} mismatch`, [ref]));
+            }
+        }
         return fieldBlockers;
     };
     for (const ref of refs) {
@@ -961,9 +1013,69 @@ function pre_edit_refs_bound_to_active_chain(ctx, active, refs, label, taskId) {
         if (!allowed.has(evidenceId))
             blockers.push(reason("pinned_evidence_ref_invalid", `${label} evidence ref is not part of active apply_worker_chain pre_edit_evidence_refs: ${evidenceId}`, [evidenceId]));
     }
-    blockers.push(...pre_edit_evidence_ref_reasons(ctx.evidences, active, taskId, "pinned_evidence_ref_invalid"));
+    blockers.push(...pre_edit_evidence_ref_reasons(ctx.changeRoot, ctx.evidences, active, taskId, "pinned_evidence_ref_invalid"));
     return blockers;
 }
+function validate_alternative_verification_evidence_refs(ctx, refs, taskId) {
+    if (refs.length === 0) {
+        return {
+            refs: [],
+            blockers: [reason("missing_alternative_verification_evidence_ref", "apply-verify-packet requires --alternative-verification-evidence-ref for no-TDD alternative verification")],
+        };
+    }
+    const resolved = [];
+    const blockers = [];
+    for (const ref of refs) {
+        let evidenceId = ref;
+        const maybePath = safe_within(ctx.changeRoot, ref);
+        if (maybePath !== null && existsSync(maybePath) && statSync(maybePath).isFile()) {
+            const loaded = read_json_ref(ctx, ref);
+            blockers.push(...loaded.blockers);
+            if (loaded.value) {
+                if (loaded.value.kind !== "alternative_verification" && loaded.value.kind !== "manual_verification") {
+                    blockers.push(reason("pinned_evidence_ref_invalid", `${ref}: kind must be alternative_verification or manual_verification`, [ref]));
+                }
+                if (normalize_gate(String(loaded.value.gate ?? "")) !== "task_complete")
+                    blockers.push(reason("pinned_evidence_ref_invalid", `${ref}: gate must be task_complete`, [ref]));
+                if (loaded.value.task_id !== taskId)
+                    blockers.push(reason("pinned_evidence_ref_invalid", `${ref}: task_id must be ${taskId}`, [ref]));
+                if (typeof loaded.value.evidence_id === "string" && loaded.value.evidence_id)
+                    evidenceId = loaded.value.evidence_id;
+            }
+        }
+        const ev = live_pass(ctx.evidences, { task_id: taskId })
+            .find((item) => String(item.evidence_id ?? "") === evidenceId && (item.kind === "alternative_verification" || item.kind === "manual_verification"));
+        if (!ev) {
+            blockers.push(reason("pinned_evidence_ref_invalid", `alternative verification evidence ref is not live/pass for ${taskId}: ${ref}`, [ref]));
+            continue;
+        }
+        if (normalize_gate(String(ev.gate ?? "")) !== "task_complete")
+            blockers.push(reason("pinned_evidence_ref_invalid", `${ref}: gate must be task_complete`, [ref]));
+        resolved.push(ev);
+    }
+    return { refs: resolved, blockers };
+}
+function active_chain_verifier_input_ref(active) {
+    return {
+        kind: "apply_worker_chain",
+        evidence_id: active?.evidence_id,
+        task_id: active?.task_id,
+        apply_worker_chain_id: active?.apply_worker_chain_id,
+        pre_edit_proof_kind: active?.pre_edit_proof_kind ?? "red_or_characterization",
+        pre_edit_evidence_refs: Array.isArray(active?.pre_edit_evidence_refs) ? active.pre_edit_evidence_refs.map(String).filter(Boolean).sort() : [],
+        ...(active?.apply_execution_surface !== undefined ? { apply_execution_surface: active.apply_execution_surface } : {}),
+        ...(active?.tdd_required !== undefined ? { tdd_required: active.tdd_required } : {}),
+        ...(active?.no_tdd_reason !== undefined ? { no_tdd_reason: active.no_tdd_reason } : {}),
+    };
+}
+function alternative_evidence_input_ref(ev) {
+    return {
+        kind: ev.kind,
+        evidence_id: ev.evidence_id,
+        gate: ev.gate,
+        task_id: ev.task_id,
+    };
+}
 function write_scope_blockers(taskId, writeScope) {
     const blockers = [];
     if (writeScope.length === 0) {
@@ -987,13 +1099,23 @@ function write_scope_blockers(taskId, writeScope) {
 function pre_edit_evidence_refs(ctx, taskId) {
     return live_pass(ctx.evidences, { gate: "task_edit", kind: "test_run", task_id: taskId })
         .filter((ev) => ev.semantic_status === "expected_failure" || ev.semantic_status === "expected_success")
+        .filter((ev) => pre_edit_worker_test_run_reasons(ctx.changeRoot, ev, taskId).length === 0)
         .map((ev) => String(ev.evidence_id ?? ""))
         .filter(Boolean)
         .sort();
 }
 function apply_task_context_fields(ctx, taskId, task, writeScope, expectedGuardRefs = []) {
+    const executionSurface = task ? task_apply_execution_surface(task) : "";
     return {
         task_content_ref: change_pinned_ref(ctx.changeRoot, "tasks.md"),
+        apply_execution_surface: executionSurface,
+        apply_execution_surface_source: task?.attrs.apply_execution_surface ? "explicit" : "default",
+        apply_execution_surface_policy: {
+            implementation_requires_executor_worker_chain: true,
+            runtime_config_requires_executor_worker_chain: true,
+            docs_generated_allows_direct_alternative_verification: true,
+            no_code_requires_empty_write_scope: true,
+        },
         task_acceptance_refs: task ? splitList(task.attrs.requirement_refs ?? "") : [],
         task_invariant_refs: task ? splitList(task.attrs.invariant_refs ?? "") : [],
         task_test_refs: task ? splitList(task.attrs.test_refs ?? "") : [],
@@ -1113,15 +1235,32 @@ function apply_executor_packet(ctx, args) {
     const { task, blockers: taskBlockers } = task_lookup_blockers(ctx, taskId);
     blockers.push(...taskBlockers);
     const writeScope = task ? splitList(task.attrs.write_scope ?? "") : [];
-    blockers.push(...write_scope_blockers(taskId, writeScope));
-    if (task && (task.attrs.tdd_required ?? "true").toLowerCase() === "false") {
-        blockers.push(reason("unsupported_executor_tdd_mode", `task ${taskId} has tdd_required:false and must stay on main-thread apply path`));
+    const executionSurface = task ? task_apply_execution_surface(task) : "";
+    const tddRequired = task ? (task.attrs.tdd_required ?? "true").toLowerCase() !== "false" : true;
+    const noTddReason = task?.attrs.no_tdd_reason;
+    const preEditProofKind = tddRequired ? "red_or_characterization" : "no_tdd_declared";
+    const activePreEditRefs = preEditProofKind === "no_tdd_declared" ? [] : pre_edit_evidence_refs(ctx, taskId);
+    if (task) {
+        blockers.push(...task_apply_execution_surface_reasons(taskId, task));
+        if (executionSurface === "implementation" || executionSurface === "runtime_config") {
+            if (!tddRequired && !NO_TDD_REASONS.has(String(noTddReason ?? ""))) {
+                blockers.push(reason("invalid_no_tdd_reason", `task ${taskId}: no_tdd_reason=${String(noTddReason ?? "")}`));
+            }
+            blockers.push(...write_scope_blockers(taskId, writeScope));
+        }
+        else {
+            blockers.push(reason("executor_handoff_not_required", `task ${taskId} apply_execution_surface=${executionSurface} does not use executor-worker implementation handoff`));
+        }
+    }
+    else {
+        blockers.push(...write_scope_blockers(taskId, writeScope));
     }
     blockers.push(...apply_worker_chain_packet_state(ctx, taskId).blockers);
     const packet = apply_packet_common(ctx, "apply_executor", taskId, "executor_worker", blockers);
     const chainId = active_apply_worker_chain_id(ctx, taskId) ?? generated_apply_worker_chain_id(ctx, taskId, writeScope);
     packet.worker_chain_context = "executor_worker";
     packet.apply_worker_chain_id = chainId;
+    packet.apply_execution_surface = executionSurface;
     packet.declared_task_write_scope = writeScope;
     packet.task_edit = decision_status(taskEdit);
     packet.task_complete = safe_decision_status(ctx, "task_complete", taskId);
@@ -1145,11 +1284,20 @@ function apply_executor_packet(ctx, args) {
         executor_packet_fingerprint: "",
         source_implementation_fingerprint: implementation_fingerprint(ctx, writeScope),
         declared_task_write_scope: writeScope,
-        pre_edit_evidence_refs: pre_edit_evidence_refs(ctx, taskId),
+        pre_edit_proof_kind: preEditProofKind,
+        apply_execution_surface: executionSurface,
+        tdd_required: tddRequired,
+        ...(tddRequired ? {} : { no_tdd_reason: noTddReason }),
+        pre_edit_evidence_refs: activePreEditRefs,
     };
     if (args.packet_format === "prompt") {
         const expectedPacketFingerprint = apply_worker_packet_fingerprint(packet);
-        const activeRefs = validate_active_apply_worker_chain_refs(ctx, args.apply_worker_chain_refs ?? [], taskId, chainId, expectedPacketFingerprint, packet.chain_activation_template.source_implementation_fingerprint, packet.chain_activation_template.declared_task_write_scope, packet.chain_activation_template.pre_edit_evidence_refs);
+        const activeRefs = validate_active_apply_worker_chain_refs(ctx, args.apply_worker_chain_refs ?? [], taskId, chainId, expectedPacketFingerprint, packet.chain_activation_template.source_implementation_fingerprint, packet.chain_activation_template.declared_task_write_scope, packet.chain_activation_template.pre_edit_evidence_refs, {
+            pre_edit_proof_kind: packet.chain_activation_template.pre_edit_proof_kind,
+            apply_execution_surface: packet.chain_activation_template.apply_execution_surface,
+            tdd_required: packet.chain_activation_template.tdd_required,
+            ...(packet.chain_activation_template.no_tdd_reason !== undefined ? { no_tdd_reason: packet.chain_activation_template.no_tdd_reason } : {}),
+        });
         blockers.push(...activeRefs.blockers);
         packet.apply_worker_chain_refs = args.apply_worker_chain_refs ?? [];
         packet.apply_worker_chain_active_refs = activeRefs.refs;
@@ -1240,10 +1388,13 @@ function apply_verify_packet(ctx, args) {
     const { task, blockers: taskBlockers } = task_lookup_blockers(ctx, taskId);
     blockers.push(...taskBlockers);
     const writeScope = task ? splitList(task.attrs.write_scope ?? "") : [];
+    const executionSurface = task ? task_apply_execution_surface(task) : "";
+    const tddRequired = task ? (task.attrs.tdd_required ?? "true").toLowerCase() !== "false" : true;
     blockers.push(...write_scope_blockers(taskId, writeScope));
     const chainId = require_active_apply_worker_chain(ctx, taskId, blockers);
     const activeChain = active_apply_worker_chain(ctx, taskId).active;
     const packet = apply_packet_common(ctx, "apply_verify", taskId, "executor_worker", blockers);
+    const completionProofKind = (args.alternative_verification_evidence_refs ?? []).length > 0 ? "alternative_verification" : "green_tests";
     if (chainId) {
         const executorRefs = validate_worker_report_refs(ctx, args.executor_report_refs ?? [], {
             role: "executor",
@@ -1286,7 +1437,8 @@ function apply_verify_packet(ctx, args) {
             missingCode: "missing_characterization_test_run_evidence_ref",
             missingMessage: "apply-verify-packet requires --characterization-test-run-evidence-ref",
         });
-        blockers.push(...executorRefs.blockers, ...codeReviewRefs.blockers, ...greenRefs.blockers);
+        const alternativeRefs = validate_alternative_verification_evidence_refs(ctx, args.alternative_verification_evidence_refs ?? [], taskId);
+        blockers.push(...executorRefs.blockers, ...codeReviewRefs.blockers);
         if (executorRefs.refs[0]) {
             blockers.push(...worker_report_origin_blockers(executorRefs.refs[0], activeChain?.executor_packet_fingerprint, "executor_report_ref"));
             if (activeChain) {
@@ -1296,19 +1448,47 @@ function apply_verify_packet(ctx, args) {
         if (executorRefs.refs[0] && codeReviewRefs.refs[0]) {
             blockers.push(...worker_report_input_blockers(codeReviewRefs.refs[0], [executorRefs.refs[0]], "task_code_review_report_ref"));
         }
-        if ((args.red_test_run_evidence_refs ?? []).length === 0 && (args.characterization_test_run_evidence_refs ?? []).length === 0) {
-            blockers.push(reason("missing_pre_edit_test_run_evidence_ref", "apply-verify-packet requires --red-test-run-evidence-ref or --characterization-test-run-evidence-ref"));
+        if (completionProofKind === "green_tests") {
+            blockers.push(...greenRefs.blockers);
+            if ((args.red_test_run_evidence_refs ?? []).length === 0 && (args.characterization_test_run_evidence_refs ?? []).length === 0) {
+                blockers.push(reason("missing_pre_edit_test_run_evidence_ref", "apply-verify-packet requires --red-test-run-evidence-ref or --characterization-test-run-evidence-ref"));
+            }
+            else {
+                if ((args.red_test_run_evidence_refs ?? []).length > 0)
+                    blockers.push(...redRefs.blockers, ...pre_edit_refs_bound_to_active_chain(ctx, activeChain, redRefs.refs, "red", taskId));
+                if ((args.characterization_test_run_evidence_refs ?? []).length > 0)
+                    blockers.push(...characterizationRefs.blockers, ...pre_edit_refs_bound_to_active_chain(ctx, activeChain, characterizationRefs.refs, "characterization", taskId));
+            }
         }
         else {
-            if ((args.red_test_run_evidence_refs ?? []).length > 0)
-                blockers.push(...redRefs.blockers, ...pre_edit_refs_bound_to_active_chain(ctx, activeChain, redRefs.refs, "red", taskId));
-            if ((args.characterization_test_run_evidence_refs ?? []).length > 0)
-                blockers.push(...characterizationRefs.blockers, ...pre_edit_refs_bound_to_active_chain(ctx, activeChain, characterizationRefs.refs, "characterization", taskId));
+            blockers.push(...alternativeRefs.blockers);
+            const activePreIds = Array.isArray(activeChain?.pre_edit_evidence_refs) ? activeChain.pre_edit_evidence_refs.map(String).filter(Boolean) : [];
+            if (activeChain?.pre_edit_proof_kind !== "no_tdd_declared") {
+                blockers.push(reason("apply_worker_chain_active_invalid", "alternative verification requires active apply_worker_chain pre_edit_proof_kind=no_tdd_declared"));
+            }
+            if (activePreIds.length > 0) {
+                blockers.push(reason("apply_worker_chain_active_invalid", `alternative verification requires empty active pre_edit_evidence_refs: ${renderList(activePreIds)}`, activePreIds));
+            }
+            if (tddRequired || activeChain?.tdd_required !== false) {
+                blockers.push(reason("apply_worker_chain_active_invalid", "alternative verification requires task and active apply_worker_chain tdd_required=false"));
+            }
+            if (executionSurface !== "implementation" && executionSurface !== "runtime_config") {
+                blockers.push(reason("alternative_verification_surface_invalid", `alternative verification worker-chain proof requires implementation/runtime_config surface, got ${executionSurface}`));
+            }
+            if (activeChain?.apply_execution_surface !== executionSurface) {
+                blockers.push(reason("apply_worker_chain_active_invalid", "active apply_worker_chain apply_execution_surface must match task surface"));
+            }
+            if (!NO_TDD_REASONS.has(String(activeChain?.no_tdd_reason ?? "")) || activeChain?.no_tdd_reason !== task?.attrs.no_tdd_reason) {
+                blockers.push(reason("apply_worker_chain_active_invalid", "active apply_worker_chain no_tdd_reason must be valid and match task"));
+            }
         }
         packet.apply_worker_chain_id = chainId;
+        packet.completion_proof_kind = completionProofKind;
+        packet.pre_edit_proof_kind = activeChain?.pre_edit_proof_kind ?? "red_or_characterization";
         packet.executor_report_pinned_refs = executorRefs.refs;
         packet.task_code_review_report_pinned_refs = codeReviewRefs.refs;
         packet.green_test_run_evidence_pinned_refs = greenRefs.refs;
+        packet.alternative_verification_evidence_pinned_refs = alternativeRefs.refs;
         packet.red_test_run_evidence_pinned_refs = redRefs.refs;
         packet.characterization_test_run_evidence_pinned_refs = characterizationRefs.refs;
         if (executorRefs.refs[0])
@@ -1318,13 +1498,14 @@ function apply_verify_packet(ctx, args) {
         if (executorRefs.refs[0] && codeReviewRefs.refs[0]) {
             packet.expected_code_review_input_ref_digest = worker_input_ref_digest([executorRefs.refs[0]]);
         }
-        if (executorRefs.refs[0] && codeReviewRefs.refs[0] && greenRefs.refs[0]) {
+        if (completionProofKind === "green_tests" && executorRefs.refs[0] && codeReviewRefs.refs[0] && greenRefs.refs[0]) {
             const canonicalGreenRefs = [...greenRefs.refs].sort((a, b) => String(a.evidence_id ?? "").localeCompare(String(b.evidence_id ?? "")));
             const expectedFreshness = compute_apply_worker_freshness(ctx.repoRoot, ctx.changeRoot, ctx.evidences, taskId, chainId, {
                 executor_report_ref: executorRefs.refs[0],
                 task_code_review_report_ref: codeReviewRefs.refs[0],
                 green_test_run_evidence_ref: String(canonicalGreenRefs[0].evidence_id ?? ""),
                 green_test_run_evidence_refs: canonicalGreenRefs.map((ev) => String(ev.evidence_id ?? "")).filter(Boolean),
+                completion_proof_kind: "green_tests",
             });
             packet.expected_freshness_fingerprint = expectedFreshness;
             const preEditRefs = [
@@ -1351,8 +1532,34 @@ function apply_verify_packet(ctx, args) {
                 blockers.push(reason("protected_path_dirty", `apply-verify-packet requires protected change artifacts to stay unchanged during executor-worker verification: ${renderList(expectedFreshness.protected_dirty_paths.map(String))}`, expectedFreshness.protected_dirty_paths.map(String)));
             }
         }
+        else if (completionProofKind === "alternative_verification" && executorRefs.refs[0] && codeReviewRefs.refs[0] && alternativeRefs.refs[0]) {
+            const canonicalAlternativeRefs = [...alternativeRefs.refs].sort((a, b) => String(a.evidence_id ?? "").localeCompare(String(b.evidence_id ?? "")));
+            const expectedFreshness = compute_apply_worker_freshness(ctx.repoRoot, ctx.changeRoot, ctx.evidences, taskId, chainId, {
+                executor_report_ref: executorRefs.refs[0],
+                task_code_review_report_ref: codeReviewRefs.refs[0],
+                alternative_verification_evidence_refs: canonicalAlternativeRefs.map((ev) => String(ev.evidence_id ?? "")).filter(Boolean),
+                completion_proof_kind: "alternative_verification",
+            });
+            packet.expected_freshness_fingerprint = expectedFreshness;
+            packet.expected_verifier_input_ref_digest = worker_input_ref_digest([
+                executorRefs.refs[0],
+                codeReviewRefs.refs[0],
+                ...canonicalAlternativeRefs.map(alternative_evidence_input_ref),
+                active_chain_verifier_input_ref(activeChain),
+            ]);
+            if (!fingerprint_matches(codeReviewRefs.refs[0].observed_implementation_fingerprint, expectedFreshness.implementation_fingerprint)) {
+                blockers.push(reason("task_code_review_implementation_fingerprint_mismatch", "apply-verify-packet requires code-reviewer observed_implementation_fingerprint to match current implementation fingerprint"));
+            }
+            if (Array.isArray(expectedFreshness.protected_dirty_paths) && expectedFreshness.protected_dirty_paths.length > 0) {
+                blockers.push(reason("protected_path_dirty", `apply-verify-packet requires protected change artifacts to stay unchanged during executor-worker verification: ${renderList(expectedFreshness.protected_dirty_paths.map(String))}`, expectedFreshness.protected_dirty_paths.map(String)));
+            }
+        }
     }
     packet.declared_task_write_scope = writeScope;
+    packet.apply_execution_surface = executionSurface;
+    packet.tdd_required = tddRequired;
+    if (!tddRequired)
+        packet.no_tdd_reason = task?.attrs.no_tdd_reason;
     packet.task_edit = decision_status(taskEdit);
     packet.task_complete = safe_decision_status(ctx, "task_complete", taskId);
     Object.assign(packet, apply_task_context_fields(ctx, taskId, task, writeScope, [
@@ -1369,20 +1576,30 @@ function apply_verify_packet(ctx, args) {
         require_scope_verdict: true,
     };
     packet.verification_checks = [
-        "red_or_characterization_pre_edit_evidence_bound_to_active_chain",
+        completionProofKind === "green_tests"
+            ? "red_or_characterization_pre_edit_evidence_bound_to_active_chain"
+            : "no_tdd_declared_active_chain_has_empty_pre_edit_refs",
         "executor_report_same_chain_and_fresh",
         "task_code_review_report_same_chain_and_fresh",
-        "green_test_run_same_chain_and_pinned_transcripts",
+        completionProofKind === "green_tests"
+            ? "green_test_run_same_chain_and_pinned_transcripts"
+            : "alternative_or_manual_verification_refs_live_pass_and_digest_bound",
         "current_freshness_matches_expected_freshness_fingerprint",
         "protected_change_artifacts_clean",
     ];
     packet.executor_report_required_fields = [...APPLY_EXECUTOR_REPORT_REQUIRED_FIELDS];
     packet.code_review_report_required_fields = [...APPLY_CODE_REVIEW_REPORT_REQUIRED_FIELDS];
-    packet.verifier_report_required_fields = [...APPLY_VERIFIER_REPORT_REQUIRED_FIELDS];
+    packet.verifier_report_required_fields = [
+        ...APPLY_VERIFIER_REPORT_REQUIRED_FIELDS,
+        ...(completionProofKind === "green_tests"
+            ? ["green_test_run_evidence_refs", "red_test_run_evidence_refs_or_characterization_test_run_evidence_refs"]
+            : ["alternative_verification_evidence_refs", "apply_execution_surface", "tdd_required", "no_tdd_reason"]),
+    ];
     packet.test_evidence_required_fields = ["command", "cwd", "exit_code", "repo_head", "implementation_fingerprint", "guard_artifact_manifest_fingerprint", "raw_log_pinned_refs"];
     packet.executor_report_refs = args.executor_report_refs ?? [];
     packet.task_code_review_report_refs = args.task_code_review_report_refs ?? [];
     packet.green_test_run_evidence_refs = args.green_test_run_evidence_refs ?? [];
+    packet.alternative_verification_evidence_refs = args.alternative_verification_evidence_refs ?? [];
     packet.red_test_run_evidence_refs = args.red_test_run_evidence_refs ?? [];
     packet.characterization_test_run_evidence_refs = args.characterization_test_run_evidence_refs ?? [];
     packet.worker_state = blockers.length === 0 ? "ready" : "blocked";

package/dist/src/packet_schema.d.ts

@@ -29,6 +29,8 @@ export type WorkflowPacket = {
     must_read_verbatim_findings?: FindingSelector[];
     must_read_verbatim_decisions?: DecisionSelector[];
     diagnostic_command?: string;
+    discovery_template?: string;
+    discovery_rules?: string[];
 };
 export type ReviewPacket = {
     consumer: "role" | "main-thread";

package/dist/src/tasks.d.ts

@@ -25,6 +25,11 @@ export declare function parse_spec_scenarios(changeRoot: string): string[];
 export declare function test_contract_covers_scenario(changeRoot: string, scenario: string): boolean;
 export declare function test_contract_invariant_refs_by_test(changeRoot: string): Map<string, Set<string>>;
 export declare function task_test_refs(tasks: Record<string, TaskInfo>): Set<string>;
+export declare const APPLY_EXECUTION_SURFACES: Set<string>;
+export type ApplyExecutionSurface = "implementation" | "runtime_config" | "docs_generated" | "no_code";
+export declare function docs_generated_write_scope_reasons(writeScope: string[], taskId?: string): Reason[];
+export declare function task_apply_execution_surface(task: TaskInfo): ApplyExecutionSurface | string;
+export declare function task_apply_execution_surface_reasons(taskId: string, task: TaskInfo): Reason[];
 export declare function write_scope_conflict_reasons(tasks: Record<string, TaskInfo>): Reason[];
 export declare function red_green_test_ids(evidences: JsonMap[]): Set<string>;
 export declare function task_test_evidence(evidences: JsonMap[], taskId: string, semanticStatus: string, gate?: string | null): JsonMap[];