@pareto4/pp-core 1.21.0 → 1.22.0

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

@@ -0,0 +1,398 @@
+"use strict";
+/**
+ * Discovery tests check (Session 9 — testing and UAT).
+ *
+ * `.planning/discovery/_tests.md` is the register of the test manager's calls
+ * the agents cannot make: which main processes get an end-to-end test (a risk
+ * rating per `MP-` process), which parts of the solution get extra test
+ * attention because they are complex (components, interfaces, rules,
+ * migration rows, entities), and the testability review of every `US-` story.
+ * Session 9 writes it; the build reads it by requirement ID through
+ * `discovery for-phase`. This module checks the structure:
+ *
+ *   - `## Process risk`, `## Focus areas` and `## Acceptance` exist with the
+ *     template's columns;
+ *   - every main process of `_processes.md` § To-be has exactly one risk row,
+ *     the risk follows from impact and likelihood by the fixed matrix, and a
+ *     high-risk process without an end-to-end test cites a `D-09-<n>`;
+ *   - every focus-area subject resolves against its source when on file;
+ *   - every story of `_stories.md` has exactly one acceptance row;
+ *   - roles resolve against `_roles.md` § Roles when on file, requirements
+ *     against `_requirements.md` when on file and parseable;
+ *   - `--require-complete`: an `open` story or a focus area whose
+ *     `Requirements` is still `—` fails on its own exit identity, so the
+ *     handoff can hard-block on it while Sessions 9 and 13 only report.
+ *
+ * Posture (D-43/D-53): reports at Sessions 9 and 13; hard-blocks at the
+ * handoff. Absent artifact → exit 0 — an engagement that predates it.
+ */
+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 TESTS_FILE = `${DISCOVERY_DIR}/_tests.md`;
+const REQUIREMENTS_FILE = `${DISCOVERY_DIR}/_requirements.md`;
+const PROCESSES_FILE = `${DISCOVERY_DIR}/_processes.md`;
+const STORIES_FILE = `${DISCOVERY_DIR}/_stories.md`;
+const ROLES_FILE = `${DISCOVERY_DIR}/_roles.md`;
+const INTEGRATIONS_FILE = `${DISCOVERY_DIR}/_integrations.md`;
+const RULES_FILE = `${DISCOVERY_DIR}/_rules.md`;
+const MIGRATION_FILE = `${DISCOVERY_DIR}/_migration.md`;
+const ENTITIES_FILE = `${DISCOVERY_DIR}/_entities.md`;
+const SESSION_05_FILE = `${DISCOVERY_DIR}/session-05.md`;
+const RISK_SECTION = 'Process risk';
+const FOCUS_SECTION = 'Focus areas';
+const ACCEPTANCE_SECTION = 'Acceptance';
+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 MP_RE = /^MP-\d{2}$/;
+const US_RE = /^US-\d{2}$/;
+const ENTITY_NAME_RE = /^[A-Z][A-Za-z0-9]*$/;
+const REQUIREMENT_ID_RE = /^[A-Z][A-Z0-9]*-\d+$/;
+const SESSION_9_DECISION_RE = /\bD-09-\d+\b/;
+const TESTABLE_RE = /^(yes|amended \(D-09-\d+\)|open \(A-09-\d+\))$/;
+const RATINGS = Object.freeze(['low', 'medium', 'high']);
+/** RISK_MATRIX[impact][likelihood] — `references/discovery-tests.md` § Risk rating. */
+const RISK_MATRIX = Object.freeze({
+    high: Object.freeze({ low: 'medium', medium: 'high', high: 'high' }),
+    medium: Object.freeze({ low: 'low', medium: 'medium', high: 'high' }),
+    low: Object.freeze({ low: 'low', medium: 'low', high: 'medium' }),
+});
+/** Subject ID prefixes and the source each resolves against. */
+const SUBJECT_KINDS = Object.freeze([
+    { re: /^C-\d{2}$/, source: 'components' },
+    { re: /^IF-\d{2}$/, source: 'interfaces' },
+    { re: /^BR-\d{2}$/, source: 'rules' },
+    { re: /^MG-\d{2}$/, source: 'migrations' },
+]);
+const PENDING = '—';
+const COMPONENT_INVENTORY_LABEL = 'Component Inventory';
+const USAGE = 'Usage: pp-tools discovery tests-check [--require-complete]';
+function readIfPresent(abs) {
+    if (!node_fs_1.default.existsSync(abs))
+        return { kind: 'absent' };
+    try {
+        return { kind: 'ok', content: node_fs_1.default.readFileSync(abs, 'utf-8') };
+    }
+    catch {
+        return { kind: 'unreadable' };
+    }
+}
+function sameHeader(actual, expected) {
+    return actual.length === expected.length && actual.every((c, i) => c.trim().toLowerCase() === expected[i].toLowerCase());
+}
+function splitList(cell) {
+    return cell.split(',').map((t) => t.trim()).filter(Boolean);
+}
+function firstColumnOf(content, heading) {
+    const section = table.splitSections(content.split(/\r?\n/), 2).find((s) => s.heading === heading);
+    if (!section)
+        return new Set();
+    const tables = table.parseTables(section.body);
+    if (tables.length === 0)
+        return new Set();
+    return new Set(tables[0].rows.map((r) => (r.cells[0] ?? '').trim()).filter(Boolean));
+}
+/** Component IDs: the first column of Session 5's Component Inventory; null when absent or without IDs. */
+function componentsFrom(content) {
+    const lines = content.split(/\r?\n/);
+    const norm = (s) => s.replace(/^#+\s*/, '').replace(/\*\*/g, '').trim();
+    const at = lines.findIndex((l) => norm(l) === COMPONENT_INVENTORY_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;
+    // A row counts only when it is more than the template's `| C-01 | | |` label.
+    const out = new Set(tables[0].rows
+        .filter((r) => r.cells.slice(1).some((c) => c.trim() !== ''))
+        .map((r) => (r.cells[0] ?? '').trim())
+        .filter((c) => c !== ''));
+    return out.size === 0 ? null : out;
+}
+/** The table under a `##` heading, or a violation when it is missing or off the template. */
+function sectionTable(sections, heading, header, violations) {
+    const section = sections.find((s) => s.heading === heading);
+    if (!section) {
+        violations.push({ artifact: TESTS_FILE, reason: 'missing_section', id: heading });
+        return null;
+    }
+    const tables = table.parseTables(section.body);
+    if (tables.length === 0) {
+        violations.push({ artifact: TESTS_FILE, reason: 'missing_section', line: section.line, id: heading });
+        return null;
+    }
+    if (!sameHeader(tables[0].header, header)) {
+        violations.push({ artifact: TESTS_FILE, reason: 'bad_table_shape', line: tables[0].line, id: heading });
+        return null;
+    }
+    return tables[0];
+}
+function checkRequirements(cell, sources, line, violations) {
+    for (const r of splitList(cell)) {
+        if (!REQUIREMENT_ID_RE.test(r))
+            violations.push({ artifact: TESTS_FILE, reason: 'unknown_requirement_id', line, id: r.slice(0, 40) });
+        else if (sources.requirementIds instanceof Set && !sources.requirementIds.has(r))
+            violations.push({ artifact: TESTS_FILE, reason: 'unknown_requirement_id', line, id: r });
+    }
+}
+function checkRole(role, sources, line, violations) {
+    if (sources.roles !== null && !sources.roles.has(role))
+        violations.push({ artifact: TESTS_FILE, reason: 'unknown_role', line, id: role.slice(0, 40) });
+}
+// ─── Check ────────────────────────────────────────────────────────────────────
+function checkTests(content, sources, requireComplete = false) {
+    const violations = [];
+    const sections = table.splitSections(content.split(/\r?\n/), 2);
+    const risk = sectionTable(sections, RISK_SECTION, RISK_HEADER, violations);
+    const focus = sectionTable(sections, FOCUS_SECTION, FOCUS_HEADER, violations);
+    const acceptance = sectionTable(sections, ACCEPTANCE_SECTION, ACCEPTANCE_HEADER, violations);
+    // Process risk — one row per main process.
+    const assessed = new Set();
+    let endToEnd = 0;
+    for (const row of risk?.rows ?? []) {
+        const [mp, impact, likelihood, rating, e2e, roles, testData, rationale] = row.cells.map((c) => c.trim());
+        const line = row.line;
+        if (!MP_RE.test(mp ?? ''))
+            violations.push({ artifact: TESTS_FILE, reason: 'bad_process', line });
+        else if (assessed.has(mp))
+            violations.push({ artifact: TESTS_FILE, reason: 'duplicate_process', line, id: mp });
+        else {
+            assessed.add(mp);
+            if (sources.processes !== null && !sources.processes.has(mp))
+                violations.push({ artifact: TESTS_FILE, reason: 'unknown_process', line, id: mp });
+        }
+        const ratings = [['Impact', impact], ['Likelihood', likelihood], ['Risk', rating]];
+        let ratingsOk = true;
+        for (const [name, cell] of ratings) {
+            if (!RATINGS.includes(cell ?? '')) {
+                violations.push({ artifact: TESTS_FILE, reason: 'bad_rating', line, id: name });
+                ratingsOk = false;
+            }
+        }
+        if (ratingsOk && RISK_MATRIX[impact][likelihood] !== rating)
+            violations.push({ artifact: TESTS_FILE, reason: 'risk_mismatch', line, id: MP_RE.test(mp ?? '') ? mp : undefined });
+        if (e2e !== 'yes' && e2e !== 'no')
+            violations.push({ artifact: TESTS_FILE, reason: 'bad_end_to_end', line });
+        if (e2e === 'yes') {
+            endToEnd += 1;
+            const names = (roles ?? '') === PENDING ? [] : splitList(roles ?? '');
+            if (names.length === 0)
+                violations.push({ artifact: TESTS_FILE, reason: 'empty_cell', line, id: 'Roles' });
+            for (const n of names)
+                checkRole(n, sources, line, violations);
+            if ((testData ?? '') === '' || testData === PENDING)
+                violations.push({ artifact: TESTS_FILE, reason: 'empty_cell', line, id: 'Test data' });
+        }
+        if ((rationale ?? '') === '')
+            violations.push({ artifact: TESTS_FILE, reason: 'empty_cell', line, id: 'Rationale' });
+        if (rating === 'high' && e2e === 'no' && !SESSION_9_DECISION_RE.test(rationale ?? '')) {
+            violations.push({ artifact: TESTS_FILE, reason: 'high_risk_not_end_to_end', line, id: MP_RE.test(mp ?? '') ? mp : undefined });
+        }
+    }
+    if (risk && sources.processes !== null) {
+        for (const mp of [...sources.processes].sort()) {
+            if (!assessed.has(mp))
+                violations.push({ artifact: TESTS_FILE, reason: 'process_not_assessed', id: mp });
+        }
+    }
+    // Focus areas — one row per subject.
+    const subjects = new Set();
+    let uncited = 0;
+    for (const row of focus?.rows ?? []) {
+        const [subject, complexity, extra, requirements] = row.cells.map((c) => c.trim());
+        const line = row.line;
+        const kind = SUBJECT_KINDS.find((k) => k.re.test(subject ?? ''));
+        if (!kind && !ENTITY_NAME_RE.test(subject ?? ''))
+            violations.push({ artifact: TESTS_FILE, reason: 'bad_subject', line });
+        else if (subjects.has(subject))
+            violations.push({ artifact: TESTS_FILE, reason: 'duplicate_subject', line, id: subject });
+        else {
+            subjects.add(subject);
+            const known = kind ? sources[kind.source] : sources.entities;
+            if (known !== null && !known.has(subject))
+                violations.push({ artifact: TESTS_FILE, reason: 'unknown_subject', line, id: subject });
+        }
+        if ((complexity ?? '') === '')
+            violations.push({ artifact: TESTS_FILE, reason: 'empty_cell', line, id: 'Complexity' });
+        if ((extra ?? '') === '')
+            violations.push({ artifact: TESTS_FILE, reason: 'empty_cell', line, id: 'Extra testing' });
+        const reqCell = requirements ?? '';
+        if (reqCell === '' || reqCell === PENDING) {
+            uncited += 1;
+            if (requireComplete)
+                violations.push({ artifact: TESTS_FILE, reason: 'uncited_focus', line, id: subjects.has(subject) ? subject : undefined });
+        }
+        else {
+            checkRequirements(reqCell, sources, line, violations);
+        }
+    }
+    // Acceptance — one row per story.
+    const reviewed = new Set();
+    let open = 0;
+    for (const row of acceptance?.rows ?? []) {
+        const [story, testable, role, testData] = row.cells.map((c) => c.trim());
+        const line = row.line;
+        if (!US_RE.test(story ?? ''))
+            violations.push({ artifact: TESTS_FILE, reason: 'bad_story', line });
+        else if (reviewed.has(story))
+            violations.push({ artifact: TESTS_FILE, reason: 'duplicate_story', line, id: story });
+        else {
+            reviewed.add(story);
+            if (sources.stories !== null && !sources.stories.has(story))
+                violations.push({ artifact: TESTS_FILE, reason: 'unknown_story', line, id: story });
+        }
+        if (!TESTABLE_RE.test(testable ?? ''))
+            violations.push({ artifact: TESTS_FILE, reason: 'bad_testable', line });
+        else if (testable.startsWith('open')) {
+            open += 1;
+            if (requireComplete)
+                violations.push({ artifact: TESTS_FILE, reason: 'story_not_testable', line, id: US_RE.test(story ?? '') ? story : undefined });
+        }
+        if ((role ?? '') === '' || role === PENDING)
+            violations.push({ artifact: TESTS_FILE, reason: 'empty_cell', line, id: 'Role' });
+        else
+            checkRole(role, sources, line, violations);
+        if ((testData ?? '') === '')
+            violations.push({ artifact: TESTS_FILE, reason: 'empty_cell', line, id: 'Test data' });
+    }
+    if (acceptance && sources.stories !== null) {
+        for (const us of [...sources.stories].sort()) {
+            if (!reviewed.has(us))
+                violations.push({ artifact: TESTS_FILE, reason: 'story_not_reviewed', id: us });
+        }
+    }
+    if (sources.requirementIds === 'unparseable')
+        violations.push({ artifact: REQUIREMENTS_FILE, reason: 'requirements_unparseable' });
+    return {
+        ok: violations.length === 0,
+        processes: assessed.size,
+        end_to_end: endToEnd,
+        focus_areas: subjects.size,
+        stories: reviewed.size,
+        open_stories: open,
+        uncited,
+        violations,
+    };
+}
+function checkProjectTests(cwd, requireComplete = false) {
+    const read = readIfPresent(node_path_1.default.join(cwd, TESTS_FILE));
+    if (read.kind === 'absent')
+        return null;
+    const empty = { processes: 0, end_to_end: 0, focus_areas: 0, stories: 0, open_stories: 0, uncited: 0 };
+    if (read.kind === 'unreadable')
+        return { ok: false, file: TESTS_FILE, ...empty, violations: [{ artifact: TESTS_FILE, reason: 'artifact_unreadable' }] };
+    const extra = [];
+    const sources = {
+        requirementIds: null, processes: null, stories: null, roles: null,
+        components: null, interfaces: null, rules: null, migrations: null, entities: null,
+    };
+    const load = (file) => {
+        const r = readIfPresent(node_path_1.default.join(cwd, file));
+        if (r.kind === 'unreadable')
+            extra.push({ artifact: file, reason: 'artifact_unreadable' });
+        return r.kind === 'ok' ? r.content : null;
+    };
+    const req = load(REQUIREMENTS_FILE);
+    if (req !== null) {
+        const parsed = rollup.parseRequirementsArtifact(req);
+        sources.requirementIds = parsed.ok ? new Set(parsed.rows.map((r) => r.id)) : 'unparseable';
+    }
+    const proc = load(PROCESSES_FILE);
+    if (proc !== null)
+        sources.processes = firstColumnOf(proc, 'To-be');
+    const sto = load(STORIES_FILE);
+    if (sto !== null)
+        sources.stories = firstColumnOf(sto, 'Stories');
+    const rol = load(ROLES_FILE);
+    if (rol !== null)
+        sources.roles = firstColumnOf(rol, 'Roles');
+    const integ = load(INTEGRATIONS_FILE);
+    if (integ !== null)
+        sources.interfaces = firstColumnOf(integ, 'Interfaces');
+    const rules = load(RULES_FILE);
+    if (rules !== null)
+        sources.rules = firstColumnOf(rules, 'Rules');
+    const mig = load(MIGRATION_FILE);
+    if (mig !== null)
+        sources.migrations = firstColumnOf(mig, 'Migration');
+    const ent = load(ENTITIES_FILE);
+    if (ent !== null)
+        sources.entities = firstColumnOf(ent, 'Entities');
+    const s5 = load(SESSION_05_FILE);
+    if (s5 !== null)
+        sources.components = componentsFrom(s5);
+    const result = checkTests(read.content, sources, requireComplete);
+    result.violations.push(...extra);
+    result.ok = result.violations.length === 0;
+    return { file: TESTS_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 tests-check [--require-complete]` (dotted
+ * `query discovery.tests-check`). Absent artifact → exit 0,
+ * `present: false`. Structural faults exit via
+ * `DISCOVERY_TESTS_CHECK_FAILED`; when every fault was raised by
+ * `--require-complete` (`story_not_testable`, `uncited_focus`), the identity
+ * is `DISCOVERY_TESTS_INCOMPLETE`.
+ */
+function cmdDiscoveryTestsCheck(cwd, args, raw) {
+    const rest = args.slice(2);
+    const requireComplete = rest.includes('--require-complete');
+    if (rest.some((a) => a !== '--require-complete')) {
+        error(USAGE, ERROR_REASON.USAGE);
+        return; // unreachable
+    }
+    const result = checkProjectTests(cwd, requireComplete);
+    if (result === null) {
+        output({ ok: true, present: false, file: TESTS_FILE }, raw);
+        return;
+    }
+    const payload = {
+        ok: result.ok, present: true, file: result.file,
+        processes: result.processes, end_to_end: result.end_to_end, focus_areas: result.focus_areas,
+        stories: result.stories, open_stories: result.open_stories, uncited: result.uncited,
+    };
+    if (!result.ok) {
+        output({ ...payload, violations: result.violations.length }, raw);
+        const onlyIncomplete = result.violations.every((v) => v.reason === 'story_not_testable' || v.reason === 'uncited_focus');
+        error(`discovery tests-check: ${result.violations.length} violation(s):\n` + result.violations.map(formatViolation).join('\n'), onlyIncomplete ? ERROR_REASON.DISCOVERY_TESTS_INCOMPLETE : ERROR_REASON.DISCOVERY_TESTS_CHECK_FAILED);
+        return; // unreachable
+    }
+    output(payload, raw);
+}
+module.exports = {
+    TESTS_FILE,
+    RISK_HEADER,
+    FOCUS_HEADER,
+    ACCEPTANCE_HEADER,
+    RISK_MATRIX,
+    TESTS_CHECK_FAILED: ERROR_REASON.DISCOVERY_TESTS_CHECK_FAILED,
+    TESTS_INCOMPLETE: ERROR_REASON.DISCOVERY_TESTS_INCOMPLETE,
+    componentsFrom,
+    checkTests,
+    checkProjectTests,
+    cmdDiscoveryTestsCheck,
+};

package/pp-core/bin/lib/io.cjs

@@ -225,6 +225,11 @@ const ERROR_REASON = Object.freeze({
     DISCOVERY_SESSION_CHECK_FAILED: 'discovery_session_check_failed',
     DISCOVERY_DEVIATIONS_CHECK_FAILED: 'discovery_deviations_check_failed',
     DISCOVERY_DEVIATIONS_UNAPPROVED: 'discovery_deviations_unapproved',
+    // discovery tests register (Session 9 — testing and UAT)
+    DISCOVERY_TESTS_CHECK_FAILED: 'discovery_tests_check_failed',
+    DISCOVERY_TESTS_INCOMPLETE: 'discovery_tests_incomplete',
+    // discovery flow page (Session 3 Step 5C — iterate a swimlane)
+    DISCOVERY_FLOW_PAGE_FAILED: 'discovery_flow_page_failed',
     // timeline (Phase 35: end with no matching open run)
     TIMELINE_NO_OPEN_RUN: 'timeline_no_open_run',
     // generic

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

@@ -58,7 +58,7 @@ const uatPredicate = require("./uat-predicate.cjs");
 const { evaluateUatPassed } = uatPredicate;
 const { planningDir, withPlanningLock, milestonePathsFor } = planningWorkspace;
 const { extractFrontmatter } = frontmatterMod;
-const { readModifyWriteStateMd, stateExtractField, stateReplaceField, stateReplaceFieldWithFallback, syncStateFrontmatter, withStateLock, updatePerformanceMetricsSection, } = stateMod;
+const { readModifyWriteStateMd, stateExtractField, stateReplaceField, stateReplaceFieldWithFallback, syncStateFrontmatter, stripFrontmatter, withStateLock, updatePerformanceMetricsSection, } = stateMod;
 // #2893 — strict canonical filter: `{padded_phase}-{NN}-PLAN.md` or `PLAN.md`.
 const isCanonicalPlanFile = (f) => f.endsWith('-PLAN.md') || f === 'PLAN.md';
 // Any .md file with PLAN anywhere in the basename — diagnostic net
@@ -1355,7 +1355,13 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
             }
             if (node_fs_1.default.existsSync(statePath)) {
                 const originalStateContent = (0, shell_command_projection_cjs_1.platformReadSync)(statePath) || '';
-                let stateContent = originalStateContent;
+                // #1257 class: the body-field patterns are case-insensitive and line-anchored, so
+                // run over the whole file they hit the YAML keys first (`status:`, `progress:`)
+                // and the body Status line never moved. Edit the body only; syncStateFrontmatter
+                // below re-derives the frontmatter from it.
+                const strippedBody = stripFrontmatter(originalStateContent);
+                let frontmatterPrefix = originalStateContent.slice(0, originalStateContent.length - strippedBody.length);
+                let stateContent = strippedBody;
                 const phaseValue = nextPhaseNum || phaseNum;
                 const nextPhaseDisplayName = phaseDisplayNameFromRoadmap(roadmapContent, nextPhaseNum) ??
                     phaseDisplayNameFromSlug(nextPhaseName);
@@ -1420,7 +1426,7 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                         const newPercent = (0, phase_lifecycle_cjs_1.clampPercent)(newCompleted, totalPhases);
                         stateContent =
                             stateReplaceField(stateContent, 'Progress', `${newPercent}%`) || stateContent;
-                        stateContent = stateContent.replace(/(percent:\s*)\d+/, `$1${newPercent}`);
+                        frontmatterPrefix = frontmatterPrefix.replace(/(percent:\s*)\d+/, `$1${newPercent}`);
                     }
                 }
                 stateContent = updatePerformanceMetricsSection(stateContent, cwd, phaseNum, planCount, summaryCount);
@@ -1430,14 +1436,14 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
                 // one still on disk.
                 // D-10: this transaction sets Last activity itself; that explicit date flows.
                 const activityFieldSet = (0, state_document_cjs_1.extractPositionalField)(stateContent, 'Last Activity', 'Last activity') !==
-                    (0, state_document_cjs_1.extractPositionalField)(originalStateContent, 'Last Activity', 'Last activity');
+                    (0, state_document_cjs_1.extractPositionalField)(strippedBody, 'Last Activity', 'Last activity');
                 // 261007-rly D-11: phase complete opts OUT of the stopped_at hold and keeps
                 // re-deriving the key from the Session line, as it did before the hold moved
                 // into syncStateFrontmatter: bug #3517's pin (tests/phase.test.cjs) needs a
                 // newer Session line to replace a stale stored value here, the opposite of
                 // the operator-note shape the hold protects. Filed, not decided here:
                 // todos/pending/phase-complete-rederives-stopped-at-from-the-session-line.md.
-                stateContent = syncStateFrontmatter(stateContent, cwd, roadmapContent, activityFieldSet, true);
+                stateContent = syncStateFrontmatter(frontmatterPrefix + stateContent, cwd, roadmapContent, activityFieldSet, true);
                 stateFrontmatterUpdated = (0, state_document_cjs_1.diffFrontmatterFields)(extractFrontmatter(originalStateContent), extractFrontmatter(stateContent));
                 writes.push({ filePath: statePath, before: originalStateContent, after: stateContent });
             }

package/pp-core/bin/lib/state.cjs

@@ -3011,6 +3011,7 @@ module.exports = {
     writeStateMd,
     readModifyWriteStateMd,
     syncStateFrontmatter,
+    stripFrontmatter,
     matchSessionSection,
     withStateLock,
     updatePerformanceMetricsSection,

package/pp-core/bin/pp-tools.cjs

@@ -2773,13 +2773,37 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
         } catch (deviationsCheckErr) {
           error(`discovery deviations-check: ${deviationsCheckErr && deviationsCheckErr.message ? deviationsCheckErr.message : String(deviationsCheckErr)}`, ERROR_REASON.UNKNOWN);
         }
+      } else if (subcommand === 'tests-check') {
+        // discovery tests-check [--require-complete] — _tests.md structure:
+        // one risk row per main process with the matrix rating, end-to-end
+        // for every high risk unless a D-09 decision says why, focus-area
+        // subjects resolving, one acceptance row per story.
+        // --require-complete also fails on an open story or an uncited focus
+        // area (discovery_tests_incomplete).
+        const testsRegister = require('./lib/discovery-tests.cjs');
+        try {
+          testsRegister.cmdDiscoveryTestsCheck(cwd, args, raw);
+        } catch (testsCheckErr) {
+          error(`discovery tests-check: ${testsCheckErr && testsCheckErr.message ? testsCheckErr.message : String(testsCheckErr)}`, ERROR_REASON.UNKNOWN);
+        }
+      } else if (subcommand === 'flow-page') {
+        // discovery flow-page <MP-nn> [--out <file.html>] — render one main
+        // process (swimlane, sub-processes, step matrix) from _processes.md
+        // as a page the agent publishes and republishes while the room
+        // iterates the diagram (Session 3 Step 5C).
+        const flowPage = require('./lib/discovery-flow-page.cjs');
+        try {
+          flowPage.cmdDiscoveryFlowPage(cwd, args, raw);
+        } catch (flowPageErr) {
+          error(`discovery flow-page: ${flowPageErr && flowPageErr.message ? flowPageErr.message : String(flowPageErr)}`, ERROR_REASON.UNKNOWN);
+        }
       } else {
         // WIRING, NOT HELP TEXT: tests/discovery-artifacts.test.cjs derives each
         // subcommand spelling by regexing `<namespace>_<subcommand>_failed` out of
         // the engine's exported exit identity, splits this string on commas and
         // asserts membership. A spelling missing here is a command the engine
         // claims to be and the router does not dispatch.
-        error('Unknown discovery subcommand. Available: rollup, input-check, research-check, screen-check, element-sweep, rebaseline-check, vault-check, charter-check, entity-check, process-check, rules-check, stories-check, phases-check, for-phase, roles-check, integrations-check, migration-check, deviations-check, session-check', ERROR_REASON.SDK_UNKNOWN_COMMAND);
+        error('Unknown discovery subcommand. Available: rollup, input-check, research-check, screen-check, element-sweep, rebaseline-check, vault-check, charter-check, entity-check, process-check, rules-check, stories-check, phases-check, for-phase, roles-check, integrations-check, migration-check, deviations-check, session-check, tests-check, flow-page', ERROR_REASON.SDK_UNKNOWN_COMMAND);
       }
       break;
     }

package/pp-core/references/discovery-build-consumption.md

@@ -43,6 +43,7 @@ blocked by it. The verifier takes the acceptance criteria of the extract's `_req
 | `_screens.md` § Screens, § No screen (still MVP) | screens whose `Requirements` cites one; no-screen rows keyed by one | ui-phase (exists); planner |
 | `_roles.md` § Permissions, § Roles, § Screens | the permission rows whose `Requirements` cites one; the § Roles row of every role those permissions name; the § Screens rows of those roles and of the phase's screens (`references/discovery-access.md`) | planner auth phase; forbidden-path tests |
 | `_integrations.md` § Interfaces, § Contract, § Errors | the interface rows whose `Requirements` cites one or that a selected step names in its `Integration` cell (`IF-nn`); their contract and error rows (`references/discovery-integrations.md`) | planner integration phases |
+| `_tests.md` § Process risk, § Focus areas, § Acceptance | the risk rows with `End-to-end` `yes` of the main processes touched; the focus-area rows whose `Requirements` cites one; the acceptance rows of the selected stories (`references/discovery-tests.md`) | planner end-to-end and extra test tasks; verifier UAT (role and test data per story) |
 | `_migration.md`, `_deviations.md` | generic: every table carrying a `Requirements` (or `Requirement IDs`) column contributes its citing rows. A table with no requirement column is listed as *not filterable* in the extract, never silently dropped — `_deviations.md § Deviations` always is | planner migration phase; `pp-vault-review` reads `_deviations.md` whole (§ Deviations read contract) |
 | `_phases.md` § Phases | the phase's requirement IDs when ROADMAP.md has none yet | ROADMAP.md (handoff 5f, verbatim); `for-phase` |
 
@@ -69,7 +70,7 @@ table must carry a `Requirements` column; the column name is the join, not the p
 | `Requirements` | comma list of `_requirements.md` IDs (`[A-Z][A-Z0-9]*-\d+`), at least one |
 | `Story` | free text — `As a <persona>, I want <goal> so that <benefit>`; pipes escaped `\|` |
 | `Acceptance criteria` | free text, non-empty, and a criterion — never a pointer such as `As in F-01`; the verifier reads it verbatim as the UAT |
-| `Source step` | comma list of `MP-<nn> #<cell>` — the main process and the `#` cell of the step-matrix row the story was derived from, copied verbatim (`MP-05 #05.1`, `MP-01 #3`) — or `—` |
+| `Source step` | comma list of `MP-<nn> #<cell>` — the main process and the `#` cell of the step-matrix row the story was derived from, copied verbatim (`MP-05 #05.1`, `MP-01 #3`); never `—` — a story comes from a step |
 
 ### Parser contract — `pp_run query discovery.stories-check`
 
@@ -82,7 +83,9 @@ table must carry a `Requirements` column; the column name is the join, not the p
 | `empty_cell` | `Story` or `Acceptance criteria` is empty (the cell is named) |
 | `acceptance_is_pointer` | `Acceptance criteria` starts with `As in`, `See`, `Zie` or `Idem` — a pointer, not a criterion the verifier can run |
 | `no_requirement` / `unknown_requirement_id` | no requirement cited, or one of the wrong shape or absent from `_requirements.md` (resolution skipped when that file is absent) |
-| `bad_source_step` / `unknown_process_id` / `unknown_process_step` | a `Source step` token is neither `—` nor `MP-nn #<cell>`; the main process is not in `_processes.md` § To-be; the step row is not in its matrix (both resolutions skipped when `_processes.md` is absent) |
+| `bad_source_step` / `unknown_process_id` / `unknown_process_step` | a `Source step` token is not `MP-nn #<cell>`; the main process is not in `_processes.md` § To-be; the step row is not in its matrix (both resolutions skipped when `_processes.md` is absent) |
+| `no_source_step` | `Source step` is `—` or empty — every story is tied to the step it came from |
+| `step_without_story` | a step row whose actor is a persona and that cites at least one `MVP` requirement (not `N-`/`T-`) is no story's source step — the stories do not cover the process. Without a parseable `_requirements.md` every persona step needs one |
 | `mvp_requirement_without_story` | an `MVP` requirement that at least one persona-actor step row cites has no story. Mirrors Step 5E: stories come from the step rows whose actor is not `System`, so a requirement realised only by `System` steps, or cited by no step at all (engagement process rows), needs none; `N-`/`T-` rows never do. Without `_processes.md` only the prefix exemption applies |
 | `requirements_unparseable` / `artifact_unreadable` | `_requirements.md` present but failing `rollup --check`; an artifact present but unreadable |
 

package/pp-core/references/discovery-id-conventions.md

@@ -102,7 +102,7 @@ Non-functional requirements are not in this list: they are `N-` rows of
 
 The canonical artifacts — `_requirements.md`, `_screens.md`, `_feedback.md`, `_sweep.md`,
 `_processes.md`, `_entities.md`, `_rules.md`, `_glossary.md`, `_stories.md`, `_phases.md`,
-`_roles.md`, `_integrations.md`, `_migration.md`, `_deviations.md`, the research registers and
+`_roles.md`, `_integrations.md`, `_migration.md`, `_deviations.md`, `_tests.md`, the research registers and
 the Project Charter — are the single source of truth for the life of the engagement, through the
 build and after it. The session files are the facilitation record behind them.
 

package/pp-core/references/discovery-processes.md

@@ -11,7 +11,7 @@ lazily; it is never `@`-imported.
 | Session | `_processes.md` | `_rules.md` | `_glossary.md` |
 |---|---|---|---|
 | 2 | created from the template; `## As-is` rows (`PRC-`) from topic 1 | — | created from the template; terms the client used for the same thing |
-| 3 | Step 5A `## To-be` rows (`MP-`, each with `Replaces`); 5B one swimlane per main process under `## Flows`; 5C one step matrix per main process under `## Steps`, `Exception` column filled; 5D back-fills `Requirements` | Step 5D′ mints `BR-` rows from the step matrices | topic 1 glossary sweep: one row per term, synonyms under `Do not use` |
+| 3 | Step 5B `## To-be` rows (`MP-`, each with `Replaces`) — the full process inventory; per main process, Step 5C its swimlane under `## Flows` with every step node labelled with its `#`, its `## Sub-processes` rows (`MP-nn.k`) and its step matrix under `## Steps`, `Exception` column filled; 5D back-fills `Requirements` | Step 5D′ mints `BR-` rows from the step matrices | topic 1 glossary sweep: one row per term, synonyms under `Do not use` |
 | 8 | `process-check` and `rules-check` in the Closing Step (reporting) | | |
 | 13 | both in the Step 0 gates (reporting) | | |
 | handoff | `process-check --require-cited` and `rules-check` hard-block | | |
@@ -48,13 +48,17 @@ Illustration only — not part of the template, names invented:
 |---|---|---|---|---|---|---|---|
 | 01.1 | Create task | Team member | Task form | Task [C] | — | Title missing → form error, nothing saved | K-06 |
 
+| ID | Sub-process | Steps |
+|---|---|---|
+| MP-01.1 | Register the request | 01.1, 01.2 |
+
 Bootstrap template — Session 2 copies it verbatim to `.planning/discovery/_processes.md`, replacing
 `[PROJECT_NAME]`:
 
 ```markdown
 # Processes — [PROJECT_NAME]
 
-**Conventions:** pp-core reference `references/discovery-processes.md`. `PRC-` rows are the as-is processes (Session 2), `MP-` rows the to-be main processes (Session 3) with the as-is processes each replaces or `new`. One swimlane and one step matrix per main process. Nothing is renumbered or deleted; a change after sign-off edits the row in place and appends `→ amended by D-<ss>-<n>`.
+**Conventions:** pp-core reference `references/discovery-processes.md`. `PRC-` rows are the as-is processes (Session 2), `MP-` rows the to-be main processes (Session 3) with the as-is processes each replaces or `new`. Every main process has sub-processes `MP-nn.k`, each listing its steps by `#`; every step belongs to exactly one. One swimlane and one step matrix per main process; the swimlane labels every step node with its `#`. Nothing is renumbered or deleted; a change after sign-off edits the row in place and appends `→ amended by D-<ss>-<n>`.
 
 ## As-is
 
@@ -66,12 +70,23 @@ Bootstrap template — Session 2 copies it verbatim to `.planning/discovery/_pro
 | ID | Main process | Replaces | Trigger | End state | Primary actor | EPICs |
 |----|--------------|----------|---------|-----------|---------------|-------|
 
+## Sub-processes
+
+| ID | Sub-process | Steps |
+|----|-------------|-------|
+
 ## Flows
 
 ## Steps
 ```
 
-Under `## Flows`, Step 5B adds one `### MP-nn — <name>` heading per main process holding a swimlane:
+An engagement whose `_processes.md` predates the Session 3 rework has no `## Sub-processes`
+section; `process-check` then skips the sub-process and flow-coverage rules below. Adding the
+section (empty) opts the engagement in.
+
+Under `## Flows`, Step 5C adds one `### MP-nn — <name>` heading per main process holding a swimlane.
+Every step node carries its matrix `#` at the start of its label, so the diagram and the matrix
+describe the same steps; decisions and end states need no number:
 
 ````markdown
 ### MP-01 — Handle a task
@@ -79,12 +94,14 @@ Under `## Flows`, Step 5B adds one `### MP-nn — <name>` heading per main proce
 ```mermaid
 flowchart LR
   subgraph Team member
-    S1[Create task] --> S2[Assign]
+    S1["01.1 Create task"] --> S2["01.2 Assign"]
+    S2 --> D1{Urgent?}
   end
   subgraph System
-    S3[Notify assignee]
+    S3["01.3 Notify assignee"]
   end
-  S2 --> S3
+  D1 -->|yes| S3
+  D1 -->|no| E1([Task queued])
 ```
 ````
 
@@ -117,6 +134,13 @@ column name and the reason code — never cell prose. Absent `_processes.md` →
 | `### MP-nn — <name>` under Flows and Steps | names a To-be row | `unknown_process` |
 | a main process without a `### MP-nn` under Flows / Steps | one swimlane and one matrix each | `flow_missing`, `steps_missing` naming the MP |
 | a flow body | a ```` ```mermaid ```` block opening with `flowchart` and holding at least one `subgraph` | `flow_not_swimlane` |
+| `## Sub-processes` (optional — absent on engagements that predate it) | one table with the template's columns | `bad_table_shape (Sub-processes)` |
+| Sub-processes `ID` | `MP-nn.k` — a To-be main process and `k` from 1, unique, contiguous per main process | `bad_subprocess`, `duplicate_id`, `unknown_process`, `sequence_gap` naming `MP-nn.k` |
+| Sub-processes `Sub-process` | non-empty | `empty_cell (Sub-process)` |
+| Sub-processes `Steps` | a comma list of `#` cells of that main process's step matrix | `subprocess_without_steps`, `unknown_step`, `step_in_two_subprocesses` naming `MP-nn #<cell>` |
+| every main process, when the section is on file | at least one sub-process | `subprocess_missing` |
+| every step row, when the section is on file | listed by exactly one sub-process | `step_without_subprocess` naming `MP-nn #<cell>` |
+| every step row, when the section is on file | its `#` appears as a whole token in its main process's flow | `step_not_in_flow` naming `MP-nn #<cell>` |
 | step `#`, `Step` | non-empty | `empty_cell (Step)` |
 | `UI`, `Integration`, `Exception` | free text (`—` allowed) | **not mechanically checked** — the Exception column must exist, its content is the facilitator's |
 | `Data objects` | `—`, or a comma list of `Name [C/R/U/D]` tokens | `bad_data_object`; whether each name is an entity is `entity-check`'s `unknown_entity` |
@@ -126,7 +150,7 @@ column name and the reason code — never cell prose. Absent `_processes.md` →
 
 **Exit identity.** `discovery_process_check_failed` for structural faults;
 `discovery_process_steps_uncited` when every fault is an `uncited_step`. Payload: `ok`, `present`,
-`file`, `as_is`, `to_be`, `flows`, `steps`, `uncited`.
+`file`, `as_is`, `to_be`, `flows`, `steps`, `sub_processes`, `uncited`.
 
 ## `_rules.md`