@opengsd/gsd-pi 1.9.0 → 1.10.0

package/src/resources/extensions/gsd/tests/skill-activation.test.ts

@@ -56,6 +56,10 @@ function buildBlock(
   });
 }
 
+function expectedSkillRead(base: string, name: string): string {
+  return `Read the skill file at \`${join(base, "skills", name, "SKILL.md")}\``;
+}
+
 test("buildSkillActivationBlock does not auto-activate skills via broad context heuristic", () => {
   const base = makeTempBase();
   try {
@@ -92,7 +96,7 @@ test("buildSkillActivationBlock activates skills via prefer_skills when context
       prefer_skills: ["react"],
     });
 
-    assert.match(result, /Read the installed 'react' skill file from <available_skills>/);
+    assert.ok(result.includes(expectedSkillRead(base, "react")));
     assert.doesNotMatch(result, /swiftui/);
   } finally {
     cleanup(base);
@@ -111,7 +115,7 @@ test("buildSkillActivationBlock includes always_use_skills using read-based skil
 
     assert.equal(
       result,
-      "<skill_activation>Read the installed 'swift-testing' skill file from <available_skills>.</skill_activation>",
+      `<skill_activation>Read the skill file at \`${join(base, "skills", "swift-testing", "SKILL.md")}\`.</skill_activation>`,
     );
   } finally {
     cleanup(base);
@@ -140,8 +144,8 @@ test("buildSkillActivationBlock includes skill_rules matches and task-plan skill
       skill_rules: [{ when: "prisma database schema", use: ["prisma"] }],
     });
 
-    assert.match(result, /Read the installed 'accessibility' skill file from <available_skills>/);
-    assert.match(result, /Read the installed 'prisma' skill file from <available_skills>/);
+    assert.ok(result.includes(expectedSkillRead(base, "accessibility")));
+    assert.ok(result.includes(expectedSkillRead(base, "prisma")));
   } finally {
     cleanup(base);
   }
@@ -163,7 +167,7 @@ test("buildSkillActivationBlock matches skill_rules against exact unit type cont
       ],
     });
 
-    assert.match(result, /Read the installed 'complete-slice-policies' skill file from <available_skills>/);
+    assert.ok(result.includes(expectedSkillRead(base, "complete-slice-policies")));
     assert.doesNotMatch(result, /slice-broad/);
   } finally {
     cleanup(base);
@@ -267,8 +271,8 @@ test("buildSkillActivationBlock allows valid skill names and rejects invalid one
     });
 
     assert.match(result, /skill_activation/);
-    assert.match(result, /Read the installed 'react' skill file from <available_skills>/);
-    assert.match(result, /Read the installed 'good-skill-2' skill file from <available_skills>/);
+    assert.ok(result.includes(expectedSkillRead(base, "react")));
+    assert.ok(result.includes(expectedSkillRead(base, "good-skill-2")));
     assert.doesNotMatch(result, /bad'name/);
   } finally {
     cleanup(base);
@@ -292,8 +296,8 @@ test("buildSkillActivationBlock: explicit always_use_skills bypass the unit-type
       always_use_skills: ["write-docs", "swiftui"],
     });
 
-    assert.match(result, /Read the installed 'write-docs' skill file from <available_skills>/);
-    assert.match(result, /Read the installed 'swiftui' skill file from <available_skills>/);
+    assert.ok(result.includes(expectedSkillRead(base, "write-docs")));
+    assert.ok(result.includes(expectedSkillRead(base, "swiftui")));
   } finally {
     cleanup(base);
   }
@@ -310,7 +314,7 @@ test("buildSkillActivationBlock falls through to all skills for unknown unit typ
     });
 
     // Unknown unit type = wildcard fallback (pre-manifest behavior).
-    assert.match(result, /Read the installed 'swiftui' skill file from <available_skills>/);
+    assert.ok(result.includes(expectedSkillRead(base, "swiftui")));
   } finally {
     cleanup(base);
   }
@@ -327,7 +331,7 @@ test("buildSkillActivationBlock without unitType preserves pre-manifest behavior
       always_use_skills: ["swiftui"],
     });
 
-    assert.match(result, /Read the installed 'swiftui' skill file from <available_skills>/);
+    assert.ok(result.includes(expectedSkillRead(base, "swiftui")));
   } finally {
     cleanup(base);
   }
@@ -344,12 +348,12 @@ test("milestone prompt builders propagate always_use_skills through buildSkillAc
     loadOnlyTestSkills(base);
 
     const researchPrompt = await buildResearchMilestonePrompt("M001", "Test", base);
-    assert.match(researchPrompt, /Read the installed 'write-docs' skill file from <available_skills>/);
-    assert.match(researchPrompt, /Read the installed 'swiftui' skill file from <available_skills>/);
+    assert.ok(researchPrompt.includes(expectedSkillRead(base, "write-docs")));
+    assert.ok(researchPrompt.includes(expectedSkillRead(base, "swiftui")));
 
     const planPrompt = await buildPlanMilestonePrompt("M001", "Test", base);
-    assert.match(planPrompt, /Read the installed 'write-docs' skill file from <available_skills>/);
-    assert.match(planPrompt, /Read the installed 'swiftui' skill file from <available_skills>/);
+    assert.ok(planPrompt.includes(expectedSkillRead(base, "write-docs")));
+    assert.ok(planPrompt.includes(expectedSkillRead(base, "swiftui")));
   } finally {
     cleanup(base);
   }
@@ -380,7 +384,7 @@ test("complete-slice prompt propagates always_use_skills through buildSkillActiv
 
     const prompt = await buildCompleteSlicePrompt("M001", "Test", "S01", "Slice", base);
 
-    assert.match(prompt, /Read the installed 'write-docs' skill file from <available_skills>/);
+    assert.ok(prompt.includes(expectedSkillRead(base, "write-docs")));
   } finally {
     cleanup(base);
   }

package/src/resources/extensions/gsd/tests/state-reconciliation-drift.test.ts

@@ -1618,6 +1618,58 @@ test("ADR-017 (#5705): in-sync ROADMAP and DB → no roadmap-divergence drift",
   );
 });
 
+test("ADR-017 (#1370): roadmap-divergence skips completed milestone sharing active worktree phase", async (t) => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-adr017-roadmap-shared-phase-"));
+  const milestoneDir = join(base, ".gsd", "phases", "06-rlrbot-m006-rlrbot-tool-registry-and-command-sa");
+  const roadmapPath = join(milestoneDir, "06-ROADMAP.md");
+  mkdirSync(milestoneDir, { recursive: true });
+  mkdirSync(join(base, ".gsd", "milestones", "M006"), { recursive: true });
+  mkdirSync(join(base, ".gsd", "milestones", "M006-rlrbot"), { recursive: true });
+  writeFileSync(join(base, ".gsd", "milestones", "M006", "M006-META.json"), "{}\n");
+  writeFileSync(join(base, ".gsd", "milestones", "M006-rlrbot", "M006-rlrbot-META.json"), "{}\n");
+  const activeRoadmap = [
+    "# M006-rlrbot: Active worktree",
+    "",
+    "**Vision:** Keep the active worktree projection authoritative.",
+    "",
+    "## Slices",
+    "",
+    "- [ ] **S01: Shared slice** `risk:medium` `depends:[]`",
+    "  > After this: Active work remains pending.",
+    "",
+  ].join("\n");
+  writeFileSync(roadmapPath, activeRoadmap);
+  t.after(() => {
+    try { closeDatabase(); } catch { /* noop */ }
+    rmSync(base, { recursive: true, force: true });
+  });
+
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  insertMilestone({ id: "M006", title: "Completed source", status: "complete" });
+  insertSlice({ id: "S01", milestoneId: "M006", title: "Shared slice", status: "complete", risk: "medium", depends: [], demo: "Completed.", sequence: 1 });
+  insertMilestone({
+    id: "M006-rlrbot",
+    title: "Active worktree",
+    status: "active",
+    planning: { vision: "Keep the active worktree projection authoritative." },
+  });
+  insertSlice({ id: "S01", milestoneId: "M006-rlrbot", title: "Shared slice", status: "pending", risk: "medium", depends: [], demo: "Active work remains pending.", sequence: 1 });
+  insertTask({ id: "T01", sliceId: "S01", milestoneId: "M006-rlrbot", title: "Plan active work", status: "pending" });
+
+  const result = await reconcileBeforeDispatch(base, {
+    invalidateStateCache: () => {},
+    deriveState: async () => makeState({ activeMilestone: { id: "M006-rlrbot", title: "Active worktree" } }),
+  });
+
+  assert.equal(result.ok, true);
+  assert.equal(
+    result.repaired.some((d) => d.kind === "roadmap-divergence"),
+    false,
+    "completed milestone sharing the phase dir must not trigger roadmap-divergence repair",
+  );
+  assert.equal(readFileSync(roadmapPath, "utf-8"), activeRoadmap);
+});
+
 // ─── #5706: missing-completion-timestamp drift ──────────────────────────────
 
 test("ADR-017 (#5706): task with SUMMARY but null completed_at → backfilled", async (t) => {

package/src/resources/extensions/gsd/tests/stop-notice.test.ts

@@ -7,6 +7,8 @@ import assert from "node:assert/strict";
 
 import {
   formatStopNoticePrefix,
+  formatVerdictRecordedNotice,
+  formatVerdictRejectedNotice,
   isBlockedStopReason,
   stopNoticeDisplayReason,
   stopNoticeKind,
@@ -63,6 +65,17 @@ describe("emitter↔detector round-trip", () => {
     assert.ok(isBlockedNoticeMessage(message));
   });
 
+  test("verdict notices classify as terminal with rejected notices blocked", () => {
+    const recorded = formatVerdictRecordedNotice("Milestone M001 verdict: needs-attention -> pass").toLowerCase();
+    const rejected = formatVerdictRejectedNotice("No milestone validation found for M001.").toLowerCase();
+
+    assert.ok(isTerminalNotice(recorded));
+    assert.equal(isBlockedNoticeMessage(recorded), false);
+
+    assert.ok(isTerminalNotice(rejected));
+    assert.ok(isBlockedNoticeMessage(rejected));
+  });
+
   test("un-showable menu notices classify as blocked (#1294)", () => {
     // Emitted verbatim by notifyCommandMenuUnavailable (next-action-ui.ts / command-feedback.ts).
     const menuUnavailable =
@@ -80,7 +93,14 @@ describe("emitter↔detector round-trip", () => {
   });
 
   test("terminal prefixes cover the known stop vocabulary", () => {
-    for (const message of ["auto-mode stopped.", "auto-mode complete", "auto-mode idle", "no active milestone"]) {
+    for (const message of [
+      "auto-mode stopped.",
+      "auto-mode complete",
+      "auto-mode idle",
+      "no active milestone",
+      "verdict recorded: milestone m001 verdict: needs-attention -> pass",
+      "verdict rejected: unexpected argument: x",
+    ]) {
       assert.ok(TERMINAL_NOTICE_PREFIXES.some((prefix) => message.startsWith(prefix)), message);
     }
   });

package/src/resources/extensions/gsd/tests/system-context-message-routing.test.ts

@@ -4,7 +4,13 @@
 import { describe, test } from "node:test";
 import assert from "node:assert/strict";
 
-import { buildContextMessage, stripVolatileCodebaseMetadata } from "../bootstrap/system-context.ts";
+import {
+  buildContextMessage,
+  GSD_CONTEXT_MESSAGE_SENTINEL,
+  stripVolatileCodebaseMetadata,
+} from "../bootstrap/system-context.ts";
+
+const SENTINEL = `${GSD_CONTEXT_MESSAGE_SENTINEL}\n`;
 
 describe("stripVolatileCodebaseMetadata (#847 — KV cache stability)", () => {
   const map = [
@@ -63,7 +69,7 @@ describe("buildContextMessage (#5019 — memory routing)", () => {
     });
     assert.ok(result, "expected a context message");
     assert.equal(result.customType, "gsd-memory");
-    assert.equal(result.content, "[GSD Context Metadata]\n- Memory supplied: yes\n\n[MEMORY]\nrule one\nrule two");
+    assert.equal(result.content, `${SENTINEL}[GSD Context Metadata]\n- Memory supplied: yes\n\n[MEMORY]\nrule one\nrule two`);
     assert.equal(result.display, false);
   });
 
@@ -75,7 +81,7 @@ describe("buildContextMessage (#5019 — memory routing)", () => {
     });
     assert.ok(result);
     assert.equal(result.customType, "gsd-guided-context");
-    assert.equal(result.content, "[GUIDED]\nexecute T01");
+    assert.equal(result.content, `${SENTINEL}[GUIDED]\nexecute T01`);
   });
 
   test("forensics injection alone emits gsd-forensics", () => {
@@ -86,7 +92,7 @@ describe("buildContextMessage (#5019 — memory routing)", () => {
     });
     assert.ok(result);
     assert.equal(result.customType, "gsd-forensics");
-    assert.equal(result.content, "[FORENSICS]\ninvestigation context");
+    assert.equal(result.content, `${SENTINEL}[FORENSICS]\ninvestigation context`);
   });
 
   test("memory + guided injection: memory prepended, customType is gsd-guided-context", () => {
@@ -97,7 +103,7 @@ describe("buildContextMessage (#5019 — memory routing)", () => {
     });
     assert.ok(result);
     assert.equal(result.customType, "gsd-guided-context");
-    assert.equal(result.content, `${markedMemory}\n\n[GUIDED]\nexecute T01`);
+    assert.equal(result.content, `${SENTINEL}${markedMemory}\n\n[GUIDED]\nexecute T01`);
   });
 
   test("memory + forensics: memory prepended, customType is gsd-forensics", () => {
@@ -108,7 +114,7 @@ describe("buildContextMessage (#5019 — memory routing)", () => {
     });
     assert.ok(result);
     assert.equal(result.customType, "gsd-forensics");
-    assert.equal(result.content, `${markedMemory}\n\n[FORENSICS]\ninvestigation context`);
+    assert.equal(result.content, `${SENTINEL}${markedMemory}\n\n[FORENSICS]\ninvestigation context`);
   });
 
   test("guided takes precedence over forensics when both are somehow present", () => {
@@ -122,6 +128,6 @@ describe("buildContextMessage (#5019 — memory routing)", () => {
     });
     assert.ok(result);
     assert.equal(result.customType, "gsd-guided-context");
-    assert.equal(result.content, "[GUIDED]");
+    assert.equal(result.content, `${SENTINEL}[GUIDED]`);
   });
 });

package/src/resources/extensions/gsd/tests/terminated-transient.test.ts

@@ -17,6 +17,20 @@ test("#2309: 'terminated' errors should be classified as transient", () => {
   assert.equal("retryAfterMs" in result && result.retryAfterMs, 15_000, "'terminated' should use 15s backoff");
 });
 
+test("#1364: provider abort stop reasons should be classified as transient", () => {
+  const result = classifyError("Unhandled stop reason: abort");
+  assert.equal(isTransient(result), true, "'abort' provider errors should be transient");
+  assert.equal(result.kind, "connection", "'abort' matches connection");
+  assert.equal("retryAfterMs" in result && result.retryAfterMs, 15_000, "'abort' should use 15s backoff");
+});
+
+test("#1364: provider unknown stop reasons should be classified as transient", () => {
+  const result = classifyError("Unhandled stop reason: unknown");
+  assert.equal(isTransient(result), true, "'unknown' provider stop reasons should be transient");
+  assert.equal(result.kind, "connection", "'unknown' stop reasons match connection");
+  assert.equal("retryAfterMs" in result && result.retryAfterMs, 15_000, "'unknown' should use 15s backoff");
+});
+
 test("#2309: 'connection reset by peer' errors should be classified as transient (network)", () => {
   const result = classifyError("connection reset by peer");
   assert.equal(isTransient(result), true, "'connection reset by peer' should be transient");

package/src/resources/extensions/gsd/tests/tool-invocation-error-loop-break.test.ts

@@ -47,6 +47,7 @@ describe("#2883: tool invocation error tracking on AutoSession", () => {
 import {
   isDeterministicPolicyError,
   isPendingUserApprovalGateError,
+  isScheduleWakeupContinuationError,
   isToolInvocationError,
   isToolUnavailableError,
   isQueuedUserMessageSkip,
@@ -118,6 +119,24 @@ describe("#2883: isToolInvocationError classification", () => {
     assert.equal(isToolInvocationError("Invalid arguments for tool gsd_slice_complete"), true);
   });
 
+  test("scopes conditional required-field validation to ScheduleWakeup", () => {
+    const error = "`prompt` is required when `stop` is not true";
+
+    assert.equal(isToolInvocationError(error), false);
+    assert.equal(
+      isScheduleWakeupContinuationError("ScheduleWakeup", error),
+      true,
+    );
+    assert.equal(isScheduleWakeupContinuationError("read", error), false);
+    assert.equal(
+      isScheduleWakeupContinuationError(
+        "ScheduleWakeup",
+        "`evidence` is required when `status` is blocking",
+      ),
+      false,
+    );
+  });
+
   test("detects 'No such tool available' error", () => {
     assert.equal(isToolInvocationError("No such tool available: mcp__gsd-workflow__memory_query"), true);
   });

package/src/resources/extensions/gsd/tests/tool-naming.test.ts

@@ -25,8 +25,16 @@ function makeMockPi() {
 
 console.log('\n── Tool naming: registration count ──');
 
+// Aliases are hidden from the model-facing surface by default (plan 035);
+// opt in here so this file can keep exercising alias-registration behavior.
+const previousAdvertiseAliases = process.env.GSD_ADVERTISE_TOOL_ALIASES;
+process.env.GSD_ADVERTISE_TOOL_ALIASES = "1";
+
 const pi = makeMockPi();
 registerDbTools(pi);
+
+if (previousAdvertiseAliases === undefined) delete process.env.GSD_ADVERTISE_TOOL_ALIASES;
+else process.env.GSD_ADVERTISE_TOOL_ALIASES = previousAdvertiseAliases;
 const toolByName = new Map<string, any>(pi.tools.map((tool: any) => [tool.name, tool]));
 const registeredCanonicalNames = new Set<string>(
   WORKFLOW_TOOL_CONTRACTS

package/src/resources/extensions/gsd/tests/unit-context-composer.test.ts

@@ -46,6 +46,7 @@ import {
   insertTask,
   saveReworkBrief,
 } from "../gsd-db.ts";
+import { clearGSDPreferencesCache, getProjectGSDPreferencesPath } from "../preferences.ts";
 
 // ─── Pure composer tests ──────────────────────────────────────────────────
 
@@ -418,6 +419,44 @@ test("Tool Surface composer: planning-dispatch lists allowed subagents", () => {
   assert.match(out, /\*\*planner\*\*/);
 });
 
+test("Tool Surface composer: planning_subagents updates plan-milestone dispatch guidance", (t) => {
+  const originalGsdHome = process.env.GSD_HOME;
+  const tempProject = mkdtempSync(join(tmpdir(), "gsd-tool-surface-planning-subagents-"));
+  const tempGsdHome = mkdtempSync(join(tmpdir(), "gsd-tool-surface-planning-subagents-home-"));
+
+  t.after(() => {
+    clearGSDPreferencesCache();
+    if (originalGsdHome === undefined) delete process.env.GSD_HOME;
+    else process.env.GSD_HOME = originalGsdHome;
+    rmSync(tempProject, { recursive: true, force: true });
+    rmSync(tempGsdHome, { recursive: true, force: true });
+  });
+
+  process.env.GSD_HOME = tempGsdHome;
+  mkdirSync(join(tempProject, ".gsd"), { recursive: true });
+  clearGSDPreferencesCache();
+  writeFileSync(
+    getProjectGSDPreferencesPath(tempProject),
+    [
+      "---",
+      "version: 1",
+      "planning_subagents:",
+      "  plan-milestone:",
+      "    allowed: [security]",
+      "---",
+      "",
+    ].join("\n"),
+    "utf-8",
+  );
+
+  const out = composeToolSurfaceInstructions("plan-milestone", {
+    renderMode: "standalone",
+    basePath: tempProject,
+  });
+  assert.match(out, /Dispatch subagents only to \*\*security\*\*/);
+  assert.doesNotMatch(out, /Do not dispatch subagents/);
+});
+
 test("Tool Surface composer: execute-task warns against slice/milestone closeout tools", () => {
   const out = composeToolSurfaceInstructions("execute-task", { renderMode: "nested" });
   assert.match(out, /^Tool surface: /);

package/src/resources/extensions/gsd/tests/validate-milestone-prompt-verification-classes.test.ts

@@ -22,3 +22,10 @@ test("validate-milestone prompt routes verification class analysis into verifica
   assert.match(prompt, /If Reviewer C omitted a planned class, reconstruct the missing row/i);
   assert.match(prompt, /Do not call `gsd_validate_milestone` with a partial `verificationClasses` table/i);
 });
+
+test("validate-milestone prompt forbids reading phase directories as files", () => {
+  assert.match(prompt, /find \.gsd -type f/i);
+  assert.match(prompt, /\.gsd\/phases\/<NN>-<slug>\/` is a directory, not an artifact/i);
+  assert.match(prompt, /never pass a phase, slice, `tasks\/`, or `slices\/` directory/i);
+  assert.doesNotMatch(prompt, /Read a full SUMMARY under `\.gsd\/milestones\/\{\{milestoneId\}\}\/slices\/`/i);
+});

package/src/resources/extensions/gsd/tests/workflow-projections.test.ts

@@ -352,7 +352,7 @@ test('workflow-projections: regenerateIfMissing SUMMARY is idempotent for flat-p
       keyDecisions: ['Use centralized task summary paths.'],
     });
 
-    const summaryPath = join(phaseDir, 'T01-SUMMARY.md');
+    const summaryPath = join(phaseDir, 'S01-T01-SUMMARY.md');
     assert.ok(!existsSync(summaryPath), 'precondition: flat-phase task summary absent');
 
     const first = await regenerateIfMissing(base, 'M001', 'S01', 'SUMMARY');
@@ -399,7 +399,7 @@ test('workflow-projections: flat-phase SUMMARY regeneration ignores stale nested
       status: 'complete',
     });
 
-    const rootSummaryPath = join(phaseDir, 'T01-SUMMARY.md');
+    const rootSummaryPath = join(phaseDir, 'S01-T01-SUMMARY.md');
     assert.ok(!existsSync(rootSummaryPath), 'precondition: canonical flat-phase task summary absent');
 
     const regenerated = await regenerateIfMissing(base, 'M001', 'S01', 'SUMMARY');
@@ -440,8 +440,8 @@ test('workflow-projections: renderSummaryProjection uses milestone title when cr
       status: 'complete',
     });
 
-    const titleSummaryPath = join(base, '.gsd', 'phases', '01-milestone', 'T01-SUMMARY.md');
-    const idSummaryPath = join(base, '.gsd', 'phases', '01-m001', 'T01-SUMMARY.md');
+    const titleSummaryPath = join(base, '.gsd', 'phases', '01-milestone', 'S01-T01-SUMMARY.md');
+    const idSummaryPath = join(base, '.gsd', 'phases', '01-m001', 'S01-T01-SUMMARY.md');
 
     renderSummaryProjection(base, 'M001', 'S01', 'T01');
 

package/src/resources/extensions/gsd/tests/worktree-state-projection.test.ts

@@ -117,8 +117,8 @@ test("projectRootToWorktree projects flat-phase discuss artifacts before dispatc
     new WorktreeStateProjection().projectRootToWorktree(scope);
 
     assert.ok(
-      existsSync(join(worktree, ".gsd", "milestones", "M001", "M001-META.json")),
-      "milestone metadata is projected into the worktree",
+      !existsSync(join(worktree, ".gsd", "milestones")),
+      "stale metadata-only legacy milestones/ scaffold is not projected into the worktree",
     );
     assert.ok(
       existsSync(join(worktree, ".gsd", "phases", "01-foundation", "01-CONTEXT.md")),

package/src/resources/extensions/gsd/tests/worktree-sync-milestones.test.ts

@@ -246,6 +246,66 @@ describe('worktree-sync-milestones', async () => {
     }
   }
 
+  // ─── 7b. flat-phase sync skips empty legacy milestones root ───────────
+  console.log('\n=== 7b. flat-phase sync skips empty legacy milestones root ===');
+  {
+    const mainBase = mkdtempSync(join(tmpdir(), 'gsd-wt-sync-flat-main-'));
+    const wtBase = mkdtempSync(join(tmpdir(), 'gsd-wt-sync-flat-wt-'));
+
+    try {
+      const phaseDir = join(mainBase, '.gsd', 'phases', '01-foundation');
+      mkdirSync(phaseDir, { recursive: true });
+      mkdirSync(join(mainBase, '.gsd', 'milestones'), { recursive: true });
+      mkdirSync(join(wtBase, '.gsd'), { recursive: true });
+      writeFileSync(join(phaseDir, '01-CONTEXT.md'), '# Foundation\n');
+
+      syncGsdStateToWorktree(mainBase, wtBase);
+
+      assert.ok(
+        existsSync(join(wtBase, '.gsd', 'phases', '01-foundation', '01-CONTEXT.md')),
+        'flat-phase artifact is synced to worktree',
+      );
+      assert.ok(
+        !existsSync(join(wtBase, '.gsd', 'milestones')),
+        'empty legacy milestones/ root is not recreated in worktree',
+      );
+    } finally {
+      rmSync(mainBase, { recursive: true, force: true });
+      rmSync(wtBase, { recursive: true, force: true });
+    }
+  }
+
+  // ─── 7c. flat-phase sync skips metadata-only legacy milestone dirs ────
+  console.log('\n=== 7c. flat-phase sync skips metadata-only legacy milestone dirs ===');
+  {
+    const mainBase = mkdtempSync(join(tmpdir(), 'gsd-wt-sync-flat-meta-main-'));
+    const wtBase = mkdtempSync(join(tmpdir(), 'gsd-wt-sync-flat-meta-wt-'));
+
+    try {
+      const phaseDir = join(mainBase, '.gsd', 'phases', '01-foundation');
+      const metaDir = join(mainBase, '.gsd', 'milestones', 'M001');
+      mkdirSync(phaseDir, { recursive: true });
+      mkdirSync(metaDir, { recursive: true });
+      mkdirSync(join(wtBase, '.gsd'), { recursive: true });
+      writeFileSync(join(phaseDir, '01-CONTEXT.md'), '# Foundation\n');
+      writeFileSync(join(metaDir, 'M001-META.json'), '{"integrationBranch":"main"}\n');
+
+      syncGsdStateToWorktree(mainBase, wtBase);
+
+      assert.ok(
+        existsSync(join(wtBase, '.gsd', 'phases', '01-foundation', '01-CONTEXT.md')),
+        'flat-phase artifact is synced to worktree',
+      );
+      assert.ok(
+        !existsSync(join(wtBase, '.gsd', 'milestones')),
+        'metadata-only legacy milestones/ scaffold is not recreated in worktree',
+      );
+    } finally {
+      rmSync(mainBase, { recursive: true, force: true });
+      rmSync(wtBase, { recursive: true, force: true });
+    }
+  }
+
   // ─── 8. syncWorktreeStateBack does not copy task projections ───────────
   console.log('\n=== 8. syncWorktreeStateBack leaves task projections in worktree ===');
   {

package/src/resources/extensions/gsd/tests/write-gate-planning-unit.test.ts

@@ -13,6 +13,7 @@ import { GSD_PHASE_SCOPE_DISPLAY_REASON, GSD_SECTION_CLOSE_GATE_DISPLAY_REASON }
 import { ALLOWED_PLANNING_DISPATCH_AGENTS, shouldBlockPlanningUnit } from '../bootstrap/write-gate.ts';
 import { extractSubagentAgentClasses } from '../bootstrap/subagent-input.ts';
 import { isDeterministicPolicyError } from '../auto-tool-tracking.ts';
+import { applyPlanningSubagentPreferences } from '../planning-subagent-policy.ts';
 import type { ToolsPolicy } from '../unit-context-manifest.ts';
 
 const BASE = join('/tmp', 'fake-project');
@@ -335,6 +336,39 @@ test('planning-dispatch: still allows writes inside .gsd/', () => {
   assert.strictEqual(r.block, false);
 });
 
+test('planning_subagents: upgrades plan-milestone to controlled read-only dispatch', () => {
+  const policy = applyPlanningSubagentPreferences('plan-milestone', PLANNING, {
+    planning_subagents: {
+      'plan-milestone': { allowed: ['security'] },
+    },
+  });
+  const allowed = shouldBlockPlanningUnit('subagent', '', BASE, 'plan-milestone', policy, ['security']);
+  assert.strictEqual(allowed.block, false);
+
+  const blocked = shouldBlockPlanningUnit('subagent', '', BASE, 'plan-milestone', policy, ['reviewer']);
+  assert.strictEqual(blocked.block, true);
+  assert.match(blocked.reason!, /planning_subagents/);
+  assert.match(blocked.reason!, /permitted agents for this unit: security/);
+});
+
+test('planning_subagents: widens plan-slice manifest allowlist without allowing unsafe agents', () => {
+  const policy = applyPlanningSubagentPreferences('plan-slice', {
+    mode: 'planning-dispatch',
+    allowedSubagents: ['scout', 'planner'],
+  }, {
+    planning_subagents: {
+      'plan-slice': { allowed: ['security'] },
+    },
+  });
+
+  const added = shouldBlockPlanningUnit('subagent', '', BASE, 'plan-slice', policy, ['security']);
+  assert.strictEqual(added.block, false);
+
+  const unsafe = shouldBlockPlanningUnit('subagent', '', BASE, 'plan-slice', policy, ['worker']);
+  assert.strictEqual(unsafe.block, true);
+  assert.match(unsafe.reason!, /read-only specialists/);
+});
+
 // ─── planning mode: pass-through tools ────────────────────────────────────
 
 test('planning-unit: allows read tool', () => {

package/src/resources/extensions/gsd/tools/complete-task.ts

@@ -36,7 +36,15 @@ import {
 } from "../gsd-db.js";
 import { getWorkflowDatabasePath, ensureWorkflowDbAtPath } from "../db-workspace.js";
 import { getGatesForTurn } from "../gate-registry.js";
-import { gsdProjectionRoot, clearPathCache, resolveMilestonePath, resolveSlicePath } from "../paths.js";
+import {
+  buildFlatTaskFileName,
+  buildTaskFileName,
+  gsdProjectionRoot,
+  clearPathCache,
+  legacyMilestonesDir,
+  resolveMilestonePath,
+  resolveSlicePath,
+} from "../paths.js";
 import { resolveCanonicalMilestoneRoot } from "../worktree-manager.js";
 import { checkOwnership, taskUnitKey } from "../unit-ownership.js";
 import { saveFile, clearParseCache } from "../files.js";
@@ -89,13 +97,20 @@ function taskSummaryPath(
   // a legacy layout and breaks all subsequent path resolution for the session.
   const slicePath = resolveSlicePath(basePath, milestoneId, sliceId);
   const phaseDir = resolveMilestonePath(basePath, milestoneId);
-  if (slicePath && phaseDir && slicePath !== phaseDir) {
-    // Legacy layout: the slice has its own slices/SID/ subdir → tasks/ subdir
-    return join(slicePath, "tasks", `${taskId}-SUMMARY.md`);
+  const legacyBase = legacyMilestonesDir(basePath);
+  const isLegacy = phaseDir
+    ? phaseDir.startsWith(legacyBase + "/") || phaseDir.startsWith(legacyBase + "\\")
+    : false;
+  if (isLegacy && phaseDir) {
+    // Legacy layout: the slice has its own slices/SID/ subdir → tasks/ subdir.
+    const legacySlicePath = slicePath && slicePath !== phaseDir
+      ? slicePath
+      : join(phaseDir, "slices", sliceId);
+    return join(legacySlicePath, "tasks", buildTaskFileName(taskId, "SUMMARY"));
   }
   if (phaseDir) {
     // Flat-phase: task summaries go in the phase dir (no tasks/ subdir)
-    return join(phaseDir, `${taskId}-SUMMARY.md`);
+    return join(phaseDir, buildFlatTaskFileName(sliceId, taskId, "SUMMARY"));
   }
   // Fallback: legacy hardcoded path (milestone/slice dir not on disk yet)
   return join(