@event4u/agent-config 14.7.0 → 14.8.0

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,10 +40,32 @@ 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
@@ -47,6 +74,44 @@ const GENERATED = [
     // 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 } {
@@ -60,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;
 }
@@ -82,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. */
@@ -125,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);
@@ -136,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,
         };
@@ -143,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,
         };
@@ -163,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,
         };
@@ -173,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,
@@ -218,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;
@@ -239,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/dist/cli-delegate/{chunk-PPQO4NGR.js → chunk-6RJA2F5A.js}

@@ -1,10 +1,10 @@
 import { createRequire as __acCreateRequire } from 'node:module'; const require = globalThis.require ?? __acCreateRequire(import.meta.url);
-import {
-  resolve_project_root
-} from "./chunk-NLP54U3J.js";
 import {
   resolvePackageRoot
 } from "./chunk-MCJYCQPF.js";
+import {
+  resolve_project_root
+} from "./chunk-NLP54U3J.js";
 
 // src/scripts/_cli/cmd_migrate.ts
 import { spawnSync } from "node:child_process";

package/dist/cli-delegate/{chunk-FBKL6JWT.js → chunk-MMSGVZKV.js}

@@ -1,4 +1,7 @@
 import { createRequire as __acCreateRequire } from 'node:module'; const require = globalThis.require ?? __acCreateRequire(import.meta.url);
+import {
+  require_dist
+} from "./chunk-OY53J6II.js";
 import {
   load_agent_settings
 } from "./chunk-NLP54U3J.js";
@@ -6,9 +9,6 @@ import {
   resolve_with_fallback,
   write_target
 } from "./chunk-NDJLNC6Q.js";
-import {
-  require_dist
-} from "./chunk-OY53J6II.js";
 import {
   __export,
   __toESM

package/dist/cli-delegate/{chunk-GJ5BVHXM.js → chunk-PMEKGDED.js}

@@ -2,12 +2,12 @@ import { createRequire as __acCreateRequire } from 'node:module'; const require
 import {
   write_atomic
 } from "./chunk-MWRD5YOH.js";
-import {
-  write_target
-} from "./chunk-NDJLNC6Q.js";
 import {
   require_dist
 } from "./chunk-OY53J6II.js";
+import {
+  write_target
+} from "./chunk-NDJLNC6Q.js";
 import {
   __export,
   __toESM