@event4u/agent-config 16.2.0 → 16.4.0

package/src/scripts/check_estate_count.ts

@@ -154,6 +154,8 @@ 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 { exemptionFindings, type ExemptionFinding } from './_lib/exemption_shape.js';
+import { classifyDiff, growthClaims, type GrowthClaim, type OffsetLedger } from './_lib/estate_offsets.js';
 import { runGateCli, runSelfTest, type SelfTestCase } from './_lib/gate_self_test.js';
 
 const GATE = 'check_estate_count';
@@ -301,32 +303,7 @@ export interface GrowthFinding {
     allowance: number;
 }
 
-/** How a change touched the active roadmap tree, as git reports it. */
-export interface OffsetLedger {
-    /** Files that entered the active top level: new files, and un-parked ones. */
-    added: string[];
-    /** Files that left it: deleted, archived, parked or merged away. */
-    offsets: string[];
-    /** Added files carrying an `estate_offset_exempt:` reason, with the reason. */
-    exempt: Array<{ file: string; reason: string }>;
-    /**
-     * The subset of `offsets` that went to `later/`.
-     *
-     * Tracked separately because parking is the one offset that RAISES another
-     * gated count: active falls by one and later rises by one, which under an
-     * exact floor is growth in `later_roadmaps` unless this allowance exists.
-     * Kept out of a general "any offset raises any allowance" rule on purpose —
-     * an archived roadmap must not buy a new `later/` file.
-     */
-    parked: string[];
-}
 
-/** An `estate_growth_exempt:` reason ADDED to a roadmap in this change. */
-export interface GrowthClaim {
-    /** The roadmap the claim was added to, as git reports the path. */
-    file: string;
-    reason: string;
-}
 
 export interface EstateVerdict {
     counts: EstateCounts;
@@ -362,6 +339,23 @@ export interface EstateVerdict {
     offsets: OffsetLedger | null;
     offsetSkipReason: string | null;
     unpaid: number;
+    /**
+     * Added exemptions whose reason names no rejected alternative, or repeats
+     * another added file's. Empty on every change that adds no exemption.
+     */
+    exemptionFindings: ExemptionFinding[];
+    /**
+     * Roadmaps carrying an unscheduled status — REPORTED, never gated.
+     *
+     * `collect()` excludes them by design, so a draft is invisible to every
+     * count above and adding one costs no slot. That is the right policy: a
+     * draft is not active work, and charging for one would make every parked
+     * idea cost a slot. What was wrong was that the number was invisible too, so
+     * a reader of `active_roadmaps 26` could not tell an estate of 26 from an
+     * estate of 26 with 14 drafts behind it. It contributes nothing to
+     * `withinBudget` — there is no floor for it and no claim path to it.
+     */
+    draftRoadmaps: number;
     /**
      * The provisional-promotion path's state, reported and never acted on.
      *
@@ -513,143 +507,51 @@ export function countEstate(repoRoot: string): EstateCounts {
     };
 }
 
-/** 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. code-comment-allow provenance-comment -- operand, not provenance */
-function isActiveTopLevel(rel: string): boolean {
-    const norm = rel.split(path.sep).join('/');
-    if (!norm.startsWith('agents/roadmaps/') || !norm.endsWith('.md')) {
-        return false;
-    }
-    const tail = norm.slice('agents/roadmaps/'.length);
-    return !tail.includes('/') && isRoadmapCandidate(norm);
-}
-
 /**
- * A disposition directory — where an offset sends a roadmap.
+ * Top-level roadmaps `collect()` drops for an unscheduled status.
  *
- * `stubs/` is in the set, and it was missing from the first version. Un-stubbing
- * is the documented promotion path, so a stub moved to the top level is an
- * ADDITION that T3 must charge, and a roadmap demoted to a stub is an offset.
- * With `stubs/` unrecognised, a promotion was classified as neither and the lint
- * could never charge it — the one hole that let an active roadmap arrive for free.
- */
-function isDisposed(rel: string): boolean {
-    const norm = rel.split(path.sep).join('/');
-    return /^agents\/roadmaps\/(archive|later|skipped|stubs)\//.test(norm);
-}
-
-/** A roadmap parked for later — the one disposition that grows another count. */
-function isParked(rel: string): boolean {
-    return rel.split(path.sep).join('/').startsWith('agents/roadmaps/later/');
-}
-
-/**
- * Read the exemption reason a newly added roadmap declares, if any.
+ * Reported beside the count, never added to it. The exclusion in `collect()` is
+ * deliberate and stays: a draft is not active work, and counting one would make
+ * every parked idea cost a slot under one-in-one-out. What the exclusion also
+ * did, silently, was make the drafts unreadable — the estate report showed
+ * `active_roadmaps 26` whether 0 or 14 drafts sat beside them. This closes the
+ * reporting half and nothing else, so it has no floor, no allowance and no
+ * claim path: it cannot fail.
  *
- * The key lives in the file's own frontmatter rather than in a config or a
- * commit trailer, for the reason `RATCHET_RESET_KEY` gives for living inside the
- * baseline JSON: the claim then shows up in the diff of the change that makes
- * it, and a reviewer sees it without being told to look.
+ * `isUnscheduled` is the same predicate `collect()` filters on, so this count
+ * and that exclusion cannot disagree — a second status list here is how a
+ * reported number starts describing a different set from the one it explains.
  */
-export function exemptionReason(text: string): string | null {
-    const fm = parseFrontmatter(text);
-    const raw = (fm as Record<string, unknown>)['estate_offset_exempt'];
-    if (typeof raw !== 'string') {
-        return null;
+export function countDrafts(repoRoot: string): number {
+    const dir = path.join(repoRoot, ROADMAPS_REL);
+    let names: string[];
+    try {
+        names = fs.readdirSync(dir);
+    } catch {
+        return 0;
     }
-    const reason = raw.trim().replace(/^["']|["']$/g, '').trim();
-    return reason === '' ? null : reason;
-}
-
-/**
- * Classify the change's effect on the active roadmap tree.
- *
- * Renames carry information a name-only diff loses: `road-to-x.md` →
- * `archive/road-to-x.md` is the wanted direction and counts as an offset, while
- * `later/road-to-x.md` → `road-to-x.md` is an un-parking and counts as an
- * addition. A top-level-to-top-level rename is neither.
- */
-export function classifyDiff(
-    nameStatus: string,
-    readFile: (rel: string) => string | null,
-): OffsetLedger {
-    const added: string[] = [];
-    const offsets: string[] = [];
-    const exempt: Array<{ file: string; reason: string }> = [];
-    const parked: string[] = [];
-    for (const line of nameStatus.split('\n')) {
-        if (line.trim() === '') continue;
-        const cols = line.split('\t');
-        const status = (cols[0] ?? '').trim();
-        if (status.startsWith('R') || status.startsWith('C')) {
-            const from = cols[1] ?? '';
-            const to = cols[2] ?? '';
-            if (isActiveTopLevel(from) && isDisposed(to)) {
-                offsets.push(from);
-                if (isParked(to)) parked.push(to);
-            } else if (isDisposed(from) && isActiveTopLevel(to)) {
-                added.push(to);
-            }
+    let n = 0;
+    for (const name of names) {
+        if (!name.endsWith('.md') || !isRoadmapCandidate(name)) continue;
+        const abs = path.join(dir, name);
+        let text: string;
+        try {
+            if (!fs.statSync(abs).isFile()) continue;
+            text = fs.readFileSync(abs, 'utf-8');
+        } catch {
             continue;
         }
-        const file = cols[1] ?? '';
-        if (!isActiveTopLevel(file)) continue;
-        if (status === 'A') {
-            added.push(file);
-        } else if (status === 'D') {
-            offsets.push(file);
-        }
-    }
-    for (const file of added) {
-        const text = readFile(file);
-        if (text === null) continue;
-        const reason = exemptionReason(text);
-        if (reason !== null) {
-            exempt.push({ file, reason });
-        }
+        if (isUnscheduled(parseFrontmatter(text))) n += 1;
     }
-    return { added, offsets, exempt, parked };
+    return n;
 }
 
-/**
- * The `estate_growth_exempt:` reasons this change ADDS, read from the patch.
- *
- * Read from the diff rather than from the file, and that is the point: a claim
- * sitting in a roadmap authorises nothing on a later change, so an exemption
- * cannot be banked the way surplus in a stored baseline could. It also means a
- * newly added roadmap and an edited one need no separate handling — in a
- * `base...HEAD` patch both arrive as `+` lines.
- *
- * `--unified=0` keeps context lines out, so a claim that merely sits NEAR an
- * edited line is not read as added. Deliberately tolerant of leading whitespace
- * and of quoted values, matching `exemptionReason`; deliberately NOT tolerant of
- * an empty reason, because an exemption whose reason is blank is the silent
- * exception the key exists to replace.
- */
-export function growthClaims(patch: string): GrowthClaim[] {
-    const out: GrowthClaim[] = [];
-    let file = '';
-    for (const line of patch.split('\n')) {
-        // `+++ b/<path>` names the file the following `+` lines belong to. The
-        // `/dev/null` form is a deletion, which cannot carry a claim.
-        const head = /^\+\+\+ b\/(.+)$/.exec(line);
-        if (head !== null) {
-            file = (head[1] ?? '').trim();
-            continue;
-        }
-        if (!line.startsWith('+') || line.startsWith('+++')) continue;
-        const m = /^\+\s*estate_growth_exempt:\s*(.+?)\s*$/.exec(line);
-        if (m === null) continue;
-        const reason = (m[1] ?? '').trim().replace(/^["']|["']$/g, '').trim();
-        if (reason !== '') out.push({ file, reason });
-    }
-    return out;
+/** 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;
 }
 
+
 export function evaluate(
     repoRoot: string,
     opts: { baseRef?: string | undefined } = {},
@@ -816,6 +718,13 @@ export function evaluate(
         unpaid = Math.max(0, chargeable.length - offsets.offsets.length);
     }
 
+    // The SHAPE half, and it is deliberately not gated on `lintApplies`. The
+    // threshold decides whether an unoffset addition is charged; it says nothing
+    // about whether a claim an author chose to write has to mean something. An
+    // exemption below the threshold buys nothing anyway, so a shapeless one
+    // below it is a line that will be read as a reason later and is not one.
+    const findings = offsets === null ? [] : exemptionFindings(offsets.exempt);
+
     // The allowances, one metric at a time and never a blanket rule. An exempt
     // addition and a parked roadmap are the two increases the existing policy
     // already sanctions, and under an exact floor each needs its own headroom or
@@ -883,13 +792,15 @@ export function evaluate(
         offsets,
         offsetSkipReason,
         unpaid,
+        exemptionFindings: findings,
+        draftRoadmaps: countDrafts(repoRoot),
         provisionalPromotion,
         // No floor is a FAILURE, not a skip, and it is the one place this gate
         // convicts on a missing input. The other halves can report "unproven" and
         // still leave a meaningful verdict behind; the count half IS the verdict,
         // so with no floor a green here would assert something nothing measured.
         // A shrink-only gate whose floor is absent passes every possible tree.
-        withinBudget: floorSkipReason === null && growth.length === 0 && unpaid === 0,
+        withinBudget: floorSkipReason === null && growth.length === 0 && unpaid === 0 && findings.length === 0,
     };
 }
 
@@ -1104,10 +1015,44 @@ function selfTest(): number {
                         write(
                             dir,
                             'agents/roadmaps/road-to-new.md',
-                            '---\nestate_offset_exempt: fixture — the addition that cannot be offset\n---\n\n' + roadmap('N'),
+                            '---\nestate_offset_exempt: fixture — archiving road-to-0 was rejected, it is mid-flight\n---\n\n' +
+                                roadmap('N'),
                         ),
                 }),
         },
+        {
+            // The shape half. The old reason here was "the addition that cannot
+            // be offset", which names no alternative and is exactly what this
+            // case now refuses — so the pair above and below are the same
+            // addition differing only in what its reason says.
+            name: 'exemption naming no rejected alternative → reject',
+            expect: 'reject',
+            run: () =>
+                fixture({
+                    roadmaps: 3,
+                    base: 'main',
+                    after: (dir) =>
+                        write(
+                            dir,
+                            'agents/roadmaps/road-to-new.md',
+                            '---\nestate_offset_exempt: fixture — lane 5 of road-to-parent\n---\n\n' + roadmap('N'),
+                        ),
+                }),
+        },
+        {
+            name: 'one exemption reason pasted into two added files → reject',
+            expect: 'reject',
+            run: () =>
+                fixture({
+                    roadmaps: 3,
+                    base: 'main',
+                    after: (dir) => {
+                        const fm = '---\nestate_offset_exempt: fixture — archiving road-to-0 was rejected, it is mid-flight\n---\n\n';
+                        write(dir, 'agents/roadmaps/road-to-n1.md', fm + roadmap('N1'));
+                        write(dir, 'agents/roadmaps/road-to-n2.md', fm + roadmap('N2'));
+                    },
+                }),
+        },
         {
             name: 'addition paid for by an archive move → accept',
             expect: 'accept',
@@ -1319,7 +1264,7 @@ export function main(argv: string[] = process.argv.slice(2)): number {
     }
 
     const ledger = new GateLedger(GATE);
-    ledger.plan([...METRICS, 'floor', 'one_in_one_out']);
+    ledger.plan([...METRICS, 'floor', 'one_in_one_out', 'exemption_shape']);
     for (const metric of METRICS) {
         // Round 2 finding 3, kept: a metric is recorded ONCE here, for whichever
         // way it actually failed, so the ledger cannot show a green completeness
@@ -1335,6 +1280,10 @@ export function main(argv: string[] = process.argv.slice(2)): number {
     if (verdict.offsets === null) ledger.skip('one_in_one_out', 'precondition_unmet');
     else if (verdict.unpaid > 0) ledger.fail('one_in_one_out', `${String(verdict.unpaid)} unpaid addition(s)`);
     else ledger.complete('one_in_one_out');
+    if (verdict.offsets === null) ledger.skip('exemption_shape', 'precondition_unmet');
+    else if (verdict.exemptionFindings.length > 0)
+        ledger.fail('exemption_shape', `${String(verdict.exemptionFindings.length)} unshaped exemption(s)`);
+    else ledger.complete('exemption_shape');
 
     if (json) {
         // The ledger goes to stderr here so stdout stays parseable after the
@@ -1358,6 +1307,12 @@ export function main(argv: string[] = process.argv.slice(2)): number {
             `  ${metric.padEnd(18)} ${String(live).padStart(5)}  (floor ${String(base)} at ${verdict.floorRef ?? '?'}, ${sign}${String(delta)})\n`,
         );
     }
+    // Beside the gated counts, never among them: no floor line, no delta, and
+    // the label says what it is. A reader comparing two runs can see the drafts
+    // move without reading this as a ratchet that moved.
+    process.stdout.write(
+        `  ${'draft_roadmaps'.padEnd(18)} ${String(verdict.draftRoadmaps).padStart(5)}  (reported, not gated — excluded from active_roadmaps)\n`,
+    );
     if (verdict.offsets !== null) {
         const o = verdict.offsets;
         process.stdout.write(
@@ -1435,6 +1390,28 @@ export function main(argv: string[] = process.argv.slice(2)): number {
                 '    that costs one reviewable line instead of a silent exception.\n',
         );
     }
+
+    for (const f of verdict.exemptionFindings) {
+        if (f.kind === 'shapeless') {
+            process.stderr.write(
+                `❌  ${f.file}: estate_offset_exempt names no rejected alternative.\n` +
+                    `    reason: ${f.reason.slice(0, 160)}\n` +
+                    '    The exemption is the escape hatch from one-in-one-out, so its reason has to\n' +
+                    '    say what you considered INSTEAD of adding a file — archiving something,\n' +
+                    '    parking it in `later/`, merging into an existing roadmap — and why that was\n' +
+                    '    not available. Name the disposition you rejected. Measured over the existing\n' +
+                    '    221 exemptions, 43 name none; this check applies to ADDED files only, so\n' +
+                    '    nothing already in the tree is re-read.\n',
+            );
+        } else {
+            process.stderr.write(
+                `❌  ${f.file}: estate_offset_exempt repeats ${f.twin ?? '(another added file)'} verbatim.\n` +
+                    `    reason: ${f.reason.slice(0, 160)}\n` +
+                    '    One sentence pasted into every file a round adds is one claim, not N. Write\n' +
+                    '    the reason this FILE could not be offset, or offset the ones that could.\n',
+            );
+        }
+    }
     ledger.report();
     if (verdict.withinBudget) {
         process.stdout.write(`✅  ${GATE}: estate within its ratchet.\n`);

package/src/scripts/check_evaluator_budgets.ts

@@ -59,6 +59,10 @@ interface BudgetEntry {
     /** `false` for wall-clock metrics: they cannot be compared run-to-run,
      * so they are excluded from the drift check. Missing = deterministic. */
     deterministic?: boolean;
+    /** Repository paths (globs as the workflow `paths` filter writes them) the
+     * metric is measured from. Every one must trigger the umbrella, so the PR
+     * that moves the input is the PR that sees the budget. */
+    inputs?: string[];
 }
 interface BudgetsDoc {
     regression_pct: number;