@event4u/agent-config 15.0.0 → 16.1.0

package/src/scripts/report_standing_payload_by_host.ts

@@ -49,13 +49,20 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import {
-    loadRouter,
-    matchTierRules,
-    pathOnlyRuleIds,
-    selectForInjection,
-} from './_lib/rule_injection.js';
+    corpusShapeProblems,
+    slotFireSizes as sampleSlotFireSizes,
+    type SlotFireSizes,
+} from './_lib/activation_payload.js';
+import { loadRouter, pathOnlyRuleIds } from './_lib/rule_injection.js';
 import { CAP_BYTES } from './hooks/rule_inject_hook.js';
 
+// Re-exported rather than redefined: this module was their only home until the
+// payload gate needed the same sample, and two copies is how two numbers start
+// disagreeing. `corpusShapeProblems` and `SlotFireSizes` are imported above
+// because this module's own code uses them; these two it only passes through.
+export { percentile, readCorpusPositives } from './_lib/activation_payload.js';
+export { corpusShapeProblems, type SlotFireSizes };
+
 const _HERE = fileURLToPath(import.meta.url);
 export const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 export const ARTIFACT_REL = path.join(
@@ -149,8 +156,13 @@ export const HOST_SURFACES: readonly HostSurface[] = [
     },
     {
         host: 'codex', surface: '.codex/agent-config.md', perRuleTree: false,
-        writer: 'src/scripts/install.ts:1541',
-        anchor: '\'agent-config.md\'',
+        writer: 'src/scripts/install.ts:1432',
+        // Scoped to `.codex` rather than the bare filename: nine other lines in
+        // `install.ts` write an `agent-config.md` for some other host, so the
+        // unscoped anchor would have accepted a drift onto any of them — the
+        // bounds-test-wearing-a-provenance-test's-name failure this field exists
+        // to close, one level down.
+        anchor: '\'.codex\', \'agent-config.md\'',
         note: 'written by the installer, not by `condense`; absent in this checkout',
     },
 ];
@@ -431,155 +443,17 @@ export function renderArtifact(root: string, pin: string): string {
     return L.join('\n');
 }
 
-/** One positive prompt of the frozen corpus, with the open files it declares. */
-interface CorpusPrompt {
-    prompt: string;
-    openFiles: string[] | null;
-}
-
 /**
- * Every YAML shape inside `positives:` this hand parser cannot read (R2 finding 10).
+ * The activation-charge sample at the concern's own cap.
  *
- * `readCorpusPositives` accepts only `- prompt: "…"` with a double-quoted
- * same-line scalar and an inline `open_files: [...]`. Any other legal shape —
- * single quotes, an unquoted scalar, a folded block, a block sequence for
- * `open_files` — was SILENTLY SKIPPED, which drops fires out of the
- * distribution the 16,384-byte `user_prompt_submit` row is derived from. A
- * measurement that governs a budget must fail loudly on a shape it cannot read
- * rather than under-count, so the CLI refuses on a non-empty result here.
- *
- * Reported as a shape problem rather than fixed by widening the parser: this
- * script must not grow a second YAML implementation, and the corpus is frozen,
- * so the honest answer to an unreadable shape is to say which file carries it.
- */
-export function corpusShapeProblems(root: string): string[] {
-    const dir = path.join(root, 'tests', 'eval', 'routing-matrix');
-    const problems: string[] = [];
-    if (!fs.existsSync(dir)) return problems;
-    for (const f of fs.readdirSync(dir).filter((n) => n.endsWith('.yaml')).sort()) {
-        let inPositives = false;
-        let lineNo = 0;
-        for (const raw of fs.readFileSync(path.join(dir, f), 'utf-8').split('\n')) {
-            lineNo += 1;
-            if (/^positives:/u.test(raw)) { inPositives = true; continue; }
-            if (/^near_misses:/u.test(raw)) { inPositives = false; continue; }
-            if (!inPositives) continue;
-            if (/^\s*-\s*prompt:/u.test(raw) && !/^\s*-\s*prompt:\s*"(.*)"\s*$/u.test(raw)) {
-                problems.push(
-                    `${f}:${String(lineNo)}: a \`- prompt:\` this parser cannot read — only a ` +
-                        `double-quoted same-line scalar is accepted: ${JSON.stringify(raw.trim())}`,
-                );
-                continue;
-            }
-            if (/^\s*-\s*/u.test(raw) && !/^\s*-\s*(prompt|command|open_files):/u.test(raw)
-                && raw.trim() !== '-' && raw.trim() !== '') {
-                // A bare sequence item under `positives:` is a shape with no
-                // `prompt:` key on its first line — folded or nested.
-                if (!/^\s{4,}/u.test(raw)) {
-                    problems.push(
-                        `${f}:${String(lineNo)}: a positives entry whose first line carries no ` +
-                            `\`prompt:\` key: ${JSON.stringify(raw.trim())}`,
-                    );
-                }
-            }
-            if (/^\s*open_files:\s*$/u.test(raw)) {
-                problems.push(
-                    `${f}:${String(lineNo)}: a BLOCK-sequence \`open_files:\` — only the inline ` +
-                        '`[...]` form is read, so this entry\'s files would be dropped',
-                );
-            }
-        }
-    }
-    return problems;
-}
-
-/** Every positive prompt in the frozen routing-matrix corpus. Near-misses are not fires. */
-export function readCorpusPositives(root: string): CorpusPrompt[] {
-    const dir = path.join(root, 'tests', 'eval', 'routing-matrix');
-    const out: CorpusPrompt[] = [];
-    if (!fs.existsSync(dir)) return out;
-    for (const f of fs.readdirSync(dir).filter((n) => n.endsWith('.yaml')).sort()) {
-        let inPositives = false;
-        let cur: CorpusPrompt | null = null;
-        for (const raw of fs.readFileSync(path.join(dir, f), 'utf-8').split('\n')) {
-            if (/^positives:/u.test(raw)) { inPositives = true; continue; }
-            if (/^near_misses:/u.test(raw)) { inPositives = false; continue; }
-            if (!inPositives) continue;
-            const p = /^\s*-\s*prompt:\s*"(.*)"\s*$/u.exec(raw);
-            if (p !== null) {
-                cur = { prompt: p[1] as string, openFiles: null };
-                out.push(cur);
-                continue;
-            }
-            const of = /^\s*open_files:\s*\[(.*)\]\s*$/u.exec(raw);
-            if (of !== null && cur !== null) {
-                cur.openFiles = (of[1] as string)
-                    .split(',')
-                    .map((x) => x.trim().replace(/^["']|["']$/gu, ''))
-                    .filter((x) => x !== '');
-            }
-        }
-    }
-    return out;
-}
-
-/** Nearest-rank percentile over an unsorted sample. Empty sample → 0. */
-export function percentile(xs: readonly number[], q: number): number {
-    if (xs.length === 0) return 0;
-    const s = [...xs].sort((a, b) => a - b);
-    return s[Math.min(s.length - 1, Math.floor(q * (s.length - 1)))] as number;
-}
-
-export interface SlotFireSizes {
-    readonly slot: string;
-    readonly fires: number;
-    readonly p50: number;
-    readonly p90: number;
-    readonly max: number;
-}
-
-/**
- * Gate-open per-fire emission sizes for the delivery concern, per slot
- * (road-to-delivery-for-every-host 3.1).
- *
- * Measured through the SAME selection the runtime concern uses —
- * `matchTierRules` + `selectForInjection` at the concern's own `CAP_BYTES` —
- * rather than through a second model of it. An offline figure computed by a
- * different matcher would price a set the concern does not deliver.
- *
- * `pre_compact` is 0 by construction rather than by measurement: that branch of
- * `rule_inject_hook` clears the seen-set and returns allow without writing to
- * stdout, so there is no emission to sample.
+ * The sampling itself moved to `_lib/activation_payload.ts` when the payload
+ * gate needed the same figure (`road-to-the-delivery-flip-that-tells-the-truth`
+ * 3.1). This wrapper supplies `CAP_BYTES` so the report's own callers keep the
+ * one-argument form, and the helpers below are re-exported so there is still
+ * exactly one implementation of each.
  */
 export function slotFireSizes(root: string): SlotFireSizes[] {
-    const router = loadRouter(root);
-    const prompts = readCorpusPositives(root);
-    const sample = (mode: 'prompt' | 'file'): number[] => {
-        const out: number[] = [];
-        for (const r of prompts) {
-            if (mode === 'file' && (r.openFiles === null || r.openFiles.length === 0)) continue;
-            const matches =
-                mode === 'prompt'
-                    ? matchTierRules(router, r.prompt, null, null)
-                    : matchTierRules(router, '', r.openFiles, null);
-            if (matches.length === 0) continue;
-            const sel = selectForInjection(root, matches, CAP_BYTES);
-            if (sel.selected.length > 0) out.push(sel.bytes);
-        }
-        return out;
-    };
-    const row = (slot: string, xs: number[]): SlotFireSizes => ({
-        slot,
-        fires: xs.length,
-        p50: percentile(xs, 0.5),
-        p90: percentile(xs, 0.9),
-        max: xs.length === 0 ? 0 : Math.max(...xs),
-    });
-    return [
-        row('user_prompt_submit', sample('prompt')),
-        row('pre_tool_use', sample('file')),
-        row('pre_compact', []),
-    ];
+    return sampleSlotFireSizes(root, CAP_BYTES);
 }
 
 function headSha(root: string): string {

package/src/scripts/schemas/agent-settings.schema.json

@@ -101,6 +101,29 @@
         }
       }
     },
+    "delivery": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "merge": {
+          "type": "string",
+          "enum": ["off", "on-green"],
+          "default": "off",
+          "description": "Whether a run may merge the pull request it produced. off (default) = the run ends at mergeable-green-and-open and says so. on-green = merge is permitted, and only when an object-bound grant covering {op: prod_merge, target: <base>} exists and the final head is required-check-green, target-current and tamper-checked (ADR-268 section 3). A precondition, never the authorisation by itself; forge auto-merge is the mechanism, so branch protection stays the gate."
+        },
+        "wait_for_ci": {
+          "type": "boolean",
+          "default": true,
+          "description": "Whether the run stays alive until the required checks settle. true (default) = the run drives CI and reports the settled verdict. false = the run ends once the branch is pushed and the PR is open. Independent of merge: a run may wait for CI without being allowed to merge."
+        },
+        "pr_topology": {
+          "type": "string",
+          "enum": ["single", "stacked"],
+          "default": "single",
+          "description": "How a mission's work is shaped into pull requests. single (default) = one branch, one pull request. stacked = a dependent series. stacked is never chosen by the agent and never asked about at roadmap creation — the owner plans it in roadmap frontmatter or it does not happen."
+        }
+      }
+    },
     "screenshots": {
       "type": "object",
       "additionalProperties": true,

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

@@ -103,6 +103,10 @@
       "pattern": "^[a-z][a-z0-9-]*$",
       "description": "Sub-command identifier within the cluster (e.g. `ci` for `/fix ci`)."
     },
+    "produces_roadmap": {
+      "type": "boolean",
+      "description": "This command produces a roadmap, so it ends in the plan-closure pass (`/challenge-me closure`). The declaration replaces the hard-coded entrance list that lived inside three command bodies and left the other five producers uncovered with nothing saying so. `lint_roadmap_producers` reds a command that declares it and carries no reference to the closure pass. Omit the key for commands that produce no plan."
+    },
     "superseded_by": {
       "type": "string",
       "pattern": "^[a-z][a-z0-9-]*( (--[a-z][a-z0-9-]*|[a-z][a-z0-9-]*))?$",

package/src/scripts/scope_growth.ts

@@ -0,0 +1,219 @@
+#!/usr/bin/env tsx
+/**
+ * Who owns a piece of scope growth discovered mid-mission.
+ *
+ * The size question — *is this small and aligned enough to do now* — already
+ * has an answer in the remediation ladder. This is the other axis, and the two
+ * are independent: something small and council-owned is still not the agent's
+ * to decide, and something agent-owned and large is still bounded by the
+ * smallest-diff rule.
+ *
+ * Four verdicts, and the last one is the important one:
+ *
+ *   `agent`      done inline, recorded as a scope delta in the PR body, never
+ *                asked about.
+ *   `council`    routed through the ownership ladder; the verdict becomes a
+ *                `## Decisions` row. It does NOT reach the owner, however
+ *                consequential — a technical decision does not become
+ *                owner-owned because it is hard.
+ *   `owner`      the work changes what the product or the business does, or it
+ *                needs a typed op for which no grant exists. Two rows, closed.
+ *   `follow-up`  not scope growth at all. A larger unrelated opportunity
+ *                becomes its own artifact and the mission does not expand to
+ *                hold it — the failure that looks like diligence is a mission
+ *                that absorbs every good idea it meets and delivers none.
+ *
+ * `unknown` is a real verdict and is deliberately NOT folded into `agent`:
+ * growth nothing classifies is growth nobody decided, and defaulting it to the
+ * cheapest rung is how an owner question becomes an agent one silently.
+ *
+ * Exit codes: 0 classified · 1 unknown · 2 bad argv.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+const _HERE = fileURLToPath(import.meta.url);
+const _PROG = 'scope_growth';
+
+export type Verdict = 'agent' | 'council' | 'owner' | 'follow-up' | 'unknown';
+
+export interface Rule {
+    readonly verdict: Verdict;
+    readonly kind: string;
+    readonly re: RegExp;
+}
+
+/**
+ * Ordered, and the order is the contract: `owner` and `follow-up` are tested
+ * BEFORE `agent`, so a row that matches both ("a missing test — in a subsystem
+ * this mission never touched") resolves to the more conservative rung rather
+ * than to the first cheap match.
+ */
+export const RULES: readonly Rule[] = [
+    // --- owner: two rows, closed ------------------------------------------
+    {
+        verdict: 'owner',
+        kind: 'product-or-business-change',
+        re: /\b(?:new user-visible|changes what the product|changes what the business|a price|pricing|a public commitment|a policy change)\b/i,
+    },
+    {
+        verdict: 'owner',
+        kind: 'typed-op-without-grant',
+        re: /\b(?:needs a typed op|no grant exists|merge to main|force-push|deploy to prod(?:uction)?|rotate the secret)\b/i,
+    },
+    // --- follow-up: unrelated, however good -------------------------------
+    {
+        verdict: 'follow-up',
+        kind: 'larger-unrelated',
+        re: /\b(?:unrelated|another subsystem|a subsystem this .{0,30}never touched|out of scope|deserves its own)\b/i,
+    },
+    // --- council: technical, contested ------------------------------------
+    {
+        verdict: 'council',
+        kind: 'larger-internal-re-cut',
+        re: /\b(?:re-?cut|restructure the module|reshape the boundary)\b/i,
+    },
+    {
+        verdict: 'council',
+        kind: 'two-equal-strategies',
+        re: /\b(?:two equal|two valid|either strategy|no evidence between them)\b/i,
+    },
+    {
+        verdict: 'council',
+        kind: 'risky-compatibility-design',
+        re: /\b(?:compatibility risk|backwards[- ]incompat|breaking change)\b/i,
+    },
+    {
+        verdict: 'council',
+        kind: 'unclear-boundary',
+        re: /\b(?:unclear boundary|where the boundary)\b/i,
+    },
+    // --- agent: six rows, closed ------------------------------------------
+    {
+        verdict: 'agent',
+        kind: 'necessary-internal-refactor',
+        re: /\b(?:necessary (?:internal )?refactor|cannot land (?:correctly )?without)\b/i,
+    },
+    { verdict: 'agent', kind: 'missing-test', re: /\bmissing test\b/i },
+    {
+        verdict: 'agent',
+        kind: 'regression-on-touched-path',
+        re: /\bregression\b[^.]{0,60}\btouched\b|\btouched\b[^.]{0,60}\bregression\b/i,
+    },
+    {
+        verdict: 'agent',
+        kind: 'small-dependency-adjustment',
+        re: /\b(?:small dependency adjustment|patch bump|minor bump)\b/i,
+    },
+    {
+        verdict: 'agent',
+        kind: 'local-api-inside-defined-semantics',
+        re: /\b(?:inside (?:the )?(?:already-)?defined semantics|the contract does not move)\b/i,
+    },
+    {
+        verdict: 'agent',
+        kind: 'boy-scout-cleanup',
+        re: /\bboy[- ]scout\b/i,
+    },
+];
+
+export interface Classification {
+    readonly verdict: Verdict;
+    readonly kind: string;
+    /** True when the verdict is done inline and recorded rather than asked. */
+    readonly records_scope_delta: boolean;
+    /** True when a person is reached at all. */
+    readonly asks: boolean;
+}
+
+export function classifyGrowth(text: string): Classification {
+    for (const r of RULES) {
+        if (r.re.test(text)) {
+            return {
+                verdict: r.verdict,
+                kind: r.kind,
+                records_scope_delta: r.verdict === 'agent',
+                asks: r.verdict === 'owner',
+            };
+        }
+    }
+    return { verdict: 'unknown', kind: 'unclassified', records_scope_delta: false, asks: false };
+}
+
+function _usage(): string {
+    return `usage: ${_PROG} [-h] [--self-test] [--json] <description...>\n`;
+}
+
+export function main(argv?: readonly string[]): number {
+    const args = argv ?? process.argv.slice(2);
+    let json = false;
+    const words: string[] = [];
+    for (const a of args) {
+        if (a === '-h' || a === '--help') {
+            process.stdout.write(_usage());
+            return 0;
+        }
+        if (a === '--self-test') return _selfTest();
+        if (a === '--json') {
+            json = true;
+            continue;
+        }
+        words.push(a);
+    }
+    if (!words.length) {
+        process.stderr.write(`${_usage()}${_PROG}: error: a description is required\n`);
+        return 2;
+    }
+    const c = classifyGrowth(words.join(' '));
+    if (json) {
+        process.stdout.write(JSON.stringify(c, null, 2) + '\n');
+    } else {
+        process.stdout.write(
+            `${c.verdict}  (${c.kind})  scope-delta=${String(c.records_scope_delta)}  asks=${String(c.asks)}\n`,
+        );
+    }
+    return c.verdict === 'unknown' ? 1 : 0;
+}
+
+function _selfTest(): number {
+    const cases: ReadonlyArray<readonly [string, Verdict]> = [
+        ['a missing test on a path this change touched', 'agent'],
+        ['a boy-scout cleanup, small and local', 'agent'],
+        ['two equal technical strategies with no evidence between them', 'council'],
+        ['this introduces a compatibility risk', 'council'],
+        ['it needs a typed op and no grant exists', 'owner'],
+        ['this adds new user-visible semantics', 'owner'],
+        ['an unrelated refactor that deserves its own roadmap', 'follow-up'],
+        ['something nobody wrote a rule for', 'unknown'],
+        // The ordering case: matches `missing test` AND `unrelated`, and the
+        // conservative rung must win or a follow-up silently becomes agent work.
+        ['a missing test in an unrelated subsystem', 'follow-up'],
+    ];
+    const failures: string[] = [];
+    for (const [text, want] of cases) {
+        const got = classifyGrowth(text).verdict;
+        if (got !== want) failures.push(`"${text}" → ${got}, wanted ${want}`);
+    }
+    if (failures.length) {
+        for (const f of failures) process.stderr.write(`❌  ${_PROG} --self-test: ${f}\n`);
+        return 1;
+    }
+    process.stdout.write(`✅  ${_PROG} --self-test: ${String(cases.length)} case(s) behaved\n`);
+    return 0;
+}
+
+function _isCliEntry(): boolean {
+    if (!process.argv[1]) return false;
+    try {
+        return fs.realpathSync(_HERE) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
+    process.exitCode = main();
+}

package/src/scripts/sync_agent_settings.ts

@@ -24,13 +24,22 @@
  * Usage:
  *     sync_agent_settings                       # write (default)
  *     sync_agent_settings --dry-run             # show diff, no write
- *     sync_agent_settings --check               # exit 2 on drift (for CI)
+ *     sync_agent_settings --check               # exit 2 if a sync is needed (CI)
  *     sync_agent_settings --profile balanced    # use a specific profile
  *     sync_agent_settings --path path/to/.agent-settings.yml
  *
  * Exit codes:
  *     0 — already in sync, or changes applied (or --dry-run ran cleanly)
- *     2 — drift detected under --check, or invalid arguments / missing files
+ *     2 — under --check, synchronization requires intervention; also invalid
+ *         arguments, missing files, and a duplicate-key repair this tool
+ *         refuses to perform.
+ *
+ * `--check` has two diagnostic cases and its stderr line already separates
+ * them, because the remedies differ: template drift ("drift detected"), and a
+ * duplicate-key repair with no drift ("duplicate keys need collapsing"). Both
+ * exit 2 — the target needs a write either way, and a green `--check` over a
+ * file the strict reader cannot parse would hide the breakage. A caller that
+ * needs the distinction reads the message, not the code.
  *
  * No behaviour changes vs. the retired Python implementation — historical quirks preserved (consumers pin the exact behaviour).
  */
@@ -441,6 +450,52 @@ function loadTemplate(p: string, profileValues: Record<string, string>): string
   return renderTemplate(fs.readFileSync(p, 'utf-8'), profileValues);
 }
 
+/**
+ * The comment `mergeIntoTemplate` writes above its appended flat-key block.
+ *
+ * Duplicated here rather than imported: the writer holds it as a literal in
+ * `src/server/io/yamlIO.ts` and exports no constant, and that module belongs
+ * to the server tree this CLI does not otherwise depend on. Keep the two in
+ * step — a drift makes the sweep below silently stop matching.
+ */
+const WIZARD_BLOCK_HEADER = '# Wizard-added keys (no template entry)';
+
+/**
+ * Drop a wizard-block header the collapse emptied.
+ *
+ * The non-idempotent writer appended the header AND its keys on every save, so
+ * a collapse that removes the later block's key lines leaves that block's
+ * header behind with nothing under it — and the next append puts a fresh
+ * header below the orphan, one more per save. A header names the keys beneath
+ * it; with none beneath it, it names nothing and misleads the next reader.
+ *
+ * A header counts as emptied only when no key line stands between it and the
+ * next header or EOF. Blanks and further comments do not count: a user comment
+ * written between the header and its first key is part of the block, not a
+ * replacement for it.
+ */
+function dropOrphanedWizardHeaders(lines: readonly string[]): string[] {
+  const drop = new Set<number>();
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i]?.trim() !== WIZARD_BLOCK_HEADER) continue;
+    let hasKey = false;
+    for (let j = i + 1; j < lines.length; j++) {
+      const l = lines[j];
+      if (l === undefined) continue;
+      if (l.trim() === WIZARD_BLOCK_HEADER) break;
+      if (l.trim() === '' || l.trimStart().startsWith('#')) continue;
+      hasKey = true;
+      break;
+    }
+    if (hasKey) continue;
+    drop.add(i);
+    // The writer emits the blank line above the header as part of the block,
+    // so removing the header alone widens the gap by one line per repair.
+    if (i > 0 && lines[i - 1]?.trim() === '') drop.add(i - 1);
+  }
+  return drop.size === 0 ? [...lines] : lines.filter((_, i) => !drop.has(i));
+}
+
 export interface DuplicateRepair {
   /** The document with every safely-collapsible duplicate run reduced to one. */
   text: string;
@@ -482,6 +537,9 @@ export interface DuplicateRepair {
  * A multi-document stream (`---` / `...`) is not repaired either. The reader
  * takes a single document and rejects such a file whatever this pass does, so
  * collapsing across a boundary could only merge two documents' keys into one.
+ *
+ * When — and only when — something did collapse, a wizard-block header the
+ * collapse emptied is removed with it; see `dropOrphanedWizardHeaders`.
  */
 export function collapseDuplicateFlatKeys(text: string): DuplicateRepair {
   // Line endings are preserved: splitting on `\n` alone leaves a trailing
@@ -630,10 +688,53 @@ export function collapseDuplicateFlatKeys(text: string): DuplicateRepair {
   if (collapsed.length === 0) {
     return { text, collapsed, unsafe };
   }
-  const kept = lines.filter((_, i) => !drop.has(i));
+  const kept = dropOrphanedWizardHeaders(lines.filter((_, i) => !drop.has(i)));
   return { text: kept.join(eol), collapsed, unsafe };
 }
 
+/**
+ * The parse error an input still carries once its duplicate keys are excused,
+ * or null when the duplicates were its only problem.
+ *
+ * `uniqueKeys: false` is what excuses them: the duplicate-key rejection is the
+ * single error the collapse has a mandate to remove, so anything the parser
+ * still raises is an error the collapse was never licensed to touch.
+ */
+function residualParseError(text: string): Error | null {
+  try {
+    parseYaml(text, { version: '1.1', uniqueKeys: false });
+    return null;
+  } catch (err) {
+    return err instanceof Error ? err : new Error(String(err));
+  }
+}
+
+/**
+ * What the parser reliably exposes about a failure, as one indented block.
+ *
+ * Available on every `YAMLParseError` observed from this parser: `message`,
+ * whose first line already carries `at line L, column C` plus the detail, and
+ * `code`, a stable identifier. `linePos` is populated too, but only while
+ * `prettyErrors` stays on (the library's own condition), so it is printed when
+ * present and never relied on. Nothing here is asserted beyond the parser's
+ * own first message line, which is derived in the test rather than hardcoded —
+ * pinning a format this module does not own would make a safety test fail on a
+ * dependency's wording change.
+ */
+function formatParserDetail(err: Error): string {
+  const first = err.message.split('\n')[0] ?? err.message;
+  const parts: string[] = [`    ${first}`];
+  const code = (err as { code?: unknown }).code;
+  const linePos = (err as { linePos?: { line: number; col: number }[] }).linePos;
+  const at = linePos?.[0];
+  if (typeof code === 'string' && at !== undefined) {
+    parts.push(`    (${code} at line ${at.line}, column ${at.col})`);
+  } else if (typeof code === 'string') {
+    parts.push(`    (${code})`);
+  }
+  return parts.join('\n') + '\n';
+}
+
 function loadUserText(raw: string): Record<string, unknown> {
   const data = parseYaml(raw, { version: '1.1' });
   if (data === null || data === undefined) {
@@ -863,6 +964,42 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
     return 2;
   }
   if (repair.collapsed.length > 0) {
+    // Refuse before anything else in this branch, including the notice below:
+    // in write mode that notice is past tense ("collapsed …"), so announcing
+    // it and then refusing describes a write that never happened.
+    //
+    // The collapse's safety rests on preserving the original's last-wins
+    // reading, and a document that is invalid for some FURTHER reason has no
+    // reading to preserve — the pass can then emit valid YAML carrying
+    // structure nobody authored, which every downstream check accepts. A
+    // stderr warning (what this branch used to do) is a weak control against a
+    // silent outcome; a refusal is loud and the operator can still recover.
+    // AI council, 2026-09-11, 2 of 2 seats, converged — including a rejection
+    // of any `--repair-anyway` escape: an operator who understands the file
+    // well enough to use it understands it well enough to fix the error first,
+    // and "read the diff" is not a trustworthy oracle for YAML semantics.
+    //
+    // Exit 2, per the taxonomy in this file's header: 2 is "this tool cannot
+    // proceed with this input", which is also what the sibling refusal above
+    // (duplicates it will not collapse) returns. 1 is spoken for — it is the
+    // mirrored `install.fail` exit and means a broken install asset.
+    //
+    // Nothing durable precedes this point: the only write in `main` is the
+    // single `writeFileSync` at the end, there is no temporary file and no
+    // rename, so the refusal leaves the target byte-for-byte unchanged.
+    const residual = residualParseError(rawText);
+    if (residual !== null) {
+      process.stderr.write(
+        `❌  ${target}: refusing the automatic duplicate repair — the file has ` +
+          `another YAML error besides its duplicate keys.\n` +
+          formatParserDetail(residual) +
+          `    Collapsing changes only WHETHER a file parses, never what it parses as, ` +
+          `and that promise is empty over a document with no valid reading.\n` +
+          `    Fix the syntax error by hand, then re-run to apply the duplicate repair.\n`,
+      );
+      return 2;
+    }
+
     // NOT gated on --quiet, and not on stdout. Both callers that matter run
     // quiet — the release's `sync-agent-settings` step and the pre-release
     // probe — so gating this would let a release rewrite the operator's own
@@ -878,21 +1015,6 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
       ? `collapsed ${repair.collapsed.length} duplicate key(s), last value kept`
       : `would collapse ${repair.collapsed.length} duplicate key(s), keeping the last value (no write in this mode)`;
     process.stderr.write(`🔧  ${target}: ${verb} — ${repair.collapsed.join(', ')}\n`);
-
-    // The collapse promises to change only WHETHER the file parses, never what
-    // it parses as — and that promise is only meaningful over an input that had
-    // a reading to preserve. If the original was unparseable for some further
-    // reason (an unterminated quote, say), the repaired file may parse to
-    // structure no human wrote, and the next `git diff` shows keys nobody
-    // added. Cheap to say, and the operator cannot recover it from the output.
-    try {
-      parseYaml(rawText, { version: '1.1', uniqueKeys: false });
-    } catch {
-      process.stderr.write(
-        `⚠️   ${target}: the original had a syntax error beyond the duplicate keys, so the ` +
-          `result may differ in structure, not only in duplicates — read the diff before trusting it.\n`,
-      );
-    }
   }
   const sourceText = repair.text;