@event4u/agent-config 14.22.0 → 15.0.0

package/src/scripts/_lib/ratification_artifact.ts

@@ -0,0 +1,278 @@
+/**
+ * The ratification artifact — ADR-268 § 4's control, in one reader.
+ *
+ * ADR-268 § 4 permits an agent to edit kernel rules, governance hooks and
+ * authority schemas inside an authorised mission, and forbids it to ratify its
+ * own increase in power:
+ *
+ * ```
+ * AN AGENT MAY MODIFY ITS CONSTITUTION. IT MAY NOT RATIFY ITS OWN INCREASE IN POWER.
+ * THE PARTY GAINING THE AUTHORITY IS NEVER THE PARTY RECORDING THE RATIFICATION.
+ * PROVIDER DIVERSITY IS REQUIRED WHERE TWO PROVIDERS ARE CONFIGURED.
+ * ```
+ *
+ * That sentence is the whole reason this module exists as a pure reader with
+ * no filesystem and no network: the gate that reds a PR
+ * (`check_kernel_edit_ratified`) and the tests that prove it reds must decide
+ * from the same code, or the fixture proves a second implementation rather
+ * than the shipped one.
+ *
+ * Why `reviewed_by` is checked against BOTH producer fields.
+ * `road-to-typed-grants-that-persist` Phase 5.1 names one fixture — an
+ * artifact whose `proposed_by` equals its `reviewed_by` is rejected. The Iron
+ * Law above is broader than that fixture: the party gaining the authority is
+ * the party that proposed the expansion AND the party that implemented it, and
+ * an artifact reviewed by its own implementer is the same defect wearing the
+ * other field's name. Both are rejected, and this paragraph is why the code is
+ * wider than the step that asked for it.
+ *
+ * What this module does NOT decide: whether a diff is authority-EXPANDING.
+ * That is a judgement over rule prose, not a property of the artifact, and
+ * ADR-268 § 4 makes the artifact required for the expanding case only.
+ * `check_kernel_edit_ratified` requires the artifact for every kernel-rule
+ * diff instead — a strictly stronger and decidable rule — and says so in its
+ * own header rather than pretending to classify.
+ */
+
+import { readAdrFrontmatter, type AdrFrontmatter } from './adr_frontmatter.js';
+
+/** Where a ratification artifact lives. One directory, so the gate can find it. */
+export const RATIFICATION_DIR = 'agents/evidence/ratifications';
+
+/**
+ * The verdict vocabulary — closed, because an open one is a free-text field
+ * that always reads as approval to a grep.
+ */
+export const RATIFICATION_VERDICTS = [
+    'ratified',
+    'confirmed-non-expanding',
+    'refused',
+    'non-convergent',
+] as const;
+export type RatificationVerdict = (typeof RATIFICATION_VERDICTS)[number];
+
+/**
+ * The two verdicts that let a diff land.
+ *
+ * `confirmed-non-expanding` exists because the gate demands an artifact for
+ * EVERY kernel and governance-hook diff, including a typo fix. Calling that a
+ * ratification of an authority expansion would be false, and a vocabulary that
+ * forces a false label is a vocabulary people route around. Adopted from the
+ * round-1 review, which named the pressure this relieves.
+ */
+export const PASSING_VERDICTS: ReadonlySet<string> = new Set([
+    'ratified',
+    'confirmed-non-expanding',
+]);
+
+/** The six fields Phase 5.1 names, all required. */
+export const RATIFICATION_FIELDS = [
+    'proposed_by',
+    'implemented_by',
+    'reviewed_by',
+    'providers',
+    'verdict',
+    'effective_after',
+] as const;
+
+export interface RatificationArtifact {
+    proposed_by: string;
+    implemented_by: string;
+    reviewed_by: string;
+    /** Provider ids consulted, in source order. Diversity is counted over this. */
+    providers: string[];
+    verdict: RatificationVerdict;
+    /** `merge`, or an ISO-8601 instant. Never a bare "later". */
+    effective_after: string;
+}
+
+export interface RatificationProblem {
+    /** Stable code, so a test asserts the reason rather than the wording. */
+    code:
+        | 'no-frontmatter'
+        | 'missing-field'
+        | 'unknown-verdict'
+        | 'self-ratified'
+        | 'no-providers'
+        | 'diversity-required'
+        | 'diversity-unverifiable'
+        | 'bad-effective-after';
+    message: string;
+}
+
+export interface RatificationReading {
+    artifact: RatificationArtifact | null;
+    problems: RatificationProblem[];
+}
+
+/** `merge`, or an ISO-8601 instant with a timezone. */
+const EFFECTIVE_AFTER_RE =
+    /^(merge|\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2}))$/;
+
+function scalarOf(fm: AdrFrontmatter, key: string): string | null {
+    const raw = fm.scalars[key];
+    if (typeof raw !== 'string') {
+        return null;
+    }
+    const trimmed = raw.trim();
+    return trimmed === '' ? null : trimmed;
+}
+
+/**
+ * Read `providers` in either shape the frontmatter parser can produce — a YAML
+ * list (nested) or an inline `[a, b]` scalar. Accepting both is not laxity:
+ * the ADR frontmatter corpus already carries both shapes for `basis`, and a
+ * reader that took only one would reject a correctly-authored artifact.
+ */
+export function readProviders(fm: AdrFrontmatter): string[] {
+    const nested = fm.nested['providers'];
+    if (Array.isArray(nested)) {
+        return nested.map((p) => String(p).trim()).filter((p) => p !== '');
+    }
+    const scalar = scalarOf(fm, 'providers');
+    if (scalar === null) {
+        return [];
+    }
+    return scalar
+        .replace(/^\[|\]$/g, '')
+        .split(',')
+        .map((p) => p.trim().replace(/^["']|["']$/g, ''))
+        .filter((p) => p !== '');
+}
+
+/**
+ * Validate one artifact's text.
+ *
+ * `configuredProviders` is the count `agent-config council:status` reports.
+ * Pass `null` when it could not be established — the diversity rule then does
+ * not fire, and the caller says so, because an unmeasured count is not
+ * evidence that diversity was unavailable.
+ */
+export function readRatification(
+    text: string,
+    configuredProviders: number | null,
+): RatificationReading {
+    const problems: RatificationProblem[] = [];
+    const fm = readAdrFrontmatter(text);
+    if (fm === null) {
+        return {
+            artifact: null,
+            problems: [{ code: 'no-frontmatter', message: 'no YAML frontmatter block' }],
+        };
+    }
+
+    const providers = readProviders(fm);
+    const values: Record<string, string | null> = {};
+    for (const field of RATIFICATION_FIELDS) {
+        if (field === 'providers') {
+            continue;
+        }
+        values[field] = scalarOf(fm, field);
+        if (values[field] === null) {
+            problems.push({ code: 'missing-field', message: `missing or empty \`${field}:\`` });
+        }
+    }
+    if (providers.length === 0) {
+        problems.push({ code: 'no-providers', message: 'missing or empty `providers:`' });
+    }
+
+    const verdict = values['verdict'] ?? null;
+    if (verdict !== null && !(RATIFICATION_VERDICTS as readonly string[]).includes(verdict)) {
+        problems.push({
+            code: 'unknown-verdict',
+            message: `verdict \`${verdict}\` is not one of ${RATIFICATION_VERDICTS.join(', ')}`,
+        });
+    }
+
+    const effective = values['effective_after'] ?? null;
+    if (effective !== null && !EFFECTIVE_AFTER_RE.test(effective)) {
+        problems.push({
+            code: 'bad-effective-after',
+            message: `effective_after \`${effective}\` is neither \`merge\` nor an ISO-8601 instant`,
+        });
+    }
+
+    // The Iron Law. Checked against both producer fields — see the header.
+    const reviewer = values['reviewed_by'];
+    if (reviewer !== null) {
+        for (const producerField of ['proposed_by', 'implemented_by'] as const) {
+            const producer = values[producerField];
+            if (producer !== null && producer === reviewer) {
+                problems.push({
+                    code: 'self-ratified',
+                    message:
+                        `\`${producerField}\` equals \`reviewed_by\` (${reviewer}) — ` +
+                        'the party gaining the authority may not record the ratification (ADR-268 section 4)',
+                });
+            }
+        }
+    }
+
+    // Diversity, against the REQUIRED count.
+    //
+    // Round 1 refused the previous shape: the count came from the user-global
+    // council config, which is absent on a CI runner, so the rule silently did
+    // not fire there. `null` now means the required count could not be
+    // established, and that is a REFUSAL rather than a skip — a control that
+    // passes when it cannot measure is advisory.
+    if (configuredProviders === null) {
+        problems.push({
+            code: 'diversity-unverifiable',
+            message:
+                'the required provider count could not be read, so diversity is unverifiable — ' +
+                'a control that cannot measure fails closed (src/config/ratification-policy.json)',
+        });
+    } else if (configuredProviders >= 2) {
+        const distinct = new Set(providers);
+        if (distinct.size < configuredProviders) {
+            problems.push({
+                code: 'diversity-required',
+                message:
+                    `${configuredProviders} distinct providers are required; ` +
+                    `the artifact names ${distinct.size} (${providers.join(', ') || 'none'})`,
+            });
+        }
+    }
+
+    if (problems.length > 0) {
+        return { artifact: null, problems };
+    }
+
+    return {
+        artifact: {
+            proposed_by: values['proposed_by'] as string,
+            implemented_by: values['implemented_by'] as string,
+            reviewed_by: reviewer as string,
+            providers,
+            verdict: verdict as RatificationVerdict,
+            effective_after: effective as string,
+        },
+        problems: [],
+    };
+}
+
+/** True when the artifact parses and carries a verdict that lets the diff land. */
+export function isRatified(reading: RatificationReading): boolean {
+    return reading.artifact !== null && PASSING_VERDICTS.has(reading.artifact.verdict);
+}
+
+/**
+ * The required distinct-provider count, from the repository's own policy file.
+ *
+ * Returns `null` when the file is missing or unparseable, and the caller turns
+ * that into a refusal — never a skip. Reading the policy from the repository
+ * rather than from the user-global council config is the round-1 fix: a runner
+ * has the repository and does not have the operator's home directory.
+ */
+export function readRequiredProviders(policyText: string | null): number | null {
+    if (policyText === null) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(policyText) as { required_providers?: unknown };
+        const n = parsed.required_providers;
+        return typeof n === 'number' && Number.isInteger(n) && n >= 1 ? n : null;
+    } catch {
+        return null;
+    }
+}

package/src/scripts/_lib/recycle_envelope_paths.ts

@@ -73,11 +73,49 @@ export function recycle_envelope_rel(session_id: string | null | undefined): str
     return _sessionKeyed(session_id, RECYCLE_ENVELOPE_REL, 'recycle-envelope', '.json');
 }
 
+/**
+ * THE KEYING CONTRACT, in one place because its absence is what allowed the
+ * 2026-09-09 defect: the record is keyed by the **producing session** — the one
+ * that ran `session:recycle` — and it is READ by the **consuming session**,
+ * which is a different session with a different id. Those two facts were each
+ * true in their own module and were never written down together, so the
+ * producer and the consumer agreed on a PATH and disagreed about whose id
+ * filled it. {@link resolveContinuityRecord} is where that is now reconciled:
+ * it admits the unique record that is NOT the reader's own.
+ */
+
 /** Consumed sibling of {@link recycle_envelope_rel}, same keying. */
 export function recycle_consumed_rel(session_id: string | null | undefined): string {
     return _sessionKeyed(session_id, RECYCLE_CONSUMED_REL, 'recycle-envelope', '.consumed.json');
 }
 
+/**
+ * Where an UNUSABLE resident record is moved aside so the slot can be
+ * published into — never deleted.
+ *
+ * `road-to-continuity-writer-activation` step 1.1. The reader already discards
+ * a malformed, schema-invalid or expired record loudly
+ * ({@link resolveContinuityRecord}'s callers), so nothing is lost by taking it
+ * out of the authoritative name. What WOULD be lost by `unlink` is the evidence
+ * of why a resume did not happen, and that is the only artefact anyone
+ * debugging a missed resume has. Quarantine is one file per session and is
+ * pruned by the same janitor as the rest of `agents/runtime/state/`.
+ *
+ * Deliberately NOT the consumed name: `.consumed.json` is a claim that a
+ * successor read the record, and `predecessorTracePresent` reads exactly that
+ * file to corroborate a lineage. Writing a never-consumed record there would
+ * manufacture a predecessor trace, which is the one thing that check exists to
+ * refuse.
+ */
+export function recycle_quarantine_rel(session_id: string | null | undefined): string {
+    return _sessionKeyed(
+        session_id,
+        path.join(_STATE_REL, 'recycle-envelope.quarantined.json'),
+        'recycle-envelope',
+        '.quarantined.json',
+    );
+}
+
 /**
  * Shared builder. Containment is asserted locally rather than trusted from
  * `safe_stem`: a guarantee living in another module's implementation is one
@@ -133,44 +171,94 @@ export interface ContinuityResolution {
 /**
  * Which record THIS session may read.
  *
- * Three cases, and the third is the one the per-session key exists for:
+ * **A resume reads the PREDECESSOR's record, and this function used to look for
+ * the reader's own.** Corrected 2026-09-09 after measuring it: the producer
+ * writes under the PRODUCING session's id and the consumer arrives with its
+ * OWN, so the two never coincided and every successor was told `absent`. The
+ * mechanism resolved only for a caller with no session id at all — the one
+ * shape no host produces, and the only shape the 19 pre-existing consumer tests
+ * exercised. `road-to-a-recycle-envelope-that-is-consumed` carries the
+ * five-fixture table; AI council 2026-09-09, 2/2, chose the rule below.
+ *
+ * Four cases, and the second is the resume:
+ *
+ * 1. **Own record.** NEVER read. A session re-reading its own state is a loop,
+ *    not a resume, and a second `session_start` for one session (resume, host
+ *    reconnect) made it reachable. Excluded by construction here rather than
+ *    guarded downstream.
+ * 2. **Exactly one record that is not the reader's own.** Read it. That is the
+ *    predecessor.
+ * 3. **Several such records.** START CLEAN and say so — the existing refusal,
+ *    unchanged and now reachable from both branches. Picking the newest is
+ *    precisely the recency resolution the no-index rule below forbids.
+ * 4. **None.** `absent`.
  *
- * 1. **Own id resolves.** Read the record keyed to it, and nothing else. A peer
- *    session's record is not a candidate at any point, so "neither observes the
- *    other's" holds by construction rather than by a comparison that could be
- *    skipped.
- * 2. **No id, one candidate.** Read it. A single record in a checkout with no
- *    resolvable identity is the pre-key situation and is unchanged.
- * 3. **No id, several candidates.** START CLEAN and say so. Picking the newest
- *    is precisely the recency resolution the no-index rule forbids: it would
- *    hand this session a stranger's state and look like a successful resume.
+ * **Why this is not recency, stated because the rule it must not become is one
+ * line away:** nothing is sorted and nothing is compared by time. Uniqueness
+ * admits; ambiguity refuses. The peer-isolation intent the per-session key was
+ * introduced for therefore moves from the KEY to the REFUSAL — a live peer's
+ * record is no longer excluded by its filename, so the branch gate in
+ * `consume_recycle_envelope` is what keeps an unrelated session from resuming
+ * it. That gate is part of this rule, not a decoration on it.
  */
 export function resolveContinuityRecord(
     workspace_root: string,
     session_id: string | null | undefined,
 ): ContinuityResolution {
     const id = String(session_id ?? '').trim();
-    if (id !== '') {
-        const own = path.join(workspace_root, recycle_envelope_rel(id));
-        return fs.existsSync(own)
-            ? { file: own, reason: `continuity record for this session (${safe_stem(id)})` }
-            : { file: null, reason: `no continuity record for this session (${safe_stem(id)})` };
-    }
-    const candidates = listContinuityRecords(workspace_root);
+    const own = id === '' ? null : path.join(workspace_root, recycle_envelope_rel(id));
+    const candidates = listContinuityRecords(workspace_root).filter((f) => f !== own);
     if (candidates.length === 0) {
-        return { file: null, reason: 'no continuity record present' };
+        return {
+            file: null,
+            reason:
+                id === ''
+                    ? 'no continuity record present'
+                    : `no predecessor record in this workspace (own: ${safe_stem(id)})`,
+        };
     }
     if (candidates.length === 1) {
-        return { file: candidates[0] as string, reason: 'one continuity record, no session id to key on' };
+        return {
+            file: candidates[0] as string,
+            reason:
+                id === ''
+                    ? 'one continuity record, no session id to key on'
+                    : `predecessor record, one candidate (own: ${safe_stem(id)})`,
+        };
     }
     return {
         file: null,
         reason:
-            `starting clean: ${candidates.length} continuity records in this workspace and no session id ` +
-            'to tell them apart — resuming from the newest would resume a peer session, not this one',
+            `starting clean: ${candidates.length} continuity records in this workspace and no way to tell ` +
+            'which is the predecessor — resuming from the newest would resume a peer session, not this one',
     };
 }
 
+/**
+ * Which session this one continues — read, never composed.
+ *
+ * The chain is derivable without any new artifact: when this session started,
+ * its reader consumed the predecessor's record and MOVED it to this session's
+ * consumed path (`recycle_consumed_rel`). So the file sitting there is, by
+ * construction, the record this session resumed from, and its `session_id` is
+ * the predecessor.
+ *
+ * Returns the explicit string `none` when there is nothing there. `none` is a
+ * CLAIM — "this session starts a chain" — and is deliberately not an empty
+ * value: a reader must be able to tell "no predecessor" from "nobody wrote the
+ * field", because only the second one is a reason to go looking.
+ */
+export function resolvePredecessor(projectRoot: string, sessionId: string | null): string {
+    try {
+        const consumed = path.join(projectRoot, recycle_consumed_rel(sessionId));
+        const raw = JSON.parse(fs.readFileSync(consumed, 'utf-8')) as { session_id?: unknown };
+        const prior = String(raw.session_id ?? '').trim();
+        return prior === '' ? 'none' : prior;
+    } catch {
+        return 'none';
+    }
+}
+
 /**
  * Is there any trace in this workspace of the session a record names as its
  * predecessor?

package/src/scripts/_lib/regression_neighbourhood.ts

@@ -12,30 +12,33 @@
  * > neighbourhood names, and a fixture proves a neighbour regression is
  * > caught.**
  *
- * ## Which graph, and why it is not the one the step names
+ * TWO GRAPHS, BOTH DELIBERATE — the substitution is retired.
  *
- * 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.
+ * The step says "the code graph". Until 2026-09-08 this module could not read
+ * it: `agent-config code-graph detect` answered `no code-graph source detected`
+ * in a fresh checkout, so it selected over the artefact graph instead and said
+ * so. `road-to-a-graph-that-is-shipped` removed that premise — Phase 0.1 ships
+ * the parsers, Phase 1 builds the graph on install, and 3.1 added
+ * `impact --diff`, which is the reverse-reachability query this selector needs.
  *
- *   · `agent-config code-graph` — the native code-graph engine (ADR-124). It
- *     shipped `hooks.code_graph.enabled: false` (a flag retired 2026-09-07)
- *     (`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.
+ * So both surfaces are now first-class, and which one a candidate uses is a
+ * property OF THE CANDIDATE rather than of what happened to resolve:
  *
- * 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.
+ *   · **Code candidates** — a diff that edits `.ts` / `.php` symbols. Use
+ *     {@link selectRegressionsFromCode}, which neighbours by SYMBOL relations
+ *     over the native graph, filtered to accepted mechanisms
+ *     (`resolved_via` not in `{name-lookup, dynamic}`) so a same-name guess
+ *     never selects a regression.
+ *   · **Artefact candidates** — a diff that edits rules, skills, guidelines.
+ *     Use {@link selectRegressions}, which neighbours by ARTEFACT relations
+ *     over `src/scripts/discovery_graph.ts` (`supersedes`, `routes_to`,
+ *     `references_adr`, pack and workspace membership). For a rule rewrite that
+ *     is the graph carrying the coupling a change can break; the code graph
+ *     does not model it at all.
+ *
+ * Neither is a fallback for the other, and neither is silent: both paths REFUSE
+ * through {@link selectionVerdict} when a touched surface is absent from the
+ * graph they read, because an unknown neighbourhood is not an empty one.
  *
  * ## Why an unresolved surface refuses instead of selecting nothing
  *
@@ -55,6 +58,9 @@
  * 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 type { GraphState } from '../code_graph/detect.js';
+import type { LoadedGraph } from '../code_graph/query.js';
+import { impact } from '../code_graph/verbs.js';
 import { affected, isSyntheticNode, type Graph } from '../discovery_graph.js';
 
 /**
@@ -106,6 +112,48 @@ export interface NeighbourhoodReport {
     selected: readonly Selection[];
     /** Registry entries whose guards intersect nothing in the neighbourhood. */
     skipped: readonly string[];
+    /**
+     * Which graph answered. Present so a verdict record can never be read as a
+     * claim about the other surface — the failure the retired substitution
+     * section describes, arriving through the report instead of through the
+     * docstring.
+     */
+    graph: 'artefact' | 'code';
+    /**
+     * The graph's freshness at selection time: `fresh` / `behind:N` / `absent`
+     * on the code path, `null` on the artefact path (which is derived from the
+     * committed manifest and has no staleness axis).
+     *
+     * Added after an independent review found the code path hardcoding
+     * `'absent'` and dropping the value: the verbs are required to report
+     * staleness, `verbs.ts` argues the whole point is telling "dead" from "dead
+     * as of a graph 40 commits behind" — and the one in-repo CONSUMER of those
+     * verbs discarded it, so no selection could refuse on a stale graph.
+     */
+    graph_state: GraphState | null;
+    /**
+     * Touched files in a language the code graph does not index. NOT a refusal
+     * reason: an unindexed `.md` is a file with no symbols, which is a fact
+     * about the language set rather than an unknown neighbourhood.
+     */
+    not_indexed: readonly string[];
+    /**
+     * The edges that produced the neighbourhood, rendered, sorted.
+     *
+     * Required by step 3.4: *"the selected regressions and the producing edges
+     * enter the verdict record"*. Empty on the artefact path, whose `affected`
+     * BFS returns a relation name per hop rather than an edge — stated rather
+     * than faked, because an empty list a reader can attribute is better than a
+     * synthesised one they cannot.
+     */
+    producing_edges: readonly string[];
+    /**
+     * The `resolved_via` histogram of the edges the walk REFUSED, on the code
+     * path. A selection that looks narrow because half the graph was a guess
+     * reads very differently from one that looks narrow because the code is
+     * decoupled, and this is the only field that distinguishes them.
+     */
+    rejected_via: string;
     /**
      * Literal 0. This module selects from a registry; a non-zero value here
      * would mean it authored a task, which is K9.
@@ -196,6 +244,80 @@ export function selectRegressions(
         unresolved: unresolvedSurfaces(graph, candidate),
         selected: selected.sort((a, b) => a.spec.id.localeCompare(b.spec.id)),
         skipped: skipped.sort((a, b) => a.localeCompare(b)),
+        graph: 'artefact',
+        graph_state: null,
+        not_indexed: [],
+        producing_edges: [],
+        rejected_via: '(not applicable — the artefact graph has no mechanism axis)',
+        authored: 0,
+    };
+}
+
+/**
+ * The code-graph path (step 3.4).
+ *
+ * Neighbours a candidate by the symbols its diff touched, over the native code
+ * graph, using the same `impact --diff` reverse walk the CLI verb exposes. The
+ * neighbourhood's nodes are the seeds at depth 0 (`touched`) plus every
+ * accepted reverse-reachable node at its shallowest depth (`neighbour`), which
+ * is the identical shape {@link neighbourhood} produces for the artefact graph
+ * — so `selectRegressions`' matching logic is reused rather than forked.
+ *
+ * `touches` is read as FILE paths here, not artefact ids: a code candidate is a
+ * diff, and a diff names files. A touched file with no node in the graph lands
+ * in `unresolved` and therefore refuses through {@link selectionVerdict}, on
+ * exactly the terms the artefact path already uses.
+ */
+export function selectRegressionsFromCode(
+    g: LoadedGraph,
+    candidate: Candidate,
+    registry: readonly RegressionSpec[],
+    depth: number = DEFAULT_NEIGHBOURHOOD_DEPTH,
+    isTest: (relPath: string) => boolean = () => false,
+    graphState: GraphState = 'absent',
+): NeighbourhoodReport {
+    const res = impact(g, candidate.touches, graphState, depth, isTest);
+    const best = new Map<string, NeighbourhoodNode>();
+    for (const seed of res.seeds) {
+        best.set(seed, { node: seed, reason: 'touched', depth: 0, via: '', synthetic: false });
+    }
+    for (const r of res.reached) {
+        if (best.has(r.node)) continue;
+        best.set(r.node, {
+            node: r.node,
+            reason: 'neighbour',
+            depth: r.depth,
+            via: `${r.via}/${r.resolved_via}`,
+            synthetic: false,
+        });
+    }
+    const hood = [...best.values()].sort((a, b) => a.depth - b.depth || a.node.localeCompare(b.node));
+    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((x) => reasonOf.has(x)).sort((a, b) => a.localeCompare(b));
+        if (matched.length === 0) {
+            skipped.push(spec.id);
+            continue;
+        }
+        selected.push({
+            spec,
+            matched,
+            reason: matched.some((m) => reasonOf.get(m) === 'touched') ? 'touched' : 'neighbour',
+        });
+    }
+    return {
+        candidate_id: candidate.id,
+        neighbourhood: hood,
+        unresolved: [...res.unresolved_files].sort((a, b) => a.localeCompare(b)),
+        selected: selected.sort((a, b) => a.spec.id.localeCompare(b.spec.id)),
+        skipped: skipped.sort((a, b) => a.localeCompare(b)),
+        graph: 'code',
+        graph_state: graphState,
+        not_indexed: [...res.not_indexed_files].sort((a, b) => a.localeCompare(b)),
+        producing_edges: [...res.producing_edges].sort(),
+        rejected_via: res.rejected_via,
         authored: 0,
     };
 }
@@ -209,9 +331,24 @@ export function selectRegressions(
  */
 export function selectionVerdict(report: NeighbourhoodReport): readonly string[] | null {
     const reasons: string[] = [];
+    // An ABSENT graph is the case the artefact path's own docstring warns
+    // about in the other direction: a lookup that cannot resolve and then
+    // selects nothing reports a clean sheet. `behind:N` is deliberately NOT a
+    // refusal — a stale graph still answers, and blocking on staleness would
+    // be the blocking-gate-on-a-stale-graph that K7 forbids. It is surfaced
+    // through `graph_state` so a caller that wants to refuse can.
+    if (report.graph === 'code' && report.graph_state === 'absent') {
+        reasons.push(
+            'the code graph is absent — a neighbourhood computed over no graph is empty for a ' +
+                'reason that has nothing to do with the candidate. Run `agent-config code-graph build`.',
+        );
+    }
     if (report.unresolved.length > 0) {
+        // Named per graph: a code-path refusal that said "relation graph" would
+        // point a reader at the wrong surface to go fix.
+        const which = report.graph === 'code' ? 'code graph' : 'artefact relation graph';
         reasons.push(
-            `touched surfaces absent from the relation graph: ${report.unresolved.join(', ')} — ` +
+            `touched surfaces absent from the ${which}: ${report.unresolved.join(', ')} — ` +
                 'their neighbourhood is unknown, and an unknown neighbourhood is not an empty one',
         );
     }