@pareto4/pp-core 1.21.1 → 1.23.1

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/discovery-stories.cjs

@@ -17,8 +17,12 @@
  *     `_requirements.md` when it is on file and parseable;
  *   - `Story` and `Acceptance criteria` are non-empty;
  *   - `Acceptance criteria` is a criterion, not a pointer (`As in F-01`);
- *   - `Source step` is `—` or a comma list of `MP-nn #<cell>`, the main process
- *     and the step row existing in `_processes.md` when it is on file;
+ *   - `Source step` is a comma list of `MP-nn #<cell>`, the main process and
+ *     the step row existing in `_processes.md` when it is on file — a story
+ *     tied to no step (`—`) is refused (Session 3 rework: stories come from
+ *     steps);
+ *   - every persona-actor step that realises an MVP requirement is the
+ *     source step of at least one story, so the stories cover the processes;
  *   - every MVP-disposition requirement that a persona-actor step cites has at
  *     least one story (the `N-`/`T-` prefixes never need one; a requirement
  *     only `System` steps realise, or no step at all, has no user to tell it).
@@ -118,6 +122,23 @@ function needsStory(r, steps) {
         return true;
     return steps.some((s) => s.requirements.includes(r.id) && s.actors.some((a) => a !== SYSTEM_ACTOR));
 }
+/**
+ * Does this step need a story naming it as its source? A step a persona
+ * performs does, when it realises an MVP requirement that is not `N-`/`T-`.
+ * With no parseable `_requirements.md` every persona step does; a step that
+ * cites nothing yet is `process-check --require-cited`'s finding, not this one.
+ */
+function stepNeedsStory(step, requirements) {
+    if (!step.actors.some((a) => a !== SYSTEM_ACTOR))
+        return false;
+    if (!(requirements instanceof Array))
+        return true;
+    const byId = new Map(requirements.map((r) => [r.id, r]));
+    return step.requirements.some((id) => {
+        const r = byId.get(id);
+        return r !== undefined && r.disposition === rollup.DISPOSITIONS.MVP && !STORYLESS_PREFIXES.includes(r.prefix);
+    });
+}
 // ─── Check ────────────────────────────────────────────────────────────────────
 function checkStories(content, sources) {
     const violations = [];
@@ -137,6 +158,7 @@ function checkStories(content, sources) {
     const ids = new Set();
     const seqs = [];
     const storied = new Set();
+    const sourced = new Set();
     for (const row of tables[0].rows) {
         const [id, epic, requirements, story, acceptance, sourceStep] = row.cells.map((c) => c.trim());
         const m = US_RE.exec(id ?? '');
@@ -170,11 +192,13 @@ function checkStories(content, sources) {
                 storied.add(r);
         }
         const src = sourceStep ?? '';
-        if (src !== PENDING) {
+        if (src === PENDING || src === '') {
+            violations.push({ artifact: STORIES_FILE, reason: 'no_source_step', line: row.line, id: m ? id : undefined });
+        }
+        else {
             const refs = splitList(src);
-            if (refs.length === 0)
-                violations.push({ artifact: STORIES_FILE, reason: 'bad_source_step', line: row.line });
             for (const ref of refs) {
+                sourced.add(ref);
                 const sm = SOURCE_STEP_RE.exec(ref);
                 if (!sm)
                     violations.push({ artifact: STORIES_FILE, reason: 'bad_source_step', line: row.line });
@@ -193,6 +217,12 @@ function checkStories(content, sources) {
                 violations.push({ artifact: STORIES_FILE, reason: 'sequence_gap', id: `US-${String(n).padStart(2, '0')}` });
         }
     }
+    for (const step of sources.steps ?? []) {
+        if (!stepNeedsStory(step, sources.requirements))
+            continue;
+        if (!sourced.has(step.key))
+            violations.push({ artifact: PROCESSES_FILE, reason: 'step_without_story', id: step.key.slice(0, 40) });
+    }
     if (sources.requirements instanceof Array) {
         for (const r of sources.requirements) {
             if (r.disposition !== rollup.DISPOSITIONS.MVP)
@@ -266,6 +296,7 @@ module.exports = {
     STORYLESS_PREFIXES,
     SYSTEM_ACTOR,
     needsStory,
+    stepNeedsStory,
     STORIES_CHECK_FAILED: ERROR_REASON.DISCOVERY_STORIES_CHECK_FAILED,
     checkStories,
     checkProjectStories,