gsd-pi 2.17.0 → 2.18.0

package/dist/resources/extensions/gsd/docs/preferences-reference.md

@@ -80,9 +80,9 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
 
 - `skill_rules`: situational rules with a human-readable `when` trigger and one or more of `use`, `prefer`, or `avoid`.
 
-- `custom_instructions`: extra durable instructions related to skill use.
+- `custom_instructions`: extra durable instructions related to skill use. For operational project knowledge (recurring rules, gotchas, patterns), use `.gsd/KNOWLEDGE.md` instead — it's injected into every agent prompt automatically and agents can append to it during execution.
 
-- `models`: per-stage model selection for auto-mode. Keys: `research`, `planning`, `execution`, `completion`. Values can be:
+- `models`: per-stage model selection for auto-mode. Keys: `research`, `planning`, `execution`, `execution_simple`, `completion`, `subagent`. Values can be:
   - Simple string: `"claude-sonnet-4-6"` — single model, no fallbacks
   - Provider-qualified string: `"bedrock/claude-sonnet-4-6"` — targets a specific provider when the same model ID exists across multiple providers
   - Object with fallbacks: `{ model: "claude-opus-4-6", fallbacks: ["glm-5", "minimax-m2.5"] }` — tries fallbacks in order if primary fails
@@ -108,10 +108,75 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
   - `pre_merge_check`: boolean or `"auto"` — run pre-merge checks before merging a worktree back to the integration branch. `true` always runs, `false` never runs, `"auto"` runs when CI is detected. Default: `false`.
   - `commit_type`: string — override the conventional commit type prefix. Must be one of: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `perf`, `ci`, `build`, `style`. Default: inferred from diff content.
   - `main_branch`: string — the primary branch name for new git repos (e.g., `"main"`, `"master"`, `"trunk"`). Also used by `getMainBranch()` as the preferred branch when auto-detection is ambiguous. Default: `"main"`.
+  - `merge_strategy`: `"squash"` or `"merge"` — controls how worktree branches are merged back. `"squash"` combines all commits into one; `"merge"` preserves individual commits. Default: `"squash"`.
+  - `isolation`: `"worktree"` or `"branch"` — controls auto-mode git isolation strategy. `"worktree"` creates a milestone worktree for isolated work; `"branch"` works directly in the project root (useful for submodule-heavy repos). Default: `"worktree"`.
   - `commit_docs`: boolean — when `false`, prevents GSD from committing `.gsd/` planning artifacts to git. The `.gsd/` folder is added to `.gitignore` and kept local-only. Useful for teams where only some members use GSD, or when company policy requires a clean repository. Default: `true`.
 
 - `unique_milestone_ids`: boolean — when `true`, generates milestone IDs in `M{seq}-{rand6}` format (e.g. `M001-eh88as`) instead of plain sequential `M001`. Prevents ID collisions in team workflows where multiple contributors create milestones concurrently. Both formats coexist — existing `M001`-style milestones remain valid. Default: `false`.
 
+- `budget_ceiling`: number — maximum dollar amount to spend on auto-mode. When reached, behavior is controlled by `budget_enforcement`. Default: no limit.
+
+- `budget_enforcement`: `"warn"`, `"pause"`, or `"halt"` — action taken when `budget_ceiling` is reached.
+  - `warn` — log a warning but continue execution.
+  - `pause` — pause auto-mode and wait for user confirmation.
+  - `halt` — stop auto-mode immediately.
+  - Default: `"pause"`.
+
+- `context_pause_threshold`: number (0-100) — context window usage percentage at which auto-mode should pause to suggest checkpointing. Set to `0` to disable. Default: `0` (disabled).
+
+- `token_profile`: `"budget"`, `"balanced"`, or `"quality"` — coordinates model selection, phase skipping, and context compression. `budget` skips research/reassessment and uses cheaper models; `balanced` (default) runs all phases; `quality` prefers higher-quality models. See token-optimization docs.
+
+- `phases`: fine-grained control over which phases run. Usually set by `token_profile`, but can be overridden. Keys:
+  - `skip_research`: boolean — skip milestone-level research. Default: `false`.
+  - `skip_reassess`: boolean — skip roadmap reassessment after each slice. Default: `false`.
+  - `skip_slice_research`: boolean — skip per-slice research. Default: `false`.
+
+- `remote_questions`: route interactive questions to Slack/Discord for headless auto-mode. Keys:
+  - `channel`: `"slack"` or `"discord"` — channel type.
+  - `channel_id`: string or number — channel ID.
+  - `timeout_minutes`: number — question timeout in minutes (clamped 1-30).
+  - `poll_interval_seconds`: number — poll interval in seconds (clamped 2-30).
+
+- `notifications`: configures desktop notification behavior during auto-mode. Keys:
+  - `enabled`: boolean — master toggle for all notifications. Default: `true`.
+  - `on_complete`: boolean — notify when a unit completes. Default: `true`.
+  - `on_error`: boolean — notify on errors. Default: `true`.
+  - `on_budget`: boolean — notify when budget thresholds are reached. Default: `true`.
+  - `on_milestone`: boolean — notify when a milestone finishes. Default: `true`.
+  - `on_attention`: boolean — notify when manual attention is needed. Default: `true`.
+
+- `uat_dispatch`: boolean — when `true`, enables UAT (User Acceptance Testing) dispatch mode. Default: `false`.
+
+- `post_unit_hooks`: array — hooks that fire after a unit completes. Each entry has:
+  - `name`: string — unique hook identifier.
+  - `after`: string[] — unit types that trigger this hook (e.g., `["execute-task"]`).
+  - `prompt`: string — prompt sent to the LLM. Supports `{milestoneId}`, `{sliceId}`, `{taskId}` substitutions.
+  - `max_cycles`: number — max times this hook fires per trigger (default: 1, max: 10).
+  - `model`: string — optional model override.
+  - `artifact`: string — expected output file name (relative to task/slice dir). Hook is skipped if file already exists (idempotent).
+  - `retry_on`: string — if this file is produced instead of the artifact, re-run the trigger unit then re-run hooks.
+  - `agent`: string — agent definition file to use for hook execution.
+  - `enabled`: boolean — toggle without removing (default: `true`).
+
+- `pre_dispatch_hooks`: array — hooks that fire before a unit is dispatched. Each entry has:
+  - `name`: string — unique hook identifier.
+  - `before`: string[] — unit types to intercept.
+  - `action`: `"modify"`, `"skip"`, or `"replace"` — what to do with the unit.
+  - `prepend`: string — text prepended to unit prompt (for `"modify"` action).
+  - `append`: string — text appended to unit prompt (for `"modify"` action).
+  - `prompt`: string — replacement prompt (for `"replace"` action; required when action is `"replace"`).
+  - `unit_type`: string — override unit type label (for `"replace"` action).
+  - `skip_if`: string — for `"skip"` action: only skip if this file exists (relative to unit dir).
+  - `model`: string — optional model override when this hook fires.
+  - `enabled`: boolean — toggle without removing (default: `true`).
+
+  **Action validation:**
+  - `"modify"` requires at least one of `prepend` or `append`.
+  - `"replace"` requires `prompt`.
+  - `"skip"` is valid with no additional fields.
+
+  **Known unit types for `before`/`after`:** `research-milestone`, `plan-milestone`, `research-slice`, `plan-slice`, `execute-task`, `complete-slice`, `replan-slice`, `reassess-roadmap`, `run-uat`.
+
 ---
 
 ## Best Practices
@@ -277,3 +342,137 @@ git:
 ```
 
 All git fields are optional. Omit any field to use the default behavior. Project-level preferences override global preferences on a per-field basis.
+
+---
+
+## Budget & Cost Control Example
+
+```yaml
+---
+version: 1
+budget_ceiling: 10.00
+budget_enforcement: pause
+context_pause_threshold: 80
+---
+```
+
+Sets a $10 budget ceiling. Auto-mode pauses when the ceiling is reached. Context window pauses at 80% usage for checkpointing.
+
+---
+
+## Notifications Example
+
+```yaml
+---
+version: 1
+notifications:
+  enabled: true
+  on_complete: false
+  on_error: true
+  on_budget: true
+  on_milestone: true
+  on_attention: true
+---
+```
+
+Disables per-unit completion notifications (noisy in long runs) while keeping error, budget, milestone, and attention notifications enabled.
+
+---
+
+## Post-Unit Hooks Example
+
+```yaml
+---
+version: 1
+post_unit_hooks:
+  - name: code-review
+    after:
+      - execute-task
+    prompt: "Review the code changes in {sliceId}/{taskId} for quality, security, and test coverage."
+    max_cycles: 1
+    artifact: REVIEW.md
+---
+```
+
+Runs an automated code review after each task execution. Skips if `REVIEW.md` already exists (idempotent).
+
+---
+
+## Pre-Dispatch Hooks Examples
+
+**Modify — inject instructions before every task:**
+
+```yaml
+---
+version: 1
+pre_dispatch_hooks:
+  - name: enforce-standards
+    before:
+      - execute-task
+    action: modify
+    prepend: "Follow our TypeScript coding standards and always run linting."
+---
+```
+
+**Skip — skip per-slice research when a research file already exists:**
+
+```yaml
+---
+version: 1
+pre_dispatch_hooks:
+  - name: skip-existing-research
+    before:
+      - research-slice
+    action: skip
+    skip_if: RESEARCH.md
+---
+```
+
+**Replace — substitute a custom prompt for task execution:**
+
+```yaml
+---
+version: 1
+pre_dispatch_hooks:
+  - name: tdd-execute
+    before:
+      - execute-task
+    action: replace
+    prompt: "Implement the task using strict TDD. Write failing tests first, then implement, then refactor."
+    model: claude-opus-4-6
+---
+```
+
+---
+
+## Token Profile & Phases Example
+
+```yaml
+---
+version: 1
+token_profile: budget
+phases:
+  skip_research: true
+  skip_reassess: true
+  skip_slice_research: false
+---
+```
+
+Uses the `budget` profile to minimize token usage, with explicit override to keep slice-level research enabled.
+
+---
+
+## Remote Questions Example
+
+```yaml
+---
+version: 1
+remote_questions:
+  channel: slack
+  channel_id: "C0123456789"
+  timeout_minutes: 15
+  poll_interval_seconds: 10
+---
+```
+
+Routes interactive questions to a Slack channel for headless auto-mode sessions. Questions time out after 15 minutes if unanswered.

package/dist/resources/extensions/gsd/files.ts

@@ -849,7 +849,7 @@ export function parseContextDependsOn(content: string | null): string[] {
   const fm = parseFrontmatterMap(fmLines);
   const raw = fm['depends_on'];
   if (!Array.isArray(raw) || raw.length === 0) return [];
-  return (raw as string[]).map(s => String(s).toUpperCase().trim()).filter(Boolean);
+  return (raw as string[]).map(s => String(s).trim()).filter(Boolean);
 }
 
 /**
@@ -951,6 +951,128 @@ export async function appendOverride(basePath: string, change: string, appliedAt
   }
 }
 
+export async function appendKnowledge(
+  basePath: string,
+  type: "rule" | "pattern" | "lesson",
+  entry: string,
+  scope: string,
+): Promise<void> {
+  const knowledgePath = resolveGsdRootFile(basePath, "KNOWLEDGE");
+  const existing = await loadFile(knowledgePath);
+
+  if (existing) {
+    // Find the next ID for this type
+    const prefix = type === "rule" ? "K" : type === "pattern" ? "P" : "L";
+    const idPattern = new RegExp(`^\\| ${prefix}(\\d+)`, "gm");
+    let maxId = 0;
+    let match;
+    while ((match = idPattern.exec(existing)) !== null) {
+      const num = parseInt(match[1], 10);
+      if (num > maxId) maxId = num;
+    }
+    const nextId = `${prefix}${String(maxId + 1).padStart(3, "0")}`;
+
+    // Build the table row
+    let row: string;
+    if (type === "rule") {
+      row = `| ${nextId} | ${scope} | ${entry} | — | manual |`;
+    } else if (type === "pattern") {
+      row = `| ${nextId} | ${entry} | — | ${scope} |`;
+    } else {
+      row = `| ${nextId} | ${entry} | — | — | ${scope} |`;
+    }
+
+    // Find the right section and append after the table header
+    const sectionHeading = type === "rule" ? "## Rules" : type === "pattern" ? "## Patterns" : "## Lessons Learned";
+    const sectionIdx = existing.indexOf(sectionHeading);
+    if (sectionIdx !== -1) {
+      // Find the end of the table header row (the |---|...| line)
+      const afterHeading = existing.indexOf("\n", sectionIdx);
+      // Find the next section or end
+      const nextSection = existing.indexOf("\n## ", afterHeading + 1);
+      const insertPoint = nextSection !== -1 ? nextSection : existing.length;
+
+      // Insert row before the next section (or at end)
+      const before = existing.slice(0, insertPoint).trimEnd();
+      const after = existing.slice(insertPoint);
+      await saveFile(knowledgePath, before + "\n" + row + "\n" + after);
+    } else {
+      // Section not found — append at end
+      await saveFile(knowledgePath, existing.trimEnd() + "\n\n" + row + "\n");
+    }
+  } else {
+    // Create file from scratch with template header
+    const header = [
+      "# Project Knowledge",
+      "",
+      "Append-only register of project-specific rules, patterns, and lessons learned.",
+      "Agents read this before every unit. Add entries when you discover something worth remembering.",
+      "",
+    ].join("\n");
+
+    let content: string;
+    if (type === "rule") {
+      content = header + [
+        "## Rules",
+        "",
+        "| # | Scope | Rule | Why | Added |",
+        "|---|-------|------|-----|-------|",
+        `| K001 | ${scope} | ${entry} | — | manual |`,
+        "",
+        "## Patterns",
+        "",
+        "| # | Pattern | Where | Notes |",
+        "|---|---------|-------|-------|",
+        "",
+        "## Lessons Learned",
+        "",
+        "| # | What Happened | Root Cause | Fix | Scope |",
+        "|---|--------------|------------|-----|-------|",
+        "",
+      ].join("\n");
+    } else if (type === "pattern") {
+      content = header + [
+        "## Rules",
+        "",
+        "| # | Scope | Rule | Why | Added |",
+        "|---|-------|------|-----|-------|",
+        "",
+        "## Patterns",
+        "",
+        "| # | Pattern | Where | Notes |",
+        "|---|---------|-------|-------|",
+        `| P001 | ${entry} | — | ${scope} |`,
+        "",
+        "## Lessons Learned",
+        "",
+        "| # | What Happened | Root Cause | Fix | Scope |",
+        "|---|--------------|------------|-----|-------|",
+        "",
+      ].join("\n");
+    } else {
+      content = header + [
+        "## Rules",
+        "",
+        "| # | Scope | Rule | Why | Added |",
+        "|---|-------|------|-----|-------|",
+        "",
+        "## Patterns",
+        "",
+        "| # | Pattern | Where | Notes |",
+        "|---|---------|-------|-------|",
+        "",
+        "## Lessons Learned",
+        "",
+        "| # | What Happened | Root Cause | Fix | Scope |",
+        "|---|--------------|------------|-----|-------|",
+        `| L001 | ${entry} | — | — | ${scope} |`,
+        "",
+      ].join("\n");
+    }
+    await saveFile(knowledgePath, content);
+  }
+}
+
 export async function loadActiveOverrides(basePath: string): Promise<Override[]> {
   const overridesPath = resolveGsdRootFile(basePath, "OVERRIDES");
   const content = await loadFile(overridesPath);

package/dist/resources/extensions/gsd/guided-flow.ts

@@ -22,11 +22,12 @@ import {
 } from "./paths.js";
 import { randomInt } from "node:crypto";
 import { join } from "node:path";
-import { readFileSync, existsSync, mkdirSync, readdirSync, rmSync, unlinkSync } from "node:fs";
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, rmSync, unlinkSync } from "node:fs";
 import { nativeIsRepo, nativeInit, nativeAddPaths, nativeCommit } from "./native-git-bridge.js";
 import { ensureGitignore, ensurePreferences, untrackRuntimeFiles } from "./gitignore.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { showConfirm } from "../shared/confirm-ui.js";
+import { loadQueueOrder, sortByQueueOrder, saveQueueOrder } from "./queue-order.js";
 
 // ─── Auto-start after discuss ─────────────────────────────────────────────────
 
@@ -203,13 +204,16 @@ function buildDiscussPrompt(nextId: string, preamble: string, _basePath: string)
 export function findMilestoneIds(basePath: string): string[] {
   const dir = milestonesDir(basePath);
   try {
-    return readdirSync(dir, { withFileTypes: true })
+    const ids = readdirSync(dir, { withFileTypes: true })
       .filter((d) => d.isDirectory())
       .map((d) => {
         const match = d.name.match(/^(M\d+(?:-[a-z0-9]{6})?)/);
         return match ? match[1] : d.name;
-      })
-      .sort(milestoneIdSort);
+      });
+
+    // Apply custom queue order if available, else fall back to numeric sort
+    const customOrder = loadQueueOrder(basePath);
+    return sortByQueueOrder(ids, customOrder);
   } catch {
     return [];
   }
@@ -305,6 +309,235 @@ export async function showQueue(
     return;
   }
 
+  // ── Count pending milestones ────────────────────────────────────────
+  const pendingMilestones = state.registry.filter(
+    m => m.status === "pending" || m.status === "active",
+  );
+  const completeCount = state.registry.filter(m => m.status === "complete").length;
+
+  // ── If multiple pending milestones, show queue management hub ──────
+  if (pendingMilestones.length > 1) {
+    const choice = await showNextAction(ctx, {
+      title: "GSD — Queue Management",
+      summary: [
+        `${completeCount} complete, ${pendingMilestones.length} pending.`,
+      ],
+      actions: [
+        {
+          id: "reorder",
+          label: "Reorder queue",
+          description: `Change execution order of ${pendingMilestones.length} pending milestones.`,
+          recommended: true,
+        },
+        {
+          id: "add",
+          label: "Add new work",
+          description: "Queue new milestones via discussion.",
+        },
+      ],
+      notYetMessage: "Run /gsd queue when ready.",
+    });
+
+    if (choice === "reorder") {
+      await handleQueueReorder(ctx, basePath, state);
+      return;
+    }
+    if (choice === "not_yet") return;
+    // "add" falls through to existing queue-add logic below
+  }
+
+  // ── Existing queue-add flow ─────────────────────────────────────────
+  await showQueueAdd(ctx, pi, basePath, state);
+}
+
+async function handleQueueReorder(
+  ctx: ExtensionCommandContext,
+  basePath: string,
+  state: Awaited<ReturnType<typeof deriveState>>,
+): Promise<void> {
+  const { showQueueReorder: showReorderUI } = await import("./queue-reorder-ui.js");
+  const { invalidateStateCache } = await import("./state.js");
+
+  const completed = state.registry
+    .filter(m => m.status === "complete")
+    .map(m => ({ id: m.id, title: m.title, dependsOn: m.dependsOn }));
+
+  const pending = state.registry
+    .filter(m => m.status !== "complete")
+    .map(m => ({ id: m.id, title: m.title, dependsOn: m.dependsOn }));
+
+  const result = await showReorderUI(ctx, completed, pending);
+  if (!result) {
+    ctx.ui.notify("Queue reorder cancelled.", "info");
+    return;
+  }
+
+  // Save the new order
+  saveQueueOrder(basePath, result.order);
+  invalidateStateCache();
+
+  // Remove conflicting depends_on entries from CONTEXT.md files
+  if (result.depsToRemove.length > 0) {
+    removeDependsOnFromContextFiles(basePath, result.depsToRemove);
+  }
+
+  // Sync PROJECT.md milestone sequence table
+  syncProjectMdSequence(basePath, state.registry, result.order);
+
+  // Commit the change
+  const filesToAdd = [".gsd/QUEUE-ORDER.json", ".gsd/PROJECT.md"];
+  for (const r of result.depsToRemove) {
+    filesToAdd.push(`.gsd/milestones/${r.milestone}/${r.milestone}-CONTEXT.md`);
+  }
+  try {
+    nativeAddPaths(basePath, filesToAdd);
+    nativeCommit(basePath, "docs: reorder queue");
+  } catch {
+    // Commit may fail if nothing changed or git hooks block — non-fatal
+  }
+
+  const depInfo = result.depsToRemove.length > 0
+    ? ` (removed ${result.depsToRemove.length} depends_on)`
+    : "";
+  ctx.ui.notify(`Queue reordered: ${result.order.join(" → ")}${depInfo}`, "info");
+}
+
+/**
+ * Remove specific depends_on entries from milestone CONTEXT.md frontmatter.
+ */
+function removeDependsOnFromContextFiles(
+  basePath: string,
+  depsToRemove: Array<{ milestone: string; dep: string }>,
+): void {
+  // Group removals by milestone
+  const byMilestone = new Map<string, string[]>();
+  for (const { milestone, dep } of depsToRemove) {
+    const existing = byMilestone.get(milestone) ?? [];
+    existing.push(dep);
+    byMilestone.set(milestone, existing);
+  }
+
+  for (const [mid, depsToRemoveForMid] of byMilestone) {
+    const contextFile = resolveMilestoneFile(basePath, mid, "CONTEXT");
+    if (!contextFile || !existsSync(contextFile)) continue;
+
+    const content = readFileSync(contextFile, "utf-8");
+
+    // Parse frontmatter
+    const trimmed = content.trimStart();
+    if (!trimmed.startsWith("---")) continue;
+    const afterFirst = trimmed.indexOf("\n");
+    if (afterFirst === -1) continue;
+    const rest = trimmed.slice(afterFirst + 1);
+    const endIdx = rest.indexOf("\n---");
+    if (endIdx === -1) continue;
+
+    const fmText = rest.slice(0, endIdx);
+    const body = rest.slice(endIdx + 4);
+
+    // Parse depends_on line(s)
+    const fmLines = fmText.split("\n");
+    const removeSet = new Set(depsToRemoveForMid.map(d => d.toUpperCase()));
+
+    // Handle inline format: depends_on: [M009, M010]
+    const inlineMatch = fmLines.findIndex(l => /^depends_on:\s*\[/.test(l));
+    if (inlineMatch >= 0) {
+      const line = fmLines[inlineMatch];
+      const inner = line.match(/\[([^\]]*)\]/);
+      if (inner) {
+        const remaining = inner[1]
+          .split(",")
+          .map(s => s.trim())
+          .filter(s => s && !removeSet.has(s.toUpperCase()));
+        if (remaining.length === 0) {
+          fmLines.splice(inlineMatch, 1);
+        } else {
+          fmLines[inlineMatch] = `depends_on: [${remaining.join(", ")}]`;
+        }
+      }
+    } else {
+      // Handle multi-line format
+      const keyIdx = fmLines.findIndex(l => /^depends_on:\s*$/.test(l));
+      if (keyIdx >= 0) {
+        let end = keyIdx + 1;
+        while (end < fmLines.length && /^\s+-\s/.test(fmLines[end])) {
+          const val = fmLines[end].replace(/^\s+-\s*/, "").trim().toUpperCase();
+          if (removeSet.has(val)) {
+            fmLines.splice(end, 1);
+          } else {
+            end++;
+          }
+        }
+        if (end === keyIdx + 1 || (end <= fmLines.length && !/^\s+-\s/.test(fmLines[keyIdx + 1] ?? ""))) {
+          fmLines.splice(keyIdx, 1);
+        }
+      }
+    }
+
+    // Rebuild file
+    const newFm = fmLines.filter(l => l !== undefined).join("\n");
+    const newContent = newFm.trim()
+      ? `---\n${newFm}\n---${body}`
+      : body.replace(/^\n+/, "");
+    writeFileSync(contextFile, newContent, "utf-8");
+  }
+}
+
+function syncProjectMdSequence(
+  basePath: string,
+  registry: Array<{ id: string; title: string; status: string }>,
+  newOrder: string[],
+): void {
+  const projectPath = resolveGsdRootFile(basePath, "PROJECT");
+  if (!projectPath || !existsSync(projectPath)) return;
+
+  const content = readFileSync(projectPath, "utf-8");
+  const lines = content.split("\n");
+
+  const headerIdx = lines.findIndex(l => /^##\s+Milestone Sequence/.test(l));
+  if (headerIdx < 0) return;
+
+  let tableStart = headerIdx + 1;
+  while (tableStart < lines.length && !lines[tableStart].startsWith("|")) tableStart++;
+  if (tableStart >= lines.length) return;
+
+  let tableEnd = tableStart + 1;
+  while (tableEnd < lines.length && lines[tableEnd].startsWith("|")) tableEnd++;
+
+  const registryMap = new Map(registry.map(m => [m.id, m]));
+  const completedSet = new Set(registry.filter(m => m.status === "complete").map(m => m.id));
+
+  const newRows: string[] = [];
+  for (const m of registry) {
+    if (m.status === "complete") {
+      newRows.push(`| ${m.id} | ${m.title} | ✅ Complete |`);
+    }
+  }
+  let isFirst = true;
+  for (const id of newOrder) {
+    if (completedSet.has(id)) continue;
+    const m = registryMap.get(id);
+    if (!m) continue;
+    const status = isFirst ? "📋 Next" : "📋 Queued";
+    newRows.push(`| ${m.id} | ${m.title} | ${status} |`);
+    isFirst = false;
+  }
+
+  const headerLine = lines[tableStart];
+  const separatorLine = lines[tableStart + 1];
+  const newTable = [headerLine, separatorLine, ...newRows];
+  lines.splice(tableStart, tableEnd - tableStart, ...newTable);
+  writeFileSync(projectPath, lines.join("\n"), "utf-8");
+}
+
+async function showQueueAdd(
+  ctx: ExtensionCommandContext,
+  pi: ExtensionAPI,
+  basePath: string,
+  state: Awaited<ReturnType<typeof deriveState>>,
+): Promise<void> {
+  const milestoneIds = findMilestoneIds(basePath);
+
   // ── Build existing milestones context for the prompt ────────────────
   const existingContext = await buildExistingMilestonesContext(basePath, milestoneIds, state);