@event4u/agent-config 14.6.0 → 14.8.0

package/src/install/ruleLayerPartition.ts

@@ -0,0 +1,212 @@
+/**
+ * The ADR-236 rule partition, decided per HOST directory on that host's own
+ * evidence.
+ *
+ * ## Why the decision moved from per-run to per-directory
+ *
+ * The filter used to sit in `condense.ts::_scoped_rule_basenames()`, which runs
+ * once per generation, so `partitionActive` — a claude-only fingerprint against
+ * `installed.lock` — decided for every host at once. That contradicted
+ * `partitionEligibility.ts`'s own fail-safe reasoning, which refuses to withhold a
+ * cursor artefact on claude's evidence because it "would deliver it nowhere", and
+ * it was measurably wrong in both directions on 2026-08-22 (partition ACTIVE,
+ * freshly generated worktree):
+ *
+ * ```
+ *   .claude/rules      13 files, 13 package-only,   0 global-only
+ *   .clinerules        14 files, 13 package-only,   0 global-only   ← narrowed on
+ *                                                                     borrowed evidence
+ *   .cursor/rules     126 files, 26 package-only, 100 global-only   ← never narrowed
+ *   .windsurf/rules   113 files, 13 package-only, 100 global-only   ← never narrowed
+ *   .augment/rules    118 files, 15 package-only, 103 global-only   ← never narrowed
+ * ```
+ *
+ * So the narrowing is per directory and gated on real evidence:
+ * {@link hostLayerCarries} reads that host's global directory and answers whether
+ * every name about to be withheld is actually there. No layer, an unreadable layer,
+ * or one missing a single name → the full projection is returned. A withhold now
+ * costs a directory read; the alternative cost a rule.
+ *
+ * ## Why it lives here rather than in condense.ts
+ *
+ * Four call sites consume it — the symlink emit plan, the cursor `.mdc` emitter,
+ * the windsurf emitter, the augment projector — and four sites deciding this
+ * separately is exactly how three of them came to disagree. It is in `src/install/`
+ * beside {@link partitionActive} and {@link hostLayerCarries}, the two predicates
+ * it composes, rather than in the 2,700-line generator that calls it.
+ *
+ * ## The classification source is the PROJECTION, not the authored tree
+ *
+ * `rulesSource` is `dist/agent-src/rules` at every call site, deliberately. A rule
+ * absent from `dist/` is compile-disabled and never projected, so it can be neither
+ * withheld nor duplicated — classifying from `src/rules` would count
+ * `telegraph-speak.md` (compile-disabled: 119 rules / 16 package-only in `src/`,
+ * 118 / 15 in `dist/`) and disagree with the emitter by exactly one file.
+ */
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+import { isExclusivelyPackageOnly, partitionActive } from './partitionEligibility.js';
+import { hostLayerCarries, toolIdForProjectRuleDir } from './globalRuleLayers.js';
+
+export interface PartitionRulesOptions {
+    /** Project-relative host directory, e.g. `.cursor/rules`. */
+    readonly toolDir: string;
+    /** Candidate rule basenames, already scope- and manual-filtered. */
+    readonly rules: readonly string[];
+    /** Absolute project root — what `partitionActive` verifies against. */
+    readonly projectRoot: string;
+    /** Absolute directory the basenames resolve against for classification. */
+    readonly rulesSource: string;
+    readonly userHome?: string;
+    /** Where the kept-full notice goes. Silent when omitted. */
+    readonly announce?: (message: string) => void;
+    /**
+     * Override the partition-active decision instead of reading `installed.lock`.
+     *
+     * Split out for the reason `partitionEligibility.ts` states about its own
+     * `personaWithheldFor`: "so the decision is testable in BOTH directions". A
+     * test over the un-injected path can only assert whatever the machine happens
+     * to be — and this one bit differs between a maintainer checkout (installed,
+     * so active) and CI (nothing installed, so inactive), which made the first
+     * version of `rule_partition_per_host.test.ts` green locally and red on every
+     * CI shard. That is the environment-dependent gate this whole change exists to
+     * remove, reproduced in its own test suite.
+     *
+     * Production callers omit it.
+     */
+    readonly active?: boolean;
+}
+
+/**
+ * Narrow one directory's rule list to the package-only set — but only when THIS
+ * host's global layer is verified to carry what would be withheld.
+ *
+ * Returns a copy of `rules` unchanged in every uncertain case. That direction is
+ * the whole design: an unnecessary duplicate costs context, a wrong withhold costs
+ * the rule.
+ */
+export function partitionRulesForDir(opts: PartitionRulesOptions): string[] {
+    const { toolDir, rules, projectRoot, rulesSource } = opts;
+    const active = opts.active ?? partitionActive(projectRoot);
+    if (!active) {
+        return [...rules];
+    }
+    const toolId = toolIdForProjectRuleDir(toolDir);
+    if (toolId === null) {
+        // An unmapped directory has no global layer this code can point at, so
+        // there is no evidence to withhold on.
+        return [...rules];
+    }
+    const packageOnly = rules.filter((r) => isExclusivelyPackageOnly(path.join(rulesSource, r)));
+    const keep = new Set(packageOnly);
+    const withheld = rules.filter((r) => !keep.has(r));
+    const home = opts.userHome ?? process.env['HOME'] ?? os.homedir();
+    const verdict = hostLayerCarries(toolId, withheld, home);
+    if (!verdict.carries) {
+        opts.announce?.(
+            `  ⚠️  ${toolDir}: full projection kept — ${toolId}'s global layer ${verdict.reason}` +
+                (verdict.missing.length > 0
+                    ? ` (${String(verdict.missing.length)} rule(s) not there, e.g. ` +
+                      `${verdict.missing.slice(0, 3).join(', ')})`
+                    : ''),
+        );
+        return [...rules];
+    }
+    return packageOnly;
+}
+
+// ── The older, weaker duplicate-avoidance mechanism ──────────────────────────
+//
+// `projection.scope_dedup` (default OFF) predates the partition and solves the
+// same problem with a narrower method: skip a project copy only when its
+// user-scope twin is BYTE-IDENTICAL. It moved here from condense.ts alongside the
+// partition because the two are one subject — a reader deciding how a duplicate is
+// avoided should find both in one file rather than one here and one in a
+// 2,700-line generator. Behaviour is unchanged; only `MODULE_STATE` reads became
+// parameters.
+
+/** `fs.statSync(p).isFile()`, false on any error — condense.ts's `_isFile`. */
+function isFile(p: string): boolean {
+    try {
+        return fs.statSync(p).isFile();
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Per-tool user-scope rule directory, for the scope-dedup below. Only tools
+ * whose host reads a user-scope rules directory can have a redundant twin;
+ * everything else has nothing to de-duplicate against.
+ */
+const USER_SCOPE_RULE_DIRS: Readonly<Record<string, string>> = {
+    '.claude/rules': path.join('.claude', 'rules'),
+};
+
+/**
+ * Rules whose user-scope twin is BYTE-IDENTICAL to the source, i.e. safe to
+ * skip at project scope: the host still loads the same text, once instead of
+ * twice, so nothing the model sees changes.
+ *
+ * Byte-identity is the whole safety argument and is not negotiable. Keying on
+ * the filename alone would silently let a stale globally-installed copy win
+ * whenever the two scopes hold different versions — which is the NORMAL state
+ * while developing the package (measured: 110/110 shared filenames differing in
+ * bytes). This is deliberately not the thin-projection mechanism: no rule
+ * becomes trigger-gated, so the quality floor that disabled thin projection
+ * does not apply here.
+ */
+export interface DedupOptions {
+    readonly toolDir: string;
+    readonly rules: readonly string[];
+    readonly userHome: string;
+    /** Absolute directory the basenames resolve against, for the byte compare. */
+    readonly rulesSource: string;
+    readonly announce?: (message: string) => void;
+}
+
+export function dedupableRules(opts: DedupOptions): Set<string> {
+    const { toolDir: tool_dir, rules, userHome, rulesSource } = opts;
+    const relative = USER_SCOPE_RULE_DIRS[tool_dir];
+    if (relative === undefined) {
+        return new Set();
+    }
+    // A hostile or simply absent $HOME must make the dedup inert, not
+    // adventurous. In a container `$HOME` is often unset (so `homedir()` can
+    // resolve to `/`) or world-writable, and this function decides which rules
+    // to STOP emitting — reading an unexpected tree there is how a projection
+    // silently loses a rule. Council review of PR #1055 raised exactly this.
+    let userDirStat: fs.Stats;
+    const userDir = path.join(userHome, relative);
+    try {
+        userDirStat = fs.statSync(userDir);
+    } catch {
+        return new Set();
+    }
+    if (!userDirStat.isDirectory()) {
+        return new Set();
+    }
+    // World-writable user scope: anyone on the box could plant a byte-identical
+    // twin and thereby delete a rule from the project projection. Refuse.
+    if ((userDirStat.mode & 0o002) !== 0) {
+        opts.announce?.(`  ⚠️  ${tool_dir}: user-scope rules dir is world-writable — scope-dedup skipped`);
+        return new Set();
+    }
+    const skip = new Set<string>();
+    for (const rule of rules) {
+        const twin = path.join(userDir, rule);
+        const source = path.join(rulesSource, rule);
+        try {
+            if (!isFile(twin) || !isFile(source)) continue;
+            if (fs.readFileSync(twin).equals(fs.readFileSync(source))) {
+                skip.add(rule);
+            }
+        } catch {
+            // An unreadable twin is simply not de-duplicable — emit the project copy.
+        }
+    }
+    return skip;
+}

package/src/scripts/_cli/cmd_adr_effective.ts

@@ -0,0 +1,484 @@
+/**
+ * `agent-config adr:effective ADR-NNN` — the effective state of one decision.
+ *
+ * Step 2.2 of `road-to-evidence-based-adr-governance`, Phase 2 — surfacing
+ * only. Nothing here gates, permits, or denies anything: the verb reports what
+ * a record says about itself and exits 1 only when the record contradicts its
+ * OWN amendment, which is a defect in the document, never a verdict about
+ * whether a transition may proceed.
+ *
+ * ## The defect it closes
+ *
+ * A long ADR is read linearly, so a reader meets whichever half comes first.
+ * `adr-layout § Amendments` records the measured cost twice over: ADR-035
+ * asserted in two places a rejection ADR-232 had reopened, and the contract
+ * paragraph naming that failure was itself stale by the time it was read. The
+ * live fixture is ADR-020, whose 2026-07-13 amendment retired the committed
+ * bridge marker while its Decision still mandates writing one and its
+ * Consequences still narrate it as a live failure mode.
+ *
+ * ## Why a declaration and not an inference
+ *
+ * "Which clauses did this amendment supersede" is a semantic question, and this
+ * roadmap's own architecture forbids answering it by guess — an agent grading
+ * its own homework is the failure round 5 refused one layer up. So the record
+ * declares it, in two literals that read as prose and parse deterministically:
+ *
+ * ```markdown
+ * ## Amendment — 2026-07-13 · bridge marker retired
+ *
+ * > retires: `agents/.event4u-bridge.yml`, `bridge marker`
+ *
+ * ... elsewhere, in the clause the amendment overtook:
+ *
+ * **(Superseded by the 2026-07-13 amendment — the marker is not written.)**
+ * ```
+ *
+ * A marked clause is reported as superseded. A clause in an ASSERTIVE section
+ * naming a retired token with no marker is a contradiction. Absent a `retires:`
+ * declaration the verb reports amendments, axes and trigger state and claims
+ * nothing about clauses — which is the honest output for the 17 other amended
+ * records, not a silent pass.
+ *
+ * ## Why only the assertive sections
+ *
+ * `Context`, `Alternatives considered` and `References` describe the situation
+ * as it stood when the decision was taken; a retired term appearing there is
+ * the history the ADR exists to keep, not a live claim. `adr-layout` frames the
+ * defect the same way — "an ADR whose top half still asserts what its own
+ * amendment reversed" — so the scan covers `Decision`, `Consequences` and
+ * earlier amendment blocks, and says so rather than reporting the whole file
+ * and burying the three lines that matter.
+ *
+ * Exit codes: 0 clean · 1 a contradiction, or the ref resolved nowhere · 2 usage.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import {
+    adr_files,
+    normalise_ref,
+    parse_frontmatter,
+    trigger_state,
+    type TriggerState,
+} from '../adr_cite_check.js';
+import {
+    authorityBasisOf,
+    evidenceOf,
+    provenanceOf,
+    readAdrFrontmatter,
+} from '../_lib/adr_frontmatter.js';
+
+const _HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(_HERE, '..', '..', '..');
+
+/**
+ * Sections whose clauses are read as live assertions.
+ *
+ * Matched on the `## ` heading's leading word so the three amendment
+ * conventions in the corpus (`## Amendment N (date)`, `## Amendment — date ·
+ * topic`, plus the `**Amended <date> —` inline form) all land in the set.
+ */
+export const ASSERTIVE_SECTIONS = ['decision', 'consequences', 'amendment'] as const;
+
+/** `> retires: \`a\`, \`b\`` — the tokens an amendment block declares retired. */
+const RETIRES_RE = /^>?\s*retires:\s*(.+)$/i;
+
+/**
+ * A clause-level supersession marker.
+ *
+ * `Superseded`, `Narrowed` and `Reopened` are all accepted: the corpus already
+ * carries the third (`ADR-035:47`, `**(Reopened by ADR-232 — see the banner
+ * above.)**`) and inventing a fourth spelling for the same act would leave that
+ * marker unread by the one tool written to read markers.
+ */
+const CLAUSE_MARKER_RE = /\*\*\((?:Superseded|Narrowed|Reopened) by ([^—)]+?)\s*(?:—[^)]*)?\)\*\*/;
+
+export interface AmendmentBlock {
+    /** The heading line, verbatim minus the leading `#`s. */
+    heading: string;
+    /** 1-based line number of the heading. */
+    line: number;
+    /** Tokens this block declares retired, verbatim (backticks stripped). */
+    retires: string[];
+    /** 1-based line range the block spans, end inclusive. */
+    range: [number, number];
+}
+
+export interface ClauseFinding {
+    /** 1-based line number of the clause's first line. */
+    line: number;
+    /** The `## ` heading the clause sits under, or `(frontmatter)`. */
+    section: string;
+    /** The retired token, or the marker's referent for a marked clause. */
+    subject: string;
+    /** The clause's first line, trimmed — enough to locate it by eye. */
+    excerpt: string;
+}
+
+export interface EffectiveState {
+    ref: string;
+    resolved: boolean;
+    file?: string;
+    status?: string;
+    date?: string;
+    decision?: string;
+    provenance_kind?: string;
+    evidence_strength?: string;
+    evidence_discovery?: string;
+    authority_basis?: string;
+    review_trigger?: string;
+    trigger_state: TriggerState;
+    amended_by?: string;
+    amendments: AmendmentBlock[];
+    /** Retired tokens declared across every amendment block, deduplicated. */
+    retired_tokens: string[];
+    /** Clauses carrying a supersession marker. */
+    superseded_clauses: ClauseFinding[];
+    /** Assertive clauses naming a retired token with no marker. */
+    contradictions: ClauseFinding[];
+    /** The Decision section, verbatim, as the effective text to read. */
+    effective_decision: string[];
+}
+
+interface Clause {
+    line: number;
+    section: string;
+    text: string;
+}
+
+/** Strip backticks and surrounding whitespace off one declared token. */
+function cleanToken(raw: string): string {
+    return raw.trim().replace(/^`+|`+$/g, '').trim();
+}
+
+/** The heading a line sits under, `(preamble)` before the first one. */
+function sectionOf(headings: { line: number; text: string }[], line: number): string {
+    let current = '(preamble)';
+    for (const h of headings) {
+        if (h.line > line) break;
+        current = h.text;
+    }
+    return current;
+}
+
+function isAssertive(section: string): boolean {
+    const first = section.toLowerCase().replace(/^#+\s*/, '').split(/[\s·—-]/)[0] ?? '';
+    return (ASSERTIVE_SECTIONS as readonly string[]).includes(first);
+}
+
+/**
+ * Split a document body into clauses.
+ *
+ * A clause ends at a blank line OR at the start of the next list item, and the
+ * second half is load-bearing: a run of bullets with no blank line between them
+ * is one contiguous block, so paragraph-only splitting would let a marker on
+ * one bullet clear the bullet below it.
+ */
+export function splitClauses(lines: string[], headings: { line: number; text: string }[]): Clause[] {
+    const out: Clause[] = [];
+    let start = -1;
+    let buf: string[] = [];
+    const flush = (): void => {
+        if (start === -1) return;
+        out.push({ line: start, section: sectionOf(headings, start), text: buf.join('\n') });
+        start = -1;
+        buf = [];
+    };
+    for (let i = 0; i < lines.length; i += 1) {
+        const raw = lines[i] as string;
+        const num = i + 1;
+        if (raw.trim() === '') {
+            flush();
+            continue;
+        }
+        if (/^\s*(?:[-*+]\s|\d+\.\s)/.test(raw)) flush();
+        if (start === -1) start = num;
+        buf.push(raw);
+    }
+    flush();
+    return out;
+}
+
+/** Every `## `/`### ` heading, plus the inline `**Amended <date>` convention. */
+function headingsOf(lines: string[]): { line: number; text: string }[] {
+    const out: { line: number; text: string }[] = [];
+    for (let i = 0; i < lines.length; i += 1) {
+        const raw = lines[i] as string;
+        if (/^#{2,3}\s+/.test(raw)) out.push({ line: i + 1, text: raw.replace(/^#+\s*/, '').trim() });
+    }
+    return out;
+}
+
+/** Amendment blocks with their extents and declared retirements. */
+export function amendmentsOf(lines: string[]): AmendmentBlock[] {
+    const headings = headingsOf(lines);
+    const out: AmendmentBlock[] = [];
+    for (let h = 0; h < headings.length; h += 1) {
+        const heading = headings[h] as { line: number; text: string };
+        if (!/^amend/i.test(heading.text)) continue;
+        const next = headings[h + 1];
+        const end = next === undefined ? lines.length : next.line - 1;
+        const retires: string[] = [];
+        for (let i = heading.line; i < end; i += 1) {
+            const m = RETIRES_RE.exec((lines[i] as string).trim());
+            if (m?.[1] === undefined) continue;
+            for (const part of m[1].split(',')) {
+                const token = cleanToken(part);
+                if (token !== '') retires.push(token);
+            }
+        }
+        out.push({ heading: heading.text, line: heading.line, retires, range: [heading.line, end] });
+    }
+    return out;
+}
+
+/** The verbatim `## Decision` section, or `[]` when the record has none. */
+export function decisionSection(lines: string[]): string[] {
+    const headings = headingsOf(lines);
+    for (let h = 0; h < headings.length; h += 1) {
+        const heading = headings[h] as { line: number; text: string };
+        if (!/^decision\b/i.test(heading.text)) continue;
+        const next = headings[h + 1];
+        const end = next === undefined ? lines.length : next.line - 1;
+        return lines.slice(heading.line, end).filter((l, idx, all) => !(l.trim() === '' && all[idx + 1] === undefined));
+    }
+    return [];
+}
+
+/**
+ * Superseded clauses and contradictions, from the declarations alone.
+ *
+ * A clause inside the amendment block that declares the retirement is skipped:
+ * naming the thing it retires is what an amendment does.
+ */
+export function clauseFindings(
+    lines: string[],
+    amendments: AmendmentBlock[],
+): { superseded: ClauseFinding[]; contradictions: ClauseFinding[] } {
+    const headings = headingsOf(lines);
+    const clauses = splitClauses(lines, headings);
+    const superseded: ClauseFinding[] = [];
+    const contradictions: ClauseFinding[] = [];
+
+    for (const clause of clauses) {
+        const marker = CLAUSE_MARKER_RE.exec(clause.text);
+        const excerpt = (clause.text.split('\n')[0] ?? '').trim();
+        if (marker?.[1] !== undefined) {
+            superseded.push({
+                line: clause.line,
+                section: clause.section,
+                subject: marker[1].trim(),
+                excerpt,
+            });
+            continue;
+        }
+        if (!isAssertive(clause.section)) continue;
+        for (const amendment of amendments) {
+            const inDeclaringBlock =
+                clause.line >= amendment.range[0] && clause.line <= amendment.range[1];
+            if (inDeclaringBlock) continue;
+            for (const token of amendment.retires) {
+                if (!clause.text.includes(token)) continue;
+                contradictions.push({
+                    line: clause.line,
+                    section: clause.section,
+                    subject: token,
+                    excerpt,
+                });
+                break;
+            }
+        }
+    }
+    return { superseded, contradictions };
+}
+
+/** Resolve one reference to a decision file on a scanned surface. */
+export function resolveAdrFile(ref: string, repoRoot: string): string | null {
+    const parsed = normalise_ref(ref);
+    if (parsed === null) return null;
+    const files = adr_files(repoRoot);
+    const { area, num } = parsed;
+    const match =
+        area === null
+            ? files.find((f) => new RegExp(`(^|/)ADR-0*${num}[-.]`, 'i').test(f))
+            : files.find((f) => new RegExp(`/docs/adrs/${area}/0*${String(Number(num))}-`, 'i').test(f));
+    return match ?? null;
+}
+
+export function effectiveState(ref: string, repoRoot: string = REPO_ROOT): EffectiveState {
+    const parsed = normalise_ref(ref);
+    const id = parsed?.id ?? ref;
+    const match = resolveAdrFile(ref, repoRoot);
+    if (match === null) {
+        return {
+            ref: id,
+            resolved: false,
+            trigger_state: 'none',
+            amendments: [],
+            retired_tokens: [],
+            superseded_clauses: [],
+            contradictions: [],
+            effective_decision: [],
+        };
+    }
+
+    const text = fs.readFileSync(match, 'utf-8');
+    const scalars = parse_frontmatter(text) ?? {};
+    const structured = readAdrFrontmatter(text);
+    const provenance = structured === null ? null : provenanceOf(structured);
+    const evidence = structured === null ? null : evidenceOf(structured);
+    const basis = structured === null ? null : authorityBasisOf(structured);
+
+    const bodyStart = text.indexOf('\n---\n', 4);
+    const frontmatterLines = bodyStart === -1 ? 0 : text.slice(0, bodyStart + 5).split('\n').length - 1;
+    const lines = text.split('\n');
+    const amendments = amendmentsOf(lines).filter((a) => a.line > frontmatterLines);
+    const { superseded, contradictions } = clauseFindings(lines, amendments);
+    const retired = [...new Set(amendments.flatMap((a) => a.retires))];
+
+    return {
+        ref: id,
+        resolved: true,
+        file: path.relative(repoRoot, match),
+        ...(scalars['status'] !== undefined ? { status: scalars['status'] } : {}),
+        ...(scalars['date'] !== undefined ? { date: scalars['date'] } : {}),
+        ...(scalars['decision'] !== undefined ? { decision: scalars['decision'] } : {}),
+        ...(provenance?.kind != null ? { provenance_kind: provenance.kind } : {}),
+        ...(evidence?.strength != null ? { evidence_strength: evidence.strength } : {}),
+        ...(evidence?.discovery != null ? { evidence_discovery: evidence.discovery } : {}),
+        ...(basis !== null ? { authority_basis: basis } : {}),
+        ...(scalars['review_trigger'] !== undefined && scalars['review_trigger'] !== ''
+            ? { review_trigger: scalars['review_trigger'] }
+            : {}),
+        trigger_state: trigger_state(scalars),
+        ...(scalars['amended_by'] !== undefined && scalars['amended_by'] !== '—'
+            ? { amended_by: scalars['amended_by'] }
+            : {}),
+        amendments,
+        retired_tokens: retired,
+        superseded_clauses: superseded,
+        contradictions,
+        effective_decision: decisionSection(lines),
+    };
+}
+
+export function render(state: EffectiveState): string[] {
+    const out: string[] = [];
+    out.push(`${state.ref}${state.file !== undefined ? `  ·  ${state.file}` : ''}`);
+    if (!state.resolved) {
+        out.push('  ❌  UNRESOLVED — no decision record carries this number on a scanned surface.');
+        return out;
+    }
+    out.push(`  status           ${state.status ?? '—'}   date ${state.date ?? '—'}`);
+    if (state.decision !== undefined) out.push(`  decision         ${state.decision}`);
+    out.push(`  provenance       ${state.provenance_kind ?? '— (no provenance axis)'}`);
+    out.push(
+        `  evidence         ${state.evidence_strength ?? '— (ungraded)'}` +
+            `  ·  discovery ${state.evidence_discovery ?? '—'}`,
+    );
+    out.push(`  authority_basis  ${state.authority_basis ?? '— (absent → evidence)'}`);
+    out.push(`  review_trigger   ${state.review_trigger ?? '— (none recorded)'}`);
+    out.push(`  trigger state    ${state.trigger_state}`);
+    if (state.amended_by !== undefined) out.push(`  amended_by       ${state.amended_by}`);
+
+    out.push('', '  active amendments');
+    if (state.amendments.length === 0) {
+        out.push('    — none in the body');
+    } else {
+        for (const a of state.amendments) {
+            const declares =
+                a.retires.length > 0 ? `  ·  retires ${a.retires.map((t) => `\`${t}\``).join(', ')}` : '';
+            out.push(`    :${String(a.line)}  ${a.heading}${declares}`);
+        }
+    }
+
+    out.push('', '  superseded clauses');
+    if (state.retired_tokens.length === 0 && state.superseded_clauses.length === 0) {
+        out.push('    — no amendment declares a `retires:` list and no clause carries a marker,');
+        out.push('      so nothing is claimed about this record\'s clauses. Read the amendments.');
+    } else if (state.superseded_clauses.length === 0) {
+        out.push('    — none marked');
+    } else {
+        for (const c of state.superseded_clauses) {
+            out.push(`    :${String(c.line)}  ${c.section} — superseded by ${c.subject}`);
+            out.push(`             ${c.excerpt}`);
+        }
+    }
+
+    out.push('', '  effective decision');
+    if (state.effective_decision.length === 0) {
+        out.push('    — no `## Decision` section');
+    } else {
+        for (const line of state.effective_decision) out.push(`    ${line}`);
+    }
+
+    if (state.contradictions.length > 0) {
+        out.push('', '  ❌  current-vs-amendment contradiction');
+        for (const c of state.contradictions) {
+            out.push(`    :${String(c.line)}  ${c.section} asserts \`${c.subject}\`, which an`);
+            out.push('             amendment on this record declares retired, and carries no marker.');
+            out.push(`             ${c.excerpt}`);
+        }
+    }
+    return out;
+}
+
+interface ParsedArgv {
+    ok: boolean;
+    message?: string;
+    refs?: string[];
+    json?: boolean;
+}
+
+export function parseArgv(argv: readonly string[]): ParsedArgv {
+    let json = false;
+    const refs: string[] = [];
+    for (const a of argv) {
+        if (a === '--json') json = true;
+        else if (a === '-h' || a === '--help')
+            return { ok: false, message: 'usage: agent-config adr:effective <ADR-NNN> [ADR-NNN …] [--json]' };
+        else if (a.startsWith('--')) return { ok: false, message: `unknown argument: ${a}` };
+        else refs.push(a);
+    }
+    if (refs.length === 0)
+        return { ok: false, message: 'usage: agent-config adr:effective <ADR-NNN> [ADR-NNN …] [--json]' };
+    return { ok: true, refs, json };
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    const parsed = parseArgv(argv);
+    if (!parsed.ok) {
+        process.stderr.write(`${parsed.message ?? 'usage error'}\n`);
+        return 2;
+    }
+    const states = (parsed.refs ?? []).map((ref) => effectiveState(ref));
+    if (parsed.json === true) {
+        process.stdout.write(`${JSON.stringify(states, null, 2)}\n`);
+    } else {
+        for (const state of states) {
+            for (const line of render(state)) process.stdout.write(`${line}\n`);
+            process.stdout.write('\n');
+        }
+    }
+    const bad = states.filter((s) => !s.resolved || s.contradictions.length > 0);
+    return bad.length > 0 ? 1 : 0;
+}
+
+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(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    process.exitCode = main();
+}