@pareto4/pp-core 1.11.0 → 1.12.0

package/bin/install.js

@@ -186,22 +186,6 @@ const GSD_COPILOT_INSTRUCTIONS_CLOSE_MARKER = '<!-- /GSD Configuration -->';
 // nothing that can dangle if a script copy is skipped. See
 // https://docs.github.com/en/copilot/reference/hooks-configuration
 const GSD_COPILOT_HOOK_FILE = 'pp-session.json';
-// Copilot parses a command hook's stdout as the hook-output JSON. For sessionStart
-// the schema is `{ additionalContext?: string }` (the text is prepended to the
-// session as context). So the hook must emit that JSON envelope — not bare text.
-// The two messages contain no JSON-special characters, so they embed verbatim.
-const GSD_COPILOT_SESSION_MSG_PRESENT =
-  'GSD: .planning/STATE.md present - review the current phase and any blockers before acting.';
-const GSD_COPILOT_SESSION_MSG_ABSENT =
-  'GSD: no .planning/ workflow found - run /pp-new-project to start a tracked workflow.';
-const GSD_COPILOT_SESSION_HOOK_BASH =
-  'if [ -f .planning/STATE.md ]; then ' +
-  `printf '%s' '{"additionalContext":"${GSD_COPILOT_SESSION_MSG_PRESENT}"}'; else ` +
-  `printf '%s' '{"additionalContext":"${GSD_COPILOT_SESSION_MSG_ABSENT}"}'; fi`;
-const GSD_COPILOT_SESSION_HOOK_PWSH =
-  'if (Test-Path .planning/STATE.md) ' +
-  `{ '{"additionalContext":"${GSD_COPILOT_SESSION_MSG_PRESENT}"}' } ` +
-  `else { '{"additionalContext":"${GSD_COPILOT_SESSION_MSG_ABSENT}"}' }`;
 
 // #777 — Cursor CLI lifecycle hook constants.
 // Cursor reads hook configs from <project-root>/.cursor/hooks.json (local) or
@@ -630,6 +614,203 @@ function computePathPrefix({ isGlobal, isOpencode, isWindowsHost: _isWindowsHost
   return `${resolvedTarget}/`;
 }
 
+/**
+ * Does Claude Code substitute `${CLAUDE_PROJECT_DIR}` inside a user-scope
+ * SKILL.md body?
+ *
+ * MEASURED 2026-09-19, `09-PROBE.md` arm B: **yes** — a personal skill whose
+ * body contained `${CLAUDE_PROJECT_DIR}` was delivered to the model as
+ * `B: [<the project root>]`. (`$HOME`, `~` and
+ * `${VAR:-default}` are NOT substituted — arms E, G, D.)
+ *
+ * true  → the dispatcher emits the literal `${CLAUDE_PROJECT_DIR}` and needs no
+ *         shell step to find the project root.
+ * false → the dispatcher first instructs one Bash derivation
+ *         (`git rev-parse --show-toplevel 2>/dev/null || pwd`) and refers to the
+ *         result as PROJECT_ROOT.
+ *
+ * Either way the dispatcher is a Read instruction, never an `@` include:
+ * `09-PROBE.md` arms A, A2–A6 and H1 measured that `@` inlines no file at all,
+ * in any path form, so a static include could never express "local if present,
+ * else global" (D-09-15).
+ */
+const CLAUDE_PROJECT_DIR_SUBSTITUTES_IN_SKILL_BODY = true;
+
+/**
+ * Replace every `@<prefix>pp-core/<rel>` include line in a GLOBAL Claude
+ * SKILL.md with a local-first dispatcher.
+ *
+ * Why (HINST-04 / D-09-14): Claude Code's documented skill precedence is
+ * Personal (`~/.claude/skills/`) > Project (`.claude/skills/`), confirmed on
+ * this build by `09-PROBE.md` arm F — a personal skill beat both a project
+ * command and a same-named project skill. A local pp-core install writes no
+ * `skills/` at all, so the personal skill is ALWAYS the one that answers, and
+ * its hard-coded global include made a 1.11.1 global workflow run over a 1.13.0
+ * project engine for ~47 days. Shipping the skill project-side would be dead
+ * weight; the fix is to make the personal skill resolve the project's install.
+ *
+ * @param {string} content            SKILL.md text, after the path rewrites
+ * @param {object} args
+ * @param {string} args.pathPrefix     trailing-slash prefix the rewrites emitted
+ *                                     (`$HOME/.claude/` on a home-dir install)
+ * @param {string} args.absolutePrefix trailing-slash absolute config dir
+ * @returns {string} content, unchanged when no include line matched
+ */
+function rewriteGlobalClaudeSkillIncludes(content, { pathPrefix, absolutePrefix } = {}) {
+  if (!content || !pathPrefix || !absolutePrefix) return content;
+  const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const prefixes = [...new Set([pathPrefix, absolutePrefix])].map(escapeRe);
+  const prefixAlt = '(?:' + prefixes.join('|') + ')';
+  // Transform A — a line whose only content is an `@`-include.
+  //
+  // G-4 (2026-09-20): the leading `(\\s*[-*+]\\s+)?` and trailing `(\\s+\\S.*?)?`
+  // groups are new. The 09-07 form was anchored `^@…$`, which could not see
+  // `- @$HOME/.claude/pp-core/workflows/complete-milestone.md (main workflow)`
+  // — a list-marker include with a trailing label. That shape reaches TWO
+  // references in pp-complete-milestone (one of them a `templates/` path), and
+  // the skill consequently carried no dispatcher at all.
+  // `\s*$` absorbs a trailing \r so CRLF-authored bodies match identically.
+  const includeRe = new RegExp(
+    '^(\\s*(?:[-*+]\\s+)?)@' + prefixAlt + 'pp-core/(\\S+?)(\\s+\\S.*?)?\\s*$'
+  );
+  // Transform B — an IN-PROSE reference, with or without `@`, on a line that is
+  // not a bare include. Three shapes ship today and none were visible to the
+  // 09-07 form:
+  //   `Execute the ship workflow from @$HOME/…/ship.md end-to-end.`
+  //   ``Read and execute `$HOME/…/discuss-phase.md` end-to-end.``
+  //   `Follow $HOME/…/help.md with $ARGUMENTS.`
+  // Six skills carried a correct dispatcher AND one of these, so the run read
+  // the project-local workflow first and the GLOBAL copy next, under a
+  // `pp-core answered from:` line that only described the first read. A
+  // whole-line replacement would destroy the sentence, so this transform
+  // rewrites the PATH TOKEN in place and leaves the prose around it alone.
+  //
+  // TWO exclusions, and both are load-bearing — a first cut of this transform
+  // carried neither and corrupted the launcher in pp-discuss-phase, pp-graphify
+  // and pp-import, because the shim's `elif [ -f "$HOME/.claude/pp-core/bin/…" ]`
+  // branch is a prefixed reference like any other:
+  //   (a) `pp-core/bin/…` is the shim's own engine lookup, never a document to
+  //       read. `(?!bin/)` keeps it out.
+  //   (b) anything inside a ``` fence is code, not prose. Rewriting there both
+  //       mangles the shell AND — since the header block is emitted before the
+  //       first touched line — injects markdown prose into the middle of a bash
+  //       block, the same fence-breaking shape `sync-runtime-launcher` hit.
+  const proseRe = new RegExp('@?' + prefixAlt + 'pp-core/(?!bin/)([^\\s`)\\]]+)', 'g');
+
+  // Split on '\n' only (never a `\r?\n` rejoin): untouched lines keep their own
+  // line ending byte-for-byte, and each emitted line copies the ending of the
+  // include line it replaces.
+  const lines = content.split('\n');
+  const matchedIndexes = [];
+  const proseIndexes = [];
+  let inFence = false;
+  for (let i = 0; i < lines.length; i++) {
+    if (/^\s*(?:```|~~~)/.test(lines[i])) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) continue;
+    if (includeRe.test(lines[i])) {
+      matchedIndexes.push(i);
+      continue;
+    }
+    proseRe.lastIndex = 0;
+    if (proseRe.test(lines[i])) proseIndexes.push(i);
+  }
+  if (matchedIndexes.length === 0 && proseIndexes.length === 0) return content;
+
+  const projectRootExpr = CLAUDE_PROJECT_DIR_SUBSTITUTES_IN_SKILL_BODY
+    ? '${CLAUDE_PROJECT_DIR}'
+    : 'PROJECT_ROOT';
+  const header = [
+    '<!-- pp-core install resolution (HINST-04, D-09-14): a project-local pp-core install answers before this global one. -->',
+    'Before anything else, resolve which pp-core install answers this skill:',
+  ];
+  if (!CLAUDE_PROJECT_DIR_SUBSTITUTES_IN_SKILL_BODY) {
+    header.push('Run `git rev-parse --show-toplevel 2>/dev/null || pwd` once and call the result PROJECT_ROOT.');
+  }
+  const answeredFrom =
+    'Then print exactly one line: `pp-core answered from: <dir> (VERSION: <contents of <dir>/VERSION, ' +
+    'or "no VERSION file">)` where <dir> is the pp-core directory you read from (D-09-13).';
+
+  // The header and the `answered from` line are emitted ONCE, bracketing every
+  // rewritten reference in the file. When only Transform B matched
+  // (pp-discuss-phase, which states all three of its workflow hand-offs in
+  // prose) the block hangs off B's first and last line instead — otherwise
+  // those skills would resolve locally while printing no provenance line at
+  // all, which is the one outcome D-09-13 exists to prevent.
+  const allIndexes = [...matchedIndexes, ...proseIndexes].sort((a, b) => a - b);
+  const firstTouched = allIndexes[0];
+  const lastTouched = allIndexes[allIndexes.length - 1];
+  const proseSet = new Set(proseIndexes);
+  const out = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const eol = line.endsWith('\r') ? '\r' : '';
+    const m = includeRe.exec(line);
+    if (!m && !proseSet.has(i)) {
+      out.push(line);
+      continue;
+    }
+    // The full header reads "Before anything else, resolve …", which is true
+    // above a bare include but NOT true spliced into a conditional branch —
+    // pp-discuss-phase states its three hand-offs under `If --assumptions …` /
+    // `Otherwise …`, and that sentence there would invite a resolve-and-read on
+    // a branch that was not taken. So a file with no bare include gets the
+    // marker comment only: each rewritten sentence already carries its own
+    // local-first conditional, and the provenance line still lands below.
+    if (i === firstTouched) {
+      const preamble = matchedIndexes.length > 0 ? header : header.slice(0, 1);
+      for (const h of preamble) out.push(h + eol);
+    }
+    if (m) {
+      const [, marker, rel] = m;
+      // Emit at the include's own indentation, always as a `- ` bullet: a bare
+      // column-0 include keeps the exact 09-07 output, and an indented list
+      // include stays inside its list.
+      const indent = /^\s*/.exec(marker)[0];
+      out.push(
+        indent + '- Read `' + projectRootExpr + '/.claude/pp-core/' + rel + '` if that file exists; ' +
+        'otherwise Read `' + absolutePrefix + 'pp-core/' + rel + '`. ' +
+        "Follow whichever you read as this skill's execution context." + eol
+      );
+    } else {
+      proseRe.lastIndex = 0;
+      out.push(
+        line.replace(proseRe, (_match, rel) =>
+          projectRootExpr + '/.claude/pp-core/' + rel +
+          ' (or ' + absolutePrefix + 'pp-core/' + rel +
+          ' if no project-local install exists)'
+        )
+      );
+    }
+    if (i === lastTouched) out.push(answeredFrom + eol);
+  }
+  return out.join('\n');
+}
+
+/**
+ * The ONE owner of "which settings file does this runtime+scope use".
+ *
+ * #338: a local Claude install writes to settings.local.json — Claude Code's
+ * per-user, gitignored slot — so engineer-specific absolute paths (Node binary,
+ * home dir) never land in the repo-shared settings.json. Global installs and
+ * every non-Claude runtime use settings.json.
+ *
+ * D-09-06: install and uninstall MUST share this one decision. They did not:
+ * install resolved the name through an inline ternary while uninstall hardcoded
+ * 'settings.json', so a local uninstall never opened the file the matching
+ * install had written and left every pp-core hook entry behind, pointing at
+ * scripts it had just deleted. Both paths now call this function.
+ *
+ * @param {string} runtime - Target runtime ('claude', 'gemini', ...)
+ * @param {boolean} isGlobal - Whether this is a global install
+ * @returns {string} Settings file basename
+ */
+function resolveSettingsFileName(runtime, isGlobal) {
+  return runtime === 'claude' && !isGlobal ? 'settings.local.json' : 'settings.json';
+}
+
 // normalizeNodePath, resolveNodeRunner, resolveBashRunner, referencesHook are
 // now owned by the runtime-hooks-surface module. Import them here so
 // install.js callers continue to work and so there is a single implementation
@@ -1726,8 +1907,8 @@ function convertClaudeToCopilotContent(content, isGlobal = false) {
   } else {
     c = c.replace(/\$HOME\/\.claude\//g, '.github/');
     c = c.replace(/~\/\.claude\//g, '.github/');
-    c = c.replace(/\$HOME\/\.claude\b/g, '.github');
-    c = c.replace(/~\/\.claude\b/g, '.github');
+    c = c.replace(/\$HOME\/\.claude(?![\w-])/g, '.github');
+    c = c.replace(/~\/\.claude(?![\w-])/g, '.github');
   }
   c = c.replace(/\.\/\.claude\//g, './.github/');
   c = c.replace(/\.claude\//g, '.github/');
@@ -2228,14 +2409,14 @@ function convertClaudeToAntigravityContent(content, isGlobal = false) {
     c = c.replace(/\$HOME\/\.claude\//g, '$HOME/.gemini/antigravity/');
     c = c.replace(/~\/\.claude\//g, '~/.gemini/antigravity/');
     // Bare form (no trailing slash) — must come after slash form to avoid double-replace
-    c = c.replace(/\$HOME\/\.claude\b/g, '$HOME/.gemini/antigravity');
-    c = c.replace(/~\/\.claude\b/g, '~/.gemini/antigravity');
+    c = c.replace(/\$HOME\/\.claude(?![\w-])/g, '$HOME/.gemini/antigravity');
+    c = c.replace(/~\/\.claude(?![\w-])/g, '~/.gemini/antigravity');
   } else {
     c = c.replace(/\$HOME\/\.claude\//g, '.agents/');
     c = c.replace(/~\/\.claude\//g, '.agents/');
     // Bare form (no trailing slash) — must come after slash form to avoid double-replace
-    c = c.replace(/\$HOME\/\.claude\b/g, '.agents');
-    c = c.replace(/~\/\.claude\b/g, '.agents');
+    c = c.replace(/\$HOME\/\.claude(?![\w-])/g, '.agents');
+    c = c.replace(/~\/\.claude(?![\w-])/g, '.agents');
   }
   c = c.replace(/\.\/\.claude\//g, './.agents/');
   c = c.replace(/\.claude\//g, '.agents/');
@@ -2849,8 +3030,8 @@ function convertClaudeToCliineMarkdown(content) {
   converted = converted.replace(/\.\/\.claude\//g, './.cline/');
   converted = converted.replace(/\.claude\//g, '.cline/');
   // Bare forms (no trailing slash) — after slash forms to avoid double-rewrite
-  converted = converted.replace(/~\/\.claude\b/g, '~/.cline');
-  converted = converted.replace(/\$HOME\/\.claude\b/g, '$HOME/.cline');
+  converted = converted.replace(/~\/\.claude(?![\w-])/g, '~/.cline');
+  converted = converted.replace(/\$HOME\/\.claude(?![\w-])/g, '$HOME/.cline');
   // Environment variable name rewrite
   converted = converted.replace(/\bCLAUDE_CONFIG_DIR\b/g, 'CLINE_CONFIG_DIR');
   converted = converted.replace(/\*\*Known Claude Code bug \(classifyHandoffIfNeeded\):\*\*[^\n]*\n/g, '');
@@ -2955,8 +3136,8 @@ function convertClaudeToCodexMarkdown(content) {
   converted = converted.replace(/~\/\.claude\//g, '~/.codex/');
   converted = converted.replace(/\.\/\.claude\//g, './.codex/');
   // Bare ~/.claude without trailing slash (e.g. configDir = ~/.claude)
-  converted = converted.replace(/\$HOME\/\.claude\b/g, '$HOME/.codex');
-  converted = converted.replace(/~\/\.claude\b/g, '~/.codex');
+  converted = converted.replace(/\$HOME\/\.claude(?![\w-])/g, '$HOME/.codex');
+  converted = converted.replace(/~\/\.claude(?![\w-])/g, '~/.codex');
   // Bare/project-relative .claude/... references (#2639). Covers strings like
   // "check `.claude/skills/`" where there is no ~/, $HOME/, or ./ anchor.
   // Negative lookbehind prevents double-replacing already-anchored forms and
@@ -5943,8 +6124,8 @@ function convertClaudeToOpencodeFrontmatter(content, { isAgent = false, modelOve
   // Replace /gsd-command colon variant with /gsd-command for opencode (flat command structure)
   convertedContent = convertedContent.replace(/\/gsd:/g, '/gsd-');
   // Replace ~/.claude and $HOME/.claude with OpenCode's config location
-  convertedContent = convertedContent.replace(/~\/\.claude\b/g, '~/.config/opencode');
-  convertedContent = convertedContent.replace(/\$HOME\/\.claude\b/g, '$HOME/.config/opencode');
+  convertedContent = convertedContent.replace(/~\/\.claude(?![\w-])/g, '~/.config/opencode');
+  convertedContent = convertedContent.replace(/\$HOME\/\.claude(?![\w-])/g, '$HOME/.config/opencode');
   // Replace general-purpose subagent type with OpenCode's equivalent "general"
   convertedContent = convertedContent.replace(/subagent_type="general-purpose"/g, 'subagent_type="general"');
   // Runtime-neutral agent name replacement (#766)
@@ -6100,8 +6281,8 @@ function convertClaudeToKiloFrontmatter(content, { isAgent = false } = {}) {
   // Replace /gsd-command colon variant with /gsd-command for Kilo (flat command structure)
   convertedContent = convertedContent.replace(/\/gsd:/g, '/gsd-');
   // Replace ~/.claude and $HOME/.claude with Kilo's config location
-  convertedContent = convertedContent.replace(/~\/\.claude\b/g, '~/.config/kilo');
-  convertedContent = convertedContent.replace(/\$HOME\/\.claude\b/g, '$HOME/.config/kilo');
+  convertedContent = convertedContent.replace(/~\/\.claude(?![\w-])/g, '~/.config/kilo');
+  convertedContent = convertedContent.replace(/\$HOME\/\.claude(?![\w-])/g, '$HOME/.config/kilo');
   convertedContent = convertedContent.replace(/\.\/\.claude\//g, './.kilo/');
   // Normalize both Claude skill directory variants to Kilo's canonical skills dir.
   convertedContent = replaceRelativePathReference(convertedContent, '.claude/skills/', '.kilo/skills/');
@@ -6554,7 +6735,7 @@ function writeHermesCategoryDescription(categoryDir) {
     '---',
     'name: gsd',
     `version: ${pkg.version}`,
-    'description: pp-core — The Pareto delivery framework. Disciplined planning, execution, and shipping workflows. Use any pp-* skill in this category to drive a project through new-project → discuss-phase → plan-phase → execute-phase → ship.',
+    'description: pp-core — The Pareto delivery framework. Disciplined planning, execution, and shipping workflows. Use any pp-* skill in this category to drive a project through init → new-project → discuss-phase → plan-phase → execute-phase → ship.',
     '---',
     '',
     '# pp-core',
@@ -6696,8 +6877,10 @@ function migrateLegacyDevPreferencesToSkill(targetDir, saved, runtime, scope = '
  * @param {string} runtime
  * @param {string} pathPrefix  e.g. "~/.codex/" — trailing-slash string
  * @param {boolean} [isGlobal=false]  true when the install is a global (home-dir) install
+ * @param {object} [opts={}]  extra rewrite inputs; `opts.configDir` supplies the
+ *   absolute global install path the HINST-04 dispatcher names in its else-clause
  */
-function applyRuntimeContentRewritesInPlace(stagedDir, runtime, pathPrefix, isGlobal = false) {
+function applyRuntimeContentRewritesInPlace(stagedDir, runtime, pathPrefix, isGlobal = false, opts = {}) {
   if (!fs.existsSync(stagedDir)) return;
 
   // Walk all SKILL.md files under stagedDir
@@ -6708,7 +6891,7 @@ function applyRuntimeContentRewritesInPlace(stagedDir, runtime, pathPrefix, isGl
         walkAndRewrite(fullPath);
       } else if (entry.name.endsWith('.md')) {
         let content = fs.readFileSync(fullPath, 'utf8');
-        content = _applyRuntimeRewrites(content, runtime, pathPrefix, isGlobal);
+        content = _applyRuntimeRewrites(content, runtime, pathPrefix, isGlobal, opts);
         fs.writeFileSync(fullPath, content);
       }
     }
@@ -6765,9 +6948,10 @@ function applyRuntimeContentRewritesForCommandsInPlace(stagedDir, runtime, pathP
  * @param {string} runtime
  * @param {string} pathPrefix  trailing-slash string
  * @param {boolean} [isGlobal=false]  true when the install is a global (home-dir) install
+ * @param {object} [opts={}]  extra rewrite inputs (see applyRuntimeContentRewritesInPlace)
  * @returns {string}
  */
-function _applyRuntimeRewrites(content, runtime, pathPrefix, isGlobal = false) {
+function _applyRuntimeRewrites(content, runtime, pathPrefix, isGlobal = false, opts = {}) {
   const dirName = getDirName(runtime);
   const normalizedPathPrefix = pathPrefix.replace(/\/$/, '');
 
@@ -6789,8 +6973,8 @@ function _applyRuntimeRewrites(content, runtime, pathPrefix, isGlobal = false) {
       content = content.replace(/~\/\.cline\//g, pathPrefix);
       content = content.replace(/\$HOME\/\.cline\//g, pathPrefix);
       // Bare forms (no trailing slash)
-      content = content.replace(/~\/\.claude\b/g, normalizedPathPrefix);
-      content = content.replace(/\$HOME\/\.claude\b/g, normalizedPathPrefix);
+      content = content.replace(/~\/\.claude(?![\w-])/g, normalizedPathPrefix);
+      content = content.replace(/\$HOME\/\.claude(?![\w-])/g, normalizedPathPrefix);
       content = content.replace(/~\/\.cline\b/g, normalizedPathPrefix);
       content = content.replace(/\$HOME\/\.cline\b/g, normalizedPathPrefix);
       content = processAttribution(content, getCommitAttribution(runtime));
@@ -6853,9 +7037,9 @@ function _applyRuntimeRewrites(content, runtime, pathPrefix, isGlobal = false) {
       content = content.replace(/~\/\.claude\//g, pathPrefix);
       content = content.replace(/\$HOME\/\.claude\//g, pathPrefix);
       content = content.replace(/\.\/\.claude\//g, `./${dirName}/`);
-      content = content.replace(/~\/\.claude\b/g, normalizedPathPrefix);
-      content = content.replace(/\$HOME\/\.claude\b/g, normalizedPathPrefix);
-      content = content.replace(/\.\/\.claude\b/g, `./${dirName}`);
+      content = content.replace(/~\/\.claude(?![\w-])/g, normalizedPathPrefix);
+      content = content.replace(/\$HOME\/\.claude(?![\w-])/g, normalizedPathPrefix);
+      content = content.replace(/\.\/\.claude(?![\w-])/g, `./${dirName}`);
       content = content.replace(/~\/\.trae\//g, pathPrefix);
       content = processAttribution(content, getCommitAttribution(runtime));
       break;
@@ -6864,9 +7048,9 @@ function _applyRuntimeRewrites(content, runtime, pathPrefix, isGlobal = false) {
       content = content.replace(/~\/\.claude\//g, pathPrefix);
       content = content.replace(/\$HOME\/\.claude\//g, pathPrefix);
       content = content.replace(/\.\/\.claude\//g, `./${dirName}/`);
-      content = content.replace(/~\/\.claude\b/g, normalizedPathPrefix);
-      content = content.replace(/\$HOME\/\.claude\b/g, normalizedPathPrefix);
-      content = content.replace(/\.\/\.claude\b/g, `./${dirName}`);
+      content = content.replace(/~\/\.claude(?![\w-])/g, normalizedPathPrefix);
+      content = content.replace(/\$HOME\/\.claude(?![\w-])/g, normalizedPathPrefix);
+      content = content.replace(/\.\/\.claude(?![\w-])/g, `./${dirName}`);
       // The codebuddy converter rewrites `.claude/` → `.codebuddy/` at stage
       // time, so `$HOME/.claude/...` arrives here as `$HOME/.codebuddy/...`.
       // Normalize BOTH the `~/` and `$HOME/` forms (slash + bare) to the install
@@ -6892,6 +7076,16 @@ function _applyRuntimeRewrites(content, runtime, pathPrefix, isGlobal = false) {
       content = content.replace(/~\/\.claude\//g, pathPrefix);
       content = content.replace(/\$HOME\/\.claude\//g, pathPrefix);
       content = content.replace(/\.\/\.claude\//g, `./${dirName}/`);
+      // HINST-04 / D-09-14: only the GLOBAL Claude skills kind reaches this —
+      // `opts.configDir` is supplied by installRuntimeArtifacts for that kind
+      // alone, and the local commands path never passes opts. A local install
+      // writes no skills/, so its commands keep their absolute include (D-09-12).
+      if (isGlobal && opts && opts.configDir) {
+        content = rewriteGlobalClaudeSkillIncludes(content, {
+          pathPrefix,
+          absolutePrefix: path.resolve(opts.configDir).replace(/\\/g, '/').replace(/\/$/, '') + '/',
+        });
+      }
       content = processAttribution(content, getCommitAttribution(runtime));
       break;
 
@@ -6940,9 +7134,9 @@ function _applyRuntimeRewrites(content, runtime, pathPrefix, isGlobal = false) {
       content = content.replace(/~\/\.claude\//g, pathPrefix);
       content = content.replace(/\$HOME\/\.claude\//g, pathPrefix);
       content = content.replace(/\.\/\.claude\//g, `./${dirName}/`);
-      content = content.replace(/~\/\.claude\b/g, normalizedPathPrefix);
-      content = content.replace(/\$HOME\/\.claude\b/g, normalizedPathPrefix);
-      content = content.replace(/\.\/\.claude\b/g, `./${dirName}`);
+      content = content.replace(/~\/\.claude(?![\w-])/g, normalizedPathPrefix);
+      content = content.replace(/\$HOME\/\.claude(?![\w-])/g, normalizedPathPrefix);
+      content = content.replace(/\.\/\.claude(?![\w-])/g, `./${dirName}`);
       content = processAttribution(content, getCommitAttribution(runtime));
       break;
 
@@ -7326,7 +7520,7 @@ function installRuntimeArtifacts(runtime, configDir, scope, resolvedProfile) {
     let stagedForCopy = staged;
     const isGlobal = scope === 'global';
     if (kind.kind === 'skills' || kind.kind === 'kimi-agents') {
-      applyRuntimeContentRewritesInPlace(staged, runtime, pathPrefix, isGlobal);
+      applyRuntimeContentRewritesInPlace(staged, runtime, pathPrefix, isGlobal, { configDir });
     } else if (kind.kind === 'commands') {
       // Returns a temp dir with rewritten content so source files are never mutated.
       stagedForCopy = applyRuntimeContentRewritesForCommandsInPlace(staged, runtime, pathPrefix, isGlobal);
@@ -7693,9 +7887,9 @@ function copyWithPathReplacement(srcDir, destDir, pathPrefix, runtime, isCommand
         content = content.replace(globalClaudeRegex, pathPrefix);
         content = content.replace(globalClaudeHomeRegex, pathPrefix);
         content = content.replace(localClaudeRegex, `./${dirName}/`);
-        content = content.replace(/~\/\.claude\b/g, pathPrefix.replace(/\/$/, ''));
-        content = content.replace(/\$HOME\/\.claude\b/g, pathPrefix.replace(/\/$/, ''));
-        content = content.replace(/\.\/\.claude\b/g, `./${dirName}`);
+        content = content.replace(/~\/\.claude(?![\w-])/g, pathPrefix.replace(/\/$/, ''));
+        content = content.replace(/\$HOME\/\.claude(?![\w-])/g, pathPrefix.replace(/\/$/, ''));
+        content = content.replace(/\.\/\.claude(?![\w-])/g, `./${dirName}`);
         content = content.replace(/~\/\.qwen\//g, pathPrefix);
         content = content.replace(/\$HOME\/\.qwen\//g, pathPrefix);
         content = content.replace(/\.\/\.qwen\//g, `./${dirName}/`);
@@ -8005,8 +8199,42 @@ const GSD_UNINSTALL_HOOKS = [
   'pp-validate-commit.sh',
   'pp-phase-boundary.sh',
   'pp-graphify-update.sh',
+  // D-09-08: absent from this list until phase 9 while still being registered
+  // in the settings file, so a project the operator believed was uninstalled
+  // kept a live pp-core PreToolUse hook on disk and wired.
+  'pp-worktree-path-guard.js',
 ];
 
+/**
+ * Files pp-core ships into the runtime hooks/ dir and deliberately does NOT
+ * remove on uninstall, each with the reason. D-09-08 locks the retention and
+ * requires uninstall to NAME what it keeps rather than leave it silently.
+ *
+ * The pin in tests/hooks-opt-in.test.cjs asserts that this table plus
+ * GSD_UNINSTALL_HOOKS together cover every name in
+ * hooks/managed-hooks-registry.cjs (plus managed-hooks-registry.cjs itself,
+ * which ships via HOOKS_TO_COPY and is not a hook), so the two lists cannot
+ * drift apart silently again.
+ */
+const GSD_UNINSTALL_RETAINED_HOOKS = Object.freeze([
+  Object.freeze({
+    file: 'managed-hooks-registry.cjs',
+    reason: 'retained per D-09-08: the list pp-check-update-worker.js requires at runtime; '
+      + 'not a hook, never registered in any settings file, referenced by no settings entry after uninstall',
+  }),
+  Object.freeze({
+    file: 'pp-check-update-worker.js',
+    reason: 'retained per D-09-08: a detached worker that pp-check-update.js spawns by path on '
+      + 'SessionStart, never registered as a hook; a worker still running from the last session keeps '
+      + 'resolving its require',
+  }),
+  Object.freeze({
+    file: 'pp-ensure-canonical-path.js',
+    reason: 'retained per D-09-08: the marketplace-plugin SessionStart bootstrap (#997); a classic '
+      + 'install never registers it, so no settings entry references it after uninstall',
+  }),
+]);
+
 /**
  * Uninstall pp-core from the specified directory for a specific runtime
  * Removes only GSD-specific files/directories, preserves user content
@@ -8405,6 +8633,9 @@ function uninstall(isGlobal, runtime = 'claude') {
   }
 
   // 4. Remove pp-core hooks
+  // Populated by the removal block below and reported in the completion message
+  // (D-09-08): uninstall names the files it deliberately keeps.
+  let retainedHooks = [];
   const hooksDir = path.join(targetDir, 'hooks');
   if (fs.existsSync(hooksDir)) {
     let hookCount = 0;
@@ -8420,6 +8651,16 @@ function uninstall(isGlobal, runtime = 'claude') {
       console.log(`  ${green}✓${reset} Removed ${hookCount} pp-core hooks`);
     }
 
+    // D-09-08: name what survives, and why. Driven by what is actually still on
+    // disk rather than by the table alone, so a runtime that never received a
+    // given file is never told it was kept.
+    retainedHooks = GSD_UNINSTALL_RETAINED_HOOKS.filter(
+      (entry) => fs.existsSync(path.join(hooksDir, entry.file))
+    );
+    for (const entry of retainedHooks) {
+      console.log(`  ${yellow}i${reset} retained hooks/${entry.file} — ${entry.reason}`);
+    }
+
     // Remove only the pp-core-managed files from hooks/lib/ (git-cmd.js + pp-graphify-rebuild.sh).
     // hooks/lib/ lives inside the user's runtime hooks directory (shared space) and
     // may contain user-owned custom helpers. We must not recursively delete the dir.
@@ -8458,7 +8699,7 @@ function uninstall(isGlobal, runtime = 'claude') {
     'github-release-notes.cjs', 'lint.cjs', 'new.cjs',
     'README.md', // documentation only — not user-authored
   ];
-  const GSD_SCRIPTS_LIB_FILES = ['cli-exit.cjs', 'allowlist-ratchet.cjs'];
+  const GSD_SCRIPTS_LIB_FILES = ['cli-exit.cjs', 'allowlist-ratchet.cjs', 'size-budget.cjs'];
 
   const changesetUninstallDir = path.join(targetDir, 'scripts', 'changeset');
   if (fs.existsSync(changesetUninstallDir)) {
@@ -8514,13 +8755,31 @@ function uninstall(isGlobal, runtime = 'claude') {
     }
   }
 
-  // 6. Clean up settings.json (remove pp-core hooks and statusline)
-  const settingsPath = path.join(targetDir, 'settings.json');
-  if (fs.existsSync(settingsPath)) {
-    let settings = readSettings(settingsPath);
+  // 6. Clean up the settings file (remove pp-core hooks, statusline,
+  // permissions and the worktree residue the installer wrote).
+  //
+  // D-09-06: the filename comes from resolveSettingsFileName — the SAME owner
+  // the install path calls — so a local Claude uninstall opens the file a local
+  // Claude install actually wrote. Hardcoding 'settings.json' here (as this did
+  // before) left every pp-core hook entry behind in settings.local.json,
+  // pointing at scripts the same uninstall had just deleted.
+  //
+  // @param {string} targetSettingsPath - Absolute path to the settings file
+  // @param {boolean} opts.removeWhenEmpty - Delete the file when nothing but
+  //   pp-core-authored content was in it. True ONLY for local Claude's
+  //   settings.local.json; the repo-shared settings.json is user territory even
+  //   when it parses to {}.
+  // @param {boolean} opts.pruneWorktreeBaseRef - Drop worktree:{baseRef:'head'}.
+  //   True ONLY where the installer can have written it (#683 applies it to
+  //   local Claude's settings.local.json and nowhere else).
+  const cleanupSettingsFile = (targetSettingsPath, { removeWhenEmpty = false, pruneWorktreeBaseRef = false } = {}) => {
+    if (!fs.existsSync(targetSettingsPath)) return;
+    const settingsName = path.basename(targetSettingsPath);
+    const settings = readSettings(targetSettingsPath);
     if (settings === null) {
-      console.log(`  ${yellow}i${reset} Skipping settings.json cleanup — file could not be parsed`);
-      settings = {}; // prevent downstream crashes, but don't write back
+      // Unparseable: never write it back and never delete it.
+      console.log(`  ${yellow}i${reset} Skipping ${settingsName} cleanup — file could not be parsed`);
+      return;
     }
     let settingsModified = false;
 
@@ -8540,6 +8799,7 @@ function uninstall(isGlobal, runtime = 'claude') {
     // Claude-only FileChanged event added in #770 — safe to iterate for all
     // runtimes; installs that don't register these events simply find no
     // entries and skip.
+    let hooksModified = false;
     for (const eventName of ['SessionStart', 'PostToolUse', 'AfterTool', 'PreToolUse', 'BeforeTool', 'SubagentStop', 'Stop', 'PreCompact', 'BeforeAgent', 'AfterAgent', 'BeforeModel', 'FileChanged']) {
       if (settings.hooks && settings.hooks[eventName]) {
         const before = JSON.stringify(settings.hooks[eventName]);
@@ -8558,14 +8818,15 @@ function uninstall(isGlobal, runtime = 'claude') {
           .filter(Boolean);
         if (JSON.stringify(settings.hooks[eventName]) !== before) {
           settingsModified = true;
+          hooksModified = true;
         }
         if (settings.hooks[eventName].length === 0) {
           delete settings.hooks[eventName];
         }
       }
     }
-    if (settingsModified) {
-      console.log(`  ${green}✓${reset} Removed pp-core hooks from settings`);
+    if (hooksModified) {
+      console.log(`  ${green}✓${reset} Removed pp-core hooks from ${settingsName}`);
     }
 
     // Clean up empty hooks object
@@ -8574,6 +8835,9 @@ function uninstall(isGlobal, runtime = 'claude') {
     }
 
     // #768 — Remove GSD-owned Claude permissions from settings.json.
+    // D-09-06: "settings.json" above is the historical wording; the file is now
+    // whatever resolveSettingsFileName picked, which for a local Claude
+    // install/uninstall is settings.local.json.
     // Applies only to Claude uninstalls. Filter only the exact GSD-owned entries
     // to preserve any user-added allow/deny entries.
     // Uses a local flag to avoid the shared `settingsModified` producing a false
@@ -8600,14 +8864,83 @@ function uninstall(isGlobal, runtime = 'claude') {
       }
       if (permissionsModified) {
         settingsModified = true;
-        console.log(`  ${green}✓${reset} Removed pp-core permissions from settings.json`);
+        console.log(`  ${green}✓${reset} Removed pp-core permissions from ${settingsName}`);
+        // D-09-06: prune ONLY the arrays this filter just emptied. A user's own
+        // empty allow[] that we never touched is their content and stays — that
+        // is why this is gated on permissionsModified rather than run always.
+        for (const key of ['allow', 'deny']) {
+          if (Array.isArray(settings.permissions[key]) && settings.permissions[key].length === 0) {
+            delete settings.permissions[key];
+          }
+        }
+        if (Object.keys(settings.permissions).length === 0) {
+          delete settings.permissions;
+        }
       }
     }
 
-    if (settingsModified) {
-      writeSettings(settingsPath, settings);
+    // D-09-06: worktree:{baseRef:'head'} is the ONE shape applyWorktreeBaseRef
+    // writes (src/worktree-base-ref.cts) and it never overwrites an explicit
+    // other value — so exactly that object, with no extra keys, is installer
+    // residue. Any other value, or extra keys, is user content and stays.
+    if (pruneWorktreeBaseRef && settings.worktree && typeof settings.worktree === 'object' &&
+      !Array.isArray(settings.worktree) &&
+      Object.keys(settings.worktree).length === 1 && settings.worktree.baseRef === 'head') {
+      delete settings.worktree;
+      settingsModified = true;
+      console.log(`  ${green}✓${reset} Removed pp-core worktree.baseRef from ${settingsName}`);
+    }
+
+    if (!settingsModified) return;
+
+    // D-09-06: when the filters emptied the file completely, nothing but
+    // pp-core content had been in it — leave no husk behind. Gated on
+    // settingsModified so a pre-existing empty file we never touched survives.
+    if (removeWhenEmpty && Object.keys(settings).length === 0) {
+      fs.unlinkSync(targetSettingsPath);
       removedCount++;
+      console.log(`  ${green}✓${reset} Removed ${settingsName} (only pp-core content remained)`);
+      return;
     }
+
+    writeSettings(targetSettingsPath, settings);
+    removedCount++;
+  };
+
+  const isLocalClaudeUninstall = runtime === 'claude' && !isGlobal;
+  cleanupSettingsFile(path.join(targetDir, resolveSettingsFileName(runtime, isGlobal)), {
+    removeWhenEmpty: isLocalClaudeUninstall,
+    pruneWorktreeBaseRef: isLocalClaudeUninstall,
+  });
+  if (isLocalClaudeUninstall) {
+    // Legacy sweep, the mirror of install's #338 migration read: a pre-#338
+    // local install wrote its managed entries into the repo-shared
+    // settings.json. Filter them out of there too, but never delete that file
+    // and never prune worktree residue from it — the installer writes neither
+    // there.
+    cleanupSettingsFile(path.join(targetDir, 'settings.json'), {
+      removeWhenEmpty: false,
+      pruneWorktreeBaseRef: false,
+    });
+  }
+
+  // The installer-migrations journal: installer-written, deliberately absent
+  // from pp-file-manifest.json, and left behind by every uninstall before this
+  // one. A stale journal makes a later install skip migrations it should run —
+  // a stored record asserting something untrue about a directory that no longer
+  // holds an install.
+  const installStatePath = path.join(targetDir, 'pp-install-state.json');
+  if (fs.existsSync(installStatePath)) {
+    fs.rmSync(installStatePath, { force: true });
+    removedCount++;
+    console.log(`  ${green}✓${reset} Removed pp-install-state.json`);
+  }
+
+  // Installer-created artifact dirs that the layout-driven removal empties but
+  // does not itself remove — mirror of the scripts/ handling above. A non-empty
+  // dir (user content) throws and stays.
+  for (const artifactDir of ['agents', 'commands']) {
+    try { fs.rmdirSync(path.join(targetDir, artifactDir)); } catch (_) { /* Not empty — leave it */ }
   }
 
   // 6. For OpenCode, clean up permissions from opencode.json or opencode.jsonc
@@ -8705,9 +9038,12 @@ function uninstall(isGlobal, runtime = 'claude') {
     console.log(`  ${yellow}⚠${reset} No pp-core files found to remove.`);
   }
 
+  const retainedSentence = retainedHooks.length > 0
+    ? `\n  Retained on disk (named per HINST-01): ${retainedHooks.map((e) => `hooks/${e.file}`).join(', ')}`
+    : '';
   console.log(`
   ${green}Done!${reset} GSD has been uninstalled from ${runtimeLabel}.
-  Your other files and settings have been preserved.
+  Your other files and settings have been preserved.${retainedSentence}
 `);
 }
 
@@ -10335,8 +10671,8 @@ function install(isGlobal, runtime = 'claude', options = {}) {
         // Replace ~/.claude/ and $HOME/.claude/ as they are the source of truth in the repo
         const dirRegex = /~\/\.claude\//g;
         const homeDirRegex = /\$HOME\/\.claude\//g;
-        const bareDirRegex = /~\/\.claude\b/g;
-        const bareHomeDirRegex = /\$HOME\/\.claude\b/g;
+        const bareDirRegex = /~\/\.claude(?![\w-])/g;
+        const bareHomeDirRegex = /\$HOME\/\.claude(?![\w-])/g;
         const normalizedPathPrefix = pathPrefix.replace(/\/$/, '');
         if (!isCopilot && !isAntigravity) {
           content = content.replace(dirRegex, pathPrefix);
@@ -10716,7 +11052,7 @@ function install(isGlobal, runtime = 'claude', options = {}) {
           }
           throw err;
         }
-        const matches = content.match(/(?:~|\$HOME)\/\.claude\b/g);
+        const matches = content.match(/(?:~|\$HOME)\/\.claude(?![\w-])/g);
         if (matches) {
           leakedPaths.push({ file: relPath, count: matches.length });
         }
@@ -11205,7 +11541,7 @@ function install(isGlobal, runtime = 'claude', options = {}) {
   // so engineer-specific absolute paths (Node binary, home dir) never land in the repo-shared
   // settings.json. Global installs and all other runtimes continue to use settings.json.
   const isLocalClaude = (runtime === 'claude' && !isGlobal);
-  const settingsFileName = isLocalClaude ? 'settings.local.json' : 'settings.json';
+  const settingsFileName = resolveSettingsFileName(runtime, isGlobal);
   const settingsPath = path.join(targetDir, settingsFileName);
 
   // #338 migration: if a prior local Claude install wrote GSD-shaped entries to settings.json,
@@ -11497,6 +11833,25 @@ function install(isGlobal, runtime = 'claude', options = {}) {
   };
 }
 
+// The ONE owner of "how to start a project" in the installer. Every
+// runtime's Done! line names the init front door (git init, remote wiring, vault
+// binding, then handoff to /pp-discovery or /pp-new-project), derived from this
+// single stem so no runtime can drift back to naming the second step.
+const START_COMMAND_STEM = 'init';
+
+/**
+ * Resolve the start command in a runtime's own invocation syntax.
+ * @param {string} runtime - installer runtime id (unknown ids get the default form)
+ * @returns {string}
+ */
+function resolveStartCommand(runtime) {
+  if (runtime === 'gemini') return `/pp:${START_COMMAND_STEM}`;
+  if (runtime === 'codex') return `$pp-${START_COMMAND_STEM}`;
+  if (runtime === 'cursor') return `pp-${START_COMMAND_STEM} (mention the skill name)`;
+  if (runtime === 'kimi') return `/skill:pp-${START_COMMAND_STEM}`;
+  return `/pp-${START_COMMAND_STEM}`;
+}
+
 /**
  * Apply statusline config, then print completion message
  */
@@ -11628,21 +11983,7 @@ function finishInstall(settingsPath, settings, statuslineCommand, shouldInstallS
   if (runtime === 'hermes') program = 'Hermes Agent';
   if (runtime === 'kimi') program = 'Kimi CLI';
 
-  let command = '/pp-new-project';
-  if (runtime === 'opencode') command = '/pp-new-project';
-  if (runtime === 'kilo') command = '/pp-new-project';
-  if (runtime === 'gemini') command = '/pp:new-project';
-  if (runtime === 'codex') command = '$pp-new-project';
-  if (runtime === 'copilot') command = '/pp-new-project';
-  if (runtime === 'antigravity') command = '/pp-new-project';
-  if (runtime === 'cursor') command = 'pp-new-project (mention the skill name)';
-  if (runtime === 'windsurf') command = '/pp-new-project';
-  if (runtime === 'augment') command = '/pp-new-project';
-  if (runtime === 'trae') command = '/pp-new-project';
-  if (runtime === 'cline') command = '/pp-new-project';
-  if (runtime === 'qwen') command = '/pp-new-project';
-  if (runtime === 'hermes') command = '/pp-new-project';
-  if (runtime === 'kimi') command = '/skill:pp-new-project';
+  const command = resolveStartCommand(runtime);
 
   // Claude Code global installs use the skills/ format (CC 2.1.88+).
   // Restart is required for CC to pick up newly-installed skills, and the
@@ -11650,7 +11991,7 @@ function finishInstall(settingsPath, settings, statuslineCommand, shouldInstallS
   // cover both invocation paths to avoid #2957-style "no commands appear".
   if (runtime === 'claude' && isGlobal) {
     console.log(`
-  ${green}Done!${reset} Restart ${program}, then in any directory either type ${cyan}${command}${reset} or ask Claude to run the ${cyan}pp-new-project${reset} skill.
+  ${green}Done!${reset} Restart ${program}, then in any directory either type ${cyan}${command}${reset} or ask Claude to run the ${cyan}pp-${START_COMMAND_STEM}${reset} skill.
 `);
     return;
   }
@@ -12315,6 +12656,9 @@ module.exports = {
     normalizeAgentBodyForRuntime,
     yamlIdentifier,
     computePathPrefix,
+    // HINST-04 / D-09-14 — global Claude SKILL.md local-first dispatcher
+    rewriteGlobalClaudeSkillIncludes,
+    CLAUDE_PROJECT_DIR_SUBSTITUTES_IN_SKILL_BODY,
     applyRuntimeContentRewritesInPlace,
     getCodexSkillAdapterHeader,
     convertClaudeCommandToCursorSkill,
@@ -12429,12 +12773,15 @@ module.exports = {
     populatePristineDir,
     USER_OWNED_ARTIFACTS,
     finishInstall,
+    resolveStartCommand,
     homePathCoveredByRc,
     maybeSuggestPathExport,
     runtimeMap,
     allRuntimes,
     selectRuntimesFromArgs,
     GSD_UNINSTALL_HOOKS,
+    GSD_UNINSTALL_RETAINED_HOOKS,
+    resolveSettingsFileName,
     parseRuntimeInput,
     buildRuntimePromptText,
     buildUpdateBannerPromptText,