fix(#581): add Edit to six writer agents' tools so Edit-only discipline is enforceable (#582)

* fix(#581): add Edit to six writer agents' tools so Edit-only discipline is enforceable

Six writer agents (gsd-eval-planner, gsd-ai-researcher, gsd-domain-researcher,
gsd-phase-researcher, gsd-ui-researcher, gsd-debug-session-manager) shipped with
Write but no Edit in their tools: frontmatter. Their spawn prompts instruct
surgical in-place section edits on existing/shared files (notably the AI-SPEC.md
trio writing disjoint sections of the same file), but with no Edit tool they
fall back to whole-file Write — silently clobbering sibling sections
(last-writer-wins) while still reporting success.

Same bug class as #571, fixed for gsd-doc-writer in #575. This adds Edit
alongside the existing Write for all six (Edit placed adjacent to Write, mirroring
the gsd-doc-writer fix). Write is retained; no prompt-body changes; no other agents
touched.

Adds a regression test (tests/agent-frontmatter.test.cjs) asserting each of the
six section-writer agents carries both Write and Edit.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* chore(#581): add changeset fragment for writer-agent Edit fix

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* chore(#581): regenerate changeset via npm run changeset

Replace hand-authored fragment with one generated by the official
scripts/changeset/new.cjs script (correct <adjective>-<noun>-<noun>
filename convention).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.changeset/wise-hawks-bark.md

@@ -0,0 +1,5 @@
+---
+type: Fixed
+pr: 582
+---
+Six writer agents (`gsd-eval-planner`, `gsd-ai-researcher`, `gsd-domain-researcher`, `gsd-phase-researcher`, `gsd-ui-researcher`, `gsd-debug-session-manager`) now carry `Edit` alongside `Write` in their `tools:` frontmatter, so the Edit-only discipline in their spawn prompts is enforceable. Previously, without `Edit`, they fell back to whole-file `Write` and silently clobbered sibling sections of shared files such as `AI-SPEC.md`. Same bug class as #571 (fixed for `gsd-doc-writer` in #575). See #581.

agents/gsd-ai-researcher.md

@@ -1,7 +1,7 @@
 ---
 name: gsd-ai-researcher
 description: Researches a chosen AI framework's official docs to produce implementation-ready guidance — best practices, syntax, core patterns, and pitfalls distilled for the specific use case. Writes the Framework Quick Reference and Implementation Guidance sections of AI-SPEC.md. Spawned by /gsd:ai-integration-phase orchestrator.
-tools: Read, Write, Bash, Grep, Glob, WebFetch, WebSearch, mcp__context7__*
+tools: Read, Write, Edit, Bash, Grep, Glob, WebFetch, WebSearch, mcp__context7__*
 color: "#34D399"
 # hooks:
 #   PostToolUse:

agents/gsd-debug-session-manager.md

@@ -1,7 +1,7 @@
 ---
 name: gsd-debug-session-manager
 description: Manages multi-cycle /gsd:debug checkpoint and continuation loop in isolated context. Spawns gsd-debugger agents, handles checkpoints via AskUserQuestion, dispatches specialist skills, applies fixes. Returns compact summary to main context. Spawned by /gsd:debug command.
-tools: Read, Write, Bash, Grep, Glob, Agent, AskUserQuestion
+tools: Read, Write, Edit, Bash, Grep, Glob, Agent, AskUserQuestion
 color: orange
 # hooks:
 #   PostToolUse:

agents/gsd-domain-researcher.md

@@ -1,7 +1,7 @@
 ---
 name: gsd-domain-researcher
 description: Researches the business domain and real-world application context of the AI system being built. Surfaces domain expert evaluation criteria, industry-specific failure modes, regulatory context, and what "good" looks like for practitioners in this field — before the eval-planner turns it into measurable rubrics. Spawned by /gsd:ai-integration-phase orchestrator.
-tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*
+tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*
 color: "#A78BFA"
 # hooks:
 #   PostToolUse:

agents/gsd-eval-planner.md

@@ -1,7 +1,7 @@
 ---
 name: gsd-eval-planner
 description: Designs a structured evaluation strategy for an AI phase. Identifies critical failure modes, selects eval dimensions with rubrics, recommends tooling, and specifies the reference dataset. Writes the Evaluation Strategy, Guardrails, and Production Monitoring sections of AI-SPEC.md. Spawned by /gsd:ai-integration-phase orchestrator.
-tools: Read, Write, Bash, Grep, Glob, AskUserQuestion
+tools: Read, Write, Edit, Bash, Grep, Glob, AskUserQuestion
 color: "#F59E0B"
 # hooks:
 #   PostToolUse:

agents/gsd-phase-researcher.md

@@ -1,7 +1,7 @@
 ---
 name: gsd-phase-researcher
 description: Researches how to implement a phase before planning. Produces RESEARCH.md consumed by gsd-planner. Spawned by /gsd:plan-phase orchestrator.
-tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*, mcp__firecrawl__*, mcp__exa__*
+tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*, mcp__firecrawl__*, mcp__exa__*
 color: cyan
 # hooks:
 #   PostToolUse:

agents/gsd-ui-researcher.md

@@ -1,7 +1,7 @@
 ---
 name: gsd-ui-researcher
 description: Produces UI-SPEC.md design contract for frontend phases. Reads upstream artifacts, detects design system state, asks only unanswered questions. Spawned by /gsd:ui-phase orchestrator.
-tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*, mcp__firecrawl__*, mcp__exa__*
+tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*, mcp__firecrawl__*, mcp__exa__*
 color: "#E879F9"
 # hooks:
 #   PostToolUse:

tests/agent-frontmatter.test.cjs

@@ -397,6 +397,41 @@ describe('DISCUSS: discussion log generation', () => {
   });
 });
 
+// ─── Section-writer agents must carry both Write and Edit (#581) ────────────
+
+describe('EDITWRITE: section-writer agents must have both Write and Edit in tools', () => {
+  // These agents perform in-place section edits on shared/existing files (e.g.
+  // AI-SPEC.md). Without Edit in tools:, the "Edit-only" discipline in their
+  // spawn-prompt is unenforceable — they fall back to whole-file Write and
+  // clobber sibling sections. Same bug class as #571/#575 (fixed gsd-doc-writer).
+  // Issue #581.
+  const SECTION_WRITER_AGENTS = [
+    'gsd-eval-planner',
+    'gsd-ai-researcher',
+    'gsd-domain-researcher',
+    'gsd-phase-researcher',
+    'gsd-ui-researcher',
+    'gsd-debug-session-manager',
+  ];
+
+  for (const agent of SECTION_WRITER_AGENTS) {
+    test(`${agent} has both Write and Edit in tools: (#581)`, () => {
+      const content = fs.readFileSync(path.join(AGENTS_DIR, agent + '.md'), 'utf-8');
+      const toolsMatch = content.match(/^tools:\s*(.+)$/m);
+      assert.ok(toolsMatch, `${agent} missing tools: line in frontmatter`);
+      const tools = toolsMatch[1].split(',').map(t => t.trim());
+      assert.ok(
+        tools.includes('Write'),
+        `${agent} missing Write in tools: — required for file creation`
+      );
+      assert.ok(
+        tools.includes('Edit'),
+        `${agent} missing Edit in tools: — required to enforce Edit-only discipline on shared files (#581)`
+      );
+    });
+  }
+});
+
 // ─── Cross-runtime agent compatibility (#1522) ──────────────────────────────
 
 describe('COMPAT: agents must not use runtime-specific frontmatter keys', () => {