@event4u/agent-config 14.5.0 → 14.7.0

package/src/install/hostLayerFingerprint.ts

@@ -0,0 +1,145 @@
+/**
+ * Deterministic content fingerprint of a host artefact layer.
+ *
+ * ## Why a fingerprint and not a version number
+ *
+ * The single-delivery partition is a *removal*: after it, `task generate-tools`
+ * writes 16 rules and zero skills into `<repo>/.claude/` and every other
+ * artefact is delivered ONLY by the host-global layer. That removes the build's
+ * own repair path — regeneration can no longer heal a stale global layer,
+ * because it stops writing the affected files at all.
+ *
+ * A package version proves *which installer claims to have written* the host
+ * directory. It does not prove that the directory holds the artefacts this
+ * checkout is about to omit. Measured on the maintainer machine 2026-08-20:
+ * `package.json` and the published release both read `14.6.0`, while **153
+ * skills existed only in the project layer** and 37 only in the global one. A
+ * version-equality predicate would have authorised the partition there and
+ * silently dropped 153 skills. So the predicate compares content.
+ *
+ * ## Cost — measured, and the earlier figure was wrong
+ *
+ * A prior revision of the blocker recorded 5.85 s per generation for a
+ * content comparison and used that number to argue the approach was too
+ * expensive. That figure was a **shell artefact**: it spawned one `cat` per
+ * file. Re-measured in Node on the same tree: **61 ms** over 664 source files,
+ * **103 ms** over 1019 host files. The comparison is cheap; the 5.85 s never
+ * described this mechanism.
+ *
+ * ## Contract
+ *
+ * Side-effect-free, no CLI entry, no `process.exit` — this module ships inside
+ * the consumer installer bundle, same constraint as `ruleInScope.ts`. Keep it
+ * that way.
+ */
+
+import { createHash } from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/**
+ * Fingerprint wire version. Bump when the digest input changes shape, so an
+ * old lockfile compares unequal instead of comparing wrong.
+ */
+export const FINGERPRINT_SCHEMA = 1;
+
+/** One layer to fingerprint: a label (stable across machines) and its root. */
+export interface LayerInput {
+    /** Stable label — `rules`, `skills`, … NOT an absolute path. */
+    readonly label: string;
+    /** Absolute directory. A missing directory contributes nothing. */
+    readonly root: string;
+}
+
+/** Files under `dir`, recursively, sorted by path — deterministic order. */
+function collectFiles(dir: string): string[] {
+    const out: string[] = [];
+    const walk = (d: string): void => {
+        let entries: fs.Dirent[];
+        try {
+            entries = fs.readdirSync(d, { withFileTypes: true });
+        } catch {
+            return; // absent or unreadable → contributes nothing
+        }
+        const sorted = [...entries].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+        for (const e of sorted) {
+            const p = path.join(d, e.name);
+            if (e.isDirectory()) {
+                walk(p);
+            } else if (e.isFile()) {
+                out.push(p);
+            }
+            // Symlinks are deliberately skipped: the project layer symlinks into
+            // `dist/`, the global layer holds real files, and following links
+            // would make two layers of identical CONTENT fingerprint differently
+            // depending on which side was read.
+        }
+    };
+    walk(dir);
+    return out.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+}
+
+/**
+ * Content fingerprint over the given layers.
+ *
+ * The digest covers, per file, its **layer-relative** path and its bytes — so a
+ * rename, a deletion, an addition, and an edit each change it, while the
+ * absolute location of the layer does not. Layers are folded in the order
+ * given; pass them in a stable order.
+ *
+ * An absent layer root is not an error: it contributes zero files. That makes
+ * the fingerprint of "nothing installed" well-defined and unequal to any real
+ * layer, which is what the fail-safe branch of the partition predicate wants.
+ */
+export function fingerprintLayers(layers: readonly LayerInput[]): string {
+    const h = createHash('sha256');
+    h.update(`v${FINGERPRINT_SCHEMA}\0`);
+    for (const layer of layers) {
+        h.update(`layer:${layer.label}\0`);
+        for (const file of collectFiles(layer.root)) {
+            h.update(path.relative(layer.root, file));
+            h.update('\0');
+            try {
+                h.update(fs.readFileSync(file));
+            } catch {
+                // A file that vanished between listing and reading is a partial
+                // install by definition. Fold a marker rather than throwing, so
+                // the digest differs from a complete layer instead of aborting
+                // the caller.
+                h.update('\0unreadable\0');
+            }
+            h.update('\0');
+        }
+    }
+    return h.digest('hex');
+}
+
+/**
+ * The host-global artefact layers the partition depends on, in a FIXED order.
+ *
+ * **This is the one definition, and it has to be.** The installer fingerprints
+ * what it wrote; the build fingerprints what it finds and compares. Two inline
+ * lists would drift — and a drift here does not fail loudly, it makes the
+ * partition permanently unreachable while every fail-safe branch reports a
+ * plausible reason. Import this; never re-list the layers.
+ *
+ * Only `claude-code` is covered, and the narrowness is the measurement rather
+ * than an omission: the 110-rule / 203,873-token duplication ADR-236 partitions
+ * was measured on `~/.claude/`. Widening this list widens what must be verified
+ * before a single artefact is withheld, so it is a deliberate addition.
+ *
+ * `commands` is in the list because the project layer writes skills AND commands
+ * into ONE directory (`generate_claude_commands` targets `CLAUDE_SKILLS_DIR`)
+ * while the host layer keeps them apart in `~/.claude/skills` and
+ * `~/.claude/commands`. Emptying the project directory withholds commands too,
+ * so commands must be part of what gets verified first. Measured 2026-08-20:
+ * 414 project entries against 298 host skills plus 93 host commands.
+ */
+export function hostLayerInputs(userHome: string): LayerInput[] {
+    const claude = path.join(userHome, '.claude');
+    return [
+        { label: 'rules', root: path.join(claude, 'rules') },
+        { label: 'skills', root: path.join(claude, 'skills') },
+        { label: 'commands', root: path.join(claude, 'commands') },
+    ];
+}

package/src/install/partitionEligibility.ts

@@ -0,0 +1,325 @@
+/**
+ * The single-delivery partition predicate — one artefact, one layer.
+ *
+ * ## What it decides
+ *
+ * Two layers deliver agent artefacts: a machine-local project layer at
+ * `<repo>/.claude/` (gitignored, 0 tracked files, rewritten by every
+ * `task generate-tools`) and a host-global layer at `~/.claude/` (written by
+ * `agent-config install`, never by the build). Measured 2026-08-19 on a freshly
+ * regenerated tree: **110 rules arrive twice**, and standing rule prose is
+ * 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**.
+ *
+ * ## 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:
+ *
+ * `.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
+ * trees are gitignored and absent. An option that made a missing global layer a
+ * hard failure was eliminated by that fact in the 2026-08-19 council round, not
+ * by preference. Under-governing a checkout is the one regression this estate
+ * 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
+ *
+ * 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
+ *
+ * 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
+ * constraint as `ruleInScope.ts`.
+ */
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+
+import { parseFrontmatter } from './ruleInScope.js';
+import { fingerprintLayers, hostLayerInputs } from './hostLayerFingerprint.js';
+import {
+    current_package_version,
+    read_lockfile,
+    write_lockfile,
+} from '../scripts/_lib/installed_lock.js';
+
+/** 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. */
+    readonly reason: string;
+}
+
+/** The lockfile fields the predicate reads — a structural subset. */
+export interface LockfileFacts {
+    readonly agent_config_version?: string | undefined;
+    readonly host_layer_fingerprint?: string | undefined;
+}
+
+export interface PartitionInputs {
+    /** `package.json` version of the checkout being built. */
+    readonly projectVersion: string;
+    /** Parsed `installed.lock`, or `null` when no global install is recorded. */
+    readonly lockfile: LockfileFacts | null;
+    /** Does the host layer exist on disk at all? */
+    readonly hostLayerPresent: boolean;
+    /**
+     * Fingerprint this checkout expects the host layer to carry. Lazy on
+     * purpose: every disqualifying branch above it returns without paying the
+     * ~100 ms hash.
+     */
+    readonly expectedFingerprint: () => string;
+}
+
+/**
+ * Select the delivery mode. Total function: always returns a verdict, never
+ * throws, never refuses.
+ *
+ * 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.
+ */
+export function partitionVerdict(inputs: PartitionInputs): PartitionVerdict {
+    if (!inputs.hostLayerPresent) {
+        return {
+            mode: 'standalone/full',
+            reason: 'no host-global layer on this machine',
+        };
+    }
+    const lock = inputs.lockfile;
+    if (lock === null) {
+        return {
+            mode: 'standalone/full',
+            reason: 'host layer present but no install record (installed.lock absent)',
+        };
+    }
+    const recorded = lock.agent_config_version;
+    if (!recorded) {
+        return {
+            mode: 'standalone/full',
+            reason: 'install record carries no version',
+        };
+    }
+    // Exact equality, deliberately not `>=`. A NEWER global layer is not a
+    // superset: a later release may have renamed or removed an artefact this
+    // checkout still expects, and ordering does not establish substitutability.
+    if (recorded !== inputs.projectVersion) {
+        return {
+            mode: 'standalone/full',
+            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',
+        };
+    }
+    let expected: string;
+    try {
+        expected = inputs.expectedFingerprint();
+    } catch {
+        return {
+            mode: 'standalone/full',
+            reason: 'could not compute the expected host-layer fingerprint',
+        };
+    }
+    if (installedFp !== expected) {
+        return {
+            mode: 'standalone/full',
+            reason: 'host-layer content differs from this checkout — re-run `agent-config install`',
+        };
+    }
+    return {
+        mode: 'dual-layer/partitioned',
+        reason: `host layer verified at ${recorded} (fingerprint ${installedFp.slice(0, 12)})`,
+    };
+}
+
+/**
+ * Does this artefact exist ONLY for this package?
+ *
+ * True iff `workspaces:` is present, non-empty, and its every entry is
+ * {@link MAINTAINER_WORKSPACE}. Measured 2026-08-20: exactly **16** rules in
+ * `src/rules/` satisfy this — the figure ADR-236 partitions on.
+ *
+ * The direction of the default is the opposite of `rule_in_scope`'s, and that
+ * is deliberate rather than an inconsistency. There, an untagged artefact ships
+ * — over-shipping is the safe error for a scope filter. Here, an untagged
+ * artefact is NOT package-only, so it is delivered globally and withheld from
+ * the project layer. Both defaults resolve toward "the artefact is generally
+ * useful"; only one of them is about withholding.
+ */
+export function isExclusivelyPackageOnly(source_path: string): boolean {
+    let meta: Record<string, unknown>;
+    try {
+        [meta] = parseFrontmatter(fs.readFileSync(source_path, 'utf-8'));
+    } catch {
+        return false; // unreadable → not package-only → delivered globally
+    }
+    const raw = meta['workspaces'];
+    if (!Array.isArray(raw) || raw.length === 0) {
+        return false;
+    }
+    return raw.every((w) => String(w) === MAINTAINER_WORKSPACE);
+}
+
+/** Emitter for the ONE mode line; see the visibility note on the resolver. */
+export type Announce = (message: string) => void;
+
+let _memo: PartitionVerdict | 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.
+ */
+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 {
+    _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.
+ *
+ * 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.
+ *
+ * **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.
+ */
+export function resolvePartitionVerdict(projectRoot: string): PartitionVerdict {
+    if (_memo !== null) {
+        return _memo;
+    }
+    const layers = hostLayerInputs(os.homedir());
+    const present = layers.some((l) => {
+        try {
+            return fs.statSync(l.root).isDirectory();
+        } catch {
+            return false;
+        }
+    });
+    let lock: LockfileFacts | null = null;
+    try {
+        lock = read_lockfile();
+    } catch {
+        lock = null; // unreadable record → fail safe
+    }
+    _memo = partitionVerdict({
+        projectVersion: current_package_version(projectRoot),
+        lockfile: lock,
+        hostLayerPresent: present,
+        expectedFingerprint: () => fingerprintLayers(layers),
+    });
+    _announce(`projection mode: ${_memo.mode} — ${_memo.reason}`);
+    return _memo;
+}
+
+/**
+ * Stamp the host-layer content fingerprint into the install record.
+ *
+ * The write side of the partition, and what makes it reachable at all: the build
+ * withholds artefacts only when this fingerprint matches what it finds on disk.
+ * No fingerprint recorded → full projection, which is the safe direction.
+ *
+ * **Call it AFTER the deploy and after the failed-tool postcheck.** The install
+ * writes its lockfile once before the redeploy; a fingerprint taken there would
+ * describe the PREVIOUS install and then verify against a layer this run
+ * replaced. Both council seats required the record be written last, and this is
+ * the function that respects it.
+ *
+ * On failure it reports and writes NOTHING. A missing fingerprint is fail-safe; a
+ * wrong one would authorise a partition against an unverified layer, so the two
+ * 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
+ * serves, and `install.ts` is 5,000+ lines where the source-size ratchet counts
+ * every added line.
+ *
+ * @returns the fingerprint written, or `null` when nothing was recorded.
+ */
+export function stampHostLayerFingerprint(
+    installedVersion: string,
+    tools: readonly string[],
+    lockfilePath: string,
+    /** Skip entirely — e.g. when the claude-code deploy itself failed. */
+    skip: boolean,
+    report: Announce,
+): string | null {
+    if (skip) {
+        return null;
+    }
+    try {
+        const fingerprint = fingerprintLayers(hostLayerInputs(os.homedir()));
+        write_lockfile(installedVersion, [...tools], {
+            path: lockfilePath,
+            host_layer_fingerprint: fingerprint,
+        });
+        report(`Host-layer fingerprint recorded: ${fingerprint.slice(0, 12)} (enables single delivery)`);
+        return fingerprint;
+    } catch (e) {
+        report(
+            `Host-layer fingerprint NOT recorded (${String(e)}) — the project layer keeps the full projection.`,
+        );
+        return null;
+    }
+}

package/src/scripts/_cli/cmd_session_recycle.ts

@@ -41,6 +41,7 @@ import {
 } from '../_lib/subagent_capsule.js';
 import { collectGrounding } from '../_lib/envelope_grounding.js';
 import { atomic_write_json } from '../hooks/state_io.js';
+import { env_session_id } from '../sessions_cli.js';
 
 export interface RecycleResult {
     code: 0 | 1 | 2;
@@ -185,7 +186,14 @@ export function runSessionRecycle(
     // composed. A model-written branch is a claim; this is a reading. The
     // composer cannot override them — a "next_task" it got wrong is a
     // proposal, a "head" it got wrong is a silent stale resume.
-    const grounding = collectGrounding(projectRoot);
+    // The session id is the ONLY channel to this session's verify state, which
+    // the producer keys per session. `env_session_id` is the canonical resolver
+    // (package variable first, then the host's `CLAUDE_CODE_SESSION_ID`) and is
+    // imported rather than re-implemented — a second copy of that precedence
+    // order would drift from the one a test covers. A host that exports neither
+    // yields `null`, and `last_verify` is then simply absent from the envelope
+    // (the delete-then-set below already treats an unreadable fact as absent).
+    const grounding = collectGrounding(projectRoot, env_session_id());
     // Drop the composer's factual keys UNCONDITIONALLY first. Guarding each
     // assignment on `!== null` would leave a model-composed branch or head
     // standing whenever the git read fails — the consumer would then compare

package/src/scripts/_dispatch.bash

@@ -220,6 +220,7 @@ Tier 2 — maintenance / internal (hooks, MCP, memory, telemetry):
                              (deliberate recycle instead of auto-compact). Flags:
                              --file <json> | --template; default reads stdin
   roadmap:progress           Regenerate agents/roadmaps-progress.md from open roadmaps
+                             (archives completed roadmaps; --no-archive to skip)
   roadmap:progress-check     Fail if agents/roadmaps-progress.md is stale (for CI)
   roadmap:archive            Archive completed roadmaps (branch-touched by default;
                              --all for every complete one; --dry-run to preview)
@@ -717,10 +718,14 @@ cmd_brand_status() {
   exec_ts "$PACKAGE_ROOT/src/scripts/_cli/cmd_brand_status.ts" "$@"
 }
 
+# `--archive`: a completed roadmap is archived here rather than reported as a
+# warning the caller has to act on. `roadmap:progress-check` never passes it —
+# a CI gate must not mutate the tree it is checking. Pass `--no-archive` to get
+# the dashboard-only behaviour back.
 cmd_roadmap_progress() {
   local script
   script="$(resolve_script "dist/agent-src/scripts/update_roadmap_progress.ts" ".augment/scripts/update_roadmap_progress.ts")"
-  exec_ts "$script" "$@"
+  exec_ts "$script" --archive "$@"
 }
 
 cmd_roadmap_progress_check() {

package/src/scripts/_lib/ac_heading.ts

@@ -0,0 +1,30 @@
+/**
+ * The one matcher for a roadmap's `## Acceptance criteria` heading.
+ *
+ * It lives here because the same defect has now been found three times, in
+ * three separately-authored copies of this regex:
+ *
+ * 1. `dispatch_r2_reviewer.extractAcceptanceCriteria` was case-sensitive, so
+ *    `## Acceptance criteria` extracted nothing (zcs-close R2 review, 2026-08-09).
+ * 2. The same function was end-anchored, so a heading carrying a qualifier —
+ *    `## Acceptance criteria (per phase, on promotion to ready)` — extracted
+ *    nothing (measured 2026-08-18).
+ * 3. `lint_plan_risk_register.extractFeatures` carried BOTH faults after the
+ *    other two were fixed, so the substantial-change heuristic hashed the empty
+ *    string for eight of the thirty-two ready roadmaps — including the roadmap
+ *    that repaired it. Any edit to those roadmaps' criteria was invisible to the
+ *    gate, which is the silent half of the failure: the gate still exited 0.
+ *
+ * Two copies drift. Three copies drift twice. The predicate is a shared constant
+ * so the next author cannot fix one call site and leave another blind.
+ *
+ * `\b` after `criteria` is the deliberate near-miss guard: `## Acceptance
+ * criteriaXYZ` is a different heading and must not match. It is asserted from
+ * both directions in `tests/scripts/lint_plan_risk_register.test.ts`.
+ */
+export const AC_HEADING_RE = /^##\s+acceptance criteria\b/i;
+
+/** True when `line` is a roadmap's acceptance-criteria section heading. */
+export function isAcceptanceCriteriaHeading(line: string): boolean {
+    return AC_HEADING_RE.test(line);
+}

package/src/scripts/_lib/agent_src.ts

@@ -277,10 +277,49 @@ export function _domains_command_logical(p: string): string | null {
     return `commands/${subpath}.md`;
 }
 
+/**
+ * Is this domains path inside a `__`-prefixed SCRATCH pack?
+ *
+ * ## Why this exists — a measured cross-test contamination
+ *
+ * A pack id is a lowercase slug (`slug_prefix` is validated against
+ * `^[a-z][a-z0-9-]*$`), so a directory whose name starts with `__` is not a
+ * pack that can ship. It is a test scratch marker, and the walkers must not
+ * count it.
+ *
+ * The defect this closes, measured 2026-08-20 on a full local suite run:
+ * `check_artefact_count_messaging`'s "live gate — real repo surfaces" test
+ * PASSED in isolation and FAILED in the suite, reporting
+ * `commands says 200, expected 207`. The +7 is exact and traceable:
+ * `lint_originality.test.ts` writes seven `command.md` files into the REAL tree
+ * at `src/domains/__origtest_batch/c1..c7/` (it must — that gate classifies an
+ * artefact by its PATH, so a tmpdir would not be a "command" at all), and
+ * removes them in `afterEach`. Vitest runs test files in parallel workers, so
+ * while those seven exist a concurrent worker counting the live tree sees 207.
+ *
+ * This is a SCOPE defect, not a flaky test: a gate asserting over the developer's
+ * live tree is not hermetic, and the remedy is a fixture boundary rather than a
+ * relaxed expectation. The boundary is placed here, at the point where a path
+ * becomes a counted artefact, because that is the one place that fixes it for
+ * every counter at once — and it weakens nothing: the count of real artefacts is
+ * still asserted exactly.
+ *
+ * Checked before shipping: no pack under `src/domains/` uses a `__` prefix, and
+ * `lint_originality` does not consume these walkers (it reads its corpus from
+ * the `--changed` paths it is handed), so its own batch test is unaffected.
+ */
+function _isScratchPack(domains_root: string, full: string): boolean {
+    const rel = path.relative(domains_root, full);
+    const first = rel.split(path.sep)[0];
+    return first !== undefined && first.startsWith('__');
+}
+
 /**
  * Yield `[physical_path, logical_relpath]` for every domains command, in
  * deterministic order. Naturally inert until `src/domains/*\/**\/command.md`
  * files exist. Mirrors `_iter_domains_commands`.
+ *
+ * Skips `__`-prefixed scratch packs — see `_isScratchPack`.
  */
 export function* _iter_domains_commands(): Generator<[string, string]> {
     const dom = _roots.SRC_DOMAINS;
@@ -291,6 +330,9 @@ export function* _iter_domains_commands(): Generator<[string, string]> {
         if (!_isFile(p)) {
             continue;
         }
+        if (_isScratchPack(dom, p)) {
+            continue;
+        }
         const logical = _domains_command_logical(p);
         if (logical !== null) {
             yield [p, logical];