@event4u/agent-config 14.21.0 → 14.23.0

package/src/scripts/check_estate_count.ts

@@ -155,8 +155,6 @@ import { materialiseSubtree } from './_lib/base_tree.js';
 import { SKILLS_POSIX, measureSkillEstate } from './_lib/skill_estate.js';
 import { CONCERN_MANIFEST_POSIX, countConcerns } from './_lib/concern_estate.js';
 import { runGateCli, runSelfTest, type SelfTestCase } from './_lib/gate_self_test.js';
-import { countDeclaredCarriers, declaresCarrier } from './_lib/carrier_status.js';
-import { carrierEstateCases } from './_lib/estate_carrier_cases.js';
 
 const GATE = 'check_estate_count';
 const BUDGET_REL = path.join('src', 'config', 'estate-count-budget.json');
@@ -438,38 +436,12 @@ function countIn(roadmapRoot: string, sub: string): number {
     }
 }
 
-/**
- * Top-level roadmaps `collect()` drops for declaring `status: carrier`, added
- * back so that FLIPPING a status is count-neutral.
- *
- * Measured before this: flipping one file to `carrier` moved `active_roadmaps
- * 3 → 2` and the gate printed "estate within its ratchet", because a count
- * below the floor is a drawdown and free. The floor is measured at the base
- * ref, so once such a flip merges the lowered number becomes the next floor —
- * the file cannot be flipped back without paying, and any roadmap can be
- * laundered out of the count by adding one word.
- *
- * A reclassification is not a disposal, so the metric counts the file on both
- * sides. Same argument `open_blockers` makes below for spanning `later/`.
- * Deleting a carrier is still a shrink and still earns no offset
- * (`classifyDiff`); adding one is growth that takes the claim path.
- *
- * This is therefore the one roadmap metric that does NOT equal the dashboard
- * header, stated here rather than left to be tripped over.
- */
-function countActiveCarriers(roadmapRoot: string): number {
-    return countDeclaredCarriers(roadmapRoot, isRoadmapCandidate, fs, path.join);
-}
-
 /**
  * Roadmaps parked in `later/` whose blockers count, parsed for them.
  *
- * Skips a draft AND a carrier, which is the same pair `collect()` skips on the
- * active side. It used to skip only the draft, so parking a carrier moved its
- * blockers INTO the gated count while the identical file at the top level kept
- * them out — a ratchet verdict that moved on a relocation, for no stated
- * reason. Three of the four status readers learned `carrier` when the status
- * shipped; this is the fourth.
+ * Skips exactly what `collect()` skips on the active side, through the same
+ * `isUnscheduled` predicate. Skipping a different set here would make a ratchet
+ * verdict move on a relocation, for no stated reason.
  */
 function laterRoadmaps(roadmapRoot: string): Array<{ open_blockers: readonly unknown[] }> {
     const dir = path.join(roadmapRoot, 'later');
@@ -496,10 +468,13 @@ function laterRoadmaps(roadmapRoot: string): Array<{ open_blockers: readonly unk
 /**
  * Count the estate, three ways.
  *
- * `active_roadmaps` is `collect()` PLUS the top-level carriers `collect()`
- * drops, so the parser is shared with the dashboard while a status flip stays
- * count-neutral — see `countActiveCarriers` for why that beats parity here, and
- * for the one number on this gate that the dashboard header does not print.
+ * `active_roadmaps` is `collect()`, so the parser is shared with the dashboard
+ * and the number equals the dashboard header. It used to carry an add-back for
+ * the top-level roadmaps `collect()` dropped for declaring `status: carrier`,
+ * which existed only to keep FLIPPING to that status count-neutral — a flip
+ * lowered the count, a count below the floor is a free drawdown, and the
+ * lowered number then became the next floor. ADR-262 deleted the status, so
+ * there is no flip to neutralise and no divergence from the header left.
  * `later_roadmaps` is a directory listing because parked files are
  * outside that corpus by design — filtered through the same `is_roadmap_candidate`
  * predicate as the active side, so `later/README.md` is not a roadmap here either.
@@ -524,7 +499,7 @@ export function countEstate(repoRoot: string): EstateCounts {
         rows.reduce((n, r) => n + r.open_blockers.length, 0);
     const skills = measureSkillEstate(repoRoot);
     return {
-        active_roadmaps: stats.length + countActiveCarriers(roadmapRoot),
+        active_roadmaps: stats.length,
         later_roadmaps: countIn(roadmapRoot, 'later'),
         open_blockers: openOf(stats) + openOf(laterRoadmaps(roadmapRoot)),
         skill_count: skills.skill_count,
@@ -590,9 +565,6 @@ export function exemptionReason(text: string): string | null {
     return reason === '' ? null : reason;
 }
 
-/** Re-export; `_lib/carrier_status.ts` holds the one implementation. */
-export const isCarrierText = declaresCarrier;
-
 /**
  * Classify the change's effect on the active roadmap tree.
  *
@@ -604,13 +576,6 @@ export const isCarrierText = declaresCarrier;
 export function classifyDiff(
     nameStatus: string,
     readFile: (rel: string) => string | null,
-    /**
-     * The file's content at the BASE ref, for paths this change removed — a
-     * deleted carrier cannot be read from the working tree and its status
-     * decides whether the deletion earns an offset. Defaults to null, which
-     * reproduces the previous scoring for any caller without a pre-image.
-     */
-    readBase: (rel: string) => string | null = () => null,
 ): OffsetLedger {
     const added: string[] = [];
     const offsets: string[] = [];
@@ -624,10 +589,8 @@ export function classifyDiff(
             const from = cols[1] ?? '';
             const to = cols[2] ?? '';
             if (isActiveTopLevel(from) && isDisposed(to)) {
-                if (!isCarrierText(readBase(from))) {
-                    offsets.push(from);
-                    if (isParked(to)) parked.push(to);
-                }
+                offsets.push(from);
+                if (isParked(to)) parked.push(to);
             } else if (isDisposed(from) && isActiveTopLevel(to)) {
                 added.push(to);
             }
@@ -638,10 +601,7 @@ export function classifyDiff(
         if (status === 'A') {
             added.push(file);
         } else if (status === 'D') {
-            // A carrier's removal is never an offset. See `readBase`.
-            if (!isCarrierText(readBase(file))) {
-                offsets.push(file);
-            }
+            offsets.push(file);
         }
     }
     for (const file of added) {
@@ -832,20 +792,13 @@ export function evaluate(
         if (!diff.ok) {
             offsetSkipReason = `git diff against ${baseRef} failed — one-in-one-out not evaluated`;
         } else {
-            offsets = classifyDiff(
-                diff.stdout,
-                (rel) => {
-                    try {
-                        return fs.readFileSync(path.join(repoRoot, rel), 'utf-8');
-                    } catch {
-                        return null;
-                    }
-                },
-                (rel) => {
-                    const show = git(['show', `${baseRef}:${rel}`], repoRoot);
-                    return show.ok ? show.stdout : null;
-                },
-            );
+            offsets = classifyDiff(diff.stdout, (rel) => {
+                try {
+                    return fs.readFileSync(path.join(repoRoot, rel), 'utf-8');
+                } catch {
+                    return null;
+                }
+            });
         }
         const patch = git(
             ['diff', '--unified=0', '--find-renames', `${baseRef}...HEAD`, '--', ROADMAPS_REL],
@@ -982,9 +935,6 @@ function selfTest(): number {
     const roadmap = (name: string, extra = ''): string =>
         `# Roadmap: ${name}\n\n## Phase 1\n\n- [ ] **1.1** s\n${extra}`;
 
-    /** A `status: carrier` roadmap — counted as estate, and never an offset. */
-    const CARRIER = `---\nstatus: carrier\n---\n# Roadmap: carrier\n\n## Phase 1\n\n- [~] **1.1** s\n`;
-
     /**
      * A `status: draft` roadmap — invisible to `collect()`, so adding one cannot
      * move `active_roadmaps`. That is what makes it the fixture for a case that
@@ -1197,14 +1147,25 @@ function selfTest(): number {
                     after: (dir) => write(dir, 'agents/roadmaps/later/road-to-parked.md', roadmap('P')),
                 }),
         },
-        ...carrierEstateCases({
-            fixture,
-            write,
-            remove: (dir, rel) => fs.rmSync(path.join(dir, rel)),
-            roadmap,
-            CARRIER,
-            DRAFT,
-        }),
+        {
+            // Survives the deletion of the carrier cases this used to control
+            // for (ADR-262): it asserts the plain rule those cases were the
+            // exception to — a removal offsets an addition — over a DRAFT
+            // addition, which `collect()` cannot see, so only the offset
+            // scoring can decide it.
+            name: 'deleting an ordinary roadmap offsets a new draft → accept',
+            expect: 'accept',
+            run: () =>
+                fixture({
+                    roadmaps: 3,
+                    base: 'main',
+                    before: (dir) => write(dir, 'agents/roadmaps/road-to-spare.md', roadmap('S')),
+                    after: (dir) => {
+                        fs.rmSync(path.join(dir, 'agents/roadmaps/road-to-spare.md'));
+                        write(dir, 'agents/roadmaps/road-to-new.md', DRAFT);
+                    },
+                }),
+        },
         {
             name: 'a new open blocker with no claim → reject',
             expect: 'reject',

package/src/scripts/check_host_tree_parity.ts

@@ -0,0 +1,291 @@
+#!/usr/bin/env tsx
+/**
+ * A host outside `lean_projection.hosts` receives EXACTLY what `eager-all` writes.
+ *
+ * `road-to-delivery-for-every-host` step 1.4, and the gate behind its AC-2.
+ *
+ * WHY A SEPARATE GATE FROM `check_rule_projection_integrity`
+ * ---------------------------------------------------------
+ * That gate reads the trees AS THEY STAND — no regeneration, by design, because
+ * its job is to catch a STALE tree and regenerating erases the evidence. Its 1.3
+ * host axis therefore asks a content question about the entries that exist:
+ * "is any of these a stub in a tree that should hold bodies?"
+ *
+ * That is necessary and it is not sufficient. It cannot see a projector change
+ * that alters a non-delivery host's output in some way OTHER than stubbing it —
+ * a different frontmatter rewrite, a dropped rule, an added byte. The AC is
+ * byte-identity, and byte-identity can only be established by producing both
+ * trees and comparing them.
+ *
+ * So this gate GENERATES, twice, into a temporary root it owns:
+ *
+ *   1. `mode: eager-all`            → the reference trees
+ *   2. `mode: delivery`, the configured `hosts:` → the trees under test
+ *
+ * and requires every tree whose host is NOT in `hosts` to be byte-identical
+ * across the two runs. It never writes into the repository: the fixture root is
+ * a `mkdtemp` directory, seeded from `dist/agent-src/rules`, and removed on exit.
+ *
+ * WHAT IT DELIBERATELY DOES NOT DO
+ * --------------------------------
+ * It does not assert that the DELIVERY host's tree changed. A flip that thins
+ * nothing is a different defect and `check_rule_projection_integrity` plus the
+ * unit corpus already cover it; asserting it here would make this gate fail on a
+ * legitimate `hosts: []`, which is the safe configuration.
+ *
+ * AND IT ASSERTS NOTHING WHEN EVERY THINNABLE HOST IS ENROLLED. With
+ * `hosts: [claude-code, cursor, cline]` there is no non-delivery tree, so the
+ * comparison has no subject. That case now prints a `⚠️  NOTHING COMPARED` line
+ * naming the gate that does carry the question, instead of the `✅ … 0 …
+ * byte-identical` line it printed until 2026-09-08 (R2 finding 12) — a green
+ * sentence for an assertion that was never made.
+ *
+ * IT ALSO DOES NOT CONSULT `lean_projection.mode`, and the divergence from
+ * `check_rule_projection_integrity._lean_projection_settings_for` — which
+ * checks the mode FIRST so "a `hosts:` list left behind after a rollback
+ * exempts nothing" — is deliberate. Recorded 2026-09-08 because R2 finding 13
+ * read it as an oversight, and running the mode-first variant here reddens the
+ * gate on this repository's own settings, which carry no `lean_projection`
+ * block at all.
+ *
+ * The two gates ask different questions. The sibling asks a question ABOUT THE
+ * CURRENT TREE — "is any entry on disk a stub in a tree with no delivery
+ * slot?" — so the live mode is part of its subject. This gate asks a
+ * COUNTERFACTUAL ABOUT THE PROJECTOR — "under a thinning mode with the
+ * configured hosts, would every other host's tree still be byte-identical?" —
+ * and supplies `mode: delivery` to its own test fixture to ask it. Reading the
+ * live mode would make the exemption set and the fixture disagree: with the
+ * mode off, `configured` would be empty while the fixture still thinned, and
+ * every stub in the delivery host's tree would be reported as a parity break.
+ *
+ * The consequence the finding names is real and is not a hole: after a rollback
+ * to `eager-all`, a leftover `hosts: [claude-code]` still excludes
+ * `.claude/rules` from THIS comparison. Nothing is hidden by that, because
+ * under `eager-all` nothing is thinned and the on-disk state is the sibling
+ * gate's subject.
+ *
+ * It also does not read the repository's own `.claude/rules` etc. Those are
+ * gitignored and absent on a fresh CI checkout, and a gate that silently passes
+ * when its subject is missing is the shape this repository's scan-scope
+ * discipline exists to reject — hence the fixture root, which always exists.
+ *
+ * Exit: 0 parity holds · 1 a non-delivery host's tree differs · 2 the gate could
+ * not run (no rule corpus to seed from).
+ */
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { GateLedger, UnaccountedTargetsError } from './_lib/gate_ledger.js';
+import { leanProjectionHostsRaw } from './_lib/hook_settings.js';
+import { resolveLeanProjectionHosts } from './_lib/lean_projection_mode.js';
+import { reportScanned } from './_lib/scan_scope.js';
+import {
+    _getStateForTest,
+    _resetStateForTest as _pointCondenseAt,
+    generate_rule_symlinks,
+} from './condense.js';
+
+const _HERE = path.resolve(fileURLToPath(import.meta.url));
+export const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+/** The tool dirs this gate compares, and the host each belongs to. */
+export const TREES: Readonly<Record<string, string>> = {
+    '.claude/rules': 'claude-code',
+    '.cursor/rules': 'cursor',
+    '.clinerules': 'cline',
+};
+
+/** Every entry in `dir` as `name -> content`, reading through symlinks. */
+export function treeContents(root: string, rel: string): Record<string, string> {
+    const dir = path.join(root, rel);
+    const out: Record<string, string> = {};
+    if (!fs.existsSync(dir)) return out;
+    for (const name of fs.readdirSync(dir).sort()) {
+        if (name === 'README.md') continue;
+        try {
+            out[name] = fs.readFileSync(path.join(dir, name), 'utf-8');
+        } catch {
+            out[name] = '<unreadable>';
+        }
+    }
+    return out;
+}
+
+/** Copy the rule corpus into a fresh fixture root carrying `settings`. */
+function seedFixture(repoRoot: string, tmp: string, label: string, settings: string): string {
+    const root = path.join(tmp, label);
+    const dist = path.join(root, 'dist', 'agent-src', 'rules');
+    fs.mkdirSync(dist, { recursive: true });
+    const src = path.join(repoRoot, 'dist', 'agent-src', 'rules');
+    for (const name of fs.readdirSync(src).filter((f) => f.endsWith('.md'))) {
+        fs.copyFileSync(path.join(src, name), path.join(dist, name));
+    }
+    fs.writeFileSync(path.join(root, '.agent-settings.yml'), settings, 'utf-8');
+    return root;
+}
+
+export interface ParityFinding {
+    readonly tree: string;
+    readonly host: string;
+    readonly rule: string;
+    readonly reason: string;
+}
+
+/** Compare two generated trees, reporting every difference in a non-delivery host's tree. */
+export function compareTrees(
+    eagerRoot: string,
+    testRoot: string,
+    deliveryHosts: readonly string[],
+): ParityFinding[] {
+    const out: ParityFinding[] = [];
+    for (const [tree, host] of Object.entries(TREES)) {
+        if (deliveryHosts.includes(host)) continue;
+        const a = treeContents(eagerRoot, tree);
+        const b = treeContents(testRoot, tree);
+        for (const name of new Set([...Object.keys(a), ...Object.keys(b)])) {
+            const left = a[name];
+            const right = b[name];
+            if (left === right) continue;
+            const reason =
+                left === undefined
+                    ? 'present under the thinning mode and absent under eager-all'
+                    : right === undefined
+                      ? 'written by eager-all and MISSING under the thinning mode'
+                      : `content differs (${String(left.length)} vs ${String(right.length)} bytes)`;
+            out.push({ tree, host, rule: name, reason });
+        }
+    }
+    return out;
+}
+
+/**
+ * The notice for a comparison with NO SUBJECT, or `null` when there is one.
+ *
+ * R2 finding 12: with every thinnable host in `lean_projection.hosts` there is
+ * no non-delivery tree left, so this gate's assertion is VACUOUS — and it used
+ * to say so inside the same `✅ … byte-identical` sentence it prints when the
+ * assertion actually held. Zero compared is not a pass; it is an absence of
+ * subject, and the reader has to be told which gate carries the question
+ * instead.
+ *
+ * Deliberately NOT an exit-1: enrolling all three hosts is a legal
+ * configuration, and reddening a legal configuration is how a gate gets
+ * switched off. Pure and exported so the wording is under test without running
+ * the two-fixture generation.
+ */
+export function parityScopeNotice(configured: readonly string[]): string | null {
+    const comparable = Object.entries(TREES).filter(([, h]) => !configured.includes(h));
+    if (comparable.length > 0) return null;
+    return (
+        `⚠️  check_host_tree_parity: NOTHING COMPARED — every thinnable host is in ` +
+        `lean_projection.hosts [${configured.join(', ') || '(none)'}], so no non-delivery tree ` +
+        `exists and this gate asserts nothing about this configuration. A stub in a tree with ` +
+        `no bound delivery slot is reported by check_rule_projection_integrity's host axis ` +
+        `(thinnedTreeFindings); the byte-identity question here has no subject.\n`
+    );
+}
+
+export function main(argv: readonly string[] = []): number {
+    const root = REPO_ROOT;
+    const dist = path.join(root, 'dist', 'agent-src', 'rules');
+    if (!fs.existsSync(dist) || fs.readdirSync(dist).filter((f) => f.endsWith('.md')).length === 0) {
+        process.stderr.write(
+            `❌  check_host_tree_parity: no rule corpus at dist/agent-src/rules — run \`task sync\` first.\n`,
+        );
+        return 2;
+    }
+    const configured = resolveLeanProjectionHosts(leanProjectionHostsRaw(root)).hosts;
+    const hostList = configured.join(', ') || '(none)';
+
+    const saved = _getStateForTest();
+    const savedHome = process.env['HOME'];
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'host-parity-'));
+    let findings: ParityFinding[];
+    try {
+        // An empty HOME: user-scope dedup must find no twin, or the two runs
+        // would differ for a reason that has nothing to do with the host axis.
+        const home = path.join(tmp, 'home');
+        fs.mkdirSync(home, { recursive: true });
+        process.env['HOME'] = home;
+
+        const eagerRoot = seedFixture(root, tmp, 'eager', 'lean_projection:\n  mode: eager-all\n');
+        _pointCondenseAt(eagerRoot);
+        generate_rule_symlinks();
+
+        const hostsBlock = configured.length === 0 ? '' : `  hosts: [${configured.join(', ')}]\n`;
+        const testRoot = seedFixture(root, tmp, 'test', `lean_projection:\n  mode: delivery\n${hostsBlock}`);
+        _pointCondenseAt(testRoot);
+        generate_rule_symlinks();
+
+        findings = compareTrees(eagerRoot, testRoot, configured);
+    } finally {
+        _pointCondenseAt(saved.PROJECT_ROOT);
+        if (savedHome === undefined) delete process.env['HOME'];
+        else process.env['HOME'] = savedHome;
+        fs.rmSync(tmp, { recursive: true, force: true });
+    }
+
+    const compared = Object.entries(TREES).filter(([, h]) => !configured.includes(h)).length;
+    reportScanned({
+        gate: 'check_host_tree_parity',
+        scanned: compared,
+        units: 'non-delivery host rule tree(s)',
+        roots: Object.keys(TREES),
+    });
+
+    // One ledger target per non-delivery tree, not per entry: the assertion is
+    // about a TREE being byte-identical, and a per-entry ledger would report
+    // 200-odd completed targets for what is three yes/no questions.
+    const ledger = new GateLedger('check_host_tree_parity');
+    const compareable = Object.entries(TREES).filter(([, h]) => !configured.includes(h)).map(([t]) => t);
+    ledger.plan(compareable);
+    const broken = new Set(findings.map((f) => f.tree));
+    for (const tree of compareable) {
+        if (broken.has(tree)) ledger.fail(tree, 'differs from the eager-all projection');
+        else ledger.complete(tree);
+    }
+    try {
+        if (argv.includes('--quiet')) ledger.finalize();
+        else ledger.report();
+    } catch (exc) {
+        if (exc instanceof UnaccountedTargetsError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
+    if (findings.length > 0) {
+        process.stderr.write(
+            `❌  check_host_tree_parity: ${String(findings.length)} entry(ies) differ between ` +
+                `eager-all and delivery on a host that is NOT in lean_projection.hosts [${hostList}]:\n`,
+        );
+        for (const f of findings) {
+            process.stderr.write(`  · ${f.tree}/${f.rule} (${f.host}) — ${f.reason}\n`);
+        }
+        process.stderr.write(
+            '\nA host outside `lean_projection.hosts` must receive exactly what `eager-all` writes ' +
+                '(K3, and the completeness invariant). Fix the projector, never the expectation.\n',
+        );
+        return 1;
+    }
+    const notice = parityScopeNotice(configured);
+    if (notice !== null) {
+        process.stderr.write(notice);
+        return 0;
+    }
+    if (!argv.includes('--quiet')) {
+        process.stdout.write(
+            `✅  check_host_tree_parity: ${String(compared)} non-delivery host tree(s) byte-identical to ` +
+                `eager-all · delivery hosts [${hostList}]\n`,
+        );
+    }
+    return 0;
+}
+
+if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+    process.exit(main(process.argv.slice(2)));
+}