@os-eco/overstory-cli 0.6.9 → 0.6.10

package/README.md

@@ -216,6 +216,15 @@ ov clean                         Clean up worktrees, sessions, artifacts
 ov doctor                        Run health checks on overstory setup
   --json                                 JSON output
   --category <name>                      Run a specific check category only
+  --fix                                  Auto-fix fixable issues
+
+ov ecosystem                     Show os-eco tool versions and health
+  --json                                 JSON output
+
+ov upgrade                       Upgrade overstory to latest npm version
+  --check                                Compare versions without installing
+  --all                                  Upgrade all 4 ecosystem tools
+  --json                                 JSON output
 
 ov inspect <agent>               Deep per-agent inspection
   --json                                 JSON output
@@ -266,6 +275,7 @@ ov metrics                       Show session metrics
 
 Global Flags:
   --quiet, -q                            Suppress non-error output
+  --timing                               Print command execution time to stderr
   --completions <shell>                  Generate shell completions (bash, zsh, fish)
 ```
 
@@ -275,13 +285,13 @@ Global Flags:
 - **Dependencies**: Minimal runtime — `chalk` (color output), `commander` (CLI framework), core I/O via Bun built-in APIs
 - **Database**: SQLite via `bun:sqlite` (WAL mode for concurrent access)
 - **Linting**: Biome (formatter + linter)
-- **Testing**: `bun test` (2186 tests across 77 files, colocated with source)
+- **Testing**: `bun test` (2241 tests across 79 files, colocated with source)
 - **External CLIs**: `bd` (beads) or `sd` (seeds), `mulch`, `git`, `tmux` — invoked as subprocesses
 
 ## Development
 
 ```bash
-# Run tests (2186 tests across 77 files)
+# Run tests (2241 tests across 79 files)
 bun test
 
 # Run a single test
@@ -322,7 +332,7 @@ overstory/
     config.ts                     Config loader + validation
     errors.ts                     Custom error types
     json.ts                       Standardized JSON envelope helpers
-    commands/                     One file per CLI subcommand (30 commands)
+    commands/                     One file per CLI subcommand (32 commands)
       agents.ts                   Agent discovery and querying
       coordinator.ts              Persistent orchestrator lifecycle
       supervisor.ts               Team lead management
@@ -345,7 +355,7 @@ overstory/
       run.ts                      Orchestration run lifecycle
       trace.ts                    Agent/bead timeline viewing
       clean.ts                    Worktree/session cleanup
-      doctor.ts                   Health check runner (9 check modules)
+      doctor.ts                   Health check runner (10 check modules)
       inspect.ts                  Deep per-agent inspection
       spec.ts                     Task spec management
       errors.ts                   Aggregated error view
@@ -353,6 +363,8 @@ overstory/
       stop.ts                     Agent termination
       costs.ts                    Token/cost analysis
       metrics.ts                  Session metrics
+      ecosystem.ts                os-eco tool dashboard
+      upgrade.ts                  npm version upgrades
       completions.ts              Shell completion generation (bash/zsh/fish)
     agents/                       Agent lifecycle management
       manifest.ts                 Agent registry (load + query)
@@ -367,7 +379,7 @@ overstory/
     watchdog/                     Tiered health monitoring (daemon, triage, health)
     logging/                      Multi-format logger + sanitizer + reporter + color control
     metrics/                      SQLite metrics + transcript parsing
-    doctor/                       Health check modules (9 checks)
+    doctor/                       Health check modules (10 checks)
     insights/                     Session insight analyzer for auto-expertise
     tracker/                      Pluggable task tracker (beads + seeds backends)
     mulch/                        mulch CLI wrapper

package/agents/builder.md

@@ -14,8 +14,8 @@ These are named failures. If you catch yourself doing any of these, stop and cor
 - **FILE_SCOPE_VIOLATION** -- Editing or writing to a file not listed in your FILE_SCOPE. Read any file for context, but only modify scoped files.
 - **CANONICAL_BRANCH_WRITE** -- Committing to or pushing to main/develop/canonical branch. You commit to your worktree branch only.
 - **SILENT_FAILURE** -- Encountering an error (test failure, lint failure, blocked dependency) and not reporting it via mail. Every error must be communicated to your parent with `--type error`.
-- **INCOMPLETE_CLOSE** -- Running `{{TRACKER_CLI}} close` without first passing quality gates (`bun test`, `bun run lint`, `bun run typecheck`) and sending a result mail to your parent.
-- **MISSING_WORKER_DONE** -- Closing a bead issue without first sending `worker_done` mail to parent. The supervisor relies on this signal to verify branches and initiate the merge pipeline.
+- **INCOMPLETE_CLOSE** -- Running `{{TRACKER_CLI}} close` without first passing quality gates ({{QUALITY_GATE_INLINE}}) and sending a result mail to your parent.
+- **MISSING_WORKER_DONE** -- Closing a {{TRACKER_NAME}} issue without first sending `worker_done` mail to parent. The supervisor relies on this signal to verify branches and initiate the merge pipeline.
 - **MISSING_MULCH_RECORD** -- Closing without recording mulch learnings. Every implementation session produces insights (conventions discovered, patterns applied, failures encountered). Skipping `ml record` loses knowledge for future agents.
 
 ## overlay
@@ -29,7 +29,7 @@ Your task-specific context (task ID, file scope, spec path, branch name, parent
 - **Never push to the canonical branch** (main/develop). You commit to your worktree branch only. Merging is handled by the orchestrator or a merger agent.
 - **Never run `git push`** -- your branch lives in the local worktree. The merge process handles integration.
 - **Never spawn sub-workers.** You are a leaf node. If you need something decomposed, ask your parent via mail.
-- **Run quality gates before closing.** Do not report completion unless `bun test`, `bun run lint`, and `bun run typecheck` pass.
+- **Run quality gates before closing.** Do not report completion unless {{QUALITY_GATE_INLINE}} pass.
 - If tests fail, fix them. If you cannot fix them, report the failure via mail with `--type error`.
 
 ## communication-protocol
@@ -49,9 +49,7 @@ Your task-specific context (task ID, file scope, spec path, branch name, parent
 
 ## completion-protocol
 
-1. Run `bun test` -- all tests must pass.
-2. Run `bun run lint` -- lint and formatting must be clean.
-3. Run `bun run typecheck` -- no TypeScript errors.
+{{QUALITY_GATE_STEPS}}
 4. Commit your scoped files to your worktree branch: `git add <files> && git commit -m "<summary>"`.
 5. **Record mulch learnings** -- review your work for insights worth preserving (conventions discovered, patterns applied, failures encountered, decisions made) and record them with outcome data:
    ```bash
@@ -88,10 +86,7 @@ You are an implementation specialist. Given a spec and a set of files you own, y
 - **Grep** -- search file contents with regex
 - **Bash:**
   - `git add`, `git commit`, `git diff`, `git log`, `git status`
-  - `bun test` (run tests)
-  - `bun run lint` (lint and format check via biome)
-  - `bun run biome check --write` (auto-fix lint/format issues)
-  - `bun run typecheck` (type checking via tsc)
+{{QUALITY_GATE_CAPABILITIES}}
   - `{{TRACKER_CLI}} show`, `{{TRACKER_CLI}} close` ({{TRACKER_NAME}} task management)
   - `ml prime`, `ml record`, `ml query` (expertise)
   - `ov mail send`, `ov mail check` (communication)
@@ -116,11 +111,7 @@ You are an implementation specialist. Given a spec and a set of files you own, y
    - Follow project conventions (check existing code for patterns).
    - Write tests alongside implementation.
 5. **Run quality gates:**
-   ```bash
-   bun test              # All tests must pass
-   bun run lint          # Lint and format must be clean
-   bun run typecheck     # No TypeScript errors
-   ```
+{{QUALITY_GATE_BASH}}
 6. **Commit your work** to your worktree branch:
    ```bash
    git add <your-scoped-files>

package/agents/lead.md

@@ -74,9 +74,7 @@ You are primarily a coordinator, but you can also be a doer for simple tasks. Yo
 - **Grep** -- search file contents with regex
 - **Bash:**
   - `git add`, `git commit`, `git diff`, `git log`, `git status`
-  - `bun test` (run tests)
-  - `bun run lint` (lint check)
-  - `bun run typecheck` (type checking)
+{{QUALITY_GATE_CAPABILITIES}}
   - `{{TRACKER_CLI}} create`, `{{TRACKER_CLI}} show`, `{{TRACKER_CLI}} ready`, `{{TRACKER_CLI}} close`, `{{TRACKER_CLI}} update` (full {{TRACKER_NAME}} management)
   - `{{TRACKER_CLI}} sync` (sync {{TRACKER_NAME}} with git)
   - `ml prime`, `ml record`, `ml query`, `ml search` (expertise)
@@ -230,7 +228,7 @@ Review is a quality investment. For complex, multi-file changes, spawn a reviewe
     **Self-verification (simple/moderate tasks):**
     1. Read the builder's diff: `git diff main..<builder-branch>`
     2. Check the diff matches the spec
-    3. Run quality gates: `bun test`, `bun run lint`, `bun run typecheck`
+    3. Run quality gates: {{QUALITY_GATE_INLINE}}
     4. If everything passes, send merge_ready directly
 
     **Reviewer verification (complex tasks):**
@@ -250,7 +248,7 @@ Review is a quality investment. For complex, multi-file changes, spawn a reviewe
       --body "Review the changes on branch <builder-branch>. Spec: .overstory/specs/<builder-bead-id>.md. Run quality gates and report PASS or FAIL." \
       --type dispatch
     ```
-    The reviewer validates against the builder's spec and runs quality gates (`bun test`, `bun run lint`, `bun run typecheck`).
+    The reviewer validates against the builder's spec and runs the project's quality gates ({{QUALITY_GATE_INLINE}}).
 13. **Handle review results:**
     - **PASS:** Either the reviewer sends a `result` mail with "PASS" in the subject, or self-verification confirms the diff matches the spec and quality gates pass. Immediately signal `merge_ready` for that builder's branch -- do not wait for other builders to finish:
       ```bash
@@ -286,7 +284,7 @@ Good decomposition follows these principles:
 
 1. **Verify review coverage:** For each builder, confirm either (a) a reviewer PASS was received, or (b) you self-verified by reading the diff and confirming quality gates pass.
 2. Verify all subtask {{TRACKER_NAME}} issues are closed AND each builder's `merge_ready` has been sent (check via `{{TRACKER_CLI}} show <id>` for each).
-3. Run integration tests if applicable: `bun test`.
+3. Run integration tests if applicable: {{QUALITY_GATE_INLINE}}.
 4. **Record mulch learnings** -- review your orchestration work for insights (decomposition strategies, worker coordination patterns, failures encountered, decisions made) and record them:
    ```bash
    ml record <domain> --type <convention|pattern|failure|decision> --description "..."

package/agents/merger.md

@@ -11,7 +11,7 @@ Every mail message and every tool call costs tokens. Be concise in communication
 These are named failures. If you catch yourself doing any of these, stop and correct immediately.
 
 - **TIER_SKIP** -- Jumping to a higher resolution tier without first attempting the lower tiers. Always start at Tier 1 and escalate only on failure.
-- **UNVERIFIED_MERGE** -- Completing a merge without running `bun test`, `bun run lint`, and `bun run typecheck` to verify the result. A merge that breaks tests is not complete.
+- **UNVERIFIED_MERGE** -- Completing a merge without running {{QUALITY_GATE_INLINE}} to verify the result. A merge that breaks tests is not complete.
 - **SCOPE_CREEP** -- Modifying code beyond what is needed for conflict resolution. Your job is to merge, not refactor or improve.
 - **SILENT_FAILURE** -- A merge fails at all tiers and you do not report it via mail. Every unresolvable conflict must be escalated to your parent with `--type error --priority urgent`.
 - **INCOMPLETE_CLOSE** -- Running `{{TRACKER_CLI}} close` without first verifying tests pass and sending a merge report mail to your parent.
@@ -28,7 +28,7 @@ Your task-specific context (task ID, branches to merge, target branch, merge ord
 - **Never push to the canonical branch** (main/develop). You commit to your worktree branch only. Merging is handled by the orchestrator or a merger agent.
 - **Never run `git push`** -- your branch lives in the local worktree. The merge process handles integration.
 - **Never spawn sub-workers.** You are a leaf node. If you need something decomposed, ask your parent via mail.
-- **Run quality gates before closing.** Do not report completion unless `bun test`, `bun run lint`, and `bun run typecheck` pass.
+- **Run quality gates before closing.** Do not report completion unless {{QUALITY_GATE_INLINE}} pass.
 - If tests fail, fix them. If you cannot fix them, report the failure via mail with `--type error`.
 
 ## communication-protocol
@@ -48,9 +48,7 @@ Your task-specific context (task ID, branches to merge, target branch, merge ord
 
 ## completion-protocol
 
-1. Run `bun test` -- all tests must pass after merge.
-2. Run `bun run lint` -- lint must be clean after merge.
-3. Run `bun run typecheck` -- no TypeScript errors after merge.
+{{QUALITY_GATE_STEPS}}
 4. **Record mulch learnings** -- capture merge resolution insights (conflict patterns, resolution strategies, branch integration issues):
    ```bash
    ml record <domain> --type <convention|pattern|failure> --description "..."
@@ -80,9 +78,7 @@ You are a branch integration specialist. When workers complete their tasks on se
   - `git merge`, `git merge --abort`, `git merge --no-edit`
   - `git log`, `git diff`, `git show`, `git status`, `git blame`
   - `git checkout`, `git branch`
-  - `bun test` (verify merged code passes tests)
-  - `bun run lint` (verify merged code passes lint)
-  - `bun run typecheck` (verify no TypeScript errors)
+{{QUALITY_GATE_CAPABILITIES}}
   - `{{TRACKER_CLI}} show`, `{{TRACKER_CLI}} close` ({{TRACKER_NAME}} task management)
   - `ml prime`, `ml query` (load expertise for conflict understanding)
   - `ov merge` (use overstory merge infrastructure)
@@ -135,11 +131,7 @@ If AI-resolve fails or produces broken code:
 - This is a last resort -- report that reimagine was needed.
 
 5. **Verify the merge:**
-   ```bash
-   bun test              # All tests must pass after merge
-   bun run lint          # Lint must be clean after merge
-   bun run typecheck     # No TypeScript errors after merge
-   ```
+{{QUALITY_GATE_BASH}}
 6. **Report the result:**
    ```bash
    {{TRACKER_CLI}} close <task-id> --reason "Merged <branch>: <tier used>, tests passing"

package/agents/reviewer.md

@@ -75,10 +75,7 @@ You are a validation specialist. Given code to review, you check it for correctn
 - **Glob** -- find files by name pattern
 - **Grep** -- search file contents with regex
 - **Bash** (observation and test commands only):
-  - `bun test` (run test suite)
-  - `bun test <specific-file>` (run targeted tests)
-  - `bun run lint` (lint and format check)
-  - `bun run typecheck` (type checking)
+{{QUALITY_GATE_CAPABILITIES}}
   - `git log`, `git diff`, `git show`, `git blame`
   - `git diff <base-branch>...<feature-branch>` (review changes)
   - `{{TRACKER_CLI}} show`, `{{TRACKER_CLI}} ready` (read {{TRACKER_NAME}} state)
@@ -107,11 +104,7 @@ You are a validation specialist. Given code to review, you check it for correctn
    - Check for: security issues, hardcoded secrets, missing input validation.
    - Check for: adequate test coverage, meaningful test assertions.
 5. **Run quality gates:**
-   ```bash
-   bun test              # Do all tests pass?
-   bun run lint          # Does lint and formatting pass?
-   bun run typecheck     # Are there any TypeScript errors?
-   ```
+{{QUALITY_GATE_BASH}}
 6. **Report results** via `{{TRACKER_CLI}} close` with a clear pass/fail summary:
    ```bash
    {{TRACKER_CLI}} close <task-id> --reason "PASS: <summary>"

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@os-eco/overstory-cli",
-	"version": "0.6.9",
+	"version": "0.6.10",
 	"description": "Multi-agent orchestration for Claude Code — spawn worker agents in git worktrees via tmux, coordinate through SQLite mail, merge with tiered conflict resolution",
 	"author": "Jaymin West",
 	"license": "MIT",

package/src/agents/hooks-deployer.test.ts

@@ -9,6 +9,7 @@ import {
 	buildPathBoundaryGuardScript,
 	deployHooks,
 	escapeForSingleQuotedShell,
+	extractQualityGatePrefixes,
 	getBashPathBoundaryGuards,
 	getCapabilityGuards,
 	getDangerGuards,
@@ -1234,6 +1235,49 @@ describe("getDangerGuards", () => {
 			);
 		}
 	});
+
+	test("custom quality gates appear in safe prefix list for non-implementation capabilities", () => {
+		const guards = getCapabilityGuards("scout", [
+			{ name: "Test", command: "pytest", description: "all tests pass" },
+			{ name: "Lint", command: "ruff check .", description: "no lint errors" },
+		]);
+		// Find the Bash guard for file modifications (last Bash entry for non-implementation)
+		const bashGuards = guards.filter((g) => g.matcher === "Bash");
+		const fileGuard = bashGuards.find((g) =>
+			g.hooks.some((h) => h.command.includes("cannot modify files")),
+		);
+		expect(fileGuard).toBeDefined();
+		const command = fileGuard?.hooks[0]?.command ?? "";
+		expect(command).toContain("pytest");
+		expect(command).toContain("ruff check .");
+		// Should NOT contain default bun commands
+		expect(command).not.toContain("bun test");
+	});
+});
+
+describe("extractQualityGatePrefixes", () => {
+	test("extracts command from each gate", () => {
+		const gates = [
+			{ name: "Test", command: "bun test", description: "all tests pass" },
+			{ name: "Lint", command: "bun run lint", description: "zero errors" },
+		];
+		const prefixes = extractQualityGatePrefixes(gates);
+		expect(prefixes).toEqual(["bun test", "bun run lint"]);
+	});
+
+	test("returns empty array for empty gates", () => {
+		expect(extractQualityGatePrefixes([])).toEqual([]);
+	});
+
+	test("works with non-bun quality gates", () => {
+		const gates = [
+			{ name: "Test", command: "pytest", description: "all tests pass" },
+			{ name: "Lint", command: "ruff check .", description: "no lint errors" },
+			{ name: "Type", command: "mypy src/", description: "type check" },
+		];
+		const prefixes = extractQualityGatePrefixes(gates);
+		expect(prefixes).toEqual(["pytest", "ruff check .", "mypy src/"]);
+	});
 });
 
 describe("buildBashFileGuardScript", () => {
@@ -1261,6 +1305,14 @@ describe("buildBashFileGuardScript", () => {
 		expect(script).toContain("git log");
 		expect(script).toContain("git diff");
 		expect(script).toContain("mulch ");
+		// Quality gate commands (bun test, bun run lint, etc.) are no longer
+		// hardcoded in SAFE_BASH_PREFIXES — they come from config via
+		// extractQualityGatePrefixes() and are passed as extraSafePrefixes
+		// through getCapabilityGuards().
+	});
+
+	test("includes quality gate prefixes when passed as extraSafePrefixes", () => {
+		const script = buildBashFileGuardScript("scout", ["bun test", "bun run lint"]);
 		expect(script).toContain("bun test");
 		expect(script).toContain("bun run lint");
 	});

package/src/agents/hooks-deployer.ts

@@ -1,6 +1,8 @@
 import { mkdir } from "node:fs/promises";
 import { dirname, join } from "node:path";
+import { DEFAULT_QUALITY_GATES } from "../config.ts";
 import { AgentError } from "../errors.ts";
+import type { QualityGate } from "../types.ts";
 
 /**
  * Capabilities that must never modify project files.
@@ -117,12 +119,20 @@ const SAFE_BASH_PREFIXES = [
 	"git blame",
 	"git branch",
 	"mulch ",
-	"bun test",
-	"bun run lint",
-	"bun run typecheck",
-	"bun run biome",
 ];
 
+/**
+ * Extract command prefixes from quality gate configurations.
+ *
+ * Each gate's command is used as a safe prefix so non-implementation agents
+ * can still run quality gate commands (e.g., reviewers running tests).
+ * This makes the safe prefix list configurable instead of hardcoding
+ * specific tool commands like "bun test".
+ */
+export function extractQualityGatePrefixes(gates: QualityGate[]): string[] {
+	return gates.map((g) => g.command);
+}
+
 /** Hook entry shape matching Claude Code's settings.local.json format. */
 interface HookEntry {
 	matcher: string;
@@ -470,8 +480,10 @@ export function getBashPathBoundaryGuards(): HookEntry[] {
  *
  * Note: All capabilities also receive Bash danger guards via getDangerGuards().
  */
-export function getCapabilityGuards(capability: string): HookEntry[] {
+export function getCapabilityGuards(capability: string, qualityGates?: QualityGate[]): HookEntry[] {
 	const guards: HookEntry[] = [];
+	const gates = qualityGates ?? DEFAULT_QUALITY_GATES;
+	const gatePrefixes = extractQualityGatePrefixes(gates);
 
 	// Block Claude Code native team/task tools for ALL overstory agents.
 	// Agents must use `overstory sling` for delegation, not native Task/Team tools.
@@ -501,7 +513,9 @@ export function getCapabilityGuards(capability: string): HookEntry[] {
 		guards.push(...toolGuards);
 
 		// Coordination capabilities get git add/commit whitelisted for beads/mulch sync
-		const extraSafe = COORDINATION_CAPABILITIES.has(capability) ? COORDINATION_SAFE_PREFIXES : [];
+		const extraSafe = COORDINATION_CAPABILITIES.has(capability)
+			? [...COORDINATION_SAFE_PREFIXES, ...gatePrefixes]
+			: gatePrefixes;
 		const bashFileGuard: HookEntry = {
 			matcher: "Bash",
 			hooks: [
@@ -560,6 +574,7 @@ export async function deployHooks(
 	worktreePath: string,
 	agentName: string,
 	capability = "builder",
+	qualityGates?: QualityGate[],
 ): Promise<void> {
 	const templatePath = getTemplatePath();
 	const file = Bun.file(templatePath);
@@ -606,7 +621,7 @@ export async function deployHooks(
 	// and do not require PATH extension.
 	const pathGuards = getPathBoundaryGuards();
 	const dangerGuards = getDangerGuards(agentName);
-	const capabilityGuards = getCapabilityGuards(capability);
+	const capabilityGuards = getCapabilityGuards(capability, qualityGates);
 	const allGuards = [...pathGuards, ...dangerGuards, ...capabilityGuards];
 
 	if (allGuards.length > 0) {

package/src/agents/overlay.test.ts

@@ -4,7 +4,15 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { AgentError } from "../errors.ts";
 import type { OverlayConfig, QualityGate } from "../types.ts";
-import { generateOverlay, isCanonicalRoot, writeOverlay } from "./overlay.ts";
+import {
+	formatQualityGatesBash,
+	formatQualityGatesCapabilities,
+	formatQualityGatesInline,
+	formatQualityGatesSteps,
+	generateOverlay,
+	isCanonicalRoot,
+	writeOverlay,
+} from "./overlay.ts";
 
 const SAMPLE_BASE_DEFINITION = `# Builder Agent
 
@@ -674,3 +682,150 @@ describe("isCanonicalRoot", () => {
 		expect(isCanonicalRoot(worktreePath, canonicalRoot)).toBe(false);
 	});
 });
+
+describe("formatQualityGatesInline", () => {
+	test("formats default gates as inline backtick list", () => {
+		const result = formatQualityGatesInline(undefined);
+		expect(result).toBe("`bun test`, `bun run lint`, `bun run typecheck`");
+	});
+
+	test("formats custom gates as inline backtick list", () => {
+		const gates: QualityGate[] = [
+			{ name: "Test", command: "pytest", description: "all tests pass" },
+			{ name: "Lint", command: "ruff check .", description: "no lint errors" },
+		];
+		const result = formatQualityGatesInline(gates);
+		expect(result).toBe("`pytest`, `ruff check .`");
+	});
+
+	test("falls back to defaults for empty array", () => {
+		const result = formatQualityGatesInline([]);
+		expect(result).toContain("`bun test`");
+	});
+});
+
+describe("formatQualityGatesSteps", () => {
+	test("formats default gates as numbered steps", () => {
+		const result = formatQualityGatesSteps(undefined);
+		expect(result).toContain("1. Run `bun test`");
+		expect(result).toContain("2. Run `bun run lint`");
+		expect(result).toContain("3. Run `bun run typecheck`");
+	});
+
+	test("formats custom gates as numbered steps", () => {
+		const gates: QualityGate[] = [
+			{ name: "Build", command: "cargo build", description: "compilation succeeds" },
+			{ name: "Test", command: "cargo test", description: "all tests pass" },
+		];
+		const result = formatQualityGatesSteps(gates);
+		expect(result).toBe(
+			"1. Run `cargo build` -- compilation succeeds.\n2. Run `cargo test` -- all tests pass.",
+		);
+	});
+});
+
+describe("formatQualityGatesBash", () => {
+	test("formats as fenced bash block with aligned comments", () => {
+		const result = formatQualityGatesBash(undefined);
+		expect(result).toContain("```bash");
+		expect(result).toContain("bun test");
+		expect(result).toContain("bun run lint");
+		expect(result).toContain("bun run typecheck");
+		expect(result).toContain("```");
+	});
+
+	test("capitalizes first letter of description in comments", () => {
+		const gates: QualityGate[] = [
+			{ name: "Test", command: "pytest", description: "all tests pass" },
+		];
+		const result = formatQualityGatesBash(gates);
+		expect(result).toContain("# All tests pass");
+	});
+
+	test("custom gates produce correct bash block", () => {
+		const gates: QualityGate[] = [
+			{ name: "Test", command: "npm test", description: "tests pass" },
+			{ name: "Lint", command: "npm run lint", description: "lint clean" },
+		];
+		const result = formatQualityGatesBash(gates);
+		expect(result).toContain("npm test");
+		expect(result).toContain("npm run lint");
+		expect(result).not.toContain("bun");
+	});
+});
+
+describe("formatQualityGatesCapabilities", () => {
+	test("formats as indented bullet list", () => {
+		const result = formatQualityGatesCapabilities(undefined);
+		expect(result).toContain("  - `bun test`");
+		expect(result).toContain("  - `bun run lint`");
+		expect(result).toContain("  - `bun run typecheck`");
+	});
+
+	test("custom gates produce correct capability bullets", () => {
+		const gates: QualityGate[] = [
+			{ name: "Test", command: "pytest", description: "run tests" },
+			{ name: "Type", command: "mypy .", description: "type check" },
+		];
+		const result = formatQualityGatesCapabilities(gates);
+		expect(result).toBe("  - `pytest` (run tests)\n  - `mypy .` (type check)");
+	});
+});
+
+describe("quality gate placeholders in base definitions", () => {
+	test("QUALITY_GATE_INLINE in base definition gets replaced", async () => {
+		const config = makeConfig({
+			baseDefinition: "Run {{QUALITY_GATE_INLINE}} before closing.",
+		});
+		const output = await generateOverlay(config);
+		expect(output).toContain("`bun test`, `bun run lint`, `bun run typecheck`");
+		expect(output).not.toContain("{{QUALITY_GATE_INLINE}}");
+	});
+
+	test("QUALITY_GATE_STEPS in base definition gets replaced", async () => {
+		const config = makeConfig({
+			baseDefinition: "## Steps\n{{QUALITY_GATE_STEPS}}",
+		});
+		const output = await generateOverlay(config);
+		expect(output).toContain("1. Run `bun test`");
+		expect(output).not.toContain("{{QUALITY_GATE_STEPS}}");
+	});
+
+	test("QUALITY_GATE_BASH in base definition gets replaced", async () => {
+		const config = makeConfig({
+			baseDefinition: "## Workflow\n{{QUALITY_GATE_BASH}}",
+		});
+		const output = await generateOverlay(config);
+		expect(output).toContain("```bash");
+		expect(output).toContain("bun test");
+		expect(output).not.toContain("{{QUALITY_GATE_BASH}}");
+	});
+
+	test("QUALITY_GATE_CAPABILITIES in base definition gets replaced", async () => {
+		const config = makeConfig({
+			baseDefinition: "## Caps\n{{QUALITY_GATE_CAPABILITIES}}",
+		});
+		const output = await generateOverlay(config);
+		expect(output).toContain("  - `bun test`");
+		expect(output).not.toContain("{{QUALITY_GATE_CAPABILITIES}}");
+	});
+
+	test("custom quality gates in base definition get custom commands", async () => {
+		const gates: QualityGate[] = [
+			{ name: "Test", command: "pytest", description: "all tests pass" },
+			{ name: "Lint", command: "ruff check .", description: "no lint errors" },
+		];
+		const config = makeConfig({
+			capability: "builder",
+			qualityGates: gates,
+			baseDefinition:
+				"Run {{QUALITY_GATE_INLINE}} before closing.\n{{QUALITY_GATE_BASH}}\n{{QUALITY_GATE_STEPS}}",
+		});
+		const output = await generateOverlay(config);
+		expect(output).toContain("`pytest`, `ruff check .`");
+		expect(output).toContain("pytest");
+		expect(output).toContain("ruff check .");
+		expect(output).not.toContain("bun test");
+		expect(output).not.toContain("{{QUALITY_GATE");
+	});
+});