@event4u/agent-config 16.5.0 → 17.0.0

package/src/scripts/measure_skill_ranker_baseline.ts

@@ -52,7 +52,9 @@ import { fileURLToPath } from 'node:url';
 
 import { wilsonInterval } from './_lib/capture_rate.js';
 import { fnv1a } from './_lib/fnv.js';
+import { corpusSkills, loadTrainCases } from './_lib/routing_corpus.js';
 import { rank } from './skill_tools/score_skill_relevance.js';
+import type { RankRow } from './skill_tools/score_skill_relevance.js';
 import type { RankOptions } from '../shared/skillRanking.js';
 
 export const REPO = path.resolve(fileURLToPath(import.meta.url), '..', '..', '..');
@@ -535,6 +537,192 @@ export function rankOptionsFor(ranker: string): RankOptions {
     return RANKER_LABELS[ranker] as RankOptions;
 }
 
+/**
+ * The second corpus this script can read, and the only one it reads by SKILL
+ * rather than by hand-written label.
+ *
+ * It is deliberately NOT a fourth `CorpusName`. The three names above all feed
+ * `measureAccuracy`, which answers "is the owning skill in the top 1 or top 3"
+ * over prompts somebody labelled with an expected-skills list. The trigger
+ * corpus answers a different question — "how deep must the answer be returned
+ * before the owning skill is in it" — over cases whose ground truth is the
+ * directory the corpus file sits in. Folding it into `CorpusName` would have
+ * put a case into `promptsForCorpus`, `DENOMINATOR_NOTES` and the pack census
+ * that none of them can answer, so the argument is a union of two kinds and
+ * `main` branches on it once.
+ */
+export const TRIGGERS_TRAIN = 'triggers-train';
+export type CorpusArg = CorpusName | typeof TRIGGERS_TRAIN;
+
+/**
+ * The depths printed. 1 and 3 so the arm is comparable with the accuracy arm,
+ * 5 because that was the shipped default `limit` the bar is measured against,
+ * and 8, 10, 20 because the question this arm exists to answer is how much
+ * recall a deeper default would buy. 8 is the default it selected
+ * (`DEFAULT_SUGGEST_LIMIT` in `src/shared/skillRanking.ts`, which records the
+ * pre-registered bar).
+ */
+export const RECALL_DEPTHS: readonly number[] = [1, 3, 5, 8, 10, 20];
+
+/** The key a depth is printed under. `recall@8` is quoted by the roadmap's verify line. */
+export function recallKey(depth: number): string {
+    return `recall@${depth}`;
+}
+
+export interface RecallPoint {
+    hits: number;
+    rate: number;
+    ci95: Interval;
+}
+
+export interface RecallSplit {
+    /** The denominator: positive cases in this split. */
+    positives: number;
+    /**
+     * Positives whose owning skill scores nothing at all.
+     *
+     * `rank()` drops every row that scores 0, so "absent from the ranked rows"
+     * and "shares no indexed term and no persona with the prompt" are the same
+     * state. These are the cases no DEPTH can reach — counted separately so a
+     * reader never reads the gap between `recall@20` and 1.0 as a ranking
+     * problem when part of it is a vocabulary problem.
+     */
+    zero_overlap: number;
+    recall: Record<string, RecallPoint>;
+}
+
+export interface NearMissArm {
+    cases: number;
+    first: number;
+    top3: number;
+    note: string;
+}
+
+export interface RecallReport {
+    schema: 1;
+    arm: 'recall-at-depth';
+    corpus: typeof TRIGGERS_TRAIN;
+    ranker: string;
+    commit: string;
+    skills_dir: string;
+    skills_indexed: number;
+    /** Train corpora read. The holdout ones are never opened — see `seal_note`. */
+    train_corpora: number;
+    cases_total: number;
+    positives: number;
+    negatives: number;
+    all: RecallSplit;
+    de: RecallSplit;
+    near_miss: NearMissArm;
+    seal_note: string;
+    denominator_note: string;
+}
+
+/**
+ * Where the owning skill sits in the ranked rows, 1-based, or `null` when it
+ * is not there at all.
+ *
+ * Computed ONCE per case and reused for every depth and for both splits. The
+ * alternative — one `rank()` call per depth — would read the catalogue from
+ * disk six times per prompt and could not be made to disagree with itself.
+ */
+export function depthOfOwner(rows: readonly RankRow[], skill: string): number | null {
+    for (let i = 0; i < rows.length; i += 1) {
+        if (rows[i]![0] === skill) return i + 1;
+    }
+    return null;
+}
+
+function splitOf(depths: readonly (number | null)[]): RecallSplit {
+    const n = depths.length;
+    const recall: Record<string, RecallPoint> = {};
+    for (const d of RECALL_DEPTHS) {
+        const hits = depths.filter((p) => p !== null && p <= d).length;
+        recall[recallKey(d)] = { hits, rate: n ? round3(hits / n) : 0, ci95: ci(hits, n) };
+    }
+    return { positives: n, zero_overlap: depths.filter((p) => p === null).length, recall };
+}
+
+/**
+ * Recall at depth over the TRAIN slice of the per-skill trigger corpus.
+ *
+ * Ground truth is the directory the case was read from, so there is no label to
+ * disagree with. The seal is inherited rather than re-implemented:
+ * `loadTrainCases` decides the partition from the directory NAME and skips a
+ * holdout path before any read, so this arm cannot open one even by mistake.
+ */
+export function measureRecallAtDepth(opts: {
+    ranker: string;
+    commit: string;
+    repo?: string;
+    skillsDir?: string;
+}): RecallReport {
+    const repo = opts.repo ?? REPO;
+    const skillsDir = opts.skillsDir ?? path.join(repo, 'src', 'skills');
+    const rankOpts = rankOptionsFor(opts.ranker);
+
+    const cases = loadTrainCases(repo);
+    const positives: (number | null)[] = [];
+    const dePositives: (number | null)[] = [];
+    let nearMissCases = 0;
+    let nearMissFirst = 0;
+    let nearMissTop3 = 0;
+
+    for (const c of cases) {
+        const at = depthOfOwner(rank(c.prompt, skillsDir, rankOpts), c.skill);
+        if (c.expect) {
+            positives.push(at);
+            if (c.language === 'de') dePositives.push(at);
+            continue;
+        }
+        if (c.caseClass === 'near-miss') {
+            nearMissCases++;
+            if (at === 1) nearMissFirst++;
+            if (at !== null && at <= 3) nearMissTop3++;
+        }
+    }
+
+    const skillsIndexed = fs.existsSync(skillsDir)
+        ? fs.readdirSync(skillsDir).filter((s) => fs.existsSync(path.join(skillsDir, s, 'SKILL.md'))).length
+        : 0;
+
+    return {
+        schema: 1,
+        arm: 'recall-at-depth',
+        corpus: TRIGGERS_TRAIN,
+        ranker: opts.ranker,
+        commit: opts.commit,
+        skills_dir: path.relative(repo, skillsDir),
+        skills_indexed: skillsIndexed,
+        train_corpora: corpusSkills(repo).filter((s) => s.partition === 'train').length,
+        cases_total: cases.length,
+        positives: positives.length,
+        negatives: cases.length - positives.length,
+        all: splitOf(positives),
+        de: splitOf(dePositives),
+        near_miss: {
+            cases: nearMissCases,
+            first: nearMissFirst,
+            top3: nearMissTop3,
+            note:
+                'Cases the corpus declares `class: near-miss`. Every one of them is a NEGATIVE ' +
+                '(`trigger: false`), so `first` and `top3` are false-positive counts, not hits — ' +
+                'lower is better, and they are printed beside recall so a depth change cannot be ' +
+                'read as free.',
+        },
+        seal_note:
+            'The sealed holdout corpora are never opened: `routing_corpus.loadTrainCases` decides ' +
+            'the partition from the skill DIRECTORY NAME and skips a holdout path before reading ' +
+            'any file. Filtering after the read would satisfy the letter of the freeze and not ' +
+            'the seal.',
+        denominator_note:
+            'Positive cases of the TRAIN slice of `src/skills/*/evals/triggers.json`. The owning ' +
+            'skill is the directory the case was read from, so no expected-skills label is ' +
+            'involved and none can be stale. `recall@k` is the share of positives whose owning ' +
+            'skill appears within the first k ranked rows.',
+    };
+}
+
 export function measure(opts: {
     ranker: string;
     commit: string;
@@ -588,13 +776,14 @@ export function measure(opts: {
     };
 }
 
-function parseCorpus(argv: readonly string[]): CorpusName {
+export function parseCorpus(argv: readonly string[]): CorpusArg {
     const i = argv.indexOf('--corpus');
     if (i === -1) return 'labelled';
     const raw = argv[i + 1];
+    if (raw === TRIGGERS_TRAIN) return TRIGGERS_TRAIN;
     if (!raw || !CORPUS_NAMES.includes(raw as CorpusName)) {
         throw new Error(
-            `measure_skill_ranker_baseline: --corpus expects one of ${CORPUS_NAMES.join(' | ')}, got ${raw ?? '(nothing)'}`,
+            `measure_skill_ranker_baseline: --corpus expects one of ${[...CORPUS_NAMES, TRIGGERS_TRAIN].join(' | ')}, got ${raw ?? '(nothing)'}`,
         );
     }
     return raw as CorpusName;
@@ -653,11 +842,11 @@ export function parseSlice(argv: readonly string[]): SliceName {
 }
 
 export function main(argv: readonly string[]): number {
-    let corpus: CorpusName;
+    let corpus: CorpusArg;
     let slice: SliceName;
     let ranker: string;
     let commit: string;
-    let out: RankerBaseline;
+    let out: RankerBaseline | RecallReport;
     try {
         corpus = parseCorpus(argv);
         slice = parseSlice(argv);
@@ -665,7 +854,16 @@ export function main(argv: readonly string[]): number {
         commit = parseFlagValue(argv, '--commit', 'unknown');
         // Inside the same guard as the two parsers above: an unknown --ranker is
         // the same class of mistake and now gets the same exit code.
-        out = measure({ ranker, commit, corpus, slice });
+        //
+        // `--slice` is PARSED on this branch and then unused, deliberately: the
+        // trigger corpus carries its own frozen train/holdout partition, so the
+        // accuracy arm's tuning/sealed division does not apply to it. Parsing it
+        // anyway keeps a malformed `--slice` an error here too rather than a
+        // value silently ignored only on this corpus.
+        out =
+            corpus === TRIGGERS_TRAIN
+                ? measureRecallAtDepth({ ranker, commit })
+                : measure({ ranker, commit, corpus, slice });
     } catch (err) {
         process.stderr.write(`${(err as Error).message}\n`);
         return 2;

package/src/scripts/measure_turn_end_gate.ts

@@ -178,6 +178,15 @@ interface Counts {
      * the pointer that makes a human read possible ships with it.
      */
     dropped_sites: { session: string; turn: number; evidence: string }[];
+    /**
+     * C's fires split by what the turn edited (road-to-agent-throughput-recovery
+     * 4.2): whether a docs-only exemption is worth proposing turns on how many
+     * fires edited nothing but `agents/**` or `docs/**` markdown. The rows sum to
+     * `unverified_fires`; a fire with no recorded path is `unknown`.
+     */
+    unverified_by_path_class: Record<EditPathClass, number>;
+    /** Where C fired, with the class only — never the path. */
+    unverified_sites: { session: string; turn: number; path_class: EditPathClass }[];
     /** The independent scanner's own per-session language total, for context. */
     scanner_language: number;
     sessions: number;
@@ -208,6 +217,31 @@ const _TEST_DIR_RE = /(?:^|\/)(?:tests?|specs?|__tests__|__specs__|e2e|cypress|p
 const _TEST_FILE_RE =
     /(?:\.(?:test|spec)\.[a-z]+$)|(?:_test\.[a-z]+$)|(?:(?:^|\/)test_[^/]+$)|(?:Test\.php$)|(?:Spec\.php$)|(?:\.feature$)/i;
 
+export const EDIT_PATH_CLASSES = ['docs-md', 'code', 'mixed', 'unknown'] as const;
+export type EditPathClass = (typeof EDIT_PATH_CLASSES)[number];
+
+const _DOCS_MD_RE = /(?:^|\/)(?:agents|docs)\/.*\.md$/i;
+const _ROOT_DOCS_MD_RE = /^(?:agents|docs)\/.*\.md$/i;
+
+/**
+ * `docs-md` when every edited path is `agents/**` or `docs/**` markdown at the
+ * repository root. With the session's `root` known an absolute path is judged
+ * relative to it, so `src/agents/x.md` or `node_modules/p/docs/y.md` is not
+ * docs; without it the segment match is the only reading available.
+ */
+export function editPathClass(paths: readonly string[], root?: string): EditPathClass {
+    if (paths.length === 0) return 'unknown';
+    const isDocs = (p: string): boolean => {
+        if (root === undefined) return _DOCS_MD_RE.test(p);
+        const prefix = root.endsWith('/') ? root : `${root}/`;
+        if (p.startsWith('/')) return p.startsWith(prefix) && _ROOT_DOCS_MD_RE.test(p.slice(prefix.length));
+        return _ROOT_DOCS_MD_RE.test(p);
+    };
+    const docs = paths.filter(isDocs).length;
+    if (docs === paths.length) return 'docs-md';
+    return docs === 0 ? 'code' : 'mixed';
+}
+
 function _looksTestPath(p: string): boolean {
     return _TEST_DIR_RE.test(p) || _TEST_FILE_RE.test(p);
 }
@@ -254,6 +288,8 @@ export function measure(store: string, limit: number): Counts {
         e2_no_test_touched: 0,
         untested_sites: [],
         dropped_sites: [],
+        unverified_by_path_class: { 'docs-md': 0, code: 0, mixed: 0, unknown: 0 },
+        unverified_sites: [],
         scanner_language: 0,
         sessions: 0,
     };
@@ -311,6 +347,9 @@ export function measure(store: string, limit: number): Counts {
         // trade taken: the closing reply the two instruments score stays
         // identical, which is the property the rest of this script rests on.
         let pendingTexts: string[] = [];
+        // The session's working directory as the transcript records it — the
+        // root `editPathClass` judges an absolute edited path against.
+        let sessionRoot: string | undefined;
         // Per-SESSION, because that is the only ordinal a reader can use to find
         // the turn again. `c.turns` is the corpus-wide running total, and
         // labelling it "turn" in a per-session pointer sends the reader to the
@@ -329,7 +368,17 @@ export function measure(store: string, limit: number): Counts {
             // 2026-09-11, holding F's finding in a file that also names a
             // detector E — the same mislabel that reached a commit title.
             const fFinding = detectUntestedChange(pendingReply, pendingCalls);
-            if (cFired) c.unverified_fires += 1;
+            if (cFired) {
+                c.unverified_fires += 1;
+                const cls = editPathClass(
+                    pendingCalls
+                        .filter((call) => _EDIT_TOOL_NAMES.has(call.name) && call.path !== undefined)
+                        .map((call) => call.path as string),
+                    sessionRoot,
+                );
+                c.unverified_by_path_class[cls] += 1;
+                c.unverified_sites.push({ session: sessionId, turn: sessionTurn, path_class: cls });
+            }
             if (fFinding !== null) {
                 c.untested_fires += 1;
                 if (!cFired) c.untested_c_silent += 1;
@@ -370,6 +419,7 @@ export function measure(store: string, limit: number): Counts {
             } catch {
                 continue;
             }
+            if (sessionRoot === undefined && typeof entry['cwd'] === 'string' && entry['cwd'] !== '') sessionRoot = entry['cwd'];
 
             const u = _userTurnText(entry);
             if (u !== null) {
@@ -446,6 +496,14 @@ export function renderFires(c: Counts): string {
         .join('\n');
 }
 
+/** C's fires with their edited-path class, for the 4.2 table. */
+export function renderUnverifiedFires(c: Counts): string {
+    if (c.unverified_sites.length === 0) return '  detector C fired on no turn in this corpus.';
+    return c.unverified_sites
+        .map((site) => `  ${site.session} turn ${String(site.turn)} — ${site.path_class}`)
+        .join('\n');
+}
+
 /**
  * E's fires, as a separate function rather than a widened `renderFires`: the
  * two lists answer different questions and a caller printing one must not
@@ -466,6 +524,7 @@ export function render(c: Counts): string {
         `  detector A (promissory)  fires on ${c.promissory_fires} turns  (${pct(c.promissory_fires)}%)`,
         `  detector B (language)    fires on ${c.language_fires} turns  (${pct(c.language_fires)}%)`,
         `  detector C (unverified)  fires on ${c.unverified_fires} turns  (${pct(c.unverified_fires)}%)`,
+        ...EDIT_PATH_CLASSES.map((k) => `    by edited path: ${k.padEnd(10)}${String(c.unverified_by_path_class[k])}`),
         `  detector E (dropped)     fires on ${c.dropped_fires} turns  (${pct(c.dropped_fires)}%)`,
         `  detector F (untested)    fires on ${c.untested_fires} turns  (${pct(c.untested_fires)}%)`,
         '',
@@ -729,6 +788,7 @@ export function main(argv: string[] = process.argv.slice(2)): number {
     if (showFires) {
         process.stdout.write(`\n  detector F fired here — read these turns before\n  calling any of them a false positive:\n${renderFires(counts)}\n`);
         process.stdout.write(`\n  detector E fired here — same reading, same reason:\n${renderDroppedFires(counts)}\n`);
+        process.stdout.write(`\n  detector C fired here, with the edited-path class:\n${renderUnverifiedFires(counts)}\n`);
     }
     return 0;
 }

package/src/scripts/merge_clearance.ts

@@ -0,0 +1,225 @@
+#!/usr/bin/env node
+/**
+ * Write and check the merge clearance a `needs-council` pull request needs.
+ *
+ *   merge_clearance write --pr N --head SHA --base SHA
+ *                         --classification FILE --session FILE --prompt FILE
+ *   merge_clearance --check N [--head SHA]
+ *
+ * `write` reads the seats from the council's saved session record and the
+ * verdict from the danger gate's output; it takes no verdict from the command
+ * line. It refuses a classification other than `needs-council` — `routine`
+ * needs no clearance and `needs-owner` is never sent for one — and a session
+ * whose `artefact` is not the prompt file given, so the prompt digest names
+ * what the seats were actually asked. It also refuses a prompt that does not
+ * fence the diff between the untrusted-data markers, under the notice that the
+ * content inside is data and not instructions (`checkPromptFraming`).
+ *
+ * `--check` exits 0 only when the record named for the pull request's live
+ * head exists, parses, re-derives to `cleared` under the committed quorum
+ * policy, and names that pull request and head. `--head` additionally pins the
+ * head the caller recorded; a live head that moved away from it fails.
+ *
+ * The record shape and every derivation live in `_lib/merge_clearance_record.ts`.
+ *
+ * Exit codes: 0 = written / cleared · 1 = not cleared · 2 = usage or input error.
+ */
+
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import {
+    CLEARANCE_DIR,
+    checkPromptFraming,
+    clearanceFileName,
+    deriveOutcome,
+    parseClearance,
+    readNeedsCouncilLine,
+    renderClearance,
+    seatsFromSession,
+    sha256,
+} from './_lib/merge_clearance_record.js';
+import { readRequiredProviders } from './_lib/ratification_artifact.js';
+
+const POLICY_PATH = 'src/config/ratification-policy.json';
+const SHA40_RE = /^[0-9a-f]{40}$/u;
+
+type Out = (line: string) => void;
+
+function argValue(argv: readonly string[], flag: string): string | null {
+    const i = argv.indexOf(flag);
+    if (i === -1) return null;
+    const v = argv[i + 1];
+    return v === undefined || v.startsWith('--') ? null : v;
+}
+
+function readPolicy(root: string): number | null {
+    try {
+        return readRequiredProviders(fs.readFileSync(path.join(root, POLICY_PATH), 'utf8'));
+    } catch {
+        return null;
+    }
+}
+
+function prNumber(raw: string | null): number | null {
+    return raw !== null && /^[1-9][0-9]*$/u.test(raw) ? Number(raw) : null;
+}
+
+export function writeClearance(argv: readonly string[], root: string, out: Out): number {
+    const pr = prNumber(argValue(argv, '--pr'));
+    const head = argValue(argv, '--head') ?? '';
+    const base = argValue(argv, '--base') ?? '';
+    const classification = argValue(argv, '--classification');
+    const sessionPath = argValue(argv, '--session');
+    const promptPath = argValue(argv, '--prompt');
+    if (pr === null || !SHA40_RE.test(head) || !SHA40_RE.test(base) || !classification || !sessionPath || !promptPath) {
+        out('merge_clearance: write needs --pr N, full --head and --base, --classification, --session and --prompt');
+        return 2;
+    }
+    const required = readPolicy(root);
+    if (required === null) {
+        out(`merge_clearance: ${POLICY_PATH} is missing or unreadable — refusing to derive an outcome`);
+        return 2;
+    }
+    let lastLine: string;
+    let session: unknown;
+    let prompt: string;
+    try {
+        const lines = fs.readFileSync(classification, 'utf8').trimEnd().split('\n');
+        lastLine = lines[lines.length - 1] ?? '';
+        session = JSON.parse(fs.readFileSync(sessionPath, 'utf8')) as unknown;
+        prompt = fs.readFileSync(promptPath, 'utf8');
+    } catch (exc) {
+        out(`merge_clearance: cannot read an input — ${String(exc)}`);
+        return 2;
+    }
+    const triggers = readNeedsCouncilLine(lastLine);
+    if (triggers === null) {
+        out(`merge_clearance: the classification's last line is not \`verdict: needs-council (…)\`: ${lastLine}`);
+        return 2;
+    }
+    const framing = checkPromptFraming(prompt);
+    if (framing !== null) {
+        out(`merge_clearance: the prompt does not fence the diff as untrusted data — ${framing}`);
+        return 2;
+    }
+    const artefact = (session as { artefact?: unknown } | null)?.artefact;
+    if (typeof artefact !== 'string' || path.resolve(root, artefact) !== path.resolve(root, promptPath)) {
+        out(`merge_clearance: the session's artefact (${String(artefact)}) is not the prompt file ${promptPath}`);
+        return 2;
+    }
+    const seats = seatsFromSession(session);
+    if (typeof seats === 'string') {
+        out(`merge_clearance: ${seats}`);
+        return 2;
+    }
+    const outcome = deriveOutcome(seats, required);
+    const body = renderClearance({
+        pr,
+        head,
+        base,
+        classifierVerdict: 'needs-council',
+        triggers,
+        promptSha256: sha256(prompt),
+        seats,
+        outcome,
+    });
+    const rel = path.posix.join(CLEARANCE_DIR, clearanceFileName(pr, head));
+    fs.mkdirSync(path.join(root, CLEARANCE_DIR), { recursive: true });
+    fs.writeFileSync(path.join(root, rel), body, 'utf8');
+    out(`merge_clearance: wrote ${rel}`);
+    out(`outcome: ${outcome}`);
+    return 0;
+}
+
+/** The pull request's live head, from the forge. `null` on any failure. */
+export function liveHeadFromForge(pr: number): string | null {
+    const r = spawnSync('gh', ['pr', 'view', String(pr), '--json', 'headRefOid', '--jq', '.headRefOid'], {
+        encoding: 'utf8',
+    });
+    const v = r.status === 0 && typeof r.stdout === 'string' ? r.stdout.trim() : '';
+    return SHA40_RE.test(v) ? v : null;
+}
+
+export function checkClearance(
+    opts: { pr: number; liveHead: string | null; pinnedHead: string | null; root: string },
+    out: Out,
+): number {
+    const { pr, liveHead, pinnedHead, root } = opts;
+    if (liveHead === null) {
+        out(`merge_clearance: not cleared — the live head of #${String(pr)} could not be read`);
+        return 1;
+    }
+    if (pinnedHead !== null && pinnedHead !== liveHead) {
+        out(`merge_clearance: not cleared — the live head ${liveHead} is not the recorded head ${pinnedHead}`);
+        return 1;
+    }
+    const required = readPolicy(root);
+    if (required === null) {
+        out(`merge_clearance: not cleared — ${POLICY_PATH} is missing or unreadable`);
+        return 1;
+    }
+    const rel = path.posix.join(CLEARANCE_DIR, clearanceFileName(pr, liveHead));
+    let text: string;
+    try {
+        text = fs.readFileSync(path.join(root, rel), 'utf8');
+    } catch {
+        out(`merge_clearance: not cleared — no record ${rel} for the live head`);
+        return 1;
+    }
+    const parsed = parseClearance(text, required);
+    if (Array.isArray(parsed)) {
+        out(`merge_clearance: not cleared — ${rel} does not parse:`);
+        for (const p of parsed) out(`  ${p}`);
+        return 1;
+    }
+    if (parsed.pr !== pr || parsed.head !== liveHead) {
+        out(`merge_clearance: not cleared — ${rel} names #${String(parsed.pr)} at ${parsed.head}`);
+        return 1;
+    }
+    if (parsed.outcome !== 'cleared') {
+        out(`merge_clearance: not cleared — ${rel} records \`${parsed.outcome}\``);
+        return 1;
+    }
+    out(`merge_clearance: cleared — #${String(pr)} at ${liveHead}`);
+    return 0;
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2), out: Out = (l) => process.stdout.write(`${l}\n`)): number {
+    const root = process.cwd();
+    if (argv[0] === 'write') {
+        return writeClearance(argv.slice(1), root, out);
+    }
+    if (argv.includes('--check')) {
+        const pr = prNumber(argValue(argv, '--check'));
+        if (pr === null) {
+            out('merge_clearance: --check needs a pull request number');
+            return 2;
+        }
+        const pinned = argValue(argv, '--head');
+        if (pinned !== null && !SHA40_RE.test(pinned)) {
+            out('merge_clearance: --head must be a full 40-hex revision');
+            return 2;
+        }
+        return checkClearance({ pr, liveHead: liveHeadFromForge(pr), pinnedHead: pinned, root }, out);
+    }
+    out('usage: merge_clearance write --pr N --head SHA --base SHA --classification F --session F --prompt F');
+    out('       merge_clearance --check N [--head SHA]');
+    return 2;
+}
+
+function isCliEntry(): boolean {
+    if (process.argv[1] === undefined) return false;
+    if (import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) return true;
+    try {
+        return fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+
+if (isCliEntry()) {
+    process.exit(main());
+}

package/src/scripts/migrate_command_suggestions.ts

@@ -73,7 +73,7 @@ export const ELIGIBLE: Record<string, [string, string]> = {
         'audit my agent docs, check the state of the agents/ directory',
         'stale files under agents/ or recent edits to .augment/ without doc updates',
     ],
-    'analyze-repo': [
+    'analyze-reference': [
         "look at how X does this, compare with that other repo, study this competitor's approach",
         'external repo URL or path mentioned in the prompt',
     ],