@pareto4/pp-core 1.21.1 → 1.22.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pp-core",
   "displayName": "PP Core",
-  "version": "1.21.1",
+  "version": "1.22.0",
   "description": "PP Core is a meta-prompting, context engineering, and spec-driven development system for AI coding agents.",
   "author": {
     "name": "pareto4",

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "pp-core",
-  "version": "1.21.1",
+  "version": "1.22.0",
   "description": "PP Core — a meta-prompting, context engineering, and spec-driven development system for AI coding agents. Loads pp-core's operating context into every Gemini CLI session.",
   "contextFileName": "GEMINI.md"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pareto4/pp-core",
-  "version": "1.21.1",
+  "version": "1.22.0",
   "description": "Pareto pp-core — The Pareto Project's AI-assisted engineering framework: meta-prompting, context engineering, and spec-driven development for AI coding agents.",
   "bin": {
     "pp-core": "bin/install.js",
@@ -71,7 +71,7 @@
   },
   "overrides": {
     "qs": ">=6.16.0",
-    "@hono/node-server": ">=2.0.5",
+    "@hono/node-server": ">=2.1.3",
     "body-parser": "^2.4.0",
     "fast-uri": "^3.1.9",
     "zod": "^4.6.6"

package/pp-core/bin/lib/discovery-flow-page.cjs

@@ -0,0 +1,191 @@
+"use strict";
+/**
+ * Discovery flow page (Session 3 Step 5C — iterate a swimlane with the room).
+ *
+ * Session 3 refines one main process at a time: the agent drafts the
+ * swimlane into `_processes.md` § Flows, the room reacts, the agent edits the
+ * draft in place, and only an accepted diagram becomes a step matrix. A
+ * terminal cannot draw Mermaid, so this command renders one main process —
+ * its swimlane, its § Sub-processes rows and its step matrix, read from the
+ * register and nothing else — as a self-contained HTML page the agent
+ * publishes as a private artifact (which renders `<pre class="mermaid">`
+ * natively) and republishes after every round. The register stays the only
+ * source: the page is regenerated, never edited.
+ *
+ * The page carries no script and no external resource; every cell is
+ * HTML-escaped, the Mermaid source included (Mermaid reads the element's
+ * text). Structure fails loud (`discovery_flow_page_failed`): no
+ * `_processes.md`, an `MP-nn` that is not in § To-be, or a main process
+ * without a flow under § Flows.
+ */
+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");
+// ─── Constants ────────────────────────────────────────────────────────────────
+const DISCOVERY_DIR = '.planning/discovery';
+const PROCESSES_FILE = `${DISCOVERY_DIR}/_processes.md`;
+const PAGES_DIR = `${DISCOVERY_DIR}/_flows`;
+const MP_RE = /^MP-\d{2}$/;
+const MP_HEADING_RE = /^(MP-\d{2})\s+—\s+(.+)$/;
+const SUB_PROCESS_RE = /^(MP-\d{2})\.\d+$/;
+const MERMAID_RE = /```mermaid\s*\n([\s\S]*?)\n\s*```/;
+const TO_BE_LABELS = Object.freeze(['ID', 'Main process', 'Replaces', 'Trigger', 'End state', 'Primary actor', 'EPICs']);
+const USAGE = 'Usage: pp-tools discovery flow-page <MP-nn> [--out <file.html>]';
+// ─── Read ─────────────────────────────────────────────────────────────────────
+function readProcessView(content, mp) {
+    const sections = table.splitSections(content.split(/\r?\n/), 2);
+    const toBe = sections.find((s) => s.heading === 'To-be');
+    const toBeRow = toBe ? table.parseTables(toBe.body)[0]?.rows.find((r) => (r.cells[0] ?? '').trim() === mp) : undefined;
+    if (!toBeRow)
+        return { ok: false, reason: 'unknown_process' };
+    const sub = (heading) => {
+        const s = sections.find((x) => x.heading === heading);
+        return s ? table.splitSections(s.body.map((l) => l.text), 3) : [];
+    };
+    const flow = sub('Flows').find((s) => MP_HEADING_RE.exec(s.heading)?.[1] === mp);
+    const mermaid = flow ? MERMAID_RE.exec(flow.body.map((l) => l.text).join('\n'))?.[1] : undefined;
+    if (!mermaid)
+        return { ok: false, reason: 'flow_missing' };
+    const stepsSec = sub('Steps').find((s) => MP_HEADING_RE.exec(s.heading)?.[1] === mp);
+    const stepsTable = stepsSec ? table.parseTables(stepsSec.body)[0] : undefined;
+    const subSec = sections.find((s) => s.heading === 'Sub-processes');
+    const subRows = subSec ? (table.parseTables(subSec.body)[0]?.rows ?? []) : [];
+    return {
+        ok: true,
+        view: {
+            id: mp,
+            name: (toBeRow.cells[1] ?? '').trim(),
+            toBe: toBeRow.cells.map((c) => c.trim()),
+            mermaid,
+            subProcesses: subRows.filter((r) => SUB_PROCESS_RE.exec((r.cells[0] ?? '').trim())?.[1] === mp),
+            stepsHeader: stepsTable ? stepsTable.header.map((c) => c.trim()) : [],
+            steps: stepsTable ? stepsTable.rows : [],
+        },
+    };
+}
+// ─── Render ───────────────────────────────────────────────────────────────────
+function esc(s) {
+    return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+function htmlTable(header, rows) {
+    const head = `<tr>${header.map((h) => `<th>${esc(h)}</th>`).join('')}</tr>`;
+    const body = rows.map((r) => `<tr>${header.map((_, i) => `<td>${esc((r.cells[i] ?? '').trim())}</td>`).join('')}</tr>`).join('\n');
+    return `<div class="scroll"><table>\n<thead>${head}</thead>\n<tbody>\n${body}\n</tbody>\n</table></div>`;
+}
+function renderPage(v) {
+    const facts = TO_BE_LABELS.slice(2)
+        .map((label, i) => `<div><dt>${esc(label)}</dt><dd>${esc(v.toBe[i + 2] ?? '')}</dd></div>`)
+        .join('');
+    const subs = v.subProcesses.length > 0
+        ? htmlTable(['ID', 'Sub-process', 'Steps'], v.subProcesses)
+        : '<p class="empty">No sub-processes yet.</p>';
+    const steps = v.steps.length > 0
+        ? htmlTable(v.stepsHeader, v.steps)
+        : '<p class="empty">No step matrix yet — it follows once the room accepts the diagram.</p>';
+    return `<title>${esc(`${v.id} ${v.name}`)}</title>
+<meta name="claude:viewport-fit-sides" content="cover">
+<style>
+:root { --bg: #f7f8fa; --surface: #ffffff; --fg: #14181f; --muted: #5b6472; --line: #dde1e8; --accent: #2251ff; }
+@media (prefers-color-scheme: dark) { :root:not([data-theme="light"]) { --bg: #0f1218; --surface: #171b23; --fg: #e8ebf0; --muted: #9aa3b2; --line: #2a303b; --accent: #7d97ff; color-scheme: dark; } }
+:root[data-theme="dark"] { --bg: #0f1218; --surface: #171b23; --fg: #e8ebf0; --muted: #9aa3b2; --line: #2a303b; --accent: #7d97ff; color-scheme: dark; }
+body { background: var(--bg); color: var(--fg); font: 15px/1.5 system-ui, -apple-system, "Segoe UI", sans-serif; padding-left: max(16px, env(safe-area-inset-left, 0px)); padding-right: max(16px, env(safe-area-inset-right, 0px)); padding-block: 24px 48px; }
+main { max-width: 1200px; margin: 0 auto; display: grid; gap: 24px; }
+header p { margin: 0; color: var(--muted); font-size: 13px; letter-spacing: .04em; text-transform: uppercase; }
+h1 { margin: 4px 0 0; font-size: 26px; text-wrap: balance; }
+h2 { margin: 0 0 8px; font-size: 16px; }
+dl { display: grid; grid-template-columns: repeat(auto-fit, minmax(180px, 1fr)); gap: 8px 24px; margin: 12px 0 0; }
+dt { color: var(--muted); font-size: 12px; text-transform: uppercase; letter-spacing: .04em; }
+dd { margin: 0; }
+section { background: var(--surface); border: 1px solid var(--line); border-radius: 10px; padding: 16px; min-width: 0; }
+.scroll { overflow-x: auto; }
+pre.mermaid { margin: 0; overflow-x: auto; background: transparent; }
+table { border-collapse: collapse; width: 100%; font-size: 14px; }
+th, td { text-align: left; vertical-align: top; padding: 6px 10px; border-bottom: 1px solid var(--line); }
+th { color: var(--muted); font-weight: 600; white-space: nowrap; }
+td:first-child { font-variant-numeric: tabular-nums; white-space: nowrap; color: var(--accent); }
+.empty { color: var(--muted); margin: 0; }
+footer { color: var(--muted); font-size: 12px; }
+</style>
+<main>
+<header>
+<p>Discovery · Session 3 · process refinement</p>
+<h1>${esc(v.id)} — ${esc(v.name)}</h1>
+<dl>${facts}</dl>
+</header>
+<section aria-label="Swimlane">
+<h2>Swimlane</h2>
+<pre class="mermaid">
+${esc(v.mermaid)}
+</pre>
+</section>
+<section aria-label="Sub-processes">
+<h2>Sub-processes</h2>
+${subs}
+</section>
+<section aria-label="Steps">
+<h2>Steps</h2>
+${steps}
+</section>
+<footer>Generated from <code>${esc(PROCESSES_FILE)}</code> by <code>pp-tools discovery flow-page ${esc(v.id)}</code>. Change the register, not this page.</footer>
+</main>
+`;
+}
+// ─── CLI adapter ──────────────────────────────────────────────────────────────
+/**
+ * `pp-tools discovery flow-page <MP-nn> [--out <file.html>]` (dotted
+ * `query discovery.flow-page`). Writes the page (default
+ * `.planning/discovery/_flows/<MP-nn>.html`) and prints `{ ok, process, file,
+ * steps, sub_processes }`.
+ */
+function cmdDiscoveryFlowPage(cwd, args, raw) {
+    const rest = args.slice(2);
+    const mp = rest[0];
+    const outAt = rest.indexOf('--out');
+    const extra = rest.filter((a, i) => i !== 0 && a !== '--out' && i !== outAt + 1);
+    if (!mp || !MP_RE.test(mp) || extra.length > 0 || (outAt !== -1 && !rest[outAt + 1])) {
+        error(USAGE, ERROR_REASON.USAGE);
+        return; // unreachable
+    }
+    const out = outAt !== -1 ? rest[outAt + 1] : `${PAGES_DIR}/${mp}.html`;
+    if (!out.endsWith('.html')) {
+        error(USAGE, ERROR_REASON.USAGE);
+        return; // unreachable
+    }
+    const abs = node_path_1.default.join(cwd, PROCESSES_FILE);
+    const fail = (reason) => error(`discovery flow-page: ${PROCESSES_FILE}: ${reason} (${mp})`, ERROR_REASON.DISCOVERY_FLOW_PAGE_FAILED);
+    if (!node_fs_1.default.existsSync(abs)) {
+        fail('processes_missing');
+        return; // unreachable
+    }
+    let content;
+    try {
+        content = node_fs_1.default.readFileSync(abs, 'utf-8');
+    }
+    catch {
+        fail('artifact_unreadable');
+        return; // unreachable
+    }
+    const result = readProcessView(content, mp);
+    if (!result.ok) {
+        fail(result.reason);
+        return; // unreachable
+    }
+    const outAbs = node_path_1.default.resolve(cwd, out);
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(outAbs), { recursive: true });
+    node_fs_1.default.writeFileSync(outAbs, renderPage(result.view));
+    output({ ok: true, process: mp, file: out, steps: result.view.steps.length, sub_processes: result.view.subProcesses.length }, raw);
+}
+module.exports = {
+    PAGES_DIR,
+    FLOW_PAGE_FAILED: ERROR_REASON.DISCOVERY_FLOW_PAGE_FAILED,
+    readProcessView,
+    renderPage,
+    cmdDiscoveryFlowPage,
+};

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

@@ -29,6 +29,9 @@
  *   - `_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`);
+ *   - `_tests.md` — the § Process risk rows with `End-to-end` `yes` of the
+ *     main processes touched, the § Focus areas rows citing one, and the
+ *     § Acceptance rows of the selected stories (`references/discovery-tests.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.
@@ -75,6 +78,7 @@ const ART = Object.freeze({
     integrations: `${DISCOVERY_DIR}/_integrations.md`,
     migration: `${DISCOVERY_DIR}/_migration.md`,
     deviations: `${DISCOVERY_DIR}/_deviations.md`,
+    tests: `${DISCOVERY_DIR}/_tests.md`,
     phases: `${DISCOVERY_DIR}/_phases.md`,
 });
 /** The generic registers: filtered by a `Requirements` column wherever one exists. */
@@ -108,6 +112,9 @@ 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 RISK_HEADER = Object.freeze(['Process', 'Impact', 'Likelihood', 'Risk', 'End-to-end', 'Roles', 'Test data', 'Rationale']);
+const FOCUS_HEADER = Object.freeze(['Subject', 'Complexity', 'Extra testing', 'Requirements']);
+const ACCEPTANCE_HEADER = Object.freeze(['Story', 'Testable', 'Role', 'Test data']);
 const PHASE_ARG_RE = /^\d+(\.\d+)?$/;
 const REQUIREMENT_ID_RE = /^[A-Z][A-Z0-9]*-\d+$/;
 const REQUIREMENTS_LINE_RE = /^\*\*Requirements\*\*:?\s*(.*)$/im;
@@ -234,26 +241,27 @@ function collectExtract(cwd, phase) {
         }
     }
     // _stories.md
+    const storyIds = new Set();
     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)),
-            });
+            const rows = t.rows.filter((r) => cites(r.cells[2], ids));
+            for (const r of rows)
+                storyIds.add((r.cells[0] ?? '').trim());
+            push({ artifact: ART.stories, title: 'User stories', subtitle: null, header: [...STORIES_HEADER], keyed: true, keyPrefix: '', rows });
         }
     }
     // _processes.md — steps, then the to-be rows of the main processes touched
     const entityNames = new Set();
     const integrationIds = new Set();
+    const mpsTouched = 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' });
@@ -417,6 +425,26 @@ function collectExtract(cwd, phase) {
             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())) });
         }
     }
+    // _tests.md — end-to-end processes touched, focus areas by requirement, acceptance of the selected stories
+    const tst = readIfPresent(node_path_1.default.join(cwd, ART.tests));
+    if (tst.kind === 'unreadable')
+        violations.push({ artifact: ART.tests, reason: 'artifact_unreadable' });
+    if (tst.kind === 'ok') {
+        const risk = tableUnder(tst.content, 'Process risk', RISK_HEADER, ART.tests, violations);
+        const focus = tableUnder(tst.content, 'Focus areas', FOCUS_HEADER, ART.tests, violations);
+        const acceptance = tableUnder(tst.content, 'Acceptance', ACCEPTANCE_HEADER, ART.tests, violations);
+        if (risk && focus && acceptance) {
+            push({
+                artifact: ART.tests, title: 'Tests', subtitle: 'End-to-end', header: [...RISK_HEADER], keyed: true, keyPrefix: 'e2e ',
+                rows: risk.rows.filter((r) => mpsTouched.has((r.cells[0] ?? '').trim()) && (r.cells[4] ?? '').trim() === 'yes'),
+            });
+            push({ artifact: ART.tests, title: 'Tests', subtitle: 'Focus areas', header: [...FOCUS_HEADER], keyed: true, keyPrefix: 'focus ', rows: focus.rows.filter((r) => cites(r.cells[3], ids)) });
+            push({
+                artifact: ART.tests, title: 'Tests', subtitle: 'Acceptance', header: [...ACCEPTANCE_HEADER], keyed: false, keyPrefix: '',
+                rows: acceptance.rows.filter((r) => storyIds.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));

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

@@ -19,6 +19,12 @@
  *     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;
+ *   - when the optional `## Sub-processes` section is on file (engagements
+ *     since the Session 3 rework): every main process has sub-processes
+ *     `MP-nn.k`, numbered from 1; every step row belongs to exactly one
+ *     sub-process of its main process and every sub-process has steps; and
+ *     every step's `#` appears in its main process's flow, so the diagram
+ *     and the matrix describe the same steps;
  *   - with `--require-cited`: every step cites at least one requirement —
  *     the state Step 5D leaves behind, required at the handoff.
  *
@@ -45,12 +51,15 @@ 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 SECTIONS = Object.freeze({ asIs: 'As-is', toBe: 'To-be', subProcesses: 'Sub-processes', 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 SUB_PROCESSES_HEADER = Object.freeze(['ID', 'Sub-process', 'Steps']);
 const PRC_RE = /^PRC-(\d{2})$/;
 const MP_RE = /^MP-(\d{2})$/;
+/** A sub-process: its main process and its 1-based number within it (`MP-01.2`). */
+const SUB_PROCESS_RE = /^(MP-\d{2})\.([1-9]\d*)$/;
 /** `### MP-01 — <name>` under Flows and Steps. */
 const MP_HEADING_RE = /^(MP-\d{2})\s+—\s+\S/;
 const PENDING = '—';
@@ -161,6 +170,7 @@ function checkProcesses(content, sources, requireCited = false) {
     let flows = 0;
     const flowsSection = sections.find((s) => s.heading === SECTIONS.flows);
     const withFlow = new Set();
+    const flowText = new Map();
     if (!flowsSection) {
         violations.push({ artifact: PROCESSES_FILE, reason: 'missing_section', id: SECTIONS.flows });
     }
@@ -175,6 +185,7 @@ function checkProcesses(content, sources, requireCited = false) {
             flows += 1;
             withFlow.add(m[1]);
             const text = s.body.map((l) => l.text).join('\n');
+            flowText.set(m[1], (flowText.get(m[1]) ?? '') + text);
             const hasFlowchart = /```mermaid\s*\n\s*flowchart\b/.test(text);
             const hasSubgraph = /^\s*subgraph\b/m.test(text);
             if (!hasFlowchart || !hasSubgraph)
@@ -185,6 +196,8 @@ function checkProcesses(content, sources, requireCited = false) {
     let steps = 0;
     let uncited = 0;
     const withSteps = new Set();
+    /** Per main process: each step's `#` cell and its line. */
+    const stepNums = new Map();
     const stepsSection = sections.find((s) => s.heading === SECTIONS.steps);
     if (!stepsSection) {
         violations.push({ artifact: PROCESSES_FILE, reason: 'missing_section', id: SECTIONS.steps });
@@ -204,9 +217,13 @@ function checkProcesses(content, sources, requireCited = false) {
                 continue;
             }
             withSteps.add(m[1]);
+            const nums = stepNums.get(m[1]) ?? new Map();
+            stepNums.set(m[1], nums);
             for (const row of tables[0].rows) {
                 steps += 1;
                 const [num, step, actor, , objects, , , requirements] = row.cells.map((c) => c.trim());
+                if ((num ?? '') !== '' && !nums.has(num))
+                    nums.set(num, row.line);
                 if ((num ?? '') === '' || (step ?? '') === '')
                     violations.push({ artifact: PROCESSES_FILE, reason: 'empty_cell', line: row.line, id: 'Step' });
                 checkActor(actor ?? '', row.line, sources, violations);
@@ -239,9 +256,85 @@ function checkProcesses(content, sources, requireCited = false) {
         if (stepsSection && !withSteps.has(id))
             violations.push({ artifact: PROCESSES_FILE, reason: 'steps_missing', line, id });
     }
+    // 5 ─ Sub-processes (optional section): every step in exactly one, every flow showing every step
+    let subProcesses = 0;
+    if (sections.some((s) => s.heading === SECTIONS.subProcesses)) {
+        const subTable = sectionTable(sections, SECTIONS.subProcesses, SUB_PROCESSES_HEADER, violations);
+        if (subTable)
+            subProcesses = checkSubProcesses(subTable.rows, toBe, stepNums, flowText, violations);
+    }
     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 };
+    return { ok: violations.length === 0, as_is: asIs.size, to_be: toBe.size, flows, steps, sub_processes: subProcesses, uncited, violations };
+}
+/** A step's `#` cell as a whole token in a flow: `01.3` must not match inside `101.3` or `01.30`. */
+function flowShowsStep(text, num) {
+    const escaped = num.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return new RegExp(`(^|[^\\w.])${escaped}(?![\\w]|\\.\\d)`).test(text);
+}
+function checkSubProcesses(rows, toBe, stepNums, flowText, violations) {
+    const ids = new Set();
+    const perProcess = new Map();
+    /** `MP-nn` → step `#` → the sub-process that claimed it. */
+    const claimed = new Map();
+    for (const row of rows) {
+        const [id, name, stepsCell] = row.cells.map((c) => c.trim());
+        const m = SUB_PROCESS_RE.exec(id ?? '');
+        if (!m) {
+            violations.push({ artifact: PROCESSES_FILE, reason: 'bad_subprocess', line: row.line });
+            continue;
+        }
+        if (ids.has(id)) {
+            violations.push({ artifact: PROCESSES_FILE, reason: 'duplicate_id', line: row.line, id });
+            continue;
+        }
+        ids.add(id);
+        const mp = m[1];
+        if (!toBe.has(mp)) {
+            violations.push({ artifact: PROCESSES_FILE, reason: 'unknown_process', line: row.line, id: mp });
+            continue;
+        }
+        perProcess.set(mp, [...(perProcess.get(mp) ?? []), Number(m[2])]);
+        if ((name ?? '') === '')
+            violations.push({ artifact: PROCESSES_FILE, reason: 'empty_cell', line: row.line, id: 'Sub-process' });
+        const tokens = (stepsCell ?? '') === PENDING ? [] : (stepsCell ?? '').split(',').map((t) => t.trim()).filter(Boolean);
+        if (tokens.length === 0)
+            violations.push({ artifact: PROCESSES_FILE, reason: 'subprocess_without_steps', line: row.line, id });
+        const known = stepNums.get(mp);
+        const owner = claimed.get(mp) ?? new Map();
+        claimed.set(mp, owner);
+        for (const t of tokens) {
+            if (known && !known.has(t))
+                violations.push({ artifact: PROCESSES_FILE, reason: 'unknown_step', line: row.line, id: `${mp} #${t}`.slice(0, 40) });
+            else if (owner.has(t))
+                violations.push({ artifact: PROCESSES_FILE, reason: 'step_in_two_subprocesses', line: row.line, id: `${mp} #${t}` });
+            else
+                owner.set(t, id);
+        }
+    }
+    for (const [mp, nums] of perProcess) {
+        const max = table.boundedSequenceMax(nums);
+        if (max === null)
+            continue;
+        const have = new Set(nums);
+        for (let n = 1; n <= max; n += 1) {
+            if (!have.has(n))
+                violations.push({ artifact: PROCESSES_FILE, reason: 'sequence_gap', id: `${mp}.${n}` });
+        }
+    }
+    for (const [mp, line] of toBe) {
+        if (!perProcess.has(mp))
+            violations.push({ artifact: PROCESSES_FILE, reason: 'subprocess_missing', line, id: mp });
+        const owner = claimed.get(mp);
+        const text = flowText.get(mp);
+        for (const [num, stepLine] of stepNums.get(mp) ?? []) {
+            if (owner && !owner.has(num))
+                violations.push({ artifact: PROCESSES_FILE, reason: 'step_without_subprocess', line: stepLine, id: `${mp} #${num}` });
+            if (text !== undefined && !flowShowsStep(text, num))
+                violations.push({ artifact: PROCESSES_FILE, reason: 'step_not_in_flow', line: stepLine, id: `${mp} #${num}` });
+        }
+    }
+    return ids.size;
 }
 /** 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) {
@@ -285,7 +378,7 @@ 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 };
+    const empty = { as_is: 0, to_be: 0, flows: 0, steps: 0, sub_processes: 0, uncited: 0 };
     if (read.kind === 'unreadable')
         return { ok: false, file: PROCESSES_FILE, ...empty, violations: [{ artifact: PROCESSES_FILE, reason: 'artifact_unreadable' }] };
     const extra = [];
@@ -330,7 +423,7 @@ function cmdDiscoveryProcessCheck(cwd, args, raw) {
         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 };
+    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, sub_processes: result.sub_processes, uncited: result.uncited };
     if (!result.ok) {
         output({ ...payload, violations: result.violations.length }, raw);
         const onlyUncited = result.violations.every((v) => v.reason === 'uncited_step');

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

@@ -17,8 +17,12 @@
  *     `_requirements.md` when it is on file and parseable;
  *   - `Story` and `Acceptance criteria` are non-empty;
  *   - `Acceptance criteria` is a criterion, not a pointer (`As in F-01`);
- *   - `Source step` is `—` or a comma list of `MP-nn #<cell>`, the main process
- *     and the step row existing in `_processes.md` when it is on file;
+ *   - `Source step` is a comma list of `MP-nn #<cell>`, the main process and
+ *     the step row existing in `_processes.md` when it is on file — a story
+ *     tied to no step (`—`) is refused (Session 3 rework: stories come from
+ *     steps);
+ *   - every persona-actor step that realises an MVP requirement is the
+ *     source step of at least one story, so the stories cover the processes;
  *   - every MVP-disposition requirement that a persona-actor step cites has at
  *     least one story (the `N-`/`T-` prefixes never need one; a requirement
  *     only `System` steps realise, or no step at all, has no user to tell it).
@@ -118,6 +122,23 @@ function needsStory(r, steps) {
         return true;
     return steps.some((s) => s.requirements.includes(r.id) && s.actors.some((a) => a !== SYSTEM_ACTOR));
 }
+/**
+ * Does this step need a story naming it as its source? A step a persona
+ * performs does, when it realises an MVP requirement that is not `N-`/`T-`.
+ * With no parseable `_requirements.md` every persona step does; a step that
+ * cites nothing yet is `process-check --require-cited`'s finding, not this one.
+ */
+function stepNeedsStory(step, requirements) {
+    if (!step.actors.some((a) => a !== SYSTEM_ACTOR))
+        return false;
+    if (!(requirements instanceof Array))
+        return true;
+    const byId = new Map(requirements.map((r) => [r.id, r]));
+    return step.requirements.some((id) => {
+        const r = byId.get(id);
+        return r !== undefined && r.disposition === rollup.DISPOSITIONS.MVP && !STORYLESS_PREFIXES.includes(r.prefix);
+    });
+}
 // ─── Check ────────────────────────────────────────────────────────────────────
 function checkStories(content, sources) {
     const violations = [];
@@ -137,6 +158,7 @@ function checkStories(content, sources) {
     const ids = new Set();
     const seqs = [];
     const storied = new Set();
+    const sourced = new Set();
     for (const row of tables[0].rows) {
         const [id, epic, requirements, story, acceptance, sourceStep] = row.cells.map((c) => c.trim());
         const m = US_RE.exec(id ?? '');
@@ -170,11 +192,13 @@ function checkStories(content, sources) {
                 storied.add(r);
         }
         const src = sourceStep ?? '';
-        if (src !== PENDING) {
+        if (src === PENDING || src === '') {
+            violations.push({ artifact: STORIES_FILE, reason: 'no_source_step', line: row.line, id: m ? id : undefined });
+        }
+        else {
             const refs = splitList(src);
-            if (refs.length === 0)
-                violations.push({ artifact: STORIES_FILE, reason: 'bad_source_step', line: row.line });
             for (const ref of refs) {
+                sourced.add(ref);
                 const sm = SOURCE_STEP_RE.exec(ref);
                 if (!sm)
                     violations.push({ artifact: STORIES_FILE, reason: 'bad_source_step', line: row.line });
@@ -193,6 +217,12 @@ function checkStories(content, sources) {
                 violations.push({ artifact: STORIES_FILE, reason: 'sequence_gap', id: `US-${String(n).padStart(2, '0')}` });
         }
     }
+    for (const step of sources.steps ?? []) {
+        if (!stepNeedsStory(step, sources.requirements))
+            continue;
+        if (!sourced.has(step.key))
+            violations.push({ artifact: PROCESSES_FILE, reason: 'step_without_story', id: step.key.slice(0, 40) });
+    }
     if (sources.requirements instanceof Array) {
         for (const r of sources.requirements) {
             if (r.disposition !== rollup.DISPOSITIONS.MVP)
@@ -266,6 +296,7 @@ module.exports = {
     STORYLESS_PREFIXES,
     SYSTEM_ACTOR,
     needsStory,
+    stepNeedsStory,
     STORIES_CHECK_FAILED: ERROR_REASON.DISCOVERY_STORIES_CHECK_FAILED,
     checkStories,
     checkProjectStories,