@dommaker/harness 1.3.0 → 1.5.0

package/src/cli/commands/passes-gate.ts

@@ -8,8 +8,9 @@ import chalk from 'chalk';
 import * as fs from 'fs/promises';
 import * as path from 'path';
 import { execAsync } from '../../utils/exec';
-import { PassesGate } from '../../core/validators/passes-gate';
+import { PassesGate, detectTestCommand } from '../../core/validators/passes-gate';
 import type { PassesGateConfig } from '../../types/passes-gate';
+import { log, processIO, type CommandIO, type CommandResult } from '../command-contract';
 
 export interface PassesGateOptions {
   /** 测试命令 */
@@ -22,45 +23,14 @@ export interface PassesGateOptions {
   maxRetries?: number;
 }
 
-/**
- * 检测项目的测试命令
- */
-async function detectTestCommand(projectPath: string): Promise<string | undefined> {
-  const packageJsonPath = path.join(projectPath, 'package.json');
-
-  try {
-    const content = await fs.readFile(packageJsonPath, 'utf-8');
-    const pkg = JSON.parse(content);
-
-    if (pkg.scripts?.test && pkg.scripts.test !== 'echo "Error: no test specified"') {
-      return 'npm test';
-    }
-    if (pkg.scripts?.['test:ci']) {
-      return 'npm run test:ci';
-    }
-  } catch {
-    // 没有 package.json
-  }
-
-  // 检查其他项目类型
-  try {
-    await fs.access(path.join(projectPath, 'pytest.ini'));
-    return 'pytest';
-  } catch {}
-
-  try {
-    await fs.access(path.join(projectPath, 'go.mod'));
-    return 'go test ./...';
-  } catch {}
-
-  return undefined;
-}
-
 /**
  * 执行测试门控
  */
-export async function runPassesGate(options: PassesGateOptions): Promise<void> {
-  console.log(chalk.blue('🚦 运行测试门控...'));
+export async function runPassesGate(
+  options: PassesGateOptions,
+  io: CommandIO = processIO,
+): Promise<CommandResult> {
+  log(io, chalk.blue('🚦 运行测试门控...'));
 
   const projectPath = options.projectPath || process.cwd();
 
@@ -71,12 +41,12 @@ export async function runPassesGate(options: PassesGateOptions): Promise<void> {
   }
 
   if (!testCommand) {
-    console.log(chalk.yellow('⚠️  未检测到测试命令，跳过测试门控'));
-    console.log(chalk.gray('提示: 使用 --test-command 指定测试命令'));
-    return;
+    log(io, chalk.yellow('⚠️  未检测到测试命令，跳过测试门控'));
+    log(io, chalk.gray('提示: 使用 --test-command 指定测试命令'));
+    return { kind: 'skip', reason: '未检测到测试命令' };
   }
 
-  console.log(chalk.gray(`测试命令: ${testCommand}`));
+  log(io, chalk.gray(`测试命令: ${testCommand}`));
 
   // 配置
   const config: PassesGateConfig = {
@@ -91,43 +61,63 @@ export async function runPassesGate(options: PassesGateOptions): Promise<void> {
   const passesGate = new PassesGate(config);
 
   try {
-    const result = await passesGate.runTests();
+    const result = await passesGate.runTests(projectPath);
 
-    console.log();
-    console.log(chalk.gray('测试结果:'));
-    console.log(chalk.gray(`  通过: ${result.passedTests}/${result.totalTests}`));
-    console.log(chalk.gray(`  失败: ${result.failedTests}/${result.totalTests}`));
-    console.log(chalk.gray(`  耗时: ${result.duration}ms`));
+    log(io);
+    log(io, chalk.gray('测试结果:'));
+    log(io, chalk.gray(`  通过: ${result.passedTests}/${result.totalTests}`));
+    log(io, chalk.gray(`  失败: ${result.failedTests}/${result.totalTests}`));
+    log(io, chalk.gray(`  耗时: ${result.duration}ms`));
 
     if (result.passed) {
-      console.log();
-      console.log(chalk.green('✅ 测试门控通过'));
-      console.log(chalk.green('   task.passes = true (由测试结果设置)'));
+      log(io);
+      log(io, chalk.green('✅ 测试门控通过'));
+      log(io, chalk.green('   task.passes = true (由测试结果设置)'));
     } else {
-      console.log();
-      console.log(chalk.red('❌ 测试门控未通过'));
-      console.log(chalk.red('   task.passes = false'));
+      log(io);
+      log(io, chalk.red('❌ 测试门控未通过'));
+      log(io, chalk.red('   task.passes = false'));
       
       if (result.failures && result.failures.length > 0) {
-        console.log(chalk.red('\n失败的测试:'));
+        log(io, chalk.red('\n失败的测试:'));
         result.failures.forEach(f => {
-          console.log(chalk.red(`  - ${f.name}: ${f.message}`));
+          log(io, chalk.red(`  - ${f.name}: ${f.message}`));
         });
       }
 
-      process.exit(1);
+      return { kind: 'fail', reason: `passes-gate denied: ${result.failedTests}/${result.totalTests} 个测试失败` };
     }
+    return { kind: 'ok' };
   } catch (error) {
-    console.log(chalk.red(`\n❌ 测试执行失败: ${(error as Error).message}`));
-    process.exit(1);
+    log(io, chalk.red(`\n❌ 测试执行失败: ${(error as Error).message}`));
+    return { kind: 'fail', reason: `passes-gate 测试执行异常: ${(error as Error).message}` };
   }
 }
 
+/**
+ * --coverage 路由入口（候选7）：projectPath 兜底 + 阈值强转编组，
+ * 自 definitions.ts 的 optionRoutes args 闭包移回命令模块。
+ */
+export async function coverageCheck(
+  options: Record<string, unknown>,
+  io: CommandIO = processIO,
+): Promise<CommandResult> {
+  return checkCoverage(
+    (options.projectPath as string) || process.cwd(),
+    parseInt(String(options.coverageThreshold), 10),
+    io,
+  );
+}
+
 /**
  * 检查测试覆盖率
  */
-export async function checkCoverage(projectPath: string, threshold: number = 80): Promise<boolean> {
-  console.log(chalk.blue(`📊 检查测试覆盖率 (阈值: ${threshold}%)...`));
+export async function checkCoverage(
+  projectPath: string,
+  threshold: number = 80,
+  io: CommandIO = processIO,
+): Promise<CommandResult> {
+  log(io, chalk.blue(`📊 检查测试覆盖率 (阈值: ${threshold}%)...`));
 
   try {
     // 运行覆盖率检查
@@ -142,17 +132,17 @@ export async function checkCoverage(projectPath: string, threshold: number = 80)
 
     const totalCoverage = coverage.total?.lines?.pct || 0;
 
-    console.log(chalk.gray(`当前覆盖率: ${totalCoverage}%`));
+    log(io, chalk.gray(`当前覆盖率: ${totalCoverage}%`));
 
     if (totalCoverage >= threshold) {
-      console.log(chalk.green(`✅ 覆盖率达标 (${totalCoverage}% >= ${threshold}%)`));
-      return true;
-    } else {
-      console.log(chalk.red(`❌ 覆盖率不足 (${totalCoverage}% < ${threshold}%)`));
-      return false;
+      log(io, chalk.green(`✅ 覆盖率达标 (${totalCoverage}% >= ${threshold}%)`));
+      return { kind: 'ok' };
     }
+    log(io, chalk.red(`❌ 覆盖率不足 (${totalCoverage}% < ${threshold}%)`));
+    // 历史行为：--coverage 路由的未达标不改退出码（今日返回值被 bin 丢弃）→ skip 保留 0 面
+    return { kind: 'skip', reason: `覆盖率不足: ${totalCoverage}% < ${threshold}%` };
   } catch (error) {
-    console.log(chalk.yellow(`⚠️  无法获取覆盖率信息: ${(error as Error).message}`));
-    return true; // 无法获取时跳过检查
+    log(io, chalk.yellow(`⚠️  无法获取覆盖率信息: ${(error as Error).message}`));
+    return { kind: 'skip', reason: `无法获取覆盖率信息: ${(error as Error).message}` }; // 无法获取时跳过检查
   }
 }

package/src/cli/commands/performance.ts

@@ -6,6 +6,7 @@
 
 import chalk from 'chalk';
 import { PerformanceGate } from '../../gates/performance';
+import { log, processIO, type CommandIO, type CommandResult } from '../command-contract';
 
 export interface PerformanceOptions {
   /** 项目路径 */
@@ -27,8 +28,11 @@ export interface PerformanceOptions {
 /**
  * 执行性能门控
  */
-export async function performance(options: PerformanceOptions): Promise<void> {
-  console.log(chalk.blue('⚡ 性能门控检查...'));
+export async function performance(
+  options: PerformanceOptions,
+  io: CommandIO = processIO,
+): Promise<CommandResult> {
+  log(io, chalk.blue('⚡ 性能门控检查...'));
 
   const projectPath = options.projectPath || process.cwd();
 
@@ -62,47 +66,48 @@ export async function performance(options: PerformanceOptions): Promise<void> {
     } as any);
 
     if (result.passed) {
-      console.log();
-      console.log(chalk.green('✅ 性能门控检查通过'));
+      log(io);
+      log(io, chalk.green('✅ 性能门控检查通过'));
 
       // 显示详细指标
       if (result.details?.metrics) {
-        console.log();
-        console.log(chalk.gray('性能指标:'));
+        log(io);
+        log(io, chalk.gray('性能指标:'));
 
         const metrics = result.details.metrics as any;
         if (metrics.coverage !== undefined) {
           const threshold = options.coverageThreshold || 80;
           const status = metrics.coverage >= threshold ? '✅' : '❌';
-          console.log(chalk.gray(`  覆盖率: ${metrics.coverage.toFixed(2)}% ${status}`));
+          log(io, chalk.gray(`  覆盖率: ${metrics.coverage.toFixed(2)}% ${status}`));
         }
 
         if (metrics.bundleSize !== undefined) {
           const thresholdKB = options.bundleThreshold || 500;
           const actualKB = metrics.bundleSize / 1024;
           const status = actualKB <= thresholdKB ? '✅' : '❌';
-          console.log(chalk.gray(`  打包大小: ${actualKB.toFixed(2)} KB ${status}`));
+          log(io, chalk.gray(`  打包大小: ${actualKB.toFixed(2)} KB ${status}`));
         }
 
         if (metrics.benchmarkTime !== undefined) {
-          console.log(chalk.gray(`  基准测试: ${metrics.benchmarkTime}ms`));
+          log(io, chalk.gray(`  基准测试: ${metrics.benchmarkTime}ms`));
         }
       }
     } else {
-      console.log();
-      console.log(chalk.red('❌ 性能门控检查失败'));
-      console.log(chalk.red(`   ${result.message}`));
+      log(io);
+      log(io, chalk.red('❌ 性能门控检查失败'));
+      log(io, chalk.red(`   ${result.message}`));
       if (result.details?.failures) {
         (result.details.failures as string[]).forEach((failure: string) => {
-          console.log(chalk.red(`   - ${failure}`));
+          log(io, chalk.red(`   - ${failure}`));
         });
       }
-      process.exit(1);
+      return { kind: 'fail', reason: `performance gate denied: ${result.message}` };
     }
+    return { kind: 'ok' };
   } catch (error: any) {
-    console.log();
-    console.log(chalk.red('❌ 性能门控检查出错'));
-    console.log(chalk.red(`   ${error.message}`));
-    process.exit(1);
+    log(io);
+    log(io, chalk.red('❌ 性能门控检查出错'));
+    log(io, chalk.red(`   ${error.message}`));
+    return { kind: 'fail', reason: `performance gate error: ${error.message}` };
   }
 }

package/src/cli/commands/posteval-plan.ts

@@ -3,9 +3,13 @@
  *
  * 调用 Studio PostEval API，验证 plan 文件的 checklist items 是否都有对应的 staged diff。
  * pre-commit hook 使用此命令防止"假装完成"。
+ *
+ * 判定经返回值外溢（架构评审候选7）：API 不可用/5xx 属"未判定"→ skip（退出码面 0 不变）；
+ * 覆盖率不足与 4xx → fail，reason 指明是哪一项否决。
  */
 
 import chalk from 'chalk';
+import { log, logError, processIO, type CommandIO, type CommandResult } from '../command-contract';
 
 export interface PostEvalPlanOptions {
   planPath: string;
@@ -38,7 +42,10 @@ async function fetchWithRetry(url: string, body: string, retries: number): Promi
   throw lastError;
 }
 
-export async function postevalPlan(options: PostEvalPlanOptions): Promise<void> {
+export async function postevalPlan(
+  options: PostEvalPlanOptions,
+  io: CommandIO = processIO,
+): Promise<CommandResult> {
   const apiPort = process.env.API_PORT || '3001';
   const url = `http://localhost:${apiPort}/api/v1/agents/post-eval/plan-coverage`;
 
@@ -48,12 +55,12 @@ export async function postevalPlan(options: PostEvalPlanOptions): Promise<void>
     if (!res.ok) {
       if (res.status >= 500) {
         // Server error — allow commit with warning (don't block on infrastructure failure)
-        console.error(chalk.yellow(`⚠️  PostEval API unavailable (${res.status}), allowing commit with warning`));
-        console.error(chalk.yellow(`   Plan: ${options.planPath}`));
-        process.exit(0);
+        logError(io, chalk.yellow(`⚠️  PostEval API unavailable (${res.status}), allowing commit with warning`));
+        logError(io, chalk.yellow(`   Plan: ${options.planPath}`));
+        return { kind: 'skip', reason: `PostEval API 服务端错误 ${res.status}，未判定` };
       }
-      console.error(chalk.red(`❌ PostEval API error: ${res.status} ${res.statusText}`));
-      process.exit(1);
+      logError(io, chalk.red(`❌ PostEval API error: ${res.status} ${res.statusText}`));
+      return { kind: 'fail', reason: `PostEval API error: ${res.status} ${res.statusText}` };
     }
 
     const report = await res.json() as {
@@ -65,20 +72,27 @@ export async function postevalPlan(options: PostEvalPlanOptions): Promise<void>
     const pct = Math.round(report.completeness * 100);
 
     if (report.completeness < 1) {
-      console.error(chalk.red(`❌ Plan coverage: ${pct}% (${report.matchedAcs.length}/${report.matchedAcs.length + report.missedAcs.length})`));
+      logError(io, chalk.red(`❌ Plan coverage: ${pct}% (${report.matchedAcs.length}/${report.matchedAcs.length + report.missedAcs.length})`));
       if (report.missedAcs.length > 0) {
-        console.error(chalk.red('Missed items:'));
-        report.missedAcs.forEach((item: string) => console.error(chalk.red(`  - ${item}`)));
+        logError(io, chalk.red('Missed items:'));
+        report.missedAcs.forEach((item: string) => logError(io, chalk.red(`  - ${item}`)));
       }
-      process.exit(1);
+      return {
+        kind: 'fail',
+        reason: `plan coverage ${pct}% < 100%，缺 ${report.missedAcs.length} 项: ${report.missedAcs.join('; ')}`,
+      };
     }
 
-    console.log(chalk.green(`✅ Plan coverage: ${pct}%`));
+    log(io, chalk.green(`✅ Plan coverage: ${pct}%`));
+    return { kind: 'ok' };
   } catch (error: any) {
     // API unreachable after all retries — allow with warning (don't block commits on infra)
-    console.error(chalk.yellow(`⚠️  Studio API unreachable after ${MAX_RETRIES} retries, allowing commit with warning`));
-    console.error(chalk.yellow(`   Plan: ${options.planPath}`));
-    console.error(chalk.yellow(`   Error: ${error?.code || error?.message || String(error)}`));
-    process.exit(0);
+    logError(io, chalk.yellow(`⚠️  Studio API unreachable after ${MAX_RETRIES} retries, allowing commit with warning`));
+    logError(io, chalk.yellow(`   Plan: ${options.planPath}`));
+    logError(io, chalk.yellow(`   Error: ${error?.code || error?.message || String(error)}`));
+    return {
+      kind: 'skip',
+      reason: `Studio API 不可达（${error?.code || error?.message || String(error)}），未判定`,
+    };
   }
 }

package/src/cli/commands/release.ts

@@ -15,6 +15,10 @@
  *   7. Check private flag
  *   8. npm publish (or skip if PR flow)
  *   9. GitHub Release
+ *
+ * 判定经返回值外溢（架构评审候选7）：12 个前置闸门维持**首败即停**，每个闸门失败
+ * 返回 `gate <id>: <原因>`；退出码映射在 bin/harness.js 唯一一处。输出经注入 io
+ * 流式打印（分钟级子进程阶段不能静默）。
  */
 
 import { execSync } from 'child_process';
@@ -22,6 +26,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import chalk from 'chalk';
 import { verifyReleaseArtifacts } from '../../release';
+import { log, logError, processIO, type CommandIO, type CommandResult } from '../command-contract';
 
 export interface ReleaseOptions {
   bumpType?: 'patch' | 'minor' | 'major';
@@ -39,7 +44,12 @@ async function run(cmd: string, cwd: string, timeout = 60_000): Promise<{ stdout
   }
 }
 
-export async function release(options: ReleaseOptions): Promise<void> {
+/** 闸门失败结果：reason 含闸门标识，可被调用方逐闸门断言 */
+function gateFail(gate: string, detail: string): CommandResult {
+  return { kind: 'fail', reason: `gate ${gate}: ${detail}` };
+}
+
+export async function release(options: ReleaseOptions, io: CommandIO = processIO): Promise<CommandResult> {
   const pkgPath = process.cwd();
   const bumpType = options.bumpType || 'patch';
   const dryRun = options.dryRun === 'true';
@@ -47,59 +57,59 @@ export async function release(options: ReleaseOptions): Promise<void> {
   // ── 1. Verify package ──
   const pkgJsonPath = path.join(pkgPath, 'package.json');
   if (!fs.existsSync(pkgJsonPath)) {
-    console.error(chalk.red(`❌ Not a package: ${pkgPath}`));
-    process.exit(1);
+    logError(io, chalk.red(`❌ Not a package: ${pkgPath}`));
+    return gateFail('package', `not a package: ${pkgPath}`);
   }
   const pkgJson = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8'));
   const pkgName = pkgJson.name;
   const oldVersion = pkgJson.version;
-  console.log(chalk.cyan(`📦 ${pkgName}@${oldVersion}`));
-  console.log(chalk.cyan(`   bump: ${bumpType}${dryRun ? ' (dry-run)' : ''}`));
+  log(io, chalk.cyan(`📦 ${pkgName}@${oldVersion}`));
+  log(io, chalk.cyan(`   bump: ${bumpType}${dryRun ? ' (dry-run)' : ''}`));
 
   // ── 2. Check branch (must be on master/main) ──
   const branchResult = await run('git rev-parse --abbrev-ref HEAD', pkgPath);
   const currentBranch = branchResult.stdout.trim();
   if (currentBranch !== 'master' && currentBranch !== 'main') {
-    console.error(chalk.red(`❌ Must be on master or main branch to release. Currently on: ${currentBranch}`));
-    console.error(chalk.gray('   Run: git checkout master && git merge ' + currentBranch));
-    process.exit(1);
+    logError(io, chalk.red(`❌ Must be on master or main branch to release. Currently on: ${currentBranch}`));
+    logError(io, chalk.gray('   Run: git checkout master && git merge ' + currentBranch));
+    return gateFail('branch', `must be on master or main branch, currently on ${currentBranch}`);
   }
-  console.log(chalk.green(`✅ git: on ${currentBranch}`));
+  log(io, chalk.green(`✅ git: on ${currentBranch}`));
 
   // ── 2b. Check remote sync ──
   await run('git fetch origin', pkgPath, 15_000);
   const behind = await run(`git rev-list --count HEAD..origin/${currentBranch}`, pkgPath);
   if (behind.stdout.trim() !== '0') {
-    console.error(chalk.red(`❌ Local ${currentBranch} is ${behind.stdout.trim()} commits behind origin/${currentBranch}. Pull first.`));
-    process.exit(1);
+    logError(io, chalk.red(`❌ Local ${currentBranch} is ${behind.stdout.trim()} commits behind origin/${currentBranch}. Pull first.`));
+    return gateFail('remote-sync', `local ${currentBranch} is ${behind.stdout.trim()} commits behind origin/${currentBranch}`);
   }
-  console.log(chalk.green('✅ git: synced with remote'));
+  log(io, chalk.green('✅ git: synced with remote'));
 
   // ── 2c. Check clean working tree ──
   const stat = await run('git status --porcelain -uno', pkgPath);
   if (stat.stdout.length > 0) {
-    console.error(chalk.red('❌ Uncommitted changes. Commit or stash before releasing.'));
-    console.error(chalk.gray(stat.stdout.slice(0, 500)));
-    process.exit(1);
+    logError(io, chalk.red('❌ Uncommitted changes. Commit or stash before releasing.'));
+    logError(io, chalk.gray(stat.stdout.slice(0, 500)));
+    return gateFail('clean-tree', 'working tree has uncommitted changes');
   }
-  console.log(chalk.green('✅ git: clean'));
+  log(io, chalk.green('✅ git: clean'));
 
   // ── 3. tsc build ──
-  console.log(chalk.cyan('🔨 Building...'));
+  log(io, chalk.cyan('🔨 Building...'));
   const build = await run('npx tsc', pkgPath, 60_000);
   if (build.stderr && !build.stdout) {
-    console.error(chalk.red('❌ tsc failed:'), build.stderr.slice(0, 800));
-    process.exit(1);
+    logError(io, chalk.red('❌ tsc failed:'), build.stderr.slice(0, 800));
+    return gateFail('build', `tsc failed: ${build.stderr.slice(0, 200)}`);
   }
-  console.log(chalk.green('✅ tsc: built'));
+  log(io, chalk.green('✅ tsc: built'));
 
   // ── 4. Verify dist（发布物完整性自检，harness#77：清单随源码维护，不再本文件硬编码）──
   const integrity = verifyReleaseArtifacts(pkgPath);
   if (!integrity.ok) {
-    console.error(chalk.red(`❌ dist missing critical artifacts (${integrity.missing.length}): ${integrity.missing.join(', ')}`));
-    process.exit(1);
+    logError(io, chalk.red(`❌ dist missing critical artifacts (${integrity.missing.length}): ${integrity.missing.join(', ')}`));
+    return gateFail('dist-artifacts', `missing critical artifacts: ${integrity.missing.join(', ')}`);
   }
-  console.log(chalk.green(`✅ dist: verified (${integrity.checked.length} critical artifacts)`));
+  log(io, chalk.green(`✅ dist: verified (${integrity.checked.length} critical artifacts)`));
 
   if (dryRun) {
     const [major, minor, patch] = oldVersion.split('.').map(Number);
@@ -107,12 +117,12 @@ export async function release(options: ReleaseOptions): Promise<void> {
     if (bumpType === 'major') newVer = `${major + 1}.0.0`;
     else if (bumpType === 'minor') newVer = `${major}.${minor + 1}.0`;
     else newVer = `${major}.${minor}.${patch + 1}`;
-    console.log(chalk.yellow(`🏁 Dry-run complete. Would publish: ${pkgName}@${newVer}`));
-    process.exit(0);
+    log(io, chalk.yellow(`🏁 Dry-run complete. Would publish: ${pkgName}@${newVer}`));
+    return { kind: 'ok' };
   }
 
   // ── 5. Bump version (npm version creates git commit + tag atomically) ──
-  console.log(chalk.cyan('🔢 Bumping version...'));
+  log(io, chalk.cyan('🔢 Bumping version...'));
   const [major, minor, patch] = oldVersion.split('.').map(Number);
   let expectedNew: string;
   if (bumpType === 'major') expectedNew = `${major + 1}.0.0`;
@@ -121,28 +131,28 @@ export async function release(options: ReleaseOptions): Promise<void> {
   const expectedTag = `v${expectedNew}`;
   const tagExists = await run(`git tag -l "${expectedTag}"`, pkgPath);
   if (tagExists.stdout.trim() === expectedTag) {
-    console.error(chalk.red(`❌ Tag ${expectedTag} already exists. Version may have been released already.`));
-    process.exit(1);
+    logError(io, chalk.red(`❌ Tag ${expectedTag} already exists. Version may have been released already.`));
+    return gateFail('tag-conflict', `tag ${expectedTag} already exists`);
   }
 
   const bump = await run(`npm version ${bumpType} -m "release: %s"`, pkgPath);
   if (bump.stderr && !bump.stdout) {
-    console.error(chalk.red('❌ npm version failed:'), bump.stderr);
-    process.exit(1);
+    logError(io, chalk.red('❌ npm version failed:'), bump.stderr);
+    return gateFail('version-bump', `npm version ${bumpType} failed: ${bump.stderr.slice(0, 200)}`);
   }
   const newVersion = bump.stdout.trim().replace(/^v/, '');
   const tag = `v${newVersion}`;
-  console.log(chalk.green(`✅ version: ${oldVersion} → ${newVersion} (committed + tagged)`));
+  log(io, chalk.green(`✅ version: ${oldVersion} → ${newVersion} (committed + tagged)`));
 
   // ── 6. Push (handle protected branch via PR) ──
-  console.log(chalk.cyan('⬆️  Pushing...'));
+  log(io, chalk.cyan('⬆️  Pushing...'));
   const push = await run(`git push origin ${currentBranch}`, pkgPath, 30_000);
   const isProtected = push.stderr.includes('GH006') || push.stderr.includes('protected branch');
 
   if (isProtected) {
     // Protected branch: create release branch + PR
     const releaseBranch = `release/v${newVersion}`;
-    console.log(chalk.yellow(`⚠️  ${currentBranch} is protected. Creating PR via ${releaseBranch}...`));
+    log(io, chalk.yellow(`⚠️  ${currentBranch} is protected. Creating PR via ${releaseBranch}...`));
 
     await run(`git checkout -b ${releaseBranch}`, pkgPath);
     await run(`git push origin ${releaseBranch}`, pkgPath, 30_000);
@@ -151,59 +161,59 @@ export async function release(options: ReleaseOptions): Promise<void> {
     const prBody = `## Release ${pkgName}@${newVersion}\n\n- Bump version: ${oldVersion} → ${newVersion}\n- Changelog updated\n\nAfter merge, push tag to trigger npm publish:\n\`\`\`\ngit push origin ${tag}\n\`\`\``;
     const pr = await run(`gh pr create --title "release: ${pkgName}@${newVersion}" --body "${prBody}" --base ${currentBranch}`, pkgPath, 30_000);
     if (pr.stdout) {
-      console.log(chalk.green(`✅ PR created: ${pr.stdout.trim()}`));
+      log(io, chalk.green(`✅ PR created: ${pr.stdout.trim()}`));
     } else {
-      console.error(chalk.red('❌ PR creation failed:'), pr.stderr.slice(0, 500));
-      process.exit(1);
+      logError(io, chalk.red('❌ PR creation failed:'), pr.stderr.slice(0, 500));
+      return gateFail('pr-create', `gh pr create failed: ${pr.stderr.slice(0, 200)}`);
     }
 
     // Switch back to original branch
     await run(`git checkout ${currentBranch}`, pkgPath);
 
-    console.log(chalk.cyan('\n📋 Next steps:'));
-    console.log(chalk.gray(`   1. Merge the PR: ${pr.stdout.trim()}`));
-    console.log(chalk.gray(`   2. After merge, push tag to trigger npm publish:`));
-    console.log(chalk.gray(`      git push origin ${tag}`));
-    console.log(chalk.gray(`   3. Or run: gh release create ${tag} --generate-notes`));
-    return;
+    log(io, chalk.cyan('\n📋 Next steps:'));
+    log(io, chalk.gray(`   1. Merge the PR: ${pr.stdout.trim()}`));
+    log(io, chalk.gray(`   2. After merge, push tag to trigger npm publish:`));
+    log(io, chalk.gray(`      git push origin ${tag}`));
+    log(io, chalk.gray(`   3. Or run: gh release create ${tag} --generate-notes`));
+    return { kind: 'ok' };
   }
 
   if (push.stderr && push.stderr.includes('error')) {
-    console.error(chalk.red('❌ git push failed:'), push.stderr.slice(0, 500));
-    process.exit(1);
+    logError(io, chalk.red('❌ git push failed:'), push.stderr.slice(0, 500));
+    return gateFail('git-push', `git push origin ${currentBranch} failed: ${push.stderr.slice(0, 200)}`);
   }
   await run(`git push origin ${tag}`, pkgPath, 30_000);
-  console.log(chalk.green('✅ git: pushed'));
+  log(io, chalk.green('✅ git: pushed'));
 
   // ── 7. Check private flag ──
   if (pkgJson.private) {
-    console.error(chalk.red('❌ package.json has "private": true. Remove it before publishing.'));
-    console.error(chalk.gray('   The release tool will NOT auto-remove private flag.'));
-    process.exit(1);
+    logError(io, chalk.red('❌ package.json has "private": true. Remove it before publishing.'));
+    logError(io, chalk.gray('   The release tool will NOT auto-remove private flag.'));
+    return gateFail('private-flag', 'package.json has "private": true');
   }
-  console.log(chalk.green('✅ package: not private'));
+  log(io, chalk.green('✅ package: not private'));
 
   // ── 8. npm publish ──
   const origRegistry = await run('npm config get registry', pkgPath);
   await run('npm config set registry https://registry.npmjs.org/', pkgPath);
-  console.log(chalk.cyan('📤 Publishing to npm...'));
+  log(io, chalk.cyan('📤 Publishing to npm...'));
   await run('npm publish --registry https://registry.npmjs.org/', pkgPath, 180_000);
   await run(`npm config set registry ${origRegistry.stdout}`, pkgPath);
   const verify = await run(`npm view ${pkgName} version --registry https://registry.npmjs.org/`, pkgPath);
   if (verify.stdout.trim() === newVersion) {
-    console.log(chalk.green(`✅ npm: published ${pkgName}@${newVersion}`));
+    log(io, chalk.green(`✅ npm: published ${pkgName}@${newVersion}`));
   } else {
-    console.error(chalk.red(`❌ npm publish verification failed. Expected ${newVersion}, registry has ${verify.stdout.trim() || '???'}`));
-    process.exit(1);
+    logError(io, chalk.red(`❌ npm publish verification failed. Expected ${newVersion}, registry has ${verify.stdout.trim() || '???'}`));
+    return gateFail('npm-publish-verify', `expected ${newVersion}, registry has ${verify.stdout.trim() || '???'}`);
   }
 
   // ── 9. GitHub Release ──
-  console.log(chalk.cyan('🐙 Creating GitHub Release...'));
+  log(io, chalk.cyan('🐙 Creating GitHub Release...'));
   const gh = await run(`gh release create ${tag} --generate-notes`, pkgPath, 30_000);
   if (gh.stderr && gh.stderr.includes('already exists')) {
-    console.log(chalk.yellow(`⚠️  gh: release ${tag} already exists`));
+    log(io, chalk.yellow(`⚠️  gh: release ${tag} already exists`));
   } else if (gh.stderr) {
-    console.log(chalk.yellow(`⚠️  gh: release may have failed (non-fatal): ${gh.stderr.slice(0, 200)}`));
+    log(io, chalk.yellow(`⚠️  gh: release may have failed (non-fatal): ${gh.stderr.slice(0, 200)}`));
   } else {
     let repoUrl = '';
     try {
@@ -211,9 +221,10 @@ export async function release(options: ReleaseOptions): Promise<void> {
       const m = remoteUrl.match(/github\.com[:/]([^/]+)\/([^/\s.]+?)(?:\.git)?$/);
       if (m) repoUrl = `https://github.com/${m[1]}/${m[2]}/releases/tag/${tag}`;
     } catch { /* no remote */ }
-    console.log(chalk.green(`✅ GitHub Release: ${repoUrl || tag}`));
+    log(io, chalk.green(`✅ GitHub Release: ${repoUrl || tag}`));
   }
 
-  console.log(chalk.green(`\n🎉 Released ${pkgName}@${newVersion}`));
-  console.log(chalk.gray(`   npm: https://www.npmjs.com/package/${pkgName}/v/${newVersion}`));
+  log(io, chalk.green(`\n🎉 Released ${pkgName}@${newVersion}`));
+  log(io, chalk.gray(`   npm: https://www.npmjs.com/package/${pkgName}/v/${newVersion}`));
+  return { kind: 'ok' };
 }