@pareto4/pp-core 1.21.1 → 1.23.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pp-core",
   "displayName": "PP Core",
-  "version": "1.21.1",
+  "version": "1.23.1",
   "description": "PP Core is a meta-prompting, context engineering, and spec-driven development system for AI coding agents.",
   "author": {
     "name": "pareto4",

package/bin/install.js

@@ -349,6 +349,9 @@ const {
 const {
   updateCacheFileName,
 } = require(path.join(__dirname, '..', 'pp-core', 'bin', 'lib', 'package-identity.cjs'));
+// Phase 39 (AUD-02): the per-person audience leaf is the only reader/writer of the
+// person file; the installer never builds that path itself (it honours GSD_HOME).
+const audienceLib = require(path.join(__dirname, '..', 'pp-core', 'bin', 'lib', 'audience.cjs'));
 
 // Parse args
 const args = process.argv.slice(2);
@@ -375,6 +378,9 @@ const _profileArgRaw = (() => {
 const _profileIsCore = _profileArgRaw === 'core';
 const _requestedProfileName = (hasMinimal || _profileIsCore) ? 'core' : (_profileArgRaw || null);
 
+// Phase 39 AUD-02: pure parse here; the main block validates it before any install branch runs.
+const audienceArg = parseAudienceArg(args);
+
 if (hasMinimal && _profileArgRaw) {
   console.error(`  ${yellow}Cannot specify both --minimal/--core-only and --profile${reset}`);
   process.exit(1);
@@ -585,7 +591,7 @@ if (hasUninstall) {
 
 // Show help if requested
 if (hasHelp) {
-  console.log(`  ${yellow}Usage:${reset} npx ${pkg.name} [options]\n\n  ${yellow}Options:${reset}\n    ${cyan}-g, --global${reset}              Install globally (to config directory)\n    ${cyan}-l, --local${reset}               Install locally (to current directory)\n    ${cyan}--claude${reset}                  Install for Claude Code only\n    ${cyan}--opencode${reset}                Install for OpenCode only\n    ${cyan}--gemini${reset}                  Install for Gemini only\n    ${cyan}--kilo${reset}                    Install for Kilo only\n    ${cyan}--codex${reset}                   Install for Codex only\n    ${cyan}--kimi${reset}                    Install for Kimi CLI only\n    ${cyan}--copilot${reset}                 Install for Copilot only\n    ${cyan}--antigravity${reset}             Install for Antigravity only\n    ${cyan}--cursor${reset}                  Install for Cursor only\n    ${cyan}--windsurf${reset}                Install for Windsurf only\n    ${cyan}--augment${reset}                 Install for Augment only\n    ${cyan}--trae${reset}                    Install for Trae only\n    ${cyan}--qwen${reset}                    Install for Qwen Code only\n    ${cyan}--hermes${reset}                  Install for Hermes Agent only\n    ${cyan}--cline${reset}                   Install for Cline only\n    ${cyan}--codebuddy${reset}              Install for CodeBuddy only\n    ${cyan}--all${reset}                     Install for all runtimes\n    ${cyan}-u, --uninstall${reset}           Uninstall pp-core (remove all pp-core files)\n    ${cyan}-c, --config-dir <path>${reset}   Specify custom config directory\n    ${cyan}-h, --help${reset}                Show this help message\n    ${cyan}--force-statusline${reset}        Replace existing statusline config\n    ${cyan}--portable-hooks${reset}          Emit \$HOME-relative hook paths in settings.json\n                              (for WSL/Docker bind-mount setups; also GSD_PORTABLE_HOOKS=1)\n    ${cyan}--profile=<name>${reset}         Install a named skill profile. Profiles:\n                              core     — ${PROFILES.core.length} main-loop skills incl. phase (~130 desc tokens)\n                              standard — ${PROFILES.standard.length} skills incl. phase, review, config (~700)\n                              full     — all skills (default)\n                              Composable: --profile=core,audit installs union of closures.\n                              Profile is persisted and respected by \`pp update\`.\n    ${cyan}--minimal${reset}                 Alias for --profile=core (back-compat).\n                              Cuts cold-start overhead from ~12k tokens to ~700.\n                              Alias: --core-only.\n\n  ${yellow}Examples:${reset}\n    ${dim}# Interactive install (prompts for runtime and location)${reset}\n    npx ${pkg.name}\n\n    ${dim}# Install for Claude Code globally${reset}\n    npx ${pkg.name} --claude --global\n\n    ${dim}# Install for Gemini globally${reset}\n    npx ${pkg.name} --gemini --global\n\n    ${dim}# Install for Kilo globally${reset}\n    npx ${pkg.name} --kilo --global\n\n    ${dim}# Install for Codex globally${reset}\n    npx ${pkg.name} --codex --global\n\n    ${dim}# Install for Kimi CLI globally${reset}\n    npx ${pkg.name} --kimi --global\n\n    ${dim}# Install for Kimi CLI under ~/.kimi-code${reset}\n    npx ${pkg.name} --kimi --global --config-dir ~/.kimi-code\n\n    ${dim}# Install for Copilot globally${reset}\n    npx ${pkg.name} --copilot --global\n\n    ${dim}# Install for Copilot locally${reset}\n    npx ${pkg.name} --copilot --local\n\n    ${dim}# Install for Antigravity globally${reset}\n    npx ${pkg.name} --antigravity --global\n\n    ${dim}# Install for Antigravity locally${reset}\n    npx ${pkg.name} --antigravity --local\n\n    ${dim}# Install for Cursor globally${reset}\n    npx ${pkg.name} --cursor --global\n\n    ${dim}# Install for Cursor locally${reset}\n    npx ${pkg.name} --cursor --local\n\n    ${dim}# Install for Windsurf globally${reset}\n    npx ${pkg.name} --windsurf --global\n\n    ${dim}# Install for Windsurf locally${reset}\n    npx ${pkg.name} --windsurf --local\n\n    ${dim}# Install for Augment globally${reset}\n    npx ${pkg.name} --augment --global\n\n    ${dim}# Install for Augment locally${reset}\n    npx ${pkg.name} --augment --local\n\n    ${dim}# Install for Trae globally${reset}\n    npx ${pkg.name} --trae --global\n\n    ${dim}# Install for Trae locally${reset}\n    npx ${pkg.name} --trae --local\n\n    ${dim}# Install for Hermes Agent globally${reset}\n    npx ${pkg.name} --hermes --global\n\n    ${dim}# Install for Hermes Agent locally${reset}\n    npx ${pkg.name} --hermes --local\n\n    ${dim}# Install for Cline globally${reset}\n    npx ${pkg.name} --cline --global\n\n    ${dim}# Install for Cline locally${reset}\n    npx ${pkg.name} --cline --local\n\n    ${dim}# Install for CodeBuddy globally${reset}\n    npx ${pkg.name} --codebuddy --global\n\n    ${dim}# Install for CodeBuddy locally${reset}\n    npx ${pkg.name} --codebuddy --local\n\n    ${dim}# Install for all runtimes globally${reset}\n    npx ${pkg.name} --all --global\n\n    ${dim}# Install to custom config directory${reset}\n    npx ${pkg.name} --kilo --global --config-dir ~/.kilo-work\n\n    ${dim}# Install to current project only${reset}\n    npx ${pkg.name} --claude --local\n\n    ${dim}# Uninstall pp-core from Cursor globally${reset}\n    npx ${pkg.name} --cursor --global --uninstall\n\n  ${yellow}Notes:${reset}\n    The --config-dir option is useful when you have multiple configurations.\n    It takes priority over CLAUDE_CONFIG_DIR / OPENCODE_CONFIG_DIR / GEMINI_CONFIG_DIR / KILO_CONFIG_DIR / CODEX_HOME / KIMI_CONFIG_DIR / COPILOT_CONFIG_DIR / COPILOT_HOME / ANTIGRAVITY_CONFIG_DIR / CURSOR_CONFIG_DIR / WINDSURF_CONFIG_DIR / AUGMENT_CONFIG_DIR / TRAE_CONFIG_DIR / QWEN_CONFIG_DIR / HERMES_HOME / CLINE_CONFIG_DIR / CODEBUDDY_CONFIG_DIR environment variables.\n    Kimi CLI defaults to the first existing generic skills root: ${cyan}~/.config/agents/skills${reset}, then ${cyan}~/.agents/skills${reset}; if neither exists, pp-core creates ${cyan}~/.config/agents${reset}.\n    Use ${cyan}--config-dir ~/.kimi-code${reset} or ${cyan}KIMI_CONFIG_DIR=~/.kimi-code${reset} for brand-specific Kimi installs.\n`);
+  console.log(`  ${yellow}Usage:${reset} npx ${pkg.name} [options]\n\n  ${yellow}Options:${reset}\n    ${cyan}-g, --global${reset}              Install globally (to config directory)\n    ${cyan}-l, --local${reset}               Install locally (to current directory)\n    ${cyan}--claude${reset}                  Install for Claude Code only\n    ${cyan}--opencode${reset}                Install for OpenCode only\n    ${cyan}--gemini${reset}                  Install for Gemini only\n    ${cyan}--kilo${reset}                    Install for Kilo only\n    ${cyan}--codex${reset}                   Install for Codex only\n    ${cyan}--kimi${reset}                    Install for Kimi CLI only\n    ${cyan}--copilot${reset}                 Install for Copilot only\n    ${cyan}--antigravity${reset}             Install for Antigravity only\n    ${cyan}--cursor${reset}                  Install for Cursor only\n    ${cyan}--windsurf${reset}                Install for Windsurf only\n    ${cyan}--augment${reset}                 Install for Augment only\n    ${cyan}--trae${reset}                    Install for Trae only\n    ${cyan}--qwen${reset}                    Install for Qwen Code only\n    ${cyan}--hermes${reset}                  Install for Hermes Agent only\n    ${cyan}--cline${reset}                   Install for Cline only\n    ${cyan}--codebuddy${reset}              Install for CodeBuddy only\n    ${cyan}--all${reset}                     Install for all runtimes\n    ${cyan}-u, --uninstall${reset}           Uninstall pp-core (remove all pp-core files)\n    ${cyan}-c, --config-dir <path>${reset}   Specify custom config directory\n    ${cyan}-h, --help${reset}                Show this help message\n    ${cyan}--force-statusline${reset}        Replace existing statusline config\n    ${cyan}--portable-hooks${reset}          Emit \$HOME-relative hook paths in settings.json\n                              (for WSL/Docker bind-mount setups; also GSD_PORTABLE_HOOKS=1)\n    ${cyan}--profile=<name>${reset}         Install a named skill profile. Profiles:\n                              core     — ${PROFILES.core.length} main-loop skills incl. phase (~130 desc tokens)\n                              standard — ${PROFILES.standard.length} skills incl. phase, review, config (~700)\n                              full     — all skills (default)\n                              Composable: --profile=core,audit installs union of closures.\n                              Profile is persisted and respected by \`pp update\`.\n    ${cyan}--minimal${reset}                 Alias for --profile=core (back-compat).\n                              Cuts cold-start overhead from ~12k tokens to ~700.\n                              Alias: --core-only.\n    ${cyan}--audience <who>${reset}          Who you are: business, engineer or developer (default developer).\n                              Saved once for you, not per project; skips the first-install question.\n\n  ${yellow}Examples:${reset}\n    ${dim}# Interactive install (prompts for runtime and location)${reset}\n    npx ${pkg.name}\n\n    ${dim}# Install for Claude Code globally${reset}\n    npx ${pkg.name} --claude --global\n\n    ${dim}# Install for Gemini globally${reset}\n    npx ${pkg.name} --gemini --global\n\n    ${dim}# Install for Kilo globally${reset}\n    npx ${pkg.name} --kilo --global\n\n    ${dim}# Install for Codex globally${reset}\n    npx ${pkg.name} --codex --global\n\n    ${dim}# Install for Kimi CLI globally${reset}\n    npx ${pkg.name} --kimi --global\n\n    ${dim}# Install for Kimi CLI under ~/.kimi-code${reset}\n    npx ${pkg.name} --kimi --global --config-dir ~/.kimi-code\n\n    ${dim}# Install for Copilot globally${reset}\n    npx ${pkg.name} --copilot --global\n\n    ${dim}# Install for Copilot locally${reset}\n    npx ${pkg.name} --copilot --local\n\n    ${dim}# Install for Antigravity globally${reset}\n    npx ${pkg.name} --antigravity --global\n\n    ${dim}# Install for Antigravity locally${reset}\n    npx ${pkg.name} --antigravity --local\n\n    ${dim}# Install for Cursor globally${reset}\n    npx ${pkg.name} --cursor --global\n\n    ${dim}# Install for Cursor locally${reset}\n    npx ${pkg.name} --cursor --local\n\n    ${dim}# Install for Windsurf globally${reset}\n    npx ${pkg.name} --windsurf --global\n\n    ${dim}# Install for Windsurf locally${reset}\n    npx ${pkg.name} --windsurf --local\n\n    ${dim}# Install for Augment globally${reset}\n    npx ${pkg.name} --augment --global\n\n    ${dim}# Install for Augment locally${reset}\n    npx ${pkg.name} --augment --local\n\n    ${dim}# Install for Trae globally${reset}\n    npx ${pkg.name} --trae --global\n\n    ${dim}# Install for Trae locally${reset}\n    npx ${pkg.name} --trae --local\n\n    ${dim}# Install for Hermes Agent globally${reset}\n    npx ${pkg.name} --hermes --global\n\n    ${dim}# Install for Hermes Agent locally${reset}\n    npx ${pkg.name} --hermes --local\n\n    ${dim}# Install for Cline globally${reset}\n    npx ${pkg.name} --cline --global\n\n    ${dim}# Install for Cline locally${reset}\n    npx ${pkg.name} --cline --local\n\n    ${dim}# Install for CodeBuddy globally${reset}\n    npx ${pkg.name} --codebuddy --global\n\n    ${dim}# Install for CodeBuddy locally${reset}\n    npx ${pkg.name} --codebuddy --local\n\n    ${dim}# Install for all runtimes globally${reset}\n    npx ${pkg.name} --all --global\n\n    ${dim}# Install to custom config directory${reset}\n    npx ${pkg.name} --kilo --global --config-dir ~/.kilo-work\n\n    ${dim}# Install to current project only${reset}\n    npx ${pkg.name} --claude --local\n\n    ${dim}# Uninstall pp-core from Cursor globally${reset}\n    npx ${pkg.name} --cursor --global --uninstall\n\n  ${yellow}Notes:${reset}\n    The --config-dir option is useful when you have multiple configurations.\n    It takes priority over CLAUDE_CONFIG_DIR / OPENCODE_CONFIG_DIR / GEMINI_CONFIG_DIR / KILO_CONFIG_DIR / CODEX_HOME / KIMI_CONFIG_DIR / COPILOT_CONFIG_DIR / COPILOT_HOME / ANTIGRAVITY_CONFIG_DIR / CURSOR_CONFIG_DIR / WINDSURF_CONFIG_DIR / AUGMENT_CONFIG_DIR / TRAE_CONFIG_DIR / QWEN_CONFIG_DIR / HERMES_HOME / CLINE_CONFIG_DIR / CODEBUDDY_CONFIG_DIR environment variables.\n    Kimi CLI defaults to the first existing generic skills root: ${cyan}~/.config/agents/skills${reset}, then ${cyan}~/.agents/skills${reset}; if neither exists, pp-core creates ${cyan}~/.config/agents${reset}.\n    Use ${cyan}--config-dir ~/.kimi-code${reset} or ${cyan}KIMI_CONFIG_DIR=~/.kimi-code${reset} for brand-specific Kimi installs.\n`);
   process.exit(0);
 }
 
@@ -9842,17 +9848,13 @@ function reportLocalPatches(configDir, runtime = 'claude') {
   try { meta = JSON.parse(fs.readFileSync(metaPath, 'utf8')); } catch { return []; }
 
   if (meta.files && meta.files.length > 0) {
-    const reapplyCommand = (runtime === 'opencode' || runtime === 'kilo' || runtime === 'copilot')
-      ? '/gsd-update --reapply'
-      : runtime === 'gemini'
-        ? '/gsd:update --reapply'
-        : runtime === 'codex'
-          ? '$gsd-update --reapply'
-        : runtime === 'cursor'
-          ? 'gsd-update --reapply (mention the skill name)'
+    const reapplyCommand = runtime === 'codex'
+      ? '$pp-update --reapply'
+      : runtime === 'cursor'
+        ? 'pp-update --reapply (mention the skill name)'
         : runtime === 'kimi'
-          ? '/skill:gsd-update --reapply'
-          : '/gsd-update --reapply';
+          ? '/skill:pp-update --reapply'
+          : '/pp-update --reapply';
     console.log('');
     console.log('  ' + yellow + 'Local patches detected' + reset + ' (from v' + meta.from_version + '):');
     for (const f of meta.files) {
@@ -11471,7 +11473,7 @@ function install(isGlobal, runtime = 'claude', options = {}) {
     }
 
     persistActiveProfileMarker();
-    return { settingsPath: null, settings: null, statuslineCommand: null, updateBannerCommand: null, runtime, configDir: targetDir };
+    return { settingsPath: null, settings: null, statuslineCommand: null, updateBannerCommand: null, runtime, configDir: targetDir, priorInstallExisted };
   }
 
   if (plan.installSurface === 'copilot-instructions') {
@@ -11501,7 +11503,7 @@ function install(isGlobal, runtime = 'claude', options = {}) {
     writeCopilotHookConfig(targetDir);
     console.log(`  ${green}✓${reset} Configured Copilot lifecycle hook (sessionStart)`);
     persistActiveProfileMarker();
-    return { settingsPath: null, settings: null, statuslineCommand: null, updateBannerCommand: null, runtime, configDir: targetDir };
+    return { settingsPath: null, settings: null, statuslineCommand: null, updateBannerCommand: null, runtime, configDir: targetDir, priorInstallExisted };
   }
 
   if (plan.installSurface === 'cursor-hooks-json') {
@@ -11516,13 +11518,13 @@ function install(isGlobal, runtime = 'claude', options = {}) {
     // Re-run the manifest pass so the hook scripts + hooks.json are hash-tracked.
     writeManifest(targetDir, runtime, { mode: _effectiveInstallMode });
     persistActiveProfileMarker();
-    return { settingsPath: null, settings: null, statuslineCommand: null, updateBannerCommand: null, runtime, configDir: targetDir };
+    return { settingsPath: null, settings: null, statuslineCommand: null, updateBannerCommand: null, runtime, configDir: targetDir, priorInstallExisted };
   }
 
   if (plan.installSurface === 'profile-marker-only') {
     // Windsurf/Trae/Kimi use artifact-only surfaces — no config.toml or settings.json hooks needed.
     persistActiveProfileMarker();
-    return { settingsPath: null, settings: null, statuslineCommand: null, updateBannerCommand: null, runtime, configDir: targetDir };
+    return { settingsPath: null, settings: null, statuslineCommand: null, updateBannerCommand: null, runtime, configDir: targetDir, priorInstallExisted };
   }
 
   if (plan.installSurface === 'cline-rules') {
@@ -11534,7 +11536,7 @@ function install(isGlobal, runtime = 'claude', options = {}) {
     // writeManifest() call, so a second pass is needed to hash-track them.
     writeManifest(targetDir, runtime, { mode: _effectiveInstallMode });
     persistActiveProfileMarker();
-    return { settingsPath: null, settings: null, statuslineCommand: null, updateBannerCommand: null, runtime, configDir: targetDir };
+    return { settingsPath: null, settings: null, statuslineCommand: null, updateBannerCommand: null, runtime, configDir: targetDir, priorInstallExisted };
   }
 
   // Configure statusline and hooks in settings.json (or settings.local.json for local Claude installs).
@@ -11836,6 +11838,7 @@ function install(isGlobal, runtime = 'claude', options = {}) {
     updateBannerCommand,
     runtime,
     configDir: targetDir,
+    priorInstallExisted,
     rollbackInstallerMigrations,
   };
 }
@@ -12177,6 +12180,163 @@ function promptRuntime(callback) {
   });
 }
 
+// ─── Audience (Phase 39 AUD-02, D-07, D-09) ─────────────────────────────────
+
+/**
+ * Parse `--audience <value>` / `--audience=<value>` from argv. Pure.
+ * @param {string[]} argv
+ * @returns {{ value: string|null, error: string|null }}
+ */
+function parseAudienceArg(argv) {
+  const list = Array.isArray(argv) ? argv : [];
+  const allowed = 'business, engineer, developer';
+  let raw = null;
+  for (let i = 0; i < list.length; i++) {
+    const arg = list[i];
+    if (typeof arg !== 'string') continue;
+    if (arg === '--audience') {
+      const next = list[i + 1];
+      if (typeof next !== 'string' || next.startsWith('--')) {
+        return { value: null, error: `--audience needs a value: ${allowed}` };
+      }
+      raw = next;
+      break;
+    }
+    if (arg.startsWith('--audience=')) {
+      raw = arg.slice('--audience='.length);
+      break;
+    }
+  }
+  if (raw === null) return { value: null, error: null };
+  const value = raw.trim().toLowerCase();
+  if (!audienceLib.isAudience(value)) {
+    return { value: null, error: `--audience "${raw.slice(0, 40)}" is not one of ${allowed}` };
+  }
+  return { value, error: null };
+}
+
+/** The first-run question, identical to the one the workflows show (D-09). Pure. */
+function buildAudiencePromptText() {
+  return audienceLib.FIRST_RUN_PROMPT;
+}
+
+/**
+ * Turn a typed answer into an audience. Enter keeps developer (D-07); an
+ * unknown answer gives no audience (`recognized: false`), so a typo is never
+ * saved as a permanent developer (WR-02). Pure.
+ */
+function resolveInstallAudienceAnswer(answer) {
+  const parsed = audienceLib.parseAudienceInput(answer == null ? '' : answer);
+  if (parsed === null) return { audience: null, recognized: false };
+  return { audience: parsed, recognized: true };
+}
+
+const AUDIENCE_RETRY_NOTICE = '  Not recognised — choose 1, 2 or 3.';
+const AUDIENCE_GIVE_UP_NOTICE = '  Not recognised — nothing saved; /pp-init and /pp-discovery will ask again.';
+const AUDIENCE_NO_ANSWER_NOTICE = '  No answer — nothing saved; /pp-init and /pp-discovery will ask again.';
+
+/**
+ * True only on an interactive first install with nothing set (D-07): all four
+ * conditions must hold. Pure.
+ */
+function shouldAskAudience({ flagValue, isInteractive, hasValidPersonSetting, priorInstallExisted }) {
+  return !flagValue && !!isInteractive && !hasValidPersonSetting && !priorInstallExisted;
+}
+
+function saveInstallAudience(audience, env) {
+  // CR-01 (D-10): no language key, so a stored language override is kept.
+  const result = audienceLib.writePerson({ audience }, env);
+  if (result && result.ok) {
+    console.log(`  ${green}✓${reset} Audience set to ${audience} ${dim}(saved in ${result.path})${reset}`);
+  } else {
+    const why = result && result.error ? `: ${result.error}` : '';
+    console.log(`  ${yellow}Could not save the audience${why}. Set it later: pp-tools audience set <business|engineer|developer>${reset}`);
+  }
+}
+
+/**
+ * Provision the per-person audience during install. `--audience` always
+ * writes and never asks; otherwise ask once, on a true first install only.
+ * Never throws. The callback runs unless the user presses Ctrl-C at the
+ * prompt, which exits 130 before finalize (WR-09); a re-run completes it.
+ */
+function handleAudience({ flagValue, isInteractive, priorInstallExisted, env = process.env, ask,
+  createInterface = () => readline.createInterface({ input: process.stdin, output: process.stdout }) }, callback) {
+  if (flagValue) {
+    saveInstallAudience(flagValue, env);
+    callback();
+    return;
+  }
+  let hasValidPersonSetting = false;
+  try {
+    hasValidPersonSetting = audienceLib.readPerson(env).audience !== null;
+  } catch {
+    hasValidPersonSetting = false;
+  }
+  if (!shouldAskAudience({ flagValue, isInteractive, hasValidPersonSetting, priorInstallExisted })) {
+    callback();
+    return;
+  }
+  // An unknown answer is asked once more; still unknown, nothing is saved and
+  // the first-run question is left for /pp-init and /pp-discovery (WR-02).
+  // One readline interface serves both attempts: a second interface on the
+  // same stdin would lose lines the first one already buffered.
+  //
+  // WR-03: on Ctrl-D or a closed stdin the question callback never fires;
+  // without the close handler the event loop drains, the process exits 0 and
+  // finalize (settings.json: hooks, permissions) never runs. Treat it as
+  // "save nothing, continue". `done` is set before rl.close(), which emits
+  // 'close' synchronously, so the callback runs exactly once.
+  let attempts = 0;
+  let done = false;
+  let rl = null;
+  const askOnce = () => {
+    attempts += 1;
+    if (typeof ask === 'function') {
+      ask(buildAudiencePromptText(), finish);
+      return;
+    }
+    if (!rl) {
+      rl = createInterface();
+      // WR-09: on a TTY, readline turns Ctrl-C into rl.close() unless a
+      // 'SIGINT' listener exists, which the close handler below would read as
+      // "no answer, continue". Ctrl-C cancels, as at the other prompts.
+      rl.on('SIGINT', () => {
+        done = true;
+        console.log(`\n  ${yellow}Installation cancelled${reset}\n`);
+        rl.close();
+        process.exit(130);
+      });
+      rl.on('close', () => {
+        if (done) return;
+        done = true;
+        console.log('\n' + AUDIENCE_NO_ANSWER_NOTICE);
+        callback();
+      });
+    }
+    rl.question('  > ', finish);
+  };
+  const finish = (answer) => {
+    const { audience, recognized } = resolveInstallAudienceAnswer(answer);
+    if (!recognized && attempts < 2) {
+      console.log(AUDIENCE_RETRY_NOTICE);
+      askOnce();
+      return;
+    }
+    done = true;
+    if (rl) rl.close();
+    if (!recognized) {
+      console.log(AUDIENCE_GIVE_UP_NOTICE);
+      callback();
+      return;
+    }
+    saveInstallAudience(audience, env);
+    callback();
+  };
+  console.log(buildAudiencePromptText());
+  askOnce();
+}
+
 // ─── Update banner (#2795) ──────────────────────────────────────────────────
 
 /**
@@ -12575,6 +12735,8 @@ function installAllRuntimes(runtimes, isGlobal, isInteractive) {
     throw error;
   }
 
+  const priorInstallExisted = results.some((r) => r && r.priorInstallExisted === true);
+
   const statuslineRuntimes = ['claude', 'gemini'];
   const primaryStatuslineResult = results.find(r => statuslineRuntimes.includes(r.runtime));
 
@@ -12640,18 +12802,24 @@ function installAllRuntimes(runtimes, isGlobal, isInteractive) {
     });
   };
 
-  if (primaryStatuslineResult) {
-    handleStatusline(primaryStatuslineResult.settings, isInteractive, continueAfterStatusline);
-  } else if (canInstallBanner) {
-    // No statusline-capable runtime, but at least one runtime can host the
-    // banner — still offer it.
-    handleUpdateBanner(isInteractive, (shouldInstallBanner) => {
-      finalize(false, shouldInstallBanner);
-    });
-  } else {
-    // Nothing to prompt about — no statusline, no banner-capable runtime.
-    finalize(false, false);
-  }
+  const runRemainingPrompts = () => {
+    if (primaryStatuslineResult) {
+      handleStatusline(primaryStatuslineResult.settings, isInteractive, continueAfterStatusline);
+    } else if (canInstallBanner) {
+      // No statusline-capable runtime, but at least one runtime can host the
+      // banner — still offer it.
+      handleUpdateBanner(isInteractive, (shouldInstallBanner) => {
+        finalize(false, shouldInstallBanner);
+      });
+    } else {
+      // Nothing to prompt about — no statusline, no banner-capable runtime.
+      finalize(false, false);
+    }
+  };
+
+  // Phase 39 AUD-02 (D-07): provision the per-person audience before the
+  // statusline/banner prompts. Non-interactive paths call back immediately.
+  handleAudience({ flagValue: audienceArg.value, isInteractive, priorInstallExisted }, runRemainingPrompts);
 }
 
 // Always export so runtime-artifact-layout.cjs's lazy loader can access
@@ -12793,6 +12961,11 @@ module.exports = {
     buildRuntimePromptText,
     buildUpdateBannerPromptText,
     parseUpdateBannerInput,
+    parseAudienceArg,
+    buildAudiencePromptText,
+    resolveInstallAudienceAnswer,
+    shouldAskAudience,
+    handleAudience,
     buildUpdateBannerHookEntry,
     buildHookCommand,
     normalizeNodePath,
@@ -12824,6 +12997,10 @@ module.exports = {
 
 // Main logic — only run when not loaded as a module for testing
 if (require.main === module && !process.env.GSD_TEST_MODE) {
+  if (audienceArg.error) {
+    console.error('  ' + yellow + audienceArg.error + reset);
+    process.exit(1);
+  }
   if (hasDryRun) {
     // --dry-run: preview legacy cleanup and exit without installing.
     if (hasUninstall) {

package/commands/pp-help.md

@@ -4,11 +4,12 @@ description: Show available pp-core commands and usage guide
 argument-hint: "[--brief | --full | <topic> | --brief <topic>]"
 allowed-tools:
   - Read
+  - Bash
 ---
 <objective>
 Display pp-core help at the tier the user asked for: brief (one-line refresher), default (one-page tour), full (complete reference), a single topic section, or a compact scoped lookup of one topic (`--brief <topic>`: signature + one-line summary).
 
-Output ONLY the reference content of the chosen tier. Do NOT add:
+Output ONLY the reference content of the chosen tier. For a business user or a business engineer, help.md prints one audience header line first; that line is part of the output. Do NOT add:
 - Project-specific analysis
 - Git status or file context
 - Next-step suggestions

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "pp-core",
-  "version": "1.21.1",
+  "version": "1.23.1",
   "description": "PP Core — a meta-prompting, context engineering, and spec-driven development system for AI coding agents. Loads pp-core's operating context into every Gemini CLI session.",
   "contextFileName": "GEMINI.md"
 }

package/hooks/dist/pp-check-update-worker.js

@@ -18,7 +18,7 @@ const { isSemverNewer } = require('../pp-core/bin/lib/semver-compare.cjs');
 // The previous `require('../package.json').name` (#378) resolved to undefined
 // in the installed tree (only a {"type":"commonjs"} marker ships), so the
 // background check never reported updates.
-const { checkLatestVersion } = require('../gsd-core/bin/check-latest-version.cjs');
+const { checkLatestVersion } = require('../pp-core/bin/check-latest-version.cjs');
 const { PACKAGE_NAME } = require('../pp-core/bin/lib/package-identity.cjs');
 // Authoritative list of managed hooks — shared with tests to retire source-grep
 // assertions (pending-migration-to-typed-ir [#455]).

package/hooks/dist/pp-context-monitor.js

@@ -133,7 +133,7 @@ process.stdin.on('end', () => {
     const isGsdActive = fs.existsSync(path.join(cwd, '.planning', 'STATE.md'));
 
     // On CRITICAL with active GSD project, auto-record session state as a
-    // breadcrumb for /gsd:resume-work (#1974). Fire-and-forget subprocess —
+    // breadcrumb for /pp-resume-work (#1974). Fire-and-forget subprocess —
     // doesn't block the hook or the agent. Fires ONCE per CRITICAL session,
     // guarded by warnData.criticalRecorded to prevent repeated overwrites
     // of the "crash moment" record on every debounce cycle.
@@ -165,8 +165,8 @@ process.stdin.on('end', () => {
       message = isGsdActive
         ? `CONTEXT CRITICAL: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
           'Context is nearly exhausted. Do NOT start new complex work or write handoff files — ' +
-          'GSD state is already tracked in STATE.md. Inform the user so they can run ' +
-          '/gsd:pause-work at the next natural stopping point.'
+          'pp-core state is already tracked in STATE.md. Inform the user so they can run ' +
+          '/pp-pause-work at the next natural stopping point.'
         : `CONTEXT CRITICAL: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
           'Context is nearly exhausted. Inform the user that context is low and ask how they ' +
           'want to proceed. Do NOT autonomously save state or write handoff files unless the user asks.';

package/hooks/dist/pp-statusline.js

@@ -9,6 +9,59 @@ const os = require('os');
 const { isSemverNewer } = require('../pp-core/bin/lib/semver-compare.cjs');
 const { PACKAGE_NAME, updateCacheFileName } = require('../pp-core/bin/lib/package-identity.cjs');
 
+// --- Audience wording (MSG-06, D-18, D-20) ----------------------------------
+// The light catalog entry. When it cannot load (missing, broken, or its slice
+// missing) every text below stays today's developer string.
+let hookMessages = null;
+try {
+  hookMessages = require('../pp-core/bin/lib/hook-messages.cjs');
+} catch (e) {
+  hookMessages = null;
+}
+
+/** The audience for this process; developer when the catalog is unavailable or throws. */
+function hookAudience() {
+  if (!hookMessages) return 'developer';
+  try {
+    return hookMessages.audienceOf(process.env);
+  } catch (e) {
+    return 'developer';
+  }
+}
+
+/** The catalog text for `code`, or `literal` (today's developer string) on any failure. */
+function hookText(code, params, audience, literal) {
+  if (!hookMessages || audience === 'developer') return literal;
+  try {
+    const out = hookMessages.msg(code, params, audience, literal);
+    return typeof out === 'string' && out !== '' ? out : literal;
+  } catch (e) {
+    return literal;
+  }
+}
+
+/** The display word for a canonical value, or the value itself on any failure. */
+function hookLabel(domain, value, audience) {
+  if (!hookMessages || audience === 'developer') return value;
+  try {
+    const out = hookMessages.label(domain, value, audience);
+    return typeof out === 'string' && out !== '' ? out : value;
+  } catch (e) {
+    return value;
+  }
+}
+
+/** The display text for a STATE.md status, or the status itself on any failure. */
+function hookStatusWord(status, audience) {
+  if (!hookMessages || audience === 'developer') return status;
+  try {
+    const out = hookMessages.statusWord(status, audience);
+    return typeof out === 'string' && out !== '' ? out : status;
+  } catch (e) {
+    return status;
+  }
+}
+
 // --- Config + last-command readers ------------------------------------------
 
 /**
@@ -241,7 +294,8 @@ function renderProgressBar(percent) {
  * Progress bar is opt-in: appended to the milestone segment only when
  * progress.percent is present in frontmatter; absent → empty string.
  */
-function formatGsdState(s) {
+function formatGsdState(s, opts) {
+  const audience = (opts && opts.audience) || 'developer';
   const parts = [];
 
   // Milestone segment: version + name + (opt-in) progress bar
@@ -261,24 +315,41 @@ function formatGsdState(s) {
     // Scene 1: an orchestrator is mid-flight on this phase.
     // stage = whichever lifecycle status was written by the orchestrator
     //   (discussing / planning / executing / verifying)
-    const stage = s.status || '';
-    parts.push(stage ? `Phase ${s.activePhase} ${stage}` : `Phase ${s.activePhase}`);
+    const stage = s.status ? hookStatusWord(s.status, audience) : '';
+    parts.push(stage
+      ? hookText('hook.statusline.phase_stage', { number: s.activePhase, stage }, audience, `Phase ${s.activePhase} ${s.status}`)
+      : hookText('hook.statusline.phase', { number: s.activePhase }, audience, `Phase ${s.activePhase}`));
   } else if (s.nextAction && phasesStr) {
     // Scene 2: idle + a recommended next command is visible to the user.
     // Surfaces "what to run next" without the user opening STATE.md.
-    parts.push(`next ${s.nextAction} ${phasesStr}`);
+    parts.push(hookText(
+      'hook.statusline.next',
+      { action: hookLabel('state.next_action', s.nextAction, audience), numbers: phasesStr },
+      audience,
+      `next ${s.nextAction} ${phasesStr}`
+    ));
   } else if (Number(s.percent) === 100 || (s.completedPhases && s.totalPhases && s.completedPhases === s.totalPhases)) {
     // Scene 3: milestone complete (every phase done).
-    parts.push('milestone complete');
+    parts.push(hookText('hook.statusline.milestone_complete', {}, audience, 'milestone complete'));
   } else {
     // Backward-compatible default — preserved EXACTLY for STATE.md files that
     // don't carry the new lifecycle fields. Identical output to v1.38.x and
     // earlier so no existing project's status-line changes shape.
-    if (s.status) parts.push(s.status);
+    if (s.status) parts.push(hookStatusWord(s.status, audience));
     if (s.phaseNum && s.phaseTotal) {
       const phase = s.phaseName
-        ? `${s.phaseName} (${s.phaseNum}/${s.phaseTotal})`
-        : `ph ${s.phaseNum}/${s.phaseTotal}`;
+        ? hookText(
+          'hook.statusline.phase_named',
+          { name: s.phaseName, num: s.phaseNum, total: s.phaseTotal },
+          audience,
+          `${s.phaseName} (${s.phaseNum}/${s.phaseTotal})`
+        )
+        : hookText(
+          'hook.statusline.phase_count',
+          { num: s.phaseNum, total: s.phaseTotal },
+          audience,
+          `ph ${s.phaseNum}/${s.phaseTotal}`
+        );
       parts.push(phase);
     }
   }
@@ -393,7 +464,9 @@ function runStatusline() {
     }
 
     // GSD state (milestone · status · phase) — shown when no todo task
-    const gsdStateStr = task ? '' : formatGsdState(readGsdState(dir) || {});
+    // The audience is resolved once per run, never inside the formatter (Pitfall 7).
+    const audience = hookAudience();
+    const gsdStateStr = task ? '' : formatGsdState(readGsdState(dir) || {}, { audience });
 
     // GSD update available?
     // Read only the per-package shared cache file (#607). The legacy
@@ -406,12 +479,12 @@ function runStatusline() {
         const cache = JSON.parse(fs.readFileSync(cacheFile, 'utf8'));
         const { showUpdate, staleWarning } = evaluateUpdateCache(cache);
         if (showUpdate) {
-          gsdUpdate = '\x1b[33m⬆ /gsd:update\x1b[0m │ ';
+          gsdUpdate = '\x1b[33m' + hookText('hook.statusline.update', {}, audience, '⬆ /pp-update') + '\x1b[0m │ ';
         }
         if (staleWarning === 'dev') {
-          gsdUpdate += '\x1b[33m⚠ dev install — re-run installer to sync hooks\x1b[0m │ ';
+          gsdUpdate += '\x1b[33m' + hookText('hook.statusline.dev_install', {}, audience, '⚠ dev install — re-run installer to sync hooks') + '\x1b[0m │ ';
         } else if (staleWarning === 'stale') {
-          gsdUpdate += '\x1b[31m⚠ stale hooks — run /gsd:update\x1b[0m │ ';
+          gsdUpdate += '\x1b[31m' + hookText('hook.statusline.stale', {}, audience, '⚠ stale hooks — run /pp-update') + '\x1b[0m │ ';
         }
       } catch (e) {}
     }
@@ -556,7 +629,8 @@ module.exports = {
  * Render the statusline from an already-parsed hook input object. Exported for
  * testing without feeding stdin. Returns the rendered string.
  */
-function renderStatusline(data) {
+function renderStatusline(data, opts) {
+  const audience = (opts && opts.audience) || hookAudience();
   const model = data.model?.display_name || 'Claude';
   const dir = data.workspace?.current_dir || process.cwd();
   const dirname = path.basename(dir);
@@ -575,7 +649,7 @@ function renderStatusline(data) {
     if (cfgPos != null) position = cfgPos;
   } catch (e) { /* swallow */ }
 
-  const gsdStateStr = formatGsdState(readGsdState(dir) || {});
+  const gsdStateStr = formatGsdState(readGsdState(dir) || {}, { audience });
   const middle = gsdStateStr ? `\x1b[2m${gsdStateStr}\x1b[0m` : null;
   return formatDevBadge(readDevBuild()) + composeStatusline({ model, ctx: '', middle, dirname, lastCmdSuffix, position });
 }