@event4u/agent-config 14.9.0 → 14.10.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/generate_pack_manifests.ts

@@ -48,6 +48,17 @@ type Dict = Record<string, unknown>;
 
 interface Artefact {
     path: string;
+    /**
+     * On-disk byte size, captured where the ABSOLUTE path is still known.
+     *
+     * `path` above is a LOGICAL relative path whose root differs per collection
+     * mode, so it cannot be stat'd later. A first version of the token passport
+     * did exactly that, and every `statSync` threw into a catch that returned 0
+     * — 17 packs generated an all-zero passport that would then have
+     * "reconciled" against nothing. Carrying the number from the one place it
+     * is knowable removes the failure mode rather than handling it.
+     */
+    bytes: number;
     name: string;
     description: string;
     category: string;
@@ -143,8 +154,15 @@ function _artefact_record(p: string, logicalRel: string, fm: Dict): Artefact {
         : path.basename(p) === 'SKILL.md'
           ? path.basename(path.dirname(p))
           : _stem(p);
+    let bytes = 0;
+    try {
+        bytes = fs.statSync(p).size;
+    } catch {
+        bytes = 0;
+    }
     return {
         path: logicalRel,
+        bytes,
         name,
         description: _pyStrip(_pyTruthy(fm.description) ? String(fm.description) : ''),
         category: _category_from_logical(logicalRel),
@@ -247,6 +265,65 @@ function _category_from_logical(logicalRel: string): string {
  * Build the pack.yaml meta dict. Mirrors `_build_pack_yaml`. Insertion
  * order here is irrelevant — `_py_safe_dump` sorts keys (sort_keys=True).
  */
+/**
+ * What this pack contributes to the STANDING session payload.
+ *
+ * Derivation, tokenizer and reconciliation target are fixed by
+ * `docs/contracts/pack-token-passport.md`, written before the first passport
+ * was generated — a number whose derivation is undocumented becomes a figure
+ * people quote without being able to reproduce.
+ *
+ * `chars/4`, deliberately, because that is the basis
+ * `preamble-payload-budget.json` declares and `preamble_byte_census.ts` uses. A
+ * passport measured with an exact tokenizer could not be reconciled against a
+ * census measured with a proxy without the gap between the two METHODS reading
+ * as a discrepancy in the packs.
+ *
+ * The catalog line is built the same way `censusSkillsCatalog` builds it —
+ * `- <name>: <description>\n` — rather than approximated, so the two sides of
+ * the reconciliation are counting the same string.
+ *
+ * It measures the STANDING contribution only. A skill body loaded on invocation
+ * is a runtime cost and is not here; the residual bucket (tool definitions +
+ * dispatch prompt) is not attributable to a pack at all. Both are stated in the
+ * contract, which is where the number lives.
+ */
+function _token_passport(artefacts: readonly Artefact[]): Dict {
+    const tok = (chars: number): number => Math.round(chars / 4);
+    let ruleChars = 0;
+    let catalogChars = 0;
+    let commandChars = 0;
+    let otherChars = 0;
+    for (const a of artefacts) {
+        if (a.category === 'skill') {
+            catalogChars += `- ${a.name}: ${a.description}\n`.length;
+            continue;
+        }
+        if (a.category === 'rule') ruleChars += a.bytes;
+        else if (a.category === 'command') commandChars += a.bytes;
+        // Everything else a pack CLAIMS — contexts, personas, presets,
+        // profiles, user-types. Counted, because a pack that claims 47
+        // artefacts and reports 0 tokens is worse than no passport: it reads as
+        // "this pack is free" when it means "the three named buckets do not
+        // cover what this pack holds". Measured: `core` claims 47 artefacts and
+        // none of them is a rule, a skill or a command — `src/agent-src/`
+        // carries no `rules/` or `skills/` subtree at all.
+        else otherChars += a.bytes;
+    }
+    const rules_tokens = tok(ruleChars);
+    const catalog_tokens = tok(catalogChars);
+    const commands_tokens = tok(commandChars);
+    const other_tokens = tok(otherChars);
+    return {
+        basis: 'chars/4',
+        rules_tokens,
+        catalog_tokens,
+        commands_tokens,
+        other_tokens,
+        total_tokens: rules_tokens + catalog_tokens + commands_tokens + other_tokens,
+    };
+}
+
 function _build_pack_yaml(pid: string, vocab: Record<string, Dict>, artefacts: Artefact[]): Dict {
     const meta = vocab[pid] ?? {};
     const label = _pyTruthy(meta.label)
@@ -276,6 +353,7 @@ function _build_pack_yaml(pid: string, vocab: Record<string, Dict>, artefacts: A
             ? (meta.trust_level_default as unknown)
             : 'core',
         artefact_count: artefacts.length,
+        token_passport: _token_passport(artefacts),
     };
     if (_isPlainObject(meta.onboarding)) {
         out.onboarding = meta.onboarding;

package/src/scripts/schemas/pack.schema.json

@@ -6,7 +6,10 @@
   "$comment": "Generated by scripts/generate_pack_manifests.py and validated on load by scripts/validate_pack_yaml.py. Schema introduced in road-to-6.0.0-D Phase 0 Step 2. `dependencies` is the artefact-level include graph (skills/rules the pack's commands reference); `requires` is the pack-level hard-dependency graph (must be acyclic — enforced by scripts/lint_pack_dependencies.py).",
   "type": "object",
   "additionalProperties": false,
-  "required": ["id", "artefact_count"],
+  "required": [
+    "id",
+    "artefact_count"
+  ],
   "properties": {
     "id": {
       "type": "string",
@@ -27,7 +30,9 @@
     },
     "owner": {
       "type": "array",
-      "items": { "type": "string" }
+      "items": {
+        "type": "string"
+      }
     },
     "requires": {
       "type": "array",
@@ -47,12 +52,21 @@
     },
     "size_class": {
       "type": "string",
-      "enum": ["core", "small", "medium", "large", "platform"],
+      "enum": [
+        "core",
+        "small",
+        "medium",
+        "large",
+        "platform"
+      ],
       "description": "Per-pack visible-command budget input."
     },
     "surface_tier": {
       "type": "string",
-      "enum": ["core", "lab"],
+      "enum": [
+        "core",
+        "lab"
+      ],
       "description": "Install-layout surface tier (road-to-install-contract-stability Phase 2). `core` = the lean stable multi-host engine that users install (rules + skills + install + condensation); `lab` = experimental / pilot domain tooling that must not destabilise the core install. Default `core`. The core-only install path excludes `lab` packs."
     },
     "trust_level_default": {
@@ -92,6 +106,50 @@
           }
         }
       }
+    },
+    "token_passport": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "basis",
+        "rules_tokens",
+        "catalog_tokens",
+        "commands_tokens",
+        "other_tokens",
+        "total_tokens"
+      ],
+      "description": "GENERATED — what this pack contributes to the STANDING session payload. Derivation, tokenizer and the reconciliation target are fixed by docs/contracts/pack-token-passport.md, written before the first passport existed. Standing cost only: 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. It is a floor on a pack's session cost, never the whole of it.",
+      "properties": {
+        "basis": {
+          "type": "string",
+          "enum": [
+            "chars/4"
+          ],
+          "description": "Pinned to an enum on purpose. chars/4 is the basis preamble-payload-budget.json declares for itself; a passport measured with an exact tokenizer could not be compared against a census measured with a proxy without the gap between two METHODS reading as a discrepancy in the packs."
+        },
+        "rules_tokens": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "catalog_tokens": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Sum of `- <name>: <description>\\n` over the pack's skill artefacts — the SAME construction censusSkillsCatalog uses, not an approximation of it."
+        },
+        "commands_tokens": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "other_tokens": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Every other claimed artefact — contexts, personas, presets, profiles, user-types. Exists because the three named buckets produced a misleading zero: `core` claimed 47 artefacts and reported 0 tokens, which reads as 'this pack is free'."
+        },
+        "total_tokens": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
     }
   }
 }

package/src/scripts/schemas/skill.schema.json

@@ -25,8 +25,8 @@
     "description": {
       "type": "string",
       "minLength": 1,
-      "maxLength": 220,
-      "description": "Trigger phrase; ≤ 200 chars recommended, 220 is the ceiling (lean-initial-context: descriptions load eagerly via progressive disclosure). Over-cap is a soft warning, not a hard fail — a warning window so authors adapt."
+      "maxLength": 200,
+      "description": "Trigger phrase; the ceiling is 200 chars, measured. Lowered from 220 on 2026-08-22 because 220 described no artefact that existed: across all 290 skills the distribution was median 181 / p75 189 / max 200, with ZERO over 200, so the 20 chars above the recommended line were dead headroom a future author could fill with no gate objecting. p75 = 189 is the recorded soft target; 200 is the hard line. Descriptions load eagerly via progressive disclosure, so every char here is standing cost on every spawn."
     },
     "compatibility": {
       "type": "string",