@event4u/agent-config 17.2.1 → 17.4.0

package/src/scripts/hooks/host_semantics.ts

@@ -35,6 +35,7 @@
  */
 
 import { blockExitFor, DEFAULT_SURFACE, loadHostLowering, surfaceRow, verifiedPlatforms } from "./host_lowering.js";
+import { hostShowsUserNotice, writeNoticeReceipts, type NoticeBatch } from "./user_notice.js";
 
 /** Internal severity, mirroring dispatch_hook's EXIT_ALLOW / BLOCK / WARN. */
 export type Severity = "allow" | "warn" | "block";
@@ -133,6 +134,77 @@ export function claudeAdditionalContext(event: string, text: string): string {
     })}\n`;
 }
 
+function isObject(v: unknown): v is Record<string, unknown> {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/**
+ * Compose the dispatcher's stdout from its three parts: plain `session_start`
+ * context, the native emission, and a user-addressed notice.
+ *
+ * Without a notice — or on a host with no verified user field — this is the
+ * old output byte for byte: context, then emission. With one, the host parses
+ * stdout as JSON only when the whole of it is one object, so the parts are
+ * MERGED as structures, never concatenated as text: the emission's object is
+ * kept, context joins its `hookSpecificOutput.additionalContext`, and the
+ * notice joins `systemMessage`. Plain context is accepted on `session_start`
+ * only, and an emission that is not one JSON object is never reinterpreted —
+ * in either case the notice is dropped and the old output stands.
+ */
+export function withUserNotice(
+    platform: string,
+    event: string,
+    context: string,
+    emission: string,
+    notice: string,
+): string {
+    const legacy = context + emission;
+    const text = notice.trim();
+    if (!text || !hostShowsUserNotice(platform) || !usesNativeEmission(platform)) return legacy;
+    if (context.trim() && event !== "session_start") return legacy;
+    let reply: Record<string, unknown> = {};
+    if (emission.trim()) {
+        try {
+            reply = JSON.parse(emission) as Record<string, unknown>;
+        } catch {
+            return legacy;
+        }
+        if (!isObject(reply)) return legacy;
+    }
+    // A field this merge would extend must already have the type it extends.
+    const hsoIn = reply["hookSpecificOutput"];
+    if (hsoIn !== undefined && !isObject(hsoIn)) return legacy;
+    if (![reply["systemMessage"], hsoIn?.["additionalContext"]].every((v) => v === undefined || typeof v === "string")) return legacy;
+    const join = (a: unknown, b: string, sep: string): string => (typeof a === "string" && a ? `${a}${sep}${b}` : b);
+    if (context.trim()) {
+        const hso = hsoIn ?? { hookEventName: nativeEventName(platform, event) };
+        reply["hookSpecificOutput"] = { ...hso, additionalContext: join(hso["additionalContext"], context.trim(), "\n\n") };
+    }
+    reply["systemMessage"] = join(reply["systemMessage"], text, "\n");
+    return `${JSON.stringify(reply)}\n`;
+}
+
+/**
+ * Write the dispatcher's whole stdout — `withUserNotice` over its parts — and
+ * only then a receipt for each notice that is actually in what was written: a
+ * write that throws leaves no receipt, and a dropped notice leaves none, so its
+ * concern says it again instead of counting it as shown. The notice rides only
+ * on exit 0, because the host parses stdout only then.
+ */
+export function writeStdout(
+    platform: string,
+    event: string,
+    context: string,
+    emission: Emission,
+    notices: NoticeBatch,
+    sessionId: string,
+    write: (text: string) => unknown,
+): void {
+    const out = withUserNotice(platform, event, context, emission.stdout, emission.exit === 0 ? notices.map((n) => n.text).join("\n") : "");
+    if (out) write(out);
+    if (notices.length > 0 && out !== context + emission.stdout) writeNoticeReceipts(notices, sessionId);
+}
+
 /**
  * A host permission verdict for a `pre_tool_use` call.
  *

package/src/scripts/hooks/lazy_concern.ts

@@ -72,6 +72,14 @@ export const LAZY_CONCERNS: Readonly<Record<string, { readonly chunk: string; re
             chunk: 'instructions_observer.chunk.cjs',
             source: 'instructions_observer_hook',
         }),
+        'src/scripts/hooks/code_graph_refresh_hook.ts': Object.freeze({
+            chunk: 'code_graph_refresh.chunk.cjs',
+            source: 'code_graph_refresh_hook',
+        }),
+        'src/scripts/update_notice_hook.ts': Object.freeze({
+            chunk: 'update_notice.chunk.cjs',
+            source: path.join('..', 'update_notice_hook'),
+        }),
     });
 
 declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;

package/src/scripts/hooks/user_notice.ts

@@ -0,0 +1,105 @@
+/**
+ * The user-addressed channel: text a concern hands the dispatcher for the HUMAN,
+ * which the host shows in its own UI and never adds to model context.
+ *
+ * WHY IT EXISTS. Every channel the dispatcher had addressed the model
+ * (`additional_context`, `context`) or went to stderr, and every host runs the
+ * dispatcher on pipes — so a concern with something to tell the user had no
+ * path that reached them. `update-notice` was refused registration for exactly
+ * that: bound, it would have said nothing anywhere.
+ *
+ * Claude Code documents a `systemMessage` field on every hook event, "Display a
+ * message to the user", read off the 2.1.310 binary on 2026-10-24. It is the
+ * only host this package has verified a user-addressed field on, so the set
+ * below is one host wide; an unlisted host gets nothing rather than a guess.
+ *
+ * loss_class: ephemeral-lossy
+ *
+ * A notice longer than USER_NOTICE_MAX_CHARS loses its tail, deliberately: the
+ * text is for the user's UI and never reaches the model, and a notice is a few
+ * lines by contract, so nothing recovers the cut part.
+ */
+
+import * as fs from 'node:fs';
+
+import { write_atomic } from '../_lib/fs_atomic.js';
+import { write_target } from '../_lib/user_global_paths.js';
+
+/** The concern reply key a notification concern puts its user-facing text under. */
+export const USER_NOTICE_KEY = 'user_notice';
+
+/** The reply key naming this one notice, echoed into its receipt and never shown. */
+export const USER_NOTICE_ID_KEY = 'notice_id';
+
+/** Longest notice the dispatcher forwards, in Unicode code points; a notice is a few lines, never a document. */
+export const USER_NOTICE_MAX_CHARS = 1000;
+
+/** Hosts with a verified field that shows text to the user and not to the model. */
+export const USER_NOTICE_HOSTS: ReadonlySet<string> = new Set(['claude']);
+
+export function hostShowsUserNotice(platform: unknown): boolean {
+    return typeof platform === 'string' && USER_NOTICE_HOSTS.has(platform);
+}
+
+/**
+ * The notices one dispatch kept, each with the concern it came from, in
+ * manifest order. One entry carries both, so the text that is emitted and the
+ * concern that gets a receipt can never come apart.
+ */
+export type NoticeBatch = Array<{ readonly concern: string; readonly text: string; readonly id: string }>;
+
+/**
+ * Only a `notification` concern may address the user: no other effect was
+ * reviewed for it. The text is cleaned, then capped by code point so a pair is
+ * never split, and kept only if something is left to show.
+ */
+export function collectUserNotice(
+    batch: NoticeBatch,
+    concern: Record<string, unknown>,
+    reply: Record<string, unknown>,
+    clean: (text: string) => string,
+): void {
+    const notice = reply[USER_NOTICE_KEY];
+    if (concern['effect'] !== 'notification' || typeof notice !== 'string') return;
+    const text = Array.from(clean(notice.trim())).slice(0, USER_NOTICE_MAX_CHARS).join('').trim();
+    const id = reply[USER_NOTICE_ID_KEY];
+    if (text) batch.push({ concern: String(concern['name']), text, id: typeof id === 'string' ? id.slice(0, 64) : '' });
+}
+
+/**
+ * A delivery receipt: the dispatcher writes one per concern whose notice it
+ * actually put into host output, naming the session and the notice's own id.
+ * A concern that must not count a notice as shown until it was handed to the
+ * host reads it on its next run and matches the id it handed over; anything the
+ * dispatcher dropped leaves no receipt for that id, so the concern says it again.
+ */
+export interface NoticeReceipt {
+    readonly session_id: string;
+    readonly notice_id: string;
+    readonly at: string;
+}
+
+function receiptPath(concern: string): string {
+    return write_target(`user-notice-${concern}.delivered`);
+}
+
+export function writeNoticeReceipts(batch: NoticeBatch, sessionId: string): void {
+    for (const { concern, id } of batch) {
+        try {
+            write_atomic(receiptPath(concern), JSON.stringify({ session_id: sessionId, notice_id: id, at: new Date().toISOString() }));
+        } catch {
+            // no receipt → the concern repeats its notice, which is the safe direction
+        }
+    }
+}
+
+export function readNoticeReceipt(concern: string): NoticeReceipt | null {
+    try {
+        const o = JSON.parse(fs.readFileSync(receiptPath(concern), 'utf-8')) as Record<string, unknown>;
+        return typeof o['session_id'] === 'string' && typeof o['notice_id'] === 'string' && typeof o['at'] === 'string'
+            ? { session_id: o['session_id'], notice_id: o['notice_id'], at: o['at'] }
+            : null;
+    } catch {
+        return null;
+    }
+}

package/src/scripts/install-hooks.sh

@@ -1,6 +1,21 @@
 #!/usr/bin/env bash
 # Install git hooks for this repository.
 # Run once: bash src/scripts/install-hooks.sh
+#
+# TRUST MODEL. The hooks this writes execute code FROM THE CHECKOUT —
+# `./agent-config`, `./scripts-run`, `task`, `npm run build:cli` — on commit,
+# checkout, merge, rebase and push. That is acceptable in exactly one place:
+# this package's own development tree, whose code the developer already runs
+# (tests, `prepare`, the CLI itself). A globally installed `agent-config` would
+# be an older build of the same code, so the checkout's own is the right one
+# HERE. It is wrong anywhere else: run from a consumer's
+# `node_modules/@event4u/agent-config/`, this script would resolve the
+# CONSUMER's git directory and install these hooks into a repository whose
+# code nobody vetted for them. The guard below enforces the boundary — the
+# project root must be the git top-level AND its package.json must name
+# @event4u/agent-config — and consumer freshness travels through the
+# `code-graph-refresh` session concern instead, which never runs repository
+# code (road-to-code-graph-refresh-follow-ups 3.1 / 3.2).
 
 set -euo pipefail
 
@@ -8,6 +23,15 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # This installer lives at src/scripts/install-hooks.sh, so the repo root
 # (which owns .git/) is two levels up.
 PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+TOPLEVEL="$(git -C "$PROJECT_ROOT" rev-parse --show-toplevel 2>/dev/null || true)"
+if [ -z "$TOPLEVEL" ] \
+    || [ "$(cd "$TOPLEVEL" && pwd -P)" != "$(cd "$PROJECT_ROOT" && pwd -P)" ] \
+    || ! grep -Eq '"name"[[:space:]]*:[[:space:]]*"@event4u/agent-config"' "$PROJECT_ROOT/package.json" 2>/dev/null; then
+    echo "❌  refusing to install the development git hooks: $PROJECT_ROOT is not the top level of an" >&2
+    echo "    @event4u/agent-config checkout. These hooks run code from the checkout (TRUST MODEL above)." >&2
+    exit 1
+fi
 # Resolve the SHARED hooks dir via git so this also works from a linked worktree
 # (where $PROJECT_ROOT/.git is a file, not a dir, and a literal .git/hooks path
 # would break under `set -e`). --git-common-dir points at the main .git even from
@@ -619,18 +643,26 @@ echo "✅  Auto-sync block appended to post-merge / post-checkout hooks." >&2
 #
 # road-to-a-graph-that-is-shipped 1.3. A code graph goes stale the moment a
 # commit lands, and the only thing that knew were the reader — after it had
-# already answered from a stale index. These two hooks close that without a
+# already answered from a stale index. These hooks close that without a
 # resident process: git tells us HEAD moved, and a detached child rebuilds.
 #
+# Four hooks, because HEAD moves through four doors (measured with a probe
+# repo): a commit fires post-commit, a branch switch post-checkout, a
+# fast-forward `git pull` ONLY post-merge, and a rebase post-checkout at its
+# START and post-rewrite at its end. Without the last two, `git pull` left the
+# graph stale and a rebase refreshed against an intermediate HEAD.
+#
 # Four properties, each load-bearing:
 #
 #   · BACKGROUND. The refresh is `&`-detached with stdout/stderr closed, so a
 #     commit never waits on a parse. Git's own runtime is unchanged.
-#   · SINGLE-FLIGHT. `mkdir` is atomic on every POSIX filesystem, so of two
-#     concurrent commits exactly one creates the lock and exactly one refresh
-#     runs. This is Risk 3 in the roadmap's register — "git hooks pile up
-#     rebuilds" — and a lock file written with `>` would not have closed it,
-#     because two processes can both truncate-and-write the same path.
+#   · SINGLE-FLIGHT. `refresh --single-flight` takes the engine's own mkdir
+#     lock (code_graph/refresh_lock.ts), the one the session-start concern and
+#     a manual `map` take too, so of two concurrent commits exactly one
+#     rebuilds. This is Risk 3 in the roadmap's register — "git hooks pile up
+#     rebuilds". The hook used to hold its own shell lock; a ratification round
+#     of 2026-10-23 found two lock protocols racing on one directory, so there
+#     is now one, and its stale-lock reclaim is mutex-guarded and re-checked.
 #   · BUDGETED. `--budget-seconds` is the engine's own wall-clock ceiling; a
 #     child that exceeds it is SIGKILLed and the OLD cache is left untouched
 #     (cli.ts's refresh contract). Kill register K7 — never block on a stale
@@ -639,9 +671,8 @@ echo "✅  Auto-sync block appended to post-merge / post-checkout hooks." >&2
 #     exists. Building a graph for someone who never asked for one is the pure
 #     cost Risk 1 names; refreshing one they built is the service.
 #
-# The lock is a directory under the gitignored runtime state, so a crashed
-# child leaves a stale lock that the next refresh clears by age rather than
-# blocking forever.
+# `--map` redraws agents/map/ under the same lock, only for a project that has
+# one (ADR-297).
 
 append_code_graph_refresh_block() {
     local name="$1"
@@ -657,30 +688,18 @@ if [ "${3:-1}" = "0" ]; then
 fi
 EOF
     fi
-    cat >> "$HOOKS_DIR/$name" << 'EOF'
-cg_cache="agents/runtime/state/code-graph-v1.json"
-cg_lock="agents/runtime/state/code-graph-refresh.lock"
-if [ -f "$cg_cache" ] && [ -x ./agent-config ]; then
-    # Clear a lock left by a killed child: older than the largest budget any
-    # caller passes, so it cannot race a refresh that is legitimately running.
-    if [ -d "$cg_lock" ]; then
-        if [ -z "$(find "$cg_lock" -maxdepth 0 -mmin -5 2>/dev/null)" ]; then
-            rmdir "$cg_lock" 2>/dev/null || true
-        fi
-    fi
-    # Atomic: exactly one of N concurrent hooks wins this, and the losers do
-    # nothing rather than queueing a second rebuild behind the first.
-    if mkdir "$cg_lock" 2>/dev/null; then
-        (
-            trap 'rmdir "$cg_lock" 2>/dev/null || true' EXIT
-            ./agent-config code-graph refresh --budget-seconds 60 >/dev/null 2>&1 || true
-            # The map follows the index it is drawn from, but only for a
-            # project that asked for one: no agents/map/, no map (ADR-297).
-            if [ -d agents/map ]; then
-                ./agent-config code-graph map --no-verify --no-build >/dev/null 2>&1 || true
-            fi
-        ) >/dev/null 2>&1 &
+    if [ "$name" = "post-rewrite" ]; then
+        cat >> "$HOOKS_DIR/$name" << 'EOF'
+# An amend already fired post-commit; only a finished rebase is news here.
+if [ "${1:-}" != "rebase" ]; then
+    exit 0
+fi
+EOF
     fi
+    cat >> "$HOOKS_DIR/$name" << 'EOF'
+if [ -f agents/runtime/state/code-graph-v1.json ] && [ -x ./agent-config ]; then
+    ./agent-config code-graph refresh --single-flight --map --budget-seconds 60 \
+        </dev/null >/dev/null 2>&1 &
 fi
 exit 0
 EOF
@@ -688,4 +707,6 @@ EOF
 
 append_code_graph_refresh_block "post-commit"
 append_code_graph_refresh_block "post-checkout"
-echo "✅  Code-graph refresh block appended to post-commit / post-checkout hooks." >&2
+append_code_graph_refresh_block "post-merge"
+append_code_graph_refresh_block "post-rewrite"
+echo "✅  Code-graph refresh block appended to post-commit / post-checkout / post-merge / post-rewrite hooks." >&2

package/src/scripts/install.ts

@@ -125,7 +125,7 @@ import { installerThinsHost } from './_lib/lean_projection_mode.js';
 import { GLOBAL_DEPLOY_SOURCES, RULE_SOURCE_REL, dryRunTargetLines } from '../install/wizard-plan.js';
 import { flattenSurface, computeSurfaceDelta, type SettingsSurface } from '../shared/settingsSurface.js';
 import { settingsSchema } from '../server/schemas/settings.js';
-import { zodToJsonSchema } from 'zod-to-json-schema';
+import { toJsonSchema7 } from '../shared/zodJsonSchema.js';
 import { detect_module_roots } from './_lib/module_detection.js';
 import {
     TIER_TO_CLAUDE_MODEL,
@@ -3671,11 +3671,7 @@ const SETTINGS_SURFACE_REL = path.join('state', 'settings-surface.json');
 const SETTINGS_DELTA_REL = path.join('state', 'settings-delta.json');
 
 function _current_settings_surface(version: string): SettingsSurface {
-    const jsonSchema = zodToJsonSchema(settingsSchema, {
-        name: 'AgentSettings',
-        $refStrategy: 'none',
-        target: 'jsonSchema7',
-    }) as Parameters<typeof flattenSurface>[0];
+    const jsonSchema = toJsonSchema7(settingsSchema, 'AgentSettings') as Parameters<typeof flattenSurface>[0];
     return flattenSurface(jsonSchema, version);
 }
 

package/src/scripts/lint_harvest_provenance.ts

@@ -30,7 +30,13 @@
  *   4. Pinning — `source_ref` carries a revision or is explicitly opaque; a
  *      bare URL is rejected because it cannot be re-verified later.
  *   5. Orphan citations — every `<!-- harvest:<id> -->` marker under the
- *      scanned roots resolves to a ledger row.
+ *      scanned roots resolves to a row in either ledger.
+ *   6. Mechanism decisions — `provenance/mechanisms.jsonl`, the source-free
+ *      decision ledger: a closed shape with no source id, pin or locator
+ *      (council O5), adopt|adapt carrying existing `realised_in` paths, reject
+ *      carrying a reason, gap|deferred carrying a roadmap or `open`. A
+ *      mechanism may repeat — the ledger is append-only and a later row
+ *      supersedes an earlier one.
  *
  * An EMPTY ledger with zero markers is a legitimate pass and is reported as
  * such on stdout. A gate that scans nothing and exits green silently is
@@ -57,6 +63,7 @@ const _HERE = path.dirname(_FILE);
 // src/scripts/lint_harvest_provenance.ts → two levels up is the repo root.
 const REPO = path.resolve(_HERE, '..', '..');
 const LEDGER_REL = 'provenance/harvests.jsonl';
+const MECHANISMS_REL = 'provenance/mechanisms.jsonl';
 
 /** Roots scanned for citation markers. Markdown-bearing authored surfaces. */
 export const CITATION_SCAN_ROOTS: readonly string[] = [
@@ -102,11 +109,23 @@ export interface HarvestRecord {
     readonly verdict: 'adopt' | 'adapt';
 }
 
+export interface MechanismRecord {
+    readonly mechanism_id: string;
+    readonly verdict: 'adopt' | 'adapt' | 'reject' | 'already' | 'gap' | 'deferred';
+    readonly realised_in?: readonly string[];
+    readonly roadmap?: string;
+    readonly decided_at: string;
+    readonly reason?: string;
+    readonly reopen_if?: string;
+}
+
 export interface Finding {
     /** Ledger line number, or 0 for findings that belong to no single row. */
     readonly line: number;
-    readonly rule: 'schema' | 'uniqueness' | 'dead-row' | 'pinning' | 'orphan-citation';
+    readonly rule: 'schema' | 'uniqueness' | 'dead-row' | 'pinning' | 'orphan-citation' | 'verdict-requirement';
     readonly message: string;
+    /** The ledger the line number refers to; absent means the harvest ledger. */
+    readonly ledger?: string;
 }
 
 function isValidCalendarDate(s: string): boolean {
@@ -227,6 +246,100 @@ export function validateRecord(raw: unknown, line: number, repoRoot: string): Fi
     return findings;
 }
 
+const MECHANISM_FIELDS = ['mechanism_id', 'verdict', 'realised_in', 'roadmap', 'decided_at', 'reason', 'reopen_if'] as const;
+const MECHANISM_REQUIRED = ['mechanism_id', 'verdict', 'decided_at'] as const;
+const MECHANISM_VERDICTS: ReadonlySet<string> = new Set(['adopt', 'adapt', 'reject', 'already', 'gap', 'deferred']);
+
+/** `rel` (with an optional `:<line>`) is a repo-relative path that exists; else the finding. */
+function repoPathFinding(rel: string, field: string, line: number, repoRoot: string): Finding | null {
+    const bare = stripLineSuffix(rel);
+    const resolved = path.resolve(repoRoot, bare);
+    if (bare.trim() === '' || path.isAbsolute(bare) || !(resolved === repoRoot || resolved.startsWith(repoRoot + path.sep))) {
+        return { line, rule: 'schema', message: `${field} '${rel}' must be a repo-relative path inside the repo`, ledger: MECHANISMS_REL };
+    }
+    if (!fs.existsSync(resolved)) {
+        return { line, rule: 'dead-row', message: `${field} '${bare}' does not exist — the decision points at nothing`, ledger: MECHANISMS_REL };
+    }
+    return null;
+}
+
+/** Validate one `mechanisms.jsonl` row: closed and source-free, then the per-verdict requirement. */
+export function validateMechanismRecord(raw: unknown, line: number, repoRoot: string): Finding[] {
+    const at = (rule: Finding['rule'], message: string): Finding => ({ line, rule, message, ledger: MECHANISMS_REL });
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) return [at('schema', 'record is not a JSON object')];
+    const rec = raw as Record<string, unknown>;
+    const findings: Finding[] = [];
+
+    for (const k of Object.keys(rec)) {
+        if ((MECHANISM_FIELDS as readonly string[]).includes(k)) continue;
+        findings.push(
+            at(
+                'schema',
+                /source|pin|locator/.test(k)
+                    ? `field '${k}' links a source to a mechanism — the tracked decision ledger is source-free (council O5); it belongs in the local lineage ledger`
+                    : `unexpected field '${k}' — the ledger schema is closed to [${MECHANISM_FIELDS.join(', ')}]`,
+            ),
+        );
+    }
+    for (const k of MECHANISM_REQUIRED) if (!(k in rec)) findings.push(at('schema', `missing required field '${k}'`));
+
+    if ('mechanism_id' in rec && (typeof rec.mechanism_id !== 'string' || !HARVEST_ID_RE.test(rec.mechanism_id))) {
+        findings.push(at('schema', `mechanism_id must be a kebab-case slug, got ${JSON.stringify(rec.mechanism_id)}`));
+    }
+    if ('decided_at' in rec && !(typeof rec.decided_at === 'string' && isValidCalendarDate(rec.decided_at))) {
+        findings.push(at('schema', `decided_at must be an ISO-8601 date (YYYY-MM-DD), got ${JSON.stringify(rec.decided_at)}`));
+    }
+    for (const k of ['reason', 'reopen_if'] as const) {
+        if (k in rec && (typeof rec[k] !== 'string' || (rec[k] as string).trim().length < EVIDENCE_MIN_LENGTH)) {
+            findings.push(at('schema', `${k} must be at least ${EVIDENCE_MIN_LENGTH} characters`));
+        }
+    }
+    const realised = rec.realised_in;
+    if (realised !== undefined && (!Array.isArray(realised) || realised.length === 0 || realised.some((r) => typeof r !== 'string'))) {
+        findings.push(at('schema', 'realised_in must be a non-empty list of repo-relative paths'));
+    } else if (Array.isArray(realised)) {
+        for (const r of realised as string[]) {
+            const f = repoPathFinding(r, 'realised_in', line, repoRoot);
+            if (f) findings.push(f);
+        }
+    }
+    if ('roadmap' in rec) {
+        if (typeof rec.roadmap !== 'string') findings.push(at('schema', "roadmap must be a repo-relative path or 'open'"));
+        else if (rec.roadmap !== 'open') {
+            const f = repoPathFinding(rec.roadmap, 'roadmap', line, repoRoot);
+            if (f) findings.push(f);
+        }
+    }
+
+    const verdict = rec.verdict;
+    if ('verdict' in rec && (typeof verdict !== 'string' || !MECHANISM_VERDICTS.has(verdict))) {
+        findings.push(at('schema', `verdict must be one of [${[...MECHANISM_VERDICTS].join(', ')}], got ${JSON.stringify(verdict)}`));
+    } else if ((verdict === 'adopt' || verdict === 'adapt') && realised === undefined) {
+        findings.push(at('verdict-requirement', `verdict '${verdict}' needs realised_in — an adoption that lives nowhere is not one`));
+    } else if (verdict === 'reject' && !('reason' in rec)) {
+        findings.push(at('verdict-requirement', "verdict 'reject' needs a reason — a rejection without one is re-litigated on every round"));
+    } else if ((verdict === 'gap' || verdict === 'deferred') && !('roadmap' in rec)) {
+        findings.push(at('verdict-requirement', `verdict '${verdict}' needs a roadmap that owns it, or 'open'`));
+    }
+    return findings;
+}
+
+/** Parse + validate every mechanism row. Repeats are allowed: a later row supersedes. */
+export function lintMechanismsText(
+    text: string,
+    repoRoot: string,
+): { readonly records: MechanismRecord[]; readonly findings: Finding[] } {
+    const { parsed, findings: parseFindings } = parseLedgerText(text);
+    const findings: Finding[] = parseFindings.map((f) => ({ ...f, ledger: MECHANISMS_REL }));
+    const records: MechanismRecord[] = [];
+    for (const { line, value } of parsed) {
+        const f = validateMechanismRecord(value, line, repoRoot);
+        findings.push(...f);
+        if (f.length === 0) records.push(value as MechanismRecord);
+    }
+    return { records, findings };
+}
+
 // ─── ledger parsing ──────────────────────────────────────────────────────────
 
 export interface ParsedLine {
@@ -371,18 +484,19 @@ export function collectPersonaSources(repoRoot: string, personaRoot = 'src/agent
     return citations;
 }
 
-/** Every citation must resolve to a ledger row. */
+/** Every citation must resolve to a row in either ledger. */
 export function findOrphanCitations(
     citations: readonly Citation[],
     records: readonly HarvestRecord[],
+    mechanisms: readonly MechanismRecord[] = [],
 ): Finding[] {
-    const known = new Set(records.map((r) => r.harvest_id));
+    const known = new Set([...records.map((r) => r.harvest_id), ...mechanisms.map((m) => m.mechanism_id)]);
     return citations
         .filter((c) => !known.has(c.id))
         .map((c) => ({
             line: 0,
             rule: 'orphan-citation' as const,
-            message: `${c.file} cites harvest '${c.id}', which has no row in ${LEDGER_REL}`,
+            message: `${c.file} cites harvest '${c.id}', which has no row in ${LEDGER_REL} or ${MECHANISMS_REL}`,
         }));
 }
 
@@ -422,6 +536,7 @@ export function main(argv: string[] = process.argv.slice(2)): number {
     // the run would report a clean green over a file that no longer exists.
     try {
         assertWatchlistResolves({ gate: 'lint_harvest_provenance', candidates: [LEDGER_REL], repoRoot: REPO });
+        assertWatchlistResolves({ gate: 'lint_harvest_provenance', candidates: [MECHANISMS_REL], repoRoot: REPO });
     } catch (exc) {
         if (exc instanceof DeadScopeError) {
             process.stderr.write(`❌  ${exc.message}\n`);
@@ -432,9 +547,11 @@ export function main(argv: string[] = process.argv.slice(2)): number {
 
     const text = fs.readFileSync(ledgerPath, 'utf-8');
     const { records, findings } = lintLedgerText(text, REPO);
+    const mechText = fs.readFileSync(path.join(REPO, MECHANISMS_REL), 'utf-8');
+    const { records: mechanisms, findings: mechFindings } = lintMechanismsText(mechText, REPO);
     const citations = [...collectCitations(REPO), ...collectPersonaSources(REPO)];
-    const orphans = findOrphanCitations(citations, records);
-    const allFindings = [...findings, ...orphans];
+    const orphans = findOrphanCitations(citations, records, mechanisms);
+    const allFindings = [...findings, ...mechFindings, ...orphans];
 
     // Per-target completeness accounting over the two populations this gate
     // reasons about: the ledger's own rows, and the citations that point at
@@ -444,7 +561,7 @@ export function main(argv: string[] = process.argv.slice(2)): number {
     // failure the success message above already tries to talk its way out of in
     // prose. The ledger states it structurally instead.
     const ledger = new GateLedger('lint_harvest_provenance');
-    const known = new Set(records.map((r) => r.harvest_id));
+    const known = new Set([...records.map((r) => r.harvest_id), ...mechanisms.map((m) => m.mechanism_id)]);
     // The row population is every PARSED ledger line, not `records`: a row that
     // fails validation or uniqueness is `continue`d and never reaches `records`,
     // so planning `records` would plan exactly the rows that passed and account
@@ -452,8 +569,11 @@ export function main(argv: string[] = process.argv.slice(2)): number {
     // 100 %. Lines are the stable key; a Finding already carries one.
     const { parsed } = parseLedgerText(text);
     const badLines = new Set(findings.filter((f) => f.line > 0).map((f) => f.line));
+    const { parsed: mechParsed } = parseLedgerText(mechText);
+    const badMechLines = new Set(mechFindings.filter((f) => f.line > 0).map((f) => f.line));
     ledger.plan([
         ...parsed.map((r) => `row:${String(r.line)}`),
+        ...mechParsed.map((r) => `mechanism:${String(r.line)}`),
         ...citations.map((c) => `citation:${c.id}@${c.file}`),
     ]);
     for (const r of parsed) {
@@ -461,6 +581,11 @@ export function main(argv: string[] = process.argv.slice(2)): number {
         if (badLines.has(r.line)) ledger.fail(id, 'ledger-row finding');
         else ledger.complete(id);
     }
+    for (const r of mechParsed) {
+        const id = `mechanism:${String(r.line)}`;
+        if (badMechLines.has(r.line)) ledger.fail(id, 'mechanism-row finding');
+        else ledger.complete(id);
+    }
     for (const c of citations) {
         const id = `citation:${c.id}@${c.file}`;
         if (known.has(c.id)) ledger.complete(id);
@@ -470,7 +595,8 @@ export function main(argv: string[] = process.argv.slice(2)): number {
 
     if (allFindings.length > 0) {
         for (const f of allFindings) {
-            const at = f.line > 0 ? `${LEDGER_REL}:${f.line}` : LEDGER_REL;
+            const file = f.ledger ?? LEDGER_REL;
+            const at = f.line > 0 ? `${file}:${f.line}` : file;
             process.stderr.write(`❌  ${at}: [${f.rule}] ${f.message}\n`);
         }
         process.stderr.write(
@@ -484,7 +610,7 @@ export function main(argv: string[] = process.argv.slice(2)): number {
         // that does not distinguish "nothing to check" from "everything checked"
         // is the failure mode this repo has already paid for once.
         process.stdout.write(
-            `✅  lint_harvest_provenance: ${records.length} ledger row(s) OK · ` +
+            `✅  lint_harvest_provenance: ${records.length} ledger row(s) OK · ${mechanisms.length} mechanism row(s) OK · ` +
             `${citations.length} citation(s) resolved across ${CITATION_SCAN_ROOTS.length} scanned root(s)` +
             `${records.length === 0 && citations.length === 0 ? ' — ledger is empty and nothing cites it, which is a legitimate pass' : ''}\n`,
         );
@@ -514,4 +640,4 @@ if (_isCliEntry()) {
     }
 }
 
-export { REPO, LEDGER_REL, ExitCode };
+export { REPO, LEDGER_REL, MECHANISMS_REL, ExitCode };

package/src/scripts/lint_hook_manifest.ts

@@ -69,6 +69,7 @@ const DEFAULT_HOST_LOWERING = path.join(HOOKS_DIR, "host_lowering.yaml");
  * - `memory`       reads or writes the memory layer
  * - `notification` tells the human something and changes nothing else
  * - `formatting`   reshapes a command or a generated file
+ * - `execution`    starts a process that outlives the event it fired on
  */
 export const CONCERN_EFFECTS: ReadonlySet<string> = new Set([
   "permission",
@@ -78,6 +79,7 @@ export const CONCERN_EFFECTS: ReadonlySet<string> = new Set([
   "memory",
   "notification",
   "formatting",
+  "execution",
 ]);
 
 // Canonical event vocabulary — keep in lock-step with