@event4u/agent-config 14.14.0 → 14.14.1

package/src/scripts/_lib/outcome_vocabularies.ts

@@ -13,7 +13,7 @@
  * |---|---|---|---|
  * | phase | one audit-log line — a `/work` PHASE | here, consumed by `orchestration_record` | 4 |
  * | step  | one work-engine STEP | `work_engine/delivery_state.ts` (template tree) | 3 |
- * | run   | one command or gate RUN | here, consumed by `outcome_envelope` | 6 |
+ * | run   | one command or gate RUN | here, consumed by `outcome_envelope` | 7 |  code-comment-allow report-comment -- one row of a pre-existing three-row table documenting the three vocabularies; the digit changed from 6 to 7 with the vocabulary, and the table is the registry's whole point
  *
  * All three are declared in code AND emitted today. `skipped` and `error` are
  * not aspirational: `envelopeOutcome` in `orchestration_record.ts` returns
@@ -33,16 +33,42 @@
  * `partial`. So: separate vocabularies, one registry, mappings only where
  * execution actually crosses.
  *
- * **Mappings are not written for symmetry.** Exactly one crossing exists
- * (`DispatchOutcome` -> phase, in `orchestration_record.ts`). A total
- * phase<->step<->run mapping would be nine relations of which one is real, and
- * the eight invented ones would read as contract.
+ * **Mappings are not written for symmetry.** Two crossings exist, and both are
+ * places where execution actually translates: `DispatchOutcome` -> phase in
+ * `orchestration_record.ts`, and `LadderAction` -> run in
+ * `continuation_ladder.ts` (added 2026-09-03 with the seventh run state, so the
+ * state has a producer rather than being a word nothing emits). A total
+ * phase<->step<->run mapping would be nine relations of which two are real, and
+ * the seven invented ones would read as contract.
  *
  * `revisit-if`: a producer needs a value its vocabulary cannot express, or a
  * second real crossing appears, or producer analysis shows two of the three
  * subjects share identical terminal semantics with a lossless mapping — at
  * which point unifying those two becomes the cheaper answer.
  *
+ * **The run vocabulary grew to seven on 2026-09-03** — exactly the first branch
+ * of the reopening condition above: the continuation ladder needed a word for a
+ * run whose plan premise moved, and had none. AI council (anthropic/claude-sonnet-4-5 +
+ * openai/codex-default, three rounds, blind chairman) resolved it unanimously
+ * as option (a), extend rather than overload `blocked` with a reason field. The
+ * seats attached the same prerequisites, discharged here: a versioned value
+ * domain ({@link RUN_TERMINAL_VOCABULARY_VERSION}), a tolerant read
+ * ({@link readRunTerminalState}), a declared downgrade
+ * ({@link RUN_TERMINAL_STATE_DOWNGRADE}) and the rollback trigger below.
+ *
+ * **Rollback trigger, stated rather than instrumented.** Withdraw
+ * `premise-invalidated` — remove it from {@link RUN_TERMINAL_STATES} and let the
+ * ladder rung report its declared downgrade `blocked` instead — on EITHER of:
+ * (1) any consumer is observed failing (a throw, a refused write, a dropped
+ * record) on encountering the value, or (2) `readRunTerminalState` returns
+ * `null` for a persisted value in normal operation, which would mean a writer
+ * emitted something this registry does not know. Both are single-occurrence
+ * triggers, not rates: the downgrade mapping already exists, so withdrawal
+ * costs one commit and no migration, and there is no reason to tolerate a
+ * budget of failures before paying that. No telemetry is built for this and
+ * none is claimed — condition (1) surfaces as a failing run and (2) as a null
+ * where a value was written.
+ *
  * Type-only + literal arrays. No `node:` import, so any surface may read it.
  */
 
@@ -82,9 +108,99 @@ export const RUN_TERMINAL_STATES = [
     'approval-required',
     'exhausted',
     'stagnated',
+    /**
+     * The plan premise this run was built on no longer holds — the situational
+     * -awareness fingerprint the run engaged under (`origin/main` plus every open
+     * PR head) was re-observed and differs.
+     *
+     * Added by `road-to-wired-instruments` Phase 2 under the AI-council decision
+     * of 2026-09-03 (option (a), unanimous). It is NOT `blocked` with a reason
+     * field: premise invalidation is operationally distinct from a missing
+     * precondition and from an exhausted budget, and folding it into either loses
+     * both aggregation by state and type-enforced exhaustive handling. The
+     * remedy differs too — re-probe and re-plan, where `blocked` says obtain the
+     * missing thing and `exhausted` says the budget was too small.
+     */
+    'premise-invalidated',
 ] as const;
 export type RunTerminalState = (typeof RUN_TERMINAL_STATES)[number];
 
+/**
+ * Version of the RUN vocabulary's VALUE DOMAIN — bumped when a member is added
+ * or removed, never for prose.
+ *
+ * Distinct from any table version: `runtime_journal.JOURNAL_SCHEMA_VERSION`
+ * covers tables and columns and is unaffected by a widening of what one column
+ * may contain, so a value-domain change needs its own number or it travels
+ * unversioned. A persisted shape carrying a `RunTerminalState` stamps THIS
+ * number beside the value, so a reader can tell a value it does not know from a
+ * value that is corrupt.
+ *
+ * v1 — the six original states.
+ * v2 — adds `premise-invalidated` (2026-09-03).
+ */
+export const RUN_TERMINAL_VOCABULARY_VERSION = 2;
+
+/** The vocabulary version each member first appeared in. */
+export const RUN_TERMINAL_STATE_SINCE: Readonly<Record<RunTerminalState, number>> = {
+    success: 1,
+    'clean-no-op': 1,
+    blocked: 1,
+    'approval-required': 1,
+    exhausted: 1,
+    stagnated: 1,
+    'premise-invalidated': 2,
+};
+
+/**
+ * What a consumer pinned to an older vocabulary version reports instead.
+ *
+ * `premise-invalidated` -> `blocked`: of the six v1 states it is the only one
+ * that is honest for a reader that cannot represent it — the run stopped on an
+ * external condition it cannot resolve by iterating. Mapping it to `exhausted`
+ * would invite the wrong remedy (raise the budget), which is the exact
+ * confusion the contract's own `exhausted`/`stagnated` split exists to prevent.
+ *
+ * Every member introduced after v1 MUST have a row here; `outcome_vocabularies`
+ * contract tests assert that, so a future eighth value cannot ship undowngradable.
+ */
+export const RUN_TERMINAL_STATE_DOWNGRADE: Readonly<Partial<Record<RunTerminalState, RunTerminalState>>> = {
+    'premise-invalidated': 'blocked',
+};
+
+/**
+ * The state a consumer pinned at `toVersion` should report for `state`.
+ *
+ * Returns the state unchanged when it already existed at that version, the
+ * declared downgrade when it did not, and `null` for a string this vocabulary
+ * does not know at all — never a throw, because this is the function a reader
+ * of PERSISTED data calls, and persisted data outlives the code that wrote it.
+ */
+export function downgradeRunTerminalState(
+    state: string,
+    toVersion: number,
+): RunTerminalState | null {
+    if (!isRunTerminalState(state)) return null;
+    if ((RUN_TERMINAL_STATE_SINCE[state] ?? 1) <= toVersion) return state;
+    return RUN_TERMINAL_STATE_DOWNGRADE[state] ?? null;
+}
+
+/**
+ * Tolerant read of a persisted terminal state: a member returns itself,
+ * anything else returns `null`. Never throws.
+ *
+ * `null` rather than a fabricated fallback is the load-bearing choice. This
+ * vocabulary's own consumers already treat a null terminal state as "not
+ * recorded" (`repeated_failure` counts it under `unknown`), and that is exactly
+ * what an unrecognised value IS to a reader that cannot name it. Substituting
+ * `blocked` here would manufacture a measurement out of an absence — the
+ * downgrade above is for a value the reader KNOWS is newer, which is a
+ * different fact from a value it cannot place.
+ */
+export function readRunTerminalState(v: unknown): RunTerminalState | null {
+    return isRunTerminalState(v) ? v : null;
+}
+
 /**
  * The crossings that exist. One row, because one crossing is real.
  *
@@ -112,6 +228,20 @@ export const CROSS_DOMAIN_MAPPINGS = [
          */
         semantics_version: 2,
     },
+    {
+        source: 'LadderAction',
+        target: 'run',
+        at: 'src/scripts/_lib/continuation_ladder.ts',
+        fn: 'terminalStateFor',
+        /**
+         * Version 1, and the mapping is TOTAL over `LadderAction` by
+         * construction: `TERMINAL_STATE_BY_ACTION` is a `Record<LadderAction,
+         * RunTerminalState | null>`, so adding a rung without deciding its
+         * terminal state does not compile. `engage` maps to null because it is
+         * the one action that is not terminal.
+         */
+        semantics_version: 1,
+    },
 ] as const;
 
 /** Is this string a phase outcome? The guard the audit-log consumer was missing. */

package/src/scripts/_lib/release_highlights.ts

@@ -331,14 +331,23 @@ export function render_derived_head_values(
  * `CURATED_HEAD_INSTRUCTION` is a named sentinel imported from the module that
  * defines it — never a shape match over comment prose, which would reject
  * unrelated legitimate comments and miss this one after a reword.
+ *
+ * `where` names the branch the remedy edit belongs on, because the same
+ * blockers are now read at a FOURTH site that is not on `main`:
+ * `guard_release_branch_push` refuses the release branch's first push, where
+ * the file to edit is on `release/X.Y.Z`. One definition of the blockers with a
+ * parameterised remedy beats a second copy of the message that drifts.
  */
-export function publication_blockers(sectionBody: string, version: string): string[] {
+export function publication_blockers(
+    sectionBody: string,
+    version: string,
+    where = '`main`',
+): string[] {
     const out: string[] = [];
     if (sectionBody.includes(DERIVED_MARKER)) {
         out.push(
             `the ${version} section still carries \`${DERIVED_MARKER}\` — the generator's ` +
-                'draft head, not a curated claim. Rewrite those line(s) on ' +
-                `${'`main`'} and re-run.`,
+                `draft head, not a curated claim. Rewrite those line(s) on ${where} and re-run.`,
         );
     }
     if (sectionBody.includes(CURATED_HEAD_INSTRUCTION)) {

package/src/scripts/_lib/repeated_failure.ts

@@ -39,9 +39,26 @@ export const SUCCESS_TERMINALS: ReadonlySet<RunTerminalState> = new Set([
     'clean-no-op',
 ]);
 
+/**
+ * Neither a failure nor a success for this metric, and each excluded for its own
+ * reason rather than by omission.
+ *
+ * `approval-required` is the safety floor working; counting a floor doing its
+ * job as a failure would make the metric fall every time governance fires.
+ *
+ * `premise-invalidated` is the same shape one layer out: the run stopped because
+ * the world it planned against moved, which is the drift detector working, not
+ * the work failing. It is also the state whose base rate is set by OTHER people's
+ * pushes rather than by this run's quality — `origin/main` moves constantly — so
+ * counting it as a failure would make the repeated-failure rate track repository
+ * traffic. That is the concrete form of this roadmap's Risk 1, arriving through
+ * the metric instead of through the ladder.
+ */
+const EXCLUDED: ReadonlySet<RunTerminalState> = new Set(['approval-required', 'premise-invalidated']);
+
 // Every terminal state is classified or deliberately excluded -- silence about
 // one is how a metric quietly changes meaning when the vocabulary grows.
-const CLASSIFIED = new Set<string>([...FAILURE_TERMINALS, ...SUCCESS_TERMINALS, 'approval-required']);
+const CLASSIFIED = new Set<string>([...FAILURE_TERMINALS, ...SUCCESS_TERMINALS, ...EXCLUDED]);
 const _unclassified = RUN_TERMINAL_STATES.filter((t) => !CLASSIFIED.has(t));
 if (_unclassified.length > 0) {
     throw new Error(
@@ -86,7 +103,7 @@ export function repeatedFailureRate(
         // `ep.terminal_state` is already the AMENDED verdict: reconstructEpisode
         // drops superseded rows and takes the LAST effective terminal state.
         const t = ep.terminal_state;
-        if (t === null || !CLASSIFIED.has(t) || t === 'approval-required') {
+        if (t === null || !CLASSIFIED.has(t) || EXCLUDED.has(t)) {
             unknown += 1;
             continue;
         }

package/src/scripts/_lib/runtime_journal.ts

@@ -173,7 +173,7 @@ import type { DatabaseSync } from 'node:sqlite';
 
 import { current_branch, git_common_dir, git_dir } from './git_common_dir.js';
 import type { TerminalState } from './outcome_envelope.js';
-import { RUN_TERMINAL_STATES } from './outcome_vocabularies.js';
+import { readRunTerminalState, RUN_TERMINAL_STATES } from './outcome_vocabularies.js';
 import {
     isSqliteAvailableSync,
     loadSqliteSync,
@@ -303,7 +303,7 @@ export const CONSUMPTION_STATES = ['consumed', 'partially-consumed', 'rejected-w
 export type Consumption = (typeof CONSUMPTION_STATES)[number];
 
 /**
- * The six terminal states as a runtime array.
+ * The run terminal states as a runtime array.
  *
  * Re-export of `RUN_TERMINAL_STATES` from `outcome_vocabularies.ts`. It used to
  * be a second literal list here, guarded by two type-level assertions that
@@ -316,6 +316,12 @@ export type Consumption = (typeof CONSUMPTION_STATES)[number];
  *
  * The name is kept because it is exported and pinned by
  * `tests/scripts/runtime_journal.test.ts:205,207`.
+ *
+ * Growing this list does NOT move {@link JOURNAL_SCHEMA_VERSION}: that covers
+ * tables and columns and a mismatch discards the store, while a widened value
+ * domain changes neither. The domain carries its own version in the registry
+ * (`RUN_TERMINAL_VOCABULARY_VERSION`), and the read path tolerates a value it
+ * does not know rather than trusting the column — see `toEvent`.
  */
 export const TERMINAL_STATES = RUN_TERMINAL_STATES;
 
@@ -1019,7 +1025,7 @@ export function recordEvent(h: JournalHandle, input: RecordEventInput): JournalE
         !(TERMINAL_STATES as readonly string[]).includes(input.terminal_state)
     ) {
         throw new JournalContractError(
-            `terminal_state ${JSON.stringify(input.terminal_state)} is not one of the six.`,
+            `terminal_state ${JSON.stringify(input.terminal_state)} is not in the run vocabulary.`,
         );
     }
     if (
@@ -1105,7 +1111,8 @@ function toEvent(r: Record<string, unknown>): JournalEvent {
         worktree_id: String(r['worktree_id']),
         at: String(r['at']),
         capability: String(r['capability']),
-        terminal_state: (r['terminal_state'] as TerminalState | null) ?? null,
+        // Tolerant, not a cast: a value this build cannot place reads as null.
+        terminal_state: readRunTerminalState(r['terminal_state']),
         return_ref: (r['return_ref'] as string | null) ?? null,
         verification_ref: (r['verification_ref'] as string | null) ?? null,
         consumption: (r['consumption'] as Consumption | null) ?? null,

package/src/scripts/check_agent_artifact_location.ts

@@ -0,0 +1,337 @@
+#!/usr/bin/env tsx
+/**
+ * Agent-artifact location guard — a roadmap-shaped file outside the roadmap root.
+ *
+ * WHAT IT PROTECTS, AND WHAT IT DOES NOT.
+ * ---------------------------------------
+ * This gate protects THIS repository, and only this one. A consumer repository
+ * never runs this repository's CI, so a gate scoped here protects the tree
+ * where the error is LEAST likely to occur — the observed failure was in a
+ * consumer project. That is not a reason to skip it, since the same mistake is
+ * possible here, but it IS a reason to write the limit down: a gate whose reach
+ * is not stated gets cited as broader than it is.
+ *
+ * The outward-facing half is `agent-config doctor --strict`, which already
+ * knows the consumer shape and can now return a non-zero exit.
+ *
+ * The constraint the detection rests on: every other mechanism that governs a
+ * roadmap is keyed on the roadmap root, so a file placed outside it is governed
+ * by nothing. This gate is the one that is keyed on the complement.
+ *
+ * WHY THE NAME TEST ALONE IS NOT THE DETECTOR.
+ * -------------------------------------------
+ * `is_roadmap_candidate` is IMPORTED from `update_roadmap_progress` rather than
+ * mirrored locally, the way `check_estate_count.ts` does it — one definition of
+ * what counts, so the roadmap corpus and this guard cannot drift apart.
+ *
+ * But that function answers "is this filename eligible to be a roadmap inside
+ * the roadmap root", and its answer over an arbitrary tree is YES for nearly
+ * every `.md` file: it excludes four names and one prefix and otherwise accepts
+ * anything. Run bare over this repository it would report thousands of
+ * legitimate documents. So the name test is a PRE-FILTER, and the decision is
+ * made by {@link roadmapShape}, which reads the file: roadmap frontmatter plus a
+ * `## Phase` heading plus at least one checkbox step. All three, because each
+ * alone is common — plenty of documents carry frontmatter, and a design doc can
+ * carry checkboxes.
+ *
+ * The finding NAMES the signals that fired, so a false positive is arguable
+ * rather than mysterious. A document that trips this gate and should not is a
+ * conversation about the signals, which is the conversation worth having.
+ *
+ * Exit codes: 0 = clean · 1 = a roadmap-shaped file sits outside the root · 3 = internal error.
+ */
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { is_roadmap_candidate as isRoadmapCandidate } from '../agent-src/scripts/update_roadmap_progress.js';
+import { reportScanned, DeadScopeError } from './_lib/scan_scope.js';
+import { runGateCli, runSelfTest, type SelfTestCase } from './_lib/gate_self_test.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+/** The one legitimate home. Everything else is a finding. */
+export const ROADMAP_ROOT_REL = 'agents/roadmaps';
+
+/**
+ * Directories the walk never enters.
+ *
+ * `dist/` and the per-tool projection trees are generated copies — a finding
+ * there is a finding about `src/`, reported twice. `node_modules` and `.git`
+ * are not this repository's prose.
+ */
+const SKIP_DIRS: ReadonlySet<string> = new Set([
+    '.git',
+    'node_modules',
+    'dist',
+    '.augment',
+    '.claude',
+    '.cursor',
+    '.clinerules',
+    '.agents',
+    'coverage',
+    '.venv',
+]);
+
+/** Frontmatter keys that only a roadmap carries in this tree. */
+const FM_ROADMAP_RE = /^complexity:[ \t]*(lightweight|structural)[ \t]*$/m;
+const FM_RE = /^---\n([\s\S]*?)\n---/;
+const PHASE_RE = /^##[ \t]+Phase[ \t]/m;
+const CHECKBOX_RE = /^[ \t]*- \[[ x~-]\][ \t]/m;
+
+export interface Shape {
+    /** Which signals fired. Empty means not roadmap-shaped. */
+    readonly signals: readonly string[];
+    readonly isRoadmap: boolean;
+}
+
+/**
+ * Decide whether a file's CONTENT is a roadmap.
+ *
+ * All three signals are required. Each is individually common; together they are
+ * this repository's roadmap format and nothing else's.
+ */
+export function roadmapShape(text: string): Shape {
+    const signals: string[] = [];
+    const fm = FM_RE.exec(text);
+    if (fm !== null && FM_ROADMAP_RE.test(fm[1] as string)) {
+        signals.push('roadmap frontmatter (`complexity:` lightweight|structural)');
+    }
+    if (PHASE_RE.test(text)) {
+        signals.push('a `## Phase` heading');
+    }
+    if (CHECKBOX_RE.test(text)) {
+        signals.push('at least one checkbox step');
+    }
+    return { signals, isRoadmap: signals.length === 3 };
+}
+
+export interface Finding {
+    readonly rel: string;
+    readonly signals: readonly string[];
+}
+
+export interface ScanResult {
+    readonly findings: readonly Finding[];
+    /** Every `.md` file the walk visited — the scope, not the matches. */
+    readonly scanned: number;
+}
+
+function walkMarkdown(root: string): string[] {
+    const out: string[] = [];
+    const stack = [root];
+    while (stack.length > 0) {
+        const cur = stack.pop() as string;
+        let entries: fs.Dirent[];
+        try {
+            entries = fs.readdirSync(cur, { withFileTypes: true });
+        } catch {
+            continue;
+        }
+        for (const e of entries) {
+            if (e.isSymbolicLink()) continue;
+            const full = path.join(cur, e.name);
+            if (e.isDirectory()) {
+                if (!SKIP_DIRS.has(e.name)) stack.push(full);
+            } else if (e.name.toLowerCase().endsWith('.md')) {
+                out.push(full);
+            }
+        }
+    }
+    return out.sort();
+}
+
+/** `true` when `child` is at or below `root`. */
+function isUnder(child: string, root: string): boolean {
+    const rel = path.relative(root, child);
+    return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+
+export function scan(root: string): ScanResult {
+    const roadmapRoot = path.join(root, ...ROADMAP_ROOT_REL.split('/'));
+    const files = walkMarkdown(root);
+    const findings: Finding[] = [];
+    for (const f of files) {
+        if (isUnder(f, roadmapRoot)) continue;
+        // Cheap name pre-filter first — the SHARED definition, imported, so the
+        // roadmap corpus and this guard cannot drift apart.
+        if (!isRoadmapCandidate(f)) continue;
+        let text: string;
+        try {
+            text = fs.readFileSync(f, 'utf-8');
+        } catch {
+            continue;
+        }
+        const shape = roadmapShape(text);
+        if (!shape.isRoadmap) continue;
+        findings.push({
+            rel: path.relative(root, f).split(path.sep).join('/'),
+            signals: shape.signals,
+        });
+    }
+    return { findings, scanned: files.length };
+}
+
+interface Args {
+    quiet: boolean;
+    selfTest: boolean;
+    root: string;
+}
+
+function parseArgs(argv: readonly string[]): Args {
+    const args: Args = { quiet: false, selfTest: false, root: REPO_ROOT };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i] as string;
+        if (a === '--quiet') args.quiet = true;
+        else if (a === '--self-test') args.selfTest = true;
+        else if (a === '--root') args.root = path.resolve(argv[++i] ?? '.');
+        else if (a === '-h' || a === '--help') {
+            process.stdout.write(
+                'usage: check_agent_artifact_location [-h] [--quiet] [--root DIR] [--self-test]\n',
+            );
+            process.exit(0);
+        } else {
+            process.stderr.write(
+                `check_agent_artifact_location: error: unrecognized arguments: ${a}\n`,
+            );
+            process.exit(2);
+        }
+    }
+    return args;
+}
+
+/** A minimal file with all three shape signals. */
+const ROADMAP_FIXTURE =
+    '---\ncomplexity: lightweight\nstatus: ready\n---\n' +
+    '# Road to a fixture\n\n## Phase 1 - a phase\n\n- [ ] **1.1 A step.**\n';
+
+/** Same content, but not roadmap-shaped — frontmatter only. */
+const PROSE_FIXTURE = '---\ntitle: a design note\n---\n\n# A design note\n\n- [ ] a todo\n';
+
+function selfTestCases(): SelfTestCase[] {
+    const mk = (rel: string, body: string): string => {
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'artloc-'));
+        const full = path.join(dir, ...rel.split('/'));
+        fs.mkdirSync(path.dirname(full), { recursive: true });
+        fs.writeFileSync(full, body);
+        return dir;
+    };
+    const run = (dir: string): number =>
+        runGateCli(
+            REPO_ROOT,
+            'src/scripts/check_agent_artifact_location.ts',
+            ['--root', dir, '--quiet'],
+            REPO_ROOT,
+        );
+    return [
+        {
+            name: 'a roadmap-shaped file under docs/roadmaps/ is reported',
+            expect: 'reject',
+            run: () => run(mk('docs/roadmaps/road-to-a-fixture.md', ROADMAP_FIXTURE)),
+        },
+        {
+            name: 'a roadmap-shaped file at the tree root is reported',
+            expect: 'reject',
+            run: () => run(mk('road-to-a-fixture.md', ROADMAP_FIXTURE)),
+        },
+        {
+            name: 'the SAME file under agents/roadmaps/ is not reported',
+            expect: 'accept',
+            run: () => run(mk('agents/roadmaps/road-to-a-fixture.md', ROADMAP_FIXTURE)),
+        },
+        {
+            name: 'a file under agents/roadmaps/later/ is not reported',
+            expect: 'accept',
+            run: () => run(mk('agents/roadmaps/later/road-to-a-fixture.md', ROADMAP_FIXTURE)),
+        },
+        {
+            name: 'prose carrying frontmatter and a checkbox but no phase is not reported',
+            expect: 'accept',
+            run: () => run(mk('docs/a-design-note.md', PROSE_FIXTURE)),
+        },
+    ];
+}
+
+export function main(argv?: readonly string[]): number {
+    const args = parseArgs(argv ?? process.argv.slice(2));
+
+    if (args.selfTest) {
+        return runSelfTest({
+            gate: 'check_agent_artifact_location',
+            cases: selfTestCases(),
+            minCases: 5,
+            minRejectCases: 2,
+        });
+    }
+
+    let result: ScanResult;
+    try {
+        result = scan(args.root);
+    } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        process.stderr.write(`❌  internal error: ${msg}\n`);
+        return 3;
+    }
+
+    // The unit is every `.md` the walk VISITED, not the matches: zero matches is
+    // the normal clean state, so only the unfiltered walk can tell "nothing
+    // misplaced" from "nothing read".
+    try {
+        reportScanned({
+            gate: 'check_agent_artifact_location',
+            scanned: result.scanned,
+            units: 'markdown file(s)',
+            roots: [path.relative(REPO_ROOT, args.root) || '.'],
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 1;
+        }
+        throw exc;
+    }
+
+    if (result.findings.length === 0) {
+        if (!args.quiet) {
+            process.stdout.write(
+                `✅  check_agent_artifact_location: no roadmap-shaped file outside ` +
+                    `${ROADMAP_ROOT_REL}/ (${String(result.scanned)} markdown file(s) read).\n`,
+            );
+        }
+        return 0;
+    }
+
+    process.stderr.write(
+        `❌  check_agent_artifact_location: ${String(result.findings.length)} ` +
+            `roadmap-shaped file(s) outside ${ROADMAP_ROOT_REL}/:\n`,
+    );
+    for (const f of result.findings) {
+        process.stderr.write(`    ${f.rel}\n`);
+        process.stderr.write(`      reads as a roadmap because it carries ${f.signals.join(', ')}\n`);
+    }
+    process.stderr.write(
+        `    Move it to ${ROADMAP_ROOT_REL}/, or — if it is genuinely not a roadmap — ` +
+            'say which of the three signals it should not be carrying.\n' +
+            '    NOTE: this gate scans THIS repository only. A consumer project never runs\n' +
+            '    it; `agent-config doctor` is the surface that carries a finding outward.\n',
+    );
+    return 1;
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) return false;
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) return true;
+    try {
+        return fs.realpathSync(_HERE) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    process.exit(main());
+}