@pareto4/pp-core 1.21.1 → 1.23.1

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

@@ -0,0 +1,271 @@
+"use strict";
+/**
+ * `pp-tools audience status|set|answer|fields`: the CLI adapter over the per-person
+ * audience setting (Phase 39: AUD-01, AUD-04; D-12, D-14; `fields` is Phase 40 CR-01).
+ *
+ * ADR-457 build-at-publish: this TypeScript file is the SOURCE OF TRUTH. It
+ * compiles to the gitignored `pp-core/bin/lib/audience-command.cjs`; do NOT
+ * hand-edit the compiled output.
+ *
+ * The person file is read and written only through `./audience.cjs`. Nothing
+ * here touches `.planning/config.json`, `~/.gsd/defaults.json` or any
+ * discovery file (D-01, D-13). `status` prints short human lines by default and
+ * one JSON object with `--raw`; workflows always call it with `--raw`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildAudienceStatus = buildAudienceStatus;
+exports.cmdAudience = cmdAudience;
+const audience_cjs_1 = require("./audience.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 configLoader = require("./config-loader.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- init.cjs is an export= CommonJS module
+const initMod = require("./init.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 AUDIENCE_LIST = audience_cjs_1.AUDIENCES.join(', ');
+const LANGUAGE_LIST = audience_cjs_1.LANGUAGES.join(', ');
+const SET_USAGE = 'Usage: pp-tools audience set <business|engineer|developer> [--language en | --clear-language], ' +
+    'or pp-tools audience set --clear-language (clears only the language)';
+const CHANGE_LINE = 'change:   pp-tools audience set <business|engineer|developer> [--language en | --clear-language]';
+/** Cut to 40 characters and strip control characters before a value enters a message. */
+function clip(v) {
+    return String(v).replace(/[\u0000-\u001f\u007f-\u009f]/g, '').slice(0, 40);
+}
+/** The project's `response_language`, or null when there is none (or no project here). */
+function projectResponseLanguage(cwd) {
+    try {
+        const rl = configLoader.loadConfig(cwd).response_language;
+        if (typeof rl === 'string' && rl.trim() !== '')
+            return rl;
+    }
+    catch {
+        // no project here: the project tier is simply absent
+    }
+    return null;
+}
+function buildAudienceStatus(cwd, env = process.env) {
+    const person = (0, audience_cjs_1.readPerson)(env);
+    const aud = (0, audience_cjs_1.resolveAudience)(env, person);
+    const projectLanguage = projectResponseLanguage(cwd);
+    const lang = (0, audience_cjs_1.resolveLanguage)({ env, person, projectResponseLanguage: projectLanguage });
+    const choice = (0, audience_cjs_1.needsChoice)(env, person);
+    const status = {
+        audience: aud.audience,
+        audience_source: aud.source,
+        language: lang.code,
+        language_name: lang.name,
+        language_source: lang.source,
+        person_file: (0, audience_cjs_1.personFilePath)(env),
+        person_file_exists: person.exists,
+        needs_choice: choice,
+        warnings: aud.warnings,
+    };
+    if (choice)
+        status.prompt = audience_cjs_1.FIRST_RUN_PROMPT;
+    return status;
+}
+const AUDIENCE_LABEL = {
+    environment: 'from PP_AUDIENCE',
+    person_file: 'from person file',
+    default: 'default — nothing set',
+};
+const LANGUAGE_LABEL = {
+    person_file: 'from person file',
+    audience: 'from audience',
+    project: 'from project response_language',
+};
+function languageLine(s) {
+    if (s.language_source === 'none')
+        return 'language: not set';
+    return `language: ${String(s.language_name)} (${s.language ?? '-'}, ${LANGUAGE_LABEL[s.language_source]})`;
+}
+function humanStatus(s) {
+    return [
+        `audience: ${s.audience} (${AUDIENCE_LABEL[s.audience_source]})`,
+        languageLine(s),
+        `file:     ${s.person_file} (${s.person_file_exists ? 'present' : 'absent'})`,
+        CHANGE_LINE,
+    ].join('\n');
+}
+function warn(text) {
+    process.stderr.write(`pp-tools: warning: ${text}\n`);
+}
+function cmdStatus(cwd, raw) {
+    const status = buildAudienceStatus(cwd);
+    for (const w of status.warnings)
+        warn(w);
+    if (raw)
+        output(status, false);
+    else
+        output(status, true, humanStatus(status));
+}
+/**
+ * Phase 40 CR-01: the audience fields an `init.*` payload carries, before any init call. A
+ * business user or business engineer gets one JSON object (`audience`, `audience_ref`,
+ * `response_language`) built by the same code as the payload; a developer gets no output at
+ * all, so a developer run loads nothing new (D-07). Workflows that ask the person something
+ * before their first init call run this first. Review iteration 2, WR-02: extra arguments are
+ * refused with a usage error, so a malformed call exits non-zero instead of looking like a
+ * developer run.
+ */
+function cmdFields(cwd, args) {
+    if (args.length > 0)
+        error('Usage: pp-tools audience fields (takes no arguments)', ERROR_REASON.USAGE);
+    const fields = initMod.audienceFields(projectResponseLanguage(cwd));
+    if (Object.keys(fields).length > 0)
+        output(fields, false);
+}
+/**
+ * Validate-then-write shared by `set` and `answer`; everything is checked before
+ * anything is written. `language` undefined keeps the stored language (CR-01).
+ */
+function save(cwd, audience, language, raw) {
+    const result = (0, audience_cjs_1.writePerson)(language === undefined ? { audience } : { audience, language });
+    if (!result.ok) {
+        error(`Could not save ${result.path}: ${result.error}`, ERROR_REASON.AUDIENCE_WRITE_FAILED);
+    }
+    const envOverride = (process.env['PP_AUDIENCE'] || '').trim().toLowerCase();
+    if ((0, audience_cjs_1.isAudience)(envOverride))
+        warn(`PP_AUDIENCE=${envOverride} overrides the saved value in this shell`);
+    const status = buildAudienceStatus(cwd);
+    for (const w of status.warnings)
+        warn(w);
+    if (raw) {
+        output({ ...status, saved: true }, false);
+        return;
+    }
+    const langText = status.language_source === 'person_file' ? `${status.language ?? '-'}` : 'not set';
+    output({ ...status, saved: true }, true, `Saved: audience ${audience} (language: ${langText}) in ${result.path}\n${CHANGE_LINE}`);
+}
+/**
+ * WR-11: `set --clear-language` without an audience removes only the stored
+ * language. The stored audience is never read back and re-saved, so a
+ * `PP_AUDIENCE` override (D-12) or a default audience cannot leak into the file.
+ */
+function clearLanguageOnly(cwd, raw) {
+    const result = (0, audience_cjs_1.writePerson)({ language: null });
+    if (!result.ok) {
+        error(`Could not save ${result.path}: ${result.error}`, ERROR_REASON.AUDIENCE_WRITE_FAILED);
+    }
+    const status = buildAudienceStatus(cwd);
+    for (const w of status.warnings)
+        warn(w);
+    const payload = { ...status, saved: result.written };
+    if (raw) {
+        output(payload, false);
+        return;
+    }
+    const text = result.written
+        ? `Cleared the language in ${result.path}; the audience decides it again (audience unchanged).`
+        : `No language is saved in ${result.path}; nothing changed.`;
+    output(payload, true, `${text}\n${CHANGE_LINE}`);
+}
+function cmdSet(cwd, args, raw) {
+    let value = null;
+    let language = null;
+    let languageGiven = false;
+    let clearLanguage = false;
+    for (let i = 0; i < args.length; i++) {
+        const a = String(args[i]);
+        if (a === '--clear-language') {
+            clearLanguage = true;
+        }
+        else if (a === '--language') {
+            languageGiven = true;
+            const next = args[i + 1];
+            if (next === undefined || next.startsWith('--'))
+                error(SET_USAGE, ERROR_REASON.USAGE);
+            language = String(next);
+            i += 1;
+        }
+        else if (a.startsWith('--language=')) {
+            languageGiven = true;
+            language = a.slice('--language='.length);
+        }
+        else if (value === null) {
+            value = a;
+        }
+        else {
+            error(SET_USAGE, ERROR_REASON.USAGE);
+        }
+    }
+    if (value === null) {
+        if (clearLanguage && !languageGiven) {
+            clearLanguageOnly(cwd, raw);
+            return;
+        }
+        error(SET_USAGE, ERROR_REASON.USAGE);
+    }
+    const audience = value.trim().toLowerCase();
+    if (!(0, audience_cjs_1.isAudience)(audience)) {
+        error(`Unknown audience "${clip(value)}". Use one of: ${AUDIENCE_LIST}.`, ERROR_REASON.USAGE);
+    }
+    if (languageGiven && clearLanguage)
+        error(SET_USAGE, ERROR_REASON.USAGE);
+    // D-10 / CR-01: without --language the stored language is kept (undefined);
+    // --clear-language removes it so the audience decides again.
+    let lang = clearLanguage ? null : undefined;
+    if (languageGiven) {
+        const l = (language ?? '').trim().toLowerCase();
+        if (l === '')
+            error(SET_USAGE, ERROR_REASON.USAGE);
+        if (!(0, audience_cjs_1.isLanguage)(l)) {
+            error(`Unknown language "${clip(language)}". Use one of: ${LANGUAGE_LIST}.`, ERROR_REASON.USAGE);
+        }
+        lang = l;
+    }
+    save(cwd, audience, lang, raw);
+}
+/**
+ * The first-run relay seam (D-06). It only ever fills an empty setting: a chat
+ * relay cannot send Enter on purpose, so a missing or blank reply is refused
+ * rather than read as `developer` (Enter-means-developer lives only in the
+ * installer's TTY prompt), and an existing valid audience is never overwritten
+ * (WR-01). Changing a saved audience is `audience set`.
+ */
+function cmdAnswer(cwd, args, raw) {
+    if (args.length === 0)
+        error('Usage: pp-tools audience answer <reply>', ERROR_REASON.USAGE);
+    const person = (0, audience_cjs_1.readPerson)();
+    if (person.audience !== null) {
+        error(`An audience is already saved (${person.audience}). Change it with: pp-tools audience set <${audience_cjs_1.AUDIENCES.join('|')}>`, ERROR_REASON.USAGE);
+    }
+    // WR-10: join every argv word, so an unquoted "Business engineer" is read
+    // whole and quoting by the relay is not load-bearing.
+    const reply = args.map(String).join(' ');
+    if (reply.trim() === '')
+        error(`Answer 1, 2 or 3 (${AUDIENCE_LIST}).`, ERROR_REASON.USAGE);
+    const audience = (0, audience_cjs_1.parseAudienceInput)(reply);
+    if (audience === null) {
+        error(`Not recognised: "${clip(reply)}". Answer 1, 2 or 3 (${AUDIENCE_LIST}).`, ERROR_REASON.USAGE);
+    }
+    save(cwd, audience, undefined, raw);
+}
+function cmdAudience(cwd, args, raw) {
+    const sub = args[0];
+    const rest = args.slice(1);
+    switch (sub) {
+        case 'status':
+            cmdStatus(cwd, raw);
+            return;
+        case 'set':
+            cmdSet(cwd, rest, raw);
+            return;
+        case 'answer':
+            cmdAnswer(cwd, rest, raw);
+            return;
+        case 'fields':
+            cmdFields(cwd, rest);
+            return;
+        case undefined:
+            error('Usage: pp-tools audience <status|set|answer|fields> ...', ERROR_REASON.USAGE);
+            return;
+        default:
+            error(`Unknown audience subcommand: ${clip(sub)}. Available: status, set, answer, fields`, ERROR_REASON.SDK_UNKNOWN_COMMAND);
+    }
+}

package/pp-core/bin/lib/audience.cjs

@@ -0,0 +1,293 @@
+"use strict";
+/**
+ * Per-person audience setting (Phase 39: AUD-01, AUD-04).
+ *
+ * ADR-457 build-at-publish: this TypeScript file is the SOURCE OF TRUTH. It
+ * compiles to the gitignored `pp-core/bin/lib/audience.cjs`; do NOT hand-edit
+ * the compiled output.
+ *
+ * This leaf is the ONLY reader and writer of the person file
+ * (`~/.gsd/person.json`, or under `GSD_HOME` when set; D-01). It imports Node
+ * built-ins only, so `io.cts` and the hooks can require it later without an
+ * import cycle. The locale (`LANG`, `LC_*`) is never read (D-02): a Dutch
+ * laptop must not silently change output for current users. The person file
+ * never enters `.planning/config.json` or `~/.gsd/defaults.json` (D-01).
+ *
+ * Audience order: `PP_AUDIENCE` env, then the person file, then `developer`.
+ * Language order (D-04): the person's explicit language, then the language the
+ * audience implies (business en, engineer en, developer none), then the
+ * project's `response_language`. English only since 2026-11-13 (operator: Dutch
+ * dropped from v1.23.0); the list shape allows adding a language later.
+ *
+ * Nothing here throws. Readers return a value plus `warnings`; the CLI adapter
+ * prints them.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FIRST_RUN_PROMPT = exports.PERSON_FILE_MAX_BYTES = exports.PERSON_FILE_VERSION = exports.LANGUAGE_NAMES = exports.IMPLIED_LANGUAGE = exports.LANGUAGES = exports.AUDIENCES = void 0;
+exports.isAudience = isAudience;
+exports.isLanguage = isLanguage;
+exports.personFilePath = personFilePath;
+exports.readPerson = readPerson;
+exports.writePerson = writePerson;
+exports.resolveAudience = resolveAudience;
+exports.resolveLanguage = resolveLanguage;
+exports.needsChoice = needsChoice;
+exports.parseAudienceInput = parseAudienceInput;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+exports.AUDIENCES = ['business', 'engineer', 'developer'];
+exports.LANGUAGES = ['en'];
+/** The language each audience implies; `developer` implies none (D-04). */
+exports.IMPLIED_LANGUAGE = {
+    business: 'en',
+    engineer: 'en',
+    developer: null,
+};
+exports.LANGUAGE_NAMES = { en: 'English' };
+exports.PERSON_FILE_VERSION = 1;
+exports.PERSON_FILE_MAX_BYTES = 4096;
+/**
+ * The first-run question (D-06, D-09): plain English (Dutch dropped 2026-11-13).
+ * Rendered from this single constant by the installer and (via
+ * `audience status --raw`) /pp-init and /pp-discovery. /pp-settings asks it as
+ * an AskUserQuestion with these same labels and descriptions, pinned by
+ * tests/feat-2527-settings-layers.test.cjs (WR-06).
+ */
+exports.FIRST_RUN_PROMPT = [
+    'Who are you?',
+    'This decides how pp-core talks to you.',
+    '',
+    '  1) Business user',
+    '     Plain words, no technical terms.',
+    '  2) Business engineer',
+    '     Plain English; you know the technology.',
+    '  3) Developer',
+    '     As today.',
+    '',
+    'Choose 1, 2 or 3 [3]:',
+].join('\n') + '\n';
+const AUDIENCE_LIST = exports.AUDIENCES.join(', ');
+const LANGUAGE_LIST = exports.LANGUAGES.join(', ');
+function isAudience(v) {
+    return typeof v === 'string' && exports.AUDIENCES.includes(v);
+}
+function isLanguage(v) {
+    return typeof v === 'string' && exports.LANGUAGES.includes(v);
+}
+/** Cut to 40 characters and strip control characters before a value enters a message. */
+function clip(v) {
+    return String(v).replace(/[\u0000-\u001f\u007f-\u009f]/g, '').slice(0, 40);
+}
+function norm(v) {
+    return typeof v === 'string' ? v.trim().toLowerCase() : '';
+}
+/** Same root rule as config-loader's `_globalDefaultsPath`, so GSD_HOME redirects both. */
+function personFilePath(env = process.env) {
+    return node_path_1.default.join(env['GSD_HOME'] || node_os_1.default.homedir(), '.gsd', 'person.json');
+}
+const POLLUTING_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+/** Parse the stored file tolerantly: any failure is reported as a warning, never thrown. */
+function loadStored(file) {
+    let size;
+    try {
+        size = node_fs_1.default.statSync(file).size;
+    }
+    catch {
+        return { obj: null, exists: false, warning: null };
+    }
+    if (size > exports.PERSON_FILE_MAX_BYTES) {
+        return { obj: null, exists: true, warning: `${file}: larger than ${exports.PERSON_FILE_MAX_BYTES} bytes — ignored` };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(node_fs_1.default.readFileSync(file, 'utf8'));
+    }
+    catch {
+        return { obj: null, exists: true, warning: `${file}: not valid JSON — ignored` };
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return { obj: null, exists: true, warning: `${file}: not a JSON object — ignored` };
+    }
+    return { obj: parsed, exists: true, warning: null };
+}
+function readPerson(env = process.env) {
+    const person = { audience: null, language: null, exists: false, warnings: [] };
+    try {
+        const file = personFilePath(env);
+        const stored = loadStored(file);
+        person.exists = stored.exists;
+        if (stored.warning)
+            person.warnings.push(stored.warning);
+        const obj = stored.obj;
+        if (!obj)
+            return person;
+        const own = (k) => Object.prototype.hasOwnProperty.call(obj, k);
+        if (own('audience')) {
+            const a = norm(obj['audience']);
+            if (isAudience(a))
+                person.audience = a;
+            else
+                person.warnings.push(`${file}: audience "${clip(obj['audience'])}" is not one of ${AUDIENCE_LIST} — ignored`);
+        }
+        if (own('language')) {
+            const l = norm(obj['language']);
+            if (isLanguage(l))
+                person.language = l;
+            else
+                person.warnings.push(`${file}: language "${clip(obj['language'])}" is not one of ${LANGUAGE_LIST} — ignored`);
+        }
+    }
+    catch (e) {
+        person.warnings.push(`person file could not be read: ${clip(e.message)}`);
+    }
+    return person;
+}
+/**
+ * Save the audience. `language` is three-state (D-10, CR-01): a value sets the
+ * override, `null` removes it, and an omitted/`undefined` language keeps
+ * whatever is stored, so callers that never ask about language cannot erase it.
+ *
+ * WR-11: `{ language: null }` without an audience clears only the language and
+ * leaves the stored `audience` key exactly as it is, so a hint that clears the
+ * language never has to name (and so never overwrites) an audience. When there
+ * is no stored `language` key to remove, nothing is written (`written: false`):
+ * a language clear never creates a person file or rewrites one it cannot parse.
+ */
+function writePerson(update, env = process.env) {
+    const file = personFilePath(env);
+    let tmp = null;
+    try {
+        // Key-preserving read-modify-write: a whole-file rewrite that drops keys is
+        // the defect that ruled out defaults.json (D-01).
+        const next = {};
+        const stored = loadStored(file).obj;
+        if (update.audience === undefined && !(stored && Object.prototype.hasOwnProperty.call(stored, 'language'))) {
+            return { ok: true, path: file, written: false };
+        }
+        const dir = node_path_1.default.dirname(file);
+        node_fs_1.default.mkdirSync(dir, { recursive: true });
+        if (stored) {
+            for (const k of Object.keys(stored)) {
+                if (!POLLUTING_KEYS.has(k))
+                    next[k] = stored[k];
+            }
+        }
+        next['version'] = exports.PERSON_FILE_VERSION;
+        if (update.audience !== undefined)
+            next['audience'] = update.audience;
+        if (update.language)
+            next['language'] = update.language;
+        else if (update.language === null)
+            delete next['language'];
+        tmp = node_path_1.default.join(dir, `person.json.tmp-${process.pid}-${Math.random().toString(16).slice(2, 10)}`);
+        node_fs_1.default.writeFileSync(tmp, JSON.stringify(next, null, 2) + '\n');
+        node_fs_1.default.renameSync(tmp, file);
+        return { ok: true, path: file, written: true };
+    }
+    catch (e) {
+        if (tmp) {
+            try {
+                node_fs_1.default.unlinkSync(tmp);
+            }
+            catch { /* best effort */ }
+        }
+        return { ok: false, path: file, error: e.message };
+    }
+}
+/** The valid PP_AUDIENCE value, or null; an invalid non-empty value is reported via `warnings`. */
+function readEnvAudience(env) {
+    const raw = env['PP_AUDIENCE'];
+    const v = norm(raw);
+    if (v === '')
+        return { value: null, warning: null };
+    if (isAudience(v))
+        return { value: v, warning: null };
+    return { value: null, warning: `PP_AUDIENCE "${clip(raw)}" is not one of ${AUDIENCE_LIST} — ignored` };
+}
+function resolveAudience(env, person) {
+    const fromEnv = readEnvAudience(env);
+    const warnings = [];
+    if (fromEnv.warning)
+        warnings.push(fromEnv.warning);
+    warnings.push(...person.warnings);
+    if (fromEnv.value)
+        return { audience: fromEnv.value, source: 'environment', warnings };
+    if (person.audience)
+        return { audience: person.audience, source: 'person_file', warnings };
+    return { audience: 'developer', source: 'default', warnings };
+}
+function resolveLanguage(input) {
+    const { env, person, projectResponseLanguage } = input;
+    if (person.language) {
+        return { code: person.language, name: exports.LANGUAGE_NAMES[person.language], source: 'person_file' };
+    }
+    const { audience } = resolveAudience(env, person);
+    const implied = exports.IMPLIED_LANGUAGE[audience];
+    if (implied)
+        return { code: implied, name: exports.LANGUAGE_NAMES[implied], source: 'audience' };
+    if (typeof projectResponseLanguage === 'string' && projectResponseLanguage.trim() !== '') {
+        return { code: null, name: projectResponseLanguage, source: 'project' };
+    }
+    return { code: null, name: null, source: 'none' };
+}
+/** True only when no valid setting exists anywhere: no usable PP_AUDIENCE and no valid person file. */
+function needsChoice(env, person) {
+    return readEnvAudience(env).value === null && person.audience === null;
+}
+const NUMBERED_AUDIENCE = new Map([
+    ['1', 'business'],
+    ['2', 'engineer'],
+    ['3', 'developer'],
+]);
+/** Option labels (D-09); lower-case, single spaces. */
+const NAMED_AUDIENCE = new Map([
+    ['business', 'business'],
+    ['business user', 'business'],
+    ['engineer', 'engineer'],
+    ['business engineer', 'engineer'],
+    ['developer', 'developer'],
+]);
+/**
+ * Map a first-run reply to an audience. Enter or whitespace means `developer`;
+ * `null`/`undefined` (no reply at all) and anything unrecognised give null.
+ *
+ * Replies are normalised before matching (WR-05), because a relaying agent
+ * most often echoes the chosen option line: a leading option number
+ * (`2) Business engineer`), a trailing `(3)`, and each half of a
+ * `a / b` label are all read. Every part that names an audience
+ * must agree; unknown text or a contradiction (`1) Business engineer`) gives
+ * null rather than a guess.
+ */
+function parseAudienceInput(answer) {
+    if (typeof answer !== 'string' && typeof answer !== 'number')
+        return null;
+    const s = String(answer).trim().toLowerCase();
+    if (s === '')
+        return 'developer';
+    const found = new Set();
+    let rest = s;
+    const lead = /^([123])(?![0-9])[).:\s-]*/.exec(rest);
+    if (lead) {
+        found.add(NUMBERED_AUDIENCE.get(lead[1]));
+        rest = rest.slice(lead[0].length);
+    }
+    const trail = /\s*\(([123])\)$/.exec(rest);
+    if (trail) {
+        found.add(NUMBERED_AUDIENCE.get(trail[1]));
+        rest = rest.slice(0, trail.index);
+    }
+    for (const half of rest.split('/')) {
+        const label = half.trim().replace(/[).:!]+$/, '').replace(/\s+/g, ' ');
+        if (label === '')
+            continue;
+        const named = NAMED_AUDIENCE.get(label);
+        if (!named)
+            return null;
+        found.add(named);
+    }
+    return found.size === 1 ? [...found][0] : null;
+}

package/pp-core/bin/lib/commands.cjs

@@ -47,6 +47,8 @@ const { extractFrontmatter } = frontmatter;
 const modelProfiles = require("./model-profiles.cjs");
 const { MODEL_PROFILES, VALID_PHASE_TYPES } = modelProfiles;
 const runtime_slash_cjs_1 = require("./runtime-slash.cjs");
+const messages_cjs_1 = require("./messages.cjs");
+const message_labels_cjs_1 = require("./message-labels.cjs");
 // 16-03: the one `.planning/` path test. The seal leaf's top level imports only
 // Node built-ins and it never requires this module, so the edge adds no cycle.
 // eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -909,17 +911,20 @@ function cmdProgressRender(cwd, format, raw) {
     catch { /* intentionally empty */ }
     const percent = totalPlans > 0 ? Math.min(100, Math.round((totalSummaries / totalPlans) * 100)) : 0;
     if (format === 'table') {
-        // Render markdown table
+        // Render markdown table. Display text only: the status cell is the canonical
+        // word relabelled here, at the last step, and nothing reads it back (D-13).
+        const audience = (0, messages_cjs_1.audienceOf)(process.env);
         const barWidth = 10;
         const filled = Math.round((percent / 100) * barWidth);
         const bar = '█'.repeat(filled) + '░'.repeat(barWidth - filled);
-        let out = `# ${milestone.version} ${milestone.name}\n\n`;
-        out += `**Progress:** [${bar}] ${totalSummaries}/${totalPlans} plans (${percent}%)\n\n`;
-        out += `| Phase | Name | Plans | Status |\n`;
-        out += `|-------|------|-------|--------|\n`;
+        let out = (0, messages_cjs_1.text)('progress.table', { version: milestone.version, name: milestone.name }, { audience }) + '\n\n';
+        out += (0, messages_cjs_1.text)('progress.table.progress', { bar, done: totalSummaries, total: totalPlans, percent }, { audience }) + '\n\n';
+        out += (0, messages_cjs_1.text)('progress.table.header', {}, { audience }) + '\n';
         for (const p of phases) {
-            out += `| ${p.number} | ${p.name} | ${p.summaries}/${p.plans} | ${p.status} |\n`;
+            out += `| ${p.number} | ${p.name} | ${p.summaries}/${p.plans} | ${(0, message_labels_cjs_1.label)('phase.status', p.status, { audience })} |\n`;
         }
+        if (audience !== 'developer')
+            out += (0, messages_cjs_1.refLine)('progress.table') + '\n';
         output({ rendered: out }, raw, out);
     }
     else if (format === 'bar') {
@@ -1279,32 +1284,36 @@ function cmdStats(cwd, format, raw) {
         last_activity: lastActivity,
     };
     if (format === 'table') {
+        // Display text only: the status cell is the canonical word relabelled here,
+        // at the last step; completedPhases above is counted on the canonical word (D-13).
+        const audience = (0, messages_cjs_1.audienceOf)(process.env);
         const barWidth = 10;
         const filled = Math.round((percent / 100) * barWidth);
         const bar = '█'.repeat(filled) + '░'.repeat(barWidth - filled);
-        let out = `# ${milestone.version} ${milestone.name} — Statistics\n\n`;
-        out += `**Progress:** [${bar}] ${completedPhases}/${phases.length} phases (${percent}%)\n`;
+        let out = (0, messages_cjs_1.text)('stats.table', { version: milestone.version, name: milestone.name }, { audience }) + '\n\n';
+        out += (0, messages_cjs_1.text)('stats.table.progress', { bar, done: completedPhases, total: phases.length, percent }, { audience }) + '\n';
         if (totalPlans > 0) {
-            out += `**Plans:** ${totalSummaries}/${totalPlans} complete (${planPercent}%)\n`;
+            out += (0, messages_cjs_1.text)('stats.table.plans', { done: totalSummaries, total: totalPlans, percent: planPercent }, { audience }) + '\n';
         }
-        out += `**Phases:** ${completedPhases}/${phases.length} complete\n`;
+        out += (0, messages_cjs_1.text)('stats.table.phases', { done: completedPhases, total: phases.length }, { audience }) + '\n';
         if (requirementsTotal > 0) {
-            out += `**Requirements:** ${requirementsComplete}/${requirementsTotal} complete\n`;
+            out += (0, messages_cjs_1.text)('stats.table.requirements', { done: requirementsComplete, total: requirementsTotal }, { audience }) + '\n';
         }
         out += '\n';
-        out += `| Phase | Name | Plans | Completed | Status | Wall-clock |\n`;
-        out += `|-------|------|-------|-----------|--------|------------|\n`;
+        out += (0, messages_cjs_1.text)('stats.table.header', {}, { audience }) + '\n';
         for (const p of phases) {
-            out += `| ${p.number} | ${p.name} | ${p.plans} | ${p.summaries} | ${p.status} | ${p.wall_clock ?? '—'} |\n`;
+            out += `| ${p.number} | ${p.name} | ${p.plans} | ${p.summaries} | ${(0, message_labels_cjs_1.label)('phase.status', p.status, { audience })} | ${p.wall_clock ?? '—'} |\n`;
         }
         if (gitCommits > 0) {
-            out += `\n**Git:** ${gitCommits} commits`;
+            out += '\n' + (0, messages_cjs_1.text)('stats.table.git', { count: gitCommits }, { audience });
             if (gitFirstCommitDate)
-                out += ` (since ${gitFirstCommitDate})`;
+                out += (0, messages_cjs_1.text)('stats.table.git_since', { date: gitFirstCommitDate }, { audience });
             out += '\n';
         }
         if (lastActivity)
-            out += `**Last activity:** ${lastActivity}\n`;
+            out += (0, messages_cjs_1.text)('stats.table.last_activity', { date: lastActivity }, { audience }) + '\n';
+        if (audience !== 'developer')
+            out += (0, messages_cjs_1.refLine)('stats.table') + '\n';
         output({ rendered: out }, raw, out);
     }
     else {