@event4u/agent-config 14.6.0 → 14.8.0

package/src/scripts/check_single_delivery.ts

@@ -29,13 +29,36 @@
  *      correctness fact rather than a token fact, and it needs a different
  *      remedy, so it is never folded into the overlap number.
  *
- * REPORT BY DEFAULT, ENFORCE ON REQUEST — and that is not timidity. The
- * invariant is not true yet: `road-to-single-delivery` Phase 2, which makes the
- * producers write disjoint layers, is HALTED on blocker
- * `partition-requires-global-layer`. A blocking default would therefore red every
- * run on a defect nobody can currently fix, which teaches readers to ignore it —
- * the exact failure this estate has recorded twice already. Pass `--enforce` once
- * Phase 2 lands.
+ * REPORT BY DEFAULT, ENFORCE ON REQUEST — and that is not timidity. A blocking
+ * default would red every run on a defect a given machine may not be able to
+ * fix, which teaches readers to ignore it — the exact failure this estate has
+ * recorded twice already.
+ *
+ * The reason used to be that `road-to-single-delivery` Phase 2 was HALTED on
+ * blocker `partition-current-layer-undecidable`. That is no longer true and the
+ * sentence is corrected rather than left standing: the blocker reads
+ * `**Status:** resolved`, its roadmap is archived, and the partition shipped
+ * under ADR-236 Phase 2. What replaced the halt is a per-machine activation —
+ * the partition withholds artefacts only where the host layer is verified
+ * against `installed.lock`, so a machine whose install predates the fingerprint
+ * keeps the full projection BY DESIGN and the overlap this gate reports there is
+ * the fail-safe working, not a regression.
+ *
+ * WHERE THIS CHECK IS MEANINGFUL — read this before quoting one of its numbers
+ * (road-to-session-closeout 3.3). It is a DEVELOPER-MACHINE check. It reads two
+ * host layers off the filesystem, and in CI both are absent: a fresh checkout
+ * carries no `<project>/.claude/**` (zero tracked files under `.claude/`) and no
+ * `~/.claude/**` because no CI leg installs at user scope. So in CI this gate
+ * finds zero layers and has nothing to compare — which is reported as `absent`
+ * rather than as a pass, per the paragraph below, but is still not a statement
+ * about any developer's machine.
+ *
+ * How large that gap is, measured on ONE tree in ONE session on 2026-08-20:
+ * `check_standing_rule_delivery` read the same repository twice and reported
+ * 115 781 tok with one layer installed and 209 767 tok with two — a 1.8x
+ * difference produced entirely by which layers existed where. Any figure from
+ * this gate or that one describes the machine it ran on. Cite it with the layer
+ * counts attached, never as a repository property.
  *
  * A LAYER THAT DOES NOT EXIST IS NOT A PASS. Where a layer is absent there is no
  * overlap to find, and saying "invariant holds" would be a gate reading nothing
@@ -51,13 +74,65 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { reportScanned } from './_lib/scan_scope.js';
 
+// ledger-exempt: this gate has no skip semantics to account for. `_lib/gate_ledger`
+// exists so a gate that PASSES OVER targets says which and why; here the target set
+// is six fixed artefact types, every one of them appears in the output, and a type
+// whose layer is missing is printed as `absent` rather than quietly dropped — see
+// the `absent` field and the `types_compared=N of 6` ledger line, which together
+// already carry what a per-target ledger would. Adding one would restate the render
+// in a second format, and the gate's own docstring warns that the degenerate pass
+// here is a marker with no argument behind it. If a future version gains a real skip
+// path — a type it declines to compare for a reason — this exemption is void and the
+// ledger is the right answer.
+
 const _HERE = fileURLToPath(import.meta.url);
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 
-/** Artefact types the host loads from both layers. */
-const TYPES = ['rules', 'skills', 'commands', 'agents'] as const;
+/**
+ * Artefact types the host loads from both layers.
+ *
+ * ## The identity key, named because it is not the same for every row
+ *
+ * Every row below compares BASENAMES within one family directory. For `rules`,
+ * `personas`, `user-types` and `agents` that IS the host's unit, so basename
+ * equality is the right key. For `commands` it is not: the host-visible unit is
+ * the invocation name `/cluster:sub`, which the colon form encodes in the PATH
+ * (`commands/<cluster>/<sub>.md`), so this gate's `commands` row compares cluster
+ * DIRECTORY names — a coarser key than the thing the host registers.
+ *
+ * That gap is recorded rather than closed, and the reason is a measurement: since
+ * `commandsWithheld` gates the colon-form generator, a machine with a verified
+ * host layer projects ZERO commands, so there is no project-side name for the
+ * coarse key to be wrong about. On a machine WITHOUT one, the project layer is
+ * the only layer and there is nothing to compare. The key is therefore imprecise
+ * exactly where it has no work to do. Closing it would mean reading each command
+ * file's own slug — real work for a row whose overlap is 0 in both topologies.
+ *
+ * `personas` and `user-types` were added 2026-08-21 (closure correction). See
+ * `unknownProjectFamilies` for what now prevents the next omission.
+ */
+const TYPES = ['rules', 'skills', 'commands', 'personas', 'user-types', 'agents'] as const;
 type ArtefactType = (typeof TYPES)[number];
 
+/**
+ * Directory names under `<repo>/.claude/` that the HOST writes, not a generator.
+ *
+ * `unknownProjectFamilies` used to rest on the premise that `<repo>/.claude/` is
+ * "written by `condense.ts` generators and nothing else". That premise is false
+ * and the gate proved it on 2026-08-22, refusing a release push over
+ * `.claude/worktrees/` — the maintainer's git-worktree root, gitignored at
+ * `.gitignore:246`, named as a conventional worktree location by
+ * `worktree_cleanup_check.STANDARD_WORKTREE_DIRS`, and excluded from
+ * `inventory_abstraction_budget`. Nothing about it is an artefact family, so
+ * "add it to TYPES" was advice that could not be taken.
+ *
+ * The set is hand-written and stays independent of any producer registry, for
+ * the same reason `TYPES` is: a verifier that derives its scope from a producer
+ * inherits that producer's omissions. It grows only on tree evidence that a name
+ * is host state — never to silence a family a generator actually emits.
+ */
+const HOST_OWNED = new Set(['worktrees']);
+
 /**
  * What a layer's entries physically ARE — symlinks, directories, or regular files.
  *
@@ -239,6 +314,54 @@ export interface Verdict {
     namesRead: number;
     /** True when no type had BOTH layers present — nothing was actually compared. */
     readNothing: boolean;
+    /**
+     * Family directories present in the PROJECT layer that `TYPES` does not name.
+     *
+     * The forcing function that makes this gate's own 2026-08-21 omission
+     * non-recurring: `personas` was written by a generator, shipped by the
+     * installer, and named by neither measurer, so it was invisible rather than
+     * reported — a gate cannot report a family it was never told exists.
+     *
+     * Only the PROJECT layer is scanned, and that is the whole reason this can be
+     * a hard refusal rather than a warning. Every entry in `<repo>/.claude/` is a
+     * family this repository chose to emit, EXCEPT the host-written names in
+     * `HOST_OWNED` — see that constant for why the unqualified version of this
+     * sentence was wrong. `~/.claude/` is the host's own directory —
+     * `plugins`, `projects`, `sessions`, `shell-snapshots`, `telemetry` and a
+     * dozen more live there — and treating an unrecognised name in it as a defect
+     * would be a false-positive generator, not a check.
+     */
+    unknownFamilies: string[];
+}
+
+/**
+ * Family directories the project layer holds that `TYPES` does not name.
+ *
+ * Deliberately NOT derived from the installer's `_CLAUDE_SKILL_BUNDLE` or from
+ * `check_generator_output_coverage`'s registry: a verifier whose scope comes from
+ * a producer inherits that producer's omissions, which is the exact defect this
+ * function exists to catch. `TYPES` stays hand-written and independent; this
+ * compares it against the filesystem the generators actually produced and refuses
+ * on disagreement.
+ */
+function unknownProjectFamilies(projectRoot: string): string[] {
+    const known = new Set<string>(TYPES);
+    let entries: fs.Dirent[];
+    try {
+        entries = fs.readdirSync(projectRoot, { withFileTypes: true });
+    } catch {
+        return []; // no project layer at all — nothing emitted, nothing to miss
+    }
+    return entries
+        .filter(
+            (e) =>
+                e.isDirectory() &&
+                !e.name.startsWith('.') &&
+                !known.has(e.name) &&
+                !HOST_OWNED.has(e.name),
+        )
+        .map((e) => e.name)
+        .sort();
 }
 
 export function evaluate(globalRoot: string, projectRoot: string): Verdict {
@@ -265,6 +388,7 @@ export function evaluate(globalRoot: string, projectRoot: string): Verdict {
             0,
         ),
         readNothing: compared === 0,
+        unknownFamilies: unknownProjectFamilies(projectRoot),
     };
 }
 
@@ -320,12 +444,24 @@ export function render(v: Verdict, globalRoot: string, projectRoot: string): str
         out.push('');
         out.push(`  layers not present (nothing to compare there): ${v.absent.join(', ')}`);
     }
+    if (v.unknownFamilies.length > 0) {
+        out.push('');
+        out.push(
+            `  ❌  unknown family in the project layer: ${v.unknownFamilies.join(', ')}` +
+                ' — add it to TYPES in this gate AND in _lib/layer_overlap_notice.ts,',
+        );
+        out.push(
+            '      or the next family shipped from two layers is invisible the way `personas`' +
+                ' was until 2026-08-21.',
+        );
+    }
     out.push('');
     out.push(
         `check_single_delivery ledger: duplicated=${v.duplicated}` +
             ` name_overlap_different_shape=${v.nameOverlapDifferentShape}` +
             ` scope_defeat=${v.defeated}` +
             ` types_compared=${v.typesCompared} of ${v.readings.length}` +
+            ` unknown_families=${v.unknownFamilies.length}` +
             ` names_read=${v.namesRead}`,
     );
     return out.join('\n');
@@ -336,6 +472,7 @@ export function main(argv?: readonly string[]): number {
     let globalRoot = path.join(os.homedir(), '.claude');
     let projectRoot = path.join(REPO_ROOT, '.claude');
     let enforce = false;
+    let quiet = false;
 
     const value = (i: number): string | null => {
         const v = args[i + 1];
@@ -354,13 +491,20 @@ export function main(argv?: readonly string[]): number {
             i += 1;
         } else if (a === '--enforce') {
             enforce = true;
+        } else if (a === '--quiet') {
+            // R2 finding: the full per-type table is ~30 lines, and preflight is a
+            // `silent: true` task. A gate that floods a quiet chain is a gate people
+            // learn to scroll past, which is the same end state as an unbound one.
+            quiet = true;
         } else if (a === '--help' || a === '-h') {
             process.stdout.write(
-                'usage: check_single_delivery [--global DIR] [--project DIR] [--enforce]\n' +
+                'usage: check_single_delivery [--global DIR] [--project DIR] [--enforce] [--quiet]\n' +
                     '\n' +
-                    'Reports by default and exits 0: the invariant is not true yet, because\n' +
-                    'road-to-single-delivery Phase 2 is halted on partition-requires-global-layer.\n' +
-                    '--enforce exits 1 on any overlap, and is what to register once Phase 2 lands.\n',
+                    'Reports by default and exits 0: the partition SHIPPED (ADR-236, Phase 2)\n' +
+                    'but activates per machine — only where a verified host layer exists, so a\n' +
+                    'checkout without one keeps the full projection BY DESIGN and reports overlap.\n' +
+                    '--enforce exits 1 on any overlap; registering it would fail every machine\n' +
+                    'that has not re-run `agent-config install`, which is why it stays opt-in.\n',
             );
             return 0;
         } else if (a !== undefined) {
@@ -379,7 +523,7 @@ export function main(argv?: readonly string[]): number {
     }
 
     const v = evaluate(globalRoot, projectRoot);
-    process.stdout.write(`${render(v, globalRoot, projectRoot)}\n`);
+    if (!quiet) process.stdout.write(`${render(v, globalRoot, projectRoot)}\n`);
     // Dead-scope assertion via the shared primitive rather than a hand-rolled
     // `scanned:` line: `check_gate_coverage`'s hardening ratchet accepts an
     // emitted line only from a gate registered in the enforced manifest, and this
@@ -417,6 +561,37 @@ export function main(argv?: readonly string[]): number {
             ' case (layers present but never paired) is refused separately.',
     });
 
+    // Refuses in both modes, unlike every other branch here — but ONLY over this
+    // repository's own generated tree, and that qualification was added by a
+    // neutral review (2026-08-21) rather than being there from the start.
+    //
+    // The asymmetry is the argument for the refusal: every other verdict here is
+    // a property of ONE MACHINE's two layers, which is why `--enforce` is opt-in.
+    // "this repository emits a family no measurer names" is true on every checkout
+    // and fixable in one line, so gating it behind `--enforce` would put the one
+    // topology-independent check behind the flag meant for topology-dependent
+    // ones.
+    //
+    // The qualification is the review's, and it is right: an unrecognised
+    // DIRECTORY does not by itself establish generator ownership. It does under
+    // `<repo>/.claude/`, which `condense.ts` writes and nothing else does. It does
+    // NOT under an arbitrary `--project` path, which may be a consumer tree with
+    // a host-native or project-only family that legitimately cannot overlap — and
+    // refusing there would make a nominal report exit 1 on a correct topology.
+    // So a repointed root REPORTS and does not refuse.
+    if (v.unknownFamilies.length > 0) {
+        const own = projectRoot === path.join(REPO_ROOT, '.claude');
+        process.stdout.write(
+            `${own ? '❌' : '⚠️ '}  check_single_delivery: unknown family in the project` +
+                ` layer: ${v.unknownFamilies.join(', ')}. Add measurement before it can ship` +
+                ' — TYPES in this gate and in _lib/layer_overlap_notice.ts.' +
+                (own ? '' : ' Reported, not enforced: --project is repointed, so generator' +
+                    ' ownership of this tree is not established.') +
+                '\n',
+        );
+        if (own) return 1;
+    }
+
     if (v.readNothing) {
         // Never a pass. A gate that compared nothing has not verified anything,
         // and saying "invariant holds" here is the false-green shape this repo
@@ -451,9 +626,11 @@ export function main(argv?: readonly string[]): number {
     }
     process.stdout.write(
         `⚠️  check_single_delivery: ${detail}. Reported, not enforced — ` +
-            'road-to-single-delivery Phase 2 is halted on `partition-requires-global-layer`, ' +
-            'so this is a known-open defect rather than a regression. Re-run with --enforce ' +
-            'once the partition ships.\n',
+            'the partition shipped (ADR-236 Phase 2) but activates per machine: it withholds ' +
+            'artefacts only where the host layer is verified against `installed.lock`, so a ' +
+            'machine whose install predates the fingerprint keeps the full projection BY DESIGN ' +
+            'and this overlap is the fail-safe working. Run `agent-config install` to enable it ' +
+            'here; use --enforce where every machine is known to be verified.\n',
     );
     return 0;
 }

package/src/scripts/check_standing_rule_delivery.ts

@@ -326,8 +326,14 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
     if (pct > 1) {
         process.stderr.write(
             `❌  ${PROG}: ${total} tok of standing rule prose exceeds the ${budget.total_cap_tokens} cap. `
-                + 'If two layers overlap, `agent-config install --layer=<global|project>` suppresses one '
-                + 'without deleting a file; otherwise scope rules with `paths:` or move bodies into the digest.\n',
+                + 'If two layers overlap, that is the ADR-236 partition not yet armed on this '
+                + 'machine: run `agent-config install` so the host layer is fingerprinted in '
+                + 'installed.lock, and the next `task generate-tools` withholds the globally-owned '
+                + 'artefacts instead of writing a second copy. (Superseded advice: this line used to '
+                + 'name `install --layer=<global|project>`, the layer-suppression remedy ADR-226 '
+                + 'declined and ADR-236 replaced — a reader following it could not fix the '
+                + 'condition.) Otherwise the total is body length, not duplication: scope rules with '
+                + '`paths:` or move bodies into the digest.\n',
         );
         return 1;
     }

package/src/scripts/ci_settle.ts

@@ -0,0 +1,170 @@
+#!/usr/bin/env tsx
+/**
+ * Wait for a PR's checks to settle, and never report a verdict it did not read.
+ *
+ * WHY THIS EXISTS. Agents write this loop by hand, and the exit condition is
+ * the part that is easy to get wrong. Measured 2026-08-20:
+ *
+ *     until ! gh pr checks 1459 | grep -q "pending"; do sleep 60; done
+ *
+ * The API then failed. Its error text — `error connecting to api.github.com` —
+ * contains no `pending`, so the loop exited, the run reported a settle that had
+ * not happened, and the claim had to be retracted to the user in the next
+ * reply. The bug is not the sleep or the grep: it is that **absence of the word
+ * `pending` was treated as evidence of completion**, and an error is neither
+ * settled nor pending.
+ *
+ * The rule this encodes, and the reason it belongs in one place rather than in
+ * every agent's head: `not settled` and `settled` are different from `could not
+ * read`, and only the first two may end a wait.
+ *
+ * Exit codes: 0 = settled, every check succeeded (or was skipped) ·
+ *             1 = settled, at least one check failed ·
+ *             2 = did not settle within the budget, or the API could not be
+ *                 read — NEVER a verdict, and the reason is printed.
+ *
+ * Usage: ./scripts-run src/scripts/ci_settle <pr> [--timeout-min N] [--interval-sec N]
+ */
+
+import { spawnSync } from 'node:child_process';
+
+/** What one poll told us. `unreadable` is deliberately not a verdict. */
+export type PollState =
+    | { kind: 'unreadable'; reason: string }
+    | { kind: 'pending'; total: number; done: number }
+    | { kind: 'settled'; failing: string[]; total: number };
+
+/** Markers that mean the API did not answer — not that nothing is pending. */
+const _UNREADABLE_MARKERS = [
+    'error connecting to',
+    'could not resolve host',
+    'connection refused',
+    'timeout',
+    'timed out',
+    'bad gateway',
+    'service unavailable',
+    'rate limit',
+    'gh auth login',
+    'not logged into',
+    'HTTP 5',
+];
+
+/**
+ * Classify one `gh pr view --json statusCheckRollup` result.
+ *
+ * Pure, so the failure this file exists to prevent is testable without a
+ * network: feed it an API error and it must answer `unreadable`, never
+ * `settled`.
+ */
+export function classifyPoll(stdout: string, stderr: string, status: number | null): PollState {
+    const combined = `${stdout}\n${stderr}`.toLowerCase();
+    for (const marker of _UNREADABLE_MARKERS) {
+        if (combined.includes(marker.toLowerCase())) {
+            return { kind: 'unreadable', reason: marker };
+        }
+    }
+    if (status !== 0) {
+        return { kind: 'unreadable', reason: `gh exited ${String(status)}` };
+    }
+    let rows: { name?: string; conclusion?: string | null; status?: string | null }[];
+    try {
+        const parsed = JSON.parse(stdout) as { statusCheckRollup?: unknown };
+        const roll = parsed.statusCheckRollup;
+        if (!Array.isArray(roll)) {
+            return { kind: 'unreadable', reason: 'no statusCheckRollup in response' };
+        }
+        rows = roll as typeof rows;
+    } catch {
+        return { kind: 'unreadable', reason: 'unparseable JSON' };
+    }
+    if (rows.length === 0) {
+        // Zero checks is not "settled green" — a run that has not registered
+        // its checks yet looks exactly like this.
+        return { kind: 'pending', total: 0, done: 0 };
+    }
+    const terminal = (r: (typeof rows)[number]): boolean =>
+        typeof r.conclusion === 'string' && r.conclusion.length > 0;
+    const done = rows.filter(terminal).length;
+    if (done < rows.length) {
+        return { kind: 'pending', total: rows.length, done };
+    }
+    const bad = new Set(['FAILURE', 'TIMED_OUT', 'CANCELLED', 'ACTION_REQUIRED', 'STARTUP_FAILURE']);
+    const failing = rows
+        .filter((r) => bad.has(String(r.conclusion).toUpperCase()))
+        .map((r) => String(r.name ?? '?'));
+    return { kind: 'settled', failing, total: rows.length };
+}
+
+function poll(pr: string): PollState {
+    const r = spawnSync('gh', ['pr', 'view', pr, '--json', 'statusCheckRollup'], {
+        encoding: 'utf-8',
+        timeout: 60_000,
+    });
+    return classifyPoll(r.stdout ?? '', r.stderr ?? '', r.status);
+}
+
+function sleepSync(seconds: number): void {
+    // Deliberately synchronous: this is a CLI whose whole job is to block.
+    spawnSync(process.execPath, ['-e', `setTimeout(()=>{}, ${String(seconds * 1000)})`], {
+        timeout: (seconds + 5) * 1000,
+    });
+}
+
+export function main(argv: readonly string[]): number {
+    const positional = argv.filter((a) => !a.startsWith('--'));
+    const pr = positional[0];
+    if (pr === undefined) {
+        process.stderr.write('usage: ci_settle <pr> [--timeout-min N] [--interval-sec N]\n');
+        return 2;
+    }
+    const num = (flag: string, dflt: number): number => {
+        const i = argv.indexOf(flag);
+        if (i === -1) return dflt;
+        const v = argv[i + 1];
+        const n = v === undefined ? NaN : parseInt(v, 10);
+        return Number.isFinite(n) && n > 0 ? n : dflt;
+    };
+    const timeoutMin = num('--timeout-min', 45);
+    const intervalSec = num('--interval-sec', 60);
+
+    const deadline = Date.now() + timeoutMin * 60_000;
+    let unreadableStreak = 0;
+
+    for (;;) {
+        const state = poll(pr);
+        if (state.kind === 'settled') {
+            if (state.failing.length === 0) {
+                process.stdout.write(`ci_settle: SETTLED GREEN — ${String(state.total)} check(s)\n`);
+                return 0;
+            }
+            process.stdout.write(
+                `ci_settle: SETTLED RED — ${String(state.failing.length)} of ${String(state.total)} failing:\n` +
+                    state.failing.map((f) => `  ${f}\n`).join(''),
+            );
+            return 1;
+        }
+        if (state.kind === 'unreadable') {
+            unreadableStreak += 1;
+            process.stdout.write(
+                `ci_settle: could not read the API (${state.reason}) — NOT a verdict, still waiting ` +
+                    `[${String(unreadableStreak)}]\n`,
+            );
+        } else {
+            unreadableStreak = 0;
+            process.stdout.write(
+                `ci_settle: pending — ${String(state.done)}/${String(state.total)} settled\n`,
+            );
+        }
+        if (Date.now() >= deadline) {
+            process.stdout.write(
+                `ci_settle: DID NOT SETTLE within ${String(timeoutMin)} min — no verdict is claimed.\n`,
+            );
+            return 2;
+        }
+        sleepSync(intervalSec);
+    }
+}
+
+if (process.argv[1] !== undefined && process.argv[1].endsWith('ci_settle.ts')) {
+    process.exitCode = main(process.argv.slice(2));
+}