@event4u/agent-config 14.6.0 → 14.8.0

package/src/scripts/skill_usage_report.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 /**
- * Aggregate `agents/runtime/metrics/skill-usage.jsonl` into a per-skill report.
+ * Aggregate `agents/runtime/metrics/skill-usage.jsonl` into a per-skill report,
+ * plus a second section over the Class-A sink export when one is present.
  *
  * Ported from the retired Python `src/scripts/skill_usage_report.py` (ADR-200,
  * Phase 8 / Wave 8b). The public surface, CLI contract, exit code,
@@ -19,13 +20,47 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
+// The "existing threshold constant" the step names — the distinct-user bar the
+// tier-usage re-tier already ships. Imported rather than restated so the sink
+// section and the re-tier decision cannot drift to two different numbers.
+import { DEFAULT_TIER_USAGE_RETIER } from '../agent-src/templates/scripts/telemetry/settings.js';
 
 const _HERE = path.dirname(fileURLToPath(import.meta.url));
 // parent.parent.parent of the .py file (src/scripts/skill_usage_report.py)
 // is the repo root — two dirs up from src/scripts.
 const REPO = path.resolve(_HERE, '..', '..');
-const IN = path.join(REPO, 'agents', 'metrics', 'skill-usage.jsonl');
-const OUT = path.join(REPO, 'agents', 'metrics', 'skill-usage-report.md');
+// Both of these pointed into `agents/metrics/`, a directory the agents/
+// taxonomy consolidation retired — so the report read a file that does not
+// exist and wrote beside it, while the real record set sat at
+// `agents/runtime/metrics/` and the tracked report at
+// `agents/evidence/metrics/`. road-to-org-telemetry Phase 0 named this repair
+// a Phase 4 prerequisite: adding the sink as a SECOND source lands beside a
+// first source that reads nothing. Destinations follow the agents/ layout
+// contract, and both match what `taskfiles/ci-fast.yml`'s own task
+// descriptions already claimed this script does.
+//
+// OUT IS THE RUNTIME COPY, NOT THE TRACKED ONE, AND THAT IS DELIBERATE. The
+// tracked `agents/evidence/metrics/skill-usage-report.md` is a promoted
+// baseline snapshot the roadmap cites by its numbers. Pointing OUT at it makes
+// every run in a checkout WITHOUT the gitignored record set overwrite that
+// baseline with zeros — measured while writing this change: 297 insertions /
+// 339 deletions, every row reclassified `dead`, from a worktree where the
+// JSONL simply does not exist. A measurement that corrupts its own baseline is
+// worse than no measurement. Promotion to `evidence/` stays a deliberate copy.
+const IN = path.join(REPO, 'agents', 'runtime', 'metrics', 'skill-usage.jsonl');
+const OUT = path.join(REPO, 'agents', 'runtime', 'metrics', 'skill-usage-report.md');
+
+/**
+ * The sink export — the SECOND source (Phase 4, step 4.1).
+ *
+ * Class-A records as JSONL, either an export of the org sink or one install's
+ * own local `.agent-telemetry.jsonl`. Default-absent is the normal state and
+ * is reported as such: `sink-choice` is transferred, so no sink exists for
+ * this repository to read, and a section that silently rendered nothing would
+ * be indistinguishable from a sink that answered zero — which is the exact
+ * blind-zero confusion this roadmap exists to remove.
+ */
+const SINK_IN = path.join(REPO, 'agents', 'runtime', 'metrics', 'telemetry-class-a.jsonl');
 
 interface Bucket {
     exposures_total: number;
@@ -197,7 +232,214 @@ function _dateIso(d: Date): string {
     return `${d.getUTCFullYear()}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())}`;
 }
 
-export function render(per: Map<string, Bucket>, known: Set<string>): string {
+// ── The sink as a second source (Phase 4, step 4.1) ────────────────────────
+//
+// WHY THIS IS A SEPARATE SECTION AND NOT EXTRA COLUMNS. The two sources do not
+// measure the same thing and cannot share a row. The first source is a regex
+// scan of the maintainer's own transcripts, so it counts *exposure* and
+// *mention* on one machine; Phase 0's third spike measured it detecting **0 of
+// 89** real invocations on the set it reads. The sink counts *invocations* with
+// a pseudonymous user per record, across every consenting install. Merging them
+// into one table would produce a row whose numbers come from different
+// populations, which is exactly the kind of arithmetic the zero-activation
+// reading already taught this repository not to trust.
+//
+// DISTINCT USERS ARE THE POINT. A per-skill invocation count from one heavy
+// user is not adoption. `user_hash` is a salted digest of host + login, so it
+// distinguishes people without naming them, and the threshold below is the bar
+// the tier-usage re-tier already uses.
+
+/** One Class-A usage record, as the emitter writes it. */
+interface ClassALine {
+    skill: string;
+    user_hash: string;
+    session_hash: string | null;
+    host: string | null;
+    ts_bucket: string;
+    record_class: string;
+}
+
+export interface SinkBucket {
+    invocations_total: number;
+    invocations_window: number;
+    users_window: Set<string>;
+    sessions_window: Set<string>;
+    hosts: Set<string>;
+    last_seen: Date | null;
+}
+
+/**
+ * Parse an hour bucket (`2026-08-20T10:00Z`).
+ *
+ * Its own parser rather than `parse_ts`: the first source carries a full ISO
+ * timestamp and the sink deliberately carries hour resolution only, so one
+ * parser over both would quietly accept a precision neither guarantees.
+ */
+export function parse_hour_bucket(raw: unknown): Date | null {
+    if (typeof raw !== 'string' || !/^\d{4}-\d{2}-\d{2}T\d{2}:00Z$/u.test(raw)) {
+        return null;
+    }
+    const d = new Date(raw);
+    return Number.isNaN(d.getTime()) ? null : d;
+}
+
+/** Load Class-A records. A missing sink export is a normal state, not an error. */
+export function load_class_a(p: string): ClassALine[] {
+    let text = '';
+    try {
+        text = fs.readFileSync(p, 'utf-8');
+    } catch {
+        return [];
+    }
+    const out: ClassALine[] = [];
+    for (const line of text.split('\n')) {
+        if (!line.trim()) continue;
+        try {
+            const rec = JSON.parse(line) as Record<string, unknown>;
+            const skill = rec['skill'];
+            const user_hash = rec['user_hash'];
+            const ts_bucket = rec['ts_bucket'];
+            // A record missing any of the three fields the aggregate is built
+            // from is dropped rather than counted with a substitute: a
+            // fabricated user or a fabricated hour both inflate the very
+            // numbers an estate decision would cite.
+            if (typeof skill !== 'string' || typeof user_hash !== 'string') continue;
+            if (typeof ts_bucket !== 'string') continue;
+            out.push({
+                skill,
+                user_hash,
+                session_hash: typeof rec['session_hash'] === 'string' ? rec['session_hash'] : null,
+                host: typeof rec['host'] === 'string' ? rec['host'] : null,
+                ts_bucket,
+                record_class: typeof rec['record_class'] === 'string' ? rec['record_class'] : '',
+            });
+        } catch {
+            // Same tolerance as the first source: a truncated tail line does
+            // not discard the file.
+        }
+    }
+    return out;
+}
+
+export function aggregate_sink(
+    records: readonly ClassALine[],
+    now: Date,
+    window_days: number,
+): Map<string, SinkBucket> {
+    const cutoff = now.getTime() - window_days * 86400_000;
+    const per = new Map<string, SinkBucket>();
+    for (const r of records) {
+        // Only usage records feed a usage report. Phase 5 adds a self-repair
+        // class to the same schema, and counting those as invocations would
+        // read defect reports as adoption.
+        if (r.record_class !== 'usage') continue;
+        const ts = parse_hour_bucket(r.ts_bucket);
+        if (ts === null) continue;
+        let b = per.get(r.skill);
+        if (b === undefined) {
+            b = {
+                invocations_total: 0,
+                invocations_window: 0,
+                users_window: new Set<string>(),
+                sessions_window: new Set<string>(),
+                hosts: new Set<string>(),
+                last_seen: null,
+            };
+            per.set(r.skill, b);
+        }
+        b.invocations_total += 1;
+        if (r.host !== null) b.hosts.add(r.host);
+        if (b.last_seen === null || ts.getTime() > b.last_seen.getTime()) b.last_seen = ts;
+        if (ts.getTime() >= cutoff) {
+            b.invocations_window += 1;
+            b.users_window.add(r.user_hash);
+            if (r.session_hash !== null) b.sessions_window.add(r.session_hash);
+        }
+    }
+    return per;
+}
+
+/** The distinct-user bar, from the constant the re-tier already ships. */
+export const MIN_DISTINCT_USERS = DEFAULT_TIER_USAGE_RETIER.min_distinct_users;
+
+/**
+ * Render the sink section.
+ *
+ * An ABSENT or EMPTY sink renders a paragraph saying so, naming the path and
+ * the reason. That is the load-bearing case today: `sink-choice` is
+ * transferred, so no sink exists for this repository to read. A section that
+ * rendered nothing would leave a reader unable to tell "no sink" from "a sink
+ * that answered zero" — the blind-zero confusion this whole roadmap exists to
+ * remove, reproduced one layer up.
+ */
+export function render_sink_section(
+    per: Map<string, SinkBucket>,
+    window_days: number,
+    source_rel: string,
+    present: boolean,
+): string[] {
+    const lines: string[] = ['', '## Second source — org sink (Class-A)', ''];
+    if (!present || per.size === 0) {
+        lines.push(
+            `> **No sink data.** \`${source_rel}\` ` +
+                (present ? 'holds no usage records' : 'does not exist') +
+                '. This is the expected state while the sink itself is transferred ' +
+                '(`sink-choice`, see `agents/roadmaps/stubs/road-to-org-telemetry-sink.md`): ' +
+                'nothing has been stood up for this report to read. Read it as ' +
+                '**no instrument**, never as no adoption — the distinction is the ' +
+                'reason this roadmap exists.',
+        );
+        lines.push('');
+        return lines;
+    }
+
+    const rows = [...per.entries()].sort((a, b) => {
+        const du = b[1].users_window.size - a[1].users_window.size;
+        if (du !== 0) return du;
+        const iv = b[1].invocations_window - a[1].invocations_window;
+        if (iv !== 0) return iv;
+        return pyStrCmp(a[0], b[0]);
+    });
+    const meeting = rows.filter(([, b]) => b.users_window.size >= MIN_DISTINCT_USERS).length;
+    lines.push(
+        `**Window:** ${window_days}-day rolling · **Source:** \`${source_rel}\` · ` +
+            `**Skills with any invocation:** ${rows.length} · ` +
+            `**At or above the ${MIN_DISTINCT_USERS}-distinct-user bar:** ${meeting}`,
+    );
+    lines.push('');
+    lines.push(
+        `| # | slug | invocations_${window_days}d | distinct_users_${window_days}d | ` +
+            `distinct_sessions_${window_days}d | hosts | meets_bar | last_seen |`,
+    );
+    lines.push('|---|---|---|---|---|---|---|---|');
+    let i = 0;
+    for (const [slug, b] of rows) {
+        i += 1;
+        const hosts = [...b.hosts].sort(pyStrCmp).join(', ') || '—';
+        const meets = b.users_window.size >= MIN_DISTINCT_USERS ? 'yes' : 'no';
+        const last = b.last_seen ? _dateIso(b.last_seen) : '—';
+        lines.push(
+            `| ${i} | \`${slug}\` | ${b.invocations_window} | ${b.users_window.size} | ` +
+                `${b.sessions_window.size} | ${hosts} | ${meets} | ${last} |`,
+        );
+    }
+    lines.push('');
+    lines.push(
+        `**Read-out:** \`meets_bar\` is the ${MIN_DISTINCT_USERS}-distinct-user threshold ` +
+            'the tier-usage re-tier already uses; below it, a count is one person\'s habit ' +
+            'rather than adoption. A host with no `Skill` tool emits no records at all, so ' +
+            'a missing host in this table is a missing instrument and not a missing user.',
+    );
+    lines.push('');
+    return lines;
+}
+
+export function render(
+    per: Map<string, Bucket>,
+    known: Set<string>,
+    sink: { per: Map<string, SinkBucket>; source_rel: string; present: boolean } | null = null,
+    window_days = 30,
+): string {
     // sorted(known | set(per))
     const allSlugs = pySortedUnique([...known, ...per.keys()]);
     const rows: ReportRow[] = [];
@@ -227,7 +469,7 @@ export function render(per: Map<string, Bucket>, known: Set<string>): string {
     const lines: string[] = [
         '# Skill Usage Report (baseline)',
         '',
-        '> Generated by `scripts/skill_usage_report.py`. Source:',
+        '> Generated by `src/scripts/skill_usage_report.ts`. Source:',
         '> `agents/runtime/metrics/skill-usage.jsonl` (collector emits per-turn',
         '> exposure/mention records). See',
         '> [`step-2-skill-inventory-rationalization.md`](../roadmaps/step-2-skill-inventory-rationalization.md)',
@@ -257,6 +499,9 @@ export function render(per: Map<string, Bucket>, known: Set<string>): string {
             'structural overlap before any deletion.',
     );
     lines.push('');
+    if (sink !== null) {
+        lines.push(...render_sink_section(sink.per, window_days, sink.source_rel, sink.present));
+    }
     return lines.join('\n');
 }
 
@@ -286,12 +531,14 @@ function _relativeToRepo(p: string): string {
 interface ParsedArgs {
     inp: string;
     out: string;
+    /** The Class-A sink export — the second source. */
+    sink: string;
     window: number;
     quiet: boolean;
 }
 
 export function parse_args(argv: string[]): ParsedArgs {
-    const out: ParsedArgs = { inp: IN, out: OUT, window: 30, quiet: false };
+    const out: ParsedArgs = { inp: IN, out: OUT, sink: SINK_IN, window: 30, quiet: false };
     const fail = (msg: string): never => {
         process.stderr.write(`skill_usage_report: error: ${msg}\n`);
         process.exit(2);
@@ -310,6 +557,12 @@ export function parse_args(argv: string[]): ParsedArgs {
             out.out = path.resolve(v as string);
         } else if (a.startsWith('--out=')) {
             out.out = path.resolve(a.slice('--out='.length));
+        } else if (a === '--sink') {
+            const v = argv[++i];
+            if (v === undefined) fail('argument --sink: expected one argument');
+            out.sink = path.resolve(v as string);
+        } else if (a.startsWith('--sink=')) {
+            out.sink = path.resolve(a.slice('--sink='.length));
         } else if (a === '--window') {
             const v = argv[++i];
             if (v === undefined) fail('argument --window: expected one argument');
@@ -319,7 +572,7 @@ export function parse_args(argv: string[]): ParsedArgs {
         } else if (a === '--quiet') {
             out.quiet = true;
         } else if (a === '-h' || a === '--help') {
-            process.stdout.write('usage: skill_usage_report [-h] [--in INP] [--out OUT] [--window WINDOW] [--quiet]\n');
+            process.stdout.write('usage: skill_usage_report [-h] [--in INP] [--out OUT] [--sink SINK] [--window WINDOW] [--quiet]\n');
             process.exit(0);
         } else {
             fail(`unrecognized arguments: ${a}`);
@@ -353,8 +606,25 @@ export function main(argv?: string[]): number {
         }
         throw exc;
     }
+    // The second source. Absent is the normal state and is rendered as such
+    // rather than omitted — see `render_sink_section`.
+    const sink_present = fs.existsSync(args.sink);
+    const sink_per = aggregate_sink(load_class_a(args.sink), now, args.window);
+    let sink_rel: string;
+    try {
+        sink_rel = _relativeToRepo(args.sink);
+    } catch {
+        // A sink export outside the repo is legitimate (an org may mount one);
+        // the report then names it by basename rather than refusing to render.
+        sink_rel = path.basename(args.sink);
+    }
+
     fs.mkdirSync(path.dirname(args.out), { recursive: true });
-    fs.writeFileSync(args.out, render(per, known), 'utf-8');
+    fs.writeFileSync(
+        args.out,
+        render(per, known, { per: sink_per, source_rel: sink_rel, present: sink_present }, args.window),
+        'utf-8',
+    );
     if (!args.quiet) {
         const count = new Set([...known, ...per.keys()]).size;
         process.stdout.write(`✅  Wrote ${_relativeToRepo(args.out)} (${count} skill(s))\n`);

package/src/scripts/sync_pr_branch.ts

@@ -21,6 +21,11 @@
  * do not hand-merge) versus authored (a human decision). Auto-resolving a
  * content conflict is how a parallel session's work disappears.
  *
+ * Classification changes the ADVICE, not the conflict. A path stays a hotspot by
+ * frequency while becoming mechanical to resolve, so a class added here is never
+ * conflict-count reduction and must not be banked as drawdown (AI council
+ * 2026-08-21, both seats; roadmap road-to-merge-hotspot-drawdown).
+ *
  * Exit codes: 0 = already current, or merged cleanly · 1 = conflict, or the base
  * could not be resolved · 2 = internal error. `scanned:` on every path.
  */
@@ -35,11 +40,78 @@ const NETWORK_TIMEOUT_MS = 8_000;
 
 /** Paths that are GENERATED — a conflict here is regenerated, never hand-merged. */
 const GENERATED = [
+    // Untracked in THIS repository since 2026-08-21 (it was the #1 conflict
+    // path: 830 commits/60d, in the conflict set of every open CONFLICTING PR).
+    // The entry STAYS anyway, and the retirement criterion is a declared window
+    // rather than "one release" — the AI council flagged the release count as
+    // arbitrary and unverifiable. Remove this entry once no open branch predates
+    // the untrack commit, which is checkable:
+    //
+    //   git branch -r --contains <untrack-commit>   # must list every open branch
+    //
+    // Until then a straggler branch created before the untrack still carries the
+    // tracked file, and a conflict on it is still resolved by regeneration.
     'agents/roadmaps-progress.md',
     'agents/index.md',
     'docs/catalog.md',
     'dist/agent-src/',
+    // Written by `src/scripts/adr/regenerate_index.ts`, which takes the decisions
+    // directory as an ARGUMENT — so the path literal appears nowhere in the
+    // generator and every grep-based audit of this list missed it. Found instead
+    // by measurement: 4 of the last 50 sessions resolved a conflict here, and
+    // its only correct resolution is `task regenerate-adr-index`, never a hunk
+    // merge of two append-shaped indexes.
+    'docs/decisions/INDEX.md',
+    // Compiled by `compile_router.ts`. The `dist/agent-src/` prefix above does
+    // NOT match a sibling one level up under `dist/`, so this file was routed to
+    // a human decision despite being pure build output.
+    'dist/router.json',
     '.augment/',
+    // Compiled from `hook_manifest.yaml` by `task build-ts`, never hand-written.
+    // It was classified AUTHORED until 2026-08-20, so this tool told the reader
+    // to "read both sides" on a file where mixing hunks yields a concern table
+    // matching NEITHER branch. One session resolved this same conflict three
+    // times and named it structural: main adds a concern and recompiles, so
+    // every open branch collides here. Regenerate; never merge.
+    'src/scripts/hook_manifest.json',
+    // Written together by one `build_archive_index.ts` call (`:409-410`) from the
+    // archived roadmap tree, so neither is ever hand-authored. They were
+    // classified AUTHORED until 2026-08-21, which made this tool ask for a human
+    // decision about a file whose only correct resolution is regeneration --
+    // the identical defect the hook_manifest.json comment above records, on two
+    // more paths at 47 commits/60d each. They conflict in 2 of the 7 open PRs
+    // measured for road-to-merge-hotspot-drawdown. Regenerate; never merge.
+    'agents/roadmaps/archive/INDEX.md',
+    'agents/roadmaps/archive/index.json',
+];
+
+/**
+ * Paths that are MEASURED BASELINES -- a conflict here is neither regenerated
+ * nor hand-merged. It is RE-MEASURED on the merged tree, and the number that
+ * measurement produces is the resolution.
+ *
+ * Why this is a third class and not a variant of GENERATED: a generated file has
+ * one correct content given the tree, so "regenerate" is a complete instruction.
+ * A ratchet baseline records what a tree MEASURED at a point in time, and two
+ * branches legitimately measured two different trees -- so there is no side to
+ * take and no file to re-render. Picking a side on a ratchet number is how the
+ * ratchet silently loosens, and mixing hunks yields a baseline matching neither
+ * branch.
+ *
+ * Why this tool never performs the re-measurement itself (AI council 2026-08-21,
+ * both seats): "re-measure instead of merge" delegates conflict resolution to a
+ * script and its execution environment, and a wrong or environment-dependent
+ * measurement would overwrite a deliberate tightening with nothing objecting,
+ * 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.
+ */
+const REMEASURED = [
+    'src/config/estate-count-budget.json',
+    'src/config/gate-violation-baselines.json',
 ];
 
 function sh(cmd: string, args: readonly string[], cwd: string): { ok: boolean; out: string; err: string } {
@@ -53,17 +125,59 @@ function sh(cmd: string, args: readonly string[], cwd: string): { ok: boolean; o
 }
 
 /** True when `rel` is a generated artefact rather than an authored one. */
+/**
+ * The subset of GENERATED that this repository no longer commits at all
+ * (`road-to-generated-artifacts-out-of-index`, 2026-08-22). They are still
+ * generated, so they stay in `GENERATED` and keep being reported — a straggler
+ * branch created before the untrack still carries them, which is exactly when
+ * the reader needs to be told something.
+ *
+ * What changes is the INSTRUCTION. A branch that predates the cutover hits a
+ * `modify/delete` conflict here, not a content conflict, and `git checkout
+ * --ours` has no side to check out: the correct resolution is to take the
+ * deletion. Printing the generic advice would send the reader to re-add the
+ * file, which is precisely how PR #1505 put the dashboard back on `main` a day
+ * after it was first untracked.
+ */
+const UNTRACKED_BY_DESIGN: readonly string[] = [
+    'agents/roadmaps-progress.md',
+    'agents/roadmaps/archive/INDEX.md',
+    'agents/roadmaps/archive/index.json',
+];
+
+/** Is this a generated path this repository deliberately does not commit? */
+export function isUntrackedByDesign(rel: string): boolean {
+    return UNTRACKED_BY_DESIGN.includes(rel);
+}
+
 export function isGenerated(rel: string): boolean {
     const norm = rel.replace(/\\/g, '/');
     return GENERATED.some((g) => (g.endsWith('/') ? norm.startsWith(g) : norm === g));
 }
 
+/**
+ * True when `rel` is listed as a measured ratchet baseline.
+ *
+ * This does NOT assert exclusivity against `GENERATED` — it only reads its own
+ * array. `classifyConflicts` establishes the precedence (generated first), so a
+ * path added to both arrays would route as generated while this predicate also
+ * returned true, and no test would catch it. Keep the arrays disjoint; the
+ * per-path exclusivity assertions in the test file cover today's two members
+ * only.
+ */
+export function isRemeasured(rel: string): boolean {
+    const norm = rel.replace(/\\/g, '/');
+    return REMEASURED.some((g) => (g.endsWith('/') ? norm.startsWith(g) : norm === g));
+}
+
 export interface Plan {
     /** 0 = nothing to do or merged · 1 = needs a human · 2 = internal. */
     exit: 0 | 1 | 2;
     message: string;
     /** Conflicted paths, split so the caller knows which to regenerate. */
     generated: string[];
+    /** Conflicted measured baselines — re-measure on the merged tree, never merge. */
+    remeasured: string[];
     authored: string[];
     scanned: number;
 }
@@ -75,14 +189,57 @@ export interface Plan {
  * the split is the useful part: a generated conflict has one correct resolution
  * (regenerate) and an authored one has none that a script may choose.
  */
-export function classifyConflicts(files: readonly string[]): Pick<Plan, 'generated' | 'authored'> {
+export function classifyConflicts(files: readonly string[]): Pick<Plan, 'generated' | 'remeasured' | 'authored'> {
     const generated: string[] = [];
+    const remeasured: string[] = [];
     const authored: string[] = [];
     for (const f of files) {
-        if (f.trim() === '') continue;
-        (isGenerated(f.trim()) ? generated : authored).push(f.trim());
+        const rel = f.trim();
+        if (rel === '') continue;
+        if (isGenerated(rel)) generated.push(rel);
+        else if (isRemeasured(rel)) remeasured.push(rel);
+        else authored.push(rel);
     }
-    return { generated, authored };
+    return { generated, remeasured, authored };
+}
+
+/**
+ * Render the conflict report for a plan that needs a human.
+ *
+ * Pure and exported so the WORDING is testable without producing a real merge
+ * conflict. That matters more than it looks: the per-class instruction is the
+ * entire value of the classification, and while this lived inline in `main()`
+ * the whole block could be deleted and every test stayed green — the header
+ * still counted the conflict, and the paths went unnamed with no instruction.
+ */
+export function renderConflictReport(plan: Plan): string {
+    const out: string[] = [`❌  ${plan.message}\n`];
+    const untracked = plan.generated.filter(isUntrackedByDesign);
+    const regenerable = plan.generated.filter((f) => !isUntrackedByDesign(f));
+    if (regenerable.length > 0) {
+        out.push(`\n  GENERATED (${String(regenerable.length)}) — resolve by REGENERATING, never by mixing hunks:\n`);
+        for (const f of regenerable) out.push(`    · ${f}\n`);
+        out.push('    → git checkout --ours <file> && task sync && task generate-tools\n');
+    }
+    if (untracked.length > 0) {
+        out.push(
+            `\n  UNTRACKED BY DESIGN (${String(untracked.length)}) — this repository does not commit these; TAKE THE DELETION:\n`,
+        );
+        for (const f of untracked) out.push(`    · ${f}\n`);
+        out.push('    → git rm --cached -- <file>   (the working-tree copy stays; regenerate it locally)\n');
+    }
+    if (plan.remeasured.length > 0) {
+        out.push(
+            `\n  REMEASURED (${String(plan.remeasured.length)}) — RE-RUN THE MEASUREMENT on the merged tree; never merge, never pick a side:\n`,
+        );
+        for (const f of plan.remeasured) out.push(`    · ${f}\n`);
+        out.push('    → resolve the tree, then re-run the gate that owns the baseline and record its number\n');
+    }
+    if (plan.authored.length > 0) {
+        out.push(`\n  AUTHORED (${String(plan.authored.length)}) — a human decision, read both sides:\n`);
+        for (const f of plan.authored) out.push(`    · ${f}\n`);
+    }
+    return out.join('');
 }
 
 /** Resolve the base this branch will actually merge into. */
@@ -118,7 +275,7 @@ export function resolveBase(repo: string, override: string | null): { base: stri
 export function sync(repo: string, baseOverride: string | null, dryRun: boolean): Plan {
     const { base, how } = resolveBase(repo, baseOverride);
     if (base === null) {
-        return { exit: 1, message: `cannot resolve a base to update against — ${how}.`, generated: [], authored: [], scanned: 0 };
+        return { exit: 1, message: `cannot resolve a base to update against — ${how}.`, generated: [], remeasured: [], authored: [], scanned: 0 };
     }
 
     const fetched = sh('git', ['fetch', 'origin', '--prune'], repo);
@@ -129,6 +286,7 @@ export function sync(repo: string, baseOverride: string | null, dryRun: boolean)
             exit: 0,
             message: `unverified — could not fetch origin (${fetched.err.split('\n')[0] ?? '?'}). Base freshness NOT checked.`,
             generated: [],
+            remeasured: [],
             authored: [],
             scanned: 0,
         };
@@ -136,13 +294,14 @@ export function sync(repo: string, baseOverride: string | null, dryRun: boolean)
 
     const behind = sh('git', ['rev-list', '--count', `HEAD..${base}`], repo).out.trim();
     if (behind === '' || behind === '0') {
-        return { exit: 0, message: `already current with ${base} (${how}).`, generated: [], authored: [], scanned: 1 };
+        return { exit: 0, message: `already current with ${base} (${how}).`, generated: [], remeasured: [], authored: [], scanned: 1 };
     }
     if (dryRun) {
         return {
             exit: 0,
             message: `${behind} commit(s) behind ${base} (${how}) — would merge it in. Dry run, nothing changed.`,
             generated: [],
+            remeasured: [],
             authored: [],
             scanned: 1,
         };
@@ -156,6 +315,7 @@ export function sync(repo: string, baseOverride: string | null, dryRun: boolean)
                 `merged ${base} in (${how}, was ${behind} behind). REGENERATE derived files now — a clean ` +
                 'auto-merge of a generated file is still wrong.',
             generated: [],
+            remeasured: [],
             authored: [],
             scanned: 1,
         };
@@ -166,7 +326,7 @@ export function sync(repo: string, baseOverride: string | null, dryRun: boolean)
     return {
         exit: 1,
         message:
-            `merge of ${base} (${how}) hit ${String(split.generated.length + split.authored.length)} conflict(s). ` +
+            `merge of ${base} (${how}) hit ${String(split.generated.length + split.remeasured.length + split.authored.length)} conflict(s). ` +
             'NOT auto-resolved: a content conflict is where a parallel session\'s work disappears.',
         ...split,
         scanned: 1,
@@ -211,7 +371,8 @@ export function main(argv?: readonly string[]): number {
                     '  Merges the PR base into the current branch so the PR does not go stale.\n' +
                     '  Resolves the base from the open PR when there is one. A conflict is\n' +
                     '  reported and never auto-resolved; generated and authored conflicts are\n' +
-                    '  listed separately because only the first has one correct resolution.\n',
+                    '  listed separately because only the first has one correct resolution;\n' +
+                    '  measured ratchet baselines are a third class, re-measured not merged.\n',
             );
             reportScanned({ gate: 'sync_pr_branch', scanned: 0, units: 'base ref(s)', roots: ['origin'], allowEmpty: 'help output' });
             return 0;
@@ -232,18 +393,7 @@ export function main(argv?: readonly string[]): number {
     }
 
     if (plan.exit === 1) {
-        process.stdout.write(`❌  ${plan.message}\n`);
-        if (plan.generated.length > 0) {
-            process.stdout.write(
-                `\n  GENERATED (${String(plan.generated.length)}) — resolve by REGENERATING, never by mixing hunks:\n`,
-            );
-            for (const f of plan.generated) process.stdout.write(`    · ${f}\n`);
-            process.stdout.write('    → git checkout --ours <file> && task sync && task generate-tools\n');
-        }
-        if (plan.authored.length > 0) {
-            process.stdout.write(`\n  AUTHORED (${String(plan.authored.length)}) — a human decision, read both sides:\n`);
-            for (const f of plan.authored) process.stdout.write(`    · ${f}\n`);
-        }
+        process.stdout.write(renderConflictReport(plan));
     } else if (plan.message.startsWith('unverified')) {
         // Loud even under --quiet: unverified reported silently is
         // indistinguishable from verified, which is the defect being closed.

package/src/server/schemas/settings.ts

@@ -200,6 +200,14 @@ export const settingsSchema = z.object({
         horizon_weeks: z.number().int().min(0).default(0).describe(
             'Optional planning horizon (weeks) the agent shows in roadmap framing ("next 4 weeks"). Set 0 to omit the horizon — most teams prefer to ship without a hardcoded window.',
         ),
+        gate_budget: z.object({
+            max_cost_per_run_usd: z.number().min(0).default(5).describe(
+                'Per-run USD ceiling for a CLASS-1 roadmap blocker executed via `agent-config gates --execute`. A class-1 entry whose **Budget:** field states a larger figure renders its consent line instead of running. Bounds the size of an authorised spend; never supplies the authorisation — `--confirm` is still required on every class-1 run.',
+            ),
+            max_cost_per_rolling_7d_usd: z.number().min(0).default(25).describe(
+                'Rolling 7-day USD ceiling for class-1 gate execution, summed from the append-only receipt ledger at agents/runtime/state/gate-budget-ledger.jsonl. A run whose estimate would cross it renders instead of running. A per-run cap alone bounds one mistake, not a week of them, which is why option (a) of b-gate-budget-preauth carries two numbers.',
+            ),
+        }).default({ max_cost_per_run_usd: 5, max_cost_per_rolling_7d_usd: 25 }),
     }),
     planning: z.object({
         challenge_on_create: z.boolean().default(true).describe(