gsd-pi 2.37.1 → 2.38.0-dev.4d4d14a

package/src/resources/extensions/gsd/prompts/guided-discuss-milestone.md

@@ -33,19 +33,16 @@ Ask **1–3 questions per round**. Keep each question focused on one of:
 
 After the user answers, investigate further if any answer opens a new unknown, then ask the next round.
 
-### Check-in after each round
+### Round cadence
 
-After each round of answers, ask:
+After each round of answers, decide whether you already have enough depth to write a strong context file.
 
-> "I think I have a solid picture of this milestone. Ready to wrap up and write the context file, or is there more to cover?"
-
-**If `{{structuredQuestionsAvailable}}` is `true`:** use `ask_user_questions` with options:
-- "Wrap up — write the context file" *(recommended after ~2–3 rounds)*
-- "Keep going — more to discuss"
-
-**If `{{structuredQuestionsAvailable}}` is `false`:** ask in plain text.
-
-If the user wants to keep going, keep asking. Stop when they say wrap up.
+- If not, investigate any newly-opened unknowns and continue to the next round immediately. Do **not** ask a meta "ready to wrap up?" question after every round.
+- Use a single wrap-up prompt only when you genuinely believe the depth checklist is satisfied or the user signals they want to stop.
+- **If `{{structuredQuestionsAvailable}}` is `true` and you need that wrap-up prompt:** use `ask_user_questions` with options:
+  - "Write the context file" *(recommended when depth is satisfied)*
+  - "One more pass"
+- **If `{{structuredQuestionsAvailable}}` is `false`:** ask in plain text only once you believe you are ready to write.
 
 ---
 
@@ -55,7 +52,7 @@ If the user wants to keep going, keep asking. Stop when they say wrap up.
 
 **Challenge vagueness, make abstract concrete.** When the user says something abstract ("it should be smart" / "good UX"), push for specifics.
 
-**Questions must be about the experience, not the implementation.** Never ask "what auth provider?" — ask "when someone logs in, what should that feel like?" Implementation is your job. Understanding what they want to experience is the discussion's job.
+**Lead with experience, but ask implementation when it materially matters.** Default questions should target the experience and outcome. But when implementation choices materially change scope, proof, compliance, integration, deployment, or irreversible architecture, ask them directly instead of forcing a fake UX phrasing.
 
 **Position-first framing.** Have opinions. "I'd lean toward X because Y — does that match your thinking?" is better than "what do you think about X vs Y?"
 
@@ -95,6 +92,8 @@ Before moving to the wrap-up gate, verify you have covered:
 
 If they clarify, absorb the correction and re-verify.
 
+The depth verification is the only required confirmation gate. Do not add a second "ready to proceed?" gate after it.
+
 ---
 
 ## Output

package/src/resources/extensions/gsd/prompts/guided-discuss-slice.md

@@ -1,6 +1,6 @@
 You are interviewing the user to surface behavioural, UX, and usage grey areas for slice **{{sliceId}}: {{sliceTitle}}** of milestone **{{milestoneId}}**.
 
-Your goal is **not** to settle tech stack, naming conventions, or architecture — that happens during research and planning. Your goal is to produce a context file that captures the human decisions: what this slice should feel like, how it should behave, what edge cases matter, where scope begins and ends, and what the user cares about that won't be obvious from the roadmap entry alone.
+Your goal is **not** to center the discussion on tech stack trivia, naming conventions, or speculative architecture. Your goal is to produce a context file that captures the human decisions: what this slice should feel like, how it should behave, what edge cases matter, where scope begins and ends, and what the user cares about that won't be obvious from the roadmap entry alone. If a technical choice materially changes scope, proof, or integration behavior, ask it directly and capture it.
 
 {{inlinedContext}}
 
@@ -27,17 +27,15 @@ Ask **1–3 questions per round** using `ask_user_questions`. Keep each question
 
 After the user answers, investigate further if any answer opens a new unknown, then ask the next round.
 
-### Check-in after each round
+### Round cadence
 
-After each round of answers, use `ask_user_questions` to ask:
+After each round of answers, decide whether you already have enough signal to write the slice context cleanly.
 
-> "I think I have a solid picture of this slice. Ready to wrap up and write the context file, or is there more to cover?"
-
-Options:
-- "Wrap up — write the context file" *(recommended after ~2–3 rounds)*
-- "Keep going — more to discuss"
-
-If the user wants to keep going, keep asking. Stop when they say wrap up.
+- If not, investigate any new unknowns and continue to the next round immediately. Do **not** ask a meta "ready to wrap up?" question after every round.
+- Ask a single wrap-up question only when you genuinely believe the slice is well understood or the user signals they want to stop.
+- When you do ask it, use `ask_user_questions` with:
+  - "Write the context file" *(recommended when the slice is well understood)*
+  - "One more pass"
 
 ---
 

package/src/resources/extensions/gsd/prompts/guided-resume-task.md

@@ -1 +1 @@
-Resume interrupted work. Find the continue file (`{{sliceId}}-CONTINUE.md` or `continue.md`) in slice {{sliceId}} of milestone {{milestoneId}}, then pick up from where you left off. Delete the continue file after reading it. If a `GSD Skill Preferences` block is present in system context, use it to decide which skills to load and follow during execution, without relaxing required verification or artifact rules.
+Resume interrupted work. Find the continue file (`{{sliceId}}-CONTINUE.md` or `continue.md`) in slice {{sliceId}} of milestone {{milestoneId}}, read it, and use it as the recovery contract for where to pick up. Do **not** delete the continue file immediately. Keep it until the task is successfully completed or you have written a newer summary/continue artifact that clearly supersedes it. If the resumed attempt fails again, update or replace the continue file so no recovery context is lost. If a `GSD Skill Preferences` block is present in system context, use it to decide which skills to load and follow during execution, without relaxing required verification or artifact rules.

package/src/resources/extensions/gsd/prompts/plan-slice.md

@@ -61,13 +61,14 @@ Then:
    - a concrete, action-oriented title
    - the inline task entry fields defined in the plan.md template (Why / Files / Do / Verify / Done when)
    - a matching task plan file with description, steps, must-haves, verification, inputs, and expected output
+   - **Inputs and Expected Output must list concrete backtick-wrapped file paths** (e.g. `` `src/types.ts` ``). These are machine-parsed to derive task dependencies — vague prose without paths breaks parallel execution. Every task must have at least one output file path.
    - Observability Impact section **only if the task touches runtime boundaries, async flows, or error paths** — omit it otherwise
 6. Write `{{outputPath}}`
 7. Write individual task plans in `{{slicePath}}/tasks/`: `T01-PLAN.md`, `T02-PLAN.md`, etc.
 8. **Self-audit the plan.** Walk through each check — if any fail, fix the plan files before moving on:
     - **Completion semantics:** If every task were completed exactly as written, the slice goal/demo should actually be true.
     - **Requirement coverage:** Every must-have in the slice maps to at least one task. No must-have is orphaned. If `REQUIREMENTS.md` exists, every Active requirement this slice owns maps to at least one task.
-    - **Task completeness:** Every task has steps, must-haves, verification, inputs, and expected output — none are blank or vague.
+    - **Task completeness:** Every task has steps, must-haves, verification, inputs, and expected output — none are blank or vague. Inputs and Expected Output list backtick-wrapped file paths, not prose descriptions.
     - **Dependency correctness:** Task ordering is consistent. No task references work from a later task.
     - **Key links planned:** For every pair of artifacts that must connect, there is an explicit step that wires them.
     - **Scope sanity:** Target 2–5 steps and 3–8 files per task. 10+ steps or 12+ files — must split. Each task must be completable in a single fresh context window.

package/src/resources/extensions/gsd/prompts/queue.md

@@ -36,15 +36,11 @@ Don't go deep — just enough that your next question reflects what's actually t
 - How the new work relates to existing milestones — overlap, dependencies, prerequisites
 - If `.gsd/REQUIREMENTS.md` exists: which unmet Active or Deferred requirements this queued work advances
 
-**Then use ask_user_questions** to dig into gray areas — architecture choices, scope boundaries, tech preferences, what's in vs out. 1-3 questions per round.
+**Then use ask_user_questions** to dig into gray areas — scope boundaries, proof expectations, integration choices, tech preferences when they materially matter, and what's in vs out. 1-3 questions per round.
 
 If a `GSD Skill Preferences` block is present in system context, use it to decide which skills to load and follow during discuss/planning work, but do not let it override the required discuss flow or artifact requirements.
 
-**Self-regulate:** After about 10-15 questions total (3-5 rounds), or when you feel you have a solid understanding, include a question like:
-"I think I have a good picture. Ready to queue this, or are there more things to discuss?"
-with options: "Ready to queue (Recommended)", "I have more to discuss"
-
-If the user wants to keep going, keep asking. If they're ready, proceed.
+**Self-regulate:** Do **not** ask a meta "ready to queue?" question after every round. Keep going until you have enough depth to write the context well, then use a single wrap-up prompt if needed. If the user clearly keeps adding detail instead of objecting, treat that as permission to continue.
 
 ## Existing Milestone Awareness
 
@@ -88,7 +84,7 @@ For EACH milestone you are about to write context for, investigate the codebase
 1. **Read the actual code** — for every file or module you reference in "Existing Codebase / Prior Art", read enough to confirm your assumptions about what exists, what it does, and what it doesn't do. Do not guess from memory or training data.
 2. **Check for stale assumptions** — the codebase may have changed since the user's spec was written. Verify: do the APIs you reference still exist? Have modules been refactored? Has upstream merged features that change the landscape?
 3. **Identify phantom capabilities** — for every capability you list as "existing," confirm it actually works as described. Look for: functions that exist but are never called, fields that are set but never read, features that are piped but never connected.
-4. **Note what you found** — include verified findings in the context file's "Existing Codebase / Prior Art" section with "verified against v{version}" annotations.
+4. **Note what you found** — include verified findings in the context file's "Existing Codebase / Prior Art" section with annotations like "verified against current codebase state" or an actual concrete version/commit only if you truly have one.
 
 ### Step 2: Per-Milestone Depth Verification
 
@@ -103,7 +99,7 @@ This triggers the per-milestone write-gate. The question should present:
 - Key technical assumptions you verified (or couldn't verify)
 - Any risks or unknowns the investigation surfaced
 
-The user confirms or corrects before you write. One depth verification per milestone — not one for all milestones combined.
+The user confirms or corrects before you write. One depth verification per milestone — not one for all milestones combined. This is the required write-gate; do not add extra "ready to proceed?" prompts around it once you have enough signal.
 
 **If you skip this step, the system will block the CONTEXT.md write and return an error telling you to complete verification first.**
 

package/src/resources/extensions/gsd/prompts/reactive-execute.md

@@ -0,0 +1,44 @@
+# Reactive Task Execution — Parallel Dispatch
+
+**Working directory:** `{{workingDirectory}}`
+**Milestone:** {{milestoneId}} — {{milestoneTitle}}
+**Slice:** {{sliceId}} — {{sliceTitle}}
+
+## Mission
+
+You are executing **multiple tasks in parallel** for this slice. The task graph below shows which tasks are ready for simultaneous execution based on their input/output dependencies.
+
+**Critical rule:** Use the `subagent` tool in **parallel mode** to dispatch all ready tasks simultaneously. Each subagent gets a full `execute-task` prompt and is responsible for its own implementation, verification, task summary, and checkbox updates. The parent batch agent orchestrates, verifies, and records failures only when a dispatched task failed before it could leave its own summary behind.
+
+## Task Dependency Graph
+
+{{graphContext}}
+
+## Ready Tasks for Parallel Dispatch
+
+{{readyTaskCount}} tasks are ready for parallel execution:
+
+{{readyTaskList}}
+
+## Execution Protocol
+
+1. **Dispatch all ready tasks** using `subagent` in parallel mode. Each subagent prompt is provided below.
+2. **Wait for all subagents** to complete.
+3. **Verify each dispatched task's outputs** — check that expected files were created/modified, that verification commands pass where applicable, and that each task wrote its own `T##-SUMMARY.md`.
+4. **Do not rewrite successful task summaries or duplicate checkbox edits.** Treat a subagent-written summary as authoritative for that task.
+5. **If a failed task produced no summary, write a recovery summary for that task** with `blocker_discovered: true`, clear failure details, and leave the task unchecked so replan/retry has an authoritative record.
+6. **Preserve successful sibling tasks exactly as they landed.** Do not roll back good work because another parallel task failed.
+7. **Do NOT create a batch commit.** The surrounding unit lifecycle owns commits; this parent batch agent should not invent a second commit layer.
+8. **Report the batch outcome** — which tasks succeeded, which failed, and any output collisions or dependency surprises.
+
+If any subagent fails:
+- Keep successful task summaries and checkbox updates as-is
+- Write a failure summary only when the failed task did not leave one behind
+- Do not silently discard or overwrite another task's outputs
+- The orchestrator will handle re-dispatch or replanning on the next iteration
+
+## Subagent Prompts
+
+{{subagentPrompts}}
+
+{{inlinedTemplates}}

package/src/resources/extensions/gsd/prompts/run-uat.md

@@ -18,32 +18,47 @@ If a `GSD Skill Preferences` block is present in system context, use it to decid
 
 **UAT file:** `{{uatPath}}`
 **Result file to write:** `{{uatResultPath}}`
+**Detected UAT mode:** `{{uatType}}`
 
-You are the test runner. Execute every check defined in `{{uatPath}}` directly:
+You are the UAT runner. Execute every check defined in `{{uatPath}}` as deeply as this mode truthfully allows. Do not collapse live or subjective checks into cheap artifact checks just to get a PASS.
+
+### Automation rules by mode
+
+- `artifact-driven` — verify with shell commands, scripts, file reads, and artifact structure checks.
+- `live-runtime` — exercise the real runtime path. Start or connect to the app/service if needed, use browser/runtime/network checks, and verify observable behavior.
+- `mixed` — run all automatable artifact-driven and live-runtime checks. Separate any remaining human-only checks explicitly.
+- `human-experience` — automate setup, preconditions, screenshots, logs, and objective checks, but do **not** invent subjective PASS results. Mark taste-based, experiential, or purely human-judgment checks as `NEEDS-HUMAN` and use an overall verdict of `PARTIAL` unless every required check was objective and passed.
+
+### Evidence tools
+
+Choose the lightest tool that proves the check honestly:
 
 - Run shell commands with `bash`
 - Run `grep` / `rg` checks against files
-- Run `node` / script invocations
+- Run `node` / other script invocations
 - Read files and verify their contents
 - Check that expected artifacts exist and have correct structure
+- For live/runtime/UI checks, exercise the real flow in the browser when applicable and inspect runtime/network/console state
+- When a check cannot be honestly automated, gather the best objective evidence you can and mark it `NEEDS-HUMAN`
 
 For each check, record:
 - The check description (from the UAT file)
+- The evidence mode used: `artifact`, `runtime`, or `human-follow-up`
 - The command or action taken
 - The actual result observed
-- PASS or FAIL verdict
+- `PASS`, `FAIL`, or `NEEDS-HUMAN`
 
 After running all checks, compute the **overall verdict**:
-- `PASS` — all checks passed
+- `PASS` — all required checks passed and no human-only checks remain
 - `FAIL` — one or more checks failed
-- `PARTIAL` — some checks passed, some failed or were skipped
+- `PARTIAL` — some checks passed, but one or more checks were skipped, inconclusive, or still require human judgment
 
 Write `{{uatResultPath}}` with:
 
 ```markdown
 ---
 sliceId: {{sliceId}}
-uatType: artifact-driven
+uatType: {{uatType}}
 verdict: PASS | FAIL | PARTIAL
 date: <ISO 8601 timestamp>
 ---
@@ -52,9 +67,9 @@ date: <ISO 8601 timestamp>
 
 ## Checks
 
-| Check | Result | Notes |
-|-------|--------|-------|
-| <check description> | PASS / FAIL | <observed output or reason> |
+| Check | Mode | Result | Notes |
+|-------|------|--------|-------|
+| <check description> | artifact / runtime / human-follow-up | PASS / FAIL / NEEDS-HUMAN | <observed output, evidence, or reason> |
 
 ## Overall Verdict
 
@@ -62,7 +77,7 @@ date: <ISO 8601 timestamp>
 
 ## Notes
 
-<any additional context, errors encountered, or follow-up items>
+<any additional context, errors encountered, screenshots/logs gathered, or manual follow-up still required>
 ```
 
 ---

package/src/resources/extensions/gsd/prompts/workflow-start.md

@@ -14,7 +14,7 @@ You are executing a **{{templateName}}** workflow (template: `{{templateId}}`).
 
 ## Workflow Definition
 
-Follow the workflow defined below. Execute each phase in order, completing one before moving to the next. At each phase gate, confirm with the user before proceeding.
+Follow the workflow defined below. Execute each phase in order, completing one before moving to the next. For low and medium complexity workflows, keep moving by default — pause only at true decision gates (user must choose between materially different directions, outward-facing actions need approval, or the workflow explicitly requires a human checkpoint). For high complexity workflows, confirm at phase transitions unless the workflow explicitly marks a gate as skip-safe.
 
 {{workflowContent}}
 
@@ -24,5 +24,5 @@ Follow the workflow defined below. Execute each phase in order, completing one b
 2. **Artifact discipline.** If an artifact directory is specified, write all planning/summary documents there.
 3. **Atomic commits.** Commit working code after each meaningful change. Use conventional commit format: `<type>(<scope>): <description>`.
 4. **Verify before shipping.** Run the project's test suite and build before marking the workflow complete.
-5. **Gate between phases.** After each phase, summarize what was done and ask the user to confirm before moving to the next phase.
+5. **Decision gates, not ceremony.** After each phase, summarize what changed. For low/medium complexity, ask for confirmation only when the next phase depends on a real user choice or external approval. For high complexity, confirm before proceeding to each new phase.
 6. **Stay focused.** This is a {{complexity}}-complexity workflow. Match your ceremony level to the task — don't over-engineer or under-deliver.

package/src/resources/extensions/gsd/reactive-graph.ts

@@ -0,0 +1,289 @@
+/**
+ * Reactive Task Graph — derives dependency edges from task plan IO signatures.
+ *
+ * Pure functions that build a DAG from task IO intersections and resolve
+ * which tasks are currently ready for parallel dispatch. Used by the
+ * reactive-execute dispatch path (ADR-004).
+ *
+ * Graph derivation and resolution functions are pure (no filesystem access).
+ * The `loadSliceTaskIO` loader at the bottom is the only async/IO function.
+ */
+
+import type { TaskIO, DerivedTaskNode, ReactiveExecutionState } from "./types.js";
+import { loadFile, parsePlan, parseTaskPlanIO } from "./files.js";
+import { resolveTasksDir, resolveTaskFiles } from "./paths.js";
+import { join } from "node:path";
+import { loadJsonFileOrNull, saveJsonFile } from "./json-persistence.js";
+import { existsSync, unlinkSync } from "node:fs";
+
+// ─── Graph Construction ───────────────────────────────────────────────────
+
+/**
+ * Build a dependency graph from task IO signatures.
+ *
+ * A task T_b depends on T_a when any of T_b's inputFiles appear in T_a's
+ * outputFiles. Self-references are excluded.
+ *
+ * Tasks are returned in the same order as the input array.
+ */
+export function deriveTaskGraph(tasks: TaskIO[]): DerivedTaskNode[] {
+  // Build output → producer lookup
+  const outputToProducer = new Map<string, string[]>();
+  for (const task of tasks) {
+    for (const outFile of task.outputFiles) {
+      const existing = outputToProducer.get(outFile);
+      if (existing) {
+        existing.push(task.id);
+      } else {
+        outputToProducer.set(outFile, [task.id]);
+      }
+    }
+  }
+
+  return tasks.map((task) => {
+    const deps = new Set<string>();
+    for (const inFile of task.inputFiles) {
+      const producers = outputToProducer.get(inFile);
+      if (producers) {
+        for (const pid of producers) {
+          if (pid !== task.id) deps.add(pid);
+        }
+      }
+    }
+    return {
+      ...task,
+      dependsOn: [...deps].sort(),
+    };
+  });
+}
+
+// ─── Ready Set Resolution ─────────────────────────────────────────────────
+
+/**
+ * Return task IDs whose dependencies are all in `completed`.
+ * Excludes tasks that are already done or in-flight.
+ */
+export function getReadyTasks(
+  graph: DerivedTaskNode[],
+  completed: Set<string>,
+  inFlight: Set<string>,
+): string[] {
+  return graph
+    .filter((node) => {
+      if (node.done || completed.has(node.id) || inFlight.has(node.id)) return false;
+      return node.dependsOn.every((dep) => completed.has(dep));
+    })
+    .map((node) => node.id);
+}
+
+// ─── Conflict-Free Subset Selection ──────────────────────────────────────
+
+/**
+ * Greedy selection of non-conflicting tasks up to `maxParallel`.
+ *
+ * Two tasks conflict if they share any outputFile. We also exclude tasks
+ * whose outputs overlap with `inFlightOutputs` (files being written by
+ * tasks currently in progress).
+ */
+export function chooseNonConflictingSubset(
+  readyIds: string[],
+  graph: DerivedTaskNode[],
+  maxParallel: number,
+  inFlightOutputs: Set<string>,
+): string[] {
+  const nodeMap = new Map(graph.map((n) => [n.id, n]));
+  const claimed = new Set(inFlightOutputs);
+  const selected: string[] = [];
+
+  for (const id of readyIds) {
+    if (selected.length >= maxParallel) break;
+    const node = nodeMap.get(id);
+    if (!node) continue;
+
+    // Check for output overlap with already-selected or in-flight
+    const conflicts = node.outputFiles.some((f) => claimed.has(f));
+    if (conflicts) continue;
+
+    // Claim this task's outputs
+    for (const f of node.outputFiles) claimed.add(f);
+    selected.push(id);
+  }
+
+  return selected;
+}
+
+// ─── Graph Quality Checks ─────────────────────────────────────────────────
+
+/**
+ * Returns true if any incomplete task has 0 inputFiles AND 0 outputFiles.
+ *
+ * An ambiguous graph means IO annotations are too sparse to derive reliable
+ * edges — the dispatcher should fall back to sequential execution.
+ */
+export function isGraphAmbiguous(graph: DerivedTaskNode[]): boolean {
+  return graph.some(
+    (node) =>
+      !node.done &&
+      node.inputFiles.length === 0 &&
+      node.outputFiles.length === 0,
+  );
+}
+
+/**
+ * Detect deadlock: no tasks are ready and none are in-flight, yet incomplete
+ * tasks remain. This indicates a circular dependency or impossible state.
+ */
+export function detectDeadlock(
+  graph: DerivedTaskNode[],
+  completed: Set<string>,
+  inFlight: Set<string>,
+): boolean {
+  const incomplete = graph.filter(
+    (n) => !n.done && !completed.has(n.id) && !inFlight.has(n.id),
+  );
+  if (incomplete.length === 0) return false; // all done
+  if (inFlight.size > 0) return false; // something is running, wait for it
+
+  // Nothing in flight, but incomplete tasks remain — check if any are ready
+  const ready = getReadyTasks(graph, completed, inFlight);
+  return ready.length === 0;
+}
+
+// ─── Graph Metrics ────────────────────────────────────────────────────────
+
+/** Compute summary metrics for logging. */
+export function graphMetrics(graph: DerivedTaskNode[]): {
+  taskCount: number;
+  edgeCount: number;
+  readySetSize: number;
+  ambiguous: boolean;
+} {
+  const completed = new Set(graph.filter((n) => n.done).map((n) => n.id));
+  const ready = getReadyTasks(graph, completed, new Set());
+  const edgeCount = graph.reduce((sum, n) => sum + n.dependsOn.length, 0);
+
+  return {
+    taskCount: graph.length,
+    edgeCount,
+    readySetSize: ready.length,
+    ambiguous: isGraphAmbiguous(graph),
+  };
+}
+
+// ─── IO Loader (async, filesystem) ────────────────────────────────────────
+
+/**
+ * Load TaskIO for all tasks in a slice by reading the slice plan (for done
+ * status and task IDs) and individual task plan files (for IO sections).
+ *
+ * Returns [] when the slice plan or tasks directory doesn't exist.
+ */
+export async function loadSliceTaskIO(
+  basePath: string,
+  mid: string,
+  sid: string,
+): Promise<TaskIO[]> {
+  const { resolveSliceFile } = await import("./paths.js");
+  const slicePlanPath = resolveSliceFile(basePath, mid, sid, "PLAN");
+  const planContent = slicePlanPath ? await loadFile(slicePlanPath) : null;
+  if (!planContent) return [];
+
+  const plan = parsePlan(planContent);
+  const tDir = resolveTasksDir(basePath, mid, sid);
+  if (!tDir) return [];
+
+  const results: TaskIO[] = [];
+
+  for (const taskEntry of plan.tasks) {
+    const planFiles = resolveTaskFiles(tDir, "PLAN");
+    const taskFileName = planFiles.find((f) =>
+      f.toUpperCase().startsWith(taskEntry.id.toUpperCase() + "-"),
+    );
+    if (!taskFileName) {
+      // Task plan file missing — include with empty IO (will trigger ambiguous)
+      results.push({
+        id: taskEntry.id,
+        title: taskEntry.title,
+        inputFiles: [],
+        outputFiles: [],
+        done: taskEntry.done,
+      });
+      continue;
+    }
+
+    const taskContent = await loadFile(join(tDir, taskFileName));
+    if (!taskContent) {
+      results.push({
+        id: taskEntry.id,
+        title: taskEntry.title,
+        inputFiles: [],
+        outputFiles: [],
+        done: taskEntry.done,
+      });
+      continue;
+    }
+
+    const io = parseTaskPlanIO(taskContent);
+    results.push({
+      id: taskEntry.id,
+      title: taskEntry.title,
+      inputFiles: io.inputFiles,
+      outputFiles: io.outputFiles,
+      done: taskEntry.done,
+    });
+  }
+
+  return results;
+}
+
+// ─── State Persistence ────────────────────────────────────────────────────
+
+function reactiveStatePath(basePath: string, mid: string, sid: string): string {
+  return join(basePath, ".gsd", "runtime", `${mid}-${sid}-reactive.json`);
+}
+
+function isReactiveState(data: unknown): data is ReactiveExecutionState {
+  if (!data || typeof data !== "object") return false;
+  const d = data as Record<string, unknown>;
+  return typeof d.sliceId === "string" && Array.isArray(d.completed) && Array.isArray(d.dispatched);
+}
+
+/**
+ * Load persisted reactive execution state for a slice.
+ * Returns null when no state file exists or the file is invalid.
+ */
+export function loadReactiveState(
+  basePath: string,
+  mid: string,
+  sid: string,
+): ReactiveExecutionState | null {
+  return loadJsonFileOrNull(reactiveStatePath(basePath, mid, sid), isReactiveState);
+}
+
+/**
+ * Save reactive execution state to disk.
+ */
+export function saveReactiveState(
+  basePath: string,
+  mid: string,
+  sid: string,
+  state: ReactiveExecutionState,
+): void {
+  saveJsonFile(reactiveStatePath(basePath, mid, sid), state);
+}
+
+/**
+ * Remove the reactive state file when a slice completes.
+ */
+export function clearReactiveState(
+  basePath: string,
+  mid: string,
+  sid: string,
+): void {
+  const path = reactiveStatePath(basePath, mid, sid);
+  try {
+    if (existsSync(path)) unlinkSync(path);
+  } catch {
+    // Non-fatal
+  }
+}

package/src/resources/extensions/gsd/repo-identity.ts

@@ -12,6 +12,8 @@ import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, rmSync, s
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 
+const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
+
 // ─── Repo Identity ──────────────────────────────────────────────────────────
 
 /**
@@ -90,14 +92,31 @@ function resolveGitRoot(basePath: string): string {
   }
 }
 
+/**
+ * Validate a GSD_PROJECT_ID value.
+ *
+ * Must contain only alphanumeric characters, hyphens, and underscores.
+ * Call this once at startup so the user gets immediate feedback on bad values.
+ */
+export function validateProjectId(id: string): boolean {
+  return /^[a-zA-Z0-9_-]+$/.test(id);
+}
+
 /**
  * Compute a stable identity for a repository.
  *
- * SHA-256 of `${remoteUrl}\n${resolvedRoot}`, truncated to 12 hex chars.
- * Deterministic: same repo always produces the same hash regardless of
- * which worktree the caller is inside.
+ * If `GSD_PROJECT_ID` is set, returns it directly (validation is expected
+ * to have already happened at startup via `validateProjectId`).
+ *
+ * Otherwise returns SHA-256 of `${remoteUrl}\n${resolvedRoot}`, truncated
+ * to 12 hex chars. Deterministic: same repo always produces the same hash
+ * regardless of which worktree the caller is inside.
  */
 export function repoIdentity(basePath: string): string {
+  const projectId = process.env.GSD_PROJECT_ID;
+  if (projectId) {
+    return projectId;
+  }
   const remoteUrl = getRemoteUrl(basePath);
   const root = resolveGitRoot(basePath);
   const input = `${remoteUrl}\n${root}`;
@@ -113,7 +132,7 @@ export function repoIdentity(basePath: string): string {
  * otherwise `~/.gsd/projects/<hash>`.
  */
 export function externalGsdRoot(basePath: string): string {
-  const base = process.env.GSD_STATE_DIR || join(homedir(), ".gsd");
+  const base = process.env.GSD_STATE_DIR || gsdHome;
   return join(base, "projects", repoIdentity(basePath));
 }
 

package/src/resources/extensions/gsd/resource-version.ts

@@ -11,6 +11,8 @@ import { join } from "node:path";
 import { homedir } from "node:os";
 import { resolveProjectRoot } from "./worktree.js";
 
+const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
+
 // ─── Resource Staleness ───────────────────────────────────────────────────
 
 /**
@@ -23,7 +25,7 @@ function isManifestWithVersion(data: unknown): data is { gsdVersion: string } {
 }
 
 export function readResourceVersion(): string | null {
-  const agentDir = process.env.GSD_CODING_AGENT_DIR || join(homedir(), ".gsd", "agent");
+  const agentDir = process.env.GSD_CODING_AGENT_DIR || join(gsdHome, "agent");
   const manifestPath = join(agentDir, "managed-resources.json");
   const manifest = loadJsonFileOrNull(manifestPath, isManifestWithVersion);
   return manifest?.gsdVersion ?? null;

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

@@ -31,7 +31,7 @@ import {
   gsdRoot,
 } from './paths.js';
 
-import { milestoneIdSort, findMilestoneIds } from './guided-flow.js';
+import { milestoneIdSort, findMilestoneIds } from './milestone-ids.js';
 import { nativeBatchParseGsdFiles, type BatchParsedFile } from './native-parser-bridge.js';
 
 import { join, resolve } from 'path';