@hegemonart/get-design-done 1.20.0 → 1.22.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/lib/trajectory/index.cjs

@@ -0,0 +1,126 @@
+/**
+ * trajectory/index.cjs — per-tool-call trajectory stream (Plan 22-03).
+ *
+ * Records every agent tool-use as one JSONL line at
+ *   `.design/telemetry/trajectories/<cycle>.jsonl`
+ *
+ * Why hash args/result instead of storing full content:
+ *   * keeps line size bounded regardless of argument payload
+ *   * de-identifies prompts that may contain user-private content
+ *   * still allows replay via dedup-by-hash if a future analyzer wants it
+ *
+ * Schema (one JSONL line):
+ *   {
+ *     ts:          ISO-8601 with ms,
+ *     session_id:  string | null,
+ *     cycle:       string,                  // 'current' if not supplied
+ *     agent:       string,                  // calling agent name
+ *     tool:        string,                  // 'Bash' / 'Edit' / 'mcp__…'
+ *     args_hash:   16-char sha256 prefix of canonical-JSON args
+ *     result_hash: 16-char sha256 prefix of canonical-JSON result
+ *     latency_ms:  number,
+ *     status:      'ok' | 'error',
+ *   }
+ *
+ * Side effects:
+ *   * appendFileSync to the trajectory file (atomic per line on POSIX/NT)
+ *   * NEVER throws — IO failure logs to stderr and returns silently
+ *   * Optionally appends a `tool_call.completed` event to the
+ *     event-stream so live subscribers can see the same call without
+ *     scanning trajectory files. Skipped if `event_stream` arg is null.
+ */
+
+'use strict';
+
+const { appendFileSync, mkdirSync } = require('node:fs');
+const { dirname, isAbsolute, join, resolve } = require('node:path');
+const { createHash } = require('node:crypto');
+
+const DEFAULT_TRAJECTORY_DIR = '.design/telemetry/trajectories';
+
+/**
+ * Compute a stable 16-char sha256-hex prefix for arbitrary JSON-shaped
+ * input. Falls back to `'0'.repeat(16)` if `JSON.stringify` throws.
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+function hashOf(value) {
+  let serialized;
+  try {
+    serialized = JSON.stringify(value ?? null);
+  } catch {
+    return '0'.repeat(16);
+  }
+  return createHash('sha256').update(serialized ?? '').digest('hex').slice(0, 16);
+}
+
+/**
+ * Resolve the on-disk trajectory file for `cycle` against `baseDir`.
+ *
+ * @param {{baseDir?: string, cycle?: string, dir?: string}} [opts]
+ * @returns {string}
+ */
+function trajectoryPath(opts = {}) {
+  const baseDir = opts.baseDir ?? process.cwd();
+  const dir = opts.dir ?? DEFAULT_TRAJECTORY_DIR;
+  const cycle = (opts.cycle ?? 'current').replace(/[^A-Za-z0-9._-]/g, '_');
+  const resolvedDir = isAbsolute(dir) ? dir : resolve(baseDir, dir);
+  return join(resolvedDir, `${cycle}.jsonl`);
+}
+
+/**
+ * Append one trajectory record. Returns the recorded line for tests
+ * that want to assert on shape without re-reading the file.
+ *
+ * @param {{
+ *   cycle?: string,
+ *   session_id?: string | null,
+ *   agent: string,
+ *   tool: string,
+ *   args?: unknown,
+ *   result?: unknown,
+ *   latency_ms?: number,
+ *   status?: 'ok' | 'error',
+ *   baseDir?: string,
+ *   path?: string,
+ * }} call
+ * @returns {string} the JSONL line that was appended (without trailing \n)
+ */
+function recordCall(call) {
+  const ts = new Date().toISOString();
+  const record = {
+    ts,
+    session_id: call.session_id ?? null,
+    cycle: call.cycle ?? 'current',
+    agent: call.agent,
+    tool: call.tool,
+    args_hash: hashOf(call.args),
+    result_hash: hashOf(call.result),
+    latency_ms: typeof call.latency_ms === 'number' ? call.latency_ms : 0,
+    status: call.status ?? 'ok',
+  };
+
+  const path = call.path ?? trajectoryPath({ baseDir: call.baseDir, cycle: record.cycle });
+  const line = JSON.stringify(record);
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    appendFileSync(path, line + '\n', { flag: 'a' });
+  } catch (err) {
+    try {
+      process.stderr.write(
+        `[trajectory] write failed: ${err && err.message ? err.message : String(err)}\n`,
+      );
+    } catch {
+      /* swallow */
+    }
+  }
+  return line;
+}
+
+module.exports = {
+  recordCall,
+  trajectoryPath,
+  hashOf,
+  DEFAULT_TRAJECTORY_DIR,
+};