@aiwg/cli 0.0.0-bootstrap.0 → 2026.7.18

package/dist/src/artifacts/corpus-tools/curator.js

@@ -0,0 +1,186 @@
+/**
+ * Curator (PROF-S) tooling — discovery-provenance / source-tracking subsystem (#1499).
+ *
+ * - curator-status: per-curator yield (inducted REFs, avg GRADE, return-to score),
+ *   revisit-cadence staleness (shared computeStaleness), and the curator-orphan
+ *   check (discovery.curator-id set but the PROF-S is missing that REF).
+ * - curator-init: scaffold a PROF-S source profile from a handle.
+ *
+ * The discovery block + PROF-S frontmatter are already parsed by the #1497
+ * parser (extractDiscovery / loadProfiles incl. `sources`); the read views
+ * by-source / by-curator shipped in #1492. This is the write/compute side.
+ *
+ * @source historical: documentation/SOURCE-TRACKING.md, profiles/sources/TEMPLATE-source-profile.md
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { loadProfiles, loadCorpus } from '../corpus-views/ref-parser.js';
+import { computeStaleness } from '../corpus-views/corpus-config.js';
+import { readAnalysisGrade } from './radar-shared.js';
+/** GRADE letter → numeric for averaging (A=4 … D=1; signs interpolate). */
+const GRADE_VALUE = { A: 4, 'A-': 3.7, B: 3, 'B-': 2.7, C: 2, 'C-': 1.7, D: 1 };
+function gradeNum(g) {
+    return GRADE_VALUE[g.toUpperCase()] ?? GRADE_VALUE[(g[0] ?? '').toUpperCase()] ?? null;
+}
+function fmStr(v) {
+    if (typeof v === 'string')
+        return v.trim() || null;
+    if (typeof v === 'number')
+        return String(v);
+    if (v instanceof Date)
+        return v.toISOString().slice(0, 10);
+    return null;
+}
+/** Per-curator (PROF-S) yield rows, ranked by return-to score (highest first). */
+export function curatorRows(corpusRoot, opts = {}) {
+    const today = new Date(`${opts.today ?? new Date().toISOString().slice(0, 10)}T00:00:00Z`);
+    const rows = loadProfiles(corpusRoot)
+        .filter((p) => p.type === 'source')
+        .map((p) => {
+        const grades = p.corpusRefs.map((r) => gradeNum(readAnalysisGrade(corpusRoot, r))).filter((x) => x !== null);
+        const avgGrade = grades.length ? grades.reduce((a, b) => a + b, 0) / grades.length : 0;
+        const cadence = fmStr(p.frontmatter['revisit-cadence']);
+        const last = fmStr(p.frontmatter['last-harvested']);
+        const s = computeStaleness(cadence, last, today);
+        return {
+            profId: p.profId,
+            name: p.name ?? '',
+            handle: fmStr(p.frontmatter.handle) ?? '',
+            platform: fmStr(p.frontmatter.platform) ?? '',
+            signalQuality: fmStr(p.frontmatter['signal-quality']) ?? '—',
+            revisitCadence: cadence ?? '—',
+            lastHarvested: last ?? '',
+            inductedCount: p.corpusRefs.length,
+            avgGrade: Math.round(avgGrade * 100) / 100,
+            returnToScore: Math.round(p.corpusRefs.length * avgGrade * 100) / 100,
+            overdueDays: s.overdueDays,
+            isStale: s.isStale,
+        };
+    });
+    return rows.sort((a, b) => b.returnToScore - a.returnToScore || (a.profId < b.profId ? -1 : a.profId > b.profId ? 1 : 0));
+}
+/**
+ * Curator orphans: a citation sidecar with `discovery.curator-id` set, but the
+ * named PROF-S is absent or is missing that REF in its `corpus-refs`. The check
+ * fires ONLY when curator-id is set (SOURCE-TRACKING §0/§3) — a missing or
+ * null/`direct` discovery block is never an orphan.
+ */
+export function curatorOrphans(corpusRoot) {
+    const { records } = loadCorpus(corpusRoot);
+    const curatorRefs = new Map(loadProfiles(corpusRoot)
+        .filter((p) => p.type === 'source')
+        .map((p) => [p.profId, new Set(p.corpusRefs)]));
+    const orphans = [];
+    for (const r of records) {
+        const cid = r.discovery?.curatorId;
+        if (!cid)
+            continue;
+        if (!curatorRefs.has(cid))
+            orphans.push({ refId: r.refId, curatorId: cid, reason: 'no PROF-S profile' });
+        else if (!curatorRefs.get(cid).has(r.refId))
+            orphans.push({ refId: r.refId, curatorId: cid, reason: 'REF missing from curator corpus-refs' });
+    }
+    return orphans;
+}
+/** Render the curator yield ranking + an orphan section. */
+export function renderCuratorStatus(rows, orphans) {
+    const lines = [
+        '# Curators (PROF-S) — yield & freshness',
+        '',
+        `${rows.length} curators · ${orphans.length} discovery orphans`,
+        '',
+        '| Curator | Handle | Signal | Cadence | Last Harvested | Inducted | Avg GRADE | Return-to | Overdue |',
+        '|---|---|---|---|---|---:|---:|---:|---:|',
+    ];
+    for (const r of rows) {
+        lines.push(`| ${r.profId} | ${r.handle || '—'} | ${r.signalQuality} | ${r.revisitCadence} | ${r.lastHarvested || '—'} | ${r.inductedCount} | ${r.avgGrade || '—'} | ${r.returnToScore || '—'} | ${r.overdueDays ?? '—'} |`);
+    }
+    lines.push('', '## Discovery orphans', '');
+    if (orphans.length) {
+        lines.push('`discovery.curator-id` set but the curator is missing the REF (SOURCE-TRACKING §3):', '', '| REF | Curator | Issue |', '|---|---|---|');
+        for (const o of orphans)
+            lines.push(`| ${o.refId} | ${o.curatorId} | ${o.reason} |`);
+    }
+    else {
+        lines.push('None — every `discovery.curator-id` resolves to a PROF-S that lists the REF.');
+    }
+    return lines.join('\n') + '\n';
+}
+/** Curator slug from a handle: lowercased, leading punctuation stripped, `_`→`-`. */
+export function curatorSlug(handle) {
+    return handle
+        .trim()
+        .replace(/^[@/]+/, '')
+        .toLowerCase()
+        .replace(/_/g, '-')
+        .replace(/[^a-z0-9-]+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+/** Scaffold a PROF-S source/curator profile from a handle. */
+export function scaffoldCurator(corpusRoot, handle, opts = {}) {
+    const slug = curatorSlug(handle);
+    const today = opts.today || new Date().toISOString().slice(0, 10);
+    const platform = opts.platform || 'x';
+    const cadence = opts.cadence || 'weekly';
+    const name = opts.name || handle;
+    const outRel = path.join('documentation', 'profiles', 'sources', `PROF-S-${slug}.md`);
+    const content = [
+        '---',
+        `prof-id: PROF-S-${slug}`,
+        `name: "${name}"`,
+        'type: source',
+        `platform: ${platform}`,
+        `handle: "${handle}"`,
+        'url: ""',
+        'operator: ""',
+        'corpus-refs: []',
+        'surfaces: []',
+        'focus-areas: []',
+        'signal-quality: "—"',
+        'grade-trajectory: unknown',
+        `revisit-cadence: ${cadence}`,
+        `last-harvested: ${today}`,
+        'last-harvested-by: curator-init-scaffold',
+        'candidate-yield: 0',
+        '---',
+        '',
+        `# ${name} — Source / Curator Profile`,
+        '',
+        '**Type**: Source / Curator',
+        `**Profile ID**: \`PROF-S-${slug}\``,
+        `**Platform**: ${platform} · **Handle**: ${handle}`,
+        `**Revisit cadence**: ${cadence}`,
+        `**Last harvested**: ${today}`,
+        '',
+        '---',
+        '',
+        '## 1. Curator Summary',
+        '',
+        'Initial scaffold — describe what this account posts and why it is worth tracking on first harvest.',
+        '',
+        '## 2. Sources Surfaced',
+        '',
+        '### Inducted (in corpus)',
+        '| REF | Title | Surfaced | GRADE |',
+        '|---|---|---|---|',
+        '',
+        '### Candidate Sources Surfaced (not yet inducted)',
+        '| Candidate | Surfaced | Harvest batch | Working file |',
+        '|---|---|---|---|',
+        '',
+        '## 3. Notes',
+        '',
+        `- Scaffolded by \`aiwg corpus curator-init\` on ${today}. Populate yield + signal-quality on first harvest.`,
+        '',
+    ].join('\n');
+    const outAbs = path.join(corpusRoot, outRel);
+    if (!opts.write)
+        return { slug, status: 'dry-run', message: `DRY-RUN PROF-S-${slug}: ${name}`, outPath: outRel, content };
+    if (fs.existsSync(outAbs))
+        return { slug, status: 'skip', message: `SKIP PROF-S-${slug} (exists)`, outPath: outRel };
+    fs.mkdirSync(path.dirname(outAbs), { recursive: true });
+    fs.writeFileSync(outAbs, content, 'utf-8');
+    return { slug, status: 'wrote', message: `WROTE PROF-S-${slug}: ${name}`, outPath: outRel, content };
+}
+//# sourceMappingURL=curator.js.map

package/dist/src/artifacts/corpus-tools/discovery-log.js

@@ -0,0 +1,70 @@
+/**
+ * discovery-log — record the source-tracking `discovery:` block on a citation
+ * sidecar (#1499). Adds or replaces the block in the sidecar frontmatter,
+ * preserving the rest of the file. Dry-run unless `write`.
+ *
+ * The `discovery` block is OPTIONAL by design (SOURCE-TRACKING §0): `date` +
+ * `surface` are the only meaningful required fields; `curator-id` is set only
+ * when the source came through a named, repeatable curator.
+ *
+ * @source historical: documentation/SOURCE-TRACKING.md §1
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+const SURFACE_VOCAB = ['x-account', 'x-search', 'x-bookmarks', 'x-foryou', 'x-following', 'rss', 'newsletter', 'web', 'referral', 'direct'];
+/** Render the `discovery:` YAML block (2-space indented under the key). */
+export function renderDiscoveryBlock(f, today) {
+    const lines = ['discovery:', `  date: ${f.date || today}`, `  surface: ${f.surface}`];
+    if (f.via)
+        lines.push(`  via: "${f.via}"`);
+    lines.push(`  curator-id: ${f.curatorId || 'null'}`);
+    if (f.harvestBatch)
+        lines.push(`  harvest-batch: ${f.harvestBatch}`);
+    if (f.harvestedBy)
+        lines.push(`  harvested-by: ${f.harvestedBy}`);
+    return lines.join('\n');
+}
+/** Drop an existing top-level `discovery:` block (key + its indented lines) from frontmatter lines. */
+function stripDiscovery(fmLines) {
+    const out = [];
+    let skipping = false;
+    for (const line of fmLines) {
+        if (skipping) {
+            if (/^\s/.test(line) || line.trim() === '')
+                continue; // still inside the block's indented body
+            skipping = false;
+        }
+        if (/^discovery:\s*$/.test(line)) {
+            skipping = true;
+            continue;
+        }
+        out.push(line);
+    }
+    return out;
+}
+/** Add or replace the discovery block in REF-XXX-citations.md frontmatter. */
+export function logDiscovery(corpusRoot, refId, opts) {
+    const today = opts.date || new Date().toISOString().slice(0, 10);
+    const block = renderDiscoveryBlock(opts, today);
+    if (!SURFACE_VOCAB.includes(opts.surface)) {
+        throw new Error(`discovery-log: unknown surface '${opts.surface}' (one of: ${SURFACE_VOCAB.join(', ')})`);
+    }
+    const sidecar = path.join(corpusRoot, 'documentation', 'citations', `${refId}-citations.md`);
+    if (!fs.existsSync(sidecar)) {
+        return { refId, status: 'skip', message: `SKIP ${refId}: no citation sidecar found`, block };
+    }
+    const text = fs.readFileSync(sidecar, 'utf-8');
+    const m = text.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+    if (!m) {
+        return { refId, status: 'skip', message: `SKIP ${refId}: citation sidecar has no YAML frontmatter`, block };
+    }
+    const fmLines = stripDiscovery(m[1].split('\n'));
+    const newFm = [...fmLines, block].join('\n');
+    const content = `---\n${newFm}\n---\n${m[2]}`;
+    if (!opts.write) {
+        return { refId, status: 'dry-run', message: `DRY-RUN ${refId}: would set discovery (surface=${opts.surface}${opts.curatorId ? `, curator=${opts.curatorId}` : ''})`, block, content };
+    }
+    fs.writeFileSync(sidecar, content, 'utf-8');
+    return { refId, status: 'wrote', message: `WROTE discovery block to ${refId}-citations.md`, block, content };
+}
+//# sourceMappingURL=discovery-log.js.map

package/dist/src/artifacts/corpus-tools/funder-network.js

@@ -0,0 +1,141 @@
+/**
+ * funder-network — bipartite funder↔paper analytics (#1500).
+ *
+ * Port of profiles/funder_network.py: per-funder paper/A-grade/mean-grade rollup,
+ * mean CD-index + novelty-bias (reusing the #1501 CD-index), and co-funding
+ * clusters. Funder linkage comes from the #1497 parser (`funders[]` on each REF).
+ * FUNDER_ALIASES are NOT ported — the optional acknowledgement scan reads a
+ * corpus-local `documentation/profiles/funder-aliases.yaml` (absent → no aliasing).
+ *
+ * @source historical: profiles/funder_network.py
+ * Reference: Wang et al. 2017 (novelty bias); Funk & Owen-Smith 2017 (novelty).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { load as loadYaml } from 'js-yaml';
+import { loadCorpus } from '../corpus-views/ref-parser.js';
+import { buildCitationGraph, cdIndex } from './corpus-graph.js';
+import { readAnalysisGrade } from './radar-shared.js';
+/** Wang et al. 2017 corpus-mean novelty baseline (override via funder-aliases.yaml `novelty-baseline`). */
+const DEFAULT_NOVELTY_BASELINE = 0.41;
+const GRADE_W = { A: 4, B: 3, C: 2, D: 1 };
+function gradeNum(g) {
+    return GRADE_W[(g[0] ?? '').toUpperCase()] ?? null;
+}
+/** Load corpus-local funder aliases (raw lowercase name → PROF-F/PROF-O id) + novelty baseline. */
+export function loadFunderAliases(corpusRoot) {
+    const file = path.join(corpusRoot, 'documentation', 'profiles', 'funder-aliases.yaml');
+    const aliases = new Map();
+    let baseline = DEFAULT_NOVELTY_BASELINE;
+    try {
+        const raw = loadYaml(fs.readFileSync(file, 'utf-8'));
+        if (raw && typeof raw === 'object') {
+            const o = raw;
+            if (typeof o['novelty-baseline'] === 'number')
+                baseline = o['novelty-baseline'];
+            const a = o.aliases;
+            if (a && typeof a === 'object')
+                for (const [k, v] of Object.entries(a))
+                    aliases.set(k.toLowerCase(), String(v));
+        }
+    }
+    catch {
+        /* absent → no aliasing */
+    }
+    return { aliases, baseline };
+}
+function buildFunderCtx(corpusRoot, scanAcks) {
+    const { records } = loadCorpus(corpusRoot);
+    const byId = new Map(records.map((r) => [r.refId, r]));
+    const cite = buildCitationGraph(records);
+    const cdByRef = new Map(records.map((r) => [r.refId, cdIndex(r.refId, cite)]));
+    const { aliases, baseline } = loadFunderAliases(corpusRoot);
+    const funderPapers = new Map();
+    const add = (fid, ref) => (funderPapers.get(fid) ?? funderPapers.set(fid, []).get(fid)).push(ref);
+    for (const r of records)
+        for (const f of r.funders)
+            if (f.id)
+                add(f.id, r.refId);
+    // Optional acknowledgement scan (externalized aliases only).
+    if (scanAcks && aliases.size) {
+        for (const r of records) {
+            if (r.funders.length)
+                continue; // sidecar funders take precedence
+            const text = fs.existsSync(r.path) ? fs.readFileSync(r.path, 'utf-8').toLowerCase() : '';
+            const ackIdx = Math.max(text.indexOf('## acknowledgement'), text.indexOf('**acknowledgement'));
+            if (ackIdx < 0)
+                continue;
+            const ack = text.slice(ackIdx, ackIdx + 2000);
+            for (const [alias, fid] of aliases)
+                if (ack.includes(alias))
+                    add(fid, r.refId);
+        }
+    }
+    return { funderPapers, byId, cdByRef, baseline };
+}
+/** Per-funder analytics, ranked by paper count. */
+export function funderRows(corpusRoot, opts = {}) {
+    const { funderPapers, byId, cdByRef, baseline } = buildFunderCtx(corpusRoot, !!opts.scanAcks);
+    const rows = [];
+    for (const [funderId, papersRaw] of funderPapers) {
+        const papers = [...new Set(papersRaw)].sort();
+        const grades = papers.map((r) => readAnalysisGrade(corpusRoot, r));
+        const gradeNums = grades.map(gradeNum).filter((x) => x != null);
+        const cds = papers.map((r) => cdByRef.get(r) ?? null).filter((x) => x != null);
+        const topicCount = new Map();
+        const years = [];
+        for (const r of papers) {
+            for (const t of byId.get(r)?.topics ?? [])
+                topicCount.set(t, (topicCount.get(t) ?? 0) + 1);
+            const y = byId.get(r)?.year;
+            if (y != null)
+                years.push(y);
+        }
+        const meanCd = cds.length ? Math.round((cds.reduce((a, b) => a + b, 0) / cds.length) * 1e4) / 1e4 : null;
+        const noveltyBias = meanCd == null ? null : meanCd < baseline - 0.1 ? 'below-baseline' : meanCd > baseline + 0.1 ? 'above-baseline' : 'baseline';
+        rows.push({
+            funderId,
+            paperCount: papers.length,
+            aGradeCount: grades.filter((g) => g.toUpperCase().startsWith('A')).length,
+            meanGrade: gradeNums.length ? Math.round((gradeNums.reduce((a, b) => a + b, 0) / gradeNums.length) * 100) / 100 : null,
+            meanCdIndex: meanCd,
+            noveltyBias,
+            topTopics: [...topicCount.entries()].sort((a, b) => b[1] - a[1]).slice(0, 5).map(([t]) => t),
+            yearRange: years.length ? [Math.min(...years), Math.max(...years)] : null,
+            papers,
+        });
+    }
+    return rows.sort((a, b) => b.paperCount - a.paperCount || (a.funderId < b.funderId ? -1 : 1));
+}
+/** Papers with ≥2 funders (co-funding), ranked by funder count. */
+export function cofundingClusters(corpusRoot) {
+    const { records } = loadCorpus(corpusRoot);
+    const clusters = [];
+    for (const r of records) {
+        const funders = [...new Set(r.funders.map((f) => f.id).filter(Boolean))];
+        if (funders.length >= 2)
+            clusters.push({ paper: r.refId, funders, count: funders.length });
+    }
+    return clusters.sort((a, b) => b.count - a.count || (a.paper < b.paper ? -1 : 1));
+}
+/** Render the funder-network markdown index. */
+export function renderFunderNetwork(rows, clusters) {
+    const lines = [
+        '# Funder Network',
+        '',
+        `**Funders tracked**: ${rows.length} · **Co-funded papers**: ${clusters.length}`,
+        '',
+        '| Funder | Papers | A-Grade | Mean Grade | Mean CD | Novelty Bias | Top Topics |',
+        '|---|---:|---:|---:|---:|---|---|',
+    ];
+    for (const r of rows) {
+        lines.push(`| ${r.funderId} | ${r.paperCount} | ${r.aGradeCount} | ${r.meanGrade ?? '—'} | ${r.meanCdIndex ?? '—'} | ${r.noveltyBias ?? '—'} | ${r.topTopics.slice(0, 3).join(', ') || '—'} |`);
+    }
+    if (clusters.length) {
+        lines.push('', '## Co-Funded Papers', '', '| Paper | Funders | Count |', '|---|---|---:|');
+        for (const c of clusters.slice(0, 20))
+            lines.push(`| ${c.paper} | ${c.funders.join(', ')} | ${c.count} |`);
+    }
+    return lines.join('\n') + '\n';
+}
+//# sourceMappingURL=funder-network.js.map

package/dist/src/artifacts/corpus-tools/induction-audit.js

@@ -0,0 +1,233 @@
+/**
+ * Induction quality: frontmatter backfill + per-type induction depth audit (#1504).
+ *
+ * TS-native port of section9 `backfill_frontmatter.py` + `audit_inductions.py`.
+ * The audit is **source-type-aware** (#1509): required-section checks come from
+ * the source-type registry, so a blog isn't flagged for missing "Benchmark
+ * Results" and a repo is checked for "Architecture"/"Maintenance Signals". This
+ * is the audit consumer that demonstrates the #1509 registry end-to-end.
+ *
+ * Reconciles with `research-quality-audit` (GRADE evidence quality) and
+ * `best-practices-audit` (corpus-wide best practices): this is the structural +
+ * depth + per-type-section induction check, not a GRADE assessment.
+ *
+ * @source historical: corpus/audit_inductions.py, corpus/backfill_frontmatter.py
+ * @tests @test/unit/artifacts/induction-audit.test.ts
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { createHash } from 'crypto';
+import { parseFrontmatter } from '../corpus-views/ref-parser.js';
+import { classifyFirst, VENUE_PATTERNS } from '../corpus-views/taxonomies.js';
+import { loadSourceTypeRegistry, normalizeSourceType, getSourceType, } from './source-types.js';
+const REFS_DIR = ['documentation', 'references'];
+const CITES_DIR = ['documentation', 'citations'];
+const PDFS_DIR = ['pdfs', 'full'];
+const LEGACY_EXCLUDED_TYPES = new Set(['redirect', 'gap-note', 'chapter']);
+function asStr(v) {
+    return v == null ? '' : String(v);
+}
+// ── Depth bands (port of audit_inductions depth logic) ───────────────────────
+function depthBand(lines) {
+    if (lines < 80)
+        return 'STUB';
+    if (lines < 150)
+        return 'compact';
+    if (lines < 250)
+        return 'good';
+    if (lines < 400)
+        return 'full';
+    return 'deep';
+}
+function refFiles(root) {
+    const dir = path.join(root, ...REFS_DIR);
+    if (!fs.existsSync(dir))
+        return [];
+    return fs.readdirSync(dir).filter((f) => /^REF-\d{3,4}[a-z]?(-.*)?\.md$/.test(f)).sort();
+}
+function refIdOf(filename) {
+    const m = filename.match(/^(REF-\d{3,4}[a-z]?)/);
+    return m ? m[1] : null;
+}
+function findAnalysis(root, refId) {
+    const dir = path.join(root, ...REFS_DIR);
+    if (!fs.existsSync(dir))
+        return null;
+    const m = fs.readdirSync(dir).find((f) => f === `${refId}.md` || f.startsWith(`${refId}-`));
+    return m ? path.join(dir, m) : null;
+}
+function hasPdf(root, refId) {
+    const dir = path.join(root, ...PDFS_DIR);
+    if (!fs.existsSync(dir))
+        return false;
+    return fs.readdirSync(dir).some((f) => f === `${refId}.pdf` || f.startsWith(`${refId}-`));
+}
+/** Audit one ref. Required sections come from its source type's registry entry. */
+function auditRef(root, refId, reg) {
+    const r = {
+        ref: refId, analysisExists: false, analysisLines: 0, sidecarExists: false,
+        pdfExists: false, pdfExcluded: false, sourceType: 'other', depthBand: '',
+        missingSections: [], issues: [],
+    };
+    const analysis = findAnalysis(root, refId);
+    if (analysis) {
+        r.analysisExists = true;
+        const text = fs.readFileSync(analysis, 'utf-8');
+        const low = text.toLowerCase();
+        r.analysisLines = text.split('\n').length;
+        r.depthBand = depthBand(r.analysisLines);
+        if (r.depthBand === 'STUB')
+            r.issues.push('below-80-line-stub-threshold');
+        const fm = parseFrontmatter(text);
+        const venue = classifyFirst(text.slice(0, 3500).toLowerCase(), VENUE_PATTERNS);
+        r.sourceType = normalizeSourceType({ type: asStr(fm.type), sourceType: asStr(fm.source_type), venue }, reg);
+        // Required sections by source type (the #1509 consumer). `meta` docs
+        // (redirects/stubs) are exempt; unknown types fall back to a base set.
+        if (r.sourceType !== 'meta') {
+            const required = getSourceType(r.sourceType, reg)?.requiredSections ?? ['Citation', 'Summary'];
+            for (const sec of required) {
+                if (!low.includes(sec.toLowerCase()))
+                    r.missingSections.push(sec);
+            }
+        }
+        // PDF-exclusion conventions (audit-exclude-missing-pdf flag or legacy type).
+        const flag = asStr(fm['audit-exclude-missing-pdf']).toLowerCase();
+        if (['true', 'yes', '1'].includes(flag))
+            r.pdfExcluded = true;
+        if (LEGACY_EXCLUDED_TYPES.has(asStr(fm.type).toLowerCase()))
+            r.pdfExcluded = true;
+    }
+    else {
+        r.issues.push('MISSING-ANALYSIS-DOC');
+    }
+    r.sidecarExists = fs.existsSync(path.join(root, ...CITES_DIR, `${refId}-citations.md`));
+    if (!r.sidecarExists)
+        r.issues.push('MISSING-SIDECAR');
+    r.pdfExists = hasPdf(root, refId);
+    if (r.pdfExists && r.pdfExcluded)
+        r.issues.push('PDF-PRESENT-BUT-MARKED-EXCLUDED');
+    else if (!r.pdfExists && !r.pdfExcluded)
+        r.issues.push('MISSING-PDF');
+    // missingSections is an informational per-type completeness signal, not a hard
+    // issue — the registry's required set is the type's full template, which real
+    // inductions don't always fill. Structural problems + stub depth are the issues.
+    return r;
+}
+export function auditInductions(root, opts = {}) {
+    const reg = loadSourceTypeRegistry(root);
+    let ids;
+    if (opts.refs?.length) {
+        ids = opts.refs;
+    }
+    else if (opts.start != null && opts.end != null) {
+        ids = [];
+        for (let n = opts.start; n <= opts.end; n++)
+            ids.push(`REF-${n}`);
+    }
+    else {
+        ids = refFiles(root).map(refIdOf).filter((x) => !!x);
+        ids = [...new Set(ids)];
+    }
+    return ids.map((id) => auditRef(root, id, reg));
+}
+export function renderAudit(results) {
+    const out = [];
+    const present = results.filter((r) => r.analysisExists);
+    const bands = {};
+    for (const r of present)
+        bands[r.depthBand] = (bands[r.depthBand] ?? 0) + 1;
+    out.push(`Induction audit — ${results.length} refs`);
+    out.push(`Analysis present: ${present.length}/${results.length}`);
+    out.push(`Sidecars present: ${results.filter((r) => r.sidecarExists).length}/${results.length}`);
+    out.push(`Depth bands: ${['STUB', 'compact', 'good', 'full', 'deep'].map((b) => `${b}=${bands[b] ?? 0}`).join('  ')}`);
+    // Per-type required-section completeness (informational — consumes the #1509 registry).
+    const incompleteByType = {};
+    for (const r of present)
+        if (r.missingSections.length)
+            incompleteByType[r.sourceType] = (incompleteByType[r.sourceType] ?? 0) + 1;
+    if (Object.keys(incompleteByType).length) {
+        out.push(`Per-type incomplete required sections: ${Object.entries(incompleteByType).map(([t, n]) => `${t}=${n}`).join('  ')}`);
+    }
+    out.push('');
+    out.push(`${'REF'.padEnd(10)} ${'type'.padEnd(14)} ${'lines'.padEnd(6)} ${'band'.padEnd(8)} ${'miss-sec'.padEnd(8)} issues`);
+    for (const r of results) {
+        if (!r.issues.length && r.depthBand !== 'STUB' && r.missingSections.length === 0)
+            continue;
+        out.push(`${r.ref.padEnd(10)} ${r.sourceType.padEnd(14)} ${String(r.analysisLines).padEnd(6)} ${r.depthBand.padEnd(8)} ${String(r.missingSections.length).padEnd(8)} ${r.issues.join(', ')}`);
+    }
+    const clean = results.filter((r) => !r.issues.length).length;
+    out.push('');
+    out.push(`${clean}/${results.length} refs free of structural issues; section-completeness shown above (informational).`);
+    return out.join('\n') + '\n';
+}
+function extractTitle(refId, text) {
+    const m1 = text.match(new RegExp(`^#\\s+${refId}[:\\s]+(.+?)\\s*$`, 'm'));
+    if (m1)
+        return m1[1].trim();
+    const m2 = text.match(/^#\s+(.+?)\s*$/m);
+    if (m2)
+        return m2[1].replace(new RegExp(`^${refId}[:\\s]+`), '').trim();
+    return null;
+}
+function extractYear(text) {
+    const cite = text.match(/^##\s+(?:1\.\s*)?Citation\s*\n+([\s\S]*?)(?:\n##|$)/m);
+    const space = (cite ? cite[1] : text).slice(0, 3000);
+    const paren = space.match(/\((19|20)\d{2}\)/);
+    if (paren)
+        return paren[0].replace(/[()]/g, '');
+    const bare = space.match(/\b(19|20)\d{2}\b/);
+    return bare ? bare[0] : null;
+}
+function pdfHash(root, refId) {
+    const dir = path.join(root, ...PDFS_DIR);
+    if (!fs.existsSync(dir))
+        return null;
+    const m = fs.readdirSync(dir).find((f) => f === `${refId}.pdf` || f.startsWith(`${refId}-`));
+    if (!m)
+        return null;
+    return createHash('sha256').update(fs.readFileSync(path.join(dir, m))).digest('hex');
+}
+/** Additive frontmatter backfill: skips docs that already have frontmatter. */
+export function backfillFrontmatter(root, opts = {}) {
+    const dir = path.join(root, ...REFS_DIR);
+    const res = { changed: [], skippedExisting: 0, holdouts: [] };
+    if (!fs.existsSync(dir))
+        return res;
+    const date = opts.date ?? 'backfilled';
+    for (const f of fs.readdirSync(dir).filter((x) => /^REF-.*\.md$/.test(x)).sort()) {
+        const refId = refIdOf(f);
+        if (!refId)
+            continue;
+        const full = path.join(dir, f);
+        const text = fs.readFileSync(full, 'utf-8');
+        if (text.startsWith('---\n')) {
+            res.skippedExisting++;
+            continue;
+        }
+        const title = extractTitle(refId, text);
+        const year = extractYear(text);
+        if (!title || !year) {
+            const missing = [!title && 'title', !year && 'year'].filter(Boolean).join(',');
+            res.holdouts.push({ ref: refId, missing });
+            continue;
+        }
+        const digest = pdfHash(root, refId);
+        const fm = ['---', `ref_id: ${refId}`, `title: ${JSON.stringify(title)}`, `year: ${year}`];
+        if (digest)
+            fm.push(`pdf_hash: ${JSON.stringify(digest)}`);
+        fm.push(`frontmatter-backfilled: ${date}`, '---', '');
+        if (opts.write)
+            fs.writeFileSync(full, fm.join('\n') + text);
+        res.changed.push(refId);
+    }
+    return res;
+}
+export function renderBackfill(r, write) {
+    const out = [];
+    out.push(`frontmatter-backfill (${write ? 'WRITE' : 'dry-run'})`);
+    out.push(`changed: ${r.changed.length}  skipped (already had frontmatter): ${r.skippedExisting}  holdouts: ${r.holdouts.length}`);
+    for (const h of r.holdouts.slice(0, 20))
+        out.push(`  ! ${h.ref}: missing ${h.missing}`);
+    return out.join('\n') + '\n';
+}
+//# sourceMappingURL=induction-audit.js.map