@opengsd/gsd-core 1.5.0-rc.3 → 1.5.0-rc.4

package/hooks/gsd-ensure-canonical-path.js

@@ -0,0 +1,305 @@
+#!/usr/bin/env node
+// gsd-hook-version: {{GSD_VERSION}}
+//
+// gsd-ensure-canonical-path — SessionStart hook (#997)
+//
+// PROBLEM: GSD agents/commands/templates use markdown `@`-file-includes that
+// hardcode the canonical path `@~/.claude/gsd-core/...` (references, workflows,
+// templates, contexts, bin). Markdown @-includes expand `~` but do NOT expand
+// environment variables, so `${CLAUDE_PLUGIN_ROOT}` cannot be used in them.
+// In a classic `bin/install.js` install the canonical path is a real directory
+// holding the bundled tree, so the includes resolve. In a Claude Code
+// *marketplace plugin* install the plugin manager only unpacks the package
+// into the version-pinned plugin cache and never runs `bin/install.js`, so
+// `~/.claude/gsd-core/` is never created and every @-include resolves to
+// nothing — every agent that depends on one fails (e.g. the executor).
+//
+// FIX: On SessionStart, when running under a plugin install (CLAUDE_PLUGIN_ROOT
+// set and a bundled `gsd-core/` tree found beneath it), ensure
+// `~/.claude/gsd-core/` exists and its immutable subdirs (bin, contexts,
+// references, templates, workflows) are symlinked to the plugin's bundled tree.
+// This changes ZERO @-references, is a no-op in classic installs (where each
+// subdir is already a real directory), preserves user-generated files
+// (USER-PROFILE.md, STATE.md, VERSION, …), prunes stale links so it self-heals
+// after `claude plugin update` rotates the version dir, and uses Windows
+// junctions for symlinks on win32.
+//
+// SECURITY: the resolved bundled-tree path and every per-subdir link target are
+// kept strictly inside the resolved plugin root (realpath-normalised, prefix-
+// checked). A real (non-symlink) file or directory already sitting at a managed
+// link target is NEVER clobbered.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// Immutable, bundled subdirectories that the canonical path must expose. These
+// are the directories `@~/.claude/gsd-core/<subdir>/...` includes point into.
+// User-generated artifacts (USER-PROFILE.md, STATE.md, VERSION, config, …) are
+// NOT in this list and are never created, moved, or deleted by this hook.
+const MANAGED_SUBDIRS = ['bin', 'contexts', 'references', 'templates', 'workflows'];
+
+/**
+ * Resolve the canonical runtime config dir for the active runtime.
+ *
+ * Honours CLAUDE_CONFIG_DIR for custom/multi-account setups (mirrors
+ * gsd-check-update.js detectConfigDir), else falls back to ~/.claude. The
+ * canonical GSD tree always lives at `<configDir>/gsd-core`.
+ */
+function resolveConfigDir(homeDir, env) {
+  const envDir = env.CLAUDE_CONFIG_DIR;
+  if (envDir && typeof envDir === 'string' && envDir.trim().length > 0) {
+    return envDir;
+  }
+  return path.join(homeDir, '.claude');
+}
+
+/**
+ * Locate the bundled `gsd-core/` tree beneath a plugin root.
+ *
+ * Claude Code unpacks the package so the bundled tree sits at
+ * `<pluginRoot>/gsd-core/`. Returns the absolute, realpath-normalised path to
+ * that directory, or null if it is absent / not a directory. Resolving with
+ * realpath collapses symlinks/.. so the subsequent containment check is sound.
+ */
+function resolveBundledTree(pluginRoot) {
+  if (!pluginRoot || typeof pluginRoot !== 'string' || pluginRoot.trim().length === 0) {
+    return null;
+  }
+  let root;
+  try {
+    root = fs.realpathSync(pluginRoot);
+  } catch (_) {
+    return null; // plugin root does not exist
+  }
+  const bundled = path.join(root, 'gsd-core');
+  let bundledReal;
+  try {
+    // The bundled tree must be a real directory (or a symlink to one) that
+    // resolves to a path inside the plugin root. realpathSync throws ENOENT/
+    // ENOTDIR if <pluginRoot>/gsd-core is absent, so no separate existence
+    // check is needed. Reject anything that does not resolve to a directory.
+    bundledReal = fs.realpathSync(bundled);
+    if (!fs.statSync(bundledReal).isDirectory()) return null;
+  } catch (_) {
+    return null;
+  }
+  // SECURITY: the resolved bundled tree must stay inside the resolved plugin
+  // root. A crafted symlink at <pluginRoot>/gsd-core pointing outside the root
+  // is rejected — we never link the canonical path at content we do not own.
+  const rootWithSep = root.endsWith(path.sep) ? root : root + path.sep;
+  if (bundledReal !== root && !bundledReal.startsWith(rootWithSep)) {
+    return null;
+  }
+  return bundledReal;
+}
+
+/**
+ * The fs.symlinkSync `type` to use for a directory link on a given platform.
+ *
+ * On Windows, unprivileged users cannot create symlinks but CAN create
+ * junctions; 'junction' requires an absolute target (we always pass one). On
+ * POSIX a 'dir' symlink is used. Exported so the win32 branch is unit-testable
+ * without a Windows host.
+ */
+function dirLinkType(platform) {
+  return platform === 'win32' ? 'junction' : 'dir';
+}
+
+/**
+ * Create a directory symlink (junction on win32) from linkPath -> target.
+ * Throws on real failure so the caller records it.
+ */
+function createDirLink(target, linkPath, platform) {
+  fs.symlinkSync(target, linkPath, dirLinkType(platform));
+}
+
+/**
+ * Does `linkPath` already correctly point at `expectedTarget`?
+ * Used to make the hook idempotent — a correct link is left untouched.
+ */
+function linkPointsAt(linkPath, expectedTarget) {
+  try {
+    if (!fs.lstatSync(linkPath).isSymbolicLink()) return false;
+    const resolved = fs.realpathSync(linkPath);
+    return resolved === fs.realpathSync(expectedTarget);
+  } catch (_) {
+    return false;
+  }
+}
+
+/**
+ * Ensure the canonical `~/.claude/gsd-core/` path exposes the bundled subdirs.
+ *
+ * Pure, dependency-injected core so tests drive it with a fake home, fake
+ * plugin root, and explicit platform. Returns a structured result describing
+ * exactly what happened (never throws for ordinary conditions — only truly
+ * unexpected I/O errors propagate, and the thin CLI wrapper swallows those so
+ * a hook failure never blocks a session).
+ *
+ * @param {object} opts
+ * @param {string} [opts.homeDir]    home directory (default os.homedir())
+ * @param {string} [opts.pluginRoot] CLAUDE_PLUGIN_ROOT (default from env)
+ * @param {string} [opts.platform]   process.platform override (tests)
+ * @param {object} [opts.env]        environment (default process.env)
+ * @returns {{status:string, canonicalDir?:string, bundledTree?:string,
+ *            linked?:string[], prunedStale?:string[], preserved?:string[],
+ *            skipped?:string[], reason?:string}}
+ */
+function ensureCanonicalPath(opts = {}) {
+  const env = opts.env || process.env;
+  const homeDir = opts.homeDir || os.homedir();
+  const platform = opts.platform || process.platform;
+  const pluginRoot = opts.pluginRoot !== undefined ? opts.pluginRoot : env.CLAUDE_PLUGIN_ROOT;
+
+  // Uniform result contract: every return carries the four action arrays so
+  // callers can read result.linked/etc without first switching on status.
+  const empty = { linked: [], prunedStale: [], preserved: [], skipped: [] };
+
+  // No plugin context → classic/npm install or non-plugin runtime. No-op.
+  const bundledTree = resolveBundledTree(pluginRoot);
+  if (!bundledTree) {
+    return { status: 'noop', reason: 'no-plugin-bundle', ...empty };
+  }
+
+  const configDir = resolveConfigDir(homeDir, env);
+  const canonicalDir = path.join(configDir, 'gsd-core');
+
+  // Inspect the canonical path itself exactly once.
+  //  - If it is a SYMLINK, the user (or another tool) deliberately pointed the
+  //    canonical path elsewhere. We must NOT write managed links *through* that
+  //    symlink into a directory we do not own — bail as a no-op.
+  //  - If it is a REAL directory with at least one REAL (non-link) managed
+  //    subdir, this is a classic `bin/install.js` install — leave it alone.
+  let canonicalStat = null;
+  try { canonicalStat = fs.lstatSync(canonicalDir); } catch (_) { canonicalStat = null; }
+
+  if (canonicalStat && canonicalStat.isSymbolicLink()) {
+    return { status: 'noop', reason: 'canonical-is-symlink', canonicalDir, bundledTree, ...empty };
+  }
+
+  if (canonicalStat && canonicalStat.isDirectory()) {
+    for (const sub of MANAGED_SUBDIRS) {
+      try {
+        const subSt = fs.lstatSync(path.join(canonicalDir, sub));
+        if (subSt.isDirectory() && !subSt.isSymbolicLink()) {
+          return { status: 'noop', reason: 'classic-install', canonicalDir, bundledTree, ...empty };
+        }
+      } catch (_) { /* subdir absent — keep checking */ }
+    }
+  }
+
+  // Ensure the canonical directory exists (as a real directory). We never
+  // replace an existing real directory; recursive mkdir is a no-op if present.
+  try {
+    fs.mkdirSync(canonicalDir, { recursive: true });
+  } catch (e) {
+    return { status: 'error', reason: `mkdir-canonical: ${e.code || e.message}`, canonicalDir, bundledTree, ...empty };
+  }
+
+  const linked = [];
+  const prunedStale = [];
+  const preserved = [];
+  const skipped = [];
+
+  // SECURITY: prefix used to confirm every per-subdir link target resolves
+  // strictly inside the bundled tree. Defence-in-depth against a tampered
+  // bundle that ships an internally-escaping symlink at <bundledTree>/<sub>.
+  const bundledWithSep = bundledTree.endsWith(path.sep) ? bundledTree : bundledTree + path.sep;
+
+  for (const sub of MANAGED_SUBDIRS) {
+    const target = path.join(bundledTree, sub);
+    // Only expose subdirs the bundle actually ships, AND only when the target
+    // resolves to a real directory that stays inside the bundled tree. A
+    // subdir whose realpath escapes the bundle (e.g. a planted symlink) is
+    // skipped — we never point the canonical path at content outside the
+    // validated plugin bundle.
+    let targetIsDir = false;
+    try {
+      const targetReal = fs.realpathSync(target);
+      // A NAMED subdir must resolve strictly BELOW the bundled tree root. We do
+      // NOT accept targetReal === bundledTree here: a subdir that self-links to
+      // the tree root would otherwise be exposed at the wrong level (e.g.
+      // `workflows` -> the whole tree), making `@.../workflows/foo` resolve to
+      // `<tree>/foo` instead of `<tree>/workflows/foo`.
+      targetIsDir = fs.statSync(targetReal).isDirectory()
+        && targetReal.startsWith(bundledWithSep);
+    } catch (_) { targetIsDir = false; }
+    if (!targetIsDir) {
+      skipped.push(sub);
+      continue;
+    }
+
+    const linkPath = path.join(canonicalDir, sub);
+
+    // Already a correct link → idempotent no-op.
+    if (linkPointsAt(linkPath, target)) {
+      linked.push(sub);
+      continue;
+    }
+
+    let existing = null;
+    try { existing = fs.lstatSync(linkPath); } catch (_) { existing = null; }
+
+    if (existing) {
+      // lstat().isSymbolicLink() is true for BOTH POSIX symlinks and Windows
+      // junctions, so this single predicate identifies every GSD-managed link.
+      if (existing.isSymbolicLink()) {
+        // A GSD-managed link that is stale or points elsewhere (e.g. previous
+        // plugin version after `claude plugin update`). Prune and recreate.
+        try {
+          fs.unlinkSync(linkPath);
+          prunedStale.push(sub);
+        } catch (e) {
+          skipped.push(sub);
+          continue;
+        }
+      } else {
+        // A REAL file or directory the user (or a classic install) owns. NEVER
+        // clobber it — preserve it untouched. This is the USER-PROFILE.md /
+        // partially-real-canonical-dir safety case.
+        preserved.push(sub);
+        continue;
+      }
+    }
+
+    try {
+      createDirLink(target, linkPath, platform);
+      linked.push(sub);
+    } catch (e) {
+      skipped.push(sub);
+    }
+  }
+
+  return {
+    status: 'ensured',
+    canonicalDir,
+    bundledTree,
+    linked,
+    prunedStale,
+    preserved,
+    skipped,
+  };
+}
+
+module.exports = {
+  ensureCanonicalPath,
+  resolveBundledTree,
+  resolveConfigDir,
+  dirLinkType,
+  MANAGED_SUBDIRS,
+};
+
+// CLI entry: run on SessionStart. Never block the session — any unexpected
+// failure is swallowed (best-effort self-heal). Emit nothing on stdout to keep
+// the hook silent in normal operation.
+if (require.main === module) {
+  try {
+    ensureCanonicalPath();
+  } catch (_) {
+    // Best-effort: a canonical-path failure must never abort a session.
+  }
+  process.exit(0);
+}

package/hooks/gsd-statusline.js

@@ -312,7 +312,7 @@ function runStatusline() {
     const totalCtx = data.context_window?.total_tokens || 1_000_000;
     const acw = parseInt(process.env.CLAUDE_CODE_AUTO_COMPACT_WINDOW || '0', 10);
     const AUTO_COMPACT_BUFFER_PCT = acw > 0
-      ? Math.min(100, (acw / totalCtx) * 100)
+      ? Math.min(100, Math.max(0, (1 - acw / totalCtx) * 100))
       : 16.5;
     let ctx = '';
     if (remaining != null) {

package/hooks/hooks.json

@@ -3,6 +3,7 @@
     "SessionStart": [
       {
         "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gsd-ensure-canonical-path.js\"", "timeout": 5 },
           { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gsd-check-update.js\"" }
         ]
       }

package/hooks/managed-hooks-registry.cjs

@@ -22,6 +22,7 @@ const MANAGED_HOOKS = [
   'gsd-context-monitor.js',
   'gsd-cursor-post-tool.js',
   'gsd-cursor-session-start.js',
+  'gsd-ensure-canonical-path.js',
   'gsd-graphify-update.sh',
   'gsd-phase-boundary.sh',
   'gsd-prompt-guard.js',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengsd/gsd-core",
-  "version": "1.5.0-rc.3",
+  "version": "1.5.0-rc.4",
   "description": "GSD Core is a meta-prompting, context engineering, and spec-driven development system for AI coding agents.",
   "bin": {
     "gsd-core": "bin/install.js",
@@ -114,9 +114,9 @@
     "test:security": "node scripts/run-tests.cjs --suite security",
     "test:slow": "node scripts/run-tests.cjs --suite slow",
     "test:affected": "node scripts/run-affected-tests.cjs",
-    "test:coverage": "c8 --check-coverage --lines 70 --reporter text --include 'gsd-core/bin/lib/*.cjs' --exclude 'tests/**' --all node scripts/run-tests.cjs",
+    "test:coverage": "c8 --check-coverage --lines 70 --branches 60 --reporter text --include 'gsd-core/bin/lib/*.cjs' --exclude 'tests/**' --all node scripts/run-tests.cjs",
     "test:coverage:scripts-floor": "c8 check-coverage --lines 55 --include 'scripts/**/*.cjs' --exclude 'tests/**' --all",
-    "test:coverage:unit": "c8 --check-coverage --lines 70 --reporter text --include 'gsd-core/bin/lib/*.cjs' --exclude 'tests/**' --all node scripts/run-tests.cjs --suite unit",
+    "test:coverage:unit": "c8 --check-coverage --lines 70 --branches 60 --reporter text --include 'gsd-core/bin/lib/*.cjs' --exclude 'tests/**' --all node scripts/run-tests.cjs --suite unit && c8 check-coverage --per-file --lines 0 --functions 0 --statements 0 --branches 70 --include 'gsd-core/bin/lib/state.cjs' --include 'gsd-core/bin/lib/phase.cjs' --include 'gsd-core/bin/lib/verify.cjs' --include 'gsd-core/bin/lib/init.cjs' --exclude 'tests/**'",
     "test:coverage:all": "npm run test:coverage",
     "test:mutation": "stryker run",
     "test:mutation:since": "stryker run --incremental --since origin/next"

package/scripts/build-hooks.js

@@ -26,6 +26,13 @@ const STAGE_DIR = path.join(HOOKS_DIR, `.dist-staging-${process.pid}`);
 const HOOKS_TO_COPY = [
   'gsd-check-update-worker.js',
   'gsd-check-update.js',
+  // SessionStart canonical-path bootstrap (#997). In a Claude Code marketplace
+  // plugin install, ~/.claude/gsd-core is never created, so every
+  // `@~/.claude/gsd-core/...` include in agents/commands/templates resolves to
+  // nothing. This hook symlinks the canonical path's immutable subdirs to the
+  // plugin's bundled gsd-core/ tree; no-op in classic installs. Must ship to
+  // dist so the installer copies it into the target hooks/ dir.
+  'gsd-ensure-canonical-path.js',
   // Required by gsd-check-update-worker.js at runtime — must ship alongside it
   // so require('./managed-hooks-registry.cjs') resolves in the installed hooks/ dir.
   'managed-hooks-registry.cjs',

package/scripts/changeset/new.cjs

@@ -106,8 +106,14 @@ function parseArgs(argv) {
       const r = requireValue(a, i);
       if (!r.ok) return { ok: false, error: r.error };
       if (a === '--type') opts.type = r.value;
-      else if (a === '--pr') opts.pr = Number(r.value);
-      else if (a === '--body') opts.body = r.value;
+      else if (a === '--pr') {
+        // Accept only decimal-integer strings (digits only, no sign, no dot,
+        // no hex prefix, no scientific notation). Non-integer input — including
+        // empty string and whitespace — is normalized to NaN so the prNaN
+        // guard below rejects it with the usage error.
+        const trimmed = r.value.trim();
+        opts.pr = /^\d+$/.test(trimmed) ? Number(trimmed) : NaN;
+      } else if (a === '--body') opts.body = r.value;
       else if (a === '--repo') opts.repo = r.value;
       i++;
       continue;
@@ -125,7 +131,15 @@ function main() {
     throw new ExitError(2);
   }
   const { opts } = parsed;
-  if (!opts.type || !opts.pr || !opts.body) {
+  // opts.pr starts as null (missing flag) and is set by parseArgs to a Number when
+  // the raw value is a pure decimal-integer string (digits only), or to NaN for any
+  // other input (empty, whitespace, floats, hex, negatives, scientific notation, etc.).
+  // Accept integer 0 (the documented pr:0 placeholder); reject a missing flag (null)
+  // and any non-decimal-integer value (NaN). The merge/lint gate separately
+  // enforces pr > 0 before a fragment can land, so 0 still cannot be merged.
+  const prMissing = opts.pr === null;
+  const prNaN = typeof opts.pr === 'number' && Number.isNaN(opts.pr);
+  if (!opts.type || prMissing || prNaN || !opts.body) {
     throw new ExitError(2, 'usage: changeset/new.cjs --type <Fixed|Added|...> --pr NNNN --body "..."');
   }
   const file = scaffoldFragment(opts);

package/scripts/fix-slash-commands.cjs

@@ -92,9 +92,21 @@ function transformContentToHyphen(src, cmdNames) {
 }
 
 function readCmdNames() {
-  return fs.readdirSync(COMMANDS_DIR)
-    .filter(f => f.endsWith('.md'))
-    .map(f => f.replace(/\.md$/, ''));
+  try {
+    return fs.readdirSync(COMMANDS_DIR)
+      .filter(f => f.endsWith('.md'))
+      .map(f => f.replace(/\.md$/, ''));
+  } catch (err) {
+    // Only swallow the missing-directory case. Any other error (EACCES, ENOTDIR,
+    // etc.) indicates a real misconfiguration and must propagate so callers are
+    // not silently handed an empty registry while the real problem goes undetected.
+    if (err.code !== 'ENOENT') throw err;
+    // COMMANDS_DIR may not exist on installs that use skill-based runtimes or
+    // global Claude installs (no local commands/gsd/ directory). Return [] so
+    // callers that handle an empty array gracefully (buildPattern returns null,
+    // transformContent is a no-op) are not broken by a missing directory.
+    return [];
+  }
 }
 
 function processFile(file, cmdNames) {

package/scripts/gen-capability-registry.cjs

@@ -546,8 +546,10 @@ function validateFeatureBody(cap) {
 }
 
 // ADR-857 phase 5e: Closed ConverterName enum — complete set used across 16 runtime descriptors,
-// all exported by bin/install.js. Any ArtifactKind with a non-null converter must use one of these.
+// all exported by bin/install.js (commands/skills) and src/runtime-artifact-conversion.cts (agents).
+// Any ArtifactKind with a non-null converter must use one of these.
 const VALID_CONVERTER_NAMES = new Set([
+  // commands / skills converters (pre-existing)
   'convertClaudeCommandToAntigravitySkill',
   'convertClaudeCommandToAugmentSkill',
   'convertClaudeCommandToClineSkill',
@@ -563,6 +565,16 @@ const VALID_CONVERTER_NAMES = new Set([
   'convertClaudeCommandToOpencodeSkill',
   'convertClaudeCommandToTraeSkill',
   'convertClaudeCommandToWindsurfSkill',
+  // agent converters (#1173 — descriptor-driven agent conversion wiring)
+  'convertClaudeAgentToCopilotAgent',
+  'convertClaudeAgentToAntigravityAgent',
+  'convertClaudeAgentToCursorAgent',
+  'convertClaudeAgentToWindsurfAgent',
+  'convertClaudeAgentToAugmentAgent',
+  'convertClaudeAgentToTraeAgent',
+  'convertClaudeAgentToCodebuddyAgent',
+  'convertClaudeAgentToClineAgent',
+  'convertClaudeAgentToCodexAgent',
 ]);
 
 // C3: Validate role:runtime body
@@ -2553,6 +2565,7 @@ module.exports = {
   computeRequiresClosure,
   topoSortSteps,
   normalizeLineEndings,
+  stripGeneratedComment,
   validateConfigSliceEntry,
   VALID_CONFIG_SLICE_TYPES,
   LOOP_HOST_CONTRACT,

package/scripts/lint-allow-test-rule-refs.allowlist.json

@@ -215,6 +215,8 @@
   "tests/forensics.test.cjs :: source-text-is-the-product",
   "tests/frontmatter-cli.test.cjs :: source-text-is-the-product",
   "tests/gates-taxonomy.test.cjs :: source-text-is-the-product",
+  "tests/git-base-branch.test.cjs :: runtime-contract-is-the-product",
+  "tests/git-base-branch.test.cjs :: runtime-contract-is-the-product — the workflow .md content IS",
   "tests/gsd-check-update-worker-platform-gate.test.cjs :: structural assertion on spawn-options shape; the behavior",
   "tests/gsd-researcher-app-aware.test.cjs :: source-text-is-the-product",
   "tests/gsd-researcher-flow-diagram.test.cjs :: source-text-is-the-product",
@@ -289,7 +291,6 @@
   "tests/research-agent-profiles.test.cjs :: <runtime-contract-is-the-product> research agent .md content is the governed surface",
   "tests/review-default-reviewers-workflow.test.cjs :: source-text-is-the-product",
   "tests/roadmap.test.cjs :: source-text-is-the-product",
-  "tests/roadmapper-granularity.test.cjs :: source-text-is-the-product",
   "tests/run-tests-harness.test.cjs :: run-tests.cjs is a CLI test harness whose only IR is its",
   "tests/runtime-launcher-parity.test.cjs :: structural parity/drift guard — asserts literal presence/absence of the canonical gsd_run launcher and the retired $GSD_SDK / `/gsd-tools` tokens across workflow markdown; there is no typed IR for \"this source file does not contain substring X\".",
   "tests/runtime-name-policy.test.cjs :: runtime-contract-is-the-product — FALLBACK_ALIASES source text IS the",

package/scripts/lint-test-file-count.allowlist.json

@@ -168,6 +168,12 @@
         "federated-config-key-removal.test.cjs"
       ],
       "issue": "TBD"
+    },
+    "external-job": {
+      "files": [
+        "external-job-waiting.test.cjs"
+      ],
+      "issue": "#1165"
     }
   }
 }