gsd-pi 2.75.0 → 2.76.0-dev.4100bd590

package/dist/resources/extensions/gsd/workflow-plugins.js

@@ -0,0 +1,346 @@
+/**
+ * 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 } from "./workflow-templates.js";
+// ─── Path resolution ─────────────────────────────────────────────────────
+function resolveBundledDir() {
+    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() {
+    const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
+    return join(gsdHome, "workflows");
+}
+function projectPluginsDir(basePath) {
+    return join(basePath, ".gsd", "workflows");
+}
+function legacyDefsDir(basePath) {
+    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) {
+    const match = content.match(/<template_meta>([\s\S]*?)<\/template_meta>/);
+    if (!match)
+        return {};
+    const body = match[1];
+    const result = {};
+    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) {
+    const match = content.match(/<phases>([\s\S]*?)<\/phases>/);
+    if (!match)
+        return [];
+    const phases = [];
+    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) {
+    const match = content.match(/^#\s+(.+)$/m);
+    return match ? match[1].trim() : undefined;
+}
+function isValidMode(v) {
+    return v === "oneshot" || v === "yaml-step" || v === "markdown-phase" || v === "auto-milestone";
+}
+// ─── Single-file plugin loaders ──────────────────────────────────────────
+function loadMarkdownPlugin(filePath, source) {
+    const name = basenameNoExt(filePath);
+    let content;
+    try {
+        content = readFileSync(filePath, "utf-8");
+    }
+    catch {
+        return null;
+    }
+    const meta = parseTemplateMeta(content);
+    const phases = parsePhasesFromMarkdown(content);
+    const declaredMode = meta.mode;
+    const mode = 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, source) {
+    const name = basenameNoExt(filePath);
+    let raw;
+    try {
+        raw = readFileSync(filePath, "utf-8");
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    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;
+    const declaredMode = def.mode;
+    const mode = isValidMode(declaredMode) ? declaredMode : "yaml-step";
+    const steps = Array.isArray(def.steps) ? def.steps : [];
+    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) {
+    const ext = extname(filePath);
+    return basename(filePath, ext);
+}
+// ─── Directory walkers ───────────────────────────────────────────────────
+const PLUGIN_EXTENSIONS = new Set([".yaml", ".yml", ".md"]);
+function walkPluginDir(dir, source, out) {
+    if (!existsSync(dir))
+        return;
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        const full = join(dir, entry);
+        let info;
+        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) {
+    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 = ext === ".md" ? "md" : "yaml";
+        const mode = 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) {
+    const out = new Map();
+    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, name) {
+    const plugins = discoverPlugins(basePath);
+    return plugins.get(name) ?? null;
+}
+/**
+ * Format all discovered plugins for display, grouped by mode.
+ */
+export function listPluginsFormatted(basePath) {
+    const plugins = discoverPlugins(basePath);
+    if (plugins.size === 0) {
+        return "No workflow plugins found.\n\nRun /gsd workflow new to author one.";
+    }
+    const groups = {
+        "oneshot": [],
+        "yaml-step": [],
+        "markdown-phase": [],
+        "auto-milestone": [],
+    };
+    for (const p of plugins.values()) {
+        groups[p.meta.mode].push(p);
+    }
+    const lines = ["Workflow Plugins\n"];
+    const order = ["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) {
+    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) {
+    return {
+        project: projectPluginsDir(basePath),
+        global: globalPluginsDir(),
+        bundled: resolveBundledDir(),
+        legacy: legacyDefsDir(basePath),
+    };
+}

package/dist/resources/extensions/gsd/workflow-projections.js

@@ -8,6 +8,7 @@ import { mkdirSync, existsSync } from "node:fs";
 import { logWarning } from "./workflow-logger.js";
 import { isClosedStatus } from "./status-guards.js";
 import { deriveState } from "./state.js";
+import { renderRoadmapFromDb } from "./markdown-renderer.js";
 // ─── Helpers ─────────────────────────────────────────────────────────────
 /**
  * Strip a leading ID prefix (e.g. "M001: " or "S04: ") from a title
@@ -325,12 +326,14 @@ export async function renderStateProjection(basePath) {
  * All calls are wrapped in try/catch — projection failure is non-fatal per D-02.
  */
 export async function renderAllProjections(basePath, milestoneId) {
-    // 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.message}`);
+        logWarning("projection", `renderRoadmapFromDb failed for ${milestoneId}: ${err.message}`);
     }
     // Query all slices for this milestone
     const sliceRows = getMilestoneSlices(milestoneId);
@@ -362,10 +365,11 @@ export async function renderAllProjections(basePath, milestoneId) {
 // ─── regenerateIfMissing ────────────────────────────────────────────────
 /**
  * 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(basePath, milestoneId, sliceId, fileType) {
+export async function regenerateIfMissing(basePath, milestoneId, sliceId, fileType) {
     let filePath;
     switch (fileType) {
         case "PLAN":
@@ -404,23 +408,21 @@ export function regenerateIfMissing(basePath, milestoneId, sliceId, fileType) {
     if (existsSync(filePath)) {
         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.message}`);

package/dist/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/dist/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/dist/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>