@pareto4/pp-core 1.19.0 → 1.20.0

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

@@ -0,0 +1,664 @@
+"use strict";
+/**
+ * Discovery project charter check (Discovery Sprint improvement plan, Batch 1).
+ *
+ * The Project Charter is the one document every stakeholder signs at the end
+ * of a Discovery Sprint. Session 13 drafts it from the session record into
+ * `docs/discovery/PROJECT-CHARTER.md` (client-visible, like `docs/architecture/`),
+ * in the sprint language, from the fixed-shape template in
+ * `pp-core/templates/project-charter.md`. This module checks the structure of
+ * that document — never its judgement:
+ *
+ *   - the frontmatter carries every machine field, with `status`, `go_no_go`,
+ *     `version`, `date` and `language` inside their closed grammars;
+ *   - every one of the twenty sections is present exactly once, in template
+ *     order, identified by its `<!-- charter:<key> -->` heading key, so the
+ *     same shape is recognised whatever language the headings are rendered in;
+ *   - every ID a table cell cites resolves: requirement IDs against
+ *     `_requirements.md` (through the rollup parser, the owner of that file),
+ *     every other discovery family (`D-`, `A-`, `OI-`, `R-`, `CON-`, `SCR-`,
+ *     `E-`, `US-`, `BO-`, `ADR-`, `IF-`, `CR-`, `RS-`, `DG-`, `DEV-`) against the
+ *     IDs the session files and registers under `.planning/discovery/` mint
+ *     in their first table column;
+ *   - the requirement counts line equals the roll-up, and every `Dropped`
+ *     requirement is listed under § Conditions;
+ *   - the Go / No-Go table and the frontmatter verdict equal Session 13's
+ *     assessment as recorded — the charter copies it, never re-judges it;
+ *   - every Session 13 open item marked "must resolve before build" is closed
+ *     or listed under § Conditions;
+ *   - `DEV-` IDs resolve only against `_deviations.md`, and every row of that
+ *     register appears in § Deviations (improvement plan, Batch 3);
+ *   - the sign-off rows agree with `status`, and the version history ends at
+ *     the frontmatter version.
+ *
+ * Reporting posture (D-43/D-53): the check fails only on structural faults.
+ * At Session 13 it reports; at `/pp-discovery-to-build` the same check runs with
+ * `--require-signed`, and a charter whose status is not `Signed` or `Signed with
+ * conditions` exits non-zero on its own identity so the handoff can hard-block
+ * on it and `--unsigned` can record the gap instead.
+ *
+ * Content-free contract (the T-02-05 precedent): output names the file, line
+ * numbers, validated IDs, section keys, field names and reason codes — never
+ * charter prose.
+ *
+ * Traversal: the check takes no positional path. The charter and every source
+ * resolve from fixed convention paths under the working directory (the T-02-08
+ * precedent).
+ */
+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;
+// `_requirements.md` is owned by `discovery rollup`; this gate consumes its
+// parser and re-implements none of its grammar.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const rollup = require("./discovery-rollup.cjs");
+// ─── Constants ────────────────────────────────────────────────────────────────
+const CHARTER_FILE = 'docs/discovery/PROJECT-CHARTER.md';
+const DISCOVERY_DIR = '.planning/discovery';
+const REQUIREMENTS_FILE = `${DISCOVERY_DIR}/_requirements.md`;
+const SESSION_13_FILE = `${DISCOVERY_DIR}/session-13.md`;
+/** The twenty sections, in template order. Keys are the heading's `<!-- charter:<key> -->`. */
+const SECTION_KEYS = Object.freeze([
+    'purpose',
+    'objectives',
+    'scope',
+    'stakeholders',
+    'approvals',
+    'solution',
+    'deviations',
+    'data',
+    'quality',
+    'validated',
+    'delivery',
+    'team',
+    'budget',
+    'risks',
+    'open-items',
+    'conditions',
+    'go-no-go',
+    'decisions',
+    'sign-off',
+    'history',
+]);
+/** Keys the parser reads a table from; a section without one is a structural fault. */
+const TABLE_REQUIRED = Object.freeze(['deviations', 'open-items', 'conditions', 'go-no-go', 'sign-off', 'history']);
+/** The one non-section key: marks the requirement-counts line in § Scope. */
+const COUNTS_KEY = 'counts';
+const DOCUMENT_KIND = 'project-charter';
+const REQUIRED_FIELDS = Object.freeze([
+    'document', 'project', 'client', 'version', 'status', 'date', 'language',
+    'discovery_sessions_completed', 'go_no_go',
+]);
+const STATUS_VALUES = Object.freeze(['Draft', 'For sign-off', 'Signed', 'Signed with conditions', 'Rejected']);
+const SIGNED_VALUES = Object.freeze(['Signed', 'Signed with conditions']);
+const GO_NO_GO_VALUES = Object.freeze(['Pending', 'Go', 'Go with conditions', 'No-Go']);
+const SIGNOFF_DECISIONS = Object.freeze(['Approve', 'Approve with conditions', 'Reject']);
+const VERSION_RE = /^\d+\.\d+$/;
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+/** BCP-47-shaped: `nl`, `en`, `en-GB`, `nl-BE`. */
+const LANGUAGE_RE = /^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$/;
+const KEY_RE = /<!--\s*charter:([a-z-]+)\s*-->/;
+const HEADING_RE = /^##\s/;
+const TABLE_SEPARATOR_RE = /^\|\s*:?-{3,}:?\s*(\|\s*:?-{3,}:?\s*)*\|?\s*$/;
+/**
+ * Session-table and register families whose IDs the charter may cite, all
+ * resolved against the first table column of the files under
+ * `.planning/discovery/`. Decisions and actions carry a session component.
+ */
+const TWO_PART_FAMILIES = Object.freeze(['D', 'A']);
+const ONE_PART_FAMILIES = Object.freeze(['OI', 'R', 'CON', 'SCR', 'E', 'US', 'BO', 'ADR', 'IF', 'CR', 'RS', 'DG', 'DEV']);
+/** The one family with a single owning register: a `DEV-` ID is minted by `_deviations.md` alone (Batch 3). */
+const DEVIATION_FAMILY = 'DEV';
+const DEVIATIONS_FILE = `${DISCOVERY_DIR}/_deviations.md`;
+const ID_TOKEN_RE = /(?<![A-Za-z0-9_`-])([A-Z][A-Z0-9]*)-((?:P?\d+)(?:-\d+)?)(?![A-Za-z0-9_-])/g;
+const FIRST_CELL_ID_RE = /^\|\s*\**\s*([A-Z][A-Z0-9]*-(?:P?\d+)(?:-\d+)?)\s*\**\s*\|/;
+const SESSION_13_GO_NO_GO = 'Go / No-Go Assessment';
+const SESSION_13_OPEN_ITEMS = 'Open Items Register';
+/** Session 13's eight Go / No-Go rows: seven criteria, then the overall recommendation. */
+const GO_NO_GO_ROWS = 8;
+const MUST_RESOLVE_RE = /^yes\b/i;
+const CLOSED_RE = /^(closed|resolved|done)\b/i;
+const USAGE = 'Usage: pp-tools discovery charter-check [--require-signed]';
+// ─── Parsing ──────────────────────────────────────────────────────────────────
+function splitCells(line) {
+    const trimmed = line.trim().replace(/^\|/, '').replace(/\|$/, '');
+    return trimmed.split('|').map((c) => c.trim());
+}
+function stripEmphasis(cell) {
+    return cell.replace(/\*\*/g, '').replace(/^_|_$/g, '').trim();
+}
+function parseFrontmatter(lines) {
+    if (lines.length === 0 || lines[0].trim() !== '---')
+        return null;
+    const fields = new Map();
+    const fieldLines = new Map();
+    for (let i = 1; i < lines.length; i += 1) {
+        if (lines[i].trim() === '---')
+            return { fields, lines: fieldLines, endLine: i + 1 };
+        const m = /^([a-z_]+):\s*(.*)$/.exec(lines[i]);
+        if (m) {
+            fields.set(m[1], m[2].trim().replace(/^"(.*)"$/, '$1'));
+            fieldLines.set(m[1], i + 1);
+        }
+    }
+    return null;
+}
+/**
+ * Every pipe table in a run of lines: the header is the row before the first
+ * separator, data rows follow until the first non-pipe line. A second table
+ * starts at the next separator.
+ */
+function parseTables(body) {
+    const tables = [];
+    for (let i = 1; i < body.length; i += 1) {
+        if (!TABLE_SEPARATOR_RE.test(body[i].text) || !body[i - 1].text.trim().startsWith('|'))
+            continue;
+        const table = { line: body[i - 1].n, header: splitCells(body[i - 1].text), rows: [] };
+        let j = i + 1;
+        for (; j < body.length; j += 1) {
+            const text = body[j].text.trim();
+            if (!text.startsWith('|'))
+                break;
+            if (TABLE_SEPARATOR_RE.test(text))
+                break;
+            table.rows.push({ line: body[j].n, cells: splitCells(text) });
+        }
+        tables.push(table);
+        i = j - 1;
+    }
+    return tables;
+}
+/** Sections by heading key, in file order, with their bodies and tables. */
+function parseSections(lines, from) {
+    const sections = [];
+    const unknown = [];
+    let counts = null;
+    let current = null;
+    const bodies = [];
+    for (let i = from; i < lines.length; i += 1) {
+        const text = lines[i];
+        const n = i + 1;
+        const key = KEY_RE.exec(text);
+        if (key && key[1] === COUNTS_KEY) {
+            counts = { n, text };
+        }
+        else if (key && !HEADING_RE.test(text)) {
+            unknown.push({ n, key: key[1] });
+        }
+        if (HEADING_RE.test(text)) {
+            if (current)
+                bodies.push(current.body);
+            if (key && key[1] !== COUNTS_KEY) {
+                current = { key: key[1], line: n, tables: [], body: [] };
+                sections.push(current);
+            }
+            else {
+                current = null;
+            }
+            continue;
+        }
+        if (current)
+            current.body.push({ n, text });
+    }
+    for (const s of sections)
+        s.tables = parseTables(s.body);
+    return { sections, counts, unknown };
+}
+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' };
+    }
+}
+/**
+ * Every ID minted in the first column of any table under `.planning/discovery/*.md`,
+ * plus the `DEV-` IDs `_deviations.md` mints on its own (`deviations` is null when
+ * that register does not exist).
+ */
+function collectMintedIds(cwd) {
+    const ids = new Set();
+    let deviations = null;
+    const unreadable = [];
+    const dir = node_path_1.default.join(cwd, DISCOVERY_DIR);
+    let names = [];
+    try {
+        names = node_fs_1.default.readdirSync(dir).filter((f) => f.endsWith('.md') && f !== '_requirements.md').sort();
+    }
+    catch {
+        return { ids, deviations, unreadable };
+    }
+    for (const name of names) {
+        const read = readIfPresent(node_path_1.default.join(dir, name));
+        if (read.kind === 'absent')
+            continue;
+        if (read.kind === 'unreadable') {
+            unreadable.push(`${DISCOVERY_DIR}/${name}`);
+            continue;
+        }
+        const isDeviations = `${DISCOVERY_DIR}/${name}` === DEVIATIONS_FILE;
+        if (isDeviations)
+            deviations = new Set();
+        for (const line of read.content.split(/\r?\n/)) {
+            const m = FIRST_CELL_ID_RE.exec(line);
+            if (!m)
+                continue;
+            if (m[1].startsWith(`${DEVIATION_FAMILY}-`)) {
+                if (isDeviations)
+                    deviations.add(m[1]);
+            }
+            else {
+                ids.add(m[1]);
+            }
+        }
+    }
+    return { ids, deviations, unreadable };
+}
+/** `_requirements.md` through its owner's parser: absent → null, unparseable → 'unparseable'. */
+function readRequirements(cwd) {
+    const read = readIfPresent(node_path_1.default.join(cwd, REQUIREMENTS_FILE));
+    if (read.kind === 'absent')
+        return null;
+    if (read.kind === 'unreadable')
+        return 'unreadable';
+    const parsed = rollup.parseRequirementsArtifact(read.content);
+    if (!parsed.ok)
+        return 'unparseable';
+    const prefixes = new Set(parsed.registry.map((r) => r.prefix));
+    const ids = new Set();
+    const liveByPrefix = new Map();
+    for (const p of prefixes)
+        liveByPrefix.set(p, 0);
+    const dropped = [];
+    for (const row of parsed.rows) {
+        ids.add(row.id);
+        if (row.disposition === 'Dropped')
+            dropped.push(row.id);
+        else
+            liveByPrefix.set(row.prefix, (liveByPrefix.get(row.prefix) ?? 0) + 1);
+    }
+    return { prefixes, ids, liveByPrefix, dropped };
+}
+/** A Notes Template table in a session file: the first table after the named label (bold or heading). */
+function sessionTable(lines, label) {
+    const norm = (s) => s.replace(/^#+\s*/, '').replace(/\*\*/g, '').trim();
+    const at = lines.findIndex((l) => norm(l) === 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 = parseTables(body);
+    return tables.length > 0 ? tables[0] : null;
+}
+function readSession13(cwd) {
+    const read = readIfPresent(node_path_1.default.join(cwd, SESSION_13_FILE));
+    if (read.kind === 'absent')
+        return null;
+    if (read.kind === 'unreadable')
+        return 'unreadable';
+    const lines = read.content.split(/\r?\n/);
+    const go = sessionTable(lines, SESSION_13_GO_NO_GO);
+    const open = sessionTable(lines, SESSION_13_OPEN_ITEMS);
+    return {
+        goNoGo: go ? go.rows.map((r) => ({ status: stripEmphasis(r.cells[1] ?? '') })) : null,
+        openItems: open
+            ? open.rows
+                .filter((r) => /^OI-\d+$/.test(stripEmphasis(r.cells[0] ?? '')))
+                .map((r) => ({
+                id: stripEmphasis(r.cells[0] ?? ''),
+                mustResolve: MUST_RESOLVE_RE.test(stripEmphasis(r.cells[4] ?? '')),
+                closed: CLOSED_RE.test(stripEmphasis(r.cells[7] ?? '')),
+            }))
+            : null,
+    };
+}
+/** Check one charter text against its sources. Pure over its inputs. */
+function checkCharter(content, sources, requireSigned = false) {
+    const violations = [];
+    const lines = content.split(/\r?\n/);
+    // 1 ─ Frontmatter
+    const fm = parseFrontmatter(lines);
+    let status = null;
+    let goNoGo = null;
+    let version = null;
+    let language = null;
+    if (fm === null) {
+        violations.push({ reason: 'frontmatter_missing', line: 1 });
+    }
+    else {
+        for (const f of REQUIRED_FIELDS) {
+            if (!fm.fields.has(f) || fm.fields.get(f) === '')
+                violations.push({ reason: 'field_missing', id: f });
+        }
+        const at = (f) => fm.lines.get(f);
+        const v = (f) => fm.fields.get(f) ?? '';
+        if (fm.fields.has('document') && v('document') !== DOCUMENT_KIND)
+            violations.push({ reason: 'bad_document', line: at('document') });
+        if (fm.fields.has('status')) {
+            if (STATUS_VALUES.includes(v('status')))
+                status = v('status');
+            else
+                violations.push({ reason: 'bad_status', line: at('status') });
+        }
+        if (fm.fields.has('go_no_go')) {
+            if (GO_NO_GO_VALUES.includes(v('go_no_go')))
+                goNoGo = v('go_no_go');
+            else
+                violations.push({ reason: 'bad_go_no_go', line: at('go_no_go') });
+        }
+        if (fm.fields.has('version')) {
+            if (VERSION_RE.test(v('version')))
+                version = v('version');
+            else
+                violations.push({ reason: 'bad_version', line: at('version') });
+        }
+        if (fm.fields.has('date') && !DATE_RE.test(v('date')))
+            violations.push({ reason: 'bad_date', line: at('date') });
+        if (fm.fields.has('language')) {
+            if (LANGUAGE_RE.test(v('language')))
+                language = v('language');
+            else
+                violations.push({ reason: 'bad_language', line: at('language') });
+        }
+    }
+    // 2 ─ Sections: present once each, in order, nothing unknown
+    const { sections, counts, unknown } = parseSections(lines, fm ? fm.endLine : 0);
+    for (const u of unknown)
+        violations.push({ reason: 'section_unknown', line: u.n, id: u.key });
+    const seen = new Map();
+    for (const s of sections) {
+        if (!SECTION_KEYS.includes(s.key)) {
+            violations.push({ reason: 'section_unknown', line: s.line, id: s.key });
+            continue;
+        }
+        if (seen.has(s.key))
+            violations.push({ reason: 'section_duplicate', line: s.line, id: s.key });
+        else
+            seen.set(s.key, s);
+    }
+    for (const k of SECTION_KEYS) {
+        if (!seen.has(k))
+            violations.push({ reason: 'section_missing', id: k });
+    }
+    const order = sections.filter((s) => seen.get(s.key) === s).map((s) => s.key);
+    const expected = SECTION_KEYS.filter((k) => seen.has(k));
+    for (let i = 0; i < order.length; i += 1) {
+        if (order[i] !== expected[i]) {
+            violations.push({ reason: 'section_order', line: seen.get(order[i])?.line, id: order[i] });
+            break;
+        }
+    }
+    for (const k of TABLE_REQUIRED) {
+        const s = seen.get(k);
+        if (s && s.tables.length === 0)
+            violations.push({ reason: 'table_missing', line: s.line, id: k });
+    }
+    // 3 ─ Every ID a table cell cites resolves
+    let idsChecked = 0;
+    const requirements = sources.requirements;
+    for (const s of seen.values()) {
+        if (s.key === 'history')
+            continue;
+        for (const t of s.tables) {
+            for (const row of t.rows) {
+                for (const cell of row.cells) {
+                    for (const m of cell.matchAll(ID_TOKEN_RE)) {
+                        const prefix = m[1];
+                        const token = `${prefix}-${m[2]}`;
+                        const twoPart = /^P?\d+-\d+$/.test(m[2]);
+                        if (TWO_PART_FAMILIES.includes(prefix)) {
+                            idsChecked += 1;
+                            if (!/^(?:\d{2}|P\d{2})-\d+$/.test(m[2]) || !sources.minted.has(token))
+                                violations.push({ reason: 'unknown_id', line: row.line, id: token });
+                        }
+                        else if (prefix === DEVIATION_FAMILY) {
+                            idsChecked += 1;
+                            if (twoPart || sources.deviations === null || !sources.deviations.has(token))
+                                violations.push({ reason: 'unknown_id', line: row.line, id: token });
+                        }
+                        else if (ONE_PART_FAMILIES.includes(prefix)) {
+                            idsChecked += 1;
+                            if (twoPart || !sources.minted.has(token))
+                                violations.push({ reason: 'unknown_id', line: row.line, id: token });
+                        }
+                        else if (requirements && requirements !== 'unparseable' && requirements.prefixes.has(`${prefix}-`)) {
+                            idsChecked += 1;
+                            if (twoPart || !requirements.ids.has(token))
+                                violations.push({ reason: 'unknown_id', line: row.line, id: token });
+                        }
+                    }
+                }
+            }
+        }
+    }
+    // 3b ─ Every deviation on file is listed in § Deviations (Batch 3)
+    const deviationsSection = seen.get('deviations');
+    if (sources.deviations !== null && deviationsSection) {
+        const listed = new Set();
+        for (const t of deviationsSection.tables)
+            for (const row of t.rows)
+                for (const m of (row.cells[0] ?? '').matchAll(ID_TOKEN_RE))
+                    listed.add(`${m[1]}-${m[2]}`);
+        for (const id of sources.deviations)
+            if (!listed.has(id))
+                violations.push({ reason: 'deviation_missing', line: deviationsSection.line, id });
+    }
+    // 4 ─ Requirement counts and dropped rows, when the register is on file
+    const conditions = seen.get('conditions');
+    const conditionsText = conditions ? conditions.tables.flatMap((t) => t.rows.flatMap((r) => r.cells)).join(' ') : '';
+    if (requirements === 'unparseable') {
+        violations.push({ reason: 'requirements_unparseable' });
+    }
+    else if (requirements) {
+        if (!counts) {
+            violations.push({ reason: 'counts_missing', line: seen.get('scope')?.line });
+        }
+        else {
+            const found = new Map();
+            for (const m of counts.text.replace(KEY_RE, '').matchAll(/([A-Z][A-Z0-9]*-)\s+(\d+)/g))
+                found.set(m[1], Number(m[2]));
+            const droppedM = /Dropped\s+(\d+)/.exec(counts.text);
+            let mismatch = droppedM === null || Number(droppedM[1]) !== requirements.dropped.length;
+            if (found.size !== requirements.liveByPrefix.size)
+                mismatch = true;
+            for (const [p, n] of requirements.liveByPrefix)
+                if (found.get(p) !== n)
+                    mismatch = true;
+            if (mismatch)
+                violations.push({ reason: 'counts_mismatch', line: counts.n });
+        }
+        if (conditions) {
+            for (const id of requirements.dropped) {
+                if (!new RegExp(`(?<![A-Z0-9-])${id}(?![0-9-])`).test(conditionsText))
+                    violations.push({ reason: 'dropped_missing', id });
+            }
+        }
+    }
+    // 5 ─ Go / No-Go: recorded, not re-judged
+    if (goNoGo === 'Pending' && status !== null && status !== 'Draft')
+        violations.push({ reason: 'go_no_go_pending', line: fm?.lines.get('go_no_go') });
+    const go = seen.get('go-no-go');
+    const goTable = go && go.tables.length > 0 ? go.tables[0] : null;
+    if (goTable && goTable.rows.length !== GO_NO_GO_ROWS)
+        violations.push({ reason: 'go_no_go_mismatch', line: goTable.line, id: 'rows' });
+    if (goTable && goTable.rows.length === GO_NO_GO_ROWS && goNoGo !== null && goNoGo !== 'Pending') {
+        const overall = stripEmphasis(goTable.rows[GO_NO_GO_ROWS - 1].cells[1] ?? '');
+        if (overall !== goNoGo)
+            violations.push({ reason: 'go_no_go_mismatch', line: goTable.rows[GO_NO_GO_ROWS - 1].line, id: 'overall' });
+    }
+    const s13 = sources.session13;
+    if (s13 && s13.goNoGo && s13.goNoGo.length === GO_NO_GO_ROWS && goTable && goTable.rows.length === GO_NO_GO_ROWS) {
+        const recordedOverall = s13.goNoGo[GO_NO_GO_ROWS - 1].status;
+        const recorded = recordedOverall !== '';
+        if (recorded) {
+            for (let i = 0; i < GO_NO_GO_ROWS; i += 1) {
+                if (stripEmphasis(goTable.rows[i].cells[1] ?? '') !== s13.goNoGo[i].status) {
+                    violations.push({ reason: 'go_no_go_mismatch', line: goTable.rows[i].line, id: `row-${i + 1}` });
+                }
+            }
+            if (goNoGo !== null && goNoGo !== recordedOverall)
+                violations.push({ reason: 'go_no_go_mismatch', line: fm?.lines.get('go_no_go'), id: 'frontmatter' });
+        }
+    }
+    // 6 ─ Must-resolve open items are closed or conditions
+    if (s13 && s13.openItems && conditions) {
+        for (const item of s13.openItems) {
+            if (item.mustResolve && !item.closed && !new RegExp(`(?<![A-Z0-9-])${item.id}(?![0-9-])`).test(conditionsText)) {
+                violations.push({ reason: 'must_resolve_open', id: item.id });
+            }
+        }
+    }
+    // 7 ─ Sign-off rows agree with status
+    const signoff = seen.get('sign-off');
+    const signTable = signoff && signoff.tables.length > 0 ? signoff.tables[0] : null;
+    if (signTable) {
+        const decisions = [];
+        for (const row of signTable.rows) {
+            const d = stripEmphasis(row.cells[2] ?? '');
+            if (d !== '' && !SIGNOFF_DECISIONS.includes(d))
+                violations.push({ reason: 'bad_signoff_decision', line: row.line });
+            else
+                decisions.push(d);
+        }
+        const all = (pred) => decisions.length > 0 && decisions.every(pred);
+        let consistent = true;
+        if (status === 'Signed')
+            consistent = all((d) => d === 'Approve');
+        else if (status === 'Signed with conditions')
+            consistent = all((d) => d === 'Approve' || d === 'Approve with conditions') && decisions.includes('Approve with conditions');
+        else if (status === 'Rejected')
+            consistent = decisions.includes('Reject');
+        if (!consistent)
+            violations.push({ reason: 'signoff_status_mismatch', line: signTable.line });
+    }
+    // 8 ─ Version history ends at the frontmatter version
+    const history = seen.get('history');
+    const histTable = history && history.tables.length > 0 ? history.tables[0] : null;
+    if (histTable) {
+        if (histTable.rows.length === 0)
+            violations.push({ reason: 'history_missing', line: histTable.line });
+        else {
+            for (const row of histTable.rows) {
+                if (!VERSION_RE.test(stripEmphasis(row.cells[0] ?? '')))
+                    violations.push({ reason: 'bad_version', line: row.line });
+            }
+            const last = stripEmphasis(histTable.rows[histTable.rows.length - 1].cells[0] ?? '');
+            if (version !== null && VERSION_RE.test(last) && last !== version)
+                violations.push({ reason: 'history_version_mismatch', line: histTable.rows[histTable.rows.length - 1].line });
+        }
+    }
+    // 9 ─ The handoff arm
+    if (requireSigned && (status === null || !SIGNED_VALUES.includes(status))) {
+        violations.push({ reason: 'charter_unsigned', line: fm?.lines.get('status') });
+    }
+    return {
+        ok: violations.length === 0,
+        status,
+        go_no_go: goNoGo,
+        version,
+        language,
+        sections: seen.size,
+        ids_checked: idsChecked,
+        violations,
+    };
+}
+/** Check the charter of the project at `cwd`. */
+function checkProjectCharter(cwd, requireSigned = false) {
+    const empty = { status: null, go_no_go: null, version: null, language: null, sections: 0, ids_checked: 0 };
+    const read = readIfPresent(node_path_1.default.join(cwd, CHARTER_FILE));
+    if (read.kind === 'absent')
+        return { ok: false, file: CHARTER_FILE, ...empty, violations: [{ reason: 'charter_missing' }] };
+    if (read.kind === 'unreadable')
+        return { ok: false, file: CHARTER_FILE, ...empty, violations: [{ reason: 'artifact_unreadable', id: CHARTER_FILE }] };
+    const content = read.content;
+    const minted = collectMintedIds(cwd);
+    const requirements = readRequirements(cwd);
+    const session13 = readSession13(cwd);
+    const sources = {
+        minted: minted.ids,
+        deviations: minted.deviations,
+        requirements: requirements === 'unreadable' ? null : requirements,
+        session13: session13 === 'unreadable' ? null : session13,
+    };
+    const result = checkCharter(content, sources, requireSigned);
+    for (const p of minted.unreadable)
+        result.violations.push({ reason: 'artifact_unreadable', id: p });
+    if (requirements === 'unreadable')
+        result.violations.push({ reason: 'artifact_unreadable', id: REQUIREMENTS_FILE });
+    if (session13 === 'unreadable')
+        result.violations.push({ reason: 'artifact_unreadable', id: SESSION_13_FILE });
+    result.ok = result.violations.length === 0;
+    return { file: CHARTER_FILE, ...result };
+}
+function formatViolation(v) {
+    const where = v.line !== undefined ? `line ${v.line}: ` : '';
+    const what = v.id !== undefined ? ` (${v.id.slice(0, 80)})` : '';
+    return `  - ${where}${v.reason}${what}`;
+}
+// ─── CLI adapter ──────────────────────────────────────────────────────────────
+/**
+ * CLI adapter for `pp-tools discovery charter-check [--require-signed]`
+ * (dotted form `pp-tools query discovery.charter-check`).
+ *
+ * Exit semantics: a structural fault exits non-zero via
+ * `ERROR_REASON.DISCOVERY_CHARTER_CHECK_FAILED`; a structurally sound charter
+ * that `--require-signed` finds unsigned exits via
+ * `ERROR_REASON.DISCOVERY_CHARTER_UNSIGNED`. The payload is emitted on stdout
+ * first on both failure paths, so the status survives alongside the error.
+ */
+function cmdDiscoveryCharterCheck(cwd, args, raw) {
+    // args arrive shaped ['discovery', 'charter-check', ...flags].
+    const rest = args.slice(2);
+    const requireSigned = rest.includes('--require-signed');
+    if (rest.some((a) => a !== '--require-signed')) {
+        error(USAGE, ERROR_REASON.USAGE);
+        return; // unreachable — error() exits
+    }
+    const result = checkProjectCharter(cwd, requireSigned);
+    const payload = {
+        ok: result.ok,
+        file: result.file,
+        status: result.status,
+        go_no_go: result.go_no_go,
+        version: result.version,
+        language: result.language,
+        sections: result.sections,
+        ids_checked: result.ids_checked,
+    };
+    if (!result.ok) {
+        output({ ...payload, violations: result.violations.length }, raw);
+        const onlyUnsigned = result.violations.every((v) => v.reason === 'charter_unsigned');
+        error(`discovery charter-check: ${result.violations.length} violation(s) in ${result.file}:\n` +
+            result.violations.map(formatViolation).join('\n'), onlyUnsigned ? ERROR_REASON.DISCOVERY_CHARTER_UNSIGNED : ERROR_REASON.DISCOVERY_CHARTER_CHECK_FAILED);
+        return; // unreachable — error() exits
+    }
+    output(payload, raw);
+}
+module.exports = {
+    CHARTER_FILE,
+    SECTION_KEYS,
+    TABLE_REQUIRED,
+    COUNTS_KEY,
+    STATUS_VALUES,
+    SIGNED_VALUES,
+    GO_NO_GO_VALUES,
+    SIGNOFF_DECISIONS,
+    CHARTER_CHECK_FAILED: ERROR_REASON.DISCOVERY_CHARTER_CHECK_FAILED,
+    CHARTER_UNSIGNED: ERROR_REASON.DISCOVERY_CHARTER_UNSIGNED,
+    parseTables,
+    checkCharter,
+    checkProjectCharter,
+    cmdDiscoveryCharterCheck,
+};