@event4u/agent-config 14.9.0 → 14.11.0

package/src/scripts/check_pack_passport_reconciliation.ts

@@ -0,0 +1,274 @@
+#!/usr/bin/env node
+/**
+ * Do the per-pack passports add up to the census the tree already runs?
+ *
+ * A per-pack number published beside a tree-wide number it contradicts is worse
+ * than no per-pack number: both get quoted, and nobody can say which is wrong.
+ * This is the check that says so out loud.
+ *
+ * THE ±10 % BAND THIS WAS SPECIFIED WITH RESTED ON A FALSE PREMISE, and the
+ * measurement is what refuted it. The band assumed packs roughly PARTITION the
+ * tree, so per-pack sums should approach the tree-wide census. Measured on
+ * 2026-08-22: across all 17 packs, `dependencies` claims **4 skills and 0
+ * rules**, against **291 skills and 118 rules** in the projection. Packs claim
+ * ~1 % of the artefacts the census counts.
+ *
+ * So the two numbers are not a reconciliation pair at all:
+ *
+ *   census   — the PROJECTED tree (`dist/agent-src/`), everything that ships
+ *   passport — what a pack CLAIMS, which is a small, deliberate subset
+ *
+ * A gate failing on an 84 % gap would be failing on a property of the tree, not
+ * on a defect — and a gate that is red by construction gets disabled rather
+ * than fixed. So this REPORTS coverage as a first-class number and exits 0.
+ * That is exactly what the step behind it asked for: a passport that does not
+ * reconcile "must say what, in-band, rather than being published alongside a
+ * number it contradicts."
+ *
+ * What would make it a gate: pack coverage approaching the tree. Then the band
+ * becomes meaningful and the exit code can follow it. Until then the useful
+ * output is the RANKING plus the coverage figure.
+ *
+ * Both sides are `chars/4` — the basis `preamble-payload-budget.json` declares
+ * for itself. Mixing an exact tokenizer into one side would make the gap
+ * between two METHODS read as a discrepancy in the packs.
+ *
+ * Also emits the RANKING, because the useful output is not the numbers but
+ * which packs carry the weight: a per-pack table sorted by cost turns "the
+ * estate grew" into "this pack grew".
+ *
+ * Exit: 0 always (it is a REPORT, not a gate), 2 on a dead scan scope. See the
+ * band note above for why the exit code does not follow the gap.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+import { runSelfTest } from './_lib/gate_self_test.js';
+import { censusRuleDir, censusSkillsCatalog } from './preamble_byte_census.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+export const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+export const PACKS_DIR = path.join(REPO_ROOT, 'src/packs');
+export const RANKING = path.join(REPO_ROOT, 'agents/evidence/reports/pack-token-ranking.md');
+
+/** ±10 %. See the module docstring for why a band exists at all. */
+export const TOLERANCE = 0.1;
+
+export interface Passport {
+    pack: string;
+    rules_tokens: number;
+    catalog_tokens: number;
+    commands_tokens: number;
+    other_tokens: number;
+    total_tokens: number;
+}
+
+/** Read `token_passport:` out of a generated pack.yaml — no YAML dependency. */
+export function readPassport(pack: string, text: string): Passport | null {
+    const start = text.indexOf('token_passport:');
+    if (start < 0) return null;
+    const num = (key: string): number => {
+        const m = new RegExp(`^\\s+${key}:\\s*(\\d+)\\s*$`, 'm').exec(text.slice(start));
+        return m === null ? 0 : Number(m[1]);
+    };
+    return {
+        pack,
+        rules_tokens: num('rules_tokens'),
+        catalog_tokens: num('catalog_tokens'),
+        commands_tokens: num('commands_tokens'),
+        other_tokens: num('other_tokens'),
+        total_tokens: num('total_tokens'),
+    };
+}
+
+export function collectPassports(dir: string = PACKS_DIR): Passport[] {
+    if (!fs.existsSync(dir)) return [];
+    const out: Passport[] = [];
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (!e.isDirectory()) continue;
+        const f = path.join(dir, e.name, 'pack.yaml');
+        if (!fs.existsSync(f)) continue;
+        const p = readPassport(e.name, fs.readFileSync(f, 'utf-8'));
+        if (p !== null) out.push(p);
+    }
+    return out;
+}
+
+export interface Reconciliation {
+    bucket: string;
+    packSum: number;
+    censusTotal: number;
+    gapPct: number;
+    inBand: boolean;
+}
+
+export function reconcile(packSum: number, censusTotal: number, bucket: string): Reconciliation {
+    // Denominator is the CENSUS, which is the side with the independent
+    // measurement. Dividing by the pack sum would let a passport that measured
+    // almost nothing report a small gap.
+    const gapPct = censusTotal === 0 ? (packSum === 0 ? 0 : 1) : Math.abs(packSum - censusTotal) / censusTotal;
+    return { bucket, packSum, censusTotal, gapPct, inBand: gapPct <= TOLERANCE };
+}
+
+export function renderRanking(ps: readonly Passport[]): string {
+    const sorted = [...ps].sort((a, b) => b.total_tokens - a.total_tokens);
+    const total = sorted.reduce((a, p) => a + p.total_tokens, 0);
+    const lines = [
+        '<!-- evidence-type: analysis -->',
+        '# Pack token ranking — which packs carry the weight',
+        '',
+        'GENERATED by `./scripts-run src/scripts/check_pack_passport_reconciliation --write-ranking`.',
+        'Do not hand-edit. Basis `chars/4`, per `docs/contracts/pack-token-passport.md`.',
+        '',
+        'The numbers are each pack\'s STANDING contribution — what is paid whether or',
+        'not the pack is used. A skill body loaded on invocation is a runtime cost and',
+        'is not here, and the residual bucket (tool definitions + dispatch prompt) is',
+        'not attributable to a pack at all.',
+        '',
+        `**${String(sorted.length)} packs, ${String(total)} tokens total.**`,
+        '',
+        '| rank | pack | total | rules | catalog | commands | other | share |',
+        '|---:|---|---:|---:|---:|---:|---:|---:|',
+    ];
+    sorted.forEach((p, i) => {
+        const share = total === 0 ? 0 : (p.total_tokens / total) * 100;
+        lines.push(
+            `| ${String(i + 1)} | \`${p.pack}\` | ${String(p.total_tokens)} | ${String(p.rules_tokens)} | ` +
+                `${String(p.catalog_tokens)} | ${String(p.commands_tokens)} | ${String(p.other_tokens)} | ${share.toFixed(1)} % |`,
+        );
+    });
+    return `${lines.join('\n')}\n`;
+}
+
+/**
+ * Discrimination over the two pure units — the parser and the ratio.
+ *
+ * This script exits 0 on every path by design (it is a report, not a gate), so
+ * no planted file can make it red and the canary harness cannot prove anything
+ * about it. The `scanned:` floor is the one thing about it that CAN break, and
+ * a self-test is what proves the two functions behind the number actually
+ * discriminate rather than returning something shaped like an answer.
+ */
+function selfTest(): number {
+    const yaml = [
+        'artefact_count: 3',
+        'token_passport:',
+        '  basis: chars/4',
+        '  catalog_tokens: 20',
+        '  commands_tokens: 5',
+        '  other_tokens: 1',
+        '  rules_tokens: 10',
+        '  total_tokens: 36',
+    ].join('\n');
+    return runSelfTest({
+        gate: 'check_pack_passport_reconciliation',
+        minCases: 6,
+        minRejectCases: 3,
+        cases: [
+            {
+                name: 'a manifest with a passport parses every field',
+                expect: 'reject',
+                run: () => {
+                    const p = readPassport('x', yaml);
+                    return p !== null && p.rules_tokens === 10 && p.total_tokens === 36 ? 1 : 0;
+                },
+            },
+            {
+                name: 'a manifest with NO passport returns null, not a zero passport',
+                expect: 'accept',
+                run: () => (readPassport('x', 'artefact_count: 3\n') === null ? 0 : 1),
+            },
+            {
+                name: 'an exact match is in band',
+                expect: 'accept',
+                run: () => (reconcile(100, 100, 'b').inBand ? 0 : 1),
+            },
+            {
+                name: 'a 9 % gap is in band and an 11 % gap is not',
+                expect: 'reject',
+                run: () => (reconcile(109, 100, 'b').inBand && !reconcile(111, 100, 'b').inBand ? 1 : 0),
+            },
+            {
+                // The denominator is the CENSUS, the side with the independent
+                // measurement. Dividing by the pack sum would let a passport
+                // that measured almost nothing report a small gap — which is
+                // exactly the failure this repo's own measurement produced.
+                name: 'the denominator is the census, not the pack sum',
+                expect: 'reject',
+                run: () => (Math.abs(reconcile(1, 100, 'b').gapPct - 0.99) < 1e-9 ? 1 : 0),
+            },
+            {
+                name: 'both sides zero is in band; a sum against a zero census is not',
+                expect: 'accept',
+                run: () => (reconcile(0, 0, 'b').inBand && !reconcile(5, 0, 'b').inBand ? 0 : 1),
+            },
+        ],
+    });
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    if (argv.includes('--self-test')) return selfTest();
+    const passports = collectPassports();
+    try {
+        assertScanned({
+            gate: 'check_pack_passport_reconciliation',
+            scanned: passports.length,
+            units: 'pack passport(s)',
+            roots: ['src/packs/*/pack.yaml'],
+        });
+    } catch (err) {
+        if (err instanceof DeadScopeError) {
+            process.stderr.write(`❌  passport reconciliation: ${err.message}\n`);
+            return 2;
+        }
+        throw err;
+    }
+    process.stdout.write(`scanned: ${String(passports.length)}\n`);
+
+    if (argv.includes('--write-ranking')) {
+        fs.mkdirSync(path.dirname(RANKING), { recursive: true });
+        fs.writeFileSync(RANKING, renderRanking(passports));
+        process.stdout.write(`✅  ranking written to ${path.relative(REPO_ROOT, RANKING)}\n`);
+    }
+
+    const rules = censusRuleDir(path.join(REPO_ROOT, 'dist', 'agent-src', 'rules'));
+    const catalog = censusSkillsCatalog(path.join(REPO_ROOT, 'dist', 'agent-src', 'skills'));
+    const tok = (chars: number): number => Math.round(chars / 4);
+    const recs = [
+        reconcile(
+            passports.reduce((a, p) => a + p.rules_tokens, 0),
+            tok(rules.chars),
+            'project-scope rules',
+        ),
+        reconcile(
+            passports.reduce((a, p) => a + p.catalog_tokens, 0),
+            tok(catalog.chars),
+            'preloaded skills catalog',
+        ),
+    ];
+    for (const r of recs) {
+        process.stdout.write(
+            `  ${r.inBand ? '✅' : '❌'} ${r.bucket.padEnd(26)} packs ${String(r.packSum).padStart(7)} · ` +
+                `census ${String(r.censusTotal).padStart(7)} · gap ${(r.gapPct * 100).toFixed(1)} %\n`,
+        );
+    }
+    const covered = recs.filter((r) => r.inBand).length;
+    process.stdout.write(
+        `\ncoverage: packs account for ${String(covered)} of ${String(recs.length)} census bucket(s) within ±${String(
+            TOLERANCE * 100,
+        )} %.\n` +
+            '  A gap here is a PROPERTY OF THE TREE, not a defect: pack `dependencies` claim a\n' +
+            '  small deliberate subset of what ships, so the two numbers are not a reconciliation\n' +
+            '  pair. Failing on that would be failing by construction, and a gate that is red by\n' +
+            '  construction gets disabled rather than fixed.\n' +
+            '  The useful output is the ranking above plus this figure. See\n' +
+            '  docs/contracts/pack-token-passport.md § Reconciliation for what would make it a gate.\n',
+    );
+    return 0;
+}
+
+if (process.argv[1] !== undefined && process.argv[1].includes('check_pack_passport_reconciliation')) {
+    process.exit(main(process.argv.slice(2)));
+}

package/src/scripts/check_proposal.ts

@@ -37,6 +37,7 @@ import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { parse as parseYaml } from 'yaml';
 
+import { asOf } from './_lib/as_of.js';
 import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 type Severity = 'error' | 'warning';
@@ -364,7 +365,7 @@ function _dateFromIso(s: string): Ymd | null {
 }
 
 function _todayMinusDays(days: number): Ymd {
-    const now = new Date();
+    const now = asOf();
     const base = Date.UTC(now.getFullYear(), now.getMonth(), now.getDate());
     const d = new Date(base - days * 86_400_000);
     return { year: d.getUTCFullYear(), month: d.getUTCMonth() + 1, day: d.getUTCDate() };

package/src/scripts/check_reach_staleness.ts

@@ -51,6 +51,7 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { asOf } from './_lib/as_of.js';
 import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 import { RegistryLoadError, load_registry } from './check_reach_channels.js';
 
@@ -108,7 +109,7 @@ export function days_between(fromStamp: number, toStamp: number): number {
 }
 
 /** Today as `YYYY-MM-DD` in UTC — the only place the clock is read. */
-export function today_iso(now: Date = new Date()): string {
+export function today_iso(now: Date = asOf()): string {
     return now.toISOString().slice(0, 10);
 }
 

package/src/scripts/check_release_adjacent_health.ts

@@ -22,6 +22,7 @@ import * as path from 'node:path';
 import { argv, env, exit } from 'node:process';
 import { fileURLToPath } from 'node:url';
 
+import { asOfMs } from './_lib/as_of.js';
 import { assertWatchlistResolves, DeadScopeError } from './_lib/scan_scope.js';
 
 // src/scripts/check_release_adjacent_health.ts → two levels up is the repo root.
@@ -119,7 +120,7 @@ async function main(): Promise<number> {
             process.stderr.write(`✅  ${wf}: last completed run green\n`);
             continue;
         }
-        const ageHours = (Date.now() - Date.parse(run.updated_at)) / 3_600_000;
+        const ageHours = (asOfMs() - Date.parse(run.updated_at)) / 3_600_000;
         if (ageHours >= maxRedHours) {
             process.stdout.write(
                 `::error::release-adjacent workflow durably red: ${wf} — last completed run ` +

package/src/scripts/check_release_pr_shape.ts

@@ -31,6 +31,11 @@ const ALLOWLIST_GLOBS = [
     'package-lock.json',
     'CHANGELOG.md',
     '.claude-plugin/marketplace.json',
+    // Augment twins — version-synced to package.json by release.ts
+    // set_augment_manifest_version, enforced by lint_marketplace. Both ship in
+    // the tarball (publish-surface.json roots), so a release PR must carry them.
+    '.augment-plugin/plugin.json',
+    '.augment-plugin/marketplace.json',
     'src/packs/*/pack.yaml',
     'src/packs/*/README.md',
     'src/domains/*/pack.yaml',

package/src/scripts/check_review_schema.ts

@@ -152,8 +152,41 @@ function main(argv?: readonly string[]): number {
         else ledger.complete(name);
     }
 
+    // SECOND SURFACE — step 2.2 of road-to-review-independence. Until it existed, this
+    // gate scanned one directory with one producer in it, so `scanned: 1` meant "the only
+    // producer of this record agrees with itself". `dispatch_r2_reviewer` now emits the
+    // same record into its findings artefact, and those are checked here on the same
+    // terms: the independence pair must be internally consistent wherever it is written,
+    // or the derivation rule is advice rather than a contract.
+    //
+    // Only the independence check runs over this surface, not the release-findings schema
+    // — an R2 artefact is a different document and validating it against the ledger
+    // schema would report violations that are not violations.
+    const REVIEWS_DIR = path.join(process.cwd(), 'agents', 'evidence', 'reviews');
+    let reviewScanned = 0;
+    if (fs.existsSync(REVIEWS_DIR)) {
+        for (const name of fs.readdirSync(REVIEWS_DIR).filter((n) => n.endsWith('.md')).sort()) {
+            const text = fs.readFileSync(path.join(REVIEWS_DIR, name), 'utf-8');
+            const m = /<!--\s*(\{"review-independence".*?\})\s*-->/su.exec(text);
+            if (m === null) continue;
+            reviewScanned += 1;
+            let rec: Record<string, unknown>;
+            try {
+                rec = (JSON.parse(m[1]!) as { 'review-independence': Record<string, unknown> })[
+                    'review-independence'
+                ];
+            } catch (exc) {
+                problems.push(`${name}: unparseable review-independence block — ${String(exc)}`);
+                continue;
+            }
+            for (const v of independenceViolations(rec)) {
+                problems.push(`${name}: independence — ${v}`);
+            }
+        }
+    }
+
     ledger.finalize();
-    process.stderr.write(`scanned: ${files.length}\n`);
+    process.stderr.write(`scanned: ${String(files.length + reviewScanned)}\n`);
 
     if (problems.length > 0) {
         process.stdout.write(

package/src/scripts/check_roadmap_trackable.ts

@@ -29,11 +29,13 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { checkRatchet } from './_lib/gate_baseline.js';
 import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 const QUIET = process.argv.slice(2).includes('--quiet');
 
 const ROADMAP_ROOT = 'agents/roadmaps';
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
 
 // --- Replicated from .augment/scripts/update_roadmap_progress.py ------------
 // CHECKBOX_RE = re.compile(r"^\s*[-*]\s+\[([ xX~\-])\]\s", re.MULTILINE)
@@ -221,6 +223,25 @@ function violations_for(p: string): string[] {
     return out;
 }
 
+/**
+ * Does this roadmap declare a `relates:` block?
+ *
+ * `road-to-roadmap-situational-awareness` § 4.2. `depends:` was defined in the
+ * template and its measured adoption was **0** — a field nothing requires is a
+ * field nobody writes. So the wider relation field is required, but RATCHETED:
+ * the roadmaps that predate the check are held at their measured count and a
+ * NEW one without the block pushes the count above it.
+ *
+ * Presence only. Whether the declared relations are legal is
+ * `lint_roadmap_complexity`'s `_check_relates`, and whether an empty list is
+ * honest is the pre-save self-check in `roadmap-writing` — a gate cannot tell a
+ * genuinely-empty `relates: []` from a reflex one, and pretending otherwise
+ * would be the worse failure.
+ */
+export function declares_relates(p: string): boolean {
+    return parse_frontmatter(fs.readFileSync(p, 'utf-8')).has('relates');
+}
+
 function main(): number {
     if (!_isDir(ROADMAP_ROOT)) {
         process.stderr.write(`❌  ${ROADMAP_ROOT} not found — run from project root.\n`);
@@ -244,8 +265,9 @@ function main(): number {
         }
         throw exc;
     }
+    const active = find_active_roadmaps(ROADMAP_ROOT);
     const findings: string[] = [];
-    for (const p of find_active_roadmaps(ROADMAP_ROOT)) {
+    for (const p of active) {
         findings.push(...violations_for(p));
     }
     if (findings.length > 0) {
@@ -259,11 +281,33 @@ function main(): number {
         );
         return 1;
     }
-    const count = find_active_roadmaps(ROADMAP_ROOT).length;
+    // The `relates:` ratchet. Reported separately from trackability because the
+    // two are different obligations: one keeps a roadmap visible to the
+    // dashboard, this one keeps its relations to sibling work declared.
+    const no_relates = active.filter((p) => !declares_relates(p));
+    const verdict = checkRatchet({
+        gate: 'check_roadmap_trackable:relates',
+        actual: no_relates.length,
+        repoRoot: REPO_ROOT,
+    });
+    if (!verdict.ok) {
+        process.stderr.write(`❌  ${verdict.message}\n`);
+        for (const p of no_relates) {
+            process.stderr.write(`    ${p}: no \`relates:\` block in the frontmatter\n`);
+        }
+        process.stderr.write(
+            '\n    Run `agent-config roadmap:context` and write one row per hit\n' +
+                "    ({slug, relation: extends|supersedes|depends|disjoint, note}), or an\n" +
+                "    explicit `relates: []` carrying the probe's `scanned:` line as its\n" +
+                '    justification. See templates/roadmaps.md rule 18.\n',
+        );
+        return 1;
+    }
     if (!QUIET) {
         process.stdout.write(
-            `✅  ${count} active roadmap(s) — all parseable, all phases have checkboxes.\n`,
+            `✅  ${active.length} active roadmap(s) — all parseable, all phases have checkboxes.\n`,
         );
+        process.stdout.write(`✅  ${verdict.message}\n`);
     }
     return 0;
 }
@@ -296,6 +340,7 @@ if (_isCliEntry() || process.argv[1] === _HERE) {
 }
 
 export {
+    REPO_ROOT,
     ROADMAP_ROOT,
     CHECKBOX_RE,
     PHASE_RE,

package/src/scripts/check_source_size_budget.ts

@@ -66,6 +66,7 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { asOf } from './_lib/as_of.js';
 import { checkRatchet } from './_lib/gate_baseline.js';
 import { GateLedger } from './_lib/gate_ledger.js';
 import { runGateCli, runSelfTest } from './_lib/gate_self_test.js';
@@ -216,7 +217,7 @@ export function selfTest(): number {
                 : {
                       check_source_size_budget: {
                           count: baseline,
-                          landed: new Date().toISOString().slice(0, 10),
+                          landed: asOf().toISOString().slice(0, 10),
                           note: 'self-test fixture',
                       },
                   };