@pareto4/pp-core 1.21.1 → 1.23.1

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

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

package/pp-core/bin/lib/explain-command.cjs

@@ -0,0 +1,48 @@
+"use strict";
+/**
+ * `pp-tools explain <code>`: the longer explanation of a message's `Ref:` code
+ * (Phase 41: D-19, MSG-05).
+ *
+ * ADR-457 build-at-publish: this TypeScript file is the SOURCE OF TRUTH. It
+ * compiles to the gitignored `pp-core/bin/lib/explain-command.cjs`; do NOT
+ * hand-edit the compiled output.
+ *
+ * A thin adapter over the message catalog. The code is only ever looked up in
+ * the catalog's Map (`explainText`), never used to index an object, so
+ * `__proto__`, `constructor` and `toString` are unknown codes like any other
+ * (T-41-13). The typed code is echoed only after `sanitizeParam` has stripped
+ * control characters (T-41-11). There is no listing mode: a bare call prints
+ * only the usage (T-41-25).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.USAGE = void 0;
+exports.cmdExplain = cmdExplain;
+const messages_cjs_1 = require("./messages.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const io = require("./io.cjs");
+const { output, ERROR_REASON } = io;
+/** Explicitly typed so TypeScript narrows after a failing guard (the destructured `io.error` does not). */
+function error(message, reason) {
+    return io.error(message, reason);
+}
+const HELP_FLAGS = ['-h', '--help', '-?', '--h', '--usage'];
+exports.USAGE = 'Usage: pp-tools explain <code> [--raw] — <code> is the text after "Ref:" at the end of a message';
+function cmdExplain(_cwd, args, raw) {
+    if (args.length === 1 && HELP_FLAGS.includes(args[0])) {
+        output({ usage: exports.USAGE }, true, exports.USAGE + '\n');
+        return;
+    }
+    if (args.length !== 1 || args[0].startsWith('--'))
+        error(exports.USAGE, ERROR_REASON.USAGE);
+    const code = args[0];
+    const audience = (0, messages_cjs_1.audienceOf)(process.env);
+    const body = (0, messages_cjs_1.explainText)(code, { audience });
+    if (body === null) {
+        io.errorCode('explain_unknown_code', { code: (0, messages_cjs_1.sanitizeParam)(code) }, ERROR_REASON.EXPLAIN_UNKNOWN_CODE);
+    }
+    if (raw) {
+        output({ code, audience, text: body }, false);
+        return;
+    }
+    output({ code, audience, text: body }, true, body + '\n');
+}

package/pp-core/bin/lib/gate-card.cjs

@@ -0,0 +1,97 @@
+"use strict";
+/**
+ * `pp-tools gate-card <query>`: the stopped-check card in the person's wording
+ * (Phase 43: D-11, TPL-02).
+ *
+ * ADR-457 build-at-publish: this TypeScript file is the SOURCE OF TRUTH. It
+ * compiles to the gitignored `pp-core/bin/lib/gate-card.cjs`; do NOT hand-edit
+ * the compiled output.
+ *
+ * Like `audience fields`, it prints nothing for a developer, so a workflow fence
+ * that calls it prints no extra line for a developer (D-03). Every word comes
+ * from the `gate` catalog slice through `msg()` / `text()` (D-10); this verb never
+ * composes wording. Codes are looked up only through the catalog Map (`has`), and
+ * the query only through `GATE_QUERIES.includes`, so `__proto__`, `constructor`
+ * and an unknown name print nothing (T-43-10). The query argument is never echoed
+ * on any path, including usage errors (T-43-11). The no-state output is one
+ * `JSON.stringify` line, so card text cannot forge a line of its own (T-43-12).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.USAGE = void 0;
+exports.cardsFor = cardsFor;
+exports.cmdGateCard = cmdGateCard;
+const messages_cjs_1 = require("./messages.cjs");
+const gate_cjs_1 = require("./messages/gate.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const io = require("./io.cjs");
+const { output, ERROR_REASON } = io;
+/** Explicitly typed so TypeScript narrows after a failing guard (the destructured `io.error` does not). */
+function error(message, reason) {
+    return io.error(message, reason);
+}
+exports.USAGE = "Usage: pp-tools gate-card <query> [--state blocked|advisory|error] [--details] [--raw] — the stopped-check card in the person's wording; prints nothing for a developer";
+/**
+ * The cards of one query, keyed by state; null for a developer or an unknown query.
+ * Only the states the query defines appear.
+ */
+function cardsFor(query, audience) {
+    if (audience === 'developer')
+        return null;
+    if (!gate_cjs_1.GATE_QUERIES.includes(query))
+        return null;
+    const cards = {};
+    for (const state of gate_cjs_1.GATE_STATES) {
+        const code = `gate.${query}.${state}`;
+        if ((0, messages_cjs_1.has)(code))
+            cards[state] = { code, text: (0, messages_cjs_1.text)(code, {}, { audience }) };
+    }
+    return cards;
+}
+function cmdGateCard(_cwd, args, raw) {
+    let query = null;
+    let state = null;
+    let details = false;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === '--raw')
+            continue;
+        if (a === '--details') {
+            details = true;
+        }
+        else if (a === '--state') {
+            const next = args[i + 1];
+            if (next === undefined || !gate_cjs_1.GATE_STATES.includes(next))
+                error(exports.USAGE, ERROR_REASON.USAGE);
+            state = next;
+            i++;
+        }
+        else if (a.startsWith('-')) {
+            error(exports.USAGE, ERROR_REASON.USAGE);
+        }
+        else if (query === null) {
+            query = a;
+        }
+        else {
+            error(exports.USAGE, ERROR_REASON.USAGE);
+        }
+    }
+    if (query === null)
+        error(exports.USAGE, ERROR_REASON.USAGE);
+    const audience = (0, messages_cjs_1.audienceOf)(process.env);
+    const cards = cardsFor(query, audience);
+    if (cards === null)
+        return;
+    if (state === null) {
+        output(cards, true, JSON.stringify(cards) + '\n');
+        return;
+    }
+    const card = Object.prototype.hasOwnProperty.call(cards, state) ? cards[state] : undefined;
+    if (card === undefined)
+        return;
+    const body = (0, messages_cjs_1.msg)(card.code, {}, { audience });
+    if (raw) {
+        output({ code: card.code, text: body }, false);
+        return;
+    }
+    output({ code: card.code, text: body }, true, body + (details ? '\nDetails:' : '') + '\n');
+}

package/pp-core/bin/lib/hook-messages.cjs

@@ -0,0 +1,132 @@
+"use strict";
+/**
+ * The hooks' light catalog entry (Phase 43, MSG-06; D-18, D-20).
+ *
+ * ADR-457 build-at-publish: this TypeScript file is the SOURCE OF TRUTH. It
+ * compiles to the gitignored `pp-core/bin/lib/hook-messages.cjs`; do NOT
+ * hand-edit the compiled output.
+ *
+ * The statusline runs on every prompt, so it cannot load the whole catalog
+ * (`messages.cjs` pulls in every slice, ~73 KB). This module imports only
+ * `./audience.cjs`, `./message-labels.cjs` and `./messages/hook.cjs`, plus
+ * `import type { CatalogEntry } from './messages.cjs'`, which compiles away.
+ * It carries its own copy of the engine's control-character regex, slot regex,
+ * ECHO_CAP, sanitise, fill and pick (about 25 lines), kept equal to
+ * `src/messages.cts` by the parity test in tests/hook-messages.test.cjs
+ * (PITFALLS #19).
+ *
+ * Its functions never throw: an unknown code, a bad param or an unreadable
+ * person file returns the fallback text. The hooks wrap their calls in
+ * try/catch as well and fall back to today's text when this module cannot load
+ * (D-20).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.audienceOf = audienceOf;
+exports.developerText = developerText;
+exports.text = text;
+exports.msg = msg;
+exports.label = label;
+exports.statusWord = statusWord;
+const audience_cjs_1 = require("./audience.cjs");
+const message_labels_cjs_1 = require("./message-labels.cjs");
+const hook_cjs_1 = require("./messages/hook.cjs");
+// Copies of the engine's constants; see the header.
+const CONTROL_CHARS_RE = /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f\p{Cf}]/gu;
+const SLOT_RE = /\{([a-z][a-z0-9_]*)\}/g;
+const ECHO_CAP = 120;
+/** The shape ship.md writes into the STATE.md status: `Phase N shipped — PR #N`. Anchored, linear. */
+const SHIPPED_STATUS_RE = /^Phase (\S+) shipped — PR #(\d+)$/;
+// Lookup only: a Map, so `__proto__` and `constructor` are unknown codes.
+const ENTRIES = new Map(Object.entries(hook_cjs_1.hook));
+function sanitize(value) {
+    let raw;
+    if (typeof value === 'number')
+        raw = String(value);
+    else if (typeof value === 'string')
+        raw = value;
+    else
+        return '';
+    const collapsed = raw.replace(CONTROL_CHARS_RE, '').replace(/\s+/g, ' ').trim();
+    return collapsed.length <= ECHO_CAP ? collapsed : `${collapsed.slice(0, ECHO_CAP)}…`;
+}
+function fill(template, params, clean) {
+    return template.replace(SLOT_RE, (match, name) => {
+        if (!Object.hasOwn(params, name))
+            return clean ? match : '';
+        const value = params[name];
+        if (!clean)
+            return typeof value === 'string' || typeof value === 'number' ? String(value) : '';
+        return sanitize(value);
+    });
+}
+function pick(entry, audience) {
+    if (audience === 'business')
+        return entry.business ?? entry.engineer ?? entry.developer;
+    if (audience === 'engineer')
+        return entry.engineer ?? entry.developer;
+    return entry.developer;
+}
+/** The audience for this process; developer on any failure. */
+function audienceOf(env = process.env) {
+    try {
+        return (0, audience_cjs_1.resolveAudience)(env, (0, audience_cjs_1.readPerson)(env)).audience;
+    }
+    catch {
+        return 'developer';
+    }
+}
+/** The developer text, params untouched. An unknown code returns the code. */
+function developerText(code, params = {}) {
+    const entry = ENTRIES.get(code);
+    if (entry === undefined)
+        return code;
+    return fill(entry.developer, params ?? {}, false);
+}
+/** The text for an audience with no Ref line. An unknown code returns the code. */
+function text(code, params = {}, audience = 'developer') {
+    const entry = ENTRIES.get(code);
+    if (entry === undefined)
+        return code;
+    if (audience === 'developer')
+        return developerText(code, params);
+    return fill(pick(entry, audience), params ?? {}, true);
+}
+/**
+ * The message for an audience: business and engineer messages that are not
+ * parts end with the Ref line. An unknown code returns `fallback` when it is a
+ * string, else the code.
+ */
+function msg(code, params = {}, audience = 'developer', fallback) {
+    const entry = ENTRIES.get(code);
+    if (entry === undefined)
+        return typeof fallback === 'string' ? fallback : code;
+    if (audience === 'developer')
+        return developerText(code, params);
+    const body = text(code, params, audience);
+    return entry.part === true ? body : `${body}\nRef: ${code}`;
+}
+/** The display word for a canonical value; the value itself for a developer, an unknown domain or an unknown value. */
+function label(domain, canonical, audience = 'developer') {
+    try {
+        return (0, message_labels_cjs_1.label)(domain, canonical, { audience });
+    }
+    catch {
+        return canonical;
+    }
+}
+/**
+ * The display text for a STATE.md `status`. A lifecycle word is relabelled
+ * through `state.status`; the ship shape renders through
+ * `hook.statusline.status_shipped`; anything else shows as written. A non-string
+ * returns ''.
+ */
+function statusWord(status, audience = 'developer') {
+    if (typeof status !== 'string')
+        return '';
+    if (audience === 'developer')
+        return status;
+    const shipped = SHIPPED_STATUS_RE.exec(status);
+    if (shipped !== null)
+        return text('hook.statusline.status_shipped', { number: shipped[1], pr: shipped[2] }, audience);
+    return label('state.status', status, audience);
+}