gsd-pi 2.38.0-dev.96dc7fb → 2.38.0-dev.98b44dc

package/src/resources/extensions/gsd/prompts/run-uat.md

@@ -10,7 +10,7 @@ All relevant context has been preloaded below. Start working immediately without
 
 {{inlinedContext}}
 
-If a `GSD Skill Preferences` block is present in system context, use it to decide which skills to load and follow during UAT execution, without relaxing required verification or artifact rules.
+{{skillActivation}}
 
 ---
 
@@ -18,32 +18,49 @@ If a `GSD Skill Preferences` block is present in system context, use it to decid
 
 **UAT file:** `{{uatPath}}`
 **Result file to write:** `{{uatResultPath}}`
+**Detected UAT mode:** `{{uatType}}`
 
-You are the test runner. Execute every check defined in `{{uatPath}}` directly:
+You are the UAT runner. Execute every check defined in `{{uatPath}}` as deeply as this mode truthfully allows. Do not collapse live or subjective checks into cheap artifact checks just to get a PASS.
+
+### Automation rules by mode
+
+- `artifact-driven` — verify with shell commands, scripts, file reads, and artifact structure checks.
+- `browser-executable` — use browser tools to navigate to the target URL and verify expected behavior. Capture screenshots as evidence. Record pass/fail with specific assertions.
+- `runtime-executable` — execute the specified command or script. Capture stdout/stderr as evidence. Record pass/fail based on exit code and output.
+- `live-runtime` — exercise the real runtime path. Start or connect to the app/service if needed, use browser/runtime/network checks, and verify observable behavior.
+- `mixed` — run all automatable artifact-driven and live-runtime checks. Separate any remaining human-only checks explicitly.
+- `human-experience` — automate setup, preconditions, screenshots, logs, and objective checks, but do **not** invent subjective PASS results. Mark taste-based, experiential, or purely human-judgment checks as `NEEDS-HUMAN` and use an overall verdict of `PARTIAL` unless every required check was objective and passed.
+
+### Evidence tools
+
+Choose the lightest tool that proves the check honestly:
 
 - Run shell commands with `bash`
 - Run `grep` / `rg` checks against files
-- Run `node` / script invocations
+- Run `node` / other script invocations
 - Read files and verify their contents
 - Check that expected artifacts exist and have correct structure
+- For live/runtime/UI checks, exercise the real flow in the browser when applicable and inspect runtime/network/console state
+- When a check cannot be honestly automated, gather the best objective evidence you can and mark it `NEEDS-HUMAN`
 
 For each check, record:
 - The check description (from the UAT file)
+- The evidence mode used: `artifact`, `runtime`, or `human-follow-up`
 - The command or action taken
 - The actual result observed
-- PASS or FAIL verdict
+- `PASS`, `FAIL`, or `NEEDS-HUMAN`
 
 After running all checks, compute the **overall verdict**:
-- `PASS` — all checks passed
+- `PASS` — all required checks passed and no human-only checks remain
 - `FAIL` — one or more checks failed
-- `PARTIAL` — some checks passed, some failed or were skipped
+- `PARTIAL` — some checks passed, but one or more checks were skipped, inconclusive, or still require human judgment
 
 Write `{{uatResultPath}}` with:
 
 ```markdown
 ---
 sliceId: {{sliceId}}
-uatType: artifact-driven
+uatType: {{uatType}}
 verdict: PASS | FAIL | PARTIAL
 date: <ISO 8601 timestamp>
 ---
@@ -52,9 +69,9 @@ date: <ISO 8601 timestamp>
 
 ## Checks
 
-| Check | Result | Notes |
-|-------|--------|-------|
-| <check description> | PASS / FAIL | <observed output or reason> |
+| Check | Mode | Result | Notes |
+|-------|------|--------|-------|
+| <check description> | artifact / runtime / human-follow-up | PASS / FAIL / NEEDS-HUMAN | <observed output, evidence, or reason> |
 
 ## Overall Verdict
 
@@ -62,7 +79,7 @@ date: <ISO 8601 timestamp>
 
 ## Notes
 
-<any additional context, errors encountered, or follow-up items>
+<any additional context, errors encountered, screenshots/logs gathered, or manual follow-up still required>
 ```
 
 ---

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

@@ -14,7 +14,7 @@ You are executing a **{{templateName}}** workflow (template: `{{templateId}}`).
 
 ## 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.
+Follow the workflow defined below. Execute each phase in order, completing one before moving to the next. For low and medium complexity workflows, keep moving by default — pause only at true decision gates (user must choose between materially different directions, outward-facing actions need approval, or the workflow explicitly requires a human checkpoint). For high complexity workflows, confirm at phase transitions unless the workflow explicitly marks a gate as skip-safe.
 
 {{workflowContent}}
 
@@ -24,5 +24,5 @@ Follow the workflow defined below. Execute each phase in order, completing one b
 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.
+5. **Decision gates, not ceremony.** After each phase, summarize what changed. For low/medium complexity, ask for confirmation only when the next phase depends on a real user choice or external approval. For high complexity, confirm before proceeding to each new 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/src/resources/extensions/gsd/repo-identity.ts

@@ -12,6 +12,8 @@ import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, rmSync, s
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 
+const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
+
 // ─── Repo Identity ──────────────────────────────────────────────────────────
 
 /**
@@ -90,14 +92,31 @@ function resolveGitRoot(basePath: string): string {
   }
 }
 
+/**
+ * Validate a GSD_PROJECT_ID value.
+ *
+ * Must contain only alphanumeric characters, hyphens, and underscores.
+ * Call this once at startup so the user gets immediate feedback on bad values.
+ */
+export function validateProjectId(id: string): boolean {
+  return /^[a-zA-Z0-9_-]+$/.test(id);
+}
+
 /**
  * Compute a stable identity for a repository.
  *
- * SHA-256 of `${remoteUrl}\n${resolvedRoot}`, truncated to 12 hex chars.
- * Deterministic: same repo always produces the same hash regardless of
- * which worktree the caller is inside.
+ * If `GSD_PROJECT_ID` is set, returns it directly (validation is expected
+ * to have already happened at startup via `validateProjectId`).
+ *
+ * Otherwise returns SHA-256 of `${remoteUrl}\n${resolvedRoot}`, truncated
+ * to 12 hex chars. Deterministic: same repo always produces the same hash
+ * regardless of which worktree the caller is inside.
  */
 export function repoIdentity(basePath: string): string {
+  const projectId = process.env.GSD_PROJECT_ID;
+  if (projectId) {
+    return projectId;
+  }
   const remoteUrl = getRemoteUrl(basePath);
   const root = resolveGitRoot(basePath);
   const input = `${remoteUrl}\n${root}`;
@@ -113,7 +132,7 @@ export function repoIdentity(basePath: string): string {
  * otherwise `~/.gsd/projects/<hash>`.
  */
 export function externalGsdRoot(basePath: string): string {
-  const base = process.env.GSD_STATE_DIR || join(homedir(), ".gsd");
+  const base = process.env.GSD_STATE_DIR || gsdHome;
   return join(base, "projects", repoIdentity(basePath));
 }
 

package/src/resources/extensions/gsd/resource-version.ts

@@ -11,6 +11,8 @@ import { join } from "node:path";
 import { homedir } from "node:os";
 import { resolveProjectRoot } from "./worktree.js";
 
+const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
+
 // ─── Resource Staleness ───────────────────────────────────────────────────
 
 /**
@@ -23,7 +25,7 @@ function isManifestWithVersion(data: unknown): data is { gsdVersion: string } {
 }
 
 export function readResourceVersion(): string | null {
-  const agentDir = process.env.GSD_CODING_AGENT_DIR || join(homedir(), ".gsd", "agent");
+  const agentDir = process.env.GSD_CODING_AGENT_DIR || join(gsdHome, "agent");
   const manifestPath = join(agentDir, "managed-resources.json");
   const manifest = loadJsonFileOrNull(manifestPath, isManifestWithVersion);
   return manifest?.gsdVersion ?? null;

package/src/resources/extensions/gsd/roadmap-mutations.ts

@@ -39,6 +39,35 @@ export function markSliceDoneInRoadmap(basePath: string, mid: string, sid: strin
   return true;
 }
 
+/**
+ * Mark a slice as not done ([ ]) in the milestone roadmap.
+ * Idempotent — no-op if already unchecked or if the slice isn't found.
+ *
+ * @returns true if the roadmap was modified, false if no change was needed
+ */
+export function markSliceUndoneInRoadmap(basePath: string, mid: string, sid: string): boolean {
+  const roadmapFile = resolveMilestoneFile(basePath, mid, "ROADMAP");
+  if (!roadmapFile) return false;
+
+  let content: string;
+  try {
+    content = readFileSync(roadmapFile, "utf-8");
+  } catch {
+    return false;
+  }
+
+  const updated = content.replace(
+    new RegExp(`^(\\s*-\\s+)\\[x\\]\\s+\\*\\*${sid}:`, "m"),
+    `$1[ ] **${sid}:`,
+  );
+
+  if (updated === content) return false;
+
+  atomicWriteSync(roadmapFile, updated);
+  clearParseCache();
+  return true;
+}
+
 /**
  * Mark a task as done ([x]) in the slice plan.
  * Idempotent — no-op if already checked or if the task isn't found.

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

@@ -31,7 +31,7 @@ import {
   gsdRoot,
 } from './paths.js';
 
-import { milestoneIdSort, findMilestoneIds } from './guided-flow.js';
+import { milestoneIdSort, findMilestoneIds } from './milestone-ids.js';
 import { nativeBatchParseGsdFiles, type BatchParsedFile } from './native-parser-bridge.js';
 
 import { join, resolve } from 'path';
@@ -126,7 +126,12 @@ export async function getActiveMilestoneId(basePath: string): Promise<string | n
       // A draft milestone is still "active" — this function only determines which milestone is current.
     }
     const roadmap = parseRoadmap(content);
-    if (!isMilestoneComplete(roadmap)) return mid;
+    if (!isMilestoneComplete(roadmap)) {
+      // Summary is the terminal artifact — if it exists, the milestone is
+      // complete even when roadmap checkboxes weren't ticked (#864).
+      const summaryFile = resolveMilestoneFile(basePath, mid, "SUMMARY");
+      if (!summaryFile) return mid;
+    }
   }
   return null;
 }
@@ -258,7 +263,13 @@ async function _deriveStateImpl(basePath: string): Promise<GSDState> {
     }
     const rmap = parseRoadmap(rc);
     roadmapCache.set(mid, rmap);
-    if (!isMilestoneComplete(rmap)) continue;
+    if (!isMilestoneComplete(rmap)) {
+      // Summary is the terminal artifact — if it exists, the milestone is
+      // complete even when roadmap checkboxes weren't ticked (#864).
+      const sf = resolveMilestoneFile(basePath, mid, "SUMMARY");
+      if (sf) completeMilestoneIds.add(mid);
+      continue;
+    }
     const sf = resolveMilestoneFile(basePath, mid, "SUMMARY");
     if (sf) completeMilestoneIds.add(mid);
   }
@@ -357,26 +368,33 @@ async function _deriveStateImpl(basePath: string): Promise<GSDState> {
       } else {
         registry.push({ id: mid, title, status: 'complete' });
       }
-    } else if (!activeMilestoneFound) {
-      // Check milestone-level dependencies before promoting to active
-      const contextFile = resolveMilestoneFile(basePath, mid, "CONTEXT");
-      const contextContent = contextFile ? await cachedLoadFile(contextFile) : null;
-      const deps = parseContextDependsOn(contextContent);
-      const depsUnmet = deps.some(dep => !completeMilestoneIds.has(dep));
-      if (depsUnmet) {
-        registry.push({ id: mid, title, status: 'pending', dependsOn: deps });
-        // Do NOT set activeMilestoneFound — let the loop continue to the next milestone
+    } else {
+      // Roadmap slices not all checked — but if a summary exists, the milestone
+      // is still complete. The summary is the terminal artifact (#864).
+      const summaryFile = resolveMilestoneFile(basePath, mid, "SUMMARY");
+      if (summaryFile) {
+        registry.push({ id: mid, title, status: 'complete' });
+      } else if (!activeMilestoneFound) {
+        // Check milestone-level dependencies before promoting to active
+        const contextFile = resolveMilestoneFile(basePath, mid, "CONTEXT");
+        const contextContent = contextFile ? await cachedLoadFile(contextFile) : null;
+        const deps = parseContextDependsOn(contextContent);
+        const depsUnmet = deps.some(dep => !completeMilestoneIds.has(dep));
+        if (depsUnmet) {
+          registry.push({ id: mid, title, status: 'pending', dependsOn: deps });
+          // Do NOT set activeMilestoneFound — let the loop continue to the next milestone
+        } else {
+          activeMilestone = { id: mid, title };
+          activeRoadmap = roadmap;
+          activeMilestoneFound = true;
+          registry.push({ id: mid, title, status: 'active', ...(deps.length > 0 ? { dependsOn: deps } : {}) });
+        }
       } else {
-        activeMilestone = { id: mid, title };
-        activeRoadmap = roadmap;
-        activeMilestoneFound = true;
-        registry.push({ id: mid, title, status: 'active', ...(deps.length > 0 ? { dependsOn: deps } : {}) });
+        const contextFile2 = resolveMilestoneFile(basePath, mid, "CONTEXT");
+        const contextContent2 = contextFile2 ? await cachedLoadFile(contextFile2) : null;
+        const deps2 = parseContextDependsOn(contextContent2);
+        registry.push({ id: mid, title, status: 'pending', ...(deps2.length > 0 ? { dependsOn: deps2 } : {}) });
       }
-    } else {
-      const contextFile2 = resolveMilestoneFile(basePath, mid, "CONTEXT");
-      const contextContent2 = contextFile2 ? await cachedLoadFile(contextFile2) : null;
-      const deps2 = parseContextDependsOn(contextContent2);
-      registry.push({ id: mid, title, status: 'pending', ...(deps2.length > 0 ? { dependsOn: deps2 } : {}) });
     }
   }
 

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

@@ -0,0 +1,21 @@
+# Runtime Context
+
+## Stack
+- **Language:** (e.g., TypeScript, Python, Go)
+- **Framework:** (e.g., Next.js, FastAPI, Gin)
+- **Build:** (e.g., npm run build, cargo build)
+- **Test:** (e.g., npm run test, pytest)
+- **Lint:** (e.g., npm run lint, ruff check)
+
+## Environment
+- **Node version:** (e.g., 20.x)
+- **Package manager:** (e.g., npm, pnpm, yarn)
+- **Required env vars:** (list any needed for local dev)
+
+## Dev Server
+- **Start command:** (e.g., npm run dev)
+- **Default port:** (e.g., 3000)
+- **Health check:** (e.g., curl http://localhost:3000/health)
+
+## Notes
+(Any runtime-specific context the executor needs to know)

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

@@ -3,6 +3,9 @@
 # Tasks with 10+ estimated steps or 12+ estimated files trigger a warning to consider splitting.
 estimated_steps: {{estimatedSteps}}
 estimated_files: {{estimatedFiles}}
+# Installed skills the planner expects the executor to load before coding.
+skills_used:
+  - {{skillName}}
 ---
 
 # {{taskId}}: {{taskTitle}}

package/src/resources/extensions/gsd/tests/agent-end-retry.test.ts

@@ -1,9 +1,9 @@
 /**
- * agent-end-retry.test.ts — Regression checks for the post-#1419 agent_end model.
+ * agent-end-retry.test.ts — Regression checks for the agent_end model.
  *
- * The old recursive handleAgentEnd retry path is gone. The loop now keeps
- * pendingResolve + pendingAgentEndQueue on AutoSession, and handleAgentEnd is
- * only a thin compatibility wrapper around resolveAgentEnd().
+ * The per-unit one-shot resolve function lives at module level in auto-loop.ts
+ * (_currentResolve). handleAgentEnd is a thin compatibility wrapper around
+ * resolveAgentEnd().
  */
 
 import test from "node:test";
@@ -14,40 +14,43 @@ import { fileURLToPath } from "node:url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const AUTO_TS_PATH = join(__dirname, "..", "auto.ts");
+const AUTO_LOOP_TS_PATH = join(__dirname, "..", "auto-loop.ts");
 const SESSION_TS_PATH = join(__dirname, "..", "auto", "session.ts");
 
 function getAutoTsSource(): string {
   return readFileSync(AUTO_TS_PATH, "utf-8");
 }
 
+function getAutoLoopTsSource(): string {
+  return readFileSync(AUTO_LOOP_TS_PATH, "utf-8");
+}
+
 function getSessionTsSource(): string {
   return readFileSync(SESSION_TS_PATH, "utf-8");
 }
 
-test("AutoSession declares pending agent_end queue state", () => {
-  const source = getSessionTsSource();
+test("auto-loop.ts declares _currentResolve for per-unit one-shot promises", () => {
+  const source = getAutoLoopTsSource();
   assert.ok(
-    source.includes("pendingResolve"),
-    "AutoSession must declare pendingResolve for the in-flight unit promise",
+    source.includes("_currentResolve"),
+    "auto-loop.ts must declare _currentResolve for the per-unit resolve function",
   );
   assert.ok(
-    source.includes("pendingAgentEndQueue"),
-    "AutoSession must declare pendingAgentEndQueue for between-iteration agent_end events",
+    source.includes("_sessionSwitchInFlight"),
+    "auto-loop.ts must declare _sessionSwitchInFlight guard",
   );
 });
 
-test("AutoSession reset clears pending agent_end queue state", () => {
+test("AutoSession no longer holds promise state (moved to auto-loop.ts module scope)", () => {
   const source = getSessionTsSource();
-  const resetIdx = source.indexOf("reset(): void");
-  assert.ok(resetIdx > -1, "AutoSession must have a reset() method");
-  const resetBlock = source.slice(resetIdx, resetIdx + 4000);
+  // Properties should NOT exist as class fields
   assert.ok(
-    resetBlock.includes("this.pendingResolve = null"),
-    "reset() must clear pendingResolve",
+    !source.includes("pendingResolve:"),
+    "AutoSession must not declare pendingResolve (moved to auto-loop.ts)",
   );
   assert.ok(
-    resetBlock.includes("this.pendingAgentEndQueue = []"),
-    "reset() must clear pendingAgentEndQueue",
+    !source.includes("pendingAgentEndQueue:"),
+    "AutoSession must not declare pendingAgentEndQueue (removed — events are dropped)",
   );
 });