@event4u/agent-config 14.2.0 → 14.4.0

package/src/agent-src/templates/scripts/telemetry/settings.ts

@@ -5,6 +5,12 @@
  * `telemetry.artifact_engagement` namespace from `.agent-settings.yml`.
  * Tolerates a missing file, a missing section, and a missing YAML parser —
  * the default-off doctrine means "everything unparseable means disabled".
+ *
+ * Three namespaces live here, all under `telemetry:` and all default-off:
+ * `artifact_engagement` (the CLI's own log), `tier_usage` (the documented
+ * signal contract), and `remote` (road-to-org-telemetry Phase 1 — the
+ * org-pack-enabled Class-A usage record). They share one doctrine and one
+ * set of coercion helpers; they share no state.
  */
 import { createRequire } from 'node:module';
 import * as fs from 'node:fs';
@@ -100,32 +106,49 @@ function _isFile(p: string): boolean {
     }
 }
 
-/** Return parsed telemetry settings — never raises on missing data. */
-export function read_settings(p: string): TelemetrySettings {
-    let section: Record<string, unknown> = {};
-    let section_present = false;
-
-    if (_isFile(p)) {
-        let raw: unknown = {};
-        try {
-            raw = YAML.parse(fs.readFileSync(p, 'utf-8'), { version: '1.1' });
-            if (raw === null || raw === undefined) {
-                raw = {};
-            }
-        } catch {
+/**
+ * Read one `telemetry.<key>` section out of a settings file.
+ *
+ * Every branch that cannot produce a section returns the empty one with
+ * `present: false` — a missing file, unparseable YAML, a missing `telemetry:`
+ * mapping, and a missing sub-key are deliberately indistinguishable here.
+ * That IS the default-off doctrine: unparseable means disabled, and a reader
+ * that could tell those cases apart would invite a caller to treat one of
+ * them as consent.
+ */
+function _read_telemetry_section(
+    p: string,
+    key: string,
+): { section: Record<string, unknown>; present: boolean } {
+    if (!_isFile(p)) {
+        return { section: {}, present: false };
+    }
+    let raw: unknown = {};
+    try {
+        raw = YAML.parse(fs.readFileSync(p, 'utf-8'), { version: '1.1' });
+        if (raw === null || raw === undefined) {
             raw = {};
         }
-        if (_isPlainObject(raw)) {
-            const tele = raw['telemetry'];
-            if (_isPlainObject(tele)) {
-                const artefact = tele['artifact_engagement'];
-                if (_isPlainObject(artefact)) {
-                    section = artefact;
-                    section_present = true;
-                }
-            }
-        }
+    } catch {
+        raw = {};
+    }
+    if (!_isPlainObject(raw)) {
+        return { section: {}, present: false };
+    }
+    const tele = raw['telemetry'];
+    if (!_isPlainObject(tele)) {
+        return { section: {}, present: false };
+    }
+    const sub = tele[key];
+    if (!_isPlainObject(sub)) {
+        return { section: {}, present: false };
     }
+    return { section: sub, present: true };
+}
+
+/** Return parsed telemetry settings — never raises on missing data. */
+export function read_settings(p: string): TelemetrySettings {
+    const { section, present: section_present } = _read_telemetry_section(p, 'artifact_engagement');
 
     const record = _isPlainObject(section['record']) ? section['record'] : {};
     const output = _isPlainObject(section['output']) ? section['output'] : {};
@@ -164,27 +187,7 @@ export class TierUsageSettings {
 
 /** Return parsed tier-usage settings — never raises on missing data. */
 export function read_tier_usage_settings(p: string): TierUsageSettings {
-    let section: Record<string, unknown> = {};
-    if (_isFile(p)) {
-        let raw: unknown = {};
-        try {
-            raw = YAML.parse(fs.readFileSync(p, 'utf-8'), { version: '1.1' });
-            if (raw === null || raw === undefined) {
-                raw = {};
-            }
-        } catch {
-            raw = {};
-        }
-        if (_isPlainObject(raw)) {
-            const tele = raw['telemetry'];
-            if (_isPlainObject(tele)) {
-                const tu = tele['tier_usage'];
-                if (_isPlainObject(tu)) {
-                    section = tu;
-                }
-            }
-        }
-    }
+    const { section } = _read_telemetry_section(p, 'tier_usage');
 
     const output = _isPlainObject(section['output']) ? section['output'] : {};
     const retier = _isPlainObject(section['retier']) ? section['retier'] : {};
@@ -208,3 +211,178 @@ export function read_tier_usage_settings(p: string): TierUsageSettings {
         min_distinct_users: _coerce_int(retier['min_distinct_users'], defaults.min_distinct_users),
     });
 }
+
+// ── telemetry.remote — org-pack Class-A usage records ───────────────────
+//
+// road-to-org-telemetry Phase 1. Same default-off doctrine as the two
+// namespaces above, with one addition the others do not need: this is the
+// only namespace whose records are intended to LEAVE the machine (Phase 2
+// transports them; Phase 1 writes them locally and nothing else). So
+// `enabled: true` alone is deliberately not enough to switch it on.
+//
+// `flush: never` AND RETENTION, TOGETHER. `never` means no transport, so the
+// local file is the only store — and the retention budget below then decides
+// what survives. A record evicted by retention under `flush: never` is a
+// record that is never sent anywhere. That is the intended trade of a growth
+// budget rather than an oversight, and it is stated here so an operator meets
+// it in the settings surface instead of inferring it from a short file. An
+// org that needs the full history configures a flush; an org that wants a
+// longer local history raises `retention.max_age_days`.
+
+export const DEFAULT_REMOTE_LOG_PATH = '.agent-telemetry.jsonl';
+export const DEFAULT_REMOTE_FLUSH = 'session-end';
+export const ALLOWED_REMOTE_FLUSH = ['session-end', 'never'] as const;
+
+/**
+ * Growth budget for the local record log (`scale-discipline` R-A7).
+ *
+ * Mirrors `DEFAULT_RETENTION_MAX_AGE_DAYS` / `DEFAULT_RETENTION_MAX_BYTES`
+ * in `remote.ts`, which is where the measured basis for both numbers is
+ * written down. Duplicated as literals rather than imported because this
+ * module is the settings surface and must stay readable on its own; the
+ * pairing is asserted by a test rather than left to a comment.
+ */
+export const DEFAULT_REMOTE_RETENTION = {
+    max_age_days: 90,
+    max_bytes: 2 * 1024 * 1024,
+} as const;
+
+/**
+ * Smallest legal retention override, per key.
+ *
+ * A budget below these is not a stricter budget, it is a broken one: a
+ * `max_bytes` under one record line empties the log on every append, and a
+ * `max_age_days` of zero prunes everything written before this instant. Both
+ * are the "retains nothing" outcome the zero-rejection above refuses, reached
+ * by a value that is technically positive. 4 KiB is one full record clear of
+ * the largest line measured (286 bytes).
+ */
+export const MIN_RETENTION_MAX_AGE_DAYS = 1;
+export const MIN_RETENTION_MAX_BYTES = 4096;
+
+/**
+ * The three fields that must ALL carry a value — on top of `enabled` —
+ * before a single record is written. `endpoint` and `org_id` name where the
+ * data goes and on whose authority; `salt` is the org-pack secret without
+ * which the user hash would be a plain hash of a login name — i.e.
+ * reversible by dictionary.
+ *
+ * None of the four has a usable default, and that is the point: an
+ * external clone of this repository carries the key NAMES and no values,
+ * so it cannot reach `active` by copying the tree.
+ */
+export const REMOTE_REQUIRED_FIELDS = ['endpoint', 'org_id', 'salt'] as const;
+
+export class RemoteTelemetrySettings {
+    /** The raw `enabled:` value. NOT the switch — see `active`. */
+    readonly enabled: boolean;
+    readonly endpoint: string;
+    readonly org_id: string;
+    /** Org-pack secret. Never written into a record, never logged. */
+    readonly salt: string;
+    readonly flush: string;
+    readonly log_path: string;
+    /**
+     * Growth budget for `log_path`. Always present — an install that
+     * declares no `retention:` gets the defaults rather than no policy,
+     * because "unbounded" is the state R-A7 forbids and a settings file is
+     * not a place to opt back into it.
+     */
+    readonly retention_max_age_days: number;
+    readonly retention_max_bytes: number;
+
+    constructor(init: {
+        enabled: boolean;
+        endpoint: string;
+        org_id: string;
+        salt: string;
+        flush: string;
+        log_path: string;
+        retention_max_age_days: number;
+        retention_max_bytes: number;
+    }) {
+        this.enabled = init.enabled;
+        this.endpoint = init.endpoint;
+        this.org_id = init.org_id;
+        this.salt = init.salt;
+        this.flush = init.flush;
+        this.log_path = init.log_path;
+        this.retention_max_age_days = init.retention_max_age_days;
+        this.retention_max_bytes = init.retention_max_bytes;
+    }
+
+    /**
+     * Which required fields are absent. Empty array + `enabled` ⇒ `active`.
+     * Exposed so a doctor command can say WHICH field is missing without
+     * printing the salt, rather than reporting a bare "disabled".
+     */
+    get missing(): string[] {
+        const out: string[] = [];
+        for (const field of REMOTE_REQUIRED_FIELDS) {
+            if (!this[field]) {
+                out.push(field);
+            }
+        }
+        return out;
+    }
+
+    /** The real switch: opted in AND fully configured by the org pack. */
+    get active(): boolean {
+        return this.enabled && this.missing.length === 0;
+    }
+}
+
+/**
+ * Return parsed remote-telemetry settings — never raises on missing data.
+ *
+ * Fail-closed on every axis. A missing file, unparseable YAML, a missing
+ * section, a missing field, or an unknown `flush` value all resolve to a
+ * settings object whose `active` is false.
+ */
+export function read_remote_settings(p: string): RemoteTelemetrySettings {
+    const { section } = _read_telemetry_section(p, 'remote');
+    const output = _isPlainObject(section['output']) ? section['output'] : {};
+    const retention = _isPlainObject(section['retention']) ? section['retention'] : {};
+
+    // A retention override must be a positive integer AND at least the floor
+    // for its key. Zero and negatives are rejected to the default rather than
+    // honoured: `max_age_days: 0` reads like "keep nothing" but would in
+    // practice mean "prune on every append", and neither is a growth budget an
+    // operator should be able to set by typing one character.
+    //
+    // The floor exists because rejecting only `0` left the strictly worse
+    // value reachable. `max_bytes: 1` is a positive integer, passes a
+    // >0 test, and is smaller than one ~270-byte record — so every append
+    // prunes the file back to empty and the log silently retains nothing,
+    // which is exactly the outcome the zero-check was written to refuse.
+    // `MIN_RETENTION_MAX_BYTES` is one full record over the largest observed
+    // line so the smallest legal setting still keeps something.
+    const _coerce_bounded_int = (value: unknown, def: number, floor: number): number => {
+        if (typeof value === 'boolean') {
+            return def;
+        }
+        if (typeof value === 'number' && Number.isInteger(value) && value >= floor) {
+            return value;
+        }
+        return def;
+    };
+
+    return new RemoteTelemetrySettings({
+        enabled: _coerce_bool(section['enabled'], false),
+        endpoint: _coerce_str(section['endpoint'], ''),
+        org_id: _coerce_str(section['org_id'], ''),
+        salt: _coerce_str(section['salt'], ''),
+        flush: _coerce_str(section['flush'], DEFAULT_REMOTE_FLUSH, ALLOWED_REMOTE_FLUSH),
+        log_path: _coerce_path(output['path'], DEFAULT_REMOTE_LOG_PATH),
+        retention_max_age_days: _coerce_bounded_int(
+            retention['max_age_days'],
+            DEFAULT_REMOTE_RETENTION.max_age_days,
+            MIN_RETENTION_MAX_AGE_DAYS,
+        ),
+        retention_max_bytes: _coerce_bounded_int(
+            retention['max_bytes'],
+            DEFAULT_REMOTE_RETENTION.max_bytes,
+            MIN_RETENTION_MAX_BYTES,
+        ),
+    });
+}

package/src/config/estate-count-budget.json

@@ -0,0 +1,120 @@
+{
+  "_comment": "Roadmap-estate ratchet (road-to-estate-drawdown T2 + T3). The estate does not walk down by itself: new roadmaps arrive faster than old ones terminate, and until this file existed nothing in CI objected \u2014 lint_roadmap_family_cap bounds concurrency WITHIN one road-to-<family>-* family, and no gate read the estate as a whole. The baseline below is the MEASURED estate at registration, not a target: a hard target gate would be red on the day it lands and would teach the reader to ignore it. It fails on GROWTH instead, so the number can only walk down. T1's proposed ceilings are recorded under `target` and are explicitly NOT registered \u2014 they are the maintainer's to set.",
+  "schema_version": 1,
+  "registered_at": "2026-08-18",
+  "owner": "maintainer",
+  "review_by": "2027-08-18",
+  "metric": {
+    "basis": "src/scripts/check_estate_count.ts, using collect() from update_roadmap_progress \u2014 the same parser the dashboard is generated from, imported rather than re-implemented",
+    "active_roadmaps": "non-draft roadmap candidates at the top level of agents/roadmaps/, as collect() counts them. Verified 2026-08-18: this is exactly the number the dashboard header prints as 'N open roadmaps'.",
+    "later_roadmaps": "roadmap-shaped *.md files under agents/roadmaps/later/ \u2014 the same is_roadmap_candidate name filter the active side uses, so later/README.md is not counted. Counted from the filesystem because parked roadmaps sit outside collect()'s corpus by design; they are estate all the same, and a drawdown that moved everything into later/ and called the number down would be the burial T1's quality anchor exists to prevent.",
+    "open_blockers": "open blockers summed over the active tree AND later/. This deliberately does NOT equal the dashboard header's blocker count, which is active-only: counting only the active tree meant PARKING a roadmap dropped this number without resolving anything, and the ratchet then printed 'free tightening' over a burial. AC-1 is phrased on this metric, so it has to survive a move that resolves nothing. archive/ and skipped/ stay out \u2014 those are terminal, and a blocker in a skipped roadmap is not open work.",
+    "not_gated": [
+      "the needs-you subset of open blockers \u2014 it moves when a blocker changes OWNER, which is not estate growth, so gating it would red on a reclassification that changed nothing about the size of the estate",
+      "agents/roadmaps/skipped/ and archive/ \u2014 these are the terminal destinations a drawdown sends files to; gating their growth would penalise the wanted direction",
+      "agents/roadmaps/stubs/ as a COUNT \u2014 a stub is not yet a roadmap, so it is not estate. It IS recognised as an offset destination and as an addition source, because un-stubbing is the documented promotion path and T3 has to be able to charge it."
+    ]
+  },
+  "baseline": {
+    "active_roadmaps": 33,
+    "later_roadmaps": 50,
+    "open_blockers": 70
+  },
+  "baseline_history": [
+    {
+      "at": "2026-08-18",
+      "active_roadmaps": 38,
+      "later_roadmaps": 44,
+      "open_blockers": 49,
+      "why": "registered with the gate, at the measured estate. Note the roadmap's own \u00a7 0 quotes 37 active / 44 later / 38 blockers against a mid-August pin; the estate moved between that draft and this registration, which is the arrival rate T3 exists to bound rather than a correction to the roadmap."
+    },
+    {
+      "at": "2026-08-18",
+      "active_roadmaps": 38,
+      "later_roadmaps": 43,
+      "open_blockers": 67,
+      "why": "Two metrics REDEFINED before the gate ever ran on a second commit, both on R2 findings against this same change, so these are re-measurements rather than raises. later_roadmaps 44 -> 43: the first count included later/README.md, which the active side's own name filter excludes \u2014 an off-by-one that made the baseline describe 43 roadmaps plus a README. open_blockers 49 -> 67: the first count spanned the active tree only, so PARKING a roadmap dropped the gated number without resolving anything and the ratchet printed 'free tightening' over a burial. It now spans active + later/ (49 + 18), which is why the number rose while the estate did not. The cost is stated rather than hidden: this metric no longer equals the dashboard header, and the first version claimed that parity as a virtue."
+    },
+    {
+      "at": "2026-08-18",
+      "active_roadmaps": 38,
+      "later_roadmaps": 43,
+      "open_blockers": 69,
+      "why": "open_blockers 67 -> 69, and this is a correction of a baseline that never described the trunk rather than room made for new growth. 67 was measured at 554b032aa, the commit that registered this gate (PR #1420). PR #1418 merged AFTER it and carried road-to-per-turn-hook-economy from one open blocker to three \u2014 verified by counting that one file at both refs, 1 at 554b032aa and 3 at 851568b5c, which is the entire delta. #1418's own CI ran before the gate existed, so nothing objected at the time and the trunk arrived at 69 with the file still claiming 67. The consequence was not a loose ratchet but a permanently red one: the count half compares the live tree against this baseline irrespective of the diff, so EVERY subsequent PR failed on growth it had not caused, and the first to notice was an evidence-only PR that adds no blocker at all. Raising to the measured trunk value restores the property the gate is for \u2014 it fails on growth from here, and 69 is now the number that must walk down. The two blockers themselves are untouched and remain open work on road-to-per-turn-hook-economy; closing or parking someone else's blockers to buy the old number back would have been a terminal disposition of another session's work, which is exactly what this ratchet must never incentivise."
+    },
+    {
+      "at": "2026-08-18",
+      "active_roadmaps": 38,
+      "later_roadmaps": 43,
+      "open_blockers": 72,
+      "why": "RAISED by 3, on top of the 67 -> 69 correction above rather than beside it. All three are road-to-per-turn-hook-economy Phase 2, and each records a finding that would otherwise rot: b-payload-read-parse-dominates (two independent measurements now say D-2's cost is the dispatcher's own read+parse of the payload, once per event, not the per-concern churn the roadmap blamed \u2014 so the phase's AC is refuted and the null is published), b-payload-mis-nested-readers (two concerns read tool payload keys off the envelope root; one is a security scanner that works only via a whole-envelope fallback, the other returns 0 on every dispatcher-path call today), and b-stop-async-split-prerequisites (step 5.3 deferred, carrying the five prerequisites its classification surfaced). A blocker that puts a maintainer decision in front of the maintainer is the estate growing in the direction this ratchet exists FOR, which is why the raise is taken rather than the findings being dropped into prose where nothing tracks them. My first version of this entry claimed two of five as unattributed drift; the trunk's correction identified the same two and named their cause, so that half is withdrawn rather than restated."
+    },
+    {
+      "at": "2026-08-19",
+      "active_roadmaps": 37,
+      "later_roadmaps": 43,
+      "open_blockers": 71,
+      "why": "LOWERED by 1 on each gated metric, in the direction this ratchet exists for. road-to-stop-gate-honesty reached zero open steps and zero deferred items and was archived, which is a terminal disposition rather than a park; its `b-detector-demotion-bars` was resolved with the decision recorded at the entry, not moved elsewhere. Both numbers are therefore measurements of a smaller estate, not room bought by relocating work \u2014 later_roadmaps is unchanged at 43, which is the check that distinguishes the two. Walked down because the count gate reported both as free tightening and its unit test asserts the committed budget equals the live tree: a baseline left above a lower measurement is headroom a later change can spend without any gate objecting, which is the loose-ratchet failure the 67 -> 69 entry above records from the other direction."
+    },
+    {
+      "at": "2026-08-19",
+      "active_roadmaps": 38,
+      "later_roadmaps": 43,
+      "open_blockers": 72,
+      "why": "RAISED by 1 on active_roadmaps and open_blockers, and the direction is stated plainly because this ratchet exists to make exactly this visible. Both come from one change that routes a MEASURED hook-latency regression to an owner: the blocker b-concern-load-taxes-every-slot on road-to-per-turn-hook-economy, and road-to-slot-scoped-concern-loading for the structural half. The trunk is red on the pre-registered latency gate \u2014 main measured pre_tool_use p50 176 ms against a derivation window of 111-148, a local A/B at the gate own n=50 reproduced +12.6 percent, and the same-run control was flat, so it is cost growth rather than runner spread. The estate grew because the defect had nowhere to live, not because scope was added. NOT offset deliberately: the only offset available here would be archiving an unrelated roadmap to buy room, which bundles an unreviewed disposition into a latency-gate PR. The roadmap carries estate_offset_exempt with that reason and its own Honest null, so it closes on a measurement in Phase 0 if module load turns out to be a minor share \u2014 which is the walk back down this raise is underwritten by. later_roadmaps unchanged at 43, the check that distinguishes a real addition from work relocated into later/."
+    },
+    {
+      "at": "2026-08-19",
+      "active_roadmaps": 37,
+      "later_roadmaps": 43,
+      "open_blockers": 71,
+      "why": "WALKED BACK DOWN, reversing the raise recorded one entry above IN THE SAME PR. That raise was explicitly underwritten by the new roadmap own Honest null \u2014 close on the Phase 0 measurement if the premise does not hold \u2014 and the null fired on the first measurement it took: a bundle carrying only the 11 pre_tool_use concerns loads in 24 ms against the full 45-concern bundle at 23 ms, so slot-scoping the dispatcher would have bought minus one millisecond. The bundle is dominated by its shared dependency graph, not by per-concern code. road-to-slot-scoped-concern-loading is therefore archived with that result published rather than left open, and b-concern-load-taxes-every-slot is resolved because the real cause was found and fixed in the same change: dispatch_hook parsed the 61 kB YAML manifest on every dispatch (8 ms module load plus 12 ms parse) and now reads a precompiled 14.7 kB JSON sibling, taking pre_tool_use p50 from 103 ms to 81 ms. Both numbers are measurements of a smaller estate, not room bought by relocating work \u2014 later_roadmaps is unchanged at 43, which is the check that distinguishes the two."
+    },
+    {
+      "at": "2026-08-19",
+      "active_roadmaps": 39,
+      "later_roadmaps": 43,
+      "open_blockers": 72,
+      "why": "RAISED by 2 active and 1 blocker ON TOP of the same-day lowering recorded directly above, for the two roadmaps the long-horizon branch installed from an inbox handover and then executed in the same PR. The arithmetic is stated because the first version of this entry got it wrong: it read 38 -> 40 and 72 -> 73 against the pre-merge trunk, and `origin/main` had meanwhile MEASURED 37 and 71 by archiving road-to-stop-gate-honesty and resolving its blocker. Carrying 40/73 through the merge would have silently pocketed that branch\u2019s drawdown as headroom, which is the loose-ratchet failure the 67 -> 69 entry records from the other direction. 37 + 2 and 71 + 1 is the honest merged value. Both roadmaps carry an `estate_offset_exempt` line, so the one-in-one-out check passes on its own terms; what still fires is the raw COUNT half, which is diff-blind by design. The honest shape of the raise: road-to-council-api-fallback arrives at 16 of 17 steps done and would have ARCHIVED in this PR \u2014 that archive is the offset the check wanted. It does not archive, because Iron Law 3 refuses a silent archive while a `[~]` item is unresolved and that resolution belongs to the user, so this is a raise one user decision turns back into 38. road-to-long-horizon-execution stays open on an OBSERVATION of a live killed-and-resumed run: not work any change-set can contain, and not something to buy back by archiving an unrelated roadmap, which would move the number without moving the estate. The +1 blocker is `team-loop-benchmark-spend`, which puts a funded-or-published-null decision in front of the maintainer \u2014 the direction this ratchet exists FOR."
+    },
+    {
+      "at": "2026-08-19",
+      "active_roadmaps": 36,
+      "later_roadmaps": 49,
+      "open_blockers": 73,
+      "why": "road-to-estate-drawdown Phase 2 triage batch 1 \u2014 the first batch of the sweep this ratchet was registered to make stick. RE-APPENDED a SECOND time, after a second merge of origin/main, and every number below is re-measured on the merged tree rather than carried over from either previous reading. The trunk moved twice under this branch: first PR #1429 (a raise to 38/43/72 then its own walk back down to 37/43/71), then the long-horizon branch installing two roadmaps (37 -> 39 active, 71 -> 72 blockers). Both of those entries stand above this one in trunk order; this entry states only what THIS branch does to the numbers they left. Six of the ten files in the batch took the verdict PARK-PROBEABLE and moved to later/ with a rewritten resume condition. active_roadmaps 39 -> 36 is WALKED DOWN, and the delta is three rather than six because three of the six carried `status: draft` and were never in collect()'s corpus to begin with \u2014 the same asymmetry that explains the blocker delta below. later_roadmaps 43 -> 49 is RAISED by all six, because every parked file is counted there whatever its status was. The raise is exactly the move this metric exists to make visible: parking is not closing, and a drawdown that moved everything into later/ and called the number down is the burial T1's quality anchor forbids. It is taken rather than avoided because all six are the later/ definition verbatim \u2014 open work that cannot proceed now, gated on an external trigger, not abandoned \u2014 and every one keeps its open-step count plus a resume condition a script or a named command can test. ONE of the six is decidable by resume_probe and reports `unmet` (domain-pack-extraction-when-triggered); the other five are recorded with a per-row reason in agents/decisions/estate-triage-dispositions.yml, because their conditions name an external fact, a content bar, or a host capability rather than a file's existence. It was two until the R2 round showed the second was decidable only through a field-split bypass, and removing that bypass took the count down \u2014 a probe that decides fewer notes honestly is worth more than one that decides more by an authoring trick. open_blockers 72 -> 73 is +1 with one cause, stated because it looks like drift and is not: road-to-product-bets carried `status: draft`, so collect() excluded it and its one blocker was invisible to this metric; parking it into later/ brought that blocker into the counted corpus. No blocker was opened, closed or moved \u2014 a draft's blocker became countable. Nothing in this batch was archived, so no closure needed a migration note; the two DECISION-SHEET verdicts route to the existing consolidated sheet and the two EXECUTE verdicts leave their files in the active tree."
+    },
+    {
+      "at": "2026-08-19",
+      "active_roadmaps": 34,
+      "later_roadmaps": 50,
+      "open_blockers": 73,
+      "why": "The two Iron-Law-3 holdouts resolved on a converged AI-council verdict \u2014 anthropic + openai, 2 of 2 present, one round, 2026-08-19 \u2014 and both roadmaps archived. active_roadmaps 36 -> 34 is WALKED DOWN by exactly those two archivals; later_roadmaps 49 -> 50 is RAISED by one, the follow-up carrier the council required for the second of them. open_blockers is UNCHANGED at 73, which is the check that says nothing was bought by relocating an open decision: both archived files carried only resolved blockers, and the new carrier carries none. The two cases were not the same case, and the council said so on both. road-to-inbox-harvest-2026-08-d-top-band-model-economy's holdout was an acceptance CRITERION that is unsatisfiable as written and contradicted in that form by ADR-035; both seats returned archive-with-no-follow-up, because a contradictory criterion is a specification defect rather than future work and a roadmap spawned from it could never close. They split on the glyph and `[-]` won on the sharper argument, verified against the tree before adoption: `[x]` would assert 'no .md names a vendor model', and 160 .md files do. road-to-council-api-fallback's holdout was a real proposal gated on an operational trigger, so it moved to a carrier rather than being archived with it \u2014 later/road-to-council-api-quota-source-split.md, with the step migrated verbatim including its 'do not build ahead of that evidence' instruction. Both seats independently REFUSED that roadmap's claim about itself that its deferral 'does not gate archival': a roadmap does not get to exempt itself from a repository-wide preservation rule, or the gate becomes discretionary exactly where it is structural. The claim is left standing in the archived file rather than deleted, because the claim is the finding. The carrier's resume condition is an existence predicate over a named evidence file, which resume_probe decides \u2014 chosen over the other seat's `gh issue list` probe because the tree has a probe for one and not the other, and both seats named parked-roadmap clutter as the failure mode of a follow-up whose trigger nothing can observe."
+    },
+    {
+      "at": "2026-08-19",
+      "active_roadmaps": 33,
+      "later_roadmaps": 50,
+      "open_blockers": 71,
+      "why": "WALKED DOWN by 1 active and 2 blockers: road-to-inbox-harvest-residuals reached a terminal state and archived. Its last two open items, R1 and R2, were both blocked on a call rather than on effort, and both are now `[-]` against named locks \u2014 one of the three terminal states that roadmap's own Exit clause allows. later_roadmaps is UNCHANGED at 50, which is the check that says this is a closure and not a park: nothing was relocated to buy the number. The two blockers resolved are the roadmap's own, each on the option the blocker itself recommended \u2014 deferred-finding-decision-reopen on (b), cancel R2 against the in-source decline; spent-inbox-artifacts-await-deletion on (c), keep-reason recorded, the branch that deletes nothing. Neither was closed to make room: the AI council was polled first on whether an agent may record a disposition against a blocker whose declared Owner is the maintainer, and both seats converged that observing a named trigger did NOT fire closes the loop while the reserved call is whether to REOPEN \u2014 which is exactly what was not done. R2's trigger was probed rather than assumed (`check_review_dispositions`: 17 archived records, all terminal, zero findings, which is the trigger's negation), and R1's cancellation had to be RE-GROUNDED because the lock the step cited says the opposite of what the step claimed: \u00a7 2.7 of plan-review-gates.md opens with 'never an edit ban on the live artefact', and that same file already carried the refutation of the broader reading in writing. The lock that does hold is narrower \u2014 \u00a7 2.7 freezes only the 16 superseded round-review records, and the contract declined a corpus-migration event for this class when it made its v1 fields optional. A cancellation resting on a lock the cited contract denies would have been a burial wearing a citation, which is the failure this ratchet's own history keeps recording from the count side."
+    },
+    {
+      "at": "2026-08-19",
+      "active_roadmaps": 33,
+      "later_roadmaps": 50,
+      "open_blockers": 70,
+      "why": "WALKED DOWN by 1 blocker: worktree-claim-root-split resolved in the change that found it. The blocker recorded a measured defect \u2014 the roadmap claim and the stop-slot concern resolved different roots, so run-continuation was inert in every worktree session \u2014 and the claim now lives in the git common dir beside the session register. Active and later are unchanged and net zero by construction: road-to-long-horizon-execution archived and road-to-run-continuation-observation was created in the same change to carry its last deferred criterion, per the preservation test the same change added to roadmap-progress-sync. Walked here rather than banked because the gate reported the slack itself, and a baseline above the measurement is headroom a later change spends with nothing objecting."
+    }
+  ],
+  "target": {
+    "_comment": "T1's proposed ceilings, kept as the destination. PROPOSALS, NOT REGISTERED: the roadmap says in as many words that both numbers and the window belong to the maintainer, and no date is pinned in this file. Nothing reads these values \u2014 `one_in_one_out.applies_above_active` is the only threshold the gate evaluates.",
+    "active_roadmaps": 15,
+    "open_blockers": 12,
+    "window": "roughly six weeks from campaign start (drafted; unregistered)"
+  },
+  "one_in_one_out": {
+    "_comment": "T3. `applies_above_active: null` means UNCONDITIONAL. T3 phrases the condition as 'while the active count sits above target', and T1 says the target belongs to the maintainer \u2014 so rather than inventing a ceiling so the condition could be evaluated, null states that no ceiling is registered and the lint therefore applies. Registering a number here is how it gets a threshold; registering one above the live count is how it is turned off.",
+    "applies_above_active": null,
+    "exemption": "estate_offset_exempt: <reason> in the added roadmap's own frontmatter. The key lives in the file rather than in this config for the reason RATCHET_RESET_KEY gives for living inside its baseline JSON: the claim shows up in the diff of the change that makes it."
+  }
+}

package/src/config/evaluator-budgets.json

@@ -58,11 +58,11 @@
       "deterministic": false
     },
     "cli_help_command_count": {
-      "max": 99,
-      "last_measured": 99,
-      "last_measured_at": "2026-08-17",
+      "max": 101,
+      "last_measured": 101,
+      "last_measured_at": "2026-08-19",
       "method": "registry enumeration — count of `{ name: '...', disposition` entries in src/cli/registry.ts (NOT --help prose parsing; methods historically disagreed 74 vs 76 vs 79)",
-      "baseline_note": "80 → 81 on 2026-08-03 (release 9.15.0 gate). This RECORDS growth that already shipped through its own reviewed PR; it does not authorize new surface. The +1 is f02db54c2 (fix(cli): register routing:doctor in the CLI registry) — the command existed, only its registry entry was missing, and the registering PR did not move this budget. The gate did its job again: breach WARNS on main and BLOCKS on release, which is the conscious-decision point rather than a silently raised cap. Re-measured 2026-08-03 via the pinned method: 81. Headroom stays zero by design — the next registry addition must move this number in its own PR. 81 → 82 on 2026-08-04: the `handoff` subcommand (road-to-agent-handoff-resume Phase 4) registers in the same PR that adds the surface, per this record's own contract. Re-measured via the pinned method: 82. 82 → 84 on 2026-08-04: the `route:explain` + `route:audit` verbs (routing-correctness validation surface) register in the same PR that adds the surface. Re-measured via the pinned method: 84. 84 → 85 on 2026-08-05: the `settings:set` verb (road-to-zero-ceremony-settings Phase 2 — the one agent-reachable settings writer) registers in the same PR that adds the surface, per this record's own contract. Re-measured via the pinned method: 85. 85 → 86 on 2026-08-06: the `conformance:behavior` verb (road-to-agent-behavior-conformance Phase 5 — replays the local transcript store through the four mechanised conformance checks) registers in the same PR that adds the surface, per this record's own contract. Re-measured via the pinned method: 86. 86 → 88 on 2026-08-07: the `sessions:list` + `sessions:claim` verbs (road-to-parallel-session-coordination — the shell surface of the shared session register, needed because /roadmap:next is command markdown and can only reach the register through a shell call) register in the same PR that adds the surface, per this record's own contract. Re-measured via the pinned method: 88. 88 → 89 on 2026-08-08: the `council:status` verb registers in the same PR that adds the surface, per this record's own contract. It exists because an agent in a consumer project announced \"kein Council konfiguriert (keine .agent-settings.yml)\" and substituted a weaker path while the council was configured user-globally the whole time — there was no verb that answered availability, so the only route was an inference from a filename, and the intuitive filename is the one location ADR-104 guarantees is never consulted. Re-measured via the pinned method: 89. 89 → 91 on 2026-08-08: the `self-repair:status` + `self-repair:release` verbs (the queued-defect reader and the single Hard-Floor-gated outward step of the self-repair loop — the loop is deliberately unable to publish unless a human runs the release command) register in the same PR that adds the surface, per this record's own contract. Landed alongside the +1 council:status move in the same branch. Re-measured via the pinned method: 91. 91 → 94 on 2026-08-08: the `packs:active`, `settings:get` and `mcp:available` verbs (road-to-capability-answerability Phase 2 — the three capability probes for the gaps that had none) register in the same PR that adds the surface, per this record's own contract. Each answers a question that was previously only inferable from a filename: which packs are active and from which file, what a setting resolves to and which file set it, and what is declared in mcp.json versus what can actually launch. 94 -> 95 in the same PR: `brand:status` (Phase 2.4 — brand-layer presence, which the rule depended on and no surface could answer). Re-measured twice via the pinned method on the unchanged tree: 95/95. 95 → 96 on 2026-08-10: the `session:recycle` verb (road-to-token-economy-recycling Phase 2.2 — the deterministic producer of the main-session recycle envelope; the recycle advisory names this exact verb, so it must exist as a shell surface) registers in the same PR that adds the surface, per this record's own contract. Re-measured via the pinned method: 96. 96 -> 97 on 2026-08-10: the `gates` verb registers in the same PR that adds the surface, per this record's own contract. It exists because the blocker fields the dashboard already parses (Owner, What to do, Resolved when — CI-enforced by lint_roadmap_blockers) had no owner-filtered reader: the dashboard counts the open blockers across a 600-line file and links each to a per-roadmap anchor, so \"which of these are mine\" was a manual read of every anchor. The same inference-from-a-filename shape as the council:status entry above, one layer up. This branch and the session:recycle branch each measured 96 independently and landed on the same number for different verbs; the merge makes it 97, re-measured twice via the pinned method on the merged tree: 97/97. 97 -> 98 on 2026-08-15: the `workspace:doctor` verb (road-to-inbox-harvest-2026-08-c-workspace-identity Phase 3 — the read-only report over the new `workspaceIdentity()` resolver) registers in the same PR that adds the surface, per this record's own contract. It exists for the same inference-from-a-filename shape as the council:status and gates entries above, one layer down: the tree answered \"where am I\" in eight ad-hoc places across six files, and the 12.0.0 span shipped the same worktree misclassification twice, so no verb could be asked which checkout is the main one. Read-only by construction — the roadmap's Non-goals put worktree disposal out of scope and its Risk 3 names \"the pressure read becomes a disposal path by accident\" as the failure to design against, so the command carries no --fix and no --prune. Re-measured twice via the pinned method on the unchanged tree: 98/98. 98 -> 99 on 2026-08-17: the `council:quota` verb (road-to-council-quota-accounting-truth Phase 2) registers in the same PR that adds the surface, per this record's own contract. Exactly the inference-from-a-filename shape as the council:status entry above, one layer down: `cmd_quota` had existed in council_cli.ts and been reachable only via `scripts-run`, so the documented recovery path for an exhausted shared counter -- read the usage, reset one provider -- did not resolve through `agent-config`, and an operator debugging a quota failure met `unknown command`. The verb is read-only apart from the pre-existing `--reset <provider>`, which already required `--confirm`. Re-measured twice via the pinned method on the unchanged tree: 99/99."
+      "baseline_note": "80 → 81 on 2026-08-03 (release 9.15.0 gate). This RECORDS growth that already shipped through its own reviewed PR; it does not authorize new surface. The +1 is f02db54c2 (fix(cli): register routing:doctor in the CLI registry) — the command existed, only its registry entry was missing, and the registering PR did not move this budget. The gate did its job again: breach WARNS on main and BLOCKS on release, which is the conscious-decision point rather than a silently raised cap. Re-measured 2026-08-03 via the pinned method: 81. Headroom stays zero by design — the next registry addition must move this number in its own PR. 81 → 82 on 2026-08-04: the `handoff` subcommand (road-to-agent-handoff-resume Phase 4) registers in the same PR that adds the surface, per this record's own contract. Re-measured via the pinned method: 82. 82 → 84 on 2026-08-04: the `route:explain` + `route:audit` verbs (routing-correctness validation surface) register in the same PR that adds the surface. Re-measured via the pinned method: 84. 84 → 85 on 2026-08-05: the `settings:set` verb (road-to-zero-ceremony-settings Phase 2 — the one agent-reachable settings writer) registers in the same PR that adds the surface, per this record's own contract. Re-measured via the pinned method: 85. 85 → 86 on 2026-08-06: the `conformance:behavior` verb (road-to-agent-behavior-conformance Phase 5 — replays the local transcript store through the four mechanised conformance checks) registers in the same PR that adds the surface, per this record's own contract. Re-measured via the pinned method: 86. 86 → 88 on 2026-08-07: the `sessions:list` + `sessions:claim` verbs (road-to-parallel-session-coordination — the shell surface of the shared session register, needed because /roadmap:next is command markdown and can only reach the register through a shell call) register in the same PR that adds the surface, per this record's own contract. Re-measured via the pinned method: 88. 88 → 89 on 2026-08-08: the `council:status` verb registers in the same PR that adds the surface, per this record's own contract. It exists because an agent in a consumer project announced \"kein Council konfiguriert (keine .agent-settings.yml)\" and substituted a weaker path while the council was configured user-globally the whole time — there was no verb that answered availability, so the only route was an inference from a filename, and the intuitive filename is the one location ADR-104 guarantees is never consulted. Re-measured via the pinned method: 89. 89 → 91 on 2026-08-08: the `self-repair:status` + `self-repair:release` verbs (the queued-defect reader and the single Hard-Floor-gated outward step of the self-repair loop — the loop is deliberately unable to publish unless a human runs the release command) register in the same PR that adds the surface, per this record's own contract. Landed alongside the +1 council:status move in the same branch. Re-measured via the pinned method: 91. 91 → 94 on 2026-08-08: the `packs:active`, `settings:get` and `mcp:available` verbs (road-to-capability-answerability Phase 2 — the three capability probes for the gaps that had none) register in the same PR that adds the surface, per this record's own contract. Each answers a question that was previously only inferable from a filename: which packs are active and from which file, what a setting resolves to and which file set it, and what is declared in mcp.json versus what can actually launch. 94 -> 95 in the same PR: `brand:status` (Phase 2.4 — brand-layer presence, which the rule depended on and no surface could answer). Re-measured twice via the pinned method on the unchanged tree: 95/95. 95 → 96 on 2026-08-10: the `session:recycle` verb (road-to-token-economy-recycling Phase 2.2 — the deterministic producer of the main-session recycle envelope; the recycle advisory names this exact verb, so it must exist as a shell surface) registers in the same PR that adds the surface, per this record's own contract. Re-measured via the pinned method: 96. 96 -> 97 on 2026-08-10: the `gates` verb registers in the same PR that adds the surface, per this record's own contract. It exists because the blocker fields the dashboard already parses (Owner, What to do, Resolved when — CI-enforced by lint_roadmap_blockers) had no owner-filtered reader: the dashboard counts the open blockers across a 600-line file and links each to a per-roadmap anchor, so \"which of these are mine\" was a manual read of every anchor. The same inference-from-a-filename shape as the council:status entry above, one layer up. This branch and the session:recycle branch each measured 96 independently and landed on the same number for different verbs; the merge makes it 97, re-measured twice via the pinned method on the merged tree: 97/97. 97 -> 98 on 2026-08-15: the `workspace:doctor` verb (road-to-inbox-harvest-2026-08-c-workspace-identity Phase 3 — the read-only report over the new `workspaceIdentity()` resolver) registers in the same PR that adds the surface, per this record's own contract. It exists for the same inference-from-a-filename shape as the council:status and gates entries above, one layer down: the tree answered \"where am I\" in eight ad-hoc places across six files, and the 12.0.0 span shipped the same worktree misclassification twice, so no verb could be asked which checkout is the main one. Read-only by construction — the roadmap's Non-goals put worktree disposal out of scope and its Risk 3 names \"the pressure read becomes a disposal path by accident\" as the failure to design against, so the command carries no --fix and no --prune. Re-measured twice via the pinned method on the unchanged tree: 98/98. 98 -> 99 on 2026-08-17: the `council:quota` verb (road-to-council-quota-accounting-truth Phase 2) registers in the same PR that adds the surface, per this record's own contract. Exactly the inference-from-a-filename shape as the council:status entry above, one layer down: `cmd_quota` had existed in council_cli.ts and been reachable only via `scripts-run`, so the documented recovery path for an exhausted shared counter -- read the usage, reset one provider -- did not resolve through `agent-config`, and an operator debugging a quota failure met `unknown command`. The verb is read-only apart from the pre-existing `--reset <provider>`, which already required `--confirm`. Re-measured twice via the pinned method on the unchanged tree: 99/99. 99 -> 100 on 2026-08-19: the `decision:memo` verb (road-to-long-horizon-execution Phase 2.2, sequencing UOTL Phase 4.3 -- the decision-memo channel) registers in the same PR that adds the surface, per this record's own contract. It exists because the question ladder gained a rung between \"halt and ask\" and \"decide silently\": a resolution the run makes without contacting the operator is only legitimate if it is reviewable afterwards, and there was no surface that wrote such a record with a fixed shape. Write-and-list only, local-only (agents/runtime/ is gitignored), and it gates nothing -- the locked decision classes are refused at the config schema, never in the ledger. 100 -> 101 in the same PR: `run:supervise` (Phase 3.1 -- the out-of-process watcher for runs whose session died with open steps left). It is the operator-facing half of session continuity: nothing anywhere had the job of noticing that a claimed run stopped moving, so a roadmap 40% done and a roadmap finished looked identical from outside the dead session. Report-only by default and it NEVER merges, pushes or closes -- the auto-merge the reference design carries is a named rejection in the roadmap's harvest section, not an unbuilt feature. Re-measured twice via the pinned method on the unchanged tree: 101/101."
     },
     "mcp_public_tool_count": {
       "max": 20,

package/src/config/gate-coverage.yml

@@ -40,12 +40,12 @@
 #                visible, or it repeats the sin it exists to catch.
 #   canary       optional mutation recipe (Phase 7) — see CANARY below
 #
-# COVERAGE — THE HONEST DENOMINATOR (re-measured 2026-08-17)
+# COVERAGE — THE HONEST DENOMINATOR (re-measured 2026-08-18)
 # ----------------------------------------------------------
-# 266 `lint_*` / `check_*` / `audit_*` scripts live under `src/scripts/`
+# 267 `lint_*` / `check_*` / `audit_*` scripts live under `src/scripts/`
 # (the count is computed, not asserted — `check_gate_coverage.count_gate_scripts`).
-# **41 of them emit the machine-readable `scanned: <N>` line under their
-# CI-identical argv, and 40 of those 41 are listed below.** The manifest is
+# **42 of them emit the machine-readable `scanned: <N>` line under their
+# CI-identical argv, and 41 of those 42 are listed below.** The manifest is
 # therefore complete with respect to its own contract for every gate that can
 # carry a floor, and covers ~15 % of the population.
 #
@@ -564,6 +564,34 @@ gates:
       reported, never silently skipped, so a collapse below the floor means
       the roadmaps root moved, not that the corpus went clean.
 
+  - id: check_estate_count
+    argv: []
+    min_scanned: 20
+    corpus: "active + parked roadmap files (81 at baseline: 38 active, 43 in later/)"
+    status: enforced
+    canary:
+      class: contract-violation
+      path: "agents/roadmaps/road-to-canary-estate-count.md"
+      content: |
+        # Roadmap: canary
+
+        ## Phase 1
+
+        - [ ] **1.1** a step
+    note: >
+      road-to-estate-drawdown T2. Two halves, one floor: the count half walks the
+      committed baseline DOWN only and always has a corpus, so it can carry a
+      floor; the one-in-one-out half (T3) is diff-scoped and legitimately weighs
+      nothing on a branch that adds no roadmap, which is why the floor counts
+      roadmap FILES rather than diff entries.
+      The floor is 20 rather than something near today's 81 because THIS gate's
+      corpus is the thing it exists to shrink: T1's proposed ceiling is 15 active,
+      and a successful campaign would land near 15 + a drained `later/` — a floor
+      of 50 would have failed on the day the drawdown worked, which is the exact
+      failure this file's own § 3 warns about, pointed the wrong way. 20 still
+      cannot survive a collapse: at that point the gate's own `reportScanned`
+      fires first. (Set to 50 in the first version, corrected on an R2 finding.)
+
   - id: check_completion_review
     argv: ["--advisory", "--base", "origin/main"]
     min_scanned: 1