@pareto4/pp-core 1.22.0 → 1.23.1

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

@@ -0,0 +1,208 @@
+"use strict";
+/**
+ * Message catalog engine (Phase 41: MSG-02, MSG-03, MSG-04; D-01..D-06, D-20).
+ *
+ * ADR-457 build-at-publish: this TypeScript file is the SOURCE OF TRUTH. It
+ * compiles to the gitignored `pp-core/bin/lib/messages.cjs`; do NOT hand-edit
+ * the compiled output.
+ *
+ * One catalog keyed by a stable code. Each entry carries `developer` (today's
+ * text, frozen byte for byte), optional `engineer`, `business` and `explain`.
+ * A business lookup resolves business, then engineer, then developer; an
+ * engineer lookup engineer, then developer; a developer lookup developer
+ * (D-01). Business and engineer messages end with a `Ref: <code>` line (D-05,
+ * D-06); developer text never does.
+ *
+ * Params are data. Substitution is a single pass with a function replacer, so
+ * a value that holds `{x}` or `$&` is never re-expanded (T-41-12). For business
+ * and engineer every param except the slots an entry marks `rawParams` is
+ * stripped of control characters, whitespace-collapsed and capped (T-41-11): at
+ * ECHO_CAP for an echo, at DIAG_CAP for the slots an entry marks `longParams`
+ * (diagnostics and approval values the person must read in full); the developer path
+ * passes params through untouched (D-08). An unknown code renders the code
+ * itself, never blank and never a throw (D-04). Lookups use a Map only, so
+ * `__proto__` and `constructor` are unknown codes (T-41-13).
+ *
+ * Machine channels never route through the audience path: `io.errorCode` writes
+ * `msgDeveloper` to the `--json-errors` message for every audience. This module
+ * must never import `io.cjs` (io imports this module). It imports Node built-ins
+ * (through the audience leaf), `audience.cjs` and the slices only, so hooks can
+ * load it later (D-02).
+ *
+ * The audience is resolved through the Phase 39 leaf (`PP_AUDIENCE`, then the
+ * person file, then developer), silently (D-20): warnings are printed by the
+ * commands that own them, never by a lookup.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SLICES = exports.DIAG_CAP = exports.ECHO_CAP = void 0;
+exports.duplicateCodesOf = duplicateCodesOf;
+exports.registry = registry;
+exports.has = has;
+exports.audienceOf = audienceOf;
+exports.sanitizeParam = sanitizeParam;
+exports.fill = fill;
+exports.pick = pick;
+exports.refLine = refLine;
+exports.msgDeveloper = msgDeveloper;
+exports.text = text;
+exports.msg = msg;
+exports.explainText = explainText;
+const audience_cjs_1 = require("./audience.cjs");
+const core_cjs_1 = require("./messages/core.cjs");
+const discovery_cjs_1 = require("./messages/discovery.cjs");
+const init_cjs_1 = require("./messages/init.cjs");
+const progress_cjs_1 = require("./messages/progress.cjs");
+const gate_cjs_1 = require("./messages/gate.cjs");
+const hook_cjs_1 = require("./messages/hook.cjs");
+/**
+ * Every control character `\s` does not match (C0 minus `\t\n\v\f\r`, DEL and
+ * C1), plus every Unicode format character (category Cf: bidi overrides and
+ * isolates, zero-width characters, the BOM, tag characters). A right-to-left
+ * override in a file name would make the shown name differ from the real one
+ * (Trojan Source). Stripped BEFORE the whitespace collapse.
+ */
+const CONTROL_CHARS_RE = /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f\p{Cf}]/gu;
+const SLOT_RE = /\{([a-z][a-z0-9_]*)\}/g;
+/** The cap for a slot that echoes a typed value (T-41-11). */
+exports.ECHO_CAP = 120;
+/**
+ * The cap for a `longParams` slot. `composeBindings` bounds each warning at 200
+ * characters, so this holds five full warnings joined with `; `.
+ */
+exports.DIAG_CAP = 1000;
+exports.SLICES = Object.freeze([
+    ['core', core_cjs_1.core],
+    ['discovery', discovery_cjs_1.discovery],
+    ['init', init_cjs_1.init],
+    ['progress', progress_cjs_1.progress],
+    ['gate', gate_cjs_1.gate],
+    ['hook', hook_cjs_1.hook],
+]);
+/** Codes defined in more than one slice, sorted. */
+function duplicateCodesOf(slices) {
+    const seen = new Set();
+    const dup = new Set();
+    for (const [, slice] of slices) {
+        for (const code of Object.keys(slice)) {
+            if (seen.has(code))
+                dup.add(code);
+            seen.add(code);
+        }
+    }
+    return [...dup].sort();
+}
+let _registry = null;
+/** The catalog as one Map, built once. On a duplicate code the first slice wins; the gate test reports duplicates. */
+function registry() {
+    if (_registry === null) {
+        const map = new Map();
+        for (const [, slice] of exports.SLICES) {
+            for (const code of Object.keys(slice)) {
+                if (!map.has(code))
+                    map.set(code, slice[code]);
+            }
+        }
+        _registry = map;
+    }
+    return _registry;
+}
+function has(code) {
+    return registry().has(code);
+}
+/** The audience for this process (D-20). Never prints, never throws; developer on any failure. */
+function audienceOf(env = process.env) {
+    try {
+        return (0, audience_cjs_1.resolveAudience)(env, (0, audience_cjs_1.readPerson)(env)).audience;
+    }
+    catch {
+        return 'developer';
+    }
+}
+/** Strip control and format characters, collapse whitespace, trim, cap at `cap` (T-41-11). Order matters. */
+function sanitizeParam(value, cap = exports.ECHO_CAP) {
+    let raw;
+    if (typeof value === 'number')
+        raw = String(value);
+    else if (typeof value === 'string')
+        raw = value;
+    else
+        return '';
+    const collapsed = raw.replace(CONTROL_CHARS_RE, '').replace(/\s+/g, ' ').trim();
+    if (collapsed.length <= cap)
+        return collapsed;
+    return `${collapsed.slice(0, cap)}…`;
+}
+function rawParam(value) {
+    return typeof value === 'string' || typeof value === 'number' ? String(value) : '';
+}
+/**
+ * One pass of `{name}` substitution with a function replacer. A missing param
+ * renders empty in the developer text (unchanged, D-08) and as its own `{name}`
+ * slot for business and engineer, so a renderer that fails to supply a value
+ * shows visibly instead of leaving a silent blank (D-04). When sanitising, only
+ * the slots in `opts.rawParams` (the entry's own marking) pass through as written,
+ * and the slots in `opts.longParams` are capped at DIAG_CAP instead of ECHO_CAP.
+ */
+function fill(template, params, opts) {
+    return template.replace(SLOT_RE, (match, name) => {
+        if (!Object.hasOwn(params, name))
+            return opts.sanitize ? match : '';
+        const value = params[name];
+        if (!opts.sanitize || (opts.rawParams?.includes(name) ?? false))
+            return rawParam(value);
+        return sanitizeParam(value, (opts.longParams?.includes(name) ?? false) ? exports.DIAG_CAP : exports.ECHO_CAP);
+    });
+}
+/** The wording for an audience: business, engineer, then developer fallbacks (D-01). */
+function pick(entry, audience) {
+    if (audience === 'business')
+        return entry.business ?? entry.engineer ?? entry.developer;
+    if (audience === 'engineer')
+        return entry.engineer ?? entry.developer;
+    return entry.developer;
+}
+function refLine(code) {
+    return `Ref: ${code}`;
+}
+/** The developer text: today's wording, params untouched (D-05, D-08). Unknown code renders the code. */
+function msgDeveloper(code, params = {}, _registry) {
+    const entry = (_registry ?? registry()).get(code);
+    if (entry === undefined)
+        return code;
+    return fill(entry.developer, params, { sanitize: false });
+}
+/** The text for an audience with no Ref line. Unknown code renders the code. */
+function text(code, params = {}, opts) {
+    const entry = (opts._registry ?? registry()).get(code);
+    if (entry === undefined)
+        return code;
+    if (opts.audience === 'developer')
+        return msgDeveloper(code, params, opts._registry);
+    return fill(pick(entry, opts.audience), params, {
+        sanitize: true,
+        rawParams: entry.rawParams,
+        longParams: entry.longParams,
+    });
+}
+/** The message for an audience: business and engineer messages end with the Ref line (D-05, D-06). */
+function msg(code, params = {}, opts) {
+    const entry = (opts._registry ?? registry()).get(code);
+    if (entry === undefined)
+        return code;
+    if (opts.audience === 'developer')
+        return msgDeveloper(code, params, opts._registry);
+    const body = text(code, params, opts);
+    if (entry.part === true)
+        return body;
+    return `${body}\n${refLine(code)}`;
+}
+/** What `pp-tools explain <code>` shows, or null for an unknown code. */
+function explainText(code, opts) {
+    const entry = (opts._registry ?? registry()).get(code);
+    if (entry === undefined)
+        return null;
+    const body = typeof entry.explain === 'string' && entry.explain !== ''
+        ? entry.explain
+        : pick(entry, opts.audience).replace(SLOT_RE, (_m, name) => `<${name}>`);
+    return `${body}\n${refLine(code)}`;
+}

package/pp-core/bin/lib/vault-command-router.cjs

@@ -39,6 +39,7 @@ const node_path_1 = __importDefault(require("node:path"));
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const childProcess = require("node:child_process");
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+const messages_cjs_1 = require("./messages.cjs");
 // CR-04 (03-11): this router's path arms resolve their containment boundary the
 // same way `cmdVaultTrace` in src/check-command-router.cts does. project-root.cjs is a
 // leaf (node builtins only), so this adds no cycle.
@@ -484,6 +485,12 @@ function routeVaultCommand({ args, cwd, raw, error, _vault, _core, _exec, _orgPr
  * `config-unreadable`, one more line per unreadable file names the file and the
  * repair; `--raw` prints the verdict object instead.
  *
+ * Phase 43 (D-12): for a business user or engineer the `--explain` lines are the
+ * card for the stopped check (`gate.vault.admission.blocked`), its `Ref:` line,
+ * `Details:` and then the same repair lines. The card is display text: the first
+ * line is the token for every audience, and without `--explain`, with `--raw`
+ * and for every other state the output is unchanged.
+ *
  * The answer comes from `vaultAdmissionVerdict` in the REAL src/vault.cts, never
  * from the injectable `_vault` seam: a governance decision must not be
  * switchable by a test mock.
@@ -518,9 +525,15 @@ function admissionVerb({ cwd, rest, raw, error, c }) {
     }
     const lines = [verdict.state];
     if (explain && verdict.state === 'config-unreadable') {
-        for (const u of verdict.unreadable) {
-            lines.push(`${u.file}: ${u.error} — repair: fix the JSON in ${u.file} (or remove the key that broke it) and re-run; ` +
-                'the gate cannot read this file and refuses to pass having checked nothing');
+        const code = 'gate.vault.admission.blocked';
+        const repair = verdict.unreadable.map((u) => (0, messages_cjs_1.msgDeveloper)(code, { file: u.file, error: u.error }));
+        const audience = (0, messages_cjs_1.audienceOf)(process.env);
+        if (audience === 'developer') {
+            lines.push(...repair);
+        }
+        else {
+            // D-12: the card for a business user or engineer, then today's repair line(s) under Details.
+            lines.push((0, messages_cjs_1.text)(code, {}, { audience }), (0, messages_cjs_1.refLine)(code), 'Details:', ...repair);
         }
     }
     c.output(verdict, true, `${lines.join('\n')}\n`);

package/pp-core/bin/lib/violation-render.cjs

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * Shared violation renderer (Phase 41: MSG-01, MSG-02, MSG-03; D-07, D-11, D-13).
+ *
+ * ADR-457 build-at-publish: this TypeScript file is the SOURCE OF TRUTH. It
+ * compiles to the gitignored `pp-core/bin/lib/violation-render.cjs`; do NOT
+ * hand-edit the compiled output.
+ *
+ * D-11: the only place a discovery violation becomes text. Built for every
+ * discovery domain; only `discovery.session` and `discovery.input` are cut over
+ * in this phase (the other 17 formatViolation copies stay behind the
+ * shrink-only ratchet in tests/fixtures/format-violation-allowlist.json).
+ *
+ * A violation is `{ reason, ...fields }`; its catalog code is
+ * `<domain>.<reason>`. A developer gets the exact line the old code printed
+ * (`msgDeveloper`, params untouched). A business user or engineer gets a block:
+ * the message with its own `Ref:` line, the first line prefixed `- ` and every
+ * following line indented, so each problem carries its code (D-05, D-07).
+ *
+ * Canonical values stay canonical (D-13): the engines pass the literals the
+ * person must write (`None identified in Discovery.`, `[TO CONFIRM]`,
+ * `Completed`) through `extra`; this module only adds a display `status` through
+ * `label()`. It never imports a discovery engine (the engines import it).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.violationParams = violationParams;
+exports.renderViolation = renderViolation;
+const messages_cjs_1 = require("./messages.cjs");
+const message_labels_cjs_1 = require("./message-labels.cjs");
+const SESSION_FILE_RE = /session-(\d{2})\.md$/;
+const SESSION_ID_RE = /^session (\d+)$/;
+function sessionNumberOf(v) {
+    for (const field of ['artifact', 'session']) {
+        const value = v[field];
+        if (typeof value !== 'string')
+            continue;
+        const m = SESSION_FILE_RE.exec(value);
+        if (m !== null)
+            return String(Number(m[1]));
+    }
+    if (typeof v.id === 'string') {
+        const m = SESSION_ID_RE.exec(v.id);
+        if (m !== null)
+            return String(Number(m[1]));
+    }
+    return null;
+}
+/** The catalog params for a violation: every string or number field except `reason`, plus the session number, `extra`, and a display `status`. */
+function violationParams(v, opts = {}) {
+    const fields = { ...v };
+    const params = {};
+    for (const [key, value] of Object.entries(fields)) {
+        if (key === 'reason')
+            continue;
+        if (typeof value === 'string' || typeof value === 'number')
+            params[key] = String(value);
+    }
+    const n = sessionNumberOf(fields);
+    if (n !== null)
+        params.session_number = n;
+    const extra = opts.extra ?? {};
+    for (const [key, value] of Object.entries(extra))
+        params[key] = String(value);
+    const statusWord = extra.status_word;
+    if (typeof statusWord === 'string') {
+        params.status = (0, message_labels_cjs_1.label)('discovery.status', statusWord, { audience: opts.audience ?? 'developer' });
+    }
+    return params;
+}
+/** One violation as text for an audience. An unknown reason renders its code, never throws. */
+function renderViolation(domain, v, opts) {
+    const code = `${domain}.${v.reason}`;
+    const params = violationParams(v, opts);
+    if (opts.audience === 'developer')
+        return (0, messages_cjs_1.msgDeveloper)(code, params);
+    const lines = (0, messages_cjs_1.msg)(code, params, { audience: opts.audience }).split('\n');
+    return lines.map((line, i) => (i === 0 ? `- ${line}` : `  ${line}`)).join('\n');
+}

package/pp-core/bin/pp-tools.cjs

@@ -71,6 +71,23 @@
  *     [--plan P] [--id ID]
  *   timeline summary <phase> [--banner]    Fold a phase's runs: wall-clock, agent time, longest
  *
+ * Audience (Phase 39):
+ *   audience status [--raw]            Show the person's audience, language and where each came from
+ *   audience set <business|engineer|developer> [--language en|nl | --clear-language]
+ *                                      Save the setting in ~/.gsd/person.json (GSD_HOME-rooted); no
+ *                                      --language keeps a stored language, --clear-language removes it
+ *   audience set --clear-language      Remove only the stored language; the stored audience is untouched
+ *   audience answer <reply>            Save a first-run reply (1, 2, 3 or a name); refused when the
+ *                                      reply is blank or an audience is already saved
+ *   PP_AUDIENCE=<value>                Override the audience for one command or shell; never stored
+ *
+ * Explain (Phase 41):
+ *   explain <code> [--raw]             Longer explanation of a message's Ref code, in the person's wording
+ *
+ * Gate card (Phase 43):
+ *   gate-card <query> [--state blocked|advisory|error] [--details] [--raw]
+ *                                      The stopped-check card in the person's wording; prints nothing for a developer
+ *
  * Ceremony (Phase 37):
  *   ceremony classify <phase> [--full] [--research] [--skip-research] [--skip-verify] [--write]
  *                                      Classify a phase (trust boundary, codebase to match, single-concern), print the
@@ -210,7 +227,7 @@ const path = require('path');
 const readline = require('readline');
 const { ExitError, runMain } = require('./lib/cli-exit.cjs');
 const io = require('./lib/io.cjs');
-const { error, ERROR_REASON, setJsonErrorMode, output } = io;
+const { error, errorCode, ERROR_REASON, setJsonErrorMode, output } = io;
 const projectRoot = require('./lib/project-root.cjs');
 // Resolve findProjectRoot lazily at call time rather than binding it at module
 // load. It is sourced from project-root.cjs; a call-time lookup is robust
@@ -226,6 +243,9 @@ const verify = require('./lib/verify.cjs');
 const config = require('./lib/config.cjs');
 const platformBindings = require('./lib/platform-bindings.cjs');
 const timeline = require('./lib/timeline.cjs');
+const audience = require('./lib/audience-command.cjs');
+const explain = require('./lib/explain-command.cjs');
+const gateCard = require('./lib/gate-card.cjs');
 const composeBindings = require('./lib/compose-bindings.cjs');
 const initContract = require('./lib/init-contract.cjs');
 const initInteractive = require('./lib/init-interactive.cjs');
@@ -538,11 +558,11 @@ async function main() {
   // discovery; previously it was a partial subset that didn't include
   // phase / roadmap / milestone / progress / etc.
   const TOP_LEVEL_USAGE = 'Usage: pp-tools <command> [args] [--raw] [--pick <field>] [--cwd <path>] [--ws <name>] [--json-errors]\n' +
-    'Commands: agent, agent-skills, audit-open, audit-uat, check, check-commit, commit, commit-to-subrepo, ' +
+    'Commands: agent, agent-skills, audience, audit-open, audit-uat, check, check-commit, commit, commit-to-subrepo, ' +
     'compose-bindings, config-ensure-section, config-get, config-new-project, config-path, config-set, migrate-config, ' +
-    'current-timestamp, detect-custom-files, discovery, docs-init, drift-guard, effort, extract-messages, find-phase, ' +
+    'current-timestamp, detect-custom-files, discovery, docs-init, drift-guard, effort, explain, extract-messages, find-phase, ' +
     'from-gsd2, frontmatter, gap-analysis, generate-claude-md, generate-claude-profile, ' +
-    'generate-client-context, generate-dev-preferences, generate-slug, graphify, history-digest, init, init-contract, intel, ' +
+    'gate-card, generate-client-context, generate-dev-preferences, generate-slug, graphify, history-digest, init, init-contract, intel, ' +
     'capability, ceremony, classify-confidence, git, learnings, list-todos, loop, milestone, package-legitimacy, phase, phase-plan-index, phases, platform-bindings, platform-latest-tag, profile-questionnaire, ' +
     'profile-sample, progress, prompt-budget, requirements, research-plan, research-store, resolve-granularity, resolve-model, roadmap, scaffold, state, ' +
     'task, template, timeline, user-story, validate, validate-bindings, verify, verify-path-exists, verify-summary, workstream, worktree\n\n' +
@@ -570,7 +590,8 @@ async function main() {
   // through this dispatcher. Rendering top-level usage on --help is strictly
   // better UX than the old short-circuit that printed unrelated usage text.
   const HELP_FLAGS = new Set(['-h', '--help', '-?', '--h', '--usage']);
-  if (args.some((a) => HELP_FLAGS.has(a))) {
+  // Phase 41: `explain` answers its own help (its usage line names the Ref code), so it is not intercepted here.
+  if (command !== 'explain' && args.some((a) => HELP_FLAGS.has(a))) {
     process.stdout.write(TOP_LEVEL_USAGE + '\n');
     return;
   }
@@ -732,14 +753,19 @@ function createReadlinePrompter({ input = process.stdin, output = process.stdout
   const rl = readline.createInterface({ input, output });
   return {
     ask(question) {
+      // Phase 41: the chrome is catalog text. A developer (no `audience` on the question) renders
+      // exactly what this prompter always printed; business and engineer get their wording and a Ref line.
+      const messages = require('./lib/messages.cjs');
+      const aud = question.audience === 'business' || question.audience === 'engineer' ? question.audience : 'developer';
+      const chrome = (code, params) => messages.text(code, params, { audience: aud });
       let rendered = question.prompt;
       if (question.options && question.options.length > 0) {
         const optionsRendered = question.options
           .map((opt) =>
-            opt === question.preselected ? `${opt} (${question.preselectedLabel || 'preselected'})` : opt,
+            opt === question.preselected ? `${opt} (${question.preselectedLabel || chrome('init.chrome.preselected', {})})` : opt,
           )
           .join(' / ');
-        rendered += `\n  Options: ${optionsRendered}`;
+        rendered += `\n  ${chrome('init.chrome.options', { options: optionsRendered })}`;
       }
       if (question.optionalAnswer && !/press Enter to skip/i.test(question.prompt)) {
         // UAT-13-F2: a detected org profile is a HINT inside the prompt text
@@ -747,7 +773,10 @@ function createReadlinePrompter({ input = process.stdin, output = process.stdout
         // text may already carry the skip hint (the org profile prompts do),
         // so it is added only for an optional question whose text lacks it
         // (I-1).
-        rendered += '\n  (press Enter to skip)';
+        rendered += `\n  ${chrome('init.chrome.skip_hint', {})}`;
+      }
+      if (aud !== 'developer' && typeof question.code === 'string') {
+        rendered += `\n${messages.refLine(question.code)}`;
       }
       return new Promise((resolve) => {
         rl.question(`${rendered}\n> `, (answer) => resolve(answer));
@@ -866,6 +895,21 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
       break;
     }
 
+    case 'audience': {
+      audience.cmdAudience(cwd, args.slice(1), raw);
+      break;
+    }
+
+    case 'explain': {
+      explain.cmdExplain(cwd, args.slice(1), raw);
+      break;
+    }
+
+    case 'gate-card': {
+      gateCard.cmdGateCard(cwd, args.slice(1), raw);
+      break;
+    }
+
     case 'ceremony': {
       // WR-04: loaded here, not at the top, so a missing ceremony-gates.json fails
       // only the ceremony command, never every pp-tools command.
@@ -1659,35 +1703,28 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
         const INIT_INTERACTIVE_FLAGS = ['--offline', '--reset'];
         const unrecognizedInitFlag = args.slice(1).find((a) => !INIT_INTERACTIVE_FLAGS.includes(a));
         if (unrecognizedInitFlag !== undefined) {
-          error(
-            `Unrecognized flag "${unrecognizedInitFlag}" for init. Supported: --offline, --reset. ` +
-              'For init workflow subcommands (execute-phase, plan-phase, new-project, ...), use "pp-tools query init.<subcommand>".',
-            ERROR_REASON.SDK_FAIL_FAST,
-          );
+          errorCode('init.unknown_flag', { flag: unrecognizedInitFlag }, ERROR_REASON.SDK_FAIL_FAST);
           break;
         }
         // Refuse to prompt when stdin is not a TTY — never block on stdin
         // in CI; a hang here would be worse than a failure (T-34-71).
         if (!process.stdin.isTTY) {
-          error(
-            '"pp-tools init" requires an interactive terminal (stdin is not a TTY) and will not prompt. ' +
-              'This command cannot run inside an AI-agent shell or a piped session — open a regular ' +
-              'terminal window (e.g. Terminal, iTerm, or Windows Terminal) and run it there. ' +
-              'For a non-interactive/CI-driven session, use "pp-tools query init-contract --session-next" / ' +
-              '"--session-answer <stepId>=<value>" directly instead.',
-            ERROR_REASON.INIT_NON_INTERACTIVE,
-          );
+          // The catalog code is the ERROR_REASON value (D-03); --json-errors keeps the developer text for every audience.
+          errorCode(ERROR_REASON.INIT_NON_INTERACTIVE, {}, ERROR_REASON.INIT_NON_INTERACTIVE);
           break;
         }
         if (args.includes('--reset')) {
           initContract.initSessionReset(cwd);
         }
         const prompter = createReadlinePrompter();
+        const initAudience = require('./lib/messages.cjs').audienceOf(process.env);
         try {
           const result = await initInteractive.runInitInteractive(cwd, prompter, {
             offline: args.includes('--offline'),
+            audience: initAudience,
           });
-          output(result, raw);
+          // Business users and engineers read the human result above; the JSON stays for developers and --raw.
+          if (initInteractive.printsResultJson(initAudience, raw)) output(result, raw);
           if (!result.ok) {
             process.exitCode = 1;
           }
@@ -2786,6 +2823,14 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
         } catch (testsCheckErr) {
           error(`discovery tests-check: ${testsCheckErr && testsCheckErr.message ? testsCheckErr.message : String(testsCheckErr)}`, ERROR_REASON.UNKNOWN);
         }
+      } else if (subcommand === 'status') {
+        // discovery status [--raw] — Phase 42 DOOR-01: discovery-only vs build, sprint state and next step; read-only. Exits 1 only on a usage error, or before it runs when the dispatcher refuses an invalid GSD_WORKSTREAM
+        const discoveryStatus = require('./lib/discovery-status.cjs');
+        try {
+          discoveryStatus.cmdDiscoveryStatus(cwd, args, raw);
+        } catch (statusErr) {
+          error(`discovery status: ${statusErr && statusErr.message ? statusErr.message : String(statusErr)}`, ERROR_REASON.UNKNOWN);
+        }
       } else if (subcommand === 'flow-page') {
         // discovery flow-page <MP-nn> [--out <file.html>] — render one main
         // process (swimlane, sub-processes, step matrix) from _processes.md
@@ -2803,7 +2848,7 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
         // the engine's exported exit identity, splits this string on commas and
         // asserts membership. A spelling missing here is a command the engine
         // claims to be and the router does not dispatch.
-        error('Unknown discovery subcommand. Available: rollup, input-check, research-check, screen-check, element-sweep, rebaseline-check, vault-check, charter-check, entity-check, process-check, rules-check, stories-check, phases-check, for-phase, roles-check, integrations-check, migration-check, deviations-check, session-check, tests-check, flow-page', ERROR_REASON.SDK_UNKNOWN_COMMAND);
+        error('Unknown discovery subcommand. Available: rollup, input-check, research-check, screen-check, element-sweep, rebaseline-check, vault-check, charter-check, entity-check, process-check, rules-check, stories-check, phases-check, for-phase, roles-check, integrations-check, migration-check, deviations-check, session-check, tests-check, flow-page, status', ERROR_REASON.SDK_UNKNOWN_COMMAND);
       }
       break;
     }

package/pp-core/bin/shared/config-schema.manifest.json

@@ -80,6 +80,7 @@
     "manager.flags.plan",
     "manager.flags.execute",
     "response_language",
+    "discovery.language",
     "context_window",
     "graphify.build_timeout",
     "graphify.auto_update",

package/pp-core/references/audience-moments.md

@@ -0,0 +1,119 @@
+# Audience moments
+
+The business and engineer forms for five moments (Next Up, a stopped check, a verification result, the fallback-standards question and a confirmation before an irreversible action) plus the discovery narration rule. Read from `audience.md`'s pointer line, never `@`-included.
+
+## When to use this
+
+Use a form below only when the payload (or `pp_run query audience fields`) carries `audience`; pick the section for that audience. A developer never reads this file, and a developer's text stays as it is.
+
+Fill every `{…}` from facts you hold (the `ROADMAP.md` goal, the plan's objective, `VERIFICATION.md`, the check's own output) and never invent one. Keep commands, file names, IDs and paths in backticks, unchanged (`audience.md`, Never reword). When the CLI already printed a card (a `GATE_CARDS=` line, or the lines `vault admission --explain` printed), relay that card word for word and never compose a second one.
+
+## Business user forms
+
+### Next Up
+
+```
+Next: {plain action}, because {reason}. Start a fresh conversation first (`/clear`) so the assistant has its full working memory, then type `{command}`.
+```
+
+- {plain action} names the step and the plan by its name, taken from the plan's objective. Never show a plan ID.
+- {reason} is one clause from that stage's `ROADMAP.md` goal or from the result just shown.
+- Say "stage N of the work", never the internal word for it.
+- A line that would show a command to print a report file becomes "Ask me to show the full report."
+- Several options become one Next line plus "Also possible:" lines in the same shape.
+
+### Stopped check
+
+`The {name} check stopped this step: {why}. What to do: {action}.`
+
+Then `Ref: {code}`, then `Details:` followed by the check's own message exactly as printed. An advisory says the step carries on. Use the card the CLI printed; compose this shape only when none was printed (an older engine).
+
+### Verification result
+
+Status line: `Done` when the report status is `passed`, `Not finished yet` for `gaps_found`, `Needs your check` for `human_needed`. Show the internal names only inside backticks.
+
+Then three headed lists, each item one plain sentence:
+
+- What works ({N} of {M})
+- What is missing
+- What needs your own test
+
+End with the Next Up line.
+
+### Vault fallback question
+
+Your organisation's own standards could not be loaded ({reason}). May the build follow the general Pareto standards instead?
+
+Then: Type `confirmed` to go ahead. This answer is never given for the person and never assumed in an unattended run. {reason} is the plain reason, for example "the connection to your organisation's standards did not answer".
+
+### Irreversible action
+
+Say the action and its target before the person answers, and keep the workflow's own way of answering: its options, or the typed name for `remove-workspace`. One row per action:
+
+- `undo`: This will undo `{commits}`, the saved changes of `{plan name}`; they stay in the history. Then ask exactly as the workflow does, with the same options.
+- `remove-workspace`: This will delete the folder `{workspace path}` and every file in it; it cannot be undone. Type `{workspace name}` to go ahead.
+- `complete-milestone`: In the workflow's question, describe its "Delete without merging" option as: This will delete `{branch}`, the separate line of work for this release; use it when that work is already on the main line or not needed. Keep all of the workflow's options.
+- `transition`: This will skip `{plan names}`, which are then not built in this stage of the work. Then ask exactly as the workflow does, with the same options.
+- `vault-write-back`: This will write `{file}` into your organisation's standards at `{target}`, where others will see it. Then ask exactly as the workflow does, with the same options.
+- `discovery-redo`: This will replace the notes of session {n} in `session-{nn}.md` and hold the session again. Then ask exactly as the workflow does, with the same options.
+- `charter-redraft`: This will reopen `PROJECT-CHARTER.md` as version `{version}`; it must be signed again. Then ask exactly as the workflow does, with the same options.
+- `init-compose`: This will write `.platform-bindings.json` with the answers you gave. Then ask exactly as the workflow does, with the same options.
+
+### Discovery narration
+
+In a discovery session with a business user, never show file paths, internal ID counts (a tally per prefix), check codes or the `vault:` lines. Never ask them to design ID prefixes: choose the prefixes yourself from the people and areas they named and say the split in one plain sentence. Refer to a recorded item as "decision 3" or "open item 2". Keep `/pp-discovery N` commands in backticks.
+
+## Business engineer forms
+
+### Next Up
+
+```
+Next: {plain action} (phase {N}), because {reason}. Run `/clear` first so the assistant starts with a fresh context window, then run `{command}`.
+```
+
+- {plain action} names the step and the plan by its name from the plan's objective; never a plan ID.
+- {reason} is one clause from the phase goal in `ROADMAP.md` or from the result just shown.
+- Explain a real term such as "context window" once, with its line from the Explain once table in `audience.md`.
+- A line that would show a command to print a report file becomes "Ask me to show the full report."
+- Several options become one Next line plus "Also possible:" lines in the same shape.
+
+### Stopped check
+
+`The {name} check stopped this step: {why}. What to do: {action}.`
+
+Then `Ref: {code}`, then `Details:` followed by the check's own message exactly as printed. An advisory says the step carries on. Use the card the CLI printed, word for word; its `Ref:` line already names the query. Compose this shape only when none was printed (an older engine), and then name the check by its query, for example `vault.trace`.
+
+### Verification result
+
+Status line: `Done` for `passed`, `Not finished yet` for `gaps_found` (a required outcome is missing; name the status once in backticks), `Needs your check` for `human_needed`.
+
+Then three headed lists, each item one plain sentence:
+
+- What works ({N} of {M})
+- What is missing
+- What needs your own test
+
+End with the Next Up line.
+
+### Vault fallback question
+
+Your client's standards vault could not be loaded ({reason}); the fallback tier would apply the general Pareto standards instead. Proceed with the fallback? Type `confirmed` to go ahead.
+
+This answer is never given for the person and never assumed in an unattended run.
+
+### Irreversible action
+
+Say the action and its target before the person answers, and keep the workflow's own way of answering: its options, or the typed name for `remove-workspace`. One row per action:
+
+- `undo`: This will revert `{commits}` with `git revert`; history is kept. Then ask exactly as the workflow does, with the same options.
+- `remove-workspace`: This will delete the folder `{workspace path}` and every file in it; it cannot be undone. Type `{workspace name}` to go ahead.
+- `complete-milestone`: In the workflow's question, describe its "Delete without merging" option as: This will delete the branch `{branch}` of this milestone. Keep all of the workflow's options.
+- `transition`: This will skip `{plan names}`; they are not built in phase {N}. Then ask exactly as the workflow does, with the same options.
+- `vault-write-back`: This will write `{file}` to the repository `{repo}` at `{target}`, visible to everyone with access. Then ask exactly as the workflow does, with the same options.
+- `discovery-redo`: This will overwrite the notes of session {n} in `session-{nn}.md` and run the session again. Then ask exactly as the workflow does, with the same options.
+- `charter-redraft`: This will reopen `PROJECT-CHARTER.md` as version `{version}`; it must be signed again. Then ask exactly as the workflow does, with the same options.
+- `init-compose`: This will write `.platform-bindings.json` with the answers you gave. Then ask exactly as the workflow does, with the same options.
+
+### Discovery narration
+
+Show an ID next to its meaning ("decision D-03-2: one database"). Paths and check codes may appear in backticks. Keep `/pp-discovery N` commands in backticks.