From 924c697097ac6ad78daf58eb03c0e626fbfe90bb Mon Sep 17 00:00:00 2001 From: Tom Boucher Date: Fri, 8 May 2026 09:06:37 -0400 Subject: [PATCH] docs: replace retired /gsd-intel with /gsd-map-codebase --query (#3258) (#3260) * test: forbid stale /gsd-intel references in workflow/reference docs (#3258) Co-Authored-By: Claude Sonnet 4.6 * docs: replace retired /gsd-intel with /gsd-map-codebase --query (#3258) Fixes 5 stale references across the two primary source files called out in the issue. PR #2790 folded /gsd-intel into /gsd-map-codebase --query; these prose surfaces were not updated at that time. Fixes #3258 Co-Authored-By: Claude Sonnet 4.6 * docs: fix additional stale /gsd-intel references found in adversarial sweep (#3258) Sweep found 7 more occurrences in docs/INVENTORY.md (x2), docs/USER-GUIDE.md (x4), docs/FEATURES.md (x2), and agents/gsd-intel-updater.md (x2). All replaced with /gsd-map-codebase --query. The gsd-intel-updater agent name itself (without leading slash) is intentionally preserved. Co-Authored-By: Claude Sonnet 4.6 * changeset: pr=3260 for #3258 Co-Authored-By: Claude Sonnet 4.6 * test: fail loudly on unreadable files in bug-3258 regression scan (CR finding) Replace silent early-return on readFileSync failure with an explicit throw so unreadable files surface as test failures rather than skipped coverage gaps. Co-Authored-By: Claude Sonnet 4.6 --------- Co-authored-by: Claude Sonnet 4.6 --- .changeset/bold-elks-zip.md | 5 + agents/gsd-intel-updater.md | 6 +- docs/FEATURES.md | 4 +- docs/INVENTORY.md | 4 +- docs/USER-GUIDE.md | 8 +- get-shit-done/references/planning-config.md | 4 +- get-shit-done/workflows/settings.md | 6 +- ...258-no-stale-gsd-intel-references.test.cjs | 109 ++++++++++++++++++ 8 files changed, 130 insertions(+), 16 deletions(-) create mode 100644 .changeset/bold-elks-zip.md create mode 100644 tests/bug-3258-no-stale-gsd-intel-references.test.cjs diff --git a/.changeset/bold-elks-zip.md b/.changeset/bold-elks-zip.md new file mode 100644 index 000000000..8cf887fd2 --- /dev/null +++ b/.changeset/bold-elks-zip.md @@ -0,0 +1,5 @@ +--- +type: Fixed +pr: 3260 +--- +**`/gsd-settings` Intel question now points to the correct command** — was telling users to use the retired `/gsd-intel` (folded into `/gsd-map-codebase --query` by #2790). Same correction applied to `references/planning-config.md`, `docs/USER-GUIDE.md`, `docs/FEATURES.md`, `docs/INVENTORY.md`, and `agents/gsd-intel-updater.md`. No backend change. diff --git a/agents/gsd-intel-updater.md b/agents/gsd-intel-updater.md index f238b0988..1a6e321e8 100644 --- a/agents/gsd-intel-updater.md +++ b/agents/gsd-intel-updater.md @@ -44,15 +44,15 @@ Write machine-parseable, evidence-based intelligence. Every claim references act ## Upstream Input -### From `/gsd-intel` Command +### From `/gsd-map-codebase --query` Command -- **Spawned by:** `/gsd-intel` command +- **Spawned by:** `/gsd-map-codebase --query` command - **Receives:** Focus directive -- either `full` (all 5 files) or `partial --files ` (update specific file entries only) - **Input format:** Spawn prompt with `focus: full|partial` directive and project root path ### Config Gate -The /gsd-intel command has already confirmed that intel.enabled is true before spawning this agent. Proceed directly to Step 1. +The /gsd-map-codebase --query command has already confirmed that intel.enabled is true before spawning this agent. Proceed directly to Step 1. ## Project Scope diff --git a/docs/FEATURES.md b/docs/FEATURES.md index e40f667a5..d06f25596 100644 --- a/docs/FEATURES.md +++ b/docs/FEATURES.md @@ -2064,7 +2064,7 @@ Test suite that scans all agent, workflow, and command files for embedded inject ### 90. Queryable Codebase Intelligence -**Command:** `/gsd-intel [query |status|diff|refresh]` +**Command:** `/gsd-map-codebase --query [|status|diff|refresh]` **Config:** `intel.enabled` **Purpose:** Maintain a queryable JSON index of codebase structure, API surface, dependency graph, file roles, and architecture decisions in `.planning/intel/`. Enables targeted lookups without reading the entire codebase. @@ -2614,7 +2614,7 @@ Users who run a memory / knowledge-base MCP server (for example, ExoCortex-style ### 121. Knowledge Graph Integration -**Purpose:** Build, query, and inspect a lightweight knowledge graph of the project in `.planning/graphs/`. Opt-in per project. Exposed as the `/gsd-graphify` user-facing command and the `gsd-tools.cjs graphify …` programmatic verb family. Complements `/gsd-intel` (snapshot-oriented) with a graph-oriented view of nodes and edges across commands, agents, workflows, and phases. +**Purpose:** Build, query, and inspect a lightweight knowledge graph of the project in `.planning/graphs/`. Opt-in per project. Exposed as the `/gsd-graphify` user-facing command and the `gsd-tools.cjs graphify …` programmatic verb family. Complements `/gsd-map-codebase --query` (snapshot-oriented) with a graph-oriented view of nodes and edges across commands, agents, workflows, and phases. **Requirements:** - REQ-GRAPH-01: Opt-in via `graphify.enabled: true` in `.planning/config.json`. When disabled, `/gsd-graphify` prints an activation hint and stops without writing. diff --git a/docs/INVENTORY.md b/docs/INVENTORY.md index e3237fd13..5652d8c1e 100644 --- a/docs/INVENTORY.md +++ b/docs/INVENTORY.md @@ -46,7 +46,7 @@ Full roster at `agents/gsd-*.md`. The "Primary doc" column flags whether [`docs/ | gsd-eval-planner | Designs structured evaluation strategy for an AI phase (AI-SPEC.md §5–§7). | `/gsd-ai-integration-phase` | advanced stub | | gsd-eval-auditor | Retroactive audit of an AI phase's evaluation coverage; produces EVAL-REVIEW.md (COVERED/PARTIAL/MISSING). | `/gsd-eval-review` | advanced stub | | gsd-framework-selector | ≤6-question interactive decision matrix that scores and recommends an AI/LLM framework. | `/gsd-ai-integration-phase`, `/gsd-select-framework` | advanced stub | -| gsd-intel-updater | Writes structured intel files (`.planning/intel/*.json`) used as a queryable codebase knowledge base. | `/gsd-intel` | advanced stub | +| gsd-intel-updater | Writes structured intel files (`.planning/intel/*.json`) used as a queryable codebase knowledge base. | `/gsd-map-codebase --query` | advanced stub | | gsd-doc-classifier | Classifies a single planning document as ADR, PRD, SPEC, DOC, or UNKNOWN; spawned in parallel to process the doc corpus. | `/gsd-ingest-docs` | advanced stub | | gsd-doc-synthesizer | Synthesizes classified planning docs into a single consolidated context with precedence rules, cycle detection, and three-bucket conflicts report. | `/gsd-ingest-docs` | advanced stub | @@ -382,7 +382,7 @@ Full listing: `get-shit-done/bin/lib/*.cjs`. | `init-command-router.cjs` | Thin CJS subcommand router adapter for `gsd-tools init` | | `init.cjs` | Compound context loading for each workflow type | | `install-profiles.cjs` | Install profile allowlist + skill staging for `--minimal` install (#2762); single source of truth for which `gsd-*` skills/agents land in runtime config dirs | -| `intel.cjs` | Codebase intel store backing `/gsd-intel` and `gsd-intel-updater` | +| `intel.cjs` | Codebase intel store backing `/gsd-map-codebase --query` and `gsd-intel-updater` | | `learnings.cjs` | Cross-phase learnings extraction for `/gsd-extract-learnings` | | `milestone.cjs` | Milestone archival, requirements marking | | `model-profiles.cjs` | Model profile resolution table (authoritative profile data) | diff --git a/docs/USER-GUIDE.md b/docs/USER-GUIDE.md index 0bd0f58fb..c2632ef03 100644 --- a/docs/USER-GUIDE.md +++ b/docs/USER-GUIDE.md @@ -821,10 +821,10 @@ For queryable codebase insights without reading the entire codebase, enable the Then build the index: ```bash -/gsd-intel refresh # Analyze codebase and write .planning/intel/ files -/gsd-intel query auth # Search for a term across all intel files -/gsd-intel status # Check freshness of intel files -/gsd-intel diff # See what changed since last snapshot +/gsd-map-codebase --query refresh # Analyze codebase and write .planning/intel/ files +/gsd-map-codebase --query auth # Search for a term across all intel files +/gsd-map-codebase --query status # Check freshness of intel files +/gsd-map-codebase --query diff # See what changed since last snapshot ``` Intel files cover stack, API surface, dependency graph, file roles, and architecture decisions. diff --git a/get-shit-done/references/planning-config.md b/get-shit-done/references/planning-config.md index b4e5cca89..574d58e40 100644 --- a/get-shit-done/references/planning-config.md +++ b/get-shit-done/references/planning-config.md @@ -319,11 +319,11 @@ Set via `learnings.*` namespace (e.g., `"learnings": { "max_inject": 5 }`). Used ### Intel Fields -Set via `intel.*` namespace (e.g., `"intel": { "enabled": true }`). Controls the queryable codebase intelligence system consumed by `/gsd-intel`. +Set via `intel.*` namespace (e.g., `"intel": { "enabled": true }`). Controls the queryable codebase intelligence system consumed by `/gsd-map-codebase --query`. | Key | Type | Default | Allowed Values | Description | |-----|------|---------|----------------|-------------| -| `intel.enabled` | boolean | `false` | `true`, `false` | Enable queryable codebase intelligence system. When `true`, `/gsd-intel` commands build and query a JSON index in `.planning/intel/`. | +| `intel.enabled` | boolean | `false` | `true`, `false` | Enable queryable codebase intelligence system. When `true`, `/gsd-map-codebase --query` builds and queries a JSON index in `.planning/intel/`. | ### Manager Fields diff --git a/get-shit-done/workflows/settings.md b/get-shit-done/workflows/settings.md index aea40ceb1..0b8307236 100644 --- a/get-shit-done/workflows/settings.md +++ b/get-shit-done/workflows/settings.md @@ -49,7 +49,7 @@ Parse current values (default to `true` if not present): - `workflow.code_review_depth` — default depth for /gsd-code-review: `quick`, `standard`, or `deep` (default: `"standard"` if absent; only relevant when `code_review` is on) - `workflow.ui_review` — run visual quality audit (/gsd-ui-review) in autonomous mode (default: true if absent) - `commit_docs` — whether `.planning/` files are committed to git (default: true if absent) -- `intel.enabled` — enable queryable codebase intelligence (/gsd-intel) (default: false if absent) +- `intel.enabled` — enable queryable codebase intelligence (/gsd-map-codebase --query) (default: false if absent) - `graphify.enabled` — enable project knowledge graph (/gsd-graphify) (default: false if absent) - `model_profile` — which model each agent uses (default: `balanced`) - `git.branching_strategy` — branching approach (default: `"none"`) @@ -292,12 +292,12 @@ AskUserQuestion([ ] }, { - question: "Enable Intel? (queryable codebase intelligence via /gsd-intel — builds a JSON index in .planning/intel/)", + question: "Enable Intel? (queryable codebase intelligence via /gsd-map-codebase --query — builds a JSON index in .planning/intel/)", header: "Intel", multiSelect: false, options: [ { label: "No (Recommended)", description: "Skip intel indexing. Use when codebase is small or intel queries are not needed." }, - { label: "Yes", description: "Enable /gsd-intel commands. Builds and queries a JSON index of the codebase." } + { label: "Yes", description: "Enable /gsd-map-codebase --query commands. Builds and queries a JSON index of the codebase." } ] }, { diff --git a/tests/bug-3258-no-stale-gsd-intel-references.test.cjs b/tests/bug-3258-no-stale-gsd-intel-references.test.cjs new file mode 100644 index 000000000..967f82d70 --- /dev/null +++ b/tests/bug-3258-no-stale-gsd-intel-references.test.cjs @@ -0,0 +1,109 @@ +// allow-test-rule: source-text-is-the-product — workflow, reference, and docs .md files +// ARE what the runtime loads and what users read; asserting their text content +// tests the deployed skill surface contract, not implementation internals. + +'use strict'; + +// Regression tests for bug #3258. +// +// PR #2790 folded `/gsd-intel` into `/gsd-map-codebase --query`. After that +// consolidation, five prose occurrences in two source files continued to +// reference the retired `/gsd-intel` slash command. Users invoking the wizard +// were directed to a command that no longer exists. +// +// Fix: replace each `/gsd-intel` (the retired user-facing slash command) with +// `/gsd-map-codebase --query` in: +// - get-shit-done/references/planning-config.md +// - get-shit-done/workflows/settings.md +// - docs/INVENTORY.md +// - docs/USER-GUIDE.md +// - docs/FEATURES.md +// +// Allowed: `gsd-intel-updater` (still-valid agent name, no leading slash), +// `intel.cjs` / `intel.enabled` / `intel.*` (internal backend, not user command), +// CHANGELOG.md (historical record), test files themselves. +// +// This test distinguishes `/gsd-intel` (the retired slash command, leading slash) +// from `gsd-intel-updater` (still-valid agent) by grepping for the literal +// string `/gsd-intel` and then asserting no match survives after excluding +// the `-updater` suffix. + +const { describe, test } = require('node:test'); +const assert = require('node:assert/strict'); +const fs = require('node:fs'); +const path = require('node:path'); + +const ROOT = path.join(__dirname, '..'); + +/** Walk a directory recursively and return absolute paths of all .md files. */ +function walkMd(dir) { + const results = []; + if (!fs.existsSync(dir)) return results; + for (const entry of fs.readdirSync(dir, { withFileTypes: true })) { + const abs = path.join(dir, entry.name); + if (entry.isDirectory()) { + results.push(...walkMd(abs)); + } else if (entry.isFile() && entry.name.endsWith('.md')) { + results.push(abs); + } + } + return results; +} + +/** + * Return all lines in `src` that contain `/gsd-intel` (the retired slash + * command) but are NOT the agent name `gsd-intel-updater`. + * We match the literal substring `/gsd-intel` (with leading slash) and then + * exclude any line where the match is immediately followed by `-updater`. + */ +function staleLinesIn(src) { + return src.split('\n').filter((line) => { + if (!line.includes('/gsd-intel')) return false; + // Remove all occurrences of the valid agent name; if nothing remains, skip. + const stripped = line.replace(/\/gsd-intel-updater/g, ''); + return stripped.includes('/gsd-intel'); + }); +} + +const SOURCE_DIRS = [ + path.join(ROOT, 'commands', 'gsd'), + path.join(ROOT, 'get-shit-done', 'workflows'), + path.join(ROOT, 'get-shit-done', 'references'), + path.join(ROOT, 'agents'), + path.join(ROOT, 'docs'), +]; + +describe('#3258: no stale /gsd-intel slash-command references in product source dirs', () => { + for (const dir of SOURCE_DIRS) { + const files = walkMd(dir); + for (const file of files) { + const rel = path.relative(ROOT, file); + + // Allowed exclusions: + // - CHANGELOG.md is a historical record; /gsd-intel appears in release notes + // - test files (under tests/) are excluded automatically by SOURCE_DIRS scope + if (rel === 'CHANGELOG.md') continue; + + test(`${rel} has no stale /gsd-intel references`, () => { + let src; + try { + src = fs.readFileSync(file, 'utf8'); + } catch (err) { + throw new Error(`failed reading ${rel}: ${err.message}`); + } + + const staleLines = staleLinesIn(src); + assert.strictEqual( + staleLines.length, + 0, + [ + `${rel} contains ${staleLines.length} stale /gsd-intel reference(s).`, + 'Replace with /gsd-map-codebase --query (retired by PR #2790).', + 'Stale lines:', + ...staleLines.map((l) => ` ${l.trim()}`), + ].join('\n'), + ); + }); + } + } +});