@event4u/agent-config 14.21.0 → 14.22.0

package/src/install/partitionEligibility.ts

@@ -1,7 +1,7 @@
 /**
  * The single-delivery partition predicate — one artefact, one layer.
  *
- * ## What it decides
+ * **What it decides.**
  *
  * Two layers deliver agent artefacts: a machine-local project layer at
  * `<repo>/.claude/` (gitignored, 0 tracked files, rewritten by every
@@ -11,16 +11,23 @@
  * 203,873 tokens against a 110,000 cap (185.3 %).
  *
  * ADR-236 partitions them: an artefact that exists ONLY for this package stays
- * in the project layer; everything else is delivered only globally. That takes
- * `<repo>/.claude/` from 111 rules and 338 skills to **16 rules and zero
- * skills**.
+ * in the project layer; everything else is delivered only globally.
  *
- * ## Why the predicate is fail-safe and never fails the build
+ * The figure this note carried — "16 rules and zero skills" — was the 2026-08-19
+ * projection of the design. Measured 2026-09-07 on the amended implementation:
+ * **13 rules** (15 package-only, 2 of them byte-identically deduped at user
+ * scope) and **zero skills**, plus 49 flat-command wrappers, which are a
+ * different family and are withheld per name like everything else.
+ *
+ * **Why the predicate is fail-safe and never fails the build.**
  *
  * The partition is a removal, so the build loses its repair path: it can no
  * longer heal a stale global layer by regenerating, because it stops writing
- * those files. Every uncertainty therefore resolves to `standalone/full` — the
- * pre-partition behaviour — and **never** to a refusal:
+ * those files. **How that fail-safe is expressed changed on 2026-09-07** and the
+ * sentence below is the OLD form, kept because the constraint it records still
+ * binds: uncertainty used to resolve to a repo-wide `standalone/full`, a mode
+ * this file no longer has. It now resolves PER ARTEFACT — an unreadable host
+ * layer withholds nothing — and still never to a refusal:
  *
  * `.github/workflows/consistency.yml:169` runs `task generate-tools` on a fresh
  * checkout where, by that workflow's own comment at `:172-174`, the host rule
@@ -30,22 +37,68 @@
  * exists to prevent; breaking the Consistency pipeline is the other. Full
  * projection is the only branch that does neither.
  *
- * ## Why content and not a version number
+ * **Why content and not a version number.**
  *
  * Rationale and the 153-skill measurement that decided it: see
  * `hostLayerFingerprint.ts`. Version equality is checked too, but as a cheap
  * pre-filter — it is necessary, never sufficient.
  *
- * ## Contract
+ * **Contract.**
  *
- * Side-effect-free, no I/O of its own (callers supply the facts), no CLI entry,
- * no `process.exit`. Ships inside the consumer installer bundle, same
+ * `verifyHostLayer` itself is side-effect-free and takes its facts from the
+ * caller. The MODULE is not: `resolveHostLayerVerdict` reads the filesystem and
+ * the lockfile, and since 2026-09-07 it re-exports `keepInProjectLayer` /
+ * `claudeLayerHolds`, which read directories. The earlier blanket "no I/O of its
+ * own" was true of the pure predicate and false of the file. No CLI entry, no
+ * `process.exit`. Ships inside the consumer installer bundle, same
  * constraint as `ruleInScope.ts`.
  */
 
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 
+import { claudeLayerHolds, keepInProjectLayer } from './claudeLayerCarriage.js';
+
+/**
+ * **`emittedWrapperSlugs` — why the skill sweep's protected set narrowed.**
+ *
+ * `generate_claude_skills` sweeps `.claude/skills/` of anything absent from the
+ * set it is about to write, and it spares command-wrapper slugs so the command
+ * emitter — which runs afterwards into the same directory — does not lose
+ * entries it is about to create. That protected set used to be EVERY command
+ * slug, which was safe only while skills were projected in full: a slug that is
+ * also a skill name was protected twice over.
+ *
+ * Once `~/.claude/skills` began withholding by name (2026-09-07) the
+ * over-protection became a leak — precisely the one
+ * `tests/scripts/single_delivery_emission.test.ts` exists for. A command-named
+ * skill survives in `.claude/skills/` while both counters read zero, because the
+ * skill sweep spares it and the command prune skips symlinks.
+ *
+ * So the set mirrors the emitter's own skips — **all of them**, which a neutral
+ * review found it did not on 2026-09-07: the note said "two" and named two while
+ * the emitter had three, so up to 8 builtin-reserved slugs (`bug`, `review`,
+ * `worktree`, `agents`, `context`, `cost`, `memory`, `skills`) were protected
+ * from a sweep that should reach them. Benign in the shipped pipeline order,
+ * because the command emitter's own stale-dir sweep cleans them afterwards — but
+ * the invariant the note asserted did not hold, and it reopens for any run that
+ * calls `generate_claude_skills` without `generate_claude_commands`.
+ *
+ * The four skips: a slug that is also a skill name · every CLUSTERED command
+ * (those reach the host as `/cluster:sub` and need no wrapper) · a Claude Code
+ * built-in name · a slug `~/.claude/skills` already carries.
+ * `condense.ts::_emitted_wrapper_slugs` is that set.
+ *
+ * **The re-export below.**
+ *
+ * `keepInProjectLayer` is re-exported so `condense.ts` reaches both halves of
+ * the partition through ONE import line. Not stylistic: that file sits ~1,200 lines past the 1,500-line
+ * source ceiling, where `check_source_size_budget` counts every added line as
+ * one unit of excess and its test asserts `baseline == live` — so a second
+ * import statement there is a blocking gate failure, while the same line here
+ * (535 lines, under the cap) costs nothing.
+ */
+export { claudeLayerHolds, keepInProjectLayer } from './claudeLayerCarriage.js';
 import { parseFrontmatter } from './ruleInScope.js';
 import { fingerprintLayers, hostLayerInputs } from './hostLayerFingerprint.js';
 import {
@@ -57,12 +110,25 @@ import {
 /** The workspace id that marks an artefact as existing only for this package. */
 export const MAINTAINER_WORKSPACE = 'agent-config-maintainer';
 
-/** Delivery mode the build selected, and prints. */
-export type PartitionMode = 'standalone/full' | 'dual-layer/partitioned';
-
-export interface PartitionVerdict {
-    readonly mode: PartitionMode;
-    /** One clause, printable, saying WHY this mode was selected. */
+/**
+ * Is the recorded install verified against the host layer on disk?
+ *
+ * This used to be a `PartitionMode` — `'standalone/full' | 'dual-layer/partitioned'` —
+ * and it used to DECIDE what the project layer got written. It no longer does
+ * (owner decision, 2026-09-07): the project layer withholds per artefact on the
+ * host layer's own contents, via `claudeLayerCarriage` and
+ * `globalRuleLayers.hostLayerCarries`. What survives here is the diagnostic —
+ * whether the layer a run is withholding against is the one this checkout's
+ * installer stamped.
+ *
+ * The type was renamed rather than kept, because a name that says "delivery mode"
+ * while deciding nothing about delivery is the half-alive machinery this change
+ * exists to remove.
+ */
+export interface HostLayerVerdict {
+    /** True only when version AND content fingerprint both match the record. */
+    readonly verified: boolean;
+    /** One clause, printable, saying WHY — including how to fix a `false`. */
     readonly reason: string;
 }
 
@@ -72,7 +138,7 @@ export interface LockfileFacts {
     readonly host_layer_fingerprint?: string | undefined;
 }
 
-export interface PartitionInputs {
+export interface HostLayerInputs {
     /** `package.json` version of the checkout being built. */
     readonly projectVersion: string;
     /** Parsed `installed.lock`, or `null` when no global install is recorded. */
@@ -88,31 +154,36 @@ export interface PartitionInputs {
 }
 
 /**
- * Select the delivery mode. Total function: always returns a verdict, never
- * throws, never refuses.
+ * Verify the host layer against the install record. Total function: always
+ * returns a verdict, never throws, never refuses.
+ *
+ * The order of the guards is cheapest-and-most-decisive first, so the
+ * fingerprint is computed only when everything else already agrees.
  *
- * The order of the guards is the fail-safe order — cheapest and most decisive
- * first, so the fingerprint is computed only when everything else already
- * agrees.
+ * **A `false` no longer changes what gets written.** It changes what the run
+ * SAYS — see `reportHostLayerVerdict`, whose warning names the remedy. The
+ * withhold decision moved to per-artefact evidence, where an unverified install
+ * that nonetheless carries an artefact is not a reason to deliver that artefact
+ * twice.
  */
-export function partitionVerdict(inputs: PartitionInputs): PartitionVerdict {
+export function verifyHostLayer(inputs: HostLayerInputs): HostLayerVerdict {
     if (!inputs.hostLayerPresent) {
         return {
-            mode: 'standalone/full',
+            verified: false,
             reason: 'no host-global layer on this machine',
         };
     }
     const lock = inputs.lockfile;
     if (lock === null) {
         return {
-            mode: 'standalone/full',
+            verified: false,
             reason: 'host layer present but no install record (installed.lock absent)',
         };
     }
     const recorded = lock.agent_config_version;
     if (!recorded) {
         return {
-            mode: 'standalone/full',
+            verified: false,
             reason: 'install record carries no version',
         };
     }
@@ -121,15 +192,15 @@ export function partitionVerdict(inputs: PartitionInputs): PartitionVerdict {
     // checkout still expects, and ordering does not establish substitutability.
     if (recorded !== inputs.projectVersion) {
         return {
-            mode: 'standalone/full',
+            verified: false,
             reason: `version mismatch (installed ${recorded}, building ${inputs.projectVersion})`,
         };
     }
     const installedFp = lock.host_layer_fingerprint;
     if (!installedFp) {
         return {
-            mode: 'standalone/full',
-            reason: 'install predates host-layer fingerprinting — re-run `agent-config install` to enable the partition',
+            verified: false,
+            reason: 'install predates host-layer fingerprinting — re-run `agent-config install` to record one',
         };
     }
     let expected: string;
@@ -137,18 +208,18 @@ export function partitionVerdict(inputs: PartitionInputs): PartitionVerdict {
         expected = inputs.expectedFingerprint();
     } catch {
         return {
-            mode: 'standalone/full',
+            verified: false,
             reason: 'could not compute the expected host-layer fingerprint',
         };
     }
     if (installedFp !== expected) {
         return {
-            mode: 'standalone/full',
+            verified: false,
             reason: 'host-layer content differs from this checkout — re-run `agent-config install`',
         };
     }
     return {
-        mode: 'dual-layer/partitioned',
+        verified: true,
         reason: `host layer verified at ${recorded} (fingerprint ${installedFp.slice(0, 12)})`,
     };
 }
@@ -167,7 +238,7 @@ export function partitionVerdict(inputs: PartitionInputs): PartitionVerdict {
  * the project layer. Both defaults resolve toward "the artefact is generally
  * useful"; only one of them is about withholding.
  *
- * ## The state space, MEASURED rather than enumerated defensively (2026-08-21)
+ * **The state space, MEASURED rather than enumerated defensively (2026-08-21).**
  *
  * Three of this function's branches — unreadable file, absent `workspaces:`,
  * empty list — all resolve to `false`, and the closure review asked whether one
@@ -206,71 +277,78 @@ export function isExclusivelyPackageOnly(source_path: string): boolean {
     return raw.every((w) => String(w) === MAINTAINER_WORKSPACE);
 }
 
-/** Emitter for the ONE mode line; see the visibility note on the resolver. */
+/** Emitter for the ONE projection line; see the visibility note on the resolver. */
 export type Announce = (message: string) => void;
 
-let _memo: PartitionVerdict | null = null;
+let _memo: HostLayerVerdict | null = null;
 let _announce: Announce = (m) => process.stdout.write(`${m}\n`);
 
 /**
- * Install the emitter used for the mode line. Callers pass a function visible at
- * their DEFAULT output level — the first implementation used one that prints only
- * at `verbose`, which withheld ~100 rules while saying nothing in a normal run.
+ * Install the emitter used for the projection line. Callers pass a function
+ * visible at their DEFAULT output level — the first implementation used one that
+ * prints only at `verbose`, which withheld ~100 rules while saying nothing in a
+ * normal run.
  */
 export function setPartitionAnnounce(fn: Announce): void {
     _announce = fn;
 }
 
-/** Test seam — drop the memo so one process can exercise both delivery modes. */
-export function _resetPartitionVerdictForTest(): void {
+/** Test seam — drop the memo so one process can exercise both verdicts. */
+export function _resetHostLayerVerdictForTest(): void {
     _memo = null;
 }
 
 /**
- * Is the partition active for this generation? Memoised per process, because the
- * fingerprint costs ~100 ms and the answer cannot change mid-run.
- *
- * This is the single entry point the generators call, deliberately: wiring a
- * feature into two files that are already past the 1,500-line source ceiling
- * costs a ratchet violation per line, so the decision, its fail-safe ordering,
- * its printed reason and its memo all live here and the call sites are one line
- * each.
- */
-export function partitionActive(projectRoot: string): boolean {
-    return resolvePartitionVerdict(projectRoot).mode === 'dual-layer/partitioned';
-}
-
-/**
- * Resolve the delivery mode for one generation, and say so once.
- *
- * Lives here rather than in `condense.ts` for two reasons. The decision belongs
- * beside {@link partitionVerdict}, whose fail-safe ordering it depends on; and
- * `condense.ts` is 1,500+ lines, where the source-size ratchet counts every
- * added line as a violation — so a block that has no reason to live there is a
- * cost as well as a misplacement.
- *
- * **Both council seats (2026-08-20, 2/2) required that generation PRINT the mode
- * it selected** rather than partition silently: a withheld artefact nobody
- * announced is exactly the under-governance the partition exists to remove. The
- * caller supplies `announce`, and the level matters — the first implementation
- * used an `info()` that prints only at `verbose`, so it withheld ~100 rules while
- * saying nothing in a default run. Pass a function that is visible at the default
- * level. Residual, stated: at an explicitly silent output level the line is
- * dropped; that is an operator choice and the partition stays fail-safe anyway.
+ * Verify the host layer once per generation, and say so once.
+ *
+ * **What this no longer does.**
+ *
+ * It used to answer `partitionActive(projectRoot)`, and every generator gated its
+ * withhold on that one boolean. **That entry point is deleted** (owner decision,
+ * 2026-09-07). The project layer's contents are now decided per artefact, on the
+ * host layer's own contents, by `claudeLayerCarriage.keepInProjectLayer` and
+ * `globalRuleLayers.hostLayerCarries`. A version number is not evidence about an
+ * artefact, and using it as one delivered 261 skills and 29 personas twice per
+ * session for as long as an install lagged a release.
+ *
+ * So what survives is the DIAGNOSTIC. **Both council seats (2026-08-20, 2/2)
+ * required that generation print the mode it selected** rather than partition
+ * silently, and that requirement is still live — but this function is no longer
+ * where it is met, and the first version of this note claimed otherwise.
+ *
+ * **Corrected 2026-09-07 after a neutral review.** The note read "it still
+ * prints". It did not: removing `partitionActive` removed `condense.ts`'s only
+ * call into this resolver, so the emitter that file installed became dead and
+ * `task generate-tools` withheld ~299 skills and 29 personas while printing
+ * nothing about the layer it withheld against. The line is now emitted by
+ * `report_layer_overlap`, the step that already runs immediately after the
+ * generator in the same chain — see the comment there for why it lives in that
+ * file rather than in the 2,700-line generator.
+ *
+ * **What that line does and does not carry**, since a second review asked: it
+ * reports the VERIFICATION state of the layer being withheld against, not a
+ * withhold count, and this verdict decides nothing. The counts are the
+ * generator's own summary one line above (`skills=N`,
+ * `command_skills=N (M withheld …)`). So the council requirement is met by the
+ * pair of lines rather than by this one — stated that way instead of claiming
+ * the line alone honours it.
+ *
+ * The caller still supplies `announce`, and the level still matters — the first
+ * implementation used an `info()` that prints only at `verbose`. Residual,
+ * stated: at an explicitly silent output level the line is dropped.
  *
  * The fingerprint compares the host layer against **what the installer recorded
- * when it wrote that layer**, not against a re-derivation from source. That
- * avoids guessing the installer's byte representation — a mismatch there would
- * make the partition permanently unreachable rather than merely inactive — and it
- * is the property the partition needs: the omitted artefacts are still present,
- * in the form this version's installer left them.
+ * when it wrote that layer**, not against a re-derivation from source — the
+ * property that keeps a mismatch informative rather than permanent.
  *
  * **Known residual:** an installer that crashes mid-write and still reaches the
  * lockfile would fingerprint its own partial layer, and that fingerprint then
  * verifies. Ordering narrows the window (the lockfile is written last) without
- * closing it; a per-artefact manifest would close it and is not built here.
+ * closing it. It now costs less than it did: the withhold no longer trusts this
+ * verdict, so a wrongly-verified layer misreports a line rather than authorising
+ * a removal.
  */
-export function resolvePartitionVerdict(projectRoot: string): PartitionVerdict {
+export function resolveHostLayerVerdict(projectRoot: string): HostLayerVerdict {
     if (_memo !== null) {
         return _memo;
     }
@@ -286,15 +364,19 @@ export function resolvePartitionVerdict(projectRoot: string): PartitionVerdict {
     try {
         lock = read_lockfile();
     } catch {
-        lock = null; // unreadable record → fail safe
+        lock = null; // unreadable record → report it as unverified
     }
-    _memo = partitionVerdict({
+    _memo = verifyHostLayer({
         projectVersion: current_package_version(projectRoot),
         lockfile: lock,
         hostLayerPresent: present,
         expectedFingerprint: () => fingerprintLayers(layers),
     });
-    _announce(`projection mode: ${_memo.mode} — ${_memo.reason}`);
+    _announce(
+        _memo.verified
+            ? `projection: project layer carries only what ~/.claude lacks — ${_memo.reason}`
+            : `projection: project layer carries only what ~/.claude lacks · ⚠️  host layer UNVERIFIED — ${_memo.reason}`,
+    );
     return _memo;
 }
 
@@ -316,7 +398,7 @@ export function resolvePartitionVerdict(projectRoot: string): PartitionVerdict {
  * errors are not symmetric and this must never prefer the second.
  *
  * Lives here rather than inline in `install.ts` for the same reason
- * {@link resolvePartitionVerdict} does: it belongs beside the predicate it
+ * {@link resolveHostLayerVerdict} does: it belongs beside the predicate it
  * serves, and `install.ts` is 5,000+ lines where the source-size ratchet counts
  * every added line.
  *
@@ -360,29 +442,31 @@ export function stampHostLayerFingerprint(
  * names**, and neither `check_single_delivery` nor `_lib/layer_overlap_notice`
  * looked, because `personas` was in neither's `TYPES`.
  *
- * ## Two properties the caller depends on
+ * **Three properties the caller depends on.**
  *
- * **Scoped to `.claude/` only.** {@link partitionActive} verifies the CLAUDE host
- * layer against `installed.lock`. It says nothing about `~/.cursor`, so
- * withholding a cursor persona on the strength of a claude fingerprint would
- * deliver it nowhere — the one failure the fail-safe design exists to prevent.
- * Every other tool directory keeps the full projection.
+ * **Scoped to `.claude/` only.** The evidence is `~/.claude/personas`. It says
+ * nothing about `~/.cursor`, so withholding a cursor persona on the strength of
+ * a claude directory listing would deliver it nowhere — the one failure the
+ * fail-safe design exists to prevent. Every other tool directory keeps the full
+ * projection.
  *
- * **Reconciliation is the empty list, not a second code path.** The caller's
+ * **Withheld PER NAME, on that directory's own contents** (owner decision,
+ * 2026-09-07). This used to gate on `partitionActive` — a version and fingerprint
+ * check against `installed.lock` — which meant an install one release behind
+ * delivered all 29 personas twice. A persona `~/.claude/personas` actually holds
+ * is withheld whatever the lockfile says; one it lacks stays, on its own, without
+ * keeping the other 28 duplicates alive with it.
+ *
+ * **Reconciliation is the shorter list, not a second code path.** The caller's
  * stale-symlink sweep removes any link whose name is absent from the list it was
- * given for that directory, so returning `[]` empties a directory an earlier
- * version populated. A gate that only declined to WRITE would leave the existing
+ * given for that directory, so a shorter list empties what an earlier version
+ * populated. A gate that only declined to WRITE would leave the existing
  * duplicate standing — a partition that stops new duplication and keeps the old
  * is not a partition.
- *
- * Verified before shipping: every one of the 29 project personas is present in
- * the global layer (32 there, a strict superset). The partition is a removal and
- * has no repair path, so withholding is only safe once the surviving layer is
- * known to carry what is withheld.
  */
 export function personaPartition(
-    projectRoot: string,
     all: readonly string[],
+    home?: string,
 ): {
     readonly all: readonly string[];
     listFor: (toolDir: string) => readonly string[];
@@ -398,34 +482,42 @@ export function personaPartition(
      */
     countFor: (toolDir: string) => number;
 } {
-    const active = partitionActive(projectRoot);
+    const claudeList = keepInProjectLayer('personas', all, home);
+    const withheld = all.length - claudeList.length;
     return {
         all,
-        listFor: (toolDir) => (personaWithheldFor(toolDir, active) ? [] : all),
-        note: active ? ' — .claude/ withheld: ADR-236 partition, personas arrive from ~/.claude' : '',
-        countFor: (toolDir) => (personaWithheldFor(toolDir, active) ? 0 : all.length),
+        listFor: (toolDir) => personaListFor(toolDir, all, claudeList),
+        note:
+            withheld > 0
+                ? ` — .claude/ withheld ${String(withheld)}: ADR-236, those personas arrive from ~/.claude`
+                : '',
+        countFor: (toolDir) => personaListFor(toolDir, all, claudeList).length,
     };
 }
 
 /**
- * The pure half of {@link personaPartition}: withhold iff the partition is active
- * AND this is a Claude tool directory.
- *
- * Split out so the decision is testable in BOTH directions. `personaPartition`
- * reads `installed.lock` through a memoized `partitionActive`, so a test over it
- * can only assert whatever this machine happens to be — which is a test that
- * passes either way and therefore proves nothing. The two properties worth
- * pinning are exactly the two this signature exposes: `.claude/` is withheld when
- * active, and NOTHING else ever is.
+ * The pure half of {@link personaPartition}: a Claude tool directory gets the
+ * narrowed list, every other directory gets the full one.
+ *
+ * Split out so the decision is testable in BOTH directions without reading this
+ * machine's `~/.claude`. A test over the un-injected path can only assert
+ * whatever the machine happens to be — a test that passes either way and
+ * therefore proves nothing. The two properties worth pinning are exactly the two
+ * this signature exposes: `.claude/` gets the narrowed list, and NOTHING else
+ * ever does.
  */
-export function personaWithheldFor(toolDir: string, active: boolean): boolean {
-    return active && toolDir.startsWith('.claude/');
+export function personaListFor(
+    toolDir: string,
+    all: readonly string[],
+    claudeList: readonly string[],
+): readonly string[] {
+    return toolDir.startsWith('.claude/') ? claudeList : all;
 }
 
 /**
  * Does the project layer withhold the colon-form `/cluster:sub` commands?
  *
- * ## The claim this replaces, and the measurement that revised it
+ * **The claim this replaces, and the measurement that revised it.**
  *
  * `generate_claude_project_commands` was written on the reasoning that "Claude
  * Code dedupes project and user scope by name, so the two copies of
@@ -447,16 +539,24 @@ export function personaWithheldFor(toolDir: string, active: boolean): boolean {
  * exists, those 40 symlinks are written, deduped away, and LOSE. They are dead
  * weight there — not a second listing, and not a reachability guarantee either.
  *
- * ## Why `partitionActive` is the right predicate rather than a new one
+ * **Why the predicate is the DIRECTORY, not `installed.lock`.**
  *
- * It is true exactly when a global layer is present and verified against
- * `installed.lock`, which is exactly the case where the project copy loses; and
- * false on a fresh checkout, an unverified install, or a version mismatch —
- * every case where the project copy is the only reachable one. So the
- * fail-safe direction the whole module is built around already matches the
- * measurement, and withholding needs no separate switch.
+ * This used to be `partitionActive` — true only when a global layer was present
+ * AND verified against `installed.lock` by version and fingerprint. That gets
+ * the measurement above backwards in the one case that matters: the project copy
+ * loses whenever the global copy EXISTS, and whether the recorded version is a
+ * release behind has no bearing on whether it exists. An install one release old
+ * therefore kept writing 40 symlinks the host deduped away — dead weight, chosen
+ * on a fact about a version number.
  *
- * ## Honest limits
+ * So the evidence is the host directory itself, asked per name (owner decision,
+ * 2026-09-07): `~/.claude/commands/<cluster>/<sub>.md` for a clustered command,
+ * `~/.claude/commands/<slug>.md` for a flat one. Present → the project copy loses
+ * and is withheld. Absent → the project copy is the only reachable one and stays.
+ * Unreadable layer → nothing is withheld. The fail-safe direction is unchanged;
+ * it is now per artefact rather than per repository.
+ *
+ * **Honest limits.**
  *
  * Self-report, n=1 per condition, one host version, one machine. What is NOT
  * claimed: that older or newer hosts dedupe the same way, or that precedence is
@@ -468,22 +568,56 @@ export function personaWithheldFor(toolDir: string, active: boolean): boolean {
  * It cannot. When this predicate returns true the project copy is never written,
  * so there is no second copy for the host to double-list or for the gate to
  * count — it would report zero overlap while the assumption underneath had
- * failed. Worse, `partitionActive` verifies the INSTALL (version + content
- * fingerprint), never the HOST version whose behaviour was measured, so a host
- * upgrade changes the premise and moves nothing this code reads.
+ * failed. The 2026-09-07 change does not repair that: reading the directory is
+ * evidence about PRESENCE, never about how the host resolves two copies of a
+ * name, so a host that stopped deduping is still undetected here.
  *
  * What actually holds: reachability survives a dedup change either way, because
  * the global copy is delivered regardless. What is lost is only the project
  * copy's redundancy, and nothing detects that. A real detector would have to
  * pin the host version this measurement was taken against and re-probe when it
  * moves — not built here, and named as absent rather than implied away.
+ *
+ * **Flat wrappers ARE withheld — corrected 2026-09-07 after a neutral review.**
+ *
+ * A CLUSTERED command reaches Claude Code as `/cluster:sub` from a `.md` under
+ * `commands/`, and `~/.claude/commands/` carries 41 such cluster directories — so
+ * the project copy has somewhere to lose to, and this predicate withholds it.
+ *
+ * A FLAT command reaches the host as a hyphen-named wrapper under `skills/`,
+ * because the host does not register flat command FILES (probed ≤ 2.1.204).
+ *
+ * **The first version of this note then claimed `~/.claude/skills` carries NONE
+ * of those wrappers, that "nothing else delivers them", and left
+ * `generate_claude_commands` ungated on that basis. All three were wrong.**
+ * `install.ts::_apply_claude_flat_command_wrappers`, wired for every
+ * `claude-code` deploy, writes `~/.claude/skills/<slug>/SKILL.md` for every
+ * VISIBLE flat command and deletes the flat file. The claim was a snapshot of one
+ * machine whose last install had not run that pass — 53 flat `.md` files still
+ * sat in `~/.claude/commands` — presented as a property of the installer.
+ *
+ * What it would have cost: the next `agent-config install` writes ~17 wrappers
+ * globally while the generator keeps writing all 49 project wrappers, so 17 flat
+ * commands arrive TWICE per session — the duplication class ADR-236 exists to
+ * remove — and `check_single_delivery` reports a `skills` overlap the same note
+ * said could not happen.
+ *
+ * So the wrapper emitter now applies the same per-name rule as everything else:
+ * `claudeLayerHolds('skills', slug)` withholds a wrapper the host layer carries,
+ * and keeps one it does not. Fail-safe per artefact, no repo-wide switch.
+ *
+ * A number in that note was wrong too, and is corrected here rather than left to
+ * be quoted: the project layer carries **49** wrappers, not 153. `153` was
+ * transplanted from the 153-skill measurement in `hostLayerFingerprint.ts`.
+ *
+ * @param globalName the host-side name — `<cluster>/<sub>.md` or `<slug>.md`.
  */
-export function commandsWithheld(projectRoot: string): boolean {
-    return partitionActive(projectRoot);
+export function commandWithheld(globalName: string, home?: string): boolean {
+    return claudeLayerHolds('commands', globalName, home);
 }
 
 /**
- * ## The caller's early return, flagged by review and kept
+ * **The caller's early return, flagged by review and kept.**
  *
  * `generate_claude_project_commands` applies this predicate and then returns
  * early when `src/domains/` is absent — BEFORE its stale-link sweep. So a tree