@event4u/agent-config 14.8.0 → 14.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (170) hide show
  1. package/.claude-plugin/marketplace.json +1 -1
  2. package/CHANGELOG.md +214 -237
  3. package/README.md +1 -1
  4. package/agents/templates/.ai-council.yml.example +34 -4
  5. package/dist/agent-src/commands/pr/merge.md +9 -5
  6. package/dist/agent-src/commands/review/changes.md +95 -14
  7. package/dist/agent-src/commands/roadmap/process-full.md +2 -2
  8. package/dist/agent-src/contexts/execution/host-capability-manifest.md +77 -0
  9. package/dist/agent-src/contexts/execution/roadmap-execution-contract.md +36 -0
  10. package/dist/agent-src/contexts/execution/subagent-response-contract.md +80 -0
  11. package/dist/agent-src/rules/untrusted-input-defense.md +9 -3
  12. package/dist/agent-src/skills/async-python-patterns/SKILL.md +1 -1
  13. package/dist/agent-src/skills/code-refactoring/SKILL.md +1 -1
  14. package/dist/agent-src/skills/code-review/evals/evals.json +87 -46
  15. package/dist/agent-src/skills/condense-memory/SKILL.md +1 -1
  16. package/dist/agent-src/skills/conventional-commits-writing/SKILL.md +1 -1
  17. package/dist/agent-src/skills/design-review/SKILL.md +1 -1
  18. package/dist/agent-src/skills/discovery-interview/SKILL.md +1 -1
  19. package/dist/agent-src/skills/doc-coauthoring/SKILL.md +1 -1
  20. package/dist/agent-src/skills/docx-authoring/SKILL.md +1 -1
  21. package/dist/agent-src/skills/editorial-calendar/SKILL.md +1 -1
  22. package/dist/agent-src/skills/github-ci/SKILL.md +1 -1
  23. package/dist/agent-src/skills/humanizer/SKILL.md +39 -0
  24. package/dist/agent-src/skills/humanizer/evals/strip_fixtures.json +57 -0
  25. package/dist/agent-src/skills/humanizer/references/fixtures.md +54 -0
  26. package/dist/agent-src/skills/judge-artifact-completeness/SKILL.md +1 -1
  27. package/dist/agent-src/skills/judge-injection-defense/SKILL.md +1 -1
  28. package/dist/agent-src/skills/judge-spec-compliance/SKILL.md +154 -0
  29. package/dist/agent-src/skills/judge-synthesis/SKILL.md +45 -0
  30. package/dist/agent-src/skills/laravel-validation/SKILL.md +1 -1
  31. package/dist/agent-src/skills/legal-intake-triage/SKILL.md +1 -1
  32. package/dist/agent-src/skills/legal-practice-profile/SKILL.md +1 -1
  33. package/dist/agent-src/skills/messaging-architecture/SKILL.md +1 -1
  34. package/dist/agent-src/skills/migration-architect/SKILL.md +1 -1
  35. package/dist/agent-src/skills/module-detect-on-the-fly/SKILL.md +1 -1
  36. package/dist/agent-src/skills/module-management/SKILL.md +1 -1
  37. package/dist/agent-src/skills/motion-choreographer/SKILL.md +1 -1
  38. package/dist/agent-src/skills/onboarding-program/SKILL.md +1 -1
  39. package/dist/agent-src/skills/perf-feedback-craft/SKILL.md +1 -1
  40. package/dist/agent-src/skills/prompt-optimizer/SKILL.md +1 -1
  41. package/dist/agent-src/skills/receiving-code-review/SKILL.md +1 -1
  42. package/dist/agent-src/skills/roadmap-writing/SKILL.md +18 -18
  43. package/dist/agent-src/skills/scene-expander/SKILL.md +1 -1
  44. package/dist/agent-src/skills/secrets-management/SKILL.md +1 -1
  45. package/dist/agent-src/skills/using-git-worktrees/SKILL.md +1 -1
  46. package/dist/agent-src/templates/agents/agent-project-settings.example.yml +1 -1
  47. package/dist/agent-src/templates/roadmaps.md +8 -0
  48. package/dist/cli/registry.js +2 -0
  49. package/dist/cli/registry.js.map +1 -1
  50. package/dist/cli-delegate/{chunk-MMSGVZKV.js → chunk-77GR3VD4.js} +65 -40
  51. package/dist/cli-delegate/{chunk-Q26HT4QT.js → chunk-E46KPN6K.js} +251 -150
  52. package/dist/cli-delegate/{chunk-EEJUMCDZ.js → chunk-PLSG6UL5.js} +1 -1
  53. package/dist/cli-delegate/cmd_conformance.js +89 -13
  54. package/dist/cli-delegate/cmd_doctor.js +3 -3
  55. package/dist/cli-delegate/cmd_handoff.js +2 -2
  56. package/dist/cli-delegate/cmd_memory_get.js +1 -1
  57. package/dist/cli-delegate/cmd_route_audit.js +1 -1
  58. package/dist/cli-delegate/cmd_settings_get.js +1 -1
  59. package/dist/cli-delegate/cmd_settings_set.js +1 -1
  60. package/dist/discovery/deprecation-report.md +1 -1
  61. package/dist/discovery/discovery-manifest.json +64 -42
  62. package/dist/discovery/discovery-manifest.json.sha256 +1 -1
  63. package/dist/discovery/discovery-manifest.summary.md +3 -3
  64. package/dist/discovery/dormancy-report.md +1 -1
  65. package/dist/discovery/orphan-report.md +1 -1
  66. package/dist/discovery/packs.json +6 -5
  67. package/dist/discovery/trust-report.md +2 -2
  68. package/dist/discovery/workspaces.json +5 -4
  69. package/dist/hooks/dispatch.js +562 -204
  70. package/dist/mcp/registry-manifest.json +3 -3
  71. package/dist/mcp/server.json +2 -2
  72. package/dist/mcp/server.mjs +808 -331
  73. package/dist/scripts/_lib/claude_plugin.js +162 -0
  74. package/dist/scripts/_lib/claude_plugin.js.map +1 -0
  75. package/dist/scripts/_lib/environment_detector.js +397 -0
  76. package/dist/scripts/_lib/environment_detector.js.map +1 -0
  77. package/dist/scripts/_lib/spawn_env.js +129 -0
  78. package/dist/scripts/_lib/spawn_env.js.map +1 -0
  79. package/dist/scripts/ai_council/modes.js +199 -0
  80. package/dist/scripts/ai_council/modes.js.map +1 -0
  81. package/dist/scripts/ai_council/transport_resolver.js +418 -0
  82. package/dist/scripts/ai_council/transport_resolver.js.map +1 -0
  83. package/dist/server/routes/wizard.js +3 -2
  84. package/dist/server/routes/wizard.js.map +1 -1
  85. package/dist/ui/assets/index-Cxgy63kz.js +26 -0
  86. package/dist/ui/assets/index-Cxgy63kz.js.map +1 -0
  87. package/dist/ui/index.html +1 -1
  88. package/docs/guidelines/agent-infra/traceability-field-mechanics.md +50 -0
  89. package/docs/guidelines/agent-infra/untrusted-input-spotlighting.md +17 -0
  90. package/package.json +7 -3
  91. package/src/config/estate-count-budget.json +13 -744
  92. package/src/config/evaluator-budgets.json +4 -4
  93. package/src/config/gate-coverage.yml +267 -9
  94. package/src/config/gate-violation-baselines.json +72 -72
  95. package/src/config/preamble-payload-budget.json +71 -67
  96. package/src/config/publish-surface.json +60 -0
  97. package/src/config/requirements-trace-budget.json +32 -0
  98. package/src/config/rule-stub-ceilings.json +8 -1
  99. package/src/scripts/_dispatch.bash +7 -0
  100. package/src/scripts/_lib/base_tree.ts +175 -0
  101. package/src/scripts/_lib/billing_grant.ts +165 -0
  102. package/src/scripts/_lib/billing_grant_cli.ts +123 -0
  103. package/src/scripts/_lib/council_fallback_posture.ts +53 -6
  104. package/src/scripts/_lib/council_fallback_wiring.ts +61 -1
  105. package/src/scripts/_lib/host_capability.ts +59 -5
  106. package/src/scripts/_lib/quota_parked.ts +133 -0
  107. package/src/scripts/_lib/retrieval_sanitize.ts +62 -0
  108. package/src/scripts/_lib/review_telemetry.ts +196 -0
  109. package/src/scripts/_lib/subagent_response.ts +92 -0
  110. package/src/scripts/adr/regenerate_index.ts +14 -7
  111. package/src/scripts/ai_council/clients.ts +12 -1
  112. package/src/scripts/ai_council/config.ts +72 -115
  113. package/src/scripts/ai_council/fallback_config.ts +19 -7
  114. package/src/scripts/ai_council/mid_flight_fallback.ts +88 -7
  115. package/src/scripts/ai_council/orchestrator.ts +2 -2
  116. package/src/scripts/ai_council/py_format.ts +124 -0
  117. package/src/scripts/ai_council/seating.ts +211 -0
  118. package/src/scripts/ai_council/transport_resolver.ts +65 -2
  119. package/src/scripts/audit_adr_coverage.ts +33 -6
  120. package/src/scripts/check_council_pin_staleness.ts +300 -0
  121. package/src/scripts/check_estate_count.ts +420 -293
  122. package/src/scripts/check_gate_coverage.ts +91 -0
  123. package/src/scripts/check_no_stub_inventory_table.ts +292 -0
  124. package/src/scripts/check_pack_passport_reconciliation.ts +274 -0
  125. package/src/scripts/check_pack_size.ts +234 -1
  126. package/src/scripts/check_publish_surface.ts +297 -0
  127. package/src/scripts/check_requirements_trace.ts +378 -0
  128. package/src/scripts/check_secret_leak.ts +166 -12
  129. package/src/scripts/code_graph/cli.ts +44 -5
  130. package/src/scripts/code_graph/extract.ts +87 -0
  131. package/src/scripts/council_cli.ts +12 -16
  132. package/src/scripts/detect_ai_tells.ts +87 -0
  133. package/src/scripts/dispatch_r2_reviewer.ts +42 -0
  134. package/src/scripts/generate_capabilities_index.ts +41 -0
  135. package/src/scripts/generate_pack_manifests.ts +78 -0
  136. package/src/scripts/git_authorization_hook.ts +54 -4
  137. package/src/scripts/hooks/block_unauthorized_git.ts +19 -1
  138. package/src/scripts/hooks/run_continuation_hook.ts +3 -1
  139. package/src/scripts/hooks/subagent_ledger_hook.ts +76 -11
  140. package/src/scripts/injection_scan_hook.ts +120 -10
  141. package/src/scripts/lint_adr_sweep_routing.ts +365 -0
  142. package/src/scripts/lint_workflow_security.ts +53 -10
  143. package/src/scripts/lint_workflow_security_allowlist.json +2 -18
  144. package/src/scripts/report_envelope_rate.ts +166 -0
  145. package/src/scripts/review_axis_report.ts +218 -0
  146. package/src/scripts/run_supervise.ts +46 -1
  147. package/src/scripts/schemas/evals.schema.json +5 -0
  148. package/src/scripts/schemas/pack.schema.json +62 -4
  149. package/src/scripts/schemas/skill.schema.json +2 -2
  150. package/src/scripts/sync_pr_branch.ts +14 -7
  151. package/src/scripts/tighten_skill_descriptions.ts +264 -0
  152. package/dist/cli/commands/commands.candidates.test.js +0 -257
  153. package/dist/cli/commands/commands.candidates.test.js.map +0 -1
  154. package/dist/cli/commands/profiles.test.js +0 -88
  155. package/dist/cli/commands/profiles.test.js.map +0 -1
  156. package/dist/cli/commands/recordTriggerEval.test.js +0 -113
  157. package/dist/cli/commands/recordTriggerEval.test.js.map +0 -1
  158. package/dist/cli/configRoot.test.js +0 -97
  159. package/dist/cli/configRoot.test.js.map +0 -1
  160. package/dist/cli/mcp/content.test.js +0 -54
  161. package/dist/cli/mcp/content.test.js.map +0 -1
  162. package/dist/cli/mcp/dispatch.test.js +0 -108
  163. package/dist/cli/mcp/dispatch.test.js.map +0 -1
  164. package/dist/server/writeRoot.test.js +0 -91
  165. package/dist/server/writeRoot.test.js.map +0 -1
  166. package/dist/shared/capabilities.test.js +0 -39
  167. package/dist/shared/capabilities.test.js.map +0 -1
  168. package/dist/ui/assets/index-C1pBRm1f.js +0 -26
  169. package/dist/ui/assets/index-C1pBRm1f.js.map +0 -1
  170. /package/dist/cli-delegate/{chunk-N7CDDGI3.js → chunk-CYH5SP6M.js} +0 -0
@@ -0,0 +1,274 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Do the per-pack passports add up to the census the tree already runs?
4
+ *
5
+ * A per-pack number published beside a tree-wide number it contradicts is worse
6
+ * than no per-pack number: both get quoted, and nobody can say which is wrong.
7
+ * This is the check that says so out loud.
8
+ *
9
+ * THE ±10 % BAND THIS WAS SPECIFIED WITH RESTED ON A FALSE PREMISE, and the
10
+ * measurement is what refuted it. The band assumed packs roughly PARTITION the
11
+ * tree, so per-pack sums should approach the tree-wide census. Measured on
12
+ * 2026-08-22: across all 17 packs, `dependencies` claims **4 skills and 0
13
+ * rules**, against **291 skills and 118 rules** in the projection. Packs claim
14
+ * ~1 % of the artefacts the census counts.
15
+ *
16
+ * So the two numbers are not a reconciliation pair at all:
17
+ *
18
+ * census — the PROJECTED tree (`dist/agent-src/`), everything that ships
19
+ * passport — what a pack CLAIMS, which is a small, deliberate subset
20
+ *
21
+ * A gate failing on an 84 % gap would be failing on a property of the tree, not
22
+ * on a defect — and a gate that is red by construction gets disabled rather
23
+ * than fixed. So this REPORTS coverage as a first-class number and exits 0.
24
+ * That is exactly what the step behind it asked for: a passport that does not
25
+ * reconcile "must say what, in-band, rather than being published alongside a
26
+ * number it contradicts."
27
+ *
28
+ * What would make it a gate: pack coverage approaching the tree. Then the band
29
+ * becomes meaningful and the exit code can follow it. Until then the useful
30
+ * output is the RANKING plus the coverage figure.
31
+ *
32
+ * Both sides are `chars/4` — the basis `preamble-payload-budget.json` declares
33
+ * for itself. Mixing an exact tokenizer into one side would make the gap
34
+ * between two METHODS read as a discrepancy in the packs.
35
+ *
36
+ * Also emits the RANKING, because the useful output is not the numbers but
37
+ * which packs carry the weight: a per-pack table sorted by cost turns "the
38
+ * estate grew" into "this pack grew".
39
+ *
40
+ * Exit: 0 always (it is a REPORT, not a gate), 2 on a dead scan scope. See the
41
+ * band note above for why the exit code does not follow the gap.
42
+ */
43
+ import * as fs from 'node:fs';
44
+ import * as path from 'node:path';
45
+ import { fileURLToPath } from 'node:url';
46
+
47
+ import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
48
+ import { runSelfTest } from './_lib/gate_self_test.js';
49
+ import { censusRuleDir, censusSkillsCatalog } from './preamble_byte_census.js';
50
+
51
+ const _HERE = fileURLToPath(import.meta.url);
52
+ export const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
53
+ export const PACKS_DIR = path.join(REPO_ROOT, 'src/packs');
54
+ export const RANKING = path.join(REPO_ROOT, 'agents/evidence/reports/pack-token-ranking.md');
55
+
56
+ /** ±10 %. See the module docstring for why a band exists at all. */
57
+ export const TOLERANCE = 0.1;
58
+
59
+ export interface Passport {
60
+ pack: string;
61
+ rules_tokens: number;
62
+ catalog_tokens: number;
63
+ commands_tokens: number;
64
+ other_tokens: number;
65
+ total_tokens: number;
66
+ }
67
+
68
+ /** Read `token_passport:` out of a generated pack.yaml — no YAML dependency. */
69
+ export function readPassport(pack: string, text: string): Passport | null {
70
+ const start = text.indexOf('token_passport:');
71
+ if (start < 0) return null;
72
+ const num = (key: string): number => {
73
+ const m = new RegExp(`^\\s+${key}:\\s*(\\d+)\\s*$`, 'm').exec(text.slice(start));
74
+ return m === null ? 0 : Number(m[1]);
75
+ };
76
+ return {
77
+ pack,
78
+ rules_tokens: num('rules_tokens'),
79
+ catalog_tokens: num('catalog_tokens'),
80
+ commands_tokens: num('commands_tokens'),
81
+ other_tokens: num('other_tokens'),
82
+ total_tokens: num('total_tokens'),
83
+ };
84
+ }
85
+
86
+ export function collectPassports(dir: string = PACKS_DIR): Passport[] {
87
+ if (!fs.existsSync(dir)) return [];
88
+ const out: Passport[] = [];
89
+ for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
90
+ if (!e.isDirectory()) continue;
91
+ const f = path.join(dir, e.name, 'pack.yaml');
92
+ if (!fs.existsSync(f)) continue;
93
+ const p = readPassport(e.name, fs.readFileSync(f, 'utf-8'));
94
+ if (p !== null) out.push(p);
95
+ }
96
+ return out;
97
+ }
98
+
99
+ export interface Reconciliation {
100
+ bucket: string;
101
+ packSum: number;
102
+ censusTotal: number;
103
+ gapPct: number;
104
+ inBand: boolean;
105
+ }
106
+
107
+ export function reconcile(packSum: number, censusTotal: number, bucket: string): Reconciliation {
108
+ // Denominator is the CENSUS, which is the side with the independent
109
+ // measurement. Dividing by the pack sum would let a passport that measured
110
+ // almost nothing report a small gap.
111
+ const gapPct = censusTotal === 0 ? (packSum === 0 ? 0 : 1) : Math.abs(packSum - censusTotal) / censusTotal;
112
+ return { bucket, packSum, censusTotal, gapPct, inBand: gapPct <= TOLERANCE };
113
+ }
114
+
115
+ export function renderRanking(ps: readonly Passport[]): string {
116
+ const sorted = [...ps].sort((a, b) => b.total_tokens - a.total_tokens);
117
+ const total = sorted.reduce((a, p) => a + p.total_tokens, 0);
118
+ const lines = [
119
+ '<!-- evidence-type: analysis -->',
120
+ '# Pack token ranking — which packs carry the weight',
121
+ '',
122
+ 'GENERATED by `./scripts-run src/scripts/check_pack_passport_reconciliation --write-ranking`.',
123
+ 'Do not hand-edit. Basis `chars/4`, per `docs/contracts/pack-token-passport.md`.',
124
+ '',
125
+ 'The numbers are each pack\'s STANDING contribution — what is paid whether or',
126
+ 'not the pack is used. A skill body loaded on invocation is a runtime cost and',
127
+ 'is not here, and the residual bucket (tool definitions + dispatch prompt) is',
128
+ 'not attributable to a pack at all.',
129
+ '',
130
+ `**${String(sorted.length)} packs, ${String(total)} tokens total.**`,
131
+ '',
132
+ '| rank | pack | total | rules | catalog | commands | other | share |',
133
+ '|---:|---|---:|---:|---:|---:|---:|---:|',
134
+ ];
135
+ sorted.forEach((p, i) => {
136
+ const share = total === 0 ? 0 : (p.total_tokens / total) * 100;
137
+ lines.push(
138
+ `| ${String(i + 1)} | \`${p.pack}\` | ${String(p.total_tokens)} | ${String(p.rules_tokens)} | ` +
139
+ `${String(p.catalog_tokens)} | ${String(p.commands_tokens)} | ${String(p.other_tokens)} | ${share.toFixed(1)} % |`,
140
+ );
141
+ });
142
+ return `${lines.join('\n')}\n`;
143
+ }
144
+
145
+ /**
146
+ * Discrimination over the two pure units — the parser and the ratio.
147
+ *
148
+ * This script exits 0 on every path by design (it is a report, not a gate), so
149
+ * no planted file can make it red and the canary harness cannot prove anything
150
+ * about it. The `scanned:` floor is the one thing about it that CAN break, and
151
+ * a self-test is what proves the two functions behind the number actually
152
+ * discriminate rather than returning something shaped like an answer.
153
+ */
154
+ function selfTest(): number {
155
+ const yaml = [
156
+ 'artefact_count: 3',
157
+ 'token_passport:',
158
+ ' basis: chars/4',
159
+ ' catalog_tokens: 20',
160
+ ' commands_tokens: 5',
161
+ ' other_tokens: 1',
162
+ ' rules_tokens: 10',
163
+ ' total_tokens: 36',
164
+ ].join('\n');
165
+ return runSelfTest({
166
+ gate: 'check_pack_passport_reconciliation',
167
+ minCases: 6,
168
+ minRejectCases: 3,
169
+ cases: [
170
+ {
171
+ name: 'a manifest with a passport parses every field',
172
+ expect: 'reject',
173
+ run: () => {
174
+ const p = readPassport('x', yaml);
175
+ return p !== null && p.rules_tokens === 10 && p.total_tokens === 36 ? 1 : 0;
176
+ },
177
+ },
178
+ {
179
+ name: 'a manifest with NO passport returns null, not a zero passport',
180
+ expect: 'accept',
181
+ run: () => (readPassport('x', 'artefact_count: 3\n') === null ? 0 : 1),
182
+ },
183
+ {
184
+ name: 'an exact match is in band',
185
+ expect: 'accept',
186
+ run: () => (reconcile(100, 100, 'b').inBand ? 0 : 1),
187
+ },
188
+ {
189
+ name: 'a 9 % gap is in band and an 11 % gap is not',
190
+ expect: 'reject',
191
+ run: () => (reconcile(109, 100, 'b').inBand && !reconcile(111, 100, 'b').inBand ? 1 : 0),
192
+ },
193
+ {
194
+ // The denominator is the CENSUS, the side with the independent
195
+ // measurement. Dividing by the pack sum would let a passport
196
+ // that measured almost nothing report a small gap — which is
197
+ // exactly the failure this repo's own measurement produced.
198
+ name: 'the denominator is the census, not the pack sum',
199
+ expect: 'reject',
200
+ run: () => (Math.abs(reconcile(1, 100, 'b').gapPct - 0.99) < 1e-9 ? 1 : 0),
201
+ },
202
+ {
203
+ name: 'both sides zero is in band; a sum against a zero census is not',
204
+ expect: 'accept',
205
+ run: () => (reconcile(0, 0, 'b').inBand && !reconcile(5, 0, 'b').inBand ? 0 : 1),
206
+ },
207
+ ],
208
+ });
209
+ }
210
+
211
+ export function main(argv: readonly string[] = process.argv.slice(2)): number {
212
+ if (argv.includes('--self-test')) return selfTest();
213
+ const passports = collectPassports();
214
+ try {
215
+ assertScanned({
216
+ gate: 'check_pack_passport_reconciliation',
217
+ scanned: passports.length,
218
+ units: 'pack passport(s)',
219
+ roots: ['src/packs/*/pack.yaml'],
220
+ });
221
+ } catch (err) {
222
+ if (err instanceof DeadScopeError) {
223
+ process.stderr.write(`❌ passport reconciliation: ${err.message}\n`);
224
+ return 2;
225
+ }
226
+ throw err;
227
+ }
228
+ process.stdout.write(`scanned: ${String(passports.length)}\n`);
229
+
230
+ if (argv.includes('--write-ranking')) {
231
+ fs.mkdirSync(path.dirname(RANKING), { recursive: true });
232
+ fs.writeFileSync(RANKING, renderRanking(passports));
233
+ process.stdout.write(`✅ ranking written to ${path.relative(REPO_ROOT, RANKING)}\n`);
234
+ }
235
+
236
+ const rules = censusRuleDir(path.join(REPO_ROOT, 'dist', 'agent-src', 'rules'));
237
+ const catalog = censusSkillsCatalog(path.join(REPO_ROOT, 'dist', 'agent-src', 'skills'));
238
+ const tok = (chars: number): number => Math.round(chars / 4);
239
+ const recs = [
240
+ reconcile(
241
+ passports.reduce((a, p) => a + p.rules_tokens, 0),
242
+ tok(rules.chars),
243
+ 'project-scope rules',
244
+ ),
245
+ reconcile(
246
+ passports.reduce((a, p) => a + p.catalog_tokens, 0),
247
+ tok(catalog.chars),
248
+ 'preloaded skills catalog',
249
+ ),
250
+ ];
251
+ for (const r of recs) {
252
+ process.stdout.write(
253
+ ` ${r.inBand ? '✅' : '❌'} ${r.bucket.padEnd(26)} packs ${String(r.packSum).padStart(7)} · ` +
254
+ `census ${String(r.censusTotal).padStart(7)} · gap ${(r.gapPct * 100).toFixed(1)} %\n`,
255
+ );
256
+ }
257
+ const covered = recs.filter((r) => r.inBand).length;
258
+ process.stdout.write(
259
+ `\ncoverage: packs account for ${String(covered)} of ${String(recs.length)} census bucket(s) within ±${String(
260
+ TOLERANCE * 100,
261
+ )} %.\n` +
262
+ ' A gap here is a PROPERTY OF THE TREE, not a defect: pack `dependencies` claim a\n' +
263
+ ' small deliberate subset of what ships, so the two numbers are not a reconciliation\n' +
264
+ ' pair. Failing on that would be failing by construction, and a gate that is red by\n' +
265
+ ' construction gets disabled rather than fixed.\n' +
266
+ ' The useful output is the ranking above plus this figure. See\n' +
267
+ ' docs/contracts/pack-token-passport.md § Reconciliation for what would make it a gate.\n',
268
+ );
269
+ return 0;
270
+ }
271
+
272
+ if (process.argv[1] !== undefined && process.argv[1].includes('check_pack_passport_reconciliation')) {
273
+ process.exit(main(process.argv.slice(2)));
274
+ }
@@ -28,6 +28,7 @@ import * as path from 'node:path';
28
28
  import { fileURLToPath } from 'node:url';
29
29
 
30
30
  import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
31
+ import { runSelfTest } from './_lib/gate_self_test.js';
31
32
 
32
33
  const REPO_ROOT = path.resolve(fileURLToPath(import.meta.url), '..', '..', '..');
33
34
  const BUDGET_PATH = path.join(REPO_ROOT, 'src', 'config', 'pack-size-budget.json');
@@ -98,6 +99,126 @@ export function skillBytes(files: readonly PackFile[]): { perSkill: Record<strin
98
99
  }
99
100
 
100
101
  /** Every violation, as human-readable lines. Empty array means green. */
102
+ /**
103
+ * Content classes the published payload is checked for.
104
+ *
105
+ * The gap this closes: before it, the tarball was measured by SIZE and by build
106
+ * correctness, and by nothing that read what the files ARE. A payload can be
107
+ * comfortably under budget and still ship compiled tests, an IDE directory, or
108
+ * a credential-shaped file.
109
+ *
110
+ * `limit: 0` is a hard class — nothing of that shape may ship. A positive limit
111
+ * is a RATCHET: the number was measured, not chosen, and it may only walk down.
112
+ * The distinction is in `measured_in`, which every entry carries, because the
113
+ * same `npm pack` reports a fifth of the source maps in an unbuilt worktree as
114
+ * in a built one. A threshold with no stated tree reads as drift the first time
115
+ * someone runs it from a fresh checkout.
116
+ */
117
+ interface ContentClass {
118
+ id: string;
119
+ /** Matches a payload path. */
120
+ match: (p: string) => boolean;
121
+ /** 0 = must not ship at all. > 0 = shrink-only ratchet. */
122
+ limit: number;
123
+ /** Which tree the limit was measured in, and when. */
124
+ measured_in: string;
125
+ /**
126
+ * True when the class only exists in a BUILT tree.
127
+ *
128
+ * This is the difference between a check and a false pass. `npm pack
129
+ * --dry-run --ignore-scripts` on a clean checkout — which is the condition
130
+ * `pack-size-budget.json` declares for its own numbers — produces no
131
+ * `dist/cli/**` at all, so a source-map count of 22 sails under a limit of
132
+ * 120 while measuring a fifth of the payload. Reported NOT MEASURABLE
133
+ * instead, on the same principle as the dead-scope assertion above: a check
134
+ * that could not run is not a clean bill.
135
+ */
136
+ requires_build: boolean;
137
+ why: string;
138
+ }
139
+
140
+ /**
141
+ * Was this payload produced from a built tree?
142
+ *
143
+ * Keyed on the payload itself rather than on the filesystem, so it describes
144
+ * the thing being judged instead of the machine judging it.
145
+ */
146
+ function payloadIsBuilt(files: readonly PackFile[]): boolean {
147
+ return files.some((f) => f.path.startsWith('dist/cli/'));
148
+ }
149
+
150
+ const CONTENT_CLASSES: readonly ContentClass[] = [
151
+ {
152
+ id: 'compiled-test-artefact',
153
+ requires_build: true,
154
+ match: (p) => /\.(test|spec)\.(js|js\.map|d\.ts)$/.test(p),
155
+ limit: 0,
156
+ measured_in: 'built main checkout, 2026-08-22: 8 `.test.js` + 8 `.test.js.map` were shipping before the `files[]` negations landed',
157
+ why: "a compiled test's output has no consumer-facing purpose; council 2026-08-22 decision (b') strips BOTH the JS and its map, because stripping only the maps left the compiled tests themselves in the tarball",
158
+ },
159
+ {
160
+ id: 'credential-shaped',
161
+ requires_build: false,
162
+ match: (p) => /(^|\/)\.env(\.|$)|\.pem$|(^|\/)id_(rsa|ed25519)$|\.p12$|\.pfx$/.test(p),
163
+ limit: 0,
164
+ measured_in: 'built main checkout, 2026-08-22: 0 present',
165
+ why: 'a clean class with no check is indistinguishable from a class nobody looked at — and this one is worth a canary precisely because it is empty today',
166
+ },
167
+ {
168
+ id: 'ide-metadata',
169
+ requires_build: false,
170
+ match: (p) => /(^|\/)\.(idea|vscode)\//.test(p),
171
+ limit: 0,
172
+ measured_in: 'built main checkout, 2026-08-22: 0 present',
173
+ why: 'same reason as the credential class: empty and unchecked is not the same as empty and verified',
174
+ },
175
+ {
176
+ id: 'source-map',
177
+ requires_build: true,
178
+ match: (p) => p.endsWith('.js.map'),
179
+ limit: 120,
180
+ measured_in: 'built worktree, 2026-08-22, AFTER the compiled-test negations: 120 product maps (128 total minus 8 test maps)',
181
+ why: "a product source map is a consumer debugging affordance — proper line mapping and stepping over shipped JS — so council 2026-08-22 kept the 119/120 product maps and refused a blanket zero. Recorded as a PROVISIONAL measured ratchet, not an architectural constant: nothing here establishes that any consumer debugs the shipped JS, and nothing establishes they do not",
182
+ },
183
+ ];
184
+
185
+ /**
186
+ * Count each content class in the payload and report over-limit classes.
187
+ *
188
+ * Returns one error string per violating class, with the offending paths — the
189
+ * count alone tells a reader a rule broke and not which file broke it.
190
+ */
191
+ export function classifyPayload(files: readonly PackFile[]): string[] {
192
+ const out: string[] = [];
193
+ const built = payloadIsBuilt(files);
194
+ for (const c of CONTENT_CLASSES) {
195
+ if (c.requires_build && !built) continue;
196
+ const hits = files.filter((f) => c.match(f.path)).map((f) => f.path);
197
+ if (hits.length <= c.limit) continue;
198
+ const shown = hits.slice(0, 8);
199
+ out.push(
200
+ `content class \`${c.id}\`: ${String(hits.length)} entr${hits.length === 1 ? 'y' : 'ies'} ` +
201
+ `exceeds its limit of ${String(c.limit)} (measured in: ${c.measured_in}) — ` +
202
+ `${shown.join(', ')}${hits.length > shown.length ? `, +${String(hits.length - shown.length)} more` : ''}. ` +
203
+ `Why this class is checked: ${c.why}`,
204
+ );
205
+ }
206
+ return out;
207
+ }
208
+
209
+ /** Per-class counts, for the green-path report. */
210
+ export function payloadClassCounts(
211
+ files: readonly PackFile[],
212
+ ): Array<{ id: string; count: number; limit: number; measurable: boolean }> {
213
+ const built = payloadIsBuilt(files);
214
+ return CONTENT_CLASSES.map((c) => ({
215
+ id: c.id,
216
+ count: files.filter((f) => c.match(f.path)).length,
217
+ limit: c.limit,
218
+ measurable: built || !c.requires_build,
219
+ }));
220
+ }
221
+
101
222
  export function evaluate(budget: PackSizeBudget, pack: PackResult): string[] {
102
223
  const errors: string[] = [];
103
224
 
@@ -163,7 +284,103 @@ function readPack(argv: readonly string[]): PackResult {
163
284
  return parsePackJson(stdout);
164
285
  }
165
286
 
287
+ /**
288
+ * Per-class discrimination, proven rather than asserted.
289
+ *
290
+ * WHY THIS EXISTS AND THE CANARY DOES NOT COVER IT. `gate-coverage.yml` carries
291
+ * `canary?: CanarySpec` — exactly ONE recipe per gate id, not a list (see
292
+ * `check_gate_coverage.ts`'s entry shape). The roadmap step behind this asked
293
+ * for "one canary per class", which the register cannot express. Two of the four
294
+ * classes cannot be planted through it at all: `compiled-test-artefact` is
295
+ * excluded from the payload by the `files[]` negations that fixed it, so a plant
296
+ * never ships and never reds, and `source-map` needs 121 files in a BUILT tree.
297
+ *
298
+ * So the register gets the one canary it can hold — the credential-shaped plant,
299
+ * chosen because that class is empty today and an empty unchecked class is
300
+ * indistinguishable from one nobody looked at — and every class is proven red
301
+ * here, over a synthetic payload, deterministically and with no pack run.
302
+ *
303
+ * A test file was the alternative and is weaker: the non-adopter ratchet in
304
+ * `check_gate_coverage` requires a NEW registered gate to carry a `--self-test`
305
+ * or an exemption, and a self-test drives the gate's own decision function
306
+ * rather than a copy of it.
307
+ */
308
+ function packFiles(...paths: readonly string[]): PackFile[] {
309
+ return paths.map((path) => ({ path, size: 1 }));
310
+ }
311
+
312
+ /** A payload that looks built, so `requires_build` classes do not abstain. */
313
+ function builtPayload(...paths: readonly string[]): PackFile[] {
314
+ return packFiles('dist/cli/agent-config.js', ...paths);
315
+ }
316
+
317
+ function selfTest(): number {
318
+ // NOT under `dist/cli/` — that prefix is exactly what `payloadIsBuilt`
319
+ // keys on, so maps placed there would make an "unbuilt" fixture built and
320
+ // the abstain case would test nothing. Found by the case failing, which is
321
+ // the self-test doing its job on its own fixtures.
322
+ const maps = (n: number): string[] =>
323
+ Array.from({ length: n }, (_, i) => `dist/hooks/chunk-${String(i)}.js.map`);
324
+ return runSelfTest({
325
+ gate: 'check_pack_size',
326
+ minCases: 9,
327
+ minRejectCases: 5,
328
+ cases: [
329
+ {
330
+ name: 'credential-shaped: a .pem in the payload is refused',
331
+ expect: 'reject',
332
+ run: () => (classifyPayload(packFiles('src/scripts/x.pem')).length > 0 ? 1 : 0),
333
+ },
334
+ {
335
+ name: 'credential-shaped: a dotted .env form is refused',
336
+ expect: 'reject',
337
+ run: () => (classifyPayload(packFiles('src/config/.env.production')).length > 0 ? 1 : 0),
338
+ },
339
+ {
340
+ name: 'ide-metadata: a .vscode entry is refused',
341
+ expect: 'reject',
342
+ run: () => (classifyPayload(packFiles('src/scripts/.vscode/settings.json')).length > 0 ? 1 : 0),
343
+ },
344
+ {
345
+ name: 'compiled-test-artefact: a shipped .test.js is refused',
346
+ expect: 'reject',
347
+ run: () => (classifyPayload(builtPayload('dist/cli/a.test.js')).length > 0 ? 1 : 0),
348
+ },
349
+ {
350
+ name: 'source-map: one over the measured ratchet is refused',
351
+ expect: 'reject',
352
+ run: () => (classifyPayload(builtPayload(...maps(121))).length > 0 ? 1 : 0),
353
+ },
354
+ {
355
+ name: 'source-map: the ratchet boundary itself passes',
356
+ expect: 'accept',
357
+ run: () => (classifyPayload(builtPayload(...maps(120))).length > 0 ? 1 : 0),
358
+ },
359
+ {
360
+ name: 'a plain payload passes — the classes are not firing on everything',
361
+ expect: 'accept',
362
+ run: () => (classifyPayload(packFiles('src/scripts/x.ts', 'README.md')).length > 0 ? 1 : 0),
363
+ },
364
+ {
365
+ // The false pass 1.2 closed. An unbuilt payload carries a fifth
366
+ // of the source maps, so a build-gated class must ABSTAIN there
367
+ // rather than report clean — and must not report a failure
368
+ // either, or every clean-checkout run would red.
369
+ name: 'unbuilt payload: build-gated classes abstain, not pass and not fail',
370
+ expect: 'accept',
371
+ run: () => (classifyPayload(packFiles(...maps(121))).length > 0 ? 1 : 0),
372
+ },
373
+ {
374
+ name: 'unbuilt payload: a build-INDEPENDENT class still fires',
375
+ expect: 'reject',
376
+ run: () => (classifyPayload(packFiles('src/scripts/id_rsa')).length > 0 ? 1 : 0),
377
+ },
378
+ ],
379
+ });
380
+ }
381
+
166
382
  export function main(argv: readonly string[] = process.argv.slice(2)): number {
383
+ if (argv.includes('--self-test')) return selfTest();
167
384
  let budget: PackSizeBudget;
168
385
  let pack: PackResult;
169
386
  try {
@@ -199,7 +416,14 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
199
416
  throw err;
200
417
  }
201
418
 
202
- const errors = evaluate(budget, pack);
419
+ // The coverage register requires an enforced gate to report what it
420
+ // inspected, and it is the same reason `assertScanned` runs above: a verdict
421
+ // with no denominator cannot be told apart from a verdict over nothing.
422
+ // Printed on EVERY path, including the failing one, so a reader of a red run
423
+ // still knows the population it was red over.
424
+ process.stdout.write(`scanned: ${String(pack.files.length)}\n`);
425
+
426
+ const errors = [...evaluate(budget, pack), ...classifyPayload(pack.files)];
203
427
  const { perSkill, total } = skillBytes(pack.files);
204
428
  if (argv.includes('--json')) {
205
429
  process.stdout.write(
@@ -216,6 +440,15 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
216
440
  `${Object.keys(perSkill).length} skills, largest share ` +
217
441
  `${Math.max(...Object.values(perSkill).map((b) => (b / total) * 100)).toFixed(2)}%\n`,
218
442
  );
443
+ // Printed on the GREEN path on purpose. A class that is clean and silent is
444
+ // indistinguishable from a class nobody checks, which is the whole reason
445
+ // two of these four are limit-0 over an empty set today.
446
+ for (const c of payloadClassCounts(pack.files)) {
447
+ const verdict = c.measurable
448
+ ? `${String(c.count)} / ${c.limit === 0 ? 'must be 0' : `${String(c.limit)} max`}`
449
+ : 'NOT MEASURABLE — this payload has no dist/cli/**, so the tree is unbuilt and the class is out of view';
450
+ process.stdout.write(` content class ${c.id}: ${verdict}\n`);
451
+ }
219
452
  return 0;
220
453
  }
221
454