@event4u/agent-config 9.29.0 → 9.30.0

package/src/scripts/_lib/judgment_ladder.ts

@@ -37,14 +37,18 @@ import {
 } from './auto_dispatch.js';
 
 /** The five dispatch rungs, or `null` for the silent ∅ (in-session / ask). */
-export type LadderRung = 0 | 1 | 2 | 3 | 4 | null;
+export type LadderRung = 0 | 0.5 | 1 | 2 | 3 | 4 | null;
 
 export type LadderVerdict =
     | 'script' // rung 0 — deterministic transform/primitive, no spawn at all
     | 'subagent' // rung 1/2 — one, or several downshifted, subagent dispatch(es)
     | 'team' // rung 3 — communicating slices, dispatched via the host teams primitive
     | 'council' // rung 4 — contested judgment
-    | 'ask' // ∅ — ambiguous; a VERDICT to the user, never a speculative spawn
+    // 'ask' carries TWO shapes, split by rung (road-to-token-economy-dispatch
+    // Phase 4): rung 0.5 = a bounded question routed to ONE completion via
+    // `ask_transport` (no session, no tools, hard-capped — never the user);
+    // rung null = ambiguity, a VERDICT to the user, never a speculative spawn.
+    | 'ask'
     | 'in-session'; // ∅ — halted, no host primitive, trivial, approval-required, or recursive guard
 
 export interface LadderResult {
@@ -279,6 +283,62 @@ export function detectContestedJudgment(text: string): { matched: boolean; reaso
  * `point-of-action-carrier` blocker already names as its pre-registered
  * null ("no discriminator" is publishable and does not block this roadmap).
  */
+/**
+ * Rung-0.5 signal — a single bounded question (token-economy-dispatch 4.2).
+ *
+ * Deliberately conservative, regex-only (the F3-lite discipline): the cost
+ * of a false NEGATIVE is one avoidable spawn; the cost of a false POSITIVE
+ * is an ask that returns INSUFFICIENT_CONTEXT and gets escalated — which the
+ * registered `ask_economy` kill criterion counts against the rung. So every
+ * ambiguity falls through (no match), and four hard exclusions apply:
+ *
+ *   1. Multi-line prompts — a bounded question is one sentence.
+ *   2. Length > 240 chars — beyond that it is a briefing, not a question.
+ *   3. Imperative work verbs (fix/implement/write/…) — those are tasks.
+ *   4. No interrogative shape — must lead with an interrogative (EN/DE) and
+ *      end with `?`, OR be an explicit classify/categorize instruction
+ *      (the one imperative the roadmap names as ask-shaped).
+ */
+const _QUESTION_IMPERATIVE_RE =
+    /\b(fix|implement|refactor|build|create|write|add|update|delete|remove|rename|migrate|install|deploy|commit|push|merge|run|execute|generate|erstelle|baue|implementiere|schreibe|behebe)\b/i;
+const _QUESTION_LEAD_RE =
+    /^(is|are|does|do|did|can|could|should|would|will|which|what|why|how|when|where|who|whose|ist|sind|hat|haben|kann|welche[rs]?|was|warum|wie|wann|wo|wer)\b/i;
+const _CLASSIFY_LEAD_RE = /^(classify|categori[sz]e|klassifiziere)\b/i;
+const _QUESTION_MAX_LEN = 240;
+
+/** A question that names a file/repo object or a concrete path needs TOOLS —
+ *  a blind completion cannot read it, so it is never ask-shaped. */
+const _NEEDS_TOOLS_RE =
+    /\b(this|the|that|my|our)\s+(?:[\w-]+\s+){0,2}?(file|files|codebase|repo|repository|transcript|log|logs|diff|document|branch|pr|route|routes|schema|module|class|function|endpoint|test|tests)\b|[\w.-]+\/[\w.-]+|\b[\w-]+\.(ts|js|py|php|md|json|yaml|yml|sh|go|rs)\b/i;
+
+export function detectBoundedQuestion(taskText: string): { matched: boolean; reason: string } {
+    const text = taskText.trim();
+    if (!text || text.length > _QUESTION_MAX_LEN || text.includes('\n')) {
+        return { matched: false, reason: 'not-bounded' };
+    }
+    if (_NEEDS_TOOLS_RE.test(text)) {
+        return { matched: false, reason: 'references-tool-requiring-objects' };
+    }
+    // Classify-lead first: its PAYLOAD may quote work verbs ("classify this
+    // error: ETIMEDOUT on push") without being a work instruction itself.
+    if (_CLASSIFY_LEAD_RE.test(text)) {
+        return {
+            matched: true,
+            reason: 'bounded-question (classification) — rung-0.5 single completion via ask_transport, no session',
+        };
+    }
+    if (_QUESTION_IMPERATIVE_RE.test(text)) {
+        return { matched: false, reason: 'imperative-work-verb' };
+    }
+    if (_QUESTION_LEAD_RE.test(text) && text.endsWith('?')) {
+        return {
+            matched: true,
+            reason: 'bounded-question — rung-0.5 single completion via ask_transport, no session',
+        };
+    }
+    return { matched: false, reason: 'no-interrogative-shape' };
+}
+
 export function classifyLadder(inp: LadderInputs): LadderResult {
     if (inp.interactiveApprovalRequired === true) {
         return {
@@ -362,6 +422,18 @@ export function classifyLadder(inp: LadderInputs): LadderResult {
     // regex and dispatched a subagent anyway, silently bypassing the floor
     // `classifyTask` had just enforced one line above.
     if (inp.signals.size_estimate <= SIZE_FLOOR) {
+        // Rung 0.5 (token-economy-dispatch 4.2) — a SELF-CONTAINED bounded
+        // question below the floor is the one below-spawn shape with its own
+        // routing verdict: one completion via ask_transport (no session, no
+        // tools, hard-capped). This is an ORCHESTRATOR-facing routing datum —
+        // the delegation-nudge carrier deliberately stays silent on it (a
+        // user's question is answered in-session at zero marginal cost; see
+        // classifyPrompt). Questions referencing files/paths are excluded by
+        // the detector: a completion without tools cannot read them.
+        const question = detectBoundedQuestion(inp.taskText);
+        if (question.matched) {
+            return { rung: 0.5, verdict: 'ask', reason: question.reason };
+        }
         return {
             rung: null,
             verdict: classification.action === 'ask' ? 'ask' : 'in-session',
@@ -380,3 +452,183 @@ export function classifyLadder(inp: LadderInputs): LadderResult {
         reason: classification.reason,
     };
 }
+
+// ── Explanation trail (additive — Phase 4.1, road-to-feedback-9-29) ──────
+//
+// `classifyLadder` short-circuits on the first rung that resolves, so its
+// minimal `{rung, verdict, reason}` return cannot answer "why NOT team /
+// why NOT council / why no spawn". This layer answers exactly that without
+// touching the minimal shape current callers depend on: the result is taken
+// from `classifyLadder` itself (never re-derived, so the two can never
+// disagree on the headline), and the per-rung trail is reconstructed from
+// the SAME exported pure detectors and gate fields the resolver reads, in
+// the same fixed priority order.
+
+export type RungStatus = 'taken' | 'rejected' | 'not-reached';
+
+export interface RungEvaluation {
+    rung: 0 | 0.5 | 1 | 2 | 3 | 4;
+    /** The verdict this rung resolves to when taken. */
+    resolves_to: 'script' | 'ask' | 'subagent' | 'team' | 'council';
+    status: RungStatus;
+    reason: string;
+}
+
+export interface LadderExplanation {
+    /** The authoritative resolution — exactly `classifyLadder(inp)`. */
+    result: LadderResult;
+    /**
+     * Per-rung trail in the resolver's fixed priority order: 0, 4, 3, 2, 0.5, 1.
+     *
+     * 0.5 sits where the resolver checks it — inside the size-floor branch,
+     * after rung 2's verdict and before rung 1 — not where its number would
+     * sort. The order IS the contract, so the trail follows the walk.
+     */
+    trail: RungEvaluation[];
+    /** Present only when `result.rung` is null (∅) — the why-no-spawn reason. */
+    no_spawn_reason?: string;
+}
+
+/**
+ * Explain one ladder resolution: the rung taken, every rung genuinely
+ * evaluated-and-rejected (with the detector's own reason), and rungs the
+ * short-circuit never reached (marked `not-reached`, never given a
+ * fabricated rejection reason — a lower rung's detector might well have
+ * matched had it been consulted).
+ */
+export function explainLadder(inp: LadderInputs): LadderExplanation {
+    const result = classifyLadder(inp);
+    const trail: RungEvaluation[] = [];
+    const approval = inp.interactiveApprovalRequired === true;
+
+    // Rung 0 — evaluated first, exempt from the guards below.
+    if (result.rung === 0) {
+        trail.push({ rung: 0, resolves_to: 'script', status: 'taken', reason: result.reason });
+    } else if (approval) {
+        trail.push({
+            rung: 0,
+            resolves_to: 'script',
+            status: 'not-reached',
+            reason: 'interactive-approval-required resolves before every rung',
+        });
+    } else {
+        const lookup = classifyLookup(inp.taskText);
+        const mechanical = detectMechanicalTransform(inp.taskText);
+        trail.push({ rung: 0, resolves_to: 'script', status: 'rejected', reason: `${lookup.reason}; ${mechanical.reason}` });
+    }
+
+    // A gate that resolved ∅ before rung 4 blocks rungs 4-1 wholesale; a
+    // resolution at rung 0 means they were never consulted either.
+    const gate: string | null = approval
+        ? 'interactive-approval-required — caller-stated, resolves ∅'
+        : result.rung === 0
+          ? 'resolved at rung 0'
+          : inp.insideSubagentSession === true
+            ? 'recursive-dispatch guard — running inside a subagent/teammate session'
+            : inp.activation.halted
+              ? 'emergency.orchestration_halt is set'
+              : !inp.activation.subagent_spawn
+                ? 'host has no subagent_spawn primitive'
+                : null;
+
+    const notReached = (why: string): string => `not evaluated — ${why}`;
+
+    // Rung 4 — council.
+    if (gate !== null) {
+        trail.push({ rung: 4, resolves_to: 'council', status: 'not-reached', reason: notReached(gate) });
+    } else if (result.rung === 4) {
+        trail.push({ rung: 4, resolves_to: 'council', status: 'taken', reason: result.reason });
+    } else {
+        trail.push({ rung: 4, resolves_to: 'council', status: 'rejected', reason: detectContestedJudgment(inp.taskText).reason });
+    }
+
+    // Rung 3 — team.
+    if (gate !== null) {
+        trail.push({ rung: 3, resolves_to: 'team', status: 'not-reached', reason: notReached(gate) });
+    } else if (result.rung === 4) {
+        trail.push({ rung: 3, resolves_to: 'team', status: 'not-reached', reason: notReached('resolved at rung 4') });
+    } else if (result.rung === 3) {
+        trail.push({ rung: 3, resolves_to: 'team', status: 'taken', reason: result.reason });
+    } else {
+        const communication = detectCommunicationNeed(inp.taskText);
+        const reason =
+            communication.matched && result.degraded_from === 3
+                ? `${communication.reason} — but host reports agent_teams: false, degraded (see resolved rung)`
+                : communication.reason;
+        trail.push({ rung: 3, resolves_to: 'team', status: 'rejected', reason });
+    }
+
+    // Rungs 2 and 1 — classifyTask's verdict, then the single-slice check.
+    const resolvedAbove = result.rung === 4 || result.rung === 3;
+    if (gate !== null || resolvedAbove) {
+        const why = gate ?? `resolved at rung ${result.rung}`;
+        trail.push({ rung: 2, resolves_to: 'subagent', status: 'not-reached', reason: notReached(why) });
+        trail.push({ rung: 0.5, resolves_to: 'ask', status: 'not-reached', reason: notReached(why) });
+        trail.push({ rung: 1, resolves_to: 'subagent', status: 'not-reached', reason: notReached(why) });
+    } else {
+        const classification = classifyTask(inp.signals, inp.activation);
+        if (result.rung === 2) {
+            trail.push({ rung: 2, resolves_to: 'subagent', status: 'taken', reason: result.reason });
+            trail.push({ rung: 0.5, resolves_to: 'ask', status: 'not-reached', reason: notReached('resolved at rung 2') });
+            trail.push({ rung: 1, resolves_to: 'subagent', status: 'not-reached', reason: notReached('resolved at rung 2') });
+        } else {
+            trail.push({ rung: 2, resolves_to: 'subagent', status: 'rejected', reason: classification.reason });
+            if (result.rung === 1) {
+                trail.push({
+                    rung: 0.5,
+                    resolves_to: 'ask',
+                    status: 'not-reached',
+                    reason: notReached(`task above the size floor (${inp.signals.size_estimate} > ${SIZE_FLOOR}) — rung 0.5 is reachable only below it`),
+                });
+                trail.push({ rung: 1, resolves_to: 'subagent', status: 'taken', reason: result.reason });
+            } else if (result.degraded_from === 3) {
+                // The communication branch returns from INSIDE rung 3's handling
+                // (its `classifyTask` fallback is the rung-2 attempt), so it exits
+                // before `detectBoundedReadHeavySlice` is ever called. Reporting
+                // rung 1 as `rejected` here quoted that detector's reason — and
+                // when the detector MATCHES, that reason describes a match, so
+                // the trail read "rejected: one lite-tier subagent instead of
+                // session-context burn". A maintainer asking why nothing spawned
+                // was told rung 1 declined, hiding the missing agent_teams
+                // capability that actually ended the walk.
+                const skipped = notReached('the rung-3 communication branch resolved before it was consulted');
+                trail.push({ rung: 0.5, resolves_to: 'ask', status: 'not-reached', reason: skipped });
+                trail.push({ rung: 1, resolves_to: 'subagent', status: 'not-reached', reason: skipped });
+            } else if (inp.signals.size_estimate <= SIZE_FLOOR) {
+                // Rung 0.5 lives INSIDE the resolver's floor branch, between rung
+                // 2 and rung 1, so it is reachable only here. Emitting it in that
+                // position keeps the trail's order the resolver's order; omitting
+                // it (as this trail did before the rung landed) would report a
+                // walk that skipped a rung the resolver actually consulted.
+                if (result.rung === 0.5) {
+                    trail.push({ rung: 0.5, resolves_to: 'ask', status: 'taken', reason: result.reason });
+                } else {
+                    trail.push({
+                        rung: 0.5,
+                        resolves_to: 'ask',
+                        status: 'rejected',
+                        reason: detectBoundedQuestion(inp.taskText).reason,
+                    });
+                }
+                trail.push({
+                    rung: 1,
+                    resolves_to: 'subagent',
+                    status: 'rejected',
+                    reason: `task below size floor (${inp.signals.size_estimate} <= ${SIZE_FLOOR}) — rung 1 never bypasses the floor`,
+                });
+            } else {
+                // Above the floor the resolver never enters the branch rung 0.5
+                // lives in, so it was not consulted — not declined.
+                trail.push({
+                    rung: 0.5,
+                    resolves_to: 'ask',
+                    status: 'not-reached',
+                    reason: notReached(`task above the size floor (${inp.signals.size_estimate} > ${SIZE_FLOOR}) — rung 0.5 is reachable only below it`),
+                });
+                trail.push({ rung: 1, resolves_to: 'subagent', status: 'rejected', reason: detectBoundedReadHeavySlice(inp.taskText).reason });
+            }
+        }
+    }
+
+    return result.rung === null ? { result, trail, no_spawn_reason: result.reason } : { result, trail };
+}

package/src/scripts/_lib/orchestration_record.ts

@@ -19,8 +19,10 @@
 import type { LookupClass } from './auto_dispatch.js';
 
 export type DispatchOutcome = 'DONE' | 'DONE_WITH_CONCERNS' | 'NEEDS_CONTEXT' | 'BLOCKED' | 'killed';
-/** Which route the lookup-class rung took (lean-init L0). */
-export type RouteTaken = 'primitive' | 'subagent';
+/** Which route the rung took: deterministic primitive (lean-init L0),
+ *  single-completion ask (token-economy-dispatch rung 0.5), or a full
+ *  subagent spawn. */
+export type RouteTaken = 'primitive' | 'subagent' | 'ask';
 export type VerifyMode = 'deterministic' | 'judge' | 'none';
 export type Provenance = 'measured' | 'estimated';
 export type TierChosen = 'lite' | 'medium' | 'high';
@@ -98,6 +100,23 @@ export interface RecordInput {
     /** Rules the worker actually applied/cited (count of the envelope's
      *  `rules_applied`-equivalent on the worker side). Counts only. */
     rules_used?: number | null | undefined;
+    // ── dispatch-economy additive fields (road-to-token-economy-dispatch
+    //    Phase 1.1). `init_tokens` above (lean-init) is the spawn-payload
+    //    half; `work_tokens` is the delta from first worker turn to envelope
+    //    close. Both are counts; the pair's provenance rides
+    //    `floor_provenance` exactly like `token_delta_provenance` tags
+    //    `token_delta`. ──
+    /** Tokens the worker consumed AFTER init (delta to envelope close). */
+    work_tokens?: number | null | undefined;
+    /** Chars the dispatch RETURNED into the orchestrator context (serialized
+     *  tool-result length on sync completions) — the Phase 6.3 detector for
+     *  "isolation win refunded through the return channel". A count, never
+     *  content. */
+    return_channel_chars?: number | null | undefined;
+    /** Provenance of the init/work pair: 'measured' (transcript ledger via
+     *  cc_transcript) or 'estimated'. Defaults to 'estimated' when either
+     *  field is present without a tag. */
+    floor_provenance?: Provenance | null | undefined;
     // ── capsule shadow-measurement fields (road-to-worker-generation-recycling
     //    Phase 1.2). SHADOW ONLY: the worker still runs to stop-loss, nothing
     //    reads a capsule. All counts / enums — a capsule's CONTENT never
@@ -138,7 +157,7 @@ const TIER_SOURCES: readonly TierSource[] = ['static', 'inferred', 'inherit'];
 const BANDS: readonly Band[] = ['low', 'medium', 'high'];
 const PHASES: readonly LinePhase[] = ['refine', 'memory', 'analyze', 'plan', 'implement', 'test', 'verify', 'report'];
 const LOOKUP_CLASSES: readonly LookupClass[] = ['definition', 'references', 'string-existence', 'report-run'];
-const ROUTES_TAKEN: readonly RouteTaken[] = ['primitive', 'subagent'];
+const ROUTES_TAKEN: readonly RouteTaken[] = ['primitive', 'subagent', 'ask'];
 const TRIGGER_ARMS: readonly TriggerArm[] = ['watermark', 'saturation', 'tie'];
 /** Hex-only payload hash — a hash can never smuggle content (privacy by construction). */
 const PAYLOAD_HASH_RE = /^[a-f0-9]{8,64}$/i;
@@ -164,13 +183,15 @@ function isInt(n: unknown): n is number {
 export function buildOrchestrationLine(input: RecordInput): BuiltLine {
     const errors: string[] = [];
 
-    // A lookup-class primitive route is the ONE recordable zero-spawn event
-    // (lean-init L0): the routing decision itself is the datum the
-    // cost-reduction claim reads. Everything else with spawn_count 0 stays
-    // unrecordable in-session work.
-    const zeroSpawnPrimitive = input.route_taken === 'primitive' && input.spawn_count === 0;
-    if (!zeroSpawnPrimitive && (!isInt(input.spawn_count) || input.spawn_count < 1)) {
-        errors.push('spawn_count must be an integer ≥ 1 (0 = handled in-session, not a dispatch — do not record; exception: route_taken=primitive lookup routes record with spawn_count 0)');
+    // A lookup-class primitive route (lean-init L0) and a rung-0.5 ask route
+    // (token-economy-dispatch Phase 4) are the TWO recordable zero-spawn
+    // events: the routing decision itself is the datum the cost-reduction
+    // claim reads. Everything else with spawn_count 0 stays unrecordable
+    // in-session work.
+    const zeroSpawnRoute =
+        (input.route_taken === 'primitive' || input.route_taken === 'ask') && input.spawn_count === 0;
+    if (!zeroSpawnRoute && (!isInt(input.spawn_count) || input.spawn_count < 1)) {
+        errors.push('spawn_count must be an integer ≥ 1 (0 = handled in-session, not a dispatch — do not record; exception: route_taken=primitive|ask routes record with spawn_count 0)');
     }
     if (!isInt(input.token_delta)) errors.push('token_delta must be an integer (negative = net saved vs the in-session baseline)');
     if (input.task_size_estimate !== undefined && (!isInt(input.task_size_estimate) || input.task_size_estimate < 0)) {
@@ -239,9 +260,14 @@ export function buildOrchestrationLine(input: RecordInput): BuiltLine {
     for (const [key, v] of [
         ['rules_carried', input.rules_carried],
         ['rules_used', input.rules_used],
+        ['work_tokens', input.work_tokens],
+        ['return_channel_chars', input.return_channel_chars],
     ] as const) {
         if (v != null && (!isInt(v) || v < 0)) errors.push(`${key} must be a non-negative integer count`);
     }
+    if (input.floor_provenance != null && !PROVENANCES.includes(input.floor_provenance)) {
+        errors.push(`floor_provenance must be one of ${PROVENANCES.join(' | ')} (or omitted)`);
+    }
     if (
         input.rules_carried != null &&
         input.rules_used != null &&
@@ -298,6 +324,11 @@ export function buildOrchestrationLine(input: RecordInput): BuiltLine {
         origin: input.origin ?? null,
         rules_carried: input.rules_carried ?? null,
         rules_used: input.rules_used ?? null,
+        // dispatch-economy additive fields — readers ignore unknowns per audit-log-v1
+        work_tokens: input.work_tokens ?? null,
+        return_channel_chars: input.return_channel_chars ?? null,
+        floor_provenance:
+            input.floor_provenance ?? (input.init_tokens != null || input.work_tokens != null ? 'estimated' : null),
         // capsule shadow-measurement — readers ignore unknowns per audit-log-v1
         capsule_emitted: input.capsule_emitted ?? null,
         capsule_entries: input.capsule_entries ?? null,

package/src/scripts/_lib/recycle_envelope_paths.ts

@@ -0,0 +1,35 @@
+/**
+ * Recycle-envelope filesystem contract (road-to-token-economy-recycling
+ * Phase 2.2/2.3) — the ONE place the producer (`session:recycle`) and the
+ * consumer (`handoff_context_hook`) agree on where the envelope lives and
+ * when it is stale. A second copy of any of these values is the drift seam
+ * Risk 6 warns about.
+ */
+import * as path from 'node:path';
+
+/** Where `session:recycle` writes the pending envelope (gitignored runtime state). */
+export const RECYCLE_ENVELOPE_REL = path.join('agents', 'runtime', 'state', 'recycle-envelope.json');
+
+/**
+ * Where the consumer MOVES the envelope on consumption — moved, not copied,
+ * so a consumed or rejected envelope can never leak into a later session,
+ * while the last one stays inspectable for debugging.
+ */
+export const RECYCLE_CONSUMED_REL = path.join(
+    'agents',
+    'runtime',
+    'state',
+    'recycle-envelope.consumed.json',
+);
+
+/** Staleness guard — mirrors the handoff file's 48 h discipline. */
+export const RECYCLE_MAX_AGE_HOURS = 48;
+
+/**
+ * Producer-side size cap on the serialized envelope. The schema's per-field
+ * caps make a transcript-shaped envelope invalid; this cap keeps even a
+ * legal envelope inside the `handoff-context` injection budget
+ * (`src/config/hook-token-budget.json`: 8192 B for the concern) with room
+ * for the wrapper block and a co-pending handoff.
+ */
+export const RECYCLE_ENVELOPE_MAX_BYTES = 6144;

package/src/scripts/_lib/self_repair.ts

@@ -28,6 +28,7 @@
 import { createHash } from 'node:crypto';
 
 import { redact_low_impact_entry } from '../ai_council/redact_low_impact_entry.js';
+import { is_kernel_rule } from './kernel_rules.js';
 
 /** Where a record came from. */
 export type DefectSource = 'user-reported' | 'self-detected';
@@ -128,6 +129,199 @@ export function egressBlockedReason(record: DefectRecord, repoRoot?: string | nu
     return `privacy floor refused the evidence (${kinds}) — record stays local`;
 }
 
+// ── may-not-modify deny-list ───────────────────────────────────────
+
+/**
+ * Surfaces self-repair may never target with a PATCH. Detection and reporting
+ * stay untouched — for a record targeting one of these, egress degrades to
+ * report-only: an issue (or the local record) is still allowed, the
+ * pull-request path refuses with the named reason.
+ *
+ * The point is structural: the loop that fixes the agent's own defects must
+ * not be a channel through which the agent loosens the floors it is bound by.
+ * Same posture as `block_kernel_rule_writes` (tool-call-time) and the settings
+ * class-C fence (write-time), applied to the one outward vehicle this loop
+ * owns. Nothing auto-applies a patch today; this keeps that true for the
+ * denied surfaces even when the PR path is otherwise available.
+ */
+export type DeniedSurface =
+    | 'kernel-rule'
+    | 'safety-floor-rule'
+    | 'settings-class-c'
+    | 'ci-enforcement'
+    | 'self-repair-policy';
+
+export interface PatchDenial {
+    surface: DeniedSurface;
+    /** The token in the record that matched. */
+    match: string;
+}
+
+/**
+ * Characters that decorate a token but never appear inside a real path, rule
+ * id, or settings key: markdown emphasis / strikethrough, autolink angle
+ * brackets, table pipes. They are removed ANYWHERE in the token, not just at
+ * its edges, so `src/rules/**scope-control**.md` reduces like `**…**` does.
+ */
+const DECORATION_RE = /[*~<>|]/g;
+
+/**
+ * Edge punctuation a sentence leaves on a token — sentence-final `.`, a `:`
+ * label separator, list/reference brackets, and underscore emphasis (`_` is
+ * stripped at the EDGES only: it is load-bearing inside `self_repair.ts`,
+ * `hook_manifest.yaml`, and every snake_case settings key).
+ */
+const EDGE_TRIM_RE = /^[.:[\]_]+|[.:[\]_]+$/g;
+
+/**
+ * Word-ish / path-ish tokens of a record's text, punctuation-stripped.
+ *
+ * `suggested_surface` is free-text the agent writes, and this repo's prose is
+ * saturated with `**bold**` file paths — so a tokenizer that only splits on
+ * whitespace-and-quotes lets ordinary markdown emphasis smuggle a denied
+ * surface past the scan (`**src/rules/scope-control.md**` read as ALLOWED
+ * while the same path bare read as DENIED). Both the raw token and its
+ * un-decorated form are emitted, and the edge trim runs AFTER the decoration
+ * strip so an unwrapped `**.github/workflows/ci.yml**` cannot keep a leading
+ * dot in front of the anchored `github/workflows/` match.
+ */
+function denyTokens(text: string): string[] {
+    const out: string[] = [];
+    for (const raw of text.split(/[\s,;()!?"'`]+/)) {
+        if (raw.length === 0) {
+            continue;
+        }
+        for (const candidate of new Set([raw, raw.replace(DECORATION_RE, '')])) {
+            const token = candidate.replace(EDGE_TRIM_RE, '');
+            if (token.length > 0) {
+                out.push(token);
+            }
+        }
+    }
+    return out;
+}
+
+/** Basename stem (no `.md`) of a path-or-id token. */
+function stemOf(token: string): string {
+    const base = token.replace(/\\/g, '/').split('/').pop() ?? token;
+    return base.replace(/\.md$/, '');
+}
+
+/** Dotted settings-key shape — `personal.autonomy`, `tokens.rich_skills`, … */
+const DOTTED_KEY_RE = /^[a-z0-9_]+(\.[a-z0-9_]+)+$/;
+
+/**
+ * The surfaces through which enforcement is actually armed or disarmed. A
+ * workflow file is only ONE of them, and in this repo it is not even the usual
+ * one — a new gate is registered in the taskfiles the workflow calls, and a
+ * tool-call-time guard is armed in the hook manifest. Each entry, and why it
+ * arms enforcement:
+ *
+ *   - `.github/workflows/` — the CI job definitions; deleting a step removes
+ *     the gate from every PR. (The leading dot is stripped by `denyTokens`, so
+ *     the match is on the segment pair, not the dotfile spelling.)
+ *   - `Taskfile.yml` / `taskfiles/*.yml` — the task graph the workflows invoke
+ *     (`task ci`, `task ci-fast`). A gate that is not listed here does not run,
+ *     however green the workflow looks.
+ *   - `src/scripts/hook_manifest.yaml` — the concern↔slot bindings. Unbinding
+ *     a concern disarms a PreToolUse guard without touching the guard's code.
+ *   - `src/scripts/hooks/` — the guard implementations themselves
+ *     (`block_no_verify`, `block_kernel_rule_writes`, `block_config_weakening`).
+ *   - `src/scripts/check_*.ts` / `src/scripts/lint_*.ts` — the gate scripts. A
+ *     loosened threshold or a narrowed scan root disarms the gate in place,
+ *     which is exactly the "gates that scan nothing exit green" failure.
+ *
+ * Deliberately NOT the whole of `src/scripts/`: that would deny nearly every
+ * legitimate repair this loop exists to file.
+ */
+function isCiEnforcementPath(token: string): boolean {
+    const t = token.replace(/\\/g, '/');
+    if (/(^|\/)github\/workflows\//.test(t)) {
+        return true;
+    }
+    if (/(^|\/)Taskfile(\.[a-z0-9_-]+)?\.ya?ml$/i.test(t)) {
+        return true;
+    }
+    if (/(^|\/)taskfiles\//.test(t)) {
+        return true;
+    }
+    if (/(^|\/)hook_manifest\.ya?ml$/.test(t)) {
+        return true;
+    }
+    if (/(^|\/)scripts\/hooks\//.test(t)) {
+        return true;
+    }
+    return /(^|\/)scripts\/(check|lint)_[a-z0-9_]+\.ts$/.test(t);
+}
+
+/**
+ * Is this record's fix aimed at a denied surface? Scans the two fields that
+ * name what the fix should change (`suggested_surface`) and what was observed
+ * (`evidence`). A match errs toward denial on purpose — the cost of a false
+ * positive is a report instead of a patch, still egress; the cost of a false
+ * negative is a patch channel into a safety floor.
+ *
+ * The kernel set resolves from `kernel_rules.ts` — the same canonical source
+ * `block_kernel_rule_writes` uses — never a copy that can drift. Settings
+ * class-C keys are matched against `classCKeys` when the caller can supply
+ * them (parsed from `docs/contracts/settings-classes.md`); the contract file
+ * itself is denied by path regardless, so an unreadable contract narrows the
+ * dynamic check without opening the fence's own definition to patching.
+ */
+export function patchDeniedSurface(
+    record: DefectFinding,
+    opts?: { classCKeys?: ReadonlySet<string> | null },
+): PatchDenial | null {
+    const classCKeys = opts?.classCKeys ?? null;
+    for (const token of denyTokens(`${record.suggested_surface}\n${record.evidence}`)) {
+        // Checked before `ci-enforcement` so a self-repair file that also lives
+        // under an enforcement path (`src/scripts/hooks/self_repair_hook.ts`)
+        // reports the more specific surface. Either way it is denied.
+        if (/self[-_]repair/i.test(token)) {
+            return { surface: 'self-repair-policy', match: token };
+        }
+        if (isCiEnforcementPath(token)) {
+            return { surface: 'ci-enforcement', match: token };
+        }
+        if (token.includes('settings-classes.md')) {
+            return { surface: 'settings-class-c', match: token };
+        }
+        if (is_kernel_rule(token)) {
+            return { surface: 'kernel-rule', match: token };
+        }
+        if (stemOf(token).endsWith('-safety-floor')) {
+            return { surface: 'safety-floor-rule', match: token };
+        }
+        if (classCKeys !== null && DOTTED_KEY_RE.test(token)) {
+            // Exact key first, then every classified ancestor down to the root
+            // segment — a class-C key whose value is a MAP has children that
+            // never appear under the key's own name.
+            const parts = token.split('.');
+            for (let end = parts.length; end > 0; end--) {
+                if (classCKeys.has(parts.slice(0, end).join('.'))) {
+                    return { surface: 'settings-class-c', match: token };
+                }
+            }
+        }
+    }
+    return null;
+}
+
+/** The named refusal the patch/PR path reports. Null = patch path allowed. */
+export function patchDeniedReason(
+    record: DefectFinding,
+    opts?: { classCKeys?: ReadonlySet<string> | null },
+): string | null {
+    const denial = patchDeniedSurface(record, opts);
+    if (denial === null) {
+        return null;
+    }
+    return (
+        `self-repair may not patch a ${denial.surface} surface (matched: ${denial.match}) — ` +
+        'the pull-request path is refused; the record egresses report-only (issue / local record)'
+    );
+}
+
 // ── detectors ──────────────────────────────────────────────────────
 
 // An agent-directed complaint, not a complaint about the code. Deliberately