@tekyzinc/gsd-t 3.29.11 → 4.0.12

package/templates/workflows/_lib.js

@@ -0,0 +1,176 @@
+// templates/workflows/_lib.js
+// Shared helpers for GSD-T Workflow scripts. CommonJS, zero deps.
+//
+// Workflow scripts call these helpers from inside agent()/parallel()/pipeline()
+// stages so the brains (file-disjointness prover, brief generator, preflight,
+// verify-gate) stay invocable while the orchestration shell becomes a Workflow.
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+// 4.8-audit fix: prefer project-local bin/<tool>.cjs when present, fall back to
+// global `gsd-t` PATH binary. Preserves M55-D5 project-local-bin invariant: a
+// detached/sandboxed Workflow worker no longer requires `gsd-t` on PATH.
+//
+// Returns { cmd, args, source: "local" | "global" }.
+function _resolveTool(projectDir, subcommand, subcommandArgs, localBinName) {
+  if (localBinName) {
+    const local = path.join(projectDir, "bin", localBinName);
+    if (fs.existsSync(local)) {
+      return {
+        cmd: process.execPath,
+        args: [local, ...subcommandArgs],
+        source: "local",
+      };
+    }
+  }
+  return { cmd: "gsd-t", args: [subcommand, ...subcommandArgs], source: "global" };
+}
+
+function readBrief(briefPath) {
+  if (!briefPath || !fs.existsSync(briefPath)) {
+    return { _missing: true, briefPath: briefPath || null };
+  }
+  try {
+    return JSON.parse(fs.readFileSync(briefPath, "utf8"));
+  } catch (e) {
+    return { _missing: true, error: String(e && e.message) };
+  }
+}
+
+function generateBrief({ kind, milestone, domain, task, spawnId, projectDir = "." } = {}) {
+  const id =
+    spawnId ||
+    `${kind || "generic"}-${Date.now().toString(36)}-${Math.floor(Math.random() * 1e6).toString(36)}`;
+  const outDir = path.join(projectDir, ".gsd-t", "briefs");
+  fs.mkdirSync(outDir, { recursive: true });
+  const out = path.join(outDir, `${id}.json`);
+  const args = [
+    "brief",
+    "--kind",
+    kind || "execute",
+    "--spawn-id",
+    id,
+    "--out",
+    out,
+  ];
+  if (milestone) args.push("--milestone", milestone);
+  if (domain) args.push("--domain", domain);
+  if (task) args.push("--task", task);
+  const t = _resolveTool(projectDir, "brief", args, "gsd-t-context-brief.cjs");
+  const r = spawnSync(t.cmd, t.args, { cwd: projectDir, stdio: "pipe" });
+  if (r.status !== 0) {
+    return {
+      ok: false,
+      briefPath: out,
+      stderr: r.stderr && r.stderr.toString(),
+      spawnError: r.error ? String(r.error.message) : null,
+      via: t.source,
+    };
+  }
+  return { ok: true, briefPath: out, via: t.source };
+}
+
+function runPreflight({ projectDir = ".", checks } = {}) {
+  const subArgs = ["--json"];
+  if (Array.isArray(checks) && checks.length) subArgs.push("--checks", checks.join(","));
+  const t = _resolveTool(projectDir, "preflight", subArgs, "cli-preflight.cjs");
+  const r = spawnSync(t.cmd, t.args, { cwd: projectDir, stdio: "pipe" });
+  const stdout = r.stdout ? r.stdout.toString() : "";
+  let envelope = null;
+  try {
+    envelope = stdout ? JSON.parse(stdout) : null;
+  } catch (_) {
+    envelope = null;
+  }
+  return {
+    ok: r.status === 0,
+    exitCode: r.status,
+    envelope,
+    stderr: r.stderr && r.stderr.toString(),
+    spawnError: r.error ? String(r.error.message) : null,
+    via: t.source,
+  };
+}
+
+function proveFileDisjointness({ projectDir = ".", domains, taskIds } = {}) {
+  // Shells out to `gsd-t parallel --dry-run` (or project-local equivalent).
+  // 4.8-audit: domains array preferred over taskIds (the CLI supports --domain
+  // but not --tasks). taskIds kept for back-compat but logged as no-op.
+  const subArgs = ["--dry-run"];
+  if (Array.isArray(domains) && domains.length) {
+    for (const d of domains) subArgs.push("--domain", d);
+  }
+  const t = _resolveTool(projectDir, "parallel", subArgs, "gsd-t-parallel.cjs");
+  const r = spawnSync(t.cmd, t.args, { cwd: projectDir, stdio: "pipe" });
+  return {
+    ok: r.status === 0,
+    exitCode: r.status,
+    stdout: r.stdout && r.stdout.toString(),
+    stderr: r.stderr && r.stderr.toString(),
+    spawnError: r.error ? String(r.error.message) : null,
+    via: t.source,
+  };
+}
+
+function runVerifyGate({ projectDir = ".", skipTrack1, skipTrack2 } = {}) {
+  const subArgs = ["--json"];
+  if (skipTrack1) subArgs.push("--skip-track1");
+  if (skipTrack2) subArgs.push("--skip-track2");
+  const t = _resolveTool(projectDir, "verify-gate", subArgs, "gsd-t-verify-gate.cjs");
+  const r = spawnSync(t.cmd, t.args, { cwd: projectDir, stdio: "pipe" });
+  let envelope = null;
+  try {
+    envelope = r.stdout ? JSON.parse(r.stdout.toString()) : null;
+  } catch (_) {
+    envelope = null;
+  }
+  return {
+    ok: r.status === 0,
+    exitCode: r.status,
+    envelope,
+    stderr: r.stderr && r.stderr.toString(),
+    spawnError: r.error ? String(r.error.message) : null,
+    via: t.source,
+  };
+}
+
+function loadProtocol(name) {
+  // name = "qa" | "red-team" | "design-verify"
+  const validNames = ["qa", "red-team", "design-verify"];
+  if (!validNames.includes(name)) {
+    throw new Error(
+      `loadProtocol: unknown protocol ${JSON.stringify(name)}. Valid: ${validNames.join(", ")}`
+    );
+  }
+  const fp = path.join(__dirname, "..", "prompts", `${name}-subagent.md`);
+  return fs.readFileSync(fp, "utf8");
+}
+
+function readDomainTasks({ projectDir = ".", domain } = {}) {
+  if (!domain) throw new Error("readDomainTasks: domain required");
+  const fp = path.join(projectDir, ".gsd-t", "domains", domain, "tasks.md");
+  if (!fs.existsSync(fp)) return null;
+  return fs.readFileSync(fp, "utf8");
+}
+
+function readScope({ projectDir = ".", domain } = {}) {
+  if (!domain) throw new Error("readScope: domain required");
+  const fp = path.join(projectDir, ".gsd-t", "domains", domain, "scope.md");
+  if (!fs.existsSync(fp)) return null;
+  return fs.readFileSync(fp, "utf8");
+}
+
+module.exports = {
+  readBrief,
+  generateBrief,
+  runPreflight,
+  proveFileDisjointness,
+  runVerifyGate,
+  loadProtocol,
+  readDomainTasks,
+  readScope,
+};

package/templates/workflows/gsd-t-debug.workflow.js

@@ -0,0 +1,86 @@
+// templates/workflows/gsd-t-debug.workflow.js
+//
+// Runtime: Anthropic native Workflow tool only.
+// Debug phase — up to 2 fix cycles per CLAUDE.md Prime Rule. If still failing
+// after 2 cycles, exit with `needs-human` so the human operator can step in.
+//
+// args: { symptom, projectDir? }
+
+export const meta = {
+  name: "gsd-t-debug",
+  description: "Diagnose and fix a failing test or runtime error (up to 2 attempts)",
+  phases: [
+    { title: "Preflight",  detail: "preflight + brief" },
+    { title: "Cycle 1",    detail: "diagnose + propose + apply + verify" },
+    { title: "Cycle 2",    detail: "if cycle 1 didn't resolve" },
+  ],
+};
+
+const lib = require("./_lib.js");
+
+const projectDir = (args && args.projectDir) || ".";
+const symptom = (args && args.symptom) || null;
+
+const DEBUG_CYCLE_SCHEMA = {
+  type: "object",
+  required: ["resolved", "rootCause", "filesEdited"],
+  properties: {
+    resolved:     { type: "boolean" },
+    rootCause:    { type: "string" },
+    filesEdited:  { type: "array", items: { type: "string" } },
+    testRunResult: {
+      type: "object",
+      properties: { pass: { type: "integer" }, fail: { type: "integer" } },
+    },
+    nextStepsIfNotResolved: { type: "string" },
+  },
+};
+
+if (!symptom) {
+  log("debug: args.symptom required (description of failing test or error)");
+  return { status: "failed", reason: "no-symptom" };
+}
+
+phase("Preflight");
+const pre = lib.runPreflight({ projectDir });
+if (!pre.ok) return { status: "failed", reason: "preflight-failed", preflight: pre.envelope };
+const brief = lib.generateBrief({ kind: "execute", projectDir });
+
+let lastResult = null;
+for (let cycle = 1; cycle <= 2; cycle++) {
+  phase(`Cycle ${cycle}`);
+  const prompt = [
+    `Debug cycle ${cycle} of 2. Symptom: ${symptom}`,
+    `**Brief:** ${brief.briefPath || "(no brief)"}`,
+    cycle > 1 && lastResult
+      ? `\nPREVIOUS CYCLE'S ROOT CAUSE HYPOTHESIS (did not resolve the issue):\n${lastResult.rootCause}\nFiles edited: ${lastResult.filesEdited.join(", ")}\nIf the hypothesis was right, the fix was incomplete. If wrong, formulate a different hypothesis.`
+      : "",
+    ``,
+    `Steps: (1) read the relevant code, (2) form a hypothesis, (3) apply a fix, (4) run the affected test(s), (5) report.`,
+    `Commit the fix with prefix "m61(debug-cycle${cycle})".`,
+    `Return JSON per the schema.`,
+  ].filter(Boolean).join("\n");
+
+  lastResult = await agent(prompt, {
+    label: `debug-cycle-${cycle}`,
+    phase: `Cycle ${cycle}`,
+    schema: DEBUG_CYCLE_SCHEMA,
+    model: "opus",
+  }).catch((e) => ({
+    resolved: false,
+    rootCause: `agent error: ${e && e.message}`,
+    filesEdited: [],
+    nextStepsIfNotResolved: "agent threw — investigate directly",
+  }));
+
+  if (lastResult.resolved) {
+    return { status: "complete", cyclesUsed: cycle, finalResult: lastResult };
+  }
+}
+
+return {
+  status: "needs-human",
+  cyclesUsed: 2,
+  finalResult: lastResult,
+  nextSteps: lastResult.nextStepsIfNotResolved || "Two fix cycles exhausted; human review required.",
+};

package/templates/workflows/gsd-t-execute.workflow.js

@@ -0,0 +1,206 @@
+// templates/workflows/gsd-t-execute.workflow.js
+//
+// IMPORTANT: this file is NOT executable via `node` directly. It is a script
+// body for the Anthropic native Workflow tool, which wraps the body in an
+// async runtime and exposes globals: agent(), parallel(), pipeline(), log(),
+// phase(), budget, args. Top-level await + return are runtime-legal in that
+// context. To run: invoke the Workflow tool with {script: this file contents,
+// args: {milestone, domains, projectDir?}}.
+//
+// Canonical native-Workflow implementation of the GSD-T execute phase.
+// Replaces the orchestrator/worker/parallel/spawn-plan scaffolding with a
+// single deterministic Workflow script. KEEPS the brains: preflight,
+// context-brief, file-disjointness, verify-gate — all invoked from inside
+// stages via templates/workflows/_lib.js helpers.
+//
+// Invocation contract:
+//   The Workflow tool reads this file's `meta` block and runs the script
+//   body. `args` is the JSON object passed in via Workflow({args}). Expected
+//   shape:
+//     {
+//       milestone: "M61",
+//       domains:   ["m61-d6-migrate-orchestration-to-workflow", ...],
+//       projectDir: ".",    // optional
+//     }
+
+export const meta = {
+  name: "gsd-t-execute",
+  description:
+    "Run a GSD-T execute phase: preflight → brief → parallel domain workers → integrate barrier → verify-gate",
+  phases: [
+    { title: "Preflight",    detail: "gsd-t preflight + brief generation" },
+    { title: "Disjointness", detail: "prove tasks are file-disjoint" },
+    { title: "Domains",      detail: "parallel domain workers" },
+    { title: "Integrate",    detail: "cross-domain wire-up" },
+    { title: "Verify-Gate",  detail: "two-track verify-gate" },
+  ],
+};
+
+// ───── Shared schemas (re-used across stages) ───────────────────────────────
+
+const DOMAIN_RESULT_SCHEMA = {
+  type: "object",
+  required: ["domain", "status", "filesTouched"],
+  additionalProperties: false,
+  properties: {
+    domain:       { type: "string" },
+    status:       { type: "string", enum: ["complete", "partial", "blocked", "failed"] },
+    filesTouched: { type: "array", items: { type: "string" } },
+    tasksDone:    { type: "array", items: { type: "string" } },
+    tasksBlocked: { type: "array", items: { type: "string" } },
+    notes:        { type: "string" },
+  },
+};
+
+const INTEGRATE_RESULT_SCHEMA = {
+  type: "object",
+  required: ["status", "crossDomainEdits"],
+  additionalProperties: false,
+  properties: {
+    status:           { type: "string", enum: ["green", "warnings", "failed"] },
+    crossDomainEdits: { type: "array", items: { type: "string" } },
+    notes:            { type: "string" },
+  },
+};
+
+// ───── Script body ──────────────────────────────────────────────────────────
+
+const lib = require("./_lib.js");
+const path = require("path");
+
+const projectDir = (args && args.projectDir) || ".";
+const milestone  = (args && args.milestone)  || null;
+const domains    = (args && Array.isArray(args.domains) && args.domains) || [];
+
+if (!milestone) {
+  log("execute: no milestone provided — args.milestone is required");
+  return { status: "failed", reason: "missing-milestone" };
+}
+if (!domains.length) {
+  log("execute: no domains — args.domains is required (non-empty list)");
+  return { status: "failed", reason: "no-domains" };
+}
+
+phase("Preflight");
+log(`execute: milestone=${milestone}, domains=${domains.length}`);
+const pre = lib.runPreflight({ projectDir });
+if (!pre.ok) {
+  log(`preflight FAIL — exitCode=${pre.exitCode}: ${pre.stderr || "(no stderr)"}`);
+  return { status: "failed", reason: "preflight-failed", preflight: pre.envelope };
+}
+log(`preflight OK`);
+
+phase("Disjointness");
+// 4.8-audit fix: scope disjointness to the requested domain set, not the whole project.
+// Without this, an unrelated DRAFT domain elsewhere in the project could flip the result.
+const disj = lib.proveFileDisjointness({ projectDir, domains });
+if (!disj.ok) {
+  log(`disjointness FAIL — exitCode=${disj.exitCode}: ${disj.stderr || disj.stdout}`);
+  return { status: "failed", reason: "non-disjoint" };
+}
+log(`disjointness OK`);
+
+phase("Domains");
+const domainResults = await parallel(
+  domains.map((domain) => async () => {
+    // 4.8-audit fix: per-domain brief (M55-D2 brief-per-spawn semantic) — each worker
+    // gets a brief scoped to its own domain so grep-the-brief is most effective.
+    const domBrief = lib.generateBrief({ kind: "execute", milestone, domain, projectDir });
+    const briefRef = domBrief.ok
+      ? domBrief.briefPath
+      : "(brief generation failed — re-walk repo)";
+
+    // 4.8-audit fix: do NOT truncate scope/tasks. The worker is being told to "execute
+    // every task" — silently dropping tail content is a correctness regression. Briefs
+    // are the compression layer; raw scope/tasks must pass whole.
+    const scope = lib.readScope({ projectDir, domain }) || "(scope.md missing)";
+    const tasks = lib.readDomainTasks({ projectDir, domain }) || "(tasks.md missing)";
+    const prompt = [
+      `You are the worker agent for the GSD-T domain \`${domain}\` in milestone \`${milestone}\`.`,
+      ``,
+      `Your job: execute every task listed under "## Tasks" in this domain's tasks.md, respecting the file ownership in scope.md.`,
+      ``,
+      `**Brief (REQUIRED READ):** ${briefRef} — if present, grep this JSON first instead of re-reading CLAUDE.md and contracts.`,
+      ``,
+      `**Scope (your owned files):**`,
+      "```",
+      scope,
+      "```",
+      ``,
+      `**Tasks:**`,
+      "```",
+      tasks,
+      "```",
+      ``,
+      `Constraints:`,
+      `- Touch only files in your scope's "Owned Files" list.`,
+      `- Make commits via bash/git tools FIRST as you complete each task or task group, THEN emit the final StructuredOutput JSON describing what you did. Do not skip commits to satisfy the schema faster.`,
+      `- Update affected docs (progress.md Decision Log, architecture.md, contracts/, requirements.md, README.md) per the Document Ripple Completion Gate in CLAUDE.md — in the SAME commits as the code changes.`,
+      `- If a task is blocked (dependency not met), record it in tasksBlocked and continue with the next.`,
+      `- Return a JSON object matching the StructuredOutput schema. The "status" field is the OVERALL domain status: "complete" if all tasks done, "partial" if some done and some blocked, "blocked" if you couldn't start, "failed" on error.`,
+    ].join("\n");
+
+    try {
+      return await agent(prompt, {
+        label: `worker:${domain}`,
+        phase: "Domains",
+        model: "sonnet",  // 4.8-audit fix: explicit per Model Display contract
+        schema: DOMAIN_RESULT_SCHEMA,
+      });
+    } catch (e) {
+      return {
+        domain,
+        status: "failed",
+        filesTouched: [],
+        notes: `agent error: ${e && e.message}`,
+      };
+    }
+  })
+);
+
+const blocking = domainResults.filter(Boolean).filter((r) => r.status === "failed");
+if (blocking.length) {
+  log(`${blocking.length} domain(s) failed — halting before integrate`);
+  return { status: "failed", reason: "domain-failed", domainResults };
+}
+
+phase("Integrate");
+const integratePrompt = [
+  `You are the integration agent. ${domainResults.length} domain workers have completed.`,
+  ``,
+  `Domain results:`,
+  "```json",
+  JSON.stringify(domainResults, null, 2),
+  "```",
+  ``,
+  `Your job: perform any cross-domain wire-up needed (e.g. resolving shared-file edits sequenced at integrate, updating cross-domain contracts, running interleaved-touch resolution). DO NOT re-do work the domain workers already did. Make commits for the cross-domain edits only.`,
+  ``,
+  `Return a JSON object per the StructuredOutput schema. status="green" if all wiring landed cleanly, "warnings" if there are non-blocking issues, "failed" if cross-domain integration cannot complete.`,
+].join("\n");
+
+const integrate = await agent(integratePrompt, {
+  label: "integrate",
+  phase: "Integrate",
+  schema: INTEGRATE_RESULT_SCHEMA,
+}).catch((e) => ({
+  status: "failed",
+  crossDomainEdits: [],
+  notes: `integrate agent error: ${e && e.message}`,
+}));
+
+if (integrate.status === "failed") {
+  log("integrate FAILED — halting before verify-gate");
+  return { status: "failed", reason: "integrate-failed", domainResults, integrate };
+}
+
+phase("Verify-Gate");
+const vg = lib.runVerifyGate({ projectDir });
+log(`verify-gate exitCode=${vg.exitCode} ok=${vg.ok}`);
+
+return {
+  status: vg.ok ? "complete" : "verify-failed",
+  milestone,
+  domainResults,
+  integrate,
+  verifyGate: vg.envelope,
+};

package/templates/workflows/gsd-t-integrate.workflow.js

@@ -0,0 +1,71 @@
+// templates/workflows/gsd-t-integrate.workflow.js
+//
+// Runtime: Anthropic native Workflow tool only.
+// Integrate phase — runs after parallel domains have committed their work.
+// Cross-domain wire-up + lightweight verify-gate sanity check.
+//
+// args: { milestone, domains: [...], projectDir? }
+
+export const meta = {
+  name: "gsd-t-integrate",
+  description: "Cross-domain integration after parallel workers complete",
+  phases: [
+    { title: "Preflight",   detail: "preflight + brief" },
+    { title: "Integrate",   detail: "cross-domain wire-up" },
+    { title: "Verify-Gate", detail: "quick verify-gate" },
+  ],
+};
+
+const lib = require("./_lib.js");
+
+const projectDir = (args && args.projectDir) || ".";
+const milestone  = (args && args.milestone) || null;
+const domains    = (args && args.domains) || [];
+
+const INTEGRATE_SCHEMA = {
+  type: "object",
+  required: ["status", "crossDomainEdits"],
+  properties: {
+    status:           { type: "string", enum: ["green", "warnings", "failed"] },
+    crossDomainEdits: { type: "array", items: { type: "string" } },
+    notes:            { type: "string" },
+  },
+};
+
+if (!milestone || !domains.length) {
+  log("integrate: args.milestone and args.domains required");
+  return { status: "failed", reason: "missing-args" };
+}
+
+phase("Preflight");
+const pre = lib.runPreflight({ projectDir });
+if (!pre.ok) return { status: "failed", reason: "preflight-failed", preflight: pre.envelope };
+const brief = lib.generateBrief({ kind: "execute", milestone, projectDir });
+
+phase("Integrate");
+const integrate = await agent(
+  [
+    `You are the integration agent for milestone \`${milestone}\`. Domains complete: ${domains.join(", ")}.`,
+    `**Brief:** ${brief.briefPath || "(no brief — re-walk repo)"}`,
+    ``,
+    `Read .gsd-t/contracts/${milestone ? milestone.toLowerCase() : ""}-integration-points.md if present.`,
+    `Resolve any shared-file edits sequenced at integrate (per "Cross-Domain File Contention Matrix").`,
+    `Update cross-domain contracts as needed.`,
+    `Commit cross-domain edits with a clear "m61(integrate)" prefix.`,
+    ``,
+    `Return JSON per the schema.`,
+  ].join("\n"),
+  { label: "integrate", phase: "Integrate", schema: INTEGRATE_SCHEMA, model: "sonnet" }
+).catch((e) => ({ status: "failed", crossDomainEdits: [], notes: `agent error: ${e && e.message}` }));
+
+if (integrate.status === "failed") {
+  return { status: "failed", reason: "integrate-failed", integrate };
+}
+
+phase("Verify-Gate");
+const vg = lib.runVerifyGate({ projectDir });
+return {
+  status: vg.ok ? "complete" : "verify-failed",
+  integrate,
+  verifyGate: vg.envelope,
+};

package/templates/workflows/gsd-t-phase.workflow.js

@@ -0,0 +1,94 @@
+// templates/workflows/gsd-t-phase.workflow.js
+//
+// Runtime: Anthropic native Workflow tool only.
+// Generic upper-stage phase runner — covers partition, plan, discuss, impact,
+// milestone, prd, design-decompose, doc-ripple.
+//
+// Each upper-stage phase is essentially: load brief -> primary agent (with phase-
+// specific protocol) -> optional validation -> commit artifacts. Wrapping each
+// in its own Workflow script is overengineering; this generic runner takes the
+// phase name as an arg and threads the right brief kind + acceptance schema.
+//
+// args: {
+//   phase: "partition" | "plan" | "discuss" | "impact" | "milestone"
+//          | "prd" | "design-decompose" | "doc-ripple",
+//   milestone?: "M61",
+//   projectDir?: ".",
+//   userInput?: string,   // arbitrary input to the phase (e.g. "$ARGUMENTS")
+// }
+
+export const meta = {
+  name: "gsd-t-phase",
+  description: "Generic upper-stage phase runner (partition/plan/discuss/etc.)",
+  phases: [
+    { title: "Preflight", detail: "preflight + brief" },
+    { title: "Phase",     detail: "primary agent with phase-specific protocol" },
+  ],
+};
+
+const lib = require("./_lib.js");
+
+const VALID_PHASES = [
+  "partition", "plan", "discuss", "impact",
+  "milestone", "prd", "design-decompose", "doc-ripple",
+];
+
+const PHASE_RESULT_SCHEMA = {
+  type: "object",
+  required: ["status", "artifacts"],
+  additionalProperties: false,
+  properties: {
+    status:    { type: "string", enum: ["complete", "partial", "blocked", "failed"] },
+    artifacts: { type: "array", items: { type: "string" } },
+    summary:   { type: "string" },
+    decisions: { type: "array", items: { type: "string" } },
+  },
+};
+
+const projectDir = (args && args.projectDir) || ".";
+const milestone  = (args && args.milestone)  || null;
+const userInput  = (args && args.userInput)  || "";
+const phaseName  = args && args.phase;
+
+if (!phaseName || !VALID_PHASES.includes(phaseName)) {
+  log(`phase: args.phase must be one of: ${VALID_PHASES.join(", ")}`);
+  return { status: "failed", reason: "invalid-phase" };
+}
+
+phase("Preflight");
+const pre = lib.runPreflight({ projectDir });
+if (!pre.ok) return { status: "failed", reason: "preflight-failed", preflight: pre.envelope };
+const brief = lib.generateBrief({ kind: phaseName, milestone, projectDir });
+
+phase("Phase");
+const promptByPhase = {
+  partition: `Decompose the milestone into 2-5 independent domains. Write .gsd-t/domains/{domain}/{scope,constraints,tasks}.md. Cross-domain contracts in .gsd-t/contracts/.`,
+  plan: `For each domain, write atomic tasks.md entries with files, contract refs, dependencies, acceptance criteria. Update .gsd-t/contracts/integration-points.md with wave groupings.`,
+  discuss: `Multi-perspective exploration of design questions. Settle locked decisions into .gsd-t/CONTEXT.md. Do NOT implement.`,
+  impact: `Analyze downstream effects of proposed changes. Identify breaking changes, affected consumers, migration paths.`,
+  milestone: `Define a new milestone — origin, goal, success criteria, falsifiable acceptance. Append to .gsd-t/progress.md. Defer partition/plan.`,
+  prd: `Generate a product requirements doc at docs/prd.md. Functional + non-functional requirements traceable to acceptance criteria.`,
+  "design-decompose": `Decompose a design reference (Figma URL / images) into hierarchical contracts: elements -> widgets -> pages, each at .gsd-t/contracts/design/.`,
+  "doc-ripple": `Identify and update all docs affected by recent code changes per the Document Ripple Completion Gate. No code edits.`,
+};
+
+const result = await agent(
+  [
+    `You are the ${phaseName} phase agent.`,
+    milestone ? `Milestone: ${milestone}` : "",
+    `**Brief (REQUIRED):** ${brief.briefPath || "(no brief — re-walk repo)"}`,
+    userInput ? `\nUser input:\n${userInput}` : "",
+    ``,
+    `Objective: ${promptByPhase[phaseName]}`,
+    ``,
+    `Follow the CLAUDE.md Pre-Commit Gate. Commit artifacts with prefix "m61(${phaseName})" or similar.`,
+    `Return JSON per the schema.`,
+  ].filter(Boolean).join("\n"),
+  { label: phaseName, phase: "Phase", schema: PHASE_RESULT_SCHEMA, model: "opus" }
+).catch((e) => ({
+  status: "failed",
+  artifacts: [],
+  summary: `agent error: ${e && e.message}`,
+}));
+
+return result;