@pareto4/pp-core 1.18.0 → 1.20.0

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

@@ -0,0 +1,216 @@
+"use strict";
+/**
+ * Discovery business-rules check (Discovery Sprint improvement plan, Batch 2).
+ *
+ * `.planning/discovery/_rules.md` is the register of business rules —
+ * validations, calculations, invariants — Session 3 Step 5D′ mints from the
+ * step matrices: `BR-nn`, the rule, what it applies to (an entity of
+ * `_entities.md` or a process of `_processes.md`), where it is checked
+ * (`UI`, `service`, `DB` — the vault's rule that a check has one owning
+ * layer), the requirements it realises, and its source. The build's planner
+ * and tests read it by requirement ID. This module checks the structure:
+ *
+ *   - the `## Rules` table exists with the template's columns;
+ *   - `BR-` IDs are well-formed, unique, contiguous;
+ *   - `Checked at` is a comma list from the closed layer vocabulary;
+ *   - every rule cites at least one requirement, each existing in
+ *     `_requirements.md` when it is on file and parseable;
+ *   - every `Applies to` token is an entity name that `_entities.md` has or a
+ *     `PRC-`/`MP-` ID that `_processes.md` has, when those artifacts are on
+ *     file (an absent artifact leaves the token shape-checked only).
+ *
+ * `_glossary.md` (`Term | Definition | Do not use | Source`) lives beside it
+ * and is deliberately not checked: a definition has no grammar.
+ *
+ * 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 RULES_FILE = `${DISCOVERY_DIR}/_rules.md`;
+const REQUIREMENTS_FILE = `${DISCOVERY_DIR}/_requirements.md`;
+const ENTITIES_FILE = `${DISCOVERY_DIR}/_entities.md`;
+const PROCESSES_FILE = `${DISCOVERY_DIR}/_processes.md`;
+const RULES_SECTION = 'Rules';
+const RULES_HEADER = Object.freeze(['ID', 'Rule', 'Applies to', 'Checked at', 'Requirements', 'Source']);
+const BR_RE = /^BR-(\d{2})$/;
+const LAYERS = Object.freeze(['UI', 'service', 'DB']);
+const ENTITY_NAME_RE = /^[A-Z][A-Za-z0-9]*$/;
+const PROCESS_ID_RE = /^(PRC|MP)-\d{2}$/;
+const REQUIREMENT_ID_RE = /^[A-Z][A-Z0-9]*-\d+$/;
+const USAGE = 'Usage: pp-tools discovery rules-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/names 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));
+}
+// ─── Check ────────────────────────────────────────────────────────────────────
+function checkRules(content, sources) {
+    const violations = [];
+    const sections = table.splitSections(content.split(/\r?\n/), 2);
+    const section = sections.find((s) => s.heading === RULES_SECTION);
+    if (!section) {
+        return { ok: false, rules: 0, violations: [{ artifact: RULES_FILE, reason: 'missing_section', id: RULES_SECTION }] };
+    }
+    const tables = table.parseTables(section.body);
+    if (tables.length === 0) {
+        return { ok: false, rules: 0, violations: [{ artifact: RULES_FILE, reason: 'missing_section', line: section.line, id: RULES_SECTION }] };
+    }
+    if (!sameHeader(tables[0].header, RULES_HEADER)) {
+        return { ok: false, rules: 0, violations: [{ artifact: RULES_FILE, reason: 'bad_table_shape', line: tables[0].line, id: RULES_SECTION }] };
+    }
+    const ids = new Set();
+    const seqs = [];
+    for (const row of tables[0].rows) {
+        const [id, rule, appliesTo, checkedAt, requirements] = row.cells.map((c) => c.trim());
+        const m = BR_RE.exec(id ?? '');
+        if (!m) {
+            violations.push({ artifact: RULES_FILE, reason: 'bad_id', line: row.line });
+        }
+        else if (ids.has(id)) {
+            violations.push({ artifact: RULES_FILE, reason: 'duplicate_id', line: row.line, id });
+        }
+        else {
+            ids.add(id);
+            seqs.push(Number(m[1]));
+        }
+        if ((rule ?? '') === '')
+            violations.push({ artifact: RULES_FILE, reason: 'empty_cell', line: row.line, id: 'Rule' });
+        const layers = splitList(checkedAt ?? '');
+        if (layers.length === 0 || layers.some((l) => !LAYERS.includes(l)))
+            violations.push({ artifact: RULES_FILE, reason: 'bad_checked_at', line: row.line });
+        const subjects = splitList(appliesTo ?? '');
+        if (subjects.length === 0)
+            violations.push({ artifact: RULES_FILE, reason: 'bad_subject', line: row.line });
+        for (const s of subjects) {
+            if (ENTITY_NAME_RE.test(s)) {
+                if (sources.entities !== null && !sources.entities.has(s))
+                    violations.push({ artifact: RULES_FILE, reason: 'unknown_subject', line: row.line, id: s });
+            }
+            else if (PROCESS_ID_RE.test(s)) {
+                if (sources.processes !== null && !sources.processes.has(s))
+                    violations.push({ artifact: RULES_FILE, reason: 'unknown_subject', line: row.line, id: s });
+            }
+            else {
+                violations.push({ artifact: RULES_FILE, reason: 'bad_subject', line: row.line });
+            }
+        }
+        const reqs = splitList(requirements ?? '');
+        if (reqs.length === 0)
+            violations.push({ artifact: RULES_FILE, reason: 'no_requirement', line: row.line });
+        for (const r of reqs) {
+            if (!REQUIREMENT_ID_RE.test(r))
+                violations.push({ artifact: RULES_FILE, reason: 'unknown_requirement_id', line: row.line, id: r.slice(0, 40) });
+            else if (sources.requirementIds instanceof Set && !sources.requirementIds.has(r))
+                violations.push({ artifact: RULES_FILE, reason: 'unknown_requirement_id', line: row.line, id: r });
+        }
+    }
+    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: RULES_FILE, reason: 'sequence_gap', id: `BR-${String(n).padStart(2, '0')}` });
+        }
+    }
+    if (sources.requirementIds === 'unparseable')
+        violations.push({ artifact: REQUIREMENTS_FILE, reason: 'requirements_unparseable' });
+    return { ok: violations.length === 0, rules: ids.size, violations };
+}
+function checkProjectRules(cwd) {
+    const read = readIfPresent(node_path_1.default.join(cwd, RULES_FILE));
+    if (read.kind === 'absent')
+        return null;
+    if (read.kind === 'unreadable')
+        return { ok: false, file: RULES_FILE, rules: 0, violations: [{ artifact: RULES_FILE, reason: 'artifact_unreadable' }] };
+    const extra = [];
+    const sources = { requirementIds: null, entities: null, processes: 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.requirementIds = parsed.ok ? new Set(parsed.rows.map((r) => r.id)) : 'unparseable';
+    }
+    const ent = readIfPresent(node_path_1.default.join(cwd, ENTITIES_FILE));
+    if (ent.kind === 'unreadable')
+        extra.push({ artifact: ENTITIES_FILE, reason: 'artifact_unreadable' });
+    if (ent.kind === 'ok')
+        sources.entities = firstColumnOf(ent.content, 'Entities');
+    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 = new Set([...firstColumnOf(proc.content, 'As-is'), ...firstColumnOf(proc.content, 'To-be')]);
+    const result = checkRules(read.content, sources);
+    result.violations.push(...extra);
+    result.ok = result.violations.length === 0;
+    return { file: RULES_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 rules-check` (dotted `query discovery.rules-check`). Absent artifact → exit 0, `present: false`. */
+function cmdDiscoveryRulesCheck(cwd, args, raw) {
+    if (args.length > 2) {
+        error(USAGE, ERROR_REASON.USAGE);
+        return; // unreachable
+    }
+    const result = checkProjectRules(cwd);
+    if (result === null) {
+        output({ ok: true, present: false, file: RULES_FILE }, raw);
+        return;
+    }
+    const payload = { ok: result.ok, present: true, file: result.file, rules: result.rules };
+    if (!result.ok) {
+        output({ ...payload, violations: result.violations.length }, raw);
+        error(`discovery rules-check: ${result.violations.length} violation(s):\n` + result.violations.map(formatViolation).join('\n'), ERROR_REASON.DISCOVERY_RULES_CHECK_FAILED);
+        return; // unreachable
+    }
+    output(payload, raw);
+}
+module.exports = {
+    RULES_FILE,
+    RULES_HEADER,
+    LAYERS,
+    RULES_CHECK_FAILED: ERROR_REASON.DISCOVERY_RULES_CHECK_FAILED,
+    checkRules,
+    checkProjectRules,
+    cmdDiscoveryRulesCheck,
+};

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

@@ -355,7 +355,7 @@ const VERDICTS = Object.freeze(['change', 'keep', 'drop', 'question']);
 const PROCESSING = Object.freeze({ OPEN: 'Open', NO_CHANGE: 'No change' });
 // D-57: the three citation shapes a Processing cell may take. Anchored,
 // quantifier-free, applied to a SINGLE already-split cell (T-04-13).
-const DECISION_CITE_RE = /^D-\d{2}-\d+$/;
+const DECISION_CITE_RE = /^D-(?:\d{2}|P\d{2})-\d+$/;
 // D-57: a data-gathering item in `_risks.md`.
 const DG_CITE_RE = /^DG-\d{2}$/;
 // D-57: a research-backlog item in `_research.md`.
@@ -1287,6 +1287,23 @@ const SCAN_SKIP_DIRS = Object.freeze(new Set([
     '.next', '.nuxt', '.turbo', '.cache', 'coverage',
     '.venv', 'venv', '__pycache__', 'vendor', 'target',
 ]));
+/**
+ * True when `dir` holds a pp-core install (`<dir>/pp-core/VERSION`, the marker
+ * `update-context` reads): a project-local runtime directory such as
+ * `.claude` or `.codex`. The walk never enters one. Its engine files, agents
+ * and commands spell the instrumentation literals out, and none of it ships
+ * in the engagement's build, so walking it reports pp-core itself as a leak
+ * (issue #12, item 7). Keyed on the marker rather than on directory names so
+ * every runtime's install directory is covered without a third list of them.
+ */
+function isPpCoreInstallDir(dir) {
+    try {
+        return node_fs_1.default.statSync(node_path_1.default.join(dir, 'pp-core', 'VERSION')).isFile();
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * The file extensions the scan actually READS. An allowlist rather than a
  * denylist, because the bound has to hold for file types nobody has thought of
@@ -1475,7 +1492,8 @@ function loadScanAllowlist(loaded) {
  *   - every entry is resolved and confirmed strictly beneath the resolved
  *     project root before any stat or read, the same posture the roll-up
  *     traversal guard takes (T-04-16);
- *   - `SCAN_SKIP_DIRS` keeps the walk out of the dependency tree;
+ *   - `SCAN_SKIP_DIRS` keeps the walk out of the dependency tree, and
+ *     `isPpCoreInstallDir` out of a project-local pp-core install;
  *   - `SCAN_EXTENSIONS` bounds what is read;
  *   - the file and byte caps stop the walk.
  *
@@ -1536,7 +1554,7 @@ function scanBuildTree(cwd, options = {}) {
             if (stat.isSymbolicLink())
                 continue;
             if (stat.isDirectory()) {
-                if (!SCAN_SKIP_DIRS.has(name))
+                if (!SCAN_SKIP_DIRS.has(name) && !isPpCoreInstallDir(full))
                     stack.push(full);
                 continue;
             }

package/pp-core/bin/lib/discovery-session-check.cjs

@@ -0,0 +1,264 @@
+"use strict";
+/**
+ * Discovery session output check (Discovery Sprint improvement plan, Batch 5).
+ *
+ * A session's Notes Template is the contract for what the session produces:
+ * every whole-line bold title under `**Notes Template:**` in
+ * `workflows/discovery-sprint/sessions/NN-*.md` names a section the session
+ * file `.planning/discovery/session-NN.md` must carry exactly once, and a
+ * section that is a table in the template must hold at least one data row
+ * (or say, on one line under its title, `None identified in Discovery.`).
+ * A prose section must hold at least one line of prose or that literal.
+ * The score formula in `discovery-sprint.md` Step 7 counts a section this
+ * check reports empty as not covered, so a session can no longer close at
+ * 100 with an empty Entity Register or an empty Roles table (review F-6).
+ *
+ * The template is read from the pp-core install itself (two directories up
+ * from the compiled engine), so the required-section list cannot drift from
+ * the session file the facilitator reads.
+ *
+ *   - `session-check <N>` checks one session whatever its status;
+ *   - `session-check --all` checks every `session-NN.md` on disk whose
+ *     frontmatter says `status: "Completed"` — Session 8's Closing Step and
+ *     the Session 13 gates run it over the sessions closed so far.
+ *
+ * Posture: reports at every session close, at Session 8 and at Session 13;
+ * hard-blocks at the handoff like the other artifact checks.
+ */
+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 SESSION_COUNT = 13;
+/** The literal a section carries when the session found nothing to record. */
+const NONE_LITERAL = 'None identified in Discovery.';
+/** A parked topic's marker (Flow 2 Step 5.3) — the section is accounted for, the score is not. */
+const PARKED_LITERAL = 'PARKED — needs business/senior input';
+const NOTES_TEMPLATE_MARKER = /^\*\*Notes Template:\*\*$/;
+const BOLD_TITLE_RE = /^\*\*([^*]+)\*\*$/;
+const HEADING_RE = /^#{1,6}\s/;
+const HEADING_TITLE_RE = /^#{1,6}\s+(.+?)\s*$/;
+const RULE_RE = /^---$/;
+const TABLE_ROW_RE = /^\|/;
+const HTML_COMMENT_RE = /^<!--.*-->$/;
+const COMPLETED_RE = /^status:\s*"?Completed"?\s*$/m;
+const SESSIONS_DIR = node_path_1.default.resolve(__dirname, '..', '..', 'workflows', 'discovery-sprint', 'sessions');
+const USAGE = 'Usage: pp-tools discovery session-check <N> [<N>…] | --all';
+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 pad(n) {
+    return String(n).padStart(2, '0');
+}
+function sessionFile(n) {
+    return `${DISCOVERY_DIR}/session-${pad(n)}.md`;
+}
+/** The session content file `NN-*.md` under the install's sessions directory, or null. */
+function templatePath(n, sessionsDir) {
+    let names;
+    try {
+        names = node_fs_1.default.readdirSync(sessionsDir);
+    }
+    catch {
+        return null;
+    }
+    const prefix = `${pad(n)}-`;
+    const found = names.find((f) => f.startsWith(prefix) && f.endsWith('.md'));
+    return found ? node_path_1.default.join(sessionsDir, found) : null;
+}
+/**
+ * Split a run of lines into titled sections. In the template (`stopAtHeading`)
+ * a title is a whole-line `**Title**` and the run ends at the first heading or
+ * rule. In a session file a facilitator writes the same titles either as
+ * `**Title**` or as a heading `## Title` (both are found in the field), so
+ * there every whole-line bold and every heading opens a section.
+ */
+function titledSections(lines, from, stopAtHeading) {
+    const out = [];
+    let current = null;
+    for (let i = from; i < lines.length; i += 1) {
+        const text = lines[i].trim();
+        if (stopAtHeading && (HEADING_RE.test(text) || RULE_RE.test(text)))
+            break;
+        const bold = BOLD_TITLE_RE.exec(text);
+        const heading = HEADING_TITLE_RE.exec(text);
+        const title = bold ? bold[1].trim() : heading ? heading[1].trim() : null;
+        if (title !== null) {
+            current = { title, line: i + 1, body: [] };
+            out.push(current);
+            continue;
+        }
+        if (current)
+            current.body.push({ n: i + 1, text: lines[i] });
+    }
+    return out;
+}
+/** The required sections of a session content file, in template order; null without a Notes Template. */
+function requiredSectionsOf(templateContent) {
+    const lines = templateContent.split(/\r?\n/);
+    const at = lines.findIndex((l) => NOTES_TEMPLATE_MARKER.test(l.trim()));
+    if (at === -1)
+        return null;
+    return titledSections(lines, at + 1, true).map((s) => {
+        const tables = table.parseTables(s.body);
+        return tables.length > 0
+            ? { title: s.title, kind: 'table', header: tables[0].header.map((c) => c.trim()) }
+            : { title: s.title, kind: 'prose', header: null };
+    });
+}
+/** A table body row holds data when at least two cells are filled (one, for a one-column table). */
+function isDataRow(cells) {
+    const filled = cells.filter((c) => c.trim() !== '').length;
+    return cells.length <= 1 ? filled >= 1 : filled >= 2;
+}
+function hasLiteral(body) {
+    return body.some((l) => {
+        const t = l.text.trim();
+        if (t === NONE_LITERAL || t === PARKED_LITERAL || t.startsWith(`${PARKED_LITERAL}`))
+            return true;
+        return TABLE_ROW_RE.test(t) && table.splitTableCells(t).some((c) => c.trim() === NONE_LITERAL);
+    });
+}
+function hasProse(body) {
+    return body.some((l) => {
+        const t = l.text.trim();
+        return t !== '' && !TABLE_ROW_RE.test(t) && !HTML_COMMENT_RE.test(t);
+    });
+}
+// ─── Check ────────────────────────────────────────────────────────────────────
+function checkSession(n, sessionContent, required) {
+    const file = sessionFile(n);
+    const violations = [];
+    const empty = [];
+    const sections = titledSections(sessionContent.split(/\r?\n/), 0, false);
+    let filled = 0;
+    for (const req of required) {
+        const found = sections.filter((s) => s.title === req.title);
+        if (found.length === 0) {
+            violations.push({ artifact: file, reason: 'missing_section', id: req.title });
+            continue;
+        }
+        if (found.length > 1) {
+            violations.push({ artifact: file, reason: 'duplicate_section', line: found[1].line, id: req.title });
+            continue;
+        }
+        const s = found[0];
+        if (hasLiteral(s.body)) {
+            filled += 1;
+            continue;
+        }
+        if (req.kind === 'table') {
+            const tables = table.parseTables(s.body);
+            if (tables.length === 0 || tables[0].header.length !== (req.header ?? []).length) {
+                violations.push({ artifact: file, reason: 'bad_table_shape', line: tables.length > 0 ? tables[0].line : s.line, id: req.title });
+                continue;
+            }
+            if (tables[0].rows.some((r) => isDataRow(r.cells)))
+                filled += 1;
+            else {
+                empty.push(req.title);
+                violations.push({ artifact: file, reason: 'empty_section', line: s.line, id: req.title });
+            }
+        }
+        else if (hasProse(s.body) || table.parseTables(s.body).some((t) => t.rows.some((r) => isDataRow(r.cells))))
+            filled += 1;
+        else {
+            empty.push(req.title);
+            violations.push({ artifact: file, reason: 'empty_section', line: s.line, id: req.title });
+        }
+    }
+    return { required: required.length, filled, empty, violations };
+}
+function checkProjectSession(cwd, n, sessionsDir = SESSIONS_DIR) {
+    const file = sessionFile(n);
+    const base = { session: n, file, required: 0, filled: 0, empty: [] };
+    const tpl = templatePath(n, sessionsDir);
+    const tplRead = tpl ? readIfPresent(tpl) : { kind: 'absent' };
+    const required = tplRead.kind === 'ok' ? requiredSectionsOf(tplRead.content) : null;
+    if (required === null)
+        return { ...base, violations: [{ artifact: `sessions/${pad(n)}-*.md`, reason: 'template_missing', id: `session ${n}` }] };
+    const read = readIfPresent(node_path_1.default.join(cwd, file));
+    if (read.kind === 'absent')
+        return { ...base, required: required.length, violations: [{ artifact: file, reason: 'session_missing' }] };
+    if (read.kind === 'unreadable')
+        return { ...base, required: required.length, violations: [{ artifact: file, reason: 'artifact_unreadable' }] };
+    return { session: n, file, ...checkSession(n, read.content, required) };
+}
+/** The sessions `--all` covers: every session file on disk whose frontmatter says Completed. */
+function completedSessions(cwd) {
+    const out = [];
+    for (let n = 1; n <= SESSION_COUNT; n += 1) {
+        const read = readIfPresent(node_path_1.default.join(cwd, sessionFile(n)));
+        if (read.kind === 'ok' && COMPLETED_RE.test(read.content.slice(0, 2000)))
+            out.push(n);
+    }
+    return out;
+}
+function checkProjectSessions(cwd, numbers, sessionsDir = SESSIONS_DIR) {
+    const sessions = numbers.map((n) => checkProjectSession(cwd, n, sessionsDir));
+    return { ok: sessions.every((s) => s.violations.length === 0), sessions };
+}
+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 session-check <N> [<N>…] | --all` (dotted
+ * `query discovery.session-check`). Faults exit via
+ * `DISCOVERY_SESSION_CHECK_FAILED`; `--all` over a project with no completed
+ * session exits 0 with `sessions: []`.
+ */
+function cmdDiscoverySessionCheck(cwd, args, raw) {
+    const rest = args.slice(2);
+    let numbers;
+    if (rest.length === 1 && rest[0] === '--all')
+        numbers = completedSessions(cwd);
+    else {
+        if (rest.length === 0 || rest.some((a) => !/^(?:[1-9]|1[0-3])$/.test(a))) {
+            error(USAGE, ERROR_REASON.USAGE);
+            return; // unreachable
+        }
+        numbers = [...new Set(rest.map(Number))];
+    }
+    const result = checkProjectSessions(cwd, numbers);
+    const payload = {
+        ok: result.ok,
+        sessions: result.sessions.map((s) => ({ session: s.session, file: s.file, required: s.required, filled: s.filled, empty: s.empty })),
+    };
+    if (!result.ok) {
+        const violations = result.sessions.flatMap((s) => s.violations);
+        output({ ...payload, violations: violations.length }, raw);
+        error(`discovery session-check: ${violations.length} violation(s):\n` + violations.map(formatViolation).join('\n'), ERROR_REASON.DISCOVERY_SESSION_CHECK_FAILED);
+        return; // unreachable
+    }
+    output(payload, raw);
+}
+module.exports = {
+    NONE_LITERAL,
+    PARKED_LITERAL,
+    SESSIONS_DIR,
+    SESSION_CHECK_FAILED: ERROR_REASON.DISCOVERY_SESSION_CHECK_FAILED,
+    requiredSectionsOf,
+    checkSession,
+    checkProjectSession,
+    checkProjectSessions,
+    completedSessions,
+    cmdDiscoverySessionCheck,
+};