@pareto4/pp-core 1.19.0 → 1.21.0

package/pp-core/bin/lib/discovery-integrations.cjs

@@ -0,0 +1,286 @@
+"use strict";
+/**
+ * Discovery integrations check (Discovery Sprint improvement plan, Batch 3).
+ *
+ * `.planning/discovery/_integrations.md` is the register of interfaces with
+ * other systems: `IF-nn` rows seeded by Session 5 (system, direction,
+ * pattern, owner, requirements) and completed by Session 8 (protocol, format,
+ * idempotency), a `## Contract` table of fields per interface, and an
+ * `## Errors` table of failure handling per interface. The step matrices of
+ * `_processes.md` name an interface by its `IF-nn` in their `Integration`
+ * cell, which is how the build's planner finds the interfaces a phase
+ * touches. This module checks the structure:
+ *
+ *   - the three sections exist with the template's columns;
+ *   - `IF-` IDs are well-formed, unique, contiguous;
+ *   - `Direction` and a contract field's `Required` come from closed
+ *     vocabularies; the cells the sessions must fill are non-empty;
+ *   - every contract and error row names an interface of `## Interfaces`;
+ *   - every `IF-nn` a step matrix cites exists (`unknown_interface` located
+ *     in `_processes.md`);
+ *   - every cited requirement exists in `_requirements.md` when it is on file
+ *     and parseable;
+ *   - `--require-cited`: an interface whose `Requirements` is still `—`, or a
+ *     step whose `Integration` cell names a system without an `IF-nn`, fails
+ *     on its own exit identity, so the handoff can hard-block on it while
+ *     Sessions 8 and 13 only report.
+ *
+ * Posture (D-43/D-53): reports at Sessions 8 and 13; hard-blocks at the
+ * handoff. Absent artifact → exit 0.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const io = require("./io.cjs");
+const { output, error, ERROR_REASON } = io;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const table = require("./discovery-table.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const rollup = require("./discovery-rollup.cjs");
+// ─── Constants ────────────────────────────────────────────────────────────────
+const DISCOVERY_DIR = '.planning/discovery';
+const INTEGRATIONS_FILE = `${DISCOVERY_DIR}/_integrations.md`;
+const REQUIREMENTS_FILE = `${DISCOVERY_DIR}/_requirements.md`;
+const PROCESSES_FILE = `${DISCOVERY_DIR}/_processes.md`;
+const INTERFACES_SECTION = 'Interfaces';
+const CONTRACT_SECTION = 'Contract';
+const ERRORS_SECTION = 'Errors';
+const INTERFACES_HEADER = Object.freeze(['ID', 'System', 'Direction', 'Pattern', 'Protocol', 'Format', 'Idempotency', 'Owner', 'Requirements']);
+const CONTRACT_HEADER = Object.freeze(['Interface', 'Field', 'Type', 'Required', 'Mapping', 'Validation']);
+const ERRORS_HEADER = Object.freeze(['Interface', 'Failure', 'Handling', 'Retry', 'Dead letter', 'Alert']);
+const IF_RE = /^IF-(\d{2})$/;
+const IF_TOKEN_RE = /\bIF-\d{2}\b/g;
+const DIRECTIONS = Object.freeze(['inbound', 'outbound', 'bidirectional']);
+const REQUIRED = Object.freeze(['yes', 'no']);
+const REQUIREMENT_ID_RE = /^[A-Z][A-Z0-9]*-\d+$/;
+const PENDING = '—';
+const STEPS_INTEGRATION_COLUMN = 'Integration';
+const USAGE = 'Usage: pp-tools discovery integrations-check [--require-cited]';
+function readIfPresent(abs) {
+    if (!node_fs_1.default.existsSync(abs))
+        return { kind: 'absent' };
+    try {
+        return { kind: 'ok', content: node_fs_1.default.readFileSync(abs, 'utf-8') };
+    }
+    catch {
+        return { kind: 'unreadable' };
+    }
+}
+function sameHeader(actual, expected) {
+    return actual.length === expected.length && actual.every((c, i) => c.trim().toLowerCase() === expected[i].toLowerCase());
+}
+function splitList(cell) {
+    return cell.split(',').map((t) => t.trim()).filter(Boolean);
+}
+/** The `Integration` cells of every step table in `_processes.md` § Steps, by header name. */
+function stepIntegrationCells(content) {
+    const out = [];
+    const steps = table.splitSections(content.split(/\r?\n/), 2).find((s) => s.heading === 'Steps');
+    if (!steps)
+        return out;
+    for (const t of table.parseTables(steps.body)) {
+        const col = t.header.findIndex((h) => h.trim().toLowerCase() === STEPS_INTEGRATION_COLUMN.toLowerCase());
+        if (col === -1)
+            continue;
+        for (const r of t.rows)
+            out.push({ line: r.line, cell: (r.cells[col] ?? '').trim() });
+    }
+    return out;
+}
+function sectionTable(content, heading, expected, violations) {
+    const section = table.splitSections(content.split(/\r?\n/), 2).find((s) => s.heading === heading);
+    if (!section) {
+        violations.push({ artifact: INTEGRATIONS_FILE, reason: 'missing_section', id: heading });
+        return null;
+    }
+    const tables = table.parseTables(section.body);
+    if (tables.length === 0) {
+        violations.push({ artifact: INTEGRATIONS_FILE, reason: 'missing_section', line: section.line, id: heading });
+        return null;
+    }
+    if (!sameHeader(tables[0].header, expected)) {
+        violations.push({ artifact: INTEGRATIONS_FILE, reason: 'bad_table_shape', line: tables[0].line, id: heading });
+        return null;
+    }
+    return tables[0];
+}
+// ─── Check ────────────────────────────────────────────────────────────────────
+function checkIntegrations(content, sources, requireCited = false) {
+    const violations = [];
+    const interfaces = sectionTable(content, INTERFACES_SECTION, INTERFACES_HEADER, violations);
+    const contract = sectionTable(content, CONTRACT_SECTION, CONTRACT_HEADER, violations);
+    const errors = sectionTable(content, ERRORS_SECTION, ERRORS_HEADER, violations);
+    const ids = new Set();
+    const seqs = [];
+    let uncited = 0;
+    if (interfaces) {
+        for (const row of interfaces.rows) {
+            const [id, system, direction, pattern, protocol, format, idempotency, owner, requirements] = row.cells.map((c) => c.trim());
+            const line = row.line;
+            const m = IF_RE.exec(id ?? '');
+            if (!m)
+                violations.push({ artifact: INTEGRATIONS_FILE, reason: 'bad_id', line });
+            else if (ids.has(id))
+                violations.push({ artifact: INTEGRATIONS_FILE, reason: 'duplicate_id', line, id });
+            else {
+                ids.add(id);
+                seqs.push(Number(m[1]));
+            }
+            const required = [['System', system], ['Pattern', pattern], ['Protocol', protocol], ['Format', format], ['Idempotency', idempotency], ['Owner', owner]];
+            for (const [name, cell] of required)
+                if ((cell ?? '') === '')
+                    violations.push({ artifact: INTEGRATIONS_FILE, reason: 'empty_cell', line, id: name });
+            if (!DIRECTIONS.includes(direction ?? ''))
+                violations.push({ artifact: INTEGRATIONS_FILE, reason: 'bad_direction', line });
+            const reqCell = requirements ?? '';
+            if (reqCell === '' || reqCell === PENDING) {
+                uncited += 1;
+                if (requireCited)
+                    violations.push({ artifact: INTEGRATIONS_FILE, reason: 'uncited_interface', line, id: m ? id : undefined });
+            }
+            else {
+                for (const r of splitList(reqCell)) {
+                    if (!REQUIREMENT_ID_RE.test(r))
+                        violations.push({ artifact: INTEGRATIONS_FILE, reason: 'unknown_requirement_id', line, id: r.slice(0, 40) });
+                    else if (sources.requirementIds instanceof Set && !sources.requirementIds.has(r))
+                        violations.push({ artifact: INTEGRATIONS_FILE, reason: 'unknown_requirement_id', line, id: r });
+                }
+            }
+        }
+        const max = table.boundedSequenceMax(seqs);
+        if (max !== null) {
+            const have = new Set(seqs);
+            for (let n = 1; n <= max; n += 1) {
+                if (!have.has(n))
+                    violations.push({ artifact: INTEGRATIONS_FILE, reason: 'sequence_gap', id: `IF-${String(n).padStart(2, '0')}` });
+            }
+        }
+    }
+    const interfaceRef = (ref, line) => {
+        if (!IF_RE.test(ref))
+            violations.push({ artifact: INTEGRATIONS_FILE, reason: 'unknown_interface', line, id: ref.slice(0, 40) });
+        else if (interfaces && !ids.has(ref))
+            violations.push({ artifact: INTEGRATIONS_FILE, reason: 'unknown_interface', line, id: ref });
+    };
+    if (contract) {
+        for (const row of contract.rows) {
+            const [ref, field, type, required] = row.cells.map((c) => c.trim());
+            interfaceRef(ref ?? '', row.line);
+            if ((field ?? '') === '')
+                violations.push({ artifact: INTEGRATIONS_FILE, reason: 'empty_cell', line: row.line, id: 'Field' });
+            if ((type ?? '') === '')
+                violations.push({ artifact: INTEGRATIONS_FILE, reason: 'empty_cell', line: row.line, id: 'Type' });
+            if (!REQUIRED.includes(required ?? ''))
+                violations.push({ artifact: INTEGRATIONS_FILE, reason: 'bad_required', line: row.line });
+        }
+    }
+    if (errors) {
+        for (const row of errors.rows) {
+            const [ref, failure, handling] = row.cells.map((c) => c.trim());
+            interfaceRef(ref ?? '', row.line);
+            if ((failure ?? '') === '')
+                violations.push({ artifact: INTEGRATIONS_FILE, reason: 'empty_cell', line: row.line, id: 'Failure' });
+            if ((handling ?? '') === '')
+                violations.push({ artifact: INTEGRATIONS_FILE, reason: 'empty_cell', line: row.line, id: 'Handling' });
+        }
+    }
+    if (sources.stepIntegrations !== null && interfaces) {
+        for (const { line, cell } of sources.stepIntegrations) {
+            if (cell === '' || cell === PENDING)
+                continue;
+            const tokens = cell.match(IF_TOKEN_RE) ?? [];
+            for (const t of tokens)
+                if (!ids.has(t))
+                    violations.push({ artifact: PROCESSES_FILE, reason: 'unknown_interface', line, id: t });
+            if (tokens.length === 0 && requireCited)
+                violations.push({ artifact: PROCESSES_FILE, reason: 'step_integration_unlinked', line });
+        }
+    }
+    if (sources.requirementIds === 'unparseable')
+        violations.push({ artifact: REQUIREMENTS_FILE, reason: 'requirements_unparseable' });
+    return {
+        ok: violations.length === 0,
+        interfaces: ids.size,
+        contract_rows: contract ? contract.rows.length : 0,
+        error_rows: errors ? errors.rows.length : 0,
+        uncited,
+        violations,
+    };
+}
+function checkProjectIntegrations(cwd, requireCited = false) {
+    const read = readIfPresent(node_path_1.default.join(cwd, INTEGRATIONS_FILE));
+    if (read.kind === 'absent')
+        return null;
+    if (read.kind === 'unreadable') {
+        return { ok: false, file: INTEGRATIONS_FILE, interfaces: 0, contract_rows: 0, error_rows: 0, uncited: 0, violations: [{ artifact: INTEGRATIONS_FILE, reason: 'artifact_unreadable' }] };
+    }
+    const extra = [];
+    const sources = { requirementIds: null, stepIntegrations: null };
+    const req = readIfPresent(node_path_1.default.join(cwd, REQUIREMENTS_FILE));
+    if (req.kind === 'unreadable')
+        extra.push({ artifact: REQUIREMENTS_FILE, reason: 'artifact_unreadable' });
+    if (req.kind === 'ok') {
+        const parsed = rollup.parseRequirementsArtifact(req.content);
+        sources.requirementIds = parsed.ok ? new Set(parsed.rows.map((r) => r.id)) : 'unparseable';
+    }
+    const proc = readIfPresent(node_path_1.default.join(cwd, PROCESSES_FILE));
+    if (proc.kind === 'unreadable')
+        extra.push({ artifact: PROCESSES_FILE, reason: 'artifact_unreadable' });
+    if (proc.kind === 'ok')
+        sources.stepIntegrations = stepIntegrationCells(proc.content);
+    const result = checkIntegrations(read.content, sources, requireCited);
+    result.violations.push(...extra);
+    result.ok = result.violations.length === 0;
+    return { file: INTEGRATIONS_FILE, ...result };
+}
+function formatViolation(v) {
+    const where = v.line !== undefined ? `:${v.line}` : '';
+    const what = v.id !== undefined ? ` (${v.id})` : '';
+    return `  - ${v.artifact}${where}: ${v.reason}${what}`;
+}
+// ─── CLI adapter ──────────────────────────────────────────────────────────────
+const STRICT_ONLY = new Set(['uncited_interface', 'step_integration_unlinked']);
+/**
+ * `pp-tools discovery integrations-check [--require-cited]` (dotted
+ * `query discovery.integrations-check`). Absent artifact → exit 0,
+ * `present: false`. Structural faults exit via
+ * `DISCOVERY_INTEGRATIONS_CHECK_FAILED`; when every fault was raised by
+ * `--require-cited`, the identity is `DISCOVERY_INTEGRATIONS_UNCITED`.
+ */
+function cmdDiscoveryIntegrationsCheck(cwd, args, raw) {
+    const rest = args.slice(2);
+    const requireCited = rest.includes('--require-cited');
+    if (rest.some((a) => a !== '--require-cited')) {
+        error(USAGE, ERROR_REASON.USAGE);
+        return; // unreachable
+    }
+    const result = checkProjectIntegrations(cwd, requireCited);
+    if (result === null) {
+        output({ ok: true, present: false, file: INTEGRATIONS_FILE }, raw);
+        return;
+    }
+    const payload = { ok: result.ok, present: true, file: result.file, interfaces: result.interfaces, contract_rows: result.contract_rows, error_rows: result.error_rows, uncited: result.uncited };
+    if (!result.ok) {
+        output({ ...payload, violations: result.violations.length }, raw);
+        const onlyStrict = result.violations.every((v) => STRICT_ONLY.has(v.reason));
+        error(`discovery integrations-check: ${result.violations.length} violation(s):\n` + result.violations.map(formatViolation).join('\n'), onlyStrict ? ERROR_REASON.DISCOVERY_INTEGRATIONS_UNCITED : ERROR_REASON.DISCOVERY_INTEGRATIONS_CHECK_FAILED);
+        return; // unreachable
+    }
+    output(payload, raw);
+}
+module.exports = {
+    INTEGRATIONS_FILE,
+    INTERFACES_HEADER,
+    CONTRACT_HEADER,
+    ERRORS_HEADER,
+    DIRECTIONS,
+    INTEGRATIONS_CHECK_FAILED: ERROR_REASON.DISCOVERY_INTEGRATIONS_CHECK_FAILED,
+    INTEGRATIONS_UNCITED: ERROR_REASON.DISCOVERY_INTEGRATIONS_UNCITED,
+    stepIntegrationCells,
+    checkIntegrations,
+    checkProjectIntegrations,
+    cmdDiscoveryIntegrationsCheck,
+};

package/pp-core/bin/lib/discovery-migration.cjs

@@ -0,0 +1,246 @@
+"use strict";
+/**
+ * Discovery migration check (Discovery Sprint improvement plan, Batch 3).
+ *
+ * `.planning/discovery/_migration.md` is the register of data the new
+ * solution takes over from existing systems: `MG-nn` rows naming the source
+ * system (a system of Session 2's Systems Landscape), the entities moved
+ * (rows of `_entities.md`), the volume, the mapping, the cut-over strategy,
+ * the reconciliation that proves the move, and the requirements the row
+ * realises. Session 2 topic 7 seeds it (what has to move, how much); Session
+ * 8 topic 6 completes it (mapping, cut-over, reconciliation) and back-fills
+ * the requirements. The build's migration phase reads it by requirement ID.
+ * This module checks the structure:
+ *
+ *   - the `## Migration` table exists with the template's columns;
+ *   - `MG-` IDs are well-formed, unique, contiguous;
+ *   - the source system is one Session 2's Systems Landscape lists, when that
+ *     table is on file with rows;
+ *   - every entity is a PascalCase name present in `_entities.md` when it is
+ *     on file;
+ *   - the cells the sessions must fill are non-empty (`—` is a pending cell);
+ *   - every cited requirement exists in `_requirements.md` when it is on file
+ *     and parseable;
+ *   - `--require-cited`: a row whose `Requirements` is still `—` fails on its
+ *     own exit identity, so the handoff can hard-block on it while Sessions 8
+ *     and 13 only report.
+ *
+ * Posture (D-43/D-53): reports at Sessions 8 and 13; hard-blocks at the
+ * handoff. Absent artifact → exit 0 — most engagements migrate nothing.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const io = require("./io.cjs");
+const { output, error, ERROR_REASON } = io;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const table = require("./discovery-table.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const rollup = require("./discovery-rollup.cjs");
+// ─── Constants ────────────────────────────────────────────────────────────────
+const DISCOVERY_DIR = '.planning/discovery';
+const MIGRATION_FILE = `${DISCOVERY_DIR}/_migration.md`;
+const REQUIREMENTS_FILE = `${DISCOVERY_DIR}/_requirements.md`;
+const ENTITIES_FILE = `${DISCOVERY_DIR}/_entities.md`;
+const SESSION_02_FILE = `${DISCOVERY_DIR}/session-02.md`;
+const MIGRATION_SECTION = 'Migration';
+const MIGRATION_HEADER = Object.freeze(['ID', 'Source system', 'Entity', 'Volume', 'Mapping', 'Cut-over', 'Reconciliation', 'Requirements']);
+const MG_RE = /^MG-(\d{2})$/;
+const ENTITY_NAME_RE = /^[A-Z][A-Za-z0-9]*$/;
+const REQUIREMENT_ID_RE = /^[A-Z][A-Z0-9]*-\d+$/;
+const PENDING = '—';
+const SYSTEMS_LANDSCAPE_LABEL = 'Systems Landscape';
+const USAGE = 'Usage: pp-tools discovery migration-check [--require-cited]';
+function readIfPresent(abs) {
+    if (!node_fs_1.default.existsSync(abs))
+        return { kind: 'absent' };
+    try {
+        return { kind: 'ok', content: node_fs_1.default.readFileSync(abs, 'utf-8') };
+    }
+    catch {
+        return { kind: 'unreadable' };
+    }
+}
+function sameHeader(actual, expected) {
+    return actual.length === expected.length && actual.every((c, i) => c.trim().toLowerCase() === expected[i].toLowerCase());
+}
+function splitList(cell) {
+    return cell.split(',').map((t) => t.trim()).filter(Boolean);
+}
+function firstColumnOf(content, heading) {
+    const section = table.splitSections(content.split(/\r?\n/), 2).find((s) => s.heading === heading);
+    if (!section)
+        return new Set();
+    const tables = table.parseTables(section.body);
+    if (tables.length === 0)
+        return new Set();
+    return new Set(tables[0].rows.map((r) => (r.cells[0] ?? '').trim()).filter(Boolean));
+}
+/** System names: the first column of Session 2's Systems Landscape table; null when absent or empty. */
+function systemsFrom(content) {
+    const lines = content.split(/\r?\n/);
+    const norm = (s) => s.replace(/^#+\s*/, '').replace(/\*\*/g, '').trim();
+    const at = lines.findIndex((l) => norm(l) === SYSTEMS_LANDSCAPE_LABEL);
+    if (at === -1)
+        return null;
+    const body = [];
+    for (let i = at + 1; i < lines.length; i += 1) {
+        if (/^#{1,3}\s/.test(lines[i]) || /^\*\*[^*]+\*\*$/.test(lines[i].trim()))
+            break;
+        body.push({ n: i + 1, text: lines[i] });
+    }
+    const tables = table.parseTables(body);
+    if (tables.length === 0)
+        return null;
+    const out = new Set(tables[0].rows.map((r) => (r.cells[0] ?? '').trim()).filter((c) => c !== ''));
+    return out.size === 0 ? null : out;
+}
+// ─── Check ────────────────────────────────────────────────────────────────────
+function checkMigration(content, sources, requireCited = false) {
+    const violations = [];
+    const section = table.splitSections(content.split(/\r?\n/), 2).find((s) => s.heading === MIGRATION_SECTION);
+    if (!section)
+        return { ok: false, rows: 0, uncited: 0, violations: [{ artifact: MIGRATION_FILE, reason: 'missing_section', id: MIGRATION_SECTION }] };
+    const tables = table.parseTables(section.body);
+    if (tables.length === 0)
+        return { ok: false, rows: 0, uncited: 0, violations: [{ artifact: MIGRATION_FILE, reason: 'missing_section', line: section.line, id: MIGRATION_SECTION }] };
+    if (!sameHeader(tables[0].header, MIGRATION_HEADER)) {
+        return { ok: false, rows: 0, uncited: 0, violations: [{ artifact: MIGRATION_FILE, reason: 'bad_table_shape', line: tables[0].line, id: MIGRATION_SECTION }] };
+    }
+    const ids = new Set();
+    const seqs = [];
+    let uncited = 0;
+    for (const row of tables[0].rows) {
+        const [id, system, entity, volume, mapping, cutOver, reconciliation, requirements] = row.cells.map((c) => c.trim());
+        const line = row.line;
+        const m = MG_RE.exec(id ?? '');
+        if (!m)
+            violations.push({ artifact: MIGRATION_FILE, reason: 'bad_id', line });
+        else if (ids.has(id))
+            violations.push({ artifact: MIGRATION_FILE, reason: 'duplicate_id', line, id });
+        else {
+            ids.add(id);
+            seqs.push(Number(m[1]));
+        }
+        if ((system ?? '') === '')
+            violations.push({ artifact: MIGRATION_FILE, reason: 'empty_cell', line, id: 'Source system' });
+        else if (sources.systems !== null && !sources.systems.has(system))
+            violations.push({ artifact: MIGRATION_FILE, reason: 'unknown_system', line, id: system.slice(0, 40) });
+        const names = splitList(entity ?? '');
+        if (names.length === 0)
+            violations.push({ artifact: MIGRATION_FILE, reason: 'bad_entity', line });
+        for (const n of names) {
+            if (!ENTITY_NAME_RE.test(n))
+                violations.push({ artifact: MIGRATION_FILE, reason: 'bad_entity', line });
+            else if (sources.entities !== null && !sources.entities.has(n))
+                violations.push({ artifact: MIGRATION_FILE, reason: 'unknown_entity', line, id: n });
+        }
+        const filled = [['Volume', volume], ['Mapping', mapping], ['Cut-over', cutOver], ['Reconciliation', reconciliation]];
+        for (const [name, cell] of filled)
+            if ((cell ?? '') === '')
+                violations.push({ artifact: MIGRATION_FILE, reason: 'empty_cell', line, id: name });
+        const reqCell = requirements ?? '';
+        if (reqCell === '' || reqCell === PENDING) {
+            uncited += 1;
+            if (requireCited)
+                violations.push({ artifact: MIGRATION_FILE, reason: 'uncited_migration', line, id: m ? id : undefined });
+        }
+        else {
+            for (const r of splitList(reqCell)) {
+                if (!REQUIREMENT_ID_RE.test(r))
+                    violations.push({ artifact: MIGRATION_FILE, reason: 'unknown_requirement_id', line, id: r.slice(0, 40) });
+                else if (sources.requirementIds instanceof Set && !sources.requirementIds.has(r))
+                    violations.push({ artifact: MIGRATION_FILE, reason: 'unknown_requirement_id', line, id: r });
+            }
+        }
+    }
+    const max = table.boundedSequenceMax(seqs);
+    if (max !== null) {
+        const have = new Set(seqs);
+        for (let n = 1; n <= max; n += 1) {
+            if (!have.has(n))
+                violations.push({ artifact: MIGRATION_FILE, reason: 'sequence_gap', id: `MG-${String(n).padStart(2, '0')}` });
+        }
+    }
+    if (sources.requirementIds === 'unparseable')
+        violations.push({ artifact: REQUIREMENTS_FILE, reason: 'requirements_unparseable' });
+    return { ok: violations.length === 0, rows: ids.size, uncited, violations };
+}
+function checkProjectMigration(cwd, requireCited = false) {
+    const read = readIfPresent(node_path_1.default.join(cwd, MIGRATION_FILE));
+    if (read.kind === 'absent')
+        return null;
+    if (read.kind === 'unreadable')
+        return { ok: false, file: MIGRATION_FILE, rows: 0, uncited: 0, violations: [{ artifact: MIGRATION_FILE, reason: 'artifact_unreadable' }] };
+    const extra = [];
+    const sources = { requirementIds: null, entities: null, systems: null };
+    const req = readIfPresent(node_path_1.default.join(cwd, REQUIREMENTS_FILE));
+    if (req.kind === 'unreadable')
+        extra.push({ artifact: REQUIREMENTS_FILE, reason: 'artifact_unreadable' });
+    if (req.kind === 'ok') {
+        const parsed = rollup.parseRequirementsArtifact(req.content);
+        sources.requirementIds = parsed.ok ? new Set(parsed.rows.map((r) => r.id)) : 'unparseable';
+    }
+    const ent = readIfPresent(node_path_1.default.join(cwd, ENTITIES_FILE));
+    if (ent.kind === 'unreadable')
+        extra.push({ artifact: ENTITIES_FILE, reason: 'artifact_unreadable' });
+    if (ent.kind === 'ok')
+        sources.entities = firstColumnOf(ent.content, 'Entities');
+    const s2 = readIfPresent(node_path_1.default.join(cwd, SESSION_02_FILE));
+    if (s2.kind === 'unreadable')
+        extra.push({ artifact: SESSION_02_FILE, reason: 'artifact_unreadable' });
+    if (s2.kind === 'ok')
+        sources.systems = systemsFrom(s2.content);
+    const result = checkMigration(read.content, sources, requireCited);
+    result.violations.push(...extra);
+    result.ok = result.violations.length === 0;
+    return { file: MIGRATION_FILE, ...result };
+}
+function formatViolation(v) {
+    const where = v.line !== undefined ? `:${v.line}` : '';
+    const what = v.id !== undefined ? ` (${v.id})` : '';
+    return `  - ${v.artifact}${where}: ${v.reason}${what}`;
+}
+// ─── CLI adapter ──────────────────────────────────────────────────────────────
+/**
+ * `pp-tools discovery migration-check [--require-cited]` (dotted
+ * `query discovery.migration-check`). Absent artifact → exit 0,
+ * `present: false`. Structural faults exit via
+ * `DISCOVERY_MIGRATION_CHECK_FAILED`; when every fault is an
+ * `uncited_migration` raised by `--require-cited`, the identity is
+ * `DISCOVERY_MIGRATION_UNCITED`.
+ */
+function cmdDiscoveryMigrationCheck(cwd, args, raw) {
+    const rest = args.slice(2);
+    const requireCited = rest.includes('--require-cited');
+    if (rest.some((a) => a !== '--require-cited')) {
+        error(USAGE, ERROR_REASON.USAGE);
+        return; // unreachable
+    }
+    const result = checkProjectMigration(cwd, requireCited);
+    if (result === null) {
+        output({ ok: true, present: false, file: MIGRATION_FILE }, raw);
+        return;
+    }
+    const payload = { ok: result.ok, present: true, file: result.file, rows: result.rows, uncited: result.uncited };
+    if (!result.ok) {
+        output({ ...payload, violations: result.violations.length }, raw);
+        const onlyUncited = result.violations.every((v) => v.reason === 'uncited_migration');
+        error(`discovery migration-check: ${result.violations.length} violation(s):\n` + result.violations.map(formatViolation).join('\n'), onlyUncited ? ERROR_REASON.DISCOVERY_MIGRATION_UNCITED : ERROR_REASON.DISCOVERY_MIGRATION_CHECK_FAILED);
+        return; // unreachable
+    }
+    output(payload, raw);
+}
+module.exports = {
+    MIGRATION_FILE,
+    MIGRATION_HEADER,
+    MIGRATION_CHECK_FAILED: ERROR_REASON.DISCOVERY_MIGRATION_CHECK_FAILED,
+    MIGRATION_UNCITED: ERROR_REASON.DISCOVERY_MIGRATION_UNCITED,
+    systemsFrom,
+    checkMigration,
+    checkProjectMigration,
+    cmdDiscoveryMigrationCheck,
+};