@opengsd/gsd-pi 1.3.0-dev.65546769 → 1.3.0-dev.965d1788

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

@@ -45,7 +45,7 @@ If slice research is inlined, trust its architectural findings, but verify every
 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. Task `verify` commands must be safe, simple commands. Do not use shell pipes, redirects, semicolons, backticks, command substitution, output trimming, or grep regex alternation with `|`. If multiple checks are needed, create a small test file and run it with `node --test` or a package test script, or use separate simple commands joined only with `&&`. For absence checks, verify a pattern does not exist with `! grep -q 'pattern' file` or `! rg -q 'pattern' file`; do not use `grep -c` or `rg -c` to assert zero matches because count commands exit 1 when they find zero matches, and the verification gate treats that as failure.
-9. 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, tests, or describes — those belong in `inputs`, `verify`, `description`, or slice success criteria. If a task is a pure verification or test task that produces no new files, `expectedOutput` must be `[]`; if it writes a test-result log or assertion output file, list only that concrete file path. 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. Never list GSD planning artifacts — anything under `.gsd/`, `.planning/`, or `.audits/`, or artifact names like `M001-CONTEXT.md` / `S01-PLAN.md` — in `inputs`, `files`, or `expectedOutput`: their content is preloaded as context, and they are written by workflow tools, not by tasks.
+9. 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. Any npm package name in a task description's install/add instructions (`npm install`, `yarn add`, `pnpm add`) or in `require('...')` or `import ... from '...'` code examples is subject to pre-execution registry validation; reference only packages that exist on the public npm registry, and remove or correct any package name that is not real. `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, tests, or describes — those belong in `inputs`, `verify`, `description`, or slice success criteria. If a task is a pure verification or test task that produces no new files, `expectedOutput` must be `[]`; if it writes a test-result log or assertion output file, list only that concrete file path. 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. Never list GSD planning artifacts — anything under `.gsd/`, `.planning/`, or `.audits/`, or artifact names like `M001-CONTEXT.md` / `S01-PLAN.md` — in `inputs`, `files`, or `expectedOutput`: their content is preloaded as context, and they are written by workflow tools, not by tasks.
 10. 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.
 11. Self-audit before finishing: goal/demo closure, requirement coverage, deliverable coverage audit (cross-check every file listed in CONTEXT.md `## Scope` / `### In Scope` against task `files` or `expectedOutput`), 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.
 12. If planning creates structural decisions, call `gsd_decision_save` for each; the tool persists the decision and regenerates `.gsd/DECISIONS.md`.

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

@@ -10,8 +10,8 @@
  */
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
-import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
-import { isAbsolute, join, relative } from "node:path";
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
 import { QUICK_BRANCH_RE } from "./branch-patterns.js";
 import { loadPrompt } from "./prompt-loader.js";
 import { gsdRoot } from "./paths.js";
@@ -31,6 +31,7 @@ interface QuickReturnState {
 }
 
 let pendingQuickReturn: QuickReturnState | null = null;
+const pendingQuickReturnMisses = new Map<string, string>();
 
 // ─── Quick Task Helpers ───────────────────────────────────────────────────────
 
@@ -189,12 +190,35 @@ export function buildQuickCommitInstruction(basePath: string, root: string): str
   ].join("\n");
 }
 
+function readHeadBranchName(basePath: string): string | null {
+  try {
+    const gitPath = join(basePath, ".git");
+    if (!existsSync(gitPath)) return null;
+
+    let headPath: string;
+    if (lstatSync(gitPath).isDirectory()) {
+      headPath = join(gitPath, "HEAD");
+    } else {
+      const gitFile = readFileSync(gitPath, "utf-8").trim();
+      if (!gitFile.startsWith("gitdir: ")) return null;
+      headPath = join(resolve(basePath, gitFile.slice("gitdir: ".length)), "HEAD");
+    }
+
+    const head = readFileSync(headPath, "utf-8").trim();
+    if (!head.startsWith("ref: refs/heads/")) return null;
+    return head.slice("ref: refs/heads/".length);
+  } catch {
+    return null;
+  }
+}
+
 function quickReturnStatePath(basePath: string): string {
   return join(gsdRoot(basePath), "runtime", "quick-return.json");
 }
 
 function persistPendingReturn(state: QuickReturnState): void {
   pendingQuickReturn = state;
+  pendingQuickReturnMisses.delete(state.basePath);
   mkdirSync(join(gsdRoot(state.basePath), "runtime"), { recursive: true });
   writeFileSync(quickReturnStatePath(state.basePath), JSON.stringify(state) + "\n", "utf-8");
 }
@@ -203,6 +227,13 @@ function readPendingReturn(basePath: string): QuickReturnState | null {
   if (pendingQuickReturn && pendingQuickReturn.basePath === basePath) {
     return pendingQuickReturn;
   }
+  if (pendingQuickReturnMisses.has(basePath)) {
+    const statePath = quickReturnStatePath(basePath);
+    if (!existsSync(statePath) && readHeadBranchName(basePath) === pendingQuickReturnMisses.get(basePath)) {
+      return null;
+    }
+    pendingQuickReturnMisses.delete(basePath);
+  }
 
   try {
     const raw = readFileSync(quickReturnStatePath(basePath), "utf-8");
@@ -216,6 +247,7 @@ function readPendingReturn(basePath: string): QuickReturnState | null {
       && typeof parsed.description === "string"
     ) {
       pendingQuickReturn = parsed as QuickReturnState;
+      pendingQuickReturnMisses.delete(basePath);
       return pendingQuickReturn;
     }
   } catch {
@@ -225,9 +257,14 @@ function readPendingReturn(basePath: string): QuickReturnState | null {
   const inferred = inferQuickReturnFromBranch(basePath);
   if (inferred) {
     pendingQuickReturn = inferred;
+    pendingQuickReturnMisses.delete(basePath);
     return inferred;
   }
 
+  const branchAtMiss = readHeadBranchName(basePath);
+  if (branchAtMiss) {
+    pendingQuickReturnMisses.set(basePath, branchAtMiss);
+  }
   return null;
 }
 
@@ -235,6 +272,10 @@ function clearPendingReturn(basePath: string): void {
   if (pendingQuickReturn?.basePath === basePath) {
     pendingQuickReturn = null;
   }
+  const branchAtMiss = readHeadBranchName(basePath);
+  if (branchAtMiss) {
+    pendingQuickReturnMisses.set(basePath, branchAtMiss);
+  }
   rmSync(quickReturnStatePath(basePath), { force: true });
 }
 

package/src/resources/extensions/gsd/safety/file-change-validator.ts

@@ -76,8 +76,14 @@ export function validateFileChanges(
   const actualFiles = getChangedFilesFromLastCommit(basePath);
   if (!actualFiles) return null;
 
-  // Filter out .gsd/ internal files — only validate project source files
-  const projectFiles = actualFiles.filter(f => !f.startsWith(".gsd/") && !f.startsWith(".gsd\\"));
+  // Filter out GSD-internal paths — only validate project source files.
+  const projectFiles = actualFiles.filter(
+    (f) =>
+      !f.startsWith(".gsd/") &&
+      !f.startsWith(".gsd\\") &&
+      !f.startsWith(".gsd-backups/") &&
+      !f.startsWith(".gsd-backups\\"),
+  );
 
   // Normalize expected paths (strip leading ./ or /)
   const normalizedExpected = new Set(

package/src/resources/extensions/gsd/session-forensics.ts

@@ -223,11 +223,21 @@ export function extractTrace(entries: unknown[]): ExecutionTrace {
 
   // Flush any pending tool calls that never got results (crash mid-tool)
   for (const [, pending] of pendingTools) {
+    const missingResultError = `Tool call ${pending.name} started but no toolResult was recorded`;
     toolCalls.push({
       name: pending.name,
       input: redactInput(pending.name, pending.input),
-      isError: false,
+      result: "missing tool result (stream/tool-call abort before execution)",
+      isError: true,
     });
+    errors.push(missingResultError);
+
+    // Mark the matching commandsRun entry as failed so it is consistent with
+    // the isError: true on the tool call above (bash/bg_shell only).
+    if (pending.name === "bash" || pending.name === "bg_shell") {
+      const lastCmd = findLast(commandsRun, c => c.command === String(pending.input.command));
+      if (lastCmd) lastCmd.failed = true;
+    }
   }
 
   return {

package/src/resources/extensions/gsd/skills/gsd-headless/references/commands.md

@@ -66,7 +66,7 @@ These commands dispatch native GSD prompts adapted to the milestone, slice, and
 | `progress` | Summarize recent work; can route `--next` or `--do "..."` |
 | `health` | Check `.gsd/` integrity (`--repair`, `--context`) |
 | `surface` | Manage surfaced skills and extensions |
-| `code-review` | Review changed source for bugs, security, and quality |
+| `code-review` | Review changed source diff-first for bugs, security, and quality |
 | `review` | Peer-review recent work across reviewer perspectives |
 | `audit-milestone` | Verify a milestone met its definition of done |
 | `audit-uat` | Audit outstanding UAT/verification items |

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

@@ -0,0 +1,46 @@
+// Project/App: gsd-pi
+// File Purpose: deriveState memoization cache and telemetry.
+
+import type { GSDState } from '../../types.js';
+
+interface StateCache {
+  basePath: string;
+  result: GSDState;
+  timestamp: number;
+}
+
+const CACHE_TTL_MS = 100;
+let _stateCache: StateCache | null = null;
+
+let _telemetry = { dbDeriveCount: 0 };
+
+export function getDeriveTelemetry() {
+  return { ..._telemetry };
+}
+
+export function resetDeriveTelemetry() {
+  _telemetry = { dbDeriveCount: 0 };
+}
+
+export function incrementDbDeriveCount(): void {
+  _telemetry.dbDeriveCount++;
+}
+
+export function invalidateStateCache(): void {
+  _stateCache = null;
+}
+
+export function readCachedDeriveState(cacheKey: string): GSDState | null {
+  if (
+    _stateCache &&
+    _stateCache.basePath === cacheKey &&
+    Date.now() - _stateCache.timestamp < CACHE_TTL_MS
+  ) {
+    return _stateCache.result;
+  }
+  return null;
+}
+
+export function writeCachedDeriveState(cacheKey: string, result: GSDState): void {
+  _stateCache = { basePath: cacheKey, result, timestamp: Date.now() };
+}

package/src/resources/extensions/gsd/state/derive/db-open.ts

@@ -0,0 +1,45 @@
+// Project/App: gsd-pi
+// File Purpose: Workflow DB open helpers for state derivation.
+
+import type { GSDState } from '../../types.js';
+import { getAllMilestones, isDbAvailable, setMilestoneQueueOrder } from '../../gsd-db.js';
+import { openExistingWorkflowDatabase } from '../../db-workspace.js';
+import { loadQueueOrder, sortByQueueOrder } from '../../queue-order.js';
+
+export function syncQueueOrderProjectionToDb(basePath: string): void {
+  const queueOrder = loadQueueOrder(basePath);
+  if (!queueOrder) return;
+
+  const currentIds = getAllMilestones().map((m) => m.id);
+  const desiredIds = sortByQueueOrder(currentIds, queueOrder);
+  if (currentIds.length === desiredIds.length && currentIds.every((id, i) => id === desiredIds[i])) return;
+
+  setMilestoneQueueOrder(desiredIds);
+}
+
+export function ensureExistingWorkflowDbOpen(basePath: string): boolean {
+  const opened = isDbAvailable() || openExistingWorkflowDatabase(basePath).ok;
+  if (opened) syncQueueOrderProjectionToDb(basePath);
+  return opened;
+}
+
+export function buildDbUnavailableState(): GSDState {
+  return {
+    activeMilestone: null,
+    activeSlice: null,
+    activeTask: null,
+    phase: "pre-planning",
+    recentDecisions: [],
+    blockers: ["DB unavailable — runtime markdown state derivation is disabled"],
+    nextAction:
+      "Open or create the canonical GSD database before deriving workflow state. If this project only has markdown state, run /gsd migrate explicitly.",
+    registry: [],
+    requirements: { active: 0, validated: 0, deferred: 0, outOfScope: 0, blocked: 0, total: 0 },
+    progress: { milestones: { done: 0, total: 0 } },
+  };
+}
+
+export function getRequestedMilestoneLock(): string | undefined {
+  const lock = process.env.GSD_MILESTONE_LOCK?.trim();
+  return lock || undefined;
+}