@opengsd/gsd-core 1.10.0 → 1.12.0

package/scripts/select-docs-guards.cjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * select-docs-guards.cjs — pure selector mapping a PR's changed docs/ paths
+ * to the subset of scripts/docs-guard-registry.cjs's DOCS_GUARD_TESTS that
+ * actually reads any of them (#3753 follow-up).
+ *
+ * Deliberately dependency-free: no fs, no git, no process. Callers (the
+ * docs-required.yml workflow, tests) are responsible for producing the
+ * changed-paths list and reading the registry; this module only implements
+ * the matching semantics so they are independently unit-testable.
+ *
+ * Pattern semantics (mirrors scripts/docs-guard-registry.cjs's header doc):
+ *   - a plain path matches an exact changed path;
+ *   - a trailing-slash path is a DIRECTORY PREFIX match — 'docs/adr/'
+ *     matches 'docs/adr/README.md' but must NOT match 'docs/adrenaline.md'
+ *     (a naive `startsWith('docs/adr')` without the trailing slash would
+ *     wrongly match the latter; matching against the full prefix INCLUDING
+ *     the trailing slash is what keeps this boundary correct);
+ *   - the sentinel '*' matches any non-empty changedDocsPaths.
+ */
+
+/**
+ * @param {string} changedPath - a single changed docs/ path (e.g. 'docs/AGENTS.md').
+ * @param {string} pattern - one entry from a registry value array.
+ * @returns {boolean}
+ */
+function patternMatches(changedPath, pattern) {
+  if (pattern === '*') return true;
+  if (pattern.endsWith('/')) return changedPath.startsWith(pattern);
+  return changedPath === pattern;
+}
+
+/**
+ * @param {string[]} changedDocsPaths - repo-relative paths under docs/ that
+ *   changed in this PR. An empty array always yields an empty selection.
+ * @param {Record<string, string[]>} registry - DOCS_GUARD_TESTS shape: test
+ *   file -> array of patterns it reads.
+ * @returns {string[]} sorted, deduped list of selected test file paths.
+ */
+function selectDocsGuards(changedDocsPaths, registry) {
+  if (!Array.isArray(changedDocsPaths) || changedDocsPaths.length === 0) return [];
+
+  const selected = new Set();
+  for (const [testFile, patterns] of Object.entries(registry)) {
+    const hit = patterns.some((pattern) =>
+      changedDocsPaths.some((changedPath) => patternMatches(changedPath, pattern)),
+    );
+    if (hit) selected.add(testFile);
+  }
+
+  return [...selected].sort();
+}
+
+module.exports = { selectDocsGuards, patternMatches };

package/scripts/sync-runtime-launcher.cjs

@@ -19,6 +19,8 @@
 const fs = require('node:fs');
 const path = require('node:path');
 
+const { escapeRegex: escapeRegExp } = require('../gsd-core/bin/lib/pattern.cjs');
+
 const WORKFLOWS_DIR = path.join(__dirname, '..', 'gsd-core', 'workflows');
 const AGENTS_DIR = path.join(__dirname, '..', 'agents');
 const SNIPPET_FILE = path.join(WORKFLOWS_DIR, '_runtime-launcher.snippet.sh');
@@ -328,6 +330,16 @@ function transformFile(content, preamble) {
   let changed = false;
   let firstGsdRunBlockIdx = -1; // index into shellBlockRanges of the first gsd_run block (after strip)
 
+  // A file may place the preamble in a bootstrap-only block that defines
+  // gsd_run without calling it (gsd-core/workflows/explore.md Step 1, which
+  // documents exactly why). Stripping empties that block of gsd_run calls, so
+  // a pure "first block that CALLS gsd_run" target silently relocates the
+  // preamble forward and breaks define-before-use. Honour where it already is.
+  const existingPreambleBlockIdx = shellBlockRanges.findIndex((range) =>
+    allLines
+      .slice(range.contentStart, range.contentEnd)
+      .some((l) => /^\s*_GSD_SHIM_NAME=/.test(l)));
+
   // First: strip + replace in all blocks, find first gsd_run block
   const strippedBlocks = shellBlockRanges.map((range) => {
     const blockLines = outputLines.slice(range.contentStart, range.contentEnd);
@@ -343,12 +355,17 @@ function transformFile(content, preamble) {
     }
   }
 
-  // Insert preamble into the first gsd_run block only — UNLESS this file
+  // If the preamble already existed in a specific block before stripping,
+  // keep it there (even if that block no longer calls gsd_run after
+  // stripping). Otherwise fall back to the first gsd_run-calling block.
+  const preambleTargetIdx = existingPreambleBlockIdx >= 0 ? existingPreambleBlockIdx : firstGsdRunBlockIdx;
+
+  // Insert preamble into the target block only — UNLESS this file
   // delegates to the shared resolver reference (@-include). Delegating files keep
   // the stripped blocks (any inline preamble removed) but never get one inserted.
   const delegates = delegatesToResolverReference(content);
   const finalBlocks = strippedBlocks.map((stripped, bi) => {
-    if (!delegates && bi === firstGsdRunBlockIdx) {
+    if (!delegates && bi === preambleTargetIdx) {
       return insertPreamble(stripped, preamble);
     }
     return stripped;
@@ -373,10 +390,6 @@ function transformFile(content, preamble) {
   return outputLines.join('\n');
 }
 
-function escapeRegExp(str) {
-  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-
 /**
  * A file "delegates to the shared resolver" when it pulls the canonical gsd_run
  * preamble in from gsd-core/references/gsd-run-resolver.md via an @-include
@@ -430,4 +443,8 @@ function main() {
   console.log(`\nDone. ${transformedCount} files transformed, ${unchangedCount} unchanged.`);
 }
 
-main();
+if (require.main === module) {
+  main();
+}
+
+module.exports = { transformFile };

package/skills/gsd-autonomous/SKILL.md

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

package/skills/gsd-code-review/SKILL.md

@@ -41,7 +41,7 @@ Optional flags parsed from $ARGUMENTS:
 - `--depth=VALUE` — Depth override (quick|standard|deep). If provided, overrides workflow.code_review_depth config.
 - `--files=file1,file2,...` — Explicit file list override. Has highest precedence for file scoping per D-08. When provided, workflow skips SUMMARY.md extraction and git diff fallback entirely.
 
-Context files (CLAUDE.md, SUMMARY.md, phase state) are resolved inside the workflow via `gsd-tools query init.phase-op` and delegated to agent via `<files_to_read>` blocks.
+Context files (CLAUDE.md, SUMMARY.md, phase state) are resolved inside the workflow via `gsd-tools query init.phase-op` and delegated to agent via `<required_reading>` blocks.
 </context>
 
 <process>

package/skills/gsd-discuss-phase/SKILL.md

@@ -48,7 +48,7 @@ Context files are resolved in-workflow using `init phase-op` and roadmap/state t
 **Mode routing:**
 ```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
-DISCUSS_MODE=$(gsd_run query config-get workflow.discuss_mode 2>/dev/null || echo "discuss")
+DISCUSS_MODE=$(gsd_run query config-get workflow.discuss_mode --raw 2>/dev/null || echo "discuss")
 ```
 
 If `--assumptions` is in $ARGUMENTS:

package/skills/gsd-execute-phase/SKILL.md

@@ -2,7 +2,6 @@
 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]"
-effort: high
 allowed-tools:
   - Read
   - Write
@@ -56,7 +55,7 @@ Phase: $ARGUMENTS
 - If none of these tokens appear, run the standard full-phase execution flow with no flag-specific filtering
 - Do not infer that a flag is active just because it is documented in this prompt
 
-Context files are resolved inside the workflow via `gsd-tools query init.execute-phase` and per-subagent `<files_to_read>` blocks.
+Context files are resolved inside the workflow via `gsd-tools query init.execute-phase` and per-subagent `<required_reading>` blocks.
 </context>
 
 <process>

package/skills/gsd-import/SKILL.md

@@ -18,7 +18,7 @@ allowed-tools:
 Import external plan files into the GSD planning system with conflict detection against PROJECT.md decisions.
 
 - **--from**: Import an external plan file, detect conflicts, write as GSD PLAN.md, validate via gsd-plan-checker.
-- **--from-gsd2**: Reverse-migrate a GSD-2 project (`.gsd/` directory) back to GSD v1 (`.planning/`) format. Runs `gsd-tools.cjs from-gsd2`. Pass `--path <dir>` to migrate a project at a different path.
+- **--from-gsd2**: Reverse-migrate a GSD-2 project (`.gsd/` directory) back to GSD v1 (`.planning/`) format. Runs `gsd_run from-gsd2`. Pass `--path <dir>` to migrate a project at a different path.
 </objective>
 
 <execution_context>

package/skills/gsd-map-codebase/SKILL.md

@@ -34,7 +34,7 @@ Output: .planning/codebase/ folder with 7 structured documents about the codebas
 Arguments: $ARGUMENTS
 
 Parse the first token of $ARGUMENTS:
-- If it is `--fast`: strip the flag, run the scan workflow (passing remaining args including optional --focus).
+- If it is `--fast`: strip the flag, then read and execute `~/.claude/gsd-core/workflows/scan.md` (passing remaining args including optional --focus). Load it on demand here — it is deliberately not in `<execution_context>`, so the common full-map path does not pay for it.
 - If it is `--query`: strip the flag, run the intel workflow (passing remaining args as the subcommand).
 - Otherwise: pass all of $ARGUMENTS as focus area to the map-codebase workflow.
 

package/skills/gsd-mempalace-capture/SKILL.md

@@ -86,7 +86,7 @@ On any error or timeout, stop and let the phase continue -- capture is best-effo
    # Mine with --wing only — no --room flag; detect_room() assigns from the folder path
    mempalace mine "$STAGE" --wing <wing>
    ```
-3. **Mirror KG facts** when `config.mempalace.mirror_kg` is true: extract decision/delivery facts and `mempalace_kg_add` them with `valid_from` = the phase date (e.g. `(<project>, decided, <decision>)` from CONTEXT; `(<phase>, delivered, <capability>)` from SUMMARY). Under `augment` these are an *additive* mirror of GSD's native `.planning/graphs/`. Under `kg_backend`/`replace` the palace KG is the *authoritative* fact store — GSD still produces `.planning/graphs/` through its normal graphify, so an unreachable palace never loses a fact.
+3. **Mirror KG facts** unless `config.mempalace.mirror_kg === false` (registry default is true — an absent key means enabled): extract decision/delivery facts and `mempalace_kg_add` them with `valid_from` = the phase date (e.g. `(<project>, decided, <decision>)` from CONTEXT; `(<phase>, delivered, <capability>)` from SUMMARY). Under `augment` these are an *additive* mirror of GSD's native `.planning/graphs/`. Under `kg_backend`/`replace` the palace KG is the *authoritative* fact store — GSD still produces `.planning/graphs/` through its normal graphify, so an unreachable palace never loses a fact.
 4. Re-running a phase MUST NOT create duplicate drawers (deterministic ids + `check_duplicate`).
 
 ## Step 4 -- Report

package/skills/gsd-mempalace-recall/SKILL.md

@@ -66,7 +66,7 @@ All calls in this step are side-effect-free. On any error or timeout, stop retri
 2. **Targeted search:**
    - Interactive: `mempalace_search(query=<topic>, wing=<wing>)`.
    - Headless: `mempalace search "<topic>" --wing <wing>`.
-3. **Knowledge-graph facts** (when `config.mempalace.mirror_kg` is true): `mempalace_kg_query` / `mempalace_kg_timeline` for decisions relevant to the topic and their validity windows. Under `augment` the palace KG *supplements* GSD's native `.planning/graphs/` — combine both, do not treat the palace as the sole source. Under `kg_backend` or `replace` the palace KG is the *primary* graph source — query it first and use `.planning/graphs/` only as a fallback when the palace is unreachable.
+3. **Knowledge-graph facts** (unless `config.mempalace.mirror_kg !== false` — registry default is true, an absent key means enabled): `mempalace_kg_query` / `mempalace_kg_timeline` for decisions relevant to the topic and their validity windows. Under `augment` the palace KG *supplements* GSD's native `.planning/graphs/` — combine both, do not treat the palace as the sole source. Under `kg_backend` or `replace` the palace KG is the *primary* graph source — query it first and use `.planning/graphs/` only as a fallback when the palace is unreachable.
 4. **Dedup** the returned drawers/facts; keep the top results.
 
 ## Step 4 -- Write MEMORY-RECALL.md

package/skills/gsd-new-milestone/SKILL.md

@@ -36,7 +36,7 @@ Brownfield equivalent of new-project. Project exists, PROJECT.md has history. Ga
 <context>
 Milestone name: $ARGUMENTS (optional - will prompt if not provided)
 
-Project and milestone context files are resolved inside the workflow (`init new-milestone`) and delegated via `<files_to_read>` blocks where subagents are used.
+Project and milestone context files are resolved inside the workflow (`init new-milestone`) and delegated via `<required_reading>` blocks where subagents are used.
 </context>
 
 <process>

package/skills/gsd-next/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: gsd-next
 description: "Smart entry — detect project state and route to the right next GSD action."
-effort: low
 allowed-tools:
   - Read
   - Bash

package/skills/gsd-plan-phase/SKILL.md

@@ -2,7 +2,6 @@
 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] [--skip-ui] [--prd <file>] [--ingest <path-or-glob>] [--ingest-format <auto|nygard|madr|narrative>] [--reviews] [--text] [--bounce] [--skip-bounce] [--chunked] [--tdd] [--mvp] [--granularity <coarse|standard|fine>] [--no-tracer] [--no-reversibility-gates]"
-effort: high
 allowed-tools:
   - Read
   - Write

package/skills/gsd-progress/SKILL.md

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

package/skills/gsd-quick/SKILL.md

@@ -46,7 +46,7 @@ Granular flags are composable: `--discuss --research --validate` gives the same
 <context>
 $ARGUMENTS
 
-Context files are resolved inside the workflow (`init quick`) and delegated via `<files_to_read>` blocks.
+Context files are resolved inside the workflow (`init quick`) and delegated via `<required_reading>` blocks.
 </context>
 
 <process>
@@ -86,12 +86,14 @@ For each directory found:
 Display format:
 ```
 Quick Tasks
-────────────────────────────────────────────────────────────
+
+---
 slug                           date        status
 backup-s3-policy               2026-04-10  in-progress
 auth-token-refresh-fix         2026-04-09  complete ✓
 update-node-deps               2026-04-08  abandoned? (>7 days, no summary)
-────────────────────────────────────────────────────────────
+
+---
 3 tasks (1 complete, 2 incomplete/in-progress)
 ```
 
@@ -113,12 +115,14 @@ If no directory found, print `No quick task found with slug: {SLUG}` and stop.
 Read PLAN.md and SUMMARY.md (if exists) for the given slug. Display:
 ```
 Quick Task: {slug}
-─────────────────────────────────────
+
+---
 Plan file: .planning/quick/{dir}/PLAN.md
 Status: {status from SUMMARY.md frontmatter, or "no summary yet"}
 Description: {first non-empty line from PLAN.md after frontmatter}
 Last action: {last meaningful line of SUMMARY.md, or "none"}
-─────────────────────────────────────
+
+---
 Resume with: /gsd-quick resume {slug}
 ```
 

package/skills/gsd-review-backlog/SKILL.md

@@ -18,7 +18,8 @@ milestone sequence or remove stale entries.
 
 1. **List backlog items:**
    ```bash
-   ls -d .planning/phases/999* 2>/dev/null || echo "No backlog items found"
+   _BACKLOG=( .planning/phases/999* )
+   if [ -e "${_BACKLOG[0]}" ]; then ls -d "${_BACKLOG[@]}"; else echo "No backlog items found"; fi
    ```
 
 2. **Read ROADMAP.md** and extract all 999.x phase entries:

package/skills/gsd-stats/SKILL.md

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

package/skills/gsd-verify-work/SKILL.md

@@ -30,7 +30,7 @@ Phase: $ARGUMENTS (optional)
 - If provided: Test specific phase (e.g., "4")
 - If not provided: Check for active sessions or prompt for phase
 
-Context files are resolved inside the workflow (`init verify-work`) and delegated via `<files_to_read>` blocks.
+Context files are resolved inside the workflow (`init verify-work`) and delegated via `<required_reading>` blocks.
 </context>
 
 <process>

package/vscode/package.json

@@ -2,7 +2,7 @@
   "name": "gsd-core-vscode",
   "displayName": "GSD Core",
   "description": "GSD orchestration engine embedded in VS Code (ADR-1239 IDE profile).",
-  "version": "1.10.0",
+  "version": "1.12.0",
   "publisher": "opengsd",
   "engines": {
     "vscode": "^1.105.0"

package/bin/lib/ui-safety-gate.cjs

@@ -1,107 +0,0 @@
-'use strict';
-
-/**
- * UI Safety Gate — shell-free implementation (#3706, #3718)
- *
- * Replaces the bash shell-based one-liner that silently degraded on Windows
- * PowerShell / cmd.exe because the locale env-var prefix was not recognised.
- * This module runs inside Node.js — no shell dependency, works identically
- * on bash, Git-Bash, PowerShell, and cmd.exe.
- *
- * Word-boundary anchoring:
- *   (^|[^a-zA-Z0-9])(TOKEN)([^a-zA-Z0-9]|$)
- * Equivalent to POSIX ERE [^[:alnum:]] — matches tokens only when they are not
- * interior substrings of alphanumeric compound words (e.g. "microfrontend" is NOT
- * matched; "micro-frontend" and "micro frontend" ARE matched).
- *
- * Public API:
- *   checkUiPresence(text: string): { hasUI: boolean, tokens: string[] }
- *
- * CLI usage — reads phase-section text from STDIN to avoid ARG_MAX limits:
- *   echo "$PHASE_SECTION" | node bin/lib/ui-safety-gate.cjs
- *   echo $?   → 0 if UI tokens found, 1 if not, 2 on usage error
- *
- * Exit codes mirror grep: 0 = match found, 1 = no match, 2 = usage error.
- */
-
-const UI_TOKENS = [
-  'UI',
-  'interface',
-  'frontend',
-  'component',
-  'layout',
-  'page',
-  'screen',
-  'view',
-  'form',
-  'dashboard',
-  'widget',
-];
-
-/**
- * Built once at module load — no per-call compilation overhead.
- * ASCII word boundaries — matches the original ASCII-grep intent of #3706.
- * Note: JS [a-zA-Z0-9] is ASCII-only and NOT equivalent to POSIX [[:alnum:]],
- * which is locale-sensitive and includes accented characters.
- */
-const UI_GATE_PATTERN = new RegExp(
-  '(^|[^a-zA-Z0-9])(' + UI_TOKENS.join('|') + ')([^a-zA-Z0-9]|$)',
-  'i'
-);
-
-// Global-flagged variant for extracting ALL matches per line (matchAll).
-const UI_GATE_PATTERN_GLOBAL = new RegExp(UI_GATE_PATTERN.source, 'gi');
-
-/**
- * Check a roadmap phase section string for frontend UI indicators.
- *
- * @param {string} text - The roadmap phase section content (may be multi-line, CRLF or LF).
- * @returns {{ hasUI: boolean, tokens: string[] }}
- *   hasUI — true if any UI token was matched as a standalone word.
- *   tokens — matched token strings (lowercased), deduplicated.
- */
-function checkUiPresence(text) {
-  if (typeof text !== 'string') {
-    return { hasUI: false, tokens: [] };
-  }
-
-  // Normalise CRLF so the pattern sees consistent line boundaries.
-  const normalised = text.replace(/\r\n/g, '\n');
-
-  const found = new Set();
-  for (const line of normalised.split('\n')) {
-    // Reset lastIndex before each line so the global pattern restarts from 0.
-    UI_GATE_PATTERN_GLOBAL.lastIndex = 0;
-    for (const m of line.matchAll(UI_GATE_PATTERN_GLOBAL)) {
-      found.add(m[2].toLowerCase());
-    }
-  }
-
-  return { hasUI: found.size > 0, tokens: [...found] };
-}
-
-module.exports = { checkUiPresence, UI_TOKENS };
-
-// ── CLI entry point ─────────────────────────────────────────────────────────
-// Reads phase-section text from STDIN (not argv) to avoid OS ARG_MAX limits.
-// Invoked by workflow .md bash blocks as: echo "$PHASE_SECTION" | node bin/lib/ui-safety-gate.cjs
-// Exit 0 = UI found, 1 = no UI, 2 = startup error.
-
-if (require.main === module) {
-  // Collect stdin chunks asynchronously.
-  const chunks = [];
-  process.stdin.setEncoding('utf-8');
-
-  process.stdin.on('data', (chunk) => chunks.push(chunk));
-
-  process.stdin.on('end', () => {
-    const input = chunks.join('');
-    const result = checkUiPresence(input);
-    process.exit(result.hasUI ? 0 : 1);
-  });
-
-  process.stdin.on('error', (err) => {
-    process.stderr.write(`ERROR: ui-safety-gate.cjs stdin read failed: ${err.message}\n`);
-    process.exit(2);
-  });
-}