@event4u/agent-config 14.8.0 → 14.10.0

package/src/scripts/review_axis_report.ts

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+/**
+ * Report the spec axis's measured effect on the review surface.
+ *
+ * The question this answers, and the only one: over the observation window,
+ * how often did the spec axis change the recommendation the craft judges would
+ * have produced alone? The honest answers include **zero**, and **"nothing was
+ * recorded"** — which is a third answer, not a variant of zero. A report that
+ * printed `0 changed` over an empty ledger would read as evidence the axis is
+ * useless, when it is evidence that nothing has been observed yet; those two
+ * states are separated everywhere below.
+ *
+ * Three populations, never collapsed (the same model `check_pack_size` and
+ * `check_requirements_trace` use):
+ *   observed   — lines in the window
+ *   comparable — lines where the axis ran, so a counterfactual exists
+ *   changed    — comparable lines where it flipped the recommendation
+ *
+ * `comparable` is the denominator, never `observed`: a run where the axis was
+ * unreachable carries `spec_axis_effect: null` and contributes to neither
+ * numerator nor denominator. Dividing by `observed` would report a low rate for
+ * an axis that was never given the chance to act, which is the mis-attribution
+ * this split exists to prevent.
+ *
+ * Exit code is 0 on every outcome including the empty one. This is a REPORT,
+ * not a gate — there is no threshold it could honestly enforce with the window
+ * this repo has, and a gate over an unmeasured surface fails for the wrong
+ * reason. `--self-test` exercises the pure summariser and exits non-zero on a
+ * mismatch.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import type { ReviewLine } from './_lib/review_telemetry.js';
+
+export interface ReviewAxisSummary {
+    observed: number;
+    /** Lines where the axis ran, i.e. a counterfactual exists. */
+    comparable: number;
+    changed: number;
+    unchanged: number;
+    /** Lines where the axis could not run at all. */
+    unreachable: number;
+    /** Reviews that ran with no criteria supplied — the axis reached, nothing to measure against. */
+    no_criteria: number;
+    /** Criteria handed over and unreadable — an error state, never folded into no_criteria. */
+    unparseable: number;
+    /** Earliest / latest `at` seen, or null over an empty window. */
+    window_start: string | null;
+    window_end: string | null;
+}
+
+/** Pure summariser — the unit under `--self-test`. */
+export function summarise(lines: readonly ReviewLine[]): ReviewAxisSummary {
+    const s: ReviewAxisSummary = {
+        observed: 0,
+        comparable: 0,
+        changed: 0,
+        unchanged: 0,
+        unreachable: 0,
+        no_criteria: 0,
+        unparseable: 0,
+        window_start: null,
+        window_end: null,
+    };
+    for (const l of lines) {
+        s.observed += 1;
+        if (s.window_start === null || l.at < s.window_start) s.window_start = l.at;
+        if (s.window_end === null || l.at > s.window_end) s.window_end = l.at;
+        if (l.spec_axis_reach === 'unreachable') s.unreachable += 1;
+        if (l.criteria_source === 'not_provided') s.no_criteria += 1;
+        if (l.criteria_source === 'supplied_unparseable') s.unparseable += 1;
+        if (l.spec_axis_effect === 'changed') {
+            s.comparable += 1;
+            s.changed += 1;
+        } else if (l.spec_axis_effect === 'unchanged') {
+            s.comparable += 1;
+            s.unchanged += 1;
+        }
+    }
+    return s;
+}
+
+/** Render the summary as the prose a human reads. Empty window says so in words. */
+export function render(s: ReviewAxisSummary): string {
+    const out: string[] = [];
+    if (s.observed === 0) {
+        out.push('NO WINDOW — 0 reviews recorded, so the spec axis has no measured effect in either direction.');
+        out.push('This is not "the axis changed nothing": nothing has been observed yet. Rerun once reviews have run.');
+        return out.join('\n');
+    }
+    out.push(`window: ${String(s.window_start)} … ${String(s.window_end)}`);
+    out.push(`observed: ${s.observed} review(s)`);
+    if (s.comparable === 0) {
+        out.push(
+            'comparable: 0 — the axis ran in none of them, so it changed nothing BY CONSTRUCTION, ' +
+                'which is not evidence about the axis.',
+        );
+    } else {
+        const pct = ((s.changed / s.comparable) * 100).toFixed(1);
+        out.push(`comparable: ${s.comparable} (the axis ran; a counterfactual exists)`);
+        out.push(`changed the recommendation: ${s.changed} of ${s.comparable} (${pct}%)`);
+        if (s.changed === 0) {
+            out.push('The honest reading of 0: the axis ran and never flipped a verdict over this window.');
+        }
+    }
+    out.push(
+        `not comparable: ${s.unreachable} unreachable · ${s.no_criteria} ran with no criteria · ` +
+            `${s.unparseable} with unreadable criteria (an error state, counted apart)`,
+    );
+    return out.join('\n');
+}
+
+function readLedger(dir: string): ReviewLine[] {
+    if (!fs.existsSync(dir)) return [];
+    const lines: ReviewLine[] = [];
+    for (const f of fs.readdirSync(dir).sort()) {
+        if (!f.endsWith('.jsonl')) continue;
+        for (const raw of fs.readFileSync(path.join(dir, f), 'utf8').split('\n')) {
+            const t = raw.trim();
+            if (!t) continue;
+            try {
+                const o = JSON.parse(t) as ReviewLine;
+                if (o && o.schema === 'review-axis-v1') lines.push(o);
+            } catch {
+                // A malformed line is skipped, never guessed at.
+            }
+        }
+    }
+    return lines;
+}
+
+function selfTest(): number {
+    const at = '2026-08-22T00:00:00Z';
+    const base = {
+        schema: 'review-axis-v1' as const,
+        at,
+        judges_declared: 6,
+        judges_ran: 6,
+        criteria_count: 2,
+        spec_missing: 0,
+        spec_partial: 0,
+        recommendation: 'proceed' as const,
+    };
+    const cases: { name: string; lines: ReviewLine[]; want: Partial<ReviewAxisSummary>; wantText?: string }[] = [
+        { name: 'empty window is not zero-effect', lines: [], want: { observed: 0, comparable: 0 }, wantText: 'NO WINDOW' },
+        {
+            name: 'unreachable contributes to neither population',
+            lines: [
+                {
+                    ...base,
+                    spec_axis_reach: 'unreachable',
+                    criteria_source: 'not_provided',
+                    criteria_count: 0,
+                    spec_axis_effect: null,
+                },
+            ],
+            want: { observed: 1, comparable: 0, changed: 0, unreachable: 1 },
+            wantText: 'BY CONSTRUCTION',
+        },
+        {
+            name: 'changed and unchanged both land in comparable',
+            lines: [
+                { ...base, spec_axis_reach: 'reachable_with_criteria', criteria_source: 'supplied', spec_axis_effect: 'changed' },
+                { ...base, spec_axis_reach: 'reachable_with_criteria', criteria_source: 'supplied', spec_axis_effect: 'unchanged' },
+            ],
+            want: { observed: 2, comparable: 2, changed: 1, unchanged: 1 },
+        },
+        {
+            name: 'unparseable is counted apart from no_criteria',
+            lines: [
+                {
+                    ...base,
+                    spec_axis_reach: 'reachable_no_criteria',
+                    criteria_source: 'supplied_unparseable',
+                    criteria_count: 0,
+                    spec_axis_effect: 'unchanged',
+                },
+            ],
+            want: { observed: 1, no_criteria: 0, unparseable: 1, comparable: 1 },
+        },
+    ];
+    let pass = 0;
+    let fail = 0;
+    for (const c of cases) {
+        const got = summarise(c.lines);
+        const bad = Object.entries(c.want).filter(([k, v]) => got[k as keyof ReviewAxisSummary] !== v);
+        const text = render(got);
+        const textBad = c.wantText !== undefined && !text.includes(c.wantText);
+        if (bad.length === 0 && !textBad) {
+            pass += 1;
+        } else {
+            fail += 1;
+            console.error(`❌ ${c.name}`);
+            for (const [k, v] of bad) console.error(`   ${k}: want ${String(v)}, got ${String(got[k as keyof ReviewAxisSummary])}`);
+            if (textBad) console.error(`   prose missing: ${String(c.wantText)}`);
+        }
+    }
+    process.stdout.write(`review_axis_report --self-test: ${pass} pass, ${fail} fail\n`);
+    return fail === 0 ? 0 : 1;
+}
+
+function main(argv: string[]): number {
+    if (argv.includes('--self-test')) return selfTest();
+    const dirIdx = argv.indexOf('--dir');
+    const dir =
+        dirIdx >= 0 && argv[dirIdx + 1] !== undefined
+            ? String(argv[dirIdx + 1])
+            : path.join(process.cwd(), 'agents', 'runtime', 'state', 'review-axis');
+    const lines = readLedger(dir);
+    process.stdout.write(render(summarise(lines)) + '\n');
+    process.stdout.write(`scanned: ${lines.length}\n`);
+    return 0;
+}
+
+if (process.argv[1] !== undefined && process.argv[1].includes('review_axis_report')) {
+    process.exit(main(process.argv.slice(2)));
+}

package/src/scripts/run_supervise.ts

@@ -51,6 +51,7 @@ import {
     roadmapPath,
 } from './_lib/run_checkpoint.js';
 import { readBudget } from './_lib/unattended_guard.js';
+import { findQuotaParked, type QuotaParkedMarker } from './_lib/quota_parked.js';
 import {
     LIVE_SPAWN_REFUSAL,
     planResume,
@@ -80,6 +81,7 @@ export type Disposition =
     | 'no-roadmap'
     | 'roadmap-unreadable'
     | 'complete'
+    | 'quota-parked'
     | 'budget-exhausted'
     | 'relaunchable';
 
@@ -246,6 +248,21 @@ export function classify(
             reason: 'no open steps remain — the run finished, the session just never said so',
         };
     }
+    // Before the relaunch cap, and the order is load-bearing in one direction
+    // only: a parked run that has also spent its relaunches should still read
+    // as parked, because "waiting for a reset" is the cause and "spent three
+    // relaunches" is a consequence of it. Reported the other way round, an
+    // operator sees a run that failed repeatedly rather than one that keeps
+    // meeting the same wall.
+    const parked = findQuotaParked(repoRoot, rec.session_id);
+    if (parked !== null) {
+        return {
+            ...base,
+            disposition: 'quota-parked',
+            open_steps: counts.open,
+            reason: quotaParkedReason(parked, counts.open),
+        };
+    }
     if (base.relaunches >= MAX_RELAUNCHES_PER_RUN) {
         return {
             ...base,
@@ -264,6 +281,23 @@ export function classify(
     };
 }
 
+/**
+ * The one sentence a human acts on for a parked run.
+ *
+ * It states the reset time is unknown rather than omitting it, and rather than
+ * guessing an interval. There is no reset-time parser and there will not be one
+ * until a verified error string exists to pin a fixture against — see
+ * `later/road-to-billing-cliff-detection.md`. An omitted unknown reads as "no
+ * wait needed"; a guessed interval reads as a fact.
+ */
+export function quotaParkedReason(m: QuotaParkedMarker, open: number): string {
+    return (
+        `plan quota exhausted on ${m.providers.join(', ')} since ${m.parked_at} — ` +
+        `${open} open step(s) remain; the run is waiting, not broken. ` +
+        `Reset time unknown (no parser: no verified error string yet).`
+    );
+}
+
 export interface ScanOptions {
     readonly now?: Date;
 }
@@ -434,10 +468,21 @@ export function digest(repoRoot: string, candidates: readonly Candidate[], now:
 
     const dead = candidates.filter((c) => c.disposition !== 'alive');
     const relaunchable = candidates.filter((c) => c.disposition === 'relaunchable');
+    const quotaParked = candidates.filter((c) => c.disposition === 'quota-parked');
     lines.push(
         `  sessions: ${candidates.length} registered · ${candidates.length - dead.length} alive · ` +
-            `${relaunchable.length} relaunchable`,
+            `${relaunchable.length} relaunchable` +
+            (quotaParked.length > 0 ? ` · ${quotaParked.length} quota-parked` : ''),
     );
+    // Named on its own line, not folded into the relaunchable count, because
+    // the two call for opposite responses: a relaunchable run wants a session,
+    // a parked one wants time. Suppressed at zero so the ordinary digest does
+    // not carry a line about a state nothing is in.
+    for (const c of quotaParked) {
+        lines.push(
+            `  parked:   ${c.roadmap ?? '-'} — ${c.reason}`,
+        );
+    }
 
     const budget = readBudget(repoRoot, now);
     lines.push(

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

@@ -48,6 +48,11 @@
             "minLength": 1,
             "description": "The input fixture handed to the skill under test."
           },
+          "_why": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Optional rationale: why this fixture exists at all. Annotation, never input — nothing reads it at run time, and it carries the same underscore prefix as the top-level `_calibration` to say so. Added because the alternative, on scenarios whose rationale IS the negative-control argument for the pair above them, was to delete the argument to satisfy additionalProperties."
+          },
           "environment": {
             "type": "string",
             "minLength": 1,

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",

package/src/scripts/sync_pr_branch.ts

@@ -105,14 +105,21 @@ const GENERATED = [
  * because the result looks measured either way. So this class NAMES the
  * resolution and stops. The human runs it, with the result in front of them.
  *
- * Both members conflict in 7 of the 7 open PRs measured for
- * road-to-merge-hotspot-drawdown. Neither is gitignorable: an untracked baseline
- * is a baseline no PR diff can be compared against, which deletes the ratchet.
+ * `gate-violation-baselines.json` conflicted in 7 of the 7 open PRs measured for
+ * road-to-merge-hotspot-drawdown, and it is not gitignorable: its counts are not
+ * a function of the tree, so the committed number is the only "before" side that
+ * exists.
+ *
+ * `estate-count-budget.json` USED to be the other member and is deliberately not
+ * listed any more (ADR-243). Its metrics ARE a function of the tree, so
+ * `check_estate_count` measures the floor at the base ref instead of storing it,
+ * and the file now carries policy only. A conflict in it is an ordinary AUTHORED
+ * one — two humans editing the same policy sentence — and telling the reader to
+ * "re-run the measurement" for that would name a resolution the file no longer
+ * has. Removing the row is the point of the change, not an oversight: the row
+ * described a conflict that no longer occurs.
  */
-const REMEASURED = [
-    'src/config/estate-count-budget.json',
-    'src/config/gate-violation-baselines.json',
-];
+const REMEASURED = ['src/config/gate-violation-baselines.json'];
 
 function sh(cmd: string, args: readonly string[], cwd: string): { ok: boolean; out: string; err: string } {
     const r = spawnSync(cmd, [...args], {