@pareto4/pp-core 1.22.0 → 1.23.1

package/pp-core/bin/lib/init-interactive.cjs

@@ -40,10 +40,12 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.printsResultJson = printsResultJson;
 exports.runInitInteractive = runInitInteractive;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const init_contract_cjs_1 = require("./init-contract.cjs");
+const messages_cjs_1 = require("./messages.cjs");
 // ─── Constants ───────────────────────────────────────────────────────────────
 /** Defensive circuit breaker against a runaway loop (a misbehaving
  * prompter or an unexpected session state that never reaches `done` or
@@ -71,29 +73,63 @@ function readBindingsContent(cwd) {
         return null;
     }
 }
+/** A value shown in the compose summary or an echo, worded for business and engineer through the catalog
+ * (`init.word.<kind>.<value>`). A developer, and any value the catalog does not know, keeps the raw value. */
+function word(kind, value, audience) {
+    if (audience === 'developer')
+        return value;
+    const code = `init.word.${kind}.${value.replace(/-/g, '_')}`;
+    return (0, messages_cjs_1.has)(code) ? (0, messages_cjs_1.text)(code, {}, { audience }) : value;
+}
+/** A parameterless message: the developer's catalog text, or the business/engineer wording with its Ref line. */
+function plainOrMsg(code, audience) {
+    return audience === 'developer' ? (0, messages_cjs_1.msgDeveloper)(code) : (0, messages_cjs_1.msg)(code, {}, { audience });
+}
+/** One unfinished-session problem as a block: its message with its own `Ref:` line, the first line prefixed `- ` and
+ * every following line indented two spaces (the shape `renderViolation` gives discovery problems). */
+function violationBlock(ref, audience) {
+    const lines = (0, messages_cjs_1.msg)(ref.code, ref.params, { audience }).split('\n');
+    return lines.map((line, i) => (i === 0 ? `- ${line}` : `  ${line}`)).join('\n');
+}
+/** Whether the CLI prints the trailing `{ "ok": … }` JSON after the human result. Autonomous Decision 7: it is a
+ * TTY-only dump that no workflow parses (the command refuses a non-TTY), so business users and engineers see only
+ * the human result; developers and `--raw` keep it. */
+function printsResultJson(audience, raw) {
+    return raw || audience === 'developer';
+}
 /** Render `compose_confirm`'s provenance table, drift list and action to
  * the prompter, BEFORE the caller asks for approval — plan Task 1's own
- * ordering requirement. */
-function renderComposeConfirm(prompter, info) {
+ * ordering requirement. The text is the catalog's (`init.compose.*`): a
+ * developer sees what the code always printed. */
+function renderComposeConfirm(prompter, info, audience) {
     if (!isRecord(info))
         return;
     const typed = info;
-    prompter.print('A binding can be composed from the org profile and project answers:');
+    const say = (code, params) => audience === 'developer' ? (0, messages_cjs_1.msgDeveloper)(code, params) : (0, messages_cjs_1.text)(code, params, { audience });
+    prompter.print(say('init.compose.header', {}));
     for (const entry of typed.provenance ?? []) {
-        prompter.print(`  ${entry.field} = ${JSON.stringify(entry.value)} (from ${entry.source})`);
+        prompter.print(say('init.compose.provenance', {
+            field: entry.field,
+            value: JSON.stringify(entry.value),
+            source: word('source', entry.source, audience),
+        }));
     }
     const drift = typed.drift ?? [];
     if (drift.length > 0) {
-        prompter.print('Drift (the already-committed file wins — nothing here is a proposed change):');
+        prompter.print(say('init.compose.drift_header', {}));
         for (const d of drift) {
-            prompter.print(`  the profile would have supplied ${JSON.stringify(d.profileValue)} for "${d.key}"; ` +
-                `the file already says ${JSON.stringify(d.effectiveValue)}, and ${JSON.stringify(d.effectiveValue)} wins.`);
+            prompter.print(say('init.compose.drift', {
+                key: d.key,
+                profile_value: JSON.stringify(d.profileValue),
+                file_value: JSON.stringify(d.effectiveValue),
+            }));
         }
     }
     for (const warning of typed.warnings ?? []) {
-        prompter.print(`  warning: ${warning}`);
+        prompter.print(say('init.compose.warning', { warning }));
     }
-    prompter.print(`Action: ${typed.action ?? 'unknown'}`);
+    const action = typed.action ?? 'unknown';
+    prompter.print(say('init.compose.action', { action: word('action', action, audience) }));
 }
 // ─── runInitInteractive ─────────────────────────────────────────────────────
 /**
@@ -117,6 +153,9 @@ function renderComposeConfirm(prompter, info) {
  */
 async function runInitInteractive(cwd, prompter, opts = {}) {
     const sessionOpts = { offline: opts.offline === true, _globalRoot: opts._globalRoot };
+    const audience = opts.audience ?? (0, messages_cjs_1.audienceOf)(process.env);
+    /** The step's wording for this audience: the catalog text for business and engineer, the session's own text for a developer. */
+    const say = (ref, developerText) => audience === 'developer' || ref === undefined ? developerText : (0, messages_cjs_1.text)(ref.code, ref.params, { audience });
     let wroteBinding = false;
     // PBI 74299: answers the session filled in itself are shown once each, as
     // soon as they are decided, so the operator sees every value before the
@@ -125,15 +164,21 @@ async function runInitInteractive(cwd, prompter, opts = {}) {
     for (let steps = 1; steps <= MAX_SESSION_STEPS; steps++) {
         const state = (0, init_contract_cjs_1.initSessionNext)(cwd, sessionOpts);
         if (state.error !== undefined) {
-            prompter.print(`Error: ${state.message ?? state.error}`);
+            const errorRef = state.display?.message;
+            prompter.print(audience !== 'developer' && errorRef !== undefined
+                ? (0, messages_cjs_1.msg)(errorRef.code, errorRef.params, { audience })
+                : (0, messages_cjs_1.msgDeveloper)('init.error_line', { message: state.message ?? state.error }));
             return { ok: false, wroteBinding, steps, violations: [] };
         }
         for (const auto of state.autoAnswered ?? []) {
             if (shownAutoAnswers.has(auto.id))
                 continue;
             shownAutoAnswers.add(auto.id);
-            const why = auto.source === 'derived' ? 'derived' : 'set by the org profile';
-            prompter.print(`  ${auto.id} = ${auto.value} (${why})`);
+            const code = auto.source === 'derived' ? 'init.auto_answer.derived' : 'init.auto_answer.org_profile';
+            const id = word('step', auto.id, audience);
+            prompter.print(audience === 'developer'
+                ? (0, messages_cjs_1.msgDeveloper)(code, { id, value: auto.value })
+                : (0, messages_cjs_1.text)(code, { id, value: auto.value }, { audience }));
         }
         if (state.done) {
             if (wroteBinding) {
@@ -148,35 +193,20 @@ async function runInitInteractive(cwd, prompter, opts = {}) {
                 // line `pp-tools init` prints contradict the config file it just
                 // finished writing, which is precisely the
                 // tool-reports-a-state-that-isn't-real failure this phase exists to
-                // end.
+                // end. Each reading has its own whole-sentence catalog entry.
                 const vaultState = (0, init_contract_cjs_1.readVaultEnabledState)(cwd).state;
+                let code;
                 if (vaultState === 'off') {
-                    prompter.print('Done — .platform-bindings.json was composed and written; vault.enabled was left at false ' +
-                        'as this project set it, so the vault capability stays off and /pp-init Step 2.6 stays ' +
-                        'inert (arm it with pp-tools config-set vault.enabled true).');
+                    code = 'init.done.vault_off';
                 }
                 else if (vaultState === 'malformed') {
-                    prompter.print('Done — .platform-bindings.json was composed and written; vault.enabled holds a non-boolean ' +
-                        'value and was left untouched — pp-tools query init-contract --verify reports it as ' +
-                        'INIT_VAULT_ENABLED_MALFORMED; store the boolean with pp-tools config-set vault.enabled true.');
+                    code = 'init.done.vault_malformed';
                 }
                 else if (vaultState === 'armed') {
                     // Quick 260916-s5n: vault.required is named only when the READING
                     // says armed, by the same rule — an explicit false is the project's
                     // choice and the last line printed must not contradict it.
-                    const requiredArmed = (0, init_contract_cjs_1.readVaultRequiredState)(cwd).state === 'armed';
-                    // Built as a head plus clauses carrying no terminator of their own,
-                    // with exactly one full stop appended at the end.
-                    const head = 'Done — .platform-bindings.json was composed and written; vault.enabled is now true ' +
-                        '(the vault capability is armed — /pp-init Step 2.6 probes reachability next)';
-                    // 15-REVIEW WR-09: the clause names what is recorded and checked.
-                    const standardsClause = '; each plan records which client standards documents governed it ' +
-                        '(<vault_standards>), checked by the vault.trace gate';
-                    const requiredClause = requiredArmed
-                        ? '; vault.required is true, so a client vault miss, a failed fetch or an unwritable vault summary ' +
-                            'stops the build at plan:pre and execute:pre'
-                        : '';
-                    prompter.print(head + standardsClause + requiredClause + '.');
+                    code = (0, init_contract_cjs_1.readVaultRequiredState)(cwd).state === 'armed' ? 'init.done.vault_armed_required' : 'init.done.vault_armed';
                 }
                 else {
                     // 'absent' — unreachable after an approved compose (the arming
@@ -184,34 +214,49 @@ async function runInitInteractive(cwd, prompter, opts = {}) {
                     // where that write itself failed. It says only what is certain:
                     // the binding was written, and it does NOT claim the capability is
                     // on, because the key is not there to say so.
-                    prompter.print('Done — .platform-bindings.json was composed and written.');
+                    code = 'init.done.written';
                 }
+                prompter.print(plainOrMsg(code, audience));
             }
             else if (typeof state.info === 'string') {
-                prompter.print(state.info);
+                const infoRef = state.display?.info;
+                prompter.print(audience === 'developer' || infoRef === undefined ? state.info : (0, messages_cjs_1.msg)(infoRef.code, infoRef.params, { audience }));
             }
             else {
-                prompter.print('Done — nothing was composed (declined, or nothing was composable).');
+                prompter.print(plainOrMsg('init.done.nothing_composed', audience));
             }
             return { ok: true, wroteBinding, steps, violations: [] };
         }
         if (state.step === 'verify') {
             const violations = state.violations ?? [];
-            prompter.print('The session could not reach a clean end state:');
-            for (const v of violations) {
-                prompter.print(`  - [${v.code}] ${v.message}`);
+            if (audience === 'developer') {
+                prompter.print((0, messages_cjs_1.msgDeveloper)('init.verify'));
+                for (const v of violations) {
+                    prompter.print((0, messages_cjs_1.msgDeveloper)('init.verify.line', { code: v.code, message: v.message }));
+                }
+            }
+            else {
+                prompter.print((0, messages_cjs_1.text)('init.verify', {}, { audience }));
+                violations.forEach((v, i) => {
+                    const ref = state.display?.violations?.[i];
+                    // A code the catalog has no wording for keeps the developer line.
+                    prompter.print(ref !== undefined && (0, messages_cjs_1.has)(ref.code)
+                        ? violationBlock(ref, audience)
+                        : (0, messages_cjs_1.msgDeveloper)('init.verify.line', { code: v.code, message: v.message }));
+                });
+                prompter.print((0, messages_cjs_1.refLine)('init.verify'));
             }
             return { ok: false, wroteBinding, steps, violations };
         }
         if (state.step === null) {
             // Defensive: the session contract never returns a null step outside
             // `done`/`verify`/`error` above. Fail closed rather than crash.
-            prompter.print('Unexpected session state: no step id was returned.');
+            prompter.print(plainOrMsg('init.unexpected_state', audience));
             return { ok: false, wroteBinding, steps, violations: [] };
         }
         const stepId = state.step;
         if (stepId === 'compose_confirm') {
-            renderComposeConfirm(prompter, state.info);
+            renderComposeConfirm(prompter, state.info, audience);
         }
         // Ask, re-asking on rejection — never swallowed (T-34-73).
         for (;;) {
@@ -220,13 +265,23 @@ async function runInitInteractive(cwd, prompter, opts = {}) {
             // pre-existing file that predates this run (a bare post-hoc
             // `existsSync` cannot make that distinction).
             const preBindings = stepId === 'compose_confirm' ? readBindingsContent(cwd) : null;
-            const answer = await prompter.ask({
-                prompt: state.prompt ?? '',
-                options: state.options,
-                preselected: state.preselected,
-                preselectedLabel: state.preselectedLabel,
-                optionalAnswer: state.optionalAnswer,
-            });
+            const answer = await prompter.ask(audience === 'developer'
+                ? {
+                    prompt: state.prompt ?? '',
+                    options: state.options,
+                    preselected: state.preselected,
+                    preselectedLabel: state.preselectedLabel,
+                    optionalAnswer: state.optionalAnswer,
+                }
+                : {
+                    prompt: say(state.display?.prompt, state.prompt ?? ''),
+                    options: state.options,
+                    preselected: state.preselected,
+                    preselectedLabel: state.preselectedLabel === undefined ? undefined : say(state.display?.preselectedLabel, state.preselectedLabel),
+                    optionalAnswer: state.optionalAnswer,
+                    code: state.display?.prompt?.code,
+                    audience,
+                });
             // UAT-13-F2: the driver has no default-acceptance path, on purpose — the
             // answer goes to initSessionAnswer verbatim, which owns the none/blank decline.
             const result = (0, init_contract_cjs_1.initSessionAnswer)(cwd, stepId, answer, sessionOpts);
@@ -236,9 +291,15 @@ async function runInitInteractive(cwd, prompter, opts = {}) {
                 }
                 break;
             }
-            prompter.print(result.message ?? `Rejected (${result.reason ?? 'unknown reason'}) — please answer again.`);
+            const rejectedRef = result.display?.message;
+            const fallback = { code: 'init.rejected_fallback', params: { reason: result.reason ?? 'unknown reason' } };
+            prompter.print(audience === 'developer'
+                ? (result.message ?? (0, messages_cjs_1.msgDeveloper)(fallback.code, fallback.params))
+                : rejectedRef !== undefined
+                    ? (0, messages_cjs_1.msg)(rejectedRef.code, rejectedRef.params, { audience })
+                    : (result.message ?? (0, messages_cjs_1.msg)(fallback.code, fallback.params, { audience })));
         }
     }
-    prompter.print('init session exceeded the maximum step count — aborting to avoid an infinite loop.');
+    prompter.print(plainOrMsg('init.step_overflow', audience));
     return { ok: false, wroteBinding, steps: MAX_SESSION_STEPS, violations: [] };
 }

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

@@ -36,6 +36,7 @@ const plan_sizing_cjs_1 = require("./plan-sizing.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- plan-scan.cjs is an export= CommonJS module
 const scanPhasePlans = require("./plan-scan.cjs");
 const state_document_cjs_1 = require("./state-document.cjs");
+const audience_cjs_1 = require("./audience.cjs");
 const runtime_slash_cjs_1 = require("./runtime-slash.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- commands.cjs is an export= CommonJS module
 const commandsMod = require("./commands.cjs");
@@ -113,7 +114,45 @@ function withProjectRoot(cwd, result) {
             result['project_title'] = h1Match[1].trim();
         }
     }
-    return result;
+    return withAudience(result, typeof config.response_language === 'string' ? config.response_language : null);
+}
+/**
+ * Phase 40 (D-01..D-04, AUD-03): carry the person's audience in the init payload.
+ *
+ * Resolved once per init call through the Phase 39 leaf. For `developer` (set or
+ * defaulted) the result is returned untouched, so every developer payload stays
+ * byte-identical (D-01, D-03). For `business` and `engineer` the payload gains `audience`
+ * and `audience_ref`, and `response_language` becomes the resolved language name, so the
+ * person's language wins over a project's (D-02). Person-file warnings go to stderr only,
+ * never into the JSON (D-04).
+ */
+function withAudience(result, projectLanguage) {
+    // Assignment keeps an existing response_language key in place, as before.
+    return Object.assign(result, audienceFields(projectLanguage));
+}
+/**
+ * The fields `withAudience` adds, on their own: `{}` for a developer (set or defaulted),
+ * otherwise `audience`, `audience_ref` and the resolved `response_language`. Phase 40 CR-01:
+ * `pp-tools audience fields` prints this object, so a workflow that asks the person something
+ * before its first init call learns the audience first, resolved by this same code.
+ */
+function audienceFields(projectLanguage) {
+    const person = (0, audience_cjs_1.readPerson)(process.env);
+    const aud = (0, audience_cjs_1.resolveAudience)(process.env, person);
+    for (const w of aud.warnings)
+        process.stderr.write(`pp-tools: warning: ${w}\n`);
+    if (aud.audience === 'developer')
+        return {};
+    const lang = (0, audience_cjs_1.resolveLanguage)({ env: process.env, person, projectResponseLanguage: projectLanguage });
+    const fields = { audience: aud.audience };
+    // The compiled file is pp-core/bin/lib/init.cjs, so ../../references is pp-core/references.
+    // bin/install.js copies pp-core/ wholesale for every runtime, so the path resolves in every
+    // install. Absolute with forward slashes; never derived from env, the person file or config.
+    fields['audience_ref'] = toPosixPath(node_path_1.default.join(__dirname, '..', '..', 'references', 'audience.md'));
+    if (typeof lang.name === 'string' && lang.name !== '') {
+        fields['response_language'] = lang.name;
+    }
+    return fields;
 }
 function getInitGitState(cwd) {
     const info = gitWorktreeInfoInternal(cwd);
@@ -1487,7 +1526,7 @@ function cmdInitListWorkspaces(cwd, raw) {
         workspaces,
         workspace_count: workspaces.length,
     };
-    output(result, raw);
+    output(withAudience(result, null), raw);
 }
 function cmdInitRemoveWorkspace(cwd, name, raw) {
     const homedir = process.env['HOME'] || node_os_1.default.homedir();
@@ -1550,7 +1589,7 @@ function cmdInitRemoveWorkspace(cwd, name, raw) {
         dirty_repos: dirtyRepos,
         has_dirty_repos: dirtyRepos.length > 0,
     };
-    output(result, raw);
+    output(withAudience(result, null), raw);
 }
 function buildAgentSkillsBlock(config, agentType, projectRoot) {
     const runtime = (config && config['runtime']) || 'claude';
@@ -1916,6 +1955,8 @@ module.exports = {
     cmdInitNewWorkspace,
     cmdInitListWorkspaces,
     cmdInitRemoveWorkspace,
+    // Phase 40 CR-01: the audience fields alone, printed by `pp-tools audience fields`.
+    audienceFields,
     detectChildRepos,
     buildAgentSkillsBlock,
     cmdAgentSkills,

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

@@ -15,6 +15,7 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+const messages_cjs_1 = require("./messages.cjs");
 // ─── Temp-file helpers (needed by output()) ──────────────────────────────────
 /**
  * Dedicated GSD temp directory: path.join(os.tmpdir(), 'gsd').
@@ -232,6 +233,10 @@ const ERROR_REASON = Object.freeze({
     DISCOVERY_FLOW_PAGE_FAILED: 'discovery_flow_page_failed',
     // timeline (Phase 35: end with no matching open run)
     TIMELINE_NO_OPEN_RUN: 'timeline_no_open_run',
+    // audience (Phase 39: person file could not be saved)
+    AUDIENCE_WRITE_FAILED: 'audience_write_failed',
+    // explain (Phase 41: pp-tools explain <code>)
+    EXPLAIN_UNKNOWN_CODE: 'explain_unknown_code',
     // generic
     USAGE: 'usage',
     UNKNOWN: 'unknown',
@@ -265,6 +270,33 @@ function error(message, reason = ERROR_REASON.UNKNOWN) {
     }
     process.exit(1);
 }
+/**
+ * Emit a catalog message as an error and exit (Phase 41 D-05, D-08).
+ *
+ * The `--json-errors` `message` is the DEVELOPER text for every audience,
+ * because workflows and tests parse it. In plain mode a developer gets
+ * `Error: ` plus the developer text, exactly as error() writes today; a
+ * business user or engineer gets the resolved wording with its `Ref: <code>`
+ * line and no `Error: ` prefix, since the first sentence already says what
+ * happened. `params` may be a function of the audience so a caller can supply
+ * different human-facing values (a session number and a section title) than the
+ * developer text uses.
+ */
+function errorCode(code, params, reason = ERROR_REASON.UNKNOWN) {
+    const p = (a) => (typeof params === 'function' ? params(a) : params);
+    if (_jsonErrorMode) {
+        const message = (0, messages_cjs_1.msgDeveloper)(code, p('developer'));
+        writeAllSync(2, JSON.stringify({ ok: false, reason, message }) + '\n');
+    }
+    else {
+        const audience = (0, messages_cjs_1.audienceOf)();
+        if (audience === 'developer')
+            writeAllSync(2, 'Error: ' + (0, messages_cjs_1.msgDeveloper)(code, p('developer')) + '\n');
+        else
+            writeAllSync(2, (0, messages_cjs_1.msg)(code, p(audience), { audience }) + '\n');
+    }
+    process.exit(1);
+}
 // ─── Pareto visual brand: banner engine (Phase 17 / UIBR-01, UIBR-02) ─────────
 //
 // A hand-rolled ANSI banner emitter (no color library — CLAUDE.md constraint).
@@ -387,6 +419,7 @@ module.exports = {
     setJsonErrorMode,
     getJsonErrorMode,
     error,
+    errorCode,
     // Pareto visual brand banner engine (Phase 17 / UIBR-01, UIBR-02)
     PARETO_BLUE,
     CREW,

package/pp-core/bin/lib/message-labels.cjs

@@ -0,0 +1,75 @@
+"use strict";
+/**
+ * Display-time labels for values the code reads back (Phase 41, D-13).
+ *
+ * ADR-457 build-at-publish: compiles to the gitignored
+ * `pp-core/bin/lib/message-labels.cjs`.
+ *
+ * Display time only: writers write and readers read the canonical word
+ * ("Executed", "Pre-Filled"); only the text a person reads is relabelled, at
+ * the last step before output. A developer, and any unknown value or domain,
+ * gets the canonical word back. D-14 allowlists the modules that may import
+ * this file (plan 41-11 enforces it), so a label can never flow into a parser.
+ *
+ * `state.status` and `state.next_action` relabel the STATE.md lifecycle words
+ * and recommended next actions the statusline shows (Phase 43, MSG-06). They are
+ * their own domains because those words (executing, verifying, ...) are not
+ * `phase.status` keys, which are ROADMAP words pinned to the contract snapshot.
+ *
+ * Wording follows pp-core/references/audience.md: the business column never
+ * shows an internal word; the engineer column keeps real terms.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LABELS = void 0;
+exports.label = label;
+exports.LABELS = Object.freeze({
+    'phase.status': Object.freeze({
+        Pending: { engineer: 'Pending', business: 'Waiting' },
+        'Not Started': { engineer: 'Not started', business: 'Not started yet' },
+        Planned: { engineer: 'Planned', business: 'Ready to build' },
+        'In Progress': { engineer: 'In progress', business: 'Being worked on' },
+        Executed: { engineer: 'Executed (not yet verified)', business: 'Built, not yet checked' },
+        'Needs Review': { engineer: 'Needs review', business: 'Waiting for your review' },
+        Complete: { engineer: 'Complete', business: 'Done' },
+    }),
+    'discovery.status': Object.freeze({
+        'Not Started': { engineer: 'Not started', business: 'Not started yet' },
+        'Pre-Filled': { engineer: 'Pre-filled from documents', business: 'Prepared from your documents' },
+        'In Progress': { engineer: 'In progress', business: 'Being worked on' },
+        Completed: { engineer: 'Completed', business: 'Done' },
+    }),
+    // STATE.md frontmatter `status`: normalizeStateStatus output plus the pass-through values
+    // (`Defining requirements`, `Active`) and the statusline body fallback `complete`.
+    'state.status': Object.freeze({
+        discussing: { engineer: 'discussing', business: 'being discussed' },
+        planning: { engineer: 'planning', business: 'being planned' },
+        executing: { engineer: 'executing', business: 'being built' },
+        verifying: { engineer: 'verifying', business: 'being checked' },
+        completed: { engineer: 'completed', business: 'done' },
+        complete: { engineer: 'complete', business: 'done' },
+        paused: { engineer: 'paused', business: 'on hold' },
+        unknown: { engineer: 'unknown', business: 'not recorded yet' },
+        'Defining requirements': { engineer: 'defining requirements', business: 'agreeing what to build' },
+        Active: { engineer: 'active', business: 'under way' },
+    }),
+    // STATE.md frontmatter `next_action`: the recommended next command, when idle.
+    'state.next_action': Object.freeze({
+        'discuss-phase': { engineer: 'discuss phase', business: 'talk through stage' },
+        'plan-phase': { engineer: 'plan phase', business: 'plan stage' },
+        'execute-phase': { engineer: 'execute phase', business: 'build stage' },
+        'verify-phase': { engineer: 'verify phase', business: 'check stage' },
+        'verify-work': { engineer: 'verify work (UAT)', business: 'test stage' },
+    }),
+});
+/** The word to show for a canonical value. Developer and anything unknown get the canonical word back. */
+function label(domain, canonical, opts) {
+    if (opts.audience === 'developer')
+        return canonical;
+    if (!Object.hasOwn(exports.LABELS, domain))
+        return canonical;
+    const table = exports.LABELS[domain];
+    if (!Object.hasOwn(table, canonical))
+        return canonical;
+    const pair = table[canonical];
+    return opts.audience === 'business' ? pair.business : pair.engineer;
+}

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

@@ -0,0 +1,20 @@
+"use strict";
+/**
+ * Catalog slice: core messages (Phase 41, plan 41-05). Data only.
+ *
+ * ADR-457 build-at-publish: compiles to the gitignored
+ * `pp-core/bin/lib/messages/core.cjs`. Imports nothing but the entry type.
+ * Wording follows pp-core/references/audience.md. Every code is a stable key;
+ * `Ref:` lines are added by the engine at render time, never written here.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.core = void 0;
+exports.core = Object.freeze({
+    explain_unknown_code: {
+        reach: 'business',
+        developer: 'No explanation for {code}.',
+        engineer: 'No explanation for {code}. No message has that reference code. Check that you copied the whole code from the line after "Ref:".',
+        business: 'No explanation for {code}. Copy the whole code from the line after "Ref:" and try again, or send it to Pareto as it is.',
+        explain: 'Every message from pp-core ends with a reference code on its own line. This command explains that code. An unknown code usually means it was cut short when it was copied.',
+    },
+});