gsd-pi 2.77.0-dev.eaa4973bc → 2.78.0-dev.aeeb2ca00

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

@@ -1,97 +1,81 @@
-import { readFileSync } from "node:fs";
+/**
+ * zombie-gsd-state.test.ts — #2942
+ *
+ * A partially initialized `.gsd/` (symlink exists but neither `PREFERENCES.md`
+ * nor `milestones/` is present) previously caused the init-wizard gate in
+ * `showSmartEntry` to be skipped. The fix introduces
+ * `hasGsdBootstrapArtifacts`, which requires at least one bootstrap artifact
+ * to be present before treating the project as initialized.
+ *
+ * These tests exercise that helper directly over synthetic filesystems and
+ * injected predicates — replacing the old source-grep assertions that only
+ * verified the function's *text* shape.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
-
-import { createTestContext } from "./test-helpers.ts";
-
-const { assertTrue, assertMatch, assertNoMatch, report } = createTestContext();
-
-// ─── #2942: Zombie .gsd state skips init wizard ─────────────────────────────
-//
-// A partially initialized .gsd/ (symlink exists but no PREFERENCES.md or
-// milestones/) causes the init wizard gate in showSmartEntry to be skipped,
-// resulting in an uninitialized project session.
-
-console.log("\n=== #2942: zombie .gsd state must not skip init wizard ===");
-
-// ── guided-flow.ts — init wizard gate must check bootstrap completeness ──
-
-const guidedFlowSrc = readFileSync(
-  join(import.meta.dirname, "..", "guided-flow.ts"),
-  "utf-8",
-);
-
-// Find the showSmartEntry function
-const smartEntryIdx = guidedFlowSrc.indexOf("export async function showSmartEntry(");
-assertTrue(smartEntryIdx >= 0, "guided-flow.ts defines showSmartEntry");
-
-// Extract the region between showSmartEntry and the first showProjectInit call
-// This is where the init wizard gate lives.
-const afterSmartEntry = smartEntryIdx >= 0 ? guidedFlowSrc.slice(smartEntryIdx, smartEntryIdx + 3000) : "";
-
-// The gate must NOT be a bare `!existsSync(gsdRoot(basePath))` check.
-// It must also verify that bootstrap artifacts (PREFERENCES.md or milestones/) exist.
-assertTrue(
-  afterSmartEntry.includes("PREFERENCES.md") || afterSmartEntry.includes("PREFERENCES"),
-  "init wizard gate checks for PREFERENCES.md, not just .gsd/ existence (#2942)",
-);
-
-assertTrue(
-  afterSmartEntry.includes("milestones"),
-  "init wizard gate checks for milestones/ directory, not just .gsd/ existence (#2942)",
-);
-
-// The init wizard should be shown when .gsd/ exists but has no bootstrap artifacts.
-// The old code was: if (!existsSync(gsdRoot(basePath))) { ... showProjectInit ... }
-// The fix should use a compound check so zombie states trigger the wizard.
-// Verify we no longer have the bare existence check as the sole gate.
-
-// Find the specific init wizard gate pattern — the detection preamble block.
-const detectionPreambleIdx = afterSmartEntry.indexOf("Detection preamble");
-const detectionRegion = detectionPreambleIdx >= 0
-  ? afterSmartEntry.slice(detectionPreambleIdx, detectionPreambleIdx + 600)
-  : afterSmartEntry.slice(0, 1500);
-
-// The gate condition must reference PREFERENCES.md or milestones (bootstrap artifacts)
-assertMatch(
-  detectionRegion,
-  /PREFERENCES\.md|milestones/,
-  "detection preamble gate references bootstrap artifacts, not just directory existence (#2942)",
-);
-
-// ── auto-start.ts — milestones/ dir creation must not be dead code ──────────
-
-console.log("\n=== #2942: auto-start milestones/ bootstrap not dead code ===");
-
-const autoStartSrc = readFileSync(
-  join(import.meta.dirname, "..", "auto-start.ts"),
-  "utf-8",
-);
-
-// After ensureGsdSymlink, the code that creates milestones/ must check for
-// the milestones directory specifically (not .gsd/ which ensureGsdSymlink already created).
-const symlinkIdx = autoStartSrc.indexOf("ensureGsdSymlink(base)");
-assertTrue(symlinkIdx >= 0, "auto-start.ts calls ensureGsdSymlink(base)");
-
-const afterSymlink = symlinkIdx >= 0
-  ? autoStartSrc.slice(symlinkIdx, autoStartSrc.indexOf("Initialize GitServiceImpl", symlinkIdx))
-  : "";
-
-// The milestones bootstrap must check milestones path, not gsdDir
-// Old (dead) code: if (!existsSync(gsdDir)) { mkdirSync(join(gsdDir, "milestones"), ...) }
-// Fixed code should check: if (!existsSync(milestonesPath)) or similar
-assertTrue(
-  afterSymlink.includes("milestones") && afterSymlink.includes("mkdirSync"),
-  "auto-start.ts creates milestones/ directory after ensureGsdSymlink (#2942)",
-);
-
-// The guard for milestones/ creation should NOT be `!existsSync(gsdDir)` —
-// that's dead code since ensureGsdSymlink already created gsdDir.
-// It should check for the milestones/ dir directly.
-const mkdirRegion = afterSymlink.slice(0, afterSymlink.indexOf("mkdirSync") + 200);
-assertMatch(
-  mkdirRegion,
-  /existsSync\([^)]*milestones/,
-  "milestones bootstrap checks milestones path existence, not .gsd/ (#2942)",
-);
-
-report();
+import { tmpdir } from "node:os";
+
+import { hasGsdBootstrapArtifacts } from "../detection.ts";
+
+function makeGsdDir(t: { after: (fn: () => void) => void }): string {
+  const dir = mkdtempSync(join(tmpdir(), "gsd-zombie-state-"));
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+  return dir;
+}
+
+test("#2942: missing .gsd/ directory entirely → treated as un-bootstrapped", () => {
+  assert.equal(
+    hasGsdBootstrapArtifacts("/nonexistent/path/does/not/exist/.gsd"),
+    false,
+  );
+});
+
+test("#2942: zombie .gsd/ (empty directory) must NOT count as bootstrapped", (t) => {
+  const gsd = makeGsdDir(t);
+  // Only the directory exists — neither PREFERENCES.md nor milestones/
+  assert.equal(
+    hasGsdBootstrapArtifacts(gsd),
+    false,
+    "an empty .gsd/ is a zombie state — init wizard must still run",
+  );
+});
+
+test("#2942: .gsd/ with PREFERENCES.md counts as bootstrapped", (t) => {
+  const gsd = makeGsdDir(t);
+  writeFileSync(join(gsd, "PREFERENCES.md"), "# prefs\n");
+  assert.equal(hasGsdBootstrapArtifacts(gsd), true);
+});
+
+test("#2942: .gsd/ with milestones/ directory counts as bootstrapped", (t) => {
+  const gsd = makeGsdDir(t);
+  mkdirSync(join(gsd, "milestones"));
+  assert.equal(hasGsdBootstrapArtifacts(gsd), true);
+});
+
+test("#2942: both artifacts present → bootstrapped", (t) => {
+  const gsd = makeGsdDir(t);
+  writeFileSync(join(gsd, "PREFERENCES.md"), "# prefs\n");
+  mkdirSync(join(gsd, "milestones"));
+  assert.equal(hasGsdBootstrapArtifacts(gsd), true);
+});
+
+test("#2942: injected existsFn — zombie via predicate is rejected", () => {
+  // Only the .gsd/ directory exists; artifacts are missing.
+  const existsFn = (p: string) => p === "/proj/.gsd";
+  assert.equal(hasGsdBootstrapArtifacts("/proj/.gsd", existsFn), false);
+});
+
+test("#2942: injected existsFn — PREFERENCES.md alone is enough", () => {
+  const existsFn = (p: string) =>
+    p === "/proj/.gsd" || p === "/proj/.gsd/PREFERENCES.md";
+  assert.equal(hasGsdBootstrapArtifacts("/proj/.gsd", existsFn), true);
+});
+
+test("#2942: injected existsFn — milestones/ alone is enough", () => {
+  const existsFn = (p: string) =>
+    p === "/proj/.gsd" || p === "/proj/.gsd/milestones";
+  assert.equal(hasGsdBootstrapArtifacts("/proj/.gsd", existsFn), true);
+});

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

@@ -18,6 +18,7 @@ import {
   getMilestoneSlices,
 } from "../gsd-db.js";
 import { resolveMilestonePath, clearPathCache } from "../paths.js";
+import { resolveCanonicalMilestoneRoot } from "../worktree-manager.js";
 import { saveFile, clearParseCache } from "../files.js";
 import { invalidateStateCache } from "../state.js";
 import { VALIDATION_VERDICTS, isValidMilestoneVerdict } from "../verdict-parser.js";
@@ -100,14 +101,19 @@ export async function handleValidateMilestone(
   }
 
   // ── Resolve paths and render markdown ────────────────────────────────
+  // #4761: route through the canonical-root resolver so that when a live
+  // worktree exists for this milestone, validation reads/writes the
+  // worktree's artifacts instead of stale project-root state.
   const validationMd = renderValidationMarkdown(params);
 
+  const canonicalBase = resolveCanonicalMilestoneRoot(basePath, params.milestoneId);
+
   let validationPath: string;
-  const milestoneDir = resolveMilestonePath(basePath, params.milestoneId);
+  const milestoneDir = resolveMilestonePath(canonicalBase, params.milestoneId);
   if (milestoneDir) {
     validationPath = join(milestoneDir, `${params.milestoneId}-VALIDATION.md`);
   } else {
-    const gsdDir = join(basePath, ".gsd");
+    const gsdDir = join(canonicalBase, ".gsd");
     const manualDir = join(gsdDir, "milestones", params.milestoneId);
     validationPath = join(manualDir, `${params.milestoneId}-VALIDATION.md`);
   }

package/src/resources/extensions/gsd/types.ts

@@ -695,8 +695,8 @@ export interface CompleteSliceParams {
 
 export type GateId = "Q3" | "Q4" | "Q5" | "Q6" | "Q7" | "Q8" | "MV01" | "MV02" | "MV03" | "MV04";
 export type GateScope = "slice" | "task" | "milestone";
-export type GateStatus = "pending" | "complete" | "omitted";
-export type GateVerdict = "pass" | "flag" | "omitted" | "";
+export type GateStatus = "pending" | "complete";
+export type GateVerdict = "pass" | "flag" | "omitted";
 
 export interface GateRow {
   milestone_id: string;
@@ -705,7 +705,7 @@ export interface GateRow {
   scope: GateScope;
   task_id: string;
   status: GateStatus;
-  verdict: GateVerdict;
+  verdict: GateVerdict | null;
   rationale: string;
   findings: string;
   evaluated_at: string | null;

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

@@ -0,0 +1,218 @@
+// GSD-2 — UnitContextComposer (#4782 phase 2).
+//
+// Reads a unit type's manifest and orchestrates artifact inlining through
+// a caller-provided resolver. Returns a joined context block suitable for
+// substitution into the unit's prompt template.
+//
+// Design rationale:
+//   - Pure dependency on the manifest module — no circular import with
+//     `auto-prompts.ts` where the per-artifact-key resolver lives.
+//   - Caller-supplied resolver means the composer can be unit-tested with
+//     trivial mocks; production wiring in `auto-prompts.ts` dispatches to
+//     the existing `inlineFile` / `inline*FromDb` helpers.
+//   - Null-returning resolvers are skipped silently: they model the
+//     "artifact is optional / missing / not applicable to this milestone"
+//     case. The composer never errors on a missing artifact.
+//
+// Scope: phase 2 pilot shipped `composeInlinedContext` for static-key
+// inlining. Phase 3.5 (#4924) adds the v2 surface — `composeUnitContext`
+// — which also handles excerpts, computed artifacts, and prepended blocks.
+// `composeInlinedContext` stays for backward compatibility with the
+// already-migrated simple builders.
+//
+// ─── Composer boundary invariant (#4924) ─────────────────────────────────
+//
+// The composer is allowed to:
+//   - order named sections per the manifest's declared sequence
+//   - resolve registered artifacts (static / computed / excerpt / on-demand)
+//   - apply typed policies (knowledge / memory / codebase-map / preferences)
+//
+// The composer must NOT grow:
+//   - arbitrary conditionals on unit state
+//   - loops over caller-supplied data
+//   - string templating beyond section composition (join + separator)
+//
+// Logic that needs those belongs in a typed computed-artifact builder
+// owned by the unit, not in the composer. Reviews must enforce this — it
+// is the difference between an orchestrator and a runaway DSL.
+
+import {
+  resolveManifest,
+  type ArtifactKey,
+  type BaseResolverContext,
+  type ComputedArtifactId,
+  type ComputedArtifactRegistry,
+  type UnitContextManifest,
+} from "./unit-context-manifest.js";
+
+/**
+ * Async function mapping an artifact key to its inlined-content string,
+ * or `null` when the artifact does not apply to the current milestone
+ * (missing file, empty table, etc).
+ */
+export type ArtifactResolver = (key: ArtifactKey) => Promise<string | null>;
+
+/**
+ * Produce the inlined-context portion of a unit's system prompt by
+ * walking the manifest's `artifacts.inline` list in order and calling
+ * the provided resolver for each key.
+ *
+ * Returns an empty string when the unit type has no manifest registered,
+ * so callers can guard their wiring with a simple truthy check. Unknown
+ * unit types do not error — this mirrors `resolveManifest`'s contract.
+ *
+ * The separator between inlined blocks matches the in-tree convention
+ * (`\n\n---\n\n`) so composer output slots into existing prompt templates
+ * without visible diff.
+ */
+export async function composeInlinedContext(
+  unitType: string,
+  resolveArtifact: ArtifactResolver,
+): Promise<string> {
+  const manifest: UnitContextManifest | null = resolveManifest(unitType);
+  if (!manifest) return "";
+
+  const blocks: string[] = [];
+  for (const key of manifest.artifacts.inline) {
+    const body = await resolveArtifact(key);
+    if (body !== null && body.length > 0) {
+      blocks.push(body);
+    }
+  }
+  return blocks.join("\n\n---\n\n");
+}
+
+/**
+ * Convenience helper returning the manifest's declared budget so callers
+ * can telemetry a mismatch between actual prompt size and declared budget.
+ * Returns null for unknown unit types.
+ */
+export function manifestBudgetChars(unitType: string): number | null {
+  const manifest = resolveManifest(unitType);
+  return manifest ? manifest.maxSystemPromptChars : null;
+}
+
+// ─── v2 surface (#4924) ───────────────────────────────────────────────────
+
+/**
+ * Resolver for excerpt-class artifacts. Returns the compact block body
+ * (per-unit excerpt rendering — e.g. `buildSliceSummaryExcerpt` for the
+ * complete-milestone closer) or `null` to omit. Mirrors `ArtifactResolver`
+ * shape so consumers can reuse the same registry pattern.
+ */
+export type ExcerptResolver = (key: ArtifactKey) => Promise<string | null>;
+
+/**
+ * Inputs to the v2 composer entrypoint. The base context is required;
+ * each resolver/registry is optional and absent ones are treated as
+ * "manifest declares no entries of that class for this unit."
+ */
+export interface ComposeUnitContextOptions {
+  readonly base: BaseResolverContext;
+  readonly resolveArtifact?: ArtifactResolver;
+  readonly resolveExcerpt?: ExcerptResolver;
+  readonly computed?: ComputedArtifactRegistry;
+}
+
+/**
+ * Composer output. Kept structured (rather than a single joined string)
+ * because some builders need to splice the prepend block above their own
+ * preamble while keeping the main context block in its existing position.
+ *
+ * Both fields are joined with the in-tree `\n\n---\n\n` separator. Empty
+ * string means "no content for this section" — callers branch on truthy
+ * to decide whether to render any wrapper headers.
+ */
+export interface ComposedUnitContext {
+  readonly prepend: string;
+  readonly inline: string;
+}
+
+const SECTION_SEPARATOR = "\n\n---\n\n";
+
+/**
+ * Compose all manifest-declared context for a unit type using the v2
+ * surface. Walks `prepend` first (computed-only), then the `inline` list
+ * (static keys via `resolveArtifact`), then `excerpt` (via `resolveExcerpt`),
+ * then `artifacts.computed` (via the typed registry). Order within each
+ * section follows the manifest's declared sequence.
+ *
+ * Unknown unit types return empty strings for both sections — callers can
+ * fall back to existing imperative wiring without a special case.
+ *
+ * Resolver / registry omissions: if the manifest declares an entry but no
+ * resolver / registry entry is provided, the composer skips it silently.
+ * This matches the v1 contract where a null body is a no-op, and lets
+ * partial migrations land without forcing every consumer to register
+ * every artifact class up-front.
+ */
+export async function composeUnitContext(
+  unitType: string,
+  opts: ComposeUnitContextOptions,
+): Promise<ComposedUnitContext> {
+  const manifest: UnitContextManifest | null = resolveManifest(unitType);
+  if (!manifest) return { prepend: "", inline: "" };
+
+  // Single-source `unitType`: the manifest is resolved against the
+  // function arg, but computed builders read it from `base.unitType`.
+  // If those ever diverge (caller passes one type to composeUnitContext
+  // but a different one in opts.base), the composer would silently
+  // mix one unit's manifest with another unit's computed context.
+  // Normalize here so the composer dispatches a consistent identity
+  // through to every builder.
+  const normalizedOpts: ComposeUnitContextOptions = {
+    ...opts,
+    base: { ...opts.base, unitType },
+  };
+
+  const prependBlocks = await runComputed(manifest.prepend ?? [], normalizedOpts);
+  const inlineBlocks: string[] = [];
+
+  for (const key of manifest.artifacts.inline) {
+    if (!normalizedOpts.resolveArtifact) break;
+    const body = await normalizedOpts.resolveArtifact(key);
+    if (body && body.length > 0) inlineBlocks.push(body);
+  }
+  for (const key of manifest.artifacts.excerpt) {
+    if (!normalizedOpts.resolveExcerpt) break;
+    const body = await normalizedOpts.resolveExcerpt(key);
+    if (body && body.length > 0) inlineBlocks.push(body);
+  }
+  inlineBlocks.push(...await runComputed(manifest.artifacts.computed ?? [], normalizedOpts));
+
+  return {
+    prepend: prependBlocks.join(SECTION_SEPARATOR),
+    inline: inlineBlocks.join(SECTION_SEPARATOR),
+  };
+}
+
+/**
+ * Invoke the registered builder for each declared computed id, in order.
+ * Missing registry entries (manifest declares the id but caller didn't
+ * register it) are skipped silently — see composeUnitContext rationale.
+ */
+async function runComputed(
+  ids: readonly ComputedArtifactId[],
+  opts: ComposeUnitContextOptions,
+): Promise<string[]> {
+  if (ids.length === 0 || !opts.computed) return [];
+  // Type safety lives at the registration boundary (caller-supplied
+  // `computed` is typed against ComputedArtifactInputs[K] per id). Inside
+  // the composer we only dispatch — view the registry through a widened
+  // local shape so the loop compiles when the registry is empty (which
+  // it is in the v2-contract foundation PR before any computed ids are
+  // registered, making `keyof ComputedArtifactInputs` resolve to `never`).
+  type AnyEntry = {
+    build: (inputs: unknown, base: BaseResolverContext) => Promise<string | null>;
+    inputs: unknown;
+  };
+  const registry = opts.computed as Record<string, AnyEntry | undefined>;
+  const out: string[] = [];
+  for (const id of ids) {
+    const entry = registry[id];
+    if (!entry) continue;
+    const body = await entry.build(entry.inputs, opts.base);
+    if (body && body.length > 0) out.push(body);
+  }
+  return out;
+}