gsd-pi 2.28.0 → 2.29.0-dev.2ccf3fb

package/src/resources/extensions/gsd/verification-gate.ts

@@ -7,6 +7,7 @@ import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { join, basename } from "node:path";
 import type { AuditWarning, RuntimeError, VerificationCheck, VerificationResult } from "./types.js";
+import { DEFAULT_COMMAND_TIMEOUT_MS } from "./constants.js";
 
 /** Maximum bytes of stdout/stderr to retain per command (10 KB). */
 const MAX_OUTPUT_BYTES = 10 * 1024;
@@ -44,11 +45,12 @@ const PACKAGE_SCRIPT_KEYS = ["typecheck", "lint", "test"] as const;
  *   4. None found
  */
 export function discoverCommands(options: DiscoverCommandsOptions): DiscoveredCommands {
-  // 1. Preference commands
+  // 1. Preference commands (still sanitize — may contain prose from misconfiguration)
   if (options.preferenceCommands && options.preferenceCommands.length > 0) {
     const filtered = options.preferenceCommands
       .map(c => c.trim())
-      .filter(Boolean);
+      .filter(Boolean)
+      .filter(c => isLikelyCommand(c));
     if (filtered.length > 0) {
       return { commands: filtered, source: "preference" };
     }
@@ -110,7 +112,9 @@ const MAX_FAILURE_CONTEXT_CHARS = 10_000;
  * Returns an empty string when all checks pass or the checks array is empty.
  */
 export function formatFailureContext(result: VerificationResult): string {
-  const failures = result.checks.filter((c) => c.exitCode !== 0);
+  // Only include blocking failures in retry context — non-blocking (advisory) failures
+  // should not be injected into retry prompts to avoid noise pollution.
+  const failures = result.checks.filter((c) => c.exitCode !== 0 && c.blocking);
   if (failures.length === 0) return "";
 
   const blocks: string[] = [];
@@ -143,18 +147,81 @@ export function formatFailureContext(result: VerificationResult): string {
 /** Characters that indicate shell injection when found in a command string. */
 const SHELL_INJECTION_PATTERN = /[;|`]|\$\(/;
 
+/**
+ * Known executable first-tokens that are safe to run.
+ * Lowercase commands, common build/test tools, and npm/yarn/pnpm invocations.
+ */
+const KNOWN_COMMAND_PREFIXES = new Set([
+  "npm", "npx", "yarn", "pnpm", "bun", "bunx", "deno",
+  "node", "ts-node", "tsx", "tsc",
+  "sh", "bash", "zsh",
+  "echo", "cat", "ls", "test", "true", "false", "pwd", "env",
+  "make", "cargo", "go", "python", "python3", "pip", "pip3",
+  "ruby", "gem", "bundle", "rake",
+  "java", "javac", "mvn", "gradle",
+  "docker", "docker-compose",
+  "git", "gh",
+  "eslint", "prettier", "vitest", "jest", "mocha", "pytest", "phpunit",
+  "curl", "wget",
+  "grep", "find", "diff", "wc", "sort", "head", "tail",
+]);
+
+/**
+ * Heuristic check: does this string look like an executable shell command
+ * rather than a prose description?
+ *
+ * Returns true when the string appears to be a command. Returns false
+ * for English prose (e.g. "Document exists, contains all 5 scale names").
+ *
+ * Heuristics (any true → command-like):
+ *   1. First token is a known command prefix
+ *   2. First token starts with `.` or `/` (path-like)
+ *   3. Any token starts with `-` (flag-like)
+ *   4. First token contains no uppercase letters (commands are lowercase)
+ *      AND first token does not end with a comma or colon (prose punctuation)
+ *
+ * Heuristics (any true → prose-like):
+ *   1. First token starts with an uppercase letter and the string has 4+ words
+ *   2. String contains commas followed by spaces (prose clause structure)
+ */
+export function isLikelyCommand(cmd: string): boolean {
+  const trimmed = cmd.trim();
+  if (!trimmed) return false;
+
+  const tokens = trimmed.split(/\s+/);
+  const firstToken = tokens[0];
+
+  // Known command prefix → definitely a command
+  if (KNOWN_COMMAND_PREFIXES.has(firstToken)) return true;
+
+  // Path-like first token → command
+  if (firstToken.startsWith("/") || firstToken.startsWith("./") || firstToken.startsWith("../")) return true;
+
+  // Has flag-like tokens → command
+  if (tokens.some(t => t.startsWith("-"))) return true;
+
+  // First token starts with uppercase + 4 or more words → prose
+  if (/^[A-Z]/.test(firstToken) && tokens.length >= 4) return false;
+
+  // Contains comma-space patterns (prose clause separators) → prose
+  if (/,\s/.test(trimmed) && tokens.length >= 4) return false;
+
+  // First token has uppercase letters and no path separators → prose
+  if (/[A-Z]/.test(firstToken) && !firstToken.includes("/")) return false;
+
+  return true;
+}
+
 /**
  * Validate a command string for obvious shell injection patterns.
  * Returns the command unchanged if safe, or null if suspicious.
  */
 function sanitizeCommand(cmd: string): string | null {
   if (SHELL_INJECTION_PATTERN.test(cmd)) return null;
+  if (!isLikelyCommand(cmd)) return null;
   return cmd;
 }
 
-/** Default timeout for verification commands (ms). */
-const DEFAULT_COMMAND_TIMEOUT_MS = 120_000;
-
 export interface RunVerificationGateOptions {
   basePath: string;
   unitId: string;
@@ -191,6 +258,10 @@ export function runVerificationGate(options: RunVerificationGateOptions): Verifi
     };
   }
 
+  // Commands from preference and task-plan sources are blocking;
+  // package-json discovered commands are advisory (non-blocking).
+  const blocking = source === "preference" || source === "task-plan";
+
   const checks: VerificationCheck[] = [];
 
   for (const command of commands) {
@@ -226,11 +297,16 @@ export function runVerificationGate(options: RunVerificationGateOptions): Verifi
       stdout: truncate(result.stdout, MAX_OUTPUT_BYTES),
       stderr,
       durationMs,
+      blocking,
     });
   }
 
+  // Gate passes if all blocking checks pass (non-blocking failures are advisory)
+  const blockingChecks = checks.filter(c => c.blocking);
+  const passed = blockingChecks.length === 0 || blockingChecks.every(c => c.exitCode === 0);
+
   return {
-    passed: checks.every(c => c.exitCode === 0),
+    passed,
     checks,
     discoverySource: source,
     timestamp,

package/src/resources/extensions/gsd/visualizer-data.ts

@@ -35,7 +35,7 @@ import type {
 export interface VisualizerMilestone {
   id: string;
   title: string;
-  status: 'complete' | 'active' | 'pending';
+  status: 'complete' | 'active' | 'pending' | 'parked';
   dependsOn: string[];
   slices: VisualizerSlice[];
 }

package/src/resources/extensions/gsd/visualizer-overlay.ts

@@ -15,7 +15,7 @@ import {
   type ProgressFilter,
 } from "./visualizer-views.js";
 import { writeExportFile } from "./export.js";
-import { stripAnsi } from "../shared/format-utils.js";
+import { stripAnsi } from "../shared/mod.js";
 
 const TAB_COUNT = 10;
 const TAB_LABELS = [
@@ -86,6 +86,9 @@ export class GSDVisualizerOverlay {
       this.data = d;
       this.loading = false;
       this.tui.requestRender();
+    }).catch(() => {
+      this.loading = false;
+      this.tui.requestRender();
     });
 
     this.refreshTimer = setInterval(() => {
@@ -94,7 +97,7 @@ export class GSDVisualizerOverlay {
         this.data = d;
         this.invalidate();
         this.tui.requestRender();
-      });
+      }).catch(() => {}); // retry on next interval
     }, 5000);
   }
 

package/src/resources/extensions/gsd/visualizer-views.ts

@@ -4,8 +4,7 @@ import type { Theme } from "@gsd/pi-coding-agent";
 import { truncateToWidth, visibleWidth } from "@gsd/pi-tui";
 import type { VisualizerData, VisualizerMilestone, SliceVerification, VisualizerSliceActivity, VisualizerStats, VisualizerSliceRef } from "./visualizer-data.js";
 import { formatCost, formatTokenCount, classifyUnitPhase } from "./metrics.js";
-import { formatDuration, padRight, joinColumns, sparkline } from "../shared/format-utils.js";
-import { STATUS_GLYPH, STATUS_COLOR } from "../shared/ui.js";
+import { formatDuration, padRight, joinColumns, sparkline, STATUS_GLYPH, STATUS_COLOR } from "../shared/mod.js";
 
 function formatCompletionDate(input: string): string {
   if (!input) return "unknown";
@@ -135,7 +134,7 @@ export function renderProgressView(
     }
 
     // Milestone header line
-    const msStatus = ms.status === "complete" ? "done" : ms.status === "active" ? "active" : "pending";
+    const msStatus = ms.status === "complete" ? "done" : ms.status === "active" ? "active" : ms.status === "parked" ? "paused" : "pending";
     const statusGlyph = th.fg(STATUS_COLOR[msStatus], STATUS_GLYPH[msStatus]);
     const statusLabel = th.fg(STATUS_COLOR[msStatus], ms.status);
 

package/src/resources/extensions/gsd/workflow-templates/bugfix.md

@@ -0,0 +1,87 @@
+# Bugfix Workflow
+
+<template_meta>
+name: bugfix
+version: 1
+requires_project: false
+artifact_dir: .gsd/workflows/bugfixes/
+</template_meta>
+
+<purpose>
+Fix a bug from identification through to PR submission. Designed for issues reported
+via GitHub, user reports, or developer discovery. Emphasizes root cause analysis
+before jumping to fixes.
+</purpose>
+
+<phases>
+1. triage    — Identify root cause, reproduce the bug
+2. fix       — Implement the fix with tests
+3. verify    — Run full test suite, check for regressions
+4. ship      — Create PR with detailed explanation
+</phases>
+
+<process>
+
+## Phase 1: Triage
+
+**Goal:** Understand the bug before touching any code.
+
+1. **Gather context:**
+   - If a GitHub issue was referenced, read the issue description, labels, and comments
+   - Identify the expected behavior vs actual behavior
+   - Note any error messages, stack traces, or reproduction steps provided
+
+2. **Reproduce:**
+   - Find the minimal reproduction path
+   - Identify the affected code paths (files, functions, lines)
+   - If the bug is intermittent, note the conditions that trigger it
+
+3. **Root cause analysis:**
+   - Trace the bug to its root cause (not just the symptom)
+   - Identify when the bug was introduced if possible (git blame/log)
+   - Assess blast radius: what else could be affected?
+
+4. **Produce:** Write a brief `TRIAGE.md` in the artifact directory with:
+   - Root cause explanation
+   - Reproduction steps
+   - Affected files/functions
+   - Proposed fix approach
+
+5. **Gate:** Present the triage findings and proposed fix to the user for confirmation.
+
+## Phase 2: Fix
+
+**Goal:** Implement a clean, tested fix.
+
+1. **Plan the fix:** Write a brief plan (1-3 tasks max)
+2. **Write the fix:** Implement the code change
+3. **Write tests:** Add or update tests that:
+   - Reproduce the original bug (test fails without fix)
+   - Verify the fix works
+   - Cover edge cases
+4. **Commit:** Atomic commit with message: `fix(<scope>): <description>`
+
+## Phase 3: Verify
+
+**Goal:** Ensure the fix doesn't break anything else.
+
+1. Run the project's full test suite
+2. Run the build (if applicable)
+3. Run the linter (if applicable)
+4. Check for regressions in related functionality
+5. If any failures, fix them before proceeding
+
+## Phase 4: Ship
+
+**Goal:** Create a well-documented PR.
+
+1. Ensure all changes are committed on the workflow branch
+2. Build the PR body:
+   - Link to the original issue (if applicable)
+   - Explain the root cause
+   - Describe the fix approach
+   - List the test coverage added
+3. Present the PR details to the user for review
+4. Create the PR via `gh pr create` (with user approval)
+
+</process>

package/src/resources/extensions/gsd/workflow-templates/dep-upgrade.md

@@ -0,0 +1,74 @@
+# Dependency Upgrade Workflow
+
+<template_meta>
+name: dep-upgrade
+version: 1
+requires_project: false
+artifact_dir: .gsd/workflows/upgrades/
+</template_meta>
+
+<purpose>
+Upgrade project dependencies safely. Assess breaking changes before upgrading,
+fix issues incrementally, and verify everything works. Handles both single-package
+upgrades and bulk dependency refresh.
+</purpose>
+
+<phases>
+1. assess  — Analyze what's outdated and what will break
+2. upgrade — Apply upgrades incrementally
+3. fix     — Resolve breaking changes
+4. verify  — Full test suite and build validation
+</phases>
+
+<process>
+
+## Phase 1: Assess
+
+**Goal:** Know what you're getting into before changing versions.
+
+1. **List outdated dependencies:** Run `npm outdated` / equivalent
+2. **For each target upgrade:**
+   - Read the changelog / release notes
+   - Identify breaking changes
+   - Check for known migration guides
+   - Assess impact on the codebase (grep for affected APIs)
+3. **Prioritize:** Which upgrades to do now, which to defer
+4. **Produce:** Write `ASSESSMENT.md` with:
+   - Dependency list with current → target versions
+   - Breaking changes per dependency
+   - Upgrade order (dependencies before dependents)
+   - Risk assessment
+
+5. **Gate:** Review assessment with user. Confirm upgrade scope.
+
+## Phase 2: Upgrade
+
+**Goal:** Apply version bumps incrementally.
+
+1. Upgrade one dependency (or one group of related dependencies) at a time
+2. Run tests after each upgrade
+3. Commit each upgrade: `chore(deps): upgrade <package> to <version>`
+4. If tests fail, move to Phase 3 for that dependency before continuing
+
+## Phase 3: Fix
+
+**Goal:** Resolve any breaking changes from upgrades.
+
+1. Fix API changes, type errors, deprecations
+2. Update configuration if needed
+3. Commit fixes separately from the upgrade: `fix(deps): adapt to <package> v<version> changes`
+
+## Phase 4: Verify
+
+**Goal:** Ensure everything works together.
+
+1. Run the full test suite
+2. Run the build
+3. Run the linter
+4. Check for deprecation warnings in output
+5. **Produce:** Write `SUMMARY.md` with:
+   - Dependencies upgraded (from → to)
+   - Breaking changes encountered and how they were resolved
+   - Any deferred upgrades and why
+
+</process>

package/src/resources/extensions/gsd/workflow-templates/full-project.md

@@ -0,0 +1,41 @@
+# Full Project Workflow
+
+<template_meta>
+name: full-project
+version: 1
+requires_project: true
+artifact_dir: .gsd/
+</template_meta>
+
+<purpose>
+The complete GSD workflow with full ceremony: roadmap, milestones, slices, tasks,
+research, planning, execution, and verification. Use for greenfield projects or
+major features that need the full planning apparatus.
+
+This template wraps the existing GSD workflow for registry completeness.
+When selected, it routes to the standard /gsd init → /gsd auto pipeline.
+</purpose>
+
+<phases>
+1. init    — Initialize project, detect stack, create .gsd/
+2. discuss — Define requirements, decisions, and architecture
+3. plan    — Create roadmap with milestones and slices
+4. execute — Execute slices: research → plan → implement → verify per slice
+5. verify  — Milestone-level verification and completion
+</phases>
+
+<process>
+
+## Routing to Standard GSD
+
+This template is a convenience entry point. When selected via `/gsd start full-project`,
+it should route to the standard GSD workflow:
+
+1. If `.gsd/` doesn't exist: Run `/gsd init` to bootstrap the project
+2. If `.gsd/` exists but no milestones: Start the discuss phase via `/gsd discuss`
+3. If milestones exist: Resume via `/gsd auto` or `/gsd next`
+
+The full GSD workflow protocol is defined in `GSD-WORKFLOW.md` and handles all
+phases, state tracking, and agent orchestration.
+
+</process>

package/src/resources/extensions/gsd/workflow-templates/hotfix.md

@@ -0,0 +1,45 @@
+# Hotfix Workflow
+
+<template_meta>
+name: hotfix
+version: 1
+requires_project: false
+artifact_dir: null
+</template_meta>
+
+<purpose>
+Minimal ceremony for urgent fixes. Fix it, test it, ship it. No planning artifacts,
+no research phase, no lengthy documentation. For when production is broken and
+speed matters.
+</purpose>
+
+<phases>
+1. fix  — Identify and fix the issue
+2. ship — Test, commit, and create PR
+</phases>
+
+<process>
+
+## Phase 1: Fix
+
+**Goal:** Find and fix the issue as fast as possible.
+
+1. Identify the broken behavior
+2. Locate the root cause
+3. Implement the minimal fix
+4. Add a regression test if possible (don't block on this if the fix is urgent)
+5. Commit: `fix(<scope>): <description>`
+
+## Phase 2: Ship
+
+**Goal:** Get the fix deployed.
+
+1. Run tests — fix any failures
+2. Run the build
+3. Push and create PR with:
+   - What broke
+   - What the fix does
+   - How to verify
+4. Present PR to user for approval
+
+</process>

package/src/resources/extensions/gsd/workflow-templates/refactor.md

@@ -0,0 +1,83 @@
+# Refactor / Migration Workflow
+
+<template_meta>
+name: refactor
+version: 1
+requires_project: false
+artifact_dir: .gsd/workflows/refactors/
+</template_meta>
+
+<purpose>
+Systematic code transformation with inventory-driven planning. Designed for
+renames, restructures, pattern migrations, and API modernization. Executes in
+waves to minimize risk and enable incremental verification.
+</purpose>
+
+<phases>
+1. inventory — Catalog everything that needs to change
+2. plan      — Group changes into safe waves
+3. migrate   — Execute waves with verification between each
+4. verify    — Full regression testing and cleanup
+</phases>
+
+<process>
+
+## Phase 1: Inventory
+
+**Goal:** Know the full scope before changing anything.
+
+1. **Scan the codebase:** Find all instances of what needs to change
+   - Files, functions, types, imports, tests, docs, config
+   - Use grep/glob to be exhaustive — don't rely on memory
+2. **Categorize:** Group by type (source, test, config, docs)
+3. **Identify dependencies:** What order must changes happen in?
+4. **Produce:** Write `INVENTORY.md` with:
+   - Complete list of files/locations that need changes
+   - Dependency relationships
+   - Estimated scope (number of files, lines affected)
+
+5. **Gate:** Review inventory with user. Confirm nothing is missing.
+
+## Phase 2: Plan
+
+**Goal:** Break the migration into safe, independently-verifiable waves.
+
+1. **Define waves:** Group related changes so each wave:
+   - Leaves the codebase in a working state
+   - Can be committed and tested independently
+   - Handles dependencies (change the definition before the consumers)
+2. **Typical wave structure:**
+   - Wave 1: Types/interfaces
+   - Wave 2: Core implementation
+   - Wave 3: Consumers/callers
+   - Wave 4: Tests
+   - Wave 5: Documentation and config
+3. **Produce:** Write `PLAN.md` with waves and per-wave file lists
+
+4. **Gate:** Confirm plan with user.
+
+## Phase 3: Migrate
+
+**Goal:** Execute waves one at a time with verification between each.
+
+1. For each wave:
+   - Make the changes
+   - Run tests (at minimum, the build must pass)
+   - Commit: `refactor(<scope>): wave N — <description>`
+2. If a wave introduces failures, fix them before moving to the next wave
+3. If unexpected scope is discovered, update the inventory and plan
+
+## Phase 4: Verify
+
+**Goal:** Ensure the full refactor is complete and clean.
+
+1. Run the complete test suite
+2. Run the build
+3. Run the linter — fix any new warnings
+4. Search for any remnants of the old pattern (grep for old names/patterns)
+5. **Produce:** Write `SUMMARY.md` with:
+   - What was changed and why
+   - Files modified (count and list)
+   - Any remaining follow-up items
+
+</process>

package/src/resources/extensions/gsd/workflow-templates/registry.json

@@ -0,0 +1,85 @@
+{
+  "version": 1,
+  "templates": {
+    "full-project": {
+      "name": "Full Project",
+      "description": "Complete GSD workflow with roadmap, milestones, slices, and full ceremony",
+      "file": "full-project.md",
+      "phases": ["init", "discuss", "plan", "execute", "verify"],
+      "triggers": ["new project", "greenfield", "from scratch", "build an app", "create a new"],
+      "artifact_dir": ".gsd/",
+      "estimated_complexity": "high",
+      "requires_project": true
+    },
+    "bugfix": {
+      "name": "Bug Fix",
+      "description": "Triage, reproduce, fix, test, and ship a bug fix",
+      "file": "bugfix.md",
+      "phases": ["triage", "fix", "verify", "ship"],
+      "triggers": ["bug", "issue", "fix", "broken", "regression", "error", "crash", "failing", "github.com/*/issues/*"],
+      "artifact_dir": ".gsd/workflows/bugfixes/",
+      "estimated_complexity": "low",
+      "requires_project": false
+    },
+    "small-feature": {
+      "name": "Small Feature",
+      "description": "Lightweight feature development with optional discussion and research",
+      "file": "small-feature.md",
+      "phases": ["scope", "plan", "implement", "verify"],
+      "triggers": ["add", "feature", "implement", "build", "create", "new command", "new endpoint"],
+      "artifact_dir": ".gsd/workflows/features/",
+      "estimated_complexity": "medium",
+      "requires_project": false
+    },
+    "refactor": {
+      "name": "Refactor / Migration",
+      "description": "Systematic code transformation with inventory and wave-based execution",
+      "file": "refactor.md",
+      "phases": ["inventory", "plan", "migrate", "verify"],
+      "triggers": ["refactor", "migrate", "rename", "restructure", "move", "reorganize", "clean up"],
+      "artifact_dir": ".gsd/workflows/refactors/",
+      "estimated_complexity": "medium",
+      "requires_project": false
+    },
+    "spike": {
+      "name": "Research Spike",
+      "description": "Investigate a question, prototype, and document findings",
+      "file": "spike.md",
+      "phases": ["scope", "research", "synthesize"],
+      "triggers": ["research", "investigate", "explore", "spike", "compare", "evaluate", "should we", "what if", "how does"],
+      "artifact_dir": ".gsd/workflows/spikes/",
+      "estimated_complexity": "low",
+      "requires_project": false
+    },
+    "hotfix": {
+      "name": "Hotfix",
+      "description": "Minimal ceremony: fix the thing, test it, ship it",
+      "file": "hotfix.md",
+      "phases": ["fix", "ship"],
+      "triggers": ["hotfix", "urgent", "critical", "asap", "production down", "p0"],
+      "artifact_dir": null,
+      "estimated_complexity": "minimal",
+      "requires_project": false
+    },
+    "security-audit": {
+      "name": "Security Audit",
+      "description": "Scan for vulnerabilities, triage findings, remediate, and verify",
+      "file": "security-audit.md",
+      "phases": ["scan", "triage", "remediate", "re-scan"],
+      "triggers": ["security", "audit", "vulnerability", "owasp", "cve", "penetration", "hardening"],
+      "artifact_dir": ".gsd/workflows/audits/",
+      "estimated_complexity": "medium",
+      "requires_project": false
+    },
+    "dep-upgrade": {
+      "name": "Dependency Upgrade",
+      "description": "Assess impact, upgrade dependencies, fix breaking changes",
+      "file": "dep-upgrade.md",
+      "phases": ["assess", "upgrade", "fix", "verify"],
+      "triggers": ["upgrade", "update", "dependency", "deps", "bump", "outdated", "npm update", "renovate"],
+      "artifact_dir": ".gsd/workflows/upgrades/",
+      "estimated_complexity": "medium",
+      "requires_project": false
+    }
+  }
+}