@pareto4/pp-core 1.19.0 → 1.20.0

package/pp-core/bin/lib/discovery-for-phase.cjs

@@ -0,0 +1,628 @@
+"use strict";
+/**
+ * Discovery extract per build phase (Discovery Sprint improvement plan,
+ * Batch 4 — §5.5 R1 and R3).
+ *
+ * A build phase is keyed by its requirement IDs (`**Requirements**: [K-03,
+ * N-02]` in ROADMAP.md; the `_phases.md` row before the handoff). `for-phase
+ * <N>` collects every row of every canonical discovery artifact that cites one
+ * of those IDs and renders them as ONE markdown extract between
+ * `<!-- discovery:auto -->` markers, which `/pp-discuss-phase` writes into
+ * CONTEXT.md and `/pp-plan-phase` hands the researcher and the planner. No
+ * agent opens a `session-NN.md`; nothing is copied by hand, so nothing drifts.
+ *
+ * What is collected, per artifact present under `.planning/discovery/`:
+ *
+ *   - `_requirements.md` § Requirements — the rows whose ID is in the set;
+ *   - `_stories.md` § Stories — rows whose `Requirements` cites one;
+ *   - `_processes.md` § Steps — step rows whose `Requirements` cites one,
+ *     under their `### MP-nn — <name>` heading, plus the § To-be row of each
+ *     main process touched;
+ *   - `_entities.md` — the entities named as data objects by those steps:
+ *     their § Entities row, attribute table, relationships and lifecycles;
+ *   - `_rules.md` § Rules — rows whose `Requirements` cites one;
+ *   - `_screens.md` § Screens rows citing one and § No screen rows keyed by one;
+ *   - `_roles.md` — the § Permissions rows citing one; the § Roles row and
+ *     the § Screens rows of each role those permissions name, plus § Screens
+ *     rows of the selected screens (Batch 3 grammar,
+ *     `references/discovery-access.md`);
+ *   - `_integrations.md` — the § Interfaces rows citing one or named by a
+ *     selected step's `Integration` cell (`IF-nn`), with their § Contract and
+ *     § Errors rows (`references/discovery-integrations.md`);
+ *   - `_migration.md`, `_deviations.md` — generic: every table carrying a
+ *     `Requirements` column contributes the rows citing one; a table without
+ *     that column is reported as unfilterable, never silently dropped.
+ *
+ * Structure fails loud (`discovery_for_phase_failed`): a present artifact
+ * whose owning section or header is off its template, or a `_requirements.md`
+ * the rollup cannot parse. An absent artifact is skipped. With no
+ * `.planning/discovery/` at all the extract is empty and the exit is 0 — a
+ * project that never ran the sprint sees nothing (the vault's posture).
+ *
+ * R3 — `--conformance-template` renders the "Discovery conformance" block the
+ * verifier fills (one row per extract row, status `honoured | amended
+ * (D-P<nn>-<n>) | missed`); `--verify <VERIFICATION.md>` checks that block
+ * covers every extract row exactly once with a legal status. A `missed` row is
+ * the verifier's finding, not this command's fault.
+ */
+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");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const phases = require("./discovery-phases.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const roadmapParser = require("./roadmap-parser.cjs");
+// ─── Constants ────────────────────────────────────────────────────────────────
+const DISCOVERY_DIR = '.planning/discovery';
+const ROADMAP_FILE = '.planning/ROADMAP.md';
+const ART = Object.freeze({
+    requirements: `${DISCOVERY_DIR}/_requirements.md`,
+    stories: `${DISCOVERY_DIR}/_stories.md`,
+    processes: `${DISCOVERY_DIR}/_processes.md`,
+    entities: `${DISCOVERY_DIR}/_entities.md`,
+    rules: `${DISCOVERY_DIR}/_rules.md`,
+    screens: `${DISCOVERY_DIR}/_screens.md`,
+    roles: `${DISCOVERY_DIR}/_roles.md`,
+    integrations: `${DISCOVERY_DIR}/_integrations.md`,
+    migration: `${DISCOVERY_DIR}/_migration.md`,
+    deviations: `${DISCOVERY_DIR}/_deviations.md`,
+    phases: `${DISCOVERY_DIR}/_phases.md`,
+});
+/** The generic registers: filtered by a `Requirements` column wherever one exists. */
+const GENERIC = Object.freeze([
+    { file: ART.migration, title: 'Migration' },
+    { file: ART.deviations, title: 'Deviations' },
+]);
+const MARKER_OPEN = '<!-- discovery:auto -->';
+const MARKER_CLOSE = '<!-- /discovery:auto -->';
+const CONFORMANCE_OPEN = '<!-- discovery:conformance -->';
+const CONFORMANCE_CLOSE = '<!-- /discovery:conformance -->';
+const CONFORMANCE_HEADING = '### Discovery conformance';
+const CONFORMANCE_HEADER = Object.freeze(['Artifact', 'Row', 'Status', 'Evidence']);
+const STATUS_RE = /^(honoured|missed|amended \(D-P\d{2}-\d+\))$/;
+const DEFAULT_STATUS = 'missed';
+const REQUIREMENTS_HEADER = Object.freeze(['ID', 'Requirement', 'MoSCoW', 'Disposition', 'Provenance', 'Acceptance Criteria']);
+const STORIES_HEADER = Object.freeze(['ID', 'EPIC', 'Requirements', 'Story', 'Acceptance criteria', 'Source step']);
+const TO_BE_HEADER = Object.freeze(['ID', 'Main process', 'Replaces', 'Trigger', 'End state', 'Primary actor', 'EPICs']);
+const STEPS_HEADER = Object.freeze(['#', 'Step', 'Actor', 'UI', 'Data objects', 'Integration', 'Exception', 'Requirements']);
+const ENTITIES_HEADER = Object.freeze(['Entity', 'Identifier', 'Status lifecycle', 'Classification', 'Retention', 'Owner module', 'Source']);
+const ATTRIBUTES_HEADER = Object.freeze(['Attribute', 'Type', 'Required', 'Bounds', 'Notes']);
+const RELATIONSHIPS_HEADER = Object.freeze(['From', 'Cardinality', 'To', 'Name']);
+const LIFECYCLES_HEADER = Object.freeze(['Entity', 'State', 'Transition', 'Allowed by']);
+const RULES_HEADER = Object.freeze(['ID', 'Rule', 'Applies to', 'Checked at', 'Requirements', 'Source']);
+const SCREENS_HEADER = Object.freeze(['ID', 'Role', 'Purpose', 'Surface', 'Requirements']);
+const NO_SCREEN_HEADER = Object.freeze(['Requirement', 'Reason']);
+const NO_SCREEN_SECTION = 'No screen (still MVP)';
+const ROLES_HEADER = Object.freeze(['Role', 'Description', 'Scope', 'Recovery path', 'Source']);
+const PERMISSIONS_HEADER = Object.freeze(['Role', 'Entity', 'Operation', 'Condition', 'Requirements']);
+const ROLE_SCREENS_HEADER = Object.freeze(['Role', 'Screen']);
+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 PHASE_ARG_RE = /^\d+(\.\d+)?$/;
+const REQUIREMENT_ID_RE = /^[A-Z][A-Z0-9]*-\d+$/;
+const REQUIREMENTS_LINE_RE = /^\*\*Requirements\*\*:?\s*(.*)$/im;
+const MP_HEADING_RE = /^(MP-\d{2})\s+—\s+\S/;
+const DATA_OBJECT_RE = /^([A-Z][A-Za-z0-9]*) \[[CRUD](?:\/[CRUD])*\]$/;
+const INTEGRATION_ID_RE = /^IF-\d{2}$/;
+const REQUIREMENT_COLUMN_NAMES = Object.freeze(['requirements', 'requirement ids', 'requirement']);
+const USAGE = 'Usage: pp-tools discovery for-phase <N> [--markdown | --conformance-template | --verify <VERIFICATION.md>]';
+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 cites(cell, ids) {
+    return splitList(cell ?? '').some((t) => ids.has(t));
+}
+function escapeCell(cell) {
+    return cell.replace(/\|/g, '\\|');
+}
+function renderTable(header, rows) {
+    const out = [`| ${header.join(' | ')} |`, `|${header.map(() => '---').join('|')}|`];
+    for (const r of rows)
+        out.push(`| ${header.map((_, i) => escapeCell(r.cells[i] ?? '')).join(' | ')} |`);
+    return out;
+}
+/** Sections of a file at heading level 2. */
+function sectionsOf(content) {
+    return table.splitSections(content.split(/\r?\n/), 2);
+}
+/** The first table under a `## <heading>`, with its header checked against `expected`. */
+function tableUnder(content, heading, expected, artifact, violations) {
+    const section = sectionsOf(content).find((s) => s.heading === heading);
+    if (!section) {
+        violations.push({ artifact, reason: 'missing_section', id: heading });
+        return null;
+    }
+    const tables = table.parseTables(section.body);
+    if (tables.length === 0) {
+        violations.push({ artifact, reason: 'missing_section', line: section.line, id: heading });
+        return null;
+    }
+    if (!sameHeader(tables[0].header, expected)) {
+        violations.push({ artifact, reason: 'bad_table_shape', line: tables[0].line, id: heading });
+        return null;
+    }
+    return tables[0];
+}
+// ─── Requirement-ID resolution ────────────────────────────────────────────────
+function parseRequirementsLine(section) {
+    const m = REQUIREMENTS_LINE_RE.exec(section);
+    if (!m)
+        return [];
+    return m[1]
+        .replace(/[[\]]/g, '')
+        .split(/[,\s]+/)
+        .map((t) => t.trim())
+        .filter((t) => REQUIREMENT_ID_RE.test(t));
+}
+function resolveRequirementIds(cwd, phase, violations) {
+    if (node_fs_1.default.existsSync(node_path_1.default.join(cwd, ROADMAP_FILE))) {
+        const found = roadmapParser.getRoadmapPhaseInternal(cwd, phase);
+        if (found && found.found) {
+            const ids = parseRequirementsLine(found.section);
+            if (ids.length > 0)
+                return { ids, source: 'ROADMAP.md' };
+        }
+    }
+    const plan = readIfPresent(node_path_1.default.join(cwd, ART.phases));
+    if (plan.kind === 'unreadable')
+        violations.push({ artifact: ART.phases, reason: 'artifact_unreadable' });
+    if (plan.kind === 'ok' && /^\d+$/.test(phase)) {
+        const parsed = phases.parsePhasePlan(plan.content);
+        for (const v of parsed.violations)
+            if (v.reason === 'missing_section' || v.reason === 'bad_table_shape')
+                violations.push(v);
+        const row = parsed.rows.find((r) => r.phase === Number(phase));
+        if (row && row.requirementIds.length > 0)
+            return { ids: row.requirementIds.filter((t) => REQUIREMENT_ID_RE.test(t)), source: '_phases.md' };
+    }
+    return { ids: [], source: null };
+}
+// ─── Collection ───────────────────────────────────────────────────────────────
+function collectExtract(cwd, phase) {
+    const violations = [];
+    const present = Object.values(ART).some((rel) => node_fs_1.default.existsSync(node_path_1.default.join(cwd, rel)));
+    if (!present && !node_fs_1.default.existsSync(node_path_1.default.join(cwd, DISCOVERY_DIR)))
+        return null;
+    const { ids: idList, source } = resolveRequirementIds(cwd, phase, violations);
+    const ids = new Set(idList);
+    const tables = [];
+    const unfilterable = [];
+    const touched = new Set();
+    const push = (t) => {
+        if (t.rows.length === 0)
+            return;
+        tables.push(t);
+        touched.add(t.artifact);
+    };
+    // _requirements.md
+    const req = readIfPresent(node_path_1.default.join(cwd, ART.requirements));
+    if (req.kind === 'unreadable')
+        violations.push({ artifact: ART.requirements, reason: 'artifact_unreadable' });
+    if (req.kind === 'ok') {
+        const parsed = rollup.parseRequirementsArtifact(req.content);
+        if (!parsed.ok)
+            violations.push({ artifact: ART.requirements, reason: 'requirements_unparseable' });
+        const t = tableUnder(req.content, 'Requirements', REQUIREMENTS_HEADER, ART.requirements, violations);
+        if (t) {
+            push({
+                artifact: ART.requirements, title: 'Requirements', subtitle: null, header: [...REQUIREMENTS_HEADER], keyed: true, keyPrefix: '',
+                rows: t.rows.filter((r) => ids.has((r.cells[0] ?? '').trim())),
+            });
+        }
+    }
+    // _stories.md
+    const sto = readIfPresent(node_path_1.default.join(cwd, ART.stories));
+    if (sto.kind === 'unreadable')
+        violations.push({ artifact: ART.stories, reason: 'artifact_unreadable' });
+    if (sto.kind === 'ok') {
+        const t = tableUnder(sto.content, 'Stories', STORIES_HEADER, ART.stories, violations);
+        if (t) {
+            push({
+                artifact: ART.stories, title: 'User stories', subtitle: null, header: [...STORIES_HEADER], keyed: true, keyPrefix: '',
+                rows: t.rows.filter((r) => cites(r.cells[2], ids)),
+            });
+        }
+    }
+    // _processes.md — steps, then the to-be rows of the main processes touched
+    const entityNames = new Set();
+    const integrationIds = new Set();
+    const proc = readIfPresent(node_path_1.default.join(cwd, ART.processes));
+    if (proc.kind === 'unreadable')
+        violations.push({ artifact: ART.processes, reason: 'artifact_unreadable' });
+    if (proc.kind === 'ok') {
+        const mpsTouched = new Set();
+        const steps = sectionsOf(proc.content).find((s) => s.heading === 'Steps');
+        if (!steps) {
+            violations.push({ artifact: ART.processes, reason: 'missing_section', id: 'Steps' });
+        }
+        else {
+            const perProcess = table.splitSections(steps.body.map((l) => l.text), 3);
+            // splitSections renumbers from 1 relative to the body; map back to file lines.
+            const base = steps.body.length > 0 ? steps.body[0].n - 1 : 0;
+            for (const sec of perProcess) {
+                const m = MP_HEADING_RE.exec(sec.heading);
+                const tbl = table.parseTables(sec.body)[0];
+                if (!m || !tbl || !sameHeader(tbl.header, STEPS_HEADER)) {
+                    violations.push({ artifact: ART.processes, reason: 'bad_table_shape', line: sec.line + base, id: sec.heading.slice(0, 40) });
+                    continue;
+                }
+                const rows = tbl.rows
+                    .filter((r) => cites(r.cells[7], ids))
+                    .map((r) => ({ cells: r.cells, line: r.line + base }));
+                if (rows.length === 0)
+                    continue;
+                mpsTouched.add(m[1]);
+                for (const r of rows) {
+                    for (const obj of splitList(r.cells[4] ?? '')) {
+                        const dm = DATA_OBJECT_RE.exec(obj);
+                        if (dm)
+                            entityNames.add(dm[1]);
+                    }
+                    for (const tok of splitList(r.cells[5] ?? ''))
+                        if (INTEGRATION_ID_RE.test(tok))
+                            integrationIds.add(tok);
+                }
+                push({ artifact: ART.processes, title: 'Process steps', subtitle: sec.heading, header: [...STEPS_HEADER], keyed: true, keyPrefix: `${m[1]} #`, rows });
+            }
+        }
+        const toBe = tableUnder(proc.content, 'To-be', TO_BE_HEADER, ART.processes, violations);
+        if (toBe && mpsTouched.size > 0) {
+            const rows = toBe.rows.filter((r) => mpsTouched.has((r.cells[0] ?? '').trim()));
+            // Main-process rows precede their steps in the extract.
+            const idx = tables.findIndex((t) => t.title === 'Process steps');
+            const mp = { artifact: ART.processes, title: 'Process steps', subtitle: 'Main processes', header: [...TO_BE_HEADER], keyed: false, keyPrefix: '', rows };
+            if (rows.length > 0)
+                tables.splice(idx === -1 ? tables.length : idx, 0, mp);
+        }
+    }
+    // _entities.md — the entities the selected steps touch
+    const ent = readIfPresent(node_path_1.default.join(cwd, ART.entities));
+    if (ent.kind === 'unreadable')
+        violations.push({ artifact: ART.entities, reason: 'artifact_unreadable' });
+    if (ent.kind === 'ok') {
+        const entities = tableUnder(ent.content, 'Entities', ENTITIES_HEADER, ART.entities, violations);
+        if (entities) {
+            push({
+                artifact: ART.entities, title: 'Entities', subtitle: null, header: [...ENTITIES_HEADER], keyed: true, keyPrefix: '',
+                rows: entities.rows.filter((r) => entityNames.has((r.cells[0] ?? '').trim())),
+            });
+            const attrs = sectionsOf(ent.content).find((s) => s.heading === 'Attributes');
+            if (attrs) {
+                const base = attrs.body.length > 0 ? attrs.body[0].n - 1 : 0;
+                for (const sec of table.splitSections(attrs.body.map((l) => l.text), 3)) {
+                    if (!entityNames.has(sec.heading.trim()))
+                        continue;
+                    const tbl = table.parseTables(sec.body)[0];
+                    if (!tbl || !sameHeader(tbl.header, ATTRIBUTES_HEADER)) {
+                        violations.push({ artifact: ART.entities, reason: 'bad_table_shape', line: sec.line + base, id: sec.heading.slice(0, 40) });
+                        continue;
+                    }
+                    push({
+                        artifact: ART.entities, title: 'Entities', subtitle: `${sec.heading.trim()} (attributes)`, header: [...ATTRIBUTES_HEADER], keyed: false, keyPrefix: '',
+                        rows: tbl.rows.map((r) => ({ cells: r.cells, line: r.line + base })),
+                    });
+                }
+            }
+            const rel = sectionsOf(ent.content).find((s) => s.heading === 'Relationships');
+            if (rel) {
+                const tbl = table.parseTables(rel.body)[0];
+                if (tbl && sameHeader(tbl.header, RELATIONSHIPS_HEADER)) {
+                    push({
+                        artifact: ART.entities, title: 'Entities', subtitle: 'Relationships', header: [...RELATIONSHIPS_HEADER], keyed: false, keyPrefix: '',
+                        rows: tbl.rows.filter((r) => entityNames.has((r.cells[0] ?? '').trim()) || entityNames.has((r.cells[2] ?? '').trim())),
+                    });
+                }
+            }
+            const life = sectionsOf(ent.content).find((s) => s.heading === 'Lifecycles');
+            if (life) {
+                const tbl = table.parseTables(life.body)[0];
+                if (tbl && sameHeader(tbl.header, LIFECYCLES_HEADER)) {
+                    push({
+                        artifact: ART.entities, title: 'Entities', subtitle: 'Lifecycles', header: [...LIFECYCLES_HEADER], keyed: false, keyPrefix: '',
+                        rows: tbl.rows.filter((r) => entityNames.has((r.cells[0] ?? '').trim())),
+                    });
+                }
+            }
+        }
+    }
+    // _rules.md
+    const rul = readIfPresent(node_path_1.default.join(cwd, ART.rules));
+    if (rul.kind === 'unreadable')
+        violations.push({ artifact: ART.rules, reason: 'artifact_unreadable' });
+    if (rul.kind === 'ok') {
+        const t = tableUnder(rul.content, 'Rules', RULES_HEADER, ART.rules, violations);
+        if (t) {
+            push({
+                artifact: ART.rules, title: 'Business rules', subtitle: null, header: [...RULES_HEADER], keyed: true, keyPrefix: '',
+                rows: t.rows.filter((r) => cites(r.cells[4], ids)),
+            });
+        }
+    }
+    // _screens.md
+    const screenIds = new Set();
+    const scr = readIfPresent(node_path_1.default.join(cwd, ART.screens));
+    if (scr.kind === 'unreadable')
+        violations.push({ artifact: ART.screens, reason: 'artifact_unreadable' });
+    if (scr.kind === 'ok') {
+        const t = tableUnder(scr.content, 'Screens', SCREENS_HEADER, ART.screens, violations);
+        if (t) {
+            const rows = t.rows.filter((r) => cites(r.cells[4], ids));
+            for (const r of rows)
+                screenIds.add((r.cells[0] ?? '').trim());
+            push({ artifact: ART.screens, title: 'Screens', subtitle: null, header: [...SCREENS_HEADER], keyed: true, keyPrefix: '', rows });
+        }
+        const bucket = tableUnder(scr.content, NO_SCREEN_SECTION, NO_SCREEN_HEADER, ART.screens, violations);
+        if (bucket) {
+            push({
+                artifact: ART.screens, title: 'Screens', subtitle: NO_SCREEN_SECTION, header: [...NO_SCREEN_HEADER], keyed: true, keyPrefix: 'no-screen ',
+                rows: bucket.rows.filter((r) => ids.has((r.cells[0] ?? '').trim())),
+            });
+        }
+    }
+    // _roles.md — permissions by requirement; the roles they name, and those roles' screens
+    const rol = readIfPresent(node_path_1.default.join(cwd, ART.roles));
+    if (rol.kind === 'unreadable')
+        violations.push({ artifact: ART.roles, reason: 'artifact_unreadable' });
+    if (rol.kind === 'ok') {
+        const roles = tableUnder(rol.content, 'Roles', ROLES_HEADER, ART.roles, violations);
+        const permissions = tableUnder(rol.content, 'Permissions', PERMISSIONS_HEADER, ART.roles, violations);
+        const roleScreens = tableUnder(rol.content, 'Screens', ROLE_SCREENS_HEADER, ART.roles, violations);
+        if (roles && permissions && roleScreens) {
+            const permRows = permissions.rows.filter((r) => cites(r.cells[4], ids));
+            const roleNames = new Set(permRows.map((r) => (r.cells[0] ?? '').trim()));
+            push({ artifact: ART.roles, title: 'Roles', subtitle: 'Roles', header: [...ROLES_HEADER], keyed: true, keyPrefix: '', rows: roles.rows.filter((r) => roleNames.has((r.cells[0] ?? '').trim())) });
+            push({ artifact: ART.roles, title: 'Roles', subtitle: 'Permissions', header: [...PERMISSIONS_HEADER], keyed: true, keyPrefix: '', rows: permRows });
+            push({
+                artifact: ART.roles, title: 'Roles', subtitle: 'Screens', header: [...ROLE_SCREENS_HEADER], keyed: false, keyPrefix: '',
+                rows: roleScreens.rows.filter((r) => roleNames.has((r.cells[0] ?? '').trim()) || screenIds.has((r.cells[1] ?? '').trim())),
+            });
+        }
+    }
+    // _integrations.md — interfaces by requirement or step reference; their contract and error rows
+    const integ = readIfPresent(node_path_1.default.join(cwd, ART.integrations));
+    if (integ.kind === 'unreadable')
+        violations.push({ artifact: ART.integrations, reason: 'artifact_unreadable' });
+    if (integ.kind === 'ok') {
+        const interfaces = tableUnder(integ.content, 'Interfaces', INTERFACES_HEADER, ART.integrations, violations);
+        const contract = tableUnder(integ.content, 'Contract', CONTRACT_HEADER, ART.integrations, violations);
+        const errors = tableUnder(integ.content, 'Errors', ERRORS_HEADER, ART.integrations, violations);
+        if (interfaces && contract && errors) {
+            const rows = interfaces.rows.filter((r) => cites(r.cells[8], ids) || integrationIds.has((r.cells[0] ?? '').trim()));
+            const selected = new Set(rows.map((r) => (r.cells[0] ?? '').trim()));
+            push({ artifact: ART.integrations, title: 'Integrations', subtitle: 'Interfaces', header: [...INTERFACES_HEADER], keyed: true, keyPrefix: '', rows });
+            push({ artifact: ART.integrations, title: 'Integrations', subtitle: 'Contract', header: [...CONTRACT_HEADER], keyed: false, keyPrefix: '', rows: contract.rows.filter((r) => selected.has((r.cells[0] ?? '').trim())) });
+            push({ artifact: ART.integrations, title: 'Integrations', subtitle: 'Errors', header: [...ERRORS_HEADER], keyed: false, keyPrefix: '', rows: errors.rows.filter((r) => selected.has((r.cells[0] ?? '').trim())) });
+        }
+    }
+    // Generic registers: filtered by a Requirements column.
+    for (const g of GENERIC) {
+        const read = readIfPresent(node_path_1.default.join(cwd, g.file));
+        if (read.kind === 'unreadable')
+            violations.push({ artifact: g.file, reason: 'artifact_unreadable' });
+        if (read.kind !== 'ok')
+            continue;
+        for (const sec of sectionsOf(read.content)) {
+            const tbl = table.parseTables(sec.body)[0];
+            if (!tbl)
+                continue;
+            const col = tbl.header.findIndex((h) => REQUIREMENT_COLUMN_NAMES.includes(h.trim().toLowerCase()));
+            if (col === -1) {
+                unfilterable.push(`${g.file} § ${sec.heading}`);
+                continue;
+            }
+            const rows = tbl.rows.filter((r) => cites(r.cells[col], ids));
+            push({ artifact: g.file, title: g.title, subtitle: sec.heading, header: tbl.header, keyed: true, keyPrefix: '', rows });
+        }
+    }
+    return { phase, source, requirementIds: idList, tables, unfilterable, artifacts: [...touched], violations };
+}
+// ─── Rendering ────────────────────────────────────────────────────────────────
+function keysOf(extract) {
+    const keys = [];
+    const seen = new Set();
+    for (const t of extract.tables) {
+        if (!t.keyed)
+            continue;
+        for (const r of t.rows) {
+            const row = `${t.keyPrefix}${(r.cells[0] ?? '').trim()}`;
+            const k = `${t.artifact} ${row}`;
+            if (seen.has(k))
+                continue;
+            seen.add(k);
+            keys.push({ artifact: node_path_1.default.basename(t.artifact), row });
+        }
+    }
+    return keys;
+}
+function renderExtract(extract) {
+    const out = [MARKER_OPEN, `## Discovery extract — Phase ${extract.phase}`, ''];
+    const src = extract.source === 'ROADMAP.md' ? ROADMAP_FILE : extract.source === '_phases.md' ? ART.phases : null;
+    out.push(extract.requirementIds.length === 0
+        ? `Requirement IDs: none resolved (no \`**Requirements**:\` line for this phase in ${ROADMAP_FILE} and no row in ${ART.phases}).`
+        : `Requirement IDs: ${extract.requirementIds.join(', ')} (source: ${src})`);
+    out.push(`Rendered by \`pp-tools discovery for-phase ${extract.phase}\`. Do not edit here: amend the artifact row (\`→ amended by D-P<nn>-<n>\`) and re-run.`, '');
+    if (extract.tables.length === 0) {
+        out.push('No artifact row cites these IDs.', '');
+    }
+    let currentTitle = null;
+    for (const t of extract.tables) {
+        if (t.title !== currentTitle) {
+            out.push(`### ${t.title} — \`${t.artifact}\``, '');
+            currentTitle = t.title;
+        }
+        if (t.subtitle)
+            out.push(`#### ${t.subtitle}`, '');
+        out.push(...renderTable(t.header, t.rows), '');
+    }
+    for (const u of extract.unfilterable)
+        out.push(`Not filterable by requirement: \`${u}\` has no requirement column — read it whole.`);
+    if (extract.unfilterable.length > 0)
+        out.push('');
+    out.push(`Artifacts read: ${extract.artifacts.length === 0 ? 'none' : extract.artifacts.join(', ')}`);
+    out.push(MARKER_CLOSE);
+    return out.join('\n') + '\n';
+}
+function renderConformanceTemplate(extract) {
+    const keys = keysOf(extract);
+    const rows = keys.map((k) => ({ cells: [`\`${k.artifact}\``, k.row, DEFAULT_STATUS, ''] }));
+    const out = [CONFORMANCE_HEADING, '', CONFORMANCE_OPEN, ...renderTable(CONFORMANCE_HEADER, rows), CONFORMANCE_CLOSE];
+    if (keys.length === 0)
+        out.splice(3, 0, '_No discovery row cites this phase._');
+    return out.join('\n') + '\n';
+}
+// ─── Conformance verification ─────────────────────────────────────────────────
+function verifyConformance(text, extract) {
+    const violations = [];
+    const lines = text.split(/\r?\n/);
+    const opens = lines.map((l, i) => (l.trim() === CONFORMANCE_OPEN ? i : -1)).filter((i) => i !== -1);
+    const closes = lines.map((l, i) => (l.trim() === CONFORMANCE_CLOSE ? i : -1)).filter((i) => i !== -1);
+    if (opens.length !== 1 || closes.length !== 1 || closes[0] < opens[0]) {
+        return { ok: false, rows: 0, honoured: 0, amended: 0, missed: 0, violations: [{ artifact: 'VERIFICATION.md', reason: 'conformance_markers' }] };
+    }
+    const body = lines.slice(opens[0] + 1, closes[0]).map((text, i) => ({ n: opens[0] + 2 + i, text }));
+    const tbl = table.parseTables(body)[0];
+    if (!tbl || !sameHeader(tbl.header, CONFORMANCE_HEADER)) {
+        return { ok: false, rows: 0, honoured: 0, amended: 0, missed: 0, violations: [{ artifact: 'VERIFICATION.md', reason: 'bad_table_shape', line: opens[0] + 1 }] };
+    }
+    const expected = new Set(keysOf(extract).map((k) => `${k.artifact} ${k.row}`));
+    const seen = new Set();
+    let honoured = 0;
+    let amended = 0;
+    let missed = 0;
+    for (const r of tbl.rows) {
+        const artifact = (r.cells[0] ?? '').trim().replace(/^`|`$/g, '');
+        const key = `${artifact} ${(r.cells[1] ?? '').trim()}`;
+        const status = (r.cells[2] ?? '').trim();
+        if (!expected.has(key))
+            violations.push({ artifact: 'VERIFICATION.md', reason: 'unknown_row', line: r.line, id: key.slice(0, 60) });
+        else if (seen.has(key))
+            violations.push({ artifact: 'VERIFICATION.md', reason: 'duplicate_row', line: r.line, id: key.slice(0, 60) });
+        seen.add(key);
+        if (!STATUS_RE.test(status)) {
+            violations.push({ artifact: 'VERIFICATION.md', reason: 'bad_status', line: r.line, id: key.slice(0, 60) });
+        }
+        else if (status === 'honoured')
+            honoured += 1;
+        else if (status === 'missed')
+            missed += 1;
+        else
+            amended += 1;
+    }
+    for (const k of expected)
+        if (!seen.has(k))
+            violations.push({ artifact: 'VERIFICATION.md', reason: 'missing_row', id: k.slice(0, 60) });
+    return { ok: violations.length === 0, rows: tbl.rows.length, honoured, amended, missed, violations };
+}
+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 for-phase <N> [--markdown | --conformance-template | --verify <file>]`
+ * (dotted `query discovery.for-phase`). No discovery package → exit 0,
+ * `present: false`, empty markdown.
+ */
+function cmdDiscoveryForPhase(cwd, args, raw) {
+    const rest = args.slice(2).filter((a) => a !== '--raw');
+    const phase = rest[0];
+    const flags = rest.slice(1);
+    const markdown = flags.includes('--markdown');
+    const template = flags.includes('--conformance-template');
+    const vIdx = flags.indexOf('--verify');
+    const verifyFile = vIdx === -1 ? undefined : flags[vIdx + 1];
+    const known = flags.filter((f, i) => f !== '--markdown' && f !== '--conformance-template' && f !== '--verify' && (vIdx === -1 || i !== vIdx + 1));
+    if (!phase || !PHASE_ARG_RE.test(phase) || known.length > 0 || [markdown, template, vIdx !== -1].filter(Boolean).length > 1 || (vIdx !== -1 && !verifyFile)) {
+        error(USAGE, ERROR_REASON.USAGE);
+        return; // unreachable
+    }
+    const extract = collectExtract(cwd, phase);
+    if (extract === null) {
+        const payload = { ok: true, present: false, phase, requirementIds: [], artifacts: [], markdown: '' };
+        output(payload, markdown || template, '');
+        return;
+    }
+    if (extract.violations.length > 0) {
+        output({ ok: false, present: true, phase, violations: extract.violations.length }, raw);
+        error(`discovery for-phase: ${extract.violations.length} violation(s):\n` + extract.violations.map(formatViolation).join('\n'), ERROR_REASON.DISCOVERY_FOR_PHASE_FAILED);
+        return; // unreachable
+    }
+    if (verifyFile !== undefined) {
+        let text = '';
+        try {
+            text = node_fs_1.default.readFileSync(node_path_1.default.resolve(cwd, verifyFile), 'utf-8');
+        }
+        catch {
+            output({ ok: false, present: true, phase, file: verifyFile }, raw);
+            error(`discovery for-phase: ${verifyFile} could not be read`, ERROR_REASON.DISCOVERY_FOR_PHASE_FAILED);
+            return; // unreachable
+        }
+        const result = verifyConformance(text, extract);
+        const payload = { ok: result.ok, present: true, phase, file: verifyFile, rows: result.rows, honoured: result.honoured, amended: result.amended, missed: result.missed };
+        if (!result.ok) {
+            output({ ...payload, violations: result.violations.length }, raw);
+            error(`discovery for-phase: conformance block has ${result.violations.length} fault(s):\n` + result.violations.map(formatViolation).join('\n'), ERROR_REASON.DISCOVERY_FOR_PHASE_FAILED);
+            return; // unreachable
+        }
+        output(payload, raw);
+        return;
+    }
+    const md = renderExtract(extract);
+    const keys = keysOf(extract);
+    const payload = {
+        ok: true,
+        present: true,
+        phase,
+        source: extract.source,
+        requirementIds: extract.requirementIds,
+        artifacts: extract.artifacts,
+        rows: keys,
+        unfilterable: extract.unfilterable,
+        markdown: md,
+    };
+    if (template) {
+        output(payload, true, renderConformanceTemplate(extract));
+        return;
+    }
+    output(payload, markdown || raw, md);
+}
+module.exports = {
+    MARKER_OPEN,
+    MARKER_CLOSE,
+    CONFORMANCE_OPEN,
+    CONFORMANCE_CLOSE,
+    CONFORMANCE_HEADING,
+    CONFORMANCE_HEADER,
+    STATUS_RE,
+    FOR_PHASE_FAILED: ERROR_REASON.DISCOVERY_FOR_PHASE_FAILED,
+    parseRequirementsLine,
+    collectExtract,
+    renderExtract,
+    renderConformanceTemplate,
+    verifyConformance,
+    cmdDiscoveryForPhase,
+};