@event4u/agent-config 14.12.0 → 14.13.0

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)),
+    };
+}

package/src/scripts/_lib/repeated_failure.ts

@@ -0,0 +1,105 @@
+/**
+ * The repeated-failure rate — computed over the AMENDED view, by construction.
+ *
+ * This is the roadmap's single pre-registered core metric, and the reason it
+ * needed the amendment path first is arithmetic rather than aesthetic. A repeat
+ * is precisely the signal that surfaces AFTER an episode's terminal record is
+ * written: rework lands, a regression is found, a review comes back. A rate
+ * computed over unamended rows therefore undercounts the exact thing it exists
+ * to measure, and undercounts it in the flattering direction.
+ *
+ * The guarantee here is structural, not documentary: this module's input type
+ * is {@link EpisodeReconstruction}, which is the folded projection. It has no
+ * overload taking raw `JournalEvent[]`, so a caller CANNOT accidentally compute
+ * the rate over unamended rows — there is nothing to pass.
+ */
+
+import type { BasisTag } from './evidence_basis.js';
+import type { EpisodeReconstruction } from './runtime_journal.js';
+import { RUN_TERMINAL_STATES, type RunTerminalState } from './outcome_vocabularies.js';
+
+/**
+ * Terminal states that count as a failure for this metric.
+ *
+ * `clean-no-op` is deliberately NOT a failure: an episode that correctly
+ * determined there was nothing to do succeeded at the thing it was asked. And
+ * `approval-required` is not one either — it is the safety floor working, and
+ * counting a floor doing its job as a failure would make the metric fall every
+ * time governance fires.
+ */
+export const FAILURE_TERMINALS: ReadonlySet<RunTerminalState> = new Set([
+    'blocked',
+    'exhausted',
+    'stagnated',
+]);
+
+/** States that count as a success for the metric. */
+export const SUCCESS_TERMINALS: ReadonlySet<RunTerminalState> = new Set([
+    'success',
+    'clean-no-op',
+]);
+
+// Every terminal state is classified or deliberately excluded -- silence about
+// one is how a metric quietly changes meaning when the vocabulary grows.
+const CLASSIFIED = new Set<string>([...FAILURE_TERMINALS, ...SUCCESS_TERMINALS, 'approval-required']);
+const _unclassified = RUN_TERMINAL_STATES.filter((t) => !CLASSIFIED.has(t));
+if (_unclassified.length > 0) {
+    throw new Error(
+        `repeated_failure: terminal state(s) ${_unclassified.join(', ')} are neither a failure, ` +
+            'a success, nor explicitly excluded. Classify them or the rate silently changes meaning.',
+    );
+}
+
+export interface RepeatedFailureRate {
+    /** Episodes whose EFFECTIVE terminal state is a failure. */
+    failed: number;
+    /** Episodes with any classifiable effective terminal state. */
+    classified: number;
+    /** Episodes whose terminal state is absent or excluded. Its own share. */
+    unknown: number;
+    /** `failed / classified`, or `null` when nothing was classifiable. */
+    rate: number | null;
+    /** How many of the counted episodes carried at least one amendment. */
+    amended_episodes: number;
+    basis: BasisTag;
+}
+
+/**
+ * Compute the rate.
+ *
+ * `rate` is `null`, never `0`, when nothing classifiable was seen — the same
+ * rule the per-asset report follows, for the same reason: zero is a measurement
+ * and null is an absence, and a reader acts on the first while asking about the
+ * second.
+ */
+export function repeatedFailureRate(
+    episodes: readonly EpisodeReconstruction[],
+): RepeatedFailureRate {
+    let failed = 0;
+    let classified = 0;
+    let unknown = 0;
+    let amended_episodes = 0;
+
+    for (const ep of episodes) {
+        if (ep.amendment_count > 0) amended_episodes += 1;
+
+        // `ep.terminal_state` is already the AMENDED verdict: reconstructEpisode
+        // drops superseded rows and takes the LAST effective terminal state.
+        const t = ep.terminal_state;
+        if (t === null || !CLASSIFIED.has(t) || t === 'approval-required') {
+            unknown += 1;
+            continue;
+        }
+        classified += 1;
+        if (FAILURE_TERMINALS.has(t)) failed += 1;
+    }
+
+    return {
+        failed,
+        classified,
+        unknown,
+        rate: classified === 0 ? null : failed / classified,
+        amended_episodes,
+        basis: 'estimated:ratio-over-amended-episode-terminals',
+    };
+}

package/src/scripts/_lib/repo_root.ts

@@ -0,0 +1,111 @@
+/**
+ * Repository-root resolution that REFUSES rather than guesses.
+ *
+ * `road-to-skill-ecosystem-runtime-enforcement` Phase 2 Step 6. The trap class
+ * this closes is small to describe and has cost multiple sessions:
+ *
+ *   1. **An inherited `GIT_DIR`.** A git hook exports `GIT_DIR` (often `.git`,
+ *      relative) into every child process. A gate that resolves its root with
+ *      `git rev-parse --show-toplevel` then answers for whatever repository the
+ *      inherited variable points at — which inside a worktree hook is the parent
+ *      checkout, not the tree being committed. The gate runs, reads the wrong
+ *      files, and passes.
+ *   2. **A path walked one directory too far.** `path.resolve(__dirname, '..',
+ *      '..')` is correct until a file moves, and then it silently addresses a
+ *      parent directory that also exists. Nothing fails; the scan is simply
+ *      empty, which several gates report as a clean pass.
+ *
+ * Both are the same failure in the end: a resolver that always SUCCEEDS. So the
+ * contract here is the opposite — a root is returned only when the directory
+ * carries a **sentinel** proving it is the repository, and otherwise the call
+ * throws. A caller that cannot locate its own repository should stop, not scan
+ * an arbitrary directory.
+ *
+ * The sentinel is `package.json` carrying this package's `name`, not a bare
+ * `package.json`: every node_modules entry and every sibling project has one of
+ * those, and a resolver that accepts any of them has not narrowed anything.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/** The package name that identifies THIS repository. */
+export const SENTINEL_PACKAGE_NAME = '@event4u/agent-config';
+
+/** Raised when no directory on the walk carries the sentinel. */
+export class RepoRootUnresolvedError extends Error {
+    readonly startedAt: string;
+
+    constructor(startedAt: string, message: string) {
+        super(message);
+        this.name = 'RepoRootUnresolvedError';
+        this.startedAt = startedAt;
+    }
+}
+
+/**
+ * True when `dir` is this repository's root.
+ *
+ * Reads `package.json` and compares `name`. A parse failure is `false`, never a
+ * throw: a malformed `package.json` somewhere up the walk must not stop the walk
+ * from reaching a valid root above it.
+ */
+export function hasSentinel(dir: string): boolean {
+    try {
+        const raw = fs.readFileSync(path.join(dir, 'package.json'), 'utf8');
+        return (JSON.parse(raw) as { name?: unknown }).name === SENTINEL_PACKAGE_NAME;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Walk upward from `from` and return the first directory carrying the sentinel.
+ *
+ * @throws {RepoRootUnresolvedError} when the walk reaches the filesystem root
+ * without finding one. Deliberately not a `null` return: an optional type
+ * invites `?? process.cwd()`, which is the guess this module exists to prevent.
+ */
+export function resolveRepoRoot(from: string = process.cwd()): string {
+    let dir = path.resolve(from);
+    const seen: string[] = [];
+    for (;;) {
+        seen.push(dir);
+        if (hasSentinel(dir)) return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir) break;
+        dir = parent;
+    }
+    throw new RepoRootUnresolvedError(
+        path.resolve(from),
+        `no repository root above ${path.resolve(from)} — no directory on the walk carries a ` +
+            `package.json named "${SENTINEL_PACKAGE_NAME}". Checked ${String(seen.length)} directory(ies). ` +
+            'This is a refusal, not a fallback: resolving to the working directory here is how a gate ' +
+            'ends up scanning an arbitrary tree and reporting a clean pass over it.',
+    );
+}
+
+/**
+ * The environment variables that override git's own discovery.
+ *
+ * `GIT_DIR` is the one that has actually bitten; the other three are listed
+ * because they fail the same way and a reader checking for one should see all
+ * four rather than believe the list is complete at one entry.
+ */
+export const GIT_DISCOVERY_OVERRIDES = [
+    'GIT_DIR',
+    'GIT_WORK_TREE',
+    'GIT_INDEX_FILE',
+    'GIT_COMMON_DIR',
+] as const;
+
+/** Any git discovery override present in `env`, with its value. */
+export function inheritedGitOverrides(
+    env: NodeJS.ProcessEnv = process.env,
+): { name: string; value: string }[] {
+    const out: { name: string; value: string }[] = [];
+    for (const name of GIT_DISCOVERY_OVERRIDES) {
+        const value = env[name];
+        if (typeof value === 'string' && value !== '') out.push({ name, value });
+    }
+    return out;
+}

package/src/scripts/_lib/review_skipped_record.ts

@@ -34,6 +34,17 @@
  */
 export type MutationMeasure = 'exact' | 'capped_approximation';
 
+import type { NoFreeForm } from './runtime_journal.js';
+import { type PrivacyClass } from './privacy_class.js';
+
+type Assert<T extends true> = T;
+
+/**
+ * What THIS producer's lines carry: counts (`diff_lines`), enums, and the
+ * `rules_applied` id array. `ids-only`, same as the orchestration producer.
+ */
+const PRODUCER_PRIVACY_CLASS: PrivacyClass = 'ids-only';
+
 export interface ReviewSkippedInput {
     /** Non-doc tracked-file mutation size that triggered the nudge (count only). */
     diff_lines: number;
@@ -92,6 +103,15 @@ export function buildReviewSkippedLine(input: ReviewSkippedInput): BuiltReviewSk
         memory: { asks: 0, hits: 0 },
         verify: { claims: 0, first_try_passes: 0 },
         rules_applied: ['delegation-policy'],
+        // MANDATORY on every audit line, same as the orchestration producer.
+        privacy_class: PRODUCER_PRIVACY_CLASS,
+        // `skills_applied` is OMITTED here, deliberately and not by oversight.
+        // audit-log-v1 distinguishes an absent key ("not recorded") from `[]`
+        // ("recorded, none applied"), and this writer observes a review that
+        // did not happen -- it has no skill observation to offer in either
+        // direction. Emitting `[]` would assert "no skills applied" on evidence
+        // this producer never gathered, which is the exact fabrication the
+        // absent/empty split exists to make impossible.
         persona: null,
         input_kind: 'prompt',
         type: 'note',
@@ -100,3 +120,20 @@ export function buildReviewSkippedLine(input: ReviewSkippedInput): BuiltReviewSk
 
     return { line, errors: [] };
 }
+
+/**
+ * The SECOND producer's half of the compile-time privacy floor.
+ *
+ * `docs/contracts/audit-log-v1.md` states that the floor holds by construction
+ * "on two paths"; guarding only the first would leave that sentence half true
+ * while reading as fully true. Same mechanism as
+ * `orchestration_record.ts`: a free-form key on the input type makes this
+ * `Assert<false>` and stops the build.
+ *
+ * The negative direction is fixtured there rather than duplicated here — one
+ * proof that `NoFreeForm` still rejects is enough for both call sites, since
+ * they share the type.
+ */
+type _ReviewSkippedInputCarriesNoFreeFormField = Assert<
+    [NoFreeForm<ReviewSkippedInput>] extends [never] ? false : true
+>;