@opengsd/gsd-core 1.3.1 → 1.4.0-rc.2

package/commands/gsd/autonomous.md

@@ -2,6 +2,8 @@
 name: gsd:autonomous
 description: Run all remaining phases autonomously — discuss→plan→execute per phase
 argument-hint: "[--from N] [--to N] [--only N] [--interactive]"
+context: fork
+effort: xhigh
 allowed-tools:
   - Read
   - Write

package/commands/gsd/execute-phase.md

@@ -2,6 +2,8 @@
 name: gsd:execute-phase
 description: Execute all plans in a phase with wave-based parallelization
 argument-hint: "<phase-number> [--wave N] [--gaps-only] [--interactive] [--tdd]"
+context: fork
+effort: xhigh
 allowed-tools:
   - Read
   - Write

package/commands/gsd/graphify.md

@@ -79,7 +79,8 @@ Modes:
 Run:
 
 ```bash
-node $HOME/.claude/gsd-core/bin/gsd-tools.cjs graphify query <term>
+_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi
+gsd_run graphify query <term>
 ```
 
 Parse the JSON output and display results:
@@ -95,7 +96,8 @@ Parse the JSON output and display results:
 Run:
 
 ```bash
-node $HOME/.claude/gsd-core/bin/gsd-tools.cjs graphify status
+_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi
+gsd_run graphify status
 ```
 
 Parse the JSON output and display:
@@ -119,7 +121,8 @@ Surface both so the agent can choose.
 Run:
 
 ```bash
-node $HOME/.claude/gsd-core/bin/gsd-tools.cjs graphify diff
+_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi
+gsd_run graphify diff
 ```
 
 Parse the JSON output and display:
@@ -137,7 +140,8 @@ If no snapshot exists, suggest running `build` twice (first to create, second to
 Run the pre-flight check first:
 
 ```bash
-node "$HOME/.claude/gsd-core/bin/gsd-tools.cjs" graphify build
+_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi
+gsd_run graphify build
 ```
 
 Parse the JSON output:
@@ -156,12 +160,13 @@ GSD > Building knowledge graph...
 Run the build, copy artifacts, write the diff snapshot, and report the summary in a single foreground Bash call so the whole pipeline survives to completion. Use a `timeout` of `600000` ms (10 minutes), which covers the `graphify.build_timeout` ceiling (default 300 s) with margin:
 
 ```bash
+_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi
 graphify update . \
   && cp graphify-out/graph.json .planning/graphs/graph.json \
   && { [ -f graphify-out/graph.html ] && cp graphify-out/graph.html .planning/graphs/graph.html || true; } \
   && cp graphify-out/GRAPH_REPORT.md .planning/graphs/GRAPH_REPORT.md \
-  && node "$HOME/.claude/gsd-core/bin/gsd-tools.cjs" graphify build snapshot \
-  && node "$HOME/.claude/gsd-core/bin/gsd-tools.cjs" graphify status
+  && gsd_run graphify build snapshot \
+  && gsd_run graphify status
 ```
 
 Do NOT pass `run_in_background: true`. Typical builds complete in 15-60 seconds and the entire chain must run foreground.

package/commands/gsd/import.md

@@ -33,8 +33,12 @@ $ARGUMENTS
 
 <process>
 If `--from-gsd2` is in $ARGUMENTS:
-Run: `node "$HOME/.claude/gsd-core/bin/gsd-tools.cjs" from-gsd2`
-Pass `--path <dir>` if provided. Present the migration result to the user.
+Run the reverse-migration (append `--path <dir>` if provided):
+```bash
+_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="$HOME/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi
+gsd_run from-gsd2
+```
+Present the migration result to the user.
 Stop here (do not run the standard import workflow).
 
 Otherwise, execute the import workflow end-to-end.

package/commands/gsd/plan-phase.md

@@ -2,6 +2,8 @@
 name: gsd:plan-phase
 description: Create detailed phase plan (PLAN.md) with verification loop
 argument-hint: "[phase] [--auto] [--research] [--skip-research] [--research-phase <N>] [--view] [--gaps] [--skip-verify] [--prd <file>] [--ingest <path-or-glob>] [--ingest-format <auto|nygard|madr|narrative>] [--reviews] [--text] [--tdd] [--mvp]"
+context: fork
+effort: xhigh
 allowed-tools:
   - Read
   - Write
@@ -22,8 +24,8 @@ Create executable phase prompts (PLAN.md files) for a roadmap phase with integra
 **Research-only mode (`--research-phase <N>`):** Spawn `gsd-phase-researcher` for phase `N`, write `RESEARCH.md`, then exit before the planner runs. Useful for cross-phase research, doc review before committing to a planning approach, and correction-without-replanning loops where iterating on research alone is dramatically cheaper than re-spawning the planner. Replaces the deleted research-phase command (#3042).
 
 **Research-only modifiers:**
-- **No flag** — when `RESEARCH.md` already exists, prompt the user to choose `update / view / skip`.
-- **`--research`** — force-refresh: re-spawn the researcher unconditionally, no prompt. Skips the existing-RESEARCH.md menu.
+- **No flag** — when `RESEARCH.md` already exists, auto-uses it: emits a one-line notice and exits cleanly, no prompt.
+- **`--research`** — force-refresh: re-spawn the researcher unconditionally, no prompt. Bypasses the existing-RESEARCH.md auto-use path.
 - **`--view`** — view-only: print existing `RESEARCH.md` to stdout. Does not spawn the researcher. Cheapest mode for the correction-without-replanning loop. If no `RESEARCH.md` exists yet, errors with a hint to drop `--view`.
 
 **Orchestrator role:** Parse arguments, validate phase, research domain (unless skipped), spawn gsd-planner, verify with gsd-plan-checker, iterate until pass or max iterations, present results.

package/commands/gsd/progress.md

@@ -2,6 +2,7 @@
 name: gsd:progress
 description: Check progress, advance workflow, or dispatch freeform intent — the unified GSD situational command
 argument-hint: "[--forensic | --next | --do \"task description\"]"
+effort: low
 allowed-tools:
   - Read
   - Bash

package/commands/gsd/stats.md

@@ -1,6 +1,7 @@
 ---
 name: gsd:stats
 description: Display project statistics — phases, plans, requirements, git metrics, and timeline
+effort: low
 allowed-tools:
   - Read
   - Bash

package/commands/gsd/update.md

@@ -1,7 +1,7 @@
 ---
 name: gsd:update
 description: Update GSD to latest version with changelog display
-argument-hint: "[--sync | --reapply]"
+argument-hint: "[--sync | --reapply | --next | --rc]"
 allowed-tools:
   - Read
   - Write
@@ -31,6 +31,7 @@ Routes to the update workflow which handles:
 <flags>
 - **--sync**: Sync managed GSD skills across runtime roots so multi-runtime users stay aligned after an update. Runs the sync-skills workflow (--from, --to, --dry-run, --apply flags supported).
 - **--reapply**: Reapply local modifications after a GSD update. Uses three-way comparison (pristine baseline, user-modified backup, newly installed version) to merge user customizations back. Runs the reapply-patches workflow.
+- **--next** (alias **--rc**): Target the `@next` RC dist-tag instead of `@latest` so you can install or refresh a release candidate (e.g. `1.4.0-rc.1`) through the normal update flow — scope/runtime detection, changelog preview, custom-file backup, and cache clearing all still apply. Omitting it keeps targeting `@latest` (no change). See ADR #660 for the RC channel.
 - **(no flag)**: Standard update — check for new version, show changelog, install.
 </flags>
 
@@ -38,7 +39,7 @@ Routes to the update workflow which handles:
 Parse the first token of $ARGUMENTS:
 - If it is `--sync`: strip the flag, execute the sync-skills workflow (passing remaining args for --from/--to/--dry-run/--apply).
 - If it is `--reapply`: strip the flag, execute the reapply-patches workflow.
-- Otherwise: execute the update workflow end-to-end.
+- Otherwise (including `--next` / `--rc`): execute the update workflow end-to-end, passing `$ARGUMENTS` through so the workflow's parse_update_channel step can select the release channel.
 
 </process>
 

package/gemini-extension.json

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

package/gsd-core/bin/check-latest-version.cjs

@@ -21,6 +21,7 @@
  */
 
 const { execNpm } = require('./lib/shell-command-projection.cjs');
+const { runMain } = require('./lib/cli-exit.cjs');
 
 // Sourced from the single Package Identity seam (#498), not re-typed. The seam
 // bakes the value from package.json at build time, so it is a code constant —
@@ -36,18 +37,64 @@ const CHECK_REASON = Object.freeze({
 
 const SEMVER_RE = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/;
 
+// #815: the one RC channel ADR #660 sanctions, plus the stable default.
+// An allowlist (not a free string) keeps a typo from silently resolving
+// `npm view` to an empty or foreign dist-tag.
+const ALLOWED_TAGS = Object.freeze(['latest', 'next']);
+
+/**
+ * Build the `npm view` args for a dist-tag. `latest` keeps the bare package
+ * spec so the default invocation is byte-for-byte identical to before tag
+ * support existed (#815); any other allowlisted tag appends `@<tag>` so
+ * `npm view @opengsd/gsd-core@next version` resolves the RC channel (#660).
+ */
+function buildViewArgs(tag = 'latest') {
+  if (!ALLOWED_TAGS.includes(tag)) {
+    throw new RangeError(`invalid dist-tag '${tag}'; allowed: ${ALLOWED_TAGS.join(', ')}`);
+  }
+  const spec = tag === 'latest' ? PACKAGE_NAME : `${PACKAGE_NAME}@${tag}`;
+  return ['view', spec, 'version'];
+}
+
+/**
+ * Resolve the requested dist-tag from argv. Defaults to `latest` (no flag =>
+ * no behavior change). Restricted to ALLOWED_TAGS so a typo can't silently
+ * resolve to an empty/foreign tag (#815 alternative 1).
+ */
+function resolveTag(argv) {
+  let val;
+  const eq = argv.find((a) => typeof a === 'string' && a.startsWith('--tag='));
+  if (eq !== undefined) {
+    val = eq.slice('--tag='.length);
+  } else {
+    const i = argv.indexOf('--tag');
+    if (i === -1) return 'latest';
+    val = argv[i + 1];
+  }
+  if (!val || !ALLOWED_TAGS.includes(val)) {
+    throw new RangeError(
+      `invalid --tag '${val || ''}'; allowed: ${ALLOWED_TAGS.join(', ')}`,
+    );
+  }
+  return val;
+}
+
 /**
  * Pure-ish: takes an injected spawn function so tests don't actually run npm.
  * In production, defaults to execNpm() from the shell-projection seam.
  */
 function checkLatestVersion(opts = {}) {
+  const tag = opts.tag || 'latest';
+  if (!ALLOWED_TAGS.includes(tag)) {
+    throw new RangeError(`invalid dist-tag '${tag}'; allowed: ${ALLOWED_TAGS.join(', ')}`);
+  }
   // Default path routes through the shell-projection seam (execNpm owns the
   // Windows shell-flag policy and timeout default). The injection point
   // remains spawnSync-shaped for test compatibility — the adapter below
   // translates { exitCode } → { status } so the consumer logic is unchanged.
   // Bounded at 15s so a hung registry doesn't block /gsd-update (#2993 CR).
   const defaultSpawn = () => {
-    const r = execNpm(['view', PACKAGE_NAME, 'version'], { timeout: 15_000 });
+    const r = execNpm(buildViewArgs(tag), { timeout: 15_000 });
     return {
       status: r.exitCode,
       stdout: r.stdout,
@@ -89,8 +136,16 @@ function checkLatestVersion(opts = {}) {
 }
 
 function main() {
-  const json = process.argv.includes('--json');
-  const r = checkLatestVersion();
+  const argv = process.argv.slice(2);
+  const json = argv.includes('--json');
+  let tag;
+  try {
+    tag = resolveTag(argv);
+  } catch (e) {
+    process.stderr.write(`check-latest-version: ${e.message}\n`);
+    return 2;
+  }
+  const r = checkLatestVersion({ tag });
   if (json) {
     process.stdout.write(JSON.stringify(r) + '\n');
   } else if (r.ok) {
@@ -98,9 +153,9 @@ function main() {
   } else {
     process.stderr.write(`check-latest-version: ${r.reason}: ${r.detail}\n`);
   }
-  process.exit(r.ok ? 0 : 1);
+  return r.ok ? 0 : 1;
 }
 
-if (require.main === module) main();
+if (require.main === module) runMain(main);
 
-module.exports = { checkLatestVersion, CHECK_REASON, PACKAGE_NAME };
+module.exports = { checkLatestVersion, CHECK_REASON, PACKAGE_NAME, ALLOWED_TAGS, buildViewArgs, resolveTag };