From c15b34faca7e7bfce2c6258444de9427d7ce6e98 Mon Sep 17 00:00:00 2001
From: mastertyko <11311479+mastertyko@users.noreply.github.com>
Date: Sat, 11 Apr 2026 17:52:56 +0200
Subject: [PATCH] fix(gsd): document flat task summary layout

---
 .../extensions/gsd/prompts/complete-slice.md   |  4 ++--
 ...te-slice-prompt-task-summary-layout.test.ts | 18 ++++++++++++++++++
 2 files changed, 20 insertions(+), 2 deletions(-)
 create mode 100644 src/resources/extensions/gsd/tests/complete-slice-prompt-task-summary-layout.test.ts

diff --git a/src/resources/extensions/gsd/prompts/complete-slice.md b/src/resources/extensions/gsd/prompts/complete-slice.md
index 86c271298..746729d82 100644
--- a/src/resources/extensions/gsd/prompts/complete-slice.md
+++ b/src/resources/extensions/gsd/prompts/complete-slice.md
@@ -21,7 +21,7 @@ All relevant context has been preloaded below — the slice plan, all task summa
 Then:
 1. Use the **Slice Summary** and **UAT** output templates from the inlined context above
 2. {{skillActivation}}
-3. Run all slice-level verification checks defined in the slice plan. All must pass before marking the slice done. If any fail, fix them first.
+3. Run all slice-level verification checks defined in the slice plan. All must pass before marking the slice done. If any fail, fix them first. Task artifacts use a **flat file layout** directly inside `tasks/` (for example `T01-SUMMARY.md`, `T02-SUMMARY.md`) rather than per-task subdirectories. If you need to count or re-read task summaries during verification, use `find .gsd/milestones/{{milestoneId}}/slices/{{sliceId}}/tasks -name "*-SUMMARY.md"` or `ls .gsd/milestones/{{milestoneId}}/slices/{{sliceId}}/tasks/*-SUMMARY.md`. Never use `tasks/*/SUMMARY.md` — that glob expects subdirectories that do not exist.
 4. If the slice plan includes observability/diagnostic surfaces, confirm they work. Skip this for simple slices that don't have observability sections.
 5. If the slice involved runtime behavior, fill the **Operational Readiness** section (Q8) in the slice summary: health signal, failure signal, recovery procedure, and monitoring gaps. Omit entirely for simple slices with no runtime concerns.
 6. If this slice produced evidence that a requirement changed status (Active → Validated, Active → Deferred, etc.), call `gsd_requirement_update` with the requirement ID, updated `status`, and `validation` evidence. Do NOT write `.gsd/REQUIREMENTS.md` directly — the engine renders it from the database.
@@ -35,7 +35,7 @@ Then:
 
 **Autonomous execution:** Do not call `ask_user_questions` or `secure_env_collect`. You are running in auto-mode — there is no human available to answer questions. Make reasonable assumptions and document them in the slice summary. If a decision genuinely requires human input, note it in the summary and proceed with the best available option.
 
-**File system safety:** Task summaries are preloaded in the inlined context above. If you need to re-read any of them, use `find .gsd/milestones/{{milestoneId}}/slices/{{sliceId}}/tasks -name "*-SUMMARY.md"` to list file paths first — never pass `{{slicePath}}` or any other directory path directly to the `read` tool. The `read` tool only accepts file paths, not directories.
+**File system safety:** Task summaries are preloaded in the inlined context above. Task artifacts use a **flat file layout** — files such as `T01-SUMMARY.md` and `T02-SUMMARY.md` live directly inside the `tasks/` directory, not inside per-task subdirectories like `tasks/T01/SUMMARY.md`. If you need to re-read any of them, use `find .gsd/milestones/{{milestoneId}}/slices/{{sliceId}}/tasks -name "*-SUMMARY.md"` to list file paths first. Never use `tasks/*/SUMMARY.md`, and never pass `{{slicePath}}` or any other directory path directly to the `read` tool. The `read` tool only accepts file paths, not directories.
 
 **You MUST call `gsd_complete_slice` with the slice summary and UAT content before finishing. The tool persists to both DB and disk and renders `{{sliceSummaryPath}}` and `{{sliceUatPath}}` automatically.**
 
diff --git a/src/resources/extensions/gsd/tests/complete-slice-prompt-task-summary-layout.test.ts b/src/resources/extensions/gsd/tests/complete-slice-prompt-task-summary-layout.test.ts
new file mode 100644
index 000000000..c50389a1d
--- /dev/null
+++ b/src/resources/extensions/gsd/tests/complete-slice-prompt-task-summary-layout.test.ts
@@ -0,0 +1,18 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const promptPath = join(process.cwd(), "src/resources/extensions/gsd/prompts/complete-slice.md");
+const prompt = readFileSync(promptPath, "utf-8");
+
+test("complete-slice prompt explains the flat task summary layout", () => {
+  assert.match(prompt, /flat file layout/i);
+  assert.match(prompt, /T01-SUMMARY\.md/);
+  assert.match(prompt, /not inside per-task subdirectories like `tasks\/T01\/SUMMARY\.md`/i);
+});
+
+test("complete-slice prompt forbids the wrong task summary glob", () => {
+  assert.match(prompt, /find .*tasks -name "\*-SUMMARY\.md"/i);
+  assert.match(prompt, /Never use `tasks\/\*\/SUMMARY\.md`/);
+});