gsd-pi 2.82.0-dev.725028083 → 2.82.0-dev.9d5798940

package/README.md

@@ -336,7 +336,7 @@ Plan (with integrated research) → Execute (per task) → Complete → Reassess
                                                                               Validate Milestone → Complete Milestone
 ```
 
-**Plan** scouts the codebase, researches relevant docs, and decomposes the slice into tasks with must-haves (mechanically verifiable outcomes). **Execute** runs each task in a fresh context window with only the relevant files pre-loaded — then runs configured verification commands (lint, test, etc.) with auto-fix retries. **Complete** writes the summary, UAT script, marks the roadmap, and commits with meaningful messages derived from task summaries. **Reassess** checks if the roadmap still makes sense given what was learned. **Validate Milestone** runs a reconciliation gate after all slices complete — comparing roadmap success criteria against actual results before sealing the milestone.
+**Plan** scouts the codebase, researches relevant docs, and decomposes the slice into tasks with must-haves (mechanically verifiable outcomes). **Execute** runs each task in a fresh context window with only the relevant files pre-loaded, then runs configured verification commands (lint, test, etc.) with auto-fix retries before the task closeout commit or snapshot is published. Failed or incomplete verification blocks execute-task closeout. **Complete** writes the summary, UAT script, marks the roadmap, and commits with meaningful messages derived from task summaries. **Reassess** checks if the roadmap still makes sense given what was learned. **Validate Milestone** runs a reconciliation gate after all slices complete — comparing roadmap success criteria against actual results before sealing the milestone.
 
 When progressive planning is enabled, the first slice is fully planned up front while later slices may appear in `M###-ROADMAP.md` with a `` `[sketch]` `` badge. A sketch slice has an approved title, dependency shape, demo line, and scope boundary, but it has not yet been expanded into task plans; auto mode runs `refine-slice` just before execution to turn the sketch into a full slice plan using the latest prior-slice summaries.
 
@@ -376,7 +376,7 @@ The database is authoritative for milestones, slices, tasks, requirements, summa
 
 10. **Adaptive replanning** — After each slice completes, the roadmap is reassessed. If the work revealed new information that changes the plan, slices are reordered, added, or removed before continuing.
 
-11. **Verification enforcement** — Configure shell commands (`npm run lint`, `npm run test`, etc.) that run automatically after task execution. Failures trigger auto-fix retries before advancing. Auto-discovered checks from `package.json` run in advisory mode — they log warnings but don't block on pre-existing errors. Configurable via `verification_commands`, `verification_auto_fix`, and `verification_max_retries` preferences.
+11. **Verification enforcement** — Configure shell commands (`npm run lint`, `npm run test`, etc.) that run automatically after task execution. Failures trigger auto-fix retries before advancing. Execute-task commits and snapshots are deferred until verification passes; failed or incomplete verification blocks closeout instead of publishing changes. Auto-discovered checks from `package.json` run in advisory mode — they log warnings but don't block on pre-existing errors. Configurable via `verification_commands`, `verification_auto_fix`, and `verification_max_retries` preferences.
 
 12. **Milestone validation** — After all slices complete, a `validate-milestone` gate compares roadmap success criteria against actual results before sealing the milestone.
 
@@ -502,6 +502,7 @@ On first run, GSD launches a branded setup wizard that walks you through LLM pro
 | `/gsd rethink`          | Conversational project reorganization                                         |
 | `/gsd mcp`              | MCP server status and connectivity                                            |
 | `/gsd status`           | Progress dashboard                                                            |
+| `/gsd brief <mode>`     | Generate a visual HTML brief (diagram, plan, diff, recap, table, slides)      |
 | `/gsd queue`            | Queue future milestones (safe during auto mode)                               |
 | `/gsd prefs`            | Model selection, timeouts, budget ceiling                                     |
 | `/gsd migrate`          | Migrate a v1 `.planning` directory to `.gsd` format                           |

package/dist/resources/.managed-resources-content-hash

@@ -1 +1 @@
-5c6d4acc2e1d8c2b
+ed49f911008c62ca

package/dist/resources/GSD-WORKFLOW.md

@@ -560,7 +560,7 @@ In all modes, slices and tasks commit sequentially on the active branch; there a
 
 1. **Milestone starts** → capture the current integration branch.
 2. **Optional isolation** → create `milestone/M001` only when `git.isolation` is `worktree` or `branch`.
-3. **Per-task commits** — atomic, descriptive, bisectable.
+3. **Per-task commits** — atomic, descriptive, bisectable, and published only after execute-task verification passes.
 4. **Slice completes** → write slice summary, UAT script, roadmap checkbox, and milestone summary.
 5. **Milestone completes** → if isolated, squash-merge the milestone branch back to the captured integration branch and clean up the worktree/branch.
 
@@ -574,6 +574,8 @@ fix: handle empty state rebuild
 
 In `none` mode these commits land directly on the current branch. In isolated modes they land on `milestone/<MID>` and are squashed back at milestone completion.
 
+Execute-task closeout is fail-closed: the system writes verification evidence first, defers the task commit or snapshot until verification passes, and pauses instead of publishing changes when verification fails or cannot complete.
+
 ### Commit Conventions
 
 | When | Format | Example |

package/dist/resources/extensions/claude-code-cli/partial-builder.js

@@ -105,9 +105,10 @@ export function mapUsage(sdkUsage, totalCostUsd) {
         output: sdkUsage.output_tokens,
         cacheRead: sdkUsage.cache_read_input_tokens,
         cacheWrite: sdkUsage.cache_creation_input_tokens,
+        // Claude Agent SDK result usage is cumulative across its internal loop;
+        // repeated cache reads do not represent additional live context.
         totalTokens: sdkUsage.input_tokens +
             sdkUsage.output_tokens +
-            sdkUsage.cache_read_input_tokens +
             sdkUsage.cache_creation_input_tokens,
         cost: {
             input: 0,

package/dist/resources/extensions/cmux/index.js

@@ -319,6 +319,11 @@ export class CmuxClient {
         const stdout = await this.runAsync(["send-surface", "--surface", surfaceId, payload]);
         return stdout !== null;
     }
+    // Send Ctrl-C (ETX) to a surface to interrupt the running command.
+    async sendInterrupt(surfaceId) {
+        const stdout = await this.runAsync(["send-surface", "--surface", surfaceId, "\x03"]);
+        return stdout !== null;
+    }
 }
 export function syncCmuxSidebar(preferences, state) {
     const client = CmuxClient.fromPreferences(preferences);

package/dist/resources/extensions/gsd/auto/orchestrator.js

@@ -3,6 +3,15 @@
 function now() {
     return Date.now();
 }
+/**
+ * Size of the dispatch-decision ring buffer used by the Auto Orchestration
+ * module's stuck-loop detector. When the same `${unitType}:${unitId}` key
+ * fills the window, advance() blocks with `action: "stop"`.
+ *
+ * Mirrors the legacy `STUCK_WINDOW_SIZE` in auto/phases.ts so behaviour is
+ * preserved across the eventual cutover (issue #5791).
+ */
+export const STUCK_WINDOW_SIZE = 6;
 export class AutoOrchestrator {
     status = {
         phase: "idle",
@@ -10,11 +19,13 @@ export class AutoOrchestrator {
     };
     deps;
     lastAdvanceKey = null;
+    dispatchKeyWindow = [];
     constructor(deps) {
         this.deps = deps;
     }
     async start(_sessionContext) {
         this.lastAdvanceKey = null;
+        this.dispatchKeyWindow = [];
         this.status.phase = "running";
         this.bumpTransition();
         await this.deps.runtime.journalTransition({ name: "start" });
@@ -24,18 +35,70 @@ export class AutoOrchestrator {
     async advance() {
         try {
             await this.deps.runtime.ensureLockOwnership();
+            const staleMsg = this.deps.health.checkResourcesStale();
+            if (staleMsg) {
+                await this.deps.uokGate.emit({
+                    gateId: "resource-version-guard",
+                    gateType: "policy",
+                    outcome: "fail",
+                    failureClass: "policy",
+                    rationale: "resource version guard blocked dispatch",
+                    findings: staleMsg,
+                });
+                const blocked = { kind: "blocked", reason: staleMsg, action: "stop" };
+                await this.deps.runtime.journalTransition({ name: "advance-blocked", reason: blocked.reason });
+                await this.deps.health.postAdvanceRecord(blocked);
+                return blocked;
+            }
+            await this.deps.uokGate.emit({
+                gateId: "resource-version-guard",
+                gateType: "policy",
+                outcome: "pass",
+                failureClass: "none",
+                rationale: "resource version guard passed",
+            });
             const gate = await this.deps.health.preAdvanceGate();
-            if (!gate.allow) {
-                const blocked = { kind: "blocked", reason: gate.reason ?? "health gate blocked" };
+            if (gate.kind === "fail") {
+                await this.deps.uokGate.emit({
+                    gateId: "pre-dispatch-health-gate",
+                    gateType: "execution",
+                    outcome: "manual-attention",
+                    failureClass: "manual-attention",
+                    rationale: "pre-dispatch health gate blocked dispatch",
+                    findings: gate.reason,
+                });
+                const blocked = { kind: "blocked", reason: gate.reason, action: "pause" };
                 await this.deps.runtime.journalTransition({ name: "advance-blocked", reason: blocked.reason });
                 await this.deps.health.postAdvanceRecord(blocked);
                 return blocked;
             }
+            if (gate.kind === "threw") {
+                await this.deps.uokGate.emit({
+                    gateId: "pre-dispatch-health-gate",
+                    gateType: "execution",
+                    outcome: "manual-attention",
+                    failureClass: "manual-attention",
+                    rationale: "pre-dispatch health gate threw unexpectedly",
+                    findings: String(gate.error),
+                });
+                // intentional fall-through: matches runPreDispatch behaviour
+            }
+            else {
+                await this.deps.uokGate.emit({
+                    gateId: "pre-dispatch-health-gate",
+                    gateType: "execution",
+                    outcome: "pass",
+                    failureClass: "none",
+                    rationale: "pre-dispatch health gate passed",
+                    findings: gate.fixesApplied?.join(", ") ?? "",
+                });
+            }
             const reconciliation = await this.deps.stateReconciliation.reconcileBeforeDispatch();
             if (!reconciliation.ok || !reconciliation.stateSnapshot) {
                 const blocked = {
                     kind: "blocked",
-                    reason: reconciliation.reason,
+                    reason: reconciliation.reason ?? "state reconciliation produced no snapshot",
+                    action: "pause",
                     stateSnapshot: reconciliation.stateSnapshot,
                 };
                 await this.deps.runtime.journalTransition({ name: "advance-blocked", reason: blocked.reason });
@@ -48,14 +111,49 @@ export class AutoOrchestrator {
                 this.status.phase = "stopped";
                 this.status.activeUnit = undefined;
                 this.lastAdvanceKey = null;
+                this.dispatchKeyWindow = [];
                 this.bumpTransition();
                 await this.deps.runtime.journalTransition({ name: "advance-stopped", reason: stopped.reason });
                 await this.deps.health.postAdvanceRecord(stopped);
                 return stopped;
             }
             const nextKey = `${decision.unitType}:${decision.unitId}`;
-            if (this.lastAdvanceKey === nextKey) {
-                const blocked = { kind: "blocked", reason: "idempotent advance: unit already active" };
+            // Record every dispatch decision in the ring buffer before pre-flight
+            // checks so the stuck-loop detector observes the full decision history
+            // (including decisions that idempotency would otherwise short-circuit).
+            // The ring is capped at STUCK_WINDOW_SIZE and evicts oldest-first.
+            this.dispatchKeyWindow.push(nextKey);
+            if (this.dispatchKeyWindow.length > STUCK_WINDOW_SIZE) {
+                this.dispatchKeyWindow.shift();
+            }
+            // Idempotency: same key as immediately previous successful advance.
+            // This is the soft, fast-path block kept from #5786. It only fires when
+            // the ring is NOT yet saturated for this key — once the ring is full of
+            // `nextKey`, the stuck-loop verdict takes precedence (see below). Both
+            // checks coexist: idempotency for the common immediate-repeat case,
+            // stuck-loop for the saturated-window case.
+            const matchingCount = this.dispatchKeyWindow.filter((k) => k === nextKey).length;
+            if (this.lastAdvanceKey === nextKey && matchingCount < STUCK_WINDOW_SIZE) {
+                const blocked = { kind: "blocked", reason: "idempotent advance: unit already active", action: "stop" };
+                await this.deps.runtime.journalTransition({
+                    name: "advance-blocked",
+                    reason: blocked.reason,
+                    unitType: decision.unitType,
+                    unitId: decision.unitId,
+                });
+                await this.deps.health.postAdvanceRecord(blocked);
+                return blocked;
+            }
+            // Stuck-loop detection: when the ring is saturated with copies of
+            // `nextKey` (count >= STUCK_WINDOW_SIZE), the orchestrator has been
+            // picking the same unit across the whole window and must hard-stop with
+            // a diagnosable reason.
+            if (matchingCount >= STUCK_WINDOW_SIZE) {
+                const blocked = {
+                    kind: "blocked",
+                    reason: `stuck-loop: ${nextKey} picked ${matchingCount} times`,
+                    action: "stop",
+                };
                 await this.deps.runtime.journalTransition({
                     name: "advance-blocked",
                     reason: blocked.reason,
@@ -70,6 +168,7 @@ export class AutoOrchestrator {
                 const blocked = {
                     kind: "blocked",
                     reason: contract.reason,
+                    action: "pause",
                     stateSnapshot: reconciliation.stateSnapshot,
                 };
                 await this.deps.runtime.journalTransition({
@@ -86,6 +185,7 @@ export class AutoOrchestrator {
                 const blocked = {
                     kind: "blocked",
                     reason: worktree.reason,
+                    action: "pause",
                     stateSnapshot: reconciliation.stateSnapshot,
                 };
                 await this.deps.runtime.journalTransition({
@@ -108,7 +208,11 @@ export class AutoOrchestrator {
                 unitId: decision.unitId,
             });
             await this.deps.worktree.syncAfterUnit(decision.unitType, decision.unitId);
-            const advanced = { kind: "advanced", stateSnapshot: reconciliation.stateSnapshot };
+            const advanced = {
+                kind: "advanced",
+                unit: { unitType: decision.unitType, unitId: decision.unitId },
+                stateSnapshot: reconciliation.stateSnapshot,
+            };
             await this.deps.health.postAdvanceRecord(advanced);
             return advanced;
         }
@@ -134,6 +238,7 @@ export class AutoOrchestrator {
             }
             if (result.kind === "stopped") {
                 this.lastAdvanceKey = null;
+                this.dispatchKeyWindow = [];
                 this.status.activeUnit = undefined;
             }
             this.bumpTransition();
@@ -158,6 +263,7 @@ export class AutoOrchestrator {
     }
     async resume() {
         this.lastAdvanceKey = null;
+        this.dispatchKeyWindow = [];
         this.status.phase = "running";
         this.bumpTransition();
         await this.deps.runtime.journalTransition({ name: "resume" });
@@ -172,6 +278,7 @@ export class AutoOrchestrator {
         this.status.phase = "stopped";
         this.status.activeUnit = undefined;
         this.lastAdvanceKey = null;
+        this.dispatchKeyWindow = [];
         this.bumpTransition();
         await this.deps.runtime.journalTransition({ name: "stop", reason });
         await this.deps.notifications.notifyLifecycle({ name: "stop", detail: reason });

package/dist/resources/extensions/gsd/auto-dispatch.js

@@ -102,6 +102,9 @@ function missingSliceStop(mid, phase) {
         level: "error",
     };
 }
+function isRegistryMilestoneComplete(state, mid) {
+    return state.registry.some((milestone) => milestone.id === mid && milestone.status === "complete");
+}
 /**
  * Check for milestone slices missing SUMMARY files.
  * Returns array of missing slice IDs, or empty array if all present or DB unavailable.
@@ -247,6 +250,8 @@ export const DISPATCH_RULES = [
                 return null;
             if (!MILESTONE_ID_RE.test(mid))
                 return null;
+            if (isRegistryMilestoneComplete(state, mid))
+                return null;
             // Align with the plan-v2 gate's lookup semantics: whitespace-only counts
             // as missing, and an auto worktree may fall back to GSD_PROJECT_ROOT.
             if (hasFinalizedMilestoneContext(basePath, mid))
@@ -557,6 +562,8 @@ export const DISPATCH_RULES = [
         match: async ({ state, mid, midTitle, basePath, prefs, structuredQuestionsAvailable }) => {
             if (state.phase !== "pre-planning")
                 return null;
+            if (isRegistryMilestoneComplete(state, mid))
+                return null;
             const contextFile = resolveMilestoneFile(basePath, mid, "CONTEXT");
             const hasContext = !!(contextFile && (await loadFile(contextFile)));
             if (hasContext)
@@ -1091,19 +1098,19 @@ export const DISPATCH_RULES = [
                     return { action: "skip" };
                 }
             }
-            // Safety guard (#2675): block completion when VALIDATION verdict is
-            // needs-remediation. The state machine treats needs-remediation as
-            // terminal (to prevent validate-milestone loops per #832), but
-            // completing-milestone should NOT proceed — remediation work is needed.
+            // Safety guard (#2675, #5747): block completion when VALIDATION
+            // verdict is non-passing. The state machine treats these verdicts as
+            // terminal, but completing-milestone should NOT proceed — remediation
+            // or human attention is needed.
             const validationFile = resolveMilestoneFile(basePath, mid, "VALIDATION");
             if (validationFile) {
                 const validationContent = await loadFile(validationFile);
                 if (validationContent) {
                     const verdict = extractVerdict(validationContent);
-                    if (verdict === "needs-remediation") {
+                    if (verdict === "needs-remediation" || verdict === "needs-attention") {
                         return {
                             action: "stop",
-                            reason: `Cannot complete milestone ${mid}: VALIDATION verdict is "needs-remediation". Address the remediation findings and re-run validation, or update the verdict manually.`,
+                            reason: `Cannot complete milestone ${mid}: VALIDATION verdict is "${verdict}". Address the validation findings and re-run validation, or update the verdict manually.`,
                             level: "warning",
                         };
                     }