@event4u/agent-config 14.12.0 → 14.14.0

package/src/scripts/_lib/promotion_review.ts

@@ -0,0 +1,294 @@
+/**
+ * The lifecycle AFTER promotion — `road-to-harness-promotion-bridge` steps 7.6
+ * and 7.7.
+ *
+ * ## 7.6 — a promoted artefact is not immortal
+ *
+ * > *post-promotion re-evaluation with `KEEP / REVISE / MERGE / SPLIT / RETIRE`.
+ * > The master's promotion phase ends at the evidence package plus a cooldown,
+ * > so nothing reopens a promoted artefact and the lifecycle is manual-only at
+ * > exactly the point where growth accumulates.*
+ * > verify: **a promoted artefact reaching its review trigger produces one of
+ * > the five verdicts, and at least one `RETIRE` path is exercised in a
+ * > fixture.**
+ *
+ * Two halves were already in the tree and one was missing. Four of the five
+ * verdicts are E6 curator ops (`_lib/curator_ops.ts`) — `REVISE` is not — and
+ * `promoted -> retired` is already the one legal retirement edge
+ * (`_lib/candidate_record.ts:210-219`). What did not exist was the REVIEW
+ * TRIGGER: nothing decided that a promoted artefact was due, and nothing turned
+ * that into a verdict. {@link reviewPromoted} is that.
+ *
+ * **The verdict set is NOT a subset of `CURATOR_OPS`, and finding that out is
+ * part of what this step buys.** E6 argued for seven curator ops on the ground
+ * that 7.6 specifies five verdicts a four-op curator could not execute — and the
+ * shipped seven still cannot execute one of them, because `REVISE` is not among
+ * them. The relationship is pinned by a test in both directions rather than
+ * papered over with a mapping nobody chose; see {@link POST_PROMOTION_VERDICTS}.
+ *
+ * ## 7.7 — best-known-state reference on regression
+ *
+ * > *Roll back to the recorded best-known state; lineage, not endless append.*
+ * > verify: **an injected regression triggers the rollback path in a fixture.**
+ *
+ * {@link BestKnownState} is the record, {@link planRollback} is the decision.
+ * "Lineage, not endless append" is carried in the type: a rollback names the
+ * state it returns to and the state it leaves, so the history is a chain rather
+ * than a pile of snapshots nobody can order.
+ *
+ * ## This module promotes nothing
+ *
+ * It reads promoted artefacts and it can RETIRE one — the only transition it
+ * expresses is `promoted -> retired`, which `assertTransition` accepts without
+ * an approver because retirement is the direction that shrinks the estate.
+ * There is no path here that moves anything INTO `promoted`; that stays behind
+ * `_lib/promotion_capability.ts`, and `lint_promotion_paths.ts` is what proves
+ * this file did not grow one.
+ */
+import { ACCEPTED_STATE, type LifecycleState, assertTransition } from './candidate_record.js';
+import { CURATOR_OPS, type CuratorOp } from './curator_ops.js';
+
+/**
+ * The five verdicts step 7.6 names, verbatim.
+ *
+ * **Four of the five are E6 curator ops. `REVISE` is not, and that is a finding
+ * rather than a detail.** `_lib/curator_ops.ts:48-56` is `KEEP · ADD · MERGE ·
+ * REPLACE · SPLIT · RETIRE · SKIP`, and its own header argues for seven ops on
+ * the ground that *"step 7.6 of the same roadmap already specifies the verdict
+ * set KEEP / REVISE / MERGE / SPLIT / RETIRE, so a four-op curator would emit
+ * verdicts it cannot execute"*. Measured against the shipped set: `REVISE` is
+ * still a verdict the curator cannot execute — `REPLACE` is the nearest op and
+ * it is not the same thing, since `REPLACE` is 1→1 with a new artefact while
+ * `REVISE` edits the one in place and keeps its identity.
+ *
+ * The list is therefore written out rather than derived, because deriving it
+ * would require inventing the mapping the two sets do not have. What IS pinned,
+ * by `tests/scripts/promotion_review.test.ts`, is the relationship in both
+ * directions: the four shared verdicts really are curator ops, and `REVISE`
+ * really is not — so a later change that adds `REVISE` to `CURATOR_OPS`, or
+ * drops one of the four, fails a test instead of drifting.
+ */
+export const POST_PROMOTION_VERDICTS = ['KEEP', 'REVISE', 'MERGE', 'SPLIT', 'RETIRE'] as const;
+
+/** The four verdicts the curator can actually execute today. */
+export const VERDICTS_EXECUTABLE_BY_CURATOR: readonly CuratorOp[] = CURATOR_OPS.filter(
+    (op) => (POST_PROMOTION_VERDICTS as readonly string[]).includes(op),
+);
+
+export type PostPromotionVerdict = (typeof POST_PROMOTION_VERDICTS)[number];
+
+/** Why a promoted artefact came up for review. Absent means it is not due. */
+export const REVIEW_TRIGGERS = [
+    'regression',
+    'usage-floor',
+    'duplicate-detected',
+    'scope-overgrown',
+    'age',
+] as const;
+export type ReviewTrigger = (typeof REVIEW_TRIGGERS)[number];
+
+/** What a review reads. Every field is an observation, not a judgement. */
+export interface PromotedArtefactState {
+    readonly id: string;
+    readonly lifecycle: LifecycleState;
+    /** Measured effect now, in the same units as the promotion evidence's delta. */
+    readonly currentDeltaPercent: number;
+    /** The delta recorded at promotion. The regression test is `current < promoted`. */
+    readonly promotedDeltaPercent: number;
+    /** How many times the artefact was actually reached since promotion. */
+    readonly invocations: number;
+    /** Ids of promoted artefacts whose text this one now duplicates. */
+    readonly duplicates: readonly string[];
+    /** Distinct responsibilities the artefact has accumulated. */
+    readonly responsibilities: number;
+    readonly daysSincePromotion: number;
+}
+
+export class NotPromotedError extends Error {
+    constructor(id: string, lifecycle: LifecycleState) {
+        super(
+            `'${id}' is '${lifecycle}', not '${ACCEPTED_STATE}' — post-promotion review acts on a ` +
+                'PROMOTED artefact. A candidate that never landed is rejected, not retired, and ' +
+                'reviewing one here would report a lifecycle event that did not happen.',
+        );
+        this.name = 'NotPromotedError';
+    }
+}
+
+export interface ReviewOutcome {
+    readonly id: string;
+    readonly trigger: ReviewTrigger;
+    readonly verdict: PostPromotionVerdict;
+    readonly reason: string;
+}
+
+/** The floors the review reads. Stated defaults; each carries its own revisit-if. */
+export const REVIEW_THRESHOLDS = {
+    /** Below this many invocations the artefact is not earning its place. `revisit-if` a
+     *  legitimately rare artefact is retired for being rare. */
+    usageFloor: 1,
+    /** Distinct responsibilities above which the artefact should be SPLIT. `revisit-if` a
+     *  cohesive artefact with several facets is split for having them. */
+    responsibilityCeiling: 2,
+    /** Days after which an unreviewed artefact is due. `revisit-if` the cadence is noise. */
+    ageDays: 180,
+} as const;
+
+/**
+ * Is this artefact due for review, and why? `null` means not due.
+ *
+ * Order is precedence: a regression outranks a usage question, which outranks a
+ * duplicate, which outranks overgrowth, which outranks mere age. Without a fixed
+ * order two triggers firing at once would make the verdict depend on evaluation
+ * order, which is how a review becomes irreproducible.
+ */
+export function reviewTriggerFor(state: PromotedArtefactState): ReviewTrigger | null {
+    if (state.currentDeltaPercent < state.promotedDeltaPercent) return 'regression';
+    if (state.invocations < REVIEW_THRESHOLDS.usageFloor) return 'usage-floor';
+    if (state.duplicates.length > 0) return 'duplicate-detected';
+    if (state.responsibilities > REVIEW_THRESHOLDS.responsibilityCeiling) return 'scope-overgrown';
+    if (state.daysSincePromotion >= REVIEW_THRESHOLDS.ageDays) return 'age';
+    return null;
+}
+
+/**
+ * Produce exactly ONE of the five verdicts for a promoted artefact that reached
+ * its review trigger.
+ *
+ * @throws {NotPromotedError} when the artefact is not promoted.
+ */
+export function reviewPromoted(state: PromotedArtefactState, trigger: ReviewTrigger): ReviewOutcome {
+    if (state.lifecycle !== ACCEPTED_STATE) {
+        throw new NotPromotedError(state.id, state.lifecycle);
+    }
+    const outcome = (verdict: PostPromotionVerdict, reason: string): ReviewOutcome => ({
+        id: state.id,
+        trigger,
+        verdict,
+        reason,
+    });
+    switch (trigger) {
+        case 'regression':
+            // A measured effect that fell BELOW zero is not worth revising; it is
+            // now costing what it was promoted to save.
+            return state.currentDeltaPercent <= 0
+                ? outcome('RETIRE', `effect fell to ${String(state.currentDeltaPercent)} pp — it no longer earns its place`)
+                : outcome(
+                      'REVISE',
+                      `effect fell ${String(state.promotedDeltaPercent)} -> ${String(state.currentDeltaPercent)} pp ` +
+                          'but is still positive',
+                  );
+        case 'usage-floor':
+            return outcome('RETIRE', `reached ${String(state.invocations)} time(s) since promotion`);
+        case 'duplicate-detected':
+            return outcome('MERGE', `now duplicates ${state.duplicates.join(', ')}`);
+        case 'scope-overgrown':
+            return outcome('SPLIT', `carries ${String(state.responsibilities)} distinct responsibilities`);
+        case 'age':
+            return outcome('KEEP', `${String(state.daysSincePromotion)} days since promotion, effect held`);
+    }
+}
+
+/**
+ * Execute the RETIRE verdict.
+ *
+ * Routes through `assertTransition`, so the ONE legal retirement edge is the one
+ * this takes and a caller cannot retire something that never landed. Returns the
+ * next lifecycle state rather than writing anything — nothing in this module
+ * touches the filesystem.
+ *
+ * @throws {LifecycleTransitionError} from `assertTransition`.
+ */
+export function retirePromoted(state: PromotedArtefactState): LifecycleState {
+    assertTransition(state.lifecycle, 'retired');
+    return 'retired';
+}
+
+// --- 7.7 — best-known state and rollback ------------------------------------
+
+/** A recorded good state, and the state it came from. Lineage, not endless append. */
+export interface BestKnownState {
+    readonly artefactId: string;
+    /** The revision or bundle identifier this state is recoverable from. */
+    readonly reference: string;
+    readonly deltaPercent: number;
+    /** The best-known state this one replaced. `null` only for the first. */
+    readonly supersedes: string | null;
+    readonly recordedAt: string;
+}
+
+export interface RollbackPlan {
+    readonly artefactId: string;
+    readonly from: string;
+    readonly to: string;
+    readonly reason: string;
+    /** Oldest first. The chain that makes this a lineage rather than a pile. */
+    readonly lineage: readonly string[];
+}
+
+export class NoBestKnownStateError extends Error {
+    constructor(artefactId: string) {
+        super(
+            `'${artefactId}' regressed and has no recorded best-known state to return to. A rollback ` +
+                'target is recorded at promotion time, not reconstructed after the regression — by ' +
+                'then the state that worked is exactly what is missing.',
+        );
+        this.name = 'NoBestKnownStateError';
+    }
+}
+
+/**
+ * Walk the `supersedes` chain, oldest first.
+ *
+ * Cycle-guarded: a chain that points at itself is a corrupted lineage, and
+ * following it forever would hang the caller rather than report the corruption.
+ */
+export function lineageOf(head: BestKnownState, all: readonly BestKnownState[]): string[] {
+    const byRef = new Map(all.map((s) => [s.reference, s]));
+    const chain: string[] = [];
+    const seen = new Set<string>();
+    let cursor: BestKnownState | undefined = head;
+    while (cursor !== undefined && !seen.has(cursor.reference)) {
+        seen.add(cursor.reference);
+        chain.push(cursor.reference);
+        cursor = cursor.supersedes === null ? undefined : byRef.get(cursor.supersedes);
+    }
+    return chain.reverse();
+}
+
+/**
+ * Plan a rollback when the current state regressed against the best known one.
+ *
+ * `null` when there is no regression — the caller does not have to know the
+ * comparison, and a rollback that fires on an improvement is worse than none.
+ *
+ * @throws {NoBestKnownStateError} when a regression has nowhere to return to.
+ */
+export function planRollback(
+    artefactId: string,
+    currentReference: string,
+    currentDeltaPercent: number,
+    history: readonly BestKnownState[],
+): RollbackPlan | null {
+    const mine = history.filter((s) => s.artefactId === artefactId);
+    const best = mine.reduce<BestKnownState | null>(
+        (acc, s) => (acc === null || s.deltaPercent > acc.deltaPercent ? s : acc),
+        null,
+    );
+    if (best === null) {
+        if (currentDeltaPercent < 0) throw new NoBestKnownStateError(artefactId);
+        return null;
+    }
+    if (currentDeltaPercent >= best.deltaPercent) {
+        return null;
+    }
+    return {
+        artefactId,
+        from: currentReference,
+        to: best.reference,
+        reason:
+            `regressed ${String(best.deltaPercent)} -> ${String(currentDeltaPercent)} pp against the ` +
+            `best-known state '${best.reference}'`,
+        lineage: lineageOf(best, mine),
+    };
+}

package/src/scripts/_lib/prompt_shape.ts

@@ -86,3 +86,95 @@ export function humanAuthoredLead(text: string): string {
   }
   return kept.join("\n");
 }
+
+/** A line that is nothing but an opening tag, with the tag name captured. */
+const REGION_OPEN = /^\s*<([A-Za-z][\w-]*)>\s*$/;
+
+/**
+ * The host's own framing of an injected region — the sentence it writes ABOUT
+ * the block, not a sentence the user typed.
+ *
+ * Named literally, for the same reason `isSyntheticPrompt` names wrapper tags:
+ * this is host furniture, and furniture is identified by what it says about
+ * itself. It is deliberately NOT a language rule — the clauses describe the
+ * region's provenance and its data status, and a user who types one is quoting
+ * the host, which is exactly the case that should be dropped too.
+ */
+const REGION_NOTE =
+  /\b(content (above|below) is from|treat (it|this|that|the (content|text|above|following)) as data)\b/i;
+
+/**
+ * Remove host-injected wrapper regions — `<launch-selected-element>` and
+ * friends — leaving the text the human actually typed around them.
+ *
+ * MEASURED, from a 14.13.0 field report (2026-09-01) reproduced against this
+ * source. `DOCUMENT_HEAD` matches a bare `<tag>` line, and Claude Code PREPENDS
+ * exactly that when the user picks a DOM element in the browser pane. So
+ * `humanAuthoredLead` broke at line zero and returned `""` for every such
+ * prompt — the lead-first isolation was not degraded, it was OFF — and the
+ * whole-text fallback then scored ~4 KB of class-heavy markup plus the host's
+ * own advisory line. Four consecutive German turns pinned English, and the
+ * turn-end gate refused each one.
+ *
+ * Two things had to move, and both are visible in the reproduction:
+ *
+ *   1. A bare `<tag>` line that HAS a matching close is the START of a region
+ *      to skip, never the end of the human lead. That is this function.
+ *   2. It runs BEFORE `instructionText`. The block's indented lines arm that
+ *      filter's paste-state machine, and where no blank line separates the
+ *      block from the user's sentence, the sentence itself was deleted — the
+ *      German markers did not merely lose the count, they reached zero.
+ *
+ * Conservative by construction, in three ways. An UNBALANCED bare tag is left
+ * in place, so a pasted document opening with one still terminates the lead
+ * exactly as before. A prompt with no balanced region is returned untouched,
+ * so nothing outside this shape reclassifies. And the framing sentence is
+ * dropped LINE BY LINE against `REGION_NOTE` rather than as a paragraph: in the
+ * reported shape the advisory and the user's sentence share one unbroken run,
+ * so dropping the run would have taken the sentence with it.
+ *
+ * Not `isSyntheticPrompt`: that answers "is this whole turn machine-written",
+ * and these turns are not — a human sentence follows the block. The wrapper is
+ * removed; the turn is kept.
+ *
+ * Nested same-name regions resolve to the FIRST matching close tag. Host
+ * wrappers do not nest by name, and stopping early keeps more human text than
+ * scanning past the wrong close would.
+ */
+export function stripInjectedRegions(text: string): string {
+  const lines = text.split("\n");
+  const kept: string[] = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    const open = REGION_OPEN.exec(line);
+    if (open === null) {
+      kept.push(line);
+      continue;
+    }
+    // The tag name comes from `[A-Za-z][\w-]*`, so it carries no regex
+    // metacharacter and needs no escaping.
+    const close = new RegExp(`^\\s*</${open[1] ?? ""}>\\s*$`);
+    let end = -1;
+    for (let j = i + 1; j < lines.length; j++) {
+      if (close.test(lines[j] ?? "")) {
+        end = j;
+        break;
+      }
+    }
+    if (end === -1) {
+      kept.push(line);
+      continue;
+    }
+    if (kept.length > 0 && REGION_NOTE.test(kept[kept.length - 1] ?? "")) {
+      kept.pop();
+    }
+    i = end;
+    while (i + 1 < lines.length && (lines[i + 1] ?? "").trim() !== "") {
+      if (!REGION_NOTE.test(lines[i + 1] ?? "")) {
+        break;
+      }
+      i++;
+    }
+  }
+  return kept.join("\n");
+}

package/src/scripts/_lib/regression_neighbourhood.ts

@@ -0,0 +1,259 @@
+/**
+ * Regression selection from the affected neighbourhood.
+ *
+ * `road-to-governed-harness-evolution` Phase 4, step 4.6.
+ *
+ * > *Use the code graph to choose which regressions to run for a given
+ * > candidate. The master adopted the attack "local improvement, global
+ * > regression" as a risk with no mechanism behind it. This is distinct from
+ * > the killed curriculum generator — it selects existing regressions, it does
+ * > not author tasks.*
+ * > verify: **a candidate touching one surface runs the regressions its
+ * > neighbourhood names, and a fixture proves a neighbour regression is
+ * > caught.**
+ *
+ * ## Which graph, and why it is not the one the step names
+ *
+ * The step says "the code graph". This tree has two graph surfaces and only one
+ * of them resolves here, so the substitution is STATED rather than hidden.
+ *
+ *   · `agent-config code-graph` — the native code-graph engine (ADR-124). It
+ *     ships `hooks.code_graph.enabled: false`
+ *     (`src/config/agent-settings.template.yml:1373-1374`), and
+ *     `agent-config code-graph detect` in this checkout answers
+ *     `no code-graph source detected`. There is no index to select against.
+ *   · `src/scripts/discovery_graph.ts` — this suite's OWN artefact relation
+ *     graph, five typed edges extracted from the discovery manifest's
+ *     structured fields, with an `affected` BFS already implemented and
+ *     answering. That is the surface this module builds on.
+ *
+ * The substitution changes what a "neighbourhood" means, and the difference is
+ * worth naming: the native engine would neighbour a candidate by SYMBOL
+ * relations, while `discovery_graph` neighbours it by ARTEFACT relations
+ * (`supersedes`, `routes_to`, `references_adr`, pack and workspace membership).
+ * For this roadmap's candidates — rules, skills, guidelines — the artefact
+ * graph is the one that carries the coupling a rewrite can break. For a
+ * candidate that edits a `.ts` symbol, it is the weaker surface, and this
+ * module says so through {@link selectionVerdict}: a touched surface absent
+ * from the graph is REFUSED, never silently neighboured with the empty set.
+ *
+ * ## Why an unresolved surface refuses instead of selecting nothing
+ *
+ * A selector whose neighbourhood lookup fails and then runs zero regressions
+ * reports a clean sheet, which is indistinguishable from a candidate that
+ * genuinely touches nothing coupled. That is exactly the "local improvement,
+ * global regression" hole the step exists to close, arriving through the
+ * selector rather than around it. So an unresolved touched surface is a
+ * refusal reason, and there is no option flag that relaxes it.
+ *
+ * ## Selects, never authors — carried by object identity (K9)
+ *
+ * K9 killed the curriculum generator. This module has no code path that
+ * constructs a {@link RegressionSpec}: every selected entry is an element of
+ * the registry the caller supplied, returned by reference, so
+ * `registry.includes(selected.spec)` holds by identity for every selection.
+ * A test asserts that identity rather than an id match, because an id match
+ * would also be satisfied by a synthesized spec carrying a copied id.
+ */
+import { affected, isSyntheticNode, type Graph } from '../discovery_graph.js';
+
+/**
+ * An EXISTING regression, as the registry holds it. `guards` names the artefact
+ * ids whose breakage this regression would detect.
+ *
+ * Nothing in this module builds one of these. It is the caller's registry entry,
+ * passed through by reference.
+ */
+export interface RegressionSpec {
+    id: string;
+    guards: readonly string[];
+}
+
+/** A candidate under evaluation, reduced to the surfaces it touches. */
+export interface Candidate {
+    id: string;
+    /** Artefact ids the candidate's diff touches. */
+    touches: readonly string[];
+}
+
+/** Why a node is in the neighbourhood: the candidate touched it, or a relation reached it. */
+export type NeighbourReason = 'touched' | 'neighbour';
+
+export interface NeighbourhoodNode {
+    node: string;
+    reason: NeighbourReason;
+    /** Hop distance from the nearest touched surface. `0` for a touched surface. */
+    depth: number;
+    /** The relation that reached it, or `''` for a touched surface. */
+    via: string;
+    /** True for `pack:` / `workspace:` container nodes the graph invents. */
+    synthetic: boolean;
+}
+
+export interface Selection {
+    spec: RegressionSpec;
+    /** The neighbourhood nodes this regression guards, sorted. */
+    matched: readonly string[];
+    /** `touched` when it guards a surface the candidate edited, else `neighbour`. */
+    reason: NeighbourReason;
+}
+
+export interface NeighbourhoodReport {
+    candidate_id: string;
+    neighbourhood: readonly NeighbourhoodNode[];
+    /** Touched surfaces that are not nodes in the graph. A refusal reason, not a warning. */
+    unresolved: readonly string[];
+    selected: readonly Selection[];
+    /** Registry entries whose guards intersect nothing in the neighbourhood. */
+    skipped: readonly string[];
+    /**
+     * Literal 0. This module selects from a registry; a non-zero value here
+     * would mean it authored a task, which is K9.
+     */
+    authored: 0;
+}
+
+/**
+ * Hops walked out from each touched surface.
+ *
+ * A STATED default, not a measured optimum. Two is the smallest depth that
+ * reaches a `routes_to` target AND that target's own container membership, so a
+ * rule edit neighbours the skill it routes to and the pack that skill sits in.
+ * `revisit-if` a run selects a regression nobody can explain from the diff, or
+ * a real breakage lands outside the two-hop set.
+ */
+export const DEFAULT_NEIGHBOURHOOD_DEPTH = 2;
+
+/**
+ * The neighbourhood of a candidate: every touched surface, plus everything the
+ * relation graph reaches from it within `depth` hops.
+ *
+ * Deterministic — nodes are emitted at their shallowest depth and sorted by
+ * `(depth, node)`, so two runs over the same graph produce byte-identical
+ * reports.
+ */
+export function neighbourhood(
+    graph: Graph,
+    candidate: Candidate,
+    depth: number = DEFAULT_NEIGHBOURHOOD_DEPTH,
+): NeighbourhoodNode[] {
+    const best = new Map<string, NeighbourhoodNode>();
+    for (const t of candidate.touches) {
+        best.set(t, { node: t, reason: 'touched', depth: 0, via: '', synthetic: isSyntheticNode(t) });
+    }
+    for (const t of candidate.touches) {
+        for (const hit of affected(graph, t, depth)) {
+            const prior = best.get(hit.node);
+            if (prior !== undefined && prior.depth <= hit.depth) continue;
+            best.set(hit.node, {
+                node: hit.node,
+                reason: 'neighbour',
+                depth: hit.depth,
+                via: hit.via,
+                synthetic: isSyntheticNode(hit.node),
+            });
+        }
+    }
+    return [...best.values()].sort((a, b) => a.depth - b.depth || a.node.localeCompare(b.node));
+}
+
+/** Touched surfaces the graph does not know about. */
+export function unresolvedSurfaces(graph: Graph, candidate: Candidate): string[] {
+    const known = new Set(graph.nodes);
+    return candidate.touches.filter((t) => !known.has(t)).sort((a, b) => a.localeCompare(b));
+}
+
+/**
+ * Select the registry entries whose guards intersect the candidate's
+ * neighbourhood.
+ *
+ * The returned `spec` values are the caller's registry objects, by reference.
+ */
+export function selectRegressions(
+    graph: Graph,
+    candidate: Candidate,
+    registry: readonly RegressionSpec[],
+    depth: number = DEFAULT_NEIGHBOURHOOD_DEPTH,
+): NeighbourhoodReport {
+    const hood = neighbourhood(graph, candidate, depth);
+    const reasonOf = new Map<string, NeighbourReason>(hood.map((n) => [n.node, n.reason]));
+    const selected: Selection[] = [];
+    const skipped: string[] = [];
+    for (const spec of registry) {
+        const matched = spec.guards.filter((g) => reasonOf.has(g)).sort((a, b) => a.localeCompare(b));
+        if (matched.length === 0) {
+            skipped.push(spec.id);
+            continue;
+        }
+        const reason: NeighbourReason = matched.some((m) => reasonOf.get(m) === 'touched')
+            ? 'touched'
+            : 'neighbour';
+        selected.push({ spec, matched, reason });
+    }
+    return {
+        candidate_id: candidate.id,
+        neighbourhood: hood,
+        unresolved: unresolvedSurfaces(graph, candidate),
+        selected: selected.sort((a, b) => a.spec.id.localeCompare(b.spec.id)),
+        skipped: skipped.sort((a, b) => a.localeCompare(b)),
+        authored: 0,
+    };
+}
+
+/**
+ * `null` when the selection may be trusted, otherwise every reason it may not.
+ *
+ * Fail-closed by construction: no option object relaxes a reason, so a caller
+ * who wants to proceed on an unresolved surface has to delete this call — which
+ * is visible in a diff — rather than pass a flag, which is not.
+ */
+export function selectionVerdict(report: NeighbourhoodReport): readonly string[] | null {
+    const reasons: string[] = [];
+    if (report.unresolved.length > 0) {
+        reasons.push(
+            `touched surfaces absent from the relation graph: ${report.unresolved.join(', ')} — ` +
+                'their neighbourhood is unknown, and an unknown neighbourhood is not an empty one',
+        );
+    }
+    if (report.neighbourhood.length === 0) {
+        reasons.push('empty neighbourhood — the candidate touches nothing the graph knows');
+    }
+    return reasons.length === 0 ? null : reasons;
+}
+
+/** One regression's observed result on a candidate. */
+export interface RegressionOutcome {
+    regression_id: string;
+    passed: boolean;
+}
+
+export interface CatchReport {
+    /** Selected regressions that FAILED — the breakages this selection caught. */
+    caught: readonly string[];
+    /**
+     * Regressions that failed but were never selected, so their failure was
+     * never observed. Present so a miss is countable rather than invisible.
+     */
+    missed: readonly string[];
+}
+
+/**
+ * Split observed regression outcomes by whether the selection actually ran them.
+ *
+ * `outcomes` is the full registry's result — what WOULD have been observed had
+ * everything run. `caught` is the part the neighbourhood selection reached;
+ * `missed` is the part it did not. A selector that narrows too far shows up
+ * here as a non-empty `missed`, which is what makes the fixture in
+ * `tests/scripts/regression_neighbourhood.test.ts` falsifiable.
+ */
+export function catchReport(
+    report: NeighbourhoodReport,
+    outcomes: readonly RegressionOutcome[],
+): CatchReport {
+    const ran = new Set(report.selected.map((s) => s.spec.id));
+    const failed = outcomes.filter((o) => !o.passed).map((o) => o.regression_id);
+    return {
+        caught: failed.filter((id) => ran.has(id)).sort((a, b) => a.localeCompare(b)),
+        missed: failed.filter((id) => !ran.has(id)).sort((a, b) => a.localeCompare(b)),
+    };
+}