@pareto4/pp-core 1.5.4 → 1.6.1

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

@@ -1,7 +1,7 @@
 "use strict";
 /**
  * Manifest-backed verify subcommand router.
- * Keeps gsd-tools.cjs thin while preserving existing command semantics.
+ * Keeps pp-tools.cjs thin while preserving existing command semantics.
  *
  * ADR-457 build-at-publish: the hand-written bin/lib/verify-command-router.cjs
  * collapsed to a TypeScript source of truth. Behaviour is preserved byte-for-behaviour

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

@@ -1432,7 +1432,7 @@ function cmdValidateHealth(cwd, options, raw) {
                     getMilestoneFromPhaseId: getMilestoneFromPhaseId,
                 });
                 for (const mm of mismatches) {
-                    addIssue('warning', 'W021', `Phase ${mm.phaseId}: integer prefix implies ${mm.expectedMilestone} but listed under ${mm.foundInMilestone}`, 'Run `gsd-tools roadmap upgrade --convention milestone-prefixed` to migrate (dry-run by default)');
+                    addIssue('warning', 'W021', `Phase ${mm.phaseId}: integer prefix implies ${mm.expectedMilestone} but listed under ${mm.foundInMilestone}`, 'Run `pp-tools roadmap upgrade --convention milestone-prefixed` to migrate (dry-run by default)');
                 }
             }
         }

package/pp-core/bin/lib/worktree-base-ref.cjs

@@ -94,9 +94,9 @@ function parseJsonc(text) {
 }
 // ─── Message constants (verbatim — downstream docs/tests depend on these) ─────
 function buildMsgDiverged(headSha, forkRef, forkSha) {
-    return `⚠ Worktree base mismatch: HEAD (${shortSha(headSha)}) differs from ${forkRef} (${shortSha(forkSha)}). Running this phase sequentially on the main working tree. To keep parallel worktrees, set worktree.baseRef:"head" in .claude/settings.local.json (or run: gsd-tools worktree set-baseref). See #683.`;
+    return `⚠ Worktree base mismatch: HEAD (${shortSha(headSha)}) differs from ${forkRef} (${shortSha(forkSha)}). Running this phase sequentially on the main working tree. To keep parallel worktrees, set worktree.baseRef:"head" in .claude/settings.local.json (or run: pp-tools worktree set-baseref). See #683.`;
 }
-const MSG_UNKNOWN = `⚠ Cannot determine the worktree fork base (origin/HEAD unresolved). Running this phase sequentially on the main working tree to avoid a base mismatch. To keep parallel worktrees, set worktree.baseRef:"head" in .claude/settings.local.json (or run: gsd-tools worktree set-baseref). See #683.`;
+const MSG_UNKNOWN = `⚠ Cannot determine the worktree fork base (origin/HEAD unresolved). Running this phase sequentially on the main working tree to avoid a base mismatch. To keep parallel worktrees, set worktree.baseRef:"head" in .claude/settings.local.json (or run: pp-tools worktree set-baseref). See #683.`;
 // ─── Exports ──────────────────────────────────────────────────────────────────
 /**
  * Returns the first 8 characters of a SHA, or '' if null/empty.

package/pp-core/bin/lib/worktree-safety.cjs

@@ -958,7 +958,7 @@ function pruneOrphanedWorktrees(repoRoot) {
         const plan = planWorktreePrune(repoRoot, { allowDestructive: false }, { parseWorktreePorcelain });
         const pruneResult = executeWorktreePrunePlan(plan);
         if (pruneResult && pruneResult.timedOut) {
-            process.stderr.write('[gsd-tools] WARNING: worktree health check degraded' +
+            process.stderr.write('[pp-tools] WARNING: worktree health check degraded' +
                 ' — git worktree prune timed out after 10s.' +
                 ' Orphaned worktree metadata may remain until the next successful run.\n');
         }

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

@@ -6,7 +6,7 @@
  * Replaces repetitive inline bash patterns across ~50 GSD command/workflow/agent files.
  * Centralizes: config parsing, model resolution, phase lookup, git commits, summary verification.
  *
- * Usage: node gsd-tools.cjs <command> [args] [--raw] [--pick <field>]
+ * Usage: node pp-tools.cjs <command> [args] [--raw] [--pick <field>]
  *
  * Atomic Commands:
  *   state load                         Load project config + state
@@ -209,6 +209,7 @@ const phase = require('./lib/phase.cjs');
 const roadmap = require('./lib/roadmap.cjs');
 const verify = require('./lib/verify.cjs');
 const config = require('./lib/config.cjs');
+const platformBindings = require('./lib/platform-bindings.cjs');
 const template = require('./lib/template.cjs');
 const milestone = require('./lib/milestone.cjs');
 const commands = require('./lib/commands.cjs');
@@ -236,6 +237,7 @@ const { routeTaskCommand } = require('./lib/task-command-router.cjs');
 const { parseNamedArgs, parseMultiwordArg } = require('./lib/command-arg-projection.cjs');
 const { cmdGitBaseBranch } = require('./lib/git-base-branch.cjs');
 const { getEffectiveAuthority, classifyDriftSeverity } = require('./lib/plan-drift-guard.cjs');
+const profileOutput = require('./lib/profile-output.cjs');
 
 // ─── Bridge collapsed (Phase 4) ────────────────────────────────────────────────
 // Non-family commands now run through their CJS handlers directly. Keep the
@@ -251,7 +253,7 @@ const { getEffectiveAuthority, classifyDriftSeverity } = require('./lib/plan-dri
  * @param {object} opts
  * @param {string} opts.registryCommand - legacy bridge placeholder
  * @param {string[]} opts.registryArgs - legacy bridge placeholder
- * @param {string} opts.legacyCommand - original gsd-tools command name
+ * @param {string} opts.legacyCommand - original pp-tools command name
  * @param {string[]} opts.legacyArgs - original args
  * @param {string} opts.cwd - project dir
  * @param {boolean} opts.raw - raw output mode
@@ -291,7 +293,7 @@ function _dispatchNonFamily({ registryCommand, registryArgs, legacyCommand, lega
  *   before requiring — defense-in-depth against corrupted/hand-edited registry entries.
  *
  * @param {object}   opts
- * @param {string}   opts.command        The command name (top-level gsd-tools command)
+ * @param {string}   opts.command        The command name (top-level pp-tools command)
  * @param {string[]} opts.args           Remaining args passed to the router
  * @param {string}   opts.cwd            Project working directory
  * @param {boolean}  opts.raw            Raw output mode flag
@@ -485,7 +487,7 @@ async function main() {
   let command = args[0];
 
   // Accept `query` as a meta-prefix for canonical dotted/spaced commands.
-  // Workflows may call `node gsd-tools.cjs query <command>` directly.
+  // Workflows may call `node pp-tools.cjs query <command>` directly.
   if (command === 'query') {
     args.shift();
     command = args[0];
@@ -510,21 +512,21 @@ async function main() {
     }
   }
 
-  // Top-level usage string — emitted by `gsd-tools` (no args) and by
-  // `gsd-tools --help` / any `--help` request below.
+  // Top-level usage string — emitted by `pp-tools` (no args) and by
+  // `pp-tools --help` / any `--help` request below.
   // CR feedback: the command list must enumerate every top-level command
   // supported by the dispatcher so `--help` is actually useful for
   // discovery; previously it was a partial subset that didn't include
   // phase / roadmap / milestone / progress / etc.
-  const TOP_LEVEL_USAGE = 'Usage: gsd-tools <command> [args] [--raw] [--pick <field>] [--cwd <path>] [--ws <name>] [--json-errors]\n' +
+  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, ' +
     'config-ensure-section, config-get, config-new-project, config-path, config-set, migrate-config, ' +
     'current-timestamp, detect-custom-files, docs-init, drift-guard, effort, extract-messages, find-phase, ' +
     'from-gsd2, frontmatter, gap-analysis, generate-claude-md, generate-claude-profile, ' +
-    'generate-dev-preferences, generate-slug, graphify, history-digest, init, intel, ' +
-    'capability, classify-confidence, git, learnings, list-todos, loop, milestone, package-legitimacy, phase, phase-plan-index, phases, profile-questionnaire, ' +
+    'generate-client-context, generate-dev-preferences, generate-slug, graphify, history-digest, init, intel, ' +
+    'capability, classify-confidence, git, learnings, list-todos, loop, milestone, package-legitimacy, phase, phase-plan-index, phases, platform-bindings, profile-questionnaire, ' +
     'profile-sample, progress, prompt-budget, requirements, research-plan, research-store, resolve-granularity, resolve-model, roadmap, scaffold, state, ' +
-    'task, template, user-story, validate, verify, verify-path-exists, verify-summary, workstream, worktree\n\n' +
+    'task, template, user-story, validate, validate-bindings, verify, verify-path-exists, verify-summary, workstream, worktree\n\n' +
     'Global flags:\n' +
     '  --raw              Emit raw output without post-processing\n' +
     '  --pick <field>     Extract a single field from JSON output (dot/bracket notation)\n' +
@@ -532,7 +534,7 @@ async function main() {
     '  --ws <name>        Override active workstream (or set GSD_WORKSTREAM)\n' +
     '  --json-errors      Emit structured JSON error objects on stderr (or set GSD_JSON_ERRORS=1)\n\n' +
     'For command-specific argument requirements, invoke the command without args ' +
-    '(e.g. `gsd-tools phase add`) — the resulting error lists what is required.';
+    '(e.g. `pp-tools phase add`) — the resulting error lists what is required.';
 
   if (!command) {
     error(TOP_LEVEL_USAGE);
@@ -556,7 +558,7 @@ async function main() {
   const NEVER_VALID_FLAGS = new Set(['--version', '-v']);
   for (const arg of args) {
     if (NEVER_VALID_FLAGS.has(arg)) {
-      error(`Unknown flag: ${arg}\ngsd-tools does not accept version flags. Run "gsd-tools" with no arguments for usage.`, ERROR_REASON.USAGE);
+      error(`Unknown flag: ${arg}\npp-tools does not accept version flags. Run "pp-tools" with no arguments for usage.`, ERROR_REASON.USAGE);
     }
   }
 
@@ -697,6 +699,41 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
       break;
     }
 
+    case 'platform-bindings': {
+      platformBindings.cmdPlatformBindings(cwd, args.slice(1), raw);
+      break;
+    }
+
+    case 'validate-bindings': {
+      platformBindings.cmdValidateBindings(cwd, args.slice(1), raw);
+      break;
+    }
+
+    case 'generate-client-context': {
+      // generate-client-context --from-json <path> [--output <path>] [--force]
+      // generate-client-context --read [--output <path>]
+      const gcArgs = args.slice(1);
+      const gcOptions = {};
+      for (let i = 0; i < gcArgs.length; i++) {
+        const a = gcArgs[i];
+        if (a === '--from-json') {
+          const v = gcArgs[i + 1];
+          if (v !== undefined && !v.startsWith('--')) { gcOptions.fromJson = v; i++; }
+          else error('--from-json requires a <path> argument');
+        } else if (a === '--output') {
+          const v = gcArgs[i + 1];
+          if (v !== undefined && !v.startsWith('--')) { gcOptions.output = v; i++; }
+          else error('--output requires a <path> argument');
+        } else if (a === '--read') {
+          gcOptions.read = true;
+        } else if (a === '--force') {
+          gcOptions.force = true;
+        }
+      }
+      profileOutput.cmdGenerateClientContext(cwd, gcOptions, raw);
+      break;
+    }
+
     case 'resolve-granularity': {
       // Parse optional --granularity <val> flag (space form only); positional is phase-type.
       // The =form (--granularity=<val>) is intentionally not supported: parseNamedArgs and
@@ -1500,18 +1537,18 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
       } else if (subcommand === 'query') {
         const tagIdx = args.indexOf('--tag');
         const tag = tagIdx !== -1 ? args[tagIdx + 1] : null;
-        if (!tag) error('Usage: gsd-tools learnings query --tag <tag>', ERROR_REASON.USAGE);
+        if (!tag) error('Usage: pp-tools learnings query --tag <tag>', ERROR_REASON.USAGE);
         learnings.cmdLearningsQuery(tag, raw);
       } else if (subcommand === 'copy') {
         learnings.cmdLearningsCopy(cwd, raw);
       } else if (subcommand === 'prune') {
         const olderIdx = args.indexOf('--older-than');
         const olderThan = olderIdx !== -1 ? args[olderIdx + 1] : null;
-        if (!olderThan) error('Usage: gsd-tools learnings prune --older-than <duration>', ERROR_REASON.USAGE);
+        if (!olderThan) error('Usage: pp-tools learnings prune --older-than <duration>', ERROR_REASON.USAGE);
         learnings.cmdLearningsPrune(olderThan, raw);
       } else if (subcommand === 'delete') {
         const id = args[2];
-        if (!id) error('Usage: gsd-tools learnings delete <id>', ERROR_REASON.USAGE);
+        if (!id) error('Usage: pp-tools learnings delete <id>', ERROR_REASON.USAGE);
         learnings.cmdLearningsDelete(id, raw);
       } else {
         error('Unknown learnings subcommand. Available: list, query, copy, prune, delete', ERROR_REASON.SDK_UNKNOWN_COMMAND);
@@ -1550,7 +1587,7 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
       const configDirIdx = args.indexOf('--config-dir');
       const configDir = configDirIdx !== -1 ? args[configDirIdx + 1] : null;
       if (!configDir) {
-        error('Usage: gsd-tools detect-custom-files --config-dir <path>', ERROR_REASON.USAGE);
+        error('Usage: pp-tools detect-custom-files --config-dir <path>', ERROR_REASON.USAGE);
       }
       const resolvedConfigDir = path.resolve(configDir);
       if (!fs.existsSync(resolvedConfigDir)) {
@@ -1859,7 +1896,7 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
       if (subcommand === 'get') {
         const key = args[2];
         if (!key || key.startsWith('--')) {
-          error('Usage: gsd-tools research-store get <key> [--kind <k>]', ERROR_REASON.USAGE);
+          error('Usage: pp-tools research-store get <key> [--kind <k>]', ERROR_REASON.USAGE);
         }
         if (!researchStore.isValidResearchKey(key)) {
           error('research-store: <key> must be a 64-char sha256 hex (use research-plan to obtain keys)', ERROR_REASON.USAGE);
@@ -1870,7 +1907,7 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
       } else if (subcommand === 'put') {
         const key = args[2];
         if (!key || key.startsWith('--')) {
-          error('Usage: gsd-tools research-store put <key> --content <str> --source <s> --provider <p> --confidence <c> --kind <k>', ERROR_REASON.USAGE);
+          error('Usage: pp-tools research-store put <key> --content <str> --source <s> --provider <p> --confidence <c> --kind <k>', ERROR_REASON.USAGE);
         }
         if (!researchStore.isValidResearchKey(key)) {
           error('research-store: <key> must be a 64-char sha256 hex (use research-plan to obtain keys)', ERROR_REASON.USAGE);
@@ -1895,7 +1932,7 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
         const confidence = getFlagValue(confidenceIdx, '--confidence');
         const kind = getFlagValue(kindIdx, '--kind');
         if (!content || !source || !provider || !confidence || !kind) {
-          error('Usage: gsd-tools research-store put <key> --content <str> --source <s> --provider <p> --confidence <c> --kind <k>', ERROR_REASON.USAGE);
+          error('Usage: pp-tools research-store put <key> --content <str> --source <s> --provider <p> --confidence <c> --kind <k>', ERROR_REASON.USAGE);
         }
         const entry = researchStore.putResearch(cwd, key, { content, source, provider, confidence, kind }, { homeDir });
         output(entry, raw);
@@ -1916,7 +1953,7 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
       const inputIdx = args.indexOf('--input');
       const inputPath = inputIdx !== -1 ? args[inputIdx + 1] : null;
       if (!inputPath || inputPath.startsWith('--')) {
-        error('Usage: gsd-tools research-plan --input <path>', ERROR_REASON.USAGE);
+        error('Usage: pp-tools research-plan --input <path>', ERROR_REASON.USAGE);
       }
       let planInput;
       try {
@@ -1950,7 +1987,7 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
       const providerIdx = args.indexOf('--provider');
       const provider = providerIdx !== -1 ? args[providerIdx + 1] : null;
       if (!provider || provider.startsWith('--')) {
-        error('Usage: gsd-tools query classify-confidence --provider <id> [--package <name> --ecosystem <npm|pypi|crates>] [--verified]', ERROR_REASON.USAGE);
+        error('Usage: pp-tools query classify-confidence --provider <id> [--package <name> --ecosystem <npm|pypi|crates>] [--verified]', ERROR_REASON.USAGE);
       }
       const verified = args.includes('--verified');
       const pkgIdx = args.indexOf('--package');
@@ -1961,7 +1998,7 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
       if (pkg && (!pkg.startsWith('--'))) {
         const VALID_ECOSYSTEMS = new Set(['npm', 'pypi', 'crates']);
         if (!ecosystem || ecosystem.startsWith('--') || !VALID_ECOSYSTEMS.has(ecosystem)) {
-          error('Usage: gsd-tools query classify-confidence --provider <id> [--package <name> --ecosystem <npm|pypi|crates>] [--verified]', ERROR_REASON.USAGE);
+          error('Usage: pp-tools query classify-confidence --provider <id> [--package <name> --ecosystem <npm|pypi|crates>] [--verified]', ERROR_REASON.USAGE);
         }
         const pkgLegitimacy = require('./lib/package-legitimacy.cjs');
         const results = await pkgLegitimacy.checkPackages({ ecosystem, packages: [pkg] }, {});
@@ -1989,7 +2026,7 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
       const ecosystem = ecoIdx !== -1 ? args[ecoIdx + 1] : null;
       const VALID_ECOSYSTEMS = new Set(['npm', 'pypi', 'crates']);
       if (!ecosystem || !VALID_ECOSYSTEMS.has(ecosystem)) {
-        error('Usage: gsd-tools package-legitimacy check --ecosystem <npm|pypi|crates> <pkg1> ...', ERROR_REASON.USAGE);
+        error('Usage: pp-tools package-legitimacy check --ecosystem <npm|pypi|crates> <pkg1> ...', ERROR_REASON.USAGE);
       }
       // Collect positional package names.
       // Only --ecosystem takes a value. Every non-flag arg is a package name.
@@ -2004,7 +2041,7 @@ async function runCommand(command, args, cwd, raw, defaultValue, originalCommand
         packages.push(a);
       }
       if (packages.length === 0) {
-        error('Usage: gsd-tools package-legitimacy check --ecosystem <eco> <pkg1> <pkg2> ...', ERROR_REASON.USAGE);
+        error('Usage: pp-tools package-legitimacy check --ecosystem <eco> <pkg1> <pkg2> ...', ERROR_REASON.USAGE);
       }
       let pkgResults;
       try {

package/pp-core/workflows/discovery-sprint.md

@@ -16,7 +16,19 @@ First parse `SESSION_ARG` (the optional session number 1–13) from `$ARGUMENTS`
 
 ```bash
 _PP_SHIM_NAME="pp-tools.cjs"; _PP_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; PP_TOOLS="${_PP_RUNTIME_ROOT}/pp-core/bin/${_PP_SHIM_NAME}"; if [ -f "$PP_TOOLS" ]; then pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${_PP_RUNTIME_ROOT}/.claude/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${_PP_RUNTIME_ROOT}/.claude/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${_PP_RUNTIME_ROOT}/.codex/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${_PP_RUNTIME_ROOT}/.codex/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif command -v pp-tools >/dev/null 2>&1; then PP_TOOLS="$(command -v pp-tools)"; pp_run() { "$PP_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${HERMES_HOME:-$HOME/.hermes}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${HERMES_HOME:-$HOME/.hermes}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CURSOR_CONFIG_DIR:-$HOME/.cursor}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${CODEX_HOME:-$HOME/.codex}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CODEX_HOME:-$HOME/.codex}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${GEMINI_CONFIG_DIR:-$HOME/.gemini}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${COPILOT_CONFIG_DIR:-$HOME/.copilot}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${AUGMENT_CONFIG_DIR:-$HOME/.augment}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${TRAE_CONFIG_DIR:-$HOME/.trae}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${TRAE_CONFIG_DIR:-$HOME/.trae}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${QWEN_CONFIG_DIR:-$HOME/.qwen}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${QWEN_CONFIG_DIR:-$HOME/.qwen}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${CLINE_CONFIG_DIR:-$HOME/.cline}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CLINE_CONFIG_DIR:-$HOME/.cline}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${GROK_AGENTS_HOME:-$HOME/.agents}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${GROK_AGENTS_HOME:-$HOME/.agents}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; else echo "ERROR: pp-tools.cjs not found at $PP_TOOLS and pp-tools is not on PATH. Run: npx -y @pareto4/pp-core@latest --claude --local" >&2; exit 1; fi; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${PP_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${PP_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
-SESSION_ARG=$(printf '%s\n' "${ARGUMENTS:-}" | grep -oE '(1[0-3]|[1-9])' | head -1)
+# WR-03: validate the FULL numeric token. The old pattern (1[0-3]|[1-9]) let grep
+# truncate out-of-range input to a spuriously valid session (14→1, 25→2, 99→9).
+# Extract the whole digit run, then range-check 1–13; flag anything else as invalid.
+SESSION_RAW=$(printf '%s' "${ARGUMENTS:-}" | grep -oE '[0-9]+' | head -1)
+SESSION_ARG=""
+SESSION_INVALID=""
+if [ -n "$SESSION_RAW" ]; then
+  if [ "$SESSION_RAW" -ge 1 ] 2>/dev/null && [ "$SESSION_RAW" -le 13 ] 2>/dev/null; then
+    SESSION_ARG="$SESSION_RAW"
+  else
+    SESSION_INVALID="$SESSION_RAW"
+  fi
+fi
 INIT=$(pp_run query init.phase-op "${SESSION_ARG:-}")
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
@@ -26,9 +38,10 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 **Text mode:** Set `TEXT_MODE=true` if `--text` is present in `$ARGUMENTS` OR `text_mode` from init JSON is `true`. When TEXT_MODE is active, replace every `AskUserQuestion` call with a plain-text numbered list and ask the user to type their choice number. This is required for non-Claude runtimes (Codex, Gemini CLI, etc.) where `AskUserQuestion` is not available.
 
 **Dispatch:**
-- If `SESSION_ARG` is empty → execute **Flow 1: Show Progress**
-- If `SESSION_ARG` is a number 1–13 → execute **Flow 2: Facilitate Session N**
-- Otherwise → show usage error
+- If `SESSION_INVALID` is non-empty → show a usage error: "Session `$SESSION_INVALID` is out
+  of range — valid sessions are 1–13." Do not run any session or the progress view.
+- Else if `SESSION_ARG` is empty (no numeric argument) → execute **Flow 1: Show Progress**
+- Else (`SESSION_ARG` is a number 1–13) → execute **Flow 2: Facilitate Session N**
 
 ---
 
@@ -694,8 +707,8 @@ This session uses the **Session 3: Process-First Protocol** (Steps 5A–5G descr
 2. **Technology stack selection**
    - What is the preferred frontend technology (React, Angular, Vue, Mendix, etc.)?
    - What is the preferred backend technology (Node.js, .NET, Java, Python)?
-   - What database technology is appropriate (relational, document, graph, time-series)?
-   - What messaging or eventing technology will be used (Kafka, RabbitMQ, Azure Service Bus)?
+   - What database technology is appropriate (relational e.g. Cloud SQL via pareto-platform-gcp, document, graph, time-series)?
+   - What messaging or eventing technology will be used (Google Cloud Pub/Sub via pareto-platform-gcp, Kafka, RabbitMQ)?
    - What caching strategy applies (Redis, in-memory, CDN)?
 
 3. **Key architectural components**
@@ -717,6 +730,8 @@ This session uses the **Session 3: Process-First Protocol** (Steps 5A–5G descr
 
 **Notes Template:**
 
+> **Platform standard (D-08):** The Pareto platform standard is GCP / `pareto-platform-gcp`. Fill this table against that baseline unless the client has an overriding constraint.
+
 **Technology Stack Decisions**
 
 | Layer | Technology | Version | Rationale | Alternatives Considered | Risk |
@@ -1129,7 +1144,7 @@ This session uses the **Session 3: Process-First Protocol** (Steps 5A–5G descr
 **What We Cover:**
 
 1. **Cloud / hosting strategy**
-   - What cloud provider will be used (AWS, Azure, GCP, on-premises, hybrid)?
+   - What cloud provider will be used (GCP / `pareto-platform-gcp` is the Pareto platform standard; or AWS, Azure, on-premises, hybrid)?
    - What is the account and subscription structure?
    - What regions and availability zones are required?
    - Are there data sovereignty or residency requirements that constrain hosting?
@@ -1138,12 +1153,12 @@ This session uses the **Session 3: Process-First Protocol** (Steps 5A–5G descr
 2. **Deployment strategy**
    - What deployment model will be used (blue-green, canary, rolling, immutable)?
    - How will the CI/CD pipeline be structured?
-   - What tools will be used for CI/CD (GitHub Actions, Azure DevOps, GitLab CI, Jenkins)?
+   - What tools will be used for CI/CD (GitLab CI is the Pareto platform pipeline; or GitHub Actions, Azure DevOps, Jenkins)?
    - How will infrastructure be managed (IaC with Terraform, Pulumi, CloudFormation)?
-   - What is the approach to containerization (Docker, Kubernetes, ECS, App Service)?
+   - What is the approach to containerization (GKE or Cloud Run via pareto-platform-gcp; Docker/Kubernetes on-prem; or other cloud options)?
 
 3. **Monitoring, logging, and alerting**
-   - What monitoring platform will be used (Datadog, New Relic, Azure Monitor, CloudWatch)?
+   - What monitoring platform will be used (Google Cloud Monitoring / Cloud Logging via pareto-platform-gcp; or Datadog, New Relic, CloudWatch)?
    - What metrics will be tracked (latency, error rate, throughput, saturation)?
    - What is the alerting strategy (thresholds, escalation chains, on-call rotation)?
    - How will application logs be aggregated and queried?
@@ -1162,6 +1177,8 @@ This session uses the **Session 3: Process-First Protocol** (Steps 5A–5G descr
 
 **Notes Template:**
 
+> **Platform standard (D-08):** The Pareto deployment platform is GCP / `pareto-platform-gcp` with GitLab CI as the CI/CD pipeline and Google Cloud Monitoring / Cloud Logging for observability. Fill the tables below against this baseline unless the client has an overriding constraint.
+
 **Infrastructure Architecture**
 
 | Component | Service / Product | Region | Tier / SKU | Redundancy | Est. Monthly Cost | Notes |

package/pp-core/workflows/execute-phase/steps/client-context-gate.md

@@ -0,0 +1,37 @@
+# Client-context gate (Build) — execute-phase sub-step
+
+Confirms the Build agent has client context in hand before any executor is dispatched.
+Gated entirely on `.platform-bindings.json` (D-13 / D-04, mirroring Phase 9): when no
+bindings file is present this gate is a **no-op** — no prompt fires and Build proceeds
+unchanged. All checks are **offline** — this gate never calls Obsidian, MCP, or any network
+resource. The captured `## Client Context & Patterns` block in CLAUDE.md (the Phase 9
+artifact, already on the Build/Validate read path) is the source of truth; the live vault is
+out of scope here.
+
+```bash
+_PP_SHIM_NAME="pp-tools.cjs"; _PP_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; PP_TOOLS="${_PP_RUNTIME_ROOT}/pp-core/bin/${_PP_SHIM_NAME}"; if [ -f "$PP_TOOLS" ]; then pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${_PP_RUNTIME_ROOT}/.claude/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${_PP_RUNTIME_ROOT}/.claude/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${_PP_RUNTIME_ROOT}/.codex/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${_PP_RUNTIME_ROOT}/.codex/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif command -v pp-tools >/dev/null 2>&1; then PP_TOOLS="$(command -v pp-tools)"; pp_run() { "$PP_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="$HOME/.claude/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${HERMES_HOME:-$HOME/.hermes}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${HERMES_HOME:-$HOME/.hermes}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CURSOR_CONFIG_DIR:-$HOME/.cursor}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${CODEX_HOME:-$HOME/.codex}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CODEX_HOME:-$HOME/.codex}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${GEMINI_CONFIG_DIR:-$HOME/.gemini}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${COPILOT_CONFIG_DIR:-$HOME/.copilot}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${AUGMENT_CONFIG_DIR:-$HOME/.augment}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${TRAE_CONFIG_DIR:-$HOME/.trae}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${TRAE_CONFIG_DIR:-$HOME/.trae}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${QWEN_CONFIG_DIR:-$HOME/.qwen}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${QWEN_CONFIG_DIR:-$HOME/.qwen}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${CLINE_CONFIG_DIR:-$HOME/.cline}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${CLINE_CONFIG_DIR:-$HOME/.cline}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${GROK_AGENTS_HOME:-$HOME/.agents}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${GROK_AGENTS_HOME:-$HOME/.agents}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; elif [ -f "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/pp-core/bin/${_PP_SHIM_NAME}" ]; then PP_TOOLS="${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/pp-core/bin/${_PP_SHIM_NAME}"; pp_run() { node "$PP_TOOLS" "$@"; }; else echo "ERROR: pp-tools.cjs not found at $PP_TOOLS and pp-tools is not on PATH. Run: npx -y @pareto4/pp-core@latest --claude --local" >&2; exit 1; fi; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${PP_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${PP_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
+CTX_GATE_PRESENT=$(pp_run query platform-bindings --pick present 2>/dev/null || echo false)
+CTX_BLOCK=$(pp_run query generate-client-context --read 2>/dev/null || echo '{"present":false}')
+CTX_BLOCK_PRESENT=$(printf '%s' "$CTX_BLOCK" | node -e "const d=require('fs').readFileSync(0,'utf-8');try{process.stdout.write(String((JSON.parse(d).present)||false));}catch{process.stdout.write('false');}")
+```
+
+**If `CTX_GATE_PRESENT` != `true`:** skip entirely (non-Pareto project — fully inert).
+
+**If `CTX_GATE_PRESENT` == `true` and `CTX_BLOCK_PRESENT` == `true`:** the client-context
+block exists and is on the executor's read path. Surface a one-line confirmation
+("Client context loaded from CLAUDE.md — Build will apply captured client patterns.") and
+require an explicit `confirmed` acknowledgment (`AskUserQuestion`, or a typed `confirmed` in
+TEXT_MODE) before dispatching any executor. Advisory checkpoint, not a hard block.
+
+**If `CTX_GATE_PRESENT` == `true` and `CTX_BLOCK_PRESENT` == `false`:** bindings indicate a
+Pareto/client engagement but no client-context block was captured. Warn: "No
+`## Client Context & Patterns` block found in CLAUDE.md — Build may proceed without client
+patterns." Offer (`AskUserQuestion` / TEXT_MODE numbered list):
+
+- **Capture now (recommended)** — pause and run `/pp-init` (its gated client-context step) to
+  write the block, then re-run `/pp-execute-phase`.
+- **Proceed without** — continue knowingly; the executor builds without captured client
+  context. Requires an explicit `confirmed`.
+
+`TEXT_MODE` follows the same rule as the host workflow (`--text` in `$ARGUMENTS`): replace
+`AskUserQuestion` with a plain-text numbered prompt.

package/pp-core/workflows/execute-phase.md

@@ -336,6 +336,10 @@ pp_run query state.begin-phase --phase "${PHASE_NUMBER}" --name "${PHASE_NAME}"
 This updates Status, Last Activity, Current focus, Current Position, and plan counts in STATE.md so frontmatter and body text reflect the active phase immediately.
 </step>
 
+<step name="client_context_gate">
+Read and execute `pp-core/workflows/execute-phase/steps/client-context-gate.md` — Pareto client-context gate (inert without `.platform-bindings.json`; confirms the Phase 9 CLAUDE.md block first).
+</step>
+
 <step name="discover_and_group_plans">
 Load plan inventory with wave grouping in one call: