@event4u/agent-config 16.4.0 → 17.0.0

package/src/scripts/adoption_status.ts

@@ -22,7 +22,13 @@
  *
  * CLI:
  *
- *   ./scripts-run src/scripts/adoption_status [--json] [--branch main]
+ *   ./scripts-run src/scripts/adoption_status [--json] [--branch main] [--check-upstream]
+ *
+ * `--check-upstream` reads each ledger row's upstream (`gh pr view` for a pull
+ * request, one `curl` for a listing page or registry query) and appends what it
+ * found. Without the flag nothing touches the network: stdout is the sheet-only
+ * report exactly as before, and stderr names that mode plus every row whose
+ * `Last read` date is missing or older than the sheet's re-read threshold.
  *
  * Exit codes:
  *
@@ -35,6 +41,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { sanitize_text } from './_lib/retrieval_sanitize.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 // src/scripts/adoption_status.ts → parents[2] is the repo root (mirrors
 // `Path(__file__).resolve().parent.parent.parent` in the .py).
@@ -234,22 +242,26 @@ export function render_json(
 interface Args {
     json: boolean;
     branch: string;
+    checkUpstream: boolean;
 }
 
 export function parse_args(argv: string[]): Args {
     let json = false;
     let branch = 'main';
+    let checkUpstream = false;
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
         if (a === '--json') {
             json = true;
+        } else if (a === '--check-upstream') {
+            checkUpstream = true;
         } else if (a === '--branch') {
             branch = argv[++i] ?? '';
         } else if (a !== undefined && a.startsWith('--branch=')) {
             branch = a.slice('--branch='.length);
         }
     }
-    return { json, branch };
+    return { json, branch, checkUpstream };
 }
 
 export function main(argv: string[] = process.argv.slice(2)): number {
@@ -267,14 +279,329 @@ export function main(argv: string[] = process.argv.slice(2)): number {
     const reports = count_recruit_reports(RECRUIT_DIR);
     const ci = ci_status_color(args.branch);
 
+    const rows = parse_ledger_rows(registryText);
+    const today = _todayUtc();
+    const unread = unread_findings(rows, today, parse_reread_threshold(registryText));
+
+    if (!args.checkUpstream) {
+        if (args.json) {
+            process.stdout.write(render_json(registryCounts, reports, ci, args.branch) + '\n');
+        } else {
+            process.stdout.write(render_text(registryCounts, reports, ci, args.branch) + '\n');
+        }
+        process.stderr.write(upstream_mode_note(false) + '\n');
+        for (const u of unread) {
+            process.stderr.write(`  row ${u.id} ${u.registry}: ${u.label}\n`);
+        }
+        return 0;
+    }
+
+    const verdicts = judge_upstream(rows, live_upstream_reader, today);
     if (args.json) {
-        process.stdout.write(render_json(registryCounts, reports, ci, args.branch) + '\n');
+        const base = JSON.parse(render_json(registryCounts, reports, ci, args.branch)) as Record<
+            string,
+            unknown
+        >;
+        base.upstream = { mode: _modeOf(verdicts), verdicts, unread };
+        process.stdout.write(_pyJsonDumpsIndent2(base) + '\n');
     } else {
         process.stdout.write(render_text(registryCounts, reports, ci, args.branch) + '\n');
+        process.stdout.write(render_upstream_text(verdicts, unread) + '\n');
     }
     return 0;
 }
 
+// --- upstream reading --------------------------------------------------------
+
+/** One row of the `Tracking rows` table, keyed by header name, not position. */
+export interface LedgerRow {
+    id: string;
+    registry: string;
+    status: string;
+    kind: string;
+    ref: string;
+    lastRead: string;
+    date: string;
+}
+
+export type UpstreamReading =
+    | { ok: true; state: 'open' | 'closed' | 'merged' | 'listed' | 'not-listed'; at?: string }
+    | { ok: false; reason: string };
+
+export type UpstreamReader = (row: LedgerRow) => UpstreamReading;
+
+export type UpstreamVerdict =
+    | 'answered-closed'
+    | 'answered-merged'
+    | 'stalled'
+    | 'open'
+    | 'listed'
+    | 'not-listed'
+    | 'unreachable'
+    | 'no-upstream';
+
+export interface RowVerdict {
+    id: string;
+    registry: string;
+    verdict: UpstreamVerdict;
+    detail: string;
+}
+
+export interface UnreadFinding {
+    id: string;
+    registry: string;
+    label: string;
+}
+
+/** Same threshold the sheet's legend states for `stalled`. */
+export const STALLED_AFTER_DAYS = 60;
+const DEFAULT_REREAD_THRESHOLD_DAYS = 30;
+
+function _cellValue(cell: string): string {
+    const v = cell.trim().replace(/`/g, '');
+    const link = /^<(.+)>$/.exec(v);
+    const out = link ? (link[1] as string) : v;
+    return out === '—' || out === '-' ? '' : out;
+}
+
+/**
+ * Parse the `Tracking rows` table by its header names, so a sheet that lacks a
+ * column yields empty fields rather than a misread neighbour.
+ */
+export function parse_ledger_rows(text: string): LedgerRow[] {
+    const rows: LedgerRow[] = [];
+    let inTable = false;
+    let header: string[] | null = null;
+    for (const line of _splitlines(text)) {
+        if (line.startsWith('## Tracking rows')) {
+            inTable = true;
+            continue;
+        }
+        if (inTable && line.startsWith('## ')) {
+            break;
+        }
+        if (!inTable || !line.startsWith('|')) {
+            continue;
+        }
+        const cells = line.split('|').slice(1, -1).map((c) => c.trim());
+        if (header === null) {
+            header = cells.map((c) => c.toLowerCase());
+            continue;
+        }
+        if (cells.every((c) => /^-+$/.test(c))) {
+            continue;
+        }
+        const names = header;
+        const col = (name: string): string => {
+            const i = names.indexOf(name);
+            return i < 0 || i >= cells.length ? '' : _cellValue(cells[i] as string);
+        };
+        rows.push({
+            id: col('#'),
+            registry: col('registry'),
+            status: col('status'),
+            kind: col('upstream kind'),
+            ref: col('upstream ref'),
+            lastRead: col('last read'),
+            date: col('date'),
+        });
+    }
+    return rows;
+}
+
+/** The sheet states its own re-read threshold as `**Re-read threshold:** N days`. */
+export function parse_reread_threshold(text: string): number {
+    const m = /\*\*Re-read threshold:\*\*\s*(\d+)\s*days/.exec(text);
+    return m ? Number(m[1]) : DEFAULT_REREAD_THRESHOLD_DAYS;
+}
+
+function _daysBetween(fromIso: string, toIso: string): number | null {
+    const a = Date.parse(fromIso.slice(0, 10) + 'T00:00:00Z');
+    const b = Date.parse(toIso.slice(0, 10) + 'T00:00:00Z');
+    if (Number.isNaN(a) || Number.isNaN(b)) {
+        return null;
+    }
+    return Math.round((b - a) / 86_400_000);
+}
+
+/** A row never read, or read longer ago than the threshold, is a finding. */
+export function unread_findings(
+    rows: LedgerRow[],
+    today: string,
+    thresholdDays: number,
+): UnreadFinding[] {
+    const out: UnreadFinding[] = [];
+    for (const row of rows) {
+        const age = row.lastRead === '' ? null : _daysBetween(row.lastRead, today);
+        if (age === null) {
+            out.push({ id: row.id, registry: row.registry, label: 'unread-never' });
+        } else if (age > thresholdDays) {
+            out.push({ id: row.id, registry: row.registry, label: `unread-for-${age}-days` });
+        }
+    }
+    return out;
+}
+
+/**
+ * `stalled` keeps its old meaning — submitted, no answer, 60 days — but is
+ * reachable only when the reading says the upstream is still open, so an
+ * answered row can no longer hide behind the date arithmetic.
+ */
+export function judge_upstream(
+    rows: LedgerRow[],
+    reader: UpstreamReader,
+    today: string,
+): RowVerdict[] {
+    return rows.map((row): RowVerdict => {
+        const base = { id: row.id, registry: row.registry };
+        if (row.kind === '' || row.ref === '') {
+            return { ...base, verdict: 'no-upstream', detail: 'the row names no upstream to read' };
+        }
+        const r = reader(row);
+        if (!r.ok) {
+            return { ...base, verdict: 'unreachable', detail: r.reason };
+        }
+        switch (r.state) {
+            case 'closed':
+                return { ...base, verdict: 'answered-closed', detail: `closed ${r.at ?? 'date unknown'}` };
+            case 'merged':
+                return { ...base, verdict: 'answered-merged', detail: `merged ${r.at ?? 'date unknown'}` };
+            case 'listed':
+            case 'not-listed':
+                return { ...base, verdict: r.state, detail: row.ref };
+            case 'open': {
+                const age = row.date === '' ? null : _daysBetween(row.date, today);
+                if (row.status === 'submitted' && age !== null && age >= STALLED_AFTER_DAYS) {
+                    return { ...base, verdict: 'stalled', detail: `open ${age} days, no answer` };
+                }
+                return { ...base, verdict: 'open', detail: age === null ? 'open' : `open ${age} days` };
+            }
+        }
+    });
+}
+
+export function upstream_mode_note(checked: boolean): string {
+    return checked
+        ? 'upstream: read live (--check-upstream)'
+        : 'upstream: not read — reporting from the sheet only; pass --check-upstream for live state';
+}
+
+function _modeOf(verdicts: RowVerdict[]): string {
+    const readable = verdicts.filter((v) => v.verdict !== 'no-upstream');
+    if (readable.length > 0 && readable.every((v) => v.verdict === 'unreachable')) {
+        return 'degraded — no upstream could be read; the sheet above is the only source';
+    }
+    return 'live';
+}
+
+export function render_upstream_text(verdicts: RowVerdict[], unread: UnreadFinding[]): string {
+    const lines: string[] = ['', `Upstream readings (${_modeOf(verdicts)}):`];
+    for (const v of verdicts) {
+        lines.push(`  row ${v.id.padEnd(3)} ${v.verdict.padEnd(16)} ${v.registry} — ${v.detail}`);
+    }
+    lines.push('');
+    lines.push(
+        unread.length === 0
+            ? 'Ledger readings: all within the re-read threshold'
+            : 'Ledger readings out of date:',
+    );
+    for (const u of unread) {
+        lines.push(`  row ${u.id.padEnd(3)} ${u.label} ${u.registry}`);
+    }
+    return lines.join('\n');
+}
+
+function _readPullRequest(ref: string): UpstreamReading {
+    const m = /^([\w.-]+\/[\w.-]+)#(\d+)$/.exec(ref);
+    if (!m) {
+        return { ok: false, reason: `unparseable pull-request ref ${ref}` };
+    }
+    if (_which('gh') === null) {
+        return { ok: false, reason: 'gh CLI not on PATH' };
+    }
+    const proc = spawnSync(
+        'gh',
+        ['pr', 'view', m[2] as string, '--repo', m[1] as string, '--json', 'state,closedAt,mergedAt'],
+        { encoding: 'utf8', timeout: 20_000 },
+    );
+    if (proc.status !== 0) {
+        const snip = sanitize_text(_pyStrip(proc.stderr ?? '')).slice(0, 80);
+        return { ok: false, reason: `gh exit=${proc.status}: ${snip}` };
+    }
+    let d: { state?: string; closedAt?: string; mergedAt?: string };
+    try {
+        d = JSON.parse(proc.stdout) as typeof d;
+    } catch {
+        return { ok: false, reason: 'gh output not parseable as JSON' };
+    }
+    if (d.state === 'MERGED') return { ok: true, state: 'merged', at: sanitize_text(d.mergedAt ?? '').slice(0, 10) };
+    if (d.state === 'CLOSED') return { ok: true, state: 'closed', at: sanitize_text(d.closedAt ?? '').slice(0, 10) };
+    if (d.state === 'OPEN') return { ok: true, state: 'open' };
+    return { ok: false, reason: `unknown pull-request state ${sanitize_text(String(d.state)).slice(0, 40)}` };
+}
+
+/** The official MCP registry routinely takes 15-20 s to answer a search; a 20 s cap cut it off. */
+export const UPSTREAM_READ_TIMEOUT_S = 45;
+
+export function read_url(
+    kind: string,
+    ref: string,
+    maxSeconds: number = UPSTREAM_READ_TIMEOUT_S,
+    schemes: readonly string[] = ['https'],
+): UpstreamReading {
+    if (_which('curl') === null) {
+        return { ok: false, reason: 'curl not on PATH' };
+    }
+    // The ref is a repo-authored ledger value: only an https URL is fetched,
+    // redirects stay on https, and `--` keeps a leading `-` from being an option.
+    const scheme = /^([a-z]+):\/\//i.exec(ref)?.[1]?.toLowerCase();
+    if (scheme === undefined || !schemes.includes(scheme)) {
+        return { ok: false, reason: `refusing a ref outside ${schemes.join('/')}: ${ref}` };
+    }
+    const proto = `=${schemes.join(',')}`;
+    const proc = spawnSync('curl', ['-sL', '--proto', proto, '--proto-redir', proto, '--max-time', String(maxSeconds), '-w', '\n%{http_code}', '--', ref], {
+        encoding: 'utf8',
+        timeout: (maxSeconds + 5) * 1000,
+    });
+    const out = proc.stdout ?? '';
+    const cut = out.lastIndexOf('\n');
+    const code = out.slice(cut + 1).trim();
+    if (proc.status !== 0 || code === '000' || code === '') {
+        return { ok: false, reason: `no response from ${ref}` };
+    }
+    if (kind === 'listing-page') {
+        if (code === '200') return { ok: true, state: 'listed' };
+        if (code === '404') return { ok: true, state: 'not-listed' };
+        return { ok: false, reason: `HTTP ${code} from ${ref}` };
+    }
+    let body: { metadata?: { count?: unknown } };
+    try {
+        body = JSON.parse(out.slice(0, cut)) as typeof body;
+    } catch {
+        return { ok: false, reason: `registry answer from ${ref} not parseable as JSON` };
+    }
+    const n = body.metadata?.count;
+    if (typeof n !== 'number') {
+        return { ok: false, reason: 'registry answer has no metadata.count' };
+    }
+    return { ok: true, state: n > 0 ? 'listed' : 'not-listed' };
+}
+
+/** Reads the real upstream: `gh` for a pull request, `curl` otherwise. */
+export const live_upstream_reader: UpstreamReader = (row) => {
+    if (row.kind === 'github-pr') {
+        return _readPullRequest(row.ref);
+    }
+    if (row.kind === 'listing-page' || row.kind === 'registry-query') {
+        return read_url(row.kind, row.ref);
+    }
+    return { ok: false, reason: `no reader for upstream kind ${row.kind}` };
+};
+
+function _todayUtc(): string {
+    return new Date().toISOString().slice(0, 10);
+}
+
 // --- helpers -----------------------------------------------------------------
 
 function _exists(p: string): boolean {

package/src/scripts/adr_cite_check.ts

@@ -183,6 +183,21 @@ export const PARTIAL_COVERAGE: readonly string[] = [];
  */
 export type TriggerState = 'none' | 'indeterminate' | 'fired' | 'not-fired' | 'dated-unparsed';
 
+/** One record's `supersedes:` naming another, with the scope it declares. */
+export interface ScopedSuccessor {
+    /** The naming record, e.g. `ADR-281`. */
+    adr: string;
+    /** Its path, relative to the repo root. */
+    file: string;
+    /**
+     * The first sentence of its `supersedes_scope`, verbatim, or a marker when
+     * the field is absent. The first sentence is what a citer needs to decide
+     * whether the clause they are about to cite is the narrowed one; the whole
+     * field is in the successor and is one `adr_cite_check` away.
+     */
+    scope: string;
+}
+
 export interface CiteResult {
     ref: string;
     resolved: boolean;
@@ -200,6 +215,18 @@ export interface CiteResult {
     amendment_blocks: string[];
     /** Other ADR files whose text names this one. */
     referenced_by: string[];
+    /**
+     * Records whose own `supersedes:` names this one, with the first sentence
+     * of their `supersedes_scope`.
+     *
+     * A scoped supersession is one-sided in the frontmatter: the successor
+     * declares it, the record it narrows carries nothing. Reading a successor
+     * only from `superseded_by` therefore reports a record as fully LIVE while
+     * one of its clauses has been replaced — which is what a citer would act
+     * on. The verdict stays LIVE because the rest of the record does bind; what
+     * changes is that the narrowed clause is now visible.
+     */
+    scoped_successors: ScopedSuccessor[];
     /** `provenance.kind` — who decided. Absent when the record carries no axis. */
     provenance_kind?: string;
     /** `provenance.agentic_mode` — descriptive shape of an agentic decision. */
@@ -531,8 +558,41 @@ export function trigger_state(fm: Record<string, string>, asOfDate?: Date): Trig
     return 'indeterminate';
 }
 
+/**
+ * The first sentence of a `supersedes_scope`, including its full stop.
+ *
+ * The YAML folds to one line, so a sentence boundary is a `.`/`!`/`?` followed
+ * by whitespace or the end. An abbreviation inside the scope would split it
+ * early; that is a shorter quotation of a field the reader can open in full,
+ * not a wrong verdict, so it is accepted rather than guessed around.
+ */
+export function first_sentence(text: string): string {
+    const trimmed = text.trim();
+    const m = /^[\s\S]*?[.!?](?=\s|$)/u.exec(trimmed);
+    return (m === null ? trimmed : m[0]).trim();
+}
+
+/** `ADR-281` from `docs/decisions/ADR-281-council-confirmed-self-modification.md`. */
+function successor_id(file: string, fm: Record<string, string>): string {
+    const base = path.basename(file);
+    const m = /^(ADR-(?:[A-Za-z]+-)?\d+)/u.exec(base);
+    if (m !== null) return m[1] as string;
+    const n = fm['adr'];
+    return n !== undefined && n !== '' ? `ADR-${n.padStart(3, '0')}` : base;
+}
+
 /** The one-line answer to "may I cite this as a reason not to act?". */
 export function verdict_for(r: Omit<CiteResult, 'verdict'>): string {
+    const base = _verdict_base(r);
+    if (!r.resolved || r.scoped_successors.length === 0) return base;
+    const names = r.scoped_successors.map((x) => x.adr).join(', ');
+    return (
+        `${base} PARTLY SUPERSEDED IN SCOPE by ${names} — one clause of this record has been ` +
+        'replaced in scope and the rest stands. Read the scope line before citing the clause it names.'
+    );
+}
+
+function _verdict_base(r: Omit<CiteResult, 'verdict'>): string {
     if (!r.resolved) return 'UNRESOLVED — no ADR file carries this number on a scanned surface.';
     const status = (r.status ?? '').toLowerCase();
     // `rejected` is deliberately NOT in this set. On an ADR it means "the
@@ -599,6 +659,7 @@ export function cite_check(refs: string[], repo_root: string = REPO_ROOT): CiteR
                 trigger_state: 'none',
                 amendment_blocks: [],
                 referenced_by: [],
+                scoped_successors: [],
             };
             return { ...empty, verdict: verdict_for(empty) };
         }
@@ -621,6 +682,7 @@ export function cite_check(refs: string[], repo_root: string = REPO_ROOT): CiteR
                 trigger_state: 'none',
                 amendment_blocks: [],
                 referenced_by: [],
+                scoped_successors: [],
             };
             return { ...empty, verdict: verdict_for(empty) };
         }
@@ -662,6 +724,32 @@ export function cite_check(refs: string[], repo_root: string = REPO_ROOT): CiteR
             .filter((f) => f !== match && cited.test(contents.get(f) ?? ''))
             .map((f) => path.relative(repo_root, f));
 
+        // A supersession in scope is declared by the SUCCESSOR and nowhere
+        // else: `supersedes:` plus `supersedes_scope:` on the newer record,
+        // with the older one's `superseded_by` still `—` because the record as
+        // a whole is alive. Reading only the older record therefore reports a
+        // narrowed clause as untouched. This scan is the other direction.
+        const scoped_successors = files
+            .filter((f) => f !== match)
+            .flatMap((f): ScopedSuccessor[] => {
+                const otherFm = parse_frontmatter(contents.get(f) ?? '') ?? {};
+                const declared = otherFm['supersedes'];
+                if (declared === undefined || declared === '' || declared === '—') return [];
+                if (!cited.test(declared)) return [];
+                const scopeRaw = otherFm['supersedes_scope'];
+                return [
+                    {
+                        adr: successor_id(f, otherFm),
+                        file: path.relative(repo_root, f),
+                        scope:
+                            scopeRaw === undefined || scopeRaw.trim() === ''
+                                ? '— (successor declares no `supersedes_scope`; read the successor in full)'
+                                : first_sentence(scopeRaw),
+                    },
+                ];
+            })
+            .sort((a, b) => a.adr.localeCompare(b.adr));
+
         const partial: Omit<CiteResult, 'verdict'> = {
             ref: id,
             resolved: true,
@@ -679,6 +767,7 @@ export function cite_check(refs: string[], repo_root: string = REPO_ROOT): CiteR
             ...(fm['amended_by'] !== undefined ? { amended_by: fm['amended_by'] } : {}),
             amendment_blocks: amendment_blocks(body),
             referenced_by,
+            scoped_successors,
             ...(provenance?.kind !== undefined && provenance.kind !== null
                 ? { provenance_kind: provenance.kind }
                 : {}),
@@ -728,6 +817,10 @@ function render(results: CiteResult[]): string {
             lines.push(`  amendments       ${String(r.amendment_blocks.length)}: ${r.amendment_blocks.join(' · ')}`);
         if (r.referenced_by.length > 0)
             lines.push(`  referenced by    ${String(r.referenced_by.length)} other ADR(s): ${r.referenced_by.join(', ')}`);
+        for (const sc of r.scoped_successors) {
+            lines.push(`  superseded in scope by   ${sc.adr}  ·  ${sc.file}`);
+            lines.push(`    scope          ${sc.scope}`);
+        }
 
         // The two descriptive axes. Printed for every resolved record, absent
         // or not: "the axis is missing" is itself the thing a citer needs to