gsd-pi 2.82.0-dev.c22380fc3 → 2.82.0-dev.e7a7f1ed5

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

@@ -186,7 +186,7 @@ Research is advisory, not auto-binding. Use discussion output to identify table
 
 ## Capability Contract
 
-Before writing a roadmap, produce or update `.gsd/REQUIREMENTS.md`.
+Before writing a roadmap, persist requirements with `gsd_requirement_save` or `gsd_requirement_update`, then render `.gsd/REQUIREMENTS.md` through `gsd_summary_save` with `artifact_type: "REQUIREMENTS"`.
 
 Use it as the project's explicit capability contract.
 
@@ -226,8 +226,8 @@ Directories use bare IDs. Files use ID-SUFFIX format. Titles live inside file co
 
 Once the user is satisfied, in a single pass:
 1. `mkdir -p .gsd/milestones/{{milestoneId}}/slices`
-2. Write or update `.gsd/PROJECT.md` — use the **Project** output template below. Describe what the project is, its current state, and list the milestone sequence.
-3. Write or update `.gsd/REQUIREMENTS.md` — use the **Requirements** output template below. Confirm requirement states, ownership, and traceability before roadmap creation.
+2. Call `gsd_summary_save` with `artifact_type: "PROJECT"` and full Project template content. The tool persists the DB-backed PROJECT artifact and renders `.gsd/PROJECT.md`. Describe what the project is, its current state, and list the milestone sequence.
+3. Persist requirements with `gsd_requirement_save` or `gsd_requirement_update`, then call `gsd_summary_save` with `artifact_type: "REQUIREMENTS"` so the tool renders `.gsd/REQUIREMENTS.md` from DB rows. Confirm requirement states, ownership, and traceability before roadmap creation.
 **Depth-Preservation Guidance for context.md:**
 When writing context.md, preserve the user's exact terminology, emphasis, and framing. Do not flatten nuance into generic summaries. If the user said "craft feel," write "craft feel," not "high-quality user experience." CONTEXT.md is downstream agents' only window into this conversation.
 
@@ -243,8 +243,8 @@ When writing CONTEXT.md, include discussion-layer sections: **Scope**, **Archite
 
 Before emitting the ready phrase, verify in the CURRENT turn that you have:
 
-- [ ] Written `.gsd/PROJECT.md` (step 2)
-- [ ] Written `.gsd/REQUIREMENTS.md` (step 3)
+- [ ] Called `gsd_summary_save` for the PROJECT artifact (step 2)
+- [ ] Persisted requirements and called `gsd_summary_save` for the REQUIREMENTS artifact (step 3)
 - [ ] Written `{{contextPath}}` (step 4)
 - [ ] Called `gsd_plan_milestone` (step 5)
 
@@ -270,8 +270,8 @@ Once the user confirms the milestone split:
 #### Phase 1: Shared artifacts
 
 1. For each milestone, call `gsd_milestone_generate_id`; never invent IDs. Then `mkdir -p .gsd/milestones/<ID>/slices`.
-2. Write `.gsd/PROJECT.md` — use the **Project** output template below.
-3. Write `.gsd/REQUIREMENTS.md` — use the **Requirements** output template below. Capture Active, Deferred, Out of Scope, and any already Validated requirements. Later milestones may have provisional ownership where slice plans do not exist yet.
+2. Call `gsd_summary_save` with `artifact_type: "PROJECT"` and full Project template content so the tool persists the DB-backed PROJECT artifact and renders `.gsd/PROJECT.md`.
+3. Persist requirements with `gsd_requirement_save` or `gsd_requirement_update`, then call `gsd_summary_save` with `artifact_type: "REQUIREMENTS"` so the tool renders `.gsd/REQUIREMENTS.md` from DB rows. Capture Active, Deferred, Out of Scope, and any already Validated requirements. Later milestones may have provisional ownership where slice plans do not exist yet.
 4. For any architectural or pattern decisions made during discussion, call `gsd_decision_save` — the tool auto-assigns IDs and regenerates `.gsd/DECISIONS.md` automatically.
 
 #### Phase 2: Primary milestone
@@ -344,8 +344,8 @@ For single-milestone projects, do NOT write this file.
 
 Before emitting the ready phrase, verify in the CURRENT turn that you have:
 
-- [ ] Written `.gsd/PROJECT.md` (Phase 1)
-- [ ] Written `.gsd/REQUIREMENTS.md` (Phase 1)
+- [ ] Called `gsd_summary_save` for the PROJECT artifact (Phase 1)
+- [ ] Persisted requirements and called `gsd_summary_save` for the REQUIREMENTS artifact (Phase 1)
 - [ ] Written primary-milestone `CONTEXT.md` (Phase 2)
 - [ ] Called `gsd_plan_milestone` for the primary milestone (Phase 2)
 - [ ] Written `.gsd/DISCUSSION-MANIFEST.json` with `gates_completed === total` (Phase 3)

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

@@ -1,6 +1,6 @@
 **Working directory:** `{{workingDirectory}}`. All file reads, writes, and shell commands MUST operate relative to this directory. Do NOT `cd` elsewhere. For `.gsd` files, use absolute paths rooted at `{{workingDirectory}}`, not `Glob`.
 
-Discuss the **project** as a whole: vision, users, anti-goals, constraints, and rough milestone sequence. Ask only real gray areas, then write `.gsd/PROJECT.md` with the **Project** template below. If a `GSD Skill Preferences` block exists, use it; artifact rules still apply.
+Discuss the **project** as a whole: vision, users, anti-goals, constraints, and rough milestone sequence. Ask only real gray areas, then persist the final Project template through `gsd_summary_save` with `artifact_type: "PROJECT"`. The tool renders `.gsd/PROJECT.md`; do not write the projection directly. If a `GSD Skill Preferences` block exists, use it; artifact rules still apply.
 
 This runs once before milestone discussion. Later milestones, requirements, and roadmaps depend on it.
 
@@ -34,7 +34,7 @@ After the opening answer, classify project shape as **`simple`** or **`complex`*
 
 **Default to `complex` when uncertain.** The user can override the verdict in plain text; if they do, accept it and proceed.
 
-Persist the verdict to PROJECT.md -> `## Project Shape`; downstream `discuss-requirements`, `discuss-milestone`, and `discuss-slice` read it from there.
+Persist the verdict through `gsd_summary_save` with `artifact_type: "PROJECT"` into `## Project Shape`; downstream `discuss-requirements`, `discuss-milestone`, and `discuss-slice` read the rendered projection.
 
 ### Before deeper rounds
 
@@ -95,7 +95,7 @@ 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.
 
-**CRITICAL — Confirmation gate:** Do not write final PROJECT.md until the user selects the "(Recommended)" option (structured path) or explicitly confirms (plain-text path). If the user declines, cancels, does not respond, or the tool fails, re-ask.
+**CRITICAL — Confirmation gate:** Do not persist final PROJECT content until the user selects the "(Recommended)" option (structured path) or explicitly confirms (plain-text path). If the user declines, cancels, does not respond, or the tool fails, re-ask.
 
 ---
 
@@ -104,7 +104,7 @@ The depth verification is the only required confirmation gate. Do not add a seco
 Once the user confirms depth:
 
 1. Use the **Project** output template (inlined above).
-2. Call `gsd_summary_save` with `artifact_type: "PROJECT"` and full project markdown as `content`; omit `milestone_id`. The tool writes `.gsd/PROJECT.md` and persists to DB. Preserve the user's terms and framing.
+2. Call `gsd_summary_save` with `artifact_type: "PROJECT"` and full project markdown as `content`; omit `milestone_id`. The tool persists the DB-backed PROJECT artifact and renders `.gsd/PROJECT.md`. Preserve the user's terms and framing.
 3. The `## Project Shape` section MUST contain `**Complexity:** simple` or `**Complexity:** complex` (matching the verdict you announced) plus a one-line `**Why:**` rationale. Downstream stages read this line.
 4. The `## Capability Contract` section MUST reference `.gsd/REQUIREMENTS.md` — that file does not yet exist; the next stage (`discuss-requirements`) will produce it.
 5. The `## Milestone Sequence` MUST list at least M001 with title and one-liner. Subsequent milestones may be listed as known intents; they will be elaborated in their own discuss-milestone stages.

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

@@ -1,6 +1,6 @@
 **Working directory:** `{{workingDirectory}}`. All file reads, writes, and shell commands MUST operate relative to this directory. Do NOT `cd` elsewhere. For `.gsd` files, use absolute paths rooted at `{{workingDirectory}}`, not `Glob`.
 
-Discuss **project-level requirements**. Read `.gsd/PROJECT.md` first; it is authoritative for vision, core value, anti-goals, and milestone sequence. Requirements must trace to it. Ask capability gray areas, then write `.gsd/REQUIREMENTS.md` using v2 `R###` format and the **Requirements** template.
+Discuss **project-level requirements**. Read `.gsd/PROJECT.md` first; it is the rendered project artifact for vision, core value, anti-goals, and milestone sequence. Requirements must trace to it. Ask capability gray areas, then persist requirements with `gsd_requirement_save` and render `.gsd/REQUIREMENTS.md` through `gsd_summary_save` using v2 `R###` format and the **Requirements** template.
 
 This runs once after `discuss-project` and before milestone work, creating the capability contract for milestones, slices, and verification.
 
@@ -25,7 +25,7 @@ Before your first action, print this banner verbatim in chat:
 3. If `.gsd/REQUIREMENTS.md` exists, read it as the working set.
 
 **Shape-dependent cadence:**
-- **`simple`**: one fast pass. Extract from PROJECT.md, ask 1-2 plain-text clarifiers only when class/status is ambiguous, then write REQUIREMENTS.md.
+- **`simple`**: one fast pass. Extract from PROJECT.md, ask 1-2 plain-text clarifiers only when class/status is ambiguous, then persist requirements through the DB-backed tools.
 - **`complex`**: multi-round questioning with structured 3-4-option questions where alternatives matter.
 
 ---
@@ -81,7 +81,7 @@ Before the wrap-up gate, verify: every milestone has an Active requirement; Core
 
 If they adjust, absorb and re-verify.
 
-**CRITICAL — Confirmation gate:** Do not write final REQUIREMENTS.md until explicit confirmation. Never rationalize past it.
+**CRITICAL — Confirmation gate:** Do not persist final REQUIREMENTS content until explicit confirmation. Never rationalize past it.
 
 ---
 

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

@@ -26,7 +26,7 @@ Before planning, validate roadmap assumptions against code and dependency summar
 
 {{sourceFilePaths}}
 
-If slice research is inlined, trust it. Explore enough code to confirm paths, boundaries, and verification. Executors later get only task plans, slice excerpt, and prior summaries, so put required paths, steps, inputs, and outputs in task plans.
+If slice research is inlined, trust its architectural findings, but verify every concrete file path you place in task `inputs` or `expectedOutput` against the current tree or prior/same-task outputs. Explore enough code to confirm paths, boundaries, and verification. Executors later get only task plans, slice excerpt, and prior summaries, so put required paths, steps, inputs, and outputs in task plans.
 
 {{executorContextConstraints}}
 
@@ -39,10 +39,10 @@ If slice research is inlined, trust it. Explore enough code to confirm paths, bo
 5. Define slice verification before tasks. Non-trivial slices need real tests or executable assertions; boundary contracts need contract-exercising checks. Tests must not read .gitignore/gitignored paths such as `.gsd/`, `.planning/`, or `.audits/`.
 6. Include Threat Surface (Q3), Requirement Impact (Q4), proof level, observability, integration closure, Failure Modes (Q5), Load Profile (Q6), and Negative Tests (Q7) only where applicable.
 7. Right-size tasks. Simple slices can be one task; split only when context, ownership, or verification boundaries justify it.
-8. Each task needs a concrete title, Why / Files / Do / Verify / Done when, plus task-plan description, steps, must-haves, verification, inputs, and expected output. Inputs and Expected Output must include concrete backtick-wrapped paths. Use paths relative to `{{workingDirectory}}`; do not put absolute paths to the original checkout or any directory outside `{{workingDirectory}}` in `files`, `inputs`, `expectedOutput`, or verification commands. **`expected_output` must only list files the task actually creates or overwrites on disk.** Do NOT include files the task merely reads, verifies, or tests — those belong only in `inputs`. If a task is a pure verification or test task that produces no new files, its `expected_output` may be empty or limited to test-result artifacts (e.g. a log or assertion output). A file that does not yet exist on disk and is needed as an `input` must be produced by an earlier task's `expected_output` — if no prior task creates it, add a task before this one that does.
-9. Persist with `gsd_plan_slice` using goal, successCriteria, optional proofLevel/integrationClosure/observabilityImpact, and tasks. `gsd_plan_slice` handles task persistence transactionally and renders `{{outputPath}}` plus task plans; do not call `gsd_plan_task`. The DB-backed tool is the canonical write path. Do **not** rely on direct `PLAN.md` writes as the source of truth.
+8. Each task needs the exact `gsd_plan_slice.tasks[]` shape: `taskId`, `title`, `description`, `estimate`, `files`, `verify`, `inputs`, `expectedOutput`, and optional `observabilityImpact`. `description` should contain the Why / Do / Done-when narrative. `files`, `inputs`, and `expectedOutput` must be JSON arrays of strings, even when there is only one path (for example, `"inputs": ["src/index.ts"]`, never `"inputs": "src/index.ts"`). Use paths relative to `{{workingDirectory}}`; do not put absolute paths to the original checkout or any directory outside `{{workingDirectory}}` in `files`, `inputs`, `expectedOutput`, or verification commands. **`expectedOutput` must only list files the task actually creates or overwrites on disk.** Do NOT include files the task merely reads, verifies, or tests — those belong only in `inputs`. If a task is a pure verification or test task that produces no new files, `expectedOutput` may be `[]` or limited to test-result artifacts (e.g. a log or assertion output). A file that does not yet exist on disk and is needed as an `input` must be produced by an earlier task's `expectedOutput` — if no prior task creates it, add a task before this one that does.
+9. Persist with `gsd_plan_slice` using `milestoneId`, `sliceId`, `goal`, optional `successCriteria`/`proofLevel`/`integrationClosure`/`observabilityImpact`, and `tasks`. `gsd_plan_slice` handles task persistence transactionally and renders `{{outputPath}}` plus task plans; do not call `gsd_plan_task`. The DB-backed tool is the canonical write path. Do **not** rely on direct `PLAN.md` writes as the source of truth.
 10. Self-audit before finishing: goal/demo closure, requirement coverage, locked decisions, concrete paths, dependency order, wiring, scope size, proof truthfulness, feature completeness, and quality gates. Quality gates: non-trivial slices/tasks include specific Q3-Q7 coverage where applicable.
-11. If planning creates structural decisions, append them to `.gsd/DECISIONS.md`.
+11. If planning creates structural decisions, call `gsd_decision_save` for each; the tool persists the decision and regenerates `.gsd/DECISIONS.md`.
 12. {{commitInstruction}}
 
 The slice directory already exists. Do not mkdir.

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

@@ -114,10 +114,10 @@ Once the user is satisfied, in one pass for **each** new milestone:
 
 After all milestone directories and context files are written:
 
-3. Update `.gsd/PROJECT.md` by adding new milestones to the Milestone Sequence. Keep existing entries exactly as-is; only add new lines.
-4. If `.gsd/REQUIREMENTS.md` exists and the queued work introduces new in-scope capabilities or promotes Deferred items, update it.
-5. If discussion produced decisions relevant to existing work, append to `.gsd/DECISIONS.md`.
-6. Append to `.gsd/QUEUE.md`.
+3. Refresh project state through `gsd_summary_save` with `artifact_type: "PROJECT"` and full PROJECT content that includes the new milestones in the Milestone Sequence; omit `milestone_id`.
+4. If the queued work introduces new in-scope capabilities or promotes Deferred items, persist those changes with `gsd_requirement_save` or `gsd_requirement_update`, then call `gsd_summary_save` with `artifact_type: "REQUIREMENTS"` so `.gsd/REQUIREMENTS.md` renders from DB rows.
+5. If discussion produced decisions relevant to existing work, call `gsd_decision_save` for each decision; the tool regenerates `.gsd/DECISIONS.md`.
+6. If `.gsd/QUEUE.md` is maintained, update it only as an audit projection of queued intent. Runtime queue state must come from the DB-backed milestone/context tool calls above.
 7. {{commitInstruction}}
 
 **Do NOT write roadmaps for queued milestones.**

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

@@ -64,10 +64,10 @@ Then:
 2. {{skillActivation}} Record the installed skills you expect executors to use in each task plan's `skills_used` frontmatter.
 3. Define slice-level verification: the objective stopping condition. Plan real test files with real assertions; for simple slices, executable commands are fine.
 4. For non-trivial slices, plan observability / proof level / integration closure, threat surface, and requirement impact. Omit entirely for simple slices.
-5. Decompose the slice into tasks that fit one context window each. Every task must have Why / Files / Do / Verify / Done-when, plus a task plan with description, steps, must-haves, verification, inputs (backtick-wrapped paths), and expected output (backtick-wrapped paths).
+5. Decompose the slice into tasks that fit one context window each. Every task passed to `gsd_plan_slice` must use the exact keys `taskId`, `title`, `description`, `estimate`, `files`, `verify`, `inputs`, `expectedOutput`, and optional `observabilityImpact`. Put Why / Do / Done-when detail in `description`. `files`, `inputs`, and `expectedOutput` must be JSON arrays of strings, even for one path (for example, `"expectedOutput": ["src/index.ts"]`, never `"expectedOutput": "src/index.ts"`).
 6. **Persist planning state through `gsd_plan_slice`.** Call it with the full payload. The tool writes to the DB and renders `{{outputPath}}` and `{{slicePath}}/tasks/T##-PLAN.md` automatically. Do NOT rely on direct `PLAN.md` writes.
 7. **Self-audit the plan.** If every task were completed exactly as written, the slice goal/demo should be true. Every must-have maps to a task. Inputs and Expected Output are backtick-wrapped file paths.
-8. If refinement produced structural decisions that diverge from the sketch, append them to `.gsd/DECISIONS.md`.
+8. If refinement produced structural decisions that diverge from the sketch, call `gsd_decision_save` for each; the tool persists the decision and regenerates `.gsd/DECISIONS.md`.
 9. {{commitInstruction}}
 
 The slice directory and tasks/ subdirectory already exist. Do NOT mkdir.

package/src/resources/extensions/gsd/prompts/rewrite-docs.md

@@ -23,7 +23,7 @@ An override was issued by the user that changes a fundamental decision or approa
    - For DECISIONS.md: append a new decision entry documenting the override and why. Do NOT delete prior decisions — mark them as superseded with a note.
    - For slice plans (S##-PLAN.md): update Goal, Demo, and Verification sections if affected. Update Files Likely Touched if the override changes scope. Do NOT modify completed task entries.
    - For REQUIREMENTS.md: update requirement descriptions if the override changes what "done" means, but do not remove requirements.
-   - For PROJECT.md: update if the override changes project-level facts.
+   - For PROJECT.md: do not edit the projection directly. If the override changes project-level facts, persist the revised Project content through `gsd_summary_save` with `artifact_type: "PROJECT"` so the DB remains authoritative.
    - Milestone context files are reference only — do not modify them.
 4. Mark all active overrides as resolved: change `**Scope:** active` to `**Scope:** resolved` in `{{overridesPath}}`
 5. Do not commit manually — the system auto-commits your changes after this unit completes.

package/src/resources/extensions/gsd/queue-reorder-ui.ts

@@ -43,6 +43,7 @@ export async function showQueueReorder(
     const items = [...pending];
     let cursor = 0;
     let grabbed = false;
+    let scrollOffset = 0;
     let cachedLines: string[] | undefined;
     let validation: DependencyValidation;
 
@@ -154,8 +155,10 @@ export async function showQueueReorder(
 
       const ui = makeUI(theme, width);
       const lines: string[] = [];
+      const queueRows: string[] = [];
       const push = (...rows: string[][]) => { for (const r of rows) lines.push(...r); };
       const add = (s: string) => truncateToWidth(s, width);
+      let cursorQueueRow = 0;
 
       const headerText = grabbed ? "  Queue Reorder — Moving Item" : "  Queue Reorder";
       push(ui.bar(), ui.blank(), ui.header(headerText), ui.blank());
@@ -188,11 +191,13 @@ export async function showQueueReorder(
         const label = item.title && item.title !== item.id ? `${item.id}  ${item.title}` : item.id;
 
         if (isCursor && grabbed) {
-          lines.push(add(`  ${theme.fg("warning", `▸▸ ${num}. ${label}`)}`));
+          cursorQueueRow = queueRows.length;
+          queueRows.push(add(`  ${theme.fg("warning", `▸▸ ${num}. ${label}`)}`));
         } else if (isCursor) {
-          lines.push(add(`  ${theme.fg("accent", `${GLYPH.cursor} ${num}. ${label}`)}`));
+          cursorQueueRow = queueRows.length;
+          queueRows.push(add(`  ${theme.fg("accent", `${GLYPH.cursor} ${num}. ${label}`)}`));
         } else {
-          lines.push(add(`    ${theme.fg("text", `${num}. ${label}`)}`));
+          queueRows.push(add(`    ${theme.fg("text", `${num}. ${label}`)}`));
         }
 
         // depends_on annotations
@@ -201,36 +206,37 @@ export async function showQueueReorder(
           if (completedIds.has(dep)) continue;
           const pairKey = `${item.id}:${dep}`;
           if (violatedPairs.has(pairKey)) {
-            lines.push(add(`       ${theme.fg("warning", `${GLYPH.statusWarning} depends_on: ${dep} — auto-removed on confirm`)}`));
+            queueRows.push(add(`       ${theme.fg("warning", `${GLYPH.statusWarning} depends_on: ${dep} — auto-removed on confirm`)}`));
           } else if (redundantPairs.has(pairKey)) {
-            lines.push(add(`       ${theme.fg("dim", `↳ depends_on: ${dep} (redundant)`)}`));
+            queueRows.push(add(`       ${theme.fg("dim", `↳ depends_on: ${dep} (redundant)`)}`));
           } else {
-            lines.push(add(`       ${theme.fg("dim", `↳ depends_on: ${dep}`)}`));
+            queueRows.push(add(`       ${theme.fg("dim", `↳ depends_on: ${dep}`)}`));
           }
         }
 
         // Missing deps
         for (const v of validation.violations.filter(v => v.milestone === item.id && v.type === 'missing_dep')) {
-          lines.push(add(`       ${theme.fg("error", `${GLYPH.statusWarning} depends_on: ${v.dependsOn} (does not exist)`)}`));
+          queueRows.push(add(`       ${theme.fg("error", `${GLYPH.statusWarning} depends_on: ${v.dependsOn} (does not exist)`)}`));
         }
       }
 
       // Removed deps feedback
+      const trailingLines: string[] = [];
       if (removedDeps.length > 0) {
-        push(ui.blank());
+        trailingLines.push(...ui.blank());
         for (const r of removedDeps) {
-          lines.push(add(`  ${theme.fg("success", `${GLYPH.statusDone} Removed: ${r.milestone} depends_on ${r.dep}`)}`));
+          trailingLines.push(add(`  ${theme.fg("success", `${GLYPH.statusDone} Removed: ${r.milestone} depends_on ${r.dep}`)}`));
         }
       }
 
       // Circular warning
       const circ = validation.violations.find(v => v.type === 'circular');
       if (circ) {
-        push(ui.blank());
-        lines.push(add(`  ${theme.fg("error", `${GLYPH.statusWarning} ${circ.message}`)}`));
+        trailingLines.push(...ui.blank());
+        trailingLines.push(add(`  ${theme.fg("error", `${GLYPH.statusWarning} ${circ.message}`)}`));
       }
 
-      push(ui.blank());
+      trailingLines.push(...ui.blank());
 
       // Hints — context-sensitive based on grab state
       const hints: string[] = [];
@@ -250,7 +256,19 @@ export async function showQueueReorder(
       }
       hints.push("esc");
 
-      push(ui.hints(hints), ui.bar());
+      trailingLines.push(...ui.hints(hints), ...ui.bar());
+
+      const maxOverlayRows = Math.max(10, process.stdout.rows ? Math.floor(process.stdout.rows * 0.8) : 24);
+      const availableQueueRows = Math.max(1, maxOverlayRows - lines.length - trailingLines.length);
+      const maxScroll = Math.max(0, queueRows.length - availableQueueRows);
+      if (cursorQueueRow < scrollOffset) {
+        scrollOffset = cursorQueueRow;
+      } else if (cursorQueueRow >= scrollOffset + availableQueueRows) {
+        scrollOffset = cursorQueueRow - availableQueueRows + 1;
+      }
+      scrollOffset = Math.min(Math.max(scrollOffset, 0), maxScroll);
+
+      lines.push(...queueRows.slice(scrollOffset, scrollOffset + availableQueueRows), ...trailingLines);
 
       cachedLines = lines;
       return lines;

package/src/resources/extensions/gsd/smart-entry-routing.ts

@@ -0,0 +1,77 @@
+// GSD-2 — Smart entry routing decisions.
+// Pure route selection for /gsd guided wizard choices.
+
+export type SmartEntryIsolationMode = "worktree" | "branch" | "none";
+
+export type ActiveTaskChoice =
+  | "execute"
+  | "auto"
+  | "status"
+  | "milestone_actions";
+
+export type ActiveTaskRoute =
+  | {
+      kind: "auto-bootstrap";
+      verboseMode: false;
+      options?: {
+        step?: true;
+        milestoneLock?: string;
+      };
+    }
+  | {
+      kind: "guided-dispatch";
+      unitType: "execute-task";
+    }
+  | {
+      kind: "status";
+    }
+  | {
+      kind: "milestone-actions";
+    };
+
+export function resolveGuidedExecuteLaunchMode(
+  isolationMode: SmartEntryIsolationMode,
+): "auto-step" | "guided-dispatch" {
+  return isolationMode === "worktree" ? "auto-step" : "guided-dispatch";
+}
+
+export function resolveActiveTaskChoiceRoute(input: {
+  choice: ActiveTaskChoice;
+  isolationMode: SmartEntryIsolationMode;
+  milestoneId: string;
+}): ActiveTaskRoute {
+  if (input.choice === "auto") {
+    return {
+      kind: "auto-bootstrap",
+      verboseMode: false,
+    };
+  }
+
+  if (input.choice === "execute") {
+    if (resolveGuidedExecuteLaunchMode(input.isolationMode) === "auto-step") {
+      return {
+        kind: "auto-bootstrap",
+        verboseMode: false,
+        options: {
+          step: true,
+          milestoneLock: input.milestoneId,
+        },
+      };
+    }
+
+    return {
+      kind: "guided-dispatch",
+      unitType: "execute-task",
+    };
+  }
+
+  if (input.choice === "status") {
+    return { kind: "status" };
+  }
+
+  if (input.choice === "milestone_actions") {
+    return { kind: "milestone-actions" };
+  }
+
+  throw new Error(`Invalid ActiveTaskChoice: ${input.choice}`);
+}

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

@@ -23,6 +23,7 @@ import {
 } from "../../native-git-bridge.js";
 import type { GSDState } from "../../types.js";
 import { logError, logWarning } from "../../workflow-logger.js";
+import { isGsdWorktreePath } from "../../worktree-root.js";
 import type { DriftContext, DriftHandler, DriftRecord } from "../types.js";
 
 export type MergeReconcileResult = "clean" | "reconciled" | "blocked";
@@ -46,7 +47,13 @@ function resolveGitDir(basePath: string): string {
       return isAbsolute(gitDir) ? gitDir : resolve(basePath, gitDir);
     }
   } catch (err) {
-    logWarning("recovery", `gitdir resolution failed: ${getErrorMessage(err)}`);
+    const message = getErrorMessage(err);
+    logWarning("recovery", `gitdir resolution failed: ${message}`);
+    if (isGsdWorktreePath(basePath)) {
+      throw new Error(
+        `Worktree integrity failure: ${basePath} is not a valid git worktree (git rev-parse failed: ${message.split("\n")[0]}). Repair or recreate the worktree before retrying.`,
+      );
+    }
   }
 
   return join(basePath, ".git");

package/src/resources/extensions/gsd/state-reconciliation/drift/project-md.ts

@@ -1,14 +1,13 @@
 // Project/App: GSD-2
 // File Purpose: ADR-017 unregistered-milestone drift handler. Detects
 // milestones whose on-disk directory has meaningful content (ROADMAP/
-// CONTEXT/SUMMARY) but no DB row, then runs the markdown importer to
-// reconcile. PROJECT.md is the human-facing index — the importer's source
-// of truth is the .gsd/milestones/ directory tree.
+// CONTEXT/SUMMARY) but no DB row, then fails closed with an explicit recovery
+// instruction. Markdown hierarchy import is reserved for operator-controlled
+// migration/recovery commands, not automatic runtime reconciliation.
 
 import { existsSync } from "node:fs";
 
 import { getMilestone, isDbAvailable } from "../../gsd-db.js";
-import { migrateHierarchyToDb } from "../../md-importer.js";
 import { findMilestoneIds } from "../../milestone-ids.js";
 import { resolveMilestoneFile } from "../../paths.js";
 import type { GSDState } from "../../types.js";
@@ -46,20 +45,18 @@ export function detectUnregisteredMilestoneDrift(
 }
 
 /**
- * Repair: invoke the markdown importer. migrateHierarchyToDb walks the same
- * findMilestoneIds list the detector uses and INSERTs OR IGNOREs every
- * missing milestone (and its slices/tasks) — idempotent under cap=2 retry.
- *
- * Note: even though we receive one record at a time, the importer is a
- * project-wide operation. Repeated invocation across multiple drift records
- * in the same pass is wasteful but safe; a future optimization could
- * coalesce by checking whether the importer has already run this pass.
+ * Repair intentionally fails closed. The project-root DB is authoritative at
+ * runtime; markdown-only milestones must be imported through an explicit
+ * migration/recovery command so operators opt into changing canonical state.
  */
 export function repairUnregisteredMilestone(
-  _record: UnregisteredMilestoneDrift,
-  ctx: DriftContext,
+  record: UnregisteredMilestoneDrift,
+  _ctx: DriftContext,
 ): void {
-  migrateHierarchyToDb(ctx.basePath);
+  throw new Error(
+    `Milestone ${record.milestoneId} exists only as markdown projection. ` +
+      "Runtime reconciliation will not import markdown into the authoritative DB; run explicit GSD recovery/migration if this markdown should repopulate the database.",
+  );
 }
 
 export const unregisteredMilestoneHandler: DriftHandler<UnregisteredMilestoneDrift> = {

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

@@ -1,8 +1,8 @@
 // Project/App: GSD-2
 // File Purpose: ADR-017 roadmap-divergence drift handler. Detects mismatches
-// between ROADMAP.md (parsed slice sequence + depends declarations) and the
-// DB slice rows for that milestone, then reconciles via the markdown
-// importer plus an explicit junction-table sync.
+// between ROADMAP.md (parsed slice sequence, depends declarations, and
+// checkboxes) and the DB slice rows for that milestone, then re-renders the
+// ROADMAP projection from the authoritative DB rows.
 
 import { existsSync, readFileSync } from "node:fs";
 
@@ -10,12 +10,12 @@ import {
   getMilestone,
   getMilestoneSlices,
   isDbAvailable,
-  syncSliceDependencies,
 } from "../../gsd-db.js";
-import { migrateHierarchyToDb } from "../../md-importer.js";
+import { renderRoadmapFromDb } from "../../markdown-renderer.js";
 import { findMilestoneIds } from "../../milestone-ids.js";
 import { parseRoadmap } from "../../parsers-legacy.js";
 import { resolveMilestoneFile } from "../../paths.js";
+import { isClosedStatus } from "../../status-guards.js";
 import type { GSDState } from "../../types.js";
 import type { DriftContext, DriftHandler, DriftRecord } from "../types.js";
 
@@ -46,14 +46,20 @@ function milestoneHasDivergence(
 
   const dbSlices = getMilestoneSlices(milestoneId);
   const dbSliceMap = new Map(dbSlices.map((s) => [s.id, s]));
+  const roadmapSliceIds = new Set<string>();
 
   for (let i = 0; i < roadmap.slices.length; i++) {
     const roadmapSlice = roadmap.slices[i]!;
+    roadmapSliceIds.add(roadmapSlice.id);
     const expectedSequence = i + 1;
     const dbSlice = dbSliceMap.get(roadmapSlice.id);
     if (!dbSlice) return true; // Roadmap has a slice the DB doesn't.
     if (dbSlice.sequence !== expectedSequence) return true;
     if (!arraysEqual(dbSlice.depends, roadmapSlice.depends)) return true;
+    if (isClosedStatus(dbSlice.status) !== roadmapSlice.done) return true;
+  }
+  for (const dbSlice of dbSlices) {
+    if (!roadmapSliceIds.has(dbSlice.id)) return true;
   }
   return false;
 }
@@ -77,29 +83,15 @@ export function detectRoadmapDivergenceDrift(
 }
 
 /**
- * Repair a milestone's roadmap divergence:
- *   1. migrateHierarchyToDb upserts slice rows (sequence + depends JSON
- *      update via ON CONFLICT DO UPDATE).
- *   2. syncSliceDependencies updates the junction table per slice — the
- *      importer only writes the JSON column, not the relational view.
+ * Repair a milestone's roadmap divergence by regenerating the projection from
+ * DB rows. ROADMAP.md is a projection; runtime reconciliation must not import
+ * slice presence, sequence, dependencies, or checkbox state from markdown.
  */
-export function repairRoadmapDivergence(
+export async function repairRoadmapDivergence(
   record: RoadmapDivergenceDrift,
   ctx: DriftContext,
-): void {
-  migrateHierarchyToDb(ctx.basePath);
-
-  const roadmapPath = resolveMilestoneFile(ctx.basePath, record.milestoneId, "ROADMAP");
-  if (!roadmapPath || !existsSync(roadmapPath)) return;
-
-  try {
-    const roadmap = parseRoadmap(readFileSync(roadmapPath, "utf-8"));
-    for (const slice of roadmap.slices) {
-      syncSliceDependencies(record.milestoneId, slice.id, slice.depends);
-    }
-  } catch {
-    /* parse failure: detector will fire again next pass */
-  }
+): Promise<void> {
+  await renderRoadmapFromDb(ctx.basePath, record.milestoneId);
 }
 
 export const roadmapDivergenceHandler: DriftHandler<RoadmapDivergenceDrift> = {

package/src/resources/extensions/gsd/status-guards.ts

@@ -25,3 +25,16 @@ export function isDeferredStatus(status: string): boolean {
 export function isInactiveStatus(status: string): boolean {
   return isClosedStatus(status) || isDeferredStatus(status);
 }
+
+/** Returns true when a prior milestone should not block dispatch ordering. */
+export function isSkippedForDispatch(status: string): boolean {
+  return isClosedStatus(status) || status === "parked" || isDeferredStatus(status);
+}
+
+/**
+ * Returns true when a milestone is future/backlog work (not currently executing).
+ * Includes legacy/project-specific alias "planned" for compatibility.
+ */
+export function isFutureMilestoneStatus(status: string): boolean {
+  return status === "pending" || status === "queued" || status === "planned";
+}

package/src/resources/extensions/gsd/templates/plan.md

@@ -99,11 +99,11 @@
   - "Improve UI"
 
   Each task should usually include:
-  - Why: why this task exists / what part of the slice it closes
-  - Files: the main files likely touched
-  - Do: concrete implementation steps and important constraints
-  - Verify: the command, test, or runtime check that proves it worked
-  - Done when: a measurable acceptance condition
+  - description: why this task exists, concrete steps, and done-when acceptance
+  - files: JSON array of likely touched paths
+  - verify: the command, test, or runtime check that proves it worked
+  - inputs: JSON array of existing paths or prior task outputs this task consumes
+  - expectedOutput: JSON array of paths this task creates or overwrites
 
   Keep the checkbox line format exactly:
   - [ ] **T01: Title** `est:30m`
@@ -131,10 +131,13 @@
 
   Verify field rules:
   - MUST be a mechanically executable command: `npm test`, `grep -q "pattern" file`, `test -f path`
+  - MUST NOT use shell pipes, redirects, semicolons, backticks, command substitution, or output trimming
   - For content/document tasks: verify file existence, section count, YAML validity, or word count
     NOT exact phrasing, specific formulas, or "zero TBD" aspirational criteria
   - If no command can verify the output, write: "Manual review — file exists and is non-empty"
+  - BAD: `python3 -m pytest tests/ -q --tb=short 2>&1 | tail -5`
   - BAD: "Sections 3.1 and 3.2 exist with exact formulas. Zero TBD/TODO."
+  - GOOD: `python3 -m pytest tests/ -q --tb=short`
   - GOOD: `grep -c "^## " doc.md` returns >= 4 (4+ sections), `! grep -q "TBD\|TODO" doc.md`
 
   Integration closure rule:

package/src/resources/extensions/gsd/templates/task-plan.md

@@ -72,7 +72,8 @@ skills_used:
 <!-- Every input MUST be a backtick-wrapped file path. These paths are machine-parsed to
      derive task dependencies — vague descriptions without paths break dependency detection.
      For the first task in a slice with no prior task outputs, list the existing source files
-     this task reads or modifies. -->
+     this task reads or modifies.
+     Tool field: inputs must be an array of strings, e.g. ["src/index.ts"], never a single string. -->
 
 - `{{filePath}}` — {{whatThisTaskNeedsFromPriorWork}}
 
@@ -82,6 +83,7 @@ skills_used:
      or modifies. These paths are machine-parsed to derive task dependencies.
      This task should produce a real increment toward making the slice goal/demo true. A full
      slice plan should not be able to mark every task complete while the claimed slice behavior
-     still does not work at the stated proof level. -->
+     still does not work at the stated proof level.
+     Tool field: expectedOutput must be an array of strings, e.g. ["src/index.ts"], never a single string. -->
 
 - `{{filePath}}` — {{whatThisTaskCreatesOrModifies}}