gsd-pi 2.28.0 → 2.29.0-dev.2ccf3fb

package/dist/resources/extensions/gsd/prompt-ordering.ts

@@ -0,0 +1,200 @@
+/**
+ * Prompt Ordering Optimizer — reorders assembled prompt sections
+ * to maximize cache prefix stability.
+ *
+ * Identifies sections by markdown heading patterns and rearranges
+ * them so stable content appears first. Anthropic caches the last
+ * user message by prefix match, so placing static/semi-static
+ * content before dynamic content improves cache hit rates.
+ */
+
+/** Section extracted from a prompt by heading markers */
+export interface ExtractedSection {
+  heading: string;
+  content: string;
+  role: "static" | "semi-static" | "dynamic";
+}
+
+/**
+ * Known heading to role mappings for GSD prompts.
+ * Static: templates, executor constraints, system instructions
+ * Semi-static: slice plan, decisions, requirements, prior summaries, overrides
+ * Dynamic: task plan, resume state, carry-forward, verification
+ */
+const HEADING_ROLES: Record<string, "static" | "semi-static" | "dynamic"> = {
+  // Static — never changes per task
+  "Output Template": "static",
+  "Executor Context Constraints": "static",
+  "Working Directory": "static",
+  "Backing Source Artifacts": "static",
+
+  // Semi-static — changes per slice but not per task
+  "Slice Plan Excerpt": "semi-static",
+  "Decisions": "semi-static",
+  "Requirements": "semi-static",
+  "Prior Task Summaries": "semi-static",
+  "Overrides": "semi-static",
+  "Project Knowledge": "semi-static",
+  "Dependency Summaries": "semi-static",
+
+  // Dynamic — changes per task
+  "Inlined Task Plan": "dynamic",
+  "Resume State": "dynamic",
+  "Carry-Forward Context": "dynamic",
+  "Verification": "dynamic",
+  "Verification Evidence": "dynamic",
+};
+
+/**
+ * Extract the heading text from a line like "## Some Heading" or "## UNIT: Execute Task ...".
+ * Returns the full text after "## " for role lookup.
+ */
+function extractHeadingText(line: string): string {
+  return line.replace(/^##\s+/, "").trim();
+}
+
+/**
+ * Classify a heading by matching against known roles.
+ * Uses substring matching so headings like "## UNIT: Execute Task T1.1" don't match
+ * but "## Inlined Task Plan" does. Unknown headings default to "dynamic".
+ */
+function classifyHeading(heading: string): "static" | "semi-static" | "dynamic" {
+  for (const [key, role] of Object.entries(HEADING_ROLES)) {
+    if (heading === key || heading.startsWith(key)) {
+      return role;
+    }
+  }
+  return "dynamic";
+}
+
+/**
+ * Split a prompt into sections at ## heading boundaries.
+ * Sub-headings (### and deeper) stay with their parent ## section.
+ * Returns a preamble (content before first ##) and an array of sections.
+ */
+function splitSections(prompt: string): { preamble: string; sections: ExtractedSection[] } {
+  const lines = prompt.split("\n");
+  let preamble = "";
+  const sections: ExtractedSection[] = [];
+  let currentHeading = "";
+  let currentContent: string[] = [];
+
+  for (const line of lines) {
+    // Match ## headings but NOT ### or deeper
+    if (/^## (?!#)/.test(line)) {
+      // Flush previous section
+      if (currentHeading) {
+        sections.push({
+          heading: currentHeading,
+          content: currentContent.join("\n"),
+          role: classifyHeading(currentHeading),
+        });
+      } else if (currentContent.length > 0) {
+        preamble = currentContent.join("\n");
+      }
+      currentHeading = extractHeadingText(line);
+      currentContent = [line];
+    } else {
+      currentContent.push(line);
+    }
+  }
+
+  // Flush last section
+  if (currentHeading) {
+    sections.push({
+      heading: currentHeading,
+      content: currentContent.join("\n"),
+      role: classifyHeading(currentHeading),
+    });
+  } else if (currentContent.length > 0) {
+    preamble = currentContent.join("\n");
+  }
+
+  return { preamble, sections };
+}
+
+const ROLE_ORDER: Record<string, number> = {
+  "static": 0,
+  "semi-static": 1,
+  "dynamic": 2,
+};
+
+/**
+ * Reorder a prompt's sections for cache efficiency.
+ * Extracts sections by ## heading markers, classifies them,
+ * and reorders: static -> semi-static -> dynamic.
+ *
+ * Content before the first ## heading is treated as a preamble
+ * and always placed first (it's usually static instructions).
+ *
+ * @param prompt The assembled prompt string
+ * @returns Reordered prompt string
+ */
+export function reorderForCaching(prompt: string): string {
+  const { preamble, sections } = splitSections(prompt);
+
+  // Nothing to reorder
+  if (sections.length <= 1) {
+    return prompt;
+  }
+
+  // Stable sort: sections with the same role keep their original relative order
+  const sorted = [...sections].sort((a, b) => {
+    return ROLE_ORDER[a.role] - ROLE_ORDER[b.role];
+  });
+
+  const parts: string[] = [];
+  if (preamble) {
+    parts.push(preamble);
+  }
+  for (const section of sorted) {
+    parts.push(section.content);
+  }
+
+  return parts.join("\n");
+}
+
+/**
+ * Analyze a prompt's cache efficiency without reordering.
+ * Returns stats about how much of the prompt is cacheable.
+ */
+export function analyzeCacheEfficiency(prompt: string): {
+  totalChars: number;
+  staticChars: number;
+  semiStaticChars: number;
+  dynamicChars: number;
+  cacheEfficiency: number;
+} {
+  const { preamble, sections } = splitSections(prompt);
+
+  let staticChars = preamble.length;
+  let semiStaticChars = 0;
+  let dynamicChars = 0;
+
+  for (const section of sections) {
+    switch (section.role) {
+      case "static":
+        staticChars += section.content.length;
+        break;
+      case "semi-static":
+        semiStaticChars += section.content.length;
+        break;
+      case "dynamic":
+        dynamicChars += section.content.length;
+        break;
+    }
+  }
+
+  const totalChars = staticChars + semiStaticChars + dynamicChars;
+  const cacheEfficiency = totalChars > 0
+    ? (staticChars + semiStaticChars) / totalChars
+    : 0;
+
+  return {
+    totalChars,
+    staticChars,
+    semiStaticChars,
+    dynamicChars,
+    cacheEfficiency,
+  };
+}

package/dist/resources/extensions/gsd/prompts/complete-milestone.md

@@ -23,8 +23,8 @@ Then:
 6. Write `{{milestoneSummaryPath}}` using the milestone-summary template. Fill all frontmatter fields and narrative sections. The `requirement_outcomes` field must list every requirement that changed status with `from_status`, `to_status`, and `proof`.
 7. Update `.gsd/REQUIREMENTS.md` if any requirement status transitions were validated in step 5.
 8. Update `.gsd/PROJECT.md` to reflect milestone completion and current project state.
-9. Do not commit manually — the system auto-commits your changes after this unit completes.
-10. Update `.gsd/STATE.md`
+9. Review all slice summaries for cross-cutting lessons, patterns, or gotchas that emerged during this milestone. Append any non-obvious, reusable insights to `.gsd/KNOWLEDGE.md`.
+10. Do not commit manually — the system auto-commits your changes after this unit completes.
 
 **Important:** Do NOT skip the success criteria and definition of done verification (steps 3-4). The milestone summary must reflect actual verified outcomes, not assumed success. If any criterion was not met, document it clearly in the summary and do not mark the milestone as passing verification.
 

package/dist/resources/extensions/gsd/prompts/complete-slice.md

@@ -27,10 +27,10 @@ Then:
 6. Write `{{sliceSummaryPath}}` (compress all task summaries).
 7. Write `{{sliceUatPath}}` — a concrete UAT script with real test cases derived from the slice plan and task summaries. Include preconditions, numbered steps with expected outcomes, and edge cases. This must NOT be a placeholder or generic template — tailor every test case to what this slice actually built.
 8. Review task summaries for `key_decisions`. Append any significant decisions to `.gsd/DECISIONS.md` if missing.
-9. Mark {{sliceId}} done in `{{roadmapPath}}` (change `[ ]` to `[x]`)
-10. Do not run git commands — the system commits your changes and handles any merge after this unit succeeds.
-11. Update `.gsd/PROJECT.md` if it exists — refresh current state if needed.
-12. Update `.gsd/STATE.md`
+9. Review task summaries for patterns, gotchas, or non-obvious lessons learned. If any would save future agents from repeating investigation or hitting the same issues, append them to `.gsd/KNOWLEDGE.md`. Only add entries that are genuinely useful — don't pad with obvious observations.
+10. Mark {{sliceId}} done in `{{roadmapPath}}` (change `[ ]` to `[x]`)
+11. Do not run git commands — the system commits your changes and handles any merge after this unit succeeds.
+12. Update `.gsd/PROJECT.md` if it exists — refresh current state if needed.
 
 **You MUST do ALL THREE before finishing: (1) write `{{sliceSummaryPath}}`, (2) write `{{sliceUatPath}}`, (3) mark {{sliceId}} as `[x]` in `{{roadmapPath}}`. The unit will not be marked complete if any of these files are missing.**
 

package/dist/resources/extensions/gsd/prompts/discuss-headless.md

@@ -50,8 +50,7 @@ Use these templates exactly:
 4. Write `{{contextPath}}` (using Context template) — preserve the specification's exact terminology, emphasis, and specific framing. Do not paraphrase domain-specific language into generics. Document assumptions under an "Assumptions" section.
 5. Write `{{roadmapPath}}` (using Roadmap template) — decompose into demoable vertical slices with checkboxes, risk, depends, demo sentences, proof strategy, verification classes, milestone definition of done, requirement coverage, and a boundary map. If the milestone crosses multiple runtime boundaries, include an explicit final integration slice.
 6. Seed `.gsd/DECISIONS.md` (using Decisions template)
-7. Update `.gsd/STATE.md`
-8. {{commitInstruction}}
+7. {{commitInstruction}}
 9. Say exactly: "Milestone {{milestoneId}} ready."
 
 **For multi-milestone**, write in this order:
@@ -70,8 +69,7 @@ Use these templates exactly:
    # M003: Title
    ```
    Each context file should be rich enough that a future agent — with no memory of this conversation — can understand the intent, constraints, dependencies, what the milestone unlocks, and what "done" looks like.
-8. Update `.gsd/STATE.md`
-9. {{multiMilestoneCommitInstruction}}
+8. {{multiMilestoneCommitInstruction}}
 10. Say exactly: "Milestone {{milestoneId}} ready."
 
 ## Critical Rules

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

@@ -11,7 +11,7 @@ After the user describes their idea, **do not ask questions yet**. First, prove
 1. Summarize what you understood in your own words — concretely, not abstractly.
 2. Give an honest size read: roughly how many milestones, roughly how many slices in the first one. Base this on the actual work involved, not a classification label. A config change might be 1 milestone with 1 slice. A social network might be 5 milestones with 8+ slices each. Use your judgment.
 3. Include scope honesty — a bullet list of the major capabilities you're hearing: "Here's what I'm hearing: [bullet list of major capabilities]."
-4. Ask: "Did I get that right, or did I miss something?" — plain text, not `ask_user_questions`. Let them correct freely.
+4. Ask: "Does that capture it? If not, tell me what I missed." — plain text, not `ask_user_questions`. Let them correct freely.
 
 This prevents runaway questioning by forcing comprehension proof before anything else. Do not skip this step. Do not combine it with the first question round.
 
@@ -200,8 +200,7 @@ When writing context.md, preserve the user's exact terminology, emphasis, and sp
 4. Write `{{contextPath}}` — use the **Context** output template below. Preserve key risks, unknowns, existing codebase constraints, integration points, and relevant requirements surfaced during discussion.
 5. Write `{{roadmapPath}}` — use the **Roadmap** output template below. Decompose into demoable vertical slices with checkboxes, risk, depends, demo sentences, proof strategy, verification classes, milestone definition of done, requirement coverage, and a boundary map. If the milestone crosses multiple runtime boundaries, include an explicit final integration slice that proves the assembled system works end-to-end in a real environment.
 6. Seed `.gsd/DECISIONS.md` — use the **Decisions** output template below. Append rows for any architectural or pattern decisions made during discussion.
-7. Update `.gsd/STATE.md`
-8. {{commitInstruction}}
+7. {{commitInstruction}}
 
 After writing the files, say exactly: "Milestone {{milestoneId}} ready." — nothing else. Auto-mode will start automatically.
 
@@ -243,6 +242,16 @@ For each remaining milestone **one at a time, in sequence**, use `ask_user_quest
 - **"Write draft for later"** — This milestone has seed material from the current conversation but needs its own dedicated discussion in a future session. Write a `CONTEXT-DRAFT.md` capturing the seed material (what was discussed, key ideas, provisional scope, open questions). Mark it clearly as a draft, not a finalized context. **What happens downstream:** When auto-mode reaches this milestone, it pauses and notifies the user: "M00x has draft context — needs discussion. Run /gsd." The `/gsd` wizard shows a "Discuss from draft" option that seeds the new discussion with this draft, so nothing from the current conversation is lost. After the dedicated discussion produces a full CONTEXT.md, the draft file is automatically deleted.
 - **"Just queue it"** — This milestone is identified but intentionally left without context. No context file is written — the directory already exists from Phase 1. **What happens downstream:** When auto-mode reaches this milestone, it pauses and notifies the user to run /gsd. The wizard starts a full discussion from scratch.
 
+**When "Discuss now" is chosen — Technical Assumption Verification is MANDATORY:**
+
+Before writing each milestone's CONTEXT.md (whether primary or secondary), you MUST verify technical assumptions:
+
+1. **Read the actual code** for every file or module you reference. Confirm APIs exist, check what functions actually do, identify phantom capabilities (code that exists but isn't wired up).
+2. **Check for stale assumptions** — the codebase changes. Verify referenced modules still work as described.
+3. **Present findings** — use `ask_user_questions` with a question ID containing BOTH `depth_verification` AND the milestone ID (e.g., `depth_verification_M002`). Present: what you're about to write, key technical findings from investigation, risks the code review surfaced.
+
+**The system mechanically blocks CONTEXT.md writes until the per-milestone depth verification passes.** Each milestone needs its own verification — one global verification does not unlock all milestones.
+
 **Why sequential, not batch:** After writing the primary milestone's context and roadmap, the agent still has context window capacity. Asking one milestone at a time lets the user decide per-milestone whether to invest that remaining capacity in a focused discussion now, or defer to a future session. A batch question ("Ready/Draft/Queue for M002, M003, M004?") forces the user to decide everything upfront without knowing how much session capacity remains.
 
 Each context file (full or draft) should be rich enough that a future agent encountering it fresh — with no memory of this conversation — can understand the intent, constraints, dependencies, what this milestone unlocks, and what "done" looks like.
@@ -270,8 +279,7 @@ For single-milestone projects, do NOT write this file — it is only for multi-m
 
 #### Phase 4: Finalize
 
-7. Update `.gsd/STATE.md`
-8. {{multiMilestoneCommitInstruction}}
+7. {{multiMilestoneCommitInstruction}}
 
 After writing the files, say exactly: "Milestone M001 ready." — nothing else. Auto-mode will start automatically.
 

package/dist/resources/extensions/gsd/prompts/execute-task.md

@@ -65,7 +65,6 @@ Then:
 15. Write `{{taskSummaryPath}}`
 16. Mark {{taskId}} done in `{{planPath}}` (change `[ ]` to `[x]`)
 17. Do not run git commands — the system reads your task summary after completion and creates a meaningful commit from it (type inferred from title, message from your one-liner, key files from frontmatter). Write a clear, specific one-liner in the summary — it becomes the commit message.
-18. Update `.gsd/STATE.md`
 
 All work stays in your working directory: `{{workingDirectory}}`.
 

package/dist/resources/extensions/gsd/prompts/guided-complete-slice.md

@@ -1,3 +1,3 @@
-Complete slice {{sliceId}} ("{{sliceTitle}}") of milestone {{milestoneId}}. Your working directory is `{{workingDirectory}}` — all file operations must use this path. All tasks are done. Your slice summary is the primary record of what was built — downstream agents (reassess-roadmap, future slice researchers) read it to understand what this slice delivered and what to watch out for. Use the **Slice Summary** and **UAT** output templates below. If a `GSD Skill Preferences` block is present in system context, use it to decide which skills to load and follow during completion, without relaxing required verification or artifact rules. Write `{{sliceId}}-SUMMARY.md` (compress task summaries), write `{{sliceId}}-UAT.md`, and fill the `UAT Type` plus `Not Proven By This UAT` sections explicitly so the artifact states what class of acceptance it covers and what still remains unproven. Review task summaries for `key_decisions` and ensure any significant ones are in `.gsd/DECISIONS.md`. Mark the slice checkbox done in the roadmap, update STATE.md, update milestone summary, Do not commit or merge manually — the system handles this after the unit completes.
+Complete slice {{sliceId}} ("{{sliceTitle}}") of milestone {{milestoneId}}. Your working directory is `{{workingDirectory}}` — all file operations must use this path. All tasks are done. Your slice summary is the primary record of what was built — downstream agents (reassess-roadmap, future slice researchers) read it to understand what this slice delivered and what to watch out for. Use the **Slice Summary** and **UAT** output templates below. If a `GSD Skill Preferences` block is present in system context, use it to decide which skills to load and follow during completion, without relaxing required verification or artifact rules. Write `{{sliceId}}-SUMMARY.md` (compress task summaries), write `{{sliceId}}-UAT.md`, and fill the `UAT Type` plus `Not Proven By This UAT` sections explicitly so the artifact states what class of acceptance it covers and what still remains unproven. Review task summaries for `key_decisions` and ensure any significant ones are in `.gsd/DECISIONS.md`. Mark the slice checkbox done in the roadmap, update milestone summary, Do not commit or merge manually — the system handles this after the unit completes.
 
 {{inlinedTemplates}}

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

@@ -91,7 +91,7 @@ Before moving to the wrap-up gate, verify you have covered:
 - options: "Yes, you got it (Recommended)", "Not quite — let me clarify"
 - **The question ID must contain `depth_verification`** (e.g. `depth_verification_confirm`) — this enables the write-gate downstream.
 
-**If `{{structuredQuestionsAvailable}}` is `false`:** ask in plain text: "Did I capture that correctly? Anything I missed?" Wait for confirmation before proceeding.
+**If `{{structuredQuestionsAvailable}}` is `false`:** ask in plain text: "Did I capture that correctly? If not, tell me what I missed." Wait for confirmation before proceeding.
 
 If they clarify, absorb the correction and re-verify.
 

package/dist/resources/extensions/gsd/prompts/guided-plan-milestone.md

@@ -26,6 +26,5 @@ Plan milestone {{milestoneId}} ("{{milestoneTitle}}"). Read `.gsd/DECISIONS.md`
 
 After writing the roadmap, analyze the slices and their boundary maps for external service dependencies (third-party APIs, SaaS platforms, cloud providers, databases requiring credentials, OAuth providers, etc.). If this milestone requires any external API keys or secrets, use the **Secrets Manifest** output template below for the expected format and write `{{secretsOutputPath}}` listing every predicted secret as an H3 section with the Service name, a direct Dashboard URL to the console page where the key is created, a Format hint showing what the key looks like, Status set to `pending`, and Destination (`dotenv`, `vercel`, or `convex`). Include numbered step-by-step guidance for obtaining each key. If this milestone does not require any external API keys or secrets, skip this step entirely — do not create an empty manifest.
 
-**You MUST update `.gsd/STATE.md`** after writing the roadmap (and secrets manifest if applicable). This is required for auto-mode to continue.
 
 {{inlinedTemplates}}

package/dist/resources/extensions/gsd/prompts/plan-milestone.md

@@ -25,7 +25,6 @@ Then:
 4. Order by risk (high-risk first)
 5. Write `{{outputPath}}` with checkboxes, risk, depends, demo sentences, proof strategy, verification classes, milestone definition of done, **requirement coverage**, and a boundary map. Write success criteria as observable truths, not implementation tasks. If the milestone crosses multiple runtime boundaries, include an explicit final integration slice that proves the assembled system works end-to-end in a real environment
 6. If planning produced structural decisions (e.g. slice ordering rationale, technology choices, scope exclusions), append them to `.gsd/DECISIONS.md` (use the **Decisions** output template from the inlined context above if the file doesn't exist yet)
-7. Update `.gsd/STATE.md`
 
 ## Requirement Mapping Rules
 

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

@@ -60,7 +60,6 @@ Then:
     - **Feature completeness:** Every task produces real, user-facing progress — not just internal scaffolding.
 9. If planning produced structural decisions, append them to `.gsd/DECISIONS.md`
 10. {{commitInstruction}}
-11. Update `.gsd/STATE.md`
 
 The slice directory and tasks/ subdirectory already exist. Do NOT mkdir. All work stays in your working directory: `{{workingDirectory}}`.
 

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

@@ -77,6 +77,36 @@ If multi-milestone: propose the split to the user before writing artifacts.
 
 Determine where the new milestones should go in the overall sequence. Consider dependencies, prerequisites, and independence.
 
+## Pre-Write Verification — MANDATORY
+
+Before writing ANY CONTEXT.md file, you MUST complete these verification steps. The system mechanically blocks CONTEXT.md writes until depth verification passes.
+
+### Step 1: Technical Assumption Verification
+
+For EACH milestone you are about to write context for, investigate the codebase to verify your technical assumptions:
+
+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.
+
+### Step 2: Per-Milestone Depth Verification
+
+For each milestone, use `ask_user_questions` with a question ID containing BOTH `depth_verification` AND the milestone ID. Example:
+
+```
+id: "depth_verification_M010-3ym37m"
+```
+
+This triggers the per-milestone write-gate. The question should present:
+- What you're about to capture as the scope
+- 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.
+
+**If you skip this step, the system will block the CONTEXT.md write and return an error telling you to complete verification first.**
+
 ## Output Phase
 
 Once the user is satisfied, in a single pass for **each** new milestone:

package/dist/resources/extensions/gsd/prompts/quick-task.md

@@ -39,10 +39,4 @@ You are executing a GSD quick task — a lightweight, focused unit of work outsi
 - <what was tested/verified>
 ```
 
-8. Update `.gsd/STATE.md` — add or update the "Quick Tasks Completed" table:
-   - If the section doesn't exist, create it after "### Blockers/Concerns"
-   - Table format: `| # | Description | Date | Commit | Directory |`
-   - Add a row: `| {{taskNum}} | {{description}} | {{date}} | <commit-hash> | [{{taskNum}}-{{slug}}](./quick/{{taskNum}}-{{slug}}/) |`
-   - Update the "Last activity" line
-
 When done, say: "Quick task {{taskNum}} complete."

package/dist/resources/extensions/gsd/prompts/replan-slice.md

@@ -44,7 +44,6 @@ Consider these captures when rewriting the remaining tasks — they represent th
    - Update the Files Likely Touched section if the replan changes which files are affected
 5. If any incomplete task had a `T0x-PLAN.md`, remove or rewrite it to match the new task description.
 6. Do not commit manually — the system auto-commits your changes after this unit completes.
-7. Update `.gsd/STATE.md`
 
 **You MUST write `{{replanPath}}` and the updated slice plan before finishing.**
 

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

@@ -25,7 +25,6 @@ An override was issued by the user that changes a fundamental decision or approa
    - 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.
-6. Update `.gsd/STATE.md`
 
 **You MUST update the relevant documents AND mark overrides as resolved in `{{overridesPath}}` before finishing.**
 

package/dist/resources/extensions/gsd/prompts/system.md

@@ -114,7 +114,7 @@ In all modes, slices commit sequentially on the active branch; there are no per-
 - **Tasks** are single-context-window units of work (T01, T02, ...)
 - Checkboxes in roadmap and plan files track completion (`[ ]` → `[x]`)
 - Summaries compress prior work - read them instead of re-reading all task details
-- `STATE.md` is the quick-glance status file - keep it updated after changes
+- `STATE.md` is a system-managed status file — rebuilt automatically after each unit completes
 
 ### Artifact Templates
 

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

@@ -0,0 +1,28 @@
+# Workflow Template: {{templateName}}
+
+You are executing a **{{templateName}}** workflow (template: `{{templateId}}`).
+
+## Context
+
+- **Description:** {{description}}
+- **Issue reference:** {{issueRef}}
+- **Date:** {{date}}
+- **Branch:** {{branch}}
+- **Artifact directory:** {{artifactDir}}
+- **Phases:** {{phases}}
+- **Complexity:** {{complexity}}
+
+## 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.
+
+{{workflowContent}}
+
+## Execution Rules
+
+1. **Follow the phases in order.** Do not skip phases unless the workflow explicitly allows it.
+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.
+6. **Stay focused.** This is a {{complexity}}-complexity workflow. Match your ceremony level to the task — don't over-engineer or under-deliver.

package/dist/resources/extensions/gsd/provider-error-pause.ts

@@ -2,12 +2,51 @@ export type ProviderErrorPauseUI = {
   notify(message: string, level?: "info" | "warning" | "error" | "success"): void;
 };
 
+/**
+ * Classify a provider error as transient (auto-resume) or permanent (manual resume).
+ *
+ * Transient: rate limits, server errors (500/502/503), overloaded, internal errors.
+ * These are expected to self-resolve and should auto-resume after a delay.
+ *
+ * Permanent: auth errors, invalid API key, billing issues.
+ * These require user intervention and should pause indefinitely.
+ */
+export function classifyProviderError(errorMsg: string): {
+  isTransient: boolean;
+  isRateLimit: boolean;
+  suggestedDelayMs: number;
+} {
+  const isRateLimit = /rate.?limit|too many requests|429/i.test(errorMsg);
+  const isServerError = /internal server error|500|502|503|overloaded|server_error|api_error|service.?unavailable/i.test(errorMsg);
+
+  // Permanent errors — never auto-resume
+  const isPermanent = /auth|unauthorized|forbidden|invalid.*key|invalid.*api|billing|quota exceeded|account/i.test(errorMsg);
+
+  if (isPermanent && !isRateLimit) {
+    return { isTransient: false, isRateLimit: false, suggestedDelayMs: 0 };
+  }
+
+  if (isRateLimit) {
+    // Try to extract retry-after from the message
+    const resetMatch = errorMsg.match(/reset in (\d+)s/i);
+    const delayMs = resetMatch ? Number(resetMatch[1]) * 1000 : 60_000; // default 60s for rate limits
+    return { isTransient: true, isRateLimit: true, suggestedDelayMs: delayMs };
+  }
+
+  if (isServerError) {
+    return { isTransient: true, isRateLimit: false, suggestedDelayMs: 30_000 }; // 30s for server errors
+  }
+
+  // Unknown error — treat as permanent (user reviews)
+  return { isTransient: false, isRateLimit: false, suggestedDelayMs: 0 };
+}
+
 /**
  * Pause auto-mode due to a provider error.
  *
- * For rate-limit errors with a known reset delay, schedules an automatic
- * resume after the delay and shows a countdown notification. For all other
- * errors, pauses indefinitely (user must manually resume).
+ * For transient errors (rate limits, server errors, overloaded), schedules
+ * an automatic resume after a delay. For permanent errors (auth, billing),
+ * pauses indefinitely — user must manually resume.
  */
 export async function pauseAutoForProviderError(
   ui: ProviderErrorPauseUI,
@@ -15,23 +54,33 @@ export async function pauseAutoForProviderError(
   pause: () => Promise<void>,
   options?: {
     isRateLimit?: boolean;
+    isTransient?: boolean;
     retryAfterMs?: number;
     resume?: () => void;
   },
 ): Promise<void> {
-  if (options?.isRateLimit && options.retryAfterMs && options.retryAfterMs > 0 && options.resume) {
-    const delaySec = Math.ceil(options.retryAfterMs / 1000);
+  const shouldAutoResume = (options?.isRateLimit || options?.isTransient)
+    && options.retryAfterMs
+    && options.retryAfterMs > 0
+    && options.resume;
+
+  if (shouldAutoResume) {
+    const delaySec = Math.ceil(options!.retryAfterMs! / 1000);
+    const reason = options!.isRateLimit ? "Rate limited" : "Server error (transient)";
     ui.notify(
-      `Rate limited${errorDetail}. Auto-resuming in ${delaySec}s...`,
+      `${reason}${errorDetail}. Auto-resuming in ${delaySec}s...`,
       "warning",
     );
     await pause();
 
-    // Schedule auto-resume after the rate limit window
+    // Schedule auto-resume after the delay
     setTimeout(() => {
-      ui.notify("Rate limit window elapsed. Resuming auto-mode.", "info");
-      options.resume!();
-    }, options.retryAfterMs);
+      const resumeMsg = options!.isRateLimit
+        ? "Rate limit window elapsed. Resuming auto-mode."
+        : "Server error recovery delay elapsed. Resuming auto-mode.";
+      ui.notify(resumeMsg, "info");
+      options!.resume!();
+    }, options!.retryAfterMs!);
   } else {
     ui.notify(`Auto-mode paused due to provider error${errorDetail}`, "warning");
     await pause();

package/dist/resources/extensions/gsd/queue-order.ts

@@ -9,10 +9,10 @@
  * survives branch switches and is shared across sessions.
  */
 
-import { readFileSync, writeFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { gsdRoot } from "./paths.js";
-import { milestoneIdSort } from "./guided-flow.js";
+import { milestoneIdSort } from "./milestone-ids.js";
+import { loadJsonFileOrNull, saveJsonFile } from "./json-persistence.js";
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 
@@ -45,6 +45,12 @@ function queueOrderPath(basePath: string): string {
   return join(gsdRoot(basePath), "QUEUE-ORDER.json");
 }
 
+// ─── Type Guards ─────────────────────────────────────────────────────────────
+
+function isQueueOrderFile(data: unknown): data is QueueOrderFile {
+  return data !== null && typeof data === "object" && "order" in data! && Array.isArray((data as QueueOrderFile).order);
+}
+
 // ─── Read / Write ────────────────────────────────────────────────────────────
 
 /**
@@ -52,15 +58,8 @@ function queueOrderPath(basePath: string): string {
  * the file is corrupt/unreadable.
  */
 export function loadQueueOrder(basePath: string): string[] | null {
-  const p = queueOrderPath(basePath);
-  if (!existsSync(p)) return null;
-  try {
-    const data: QueueOrderFile = JSON.parse(readFileSync(p, "utf-8"));
-    if (!Array.isArray(data.order)) return null;
-    return data.order;
-  } catch {
-    return null;
-  }
+  const data = loadJsonFileOrNull(queueOrderPath(basePath), isQueueOrderFile);
+  return data?.order ?? null;
 }
 
 /**
@@ -71,7 +70,7 @@ export function saveQueueOrder(basePath: string, order: string[]): void {
     order,
     updatedAt: new Date().toISOString(),
   };
-  writeFileSync(queueOrderPath(basePath), JSON.stringify(data, null, 2) + "\n", "utf-8");
+  saveJsonFile(queueOrderPath(basePath), data);
 }
 
 // ─── Sorting ─────────────────────────────────────────────────────────────────

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

@@ -11,7 +11,7 @@
 import type { ExtensionContext } from "@gsd/pi-coding-agent";
 import { type Theme } from "@gsd/pi-coding-agent";
 import { Key, matchesKey, truncateToWidth, type TUI } from "@gsd/pi-tui";
-import { makeUI, GLYPH } from "../shared/ui.js";
+import { makeUI, GLYPH } from "../shared/mod.js";
 import { validateQueueOrder, type DependencyValidation } from "./queue-order.js";
 
 export interface ReorderItem {
@@ -38,7 +38,7 @@ export async function showQueueReorder(
   if (!ctx.hasUI) return null;
   if (pending.length < 2) return null;
 
-  return ctx.ui.custom<ReorderResult | null>((tui: TUI, theme: Theme, _kb, done) => {
+  const result = await ctx.ui.custom<ReorderResult | null>((tui: TUI, theme: Theme, _kb, done) => {
     const items = [...pending];
     let cursor = 0;
     let grabbed = false;
@@ -260,4 +260,17 @@ export async function showQueueReorder(
     overlay: true,
     overlayOptions: { width: "70%", minWidth: 50, maxHeight: "80%", anchor: "center" },
   });
+
+  // Fallback for RPC mode where ctx.ui.custom() returns undefined.
+  // Reorder requires interactive input — notify and return null.
+  if (result === undefined) {
+    ctx.ui.notify(
+      "Queue reorder requires an interactive terminal. Current order: " +
+        pending.map(p => p.id).join(" → "),
+      "warning",
+    );
+    return null;
+  }
+
+  return result;
 }