@hegemonart/get-design-done 1.19.6 → 1.21.0

package/scripts/mcp-servers/gdd-state/tools/update_progress.ts

@@ -0,0 +1,81 @@
+// scripts/mcp-servers/gdd-state/tools/update_progress.ts
+//
+// Tool: gdd_state__update_progress
+// Purpose: Update <position>.task_progress and/or <position>.status.
+// Emits state.mutation on success.
+
+import { mutate } from '../../../lib/gdd-state/index.ts';
+import {
+  emitStateMutation,
+  errorResponse,
+  okResponse,
+  resolveStatePath,
+  throwValidation,
+  type ToolResponse,
+} from './shared.ts';
+
+export const name = 'gdd_state__update_progress';
+export const schemaPath = '../schemas/update_progress.schema.json';
+
+export interface UpdateProgressInput {
+  task_progress?: string;
+  status?: 'initialized' | 'in_progress' | 'completed' | 'blocked';
+}
+
+/** Accept the same regex the JSON Schema enforces — double-check for
+ *  defense in depth against a caller that somehow routes around schema
+ *  validation (e.g. when we run the handler directly in a test). */
+const TASK_PROGRESS_RE = /^[0-9]+\/[0-9]+$/;
+const STATUSES = new Set([
+  'initialized',
+  'in_progress',
+  'completed',
+  'blocked',
+]);
+
+export async function handle(input: unknown): Promise<ToolResponse> {
+  try {
+    const typed = (input ?? {}) as UpdateProgressInput;
+    if (typed.task_progress === undefined && typed.status === undefined) {
+      throwValidation(
+        'MISSING_FIELD',
+        'update_progress requires at least one of task_progress / status',
+      );
+    }
+    if (typed.task_progress !== undefined) {
+      if (!TASK_PROGRESS_RE.test(typed.task_progress)) {
+        throwValidation(
+          'TASK_PROGRESS_FORMAT',
+          `task_progress "${typed.task_progress}" must match N/M (digits)`,
+        );
+      }
+    }
+    if (typed.status !== undefined && !STATUSES.has(typed.status)) {
+      throwValidation(
+        'STATUS_INVALID',
+        `status "${typed.status}" is not one of initialized/in_progress/completed/blocked`,
+      );
+    }
+
+    const path = resolveStatePath();
+    const diff: Record<string, unknown> = {};
+    const after = await mutate(path, (s) => {
+      if (typed.task_progress !== undefined) {
+        diff['task_progress'] = {
+          before: s.position.task_progress,
+          after: typed.task_progress,
+        };
+        s.position.task_progress = typed.task_progress;
+      }
+      if (typed.status !== undefined) {
+        diff['status'] = { before: s.position.status, after: typed.status };
+        s.position.status = typed.status;
+      }
+      return s;
+    });
+    emitStateMutation(name, diff, after);
+    return okResponse({ position: after.position });
+  } catch (err) {
+    return errorResponse(err);
+  }
+}

package/scripts/validate-frontmatter.ts

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+/**
+ * validate-frontmatter.ts — CI-friendly frontmatter validator for agents/*.md.
+ *
+ * Enforces the Phase 7 agent frontmatter hygiene contract. Exits 0 on
+ * success, 1 on any violation. One finding per stdout line.
+ *
+ * Converted from scripts/validate-frontmatter.cjs in Plan 20-00 (Tier-1).
+ * Behavior preserved verbatim; strict types added for the frontmatter shape.
+ *
+ * Usage:
+ *   node --experimental-strip-types scripts/validate-frontmatter.ts [paths...]
+ *   # default path is `agents/` when none given.
+ */
+
+import { existsSync, statSync, readdirSync } from 'node:fs';
+import { join, basename } from 'node:path';
+
+import { readFrontmatter } from '../tests/helpers.ts';
+
+// Importing a type from generated.d.ts satisfies the Plan 20-00 rule that
+// every Tier-1 TS file participates in the codegen graph. We don't use
+// IntelSchema at runtime; the re-export keeps it visible for static checks.
+import type { IntelSchema } from '../reference/schemas/generated.js';
+export type { IntelSchema };
+
+/**
+ * Strict shape of the agent-frontmatter subset this validator enforces.
+ * Matches REQUIRED_FIELDS below. `readFrontmatter` returns a permissive
+ * `Record<string, string | boolean | string[]>` — we narrow per-field as
+ * needed rather than asserting the whole object at once.
+ */
+export interface AgentFrontmatter {
+  name: string;
+  description: string;
+  tools: string;
+  color: string;
+  'parallel-safe': boolean | string;
+  'typical-duration-seconds': string | number;
+  'reads-only': boolean | string;
+  writes: string | string[];
+  'default-tier'?: 'haiku' | 'sonnet' | 'opus';
+  'size_budget'?: 'S' | 'M' | 'L' | 'XL';
+}
+
+const REQUIRED_FIELDS: readonly (keyof AgentFrontmatter)[] = [
+  'name',
+  'description',
+  'tools',
+  'color',
+  'parallel-safe',
+  'typical-duration-seconds',
+  'reads-only',
+  'writes',
+];
+
+function walkMd(dir: string): string[] {
+  const out: string[] = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full: string = join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...walkMd(full));
+    else if (entry.isFile() && entry.name.endsWith('.md')) out.push(full);
+  }
+  return out;
+}
+
+/**
+ * Return true when the frontmatter value is "missing" per the original
+ * .cjs contract: undefined / null / empty string. Preserves the semantics
+ * exactly so the CI gate fires on the same inputs.
+ */
+function isMissing(v: unknown): boolean {
+  if (v === undefined || v === null) return true;
+  if (typeof v === 'string' && v === '') return true;
+  return false;
+}
+
+function main(): void {
+  const args: string[] = process.argv.slice(2).filter((a) => !a.startsWith('--'));
+  const targets: string[] = args.length ? args : ['agents/'];
+  const files: string[] = [];
+  for (const t of targets) {
+    if (!existsSync(t)) {
+      console.error(`${t}: path does not exist`);
+      process.exit(1);
+    }
+    const stat = statSync(t);
+    if (stat.isDirectory()) files.push(...walkMd(t));
+    else files.push(t);
+  }
+
+  let violations = 0;
+  for (const f of files) {
+    const fm = readFrontmatter(f);
+    if (Object.keys(fm).length === 0) {
+      // README.md under agents/ may have no frontmatter — skip
+      if (basename(f).toLowerCase() === 'readme.md') continue;
+      console.log(`${f}:frontmatter: missing`);
+      violations++;
+      continue;
+    }
+    for (const field of REQUIRED_FIELDS) {
+      if (!(field in fm) || isMissing((fm as Record<string, unknown>)[field])) {
+        console.log(`${f}:${field}: missing`);
+        violations++;
+      }
+    }
+  }
+
+  console.log(`summary: ${files.length} file(s) checked, ${violations} violation(s)`);
+  process.exit(violations === 0 ? 0 : 1);
+}
+
+main();

package/scripts/validate-schemas.ts

@@ -0,0 +1,401 @@
+#!/usr/bin/env node
+/**
+ * validate-schemas.ts
+ *
+ * Runs all Draft-07 JSON schemas under reference/schemas/ against their
+ * corresponding subject files. Used by `npm run validate:schemas` and by the
+ * CI validate job.
+ *
+ * Primary path: spawn `npx --yes ajv-cli@5 validate -s <schema> -d <data>`.
+ *
+ * Fallback path: if `npx --yes` cannot fetch ajv-cli (offline/sandboxed
+ * environment), fall back to a structural parse check: confirm each schema is
+ * valid Draft-07 JSON (has $schema, type) and each data file is parseable JSON.
+ * The fallback exits 0 on structural validity; CI will run the real ajv pass.
+ *
+ * Usage:
+ *   node --experimental-strip-types scripts/validate-schemas.ts
+ *   node --experimental-strip-types scripts/validate-schemas.ts --no-npx
+ *
+ * Exit codes:
+ *   0 — all present (schema, data) pairs pass
+ *   1 — one or more pairs failed validation or a present schema is invalid
+ *
+ * Converted from scripts/validate-schemas.cjs in Plan 20-00. Behavior is
+ * verbatim; only typing + generated-type-import were added.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, join, dirname } from 'node:path';
+
+// Generated types from reference/schemas/generated.d.ts — importing any one
+// of them satisfies Plan 20-00's requirement that every Tier-1 TS file
+// consumes the codegen graph. We re-export so downstream callers can also
+// pin to these types for static validation.
+import type {
+  ConfigSchema,
+  PluginSchema,
+  MarketplaceSchema,
+  HooksSchema,
+  IntelSchema,
+  AuthoritySnapshotSchema,
+  EventsSchema,
+  McpGddStateToolsSchema,
+  BudgetSchema,
+  RateLimitsSchema,
+  IterationBudgetSchema,
+} from '../reference/schemas/generated.js';
+
+export type {
+  ConfigSchema,
+  PluginSchema,
+  MarketplaceSchema,
+  HooksSchema,
+  IntelSchema,
+  AuthoritySnapshotSchema,
+  EventsSchema,
+  McpGddStateToolsSchema,
+  BudgetSchema,
+  RateLimitsSchema,
+  IterationBudgetSchema,
+};
+
+/**
+ * Discover the repo root by walking up from cwd to find our package.json.
+ * Kept identical to the approach in tests/helpers.ts so both modules behave
+ * the same when invoked from worktrees, subdirectories, or CI.
+ */
+function findRepoRoot(): string {
+  let dir: string = process.cwd();
+  for (let i = 0; i < 10; i++) {
+    try {
+      const pkgPath: string = join(dir, 'package.json');
+      const pkg: { name?: string } = JSON.parse(readFileSync(pkgPath, 'utf8')) as { name?: string };
+      if (pkg.name === '@hegemonart/get-design-done') return dir;
+    } catch {
+      // not this level
+    }
+    const parent: string = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return resolve(process.cwd());
+}
+
+const REPO_ROOT: string = findRepoRoot();
+
+/**
+ * (schema, data) pairs. `data` is relative to repo root. `required=true`
+ * means the data file MUST exist in the repo; `required=false` means the
+ * data file is generated at runtime (gitignored) and only the schema itself
+ * is compiled.
+ */
+interface Pair {
+  name: string;
+  schema: string;
+  data: string | null;
+  required: boolean;
+}
+
+export const PAIRS: readonly Pair[] = [
+  {
+    name: 'plugin',
+    schema: 'reference/schemas/plugin.schema.json',
+    data: '.claude-plugin/plugin.json',
+    required: true,
+  },
+  {
+    name: 'marketplace',
+    schema: 'reference/schemas/marketplace.schema.json',
+    data: '.claude-plugin/marketplace.json',
+    required: true,
+  },
+  {
+    name: 'hooks',
+    schema: 'reference/schemas/hooks.schema.json',
+    data: 'hooks/hooks.json',
+    required: true,
+  },
+  {
+    name: 'config',
+    schema: 'reference/schemas/config.schema.json',
+    data: '.design/config.json',
+    required: false,
+  },
+  {
+    name: 'intel',
+    schema: 'reference/schemas/intel.schema.json',
+    // intel files are runtime-only (gitignored). Only schema-compile it.
+    data: null,
+    required: false,
+  },
+  {
+    name: 'authority-snapshot',
+    schema: 'reference/schemas/authority-snapshot.schema.json',
+    // .design/authority-snapshot.json is runtime-only (gitignored via .design/).
+    // Only schema-compile it.
+    data: null,
+    required: false,
+  },
+  {
+    name: 'events',
+    schema: 'reference/schemas/events.schema.json',
+    // .design/telemetry/events.jsonl is runtime-only (gitignored). It is
+    // JSONL (one JSON object per line) rather than a single JSON document,
+    // so we cannot point ajv-cli at it as a `data` subject — each *line*
+    // is the schema subject, not the file. Schema-compile only here;
+    // per-line structural discipline is enforced by the EventWriter at
+    // runtime (Plan 20-06). See scripts/lib/event-stream/writer.ts.
+    data: null,
+    required: false,
+  },
+  {
+    name: 'mcp-gdd-state-tools',
+    schema: 'reference/schemas/mcp-gdd-state-tools.schema.json',
+    // The combined tool manifest is a codegen artifact — individual per-tool
+    // schemas live under scripts/mcp-servers/gdd-state/schemas/ and are
+    // consumed directly by the server. Schema-compile only here so the
+    // Draft-07 declaration stays valid as tools evolve. See Plan 20-05.
+    data: null,
+    required: false,
+  },
+  {
+    name: 'budget',
+    schema: 'reference/schemas/budget.schema.json',
+    // .design/budget.json is runtime-only (created by scripts/bootstrap.sh
+    // on first session if absent, per D-12). It's gitignored under .design/
+    // so the data file isn't tracked — schema-compile only here. The
+    // budget-enforcer.ts hook consumes BudgetSchema from generated.d.ts at
+    // type-check time regardless of file presence. See Plan 20-13.
+    data: null,
+    required: false,
+  },
+  {
+    name: 'rate-limits',
+    schema: 'reference/schemas/rate-limits.schema.json',
+    // .design/rate-limits/<provider>.json is runtime-only, written by
+    // scripts/lib/rate-guard.cjs as a side-effect of every
+    // ingestHeaders() call. One file per provider — they're all the same
+    // shape — so no single subject data path exists. Schema-compile
+    // only here; per-file structural discipline is enforced at write
+    // time by rate-guard. See Plan 20-14.
+    data: null,
+    required: false,
+  },
+  {
+    name: 'iteration-budget',
+    schema: 'reference/schemas/iteration-budget.schema.json',
+    // .design/iteration-budget.json is runtime-only, written by
+    // scripts/lib/iteration-budget.cjs. Schema-compile only here.
+    // See Plan 20-14.
+    data: null,
+    required: false,
+  },
+];
+
+const USE_NPX: boolean = !process.argv.includes('--no-npx');
+
+/** Shape of an ajv-cli invocation result. */
+interface AjvResult {
+  ok: boolean;
+  stdout: string;
+  stderr: string;
+  status: number | null;
+  fetchFailed: boolean;
+}
+
+/**
+ * Try running ajv-cli via npx. Returns { ok, stdout, stderr, status, fetchFailed }.
+ * fetchFailed=true if npx couldn't fetch the package (offline); caller should fall back.
+ *
+ * We pass `-c ajv-formats` so schemas declaring `format: "date-time"` (etc.) are
+ * validated against the standard JSON Schema formats plugin rather than being
+ * rejected as unknown formats under ajv's strict mode.
+ */
+function runAjv(args: readonly string[]): AjvResult {
+  const injected: string[] = [...args, '-c', 'ajv-formats'];
+  // Windows ships `npx.cmd` (batch shim); Node's spawnSync cannot invoke .cmd
+  // files without `shell: true`. On POSIX `shell: true` is a no-op here since
+  // the argv is a fixed whitelist (no user-controlled substitution). This
+  // fixes the pre-existing Windows-local failure while preserving CI
+  // behavior on Linux runners.
+  const result = spawnSync(
+    'npx',
+    ['--yes', '-p', 'ajv-cli@5', '-p', 'ajv-formats@3', 'ajv', ...injected],
+    { encoding: 'utf8', cwd: REPO_ROOT, shell: process.platform === 'win32' },
+  );
+  const stdout: string = result.stdout ?? '';
+  const stderr: string = result.stderr ?? '';
+  const combined: string = stdout + stderr;
+  // fetchFailed heuristic now also catches the "npx binary not on PATH /
+  // spawn ENOENT" case so offline or missing-npx sandboxes fall back cleanly.
+  const spawnFailed: boolean =
+    result.error !== undefined &&
+    ((result.error as NodeJS.ErrnoException).code === 'ENOENT' ||
+      (result.error as NodeJS.ErrnoException).code === 'ENOTDIR');
+  const fetchFailed: boolean =
+    spawnFailed ||
+    (result.status !== 0 &&
+      /(ENOTFOUND|ECONNREFUSED|ETIMEDOUT|getaddrinfo|network|unable to resolve|unable to fetch|offline|E404|registry\.npmjs\.org)/i.test(
+        combined,
+      ));
+  return {
+    ok: result.status === 0,
+    stdout,
+    stderr,
+    status: result.status,
+    fetchFailed,
+  };
+}
+
+/** Outcome of a structural (fallback) schema/data parse check. */
+interface StructuralResult {
+  ok: boolean;
+  reason?: string;
+}
+
+/**
+ * Fallback: confirm schema file is a valid Draft-07 JSON Schema (has $schema
+ * pointing at draft-07). Confirm data file (if present) parses as JSON.
+ */
+function structuralCheck(schemaAbs: string, dataAbs: string | null): StructuralResult {
+  let schema: { $schema?: string };
+  try {
+    schema = JSON.parse(readFileSync(schemaAbs, 'utf8')) as { $schema?: string };
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    return { ok: false, reason: `schema not parseable JSON: ${msg}` };
+  }
+  if (!schema.$schema || !/draft-07/.test(schema.$schema)) {
+    return { ok: false, reason: `schema missing Draft-07 $schema declaration` };
+  }
+  if (dataAbs) {
+    try {
+      JSON.parse(readFileSync(dataAbs, 'utf8'));
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      return { ok: false, reason: `data file not parseable JSON: ${msg}` };
+    }
+  }
+  return { ok: true };
+}
+
+/** Per-pair validation result. */
+interface PairResult {
+  name: string;
+  ok: boolean;
+  via: string;
+  note?: string;
+  reason?: string;
+}
+
+function main(): void {
+  const results: PairResult[] = [];
+  let fallbackReason: string | null = null;
+
+  for (const pair of PAIRS) {
+    const schemaAbs: string = join(REPO_ROOT, pair.schema);
+    const dataAbs: string | null = pair.data ? join(REPO_ROOT, pair.data) : null;
+
+    if (!existsSync(schemaAbs)) {
+      results.push({
+        name: pair.name,
+        ok: false,
+        via: 'missing-schema',
+        reason: `schema not found at ${pair.schema}`,
+      });
+      continue;
+    }
+
+    const dataPresent: boolean = Boolean(dataAbs) && existsSync(dataAbs as string);
+
+    if (!dataPresent && pair.required) {
+      results.push({
+        name: pair.name,
+        ok: false,
+        via: 'missing-data',
+        reason: `required data file missing at ${pair.data}`,
+      });
+      continue;
+    }
+
+    if (!dataPresent) {
+      // Schema-only: compile to confirm the schema is structurally valid.
+      if (USE_NPX && !fallbackReason) {
+        const r = runAjv(['compile', '-s', schemaAbs]);
+        if (r.ok) {
+          results.push({
+            name: pair.name,
+            ok: true,
+            via: 'ajv-compile',
+            note: 'data not present in repo tree — schema compiled only',
+          });
+          continue;
+        }
+        if (r.fetchFailed) {
+          fallbackReason = `npx fetch failed: ${r.stderr.split('\n')[0] || 'unknown'}`;
+        } else {
+          results.push({
+            name: pair.name,
+            ok: false,
+            via: 'ajv-compile',
+            reason: r.stderr || r.stdout || `exit ${r.status ?? 'null'}`,
+          });
+          continue;
+        }
+      }
+      const s = structuralCheck(schemaAbs, null);
+      const reason: string = s.ok
+        ? 'schema is valid Draft-07 (data not in repo tree)'
+        : s.reason ?? 'unknown failure';
+      results.push({ name: pair.name, ok: s.ok, via: 'structural-compile', reason });
+      continue;
+    }
+
+    // Both schema and data present — full validation.
+    if (USE_NPX && !fallbackReason) {
+      const r = runAjv(['validate', '-s', schemaAbs, '-d', dataAbs as string]);
+      if (r.ok) {
+        results.push({ name: pair.name, ok: true, via: 'ajv-validate' });
+        continue;
+      }
+      if (r.fetchFailed) {
+        fallbackReason = `npx fetch failed: ${r.stderr.split('\n')[0] || 'unknown'}`;
+      } else {
+        results.push({
+          name: pair.name,
+          ok: false,
+          via: 'ajv-validate',
+          reason: r.stderr || r.stdout || `exit ${r.status ?? 'null'}`,
+        });
+        continue;
+      }
+    }
+    const s = structuralCheck(schemaAbs, dataAbs);
+    const reason: string = s.ok
+      ? 'schema is valid Draft-07 and data parses as JSON'
+      : s.reason ?? 'unknown failure';
+    results.push({ name: pair.name, ok: s.ok, via: 'structural-validate', reason });
+  }
+
+  // Report.
+  console.log('validate-schemas: results');
+  for (const r of results) {
+    const status: string = r.ok ? 'OK' : 'FAIL';
+    const note: string = r.note ? ` (${r.note})` : '';
+    const reason: string = r.reason ? ` — ${r.reason}` : '';
+    console.log(`  [${status}] ${r.name} via ${r.via}${note}${reason}`);
+  }
+  if (fallbackReason) {
+    console.log(
+      `\nnote: ajv-cli via npx unavailable (${fallbackReason}); fell back to structural checks. CI will run the authoritative ajv pass.`,
+    );
+  }
+  const failed: PairResult[] = results.filter((r) => !r.ok);
+  console.log(`summary: ${results.length} pair(s) checked, ${failed.length} failure(s)`);
+
+  process.exit(failed.length === 0 ? 0 : 1);
+}
+
+main();

package/skills/brief/SKILL.md

@@ -2,7 +2,7 @@
 name: gdd-brief
 description: "Design intake — captures problem statement, audience, constraints, success metrics, and scope into .design/BRIEF.md (Stage 1 of 5)"
 argument-hint: "[--re-brief to redo intake on existing project]"
-tools: Read, Write, AskUserQuestion
+tools: Read, Write, AskUserQuestion, mcp__gdd_state__frontmatter_update, mcp__gdd_state__set_status, mcp__gdd_state__update_progress, mcp__gdd_state__get
 ---
 
 # Get Design Done — Brief
@@ -56,12 +56,21 @@ Write the brief with these sections, preserving any pre-existing answers:
 <answer>
 ```
 
-## Step 4 — Update STATE.md
+## Step 4 — Bootstrap STATE.md (if missing)
 
-- If `.design/STATE.md` does not exist, create it from `reference/STATE-TEMPLATE.md`.
-- Set frontmatter `stage: explore` (next stage).
-- Update `last_checkpoint` to now.
-- Write STATE.md.
+<!-- BOOTSTRAP EXCEPTION: STATE.md does not exist yet — MCP tools require it to exist. Direct Write is intentional. All subsequent mutations use MCP. -->
+
+If `.design/STATE.md` does not exist, copy the template block from `reference/STATE-TEMPLATE.md` (between `==== BEGIN TEMPLATE ====` and `==== END TEMPLATE ====`) to `.design/STATE.md` via `Write`. Leave the `<ISO 8601 timestamp>` placeholders in-place — Step 5 stamps them via MCP. If STATE.md already exists, skip to Step 5.
+
+## Step 5 — Commit STATE.md initialization
+
+With `.design/STATE.md` seeded from the template:
+
+1. Stamp timestamps + cycle id: call `mcp__gdd_state__frontmatter_update` with `patch: { started_at: <ISO>, last_checkpoint: <ISO>, cycle: <cycle-id> }`.
+2. Mark brief progress: call `mcp__gdd_state__update_progress` with `task_progress: "5/5"`, `status: "brief_complete"`.
+3. Set handoff status: call `mcp__gdd_state__set_status` with `status: "brief_complete"`.
+
+Do NOT call `mcp__gdd_state__transition_stage` from brief — explore calls it on entry, keeping the transition atomic with the stage that owns the new state.
 
 ## After Writing