@pareto4/pp-core 1.19.0 → 1.20.0

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

@@ -0,0 +1,273 @@
+"use strict";
+/**
+ * Discovery user-stories check (Discovery Sprint improvement plan, Batch 4).
+ *
+ * `.planning/discovery/_stories.md` is the register of user stories Session 3
+ * Step 5E mints from the step matrices: `US-nn`, the EPIC it belongs to, the
+ * requirements it realises, the story itself, its acceptance criteria and the
+ * step it was derived from. Before Batch 4 the stories lived only in Session
+ * 3's Notes Template, where no build agent read them (review F-4); the
+ * verifier now takes its UAT from this register through `for-phase`. This
+ * module checks the structure:
+ *
+ *   - the `## Stories` table exists with the template's columns;
+ *   - `US-` IDs are well-formed, unique, contiguous;
+ *   - `EPIC` is one `E-nn`;
+ *   - every story cites at least one requirement, each existing in
+ *     `_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;
+ *   - 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).
+ *
+ * Posture (D-43/D-53): reports at Sessions 8 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 STORIES_FILE = `${DISCOVERY_DIR}/_stories.md`;
+const REQUIREMENTS_FILE = `${DISCOVERY_DIR}/_requirements.md`;
+const PROCESSES_FILE = `${DISCOVERY_DIR}/_processes.md`;
+const STORIES_SECTION = 'Stories';
+const STORIES_HEADER = Object.freeze(['ID', 'EPIC', 'Requirements', 'Story', 'Acceptance criteria', 'Source step']);
+const US_RE = /^US-(\d{2})$/;
+const EPIC_RE = /^E-\d{2}$/;
+const REQUIREMENT_ID_RE = /^[A-Z][A-Z0-9]*-\d+$/;
+/** `MP-nn #<cell>` — the main process and the step matrix's `#` cell, copied verbatim (`01.3`, `5`). */
+const SOURCE_STEP_RE = /^(MP-\d{2}) #(\S+)$/;
+const MP_HEADING_RE = /^(MP-\d{2})\s+—\s+\S/;
+const SYSTEM_ACTOR = 'System';
+/** An acceptance-criteria cell that only points elsewhere is no criterion the verifier can run. */
+const POINTER_AC_RE = /^(as in|see|zie|idem)\b/i;
+const PENDING = '—';
+/** Requirement prefixes that need no user story: non-functional and technical rows have no actor. */
+const STORYLESS_PREFIXES = Object.freeze(['N-', 'T-']);
+const USAGE = 'Usage: pp-tools discovery stories-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);
+}
+/** First-column IDs of the first table under a `## <heading>` of another artifact. */
+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));
+}
+/**
+ * Every step row of `_processes.md` § Steps: its key (`MP-nn #<cell>`), its
+ * actors and the requirements it cites. `null` when the section is absent —
+ * the step rule then cannot run and only the prefix exemption applies.
+ */
+function stepsOf(content) {
+    const steps = table.splitSections(content.split(/\r?\n/), 2).find((s) => s.heading === 'Steps');
+    if (!steps)
+        return null;
+    const out = [];
+    for (const sec of table.splitSections(steps.body.map((l) => l.text), 3)) {
+        const m = MP_HEADING_RE.exec(sec.heading);
+        const tbl = table.parseTables(sec.body)[0];
+        if (!m || !tbl)
+            continue;
+        for (const r of tbl.rows) {
+            out.push({ key: `${m[1]} #${(r.cells[0] ?? '').trim()}`, actors: splitList(r.cells[2] ?? ''), requirements: splitList(r.cells[7] ?? '') });
+        }
+    }
+    return out;
+}
+/**
+ * Does this MVP requirement need a user story? Step 5E derives stories from the
+ * step rows where the actor is a persona, so the check mirrors that: a
+ * requirement needs one when at least one step citing it has an actor other
+ * than `System`. Without a step matrix the prefix exemption is all there is.
+ */
+function needsStory(r, steps) {
+    if (STORYLESS_PREFIXES.includes(r.prefix))
+        return false;
+    if (steps === null)
+        return true;
+    return steps.some((s) => s.requirements.includes(r.id) && s.actors.some((a) => a !== SYSTEM_ACTOR));
+}
+// ─── Check ────────────────────────────────────────────────────────────────────
+function checkStories(content, sources) {
+    const violations = [];
+    const sections = table.splitSections(content.split(/\r?\n/), 2);
+    const section = sections.find((s) => s.heading === STORIES_SECTION);
+    if (!section) {
+        return { ok: false, stories: 0, violations: [{ artifact: STORIES_FILE, reason: 'missing_section', id: STORIES_SECTION }] };
+    }
+    const tables = table.parseTables(section.body);
+    if (tables.length === 0) {
+        return { ok: false, stories: 0, violations: [{ artifact: STORIES_FILE, reason: 'missing_section', line: section.line, id: STORIES_SECTION }] };
+    }
+    if (!sameHeader(tables[0].header, STORIES_HEADER)) {
+        return { ok: false, stories: 0, violations: [{ artifact: STORIES_FILE, reason: 'bad_table_shape', line: tables[0].line, id: STORIES_SECTION }] };
+    }
+    const knownIds = sources.requirements instanceof Array ? new Set(sources.requirements.map((r) => r.id)) : null;
+    const ids = new Set();
+    const seqs = [];
+    const storied = 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 ?? '');
+        if (!m) {
+            violations.push({ artifact: STORIES_FILE, reason: 'bad_id', line: row.line });
+        }
+        else if (ids.has(id)) {
+            violations.push({ artifact: STORIES_FILE, reason: 'duplicate_id', line: row.line, id });
+        }
+        else {
+            ids.add(id);
+            seqs.push(Number(m[1]));
+        }
+        if (!EPIC_RE.test(epic ?? ''))
+            violations.push({ artifact: STORIES_FILE, reason: 'bad_epic', line: row.line });
+        if ((story ?? '') === '')
+            violations.push({ artifact: STORIES_FILE, reason: 'empty_cell', line: row.line, id: 'Story' });
+        if ((acceptance ?? '') === '')
+            violations.push({ artifact: STORIES_FILE, reason: 'empty_cell', line: row.line, id: 'Acceptance criteria' });
+        else if (POINTER_AC_RE.test(acceptance))
+            violations.push({ artifact: STORIES_FILE, reason: 'acceptance_is_pointer', line: row.line, id });
+        const reqs = splitList(requirements ?? '');
+        if (reqs.length === 0)
+            violations.push({ artifact: STORIES_FILE, reason: 'no_requirement', line: row.line });
+        for (const r of reqs) {
+            if (!REQUIREMENT_ID_RE.test(r))
+                violations.push({ artifact: STORIES_FILE, reason: 'unknown_requirement_id', line: row.line, id: r.slice(0, 40) });
+            else if (knownIds !== null && !knownIds.has(r))
+                violations.push({ artifact: STORIES_FILE, reason: 'unknown_requirement_id', line: row.line, id: r });
+            else
+                storied.add(r);
+        }
+        const src = sourceStep ?? '';
+        if (src !== PENDING) {
+            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) {
+                const sm = SOURCE_STEP_RE.exec(ref);
+                if (!sm)
+                    violations.push({ artifact: STORIES_FILE, reason: 'bad_source_step', line: row.line });
+                else if (sources.processes !== null && !sources.processes.has(sm[1]))
+                    violations.push({ artifact: STORIES_FILE, reason: 'unknown_process_id', line: row.line, id: sm[1] });
+                else if (sources.steps !== null && !sources.steps.some((st) => st.key === ref))
+                    violations.push({ artifact: STORIES_FILE, reason: 'unknown_process_step', line: row.line, id: ref.slice(0, 40) });
+            }
+        }
+    }
+    const max = table.boundedSequenceMax(seqs);
+    if (max !== null) {
+        const have = new Set(seqs);
+        for (let n = 1; n <= max; n += 1) {
+            if (!have.has(n))
+                violations.push({ artifact: STORIES_FILE, reason: 'sequence_gap', id: `US-${String(n).padStart(2, '0')}` });
+        }
+    }
+    if (sources.requirements instanceof Array) {
+        for (const r of sources.requirements) {
+            if (r.disposition !== rollup.DISPOSITIONS.MVP)
+                continue;
+            if (!needsStory(r, sources.steps))
+                continue;
+            if (!storied.has(r.id))
+                violations.push({ artifact: REQUIREMENTS_FILE, reason: 'mvp_requirement_without_story', id: r.id });
+        }
+    }
+    else if (sources.requirements === 'unparseable') {
+        violations.push({ artifact: REQUIREMENTS_FILE, reason: 'requirements_unparseable' });
+    }
+    return { ok: violations.length === 0, stories: ids.size, violations };
+}
+function checkProjectStories(cwd) {
+    const read = readIfPresent(node_path_1.default.join(cwd, STORIES_FILE));
+    if (read.kind === 'absent')
+        return null;
+    if (read.kind === 'unreadable')
+        return { ok: false, file: STORIES_FILE, stories: 0, violations: [{ artifact: STORIES_FILE, reason: 'artifact_unreadable' }] };
+    const extra = [];
+    const sources = { requirements: null, processes: null, steps: null };
+    const req = readIfPresent(node_path_1.default.join(cwd, REQUIREMENTS_FILE));
+    if (req.kind === 'unreadable')
+        extra.push({ artifact: REQUIREMENTS_FILE, reason: 'artifact_unreadable' });
+    if (req.kind === 'ok') {
+        const parsed = rollup.parseRequirementsArtifact(req.content);
+        sources.requirements = parsed.ok ? parsed.rows.map((r) => ({ id: r.id, prefix: r.prefix, disposition: r.disposition })) : 'unparseable';
+    }
+    const proc = readIfPresent(node_path_1.default.join(cwd, PROCESSES_FILE));
+    if (proc.kind === 'unreadable')
+        extra.push({ artifact: PROCESSES_FILE, reason: 'artifact_unreadable' });
+    if (proc.kind === 'ok') {
+        sources.processes = firstColumnOf(proc.content, 'To-be');
+        sources.steps = stepsOf(proc.content);
+    }
+    const result = checkStories(read.content, sources);
+    result.violations.push(...extra);
+    result.ok = result.violations.length === 0;
+    return { file: STORIES_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 stories-check` (dotted `query discovery.stories-check`). Absent artifact → exit 0, `present: false`. */
+function cmdDiscoveryStoriesCheck(cwd, args, raw) {
+    if (args.length > 2) {
+        error(USAGE, ERROR_REASON.USAGE);
+        return; // unreachable
+    }
+    const result = checkProjectStories(cwd);
+    if (result === null) {
+        output({ ok: true, present: false, file: STORIES_FILE }, raw);
+        return;
+    }
+    const payload = { ok: result.ok, present: true, file: result.file, stories: result.stories };
+    if (!result.ok) {
+        output({ ...payload, violations: result.violations.length }, raw);
+        error(`discovery stories-check: ${result.violations.length} violation(s):\n` + result.violations.map(formatViolation).join('\n'), ERROR_REASON.DISCOVERY_STORIES_CHECK_FAILED);
+        return; // unreachable
+    }
+    output(payload, raw);
+}
+module.exports = {
+    STORIES_FILE,
+    STORIES_HEADER,
+    STORYLESS_PREFIXES,
+    SYSTEM_ACTOR,
+    needsStory,
+    STORIES_CHECK_FAILED: ERROR_REASON.DISCOVERY_STORIES_CHECK_FAILED,
+    checkStories,
+    checkProjectStories,
+    cmdDiscoveryStoriesCheck,
+};

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

@@ -40,7 +40,7 @@ const VOID_TAGS = new Set([
 const RAW_TEXT_TAGS = new Set(['script', 'style', 'noscript']);
 const ID_RE = /^[A-Za-z][A-Za-z0-9_:.-]{0,79}$/;
 const REQ_ID_RE = /^[A-Z][A-Z0-9]*-\d+$/;
-const DECISION_RE = /^D-\d{2}-\d+$/;
+const DECISION_RE = /^D-(?:\d{2}|P\d{2})-\d+$/;
 const ELEMENT_RE = /^(\*|[A-Za-z0-9_.-]+\.html?)#([A-Za-z][A-Za-z0-9_:.-]{0,79})$/;
 const ROUND_RE = /^## Sweep (\d{1,2}) — \d{4}-\d{2}-\d{2} — .+$/;
 const TABLE_HEADER = ['Element', 'Outcome', 'Reference'];

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

@@ -90,9 +90,64 @@ function boundedSequenceMax(seqs) {
     const max = seqs.reduce((a, b) => (b > a ? b : a), 0);
     return max > MAX_SEQUENCE_SPAN ? null : max;
 }
+/**
+ * Every pipe table in a run of numbered lines (Discovery Sprint improvement
+ * plan, Batch 2). The header is the row before the first separator; data rows
+ * follow until the first line that is not a pipe row; a second separator
+ * starts the next table. Cells go through `splitTableCells`, so an escaped pipe
+ * inside a free-text cell never shifts a column.
+ */
+function parseTables(body) {
+    const tables = [];
+    for (let i = 1; i < body.length; i += 1) {
+        if (!SEPARATOR_ROW_RE.test(body[i].text) || !body[i - 1].text.trim().startsWith('|'))
+            continue;
+        const table = { line: body[i - 1].n, header: splitTableCells(body[i - 1].text), rows: [] };
+        let j = i + 1;
+        for (; j < body.length; j += 1) {
+            const text = body[j].text.trim();
+            if (!text.startsWith('|') || SEPARATOR_ROW_RE.test(text))
+                break;
+            table.rows.push({ line: body[j].n, cells: splitTableCells(text) });
+        }
+        tables.push(table);
+        i = j - 1;
+    }
+    return tables;
+}
+/**
+ * Split a file into the sections opened by headings of exactly `level` hashes
+ * (`## ` for 2). A section's body runs to the next heading of the same or a
+ * higher level; lower-level headings stay inside the body, so a caller can
+ * split a body again at the next level. Lines before the first heading belong
+ * to no section.
+ */
+function splitSections(lines, level) {
+    const open = new RegExp(`^#{${level}}\\s+(.*)$`);
+    const close = new RegExp(`^#{1,${level}}\\s`);
+    const out = [];
+    let current = null;
+    for (let i = 0; i < lines.length; i += 1) {
+        const m = open.exec(lines[i]);
+        if (m) {
+            current = { heading: m[1].trim(), line: i + 1, body: [] };
+            out.push(current);
+            continue;
+        }
+        if (close.test(lines[i])) {
+            current = null;
+            continue;
+        }
+        if (current)
+            current.body.push({ n: i + 1, text: lines[i] });
+    }
+    return out;
+}
 module.exports = {
     splitTableCells,
     SEPARATOR_ROW_RE,
     MAX_SEQUENCE_SPAN,
     boundedSequenceMax,
+    parseTables,
+    splitSections,
 };

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

@@ -203,6 +203,28 @@ const ERROR_REASON = Object.freeze({
     DISCOVERY_REBASELINE_CHECK_FAILED: 'discovery_rebaseline_check_failed',
     // discovery vault context record (PBI 75336)
     DISCOVERY_VAULT_CHECK_FAILED: 'discovery_vault_check_failed',
+    // discovery project charter (Discovery Sprint improvement plan, Batch 1)
+    DISCOVERY_CHARTER_CHECK_FAILED: 'discovery_charter_check_failed',
+    DISCOVERY_CHARTER_UNSIGNED: 'discovery_charter_unsigned',
+    // discovery data model, processes, business rules (improvement plan, Batch 2)
+    DISCOVERY_ENTITY_CHECK_FAILED: 'discovery_entity_check_failed',
+    DISCOVERY_ENTITY_CHECK_INCOMPLETE: 'discovery_entity_check_incomplete',
+    DISCOVERY_PROCESS_CHECK_FAILED: 'discovery_process_check_failed',
+    DISCOVERY_PROCESS_STEPS_UNCITED: 'discovery_process_steps_uncited',
+    DISCOVERY_RULES_CHECK_FAILED: 'discovery_rules_check_failed',
+    DISCOVERY_STORIES_CHECK_FAILED: 'discovery_stories_check_failed',
+    DISCOVERY_PHASES_CHECK_FAILED: 'discovery_phases_check_failed',
+    DISCOVERY_FOR_PHASE_FAILED: 'discovery_for_phase_failed',
+    // discovery roles, integrations, migration, deviations (improvement plan, Batch 3)
+    DISCOVERY_ROLES_CHECK_FAILED: 'discovery_roles_check_failed',
+    DISCOVERY_INTEGRATIONS_CHECK_FAILED: 'discovery_integrations_check_failed',
+    DISCOVERY_INTEGRATIONS_UNCITED: 'discovery_integrations_uncited',
+    DISCOVERY_MIGRATION_CHECK_FAILED: 'discovery_migration_check_failed',
+    DISCOVERY_MIGRATION_UNCITED: 'discovery_migration_uncited',
+    // discovery session output gate (improvement plan, Batch 5)
+    DISCOVERY_SESSION_CHECK_FAILED: 'discovery_session_check_failed',
+    DISCOVERY_DEVIATIONS_CHECK_FAILED: 'discovery_deviations_check_failed',
+    DISCOVERY_DEVIATIONS_UNAPPROVED: 'discovery_deviations_unapproved',
     // generic
     USAGE: 'usage',
     UNKNOWN: 'unknown',

package/pp-core/bin/lib/vault-standards-review.cjs

@@ -3,7 +3,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.REVIEW_FILES_CAP = exports.REVIEW_VERDICTS_HEADING = exports.REVIEW_ARTIFACT_MARKER = exports.REVIEW_ARTIFACT_SUFFIX = exports.REVIEW_VERDICTS = void 0;
+exports.DEVIATIONS_FILE = exports.REVIEW_FILES_CAP = exports.REVIEW_VERDICTS_HEADING = exports.REVIEW_ARTIFACT_MARKER = exports.REVIEW_ARTIFACT_SUFFIX = exports.REVIEW_VERDICTS = void 0;
+exports.readDeviations = readDeviations;
 exports.deriveStandardsReview = deriveStandardsReview;
 exports.formatReviewCounts = formatReviewCounts;
 exports.validateReviewArtifact = validateReviewArtifact;
@@ -59,6 +60,8 @@ exports.REVIEW_VERDICTS_HEADING = '## Standard Verdicts';
 exports.REVIEW_FILES_CAP = 200;
 /** Bound on a git query a review makes. */
 const REVIEW_GIT_TIMEOUT_MS = 30_000;
+/** Where the Discovery Sprint records agreed departures from the vault. */
+exports.DEVIATIONS_FILE = '.planning/discovery/_deviations.md';
 // ─── Derivation ──────────────────────────────────────────────────────────────
 const PLAN_RE = /(^|-)PLAN\.md$/;
 const SUMMARY_RE = /(^|-)SUMMARY\.md$/;
@@ -73,6 +76,47 @@ function readBounded(abs) {
         return null;
     }
 }
+/**
+ * The deviations on file, read by header name so Batch 3's full grammar can
+ * add or reorder columns without touching this reader. `gap` is set when the
+ * file exists but yields no readable table with both join columns.
+ */
+function readDeviations(root) {
+    const abs = node_path_1.default.join(root, exports.DEVIATIONS_FILE);
+    if (!node_fs_1.default.existsSync(abs))
+        return { deviations: [], gap: null };
+    const text = readBounded(abs);
+    if (text === null)
+        return { deviations: [], gap: `${exports.DEVIATIONS_FILE} could not be read (unreadable or over the size cap), so deviations on file are unknown` };
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const table = require('./discovery-table.cjs');
+    const deviations = [];
+    let joinable = false;
+    for (const section of table.splitSections(text.split(/\r?\n/), 2)) {
+        for (const tbl of table.parseTables(section.body)) {
+            const names = tbl.header.map((h) => h.trim().toLowerCase());
+            const col = (name) => names.indexOf(name);
+            const standard = col('standard');
+            const status = col('status');
+            if (standard === -1 || status === -1)
+                continue;
+            joinable = true;
+            const cell = (row, i) => (i === -1 ? '' : (row.cells[i] ?? '').trim());
+            for (const row of tbl.rows) {
+                deviations.push({
+                    id: cell(row, col('id')),
+                    standard: cell(row, standard),
+                    status: cell(row, status),
+                    decision: cell(row, col('decision')),
+                    approver: cell(row, col('approver')),
+                });
+            }
+        }
+    }
+    if (!joinable)
+        return { deviations: [], gap: `${exports.DEVIATIONS_FILE} carries no table with Standard and Status columns, so deviations on file are unknown` };
+    return { deviations, gap: null };
+}
 function consultedText(entry, hasSummary) {
     if (!hasSummary)
         return 'no summary';
@@ -206,6 +250,9 @@ function deriveStandardsReview(root, cwd, positional, opts = {}) {
             });
         }
     }
+    const onFile = readDeviations(root);
+    if (onFile.gap !== null)
+        gaps.push(onFile.gap);
     if (plans.length === 0 || documents.size === 0) {
         return {
             status: 'no-records',
@@ -216,9 +263,10 @@ function deriveStandardsReview(root, cwd, positional, opts = {}) {
             plans,
             documents: [],
             gaps,
+            deviations: onFile.deviations,
         };
     }
-    return { status: 'ok', phaseDir: phase.rel, plans, documents: [...documents.values()], gaps };
+    return { status: 'ok', phaseDir: phase.rel, plans, documents: [...documents.values()], gaps, deviations: onFile.deviations };
 }
 /** The counts line, in verdict order: `p PASS · f FAIL · n N-A · i INCONCLUSIVE (of N documents)`. */
 function formatReviewCounts(counts) {

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

@@ -2564,13 +2564,155 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
         } catch (vaultCheckErr) {
           error(`discovery vault-check: ${vaultCheckErr && vaultCheckErr.message ? vaultCheckErr.message : String(vaultCheckErr)}`, ERROR_REASON.UNKNOWN);
         }
+      } else if (subcommand === 'charter-check') {
+        // discovery charter-check [--require-signed]
+        //
+        // Structural check of docs/discovery/PROJECT-CHARTER.md: frontmatter
+        // enums, the twenty `<!-- charter:<key> -->` sections in order, every
+        // cited ID resolving to a session table or _requirements.md row, the
+        // Go / No-Go table equal to Session 13's, must-resolve open items
+        // closed or listed as conditions, sign-off rows agreeing with status.
+        // --require-signed also fails (discovery_charter_unsigned) unless the
+        // status is Signed or Signed with conditions — the handoff gate's arm.
+        const charter = require('./lib/discovery-charter.cjs');
+        try {
+          charter.cmdDiscoveryCharterCheck(cwd, args, raw);
+        } catch (charterCheckErr) {
+          error(`discovery charter-check: ${charterCheckErr && charterCheckErr.message ? charterCheckErr.message : String(charterCheckErr)}`, ERROR_REASON.UNKNOWN);
+        }
+      } else if (subcommand === 'entity-check') {
+        // discovery entity-check [--require-complete] — _entities.md structure
+        // (improvement plan, Batch 2): named entities, closed lifecycle and
+        // classification cells, attributes per entity, Mermaid cardinalities,
+        // step-matrix data objects resolving. --require-complete also fails on
+        // pending `—` cells (discovery_entity_check_incomplete).
+        const entities = require('./lib/discovery-entities.cjs');
+        try {
+          entities.cmdDiscoveryEntityCheck(cwd, args, raw);
+        } catch (entityCheckErr) {
+          error(`discovery entity-check: ${entityCheckErr && entityCheckErr.message ? entityCheckErr.message : String(entityCheckErr)}`, ERROR_REASON.UNKNOWN);
+        }
+      } else if (subcommand === 'process-check') {
+        // discovery process-check [--require-cited] — _processes.md structure:
+        // PRC-/MP- sequences, Replaces resolving, one swimlane and one step
+        // matrix per main process, actors, data objects, requirement IDs.
+        // --require-cited also fails on a step citing no requirement.
+        const processes = require('./lib/discovery-processes.cjs');
+        try {
+          processes.cmdDiscoveryProcessCheck(cwd, args, raw);
+        } catch (processCheckErr) {
+          error(`discovery process-check: ${processCheckErr && processCheckErr.message ? processCheckErr.message : String(processCheckErr)}`, ERROR_REASON.UNKNOWN);
+        }
+      } else if (subcommand === 'rules-check') {
+        // discovery rules-check — _rules.md structure: BR- sequence, layer
+        // vocabulary, every rule citing an existing requirement and an existing
+        // entity or process.
+        const rules = require('./lib/discovery-rules.cjs');
+        try {
+          rules.cmdDiscoveryRulesCheck(cwd, args, raw);
+        } catch (rulesCheckErr) {
+          error(`discovery rules-check: ${rulesCheckErr && rulesCheckErr.message ? rulesCheckErr.message : String(rulesCheckErr)}`, ERROR_REASON.UNKNOWN);
+        }
+      } else if (subcommand === 'stories-check') {
+        // discovery stories-check — _stories.md structure (improvement plan,
+        // Batch 4): US- sequence, EPIC shape, every story citing an existing
+        // requirement, source step resolving, every MVP domain requirement
+        // carrying at least one story.
+        const stories = require('./lib/discovery-stories.cjs');
+        try {
+          stories.cmdDiscoveryStoriesCheck(cwd, args, raw);
+        } catch (storiesCheckErr) {
+          error(`discovery stories-check: ${storiesCheckErr && storiesCheckErr.message ? storiesCheckErr.message : String(storiesCheckErr)}`, ERROR_REASON.UNKNOWN);
+        }
+      } else if (subcommand === 'phases-check') {
+        // discovery phases-check — _phases.md structure (improvement plan,
+        // Batch 4): contiguous phases, requirement IDs resolving and not
+        // dropped, dependencies on earlier phases, every MVP requirement in
+        // exactly one phase.
+        const phasesCheck = require('./lib/discovery-phases.cjs');
+        try {
+          phasesCheck.cmdDiscoveryPhasesCheck(cwd, args, raw);
+        } catch (phasesCheckErr) {
+          error(`discovery phases-check: ${phasesCheckErr && phasesCheckErr.message ? phasesCheckErr.message : String(phasesCheckErr)}`, ERROR_REASON.UNKNOWN);
+        }
+      } else if (subcommand === 'for-phase') {
+        // discovery for-phase <N> [--markdown | --conformance-template |
+        // --verify <file>] — the rows of every canonical artifact that cite
+        // the phase's requirement IDs as one extract between
+        // <!-- discovery:auto --> markers (improvement plan, Batch 4, R1);
+        // the verifier's conformance block and its check (R3). Fails loud on
+        // artifact structure only; no discovery package → exit 0, empty.
+        const forPhase = require('./lib/discovery-for-phase.cjs');
+        try {
+          forPhase.cmdDiscoveryForPhase(cwd, args, raw);
+        } catch (forPhaseErr) {
+          error(`discovery for-phase: ${forPhaseErr && forPhaseErr.message ? forPhaseErr.message : String(forPhaseErr)}`, ERROR_REASON.UNKNOWN);
+        }
+      } else if (subcommand === 'roles-check') {
+        // discovery roles-check — _roles.md structure (improvement plan,
+        // Batch 3): every role a persona, a step-matrix actor or System;
+        // permissions naming a known role, an existing entity, lowercase
+        // operations and at least one requirement; screen rows resolving.
+        const roles = require('./lib/discovery-access.cjs');
+        try {
+          roles.cmdDiscoveryRolesCheck(cwd, args, raw);
+        } catch (rolesCheckErr) {
+          error(`discovery roles-check: ${rolesCheckErr && rolesCheckErr.message ? rolesCheckErr.message : String(rolesCheckErr)}`, ERROR_REASON.UNKNOWN);
+        }
+      } else if (subcommand === 'integrations-check') {
+        // discovery integrations-check [--require-cited] — _integrations.md
+        // structure: IF- sequence, direction vocabulary, contract and error
+        // rows naming a known interface, step-matrix IF- tokens resolving.
+        // --require-cited also fails on an uncited interface and on a step
+        // naming a system without an IF- (discovery_integrations_uncited).
+        const integrations = require('./lib/discovery-integrations.cjs');
+        try {
+          integrations.cmdDiscoveryIntegrationsCheck(cwd, args, raw);
+        } catch (integrationsCheckErr) {
+          error(`discovery integrations-check: ${integrationsCheckErr && integrationsCheckErr.message ? integrationsCheckErr.message : String(integrationsCheckErr)}`, ERROR_REASON.UNKNOWN);
+        }
+      } else if (subcommand === 'migration-check') {
+        // discovery migration-check [--require-cited] — _migration.md
+        // structure: MG- sequence, source system in Session 2's landscape,
+        // entities resolving, requirement IDs resolving. --require-cited
+        // also fails on an uncited row (discovery_migration_uncited).
+        const migration = require('./lib/discovery-migration.cjs');
+        try {
+          migration.cmdDiscoveryMigrationCheck(cwd, args, raw);
+        } catch (migrationCheckErr) {
+          error(`discovery migration-check: ${migrationCheckErr && migrationCheckErr.message ? migrationCheckErr.message : String(migrationCheckErr)}`, ERROR_REASON.UNKNOWN);
+        }
+      } else if (subcommand === 'session-check') {
+        // discovery session-check <N> [<N>…] | --all — every Notes Template
+        // section of the session content file present exactly once in
+        // session-NN.md, each table with a data row or the literal
+        // `None identified in Discovery.`; --all covers the Completed sessions.
+        const sessionCheck = require('./lib/discovery-session-check.cjs');
+        try {
+          sessionCheck.cmdDiscoverySessionCheck(cwd, args, raw);
+        } catch (sessionCheckErr) {
+          error(`discovery session-check: ${sessionCheckErr && sessionCheckErr.message ? sessionCheckErr.message : String(sessionCheckErr)}`, ERROR_REASON.UNKNOWN);
+        }
+      } else if (subcommand === 'deviations-check') {
+        // discovery deviations-check [--require-approved] — _deviations.md
+        // structure: DEV- sequence, a [vault: path] standard present in the
+        // cache, reversible and status vocabularies, approver in Session 1's
+        // Approval Matrix, decision ID shape. --require-approved also fails
+        // on a hard-to-reverse deviation still Proposed
+        // (discovery_deviations_unapproved).
+        const deviations = require('./lib/discovery-deviations.cjs');
+        try {
+          deviations.cmdDiscoveryDeviationsCheck(cwd, args, raw);
+        } catch (deviationsCheckErr) {
+          error(`discovery deviations-check: ${deviationsCheckErr && deviationsCheckErr.message ? deviationsCheckErr.message : String(deviationsCheckErr)}`, 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', 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', ERROR_REASON.SDK_UNKNOWN_COMMAND);
       }
       break;
     }