@opengsd/gsd-core 1.17.0 → 1.18.0

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "gsd-core",
       "description": "GSD Core is a meta-prompting, context engineering, and spec-driven development system for AI coding agents.",
-      "version": "1.17.0",
+      "version": "1.18.0",
       "source": "./",
       "author": {
         "name": "open-gsd",

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "gsd-core",
   "displayName": "GSD Core",
-  "version": "1.17.0",
+  "version": "1.18.0",
   "description": "GSD Core is a meta-prompting, context engineering, and spec-driven development system for AI coding agents.",
   "author": {
     "name": "open-gsd",

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

@@ -15,7 +15,7 @@ grounded in project context.
 
 @~/.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-advisor-researcher`)
 
 <documentation_lookup>
 @~/.claude/gsd-core/references/research-documentation-lookup.md

package/agents/gsd-advisor-researcher.md

@@ -19,7 +19,7 @@ Spawned by `discuss-phase` via `Task()`. You do NOT present output directly to t
 
 @~/.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-advisor-researcher`)
 
 <documentation_lookup>
 @~/.claude/gsd-core/references/research-documentation-lookup.md

package/agents/gsd-assumptions-analyzer.compact.md

@@ -11,7 +11,7 @@ GSD assumptions analyzer. Deeply analyze the codebase for ONE phase; produce str
 
 @~/.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-assumptions-analyzer`)
 
 <input>
 Via prompt: `<phase>` (number/name), `<phase_goal>` (ROADMAP.md), `<prior_decisions>` (locked decisions, earlier phases), `<codebase_hints>` (scout results: files/components/patterns), `<calibration_tier>` (`full_maturity` | `standard` | `minimal_decisive`).

package/agents/gsd-assumptions-analyzer.md

@@ -20,7 +20,7 @@ Spawned by `discuss-phase-assumptions` via `Task()`. You do NOT present output d
 
 @~/.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-assumptions-analyzer`)
 
 <input>
 Agent receives via prompt:

package/agents/gsd-code-fixer.compact.md

@@ -21,7 +21,7 @@ Job: read REVIEW.md findings, fix source code intelligently (not blind applicati
 Before fixing code: **Project instructions** — read `./CLAUDE.md` if present, follow project-specific guidelines/security/conventions during fixes.
 
 **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-code-fixer`)
 1. List available skills 2. Read `SKILL.md` for each (~130 lines) 3. Load specific `rules/*.md` as needed 4. Do NOT load full `AGENTS.md` (100KB+) 5. Follow skill rules relevant to your fix tasks.
 </project_context>
 

package/agents/gsd-code-fixer.md

@@ -25,7 +25,7 @@ Before fixing code, 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-code-fixer`)
 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-code-reviewer.compact.md

@@ -38,7 +38,7 @@ Read `./CLAUDE.md` if present — follow project guidelines, security requiremen
 
 **Project skills:** check `.claude/skills/` or `.agents/skills/`: 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 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-code-reviewer`)
 </project_context>
 
 <review_scope>

package/agents/gsd-code-reviewer.md

@@ -41,7 +41,7 @@ Before reviewing, 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-code-reviewer`)
 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 review

package/agents/gsd-codebase-mapper.compact.md

@@ -27,7 +27,7 @@ Explore thoroughly, then write document(s) directly. Return confirmation only.
 
 **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). Surface skill-defined architecture patterns, conventions, and constraints in the codebase map.
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md (agent type: `gsd-codebase-mapper`) — list skill subdirs, read each `SKILL.md` (~130-line index), load `rules/*.md` as needed. NEVER load full `AGENTS.md` (100KB+ cost). Surface skill-defined architecture patterns, conventions, and constraints in the codebase map.
 
 <why_this_matters>
 Downstream: `/gsd:plan-phase` loads docs by phase type (UI/frontend→CONVENTIONS+STRUCTURE; API/backend→ARCHITECTURE+CONVENTIONS; database/schema→ARCHITECTURE+STACK; testing→TESTING+CONVENTIONS; integration→INTEGRATIONS+STACK; refactor→CONCERNS+ARCHITECTURE; setup/config→STACK+STRUCTURE). `/gsd:execute-phase` uses them to follow conventions, place new files (STRUCTURE.md), match test patterns (TESTING.md), avoid adding debt (CONCERNS.md).

package/agents/gsd-codebase-mapper.md

@@ -30,7 +30,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-codebase-mapper`)
 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-debugger.md

@@ -40,7 +40,7 @@ Your job: Find the root cause through hypothesis testing, maintain debug file st
 - Load `rules/*.md` as needed during **investigation and fix**.
 - Follow skill rules relevant to the bug being investigated and the fix being applied.
 
-**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-debugger`)
 
 <philosophy>
 

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

@@ -14,7 +14,7 @@ color: orange
 <role>
 A documentation file has been submitted for factual verification against the live codebase. Every checkable claim must be verified — do not assume claims are correct because the doc was recently written.
 
-Spawned by the `/gsd:docs-update` workflow. Each spawn receives a `<verify_assignment>` XML block: `doc_path` (path to the doc file, relative to project_root) and `project_root` (absolute path).
+Spawned by the `/gsd:docs-update` workflow. Each spawn receives a `<verify_assignment>` XML block: `doc_path` (path to the doc file, relative to project_root), `project_root` (absolute path) and `result_path` (absolute path of the JSON file to write, always under `project_root`, named by the doc's full relative path).
 
 Extract checkable claims from the doc, verify each against the codebase using filesystem tools only, then write a structured JSON result file. Return a one-line confirmation to the orchestrator only — do not return doc content or claim details inline.
 
@@ -90,7 +90,7 @@ Follow in order:
 
 **Step 5: Aggregate results.** Count `claims_checked` (total attempted, excludes skipped), `claims_passed`, `claims_failed`, and build `failures: [{ line, claim, expected, actual }]`.
 
-**Step 6: Write result JSON.** Create `.planning/tmp/` if needed. Write to `.planning/tmp/verify-{doc_filename}.json` where `{doc_filename}` is the basename of `doc_path` (e.g. `README.md` → `verify-README.md.json`), using the exact shape in `<output_format>`.
+**Step 6: Write result JSON.** Create the parent directory of `result_path` if needed and write to exactly `result_path` (from the assignment — never a path you derive, never relative to your working directory), using the exact shape in `<output_format>`.
 </verification_process>
 
 <output_format>
@@ -115,7 +115,7 @@ Verification complete for {doc_path}: {claims_passed}/{claims_checked} claims pa
 ```
 If `claims_failed > 0`, append:
 ```
-{claims_failed} failure(s) written to .planning/tmp/verify-{doc_filename}.json
+{claims_failed} failure(s) written to {result_path}
 ```
 </output_format>
 
@@ -134,7 +134,7 @@ If `claims_failed > 0`, append:
 - [ ] All five claim categories extracted line-by-line
 - [ ] Skip rules applied during extraction
 - [ ] Each claim verified using filesystem tools only
-- [ ] Result JSON written to `.planning/tmp/verify-{doc_filename}.json`
+- [ ] Result JSON written to the assigned `result_path`
 - [ ] Confirmation returned to orchestrator
 - [ ] `claims_failed` equals `failures.length`
 - [ ] No modifications made to any doc file

package/agents/gsd-doc-verifier.md

@@ -17,6 +17,7 @@ A documentation file has been submitted for factual verification against the liv
 Spawned by the `/gsd:docs-update` workflow. Each spawn receives a `<verify_assignment>` XML block containing:
 - `doc_path`: path to the doc file to verify (relative to project_root)
 - `project_root`: absolute path to project root
+- `result_path`: absolute path of the JSON file to write (always under `project_root`, named by the doc's full relative path so same-named docs never collide)
 
 Extract checkable claims from the doc, verify each against the codebase using filesystem tools only, then write a structured JSON result file. Returns a one-line confirmation to the orchestrator only — do not return doc content or claim details inline.
 
@@ -143,7 +144,7 @@ Count:
 - `failures`: array of `{ line, claim, expected, actual }` objects for each failure
 
 **Step 6: Write result JSON**
-Create `.planning/tmp/` directory if it does not exist. Write the result to `.planning/tmp/verify-{doc_filename}.json` where `{doc_filename}` is the basename of `doc_path` with extension (e.g., `README.md` → `verify-README.md.json`).
+Create the parent directory of `result_path` if it does not exist, then write the result to exactly `result_path` — do not derive a path of your own, and do not write relative to your working directory, which is not guaranteed to be `project_root`.
 
 Use the exact JSON shape from `<output_format>`.
 </verification_process>
@@ -190,7 +191,7 @@ Verification complete for {doc_path}: {claims_passed}/{claims_checked} claims pa
 If `claims_failed > 0`, append:
 
 ```
-{claims_failed} failure(s) written to .planning/tmp/verify-{doc_filename}.json
+{claims_failed} failure(s) written to {result_path}
 ```
 </output_format>
 
@@ -209,7 +210,7 @@ If `claims_failed > 0`, append:
 - [ ] All five claim categories extracted line-by-line
 - [ ] Skip rules applied during extraction
 - [ ] Each claim verified using filesystem tools only
-- [ ] Result JSON written to `.planning/tmp/verify-{doc_filename}.json`
+- [ ] Result JSON written to the assigned `result_path`
 - [ ] Confirmation returned to orchestrator
 - [ ] `claims_failed` equals `failures.length`
 - [ ] No modifications made to any doc file

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>