@hegemonart/get-design-done 1.19.6 → 1.21.0

package/scripts/lib/tool-scoping/parse-agent-tools.ts

@@ -0,0 +1,207 @@
+// scripts/lib/tool-scoping/parse-agent-tools.ts — extract the `tools:`
+// list from an agent markdown file's YAML frontmatter.
+//
+// Why a hand-rolled parser instead of pulling in js-yaml:
+//   * No new npm deps (Plan 21-03 hard constraint).
+//   * The `tools:` field grammar is narrow (4 YAML shapes + wildcard +
+//     empty). A minimal parser covering exactly those shapes is
+//     maintainable and keeps the surface area tight.
+//
+// Supported frontmatter shapes:
+//   tools: Read, Write, Grep              → ['Read','Write','Grep']
+//   tools: [Read, Write]                  → ['Read','Write']
+//   tools: "*"                            → null (wildcard fallback)
+//   tools: []                             → []    (MCP-only narrow)
+//   tools:
+//     - Read
+//     - Write                             → ['Read','Write']
+//
+// Return contract:
+//   null         — file missing, no frontmatter, tools key absent, OR wildcard.
+//   []           — tools: [] OR tools: (no children).
+//   string[]     — the declared, trimmed, de-quoted list.
+
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+/**
+ * Read the `tools:` field from an agent markdown file's YAML
+ * frontmatter. See module header for the full grammar.
+ *
+ * @param agentMdPath absolute or cwd-relative path to an `agents/*.md`.
+ * @returns readonly string[] | null per the contract above.
+ */
+export function parseAgentTools(
+  agentMdPath: string,
+): readonly string[] | null {
+  let raw: string;
+  try {
+    raw = readFileSync(agentMdPath, 'utf8');
+  } catch (err) {
+    // ENOENT or any read error → treat as "no override" (null).
+    if (
+      err !== null &&
+      typeof err === 'object' &&
+      'code' in err &&
+      (err as { code: string }).code === 'ENOENT'
+    ) {
+      return null;
+    }
+    // Permission/IO errors also fall through to null — a parser that
+    // throws on any fs hiccup would crash the entire session at scope
+    // computation time; fail-closed (null = stage default) is safer.
+    return null;
+  }
+
+  const frontmatter: string | null = extractFrontmatter(raw);
+  if (frontmatter === null) return null;
+
+  return extractToolsField(frontmatter);
+}
+
+/**
+ * Convenience: look up an agent by bare name under `<agentsRoot>/<name>.md`
+ * and delegate to `parseAgentTools`. Defaults to `./agents` when no root
+ * is supplied.
+ */
+export function parseAgentToolsByName(
+  name: string,
+  agentsRoot: string = 'agents',
+): readonly string[] | null {
+  const path: string = resolve(agentsRoot, `${name}.md`);
+  return parseAgentTools(path);
+}
+
+// ---------------------------------------------------------------------------
+// Internal — frontmatter splitter
+// ---------------------------------------------------------------------------
+
+/**
+ * Return the text between the opening `---\n` and closing `---\n` lines,
+ * or null when no valid frontmatter block exists.
+ *
+ * Matches the splitter in `scripts/lib/prompt-sanitizer/index.ts` — kept
+ * local (rather than imported) to avoid coupling the tool-scoping module
+ * to prompt-sanitizer internals.
+ */
+function extractFrontmatter(raw: string): string | null {
+  // Accept LF or CRLF. First line must be exactly `---`.
+  const match: RegExpExecArray | null = /^---\r?\n([\s\S]*?)\r?\n---\r?\n/.exec(
+    raw,
+  );
+  if (match === null) return null;
+  const body: string | undefined = match[1];
+  return body ?? null;
+}
+
+// ---------------------------------------------------------------------------
+// Internal — tools field extractor
+// ---------------------------------------------------------------------------
+
+/**
+ * Given the frontmatter body (text between `---` fences), return the
+ * parsed `tools:` field per the contract. Absence returns null.
+ */
+function extractToolsField(frontmatter: string): readonly string[] | null {
+  const lines: string[] = frontmatter.split(/\r?\n/);
+  const toolsLineRe = /^tools:\s*(.*)$/;
+
+  for (let i = 0; i < lines.length; i += 1) {
+    const line: string = lines[i] ?? '';
+    const m: RegExpExecArray | null = toolsLineRe.exec(line);
+    if (m === null) continue;
+
+    const rest: string = (m[1] ?? '').trim();
+
+    // Case 1: wildcard — `tools: "*"` or `tools: *`.
+    //   Per the Plan 21-03 frontmatter contract, this is a forward-compat
+    //   escape that falls back to stage default (NOT "everything"), so we
+    //   return null to signal "no override".
+    if (rest === '*' || rest === '"*"' || rest === "'*'") {
+      return null;
+    }
+
+    // Case 2: flow-style `tools: [...]` or empty `tools: []`.
+    if (rest.startsWith('[') && rest.endsWith(']')) {
+      const inner: string = rest.slice(1, -1).trim();
+      if (inner === '') return Object.freeze([]);
+      return Object.freeze(splitAndClean(inner));
+    }
+
+    // Case 3: YAML list (empty value on tools: line, items follow).
+    if (rest === '') {
+      const items: string[] = [];
+      for (let j = i + 1; j < lines.length; j += 1) {
+        const next: string = lines[j] ?? '';
+        // A blank line or a non-list-item line ends the block.
+        if (next.trim() === '') continue;
+        const listItem: RegExpExecArray | null = /^\s*-\s*(\S.*)$/.exec(next);
+        if (listItem === null) break;
+        const entry: string | undefined = listItem[1];
+        if (entry === undefined) break;
+        items.push(cleanToken(entry));
+      }
+      return Object.freeze(items);
+    }
+
+    // Case 4: inline comma-separated list (may have quoted entries).
+    return Object.freeze(splitAndClean(rest));
+  }
+
+  return null;
+}
+
+/**
+ * Split a comma-separated list while honoring double-quoted entries
+ * (so `"Read, with-comma", "Write"` stays a 2-element list). Trims
+ * whitespace and strips surrounding single / double quotes from each
+ * token.
+ */
+function splitAndClean(input: string): string[] {
+  const out: string[] = [];
+  let buf: string[] = [];
+  let inDouble = false;
+  let inSingle = false;
+
+  for (const ch of input) {
+    if (ch === '"' && !inSingle) {
+      inDouble = !inDouble;
+      buf.push(ch);
+      continue;
+    }
+    if (ch === "'" && !inDouble) {
+      inSingle = !inSingle;
+      buf.push(ch);
+      continue;
+    }
+    if (ch === ',' && !inDouble && !inSingle) {
+      out.push(cleanToken(buf.join('')));
+      buf = [];
+      continue;
+    }
+    buf.push(ch);
+  }
+
+  const tail: string = cleanToken(buf.join(''));
+  if (tail !== '' || out.length === 0) {
+    out.push(tail);
+  }
+
+  return out.filter((t) => t !== '');
+}
+
+/**
+ * Trim whitespace + strip matching leading/trailing quote pairs.
+ * Applied to each split list entry.
+ */
+function cleanToken(token: string): string {
+  let t: string = token.trim();
+  if (t.length >= 2) {
+    const first: string = t[0] ?? '';
+    const last: string = t[t.length - 1] ?? '';
+    if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+      t = t.slice(1, -1).trim();
+    }
+  }
+  return t;
+}

package/scripts/lib/tool-scoping/stage-scopes.ts

@@ -0,0 +1,139 @@
+// scripts/lib/tool-scoping/stage-scopes.ts — frozen per-stage default
+// scope registry and native-tool classifier.
+//
+// The locked table below is the single source of truth for what each
+// pipeline stage is permitted. DO NOT MODIFY without a follow-up plan:
+// widening a stage here silently expands every headless session that
+// falls back to defaults.
+//
+// MCP tools (`mcp__*`) are NEVER in this registry — they're always
+// permitted and bypass the native filter entirely. See `isMcpTool`.
+
+import type { Stage } from './types.ts';
+
+/**
+ * Shape of a single registry entry. Frozen at module load.
+ */
+interface StageDefault {
+  readonly allowed: readonly string[];
+  readonly bashMutation: boolean;
+}
+
+/**
+ * Per-stage default scope table. Every `Stage` key must have an entry —
+ * `computeScope` relies on this for invariant lookup.
+ *
+ * Locked contract (see PLAN 21-03):
+ *   brief   — Read/Write/Edit/Grep/Glob/Bash (Bash read-only, advisory)
+ *   explore — Read/Grep/Glob/Bash/WebSearch/WebFetch/Task (Bash read-only)
+ *   plan    — Read/Write/Edit/Grep/Glob/Bash/Task (Bash read-only)
+ *   design  — Read/Write/Edit/Grep/Glob/Bash/Task (Bash mutation ALLOWED)
+ *   verify  — Read/Grep/Glob/Bash (NO Write/Edit/Task; Bash read-only)
+ *   init    — Read/Write/Grep/Glob/Bash/Task/WebSearch/WebFetch (bootstrap)
+ *   custom  — empty (caller-provided only; no defaults)
+ */
+export const STAGE_SCOPES: Readonly<Record<Stage, StageDefault>> =
+  Object.freeze({
+    brief: Object.freeze({
+      allowed: Object.freeze(['Read', 'Write', 'Edit', 'Grep', 'Glob', 'Bash']),
+      bashMutation: false,
+    }),
+    explore: Object.freeze({
+      allowed: Object.freeze([
+        'Read',
+        'Grep',
+        'Glob',
+        'Bash',
+        'WebSearch',
+        'WebFetch',
+        'Task',
+      ]),
+      bashMutation: false,
+    }),
+    plan: Object.freeze({
+      allowed: Object.freeze([
+        'Read',
+        'Write',
+        'Edit',
+        'Grep',
+        'Glob',
+        'Bash',
+        'Task',
+      ]),
+      bashMutation: false,
+    }),
+    design: Object.freeze({
+      allowed: Object.freeze([
+        'Read',
+        'Write',
+        'Edit',
+        'Grep',
+        'Glob',
+        'Bash',
+        'Task',
+      ]),
+      bashMutation: true,
+    }),
+    verify: Object.freeze({
+      allowed: Object.freeze(['Read', 'Grep', 'Glob', 'Bash']),
+      bashMutation: false,
+    }),
+    init: Object.freeze({
+      allowed: Object.freeze([
+        'Read',
+        'Write',
+        'Grep',
+        'Glob',
+        'Bash',
+        'Task',
+        'WebSearch',
+        'WebFetch',
+      ]),
+      bashMutation: false,
+    }),
+    custom: Object.freeze({
+      allowed: Object.freeze([]),
+      bashMutation: false,
+    }),
+  });
+
+/**
+ * Authoritative list of native (harness-managed) tool names. Anything
+ * NOT in this list and NOT MCP-prefixed is unknown and treated as a
+ * native miss by `checkTool`.
+ *
+ * Order matches the documented stage scopes; tests assert that every
+ * tool referenced in STAGE_SCOPES is a member of NATIVE_TOOLS.
+ */
+export const NATIVE_TOOLS: readonly string[] = Object.freeze([
+  'Read',
+  'Write',
+  'Edit',
+  'Grep',
+  'Glob',
+  'Bash',
+  'Task',
+  'WebSearch',
+  'WebFetch',
+]);
+
+/** MCP tools carry the `mcp__` prefix by convention. */
+const MCP_PREFIX = 'mcp__';
+
+/**
+ * True when `name` is an MCP tool. MCP tools always pass scope checks —
+ * each MCP server declares its own security perimeter, so the stage
+ * filter only gates native harness tools.
+ */
+export function isMcpTool(name: string): boolean {
+  return typeof name === 'string' && name.startsWith(MCP_PREFIX);
+}
+
+/**
+ * True when `name` is a known native harness tool. Used by
+ * `computeScope` to split caller-supplied lists into native vs MCP
+ * buckets.
+ */
+export function isNativeTool(name: string): boolean {
+  return NATIVE_TOOLS.includes(name);
+}

package/scripts/lib/tool-scoping/types.ts

@@ -0,0 +1,77 @@
+// scripts/lib/tool-scoping/types.ts — type definitions for per-stage
+// allowed-tools enforcement.
+//
+// See ./index.ts for the public API surface. Types are kept in this file
+// so fixtures, tests, and callers can import them without pulling the
+// full parser/compute machinery.
+
+/**
+ * Canonical pipeline stage name. `custom` is the escape valve for
+ * callers that manage their own scope entirely; it has no defaults.
+ */
+export type Stage =
+  | 'brief'
+  | 'explore'
+  | 'plan'
+  | 'design'
+  | 'verify'
+  | 'init'
+  | 'custom';
+
+/**
+ * Computed scope for a headless Agent SDK session. Produced by
+ * `computeScope`; consumed by `checkTool`, `enforceScope`, and
+ * `session-runner`'s `allowedTools` parameter.
+ *
+ * `allowed` is a flattened, deduplicated, alphabetically sorted list
+ * (deterministic output — stable across runs).
+ *
+ * `denied` is `NATIVE_TOOLS \ allowed_native`: the set of native
+ * harness tools explicitly NOT permitted on this session. MCP tools
+ * are never in `denied` — they always pass.
+ */
+export interface Scope {
+  readonly stage: Stage;
+  /** Flattened, deduplicated, sorted list of allowed tool names. */
+  readonly allowed: readonly string[];
+  /** Native tools explicitly denied by the stage (e.g., verify denies Write). */
+  readonly denied: readonly string[];
+  /**
+   * Whether bash mutations are permitted (stage-level flag, advisory —
+   * hard gating is future work in Phase 22's `gdd-router`).
+   */
+  readonly bashMutation: boolean;
+}
+
+/**
+ * Input to `computeScope` / `enforceScope`.
+ *
+ * `agentTools` precedence rules (documented in stage-scopes.ts):
+ *   undefined / null    → stage default applies
+ *   []                  → scope narrows to MCP-only (empty native list)
+ *   string[] (non-empty)→ overrides stage defaults entirely
+ *
+ * `additional` is unioned with the scope (caller-supplied, e.g.,
+ * `mcp__gdd_state__*` tool names the session needs access to).
+ */
+export interface ScopeInput {
+  readonly stage: Stage;
+  /** Optional agent-frontmatter override (from parseAgentTools). */
+  readonly agentTools?: readonly string[] | null;
+  /** Additional tools to union with the scope (caller-supplied). */
+  readonly additional?: readonly string[];
+}
+
+/**
+ * Structured denial record returned by `checkTool`. `enforceScope`
+ * lifts these into `ValidationError` instances (from gdd-errors).
+ *
+ * `tool` is absent when the violation is not tool-specific
+ * (e.g., `INVALID_STAGE`, `EMPTY_SCOPE`).
+ */
+export interface ScopeViolation {
+  readonly code: 'TOOL_NOT_ALLOWED' | 'INVALID_STAGE' | 'EMPTY_SCOPE';
+  readonly tool?: string;
+  readonly stage: Stage;
+  readonly message: string;
+}

package/scripts/mcp-servers/gdd-state/schemas/add_blocker.schema.json

@@ -0,0 +1,67 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/hegemonart/get-design-done/main/scripts/mcp-servers/gdd-state/schemas/add_blocker.schema.json",
+  "title": "GddStateAddBlocker",
+  "description": "MCP tool gdd_state__add_blocker — append one entry to <blockers>. Emits state.mutation.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["input", "output"],
+  "properties": {
+    "input": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["text"],
+      "properties": {
+        "text": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Human-readable blocker description."
+        },
+        "stage": {
+          "type": "string",
+          "description": "Optional. Defaults to <position>.stage."
+        },
+        "date": {
+          "type": "string",
+          "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$",
+          "description": "Optional ISO date (YYYY-MM-DD). Defaults to today (UTC)."
+        }
+      }
+    },
+    "output": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["success"],
+      "properties": {
+        "success": { "type": "boolean" },
+        "data": {
+          "type": "object",
+          "additionalProperties": true,
+          "properties": {
+            "blocker": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["stage", "date", "text"],
+              "properties": {
+                "stage": { "type": "string" },
+                "date": { "type": "string" },
+                "text": { "type": "string" }
+              }
+            },
+            "count": { "type": "integer", "minimum": 1 }
+          }
+        },
+        "error": {
+          "type": "object",
+          "additionalProperties": true,
+          "required": ["code", "message", "kind"],
+          "properties": {
+            "code": { "type": "string" },
+            "message": { "type": "string" },
+            "kind": { "type": "string", "enum": ["validation", "state_conflict", "operation_failed", "unknown"] }
+          }
+        }
+      }
+    }
+  }
+}

package/scripts/mcp-servers/gdd-state/schemas/add_decision.schema.json

@@ -0,0 +1,68 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/hegemonart/get-design-done/main/scripts/mcp-servers/gdd-state/schemas/add_decision.schema.json",
+  "title": "GddStateAddDecision",
+  "description": "MCP tool gdd_state__add_decision — append one entry to <decisions>. Emits state.mutation.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["input", "output"],
+  "properties": {
+    "input": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["text"],
+      "properties": {
+        "text": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Human-readable decision text."
+        },
+        "status": {
+          "type": "string",
+          "enum": ["locked", "tentative"],
+          "description": "Defaults to tentative."
+        },
+        "id": {
+          "type": "string",
+          "pattern": "^D-[0-9]+$",
+          "description": "Optional. Defaults to next available D-N based on existing decisions."
+        }
+      }
+    },
+    "output": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["success"],
+      "properties": {
+        "success": { "type": "boolean" },
+        "data": {
+          "type": "object",
+          "additionalProperties": true,
+          "properties": {
+            "decision": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["id", "text", "status"],
+              "properties": {
+                "id": { "type": "string" },
+                "text": { "type": "string" },
+                "status": { "type": "string", "enum": ["locked", "tentative"] }
+              }
+            },
+            "count": { "type": "integer", "minimum": 1 }
+          }
+        },
+        "error": {
+          "type": "object",
+          "additionalProperties": true,
+          "required": ["code", "message", "kind"],
+          "properties": {
+            "code": { "type": "string" },
+            "message": { "type": "string" },
+            "kind": { "type": "string", "enum": ["validation", "state_conflict", "operation_failed", "unknown"] }
+          }
+        }
+      }
+    }
+  }
+}

package/scripts/mcp-servers/gdd-state/schemas/add_must_have.schema.json

@@ -0,0 +1,68 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/hegemonart/get-design-done/main/scripts/mcp-servers/gdd-state/schemas/add_must_have.schema.json",
+  "title": "GddStateAddMustHave",
+  "description": "MCP tool gdd_state__add_must_have — append one entry to <must_haves>. Emits state.mutation.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["input", "output"],
+  "properties": {
+    "input": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["text"],
+      "properties": {
+        "text": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Human-readable must-have criterion."
+        },
+        "status": {
+          "type": "string",
+          "enum": ["pending", "pass", "fail"],
+          "description": "Defaults to pending."
+        },
+        "id": {
+          "type": "string",
+          "pattern": "^M-[0-9]+$",
+          "description": "Optional. Defaults to next available M-N based on existing must_haves."
+        }
+      }
+    },
+    "output": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["success"],
+      "properties": {
+        "success": { "type": "boolean" },
+        "data": {
+          "type": "object",
+          "additionalProperties": true,
+          "properties": {
+            "must_have": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["id", "text", "status"],
+              "properties": {
+                "id": { "type": "string" },
+                "text": { "type": "string" },
+                "status": { "type": "string", "enum": ["pending", "pass", "fail"] }
+              }
+            },
+            "count": { "type": "integer", "minimum": 1 }
+          }
+        },
+        "error": {
+          "type": "object",
+          "additionalProperties": true,
+          "required": ["code", "message", "kind"],
+          "properties": {
+            "code": { "type": "string" },
+            "message": { "type": "string" },
+            "kind": { "type": "string", "enum": ["validation", "state_conflict", "operation_failed", "unknown"] }
+          }
+        }
+      }
+    }
+  }
+}

package/scripts/mcp-servers/gdd-state/schemas/checkpoint.schema.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/hegemonart/get-design-done/main/scripts/mcp-servers/gdd-state/schemas/checkpoint.schema.json",
+  "title": "GddStateCheckpoint",
+  "description": "MCP tool gdd_state__checkpoint — bump frontmatter.last_checkpoint + append a <timestamps> entry. Emits state.mutation.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["input", "output"],
+  "properties": {
+    "input": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "label": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Optional label for the timestamp entry key. When absent the key is `<stage>_checkpoint_at`."
+        }
+      }
+    },
+    "output": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["success"],
+      "properties": {
+        "success": { "type": "boolean" },
+        "data": {
+          "type": "object",
+          "additionalProperties": true,
+          "properties": {
+            "last_checkpoint": {
+              "type": "string",
+              "format": "date-time"
+            },
+            "timestamp_key": { "type": "string" }
+          }
+        },
+        "error": {
+          "type": "object",
+          "additionalProperties": true,
+          "required": ["code", "message", "kind"],
+          "properties": {
+            "code": { "type": "string" },
+            "message": { "type": "string" },
+            "kind": { "type": "string", "enum": ["validation", "state_conflict", "operation_failed", "unknown"] }
+          }
+        }
+      }
+    }
+  }
+}