gsd-pi 2.75.0 → 2.76.0-dev.b072ebb73

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

@@ -0,0 +1,403 @@
+/**
+ * workflow-plugins.ts — Unified discovery for workflow plugins.
+ *
+ * Discovers workflow definitions from three tiers (project > global > bundled)
+ * in both YAML and markdown formats. Each plugin declares an execution mode
+ * that controls how `/gsd workflow <name>` dispatches it:
+ *
+ *   oneshot         — prompt-only, no state or scaffolding
+ *   yaml-step       — CustomWorkflowEngine run with GRAPH.yaml
+ *   markdown-phase  — STATE.json + phase gates (current md template behavior)
+ *   auto-milestone  — hooks into /gsd auto pipeline (full-project only)
+ *
+ * Precedence: project > global > bundled. Same-named file wins.
+ */
+
+import {
+  readFileSync,
+  readdirSync,
+  existsSync,
+  statSync,
+} from "node:fs";
+import { join, dirname, extname, basename } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+import { parse as parseYaml } from "yaml";
+
+import { loadRegistry, type TemplateEntry, type WorkflowMode } from "./workflow-templates.js";
+
+export type { WorkflowMode } from "./workflow-templates.js";
+
+export type PluginSource = "project" | "global" | "bundled";
+export type PluginFormat = "yaml" | "md";
+
+export interface WorkflowPluginMeta {
+  displayName: string;
+  description?: string;
+  mode: WorkflowMode;
+  phases?: string[];
+  triggers?: string[];
+  complexity?: string;
+  artifactDir?: string | null;
+  requiresProject?: boolean;
+}
+
+export interface WorkflowPlugin {
+  name: string;
+  path: string;
+  format: PluginFormat;
+  source: PluginSource;
+  meta: WorkflowPluginMeta;
+  /** Populated if the plugin failed validation — discovery still succeeds. */
+  error?: string;
+}
+
+// ─── Path resolution ─────────────────────────────────────────────────────
+
+function resolveBundledDir(): string {
+  const moduleDir = dirname(fileURLToPath(import.meta.url));
+  const local = join(moduleDir, "workflow-templates");
+  if (existsSync(local)) return local;
+  const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
+  const agentGsdDir = join(gsdHome, "agent", "extensions", "gsd", "workflow-templates");
+  if (existsSync(agentGsdDir)) return agentGsdDir;
+  return local;
+}
+
+function globalPluginsDir(): string {
+  const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
+  return join(gsdHome, "workflows");
+}
+
+function projectPluginsDir(basePath: string): string {
+  return join(basePath, ".gsd", "workflows");
+}
+
+function legacyDefsDir(basePath: string): string {
+  return join(basePath, ".gsd", "workflow-defs");
+}
+
+// ─── Markdown frontmatter parsing ────────────────────────────────────────
+
+/**
+ * Parse the `<template_meta>` block from bundled/user markdown workflow files.
+ * Returns a loose key-value map (strings only).
+ */
+function parseTemplateMeta(content: string): Record<string, string> {
+  const match = content.match(/<template_meta>([\s\S]*?)<\/template_meta>/);
+  if (!match) return {};
+
+  const body = match[1];
+  const result: Record<string, string> = {};
+  for (const line of body.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    const colon = trimmed.indexOf(":");
+    if (colon === -1) continue;
+    const key = trimmed.slice(0, colon).trim();
+    const value = trimmed.slice(colon + 1).trim();
+    result[key] = value;
+  }
+  return result;
+}
+
+function parsePhasesFromMarkdown(content: string): string[] {
+  const match = content.match(/<phases>([\s\S]*?)<\/phases>/);
+  if (!match) return [];
+  const phases: string[] = [];
+  for (const line of match[1].split(/\r?\n/)) {
+    const m = line.match(/^\s*\d+\.\s*(\S+)/);
+    if (m) phases.push(m[1]);
+  }
+  return phases;
+}
+
+function firstHeading(content: string): string | undefined {
+  const match = content.match(/^#\s+(.+)$/m);
+  return match ? match[1].trim() : undefined;
+}
+
+function isValidMode(v: unknown): v is WorkflowMode {
+  return v === "oneshot" || v === "yaml-step" || v === "markdown-phase" || v === "auto-milestone";
+}
+
+// ─── Single-file plugin loaders ──────────────────────────────────────────
+
+function loadMarkdownPlugin(filePath: string, source: PluginSource): WorkflowPlugin | null {
+  const name = basenameNoExt(filePath);
+  let content: string;
+  try {
+    content = readFileSync(filePath, "utf-8");
+  } catch {
+    return null;
+  }
+
+  const meta = parseTemplateMeta(content);
+  const phases = parsePhasesFromMarkdown(content);
+  const declaredMode = meta.mode;
+  const mode: WorkflowMode = isValidMode(declaredMode) ? declaredMode : "markdown-phase";
+
+  const triggers = meta.triggers
+    ? meta.triggers.split(",").map((s) => s.trim()).filter(Boolean)
+    : undefined;
+
+  const artifactDirValue = meta.artifact_dir === "null" || meta.artifact_dir === "" ? null : meta.artifact_dir;
+
+  return {
+    name,
+    path: filePath,
+    format: "md",
+    source,
+    meta: {
+      displayName: meta.name || firstHeading(content) || name,
+      description: meta.description,
+      mode,
+      phases: phases.length > 0 ? phases : undefined,
+      triggers,
+      complexity: meta.complexity,
+      artifactDir: artifactDirValue ?? undefined,
+      requiresProject: meta.requires_project === "true",
+    },
+  };
+}
+
+function loadYamlPlugin(filePath: string, source: PluginSource): WorkflowPlugin | null {
+  const name = basenameNoExt(filePath);
+  let raw: string;
+  try {
+    raw = readFileSync(filePath, "utf-8");
+  } catch {
+    return null;
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = parseYaml(raw);
+  } catch (err) {
+    return {
+      name,
+      path: filePath,
+      format: "yaml",
+      source,
+      meta: { displayName: name, mode: "yaml-step" },
+      error: `YAML parse error: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+
+  if (parsed == null || typeof parsed !== "object") {
+    return {
+      name,
+      path: filePath,
+      format: "yaml",
+      source,
+      meta: { displayName: name, mode: "yaml-step" },
+      error: "Definition is not an object",
+    };
+  }
+
+  const def = parsed as Record<string, unknown>;
+  const declaredMode = def.mode;
+  const mode: WorkflowMode = isValidMode(declaredMode) ? declaredMode : "yaml-step";
+
+  const steps = Array.isArray(def.steps) ? (def.steps as Array<Record<string, unknown>>) : [];
+  const phases = steps.map((s) => String(s.id ?? "")).filter(Boolean);
+
+  return {
+    name,
+    path: filePath,
+    format: "yaml",
+    source,
+    meta: {
+      displayName: typeof def.name === "string" && def.name.trim() ? def.name : name,
+      description: typeof def.description === "string" ? def.description : undefined,
+      mode,
+      phases: phases.length > 0 ? phases : undefined,
+    },
+  };
+}
+
+function basenameNoExt(filePath: string): string {
+  const ext = extname(filePath);
+  return basename(filePath, ext);
+}
+
+// ─── Directory walkers ───────────────────────────────────────────────────
+
+const PLUGIN_EXTENSIONS = new Set([".yaml", ".yml", ".md"]);
+
+function walkPluginDir(dir: string, source: PluginSource, out: Map<string, WorkflowPlugin>): void {
+  if (!existsSync(dir)) return;
+  let entries: string[];
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const full = join(dir, entry);
+    let info: ReturnType<typeof statSync>;
+    try {
+      info = statSync(full);
+    } catch {
+      continue;
+    }
+    if (!info.isFile()) continue;
+    const ext = extname(entry).toLowerCase();
+    if (!PLUGIN_EXTENSIONS.has(ext)) continue;
+
+    const plugin = ext === ".md"
+      ? loadMarkdownPlugin(full, source)
+      : loadYamlPlugin(full, source);
+    if (!plugin) continue;
+    out.set(plugin.name, plugin);
+  }
+}
+
+function loadBundledPlugins(out: Map<string, WorkflowPlugin>): void {
+  const bundledDir = resolveBundledDir();
+  if (!existsSync(bundledDir)) return;
+
+  const registry = loadRegistry();
+  for (const [id, entry] of Object.entries(registry.templates)) {
+    const filePath = join(bundledDir, entry.file);
+    if (!existsSync(filePath)) continue;
+    const ext = extname(entry.file).toLowerCase();
+    const format: PluginFormat = ext === ".md" ? "md" : "yaml";
+    const mode: WorkflowMode = isValidMode(entry.mode)
+      ? entry.mode
+      : (format === "yaml" ? "yaml-step" : "markdown-phase");
+    out.set(id, {
+      name: id,
+      path: filePath,
+      format,
+      source: "bundled",
+      meta: {
+        displayName: entry.name,
+        description: entry.description,
+        mode,
+        phases: Array.isArray(entry.phases) && entry.phases.length > 0 ? entry.phases : undefined,
+        triggers: Array.isArray(entry.triggers) ? entry.triggers : undefined,
+        complexity: entry.estimated_complexity,
+        artifactDir: entry.artifact_dir,
+        requiresProject: entry.requires_project,
+      },
+    });
+  }
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────
+
+/**
+ * Discover all workflow plugins. Project overrides global overrides bundled.
+ *
+ * The legacy `.gsd/workflow-defs/*.yaml` directory is also scanned as a
+ * fallback YAML source so existing user definitions keep working.
+ */
+export function discoverPlugins(basePath: string): Map<string, WorkflowPlugin> {
+  const out = new Map<string, WorkflowPlugin>();
+
+  loadBundledPlugins(out);
+  walkPluginDir(globalPluginsDir(), "global", out);
+  walkPluginDir(legacyDefsDir(basePath), "project", out);
+  walkPluginDir(projectPluginsDir(basePath), "project", out);
+
+  return out;
+}
+
+/**
+ * Resolve a plugin by name using the precedence chain.
+ * Returns null if no plugin by that name exists anywhere.
+ */
+export function resolvePlugin(basePath: string, name: string): WorkflowPlugin | null {
+  const plugins = discoverPlugins(basePath);
+  return plugins.get(name) ?? null;
+}
+
+/**
+ * Format all discovered plugins for display, grouped by mode.
+ */
+export function listPluginsFormatted(basePath: string): string {
+  const plugins = discoverPlugins(basePath);
+  if (plugins.size === 0) {
+    return "No workflow plugins found.\n\nRun /gsd workflow new to author one.";
+  }
+
+  const groups: Record<WorkflowMode, WorkflowPlugin[]> = {
+    "oneshot": [],
+    "yaml-step": [],
+    "markdown-phase": [],
+    "auto-milestone": [],
+  };
+  for (const p of plugins.values()) {
+    groups[p.meta.mode].push(p);
+  }
+
+  const lines: string[] = ["Workflow Plugins\n"];
+
+  const order: WorkflowMode[] = ["markdown-phase", "yaml-step", "oneshot", "auto-milestone"];
+  for (const mode of order) {
+    const list = groups[mode].slice().sort((a, b) => a.name.localeCompare(b.name));
+    if (list.length === 0) continue;
+    lines.push(`  [${mode}]`);
+    for (const p of list) {
+      const tag = `${p.source}/${p.format}`;
+      const desc = p.meta.description ? ` — ${p.meta.description}` : "";
+      lines.push(`    ${p.name.padEnd(22)} ${tag.padEnd(16)}${desc}`);
+    }
+    lines.push("");
+  }
+
+  lines.push("Usage:");
+  lines.push("  /gsd workflow <name>          Run a plugin directly");
+  lines.push("  /gsd workflow info <name>     Show plugin details");
+  lines.push("  /gsd workflow install <src>   Install a plugin from a URL");
+
+  return lines.join("\n");
+}
+
+/**
+ * Format a single plugin's metadata for `/gsd workflow info <name>`.
+ */
+export function formatPluginInfo(plugin: WorkflowPlugin): string {
+  const lines = [
+    `Plugin: ${plugin.meta.displayName} (${plugin.name})`,
+    "",
+    `Source:   ${plugin.source}`,
+    `Format:   ${plugin.format}`,
+    `Mode:     ${plugin.meta.mode}`,
+    `Path:     ${plugin.path}`,
+  ];
+  if (plugin.meta.description) {
+    lines.push(`About:    ${plugin.meta.description}`);
+  }
+  if (plugin.meta.complexity) {
+    lines.push(`Complexity: ${plugin.meta.complexity}`);
+  }
+  if (plugin.meta.phases && plugin.meta.phases.length > 0) {
+    lines.push("", "Phases/Steps:");
+    plugin.meta.phases.forEach((p, i) => lines.push(`  ${i + 1}. ${p}`));
+  }
+  if (plugin.meta.triggers && plugin.meta.triggers.length > 0) {
+    lines.push("", `Triggers: ${plugin.meta.triggers.join(", ")}`);
+  }
+  if (plugin.meta.artifactDir) {
+    lines.push("", `Artifacts: ${plugin.meta.artifactDir}`);
+  }
+  if (plugin.error) {
+    lines.push("", `⚠ Error: ${plugin.error}`);
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Get the plugin directory paths for the project/global/bundled tiers.
+ * Exposed for the install command and tests.
+ */
+export function getPluginDirs(basePath: string): { project: string; global: string; bundled: string; legacy: string } {
+  return {
+    project: projectPluginsDir(basePath),
+    global: globalPluginsDir(),
+    bundled: resolveBundledDir(),
+    legacy: legacyDefsDir(basePath),
+  };
+}

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

@@ -19,6 +19,7 @@ import { logWarning } from "./workflow-logger.js";
 import { isClosedStatus } from "./status-guards.js";
 import { deriveState } from "./state.js";
 import type { GSDState } from "./types.js";
+import { renderRoadmapFromDb } from "./markdown-renderer.js";
 
 // ─── Helpers ─────────────────────────────────────────────────────────────
 
@@ -375,11 +376,13 @@ export async function renderStateProjection(basePath: string): Promise<void> {
  * All calls are wrapped in try/catch — projection failure is non-fatal per D-02.
  */
 export async function renderAllProjections(basePath: string, milestoneId: string): Promise<void> {
-  // Render ROADMAP.md for the milestone
+  // Delegate to the authoritative roadmap renderer — the reduced
+  // renderRoadmapProjection omits sections like ## Boundary Map and would
+  // clobber the output written by plan-milestone / reassess-roadmap.
   try {
-    renderRoadmapProjection(basePath, milestoneId);
+    await renderRoadmapFromDb(basePath, milestoneId);
   } catch (err) {
-    logWarning("projection", `renderRoadmapProjection failed for ${milestoneId}: ${(err as Error).message}`);
+    logWarning("projection", `renderRoadmapFromDb failed for ${milestoneId}: ${(err as Error).message}`);
   }
 
   // Query all slices for this milestone
@@ -416,15 +419,16 @@ export async function renderAllProjections(basePath: string, milestoneId: string
 
 /**
  * Check if a projection file exists on disk. If missing, regenerate it from DB.
- * Returns true if the file was regenerated, false if it already existed.
+ * Returns true if the file was regenerated, false if it already existed or
+ * regeneration failed.
  * Satisfies PROJ-05 (corrupted/deleted projections regenerate on demand).
  */
-export function regenerateIfMissing(
+export async function regenerateIfMissing(
   basePath: string,
   milestoneId: string,
   sliceId: string,
   fileType: "PLAN" | "ROADMAP" | "SUMMARY" | "STATE",
-): boolean {
+): Promise<boolean> {
   let filePath: string;
 
   switch (fileType) {
@@ -466,23 +470,21 @@ export function regenerateIfMissing(
     return false;
   }
 
-  // Regenerate the missing file
+  // Regenerate the missing file. Each renderer may swallow its own errors
+  // (e.g. renderStateProjection), so confirm the file actually exists on
+  // disk before reporting success — true must mean "file is there now".
   try {
     switch (fileType) {
       case "PLAN":
         renderPlanProjection(basePath, milestoneId, sliceId);
-        break;
+        return existsSync(filePath);
       case "ROADMAP":
-        renderRoadmapProjection(basePath, milestoneId);
-        break;
+        await renderRoadmapFromDb(basePath, milestoneId);
+        return existsSync(filePath);
       case "STATE":
-        // renderStateProjection is async — fire-and-forget.
-        // Return false since the file isn't written yet; it will appear
-        // on the next post-mutation hook cycle.
-        void renderStateProjection(basePath);
-        return false;
+        await renderStateProjection(basePath);
+        return existsSync(filePath);
     }
-    return true;
   } catch (err) {
     logWarning("projection", `regenerateIfMissing ${fileType} failed: ${(err as Error).message}`);
     return false;

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

@@ -0,0 +1,88 @@
+# Accessibility Audit
+
+<template_meta>
+name: accessibility-audit
+version: 1
+mode: oneshot
+requires_project: false
+artifact_dir: null
+</template_meta>
+
+<purpose>
+Scan the UI layer for accessibility issues and produce a prioritized remediation
+list. Oneshot — report only, no code changes.
+</purpose>
+
+<instructions>
+
+## 1. Identify the UI stack
+
+- React, Vue, Svelte, Angular, plain HTML, or something else?
+- Which files contain user-facing templates? (e.g. `src/components/**/*.tsx`,
+  `pages/**/*.vue`, `templates/**/*.html`).
+
+If the project has no UI layer (library, CLI, backend), say so and stop.
+
+## 2. Run available a11y tooling
+
+Prefer automated tools when installed:
+- React: `@axe-core/react`, `eslint-plugin-jsx-a11y`.
+- Vue: `eslint-plugin-vuejs-accessibility`.
+- Any: `pa11y` or `axe` against a running dev server.
+
+If nothing's installed, do a **static audit**: grep for the common
+violations listed below.
+
+## 3. Check the WCAG essentials
+
+For each component/page:
+
+1. **Images** without `alt`.
+2. **Buttons** that are `<div onClick>` instead of real `<button>`.
+3. **Links** without `href` or with only an icon and no label.
+4. **Form inputs** without an associated `<label>` or `aria-label`.
+5. **Color-only** state indicators (errors shown only with red, etc.).
+6. **Focus management**: missing `:focus-visible`, tab traps, hidden focus.
+7. **Headings** that skip levels (`h1` → `h3` with no `h2`).
+8. **ARIA**: `role=button` on divs (should just be a button), misuse of
+   `aria-label` on elements that already have accessible text.
+9. **Landmark regions**: missing `<main>`, `<nav>`, `<header>`.
+10. **Keyboard traps**: modals/dialogs without escape handlers.
+
+## 4. Triage by severity
+
+- **Blocker** (P0) — prevents a user from completing a core task with
+  keyboard / screen reader.
+- **Serious** (P1) — materially degrades the experience but workable.
+- **Moderate** (P2) — fixable, would benefit most users.
+- **Minor** (P3) — polish.
+
+## 5. Output
+
+```
+# A11y Audit — <date>
+
+## Summary
+<scope — how many components/pages reviewed, tool coverage>
+
+## Blockers (P0) — <n>
+- file:line — issue
+  Fix: <specific code suggestion>
+
+## Serious (P1) — <n>
+...
+
+## Moderate / Minor
+...
+
+## Top 5 Recommendations
+1. <highest-impact fix first>
+```
+
+## 6. Don't refactor
+
+Suggestions should be specific enough to act on, but don't edit any files.
+If the user wants to apply the fixes, suggest:
+> `/gsd workflow refactor "apply a11y fixes"` with this report as context.
+
+</instructions>

package/src/resources/extensions/gsd/workflow-templates/api-breaking-change.md

@@ -0,0 +1,117 @@
+# API Breaking Change Workflow
+
+<template_meta>
+name: api-breaking-change
+version: 1
+mode: markdown-phase
+requires_project: false
+artifact_dir: .gsd/workflows/api-breaks/
+</template_meta>
+
+<purpose>
+Remove or redesign a public API in a controlled way. Surveys all callers,
+migrates them, deprecates the old surface, and schedules the removal release.
+Built for APIs consumed by other modules in the repo AND by external
+dependents where feasible.
+</purpose>
+
+<phases>
+1. survey     — Identify all callers, draft the new design
+2. migrate    — Land the new API and migrate internal callers
+3. deprecate  — Mark the old API deprecated, communicate the change
+4. release    — Remove the old API in a future release
+</phases>
+
+<process>
+
+## Phase 1: Survey
+
+**Goal:** Understand the blast radius before touching anything.
+
+1. **Identify the old API:**
+   - What's the symbol/route/contract? Where is it defined?
+   - Is it internal-only, exported to the SDK, or a public network endpoint?
+
+2. **Map callers:**
+   - Internal: `grep` the symbol across the repo. List every call site with
+     file:line.
+   - External (if applicable): check the package registry for direct
+     dependents, look for GitHub code search results, check the docs.
+
+3. **Draft the new shape:**
+   - What's changing? (rename, signature change, semantic change?)
+   - What's the migration pattern for a typical caller?
+   - Can callers migrate incrementally, or is it all-or-nothing?
+
+4. **Produce `SURVEY.md`** with:
+   - Old signature vs new signature.
+   - Full caller list (internal + best-effort external).
+   - Migration difficulty per caller type.
+   - Timeline proposal: deprecate in release X, remove in release Y.
+
+5. **Gate:** Review the survey with the user. This is the "do we actually want
+   to do this?" checkpoint. Don't proceed if the blast radius is larger than
+   the benefit.
+
+## Phase 2: Migrate
+
+**Goal:** Land the new API and move internal callers to it.
+
+1. **Introduce the new API alongside the old one:**
+   - Export the new function/class/endpoint.
+   - The old API still works unchanged.
+   - Add tests for the new API.
+
+2. **Migrate internal callers:**
+   - One file at a time, atomic commits: `refactor(api): migrate <caller> to <new-api>`.
+   - Run tests after each batch.
+
+3. **Add a feature flag** if helpful — some callers may need runtime toggles
+   during a staged rollout.
+
+4. **Gate:** All internal callers migrated, tests green. Confirm before
+   proceeding to the deprecation phase.
+
+## Phase 3: Deprecate
+
+**Goal:** Tell external callers to migrate.
+
+1. **Mark the old API deprecated:**
+   - Add `@deprecated` JSDoc / language-equivalent annotations.
+   - Log a runtime deprecation warning on first use (if feasible and the
+     language supports it). Include the migration path in the message.
+
+2. **Update docs:**
+   - Changelog: a prominent `### Deprecated` section with migration guidance.
+   - README / API docs: note the deprecation timeline.
+   - If there's a `MIGRATIONS.md`, add an entry.
+
+3. **Communicate:**
+   - Draft a release-notes entry with before/after code examples.
+   - If the API has external users, draft an issue or blog post.
+
+4. **Ship** the deprecation release (coordinate with `/gsd workflow release`).
+
+5. **Gate:** Deprecation is live, callers have had time to migrate. Decide
+   the removal timeline (typically next minor or next major).
+
+## Phase 4: Release (removal)
+
+**Goal:** Delete the old API in a future release.
+
+1. **Verify ecosystem readiness:**
+   - Have internal consumers upgraded?
+   - Have known external consumers upgraded? If not, is it OK to force it?
+
+2. **Remove the old API:**
+   - Delete the deprecated code paths.
+   - Update tests.
+   - Update docs to remove references.
+
+3. **Release** as part of a major version bump (semver). Document the removal
+   prominently in the changelog.
+
+4. **Close the loop:** update `SURVEY.md` with the final outcome — what
+   shipped, what's still outstanding, any lessons learned.
+
+</process>

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

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