@pareto4/pp-core 1.19.0 → 1.21.0

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

@@ -0,0 +1,233 @@
+"use strict";
+/**
+ * Discovery phase-plan check (Discovery Sprint improvement plan, Batch 4).
+ *
+ * `.planning/discovery/_phases.md` is the Phase Plan Session 11 decides —
+ * one row per build phase with its goal, EPICs, requirement IDs, success
+ * criteria and dependencies — and the literal source of `ROADMAP.md` at the
+ * handoff (review F-5: before Batch 4 the roadmap was derived by prose
+ * instruction from an EPIC build order that carried no requirement IDs). This
+ * module checks the structure:
+ *
+ *   - the `## Phases` table exists with the template's columns;
+ *   - `Phase` is a positive integer, unique, contiguous from 1;
+ *   - `Goal` and `Success criteria` are non-empty;
+ *   - `EPICs` is `—` or a comma list of `E-nn`;
+ *   - `Requirement IDs` is a comma list (or `—` for a phase that realises no
+ *     requirement), each ID existing in `_requirements.md` when it is on file
+ *     and parseable, none `Dropped`;
+ *   - `Depends on` is `—` or a comma list of earlier phase numbers;
+ *   - every MVP-disposition requirement appears in exactly one phase.
+ *
+ * Posture (D-43/D-53): reports at Sessions 11 and 13; hard-blocks at
+ * `/pp-discovery-to-build`. 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 PHASES_FILE = `${DISCOVERY_DIR}/_phases.md`;
+const REQUIREMENTS_FILE = `${DISCOVERY_DIR}/_requirements.md`;
+const PHASES_SECTION = 'Phases';
+const PHASES_HEADER = Object.freeze(['Phase', 'Goal', 'EPICs', 'Requirement IDs', 'Success criteria', 'Depends on']);
+const PHASE_RE = /^[1-9]\d{0,2}$/;
+const EPIC_RE = /^E-\d{2}$/;
+const REQUIREMENT_ID_RE = /^[A-Z][A-Z0-9]*-\d+$/;
+const PENDING = '—';
+/** Separator between success criteria inside one cell: space, middle dot U+00B7, space (the Provenance grammar's). */
+const CRITERIA_SEPARATOR = ' · ';
+const USAGE = 'Usage: pp-tools discovery phases-check';
+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 `## Phases` rows of a `_phases.md` text, or `null` with the structural
+ * fault when the section or table is off the template. Shared with
+ * `for-phase`, which reads the plan as the pre-handoff source of a phase's
+ * requirement IDs.
+ */
+function parsePhasePlan(content) {
+    const violations = [];
+    const section = table.splitSections(content.split(/\r?\n/), 2).find((s) => s.heading === PHASES_SECTION);
+    if (!section)
+        return { rows: [], violations: [{ artifact: PHASES_FILE, reason: 'missing_section', id: PHASES_SECTION }] };
+    const tables = table.parseTables(section.body);
+    if (tables.length === 0)
+        return { rows: [], violations: [{ artifact: PHASES_FILE, reason: 'missing_section', line: section.line, id: PHASES_SECTION }] };
+    if (!sameHeader(tables[0].header, PHASES_HEADER)) {
+        return { rows: [], violations: [{ artifact: PHASES_FILE, reason: 'bad_table_shape', line: tables[0].line, id: PHASES_SECTION }] };
+    }
+    const rows = [];
+    for (const row of tables[0].rows) {
+        const [phase, goal, epics, requirementIds, successCriteria, dependsOn] = row.cells.map((c) => c.trim());
+        if (!PHASE_RE.test(phase ?? '')) {
+            violations.push({ artifact: PHASES_FILE, reason: 'bad_phase_number', line: row.line });
+            continue;
+        }
+        const epicList = (epics ?? '') === PENDING ? [] : splitList(epics ?? '');
+        const depList = (dependsOn ?? '') === PENDING ? [] : splitList(dependsOn ?? '');
+        rows.push({
+            phase: Number(phase),
+            goal: goal ?? '',
+            epics: epicList,
+            requirementIds: (requirementIds ?? '') === PENDING ? [] : splitList(requirementIds ?? ''),
+            requirementsPending: (requirementIds ?? '') === PENDING,
+            successCriteria: (successCriteria ?? '').split(CRITERIA_SEPARATOR).map((s) => s.trim()).filter(Boolean),
+            dependsOn: depList.map((d) => (PHASE_RE.test(d) ? Number(d) : NaN)),
+            line: row.line,
+        });
+    }
+    return { rows, violations };
+}
+// ─── Check ────────────────────────────────────────────────────────────────────
+function checkPhases(content, requirements) {
+    const parsed = parsePhasePlan(content);
+    const violations = [...parsed.violations];
+    if (parsed.rows.length === 0 && violations.length > 0 && violations[0].reason !== 'bad_phase_number') {
+        return { ok: false, phases: 0, violations };
+    }
+    const known = requirements instanceof Array ? new Map(requirements.map((r) => [r.id, r])) : null;
+    const seen = new Set();
+    const planned = new Map();
+    for (const row of parsed.rows) {
+        if (seen.has(row.phase))
+            violations.push({ artifact: PHASES_FILE, reason: 'duplicate_phase', line: row.line, id: String(row.phase) });
+        seen.add(row.phase);
+        if (row.goal === '')
+            violations.push({ artifact: PHASES_FILE, reason: 'empty_cell', line: row.line, id: 'Goal' });
+        if (row.successCriteria.length === 0)
+            violations.push({ artifact: PHASES_FILE, reason: 'empty_cell', line: row.line, id: 'Success criteria' });
+        for (const e of row.epics)
+            if (!EPIC_RE.test(e))
+                violations.push({ artifact: PHASES_FILE, reason: 'bad_epic', line: row.line, id: e.slice(0, 40) });
+        if (row.requirementIds.length === 0 && !row.requirementsPending)
+            violations.push({ artifact: PHASES_FILE, reason: 'no_requirement', line: row.line });
+        for (const r of row.requirementIds) {
+            if (!REQUIREMENT_ID_RE.test(r)) {
+                violations.push({ artifact: PHASES_FILE, reason: 'unknown_requirement_id', line: row.line, id: r.slice(0, 40) });
+                continue;
+            }
+            if (known !== null) {
+                const fact = known.get(r);
+                if (!fact) {
+                    violations.push({ artifact: PHASES_FILE, reason: 'unknown_requirement_id', line: row.line, id: r });
+                    continue;
+                }
+                if (fact.disposition === rollup.DISPOSITIONS.DROPPED)
+                    violations.push({ artifact: PHASES_FILE, reason: 'dropped_requirement_planned', line: row.line, id: r });
+            }
+            const list = planned.get(r) ?? [];
+            list.push(row.phase);
+            planned.set(r, list);
+        }
+        for (const d of row.dependsOn) {
+            if (Number.isNaN(d) || d >= row.phase)
+                violations.push({ artifact: PHASES_FILE, reason: 'bad_dependency', line: row.line, id: String(row.phase) });
+        }
+    }
+    const max = table.boundedSequenceMax([...seen]);
+    if (max !== null) {
+        for (let n = 1; n <= max; n += 1) {
+            if (!seen.has(n))
+                violations.push({ artifact: PHASES_FILE, reason: 'sequence_gap', id: String(n) });
+        }
+    }
+    for (const row of parsed.rows) {
+        for (const d of row.dependsOn) {
+            if (!Number.isNaN(d) && d < row.phase && !seen.has(d))
+                violations.push({ artifact: PHASES_FILE, reason: 'bad_dependency', line: row.line, id: String(d) });
+        }
+    }
+    for (const [id, phases] of planned) {
+        if (phases.length > 1)
+            violations.push({ artifact: PHASES_FILE, reason: 'requirement_in_multiple_phases', id: `${id} (${phases.join(', ')})` });
+    }
+    if (requirements instanceof Array) {
+        for (const r of requirements) {
+            if (r.disposition === rollup.DISPOSITIONS.MVP && !planned.has(r.id))
+                violations.push({ artifact: REQUIREMENTS_FILE, reason: 'mvp_requirement_unplanned', id: r.id });
+        }
+    }
+    else if (requirements === 'unparseable') {
+        violations.push({ artifact: REQUIREMENTS_FILE, reason: 'requirements_unparseable' });
+    }
+    return { ok: violations.length === 0, phases: seen.size, violations };
+}
+function checkProjectPhases(cwd) {
+    const read = readIfPresent(node_path_1.default.join(cwd, PHASES_FILE));
+    if (read.kind === 'absent')
+        return null;
+    if (read.kind === 'unreadable')
+        return { ok: false, file: PHASES_FILE, phases: 0, violations: [{ artifact: PHASES_FILE, reason: 'artifact_unreadable' }] };
+    const extra = [];
+    let requirements = 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);
+        requirements = parsed.ok ? parsed.rows.map((r) => ({ id: r.id, disposition: r.disposition })) : 'unparseable';
+    }
+    const result = checkPhases(read.content, requirements);
+    result.violations.push(...extra);
+    result.ok = result.violations.length === 0;
+    return { file: PHASES_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 phases-check` (dotted `query discovery.phases-check`). Absent artifact → exit 0, `present: false`. */
+function cmdDiscoveryPhasesCheck(cwd, args, raw) {
+    if (args.length > 2) {
+        error(USAGE, ERROR_REASON.USAGE);
+        return; // unreachable
+    }
+    const result = checkProjectPhases(cwd);
+    if (result === null) {
+        output({ ok: true, present: false, file: PHASES_FILE }, raw);
+        return;
+    }
+    const payload = { ok: result.ok, present: true, file: result.file, phases: result.phases };
+    if (!result.ok) {
+        output({ ...payload, violations: result.violations.length }, raw);
+        error(`discovery phases-check: ${result.violations.length} violation(s):\n` + result.violations.map(formatViolation).join('\n'), ERROR_REASON.DISCOVERY_PHASES_CHECK_FAILED);
+        return; // unreachable
+    }
+    output(payload, raw);
+}
+module.exports = {
+    PHASES_FILE,
+    PHASES_HEADER,
+    CRITERIA_SEPARATOR,
+    PHASES_CHECK_FAILED: ERROR_REASON.DISCOVERY_PHASES_CHECK_FAILED,
+    parsePhasePlan,
+    checkPhases,
+    checkProjectPhases,
+    cmdDiscoveryPhasesCheck,
+};

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

@@ -0,0 +1,355 @@
+"use strict";
+/**
+ * Discovery process-model check (Discovery Sprint improvement plan, Batch 2).
+ *
+ * `.planning/discovery/_processes.md` holds the as-is processes (`PRC-`,
+ * Session 2), the to-be main processes (`MP-`, Session 3) with the as-is
+ * processes each one replaces, one swimlane flowchart per main process (a
+ * `subgraph` per actor) and one step matrix per main process whose rows are
+ * what Session 3 Step 5D mints requirements from — now with an `Exception`
+ * column, so every error path has a home. This module checks the structure:
+ *
+ *   - the four sections exist and the tables have the template's columns;
+ *   - `PRC-` and `MP-` IDs are well-formed, unique and contiguous;
+ *   - every `Replaces` cell is `new` or names as-is processes that exist;
+ *   - every main process has a flow (a `flowchart` with at least one
+ *     `subgraph`) and a step table, and every flow or step heading names a
+ *     main process that exists;
+ *   - every actor is a Session 2 persona or `System`, when `session-02.md`
+ *     is on file; every data object is `Name [C/R/U/D]` or `—`;
+ *   - every cited requirement exists in `_requirements.md`, when it is on
+ *     file and parseable;
+ *   - with `--require-cited`: every step cites at least one requirement —
+ *     the state Step 5D leaves behind, required at the handoff.
+ *
+ * Posture (D-43/D-53): reports at Sessions 8 and 13; hard-blocks at
+ * `/pp-discovery-to-build` with `--require-cited`. Absent artifact → exit 0.
+ *
+ * Content-free contract: output names artifacts, line numbers, validated IDs,
+ * section names, column names and reason codes — never cell prose.
+ */
+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 PROCESSES_FILE = `${DISCOVERY_DIR}/_processes.md`;
+const REQUIREMENTS_FILE = `${DISCOVERY_DIR}/_requirements.md`;
+const SESSION_02_FILE = `${DISCOVERY_DIR}/session-02.md`;
+const SECTIONS = Object.freeze({ asIs: 'As-is', toBe: 'To-be', flows: 'Flows', steps: 'Steps' });
+const AS_IS_HEADER = Object.freeze(['ID', 'Process', 'Owner', 'Trigger', 'End state', 'Frequency', 'Avg duration', 'Criticality']);
+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 PRC_RE = /^PRC-(\d{2})$/;
+const MP_RE = /^MP-(\d{2})$/;
+/** `### MP-01 — <name>` under Flows and Steps. */
+const MP_HEADING_RE = /^(MP-\d{2})\s+—\s+\S/;
+const PENDING = '—';
+const NEW = 'new';
+const SYSTEM_ACTOR = 'System';
+const DATA_OBJECT_RE = /^([A-Z][A-Za-z0-9]*) \[([CRUD](?:\/[CRUD])*)\]$/;
+const REQUIREMENT_ID_RE = /^[A-Z][A-Z0-9]*-\d+$/;
+const PERSONAS_LABEL = 'User Personas';
+const USAGE = 'Usage: pp-tools discovery process-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 sectionTable(sections, heading, expected, violations) {
+    const section = sections.find((s) => s.heading === heading);
+    if (!section) {
+        violations.push({ artifact: PROCESSES_FILE, reason: 'missing_section', id: heading });
+        return null;
+    }
+    const tables = table.parseTables(section.body);
+    if (tables.length === 0) {
+        violations.push({ artifact: PROCESSES_FILE, reason: 'missing_section', line: section.line, id: heading });
+        return null;
+    }
+    if (!sameHeader(tables[0].header, expected)) {
+        violations.push({ artifact: PROCESSES_FILE, reason: 'bad_table_shape', line: tables[0].line, id: heading });
+        return null;
+    }
+    return tables[0];
+}
+/** Validate an ID column: shape, uniqueness, contiguity from 01. Returns the accepted IDs. */
+function validateIds(rows, re, violations) {
+    const ids = new Map();
+    const seqs = [];
+    for (const row of rows) {
+        const id = (row.cells[0] ?? '').trim();
+        const m = re.exec(id);
+        if (!m) {
+            violations.push({ artifact: PROCESSES_FILE, reason: 'bad_id', line: row.line });
+            continue;
+        }
+        if (ids.has(id)) {
+            violations.push({ artifact: PROCESSES_FILE, reason: 'duplicate_id', line: row.line, id });
+            continue;
+        }
+        ids.set(id, row.line);
+        seqs.push(Number(m[1]));
+    }
+    const max = table.boundedSequenceMax(seqs);
+    if (max !== null) {
+        const prefix = re.source.startsWith('^PRC') ? 'PRC' : 'MP';
+        const have = new Set(seqs);
+        for (let n = 1; n <= max; n += 1) {
+            if (!have.has(n))
+                violations.push({ artifact: PROCESSES_FILE, reason: 'sequence_gap', id: `${prefix}-${String(n).padStart(2, '0')}` });
+        }
+    }
+    return ids;
+}
+// ─── Check ────────────────────────────────────────────────────────────────────
+function checkProcesses(content, sources, requireCited = false) {
+    const violations = [];
+    const lines = content.split(/\r?\n/);
+    const sections = table.splitSections(lines, 2);
+    // 1 ─ As-is
+    let asIs = new Map();
+    const asIsTable = sectionTable(sections, SECTIONS.asIs, AS_IS_HEADER, violations);
+    if (asIsTable) {
+        asIs = validateIds(asIsTable.rows, PRC_RE, violations);
+        for (const row of asIsTable.rows) {
+            if ((row.cells[1] ?? '').trim() === '')
+                violations.push({ artifact: PROCESSES_FILE, reason: 'empty_cell', line: row.line, id: 'Process' });
+        }
+    }
+    // 2 ─ To-be
+    let toBe = new Map();
+    const toBeTable = sectionTable(sections, SECTIONS.toBe, TO_BE_HEADER, violations);
+    if (toBeTable) {
+        toBe = validateIds(toBeTable.rows, MP_RE, violations);
+        for (const row of toBeTable.rows) {
+            const [, name, replaces, , , actor] = row.cells.map((c) => c.trim());
+            if ((name ?? '') === '')
+                violations.push({ artifact: PROCESSES_FILE, reason: 'empty_cell', line: row.line, id: 'Main process' });
+            if ((replaces ?? '') === '') {
+                violations.push({ artifact: PROCESSES_FILE, reason: 'bad_replaces', line: row.line });
+            }
+            else if (replaces !== NEW) {
+                for (const token of replaces.split(',').map((t) => t.trim())) {
+                    if (!PRC_RE.test(token))
+                        violations.push({ artifact: PROCESSES_FILE, reason: 'bad_replaces', line: row.line });
+                    else if (!asIs.has(token))
+                        violations.push({ artifact: PROCESSES_FILE, reason: 'unknown_process', line: row.line, id: token });
+                }
+            }
+            checkActor(actor ?? '', row.line, sources, violations);
+        }
+    }
+    // 3 ─ Flows: one swimlane per main process
+    let flows = 0;
+    const flowsSection = sections.find((s) => s.heading === SECTIONS.flows);
+    const withFlow = new Set();
+    if (!flowsSection) {
+        violations.push({ artifact: PROCESSES_FILE, reason: 'missing_section', id: SECTIONS.flows });
+    }
+    else {
+        for (const s of table.splitSections(flowsSection.body.map((l) => l.text), 3)) {
+            const line = flowsSection.body[s.line - 1]?.n ?? flowsSection.line;
+            const m = MP_HEADING_RE.exec(s.heading);
+            if (!m || !toBe.has(m[1])) {
+                violations.push({ artifact: PROCESSES_FILE, reason: 'unknown_process', line, id: (m ? m[1] : s.heading).slice(0, 40) });
+                continue;
+            }
+            flows += 1;
+            withFlow.add(m[1]);
+            const text = s.body.map((l) => l.text).join('\n');
+            const hasFlowchart = /```mermaid\s*\n\s*flowchart\b/.test(text);
+            const hasSubgraph = /^\s*subgraph\b/m.test(text);
+            if (!hasFlowchart || !hasSubgraph)
+                violations.push({ artifact: PROCESSES_FILE, reason: 'flow_not_swimlane', line, id: m[1] });
+        }
+    }
+    // 4 ─ Steps: one matrix per main process
+    let steps = 0;
+    let uncited = 0;
+    const withSteps = new Set();
+    const stepsSection = sections.find((s) => s.heading === SECTIONS.steps);
+    if (!stepsSection) {
+        violations.push({ artifact: PROCESSES_FILE, reason: 'missing_section', id: SECTIONS.steps });
+    }
+    else {
+        for (const s of table.splitSections(stepsSection.body.map((l) => l.text), 3)) {
+            const line = stepsSection.body[s.line - 1]?.n ?? stepsSection.line;
+            const m = MP_HEADING_RE.exec(s.heading);
+            if (!m || !toBe.has(m[1])) {
+                violations.push({ artifact: PROCESSES_FILE, reason: 'unknown_process', line, id: (m ? m[1] : s.heading).slice(0, 40) });
+                continue;
+            }
+            const body = s.body.map((l, i) => ({ n: stepsSection.body[s.line + i]?.n ?? line, text: l.text }));
+            const tables = table.parseTables(body);
+            if (tables.length === 0 || !sameHeader(tables[0].header, STEPS_HEADER)) {
+                violations.push({ artifact: PROCESSES_FILE, reason: 'bad_table_shape', line, id: `${SECTIONS.steps} · ${m[1]}` });
+                continue;
+            }
+            withSteps.add(m[1]);
+            for (const row of tables[0].rows) {
+                steps += 1;
+                const [num, step, actor, , objects, , , requirements] = row.cells.map((c) => c.trim());
+                if ((num ?? '') === '' || (step ?? '') === '')
+                    violations.push({ artifact: PROCESSES_FILE, reason: 'empty_cell', line: row.line, id: 'Step' });
+                checkActor(actor ?? '', row.line, sources, violations);
+                if ((objects ?? '') !== '' && objects !== PENDING) {
+                    for (const token of objects.split(',').map((t) => t.trim()).filter(Boolean)) {
+                        if (!DATA_OBJECT_RE.test(token))
+                            violations.push({ artifact: PROCESSES_FILE, reason: 'bad_data_object', line: row.line });
+                    }
+                }
+                if ((requirements ?? '') === '' || requirements === PENDING) {
+                    uncited += 1;
+                    if (requireCited)
+                        violations.push({ artifact: PROCESSES_FILE, reason: 'uncited_step', line: row.line });
+                }
+                else {
+                    for (const token of requirements.split(',').map((t) => t.trim()).filter(Boolean)) {
+                        if (!REQUIREMENT_ID_RE.test(token))
+                            violations.push({ artifact: PROCESSES_FILE, reason: 'unknown_requirement_id', line: row.line, id: token.slice(0, 40) });
+                        else if (sources.requirementIds instanceof Set && !sources.requirementIds.has(token)) {
+                            violations.push({ artifact: PROCESSES_FILE, reason: 'unknown_requirement_id', line: row.line, id: token });
+                        }
+                    }
+                }
+            }
+        }
+    }
+    for (const [id, line] of toBe) {
+        if (flowsSection && !withFlow.has(id))
+            violations.push({ artifact: PROCESSES_FILE, reason: 'flow_missing', line, id });
+        if (stepsSection && !withSteps.has(id))
+            violations.push({ artifact: PROCESSES_FILE, reason: 'steps_missing', line, id });
+    }
+    if (sources.requirementIds === 'unparseable')
+        violations.push({ artifact: REQUIREMENTS_FILE, reason: 'requirements_unparseable' });
+    return { ok: violations.length === 0, as_is: asIs.size, to_be: toBe.size, flows, steps, uncited, violations };
+}
+/** An actor cell: one persona or `System`, or a comma list of them when a step genuinely has two actors. */
+function checkActor(actor, line, sources, violations) {
+    const tokens = actor.split(',').map((t) => t.trim()).filter(Boolean);
+    if (tokens.length === 0) {
+        violations.push({ artifact: PROCESSES_FILE, reason: 'bad_actor', line });
+        return;
+    }
+    if (sources.personas === null)
+        return;
+    for (const t of tokens) {
+        if (t !== SYSTEM_ACTOR && !sources.personas.has(t))
+            violations.push({ artifact: PROCESSES_FILE, reason: 'bad_actor', line });
+    }
+}
+/** Persona names: the first column of Session 2's User Personas table. */
+function personasFrom(content) {
+    const lines = content.split(/\r?\n/);
+    const norm = (s) => s.replace(/^#+\s*/, '').replace(/\*\*/g, '').trim();
+    const at = lines.findIndex((l) => norm(l) === PERSONAS_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;
+    return new Set(tables[0].rows.map((r) => (r.cells[0] ?? '').trim()).filter((c) => c !== ''));
+}
+function requirementIdsFrom(content) {
+    const parsed = rollup.parseRequirementsArtifact(content);
+    if (!parsed.ok)
+        return 'unparseable';
+    return new Set(parsed.rows.map((r) => r.id));
+}
+function checkProjectProcesses(cwd, requireCited = false) {
+    const read = readIfPresent(node_path_1.default.join(cwd, PROCESSES_FILE));
+    if (read.kind === 'absent')
+        return null;
+    const empty = { as_is: 0, to_be: 0, flows: 0, steps: 0, uncited: 0 };
+    if (read.kind === 'unreadable')
+        return { ok: false, file: PROCESSES_FILE, ...empty, violations: [{ artifact: PROCESSES_FILE, reason: 'artifact_unreadable' }] };
+    const extra = [];
+    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' });
+    const req = readIfPresent(node_path_1.default.join(cwd, REQUIREMENTS_FILE));
+    if (req.kind === 'unreadable')
+        extra.push({ artifact: REQUIREMENTS_FILE, reason: 'artifact_unreadable' });
+    const sources = {
+        personas: s2.kind === 'ok' ? personasFrom(s2.content) : null,
+        requirementIds: req.kind === 'ok' ? requirementIdsFrom(req.content) : null,
+    };
+    const result = checkProcesses(read.content, sources, requireCited);
+    result.violations.push(...extra);
+    result.ok = result.violations.length === 0;
+    return { file: PROCESSES_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 ──────────────────────────────────────────────────────────────
+/**
+ * CLI adapter for `pp-tools discovery process-check [--require-cited]`
+ * (dotted `query discovery.process-check`). Absent artifact → exit 0 with
+ * `present: false`. Structural faults exit via
+ * `DISCOVERY_PROCESS_CHECK_FAILED`; when every fault is an `uncited_step`
+ * raised by `--require-cited`, the identity is
+ * `DISCOVERY_PROCESS_STEPS_UNCITED`.
+ */
+function cmdDiscoveryProcessCheck(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 = checkProjectProcesses(cwd, requireCited);
+    if (result === null) {
+        output({ ok: true, present: false, file: PROCESSES_FILE }, raw);
+        return;
+    }
+    const payload = { ok: result.ok, present: true, file: result.file, as_is: result.as_is, to_be: result.to_be, flows: result.flows, steps: result.steps, uncited: result.uncited };
+    if (!result.ok) {
+        output({ ...payload, violations: result.violations.length }, raw);
+        const onlyUncited = result.violations.every((v) => v.reason === 'uncited_step');
+        error(`discovery process-check: ${result.violations.length} violation(s):\n` + result.violations.map(formatViolation).join('\n'), onlyUncited ? ERROR_REASON.DISCOVERY_PROCESS_STEPS_UNCITED : ERROR_REASON.DISCOVERY_PROCESS_CHECK_FAILED);
+        return; // unreachable
+    }
+    output(payload, raw);
+}
+module.exports = {
+    PROCESSES_FILE,
+    AS_IS_HEADER,
+    TO_BE_HEADER,
+    STEPS_HEADER,
+    MP_HEADING_RE,
+    DATA_OBJECT_RE,
+    PROCESS_CHECK_FAILED: ERROR_REASON.DISCOVERY_PROCESS_CHECK_FAILED,
+    PROCESS_STEPS_UNCITED: ERROR_REASON.DISCOVERY_PROCESS_STEPS_UNCITED,
+    checkProcesses,
+    personasFrom,
+    checkProjectProcesses,
+    cmdDiscoveryProcessCheck,
+};

package/pp-core/bin/lib/discovery-research-track.cjs

@@ -6,8 +6,9 @@
  * Read-only structural validator over the three per-engagement research
  * registers — `.planning/discovery/_research.md` (the backlog),
  * `_risks.md` (the data-gathering register) and `_sparring.md` (the position
- * tracker) — plus every `⚠️ CONDITIONAL —` marker in the session files and
- * `_context.md` that cites them.
+ * tracker) — plus every `⚠️ CONDITIONAL —` marker in the session files that
+ * cites them (and in a legacy `_context.md`, when an engagement that predates
+ * its retirement still carries one).
  *
  * Fail-loud (D-42), one bullet per fault class:
  *   - bad_id / duplicate_id — a register row whose ID is not `^(RS|DG|SP)-\d{2}$`,
@@ -156,10 +157,10 @@ const DG_ID_RE = /^DG-\d{2}$/;
 const SP_ID_RE = /^SP-\d{2}$/;
 const SEPARATOR_ROW_RE = /^\s*\|[\s:|-]+\|\s*$/;
 /** D-35 evidence form 1: a decision ID. Form 2 is an existing repo-relative path. */
-const EVIDENCE_DECISION_RE = /^D-\d{2}-\d+$/;
+const EVIDENCE_DECISION_RE = /^D-(?:\d{2}|P\d{2})-\d+$/;
 const CLOSED_EVIDENCE_RE = /^Closed \((.+)\)$/;
 /** D-37 Source vocabulary. */
-const SOURCE_RE = /^(DG-\d{2}|SP-\d{2}|S\d+|D-\d{2}-\d+)$/;
+const SOURCE_RE = /^(DG-\d{2}|SP-\d{2}|S\d+|D-(?:\d{2}|P\d{2})-\d+)$/;
 /** D-40 Feeds: comma-separated session refs. */
 const FEEDS_RE = /^S\d+$/;
 /** A requirement ID as `_requirements.md` mints them (rollup's ROW_ID_RE shape). */

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

@@ -13,10 +13,11 @@
  * must exist in the same table. Grammar single-source: same reference file.
  *
  * Phase 3 (D-44), extended by Phase 4 (D-50) and issue #12: a Prefix Registry
- * row may not claim one of the seven reserved prefixes (`D-` `A-` `SP-` `DG-`
- * `RS-` `SCR-` `PRC-`) — they all match the requirement-ID regex, so
- * registering one collides with the decision / action / sparring /
- * data-gathering / research / screen / process ID families. Reserved set
+ * row may not claim one of the twelve reserved prefixes (`D-` `A-` `SP-` `DG-`
+ * `RS-` `SCR-` `PRC-` `MP-` `BR-` `IF-` `MG-` `DEV-`) — they all match the
+ * requirement-ID regex, so registering one collides with the decision / action /
+ * sparring / data-gathering / research / screen / process / interface /
+ * migration / deviation ID families. Reserved set
  * single-source: same reference file.
  *
  * Fail-loud contract (D-08): any unparseable row, malformed/duplicate ID,
@@ -49,9 +50,9 @@ const MOSCOW = Object.freeze({ MUST: 'Must', SHOULD: 'Should', COULD: 'Could', W
 // requirements table.
 // Issue #12 added `PRC-`: Session 2 numbers its Process Inventory `PRC-<nn>`,
 // which a later session cites beside requirement IDs.
-const RESERVED_PREFIXES = new Set(['D-', 'A-', 'SP-', 'DG-', 'RS-', 'SCR-', 'PRC-']);
+const RESERVED_PREFIXES = new Set(['D-', 'A-', 'SP-', 'DG-', 'RS-', 'SCR-', 'PRC-', 'MP-', 'BR-', 'IF-', 'MG-', 'DEV-']);
 const ROW_ID_RE = /^([A-Z][A-Z0-9]*-)(\d+)$/;
-const DROPPED_RE = /^Dropped \((D-\d{2}-\d+)\)$/;
+const DROPPED_RE = /^Dropped \((D-(?:\d{2}|P\d{2})-\d+)\)$/;
 const SEPARATOR_ROW_RE = /^\s*\|[\s:|-]+\|\s*$/;
 const ROLLUP_OPEN = '<!-- rollup:auto -->';
 const ROLLUP_CLOSE = '<!-- /rollup:auto -->';
@@ -64,7 +65,7 @@ const STRIKE_RE = /^~~.+~~$/;
 const PROVENANCE_SEP = ' · ';
 const ACCESSION_CITE_RE = /^\[(\d{2})( §[^\]]{1,80})?\]$/;
 const SESSION_REF_RE = /^S\d+$/;
-const PROVENANCE_DECISION_RE = /^D-\d{2}-\d+$/;
+const PROVENANCE_DECISION_RE = /^D-(?:\d{2}|P\d{2})-\d+$/;
 const RELATION_RE = /^(refines|absorbed into) ([A-Z][A-Z0-9]*-\d+)$/;
 const MOSCOW_SET = new Set(Object.values(MOSCOW));
 const REGISTRY_HEADING = '## Prefix Registry';