role-os 2.2.1 → 2.3.0

package/src/mission.mjs

@@ -327,6 +327,132 @@ export const MISSIONS = {
     dispatchDefaults: { model: "sonnet", maxTurns: 25, maxBudgetUsd: 3.0 },
     trialEvidence: "New mission — no trial evidence yet. Architecture designed 2026-03-27.",
   },
+
+  // ── Dogfood Swarm (Multi-Pass Health + Feature Convergence) ─────────────────
+  "dogfood-swarm": {
+    name: "Dogfood Swarm",
+    description: "Three-stage health pass (bug/security → proactive → humanization) then iterative feature pass with exclusive file ownership, build gates, and user checkpoints. Moves a repo from 'works' to 'production-ready.' Domain agent count scales with repo structure.",
+    pack: "swarm",
+    entryPath: "Generate swarm manifest → Save-point tag → Health-A wave (5 agents parallel, loop until 0 CRITICAL+HIGH) → Health-B wave (proactive, user review) → Health-C wave (humanization, loop) → Feature wave (user approval gate, loop) → Synthesizer → Critic verdict",
+    roleChain: [
+      "Swarm Coordinator",     // ×1 — orchestrates all stages, enforces gates
+      "Swarm Backend Agent",   // ×1 — exclusive ownership of backend files
+      "Swarm Bridge Agent",    // ×1 — exclusive ownership of bridge/integration files
+      "Swarm Tests Agent",     // ×1 — exclusive ownership of test files
+      "Swarm Infra Agent",     // ×1 — exclusive ownership of CI/config/docs
+      "Swarm Frontend Agent",  // ×1 — exclusive ownership of frontend files
+      "Swarm Synthesizer",     // ×1 — final verification report
+      "Critic Reviewer",       // ×1 — final acceptance
+    ],
+    // Dynamic dispatch contract:
+    // swarm-manifest.json defines domains[] with non-overlapping file paths.
+    // Each domain maps to one of the 5 domain agent roles.
+    // Domains are instantiated per stage (health-a, health-b, health-c, feature).
+    // Coordinator gates between stages evaluate exit conditions.
+    dynamicDispatch: {
+      scalingRoles: ["Swarm Backend Agent", "Swarm Bridge Agent", "Swarm Tests Agent", "Swarm Infra Agent", "Swarm Frontend Agent"],
+      manifestSource: "swarm-manifest.json",
+      domainAgentPer: "domains",
+      coordinatorAfter: "each-stage",
+      synthesisAfter: "all-stages",
+    },
+    // Wave loops — iterative convergence (new primitive, unique to swarm)
+    waveLoops: [
+      {
+        stage: "health-a",
+        lens: "Bug/Security Fix — audit for bugs, security, quality, types, test coverage, doc accuracy",
+        exitCondition: "0 CRITICAL + 0 HIGH findings open",
+        maxIterations: 4,
+        buildGate: true,
+        userApproval: false,
+      },
+      {
+        stage: "health-b",
+        lens: "Proactive Health — defensive coding, observability, graceful degradation, future-proofing",
+        exitCondition: "user approves proactive findings",
+        maxIterations: 2,
+        buildGate: true,
+        userApproval: true,
+      },
+      {
+        stage: "health-c",
+        lens: "Humanization — error messages that help users fix problems, reconnection/retry feedback, responsive layouts, loading states, state persistence, accessibility",
+        exitCondition: "0 CRITICAL + 0 HIGH humanization findings open",
+        maxIterations: 3,
+        buildGate: true,
+        userApproval: false,
+      },
+      {
+        stage: "feature",
+        lens: "Feature Audit — missing capabilities, feature gaps, UX, production readiness",
+        exitCondition: "user approves feature audit + 0 CRITICAL feature gaps",
+        maxIterations: 5,
+        buildGate: true,
+        userApproval: true,
+      },
+    ],
+    // Exclusive ownership — domain file boundaries (new primitive, unique to swarm)
+    exclusiveOwnership: {
+      mode: "strict",
+      manifestSource: "swarm-manifest.json",
+      maxAgentsPerWave: 5,
+    },
+    artifactFlow: [
+      // Health-A: Bug/Security audit + remediate (loops)
+      { role: "Swarm Backend Agent",  produces: "wave-report",        consumedBy: "Swarm Coordinator", stage: "health-a" },
+      { role: "Swarm Bridge Agent",   produces: "wave-report",        consumedBy: "Swarm Coordinator", stage: "health-a" },
+      { role: "Swarm Tests Agent",    produces: "wave-report",        consumedBy: "Swarm Coordinator", stage: "health-a" },
+      { role: "Swarm Infra Agent",    produces: "wave-report",        consumedBy: "Swarm Coordinator", stage: "health-a" },
+      { role: "Swarm Frontend Agent", produces: "wave-report",        consumedBy: "Swarm Coordinator", stage: "health-a" },
+      { role: "Swarm Coordinator",    produces: "swarm-gate",         consumedBy: "Swarm Backend Agent", stage: "health-a" },
+
+      // Health-B: Proactive hardening (user review gate)
+      { role: "Swarm Backend Agent",  produces: "wave-report",        consumedBy: "Swarm Coordinator", stage: "health-b" },
+      { role: "Swarm Bridge Agent",   produces: "wave-report",        consumedBy: "Swarm Coordinator", stage: "health-b" },
+      { role: "Swarm Tests Agent",    produces: "wave-report",        consumedBy: "Swarm Coordinator", stage: "health-b" },
+      { role: "Swarm Infra Agent",    produces: "wave-report",        consumedBy: "Swarm Coordinator", stage: "health-b" },
+      { role: "Swarm Frontend Agent", produces: "wave-report",        consumedBy: "Swarm Coordinator", stage: "health-b" },
+      { role: "Swarm Coordinator",    produces: "swarm-gate",         consumedBy: "Swarm Backend Agent", stage: "health-b" },
+
+      // Health-C: Humanization (UX emphasis, loops)
+      { role: "Swarm Backend Agent",  produces: "wave-report",        consumedBy: "Swarm Coordinator", stage: "health-c" },
+      { role: "Swarm Bridge Agent",   produces: "wave-report",        consumedBy: "Swarm Coordinator", stage: "health-c" },
+      { role: "Swarm Tests Agent",    produces: "wave-report",        consumedBy: "Swarm Coordinator", stage: "health-c" },
+      { role: "Swarm Infra Agent",    produces: "wave-report",        consumedBy: "Swarm Coordinator", stage: "health-c" },
+      { role: "Swarm Frontend Agent", produces: "wave-report",        consumedBy: "Swarm Coordinator", stage: "health-c" },
+      { role: "Swarm Coordinator",    produces: "swarm-gate",         consumedBy: "Swarm Backend Agent", stage: "health-c" },
+
+      // Feature: Audit → user approval → execute (loops)
+      { role: "Swarm Backend Agent",  produces: "wave-report",        consumedBy: "Swarm Coordinator", stage: "feature" },
+      { role: "Swarm Bridge Agent",   produces: "wave-report",        consumedBy: "Swarm Coordinator", stage: "feature" },
+      { role: "Swarm Tests Agent",    produces: "wave-report",        consumedBy: "Swarm Coordinator", stage: "feature" },
+      { role: "Swarm Infra Agent",    produces: "wave-report",        consumedBy: "Swarm Coordinator", stage: "feature" },
+      { role: "Swarm Frontend Agent", produces: "wave-report",        consumedBy: "Swarm Coordinator", stage: "feature" },
+      { role: "Swarm Coordinator",    produces: "swarm-gate",         consumedBy: "Swarm Synthesizer", stage: "feature" },
+
+      // Final: Synthesize + Critic verdict
+      { role: "Swarm Synthesizer",    produces: "swarm-final-report", consumedBy: "Critic Reviewer",   stage: "final" },
+      { role: "Critic Reviewer",      produces: "review-verdict",     consumedBy: null,                 stage: "final" },
+    ],
+    escalationBranches: [
+      { trigger: "build gate fails after remediation", from: "Swarm Coordinator", to: "Swarm Coordinator", action: "halt stage, report which agent's changes broke the build" },
+      { trigger: "domain agent touches files outside its assignment", from: "Swarm Coordinator", to: "Swarm Coordinator", action: "reject wave-report, re-run agent with strict boundary warning" },
+      { trigger: "finding spans multiple domains", from: "Swarm Coordinator", to: "Swarm Coordinator", action: "assign to the domain with most file overlap, note cross-domain in finding" },
+      { trigger: "health pass stuck at max iterations", from: "Swarm Coordinator", to: "Swarm Synthesizer", action: "synthesize with partial health — document remaining CRITICAL/HIGH" },
+      { trigger: "feature audit finds no gaps", from: "Swarm Coordinator", to: "Swarm Synthesizer", action: "skip feature execution, advance to final synthesis" },
+      { trigger: "user rejects feature audit", from: "Swarm Coordinator", to: "Swarm Coordinator", action: "re-scope feature audit with user feedback, re-run" },
+    ],
+    honestPartial: "One or more health stages complete but feature pass blocked or incomplete. Per-stage findings are individually valid and actionable. Manifest and wave reports exist even if synthesis does not. Build gate status is known.",
+    stopConditions: [
+      "All four stages converge — Synthesizer produces final report, Critic accepts",
+      "Health pass stuck after max iterations — synthesize with partial health findings",
+      "Feature pass stuck after max iterations — synthesize with partial feature progress",
+      "Build gate fails repeatedly — stop and report infrastructure issue",
+      "User halts swarm — synthesize from completed stages",
+    ],
+    dispatchDefaults: { model: "sonnet", maxTurns: 40, maxBudgetUsd: 6.0 },
+    trialEvidence: "Proven on claude-collaborate (2026-03-28): 35→129 tests, 106 health findings fixed, v1.1.0 shipped. Protocol v2.0.",
+  },
 };
 
 // ── Mission catalog ─────────────────────────────────────────────────────────
@@ -395,6 +521,10 @@ export function suggestMission(taskDescription) {
       signals: ["deep audit", "component audit", "decompose and audit", "audit components", "structural audit", "deep review", "code audit", "repo deep dive"],
       weight: 1.2,
     },
+    "dogfood-swarm": {
+      signals: ["dogfood swarm", "swarm", "health pass", "multi-pass", "convergence", "full quality pass", "production ready", "wave-based audit", "swarm this repo"],
+      weight: 1.3,
+    },
   };
 
   let bestKey = null;

package/src/packs.mjs

@@ -323,6 +323,42 @@ export const TEAM_PACKS = {
       { notForSignals: ["handbook", "documentation", "restructure docs"], suggestInstead: "docs", reason: "This is docs work, not a brainstorm" },
     ],
   },
+
+  // ── Dogfood Swarm (Multi-Pass Health + Feature Convergence) ─────────────────
+  swarm: {
+    name: "Dogfood Swarm (Multi-Pass Convergence)",
+    description: "Three-stage health pass (bug/security → proactive → humanization) then iterative feature pass, all with exclusive file ownership, build gates, and user checkpoints. Moves a repo from 'works' to 'production-ready.'",
+    roles: [
+      "Swarm Coordinator",
+      "Swarm Backend Agent",
+      "Swarm Bridge Agent",
+      "Swarm Tests Agent",
+      "Swarm Infra Agent",
+      "Swarm Frontend Agent",
+      "Swarm Synthesizer",
+      "Critic Reviewer",
+    ],
+    orchestratorRequired: false,
+    optionalRoles: [],
+    chainOrder: "Coordinator → [5 domain agents parallel] → Coordinator gate (repeat per stage: health-a, health-b, health-c, feature) → Synthesizer → Critic Reviewer",
+    requiredArtifacts: ["swarm-gate", "wave-report", "swarm-final-report", "review-verdict"],
+    stopConditions: [
+      "All four stages converge — Synthesizer produces final report, Critic accepts",
+      "Health pass stuck after max iterations — synthesize with partial health findings",
+      "Feature pass stuck after max iterations — synthesize with partial feature progress",
+      "Build gate fails repeatedly — stop and report infrastructure issue",
+    ],
+    escalationOwner: "Swarm Coordinator",
+    dispatchDefaults: { model: "sonnet", maxTurns: 40, maxBudgetUsd: 6.0 },
+    trialEvidence: "Proven on claude-collaborate (2026-03-28): 35→129 tests, 106 health findings fixed, v1.1.0 shipped. Protocol v2.0.",
+    mismatchGuards: [
+      { notForSignals: ["fix bug", "single bug", "one crash", "quick fix"], suggestInstead: "bugfix", reason: "This is a single bug to fix, not a full swarm" },
+      { notForSignals: ["brainstorm", "explore ideas", "concept", "ideate"], suggestInstead: "brainstorm", reason: "This is exploration, not convergence work" },
+      { notForSignals: ["research", "competitive analysis", "user research"], suggestInstead: "research", reason: "This is research, not repo health work" },
+      { notForSignals: ["launch", "announce", "release notes", "go-to-market"], suggestInstead: "launch", reason: "This is launch work, not repo health" },
+      { notForSignals: ["handbook", "documentation only", "restructure docs"], suggestInstead: "docs", reason: "This is docs work — swarm is for full repo convergence" },
+    ],
+  },
 };
 
 // ── Pack selection ────────────────────────────────────────────────────────────
@@ -337,6 +373,7 @@ const PACK_KEYWORDS = {
   treatment: ["treatment", "polish", "cleanup", "repo audit", "shipcheck", "full treatment"],
   brainstorm: ["brainstorm", "explore", "ideate", "divergent", "opportunity", "creative directions", "concept exploration", "what could", "possibilities"],
   "deep-audit": ["deep audit", "component audit", "repo audit deep", "decompose and audit", "audit components", "code audit", "structural audit", "deep review"],
+  swarm: ["swarm", "dogfood", "health pass", "multi-pass", "convergence", "wave", "full quality", "production ready", "dogfood swarm"],
 };
 
 /**

package/src/route.mjs

@@ -374,6 +374,57 @@ export const ROLE_CATALOG = [
     excludeWhen: ["component audit still running", "no findings to synthesize"],
     deliverableAffinity: ["Review"],
   },
+
+  // ── Dogfood Swarm (Multi-Pass Health + Feature Convergence) ─────────────────
+  {
+    name: "Swarm Coordinator", pack: "swarm", phase: 0,
+    keywords: ["swarm", "wave", "gate", "convergence", "health pass", "dogfood"],
+    triggers: ["dogfood swarm", "swarm coordinator", "wave orchestration", "health gate"],
+    excludeWhen: ["single bug fix", "brainstorm only", "docs only"],
+    deliverableAffinity: ["Review"],
+  },
+  {
+    name: "Swarm Backend Agent", pack: "swarm", phase: 3,
+    keywords: ["backend", "server", "core logic", "api", "database", "service"],
+    triggers: ["swarm backend", "backend audit and fix", "server health"],
+    excludeWhen: ["frontend only", "docs only", "test only"],
+    deliverableAffinity: ["Code", "Review"],
+  },
+  {
+    name: "Swarm Bridge Agent", pack: "swarm", phase: 3,
+    keywords: ["bridge", "integration", "websocket", "middleware", "adapter", "protocol"],
+    triggers: ["swarm bridge", "bridge audit and fix", "integration health"],
+    excludeWhen: ["no secondary services", "single module repo"],
+    deliverableAffinity: ["Code", "Review"],
+  },
+  {
+    name: "Swarm Tests Agent", pack: "swarm", phase: 3,
+    keywords: ["test", "coverage", "fixture", "mock", "assertion", "spec"],
+    triggers: ["swarm tests", "test audit and fix", "test health"],
+    excludeWhen: ["no test suite", "implementation only"],
+    deliverableAffinity: ["Test", "Review"],
+  },
+  {
+    name: "Swarm Infra Agent", pack: "swarm", phase: 3,
+    keywords: ["ci", "workflow", "config", "docs", "readme", "changelog", "infrastructure"],
+    triggers: ["swarm infra", "infra audit and fix", "ci health", "docs health"],
+    excludeWhen: ["code only", "no ci"],
+    deliverableAffinity: ["Review"],
+  },
+  {
+    name: "Swarm Frontend Agent", pack: "swarm", phase: 3,
+    keywords: ["frontend", "ui", "component", "css", "html", "react", "view"],
+    triggers: ["swarm frontend", "frontend audit and fix", "ui health"],
+    excludeWhen: ["no frontend", "cli only", "backend only"],
+    deliverableAffinity: ["Code", "Review"],
+  },
+  {
+    name: "Swarm Synthesizer", pack: "swarm", phase: 5,
+    keywords: ["synthesis", "final report", "verification", "summary", "recommendation"],
+    triggers: ["swarm synthesis", "swarm final report", "swarm verification"],
+    excludeWhen: ["swarm still running", "no wave results"],
+    deliverableAffinity: ["Review"],
+  },
 ];
 
 // ── Deliverable type → role affinity ──────────────────────────────────────────

package/src/run-cmd.mjs

@@ -109,13 +109,16 @@ export async function runCommand(args) {
   // Strip flags from task description
   const taskText = args.filter(a => !a.startsWith("--")).join(" ");
 
-  const run = createPersistentRun(taskText, cwd, opts);
+  const run = await createPersistentRun(taskText, cwd, opts);
 
   console.log(`Created run: ${run.id}`);
   console.log(`Entry: ${run.entryLevel.toUpperCase()}`);
   if (run.missionKey) console.log(`Mission: ${run.missionKey}`);
   if (run.packKey) console.log(`Pack: ${run.packKey}`);
   console.log(`Steps: ${run.steps.length}`);
+  if (run.knowledge) {
+    console.log(`Knowledge: ${run.knowledge.status} (${run.knowledge.retrieval_bundle?.selected?.length ?? 0} chunks)`);
+  }
   console.log("");
 
   // Auto-start the first step

package/src/run.mjs

@@ -19,6 +19,7 @@ import { getMission } from "./mission.mjs";
 import { TEAM_PACKS, getPack } from "./packs.mjs";
 import { ROLE_CATALOG } from "./route.mjs";
 import { ROLE_ARTIFACT_CONTRACTS, validateArtifact, getHandoffContract } from "./artifacts.mjs";
+import { retrieveForDispatch, isKnowledgeConfigured } from "./knowledge/index.mjs";
 
 // ── Run directory ────────────────────────────────────────────────────────────
 
@@ -88,7 +89,7 @@ let _counter = 0;
  * @param {string} [opts.forcePack] - force a specific pack key
  * @returns {PersistentRun}
  */
-export function createPersistentRun(taskDescription, cwd, opts = {}) {
+export async function createPersistentRun(taskDescription, cwd, opts = {}) {
   if (!taskDescription || !taskDescription.trim()) {
     throw new Error("Task description required");
   }
@@ -125,6 +126,26 @@ export function createPersistentRun(taskDescription, cwd, opts = {}) {
 
   const id = `run-${Date.now()}-${++_counter}`;
 
+  // Knowledge retrieval — automatic when corpus is configured
+  let knowledge = null;
+  if (isKnowledgeConfigured()) {
+    // Retrieve for the primary role in the chain (first step's role)
+    const primaryRole = steps[0]?.role;
+    if (primaryRole) {
+      try {
+        const roleId = primaryRole.toLowerCase().replace(/\s+/g, "-");
+        const result = await retrieveForDispatch({
+          roleId,
+          taskText: taskDescription.trim(),
+        });
+        knowledge = { retrieval_bundle: result.bundle, status: result.status };
+      } catch (e) {
+        // Retrieval failure is non-fatal — run proceeds without knowledge
+        knowledge = null;
+      }
+    }
+  }
+
   const run = {
     id,
     taskDescription: taskDescription.trim(),
@@ -140,6 +161,7 @@ export function createPersistentRun(taskDescription, cwd, opts = {}) {
     pausedAt: null,
     completedAt: null,
     completionReport: null,
+    knowledge,
   };
 
   // Persist
@@ -789,6 +811,13 @@ export function generateReport(run) {
     artifactChain: artifacts,
     escalationCount: run.escalations.length,
     interventionCount: run.interventions.length,
+    knowledge: run.knowledge ? {
+      status: run.knowledge.status,
+      selected_count: run.knowledge.retrieval_bundle?.selected?.length ?? 0,
+      trust_posture: run.knowledge.retrieval_bundle?.provenance?.trust_posture ?? "unknown",
+      freshness_posture: run.knowledge.retrieval_bundle?.provenance?.freshness_posture ?? "unknown",
+      warning_codes: (run.knowledge.retrieval_bundle?.warnings ?? []).map((w) => w.code),
+    } : null,
     honestPartial: (isPartial || isFailed) ? honestPartial : null,
     verdict: isComplete
       ? "Run completed — all steps passed."
@@ -835,6 +864,18 @@ export function formatReport(report) {
     lines.push(`  ${icon} ${step.index}. ${step.role}${artifact}${note}`);
   }
 
+  // Knowledge posture (Phase 5)
+  if (report.knowledge) {
+    lines.push("");
+    lines.push("## Knowledge");
+    lines.push(`  Status: ${report.knowledge.status}`);
+    lines.push(`  Evidence: ${report.knowledge.selected_count} chunks selected`);
+    lines.push(`  Trust: ${report.knowledge.trust_posture} | Freshness: ${report.knowledge.freshness_posture}`);
+    if (report.knowledge.warning_codes.length > 0) {
+      lines.push(`  Warnings: ${report.knowledge.warning_codes.join(", ")}`);
+    }
+  }
+
   if (report.honestPartial) {
     lines.push("");
     lines.push("## Honest Partial");

package/src/swarm/build-gate.mjs

@@ -0,0 +1,127 @@
+/**
+ * Build Gate — Detects build system and runs lint/typecheck/test verification.
+ *
+ * After every swarm wave, the build gate runs to ensure changes didn't break anything.
+ * Auto-detects the build system from project files and runs appropriate commands.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { execSync } from "node:child_process";
+
+// ── Build system detection ──────────────────────────────────────────────────
+
+/**
+ * Detect the build system and available verification commands.
+ * @param {string} cwd - Repository root directory
+ * @returns {{ type: string, lintCmd: string|null, typecheckCmd: string|null, testCmd: string|null }}
+ */
+export function detectBuildSystem(cwd) {
+  // Node.js (package.json)
+  const pkgPath = join(cwd, "package.json");
+  if (existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+      const scripts = pkg.scripts || {};
+      return {
+        type: "node",
+        lintCmd: scripts.lint ? "npm run lint" : null,
+        typecheckCmd: scripts.typecheck ? "npm run typecheck" : (scripts["type-check"] ? "npm run type-check" : null),
+        testCmd: scripts.test ? "npm test" : null,
+      };
+    } catch {
+      // Fall through
+    }
+  }
+
+  // Rust (Cargo.toml)
+  if (existsSync(join(cwd, "Cargo.toml"))) {
+    return {
+      type: "rust",
+      lintCmd: "cargo clippy --all-targets -- -D warnings",
+      typecheckCmd: "cargo check",
+      testCmd: "cargo test",
+    };
+  }
+
+  // Python (pyproject.toml or setup.py)
+  if (existsSync(join(cwd, "pyproject.toml")) || existsSync(join(cwd, "setup.py"))) {
+    const hasRuff = existsSync(join(cwd, "pyproject.toml")) &&
+      readFileSync(join(cwd, "pyproject.toml"), "utf8").includes("[tool.ruff]");
+    return {
+      type: "python",
+      lintCmd: hasRuff ? "ruff check ." : null,
+      typecheckCmd: null,
+      testCmd: "pytest",
+    };
+  }
+
+  // Go (go.mod)
+  if (existsSync(join(cwd, "go.mod"))) {
+    return {
+      type: "go",
+      lintCmd: "golangci-lint run",
+      typecheckCmd: "go vet ./...",
+      testCmd: "go test ./...",
+    };
+  }
+
+  return { type: "unknown", lintCmd: null, typecheckCmd: null, testCmd: null };
+}
+
+// ── Build gate execution ────────────────────────────────────────────────────
+
+/**
+ * Run the build gate: lint → typecheck → test.
+ * @param {string} cwd - Repository root directory
+ * @param {object} [options]
+ * @param {object} [options.buildSystem] - Override auto-detected build system
+ * @param {number} [options.timeout] - Per-command timeout in ms (default: 120000)
+ * @returns {{ pass: boolean, lint: StepResult, typecheck: StepResult, test: StepResult, duration: number }}
+ *
+ * @typedef {{ status: "pass"|"fail"|"skip", output: string, duration: number }} StepResult
+ */
+export function runBuildGate(cwd, options = {}) {
+  const bs = options.buildSystem || detectBuildSystem(cwd);
+  const timeout = options.timeout || 120_000;
+  const start = Date.now();
+
+  const lint = runStep(bs.lintCmd, cwd, timeout);
+  const typecheck = runStep(bs.typecheckCmd, cwd, timeout);
+  const test = runStep(bs.testCmd, cwd, timeout);
+
+  const pass = lint.status !== "fail" && typecheck.status !== "fail" && test.status !== "fail";
+
+  return {
+    pass,
+    lint,
+    typecheck,
+    test,
+    duration: Date.now() - start,
+  };
+}
+
+/**
+ * Run a single build step.
+ * @param {string|null} cmd
+ * @param {string} cwd
+ * @param {number} timeout
+ * @returns {StepResult}
+ */
+function runStep(cmd, cwd, timeout) {
+  if (!cmd) return { status: "skip", output: "", duration: 0 };
+
+  const start = Date.now();
+  try {
+    const output = execSync(cmd, {
+      cwd,
+      timeout,
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    return { status: "pass", output: output.slice(0, 2000), duration: Date.now() - start };
+  } catch (err) {
+    const output = (err.stdout || "") + "\n" + (err.stderr || "");
+    return { status: "fail", output: output.slice(0, 2000), duration: Date.now() - start };
+  }
+}