gsd-pi 2.75.0-dev.063e5a3 → 2.75.0-dev.fd2382b9f

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>

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 {

package/src/resources/extensions/gsd/worktree-resolver.ts

@@ -44,6 +44,7 @@ export interface WorktreeResolverDeps {
   ) => void;
   createAutoWorktree: (basePath: string, milestoneId: string) => string;
   enterAutoWorktree: (basePath: string, milestoneId: string) => string;
+  enterBranchModeForMilestone: (basePath: string, milestoneId: string) => void;
   getAutoWorktreePath: (basePath: string, milestoneId: string) => string | null;
   autoCommitCurrentBranch: (
     basePath: string,
@@ -162,7 +163,9 @@ export class WorktreeResolver {
       return;
     }
 
-    if (!this.deps.shouldUseWorktreeIsolation()) {
+    const mode = this.deps.getIsolationMode();
+
+    if (mode === "none") {
       debugLog("WorktreeResolver", {
         action: "enterMilestone",
         milestoneId,
@@ -183,9 +186,52 @@ export class WorktreeResolver {
     debugLog("WorktreeResolver", {
       action: "enterMilestone",
       milestoneId,
+      mode,
       basePath,
     });
 
+    // ── Branch mode: create/checkout milestone branch, stay in project root ──
+    if (mode === "branch") {
+      try {
+        this.deps.enterBranchModeForMilestone(basePath, milestoneId);
+        // basePath does not change — no worktree, no chdir.
+        // Rebuild GitService so the new HEAD is reflected, then flush any
+        // path-keyed caches that may have been populated before the checkout.
+        this.rebuildGitService();
+        this.deps.invalidateAllCaches();
+        debugLog("WorktreeResolver", {
+          action: "enterMilestone",
+          milestoneId,
+          mode: "branch",
+          result: "success",
+        });
+        emitJournalEvent(basePath, {
+          ts: new Date().toISOString(),
+          flowId: randomUUID(),
+          seq: 0,
+          eventType: "worktree-skip",
+          data: { milestoneId, reason: "branch-mode-no-worktree" },
+        });
+        ctx.notify(`Switched to branch milestone/${milestoneId}.`, "info");
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        debugLog("WorktreeResolver", {
+          action: "enterMilestone",
+          milestoneId,
+          mode: "branch",
+          result: "error",
+          error: msg,
+        });
+        ctx.notify(
+          `Branch isolation setup for ${milestoneId} failed: ${msg}. Continuing on current branch.`,
+          "warning",
+        );
+        this.s.isolationDegraded = true;
+      }
+      return;
+    }
+
+    // ── Worktree mode ─────────────────────────────────────────────────────────
     try {
       const existingPath = this.deps.getAutoWorktreePath(basePath, milestoneId);
       let wtPath: string;