@pareto4/pp-core 1.22.0 → 1.23.1

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

@@ -5,7 +5,7 @@
  * 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
+ * in the charter language, from the fixed-shape template in
  * `pp-core/templates/project-charter.md`. This module checks the structure of
  * that document — never its judgement:
  *
@@ -148,6 +148,17 @@ function parseFrontmatter(lines) {
     }
     return null;
 }
+/**
+ * The charter's frontmatter `status` exactly as `charter-check` reads it: one of
+ * `STATUS_VALUES`, else null (no frontmatter, no field, or a value the check
+ * reports as `bad_status`). `discovery status` predicts the gate with this, so
+ * the two never disagree on what the status is (42-REVIEW WR-01).
+ */
+function charterStatusOf(content) {
+    const fm = parseFrontmatter(content.split(/\r?\n/));
+    const value = fm?.fields.get('status') ?? '';
+    return STATUS_VALUES.includes(value) ? value : 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
@@ -658,6 +669,7 @@ module.exports = {
     CHARTER_CHECK_FAILED: ERROR_REASON.DISCOVERY_CHARTER_CHECK_FAILED,
     CHARTER_UNSIGNED: ERROR_REASON.DISCOVERY_CHARTER_UNSIGNED,
     parseTables,
+    charterStatusOf,
     checkCharter,
     checkProjectCharter,
     cmdDiscoveryCharterCheck,

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

@@ -30,9 +30,10 @@ const node_path_1 = __importDefault(require("node:path"));
 const node_child_process_1 = require("node:child_process");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const io = require("./io.cjs");
-const { output, error, ERROR_REASON } = io;
+const { output, error, errorCode, ERROR_REASON } = io;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const fm = require("./frontmatter.cjs");
+const violation_render_cjs_1 = require("./violation-render.cjs");
 // ─── Constants ────────────────────────────────────────────────────────────────
 const SESSION_STATUS = Object.freeze({
     NOT_STARTED: 'Not Started',
@@ -169,14 +170,6 @@ function checkInputPackage(cwd) {
     return { ok: true, ...summary };
 }
 // ─── CLI adapter ──────────────────────────────────────────────────────────────
-/** One content-free line per violation: path + structured reason + counts (T-02-05). */
-function formatViolation(v) {
-    if (v.reason === 'confidential_tracked') {
-        return `  ${v.file}: confidential_tracked`;
-    }
-    const score = v.reason === 'score_counts_unconfirmed' ? `score: ${v.score}, ` : '';
-    return `  ${v.session}: ${v.reason} (${score}markers: ${v.markers})`;
-}
 /**
  * CLI adapter for `pp-tools discovery input-check` (dotted form
  * `pp-tools query discovery.input-check`).
@@ -197,8 +190,15 @@ function cmdDiscoveryInputCheck(cwd, args, raw) {
     }
     const result = checkInputPackage(cwd);
     if (!result.ok) {
-        const lines = result.violations.map(formatViolation).join('\n');
-        error(`discovery input-check: ${result.violations.length} violation(s):\n${lines}`, ERROR_REASON.DISCOVERY_INPUT_CHECK_FAILED);
+        // Content-free contract (T-02-05): each line names a path, a structured reason and counts, never file contents.
+        // The code is the ERROR_REASON value itself (D-03); the lines come from the shared renderer (D-11).
+        const violations = result.violations;
+        errorCode(ERROR_REASON.DISCOVERY_INPUT_CHECK_FAILED, (audience) => ({
+            count: violations.length,
+            lines: violations
+                .map((v) => (0, violation_render_cjs_1.renderViolation)('discovery.input', v, { audience, extra: { marker: TO_CONFIRM_MARKER, status_word: SESSION_STATUS.COMPLETED } }))
+                .join('\n'),
+        }), ERROR_REASON.DISCOVERY_INPUT_CHECK_FAILED);
         return; // unreachable — error() exits
     }
     output({

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

@@ -32,9 +32,10 @@ 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;
+const { output, error, errorCode, ERROR_REASON } = io;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const table = require("./discovery-table.cjs");
+const violation_render_cjs_1 = require("./violation-render.cjs");
 // ─── Constants ────────────────────────────────────────────────────────────────
 const DISCOVERY_DIR = '.planning/discovery';
 const SESSION_COUNT = 13;
@@ -213,11 +214,6 @@ function checkProjectSessions(cwd, numbers, sessionsDir = SESSIONS_DIR) {
     const sessions = numbers.map((n) => checkProjectSession(cwd, n, sessionsDir));
     return { ok: sessions.every((s) => s.violations.length === 0), sessions };
 }
-function formatViolation(v) {
-    const where = v.line !== undefined ? `:${v.line}` : '';
-    const what = v.id !== undefined ? ` (${v.id})` : '';
-    return `  - ${v.artifact}${where}: ${v.reason}${what}`;
-}
 // ─── CLI adapter ──────────────────────────────────────────────────────────────
 /**
  * `pp-tools discovery session-check <N> [<N>…] | --all` (dotted
@@ -245,7 +241,11 @@ function cmdDiscoverySessionCheck(cwd, args, raw) {
     if (!result.ok) {
         const violations = result.sessions.flatMap((s) => s.violations);
         output({ ...payload, violations: violations.length }, raw);
-        error(`discovery session-check: ${violations.length} violation(s):\n` + violations.map(formatViolation).join('\n'), ERROR_REASON.DISCOVERY_SESSION_CHECK_FAILED);
+        // The code is the ERROR_REASON value itself (D-03); the lines come from the shared renderer (D-11).
+        errorCode(ERROR_REASON.DISCOVERY_SESSION_CHECK_FAILED, (audience) => ({
+            count: violations.length,
+            lines: violations.map((v) => (0, violation_render_cjs_1.renderViolation)('discovery.session', v, { audience, extra: { none: NONE_LITERAL } })).join('\n'),
+        }), ERROR_REASON.DISCOVERY_SESSION_CHECK_FAILED);
         return; // unreachable
     }
     output(payload, raw);

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

@@ -0,0 +1,419 @@
+"use strict";
+/**
+ * `pp-tools discovery status` (Phase 42, DOOR-01; D-01..D-08).
+ *
+ * ADR-457 build-at-publish: this TypeScript file is the SOURCE OF TRUTH. It
+ * compiles to the gitignored `pp-core/bin/lib/discovery-status.cjs`; do NOT
+ * hand-edit the compiled output.
+ *
+ * Tells a project that is only in the Discovery Sprint from one that has a build,
+ * and shows the sprint's state in the person's own wording through the Phase 41
+ * catalog: a headline count, one row per session, where the sprint stopped and
+ * the next step with its command. The wording lives in `src/messages/discovery.cts`
+ * (`discovery.status*`); this module supplies every slot.
+ *
+ * Display only: the JSON keeps the canonical status words and the canonical
+ * commands, and a status word is relabelled for the person only at the last step,
+ * when a row or a line is written (D-13). `--raw` prints the same JSON for every
+ * audience (41 D-08); only the text view follows the audience.
+ *
+ * Everything echoed from the tracker or the charter (project name, session names,
+ * charter status) is cleaned for EVERY audience, developer included, because the
+ * developer path of the catalog does not sanitise (T-42-01).
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_FILE_BYTES = exports.REGISTRY_SIZE = exports.MAX_ROWS = exports.TRACKER_FILE = void 0;
+exports.renderStatus = renderStatus;
+exports.computeStatus = computeStatus;
+exports.cmdDiscoveryStatus = cmdDiscoveryStatus;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const messages_cjs_1 = require("./messages.cjs");
+const message_labels_cjs_1 = require("./message-labels.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const io = require("./io.cjs");
+// 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 inputCheck = require("./discovery-input-check.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const charterMod = require("./discovery-charter.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planningWorkspace = require("./planning-workspace.cjs");
+const { output, ERROR_REASON } = io;
+const { SESSION_STATUS } = inputCheck;
+const { CHARTER_FILE, SIGNED_VALUES } = charterMod;
+/** Explicitly typed so TypeScript narrows after a failing guard (the destructured `io.error` does not). */
+function error(message, reason) {
+    return io.error(message, reason);
+}
+/** The progress sheet every discovery session start and prefill creates (D-01). */
+exports.TRACKER_FILE = '.planning/discovery/_progress.md';
+/** The tracker's table is examined up to the table-primitive span, never beyond (T-42-03). */
+exports.MAX_ROWS = 99;
+/**
+ * The Session Registry's size (discovery-sprint.md). Only sessions 1..13 count, a
+ * registry session with no row counts as Not Started, and the totals are always
+ * out of 13, as Flow 1 counts them (42-REVIEW WR-02).
+ */
+exports.REGISTRY_SIZE = 13;
+/** A tracker or charter larger than this is never read (T-42-03). */
+exports.MAX_FILE_BYTES = 1048576;
+/** The columns a Session Progress table must have, by lower-cased header name (D-06). */
+const REQUIRED_COLUMNS = ['#', 'session', 'status'];
+const PLACEHOLDER_PROJECT = '[PROJECT_NAME]';
+const ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+const SESSION_NUMBER_RE = /^\d{1,2}$/;
+/** Every Unicode format character (bidi overrides and isolates, zero-width, BOM, tag characters). */
+const FORMAT_CHARS_RE = /\p{Cf}/gu;
+/**
+ * A value read from a file, made safe to print for every audience: format
+ * characters removed first, then control characters stripped, whitespace
+ * collapsed and the length capped (T-42-01).
+ */
+function cleanText(v) {
+    if (typeof v !== 'string' && typeof v !== 'number')
+        return '';
+    return (0, messages_cjs_1.sanitizeParam)(String(v).replace(FORMAT_CHARS_RE, ''));
+}
+/** A table cell: cleaned, and a `|` can never add a column (T-42-02). */
+function cell(v) {
+    return cleanText(v).replace(/\|/g, '/');
+}
+/**
+ * The sprint view for one audience. Text only: every visible word comes from the
+ * catalog, every status word through `label()`, and business and engineer text
+ * ends with exactly one `Ref:` line (developer text has none).
+ */
+function renderStatus(status, audience) {
+    if (!status.in_discovery) {
+        return (0, messages_cjs_1.msg)('discovery.status.none', { file: exports.TRACKER_FILE, command: '/pp-discovery 1' }, { audience }) + '\n';
+    }
+    if (status.tracker === 'unreadable') {
+        return (0, messages_cjs_1.msg)('discovery.status.unreadable', { file: exports.TRACKER_FILE, command: '/pp-discovery' }, { audience }) + '\n';
+    }
+    const words = (code) => (0, messages_cjs_1.text)(code, {}, { audience });
+    const nameOf = (name) => cell(name) || words('discovery.status.session_unnamed');
+    const wording = (canonical) => (0, message_labels_cjs_1.label)('discovery.status', String(canonical), { audience });
+    const counts = status.counts ?? { total: 0, completed: 0, in_progress: 0, pre_filled: 0, not_started: 0 };
+    const sessions = status.sessions ?? [];
+    const out = [];
+    out.push((0, messages_cjs_1.text)('discovery.status', { project: cleanText(status.project) || words('discovery.status.project_unknown') }, { audience }));
+    out.push('');
+    out.push((0, messages_cjs_1.text)('discovery.status.counts', {
+        done: counts.completed,
+        total: counts.total,
+        in_progress: counts.in_progress,
+        pre_filled: counts.pre_filled,
+        not_started: counts.not_started,
+    }, { audience }));
+    out.push('');
+    out.push(words('discovery.status.header'));
+    for (const s of sessions) {
+        out.push(`| ${String(s.number)} | ${nameOf(s.name)} | ${wording(s.status)} |`);
+    }
+    out.push('');
+    const unknown = status.unknown_status ?? [];
+    if (unknown.length > 0) {
+        out.push((0, messages_cjs_1.text)('discovery.status.unknown_status', { sessions: unknown.join(', ') }, { audience }));
+    }
+    const stopped = status.stopped_at;
+    if (stopped !== undefined && stopped.basis === 'in_progress') {
+        out.push((0, messages_cjs_1.text)('discovery.status.stopped.in_progress', { session: stopped.session ?? '', name: nameOf(stopped.name), status: wording(stopped.status ?? '') }, { audience }));
+    }
+    else if (stopped !== undefined && stopped.basis === 'completed') {
+        out.push((0, messages_cjs_1.text)('discovery.status.stopped.completed', { session: stopped.session ?? '', name: nameOf(stopped.name) }, { audience }));
+    }
+    else {
+        out.push(words('discovery.status.stopped.none'));
+    }
+    const next = status.next;
+    if (next !== undefined) {
+        const named = (code) => {
+            const target = sessions.find((s) => s.number === next.session);
+            return (0, messages_cjs_1.text)(code, { session: next.session ?? '', name: nameOf(target === undefined ? '' : target.name), command: next.command }, { audience });
+        };
+        switch (next.kind) {
+            case 'resume':
+                out.push(named('discovery.status.next.resume'));
+                break;
+            case 'confirm':
+                out.push(named('discovery.status.next.confirm'));
+                break;
+            case 'start':
+                out.push(named('discovery.status.next.start'));
+                break;
+            case 'charter_draft':
+                out.push((0, messages_cjs_1.text)('discovery.status.next.charter_draft', { command: next.command }, { audience }));
+                break;
+            case 'charter_sign':
+                out.push((0, messages_cjs_1.text)('discovery.status.next.charter_sign', {
+                    command: next.command,
+                    charter_status: cleanText(status.charter?.status) || words('discovery.status.charter_no_status'),
+                }, { audience }));
+                break;
+            case 'to_build':
+                out.push((0, messages_cjs_1.text)('discovery.status.next.to_build', { command: next.command }, { audience }));
+                break;
+            case 'open_sprint':
+                // With a readable tracker: a session with an unrecognised status is the lowest open one (WR-03).
+                out.push((0, messages_cjs_1.text)('discovery.status.next.check_sheet', { command: next.command }, { audience }));
+                break;
+        }
+    }
+    if (audience !== 'developer')
+        out.push((0, messages_cjs_1.refLine)('discovery.status'));
+    return out.join('\n') + '\n';
+}
+// ─── computeStatus ────────────────────────────────────────────────────────────
+const CANONICAL_WORDS = [
+    SESSION_STATUS.NOT_STARTED,
+    SESSION_STATUS.PRE_FILLED,
+    SESSION_STATUS.IN_PROGRESS,
+    SESSION_STATUS.COMPLETED,
+];
+/**
+ * What is at `p`: a regular file within the size bound, something else, or nothing.
+ * The tracker is judged without following a link; the charter follows one, as
+ * `charter-check` does (42-REVIEW WR-01).
+ */
+function kindOf(p, followLink = false) {
+    try {
+        const st = followLink ? node_fs_1.default.statSync(p) : node_fs_1.default.lstatSync(p);
+        return st.isFile() && st.size <= exports.MAX_FILE_BYTES ? 'regular' : 'other';
+    }
+    catch {
+        return 'absent';
+    }
+}
+function readText(p) {
+    try {
+        return node_fs_1.default.readFileSync(p, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+/** The sessions of a tracker's `## Session Progress` table, or null when the table cannot be read (D-06, D-08). */
+function parseSessions(content) {
+    const lines = content.split(/\r?\n/);
+    const section = table.splitSections(lines, 2).find((s) => s.heading.trim().toLowerCase() === 'session progress');
+    if (section === undefined)
+        return null;
+    const parsed = table.parseTables(section.body)[0];
+    if (parsed === undefined)
+        return null;
+    const header = parsed.header.map((h) => h.trim().toLowerCase());
+    const [iNumber, iName, iStatus] = REQUIRED_COLUMNS.map((c) => header.indexOf(c));
+    if (iNumber < 0 || iName < 0 || iStatus < 0)
+        return null;
+    const iDone = header.indexOf('completed');
+    const byNumber = new Map();
+    const unknown = [];
+    for (const row of parsed.rows.slice(0, exports.MAX_ROWS)) {
+        const numberCell = (row.cells[iNumber] ?? '').trim();
+        if (!SESSION_NUMBER_RE.test(numberCell))
+            continue;
+        const number = Number(numberCell);
+        // Outside the registry: `/pp-discovery` rejects it, so it is never a session here (WR-02).
+        if (number < 1 || number > exports.REGISTRY_SIZE || byNumber.has(number))
+            continue;
+        const wordCell = (row.cells[iStatus] ?? '').trim().replace(/\s+/g, ' ').toLowerCase();
+        const canonical = CANONICAL_WORDS.find((w) => w.toLowerCase() === wordCell);
+        if (canonical === undefined)
+            unknown.push(number);
+        const doneCell = iDone >= 0 ? (row.cells[iDone] ?? '').trim() : '';
+        byNumber.set(number, {
+            number,
+            name: cleanText(row.cells[iName] ?? ''),
+            status: canonical ?? SESSION_STATUS.NOT_STARTED,
+            completed: ISO_DATE_RE.test(doneCell) ? doneCell : null,
+        });
+    }
+    if (byNumber.size === 0)
+        return null;
+    // A registry session with no row has not been held: Not Started, so a truncated
+    // tracker is never "every session done" (WR-02).
+    for (let n = 1; n <= exports.REGISTRY_SIZE; n += 1) {
+        if (!byNumber.has(n))
+            byNumber.set(n, { number: n, name: '', status: SESSION_STATUS.NOT_STARTED, completed: null });
+    }
+    const sessions = [...byNumber.values()].sort((a, b) => a.number - b.number);
+    return { sessions, unknown: unknown.sort((a, b) => a - b) };
+}
+/**
+ * The Project Charter's state, read only when every session is Completed (D-05, D-06).
+ * The status is read by `charter-check`'s own reader, so "signed" here means what
+ * `/pp-discovery-to-build`'s gate means by it (42-REVIEW WR-01).
+ */
+function charterOf(cwd) {
+    const file = node_path_1.default.join(cwd, CHARTER_FILE);
+    const kind = kindOf(file, true);
+    if (kind === 'absent')
+        return { state: 'missing', status: null };
+    let value = null;
+    if (kind === 'regular') {
+        const content = readText(file);
+        if (content !== null)
+            value = charterMod.charterStatusOf(content);
+    }
+    const signed = value !== null && SIGNED_VALUES.includes(value);
+    return { state: signed ? 'signed' : 'unsigned', status: value === null ? null : cleanText(value) || null };
+}
+/**
+ * Flow 1's rule (discovery-sprint.md, Flow 1 step 3): in progress, then pre-filled, then not started, then the charter.
+ * A session whose status word is not recognised counts as not started but is never
+ * the session to start: it may be a finished workshop with a typo (`Done`). When it
+ * is the lowest open session the next step is the sprint itself, so the sheet is
+ * checked first (42-REVIEW WR-03).
+ */
+function nextOf(sessions, unknown, charter) {
+    const unknownSet = new Set(unknown);
+    const lowest = (word) => sessions.find((s) => s.status === word && !unknownSet.has(s.number));
+    const firstUnknown = sessions.find((s) => unknownSet.has(s.number));
+    const open = [
+        [SESSION_STATUS.IN_PROGRESS, 'resume'],
+        [SESSION_STATUS.PRE_FILLED, 'confirm'],
+        [SESSION_STATUS.NOT_STARTED, 'start'],
+    ];
+    for (const [word, kind] of open) {
+        const hit = lowest(word);
+        if (kind === 'start' && firstUnknown !== undefined && (hit === undefined || firstUnknown.number < hit.number)) {
+            return { kind: 'open_sprint', session: null, command: '/pp-discovery' };
+        }
+        // The command is built from the integer session number, never from file text (T-42-05).
+        if (hit !== undefined)
+            return { kind, session: hit.number, command: `/pp-discovery ${String(hit.number)}` };
+    }
+    if (charter.state === 'missing')
+        return { kind: 'charter_draft', session: null, command: '/pp-discovery 13' };
+    if (charter.state === 'signed')
+        return { kind: 'to_build', session: null, command: '/pp-discovery-to-build' };
+    return { kind: 'charter_sign', session: null, command: '/pp-discovery charter' };
+}
+/** Where the sprint stopped (D-08): the lowest In Progress session, else the one completed last, else nowhere. */
+function stoppedOf(sessions) {
+    const inProgress = sessions.find((s) => s.status === SESSION_STATUS.IN_PROGRESS);
+    if (inProgress !== undefined) {
+        return { basis: 'in_progress', session: inProgress.number, name: inProgress.name, status: SESSION_STATUS.IN_PROGRESS };
+    }
+    const done = sessions.filter((s) => s.status === SESSION_STATUS.COMPLETED);
+    if (done.length === 0)
+        return { basis: 'none', session: null, name: null, status: null };
+    let best = done[0];
+    for (const s of done) {
+        // Sessions are sorted by number, so `>=` makes a tie, or a blank date, go to the higher number.
+        if ((s.completed ?? '') >= (best.completed ?? ''))
+            best = s;
+    }
+    return { basis: 'completed', session: best.number, name: best.name, status: SESSION_STATUS.COMPLETED };
+}
+/**
+ * The sprint's state for `cwd`. Read-only and never throws: every file step has
+ * its own guard, and a workspace setting that cannot be resolved answers "not
+ * discovery-only", so a broken workstream setup keeps today's routing (research A4).
+ */
+function computeStatus(cwd) {
+    let projectExists = false;
+    let roadmapExists = false;
+    let workspaceError = false;
+    try {
+        // The resolvers init.progress and init.resume use (D-02). STATE.md is never read.
+        projectExists = planningWorkspace.resolveProjectFile(cwd).exists;
+        roadmapExists = node_fs_1.default.existsSync(node_path_1.default.join(planningWorkspace.planningDir(cwd), 'ROADMAP.md'));
+    }
+    catch {
+        projectExists = false;
+        roadmapExists = false;
+        workspaceError = true;
+    }
+    const hasBuild = projectExists || roadmapExists;
+    let trackerPath = '';
+    let trackerKind = 'absent';
+    try {
+        trackerPath = node_path_1.default.join(planningWorkspace.planningRoot(cwd), 'discovery', '_progress.md');
+        trackerKind = kindOf(trackerPath);
+    }
+    catch {
+        trackerKind = 'absent';
+    }
+    const facts = {
+        has_build: hasBuild,
+        project_exists: projectExists,
+        roadmap_exists: roadmapExists,
+        workspace_error: workspaceError,
+    };
+    if (trackerKind === 'absent') {
+        return { discovery_only: false, in_discovery: false, ...facts, tracker: 'absent' };
+    }
+    const discoveryOnly = !hasBuild && !workspaceError;
+    const unreadable = (project) => ({
+        discovery_only: discoveryOnly,
+        in_discovery: true,
+        ...facts,
+        tracker: 'unreadable',
+        project,
+        next: { kind: 'open_sprint', session: null, command: '/pp-discovery' },
+    });
+    try {
+        const content = trackerKind === 'regular' ? readText(trackerPath) : null;
+        if (content === null)
+            return unreadable(null);
+        let project = null;
+        for (const line of content.split(/\r?\n/)) {
+            const m = /^\*\*Project:\*\*\s*(.+)$/.exec(line);
+            if (m !== null) {
+                const name = cleanText(m[1]);
+                project = name === '' || name === PLACEHOLDER_PROJECT ? null : name;
+                break;
+            }
+        }
+        const parsed = parseSessions(content);
+        if (parsed === null)
+            return unreadable(project);
+        const { sessions, unknown } = parsed;
+        const count = (word) => sessions.filter((s) => s.status === word).length;
+        const counts = {
+            total: sessions.length,
+            completed: count(SESSION_STATUS.COMPLETED),
+            in_progress: count(SESSION_STATUS.IN_PROGRESS),
+            pre_filled: count(SESSION_STATUS.PRE_FILLED),
+            not_started: count(SESSION_STATUS.NOT_STARTED),
+        };
+        // The charter matters only once all 13 sessions are Completed; until then it is not read.
+        const charter = counts.completed === exports.REGISTRY_SIZE ? charterOf(cwd) : { state: 'not_checked', status: null };
+        return {
+            discovery_only: discoveryOnly,
+            in_discovery: true,
+            ...facts,
+            tracker: 'ok',
+            project,
+            counts,
+            sessions,
+            unknown_status: unknown,
+            stopped_at: stoppedOf(sessions),
+            charter,
+            next: nextOf(sessions, unknown, charter),
+        };
+    }
+    catch {
+        return unreadable(null);
+    }
+}
+/**
+ * `pp-tools discovery status [--raw]`. `--raw` prints the JSON, the same for every
+ * audience (41 D-08); without it the view is printed in the person's wording.
+ * Do not copy `cmdProgressRender`, whose `--raw` prints audience text (41-REVIEW WR-05).
+ */
+function cmdDiscoveryStatus(cwd, args, raw) {
+    if (args.slice(2).length > 0)
+        error('Usage: pp-tools discovery status [--raw]', ERROR_REASON.USAGE);
+    const status = computeStatus(cwd);
+    if (raw)
+        output(status, false);
+    else
+        output(status, true, renderStatus(status, (0, messages_cjs_1.audienceOf)(process.env)));
+}

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');
+}