gsd-pi 2.75.0 → 2.76.0-dev.4100bd590

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

@@ -5,6 +5,7 @@
       "name": "Full Project",
       "description": "Complete GSD workflow with roadmap, milestones, slices, and full ceremony",
       "file": "full-project.md",
+      "mode": "auto-milestone",
       "phases": ["init", "discuss", "plan", "execute", "verify"],
       "triggers": ["new project", "greenfield", "from scratch", "build an app", "create a new"],
       "artifact_dir": ".gsd/",
@@ -15,6 +16,7 @@
       "name": "Bug Fix",
       "description": "Triage, reproduce, fix, test, and ship a bug fix",
       "file": "bugfix.md",
+      "mode": "markdown-phase",
       "phases": ["triage", "fix", "verify", "ship"],
       "triggers": ["bug", "issue", "fix", "broken", "regression", "error", "crash", "failing", "github.com/*/issues/*"],
       "artifact_dir": ".gsd/workflows/bugfixes/",
@@ -25,6 +27,7 @@
       "name": "Small Feature",
       "description": "Lightweight feature development with optional discussion and research",
       "file": "small-feature.md",
+      "mode": "markdown-phase",
       "phases": ["scope", "plan", "implement", "verify"],
       "triggers": ["add", "feature", "implement", "build", "create", "new command", "new endpoint"],
       "artifact_dir": ".gsd/workflows/features/",
@@ -35,6 +38,7 @@
       "name": "Refactor / Migration",
       "description": "Systematic code transformation with inventory and wave-based execution",
       "file": "refactor.md",
+      "mode": "markdown-phase",
       "phases": ["inventory", "plan", "migrate", "verify"],
       "triggers": ["refactor", "migrate", "rename", "restructure", "move", "reorganize", "clean up"],
       "artifact_dir": ".gsd/workflows/refactors/",
@@ -45,6 +49,7 @@
       "name": "Research Spike",
       "description": "Investigate a question, prototype, and document findings",
       "file": "spike.md",
+      "mode": "markdown-phase",
       "phases": ["scope", "research", "synthesize"],
       "triggers": ["research", "investigate", "explore", "spike", "compare", "evaluate", "should we", "what if", "how does"],
       "artifact_dir": ".gsd/workflows/spikes/",
@@ -55,6 +60,7 @@
       "name": "Hotfix",
       "description": "Minimal ceremony: fix the thing, test it, ship it",
       "file": "hotfix.md",
+      "mode": "markdown-phase",
       "phases": ["fix", "ship"],
       "triggers": ["hotfix", "urgent", "critical", "asap", "production down", "p0"],
       "artifact_dir": null,
@@ -65,6 +71,7 @@
       "name": "Security Audit",
       "description": "Scan for vulnerabilities, triage findings, remediate, and verify",
       "file": "security-audit.md",
+      "mode": "markdown-phase",
       "phases": ["scan", "triage", "remediate", "re-scan"],
       "triggers": ["security", "audit", "vulnerability", "owasp", "cve", "penetration", "hardening"],
       "artifact_dir": ".gsd/workflows/audits/",
@@ -75,11 +82,188 @@
       "name": "Dependency Upgrade",
       "description": "Assess impact, upgrade dependencies, fix breaking changes",
       "file": "dep-upgrade.md",
+      "mode": "markdown-phase",
       "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
+    },
+    "pr-review": {
+      "name": "PR Review",
+      "description": "Walk git diff, produce structured review notes (oneshot — no state)",
+      "file": "pr-review.md",
+      "mode": "oneshot",
+      "phases": [],
+      "triggers": ["pr review", "code review", "review this pr", "review changes", "review diff"],
+      "artifact_dir": null,
+      "estimated_complexity": "low",
+      "requires_project": false
+    },
+    "changelog-gen": {
+      "name": "Changelog Generator",
+      "description": "Parse git log since last tag, categorize, write CHANGELOG entry (oneshot)",
+      "file": "changelog-gen.md",
+      "mode": "oneshot",
+      "phases": [],
+      "triggers": ["changelog", "release notes", "generate changelog", "what changed"],
+      "artifact_dir": null,
+      "estimated_complexity": "low",
+      "requires_project": false
+    },
+    "issue-triage": {
+      "name": "Issue Triage",
+      "description": "Categorize, label, prioritize a GitHub issue and suggest next action (oneshot)",
+      "file": "issue-triage.md",
+      "mode": "oneshot",
+      "phases": [],
+      "triggers": ["triage issue", "categorize issue", "label issue", "prioritize issue"],
+      "artifact_dir": null,
+      "estimated_complexity": "low",
+      "requires_project": false
+    },
+    "pr-triage": {
+      "name": "PR Triage",
+      "description": "Walk open PRs, flag stale, recommend merge/close/nudge (oneshot)",
+      "file": "pr-triage.md",
+      "mode": "oneshot",
+      "phases": [],
+      "triggers": ["triage prs", "pr triage", "open prs", "stale prs", "review open prs"],
+      "artifact_dir": null,
+      "estimated_complexity": "low",
+      "requires_project": false
+    },
+    "onboarding-check": {
+      "name": "Onboarding Check",
+      "description": "Verify README setup works end-to-end for a new contributor (oneshot)",
+      "file": "onboarding-check.md",
+      "mode": "oneshot",
+      "phases": [],
+      "triggers": ["onboarding", "new contributor", "setup check", "readme check", "verify setup"],
+      "artifact_dir": null,
+      "estimated_complexity": "low",
+      "requires_project": false
+    },
+    "dead-code": {
+      "name": "Dead Code Finder",
+      "description": "Find unused code and report; human approves before removal (oneshot)",
+      "file": "dead-code.md",
+      "mode": "oneshot",
+      "phases": [],
+      "triggers": ["dead code", "unused code", "unreachable", "remove unused"],
+      "artifact_dir": null,
+      "estimated_complexity": "low",
+      "requires_project": false
+    },
+    "accessibility-audit": {
+      "name": "Accessibility Audit",
+      "description": "A11y scan with remediation recommendations (oneshot)",
+      "file": "accessibility-audit.md",
+      "mode": "oneshot",
+      "phases": [],
+      "triggers": ["a11y", "accessibility", "wcag", "screen reader", "aria"],
+      "artifact_dir": null,
+      "estimated_complexity": "low",
+      "requires_project": false
+    },
+    "test-backfill": {
+      "name": "Test Backfill",
+      "description": "Iterate untested functions, add tests, shell-verify suite (yaml engine)",
+      "file": "test-backfill.yaml",
+      "mode": "yaml-step",
+      "phases": [],
+      "triggers": ["test backfill", "backfill tests", "add missing tests", "coverage gap"],
+      "artifact_dir": null,
+      "estimated_complexity": "medium",
+      "requires_project": false
+    },
+    "docs-sync": {
+      "name": "Docs Sync",
+      "description": "Iterate undocumented exports, update JSDoc/README (yaml engine)",
+      "file": "docs-sync.yaml",
+      "mode": "yaml-step",
+      "phases": [],
+      "triggers": ["docs sync", "sync docs", "update docs", "document exports"],
+      "artifact_dir": null,
+      "estimated_complexity": "medium",
+      "requires_project": false
+    },
+    "rename-symbol": {
+      "name": "Rename Symbol",
+      "description": "Iterate files containing symbol, rename, verify build+tests (yaml engine)",
+      "file": "rename-symbol.yaml",
+      "mode": "yaml-step",
+      "phases": [],
+      "triggers": ["rename symbol", "rename function", "rename variable", "rename class"],
+      "artifact_dir": null,
+      "estimated_complexity": "medium",
+      "requires_project": false
+    },
+    "env-audit": {
+      "name": "Env Audit",
+      "description": "Iterate env vars across code/docs/CI, flag drift (yaml engine)",
+      "file": "env-audit.yaml",
+      "mode": "yaml-step",
+      "phases": [],
+      "triggers": ["env audit", "audit env", "env vars", "environment variables"],
+      "artifact_dir": null,
+      "estimated_complexity": "medium",
+      "requires_project": false
+    },
+    "release": {
+      "name": "Release",
+      "description": "Version bump, changelog, tag, publish — phased with approval gates",
+      "file": "release.md",
+      "mode": "markdown-phase",
+      "phases": ["prepare", "bump", "publish", "announce"],
+      "triggers": ["release", "ship release", "cut release", "tag release", "publish release"],
+      "artifact_dir": ".gsd/workflows/releases/",
+      "estimated_complexity": "medium",
+      "requires_project": false
+    },
+    "api-breaking-change": {
+      "name": "API Breaking Change",
+      "description": "Find callers, migrate, deprecate, release — multi-session phased",
+      "file": "api-breaking-change.md",
+      "mode": "markdown-phase",
+      "phases": ["survey", "migrate", "deprecate", "release"],
+      "triggers": ["breaking change", "api break", "remove api", "deprecate"],
+      "artifact_dir": ".gsd/workflows/api-breaks/",
+      "estimated_complexity": "high",
+      "requires_project": false
+    },
+    "performance-audit": {
+      "name": "Performance Audit",
+      "description": "Profile hot paths, prioritize, implement fixes, verify — phased",
+      "file": "performance-audit.md",
+      "mode": "markdown-phase",
+      "phases": ["profile", "prioritize", "fix", "verify"],
+      "triggers": ["performance", "slow", "perf audit", "bottleneck", "optimize"],
+      "artifact_dir": ".gsd/workflows/perf/",
+      "estimated_complexity": "medium",
+      "requires_project": false
+    },
+    "observability-setup": {
+      "name": "Observability Setup",
+      "description": "Survey, design, add logging/metrics/traces, verify — phased",
+      "file": "observability-setup.md",
+      "mode": "markdown-phase",
+      "phases": ["survey", "design", "implement", "verify"],
+      "triggers": ["observability", "logging", "metrics", "tracing", "opentelemetry"],
+      "artifact_dir": ".gsd/workflows/observability/",
+      "estimated_complexity": "medium",
+      "requires_project": false
+    },
+    "ci-bootstrap": {
+      "name": "CI Bootstrap",
+      "description": "Discover stack, design pipeline, implement, verify — phased",
+      "file": "ci-bootstrap.md",
+      "mode": "markdown-phase",
+      "phases": ["discover", "design", "implement", "verify"],
+      "triggers": ["ci bootstrap", "setup ci", "github actions", "build pipeline", "test pipeline"],
+      "artifact_dir": ".gsd/workflows/ci/",
+      "estimated_complexity": "medium",
+      "requires_project": false
     }
   }
 }

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

@@ -0,0 +1,118 @@
+# Release Workflow
+
+<template_meta>
+name: release
+version: 1
+mode: markdown-phase
+requires_project: false
+artifact_dir: .gsd/workflows/releases/
+</template_meta>
+
+<purpose>
+Cut a software release in four phases with approval gates. Handles version
+bump, changelog generation, tag creation, and publish/announce. Conservative
+by default — prompts for confirmation before any action that's visible outside
+the repo.
+</purpose>
+
+<phases>
+1. prepare  — Decide version bump, verify state
+2. bump     — Write version, changelog, create tag
+3. publish  — Push tag, run release pipeline
+4. announce — Post release notes
+</phases>
+
+<process>
+
+## Phase 1: Prepare
+
+**Goal:** Decide the version bump and confirm the repo is ready to release.
+
+1. **Read the state of the repo:**
+   - `git log <last_tag>..HEAD --oneline --no-merges` — commits since last release.
+   - Check for uncommitted changes (`git status`).
+   - Identify the branch (release from main/master unless explicitly told otherwise).
+
+2. **Propose a semver bump:**
+   - `major` if any commit has a `BREAKING CHANGE:` footer or `!` suffix.
+   - `minor` if any commit is `feat:` / `feature:`.
+   - `patch` otherwise.
+   - Print: current version, proposed next version, and the commit categorization.
+
+3. **Write `PREPARE.md`** in the artifact directory with:
+   - Proposed version.
+   - Commit summary grouped by type.
+   - Any concerns (unmerged PRs, failing CI, recent reverts).
+
+4. **Gate:** Present the plan and ask the user to confirm the version before
+   proceeding. If the user wants a different bump, record the rationale.
+
+## Phase 2: Bump
+
+**Goal:** Commit the version bump and write the changelog.
+
+1. **Bump the version** in the appropriate file(s):
+   - Node: `package.json` (and workspace `package.json`s if monorepo).
+   - Python: `pyproject.toml` / `setup.py` / `__version__`.
+   - Rust: `Cargo.toml`.
+   - Other: ask if unsure.
+
+2. **Generate the changelog entry** — follow Keep a Changelog format. Add it
+   to `CHANGELOG.md` under `## [x.y.z] - YYYY-MM-DD`. Preserve all existing
+   entries untouched.
+
+3. **Commit:**
+   ```
+   chore(release): v<x.y.z>
+   ```
+
+4. **Create an annotated tag:**
+   ```
+   git tag -a v<x.y.z> -m "Release v<x.y.z>"
+   ```
+   Don't push yet.
+
+5. **Gate:** Show the diff (`git show HEAD`, `git show v<x.y.z>`) and confirm
+   before pushing.
+
+## Phase 3: Publish
+
+**Goal:** Push the release and kick off downstream pipelines.
+
+1. **Push commit + tag:**
+   ```
+   git push origin <branch>
+   git push origin v<x.y.z>
+   ```
+
+2. **Trigger the release pipeline** if applicable:
+   - GitHub Actions release workflow (often triggered by tag push).
+   - `npm publish`, `cargo publish`, `pypi upload` — only if explicitly asked.
+
+3. **Verify:**
+   - CI passes on the tagged commit.
+   - Release artifact appears where expected (GitHub releases, registry, etc).
+
+4. **Gate:** Confirm the release is live and visible before announcing.
+
+## Phase 4: Announce
+
+**Goal:** Make the release discoverable.
+
+1. **Create or update the GitHub Release** (via `gh release create` or an
+   existing workflow output). Include:
+   - Tag name.
+   - Title: `v<x.y.z>`.
+   - Body: the CHANGELOG entry for this version.
+
+2. **Optional follow-ups** (ask the user first):
+   - Slack / Discord announcement draft.
+   - Update docs / examples that reference the version.
+   - Close any milestone linked to this release.
+
+3. **Write `RELEASE.md`** in the artifact dir capturing:
+   - What shipped.
+   - Links to the release, changelog, and key PRs.
+   - Any post-release follow-ups.
+
+</process>

package/src/resources/extensions/gsd/workflow-templates/rename-symbol.yaml

@@ -0,0 +1,99 @@
+# Rename Symbol workflow — mode: yaml-step
+#
+# Rename a symbol across the codebase. Inventories call sites, renames each
+# file atomically, and verifies the project still builds and tests pass.
+#
+# Run with: /gsd workflow rename-symbol old_name=foo new_name=bar
+
+version: 1
+name: rename-symbol
+mode: yaml-step
+description: >-
+  Find all occurrences of a symbol and rename it across the codebase,
+  verifying the build and tests stay green.
+
+params:
+  old_name: "OLD_SYMBOL_HERE"
+  new_name: "NEW_SYMBOL_HERE"
+  src_glob: "src/**/*.ts"
+  build_command: "npm run build"
+  test_command: "npm test"
+
+steps:
+  - id: inventory
+    name: Find files that reference the symbol
+    prompt: >-
+      Search {{src_glob}} for files that reference the symbol `{{old_name}}`.
+      Include callers, imports, and any string references that look like
+      identifier usage (but skip unrelated word matches in comments/docs).
+
+      Write one file path per line:
+
+        - <relative file path>
+
+      Save to `rename-targets.md`. If there are zero matches, write
+      "no matches" and no items.
+    requires: []
+    produces:
+      - rename-targets.md
+    verify:
+      policy: content-heuristic
+
+  - id: rename-file
+    name: Rename in one file
+    prompt: >-
+      In the file indicated by {{_iter_capture_1}}, rename every
+      identifier-style occurrence of `{{old_name}}` to `{{new_name}}`.
+
+      - Only replace actual code references (identifiers, imports).
+      - Leave unrelated substrings (e.g. comments that happen to contain
+        the word but aren't referring to the symbol) alone.
+      - Preserve surrounding formatting.
+      - If the file defines `{{old_name}}` directly, rename the definition too.
+
+      Append a log line to `rename-log.md`:
+      `- <file> — <count> replacement(s)`.
+    requires:
+      - inventory
+    context_from:
+      - inventory
+    produces:
+      - rename-log.md
+    iterate:
+      source: rename-targets.md
+      pattern: "^- (.+)$"
+    verify:
+      policy: content-heuristic
+
+  - id: verify-build
+    name: Verify the build
+    prompt: >-
+      Run the build: `{{build_command}}`. If it fails, examine the failure
+      and report the root cause in `rename-build.md` — the rename may have
+      broken something that needs a manual fix before proceeding.
+    requires:
+      - rename-file
+    context_from:
+      - rename-file
+    produces:
+      - rename-build.md
+    verify:
+      policy: shell-command
+      command: "{{build_command}}"
+
+  - id: verify-tests
+    name: Verify the test suite
+    prompt: >-
+      Run the tests: `{{test_command}}`. If any fail, report which tests
+      failed and why in `rename-tests.md`. Tests that reference the old
+      name in string literals (e.g. snapshot tests, API contracts) may
+      need intentional updates.
+    requires:
+      - verify-build
+    context_from:
+      - verify-build
+    produces:
+      - rename-tests.md
+    verify:
+      policy: shell-command
+      command: "{{test_command}}"

package/src/resources/extensions/gsd/workflow-templates/security-audit.md

@@ -3,6 +3,7 @@
 <template_meta>
 name: security-audit
 version: 1
+mode: markdown-phase
 requires_project: false
 artifact_dir: .gsd/workflows/audits/
 </template_meta>

package/src/resources/extensions/gsd/workflow-templates/small-feature.md

@@ -3,6 +3,7 @@
 <template_meta>
 name: small-feature
 version: 1
+mode: markdown-phase
 requires_project: false
 artifact_dir: .gsd/workflows/features/
 </template_meta>

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

@@ -3,6 +3,7 @@
 <template_meta>
 name: spike
 version: 1
+mode: markdown-phase
 requires_project: false
 artifact_dir: .gsd/workflows/spikes/
 </template_meta>
@@ -65,5 +66,11 @@ Use for: technology evaluation, architecture decisions, "should we X?" questions
    - Recommendation with rationale
    - Next steps if the recommendation is accepted
 4. **Present** the recommendation to the user for discussion
+5. **Offer wrap-up:** If the findings are reusable on future work, offer to run
+   the `spike-wrap-up` skill to package them as a project-local skill at
+   `.claude/skills/<name>/SKILL.md`. That skill will auto-load on future
+   similar tasks via `skill-discovery.ts`. If the recommendation is
+   decision-only (no reusable guidance), suggest appending a one-liner to
+   `.gsd/DECISIONS.md` instead.
 
 </process>

package/src/resources/extensions/gsd/workflow-templates/test-backfill.yaml

@@ -0,0 +1,73 @@
+# Test Backfill workflow — mode: yaml-step
+#
+# Iterate over functions that lack unit tests, write a test for each, and
+# shell-verify the suite stays green. Use for paying down coverage debt.
+
+version: 1
+name: test-backfill
+mode: yaml-step
+description: >-
+  Inventory untested functions, write a focused test for each,
+  and verify the test suite passes after each addition.
+
+params:
+  test_command: "npm test"
+  src_glob: "src/**/*.ts"
+
+steps:
+  - id: inventory
+    name: Inventory untested functions
+    prompt: >-
+      Scan the source tree (glob: {{src_glob}}) and identify exported
+      functions, classes, and React components that have no direct unit
+      test. Write one finding per line as a Markdown list item:
+
+        - <file_path>::<symbol_name> — <1-line reason it's worth testing>
+
+      Save the list to `untested.md`. If nothing is untested, write a
+      single line "all covered" and no list items.
+    requires: []
+    produces:
+      - untested.md
+    verify:
+      policy: content-heuristic
+      minSize: 1
+
+  - id: write-test
+    name: Write a test for one untested symbol
+    prompt: >-
+      Write a unit test for the symbol indicated by the captured path.
+      The symbol reference in {{_iter_capture_1}} has the form
+      `<file_path>::<symbol_name>`. Follow the project's existing test
+      conventions (framework, style, file naming). Add the test file
+      alongside existing tests or under a parallel tests/ tree.
+
+      After writing, append a one-line note to `backfill-log.md`:
+      `- <symbol_name> — <test file path> — <pass|fail>`.
+    requires:
+      - inventory
+    context_from:
+      - inventory
+    produces:
+      - backfill-log.md
+    iterate:
+      source: untested.md
+      pattern: "^- (.+::.+?) — "
+    verify:
+      policy: shell-command
+      command: "{{test_command}}"
+
+  - id: summary
+    name: Produce coverage summary
+    prompt: >-
+      Summarize the session: how many symbols got tests, how many were
+      skipped and why, and what remains in `untested.md` that would
+      benefit from human review. Save to `backfill-summary.md`.
+    requires:
+      - write-test
+    context_from:
+      - write-test
+    produces:
+      - backfill-summary.md
+    verify:
+      policy: content-heuristic

package/src/resources/extensions/gsd/workflow-templates.ts

@@ -25,10 +25,17 @@ function resolveGsdExtensionDir(): string {
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 
+export type WorkflowMode =
+  | "oneshot"
+  | "yaml-step"
+  | "markdown-phase"
+  | "auto-milestone";
+
 export interface TemplateEntry {
   name: string;
   description: string;
   file: string;
+  mode?: WorkflowMode;
   phases: string[];
   triggers: string[];
   artifact_dir: string | null;

package/src/resources/extensions/gsd/workspace-index.ts

@@ -43,9 +43,7 @@ export interface WorkspaceMilestoneTarget {
   id: string;
   title: string;
   roadmapPath?: string;
-  /** Authoritative milestone lifecycle status from the GSD state registry. */
   status?: "complete" | "active" | "pending" | "parked";
-  /** Milestone validation verdict, when validation has been performed. */
   validationVerdict?: "pass" | "needs-attention" | "needs-remediation";
   slices: WorkspaceSliceTarget[];
 }
@@ -56,7 +54,12 @@ export interface WorkspaceScopeTarget {
   kind: "project" | "milestone" | "slice" | "task";
 }
 
-export interface GSDWorkspaceIndex {
+export interface WorkspaceValidationIssue {
+  message?: string;
+  [key: string]: unknown;
+}
+
+export interface WorkspaceIndex {
   milestones: WorkspaceMilestoneTarget[];
   active: {
     milestoneId?: string;
@@ -65,9 +68,11 @@ export interface GSDWorkspaceIndex {
     phase: string;
   };
   scopes: WorkspaceScopeTarget[];
-  validationIssues: Array<Record<string, unknown>>;
+  validationIssues: WorkspaceValidationIssue[];
 }
 
+export type GSDWorkspaceIndex = WorkspaceIndex;
+
 // Extract milestone title from roadmap header without using parsers.
 // Falls back to the milestone ID if no title line found.
 function titleFromRoadmapHeader(content: string, fallbackId: string): string {