gsd-pi 2.78.1-dev.b6a389b66 → 2.78.1-dev.d8826a445

package/src/resources/extensions/gsd/tests/path-normalization-unified.test.ts

@@ -0,0 +1,175 @@
+// GSD-2 + Unified path normalization tests: normalizeRealPath and tryRealpath parity
+
+import { describe, test, before, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import {
+  mkdtempSync,
+  mkdirSync,
+  writeFileSync,
+  existsSync,
+  rmSync,
+  realpathSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { normalizeRealPath } from "../paths.ts";
+import { createWorkspace } from "../workspace.ts";
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+/**
+ * Detect whether the filesystem hosting `dir` is case-insensitive.
+ * Creates a file with a lowercase name, then probes it via an uppercase name.
+ */
+function isCaseInsensitiveFs(dir: string): boolean {
+  const lower = join(dir, "ci_probe_lower.txt");
+  const upper = join(dir, "CI_PROBE_LOWER.TXT");
+  try {
+    writeFileSync(lower, "probe");
+    return existsSync(upper);
+  } finally {
+    try { rmSync(lower); } catch { /* ignore */ }
+  }
+}
+
+function makeProjectDir(): string {
+  const dir = realpathSync(mkdtempSync(join(tmpdir(), "gsd-pathnorm-")));
+  mkdirSync(join(dir, ".gsd", "milestones"), { recursive: true });
+  return dir;
+}
+
+// ─── Suite 1: normalizeRealPath and tryRealpath return identical strings ──────
+
+describe("normalizeRealPath and tryRealpath produce identical results", () => {
+  let projectDir: string;
+
+  beforeEach(() => {
+    projectDir = makeProjectDir();
+  });
+
+  afterEach(() => {
+    rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  test("normalizeRealPath on an existing directory matches realpathSync.native", () => {
+    const result = normalizeRealPath(projectDir);
+    // realpathSync.native is the canonical form — result must equal it
+    const expected = realpathSync.native(projectDir);
+    assert.equal(result, expected);
+  });
+
+  test("createWorkspace identityKey equals normalizeRealPath of projectRoot", () => {
+    const ws = createWorkspace(projectDir);
+    // identityKey is computed via tryRealpath → normalizeRealPath
+    assert.equal(ws.identityKey, normalizeRealPath(ws.projectRoot));
+  });
+
+  test("createWorkspace identityKey and normalizeRealPath agree on the same input", () => {
+    const ws = createWorkspace(projectDir);
+    const direct = normalizeRealPath(projectDir);
+    assert.equal(ws.identityKey, direct);
+  });
+});
+
+// ─── Suite 2: non-existent path fallback ─────────────────────────────────────
+
+describe("normalizeRealPath: fallback for non-existent paths", () => {
+  test("returns a resolved (absolute) path for a non-existent input", () => {
+    const ghost = join(tmpdir(), "gsd-pathnorm-ghost-does-not-exist-" + Date.now());
+    const result = normalizeRealPath(ghost);
+    // Must be a string, must be absolute, must not throw
+    assert.equal(typeof result, "string");
+    assert.ok(result.startsWith("/") || /^[A-Za-z]:/.test(result), "result must be absolute");
+  });
+
+  test("normalizeRealPath of a non-existent path is idempotent", () => {
+    const ghost = join(tmpdir(), "gsd-pathnorm-ghost2-" + Date.now());
+    const first = normalizeRealPath(ghost);
+    const second = normalizeRealPath(first);
+    assert.equal(first, second);
+  });
+});
+
+// ─── Suite 3: idempotency on existing paths ───────────────────────────────────
+
+describe("normalizeRealPath: idempotency on existing paths", () => {
+  let projectDir: string;
+
+  beforeEach(() => {
+    projectDir = makeProjectDir();
+  });
+
+  afterEach(() => {
+    rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  test("normalizeRealPath of a normalizeRealPath result is the same", () => {
+    const once = normalizeRealPath(projectDir);
+    const twice = normalizeRealPath(once);
+    assert.equal(once, twice);
+  });
+
+  test("createWorkspace identityKey is idempotent across two calls with same path", () => {
+    const ws1 = createWorkspace(projectDir);
+    const ws2 = createWorkspace(projectDir);
+    assert.equal(ws1.identityKey, ws2.identityKey);
+  });
+});
+
+// ─── Suite 4: case-insensitive filesystem (macOS HFS+/APFS) ──────────────────
+
+describe("normalizeRealPath: case normalization on case-insensitive volumes", () => {
+  let projectDir: string;
+  let caseInsensitive: boolean;
+
+  before(() => {
+    // Detect FS case sensitivity once for the suite
+    const probe = mkdtempSync(join(tmpdir(), "gsd-ci-probe-"));
+    caseInsensitive = isCaseInsensitiveFs(probe);
+    rmSync(probe, { recursive: true, force: true });
+  });
+
+  beforeEach(() => {
+    projectDir = makeProjectDir();
+  });
+
+  afterEach(() => {
+    rmSync(projectDir, { recursive: true, force: true });
+  });
+
+  test("upper and lower case paths resolve to the same canonical string on case-insensitive FS", (t) => {
+    if (!caseInsensitive) {
+      t.skip("case-sensitive filesystem — case-normalization check not applicable");
+      return;
+    }
+
+    const lower = projectDir.toLowerCase();
+    const upper = projectDir.toUpperCase();
+
+    const canonicalFromLower = normalizeRealPath(lower);
+    const canonicalFromUpper = normalizeRealPath(upper);
+
+    assert.equal(
+      canonicalFromLower,
+      canonicalFromUpper,
+      "both case variants must resolve to the same canonical path on case-insensitive FS",
+    );
+  });
+
+  test("createWorkspace identityKey is case-stable on case-insensitive FS", (t) => {
+    if (!caseInsensitive) {
+      t.skip("case-sensitive filesystem — case-normalization check not applicable");
+      return;
+    }
+
+    const wsLower = createWorkspace(projectDir.toLowerCase());
+    const wsUpper = createWorkspace(projectDir.toUpperCase());
+
+    assert.equal(
+      wsLower.identityKey,
+      wsUpper.identityKey,
+      "identityKey must be identical regardless of input case on case-insensitive FS",
+    );
+  });
+});

package/src/resources/extensions/gsd/tests/paths-cache.test.ts

@@ -0,0 +1,170 @@
+// GSD2 — paths cache normalization and clearPathCache() invalidation tests
+
+import { describe, test, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, rmSync, renameSync, realpathSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { gsdRoot, clearPathCache, _clearGsdRootCache } from '../paths.ts';
+
+describe('gsdRootCache key normalization', () => {
+  let projectDir: string;
+  let fakeHome: string;
+  let savedHome: string | undefined;
+  let savedUserProfile: string | undefined;
+  let savedGsdHome: string | undefined;
+
+  beforeEach(() => {
+    projectDir = realpathSync(mkdtempSync(join(tmpdir(), 'gsd-cache-norm-')));
+    mkdirSync(join(projectDir, '.gsd'), { recursive: true });
+
+    fakeHome = realpathSync(mkdtempSync(join(tmpdir(), 'gsd-cache-home-')));
+
+    savedHome = process.env.HOME;
+    savedUserProfile = process.env.USERPROFILE;
+    savedGsdHome = process.env.GSD_HOME;
+
+    // Point HOME and GSD_HOME at an unrelated temp dir to prevent ~/.gsd interference.
+    process.env.HOME = fakeHome;
+    process.env.USERPROFILE = fakeHome;
+    process.env.GSD_HOME = join(fakeHome, '.gsd');
+
+    _clearGsdRootCache();
+  });
+
+  afterEach(() => {
+    if (savedHome === undefined) delete process.env.HOME;
+    else process.env.HOME = savedHome;
+    if (savedUserProfile === undefined) delete process.env.USERPROFILE;
+    else process.env.USERPROFILE = savedUserProfile;
+    if (savedGsdHome === undefined) delete process.env.GSD_HOME;
+    else process.env.GSD_HOME = savedGsdHome;
+
+    clearPathCache();
+    rmSync(projectDir, { recursive: true, force: true });
+    rmSync(fakeHome, { recursive: true, force: true });
+  });
+
+  test('gsdRoot with trailing slash returns same result as without', () => {
+    const withoutSlash = gsdRoot(projectDir);
+    _clearGsdRootCache();
+    const withSlash = gsdRoot(projectDir + '/');
+
+    assert.equal(
+      withoutSlash,
+      withSlash,
+      'gsdRoot must return the same path regardless of trailing slash',
+    );
+    assert.equal(
+      withoutSlash,
+      join(projectDir, '.gsd'),
+      'both calls should resolve to projectDir/.gsd',
+    );
+  });
+
+  test('second call with trailing slash hits cache set by first call without slash', () => {
+    // Prime the cache with the no-slash form.
+    const first = gsdRoot(projectDir);
+    // Now remove .gsd so a fresh probe would return a different path.
+    renameSync(join(projectDir, '.gsd'), join(projectDir, '.gsd-hidden'));
+    // Call with trailing slash — must hit the normalized cache entry (no re-probe).
+    const second = gsdRoot(projectDir + '/');
+    // Restore for cleanup.
+    renameSync(join(projectDir, '.gsd-hidden'), join(projectDir, '.gsd'));
+
+    assert.equal(
+      second,
+      first,
+      'trailing-slash call must return cached result from the no-slash call',
+    );
+  });
+});
+
+describe('clearPathCache() does NOT invalidate gsdRootCache (process-lifetime semantics)', () => {
+  let projectDir: string;
+  let fakeHome: string;
+  let savedHome: string | undefined;
+  let savedUserProfile: string | undefined;
+  let savedGsdHome: string | undefined;
+
+  beforeEach(() => {
+    projectDir = realpathSync(mkdtempSync(join(tmpdir(), 'gsd-cache-clear-')));
+    mkdirSync(join(projectDir, '.gsd'), { recursive: true });
+
+    fakeHome = realpathSync(mkdtempSync(join(tmpdir(), 'gsd-cache-home2-')));
+
+    savedHome = process.env.HOME;
+    savedUserProfile = process.env.USERPROFILE;
+    savedGsdHome = process.env.GSD_HOME;
+
+    process.env.HOME = fakeHome;
+    process.env.USERPROFILE = fakeHome;
+    process.env.GSD_HOME = join(fakeHome, '.gsd');
+
+    _clearGsdRootCache();
+  });
+
+  afterEach(() => {
+    if (savedHome === undefined) delete process.env.HOME;
+    else process.env.HOME = savedHome;
+    if (savedUserProfile === undefined) delete process.env.USERPROFILE;
+    else process.env.USERPROFILE = savedUserProfile;
+    if (savedGsdHome === undefined) delete process.env.GSD_HOME;
+    else process.env.GSD_HOME = savedGsdHome;
+
+    _clearGsdRootCache();
+    clearPathCache();
+    rmSync(projectDir, { recursive: true, force: true });
+    rmSync(fakeHome, { recursive: true, force: true });
+  });
+
+  test('clearPathCache() does NOT evict a cached gsdRoot result', (t) => {
+    // Prime the cache.
+    const firstResult = gsdRoot(projectDir);
+    assert.equal(firstResult, join(projectDir, '.gsd'));
+
+    // Remove .gsd so a fresh probe would return a different (fallback) result.
+    renameSync(join(projectDir, '.gsd'), join(projectDir, '.gsd-hidden'));
+    t.after(() => {
+      try { renameSync(join(projectDir, '.gsd-hidden'), join(projectDir, '.gsd')); } catch { /* ignore */ }
+    });
+
+    // clearPathCache() only clears volatile dir caches — gsdRootCache is untouched.
+    clearPathCache();
+    const afterClearPath = gsdRoot(projectDir);
+    assert.equal(
+      afterClearPath,
+      firstResult,
+      'clearPathCache must NOT evict gsdRootCache — result must still be the cached value',
+    );
+  });
+
+  test('_clearGsdRootCache() DOES evict gsdRootCache, causing re-probe', (t) => {
+    // Prime the cache.
+    const firstResult = gsdRoot(projectDir);
+    assert.equal(firstResult, join(projectDir, '.gsd'));
+
+    // Remove .gsd so a fresh probe returns the creation fallback.
+    renameSync(join(projectDir, '.gsd'), join(projectDir, '.gsd-hidden'));
+    t.after(() => {
+      try { renameSync(join(projectDir, '.gsd-hidden'), join(projectDir, '.gsd')); } catch { /* ignore */ }
+    });
+
+    // _clearGsdRootCache() evicts the entry — next call re-probes.
+    _clearGsdRootCache();
+    const afterClearRoot = gsdRoot(projectDir);
+    assert.equal(
+      afterClearRoot,
+      join(projectDir, '.gsd'),
+      'after _clearGsdRootCache, gsdRoot must re-probe and return creation fallback',
+    );
+    // The two results are equal (same path) but the key point is re-probe occurred;
+    // the cached firstResult also happened to equal the fallback path.
+    // Verify: if we prime again without removing .gsd, clearing root re-probes to gsd.
+    renameSync(join(projectDir, '.gsd-hidden'), join(projectDir, '.gsd'));
+    _clearGsdRootCache();
+    const reprobe = gsdRoot(projectDir);
+    assert.equal(reprobe, join(projectDir, '.gsd'), 're-probe after restore returns .gsd');
+  });
+});

package/src/resources/extensions/gsd/tests/pending-autostart-scope.test.ts

@@ -0,0 +1,120 @@
+// GSD-2 + Tests for MilestoneScope pinning in pendingAutoStartMap (C1 regression guard)
+
+import { describe, test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import {
+  setPendingAutoStart,
+  clearPendingAutoStart,
+  _getPendingAutoStart,
+} from "../guided-flow.ts";
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function makeProjectDir(): string {
+  const dir = realpathSync(mkdtempSync(join(tmpdir(), "gsd-pas-scope-")));
+  mkdirSync(join(dir, ".gsd", "milestones"), { recursive: true });
+  return dir;
+}
+
+// ─── Tests ───────────────────────────────────────────────────────────────────
+
+describe("pendingAutoStart scope pinning (C1)", () => {
+  let base: string;
+
+  beforeEach(() => {
+    clearPendingAutoStart();
+    base = makeProjectDir();
+  });
+
+  afterEach(() => {
+    clearPendingAutoStart();
+    if (base) {
+      rmSync(base, { recursive: true, force: true });
+    }
+  });
+
+  test("setPendingAutoStart stores a scope whose paths derive from the basePath at reservation time", () => {
+    setPendingAutoStart(base, { basePath: base, milestoneId: "M001" });
+
+    const entry = _getPendingAutoStart(base);
+    assert.ok(entry, "entry should exist");
+    assert.ok(entry.scope, "entry.scope should be set");
+    assert.equal(entry.scope.milestoneId, "M001");
+
+    const expectedContext = join(base, ".gsd", "milestones", "M001", "M001-CONTEXT.md");
+    const expectedRoadmap = join(base, ".gsd", "milestones", "M001", "M001-ROADMAP.md");
+    const expectedState = join(base, ".gsd", "STATE.md");
+
+    assert.equal(entry.scope.contextFile(), expectedContext);
+    assert.equal(entry.scope.roadmapFile(), expectedRoadmap);
+    assert.equal(entry.scope.stateFile(), expectedState);
+  });
+
+  test("scope paths are unaffected by process.chdir after reservation", (t) => {
+    setPendingAutoStart(base, { basePath: base, milestoneId: "M002" });
+
+    const entry = _getPendingAutoStart(base);
+    assert.ok(entry, "entry should exist");
+
+    // Capture paths before cwd change
+    const ctxBefore = entry.scope.contextFile();
+    const roadmapBefore = entry.scope.roadmapFile();
+    const stateBefore = entry.scope.stateFile();
+
+    // Change cwd to a different directory, then check that scope is unchanged
+    const originalCwd = process.cwd();
+    const altDir = mkdtempSync(join(tmpdir(), "gsd-cwd-alt-"));
+    t.after(() => {
+      process.chdir(originalCwd);
+      rmSync(altDir, { recursive: true, force: true });
+    });
+
+    process.chdir(altDir);
+
+    assert.equal(entry.scope.contextFile(), ctxBefore, "contextFile must not change after cwd drift");
+    assert.equal(entry.scope.roadmapFile(), roadmapBefore, "roadmapFile must not change after cwd drift");
+    assert.equal(entry.scope.stateFile(), stateBefore, "stateFile must not change after cwd drift");
+  });
+
+  test("scope identityKey matches the realpath of the original basePath even with trailing slash", () => {
+    const baseWithSlash = base + "/";
+    setPendingAutoStart(base, { basePath: baseWithSlash, milestoneId: "M003" });
+
+    const entry = _getPendingAutoStart(base);
+    assert.ok(entry, "entry should exist");
+
+    const expectedIdentityKey = realpathSync(base);
+    assert.equal(
+      entry.scope.workspace.identityKey,
+      expectedIdentityKey,
+      "identityKey must match realpath of the original (non-canonical) basePath",
+    );
+  });
+
+  test("clearPendingAutoStart removes the entry", () => {
+    setPendingAutoStart(base, { basePath: base, milestoneId: "M001" });
+
+    const before = _getPendingAutoStart(base);
+    assert.ok(before, "entry should exist before clear");
+
+    clearPendingAutoStart(base);
+
+    const after = _getPendingAutoStart(base);
+    assert.equal(after, null, "entry should be null after clearPendingAutoStart(base)");
+  });
+
+  test("_getPendingAutoStart with no basePath argument returns the sole entry", () => {
+    setPendingAutoStart(base, { basePath: base, milestoneId: "M001" });
+
+    // No argument — should return the sole entry
+    const entry = _getPendingAutoStart();
+    assert.ok(entry, "sole entry should be returned when no basePath given");
+    assert.equal(entry.milestoneId, "M001");
+    assert.ok(entry.scope, "sole entry must have a scope");
+    assert.equal(entry.scope.milestoneId, "M001");
+  });
+});

package/src/resources/extensions/gsd/tests/prompt-contracts.test.ts

@@ -4,11 +4,16 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 
 const promptsDir = join(process.cwd(), "src/resources/extensions/gsd/prompts");
+const templatesDir = join(process.cwd(), "src/resources/extensions/gsd/templates");
 
 function readPrompt(name: string): string {
   return readFileSync(join(promptsDir, `${name}.md`), "utf-8");
 }
 
+function readTemplate(name: string): string {
+  return readFileSync(join(templatesDir, `${name}.md`), "utf-8");
+}
+
 test("reactive-execute prompt keeps task summaries with subagents and avoids batch commits", () => {
   const prompt = readPrompt("reactive-execute");
   assert.match(prompt, /subagent-written summary as authoritative/i);
@@ -174,15 +179,15 @@ test("guided-resume-task prompt preserves recovery state until work is supersede
 
 // ─── Prompt migration: execute-task → gsd_complete_task ───────────────
 
-test("execute-task prompt references gsd_complete_task tool", () => {
+test("execute-task prompt references gsd_task_complete tool", () => {
   const prompt = readPrompt("execute-task");
-  assert.match(prompt, /gsd_complete_task/);
+  assert.match(prompt, /gsd_task_complete/);
 });
 
-test("execute-task prompt uses gsd_complete_task as canonical summary write path", () => {
+test("execute-task prompt uses gsd_task_complete as canonical summary write path", () => {
   const prompt = readPrompt("execute-task");
   assert.match(prompt, /\{\{taskSummaryPath\}\}/);
-  assert.match(prompt, /gsd_complete_task/);
+  assert.match(prompt, /gsd_task_complete/);
   assert.match(prompt, /DB-backed tool is the canonical write path/i);
   assert.match(prompt, /Do \*\*not\*\* manually write `?\{\{taskSummaryPath\}\}`?/i);
   assert.doesNotMatch(prompt, /^\d+\.\s+Write `?\{\{taskSummaryPath\}\}`?\s*$/m);
@@ -202,9 +207,9 @@ test("execute-task prompt still contains template variables for context", () =>
 
 // ─── Prompt migration: complete-slice → gsd_complete_slice ────────────
 
-test("complete-slice prompt references gsd_complete_slice tool", () => {
+test("complete-slice prompt references gsd_slice_complete tool", () => {
   const prompt = readPrompt("complete-slice");
-  assert.match(prompt, /gsd_complete_slice/);
+  assert.match(prompt, /gsd_slice_complete/);
 });
 
 test("complete-slice prompt does not instruct LLM to toggle checkboxes manually", () => {
@@ -216,7 +221,7 @@ test("complete-slice prompt instructs writing summary and UAT files before tool
   const prompt = readPrompt("complete-slice");
   assert.match(prompt, /\{\{sliceSummaryPath\}\}/);
   assert.match(prompt, /\{\{sliceUatPath\}\}/);
-  assert.match(prompt, /gsd_complete_slice/);
+  assert.match(prompt, /gsd_slice_complete/);
   assert.match(prompt, /DB-backed tool is the canonical write path/i);
   assert.match(prompt, /Do \*\*not\*\* manually write `?\{\{sliceSummaryPath\}\}`?/i);
   assert.match(prompt, /Do \*\*not\*\* manually write `?\{\{sliceUatPath\}\}`?/i);
@@ -398,3 +403,141 @@ test("reactive-execute prompt references tool calls instead of checkbox updates"
   assert.doesNotMatch(prompt, /checkbox edits/);
   assert.match(prompt, /completion tool calls/);
 });
+
+// ─── Project-shape classifier + 3-or-4-options-with-Other-hatch contract ──
+
+test("guided-discuss-project classifies project shape and persists the verdict to PROJECT.md", () => {
+  const prompt = readPrompt("guided-discuss-project");
+  assert.match(prompt, /Classify project shape/i, "must include the classifier section");
+  assert.match(prompt, /`simple`/);
+  assert.match(prompt, /`complex`/);
+  assert.match(prompt, /Default to `complex` when uncertain/i);
+  assert.match(prompt, /## Project Shape/, "must reference the persisted PROJECT.md section");
+  assert.match(prompt, /\*\*Complexity:\*\*\s*simple/);
+  assert.match(prompt, /\*\*Complexity:\*\*\s*complex/);
+});
+
+test("guided-discuss prompts require 3-or-4 options plus Other-let-me-discuss in complex mode", () => {
+  for (const name of [
+    "guided-discuss-project",
+    "guided-discuss-milestone",
+    "guided-discuss-slice",
+  ]) {
+    const prompt = readPrompt(name);
+    assert.match(
+      prompt,
+      /3 or 4 concrete, researched options/i,
+      `${name} must require 3 or 4 grounded options in complex mode`,
+    );
+    assert.match(
+      prompt,
+      /"Other — let me discuss"/,
+      `${name} must include the "Other — let me discuss" escape hatch`,
+    );
+    assert.match(
+      prompt,
+      /grounded in (the |your |)investigation/i,
+      `${name} must require options grounded in prior investigation`,
+    );
+  }
+});
+
+test("guided-discuss-requirements scopes the 3-or-4-options rule to free-form questions only", () => {
+  const prompt = readPrompt("guided-discuss-requirements");
+  assert.match(prompt, /3 or 4 concrete, researched options/i);
+  assert.match(prompt, /"Other — let me discuss"/);
+  // Class-assignment and status questions have fixed enumerations, so the rule must exempt them.
+  assert.match(prompt, /class-assignment.*status.*exempt/i);
+});
+
+test("downstream discuss prompts read project shape verdict from PROJECT.md", () => {
+  for (const name of [
+    "guided-discuss-milestone",
+    "guided-discuss-requirements",
+    "guided-discuss-slice",
+  ]) {
+    const prompt = readPrompt(name);
+    assert.match(
+      prompt,
+      /Project Shape/,
+      `${name} must reference Project Shape from PROJECT.md`,
+    );
+    assert.match(
+      prompt,
+      /default to `complex`/i,
+      `${name} must default to complex when the verdict is missing`,
+    );
+  }
+});
+
+test("project template includes the Project Shape section so the verdict has a home", () => {
+  const template = readTemplate("project");
+  assert.match(template, /## Project Shape/);
+  assert.match(template, /\*\*Complexity:\*\*/);
+});
+
+// ─── Project shape verdict — end-to-end propagation contract (F7 / #5267) ──
+// The verdict is propagated from discuss-project to downstream stages via
+// PROJECT.md text only, with no parser. These tests pin the round-trip:
+// the format the upstream stage is told to write must be discoverable by
+// the regex pattern the downstream stage is told to look for.
+
+/**
+ * Render the project.md template with a concrete complexity verdict so we
+ * can assert on a realistic PROJECT.md (the placeholder is filled the way
+ * an LLM following the prompt would fill it).
+ */
+function renderProjectMd(verdict: "simple" | "complex"): string {
+  return readTemplate("project")
+    .replace("{{simple | complex}}", verdict)
+    .replace("{{one-line rationale citing the signals that decided it}}", "Test fixture rationale.");
+}
+
+test("project shape verdict survives the discuss-project → discuss-milestone round trip", () => {
+  for (const verdict of ["simple", "complex"] as const) {
+    const projectMd = renderProjectMd(verdict);
+
+    // Upstream contract: the PROJECT.md the discuss-project prompt writes
+    // must contain the section header and the bolded `**Complexity:** <verdict>`
+    // marker that downstream stages are told to grep for.
+    assert.match(projectMd, /## Project Shape/, `rendered ${verdict} PROJECT.md must keep the section header`);
+    const complexityMarker = new RegExp(`\\*\\*Complexity:\\*\\*\\s*${verdict}\\b`);
+    assert.match(
+      projectMd,
+      complexityMarker,
+      `rendered ${verdict} PROJECT.md must expose the bolded Complexity marker the downstream regex looks for`,
+    );
+
+    // Downstream contract: discuss-milestone, discuss-requirements, and
+    // discuss-slice must each instruct the LLM to look at the same section
+    // header AND the same `**Complexity:**` marker the template writes.
+    // Without this, the upstream verdict is silently dropped.
+    for (const downstream of ["guided-discuss-milestone", "guided-discuss-requirements", "guided-discuss-slice"]) {
+      const prompt = readPrompt(downstream);
+      assert.match(
+        prompt,
+        /## Project Shape/,
+        `${downstream} must direct the LLM to the same section header the template writes`,
+      );
+      assert.match(
+        prompt,
+        /\*\*Complexity:\*\*/,
+        `${downstream} must direct the LLM to the same **Complexity:** marker the template writes`,
+      );
+    }
+  }
+});
+
+test("downstream discuss prompts default to complex when PROJECT.md lacks the verdict", () => {
+  // Safe-by-default: if upstream omits the section (existing projects, LLM
+  // drift, future template change), each downstream stage must explicitly
+  // fall back to complex so behavior is conservative rather than stuck.
+  for (const downstream of ["guided-discuss-milestone", "guided-discuss-requirements", "guided-discuss-slice"]) {
+    const prompt = readPrompt(downstream);
+    assert.match(
+      prompt,
+      /default to `complex`/i,
+      `${downstream} must default to complex when the upstream verdict is missing`,
+    );
+  }
+});