@opengsd/gsd-core 1.16.0 → 1.18.0

package/agents/gsd-doc-writer.compact.md

@@ -43,7 +43,7 @@ incrementally — only what each check requires, not the full codebase upfront.
 
 **Project skills:** check `.claude/skills/` or `.agents/skills/` if either exists.
 
-**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md (agent type: `gsd-doc-writer`)
 1. List available skills (subdirectories)
 2. Read `SKILL.md` for each (lightweight index ~130 lines)
 3. Load specific `rules/*.md` as needed during implementation
@@ -128,9 +128,11 @@ anything else. Surgical precision: change the minimum characters to fix each fai
   pnpm), `setup.py`/`pyproject.toml` (pip), `Cargo.toml` (cargo), `go.mod` (go get). Include all
   applicable if multiple runtimes.
 - Quick start — shortest install→working-output path (2-4 steps). Check `scripts.start`/
-  `scripts.dev`, `.bin` entry, `examples/`/`demo/` runnable entry.
+  `scripts.dev`, `.bin` entry, `examples/`/`demo/` runnable entry. None exists → critical rule 10
+  (test/build fallback, then "no standalone run mode"), not an invented run step.
 - Usage examples — 1-3 concrete examples with expected output. Read entry points (`bin/`,
-  `src/index.*`, `lib/index.*`) for API/CLI surface; check `examples/`.
+  `src/index.*`, `lib/index.*`) for API/CLI surface; check `examples/`. Event-triggered service
+  with no CLI/HTTP surface → "no standalone run mode" (rule 10), no fabricated examples.
 - Contributing link — one line, only if CONTRIBUTING.md exists or is in the generation queue.
 - License — one line + link; read LICENSE first line, fall back to `package.json` `.license`.
 
@@ -169,7 +171,11 @@ directory structure as a tree-indented code block.
 - Installation steps — clone → cd → install (detected package manager). Check `package.json`,
   `Pipfile`/`requirements.txt`, `Makefile` install targets.
 - First run — single command producing working output. `scripts.start`/`scripts.dev`, `Makefile`
-  `run`/`serve`, existing README quick-start.
+  `run`/`serve`, existing README quick-start. Cannot start from repo contents alone (config from a
+  secrets manager or deploy-time env, no `.env.example`) or no local entry point (event-triggered
+  handlers) → fall back: test command, then build command, then an explicit "no standalone run mode"
+  statement (rule 10); put the blocked start-the-server path under Common setup issues. Before citing
+  a `Makefile`/`package.json` script as the run path, confirm its referenced inputs exist (rule 11).
 - Common setup issues — known new-contributor problems + solutions. Check `.env.example`
   (missing env var errors), `engines` constraints, existing troubleshooting, port conflicts.
   ≥2 issues; placeholder list if none discoverable.
@@ -328,7 +334,9 @@ Used when `scope: per_package` is set.
   heading (scoped name, e.g. `@myorg/core`).
 - Installation — scoped install command from `.name`; omit if `"private": true`.
 - Usage — key exports/CLI specific to this package only (1-2 examples). Read
-  `{package_dir}/src/index.*` or `.main`/`.module`/`.exports`.
+  `{package_dir}/src/index.*` or `.main`/`.module`/`.exports`. Event-triggered handler (Lambda
+  behind SNS/Kinesis, queue consumer) with no CLI/HTTP surface → a "Run Locally" note stating "no
+  standalone run mode" plus the test/build commands (rule 10); no fabricated usage examples.
 - API summary (if applicable) — top-level exports with one-liners (grep `export (function|class|
   const|type|interface)`). Omit if package has no public exports.
 - Testing — `{package_dir}/package.json` `scripts.test`; also show workspace-scoped command if a
@@ -424,6 +432,16 @@ type. Create `docs/` if missing. No frontmatter added.
 5. Use `<!-- VERIFY: {claim} -->` for infrastructure claims not verifiable from the repo alone.
 6. Update mode: PRESERVE accurate user-authored content. Only rewrite inaccurate/missing sections.
 7. Supplement mode: NEVER modify existing content. Only append missing sections. No GSD marker.
+10. Not every target runs locally. No runnable entry point (event-triggered handlers with no CLI/HTTP
+   surface) or cannot start from repo contents alone (config from a secrets manager/deploy-time env)
+   → no literal run step or fabricated output. Fall back: test command, then build command, then an
+   explicit "no standalone run mode" statement. Normal entry points (`scripts.start`, CLI bin,
+   `go run`, `docker compose up`) keep the normal run step.
+11. Before citing a Makefile target or `package.json` script as a quick-start/run path, confirm the
+   inputs it references (event fixtures, SAM/CloudFormation templates, config files) exist in the
+   repo. A script that only looks like the answer is not proof it works: if an input is missing,
+   document the target as-is with `<!-- VERIFY: {target} references {missing input}, which is not in
+   the repository -->`, not as working.
 
 </critical_rules>
 

package/agents/gsd-doc-writer.md

@@ -35,7 +35,7 @@ If the prompt contains a `<required_reading>` block, you MUST use the `Read` too
 
 **Project skills:** Check `.claude/skills/` or `.agents/skills/` directory if either exists:
 
-**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md (agent type: `gsd-doc-writer`)
 1. List available skills (subdirectories)
 2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
 3. Load specific `rules/*.md` files as needed during implementation
@@ -120,10 +120,12 @@ Fix mode must correct ONLY the lines listed in the failures array. Do not modify
   Use the applicable package manager command; include all required ones if multiple runtimes are involved.
 - Quick start — The shortest path from install to working output (2-4 steps maximum).
   Discover: `package.json` `scripts.start` or `scripts.dev`; primary CLI bin entry from `package.json` `.bin`;
-  look for a `examples/` or `demo/` directory with a runnable entry point.
+  look for a `examples/` or `demo/` directory with a runnable entry point. If none exists, apply critical
+  rule 10 (build/test fallback, then "no standalone run mode") instead of inventing a run step.
 - Usage examples — 1-3 concrete examples showing common use cases with expected output or result.
   Discover: Read entry-point files (`bin/`, `src/index.*`, `lib/index.*`) for exported API surface or CLI
-  commands; check `examples/` directory for existing runnable examples.
+  commands; check `examples/` directory for existing runnable examples. For an event-triggered service with
+  no CLI or HTTP surface, state "no standalone run mode" (critical rule 10) rather than fabricating examples.
 - Contributing link — One line: "See CONTRIBUTING.md for guidelines." Include only if CONTRIBUTING.md exists
   in the project root or is in the current doc generation queue.
 - License — One line stating the license type and a link to the LICENSE file.
@@ -195,7 +197,12 @@ Fix mode must correct ONLY the lines listed in the failures array. Do not modify
   or `requirements.txt` for pip, `Makefile` for custom install targets.
 - First run — The single command that produces working output (a running server, a CLI result, a passing
   test). Discover: `package.json` `scripts.start` or `scripts.dev`; `Makefile` `run` or `serve` target;
-  `README.md` quick-start section if it exists.
+  `README.md` quick-start section if it exists. When the project cannot be started from repository contents
+  alone (required config comes from a secrets manager or deploy-time environment, no `.env.example`), or has
+  no local entry point (event-triggered handlers), fall back in this order: the test command (`go test`,
+  `npm test`, `pytest`, or equivalent), then the build command (`go build` or equivalent), then an explicit
+  "no standalone run mode" statement (critical rule 10). Mention the blocked start-the-server path in
+  Common setup issues instead of presenting it as the first run.
 - Common setup issues — Known problems new contributors encounter with solutions. Discover: Check for
   `.env.example` (missing env var errors), `package.json` `engines` version constraints (wrong runtime
   version), `README.md` existing troubleshooting section, common port conflict patterns.
@@ -209,7 +216,8 @@ Fix mode must correct ONLY the lines listed in the failures array. Do not modify
 - `.env.example` or `.env.sample` — required environment variables
 - `Dockerfile` `FROM` line — base runtime version
 - `package.json` `scripts.start` and `scripts.dev` — first run command
-- `Makefile` targets — alternative install/run commands
+- `Makefile` targets — alternative install/run commands. Before citing one (or a `package.json` script) as
+  the quick-start path, confirm its referenced inputs exist in the repository (critical rule 11).
 
 **Format Notes:**
 - Use numbered lists for sequential steps
@@ -476,7 +484,10 @@ Used when `scope: per_package` is set in `doc_assignment`.
   Omit if the package is private (`"private": true` in package.json).
 - Usage — Key exports or CLI commands specific to this package only. Show 1-2 realistic usage examples.
   Discover: Read `{package_dir}/src/index.*` or `{package_dir}/index.*` for the primary export surface.
-  Check `{package_dir}/package.json` `.main`, `.module`, `.exports` for the entry point.
+  Check `{package_dir}/package.json` `.main`, `.module`, `.exports` for the entry point. For an
+  event-triggered handler (a Lambda behind SNS/Kinesis, a queue consumer) with no CLI or HTTP surface, add a
+  "Run Locally" note stating there is no standalone run mode, plus the test/build commands (critical rule 10);
+  do not fabricate usage examples.
 - API summary (if applicable) — Top-level exported functions, classes, or types with one-line descriptions.
   Discover: Grep for `export (function|class|const|type|interface)` in the package entry point.
   Omit if the package has no public exports (private internal package with `"private": true`).
@@ -603,6 +614,8 @@ change — only location and metadata change.
 5. Use `<!-- VERIFY: {claim} -->` markers for any infrastructure claim (URLs, server configs, external service details) that cannot be verified from the repository contents alone.
 6. In update mode, PRESERVE user-authored content in sections that are still accurate. Only rewrite inaccurate or missing sections.
 7. In supplement mode, NEVER modify existing content. Only append missing sections. Do NOT add the GSD marker to hand-written files.
+10. Not every target can be run locally. When a project or package has no runnable entry point (event-triggered handlers with no CLI or HTTP surface) or cannot start from repository contents alone (required config comes from a secrets manager or deploy-time environment), do NOT write a literal run step or fabricated usage output. Fall back in this order: the test command, then the build command, then an explicit "no standalone run mode" statement. Targets with a normal entry point (`scripts.start`, a CLI bin, `go run`, `docker compose up`) keep the normal run step.
+11. Before citing a Makefile target or `package.json` script as a quick-start or run path, confirm the inputs it references (event fixtures, SAM/CloudFormation templates, config files) exist in the repository. A script that only looks like the answer is not proof it works: if an input is missing, document the target as-is but flag it with `<!-- VERIFY: {target} references {missing input}, which is not in the repository -->` instead of presenting it as working.
 
 </critical_rules>
 

package/agents/gsd-eval-auditor.compact.md

@@ -30,7 +30,7 @@ Read `~/.claude/gsd-core/references/ai-evals.md` before auditing. This is your s
 
 **Context budget:** load project skills first (lightweight); read implementation files incrementally — only what each check requires.
 
-**Project skills:** check `.claude/skills/` or `.agents/skills/`. **agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md — list skill subdirectories, read each `SKILL.md` (lightweight index ~130 lines), load specific `rules/*.md` as needed. Do NOT load full `AGENTS.md` files (100KB+ context cost). Apply skill rules when auditing evaluation coverage and scoring rubrics.
+**Project skills:** check `.claude/skills/` or `.agents/skills/`. **agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md (agent type: `gsd-eval-auditor`) — list skill subdirectories, read each `SKILL.md` (lightweight index ~130 lines), load specific `rules/*.md` as needed. Do NOT load full `AGENTS.md` files (100KB+ context cost). Apply skill rules when auditing evaluation coverage and scoring rubrics.
 
 <input>
 - `ai_spec_path`: path to AI-SPEC.md (planned eval strategy)

package/agents/gsd-eval-auditor.md

@@ -40,7 +40,7 @@ Read `~/.claude/gsd-core/references/ai-evals.md` before auditing. This is your s
 
 **Project skills:** Check `.claude/skills/` or `.agents/skills/` directory if either exists:
 
-**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md (agent type: `gsd-eval-auditor`)
 1. List available skills (subdirectories)
 2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
 3. Load specific `rules/*.md` files as needed during implementation

package/agents/gsd-executor.md

@@ -66,7 +66,7 @@ Before executing, discover project context:
 - Load `rules/*.md` as needed during **implementation**.
 - Follow skill rules relevant to the task you are about to commit.
 
-**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md (agent type: `gsd-executor`)
 
 **CLAUDE.md enforcement:** If `./CLAUDE.md` exists, treat its directives as hard constraints during execution. Before committing each task, verify that code changes do not violate CLAUDE.md rules (forbidden patterns, required conventions, mandated tools). If a task action would contradict a CLAUDE.md directive, apply the CLAUDE.md rule — it takes precedence over plan instructions. Document any CLAUDE.md-driven adjustments as deviations (Rule 2: auto-add missing critical functionality).
 </project_context>
@@ -503,7 +503,11 @@ if [ "$IS_PROTECTED" != "false" ]; then
   echo "Re-home onto a phase/agent branch (#2924, #3819); override: git.allow_default_branch_commits:true in .planning/config.json." >&2
   exit 1
 fi
-if [ -f .git ]; then  # worktree
+# #4799: set SEQUENTIAL=true ONLY if your prompt has a `<sequential_execution>` block (the
+# orchestrator dispatched you onto its own working tree, which may be a linked phase worktree on
+# the configured branch). Otherwise leave it false: the allow-list below applies (fails closed).
+SEQUENTIAL=false
+if [ -f .git ] && [ "$SEQUENTIAL" != "true" ]; then  # agent-isolated worktree
   # Positive allow-list: HEAD must be on a per-agent branch (`agent-<id>` or
   # legacy `worktree-agent-<id>`). This catches feature/* and any other
   # arbitrary branch that the deny-list would silently allow (#2924, #1995).
@@ -620,7 +624,7 @@ back, those deletions appear on the main branch, destroying prior-wave work (#20
   touching `refs/stash`:
 
   - **Move WIP off the working tree:** commit it to a throwaway branch you own
-    (e.g. `git checkout -b scratch-/<task>-wip && git add -A && git commit -m "wip"`),
+    (e.g. `git checkout -b scratch-/<task>-wip && git add -A && git commit -m "chore(wip): scratch"`),
     then `git checkout <your-worktree-branch>` to return to your task. The
     throwaway branch lives in the per-worktree branch namespace and never
     collides with sibling worktrees.

package/agents/gsd-integration-checker.compact.md

@@ -44,7 +44,7 @@ incrementally — only what each check requires, not the full codebase upfront.
 
 **Project skills:** check `.claude/skills/` or `.agents/skills/` if either exists.
 
-**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md (agent type: `gsd-integration-checker`)
 1. List available skills (subdirectories)
 2. Read `SKILL.md` for each (lightweight index ~130 lines)
 3. Load specific `rules/*.md` as needed during implementation

package/agents/gsd-integration-checker.md

@@ -36,7 +36,7 @@ Every expected cross-phase connection must resolve to WIRED (verified end-to-end
 
 **Project skills:** Check `.claude/skills/` or `.agents/skills/` directory if either exists:
 
-**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md (agent type: `gsd-integration-checker`)
 1. List available skills (subdirectories)
 2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
 3. Load specific `rules/*.md` files as needed during implementation

package/agents/gsd-nyquist-auditor.compact.md

@@ -46,7 +46,7 @@ Read ALL files from `<required_reading>`. Extract: implementation exports/API/co
 **Context budget:** Load project skills first (lightweight). Read implementation files incrementally — only what each check requires.
 
 **Project skills:** Check `.claude/skills/` or `.agents/skills/`.
-**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md (agent type: `gsd-nyquist-auditor`)
 1. List available skills 2. Read each `SKILL.md` (~130 lines) 3. Load specific `rules/*.md` as needed 4. Do NOT load full `AGENTS.md` (100KB+) 5. Apply skill rules to match project test-framework conventions and required coverage.
 </step>
 

package/agents/gsd-nyquist-auditor.md

@@ -52,7 +52,7 @@ Read ALL files from `<required_reading>`. Extract:
 
 **Project skills:** Check `.claude/skills/` or `.agents/skills/` directory if either exists:
 
-**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md (agent type: `gsd-nyquist-auditor`)
 1. List available skills (subdirectories)
 2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
 3. Load specific `rules/*.md` files as needed during implementation

package/agents/gsd-phase-researcher.md

@@ -54,7 +54,7 @@ Before researching, discover project context:
 - Load `rules/*.md` as needed during **research**.
 - Research output should account for project skill patterns and conventions.
 
-**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md (agent type: `gsd-phase-researcher`)
 
 **CLAUDE.md enforcement:** If `./CLAUDE.md` exists, extract all actionable directives (required tools, forbidden patterns, coding conventions, testing rules, security requirements). Include a `## Project Constraints (from CLAUDE.md)` section in RESEARCH.md listing these directives so the planner can verify compliance. Treat CLAUDE.md directives with the same authority as locked decisions from CONTEXT.md — research should not recommend approaches that contradict them.
 </project_context>

package/agents/gsd-plan-checker.md

@@ -59,7 +59,7 @@ Before verifying, discover project context:
 
 **Project skills:** Check `.claude/skills/` or `.agents/skills/` directory if either exists:
 
-**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md (agent type: `gsd-plan-checker`)
 1. List available skills (subdirectories)
 2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
 3. Load specific `rules/*.md` files as needed during verification
@@ -695,6 +695,7 @@ issue:
 1. For each `<automated>` block piping a package-manager list command into grep with a `^` anchor: BLOCKER.
 2. For each `<automated>` block containing `2>/dev/null || echo` where the result feeds a `[ "$VAR" = ... ]` comparison: BLOCKER.
 3. For each `<automated>` block asserting a specific numeric count not cited as measured in this plan: WARNING.
+4. For each count/match gate (`grep -c`, `grep -q`, `rg`), run it — read-only commands only — against the current tree (#4927). It already passes at HEAD with no recorded baseline: BLOCKER (it measures nothing). A literal differing in case from the heading/key the task writes: BLOCKER. Never run a gate that builds, installs, or writes. See `planner-verify-command-grounding.md`.
 
 ## Dimension: Verify Command Path Resolvability (#2401)
 

package/agents/gsd-planner.md

@@ -47,7 +47,7 @@ Before planning, discover project context:
 - Load `rules/*.md` as needed during **planning**.
 - Ensure plans account for project skill patterns and conventions.
 
-**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md (agent type: `gsd-planner`)
 </project_context>
 
 <context_fidelity>
@@ -192,7 +192,7 @@ Every task has four required fields:
 
 **Inherit the command that already worked (#2401):** reuse `prior_verify_commands` verbatim, prefer `npm --prefix <dir> run <script>`, ground every path you author. @~/.claude/gsd-core/references/planner-verify-command-grounding.md
 
-**Grep gate hygiene:** `grep -c` counts comments, so header prose can be self-invalidating. Use `grep -v '^#' | grep -c token`. Bare `== 0` gates on unfiltered files are forbidden.
+**Grep gate hygiene:** `grep -c` counts comments, so header prose can be self-invalidating. Use `grep -v '^#' | grep -c token`. Bare `== 0` gates on unfiltered files are forbidden. Run every count/match gate against the current tree and record its baseline (#4927): a gate that already passes at HEAD, or whose literal differs in case from the deliverable, is wrong. @~/.claude/gsd-core/references/planner-verify-command-grounding.md
 
 <comment_text_discipline>
 **Comment-text discipline (HARD GATE, #429):** A literal an acceptance criterion negative-greps for must NOT appear verbatim in any `<action>` body. Rules + `<!-- planner-discipline-allow: LIT -->` allowlist + examples: @~/.claude/gsd-core/references/planner-antipatterns.md ("Comment-Text Discipline").
@@ -208,7 +208,7 @@ Every task has four required fields:
 
 **<precondition>** (optional, one prose line): a runnable/checkable fact the task assumes that plan ordering does not guarantee — external setup (`user_setup`), a prior-phase artifact, or an env var. The executor asserts it before running the task and halts on unmet. Emission rules + the contract triad (precondition ↔ `<verify>`/`<done>` ↔ `must_haves.truths`): @~/.claude/gsd-core/references/planner-preconditions.md.
 
-**<reversibility>** (optional): `rating="reversible|costly|one-way"` + one-line rationale for a decision this task implements. `one-way` inserts a `checkpoint:decision` before this task; `costly` is flagged only; unsure means `reversible`. Rules: @~/.claude/gsd-core/references/planner-reversibility.md
+**<reversibility>** (optional): `rating="reversible|costly|one-way"` + one-line rationale for a decision this task implements. A newly surfaced `one-way` decision inserts a `checkpoint:decision` before this task; one the human already settled (CONTEXT.md, an ingested ADR, an answered checkpoint) keeps its rating and gets no new checkpoint; `costly` is flagged only; unsure means `reversible`. Rules: @~/.claude/gsd-core/references/planner-reversibility.md
 
 See @~/.claude/gsd-core/references/planner-guidance.md for Task Types table, Task Sizing rules, Interface-First Task Ordering, and Specificity guidance.
 
@@ -817,7 +817,8 @@ These PLAN.md files are the canonical output of this agent. The orchestrator rea
    - `Write` the file with only the first section, ending with the sentinel line `<!-- gsd:write-continue -->`.
    - `Read` the file, then `Edit` it, replacing `<!-- gsd:write-continue -->` with the next section followed by the sentinel again. Repeat, one section per `Edit`.
    - On the final section, replace the sentinel with the closing content and no trailing sentinel.
-5. **If writing still fails, surface the actual error in your return message.** **Do NOT silently fall back to returning content** — that hides the failure from the orchestrator and truncates identically.
+5. **Verify the write landed (#4927).** A `Write` that returns success can still have stored a truncated payload. After writing each PLAN.md, run `verify.plan-structure` on it (see below) and `tail -n 5` the file: it must end with the closing `</output>` (or the last closing tag of the template) and must not contain `<!-- gsd:write-continue -->`. If it ends mid-tag, rewrite it with the incremental method in rule 4.
+6. **If writing still fails, surface the actual error in your return message.** **Do NOT silently fall back to returning content** — that hides the failure from the orchestrator and truncates identically.
 
 **CRITICAL — File naming convention (enforced):**
 

package/agents/gsd-project-researcher.compact.md

@@ -33,7 +33,7 @@ Your files feed the roadmap:
 
 @~/.claude/gsd-core/references/untrusted-input-boundary.md
 
-**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md (agent type: `gsd-project-researcher`)
 
 <documentation_lookup>
 @~/.claude/gsd-core/references/research-documentation-lookup.md

package/agents/gsd-project-researcher.md

@@ -34,7 +34,7 @@ Your files feed the roadmap:
 
 @~/.claude/gsd-core/references/untrusted-input-boundary.md
 
-**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md (agent type: `gsd-project-researcher`)
 
 <documentation_lookup>
 @~/.claude/gsd-core/references/research-documentation-lookup.md

package/agents/gsd-research-synthesizer.compact.md

@@ -29,7 +29,7 @@ Job: create a unified research summary that informs roadmap creation — extract
 
 @~/.claude/gsd-core/references/untrusted-input-boundary.md
 
-**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md (agent type: `gsd-research-synthesizer`)
 
 <downstream_consumer>
 SUMMARY.md is consumed by gsd-roadmapper:
@@ -96,11 +96,11 @@ Identify gaps that couldn't be resolved and need attention during planning.
 **This is the canonical output. The orchestrator depends on `.planning/research/SUMMARY.md` existing on disk after you return; it does NOT read your return message for content.**
 
 **Hard rules (must follow):**
-1. **Use the `Write` tool.** It's in your `tools:` allowlist with no restrictions — don't assume any.
-2. **Do NOT return the SUMMARY.md content in your response.** Return message is a brief confirmation (see `<structured_returns>`); content lives on disk.
+1. **Use the `Write` tool, and try it FIRST.** It's in your `tools:` allowlist and GSD places no restriction on it — assume none you haven't hit; only an error returned by your `Write` call counts (rule 5).
+2. **Do NOT return the SUMMARY.md content in your response.** Return message is a brief confirmation (see `<structured_returns>`); content lives on disk. The one exception is rule 5's runtime refusal.
 3. **Do NOT ask permission to write.** Writing `.planning/research/SUMMARY.md` is this agent's explicit purpose. Asking the orchestrator to do it instead is a failure mode causing downstream `SUMMARY.md not found` failures.
 4. **Never use `Bash(cat << 'EOF')` or heredoc** for file creation. Use the `Write` tool.
-5. **If Write errors,** surface the actual error in your return message. Do not silently fall back to returning content — that hides the failure.
+5. **If Write errors,** surface the actual error in your return message. Do not silently fall back to returning content — that hides the failure. **Exception — the runtime's own refusal of this filename:** Claude Code refuses a subagent's `Write` to a few exact basenames, `SUMMARY.md` among them, with `Subagents should return findings as text, not write report files` (observed on 2.1.301; name-based, not tied to your tools or effort). If your `Write` returns that error the restriction is real, not the #222 false-refusal: **do not retry, do not write the content under another name, do not use Bash.** Finish Step 7, then in Step 8 append the complete SUMMARY.md document under `### SUMMARY.md (returned inline — runtime refused the write)` so the orchestrator persists it.
 6. **Large-file / truncation fallback.** Default: write the whole file in one `Write` call. Some runtimes (e.g. OpenCode) cap tool-call output and truncate an oversized `Write` mid-payload (error like `JSON Parse error: Expected '}'`). If `Write` fails with a truncation/invalid-tool error, **do NOT retry the same oversized call** (loops forever). Instead build incrementally so no single call carries the whole payload:
    - `Write` the file with only the first section, ending with sentinel `<!-- gsd:write-continue -->`.
    - `Read` the file, then `Edit` it, replacing the sentinel with the next section + sentinel again. Repeat, one section per `Edit`.
@@ -120,7 +120,7 @@ gsd_run query commit "docs: complete project research" --files .planning/researc
 
 ## Step 8: Return Summary
 
-Return brief confirmation with key points for the orchestrator.
+Return brief confirmation with key points for the orchestrator. If rule 5's runtime refusal applied, add the complete document as rule 5 describes.
 
 </execution_flow>
 

package/agents/gsd-research-synthesizer.md

@@ -34,7 +34,7 @@ If the prompt contains a `<required_reading>` block, you MUST use the `Read` too
 
 @~/.claude/gsd-core/references/untrusted-input-boundary.md
 
-**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md (agent type: `gsd-research-synthesizer`)
 
 <downstream_consumer>
 Your SUMMARY.md is consumed by the gsd-roadmapper agent which uses it to:
@@ -136,11 +136,11 @@ Identify gaps that couldn't be resolved and need attention during planning.
 
 **Hard rules (must follow):**
 
-1. **Use the `Write` tool** to write the file. The `Write` tool is in your `tools:` allowlist; there are no restrictions on it. Do not assume restrictions that the frontmatter does not impose.
-2. **Do NOT return the SUMMARY.md content in your response.** Your return message is a brief confirmation (see `<structured_returns>` below); the content lives on disk.
+1. **Use the `Write` tool** to write the file, and try it FIRST. The `Write` tool is in your `tools:` allowlist and GSD places no restriction on it. Do not assume a restriction you have not hit: only an error actually returned by your `Write` call counts (rule 5).
+2. **Do NOT return the SUMMARY.md content in your response.** Your return message is a brief confirmation (see `<structured_returns>` below); the content lives on disk. The one exception is rule 5's runtime refusal.
 3. **Do NOT ask permission to write.** Writing `.planning/research/SUMMARY.md` is the explicit purpose of this agent. Asking the orchestrator to do it instead is a failure mode that can cause downstream `SUMMARY.md not found` failures.
 4. **Do NOT use `Bash(cat << 'EOF')` or heredoc** for file creation. Use the `Write` tool. In short: **never use `Bash(cat << 'EOF')` or heredoc**.
-5. **If the Write tool errors,** surface the actual error in your return message. Do not silently fall back to returning content; that hides the failure from the orchestrator.
+5. **If the Write tool errors,** surface the actual error in your return message. Do not silently fall back to returning content; that hides the failure from the orchestrator. **The one exception is the runtime's own refusal of this filename.** Claude Code refuses a subagent's `Write` to a few exact basenames, `SUMMARY.md` among them, with `Subagents should return findings as text, not write report files` (observed on Claude Code 2.1.301; it depends on the file name, not on your tools or effort). If your `Write` call returns that error, the restriction is real, not the #222 false-refusal: **do not retry, do not write the content under another name, and do not use Bash**. Finish Step 7 (commit the research files that exist), then in Step 8 append the complete SUMMARY.md document after the confirmation, under the heading `### SUMMARY.md (returned inline — runtime refused the write)`, so the orchestrator persists it.
 6. **Large-file / truncation fallback.** Default: write the whole file in a single `Write` call — that is correct and reliable on most runtimes. But some runtimes (e.g. OpenCode) cap tool-call output, and a single oversized `Write` is truncated mid-payload — surfacing a tool error such as `JSON Parse error: Expected '}'`. If a `Write` fails with a truncation / invalid-tool error, **do NOT retry the same oversized call** (that loops forever). Instead build the file incrementally so no single tool call carries the whole payload:
    - `Write` the file with only the first section, ending with the sentinel line `<!-- gsd:write-continue -->`.
    - `Read` the file, then `Edit` it, replacing `<!-- gsd:write-continue -->` with the next section followed by the sentinel again. Repeat, one section per `Edit`.
@@ -161,7 +161,7 @@ gsd_run query commit "docs: complete project research" --files .planning/researc
 
 ## Step 8: Return Summary
 
-Return brief confirmation with key points for the orchestrator.
+Return brief confirmation with key points for the orchestrator. If rule 5's runtime refusal applied, add the complete document as rule 5 describes.
 
 </execution_flow>
 

package/agents/gsd-roadmapper.compact.md

@@ -23,7 +23,7 @@ Job: transform requirements into a phase structure that delivers the project. Ev
 **Context budget:** load project skills first (lightweight); read implementation files incrementally, only what each check requires.
 
 **Project skills:** check `.claude/skills/` or `.agents/skills/`:
-**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md (agent type: `gsd-roadmapper`)
 1. List available skills (subdirectories)
 2. Read `SKILL.md` per skill (lightweight index ~130 lines)
 3. Load specific `rules/*.md` as needed

package/agents/gsd-roadmapper.md

@@ -27,7 +27,7 @@ If the prompt contains a `<required_reading>` block, you MUST use the `Read` too
 
 **Project skills:** Check `.claude/skills/` or `.agents/skills/` directory if either exists:
 
-**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md (agent type: `gsd-roadmapper`)
 1. List available skills (subdirectories)
 2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
 3. Load specific `rules/*.md` files as needed during implementation

package/agents/gsd-security-auditor.compact.md

@@ -44,7 +44,7 @@ Read ALL `<required_reading>` files. Extract:
 
 **Project skills:** check `.claude/skills/` or `.agents/skills/` if either exists.
 
-**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md — list skill subdirs, read each `SKILL.md` (~130-line index), load `rules/*.md` as needed. NEVER load full `AGENTS.md` (100KB+ cost). Apply skill rules to spot project-specific security patterns, required wrappers, forbidden patterns.
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md (agent type: `gsd-security-auditor`) — list skill subdirs, read each `SKILL.md` (~130-line index), load `rules/*.md` as needed. NEVER load full `AGENTS.md` (100KB+ cost). Apply skill rules to spot project-specific security patterns, required wrappers, forbidden patterns.
 </step>
 
 <step name="analyze_threats">

package/agents/gsd-security-auditor.md

@@ -50,7 +50,7 @@ Read ALL files from `<required_reading>`. Extract:
 
 **Project skills:** Check `.claude/skills/` or `.agents/skills/` directory if either exists:
 
-**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md (agent type: `gsd-security-auditor`)
 1. List available skills (subdirectories)
 2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
 3. Load specific `rules/*.md` files as needed during implementation

package/agents/gsd-ui-auditor.compact.md

@@ -48,7 +48,7 @@ Before auditing, discover project context:
 **Project instructions:** Read `./CLAUDE.md` if present; follow all project-specific guidelines.
 
 **Project skills:** Check `.claude/skills/` or `.agents/skills/`.
-**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md (agent type: `gsd-ui-auditor`)
 1. List available skills 2. Read `SKILL.md` for each 3. Do NOT load full `AGENTS.md` (100KB+ context cost)
 </project_context>
 

package/agents/gsd-ui-auditor.md

@@ -50,7 +50,7 @@ Before auditing, discover project context:
 
 **Project skills:** Check `.claude/skills/` or `.agents/skills/` directory if either exists:
 
-**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md (agent type: `gsd-ui-auditor`)
 1. List available skills (subdirectories)
 2. Read `SKILL.md` for each skill
 3. Do NOT load full `AGENTS.md` files (100KB+ context cost)

package/agents/gsd-ui-checker.compact.md

@@ -63,7 +63,7 @@ Before verifying: read `./CLAUDE.md` if present, follow project-specific guideli
 
 Check `.claude/skills/` or `.agents/skills/` if either exists.
 
-**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md — list
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md (agent type: `gsd-ui-checker`) — list
 skills, read each `SKILL.md` (~130 lines), load `rules/*.md` as needed during verification. Do
 NOT load full `AGENTS.md` (100KB+ cost). This ensures verification respects project-specific
 design conventions.

package/agents/gsd-ui-checker.md

@@ -62,7 +62,7 @@ Before verifying, discover project context:
 
 **Project skills:** Check `.claude/skills/` or `.agents/skills/` directory if either exists:
 
-**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md (agent type: `gsd-ui-checker`)
 1. List available skills (subdirectories)
 2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
 3. Load specific `rules/*.md` files as needed during verification

package/agents/gsd-ui-researcher.compact.md

@@ -29,7 +29,7 @@ GSD UI researcher, spawned by `/gsd:ui-phase`. Answer "What visual and interacti
 <project_context>
 Before researching: read `./CLAUDE.md` if it exists (follow project guidelines/security/conventions). Check `.claude/skills/` or `.agents/skills/`:
 
-**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md — list skill subdirectories; read each `SKILL.md` (~130 lines); load `rules/*.md` as needed; do NOT load full `AGENTS.md` (100KB+ cost); account for project skill patterns in the design contract.
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md (agent type: `gsd-ui-researcher`) — list skill subdirectories; read each `SKILL.md` (~130 lines); load `rules/*.md` as needed; do NOT load full `AGENTS.md` (100KB+ cost); account for project skill patterns in the design contract.
 </project_context>
 
 <upstream_input>
@@ -99,6 +99,18 @@ node -p "require('<pkg>/package.json').version"                            # RES
 ```
 A first-party CLI with a JSON mode, or an MCP tool the design system ships, beats all three. What matters: the command is **recorded and re-runnable**. Take the version from the installed package, not the range in your dependent's `package.json` (a caret range hides staleness).
 
+**Cross-check the first answer — always.** A tool's count is a claim: `npx shadcn info` reports "No components installed" on projects with hand-authored or pre-CLI primitives. After the first command answers, count component files on disk as a second source (shadcn: the `aliases.ui` dir in `components.json`, else `components/ui` / `src/components/ui`):
+```bash
+ls <ui-dir>/*.tsx 2>/dev/null | wc -l                                      # filesystem count
+```
+If they disagree (including a tool reporting none while files exist), do not pick silently: record the larger filesystem-backed count with the command that produced it, and add directly under the provenance line `Mismatch: <tool> reported <A>, filesystem has <B>.`
+
+**A failed lookup is a failure, never a pass-through.** `2>/dev/null` hides why `node -p` died: treat empty output, a non-zero exit, or the literal `undefined` as that step failing. With `node_modules` absent the `require()` version lookup fails; resolve from the lockfile instead (still not the caret range):
+```bash
+node -p "(require('./package-lock.json').packages['node_modules/<pkg>']||{}).version"
+```
+For `pnpm-lock.yaml` / `yarn.lock`, read `<pkg>`'s resolved version from that file. If the lockfile cannot answer, write `<version unresolved: <reason>>` in the version slot instead of leaving it empty or guessing.
+
 Record it as the first line of the section, verbatim:
 ```
 Enumerated by `<command>` — <N> components — <package>@<version> — <YYYY-MM-DD>.

package/agents/gsd-ui-researcher.md

@@ -41,7 +41,7 @@ Before researching, discover project context:
 
 **Project skills:** Check `.claude/skills/` or `.agents/skills/` directory if either exists:
 
-**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md (agent type: `gsd-ui-researcher`)
 1. List available skills (subdirectories)
 2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
 3. Load specific `rules/*.md` files as needed during research
@@ -166,6 +166,33 @@ A first-party CLI with a JSON mode, or an MCP tool the design system ships, beat
 matters is that the command is **recorded and re-runnable**. Take the version from the installed
 package, not the range in your dependent's `package.json` — a caret range hides staleness.
 
+**Cross-check the first answer — always.** A tool's count is a claim, not a fact: `npx shadcn info`
+reports "No components installed" on a project whose primitives were hand-authored or predate the
+CLI's tracking. After the first command answers, count the component files on disk as an independent
+second source (for shadcn, the `aliases.ui` directory in `components.json`, else `components/ui` or
+`src/components/ui`):
+
+```bash
+ls <ui-dir>/*.tsx 2>/dev/null | wc -l                                      # filesystem count
+```
+
+If the two disagree — including a tool that reports none while files exist — do not pick one
+silently. Record the larger, filesystem-backed count with the command that produced it, and add a
+line directly under the provenance line: `Mismatch: <tool> reported <A>, filesystem has <B>.`
+
+**A failed lookup is a failure, never a pass-through.** `2>/dev/null` hides why a `node -p` call died,
+so treat empty output, a non-zero exit, or the literal `undefined` as that step failing. When
+`node_modules` is absent the `require()` version lookup fails; resolve the version from the lockfile
+instead — still not the caret range:
+
+```bash
+node -p "(require('./package-lock.json').packages['node_modules/<pkg>']||{}).version"
+```
+
+For `pnpm-lock.yaml` or `yarn.lock`, read the resolved version for `<pkg>` from that file. If the
+lockfile cannot answer either, say `<version unresolved: <reason>>` in the version slot rather than
+leaving it empty or guessing.
+
 Record it as the first line of the section, verbatim:
 
 ```

package/agents/gsd-verifier.md

@@ -55,7 +55,7 @@ Before verifying, discover project context:
 - Load `rules/*.md` as needed during **verification**.
 - Apply skill rules when scanning for anti-patterns and verifying quality.
 
-**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md (agent type: `gsd-verifier`)
 </project_context>
 
 <core_principle>

package/bin/gsd-mcp-server.js

@@ -24,7 +24,9 @@ const { runServer } = require('../gsd-core/bin/lib/mcp-server.cjs');
 runServer({
   input: process.stdin,
   output: process.stdout,
-  ctx: { cwd: process.cwd() },
+  // --no-prompts: do not advertise the prompt catalog (hosts that turn MCP prompts into slash commands
+  // would list every GSD command twice).
+  ctx: { cwd: process.cwd(), prompts: !process.argv.includes('--no-prompts') },
 }).catch((err) => {
   process.stderr.write(String((err && err.message) || err) + '\n');
   process.exit(1);