gsd-pi 2.82.0-dev.ed17d078d → 3.0.0-dev.2e8b124f7

package/src/resources/extensions/gsd/tests/worktree-journal-events.test.ts

@@ -30,11 +30,13 @@ function initGitRepoIn(base: string, isolation: "worktree" | "branch" | "none"):
 }
 import {
   WorktreeLifecycle,
+  resetRecentWorktreeMergeFailuresForTest,
   type WorktreeLifecycleDeps,
   type NotifyCtx,
 } from "../worktree-lifecycle.js";
 import { WorktreeStateProjection } from "../worktree-state-projection.js";
 import { type TaskCommitContext } from "../worktree.js";
+import { MergeConflictError } from "../git-service.js";
 
 // ADR-016 phase 2 / C-track retired all worktree-manager + cache + prefs
 // fields from `WorktreeLifecycleDeps`. Tests still pass them as overrides
@@ -141,6 +143,20 @@ function readJournalEntries(basePath: string): JournalEntry[] {
   }
 }
 
+function setupMergeWorktree(basePath: string, milestoneId: string): string {
+  initGitRepoIn(basePath, "worktree");
+  execFileSync("git", ["checkout", "-b", `milestone/${milestoneId}`], { cwd: basePath, stdio: "pipe" });
+  execFileSync("git", ["checkout", "main"], { cwd: basePath, stdio: "pipe" });
+  const wt = join(basePath, ".gsd", "worktrees", milestoneId);
+  execFileSync("git", ["worktree", "add", wt, `milestone/${milestoneId}`], { cwd: basePath, stdio: "pipe" });
+  mkdirSync(join(basePath, ".gsd", "milestones", milestoneId), { recursive: true });
+  writeFileSync(
+    join(basePath, ".gsd", "milestones", milestoneId, `${milestoneId}-ROADMAP.md`),
+    `# ${milestoneId}\n- [x] S01: Slice one\n`,
+  );
+  return wt;
+}
+
 // ─── Tests ───────────────────────────────────────────────────────────────────
 
 describe("worktree journal events", () => {
@@ -148,6 +164,7 @@ describe("worktree journal events", () => {
   const originalCwd = process.cwd();
 
   beforeEach(() => {
+    resetRecentWorktreeMergeFailuresForTest();
     // realpathSync to match what `auto-worktree.ts` returns from
     // `resolveWorktreeProjectRoot` (macOS resolves `/var` → `/private/var`).
     tmp = realpathSync(mkdtempSync(join(tmpdir(), "wt-journal-")));
@@ -284,17 +301,7 @@ describe("worktree journal events", () => {
   });
 
   test("mergeAndExit emits worktree-merge-failed on error", () => {
-    initGitRepoIn(tmp, "worktree");
-    execFileSync("git", ["checkout", "-b", "milestone/M001"], { cwd: tmp, stdio: "pipe" });
-    execFileSync("git", ["checkout", "main"], { cwd: tmp, stdio: "pipe" });
-    const wt = join(tmp, ".gsd", "worktrees", "M001");
-    execFileSync("git", ["worktree", "add", wt, "milestone/M001"], { cwd: tmp, stdio: "pipe" });
-    mkdirSync(join(tmp, ".gsd", "milestones", "M001"), { recursive: true });
-    writeFileSync(
-      join(tmp, ".gsd", "milestones", "M001", "M001-ROADMAP.md"),
-      "# M001\n- [x] S01: Slice one\n",
-    );
-
+    const wt = setupMergeWorktree(tmp, "M001");
     const s = makeSession({ basePath: wt, originalBasePath: tmp });
     const deps = makeDeps({
       mergeMilestoneToMain: () => { throw new Error("conflict in main"); },
@@ -318,11 +325,56 @@ describe("worktree journal events", () => {
       );
     }
 
+    new WorktreeLifecycle(s, deps).exitMilestone(
+      "M001",
+      { merge: true },
+      makeNotifyCtx(),
+    );
+
     const entries = readJournalEntries(tmp);
-    const failed = entries.find(e => e.eventType === "worktree-merge-failed");
+    const failures = entries.filter(e => e.eventType === "worktree-merge-failed");
+    const failed = failures[0];
     assert.ok(failed, "worktree-merge-failed event should be emitted");
     assert.equal(failed!.data?.milestoneId, "M001");
     assert.equal(failed!.data?.error, "conflict in main");
+    assert.equal(failures.length, 1, "duplicate merge failures are journaled once");
+  });
+
+  test("merge failure dedupe uses stable conflict category and expires", (t) => {
+    let now = 1_000_000;
+    t.mock.method(Date, "now", () => now);
+    const wt = setupMergeWorktree(tmp, "M001");
+    const s = makeSession({ basePath: wt, originalBasePath: tmp });
+    let attempt = 0;
+    const deps = makeDeps({
+      mergeMilestoneToMain: () => {
+        attempt += 1;
+        throw new MergeConflictError(
+          attempt === 1 ? ["src/a.ts"] : ["src/b.ts", "src/c.ts"],
+          "squash",
+          "milestone/M001",
+          "main",
+        );
+      },
+    });
+    const lifecycle = new WorktreeLifecycle(s, deps);
+
+    lifecycle.exitMilestone("M001", { merge: true }, makeNotifyCtx());
+    lifecycle.exitMilestone("M001", { merge: true }, makeNotifyCtx());
+
+    let failures = readJournalEntries(tmp).filter(e => e.eventType === "worktree-merge-failed");
+    assert.equal(failures.length, 1, "variable conflict filenames should not bypass dedupe");
+    assert.match(
+      String(failures[0]!.data?.error),
+      /src\/a\.ts/,
+      "journal payload keeps the original error message",
+    );
+
+    now += 60_001;
+    lifecycle.exitMilestone("M001", { merge: true }, makeNotifyCtx());
+
+    failures = readJournalEntries(tmp).filter(e => e.eventType === "worktree-merge-failed");
+    assert.equal(failures.length, 2, "same merge failure is journaled again after dedupe expiry");
   });
 
   test("journal entries have valid flowId, seq, and ts fields", () => {

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

@@ -213,7 +213,7 @@ test("enterMilestone returns ok:true mode:none when isolation disabled", () => {
 
 test("enterMilestone returns ok:false reason:isolation-degraded when session degraded", () => {
   const s = makeSession({ isolationDegraded: true });
-  const deps = makeDeps();
+  const deps = makeDeps({ getIsolationMode: () => "branch" });
   const ctx = makeCtx();
   const lifecycle = new WorktreeLifecycle(s, deps);
 
@@ -225,7 +225,37 @@ test("enterMilestone returns ok:false reason:isolation-degraded when session deg
   }
   assert.equal(s.basePath, "/project");
   assert.equal(s.milestoneLeaseToken, null);
-  assert.equal(deps.calls.filter((c) => c.fn === "getIsolationMode").length, 0);
+});
+
+test("enterMilestone falls back to branch mode when session is degraded in worktree isolation", (t) => {
+  const previousCwd = process.cwd();
+  const base = makeGitRepoBase({ isolation: "worktree" });
+  t.after(() => cleanupRepoBase(base, previousCwd));
+
+  const s = makeSession({
+    basePath: base,
+    originalBasePath: base,
+    isolationDegraded: true,
+  });
+  const deps = makeDeps();
+  const ctx = makeCtx();
+  const lifecycle = new WorktreeLifecycle(s, deps);
+
+  const result = lifecycle.enterMilestone("M001", ctx);
+
+  assert.equal(result.ok, true, `expected ok:true, got: ${JSON.stringify(result)}`);
+  if (result.ok) {
+    assert.equal(result.mode, "branch");
+    assert.equal(result.path, base);
+  }
+  assert.equal(s.basePath, base);
+  assert.equal(
+    ctx.messages.some((m) =>
+      m.level === "warning" &&
+      m.msg.includes("Worktree isolation is degraded. Fell back to branch"),
+    ),
+    true,
+  );
 });
 
 test("enterMilestone returns ok:false reason:creation-failed and degrades session on worktree throw", (t) => {
@@ -538,6 +568,31 @@ test("restoreToProjectRoot is no-op when originalBasePath is empty", () => {
   assert.equal(deps.calls.filter((c) => c.fn === "gitServiceFactory").length, 0);
 });
 
+test("restoreToProjectRoot completes session-state restore even when chdir fails (ADR-016 phase 3, #5693)", () => {
+  // The verb attempts process.chdir to s.basePath after restoring it. The
+  // chdir is best-effort; failure must not abort the session-state restore.
+  // We exercise that contract by pointing originalBasePath at a path that
+  // cannot be chdir'd into.
+  const s = makeSession();
+  s.originalBasePath = "/this/path/should/not/exist/in/any/test/env";
+  s.basePath = "/project/.gsd/worktrees/M001";
+  const deps = makeDeps();
+  const lifecycle = new WorktreeLifecycle(s, deps);
+
+  // Capture cwd so we can confirm we did NOT successfully chdir.
+  const cwdBefore = process.cwd();
+  lifecycle.restoreToProjectRoot();
+
+  // Session-state restore happened despite chdir failure.
+  assert.equal(s.basePath, "/this/path/should/not/exist/in/any/test/env");
+  assert.equal(
+    deps.calls.filter((c) => c.fn === "gitServiceFactory").length,
+    1,
+  );
+  // cwd is unchanged because chdir threw and was swallowed.
+  assert.equal(process.cwd(), cwdBefore);
+});
+
 // ─── adoptSessionRoot (ADR-016 phase 2 / B2, issue #5620) ─────────────────────
 
 test("adoptSessionRoot sets basePath and seeds originalBasePath on a fresh session", () => {

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

@@ -86,6 +86,31 @@ test("#2684: syncGsdStateToWorktree forward-syncs PREFERENCES.md when missing fr
   );
 });
 
+test("syncGsdStateToWorktree creates missing worktree .gsd and projects DECISIONS.md", (t) => {
+  const mainBase = makeTempDir("main");
+  const wtBase = makeTempDir("wt");
+  t.after(() => cleanup(mainBase, wtBase));
+
+  const decisions = "# Decisions\n\n- D001: Test decision\n";
+  writeFile(mainBase, ".gsd/DECISIONS.md", decisions);
+
+  const result = syncGsdStateToWorktree(mainBase, wtBase);
+
+  assert.ok(
+    existsSync(join(wtBase, ".gsd", "DECISIONS.md")),
+    "DECISIONS.md should be projected into worktree .gsd",
+  );
+  assert.equal(
+    readFileSync(join(wtBase, ".gsd", "DECISIONS.md"), "utf-8"),
+    decisions,
+    "DECISIONS.md content should match project root projection",
+  );
+  assert.ok(
+    result.synced.includes("DECISIONS.md"),
+    "DECISIONS.md should appear in synced list",
+  );
+});
+
 test("syncGsdStateToWorktree still accepts legacy lowercase preferences.md", (t) => {
   const mainBase = makeTempDir("main");
   const wtBase = makeTempDir("wt");

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

@@ -189,6 +189,52 @@ describe("Worktree Safety module", () => {
     assert.equal(result.kind, "worktree-unregistered");
   });
 
+  test("attempts prune recovery once for unregistered worktrees and tracks failed roots", () => {
+    let pruneCalls = 0;
+    let listCalls = 0;
+    const safety = createWorktreeSafetyModule({
+      existsSync: () => true,
+      lstatSync: () => ({ isFile: () => true }),
+      pruneRegisteredWorktrees: () => {
+        pruneCalls += 1;
+      },
+      listRegisteredWorktrees: () => {
+        listCalls += 1;
+        return [];
+      },
+    });
+
+    const first = safety.validateUnitRoot({
+      unitType: "execute-task",
+      unitId: "M001/S01/T01",
+      writeScope: "source-writing",
+      projectRoot,
+      unitRoot,
+      milestoneId: "M001",
+    });
+    assert.equal(first.ok, false);
+    assert.equal(first.kind, "worktree-unregistered");
+    assert.equal(first.details?.attemptedPrune, true);
+    assert.equal(first.details?.trackedAsFailed, true);
+    assert.equal(pruneCalls, 1);
+    assert.equal(listCalls, 2);
+
+    const second = safety.validateUnitRoot({
+      unitType: "execute-task",
+      unitId: "M001/S01/T01",
+      writeScope: "source-writing",
+      projectRoot,
+      unitRoot,
+      milestoneId: "M001",
+    });
+    assert.equal(second.ok, false);
+    assert.equal(second.kind, "worktree-unregistered");
+    assert.equal(second.details?.attemptedPrune, false);
+    assert.equal(second.details?.trackedAsFailed, true);
+    assert.equal(pruneCalls, 1);
+    assert.equal(listCalls, 3);
+  });
+
   test("converts registered worktree list failures into typed failures", () => {
     const safety = createWorktreeSafetyModule({
       existsSync: () => true,

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

@@ -607,4 +607,99 @@ describe('worktree-sync-milestones', async () => {
       rmSync(wtBase, { recursive: true, force: true });
     }
   }
+
+  // ─── 16. pre-dispatch sync projects missing future milestone top-level artifacts (#5687) ──
+  console.log('\n=== 16. pre-dispatch sync projects missing future milestone top-level artifacts (#5687) ===');
+  {
+    const mainBase = createBase('main');
+    const wtBase = createBase('wt');
+
+    try {
+      // Canonical .gsd has M003 context draft that complete-milestone needs.
+      const mainM003 = join(mainBase, '.gsd', 'milestones', 'M003');
+      mkdirSync(mainM003, { recursive: true });
+      writeFileSync(join(mainM003, 'M003-CONTEXT-DRAFT.md'), '# M003 Context Draft');
+      writeFileSync(join(mainM003, 'M003-ROADMAP.md'), '# M003 Roadmap');
+
+      // Worktree only has skeletal roadmap for M003.
+      const wtM003 = join(wtBase, '.gsd', 'milestones', 'M003');
+      mkdirSync(wtM003, { recursive: true });
+      writeFileSync(join(wtM003, 'M003-ROADMAP.md'), '# WT Roadmap');
+
+      // Worktree has current milestone file that must not be overwritten.
+      const mainM002 = join(mainBase, '.gsd', 'milestones', 'M002');
+      mkdirSync(mainM002, { recursive: true });
+      writeFileSync(join(mainM002, 'M002-ROADMAP.md'), '# Main M002 Roadmap');
+      const wtM002 = join(wtBase, '.gsd', 'milestones', 'M002');
+      mkdirSync(wtM002, { recursive: true });
+      writeFileSync(join(wtM002, 'M002-ROADMAP.md'), '# Worktree M002 Roadmap');
+
+      // Canonical .gsd has M004 with no corresponding worktree directory at all.
+      const mainM004 = join(mainBase, '.gsd', 'milestones', 'M004');
+      mkdirSync(mainM004, { recursive: true });
+      writeFileSync(join(mainM004, 'M004-CONTEXT-DRAFT.md'), '# M004 Context Draft');
+
+      syncProjectRootToWorktree(mainBase, wtBase, 'M002');
+
+      assert.ok(
+        existsSync(join(wtBase, '.gsd', 'milestones', 'M003', 'M003-CONTEXT-DRAFT.md')),
+        '#5687: future milestone context draft projected into worktree',
+      );
+      assert.equal(
+        readFileSync(join(wtBase, '.gsd', 'milestones', 'M003', 'M003-ROADMAP.md'), 'utf-8'),
+        '# WT Roadmap',
+        '#5687: existing worktree-local M003 file is not overwritten',
+      );
+      assert.equal(
+        readFileSync(join(wtBase, '.gsd', 'milestones', 'M002', 'M002-ROADMAP.md'), 'utf-8'),
+        '# Worktree M002 Roadmap',
+        '#5687: existing worktree-local files are not overwritten',
+      );
+      assert.ok(
+        existsSync(join(wtBase, '.gsd', 'milestones', 'M004', 'M004-CONTEXT-DRAFT.md')),
+        '#5687: future milestone context draft projected into worktree when no wt dir existed',
+      );
+    } finally {
+      cleanup(mainBase);
+      cleanup(wtBase);
+    }
+  }
+
+  // ─── 17. pre-dispatch sync creates absent worktree milestone dir before projecting artifacts (#5687) ──
+  console.log('\n=== 17. pre-dispatch sync creates absent worktree milestone dir before projecting artifacts (#5687) ===');
+  {
+    const mainBase = createBase('main');
+    const wtBase = createBase('wt');
+
+    try {
+      // Canonical .gsd has a future milestone M004 with a context draft.
+      const mainM004 = join(mainBase, '.gsd', 'milestones', 'M004');
+      mkdirSync(mainM004, { recursive: true });
+      writeFileSync(join(mainM004, 'M004-CONTEXT-DRAFT.md'), '# M004 Context Draft');
+
+      // Active milestone M002 exists in both main and worktree.
+      const mainM002 = join(mainBase, '.gsd', 'milestones', 'M002');
+      mkdirSync(mainM002, { recursive: true });
+      writeFileSync(join(mainM002, 'M002-ROADMAP.md'), '# Main M002 Roadmap');
+      const wtM002 = join(wtBase, '.gsd', 'milestones', 'M002');
+      mkdirSync(wtM002, { recursive: true });
+      writeFileSync(join(wtM002, 'M002-ROADMAP.md'), '# Worktree M002 Roadmap');
+
+      // M004 does NOT exist in the worktree at all before sync.
+      assert.ok(
+        !existsSync(join(wtBase, '.gsd', 'milestones', 'M004')),
+        '#5687: worktree M004 dir must not exist before sync',
+      );
+
+      syncProjectRootToWorktree(mainBase, wtBase, 'M002');
+
+      assert.ok(
+        existsSync(join(wtBase, '.gsd', 'milestones', 'M004', 'M004-CONTEXT-DRAFT.md')),
+        '#5687: context draft projected into worktree even when milestone dir was absent',
+      );
+    } finally {
+      cleanup(mainBase);
+      cleanup(wtBase);
+    }
+  }
 });

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

@@ -123,6 +123,20 @@ describe("shouldBlockWorktreeWrite (#5199)", () => {
     assert.equal(result.block, false);
   });
 
+  test("Case 6b: relative write from active worktree cwd is allowed", () => {
+    projectRoot = makeProject("worktree");
+    const inside = join(projectRoot, ".gsd", "worktrees", "M001");
+    mkdirSync(inside, { recursive: true });
+    const result = shouldBlockWorktreeWrite(
+      "write",
+      "DESIGN.md",
+      inside,
+      /* isAutoLive */ true,
+      null,
+    );
+    assert.equal(result.block, false);
+  });
+
   test("Case 7: isolation=worktree, auto active, effectiveBasePath is project root (cwd never flipped) → block", () => {
     projectRoot = makeProject("worktree");
     const result = shouldBlockWorktreeWrite(
@@ -136,6 +150,19 @@ describe("shouldBlockWorktreeWrite (#5199)", () => {
     assert.match(result.reason ?? "", /HARD BLOCK/);
   });
 
+  test("Case 7b: relative write from project root cwd is blocked", () => {
+    projectRoot = makeProject("worktree");
+    const result = shouldBlockWorktreeWrite(
+      "write",
+      "DESIGN.md",
+      projectRoot,
+      /* isAutoLive */ true,
+      null,
+    );
+    assert.equal(result.block, true);
+    assert.match(result.reason ?? "", /HARD BLOCK/);
+  });
+
   test("Case 8: bootstrap unit type active → allow", () => {
     projectRoot = makeProject("worktree");
     for (const unitType of ["discuss-milestone", "plan-milestone", "init"]) {

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

@@ -26,6 +26,7 @@ const PLANNING_DISPATCH_REVIEW: ToolsPolicy = {
 };
 const READ_ONLY: ToolsPolicy = { mode: 'read-only' };
 const ALL: ToolsPolicy = { mode: 'all' };
+const VERIFICATION: ToolsPolicy = { mode: 'verification' };
 const DOCS: ToolsPolicy = {
   mode: 'docs',
   allowedPathGlobs: ['docs/**', 'README.md', 'README.*.md', 'CHANGELOG.md', '*.md'],
@@ -116,6 +117,11 @@ test('planning-unit: allows read-only bash (cat)', () => {
   assert.strictEqual(r.block, false);
 });
 
+test('planning-unit: allows read-only bash prefixed with cd', () => {
+  const r = shouldBlockPlanningUnit('bash', 'cd .gsd && cat PROJECT.md', BASE, 'plan-slice', PLANNING_DISPATCH);
+  assert.strictEqual(r.block, false);
+});
+
 test('planning-unit: blocks mutating bash (rm -rf)', () => {
   const r = shouldBlockPlanningUnit('bash', 'rm -rf /tmp/foo', BASE, 'discuss-milestone', PLANNING);
   assert.strictEqual(r.block, true);
@@ -157,6 +163,13 @@ test('planning-dispatch: allows subagent dispatch (delegated recon/planner durin
   assert.strictEqual(r.block, false);
 });
 
+test('planning-dispatch: allows markdown agent filenames after identity normalization', () => {
+  const agentClasses = extractSubagentAgentClasses({ agent: 'scout.md' });
+  assert.deepEqual(agentClasses, ['scout']);
+  const r = shouldBlockPlanningUnit('subagent', '', BASE, 'plan-slice', PLANNING_DISPATCH, agentClasses);
+  assert.strictEqual(r.block, false);
+});
+
 test('planning-dispatch: allows task dispatch (delegated recon/planner during slice planning)', () => {
   const r = shouldBlockPlanningUnit('task', '', BASE, 'plan-slice', PLANNING_DISPATCH, ['planner']);
   assert.strictEqual(r.block, false);
@@ -172,6 +185,22 @@ test('planning-dispatch: extracts subagent classes from single, parallel, and ch
     extractSubagentAgentClasses({ chain: [{ agent: 'reviewer' }, { agent: 'security' }] }),
     ['reviewer', 'security'],
   );
+  assert.deepEqual(
+    extractSubagentAgentClasses({
+      chain: [
+        { agent: 'scout' },
+        { parallel: [{ agent: 'reviewer' }, { agent: ' security ' }] },
+      ],
+    }),
+    ['scout', 'reviewer', 'security'],
+  );
+});
+
+test('planning-dispatch: extracts subagent classes without recursing through cycles', () => {
+  const input: { agent: string; parallel?: unknown[] } = { agent: 'scout' };
+  input.parallel = [input, { agent: 'reviewer' }];
+
+  assert.deepEqual(extractSubagentAgentClasses(input), ['scout', 'reviewer']);
 });
 
 test('planning-dispatch: blocks subagent dispatch when agentClasses is undefined (stale caller shim)', () => {
@@ -315,6 +344,36 @@ test('all-mode: execute-task can dispatch subagents', () => {
   assert.strictEqual(r.block, false);
 });
 
+// ─── verification mode: bash allowed, writes still scoped ─────────────────
+
+test('verification-mode: run-uat can run build commands', () => {
+  const r = shouldBlockPlanningUnit('bash', 'npm run build 2>&1', BASE, 'run-uat', VERIFICATION);
+  assert.strictEqual(r.block, false);
+});
+
+test('verification-mode: run-uat blocks destructive bash (rm -rf)', () => {
+  const r = shouldBlockPlanningUnit('bash', 'rm -rf dist', BASE, 'run-uat', VERIFICATION);
+  assert.strictEqual(r.block, true);
+  assert.match(r.reason!, /bash is restricted to build\/test verification commands/);
+});
+
+test('verification-mode: run-uat allows read-only investigative bash (git status)', () => {
+  const r = shouldBlockPlanningUnit('bash', 'git status', BASE, 'run-uat', VERIFICATION);
+  assert.strictEqual(r.block, false);
+});
+
+test('verification-mode: run-uat still blocks user source edits', () => {
+  const r = shouldBlockPlanningUnit('edit', join(BASE, 'src', 'main.ts'), BASE, 'run-uat', VERIFICATION);
+  assert.strictEqual(r.block, true);
+  assert.match(r.reason!, /tools-policy "verification"/);
+});
+
+test('verification-mode: run-uat still blocks subagent dispatch', () => {
+  const r = shouldBlockPlanningUnit('subagent', '', BASE, 'run-uat', VERIFICATION);
+  assert.strictEqual(r.block, true);
+  assert.match(r.reason!, /subagent dispatch is not permitted/);
+});
+
 // ─── read-only mode ───────────────────────────────────────────────────────
 
 test('read-only: blocks any edit even to .gsd/', () => {

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

@@ -38,9 +38,9 @@ export interface CompleteMilestoneParams {
   definitionOfDoneResults?: string;
   /** @optional — empty/omitted renders as "Not provided." */
   requirementOutcomes?: string;
-  /** @optional — empty/omitted renders as "(none)" */
+  /** @optional — empty/omitted renders as an empty frontmatter list */
   keyDecisions?: string[];
-  /** @optional — empty/omitted renders as "(none)" */
+  /** @optional — empty/omitted renders as an empty frontmatter list */
   keyFiles?: string[];
   /** @optional — empty/omitted renders as "(none)" */
   lessonsLearned?: string[];
@@ -70,12 +70,12 @@ function renderMilestoneSummaryMarkdown(params: CompleteMilestoneParams, complet
   const lessonsLearned = params.lessonsLearned ?? [];
 
   const keyDecisionsYaml = keyDecisions.length > 0
-    ? keyDecisions.map(d => `  - ${d}`).join("\n")
-    : "  - (none)";
+    ? `\n${keyDecisions.map(d => `  - ${d}`).join("\n")}`
+    : " []";
 
   const keyFilesYaml = keyFiles.length > 0
-    ? keyFiles.map(f => `  - ${f}`).join("\n")
-    : "  - (none)";
+    ? `\n${keyFiles.map(f => `  - ${f}`).join("\n")}`
+    : " []";
 
   const lessonsYaml = lessonsLearned.length > 0
     ? lessonsLearned.map(l => `  - ${l}`).join("\n")
@@ -86,10 +86,8 @@ id: ${params.milestoneId}
 title: "${displayTitle}"
 status: complete
 completed_at: ${completedAt}
-key_decisions:
-${keyDecisionsYaml}
-key_files:
-${keyFilesYaml}
+key_decisions:${keyDecisionsYaml}
+key_files:${keyFilesYaml}
 lessons_learned:
 ${lessonsYaml}
 ---

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

@@ -104,12 +104,12 @@ function renderSliceSummaryMarkdown(params: CompleteSliceParams): string {
     : "  []";
 
   const keyFilesYaml = keyFiles.length > 0
-    ? keyFiles.map(f => `  - ${f}`).join("\n")
-    : "  - (none)";
+    ? `\n${keyFiles.map(f => `  - ${f}`).join("\n")}`
+    : " []";
 
   const keyDecisionsYaml = keyDecisions.length > 0
-    ? keyDecisions.map(d => `  - ${d}`).join("\n")
-    : "  - (none)";
+    ? `\n${keyDecisions.map(d => `  - ${d}`).join("\n")}`
+    : " []";
 
   const patternsYaml = patternsEstablished.length > 0
     ? patternsEstablished.map(p => `  - ${p}`).join("\n")
@@ -155,10 +155,8 @@ requires:
 ${requiresYaml}
 affects:
 ${affectsYaml}
-key_files:
-${keyFilesYaml}
-key_decisions:
-${keyDecisionsYaml}
+key_files:${keyFilesYaml}
+key_decisions:${keyDecisionsYaml}
 patterns_established:
 ${patternsYaml}
 observability_surfaces:

package/src/resources/extensions/gsd/tools/plan-milestone.ts

@@ -1,6 +1,6 @@
 import { clearParseCache } from "../files.js";
 import { isClosedStatus } from "../status-guards.js";
-import { isNonEmptyString, validateStringArray } from "../validation.js";
+import { isNonEmptyString, validateStringArray, validateTitle } from "../validation.js";
 import {
   transaction,
   getMilestone,
@@ -148,6 +148,8 @@ function validateSlices(value: unknown): PlanMilestoneSliceInput[] {
     if (seen.has(sliceId)) throw new Error(`slices[${index}].sliceId must be unique`);
     seen.add(sliceId);
     if (!isNonEmptyString(title)) throw new Error(`slices[${index}].title must be a non-empty string`);
+    const titleIssue = validateTitle(title);
+    if (titleIssue) throw new Error(`slices[${index}].title is invalid: ${titleIssue}`);
     if (!isNonEmptyString(risk)) throw new Error(`slices[${index}].risk must be a non-empty string`);
     if (!Array.isArray(depends) || depends.some((item) => !isNonEmptyString(item))) {
       throw new Error(`slices[${index}].depends must be an array of non-empty strings`);
@@ -190,6 +192,8 @@ function validateParams(params: PlanMilestoneParams): PlanMilestoneParams {
   if (!isNonEmptyString(params?.milestoneId)) throw new Error("milestoneId is required");
   if (!isNonEmptyString(params?.title)) throw new Error("title is required");
   if (!isNonEmptyString(params?.vision)) throw new Error("vision is required");
+  const milestoneTitleIssue = validateTitle(params.title);
+  if (milestoneTitleIssue) throw new Error(`title is invalid: ${milestoneTitleIssue}`);
 
   return {
     ...params,