@event4u/agent-config 14.14.0 → 14.14.1

package/src/scripts/grade_target_readiness.ts

@@ -7,7 +7,7 @@
  * written in a command's markdown cannot be asserted by anything. So the
  * detection is here and the command invokes it; the command keeps the narrative.
  *
- * THE ANTI-VANITY RULE IS STRUCTURAL, NOT A STYLE NOTE. Ten dimensions are
+ * THE ANTI-VANITY RULE IS STRUCTURAL, NOT A STYLE NOTE. Thirteen dimensions are
  * graded 0 Absent / 1 Present / 2 Enforced-in-CI / 3 Independent-and-diff-scoped,
  * and the verdict is `min` over the FOUR knockout dimensions, reported as
  * `L<n> — bound by <dimension>`. **No aggregate number is ever emitted** — no
@@ -113,6 +113,66 @@ function _ciText(root: string): string {
     return out;
 }
 
+/* -- bounded text corpus, for the Phase 4 dimensions ----------------------- */
+
+/** Directories a target scan must never descend into: cost with no signal. */
+const _SKIP_DIRS = new Set([
+    'node_modules', '.git', 'vendor', 'dist', 'build', 'out', 'coverage',
+    '.next', '.nuxt', '.venv', 'venv', '__pycache__', 'target', '.terraform',
+]);
+/** Extensions that can carry a DNS record, a policy doc or an ops runbook. */
+const _CORPUS_RE = /\.(tf|tfvars|hcl|ya?ml|json|txt|zone|dns|ini|conf|cfg|toml|md|env|example|sh)$/i;
+const _CORPUS_MAX_FILES = 2000;
+const _CORPUS_MAX_BYTES = 256 * 1024;
+
+/**
+ * Read a bounded slice of the target's text, once, for the dimensions that
+ * cannot be answered by a root-level `_exists` probe.
+ *
+ * Three dimensions need to see INSIDE files — a DMARC policy is a string in a
+ * zone file or a Terraform record, not a filename — and the existing probes are
+ * all filename-shaped. The walk is capped in three directions (skip list, file
+ * count, per-file bytes) because an unbounded read of an arbitrary target repo
+ * is a cost this grader has no way to predict.
+ *
+ * Returns the concatenated text AND the relative paths, because a dimension that
+ * says WHERE it saw something is auditable and one that only says "somewhere in
+ * the tree" is not.
+ */
+export function _textCorpus(root: string): { text: string; paths: string[] } {
+    const paths: string[] = [];
+    let text = '';
+    const walk = (dir: string, rel: string): void => {
+        if (paths.length >= _CORPUS_MAX_FILES) return;
+        let entries: fs.Dirent[];
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        } catch {
+            return;
+        }
+        for (const e of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+            if (paths.length >= _CORPUS_MAX_FILES) return;
+            const abs = path.join(dir, e.name);
+            const r = rel === '' ? e.name : `${rel}/${e.name}`;
+            if (e.isDirectory()) {
+                if (_SKIP_DIRS.has(e.name)) continue;
+                walk(abs, r);
+                continue;
+            }
+            if (!_CORPUS_RE.test(e.name)) continue;
+            try {
+                if (fs.statSync(abs).size > _CORPUS_MAX_BYTES) continue;
+                text += `${fs.readFileSync(abs, 'utf-8')}\n`;
+            } catch {
+                continue;
+            }
+            paths.push(r);
+        }
+    };
+    walk(root, '');
+    return { text, paths };
+}
+
 /**
  * Is this a Python-primary target?
  *
@@ -125,7 +185,7 @@ export function isPythonTarget(root: string): boolean {
     return py && !other;
 }
 
-// ── the ten dimensions ─────────────────────────────────────────────────────
+// ── the thirteen dimensions ──
 
 /**
  * Grade one dimension. `ci` decides 1 → 2: a thing that exists is `Present`; a
@@ -149,6 +209,113 @@ function _ciBlocks(ci: string, ...needles: string[]): boolean {
     return !allSoft;
 }
 
+/* -- Phase 4 dimension ladders --------------------------------------------- */
+
+interface Scored {
+    grade: Grade;
+    evidence: string;
+}
+
+/** A runbook, a restore procedure, or a rollback path — and whether CI runs it. */
+function _recovery(corpus: { text: string; paths: string[] }, ci: string): Scored {
+    const namedFile = corpus.paths.some((p) => /(^|\/)(runbook|runbooks|disaster-recovery|dr)([./-]|$)/i.test(p));
+    const procedure = /\b(restore from backup|disaster recovery|rollback plan|pg_restore|pg_dump|restic|velero|RPO|RTO)\b/i.test(corpus.text);
+    const present = namedFile || procedure;
+    const enforced = _ciBlocks(ci, 'restore', 'rollback', 'disaster-recovery', 'backup');
+    // A DRILL is what separates a documented procedure from a proven one. It is
+    // the only honest route to 3 here, because "independent" for recovery means
+    // the restore was actually exercised rather than described.
+    const drill = /\b(restore (drill|test|rehearsal)|recovery drill|game ?day)\b/i.test(corpus.text);
+    const seen: string[] = [
+        ...(namedFile ? ['a runbook or DR document'] : []),
+        ...(procedure ? ['a restore/rollback procedure in the text'] : []),
+        ...(enforced ? ['a blocking CI step naming restore/rollback/backup'] : []),
+        ...(drill ? ['a restore drill'] : []),
+    ];
+    return {
+        grade: _graded(present, enforced, drill),
+        evidence: seen.length > 0 ? seen.join('; ') : 'no runbook, restore procedure or rollback path found',
+    };
+}
+
+/**
+ * SPF, DKIM and DMARC — and the rung that must not be fudged (4.2).
+ *
+ *   0 Absent   — no SPF, DKIM or DMARC RECORD anywhere. Prose about DMARC is
+ *                not a DMARC record; the signal is the record shape.
+ *   1 Present  — SPF and/or DKIM published, OR a DMARC record with `p=none`.
+ *                `p=none` is a MONITORING policy: it requests aggregate reports
+ *                and instructs receivers to take no action on a failing message.
+ *                A domain publishing it is measuring the problem, not preventing
+ *                it, so it is capped here however much else sits alongside it.
+ *   2 Enforced — DMARC `p=quarantine` or `p=reject`, with SPF or DKIM to align
+ *                against. An enforcing policy with nothing to align is a policy
+ *                over no signal, and stays at 1.
+ *   3 Top      — `p=reject` with BOTH SPF and DKIM and an `rua=` reporting
+ *                address, so the enforcement can be observed rather than assumed.
+ */
+function _mailAuthenticity(corpus: { text: string }): Scored {
+    const t = corpus.text;
+    const spf = /v=spf1\b/i.test(t);
+    const dkim = /v=DKIM1\b/i.test(t);
+    const dmarc = /v=DMARC1\b/i.test(t);
+    const policy = /v=DMARC1[^"'\n]*?\bp\s*=\s*(none|quarantine|reject)\b/i.exec(t)?.[1]?.toLowerCase();
+    const rua = /v=DMARC1[^"'\n]*?\brua\s*=/i.test(t);
+    const aligned = spf || dkim;
+    const parts = [
+        spf ? 'SPF published' : 'no SPF record',
+        dkim ? 'DKIM published' : 'no DKIM record',
+        dmarc ? `DMARC published (p=${policy ?? 'unset'})` : 'no DMARC record',
+    ];
+    if (!spf && !dkim && !dmarc) {
+        return { grade: 0, evidence: 'no SPF, DKIM or DMARC record found in the tree' };
+    }
+    if (policy === 'none') {
+        return {
+            grade: 1,
+            evidence:
+                `${parts.join('; ')} — capped at Present: p=none is a monitoring policy and is NOT protection, ` +
+                'because receivers are told to take no action on a message that fails. A domain publishing it ' +
+                'scores below one that enforces.',
+        };
+    }
+    if (policy === 'quarantine' || policy === 'reject') {
+        if (!aligned) {
+            return {
+                grade: 1,
+                evidence: `${parts.join('; ')} — an enforcing policy with neither SPF nor DKIM to align against protects nothing yet`,
+            };
+        }
+        if (policy === 'reject' && spf && dkim && rua) {
+            return { grade: 3, evidence: `${parts.join('; ')} — enforcing, both mechanisms aligned, and reporting to an rua address` };
+        }
+        return { grade: 2, evidence: `${parts.join('; ')} — an enforcing DMARC policy with an aligned mechanism` };
+    }
+    return { grade: 1, evidence: `${parts.join('; ')} — a mail-authenticity record exists, with no enforcing DMARC policy above it` };
+}
+
+/** A privacy notice, a retention rule, a consent mechanism, a deletion path. */
+function _privacyObligations(corpus: { text: string; paths: string[] }, ci: string): Scored {
+    const notice =
+        corpus.paths.some((p) => /(privacy|datenschutz|\bdpa\b|data-processing)/i.test(p)) ||
+        /\b(privacy (policy|notice)|Datenschutzerkl)/i.test(corpus.text);
+    const retention = /\b(retention (policy|period|schedule)|data retention|storage limitation)\b/i.test(corpus.text);
+    const consent = /\b(cookie consent|consent (banner|manager|mode)|cookiebot|usercentrics|klaro|borlabs)\b/i.test(corpus.text);
+    const erasure = /\b(right to erasure|data subject request|DSAR|DSR|account deletion|delete my data)\b/i.test(corpus.text);
+    const enforced = _ciBlocks(ci, 'privacy', 'gdpr', 'retention', 'consent', 'dsar');
+    const seen: string[] = [
+        ...(notice ? ['a privacy notice or DPA'] : []),
+        ...(retention ? ['a retention rule'] : []),
+        ...(consent ? ['a consent mechanism'] : []),
+        ...(erasure ? ['an erasure / data-subject-request path'] : []),
+        ...(enforced ? ['a blocking CI step naming a privacy obligation'] : []),
+    ];
+    return {
+        grade: _graded(notice || retention || consent || erasure, enforced),
+        evidence: seen.length > 0 ? seen.join('; ') : 'no privacy notice, retention rule, consent mechanism or erasure path found',
+    };
+}
+
 export function grade(root: string): Matrix {
     const ci = _ciText(root);
     const hasCi = ci !== '';
@@ -310,6 +477,41 @@ export function grade(root: string): Matrix {
         evidence: 'out of scope by design (see the roadmap exclusion table)',
     });
 
+    // 11. operational recovery — NON-KNOCKOUT
+    //
+    // New dimensions are never knockouts. A knockout added today would re-bind
+    // every existing verdict at L0 on the day it shipped, which changes what the
+    // level MEANS while looking like a change to what it measures.
+    const corpus = _textCorpus(root);
+    const recovery = _recovery(corpus, ci);
+    dims.push({
+        id: 'operational-recovery',
+        label: 'operational recovery',
+        knockout: false,
+        grade: recovery.grade,
+        evidence: recovery.evidence,
+    });
+
+    // 12. mail authenticity — NON-KNOCKOUT, own ladder (4.2)
+    const mail = _mailAuthenticity(corpus);
+    dims.push({
+        id: 'mail-authenticity',
+        label: 'mail authenticity',
+        knockout: false,
+        grade: mail.grade,
+        evidence: mail.evidence,
+    });
+
+    // 13. privacy obligations — NON-KNOCKOUT
+    const privacy = _privacyObligations(corpus, ci);
+    dims.push({
+        id: 'privacy-obligations',
+        label: 'privacy obligations',
+        knockout: false,
+        grade: privacy.grade,
+        evidence: privacy.evidence,
+    });
+
     // ── the verdict: min over knockouts, undetectable binds at L0 ──────────
     const knockouts = dims.filter((d) => d.knockout);
     const undetectable = knockouts.find((d) => d.grade === null);
@@ -440,6 +642,23 @@ export function selfTest(): number {
                 return /%|\/100/.test(out) ? 1 : 0;
             },
         },
+        {
+            name: 'DMARC p=none scores strictly below p=quarantine — monitoring is not protection',
+            expect: 'accept',
+            run: () => {
+                const g = (zone: string): number => {
+                    const d = grade(mk({
+                        'dns/zone.txt': zone,
+                        'dns/spf.txt': '@ IN TXT "v=spf1 include:_spf.example.net -all"\n',
+                        'dns/dkim.txt': 'sel._domainkey IN TXT "v=DKIM1; k=rsa; p=MIIB"\n',
+                    }));
+                    return d.dimensions.find((x) => x.id === 'mail-authenticity')?.grade ?? -1;
+                };
+                const none = g('_dmarc IN TXT "v=DMARC1; p=none; rua=mailto:d@example.com"\n');
+                const quarantine = g('_dmarc IN TXT "v=DMARC1; p=quarantine; rua=mailto:d@example.com"\n');
+                return none === 1 && quarantine === 2 ? 0 : 1;
+            },
+        },
         {
             name: 'rejects a missing target root rather than grading an empty tree',
             expect: 'reject',

package/src/scripts/hook_effect_doctor.ts

@@ -42,8 +42,13 @@
  * measurement runs first.
  *
  * Usage:
- *   ./scripts-run src/scripts/hooks_doctor [--host <name>] [--format text|json]
- *     [--root <path>] [--limit <n>]
+ *   ./agent-config hooks:effect [--host <name>] [--format text|json]
+ *     [--root <path>] [--limit <n>] [--help]
+ *   ./scripts-run src/scripts/hook_effect_doctor  (same flags, in this checkout)
+ *
+ * `--help` prints the two verdict vocabularies FROM THE MODULE THAT DEFINES
+ * THEM. A help text that restated them by hand would be a fifth hand-typed copy
+ * of a closed set, which is the drift class this repository gates elsewhere.
  */
 import { spawnSync } from 'node:child_process';
 import * as crypto from 'node:crypto';
@@ -51,7 +56,13 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 
-import { buildHostReport, type ConcernProbe, type HostReport } from './_lib/hook_effect_probe.js';
+import {
+    HOST_VERDICTS,
+    PROBE_STATES,
+    buildHostReport,
+    type ConcernProbe,
+    type HostReport,
+} from './_lib/hook_effect_probe.js';
 
 const HERE = path.dirname(new URL(import.meta.url).pathname);
 const REPO_ROOT = path.resolve(HERE, '..', '..');
@@ -230,6 +241,34 @@ export function renderText(r: HostReport): string {
     return out.join('\n') + '\n';
 }
 
+/**
+ * The synopsis, both closed vocabularies, and the scope line.
+ *
+ * Rendered from `PROBE_STATES` and `HOST_VERDICTS` rather than restated, so the
+ * help can never describe a vocabulary the probe no longer has.
+ */
+export function renderHelp(): string {
+    return [
+        'agent-config hooks:effect — does a bound concern actually FIRE on this host?',
+        '',
+        'Usage: agent-config hooks:effect [--host <name>] [--format text|json]',
+        '                                 [--root <path>] [--limit <n>] [--help]',
+        '',
+        'Not hooks:doctor. That one reads the MANIFEST — which concerns are declared,',
+        'their posture, whether their scripts and trampolines exist. This one dispatches',
+        'each eligible concern against a scratch root and reports what was observed.',
+        '',
+        `per-concern states:  ${PROBE_STATES.join(' · ')}`,
+        `host verdicts:       ${HOST_VERDICTS.join(' · ')}`,
+        '',
+        '`unknown` is never rendered as `effective`: a concern that wrote in the sandbox,',
+        'or that could not be dispatched at all, is reported as unestablished — never as a',
+        'working configuration.',
+        '',
+        'Exits 0 on every verdict. An `inert` host is information, not a build failure.',
+    ].join('\n') + '\n';
+}
+
 export function main(argv: string[] = process.argv.slice(2)): number {
     let host = 'claude';
     let format: 'text' | 'json' = 'text';
@@ -237,6 +276,10 @@ export function main(argv: string[] = process.argv.slice(2)): number {
     let limit = 200;
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
+        if (a === '--help' || a === '-h') {
+            process.stdout.write(renderHelp());
+            return 0;
+        }
         if (a === '--host') host = argv[++i] ?? host;
         else if (a === '--format') format = (argv[++i] as 'text' | 'json') ?? format;
         else if (a === '--root') root = path.resolve(argv[++i] ?? root);
@@ -246,7 +289,7 @@ export function main(argv: string[] = process.argv.slice(2)): number {
     try {
         report = buildReport(root, host, limit);
     } catch (err) {
-        process.stderr.write(`❌  hooks_doctor: ${(err as Error).message}\n`);
+        process.stderr.write(`❌  hooks:effect: ${(err as Error).message}\n`);
         return 2;
     }
     process.stdout.write(format === 'json' ? JSON.stringify(report, null, 2) + '\n' : renderText(report));

package/src/scripts/hooks/run_continuation_hook.ts

@@ -64,6 +64,13 @@
  *                                inert mechanism that says nothing is
  *                                indistinguishable from a healthy idle run,
  *                                which is the failure this file exists over)
+ *   plan premise moved         → allow  (event: halt-premise-invalidated, ONCE per
+ *                                run. Engaged-under fingerprint and newest
+ *                                observation both known and differing. Before the
+ *                                counter rungs: iterating against a stale plan
+ *                                does not make it current, and capping out would
+ *                                report `exhausted`, a budget word, for staleness.
+ *                                Never fires on traffic the run did not observe)
  *   quality-gate refusal       → defer            (event: deferred-quality-gate)
  *   duplicate stop fire        → repeat the BLOCK, no count (event: none —
  *                                an allow here would END the reply the block
@@ -173,8 +180,35 @@ import {
     readUnavailableDependency,
     stallSignal,
     type StallLevel,
-    type UnavailableDependency,
 } from '../_lib/loop_guards.js';
+import { premiseMoved, readContextObservation } from '../_lib/context_observation.js';
+import { RUN_TERMINAL_VOCABULARY_VERSION } from '../_lib/outcome_vocabularies.js';
+import {
+    HALT_ACTIONS,
+    ladder,
+    MAX_ITERATIONS,
+    parseHaltStamp,
+    STALL_WINDOW,
+    terminalStateFor,
+    WALL_CLOCK_CAP_MS,
+    type LadderAction,
+} from '../_lib/continuation_ladder.js';
+
+/**
+ * DECLARED in `_lib/continuation_ladder.ts`, re-exported here: one declaration,
+ * two import paths, no second copy to drift. That module's header says why the
+ * move happened (`road-to-wired-instruments` Phase 2).
+ */
+export {
+    HALT_ACTIONS,
+    ladder,
+    MAX_ITERATIONS,
+    parseHaltStamp,
+    STALL_WINDOW,
+    terminalStateFor,
+    WALL_CLOCK_CAP_MS,
+    type LadderAction,
+};
 
 /** Re-exported so a test can assert the IDENTITY, not two matching literals. */
 export { TRANSCRIPT_READ_MAX_BYTES };
@@ -198,11 +232,6 @@ export const EVENTS_RELPATH = path.join(
 );
 const STATE_DIR_REL = path.join('agents', 'runtime', 'state');
 
-/** Ladder defaults. Phase 1.1 pre-registers all three for revisit, not tuning. */
-export const MAX_ITERATIONS = 25;
-export const WALL_CLOCK_CAP_MS = 4 * 60 * 60 * 1000;
-export const STALL_WINDOW = 3;
-
 /**
  * How many consecutive absent-roadmap fires confirm the absence.
  *
@@ -285,6 +314,14 @@ export interface RunState {
      * cannot finish") named these rungs as its mitigation.
      */
     halted?: LadderAction;
+    /**
+     * The fingerprint this run ENGAGED under — its plan premise, recorded once on
+     * the first engagement from `_lib/context_observation` and then left alone.
+     * Refreshing it every fire would make both sides of the premise comparison
+     * equal by construction and the rung unreachable. Absent means the run never
+     * observed one, which is never a disagreement (`premiseMoved`).
+     */
+    context_fingerprint?: string;
 }
 
 /**
@@ -347,34 +384,6 @@ export interface ScanResult {
     next: NextStep | null;
 }
 
-export type LadderAction =
-    | 'engage'
-    | 'complete'
-    | 'blocked'
-    | 'halt-max-iterations'
-    | 'halt-wall-clock'
-    | 'halt-stall'
-    | 'halt-dependency-unavailable';
-
-/** The terminal rungs — the set `RunState.halted` may hold. */
-/**
- * `halt-roadmap-absent` is deliberately NOT in this union and not in
- * `LadderAction`. It is an event name the caller emits directly when the claimed
- * roadmap is unreadable from the authoritative tree, and it CLEARS the state
- * rather than stamping `halted` — widening the union would let `parseRecord`
- * accept it as a `halted` value, which would mean a run whose budget was cleared
- * also carried a halt stamp. The two are mutually exclusive by construction.
- */
-export const HALT_ACTIONS: readonly LadderAction[] = [
-    'halt-max-iterations',
-    'halt-wall-clock',
-    'halt-stall',
-    // Phase 5.4. Checked BEFORE the counter rungs: a dependency the run cannot
-    // obtain is not something more iterations close, so consuming the budget
-    // against it is the waste the rung exists to stop.
-    'halt-dependency-unavailable',
-];
-
 /**
  * Frontmatter `execution.mode`, or null. Line-oriented on purpose: the
  * frontmatter this repo writes is two levels deep at most, and a YAML parser
@@ -480,50 +489,6 @@ export function extractVerify(stepText: string): string | null {
     return null;
 }
 
-/**
- * The termination ladder, pure. `state` is the record BEFORE this stop;
- * `openCount` is the scan of the claimed roadmap as it stands now.
- */
-export function ladder(
-    state: RunState,
-    openCount: number,
-    nowMs: number,
-    // No default: `= 0` would silently restore the complete-instead-of-blocked
-    // behaviour for any caller that omitted it.
-    blockedCount: number,
-    caps: { maxIterations: number; wallClockMs: number; stallWindow: number } = {
-        maxIterations: MAX_ITERATIONS,
-        wallClockMs: WALL_CLOCK_CAP_MS,
-        stallWindow: STALL_WINDOW,
-    },
-    // Phase 5.4. `null` when nothing unobtainable was detected. Optional so every
-    // existing caller and test keeps its meaning unchanged.
-    unavailable: UnavailableDependency | null = null,
-): LadderAction {
-    // A halt is terminal for this run id. Checked BEFORE `complete` so a
-    // halted run whose roadmap later reads zero-open does not report a
-    // completion it never reached.
-    if (state.halted) return state.halted;
-    // `scanOpenSteps` EXCLUDES `blocked-by:` steps from `openCount`, so zero-open
-    // with blocked steps left is exhaustion of runnable work, not completion —
-    // ADR-235's own terminal outcome, and never a sixth halt.
-    if (openCount === 0) return blockedCount > 0 ? 'blocked' : 'complete';
-    // BEFORE the counter rungs, deliberately: a missing credential, an absent
-    // binary or an exhausted quota is not closed by iterating, so spending the
-    // budget on it converts a nameable blocker into an anonymous cap-out.
-    if (unavailable !== null) return 'halt-dependency-unavailable';
-    if (state.iterations >= caps.maxIterations) return 'halt-max-iterations';
-    const started = Date.parse(state.started_at);
-    if (Number.isFinite(started) && nowMs - started >= caps.wallClockMs) {
-        return 'halt-wall-clock';
-    }
-    const tail = state.history.slice(-caps.stallWindow);
-    if (tail.length >= caps.stallWindow && tail.every((n) => n === openCount)) {
-        return 'halt-stall';
-    }
-    return 'engage';
-}
-
 /**
  * Where a run's state lives: keyed on the session AND the roadmap.
  *
@@ -686,16 +651,17 @@ function readState(file: string): RunState | null {
         if (o['inert_reported'] === true) {
             rec.inert_reported = true;
         }
-        // Validated against the halt set rather than accepted as any string:
-        // an unrecognised value would be returned verbatim by `ladder` and
-        // become an action no branch below handles.
-        const halted = o['halted'];
-        if (
-            typeof halted === 'string' &&
-            (HALT_ACTIONS as readonly string[]).includes(halted)
-        ) {
-            rec.halted = halted as LadderAction;
+        // Round-tripped for the same reason `history_source` is: dropped, the
+        // premise would be re-recorded every fire from the newest observation, so
+        // the two sides could never differ and the rung would be dead code.
+        if (typeof o['context_fingerprint'] === 'string' && o['context_fingerprint'] !== '') {
+            rec.context_fingerprint = o['context_fingerprint'];
         }
+        // Tolerant, not permissive — see `parseHaltStamp` for what it accepts
+        // beyond the halt set and why dropping a newer build's stamp was the
+        // wrong failure direction for a budget.
+        const halted = parseHaltStamp(o['halted']);
+        if (halted !== null) rec.halted = halted;
         return rec;
     } catch {
         return null;
@@ -1412,7 +1378,21 @@ export function main(): number {
     // differently. One producer, one definition.
     state.stall = stallSignal(state.history, STALL_WINDOW).level;
 
-    const action = ladder(state, scan.open, Date.now(), scan.blocked, undefined, unavailable);
+    // 2.1 — repository drift, from the newest observation `roadmap:context`
+    // recorded. No probe here: the fingerprint costs a `gh` call and this is the
+    // Stop path. An unknown on either side is never a halt.
+    const observed = readContextObservation(workspaceRoot)?.fingerprint ?? null;
+    const premiseInvalidated = premiseMoved(state.context_fingerprint, observed);
+
+    const action = ladder(
+        state,
+        scan.open,
+        Date.now(),
+        scan.blocked,
+        undefined,
+        unavailable,
+        premiseInvalidated,
+    );
 
     if (action !== 'engage') {
         // A run that is ALREADY stamped emits nothing further — round 6 finding 6.
@@ -1436,6 +1416,12 @@ export function main(): number {
                 iterations: state.iterations,
                 open: scan.open,
                 blocked: scan.blocked,
+                // A ledger line is a persisted shape carrying a `RunTerminalState`,
+                // so it names the vocabulary version it was written against: a
+                // reader meeting an unknown value can then tell a newer writer
+                // from a corrupt row.
+                terminal_state: terminalStateFor(action),
+                terminal_vocabulary_version: RUN_TERMINAL_VOCABULARY_VERSION,
                 at: new Date().toISOString(),
                 ...roots,
             });
@@ -1472,6 +1458,10 @@ export function main(): number {
 
     state.iterations += 1;
     state.last_turn = turnOrdinal;
+    // Recorded ONCE — the premise this run engaged under. See the field's docblock.
+    if (state.context_fingerprint === undefined && observed !== null) {
+        state.context_fingerprint = observed;
+    }
     state.history.push(scan.open);
     state.last_engaged_at = new Date().toISOString();
     if (!writeState(stateFile, state)) {

package/src/scripts/hooks/session_eol_hook.ts

@@ -54,6 +54,7 @@ import {
     scanEolSlice,
     type EolCounters,
 } from '../_lib/session_eol.js';
+import { readContextObservation } from '../_lib/context_observation.js';
 import { buildCheckpoint, writeCheckpoint } from '../_lib/run_checkpoint.js';
 import { read_claimed_slug } from '../session_register_hook.js';
 import { unwrap, type JsonObject, type JsonValue } from './envelope.js';
@@ -381,7 +382,17 @@ export function main(): number {
         try {
             const slug = read_claimed_slug(workspaceRoot, checkpointRunId);
             if (slug !== null) {
-                const cp = buildCheckpoint(workspaceRoot, eolSessionKey(checkpointRunId), slug);
+                // `road-to-wired-instruments` 2.1. The fingerprint was never
+                // passed here, so `context_fingerprint` was null in every
+                // checkpoint this package has ever written and the resume-time
+                // drift check it exists for could not fire. The value comes from
+                // the newest recorded probe rather than from a fresh one: this is
+                // the Stop path, and the probe costs a `gh` call. Absent stays
+                // absent, which reads as "not known" and never as "unchanged".
+                const observed = readContextObservation(workspaceRoot)?.fingerprint ?? null;
+                const cp = buildCheckpoint(workspaceRoot, eolSessionKey(checkpointRunId), slug, {
+                    ...(observed !== null ? { contextFingerprint: observed } : {}),
+                });
                 if (cp !== null) writeCheckpoint(workspaceRoot, cp);
             }
         } catch {

package/src/scripts/install-hooks.sh

@@ -26,6 +26,24 @@ cat > "$HOOKS_DIR/pre-push" << 'EOF'
 # Pre-push hook: mirror the CI "Sync + Generate Tools Consistency" gate LOCALLY
 # so derived-output drift is caught BEFORE push, not in remote CI.
 #
+# THIS HOOK REFUSES. IT NEVER MERGES, AND NO ONE MAY "IMPROVE" IT INTO ONE.
+# A merge inside pre-push rewrites the working tree at the exact moment the
+# contributor believes their work is finished: one rejected push silently
+# becomes an unreviewed commit, and a conflict lands them mid-merge with no
+# warning and no way back to the state they typed `git push` from. Detection
+# belongs here; resolution belongs to a step run with the result in front of
+# you. When this hook refuses for staleness, the thing that fixes it is
+#
+#     task push-ready          # fetch -> integrate the base SET -> regenerate
+#                              # -> verify -> re-check freshness -> push
+#     task push-ready DRY=1    # the same six steps, read-only
+#
+# The base is a SET: a branch targeting a release line or a stacked parent may
+# also have to integrate the default branch, per the branch-convergence policy
+# read at the TARGET commit (src/scripts/_lib/branch_convergence.ts). The
+# default is merged FIRST, so a conflict surfaces against the broader base
+# where it is cheapest to abandon.
+#
 # History: the remote "Consistency" check failed in a large share of PRs because
 # the old hook only verified dist sync + the COMMAND count — it missed
 # guideline/skill/rule count drift and the generate-tools / router / corpus