@pareto4/pp-core 1.18.0 → 1.20.0

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

@@ -0,0 +1,264 @@
+"use strict";
+/**
+ * Discovery deviations check (Discovery Sprint improvement plan, Batch 3).
+ *
+ * `.planning/discovery/_deviations.md` is the register of agreed departures
+ * from the client's standards: `DEV-nn`, the vault standard deviated from
+ * (`[vault: <path>]`), the choice made instead, the reason, whether the choice
+ * is easy or hard to reverse (the vault's own distinction — a hard one blocks
+ * the affected work until an architect signs), who approves it, the decision
+ * that recorded it and its status. Sessions 1 and 4–10 write it as their
+ * Standards Applied rows surface a deviation; the charter § 7 copies it; the
+ * vault reviewer reads it so an approved deviation is reported as "deviation
+ * on file" and never as a violation. This module checks the structure:
+ *
+ *   - the `## Deviations` table exists with the template's columns;
+ *   - `DEV-` IDs are well-formed, unique, contiguous;
+ *   - `Standard` cites at least one `[vault: <path>]`, each path safe and,
+ *     when the vault cache is on disk, present in it;
+ *   - `Reversible` and `Status` come from their closed vocabularies;
+ *   - `Approver` is one the Session 1 Approval Matrix names, when that table
+ *     is on file with rows;
+ *   - `Decision` is `—` or a decision ID, and an `Approved` or `Rejected` row
+ *     carries one;
+ *   - `--require-approved`: a hard-to-reverse deviation that is still
+ *     `Proposed` fails on its own exit identity, so `/pp-discovery-to-build`
+ *     can hard-block on it while Sessions 8 and 13 only report.
+ *
+ * Posture (D-43/D-53): reports at Sessions 8 and 13; hard-blocks at the
+ * handoff. 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");
+// The vault-index leaf owns the vault path rule (14-03 anti-drift: one owner in src/).
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const vaultIndex = require("./vault-index.cjs");
+// ─── Constants ────────────────────────────────────────────────────────────────
+const DISCOVERY_DIR = '.planning/discovery';
+const DEVIATIONS_FILE = `${DISCOVERY_DIR}/_deviations.md`;
+const SESSION_01_FILE = `${DISCOVERY_DIR}/session-01.md`;
+const DEVIATIONS_SECTION = 'Deviations';
+const DEVIATIONS_HEADER = Object.freeze(['ID', 'Standard', 'Choice', 'Reason', 'Reversible', 'Approver', 'Decision', 'Status']);
+const DEV_RE = /^DEV-(\d{2})$/;
+const REVERSIBLE = Object.freeze(['easy', 'hard']);
+const STATUSES = Object.freeze(['Proposed', 'Approved', 'Rejected', 'Superseded']);
+const DECIDED_STATUSES = Object.freeze(['Approved', 'Rejected']);
+const DECISION_ID_RE = /^D-(\d{2}|P\d{2})-\d+$/;
+const VAULT_CITE_RE = /\[vault:\s*([^\]]+?)\s*\]/g;
+const PENDING = '—';
+const APPROVAL_MATRIX_LABEL = 'Approval Matrix';
+const APPROVER_COLUMN = 'Approver';
+const USAGE = 'Usage: pp-tools discovery deviations-check [--require-approved]';
+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);
+}
+/**
+ * A vault path a deviation may cite: the vault index leaf's path rule (relative,
+ * no traversal, no dot or empty segment, display-safe) plus the sessions' own
+ * `.md` requirement (`workflows/discovery-sprint/sessions/04-ux-design.md`).
+ */
+function isSafeStandardPath(p) {
+    return vaultIndex.isSafeVaultPath(p) && p.endsWith('.md');
+}
+/** The Approver tokens of Session 1's Approval Matrix, by header name; null when absent or empty. */
+function approversFrom(content) {
+    const lines = content.split(/\r?\n/);
+    const norm = (s) => s.replace(/^#+\s*/, '').replace(/\*\*/g, '').trim();
+    const at = lines.findIndex((l) => norm(l) === APPROVAL_MATRIX_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;
+    const col = tables[0].header.findIndex((h) => h.trim().toLowerCase() === APPROVER_COLUMN.toLowerCase());
+    if (col === -1)
+        return null;
+    const out = new Set();
+    for (const r of tables[0].rows)
+        for (const t of splitList(r.cells[col] ?? ''))
+            out.add(t);
+    return out.size === 0 ? null : out;
+}
+/** The vault cache directory on disk, through the vault's own resolver when it loads; null when there is no cache. */
+function vaultCacheDirOf(cwd) {
+    let dir = node_path_1.default.join(cwd, '.planning', 'vault');
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const vault = require('./vault.cjs');
+        if (typeof vault.resolveVaultCacheDir === 'function')
+            dir = vault.resolveVaultCacheDir(cwd).dir;
+    }
+    catch {
+        /* the local cache path stands */
+    }
+    try {
+        return node_fs_1.default.statSync(dir).isDirectory() ? dir : null;
+    }
+    catch {
+        return null;
+    }
+}
+// ─── Check ────────────────────────────────────────────────────────────────────
+function checkDeviations(content, sources, requireApproved = false) {
+    const violations = [];
+    const empty = { deviations: 0, approved: 0, unapproved_hard: 0 };
+    const section = table.splitSections(content.split(/\r?\n/), 2).find((s) => s.heading === DEVIATIONS_SECTION);
+    if (!section)
+        return { ok: false, ...empty, violations: [{ artifact: DEVIATIONS_FILE, reason: 'missing_section', id: DEVIATIONS_SECTION }] };
+    const tables = table.parseTables(section.body);
+    if (tables.length === 0)
+        return { ok: false, ...empty, violations: [{ artifact: DEVIATIONS_FILE, reason: 'missing_section', line: section.line, id: DEVIATIONS_SECTION }] };
+    if (!sameHeader(tables[0].header, DEVIATIONS_HEADER)) {
+        return { ok: false, ...empty, violations: [{ artifact: DEVIATIONS_FILE, reason: 'bad_table_shape', line: tables[0].line, id: DEVIATIONS_SECTION }] };
+    }
+    const ids = new Set();
+    const seqs = [];
+    let approved = 0;
+    let unapprovedHard = 0;
+    for (const row of tables[0].rows) {
+        const [id, standard, choice, reason, reversible, approver, decision, status] = row.cells.map((c) => c.trim());
+        const line = row.line;
+        const m = DEV_RE.exec(id ?? '');
+        if (!m)
+            violations.push({ artifact: DEVIATIONS_FILE, reason: 'bad_id', line });
+        else if (ids.has(id))
+            violations.push({ artifact: DEVIATIONS_FILE, reason: 'duplicate_id', line, id });
+        else {
+            ids.add(id);
+            seqs.push(Number(m[1]));
+        }
+        const cites = [...(standard ?? '').matchAll(VAULT_CITE_RE)].map((c) => c[1]);
+        if (cites.length === 0)
+            violations.push({ artifact: DEVIATIONS_FILE, reason: 'bad_standard', line });
+        for (const p of cites) {
+            if (!isSafeStandardPath(p))
+                violations.push({ artifact: DEVIATIONS_FILE, reason: 'bad_standard', line, id: p.slice(0, 80) });
+            else if (sources.vaultCacheDir !== null && !node_fs_1.default.existsSync(node_path_1.default.join(sources.vaultCacheDir, p)))
+                violations.push({ artifact: DEVIATIONS_FILE, reason: 'unknown_standard', line, id: p });
+        }
+        if ((choice ?? '') === '')
+            violations.push({ artifact: DEVIATIONS_FILE, reason: 'empty_cell', line, id: 'Choice' });
+        if ((reason ?? '') === '')
+            violations.push({ artifact: DEVIATIONS_FILE, reason: 'empty_cell', line, id: 'Reason' });
+        const rev = reversible ?? '';
+        if (!REVERSIBLE.includes(rev))
+            violations.push({ artifact: DEVIATIONS_FILE, reason: 'bad_reversible', line });
+        if ((approver ?? '') === '')
+            violations.push({ artifact: DEVIATIONS_FILE, reason: 'empty_cell', line, id: 'Approver' });
+        else if (sources.approvers !== null && !sources.approvers.has(approver))
+            violations.push({ artifact: DEVIATIONS_FILE, reason: 'unknown_approver', line });
+        const dec = decision ?? '';
+        const st = status ?? '';
+        if (dec !== PENDING && !DECISION_ID_RE.test(dec))
+            violations.push({ artifact: DEVIATIONS_FILE, reason: 'bad_decision', line });
+        if (!STATUSES.includes(st))
+            violations.push({ artifact: DEVIATIONS_FILE, reason: 'bad_status', line });
+        else {
+            if (DECIDED_STATUSES.includes(st) && dec === PENDING)
+                violations.push({ artifact: DEVIATIONS_FILE, reason: 'decision_missing', line, id: m ? id : undefined });
+            if (st === 'Approved')
+                approved += 1;
+            if (st === 'Proposed' && rev === 'hard') {
+                unapprovedHard += 1;
+                if (requireApproved)
+                    violations.push({ artifact: DEVIATIONS_FILE, reason: 'hard_deviation_unapproved', line, id: m ? id : undefined });
+            }
+        }
+    }
+    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: DEVIATIONS_FILE, reason: 'sequence_gap', id: `DEV-${String(n).padStart(2, '0')}` });
+        }
+    }
+    return { ok: violations.length === 0, deviations: ids.size, approved, unapproved_hard: unapprovedHard, violations };
+}
+function checkProjectDeviations(cwd, requireApproved = false) {
+    const read = readIfPresent(node_path_1.default.join(cwd, DEVIATIONS_FILE));
+    if (read.kind === 'absent')
+        return null;
+    if (read.kind === 'unreadable') {
+        return { ok: false, file: DEVIATIONS_FILE, deviations: 0, approved: 0, unapproved_hard: 0, violations: [{ artifact: DEVIATIONS_FILE, reason: 'artifact_unreadable' }] };
+    }
+    const extra = [];
+    const sources = { approvers: null, vaultCacheDir: vaultCacheDirOf(cwd) };
+    const s1 = readIfPresent(node_path_1.default.join(cwd, SESSION_01_FILE));
+    if (s1.kind === 'unreadable')
+        extra.push({ artifact: SESSION_01_FILE, reason: 'artifact_unreadable' });
+    if (s1.kind === 'ok')
+        sources.approvers = approversFrom(s1.content);
+    const result = checkDeviations(read.content, sources, requireApproved);
+    result.violations.push(...extra);
+    result.ok = result.violations.length === 0;
+    return { file: DEVIATIONS_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 deviations-check [--require-approved]` (dotted `query discovery.deviations-check`). Absent artifact → exit 0, `present: false`. */
+function cmdDiscoveryDeviationsCheck(cwd, args, raw) {
+    const rest = args.slice(2);
+    const requireApproved = rest.includes('--require-approved');
+    if (rest.some((a) => a !== '--require-approved')) {
+        error(USAGE, ERROR_REASON.USAGE);
+        return; // unreachable
+    }
+    const result = checkProjectDeviations(cwd, requireApproved);
+    if (result === null) {
+        output({ ok: true, present: false, file: DEVIATIONS_FILE }, raw);
+        return;
+    }
+    const payload = { ok: result.ok, present: true, file: result.file, deviations: result.deviations, approved: result.approved, unapproved_hard: result.unapproved_hard };
+    if (!result.ok) {
+        const onlyUnapproved = result.violations.every((v) => v.reason === 'hard_deviation_unapproved');
+        output({ ...payload, violations: result.violations.length }, raw);
+        error(`discovery deviations-check: ${result.violations.length} violation(s):\n` + result.violations.map(formatViolation).join('\n'), onlyUnapproved ? ERROR_REASON.DISCOVERY_DEVIATIONS_UNAPPROVED : ERROR_REASON.DISCOVERY_DEVIATIONS_CHECK_FAILED);
+        return; // unreachable
+    }
+    output(payload, raw);
+}
+module.exports = {
+    DEVIATIONS_FILE,
+    DEVIATIONS_HEADER,
+    REVERSIBLE,
+    STATUSES,
+    DEVIATIONS_CHECK_FAILED: ERROR_REASON.DISCOVERY_DEVIATIONS_CHECK_FAILED,
+    DEVIATIONS_UNAPPROVED: ERROR_REASON.DISCOVERY_DEVIATIONS_UNAPPROVED,
+    isSafeStandardPath,
+    approversFrom,
+    checkDeviations,
+    checkProjectDeviations,
+    cmdDiscoveryDeviationsCheck,
+};

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

@@ -0,0 +1,323 @@
+"use strict";
+/**
+ * Discovery data-model check (Discovery Sprint improvement plan, Batch 2).
+ *
+ * `.planning/discovery/_entities.md` is the one data model a build starts
+ * from: every entity by name (entities are named, never numbered — Batch 2
+ * decision), its identifier, whether it has a status lifecycle, its
+ * classification in the vault's four levels, its retention, its owner module
+ * and its source; one attribute table per entity; relationships with Mermaid
+ * cardinality; lifecycle states and transitions. Session 2 seeds it from the
+ * Data Entity Map, Session 3's step matrices name the objects each step
+ * touches, Session 5 consolidates it, Session 6 writes classification and
+ * retention. This module checks the structure — never the judgement:
+ *
+ *   - the four sections exist, each table has the template's columns;
+ *   - entity names are PascalCase tokens, unique; `Status lifecycle` and
+ *     `Classification` are inside their closed vocabularies;
+ *   - every attribute heading, relationship end and lifecycle row names an
+ *     entity the `## Entities` table has; `Required` is `yes` or `no`;
+ *   - every cardinality is a Mermaid `erDiagram` cardinality, so the ERD the
+ *     handoff draws needs no default;
+ *   - a lifecycle flag of `yes` has states, and states have a flag;
+ *   - every data object a step matrix in `_processes.md` touches (`Task [C]`)
+ *     is an entity;
+ *   - with `--require-complete`: no `—` is left in Identifier, Status
+ *     lifecycle, Classification or Retention, and every entity has at least
+ *     one attribute. Before Session 5 those cells are allowed to be pending.
+ *
+ * Posture (D-43/D-53): the check reports at Sessions 8 and 13 and hard-blocks
+ * at `/pp-discovery-to-build`, where `--require-complete` is added. Absent
+ * artifact → exit 0 (an engagement that predates the data model).
+ *
+ * Content-free contract: output names the artifact, line numbers, entity
+ * names (validated tokens), section keys and reason codes — never cell prose.
+ * No positional path: convention paths resolve against the working directory.
+ */
+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 ENTITIES_FILE = `${DISCOVERY_DIR}/_entities.md`;
+const PROCESSES_FILE = `${DISCOVERY_DIR}/_processes.md`;
+const SECTIONS = Object.freeze({ entities: 'Entities', attributes: 'Attributes', relationships: 'Relationships', lifecycles: 'Lifecycles' });
+const ENTITIES_HEADER = Object.freeze(['Entity', 'Identifier', 'Status lifecycle', 'Classification', 'Retention', 'Owner module', 'Source']);
+const ATTRIBUTES_HEADER = Object.freeze(['Attribute', 'Type', 'Required', 'Bounds', 'Notes']);
+const RELATIONSHIPS_HEADER = Object.freeze(['From', 'Cardinality', 'To', 'Name']);
+const LIFECYCLES_HEADER = Object.freeze(['Entity', 'State', 'Transition', 'Allowed by']);
+/** Entities are named, never numbered: one PascalCase token, cited exactly. */
+const ENTITY_NAME_RE = /^[A-Z][A-Za-z0-9]*$/;
+const PENDING = '—';
+const LIFECYCLE_VALUES = Object.freeze(['none', 'yes', PENDING]);
+/** The vault's four levels (`security/compliance.md` § Information handling). */
+const CLASSIFICATION_LEVELS = Object.freeze(['Public', 'Internal', 'Confidential', 'Restricted']);
+const REQUIRED_VALUES = Object.freeze(['yes', 'no', PENDING]);
+/** Mermaid `erDiagram` cardinality: a left end, an identifying (`--`) or non-identifying (`..`) line, a right end. */
+const CARDINALITY_RE = /^(\|\||\|o|\}o|\}\|)(--|\.\.)(\|\||o\||o\{|\|\{)$/;
+/** A step-matrix data object: `Task [C]`, `Membership [C/R/U]`. */
+const DATA_OBJECT_RE = /^([A-Z][A-Za-z0-9]*) \[([CRUD](?:\/[CRUD])*)\]$/;
+const STEPS_DATA_OBJECTS_COLUMN = 'Data objects';
+const USAGE = 'Usage: pp-tools discovery entity-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());
+}
+/** The first table of a `##` section, with its header verified; null when the section or table is absent. */
+function sectionTable(sections, heading, expected, violations) {
+    const section = sections.find((s) => s.heading === heading);
+    if (!section) {
+        violations.push({ artifact: ENTITIES_FILE, reason: 'missing_section', id: heading });
+        return null;
+    }
+    const tables = table.parseTables(section.body);
+    if (tables.length === 0) {
+        violations.push({ artifact: ENTITIES_FILE, reason: 'missing_section', line: section.line, id: heading });
+        return null;
+    }
+    if (!sameHeader(tables[0].header, expected)) {
+        violations.push({ artifact: ENTITIES_FILE, reason: 'bad_table_shape', line: tables[0].line, id: heading });
+        return null;
+    }
+    return tables[0];
+}
+// ─── Check ────────────────────────────────────────────────────────────────────
+/** Check `_entities.md` text; `stepObjects` are the `Data objects` cells of `_processes.md` step tables. */
+function checkEntities(content, stepObjects = [], requireComplete = false) {
+    const violations = [];
+    const lines = content.split(/\r?\n/);
+    const sections = table.splitSections(lines, 2);
+    // 1 ─ Entities
+    const entities = new Map();
+    const entitiesTable = sectionTable(sections, SECTIONS.entities, ENTITIES_HEADER, violations);
+    if (entitiesTable) {
+        for (const row of entitiesTable.rows) {
+            const [name, identifier, lifecycle, classification, retention] = row.cells.map((c) => c.trim());
+            if (!ENTITY_NAME_RE.test(name ?? '')) {
+                violations.push({ artifact: ENTITIES_FILE, reason: 'bad_entity_name', line: row.line });
+                continue;
+            }
+            if (entities.has(name)) {
+                violations.push({ artifact: ENTITIES_FILE, reason: 'duplicate_entity', line: row.line, id: name });
+                continue;
+            }
+            if (!LIFECYCLE_VALUES.includes(lifecycle ?? ''))
+                violations.push({ artifact: ENTITIES_FILE, reason: 'bad_lifecycle_flag', line: row.line, id: name });
+            if ((classification ?? '') !== PENDING && !CLASSIFICATION_LEVELS.includes(classification ?? '')) {
+                violations.push({ artifact: ENTITIES_FILE, reason: 'bad_classification', line: row.line, id: name });
+            }
+            for (const [col, value] of [['Identifier', identifier], ['Retention', retention]]) {
+                if ((value ?? '') === '')
+                    violations.push({ artifact: ENTITIES_FILE, reason: 'empty_cell', line: row.line, id: `${name} · ${col}` });
+            }
+            if (requireComplete) {
+                for (const [col, value] of [['Identifier', identifier], ['Status lifecycle', lifecycle], ['Classification', classification], ['Retention', retention]]) {
+                    if ((value ?? '') === PENDING)
+                        violations.push({ artifact: ENTITIES_FILE, reason: 'incomplete_cell', line: row.line, id: `${name} · ${col}` });
+                }
+            }
+            entities.set(name, { name, line: row.line, identifier: identifier ?? '', lifecycle: lifecycle ?? '', classification: classification ?? '', retention: retention ?? '' });
+        }
+    }
+    // 2 ─ Attributes: one `### <Entity>` table each
+    let attributes = 0;
+    const withAttributes = new Set();
+    const attributesSection = sections.find((s) => s.heading === SECTIONS.attributes);
+    if (!attributesSection) {
+        violations.push({ artifact: ENTITIES_FILE, reason: 'missing_section', id: SECTIONS.attributes });
+    }
+    else {
+        const sub = table.splitSections(attributesSection.body.map((l) => l.text), 3);
+        for (const s of sub) {
+            const name = s.heading.trim();
+            const line = attributesSection.body[s.line - 1]?.n ?? attributesSection.line;
+            if (!entities.has(name)) {
+                violations.push({ artifact: ENTITIES_FILE, reason: 'unknown_entity', line, id: name.slice(0, 60) });
+                continue;
+            }
+            const tables = table.parseTables(s.body.map((l, i) => ({ n: attributesSection.body[s.line + i]?.n ?? line, text: l.text })));
+            if (tables.length === 0 || !sameHeader(tables[0].header, ATTRIBUTES_HEADER)) {
+                violations.push({ artifact: ENTITIES_FILE, reason: 'bad_table_shape', line, id: `${SECTIONS.attributes} · ${name}` });
+                continue;
+            }
+            if (tables[0].rows.length > 0)
+                withAttributes.add(name);
+            for (const row of tables[0].rows) {
+                attributes += 1;
+                if ((row.cells[0] ?? '').trim() === '' || (row.cells[1] ?? '').trim() === '') {
+                    violations.push({ artifact: ENTITIES_FILE, reason: 'empty_cell', line: row.line, id: `${name} · Attribute` });
+                }
+                if (!REQUIRED_VALUES.includes((row.cells[2] ?? '').trim()))
+                    violations.push({ artifact: ENTITIES_FILE, reason: 'bad_required', line: row.line, id: name });
+                if (requireComplete) {
+                    for (const [col, idx] of [['Type', 1], ['Required', 2]]) {
+                        if ((row.cells[idx] ?? '').trim() === PENDING)
+                            violations.push({ artifact: ENTITIES_FILE, reason: 'incomplete_cell', line: row.line, id: `${name} · ${(row.cells[0] ?? '').trim()} · ${col}` });
+                    }
+                }
+            }
+        }
+    }
+    if (requireComplete) {
+        for (const e of entities.values()) {
+            if (!withAttributes.has(e.name))
+                violations.push({ artifact: ENTITIES_FILE, reason: 'attributes_missing', line: e.line, id: e.name });
+        }
+    }
+    // 3 ─ Relationships
+    let relationships = 0;
+    const relTable = sectionTable(sections, SECTIONS.relationships, RELATIONSHIPS_HEADER, violations);
+    if (relTable) {
+        for (const row of relTable.rows) {
+            relationships += 1;
+            const [from, cardinality, to] = row.cells.map((c) => c.trim());
+            for (const end of [from, to]) {
+                if (!entities.has(end ?? ''))
+                    violations.push({ artifact: ENTITIES_FILE, reason: 'unknown_entity', line: row.line, id: (end ?? '').slice(0, 60) });
+            }
+            if (!CARDINALITY_RE.test(cardinality ?? ''))
+                violations.push({ artifact: ENTITIES_FILE, reason: 'bad_cardinality', line: row.line });
+        }
+    }
+    // 4 ─ Lifecycles
+    let lifecycles = 0;
+    const withStates = new Set();
+    const lifeTable = sectionTable(sections, SECTIONS.lifecycles, LIFECYCLES_HEADER, violations);
+    if (lifeTable) {
+        for (const row of lifeTable.rows) {
+            lifecycles += 1;
+            const name = (row.cells[0] ?? '').trim();
+            if (!entities.has(name)) {
+                violations.push({ artifact: ENTITIES_FILE, reason: 'unknown_entity', line: row.line, id: name.slice(0, 60) });
+                continue;
+            }
+            withStates.add(name);
+            if ((row.cells[1] ?? '').trim() === '')
+                violations.push({ artifact: ENTITIES_FILE, reason: 'empty_cell', line: row.line, id: `${name} · State` });
+        }
+    }
+    for (const e of entities.values()) {
+        if (e.lifecycle === 'yes' && !withStates.has(e.name))
+            violations.push({ artifact: ENTITIES_FILE, reason: 'lifecycle_without_states', line: e.line, id: e.name });
+        if (e.lifecycle === 'none' && withStates.has(e.name))
+            violations.push({ artifact: ENTITIES_FILE, reason: 'states_without_lifecycle', line: e.line, id: e.name });
+    }
+    // 5 ─ Every data object a step touches is an entity
+    let stepObjectsChecked = 0;
+    for (const { line, cell } of stepObjects) {
+        if (cell.trim() === PENDING || cell.trim() === '')
+            continue;
+        for (const token of cell.split(',').map((t) => t.trim()).filter(Boolean)) {
+            const m = DATA_OBJECT_RE.exec(token);
+            if (!m)
+                continue; // a malformed token is process-check's fault to report
+            stepObjectsChecked += 1;
+            if (!entities.has(m[1]))
+                violations.push({ artifact: PROCESSES_FILE, reason: 'unknown_entity', line, id: m[1] });
+        }
+    }
+    return { ok: violations.length === 0, entities: entities.size, attributes, relationships, lifecycles, step_objects_checked: stepObjectsChecked, violations };
+}
+/** The `Data objects` cells of every step table in `_processes.md` § Steps. */
+function stepDataObjects(content) {
+    const lines = content.split(/\r?\n/);
+    const steps = table.splitSections(lines, 2).find((s) => s.heading === 'Steps');
+    if (!steps)
+        return [];
+    const out = [];
+    for (const t of table.parseTables(steps.body)) {
+        const col = t.header.findIndex((h) => h.trim().toLowerCase() === STEPS_DATA_OBJECTS_COLUMN.toLowerCase());
+        if (col === -1)
+            continue;
+        for (const row of t.rows)
+            out.push({ line: row.line, cell: row.cells[col] ?? '' });
+    }
+    return out;
+}
+function checkProjectEntities(cwd, requireComplete = false) {
+    const read = readIfPresent(node_path_1.default.join(cwd, ENTITIES_FILE));
+    if (read.kind === 'absent')
+        return null;
+    const empty = { entities: 0, attributes: 0, relationships: 0, lifecycles: 0, step_objects_checked: 0 };
+    if (read.kind === 'unreadable')
+        return { ok: false, file: ENTITIES_FILE, ...empty, violations: [{ artifact: ENTITIES_FILE, reason: 'artifact_unreadable' }] };
+    const processes = readIfPresent(node_path_1.default.join(cwd, PROCESSES_FILE));
+    const stepObjects = processes.kind === 'ok' ? stepDataObjects(processes.content) : [];
+    const result = checkEntities(read.content, stepObjects, requireComplete);
+    if (processes.kind === 'unreadable')
+        result.violations.push({ artifact: PROCESSES_FILE, reason: 'artifact_unreadable' });
+    result.ok = result.violations.length === 0;
+    return { file: ENTITIES_FILE, ...result };
+}
+function formatViolation(v) {
+    const where = v.line !== undefined ? `:${v.line}` : '';
+    const what = v.id !== undefined ? ` (${v.id})` : '';
+    return `  - ${v.artifact}${where}: ${v.reason}${what}`;
+}
+// ─── CLI adapter ──────────────────────────────────────────────────────────────
+/**
+ * CLI adapter for `pp-tools discovery entity-check [--require-complete]`
+ * (dotted form `query discovery.entity-check`). An absent `_entities.md`
+ * exits 0 with `{ ok: true, present: false }`. Structural faults exit via
+ * `DISCOVERY_ENTITY_CHECK_FAILED`; when every fault is an `incomplete_cell` or
+ * `attributes_missing` raised by `--require-complete`, the identity is
+ * `DISCOVERY_ENTITY_CHECK_INCOMPLETE`, so a gate can tell "not finished" from
+ * "malformed".
+ */
+function cmdDiscoveryEntityCheck(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 — error() exits
+    }
+    const result = checkProjectEntities(cwd, requireComplete);
+    if (result === null) {
+        output({ ok: true, present: false, file: ENTITIES_FILE }, raw);
+        return;
+    }
+    const payload = {
+        ok: result.ok, present: true, file: result.file, entities: result.entities, attributes: result.attributes,
+        relationships: result.relationships, lifecycles: result.lifecycles, step_objects_checked: result.step_objects_checked,
+    };
+    if (!result.ok) {
+        output({ ...payload, violations: result.violations.length }, raw);
+        const onlyIncomplete = result.violations.every((v) => v.reason === 'incomplete_cell' || v.reason === 'attributes_missing');
+        error(`discovery entity-check: ${result.violations.length} violation(s):\n` + result.violations.map(formatViolation).join('\n'), onlyIncomplete ? ERROR_REASON.DISCOVERY_ENTITY_CHECK_INCOMPLETE : ERROR_REASON.DISCOVERY_ENTITY_CHECK_FAILED);
+        return; // unreachable
+    }
+    output(payload, raw);
+}
+module.exports = {
+    ENTITIES_FILE,
+    ENTITIES_HEADER,
+    ATTRIBUTES_HEADER,
+    RELATIONSHIPS_HEADER,
+    LIFECYCLES_HEADER,
+    CLASSIFICATION_LEVELS,
+    LIFECYCLE_VALUES,
+    CARDINALITY_RE,
+    DATA_OBJECT_RE,
+    ENTITY_CHECK_FAILED: ERROR_REASON.DISCOVERY_ENTITY_CHECK_FAILED,
+    ENTITY_CHECK_INCOMPLETE: ERROR_REASON.DISCOVERY_ENTITY_CHECK_INCOMPLETE,
+    checkEntities,
+    stepDataObjects,
+    checkProjectEntities,
+    cmdDiscoveryEntityCheck,
+};