@event4u/agent-config 14.11.0 → 14.13.0

package/src/scripts/check_estate_count.ts

@@ -152,6 +152,8 @@ import { reportScanned, DeadScopeError } from './_lib/scan_scope.js';
 import { GateLedger } from './_lib/gate_ledger.js';
 import { resolveBaseRef } from './_lib/ratchet_base_ref.js';
 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';
 
 const GATE = 'check_estate_count';
@@ -171,11 +173,53 @@ export interface EstateCounts {
     active_roadmaps: number;
     later_roadmaps: number;
     open_blockers: number;
+    /**
+     * Maintained `SKILL.md` files — `lifecycle: deprecated` excluded.
+     *
+     * A FOURTH corpus on the same machinery, added 2026-08-24 on AI council 2/2
+     * over the alternative of a second budget file and a second gate: the
+     * floor-from-the-base-ref machinery is the expensive part and should not be
+     * written twice, and a second ratchet is a second place to forget.
+     */
+    skill_count: number;
+    /**
+     * Exact-BPE tokens across those skills' `description:` fields.
+     *
+     * The second DIMENSION, not a companion figure. A count ratchet alone is
+     * gameable by merging four large skills into one file: the count falls, the
+     * payload a host must carry does not. `0` here means UNRESOLVED, never
+     * "no tokens" — see `tokensExact`.
+     */
+    skill_description_tokens: number;
+    /**
+     * Hook concerns declared in `src/scripts/hook_manifest.yaml`.
+     *
+     * A FIFTH corpus on the same machinery, and the same argument that admitted
+     * skills: the floor-from-the-base-ref work is the expensive part and should
+     * not be written a third time, and a separate ratchet is a separate place to
+     * forget.
+     *
+     * Read with the SCOPED parser in `_lib/concern_estate.ts`, not the
+     * whole-file grep the originating roadmap reproduces its series with. That
+     * grep over-counts by exactly 16 at every one of its six pins, because
+     * `roles:`, `platforms:` and `native_event_aliases:` sit at the same indent.
+     * The growth finding survives the correction — the delta is constant — but
+     * the absolute figure does not: the axis stands at 55, not 71, and a floor
+     * of 71 is one this gate's own parser could never reproduce.
+     */
+    concern_count: number;
 }
 
 export type MetricName = keyof EstateCounts;
 
-export const METRICS: readonly MetricName[] = ['active_roadmaps', 'later_roadmaps', 'open_blockers'];
+export const METRICS: readonly MetricName[] = [
+    'active_roadmaps',
+    'later_roadmaps',
+    'open_blockers',
+    'skill_count',
+    'skill_description_tokens',
+    'concern_count',
+];
 
 export interface EstateBudget {
     /**
@@ -247,6 +291,16 @@ export interface EstateVerdict {
     authorisedGrowth: GrowthFinding[];
     /** The claims found in this change's diff, with their reasons. */
     claims: GrowthClaim[];
+    /**
+     * Metrics dropped from the compare, each with its reason.
+     *
+     * Never empty-and-silent: a skill metric drops when the base ref carries no
+     * `src/skills` (an old tag, a shallow clone) or when the tokeniser resolved
+     * on one side and not the other. Comparing an exact reading against a proxy
+     * one would move the number by more than the growth this gate exists to
+     * catch, so the metric is stated unavailable rather than guessed.
+     */
+    skippedMetrics: { metric: MetricName; reason: string }[];
     /** `null` when the diff half could not run; the reason is printed either way. */
     offsets: OffsetLedger | null;
     offsetSkipReason: string | null;
@@ -268,6 +322,29 @@ function repoRootFrom(start: string): string {
     }
 }
 
+/** File contents, or `null` when it is absent. Absent is a real state here. */
+function readIfPresent(file: string): string | null {
+    try {
+        return fs.readFileSync(file, 'utf-8');
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Concern count at a git ref, or `null` when the manifest is unreadable there.
+ *
+ * `null` is NOT zero, and the distinction is the whole reason this returns an
+ * option. A missing manifest read as 0 makes the floor 0, which makes the
+ * ratchet inert on that path while still printing a green line — "a gate that
+ * read nothing has not passed", in this repository's own words. The caller
+ * turns `null` into a floor-skip, which this gate already treats as a failure.
+ */
+function concernCountAt(repoRoot: string, ref: string): number | null {
+    const res = git(['show', `${ref}:${CONCERN_MANIFEST_POSIX}`], repoRoot);
+    return res.ok ? countConcerns(res.stdout) : null;
+}
+
 function git(args: readonly string[], cwd: string): { ok: boolean; stdout: string } {
     const res = spawnSync('git', [...args], { cwd, encoding: 'utf-8', maxBuffer: 32 * 1024 * 1024 });
     return { ok: res.status === 0, stdout: res.stdout ?? '' };
@@ -342,13 +419,27 @@ export function countEstate(repoRoot: string): EstateCounts {
     const stats = collect(roadmapRoot);
     const openOf = (rows: readonly { open_blockers: readonly unknown[] }[]): number =>
         rows.reduce((n, r) => n + r.open_blockers.length, 0);
+    const skills = measureSkillEstate(repoRoot);
     return {
         active_roadmaps: stats.length,
         later_roadmaps: countIn(roadmapRoot, 'later'),
         open_blockers: openOf(stats) + openOf(laterRoadmaps(roadmapRoot)),
+        skill_count: skills.skill_count,
+        // 0 stands for unresolved. `skillTokensExact` below is what the caller
+        // reads to tell that apart from a genuinely empty corpus, and the
+        // verdict skips the metric rather than comparing an exact reading
+        // against a proxy one — they differ by more than the growth a ratchet
+        // is trying to catch.
+        skill_description_tokens: skills.skill_description_tokens ?? 0,
+        concern_count: countConcerns(readIfPresent(path.join(repoRoot, CONCERN_MANIFEST_POSIX)) ?? ''),
     };
 }
 
+/** Did the tokeniser resolve under `root`? A ratchet must not mix the two modes. */
+export function skillTokensExact(root: string): boolean {
+    return measureSkillEstate(root).skill_description_tokens !== null;
+}
+
 /** `agents/roadmaps/<name>.md` — the active top level, never a subdirectory. */
 function isActiveTopLevel(rel: string): boolean {
     const norm = rel.split(path.sep).join('/');
@@ -506,19 +597,89 @@ export function evaluate(
     // property, and unlike a number nobody has to remember to update it.
     let floor: EstateCounts | null = null;
     let floorSkipReason: string | null = null;
+    /**
+     * Does the WORKING TREE carry a manifest at all?
+     *
+     * The base-ref read only matters when it does. A repository with no manifest
+     * on either side has no concern axis to ratchet, and failing there would
+     * turn every unrelated fixture red — which is how the first version of this
+     * clause was caught.
+     */
+    const headHasManifest = fs.existsSync(path.join(repoRoot, CONCERN_MANIFEST_POSIX));
+    /** Set when the base ref carries no `src/skills` — the skill metrics drop. */
+    let skillFloorSkipReason: string | null = null;
+    /** Set when either side's tokeniser did not resolve — that ONE metric drops. */
+    let skillTokenSkipReason: string | null = null;
+    if (!skillTokensExact(repoRoot)) {
+        skillTokenSkipReason =
+            'the tokeniser did not resolve at HEAD; an exact reading may not be compared ' +
+            'against a proxy one';
+    }
     if (baseRef === null || baseRef === undefined) {
         floorSkipReason =
             'no base ref resolved (no origin/main, no merge-commit parent) — the floor cannot be measured';
     } else {
         const base = materialiseSubtree(repoRoot, baseRef, ROADMAPS_POSIX);
+        // TWO subtrees, because the estate now spans two corpora and the floor
+        // must be measured on the base ref's own tree for BOTH. Materialised
+        // separately rather than widening the first call: `materialiseSubtree`
+        // takes one prefix, and the roadmap tree must stay readable even when
+        // the skills read fails (a `src/skills`-less base ref is a real state —
+        // an old tag, a shallow clone), in which case the skill metrics skip and
+        // the roadmap metrics still ratchet.
+        const baseSkills = materialiseSubtree(repoRoot, baseRef, SKILLS_POSIX);
         try {
             if (base.error !== null || base.files === 0) {
                 floorSkipReason = `could not read ${ROADMAPS_POSIX} at ${baseRef} — ${base.error ?? 'no files'}`;
             } else {
-                floor = countEstate(base.root);
+                const roadmapFloor = countEstate(base.root);
+                if (baseSkills.error !== null || baseSkills.files === 0) {
+                    // Roadmap floor stands; the skill floor is stated as
+                    // unavailable and its metrics are dropped from the compare.
+                    const cf = concernCountAt(repoRoot, baseRef);
+                    floor = { ...roadmapFloor, concern_count: cf ?? 0 };
+                    if (cf === null && headHasManifest) {
+                        floorSkipReason =
+                            `could not read ${CONCERN_MANIFEST_POSIX} at ${baseRef} while HEAD ` +
+                            'carries one. A floor of 0 would make the concern ratchet inert while ' +
+                            'still printing green, so this fails rather than skips.';
+                    }
+                    skillFloorSkipReason =
+                        `could not read ${SKILLS_POSIX} at ${baseRef} — ` +
+                        `${baseSkills.error ?? 'no files'}`;
+                } else {
+                    const s = measureSkillEstate(baseSkills.root);
+                    floor = {
+                        ...roadmapFloor,
+                        skill_count: s.skill_count,
+                        skill_description_tokens: s.skill_description_tokens ?? 0,
+                        // A SINGLE FILE, so `git show` rather than a third
+                        // `materialiseSubtree` — stated because the roadmap asks
+                        // which of the two this uses. Materialising a subtree to
+                        // reach one known path would spend a temp tree and a
+                        // recursive ls-tree on a `git cat-file` in disguise.
+                        //
+                        // `?? 0` never stands for "unreadable": the branch below
+                        // turns that into a floor-skip, which fails. This
+                        // coalesce only satisfies the type.
+                        concern_count: concernCountAt(repoRoot, baseRef) ?? 0,
+                    };
+                    if (concernCountAt(repoRoot, baseRef) === null && headHasManifest) {
+                        floorSkipReason =
+                            `could not read ${CONCERN_MANIFEST_POSIX} at ${baseRef} while HEAD ` +
+                            'carries one. A floor of 0 would make the concern ratchet inert while ' +
+                            'still printing green, so this fails rather than skips.';
+                    }
+                    if (s.skill_description_tokens === null) {
+                        skillTokenSkipReason =
+                            `the tokeniser did not resolve at ${baseRef}; an exact reading may ` +
+                            'not be compared against a proxy one';
+                    }
+                }
             }
         } finally {
             fs.rmSync(base.root, { recursive: true, force: true });
+            fs.rmSync(baseSkills.root, { recursive: true, force: true });
         }
     }
 
@@ -571,11 +732,40 @@ export function evaluate(
         active_roadmaps: offsets?.exempt.length ?? 0,
         later_roadmaps: offsets?.parked.length ?? 0,
         open_blockers: 0,
+        // The skill corpus gets NO allowance, and that is the whole point of the
+        // metric: the defect it addresses is a corpus that grew +8 in one release
+        // with nothing objecting. An addition takes the `estate_growth_exempt`
+        // claim path — a recorded reason in the diff — or it fails.
+        skill_count: 0,
+        skill_description_tokens: 0,
+        // Step 1.2: NO new allowance key. The concern axis joins `skill_count`
+        // in taking the claim path or nothing, for the reason the budget file
+        // already records for skills — an allowance reopens the gaming path the
+        // dimension exists to close. Eight concerns spread across eight events
+        // violate the existing per-event cap zero times, which is exactly why a
+        // total-growth ratchet was needed and exactly why it must not carry a
+        // per-change freebie.
+        concern_count: 0,
+    };
+
+    /** Metrics dropped from the compare, with the reason, never silently. */
+    const skippedMetrics: { metric: MetricName; reason: string }[] = [];
+    const skipMetric = (metric: MetricName): boolean => {
+        if (skillFloorSkipReason !== null && (metric === 'skill_count' || metric === 'skill_description_tokens')) {
+            skippedMetrics.push({ metric, reason: skillFloorSkipReason });
+            return true;
+        }
+        if (skillTokenSkipReason !== null && metric === 'skill_description_tokens') {
+            skippedMetrics.push({ metric, reason: skillTokenSkipReason });
+            return true;
+        }
+        return false;
     };
 
     const over: GrowthFinding[] = [];
     if (floor !== null) {
         for (const metric of METRICS) {
+            if (skipMetric(metric)) continue;
             const live = counts[metric];
             const allowed = floor[metric] + allowance[metric];
             if (live > allowed) {
@@ -596,6 +786,7 @@ export function evaluate(
         growth,
         authorisedGrowth,
         claims,
+        skippedMetrics,
         offsets,
         offsetSkipReason,
         unpaid,
@@ -700,6 +891,64 @@ function selfTest(): number {
             expect: 'accept',
             run: () => fixture({ roadmaps: 3, base: 'main', after: () => undefined }),
         },
+        {
+            // The concern axis, both directions. Seeded into the BASE tree so
+            // the floor is a real reading of the fixture's own manifest rather
+            // than this repository's -- the whole point of measuring the floor
+            // from the base ref.
+            name: 'concern count grows above the base-tree floor → reject',
+            expect: 'reject',
+            run: () =>
+                fixture({
+                    roadmaps: 3,
+                    base: 'main',
+                    before: (dir) =>
+                        write(dir, CONCERN_MANIFEST_POSIX, 'concerns:\n  one:\n    severity: advisory\n'),
+                    after: (dir) =>
+                        write(
+                            dir,
+                            CONCERN_MANIFEST_POSIX,
+                            'concerns:\n  one:\n    severity: advisory\n  two:\n    severity: advisory\n',
+                        ),
+                }),
+        },
+        {
+            // AC-3's explicit clause, and it corrects the first implementation
+            // of this metric: an unreadable manifest at the base ref must FAIL,
+            // never read as 0. A floor of 0 makes the ratchet inert on that
+            // path while still printing a green line, which is the shape this
+            // repository calls "a gate that read nothing has not passed".
+            name: 'base ref carries no manifest → reject (a 0 floor is not a floor)',
+            expect: 'reject',
+            run: () =>
+                fixture({
+                    roadmaps: 3,
+                    base: 'main',
+                    after: (dir) =>
+                        write(dir, CONCERN_MANIFEST_POSIX, 'concerns:\n  one:\n    severity: advisory\n'),
+                }),
+        },
+        {
+            // The half that proves the parser is SCOPED rather than a grep: a
+            // top-level map gaining members at the same two-space indent is not
+            // concern growth, and the roadmap's own reproduce command would
+            // have counted it as such.
+            name: 'a non-concern top-level map growing is not concern growth → accept',
+            expect: 'accept',
+            run: () =>
+                fixture({
+                    roadmaps: 3,
+                    base: 'main',
+                    before: (dir) =>
+                        write(dir, CONCERN_MANIFEST_POSIX, 'concerns:\n  one:\n    severity: advisory\nroles:\n  dev:\n'),
+                    after: (dir) =>
+                        write(
+                            dir,
+                            CONCERN_MANIFEST_POSIX,
+                            'concerns:\n  one:\n    severity: advisory\nroles:\n  dev:\n  ops:\n  sre:\n',
+                        ),
+                }),
+        },
         {
             // The floor is now exact, so this case no longer depends on anyone
             // having typed the right number at the base commit.
@@ -1010,8 +1259,12 @@ export function main(argv: string[] = process.argv.slice(2)): number {
 
     for (const g of verdict.growth) {
         const allow = g.allowance > 0 ? ` (+${String(g.allowance)} allowed here)` : '';
+        // Two corpora share this gate, so the line names which one grew. It used
+        // to say "the roadmap estate" unconditionally, which was already the
+        // wrong noun for `skill_count` the moment that metric landed.
+        const corpus = g.metric.startsWith('skill_') ? 'the skill estate' : 'the roadmap estate';
         process.stderr.write(
-            `❌  the roadmap estate grew: ${g.metric} ${String(g.floor)} → ${String(g.live)}${allow}.\n` +
+            `❌  ${corpus} grew: ${g.metric} ${String(g.floor)} → ${String(g.live)}${allow}.\n` +
                 `    The floor is the measurement at ${verdict.floorRef ?? 'the base ref'}, not a number in a\n` +
                 '    config — so there is no number to edit and nothing to walk. The estate does not\n' +
                 '    walk down by itself, which is the defect this ratchet exists for. Either close,\n' +
@@ -1022,6 +1275,13 @@ export function main(argv: string[] = process.argv.slice(2)): number {
         );
     }
 
+    // A dropped metric is REPORTED, never silent: a reader must be able to tell
+    // "within its ratchet" from "within the ratchet of the metrics that could be
+    // measured". This is the same distinction the floor-skip reason above keeps.
+    for (const s of verdict.skippedMetrics) {
+        process.stdout.write(`  ⏭️  ${s.metric} not compared — ${s.reason}\n`);
+    }
+
     if (verdict.unpaid > 0 && verdict.offsets !== null) {
         process.stderr.write(
             `❌  ${String(verdict.unpaid)} new active roadmap(s) with no offset in the same change.\n` +