@opengsd/get-shit-done-redux 1.0.0

package/sdk/src/workflow-agent-skills-consistency.test.ts

@@ -0,0 +1,98 @@
+/**
+ * Contract test: every `gsd-sdk query agent-skills <slug>` invocation in
+ * `get-shit-done/workflows/**\/*.md` must reference a slug that exists as
+ * `agents/<slug>.md` at the repository root.
+ *
+ * A mismatch produces a silent no-op at runtime — the SDK returns `""` for an
+ * unknown key, and the workflow interpolates the empty string into the spawn
+ * prompt, so any `agent_skills.<correct-slug>` configuration in
+ * `.planning/config.json` is silently ignored. This test prevents regression.
+ *
+ * Related: https://github.com/open-gsd/get-shit-done-redux/issues/2615
+ */
+import { describe, it, expect } from 'vitest';
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const repoRoot = join(__dirname, '..', '..');
+const workflowsDir = join(repoRoot, 'get-shit-done', 'workflows');
+const agentsDir = join(repoRoot, 'agents');
+
+/**
+ * Matches a full `gsd-sdk query agent-skills <slug>` invocation and captures
+ * the slug. Requires a token boundary before `gsd-sdk` and a word boundary
+ * after the slug so that prose references (e.g. documentation mentioning the
+ * string "agent-skills") do not produce false positives. The `\s+` between
+ * tokens accepts newlines, so commands wrapped across lines still match.
+ */
+const QUERY_KEY_PATTERN = /\bgsd-sdk\s+query\s+agent-skills\s+([a-z][a-z0-9-]*)\b/g;
+
+interface QueryUsage {
+  readonly file: string;
+  readonly line: number;
+  readonly slug: string;
+}
+
+/** Recursively collects all `.md` file paths under `dir`. */
+function walkMarkdown(dir: string): string[] {
+  const out: string[] = [];
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) {
+      out.push(...walkMarkdown(full));
+    } else if (entry.endsWith('.md')) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+/** Returns the set of agent slugs defined by `<slug>.md` files in `dir`. */
+function collectAgentSlugs(dir: string): Set<string> {
+  return new Set(
+    readdirSync(dir)
+      .filter((name) => name.endsWith('.md'))
+      .map((name) => name.replace(/\.md$/, '')),
+  );
+}
+
+/**
+ * Extracts every `gsd-sdk query agent-skills <slug>` usage from the given
+ * markdown files. Runs the regex over each file's full content (not line by
+ * line) so wrapped commands still match, then resolves the 1-based line number
+ * from the match index.
+ */
+function collectQueryUsages(files: readonly string[]): QueryUsage[] {
+  const usages: QueryUsage[] = [];
+  for (const file of files) {
+    const content = readFileSync(file, 'utf8');
+    for (const match of content.matchAll(QUERY_KEY_PATTERN)) {
+      const index = match.index ?? 0;
+      const line = content.slice(0, index).split('\n').length;
+      usages.push({ file, line, slug: match[1]! });
+    }
+  }
+  return usages;
+}
+
+describe('workflow agent-skills query consistency', () => {
+  it('every `agent-skills <slug>` query refers to an existing `agents/<slug>.md`', () => {
+    const validSlugs = collectAgentSlugs(agentsDir);
+    const workflowFiles = walkMarkdown(workflowsDir);
+    const usages = collectQueryUsages(workflowFiles);
+    const invalid = usages.filter((u) => !validSlugs.has(u.slug));
+
+    const report = invalid
+      .map((u) => `  ${relative(repoRoot, u.file)}:${u.line} — unknown slug '${u.slug}'`)
+      .join('\n');
+
+    expect(
+      invalid,
+      invalid.length
+        ? `Found ${invalid.length} agent-skills query keys with no matching agents/<slug>.md:\n${report}`
+        : '',
+    ).toHaveLength(0);
+  });
+});

package/sdk/src/workstream-inventory/builder.test.ts

@@ -0,0 +1,241 @@
+/**
+ * Pinning tests for the Workstream Inventory Builder.
+ *
+ * The Builder is pure (no I/O). It takes pre-collected BuilderInputs and
+ * returns a WorkstreamInventory. These tests lock the projection logic against
+ * the canonical shape defined in sdk/src/query/workstream-inventory.ts.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { buildWorkstreamInventory, isCompletedInventory } from './builder.js';
+import type { BuilderInputs } from './builder.js';
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function minimalInputs(overrides: Partial<BuilderInputs> = {}): BuilderInputs {
+  return {
+    name: 'my-ws',
+    projectDir: '/project',
+    workstreamDir: '/project/.planning/workstreams/my-ws',
+    phaseDirNames: [],
+    activeWorkstreamName: null,
+    phaseFilesCounts: [],
+    roadmapPhaseCount: 0,
+    stateProjection: { status: 'unknown', current_phase: null, last_activity: null },
+    filesExist: { roadmap: false, state: false, requirements: false },
+    ...overrides,
+  };
+}
+
+// ─── Tests ───────────────────────────────────────────────────────────────────
+
+describe('buildWorkstreamInventory', () => {
+  it('empty inventory: no phase dirs, no STATE.md', () => {
+    const result = buildWorkstreamInventory(minimalInputs());
+    expect(result).toEqual({
+      name: 'my-ws',
+      path: '.planning/workstreams/my-ws',
+      active: false,
+      files: { roadmap: false, state: false, requirements: false },
+      status: 'unknown',
+      current_phase: null,
+      last_activity: null,
+      phases: [],
+      phase_count: 0,
+      completed_phases: 0,
+      roadmap_phase_count: 0,
+      total_plans: 0,
+      completed_plans: 0,
+      progress_percent: 0,
+    });
+  });
+
+  it('one phase in_progress (partial plan completion)', () => {
+    const result = buildWorkstreamInventory(
+      minimalInputs({
+        phaseDirNames: ['01-alpha'],
+        phaseFilesCounts: [{ directory: '01-alpha', planCount: 3, summaryCount: 1 }],
+        roadmapPhaseCount: 1,
+        stateProjection: { status: 'executing', current_phase: '01-alpha', last_activity: '2026-05-01' },
+        filesExist: { roadmap: true, state: true, requirements: false },
+      }),
+    );
+    expect(result.phases).toHaveLength(1);
+    expect(result.phases[0]).toEqual({
+      directory: '01-alpha',
+      status: 'in_progress',
+      plan_count: 3,
+      summary_count: 1,
+    });
+    expect(result.phase_count).toBe(1);
+    expect(result.completed_phases).toBe(0);
+    expect(result.total_plans).toBe(3);
+    expect(result.completed_plans).toBe(1);
+    expect(result.progress_percent).toBe(0);
+    expect(result.status).toBe('executing');
+    expect(result.current_phase).toBe('01-alpha');
+    expect(result.last_activity).toBe('2026-05-01');
+    expect(result.files).toEqual({ roadmap: true, state: true, requirements: false });
+  });
+
+  it('one phase complete (summary_count >= plan_count)', () => {
+    const result = buildWorkstreamInventory(
+      minimalInputs({
+        phaseDirNames: ['01-alpha'],
+        phaseFilesCounts: [{ directory: '01-alpha', planCount: 2, summaryCount: 2 }],
+        roadmapPhaseCount: 1,
+        stateProjection: { status: 'milestone complete', current_phase: null, last_activity: '2026-04-01' },
+        filesExist: { roadmap: true, state: true, requirements: true },
+      }),
+    );
+    expect(result.phases[0].status).toBe('complete');
+    expect(result.completed_phases).toBe(1);
+    expect(result.progress_percent).toBe(100);
+    expect(result.completed_plans).toBe(2);
+  });
+
+  it('one phase pending (plan_count is 0)', () => {
+    const result = buildWorkstreamInventory(
+      minimalInputs({
+        phaseDirNames: ['01-alpha'],
+        phaseFilesCounts: [{ directory: '01-alpha', planCount: 0, summaryCount: 0 }],
+        roadmapPhaseCount: 1,
+        stateProjection: { status: 'planning', current_phase: null, last_activity: null },
+      }),
+    );
+    expect(result.phases[0].status).toBe('pending');
+    expect(result.completed_phases).toBe(0);
+    expect(result.progress_percent).toBe(0);
+  });
+
+  it('multiple phases with mixed statuses', () => {
+    const result = buildWorkstreamInventory(
+      minimalInputs({
+        phaseDirNames: ['01-alpha', '02-beta', '03-gamma'],
+        phaseFilesCounts: [
+          { directory: '01-alpha', planCount: 2, summaryCount: 2 }, // complete
+          { directory: '02-beta', planCount: 3, summaryCount: 1 },  // in_progress
+          { directory: '03-gamma', planCount: 0, summaryCount: 0 }, // pending
+        ],
+        roadmapPhaseCount: 3,
+        stateProjection: { status: 'executing', current_phase: '02-beta', last_activity: '2026-05-10' },
+        filesExist: { roadmap: true, state: true, requirements: false },
+      }),
+    );
+    expect(result.phases).toHaveLength(3);
+    expect(result.phases[0].status).toBe('complete');
+    expect(result.phases[1].status).toBe('in_progress');
+    expect(result.phases[2].status).toBe('pending');
+    expect(result.completed_phases).toBe(1);
+    expect(result.total_plans).toBe(5);
+    expect(result.completed_plans).toBe(3); // 2 from alpha + min(1,3)=1 from beta + 0 from gamma
+    expect(result.progress_percent).toBe(Math.round((1 / 3) * 100)); // 33
+    expect(result.roadmap_phase_count).toBe(3);
+  });
+
+  it('progress_percent clamps to 100 when completedPhases > roadmapPhaseCount', () => {
+    // 3 phase dirs all complete, but roadmap only has 1 entry
+    const result = buildWorkstreamInventory(
+      minimalInputs({
+        phaseDirNames: ['01-alpha', '02-beta', '03-gamma'],
+        phaseFilesCounts: [
+          { directory: '01-alpha', planCount: 1, summaryCount: 1 },
+          { directory: '02-beta', planCount: 1, summaryCount: 1 },
+          { directory: '03-gamma', planCount: 1, summaryCount: 1 },
+        ],
+        roadmapPhaseCount: 1,
+        stateProjection: { status: 'milestone complete', current_phase: null, last_activity: null },
+        filesExist: { roadmap: true, state: true, requirements: false },
+      }),
+    );
+    expect(result.completed_phases).toBe(3);
+    expect(result.roadmap_phase_count).toBe(1);
+    expect(result.progress_percent).toBe(100);
+  });
+
+  it('active workstream marker: active: true when activeWorkstreamName === name', () => {
+    const result = buildWorkstreamInventory(
+      minimalInputs({
+        name: 'my-ws',
+        activeWorkstreamName: 'my-ws',
+      }),
+    );
+    expect(result.active).toBe(true);
+  });
+
+  it('active: false when activeWorkstreamName is a different workstream', () => {
+    const result = buildWorkstreamInventory(
+      minimalInputs({
+        name: 'my-ws',
+        activeWorkstreamName: 'other-ws',
+      }),
+    );
+    expect(result.active).toBe(false);
+  });
+
+  it('phases are sorted by directory name', () => {
+    // Provide dirs in reverse order to verify sorting
+    const result = buildWorkstreamInventory(
+      minimalInputs({
+        phaseDirNames: ['03-gamma', '01-alpha', '02-beta'],
+        phaseFilesCounts: [
+          { directory: '03-gamma', planCount: 1, summaryCount: 0 },
+          { directory: '01-alpha', planCount: 1, summaryCount: 1 },
+          { directory: '02-beta', planCount: 1, summaryCount: 0 },
+        ],
+        roadmapPhaseCount: 3,
+        stateProjection: { status: 'executing', current_phase: null, last_activity: null },
+        filesExist: { roadmap: true, state: false, requirements: false },
+      }),
+    );
+    expect(result.phases.map((p) => p.directory)).toEqual(['01-alpha', '02-beta', '03-gamma']);
+  });
+
+  it('path is relative from projectDir to workstreamDir using posix separators', () => {
+    const result = buildWorkstreamInventory(
+      minimalInputs({
+        projectDir: '/home/user/project',
+        workstreamDir: '/home/user/project/.planning/workstreams/my-ws',
+      }),
+    );
+    expect(result.path).toBe('.planning/workstreams/my-ws');
+  });
+});
+
+describe('isCompletedInventory', () => {
+  it('returns true for "milestone complete"', () => {
+    expect(isCompletedInventory('milestone complete')).toBe(true);
+  });
+
+  it('returns true for "Milestone Complete" (case-insensitive)', () => {
+    expect(isCompletedInventory('Milestone Complete')).toBe(true);
+  });
+
+  it('returns true for "archived"', () => {
+    expect(isCompletedInventory('archived')).toBe(true);
+  });
+
+  it('returns true for "Archived"', () => {
+    expect(isCompletedInventory('Archived')).toBe(true);
+  });
+
+  it('returns false for "executing"', () => {
+    expect(isCompletedInventory('executing')).toBe(false);
+  });
+
+  it('returns false for "planning"', () => {
+    expect(isCompletedInventory('planning')).toBe(false);
+  });
+
+  it('returns false for "unknown"', () => {
+    expect(isCompletedInventory('unknown')).toBe(false);
+  });
+
+  it('returns false for "unarchived" (word-boundary guard)', () => {
+    expect(isCompletedInventory('unarchived')).toBe(false);
+  });
+
+  it('returns false for empty string', () => {
+    expect(isCompletedInventory('')).toBe(false);
+  });
+});

package/sdk/src/workstream-inventory/builder.ts

@@ -0,0 +1,170 @@
+/**
+ * Workstream Inventory Builder — pure projection from pre-collected
+ * filesystem data to typed WorkstreamInventory. No I/O. No async.
+ *
+ * The caller is responsible for collecting BuilderInputs from the filesystem
+ * (or from test fixtures). This module performs only the stateless transformation.
+ */
+
+import { relative } from 'node:path';
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export interface WorkstreamPhaseInventory {
+  directory: string;
+  status: 'complete' | 'in_progress' | 'pending';
+  plan_count: number;
+  summary_count: number;
+}
+
+export interface WorkstreamInventory {
+  name: string;
+  path: string;
+  active: boolean;
+  files: {
+    roadmap: boolean;
+    state: boolean;
+    requirements: boolean;
+  };
+  status: string;
+  current_phase: string | null;
+  last_activity: string | null;
+  phases: WorkstreamPhaseInventory[];
+  phase_count: number;
+  completed_phases: number;
+  roadmap_phase_count: number;
+  total_plans: number;
+  completed_plans: number;
+  progress_percent: number;
+}
+
+export interface WorkstreamInventoryList {
+  mode: 'flat' | 'workstream';
+  active: string | null;
+  workstreams: WorkstreamInventory[];
+  count: number;
+  message?: string;
+}
+
+// ─── Inputs ───────────────────────────────────────────────────────────────────
+
+export interface BuilderInputs {
+  /** The workstream name (directory basename). */
+  name: string;
+  /** Absolute path to the project root. */
+  projectDir: string;
+  /** Absolute path to the workstream directory. */
+  workstreamDir: string;
+  /** List of phase directory names (unsorted; builder will sort them). */
+  phaseDirNames: string[];
+  /** The currently active workstream name, or null if none. */
+  activeWorkstreamName: string | null;
+  /**
+   * Pre-collected plan/summary counts per phase directory.
+   * The `directory` field must match entries in `phaseDirNames`.
+   */
+  phaseFilesCounts: Array<{ directory: string; planCount: number; summaryCount: number }>;
+  /** Phase count from the ROADMAP.md (already resolved, fallback applied). */
+  roadmapPhaseCount: number;
+  /** Projection from the workstream's STATE.md (already read). */
+  stateProjection: { status: string; current_phase: string | null; last_activity: string | null };
+  /** Whether each canonical file exists (already checked). */
+  filesExist: { roadmap: boolean; state: boolean; requirements: boolean };
+}
+
+// ─── Internal helpers ─────────────────────────────────────────────────────────
+
+/**
+ * Convert a path to POSIX format (forward slashes only).
+ * Pure string transform — no filesystem access.
+ */
+function toPosixPath(p: string): string {
+  return p.split('\\').join('/');
+}
+
+// ─── Exports ──────────────────────────────────────────────────────────────────
+
+/**
+ * Pure classifier: returns true if the given status string indicates a
+ * completed or archived workstream (case-insensitive, boundary-aware match).
+ */
+export function isCompletedInventory(status: string): boolean {
+  const s = String(status ?? '').trim().toLowerCase();
+  return /\bmilestone\s+complete\b/.test(s) || /\barchived\b/.test(s);
+}
+
+/**
+ * Build a WorkstreamInventory from pre-collected BuilderInputs.
+ *
+ * This is a pure function — it does not read the filesystem and does not
+ * produce side-effects. All I/O must be done by the caller before invoking.
+ */
+export function buildWorkstreamInventory(inputs: BuilderInputs): WorkstreamInventory {
+  const {
+    name,
+    projectDir,
+    workstreamDir,
+    phaseDirNames,
+    activeWorkstreamName,
+    phaseFilesCounts,
+    roadmapPhaseCount,
+    stateProjection,
+    filesExist,
+  } = inputs;
+
+  // Index counts by directory for O(1) lookup during sort/iteration
+  const countsMap = new Map<string, { planCount: number; summaryCount: number }>();
+  for (const entry of phaseFilesCounts) {
+    countsMap.set(entry.directory, { planCount: entry.planCount, summaryCount: entry.summaryCount });
+  }
+
+  const phases: WorkstreamPhaseInventory[] = [];
+  let completedPhases = 0;
+  let totalPlans = 0;
+  let completedPlans = 0;
+
+  for (const dir of [...phaseDirNames].sort()) {
+    const counts = countsMap.get(dir) ?? { planCount: 0, summaryCount: 0 };
+    const status: WorkstreamPhaseInventory['status'] =
+      counts.summaryCount >= counts.planCount && counts.planCount > 0
+        ? 'complete'
+        : counts.planCount > 0
+          ? 'in_progress'
+          : 'pending';
+
+    totalPlans += counts.planCount;
+    completedPlans += Math.min(counts.summaryCount, counts.planCount);
+    if (status === 'complete') completedPhases++;
+
+    phases.push({
+      directory: dir,
+      status,
+      plan_count: counts.planCount,
+      summary_count: counts.summaryCount,
+    });
+  }
+
+  return {
+    name,
+    path: toPosixPath(relative(projectDir, workstreamDir)),
+    active: name === activeWorkstreamName,
+    files: {
+      roadmap: filesExist.roadmap,
+      state: filesExist.state,
+      requirements: filesExist.requirements,
+    },
+    status: stateProjection.status,
+    current_phase: stateProjection.current_phase,
+    last_activity: stateProjection.last_activity,
+    phases,
+    phase_count: phases.length,
+    completed_phases: completedPhases,
+    roadmap_phase_count: roadmapPhaseCount,
+    total_plans: totalPlans,
+    completed_plans: completedPlans,
+    progress_percent:
+      roadmapPhaseCount > 0
+        ? Math.min(100, Math.round((completedPhases / roadmapPhaseCount) * 100))
+        : 0,
+  };
+}

package/sdk/src/workstream-name-policy.ts

@@ -0,0 +1,57 @@
+/**
+ * Workstream Name Policy Module
+ *
+ * Owns canonical workstream name validation and slug normalization.
+ * Shared by CJS runtime (active-workstream-store.cjs, planning-workspace.cjs,
+ * workstream.cjs) and SDK layer.
+ *
+ * Phase 6 (#3575): added hasInvalidPathSegment and isValidActiveWorkstreamName
+ * from CJS bin/lib/workstream-name-policy.cjs to complete the MIGRATE_ME migration.
+ */
+
+const ACTIVE_WORKSTREAM_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+
+/**
+ * Validate a workstream name.
+ * Allowed: alphanumeric, hyphens, underscores, dots.
+ * Disallowed: empty, spaces, slashes, special chars, path traversal.
+ *
+ * Alias for isValidActiveWorkstreamName; provided for SDK-layer callers.
+ */
+export function validateWorkstreamName(name: string): boolean {
+  return isValidActiveWorkstreamName(name);
+}
+
+/**
+ * Convert a display name to a URL/filesystem-safe workstream slug.
+ * Lowercases, collapses non-alphanumeric runs to hyphens, strips leading/trailing hyphens.
+ */
+export function toWorkstreamSlug(name: string): string {
+  return String(name || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+/**
+ * Returns true when `name` contains a path separator, a bare dot, or a
+ * dot-dot sequence — any of which would make the name unsafe for use as a
+ * filesystem path segment.
+ */
+export function hasInvalidPathSegment(name: string): boolean {
+  const value = String(name || '');
+  return /[/\\]/.test(value) || value === '.' || value === '..' || value.includes('..');
+}
+
+/**
+ * Returns true when `name` is a valid active workstream name:
+ * - Must start with alphanumeric
+ * - May contain alphanumeric, dots, underscores, hyphens
+ * - Must not contain path traversal sequences (..)
+ */
+export function isValidActiveWorkstreamName(name: string): boolean {
+  const value = String(name || '');
+  if (value === '..' || value.startsWith('../') || value.includes('..')) return false;
+  return ACTIVE_WORKSTREAM_RE.test(value);
+}
+

package/sdk/src/workstream-utils.ts

@@ -0,0 +1,36 @@
+/**
+ * Workstream utility functions for multi-workstream project support.
+ *
+ * When --ws <name> is provided, all .planning/ paths are routed to
+ * .planning/workstreams/<name>/ instead.
+ */
+
+import { posix } from 'node:path';
+import { validateWorkstreamName } from './workstream-name-policy.js';
+export { validateWorkstreamName, toWorkstreamSlug } from './workstream-name-policy.js';
+
+/**
+ * Return the relative planning directory path.
+ *
+ * - Without workstream: `.planning`
+ * - With workstream: `.planning/workstreams/<name>`
+ *
+ * #3589 (security): validates the explicit workstream name against the
+ * shared `validateWorkstreamName` policy before path construction. Path
+ * traversal segments (`..`, `/`, `\\`) and other invalid identifiers throw
+ * synchronously, so every caller — direct SDK use, `planningPaths`,
+ * `ContextEngine` — fails closed at the same seam. Env-sourced workstreams
+ * are still pre-filtered to `null` by `planningPaths` (the #2791 silent
+ * fallback contract), so this guard does NOT change env-sourced behaviour.
+ */
+export function relPlanningPath(workstream?: string): string {
+  if (!workstream) return '.planning';
+  if (!validateWorkstreamName(workstream)) {
+    throw new Error(
+      `Invalid workstream name: ${JSON.stringify(workstream)}. ` +
+        `Workstream names must match /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/ and may not contain '..'.`,
+    );
+  }
+  // Use POSIX segments so the same logical path string is used on all platforms (Windows included).
+  return posix.join('.planning', 'workstreams', workstream);
+}