@event4u/agent-config 14.21.0 → 14.23.0

package/src/scripts/_lib/continuity_writer.ts

@@ -0,0 +1,253 @@
+/**
+ * The deterministic continuity-record writer.
+ *
+ * `road-to-continuity-writer-activation` step 1.2. Until this module existed
+ * `agent-config session:recycle` was the ONLY writer of the continuity record
+ * in the tree, which is why `verb:session:recycle` counts on the
+ * `public_continuity_commands` axis and why an advisory has to tell a human to
+ * run it before `/clear`: continuity did not happen unless somebody
+ * remembered.
+ *
+ * Every field here is computed from on-disk state and nothing is asked of a
+ * model. That is not a cost optimisation, it is what makes the record a
+ * `continuity_record` rather than a `main_session` one: the judgement fields
+ * (`decisions`, `failed_approaches`, `successful_approaches`, …) are FORBIDDEN
+ * on the variant precisely so a deterministic writer cannot fill one with a
+ * guess and a reader cannot be left unable to tell a derived record from a
+ * judged one.
+ *
+ * Two gates, and both are needed:
+ *
+ *   1. `continuity.auto_record` must be `on`. It ships `off`, so with the
+ *      shipped default this module is never reached and the tree behaves
+ *      exactly as it does today.
+ *   2. The session must be SUBSTANTIVE by the committed floor
+ *      (`is_substantive`) and must have a resolvable task. Both come from the
+ *      concern's own counters and claim state, never from file presence.
+ *
+ * The task gate is the sharper of the two, and its bound is stated rather than
+ * hidden: a record needs at least one `acceptance_criteria` entry, and the only
+ * deterministic source of one in this tree is the roadmap a session has
+ * claimed. A session with no claim therefore leaves no record — and the
+ * alternative, writing a placeholder acceptance criterion, would assert a
+ * definition of "done" nobody set, which is the exact failure the variant's
+ * forbidden-key set exists to prevent.
+ */
+import * as fs from 'node:fs';
+
+import { load_agent_settings } from './agent_settings.js';
+import { resolvePredecessor } from './recycle_envelope_paths.js';
+import { CHECKBOX_LINE, phaseLines } from './roadmap_checkboxes.js';
+import { readHead, roadmapPath } from './run_checkpoint.js';
+import { is_substantive, type StoredEolCounters } from './session_eol.js';
+import { CAPSULE_SCHEMA_VERSION, MAX_ENTRIES, MAX_LINE_CHARS } from './subagent_capsule.js';
+
+/** Settings key that arms this writer. Ships `off`. */
+export const AUTO_RECORD_KEY = 'continuity.auto_record';
+
+/**
+ * Read `continuity.auto_record` from the merged settings cascade.
+ *
+ * The cascade merges the shipped template, so a workspace with no settings file
+ * resolves `off` through the template rather than through the trailing
+ * `return false` — which is why that line is defence against an unreadable
+ * cascade and not the path a default install takes. Both directions are pinned
+ * by fixtures, because "absent" and "off" arriving by different routes is
+ * exactly the kind of thing a reader assumes and a test has to establish.
+ */
+export function auto_record_enabled(root: string): boolean {
+    try {
+        const settings = load_agent_settings({ cwd: root });
+        const section = settings['continuity'];
+        if (section && typeof section === 'object' && !Array.isArray(section)) {
+            const v = (section as Record<string, unknown>)['auto_record'];
+            // YAML 1.1 parses a bare `on` as boolean true — accept both.
+            return v === 'on' || v === true;
+        }
+    } catch {
+        // fail-closed: unreadable settings leave the writer disarmed
+    }
+    return false;
+}
+
+/** Settings key that governs run-checkpoint production. Ships `on`. */
+export const RUN_CHECKPOINTS_KEY = 'continuity.run_checkpoints';
+
+/**
+ * Read `continuity.run_checkpoints` from the merged settings cascade.
+ *
+ * Fails OPEN, unlike its sibling above, and the asymmetry is the point: this
+ * switch governs behaviour the tree already had, so an unreadable cascade must
+ * leave it running. Its sibling arms something new, so an unreadable cascade
+ * must leave that disarmed. A single helper with one polarity would have been
+ * wrong for one of the two.
+ */
+export function run_checkpoints_enabled(root: string): boolean {
+    try {
+        const settings = load_agent_settings({ cwd: root });
+        const section = settings['continuity'];
+        if (section && typeof section === 'object' && !Array.isArray(section)) {
+            const v = (section as Record<string, unknown>)['run_checkpoints'];
+            if (v === 'off' || v === false) return false;
+        }
+    } catch {
+        // fail-open: an unreadable cascade never silently removes a recovery aid
+    }
+    return true;
+}
+
+/** Why no record was built, when none was. Always a stated reason. */
+export interface WriterDecision {
+    record: Record<string, unknown> | null;
+    reason: string;
+}
+
+/** How many `remaining` / `acceptance_criteria` lines a record carries. */
+const LIST_CAP = 12;
+
+function _clip(line: string): string {
+    const one = line.replace(/\s+/g, ' ').trim();
+    return one.length <= MAX_LINE_CHARS ? one : `${one.slice(0, MAX_LINE_CHARS - 1)}…`;
+}
+
+/**
+ * Open, closed and parked step counts plus the open step bodies.
+ *
+ * Deliberately reuses `phaseLines` + `CHECKBOX_LINE` rather than a fourth
+ * regex: a writer that disagreed with the dashboard about whether a roadmap is
+ * finished would put that disagreement into the record a successor resumes
+ * from.
+ */
+export function roadmapShape(text: string): { done: number; total: number; open: string[] } {
+    let done = 0;
+    let total = 0;
+    const open: string[] = [];
+    for (const raw of phaseLines(text)) {
+        const m = CHECKBOX_LINE.exec(raw);
+        if (m === null) continue;
+        total += 1;
+        const mark = m[1];
+        if (mark === 'x' || mark === 'X') {
+            done += 1;
+            continue;
+        }
+        if (mark === '~' || mark === '-') continue;
+        if (open.length < LIST_CAP) {
+            open.push(_clip((m[2] ?? '').replace(/\*\*/g, '')));
+        }
+    }
+    return { done, total, open };
+}
+
+/**
+ * Checkbox bodies under an `## Acceptance Criteria` heading.
+ *
+ * `phaseLines` deliberately excludes this section — an autonomous run must not
+ * mistake an acceptance criterion for its next step — so it is read separately
+ * here, which is the one place the two readings legitimately differ.
+ */
+export function acceptanceCriteria(text: string): string[] {
+    const lines = text.split('\n');
+    const out: string[] = [];
+    let inside = false;
+    for (const raw of lines) {
+        const heading = /^(#{2,3})[ \t]+(.*?)[ \t]*$/.exec(raw);
+        if (heading !== null) {
+            inside = /^Acceptance[ \t]+Criteria\b/i.test(heading[2] ?? '');
+            continue;
+        }
+        if (!inside) continue;
+        const m = CHECKBOX_LINE.exec(raw);
+        if (m === null) continue;
+        if (out.length < LIST_CAP) {
+            out.push(_clip((m[2] ?? '').replace(/\*\*/g, '')));
+        }
+    }
+    return out;
+}
+
+export interface BuildInput {
+    /** Workspace root — the record's `workspace`, and the root every read is relative to. */
+    root: string;
+    /** Raw session id, as the record paths and the claim state key on it. */
+    sessionId: string;
+    /** The roadmap slug this session claimed, or `null` when it claimed none. */
+    slug: string | null;
+    /** The concern's own counters for this session. */
+    counters: StoredEolCounters | null;
+    /** Injected for determinism in tests. */
+    now?: Date;
+}
+
+/**
+ * Build the record, or say why there is none.
+ *
+ * Never throws and never shells out: this runs on the Stop path, where a
+ * subprocess is a latency cost paid on every turn's end and an exception is
+ * worse than a missing record. `head` is read from `.git` directly (worktree
+ * aware) rather than through `git`, and the richer anchor fields
+ * `session:recycle` collects with `git status` are deliberately omitted — the
+ * trade is one drift line for a Stop path that spawns nothing, and it is stated
+ * in `docs/contracts/continuity-record-slot.md` rather than left for a reader
+ * to discover by diffing two producers.
+ */
+export function buildContinuityRecord(input: BuildInput): WriterDecision {
+    const { root, sessionId, slug, counters } = input;
+    const now = input.now ?? new Date();
+
+    if (!is_substantive(counters)) {
+        return {
+            record: null,
+            reason: 'no record — the session is not substantive by the committed floor',
+        };
+    }
+    if (slug === null || slug.trim() === '') {
+        return {
+            record: null,
+            reason: 'no record — no claimed roadmap, so no deterministic acceptance criterion exists',
+        };
+    }
+
+    let text: string;
+    try {
+        text = fs.readFileSync(roadmapPath(root, slug), 'utf-8');
+    } catch {
+        return { record: null, reason: `no record — the claimed roadmap ${slug} is not readable` };
+    }
+
+    const shape = roadmapShape(text);
+    if (shape.total === 0) {
+        return { record: null, reason: `no record — ${slug} carries no phase checkboxes to count` };
+    }
+
+    const declared = acceptanceCriteria(text);
+    const criteria =
+        declared.length > 0
+            ? declared
+            : // A roadmap with no declared criteria still has one definitional
+              // completion condition, and it is derived from the artefact class
+              // rather than judged: every step closed. Anything richer would be
+              // a definition of done nobody wrote.
+              [`every phase step in agents/roadmaps/${slug}.md is closed`];
+
+    const record: Record<string, unknown> = {
+        capsule_version: CAPSULE_SCHEMA_VERSION,
+        variant: 'continuity_record',
+        summary: _clip(`${slug}: ${shape.done} of ${shape.total} steps closed`),
+        task: _clip(slug),
+        workspace: root,
+        written_at: now.toISOString(),
+        acceptance_criteria: criteria.slice(0, MAX_ENTRIES),
+        remaining: shape.open.slice(0, MAX_ENTRIES),
+        predecessor: resolvePredecessor(root, sessionId),
+        artifact_paths: [`agents/roadmaps/${slug}.md`],
+    };
+    if (sessionId.trim() !== '') {
+        record['session_id'] = sessionId.trim();
+    }
+    const head = readHead(root);
+    if (head !== null) {
+        record['head'] = head;
+    }
+    return { record, reason: `record built for ${slug} (${shape.done}/${shape.total} closed)` };
+}

package/src/scripts/_lib/corpus_manifest.ts

@@ -46,7 +46,19 @@ import {
 import { isExclusivelyPackageOnly } from '../../install/partitionEligibility.js';
 import { dedupableRules } from '../../install/ruleLayerPartition.js';
 
-export const CORPUS_MANIFEST_VERSION = 'corpus-manifest-v1';
+/**
+ * Bumped to v2 on 2026-09-07 with the `partition_active` -> `host_layer_verified`
+ * rename, after a neutral review named the alternative: `parseManifest` accepts
+ * any object carrying the declared version and validates three fields, and
+ * `diffManifests` compares with `String(e) !== String(a)`. So a v1 manifest
+ * (which has `partition_active` and no `host_layer_verified`) compared against
+ * another v1 yields `"undefined" === "undefined"` on the renamed field — NO
+ * difference reported, on a field neither side has. That is verbatim the failure
+ * `parseManifest`'s own error text says the version check exists to prevent:
+ * "comparing it partially would report equivalence from the fields that happened
+ * to survive". A rename inside a frozen version is exactly that.
+ */
+export const CORPUS_MANIFEST_VERSION = 'corpus-manifest-v2';
 
 /** The tool directory the experiment's corpus is enumerated from. */
 export const CORPUS_TOOL_DIR = '.claude/rules';
@@ -142,7 +154,7 @@ export interface ProjectionDecision {
      * `null` is the default and is the honest value for a capture that cannot
      * establish it. Every other field in this struct is a function of the
      * `(repoRoot, userHome)` pair the capture was given; this one is not.
-     * `partitionActive` resolves through `resolvePartitionVerdict`, which reads
+     * `hostLayerVerified` resolves through `resolveHostLayerVerdict`, which reads
      * the host layer at `os.homedir()` and the install lockfile at its own
      * fixed location — ignoring `userHome` entirely — and memoises the answer
      * for the life of the process. So a capture over a temporary tree that
@@ -150,7 +162,7 @@ export interface ProjectionDecision {
      * one process would reuse the first verdict. A caller for which those
      * globals ARE the run's own host supplies the predicate; nobody else does.
      */
-    readonly partition_active: boolean | null;
+    readonly host_layer_verified: boolean | null;
     readonly tool_id: string | null;
     /** The global layer directory, home-relative; `null` when this host has none. */
     readonly layer_dir: string | null;
@@ -365,7 +377,7 @@ export interface ProjectionDecisionOptions {
      * The host partition verdict, supplied by a caller for which the process
      * globals it reads are this run's own host. Omitted → `null`.
      */
-    readonly partitionActive?: ((repoRoot: string) => boolean) | undefined;
+    readonly hostLayerVerified?: ((repoRoot: string) => boolean) | undefined;
 }
 
 export function captureProjectionDecision(
@@ -401,7 +413,8 @@ export function captureProjectionDecision(
             sha256: layerPath === null ? null : sha256OfFile(path.join(layerPath, n)),
         }));
     return {
-        partition_active: opts.partitionActive === undefined ? null : opts.partitionActive(repoRoot),
+        host_layer_verified:
+            opts.hostLayerVerified === undefined ? null : opts.hostLayerVerified(repoRoot),
         tool_id: toolId,
         layer_dir: layerPath === null ? null : homeRelative(layerPath, userHome),
         carries: verdict.carries,
@@ -451,8 +464,8 @@ export interface CaptureOptions {
     readonly limit: number;
     readonly enumerationRule: string;
     readonly env?: Readonly<Record<string, string | undefined>> | undefined;
-    /** See {@link ProjectionDecisionOptions.partitionActive}. Omitted → `null`. */
-    readonly partitionActive?: ((repoRoot: string) => boolean) | undefined;
+    /** See {@link ProjectionDecisionOptions.hostLayerVerified}. Omitted → `null`. */
+    readonly hostLayerVerified?: ((repoRoot: string) => boolean) | undefined;
     /** See {@link UserScopeOptions.ruleNames}. Omitted → the projection-source superset. */
     readonly ruleNames?: readonly string[] | undefined;
 }
@@ -531,7 +544,7 @@ export function captureManifest(opts: CaptureOptions): CorpusManifest {
         user_scope_population:
             opts.ruleNames === undefined ? 'projection-source-superset' : 'caller-supplied',
         projection: captureProjectionDecision(repoRoot, userHome, {
-            partitionActive: opts.partitionActive,
+            hostLayerVerified: opts.hostLayerVerified,
         }),
         generator_config: generatorConfig,
         runtime: { node: process.version, platform: os.platform(), arch: os.arch() },
@@ -656,7 +669,11 @@ export function diffManifests(expected: CorpusManifest, actual: CorpusManifest):
     // The partition half, which is where the observed skips actually came from.
     // Diffed by digest rather than by name list because the inventory runs to
     // three figures and a diff nobody reads is a diff that does not exist.
-    push('projection.partition_active', expected.projection.partition_active, actual.projection.partition_active);
+    push(
+        'projection.host_layer_verified',
+        expected.projection.host_layer_verified,
+        actual.projection.host_layer_verified,
+    );
     push('projection.carries', expected.projection.carries, actual.projection.carries);
     push('projection.reason', expected.projection.reason, actual.projection.reason);
     push('projection.layer_digest', expected.projection.layer_digest, actual.projection.layer_digest);

package/src/scripts/_lib/hook_settings.ts

@@ -3,7 +3,7 @@
  * `.agent-settings.yml` without dragging a YAML parser into a hook.
  *
  * Every default-OFF hook needs the same two-level lookup, and the tree already
- * carries two hand-rolled copies of it (`code_graph_nudge_hook.enabled` and the
+ * carries two hand-rolled copies of it (`code_graph_context_hook (no flag)` and the
  * equivalent inside `design_slop_hook`). Adding a third copy for the route
  * nudge is what this file prevents; the two existing copies are pre-existing
  * duplication and are deliberately left alone — folding them in is a separate,
@@ -110,3 +110,88 @@ export function leanProjectionModeRaw(root: string): string {
     }
     return '';
 }
+
+/**
+ * Raw `lean_projection.hosts` list out of `.agent-settings.yml`, or `[]`.
+ *
+ * Same indentation-shaped discipline as `leanProjectionModeRaw` above and for
+ * the same reason — a hook must never fail a tool call because a YAML parser
+ * could not load — extended to the three list shapes a human writes:
+ *
+ *     lean_projection:
+ *       hosts: [claude-code]          # inline
+ *     lean_projection:
+ *       hosts:                        # block, indented under the key
+ *         - claude-code
+ *     lean_projection:
+ *       hosts:                        # block, at the key's own indent
+ *       - claude-code
+ *
+ * All three are legal YAML and `js-yaml` loads them identically; the third was
+ * read as `[]` until 2026-09-08 (R2 finding 2) and is covered by three fixtures
+ * in `tests/scripts/lean_projection_hosts.test.ts`.
+ *
+ * Interpretation is NOT done here. `[]` means "nothing was written", and
+ * `_lib/lean_projection_mode.ts::resolveLeanProjectionHosts` decides that this
+ * means the default rather than "no host" — keeping that decision in one place
+ * is what stops the projector and the delivery concern from disagreeing, which
+ * is the whole reason the mode reader is split this way.
+ */
+export function leanProjectionHostsRaw(root: string): string[] {
+    const file = path.join(root, SETTINGS_FILE);
+    let text: string;
+    try {
+        if (!fs.statSync(file).isFile()) return [];
+        text = fs.readFileSync(file, 'utf-8');
+    } catch {
+        return [];
+    }
+    const strip = (s: string): string => s.trim().replace(/^["']|["']$/g, '');
+    let inSection = false;
+    let inBlock = false;
+    let blockIndent = -1;
+    const out: string[] = [];
+    for (const raw of text.split(/\r\n|\r|\n/)) {
+        const line = raw.replace(/\s+$/, '');
+        if (!line || line.replace(/^\s+/, '').startsWith('#')) continue;
+        if (!(line.startsWith(' ') || line.startsWith('\t'))) {
+            inSection = /^lean_projection\s*:\s*$/.test(line);
+            inBlock = false;
+            continue;
+        }
+        if (!inSection) continue;
+        const indent = (/^\s*/.exec(line) as RegExpExecArray)[0].length;
+        if (inBlock) {
+            const item = /^\s*-\s*(\S.*)$/.exec(line);
+            // `>=`, not `>`: YAML lets a block sequence sit at its KEY's own
+            // indent, and `js-yaml` — the parser `condense` uses on this same
+            // file — loads that shape identically to the deeper-indented one.
+            // With `>` the same-indent form parsed as `[]`, which
+            // `resolveLeanProjectionHosts` reads as "nothing was written" and
+            // answers with the default `[claude-code]` while the projector
+            // thins whatever the file actually says. Two readers disagreeing
+            // about the delivery-host set is the one failure this split exists
+            // to prevent (R2 finding 2). A SHALLOWER item still ends the block:
+            // it belongs to a different mapping level, never to `hosts`.
+            if (item !== null && indent >= blockIndent) {
+                const v = strip(item[1] ?? '');
+                if (v !== '') out.push(v);
+                continue;
+            }
+            inBlock = false;
+        }
+        const inline = /^\s+hosts\s*:\s*\[([^\]]*)\]\s*$/.exec(line);
+        if (inline !== null) {
+            for (const part of (inline[1] ?? '').split(',')) {
+                const v = strip(part);
+                if (v !== '') out.push(v);
+            }
+            continue;
+        }
+        if (/^\s+hosts\s*:\s*$/.test(line)) {
+            inBlock = true;
+            blockIndent = indent;
+        }
+    }
+    return out;
+}

package/src/scripts/_lib/injection_effect.ts

@@ -0,0 +1,151 @@
+/**
+ * Does a delivered rule body actually reach the model's context on this host?
+ *
+ * `road-to-delivery-on-hook-hosts` step 1.1, and the record owner ruling E3
+ * admits a host on.
+ *
+ * THE ONE THING THIS MODULE EXISTS TO REFUSE
+ * ------------------------------------------
+ * A host that BINDS `user_prompt_submit` looks, from every artefact in this
+ * tree, exactly like a host that DELIVERS. Cowork is the proof that they are
+ * different: it binds eight slots and its trampoline discards dispatcher output
+ * and `exit 0`s (`docs/enforcement-by-host.md:21`). Cursor and Cline bind the
+ * same slot the delivery concern needs, and whether their hook stdout reaches
+ * the model is unmeasured.
+ *
+ * So the binding is computable and the effect is not. This module keeps them
+ * apart by construction:
+ *
+ *   · `emits`             — computed. Is the concern bound on the slot at all?
+ *                           Read from the manifest. Cheap, always available,
+ *                           and NEVER promoted to an observation.
+ *   · `injection_effect`  — observed. Did a model visibly act on a delivered
+ *                           body? Read from a committed record and from nowhere
+ *                           else. There is no code path that derives it.
+ *
+ * An `observed-*` value is admissible only with the four-part citation the
+ * host-capability observation protocol requires (host · host version ·
+ * transcript or artefact reference · date) — see
+ * `_lib/host_capability.ts:183`. A record missing any part is rejected rather
+ * than downgraded, because a half-cited observation is the shape that gets
+ * quoted as a whole one.
+ *
+ * `unobserved` is a RESULT, not a gap. Most hosts cannot be observed from a
+ * Claude Code session at all, and the roadmap's K6 makes that an outcome: the
+ * host keeps its full rule bodies and loses nothing while it waits.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/** Where the committed observations live. One file, so there is one place to audit. */
+export const RECORD_REL = path.join('src', 'config', 'host-injection-effect.json');
+
+/**
+ * The three states, and the reason there is no fourth.
+ *
+ * `observed-false` is not "probably not" — it is a recorded observation that a
+ * delivered body did NOT reach the model, which is as citable as the positive.
+ * Anything not observed in either direction is `unobserved`.
+ */
+export const INJECTION_STATES = ['observed-true', 'observed-false', 'unobserved'] as const;
+export type InjectionState = (typeof INJECTION_STATES)[number];
+
+export interface InjectionObservation {
+    readonly state: InjectionState;
+    /** Host version the observation was taken on. Required for an `observed-*` state. */
+    readonly host_version: string | null;
+    /** Transcript or artefact reference. Required for an `observed-*` state. */
+    readonly transcript: string | null;
+    /** ISO date of the observation. Required for an `observed-*` state. */
+    readonly date: string | null;
+    /** Why it reads the way it does — required always, including for `unobserved`. */
+    readonly reason: string;
+}
+
+export type InjectionRecord = Readonly<Record<string, InjectionObservation>>;
+
+/** A malformed or under-cited row, in the words a maintainer needs to fix it. */
+export interface InjectionProblem {
+    readonly host: string;
+    readonly message: string;
+}
+
+/**
+ * Validate a record.
+ *
+ * The citation requirement is enforced HERE rather than at the reader, so every
+ * consumer gets the same answer: an `observed-*` row without all three citation
+ * fields is a problem, and `unobserved` needs only its reason.
+ */
+export function recordProblems(rec: InjectionRecord): InjectionProblem[] {
+    const out: InjectionProblem[] = [];
+    for (const [host, obs] of Object.entries(rec)) {
+        // A leading `_comment` is the convention every config JSON in this tree
+        // uses to carry its own contract, and it is not a host row. Skipping the
+        // underscore prefix rather than a literal `_comment` keeps a second
+        // annotation key from becoming a fake host with a fake verdict.
+        if (host.startsWith('_')) continue;
+        if (!(INJECTION_STATES as readonly string[]).includes(obs.state)) {
+            out.push({ host, message: `state ${JSON.stringify(obs.state)} is not one of ${INJECTION_STATES.join(' | ')}` });
+            continue;
+        }
+        if (typeof obs.reason !== 'string' || obs.reason.trim().length < 20) {
+            out.push({ host, message: 'reason is missing or shorter than 20 characters — an unexplained row reads as answered' });
+        }
+        if (obs.state === 'unobserved') continue;
+        for (const field of ['host_version', 'transcript', 'date'] as const) {
+            const v = obs[field];
+            if (typeof v !== 'string' || v.trim() === '') {
+                out.push({
+                    host,
+                    message:
+                        `state ${obs.state} without \`${field}\` — the observation protocol ` +
+                        '(host · host version · transcript · date) admits no partial citation',
+                });
+            }
+        }
+    }
+    return out;
+}
+
+/** Load the committed record. A missing file is an empty record, never a throw. */
+export function loadRecord(root: string): InjectionRecord {
+    try {
+        return JSON.parse(fs.readFileSync(path.join(root, RECORD_REL), 'utf-8')) as InjectionRecord;
+    } catch {
+        return {};
+    }
+}
+
+/**
+ * The state for one host — `unobserved` when the record says nothing.
+ *
+ * Defaulting to `unobserved` rather than to a computed guess is the whole
+ * contract: a host nobody has looked at must never inherit a neighbour's
+ * verdict, and a bound slot must never imply a delivered body.
+ */
+export function stateFor(rec: InjectionRecord, host: string): InjectionState {
+    return rec[host]?.state ?? 'unobserved';
+}
+
+/**
+ * Is the concern bound on this host's slot? Computed from the manifest.
+ *
+ * Deliberately a separate function from `stateFor`, with a name that cannot be
+ * mistaken for it. This answers "could a body be emitted here", never "did one
+ * arrive".
+ */
+export function concernBound(
+    platforms: Readonly<Record<string, Readonly<Record<string, readonly string[]>>>>,
+    host: string,
+    slot: string,
+    concern: string,
+): boolean {
+    return (platforms[host]?.[slot] ?? []).includes(concern);
+}
+
+/** Does this host admit to `lean_projection.hosts` under E3? Observation only. */
+export function admissibleUnderE3(rec: InjectionRecord, host: string): boolean {
+    return stateFor(rec, host) === 'observed-true';
+}

package/src/scripts/_lib/layer_overlap_notice.ts

@@ -54,12 +54,16 @@ const TYPES = ['rules', 'skills', 'commands', 'personas', 'user-types', 'agents'
 export function overlapFindings(homeDir: string, projectRoot: string): string[] {
     const findings: string[] = [];
     for (const type of TYPES) {
-        let g: string[];
-        let p: string[];
-        try {
-            g = fs.readdirSync(path.join(homeDir, '.claude', type));
-            p = fs.readdirSync(path.join(projectRoot, '.claude', type));
-        } catch {
+        // `commands` keys on the POSIX SUBPATH, matching
+        // `check_single_delivery`'s own key. Top-level names are the CLUSTER, and
+        // since per-name withholding (2026-09-07) the project layer holds exactly
+        // the commands the host lacks — which can share a cluster with commands the
+        // host has. Observed the same day: `analyze/` in both layers over two
+        // disjoint command sets, reported here as `commands=1`. This notice and
+        // that gate must not disagree about the same question.
+        const g = _entries(path.join(homeDir, '.claude', type), type === 'commands');
+        const p = _entries(path.join(projectRoot, '.claude', type), type === 'commands');
+        if (g === null || p === null) {
             continue;
         }
         const gset = new Set(g);
@@ -69,6 +73,46 @@ export function overlapFindings(homeDir: string, projectRoot: string): string[]
     return findings;
 }
 
+/**
+ * One layer's entry names — top level, or every `*.md` subpath when `recursive`.
+ *
+ * `null` means the directory is not readable, which the caller must treat as "skip
+ * this type": one layer absent means nothing is doubled there.
+ */
+function _entries(dir: string, recursive: boolean): string[] | null {
+    if (!recursive) {
+        try {
+            return fs.readdirSync(dir);
+        } catch {
+            return null;
+        }
+    }
+    let top: fs.Dirent[];
+    try {
+        top = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+        return null;
+    }
+    const out: string[] = [];
+    const walk = (kids: fs.Dirent[], abs: string, rel: string): void => {
+        for (const k of kids) {
+            const childRel = rel === '' ? k.name : `${rel}/${k.name}`;
+            if (k.isDirectory()) {
+                try {
+                    walk(fs.readdirSync(path.join(abs, k.name), { withFileTypes: true }), path.join(abs, k.name), childRel);
+                } catch {
+                    // An unreadable subdirectory contributes no names; the layer
+                    // itself was readable, so the type stays compared.
+                }
+            } else if (k.name.endsWith('.md') && k.name !== 'README.md') {
+                out.push(childRel);
+            }
+        }
+    };
+    walk(top, dir, '');
+    return out;
+}
+
 /** Render the notice, or `null` when there is nothing to say. */
 export function overlapNotice(homeDir: string, projectRoot: string): string | null {
     const findings = overlapFindings(homeDir, projectRoot);