@dommaker/harness 1.3.0 → 1.4.0

package/src/cli/commands/report.ts

@@ -9,7 +9,9 @@ import * as fs from 'fs/promises';
 import { ConstraintChecker } from '../../core/constraints/checker';
 import { IRON_LAWS, GUIDELINES, PROMPTS } from '../../core/constraints/definitions';
 import { executeWithCollect } from '../../failure/constraint-handler';
+import { getTraceCollector } from '../../monitoring/traces';
 import type { ConstraintContext } from '../../types/constraint';
+import { log, processIO, type CommandIO, type CommandResult } from '../command-contract';
 
 export interface ReportOptions {
   /** 输出文件路径 */
@@ -42,11 +44,12 @@ interface ReportData {
 /**
  * 生成检查报告
  */
-export async function report(options: ReportOptions): Promise<void> {
-  console.log(chalk.blue('📊 生成检查报告...'));
+export async function report(options: ReportOptions, io: CommandIO = processIO): Promise<CommandResult> {
+  log(io, chalk.blue('📊 生成检查报告...'));
 
   const projectPath = options.projectPath || process.cwd();
-  const checker = ConstraintChecker.getInstance();
+  // trace 记录器经构造参数接线（harness#88）：本命令是组合根
+  const checker = new ConstraintChecker(getTraceCollector());
 
   const allConstraints = { ...IRON_LAWS, ...GUIDELINES, ...PROMPTS };
   const totalConstraints = Object.keys(allConstraints).length;
@@ -105,10 +108,11 @@ export async function report(options: ReportOptions): Promise<void> {
 
   if (options.output) {
     await fs.writeFile(options.output, content, 'utf-8');
-    console.log(chalk.green(`✅ 报告已保存到: ${options.output}`));
+    log(io, chalk.green(`✅ 报告已保存到: ${options.output}`));
   } else {
-    console.log(content);
+    log(io, content);
   }
+  return { kind: 'ok' };
 }
 
 function generateMarkdownReport(data: ReportData): string {

package/src/cli/commands/review.ts

@@ -7,6 +7,7 @@
 import chalk from 'chalk';
 import { execAsync } from '../../utils/exec';
 import { ReviewGate } from '../../gates/review';
+import { log, processIO, type CommandIO, type CommandResult } from '../command-contract';
 
 export interface ReviewOptions {
   /** 项目路径 */
@@ -24,8 +25,11 @@ export interface ReviewOptions {
 /**
  * 执行审查门控
  */
-export async function review(options: ReviewOptions): Promise<void> {
-  console.log(chalk.blue('👀 代码审查门控检查...'));
+export async function review(
+  options: ReviewOptions,
+  io: CommandIO = processIO,
+): Promise<CommandResult> {
+  log(io, chalk.blue('👀 代码审查门控检查...'));
 
   const projectPath = options.projectPath || process.cwd();
 
@@ -40,49 +44,53 @@ export async function review(options: ReviewOptions): Promise<void> {
 
   try {
     const { stdout: branch } = await execAsync('git rev-parse --abbrev-ref HEAD', { cwd: projectPath });
-    console.log(chalk.gray(`当前分支: ${branch.trim()}`));
+    log(io, chalk.gray(`当前分支: ${branch.trim()}`));
 
     const result = await gate.check({ projectPath, projectId: 'default' });
 
-    console.log();
+    log(io);
     if (result.passed) {
-      console.log(chalk.green('✅ 代码审查门控检查通过'));
+      log(io, chalk.green('✅ 代码审查门控检查通过'));
       if (result.details) {
-        console.log(chalk.gray(`   审批: ${result.details.approvals ?? 0}, 变更请求: ${result.details.changesRequested ?? 0}`));
+        log(io, chalk.gray(`   审批: ${result.details.approvals ?? 0}, 变更请求: ${result.details.changesRequested ?? 0}`));
       }
     } else {
-      console.log(chalk.red('❌ 代码审查门控检查失败'));
-      console.log(chalk.red(`   ${result.message}`));
+      log(io, chalk.red('❌ 代码审查门控检查失败'));
+      log(io, chalk.red(`   ${result.message}`));
       if (result.details?.suggestion) {
-        console.log(chalk.gray(`   ${result.details.suggestion}`));
+        log(io, chalk.gray(`   ${result.details.suggestion}`));
       }
-      process.exit(1);
+      return { kind: 'fail', reason: `review gate denied: ${result.message}` };
     }
+    return { kind: 'ok' };
   } catch (error: any) {
-    console.log();
-    console.log(chalk.red('❌ 代码审查门控检查出错'));
-    console.log(chalk.red(`   ${error.message}`));
+    log(io);
+    log(io, chalk.red('❌ 代码审查门控检查出错'));
+    log(io, chalk.red(`   ${error.message}`));
 
     if (error.message.includes('not a git repository')) {
-      console.log();
-      console.log(chalk.gray('提示: 此命令需要在 Git 仓库中运行'));
+      log(io);
+      log(io, chalk.gray('提示: 此命令需要在 Git 仓库中运行'));
     }
 
-    process.exit(1);
+    return { kind: 'fail', reason: `review gate error: ${error.message}` };
   }
 }
 
 /**
  * 显示审查状态详情
  */
-export async function reviewStatus(options: ReviewOptions): Promise<void> {
-  console.log(chalk.blue('👀 代码审查状态...\n'));
+export async function reviewStatus(
+  options: ReviewOptions,
+  io: CommandIO = processIO,
+): Promise<CommandResult> {
+  log(io, chalk.blue('👀 代码审查状态...\n'));
 
   const projectPath = options.projectPath || process.cwd();
 
   try {
     const { stdout: branch } = await execAsync('git rev-parse --abbrev-ref HEAD', { cwd: projectPath });
-    console.log(chalk.gray(`当前分支: ${branch.trim()}`));
+    log(io, chalk.gray(`当前分支: ${branch.trim()}`));
 
     try {
       const { stdout: prInfo } = await execAsync('gh pr view --json number,title,state,reviewDecision,reviews', {
@@ -90,29 +98,31 @@ export async function reviewStatus(options: ReviewOptions): Promise<void> {
       });
       const pr = JSON.parse(prInfo);
 
-      console.log();
-      console.log(chalk.cyan(`PR #${pr.number}: ${pr.title}`));
-      console.log(chalk.gray(`状态: ${pr.state}`));
+      log(io);
+      log(io, chalk.cyan(`PR #${pr.number}: ${pr.title}`));
+      log(io, chalk.gray(`状态: ${pr.state}`));
 
       if (pr.reviewDecision) {
         const decisionColor = pr.reviewDecision === 'APPROVED' ? chalk.green : chalk.yellow;
-        console.log(decisionColor(`审查决策: ${pr.reviewDecision}`));
+        log(io, decisionColor(`审查决策: ${pr.reviewDecision}`));
       }
 
       if (pr.reviews && pr.reviews.length > 0) {
-        console.log();
-        console.log(chalk.gray('审查历史:'));
+        log(io);
+        log(io, chalk.gray('审查历史:'));
         pr.reviews.forEach((r: any) => {
           const statusColor = r.state === 'APPROVED' ? chalk.green :
                               r.state === 'CHANGES_REQUESTED' ? chalk.red : chalk.gray;
-          console.log(statusColor(`  - ${r.author?.login || 'unknown'}: ${r.state}`));
+          log(io, statusColor(`  - ${r.author?.login || 'unknown'}: ${r.state}`));
         });
       }
     } catch {
-      console.log(chalk.yellow('\n⚠️  未找到关联的 PR'));
-      console.log(chalk.gray('   使用 gh pr create 创建 PR'));
+      log(io, chalk.yellow('\n⚠️  未找到关联的 PR'));
+      log(io, chalk.gray('   使用 gh pr create 创建 PR'));
     }
+    return { kind: 'ok' };
   } catch (error: any) {
-    console.log(chalk.red(`❌ 获取审查状态失败: ${error.message}`));
+    log(io, chalk.red(`❌ 获取审查状态失败: ${error.message}`));
+    return { kind: 'skip', reason: `获取审查状态失败: ${error.message}` };
   }
 }

package/src/cli/commands/sdd.ts

@@ -2,6 +2,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { SDDIndexGenerator } from '../../sdd/index-generator';
+import { log, processIO, type CommandIO, type CommandResult } from '../command-contract';
 
 export interface SDDOptions {
   projectPath?: string;
@@ -14,7 +15,7 @@ function getSDDDir(projectPath?: string): string {
   return base;
 }
 
-export function sddIndex(options: SDDOptions & { dir?: string }): void {
+export function sddIndex(options: SDDOptions & { dir?: string }, io: CommandIO = processIO): CommandResult {
   const baseDir = options.dir || getSDDDir(options.projectPath);
   const gen = new SDDIndexGenerator(baseDir);
 
@@ -30,15 +31,16 @@ export function sddIndex(options: SDDOptions & { dir?: string }): void {
   );
 
   if (options.json) {
-    console.log(JSON.stringify({
+    log(io, JSON.stringify({
       path: indexPath,
       entries: result.count,
       size: afterSize,
       previousSize: beforeSize,
     }));
   } else {
-    console.log(`SDD Index regenerated: ${indexPath}`);
-    console.log(`  Entries: ${result.count}`);
-    console.log(`  Size: ${beforeSize} → ${afterSize} bytes`);
+    log(io, `SDD Index regenerated: ${indexPath}`);
+    log(io, `  Entries: ${result.count}`);
+    log(io, `  Size: ${beforeSize} → ${afterSize} bytes`);
   }
+  return { kind: 'ok' };
 }

package/src/cli/commands/security.ts

@@ -6,6 +6,7 @@
 
 import chalk from 'chalk';
 import { SecurityGate } from '../../gates/security';
+import { log, processIO, type CommandIO, type CommandResult } from '../command-contract';
 
 export interface SecurityOptions {
   /** 项目路径 */
@@ -23,8 +24,11 @@ export interface SecurityOptions {
 /**
  * 执行安全门控
  */
-export async function security(options: SecurityOptions): Promise<void> {
-  console.log(chalk.blue('🔒 安全门控检查...'));
+export async function security(
+  options: SecurityOptions,
+  io: CommandIO = processIO,
+): Promise<CommandResult> {
+  log(io, chalk.blue('🔒 安全门控检查...'));
 
   try {
     const projectPath = options.projectPath || process.cwd();
@@ -38,30 +42,31 @@ export async function security(options: SecurityOptions): Promise<void> {
 
     const result = await gate.scan({ projectPath, projectId: 'default' });
 
-    console.log();
+    log(io);
     if (result.passed) {
-      console.log(chalk.green('✅ 安全门控检查通过'));
+      log(io, chalk.green('✅ 安全门控检查通过'));
       if (result.details) {
-        console.log(chalk.gray(`   critical: ${result.details.critical}, high: ${result.details.high}, moderate: ${result.details.moderate}, low: ${result.details.low}`));
+        log(io, chalk.gray(`   critical: ${result.details.critical}, high: ${result.details.high}, moderate: ${result.details.moderate}, low: ${result.details.low}`));
       }
     } else {
-      console.log(chalk.red('❌ 安全门控检查失败'));
-      console.log(chalk.red(`   ${result.message}`));
+      log(io, chalk.red('❌ 安全门控检查失败'));
+      log(io, chalk.red(`   ${result.message}`));
       if (result.details?.vulnerabilities) {
-        console.log();
+        log(io);
         (result.details.vulnerabilities as Array<{ name: string; severity: string; via: string }>).forEach((v, i) => {
           const severityColor = getSeverityColor(v.severity);
-          console.log(severityColor(`  ${i + 1}. [${v.severity.toUpperCase()}] ${v.name}`));
-          console.log(chalk.gray(`     via: ${v.via}`));
+          log(io, severityColor(`  ${i + 1}. [${v.severity.toUpperCase()}] ${v.name}`));
+          log(io, chalk.gray(`     via: ${v.via}`));
         });
       }
-      console.log(chalk.gray('\n   运行 harness security audit 查看详情'));
-      process.exit(1);
+      log(io, chalk.gray('\n   运行 harness security audit 查看详情'));
+      return { kind: 'fail', reason: `security gate denied (threshold ${options.severity || 'high'}): ${result.message}` };
     }
+    return { kind: 'ok' };
   } catch (error) {
-    console.log();
-    console.log(chalk.red(`❌ 安全检查异常: ${error instanceof Error ? error.message : String(error)}`));
-    process.exit(1);
+    log(io);
+    log(io, chalk.red(`❌ 安全检查异常: ${error instanceof Error ? error.message : String(error)}`));
+    return { kind: 'fail', reason: `security scan error: ${error instanceof Error ? error.message : String(error)}` };
   }
 }
 
@@ -86,8 +91,11 @@ function getSeverityColor(severity: string): (text: string) => string {
 /**
  * 运行安全审计详情
  */
-export async function auditDetails(options: SecurityOptions): Promise<void> {
-  console.log(chalk.blue('🔒 安全审计详情...\n'));
+export async function auditDetails(
+  options: SecurityOptions,
+  io: CommandIO = processIO,
+): Promise<CommandResult> {
+  log(io, chalk.blue('🔒 安全审计详情...\n'));
 
   try {
     const projectPath = options.projectPath || process.cwd();
@@ -100,23 +108,24 @@ export async function auditDetails(options: SecurityOptions): Promise<void> {
     const result = await gate.scan({ projectPath, projectId: 'default' });
 
     if (result.passed && !result.details?.total) {
-      console.log(chalk.green('✅ 未发现安全漏洞'));
-      return;
+      log(io, chalk.green('✅ 未发现安全漏洞'));
+      return { kind: 'ok' };
     }
 
     const details = result.details as any;
     if (details?.vulnerabilities?.length > 0) {
-      console.log(chalk.yellow(`发现 ${details.total} 个漏洞:\n`));
+      log(io, chalk.yellow(`发现 ${details.total} 个漏洞:\n`));
       for (const v of details.vulnerabilities) {
         const severityColor = getSeverityColor(v.severity);
-        console.log(severityColor(`[${v.severity.toUpperCase()}] ${v.name}`));
-        console.log(chalk.gray(`  via: ${v.via}`));
-        console.log();
+        log(io, severityColor(`[${v.severity.toUpperCase()}] ${v.name}`));
+        log(io, chalk.gray(`  via: ${v.via}`));
+        log(io);
       }
     }
+    return { kind: 'ok' };
   } catch (error) {
-    console.log();
-    console.log(chalk.red(`❌ 安全审计异常: ${error instanceof Error ? error.message : String(error)}`));
-    process.exit(1);
+    log(io);
+    log(io, chalk.red(`❌ 安全审计异常: ${error instanceof Error ? error.message : String(error)}`));
+    return { kind: 'fail', reason: `security audit error: ${error instanceof Error ? error.message : String(error)}` };
   }
 }

package/src/cli/commands/spec-baseline-check.ts

@@ -8,6 +8,7 @@
 import chalk from 'chalk';
 import * as fs from 'fs';
 import * as path from 'path';
+import { log, logError, processIO, type CommandIO, type CommandResult } from '../command-contract';
 import { walkFiles } from '../../utils/file-walk';
 
 export interface SpecBaselineCheckOptions {
@@ -333,13 +334,13 @@ function formatTable(results: PrerequisiteResult[]): string {
 export async function specBaselineCheck(
   specPath: string,
   options: SpecBaselineCheckOptions = {},
-): Promise<void> {
+  io: CommandIO = processIO,
+): Promise<CommandResult> {
   // 验证文件存在
   const resolvedPath = path.resolve(specPath);
   if (!fs.existsSync(resolvedPath)) {
-    console.error(chalk.red(`文件不存在: ${resolvedPath}`));
-    process.exitCode = 1;
-    return;
+    logError(io, chalk.red(`文件不存在: ${resolvedPath}`));
+    return { kind: 'usage-error', reason: `spec 文件不存在: ${resolvedPath}` };
   }
 
   const projectPath = options.projectPath || path.dirname(resolvedPath);
@@ -352,11 +353,11 @@ export async function specBaselineCheck(
 
   if (prerequisites.length === 0) {
     if (options.json) {
-      console.log(JSON.stringify({ prerequisites: [], message: '未找到 Baseline / 前置条件 section' }, null, 2));
+      log(io, JSON.stringify({ prerequisites: [], message: '未找到 Baseline / 前置条件 section' }, null, 2));
     } else {
-      console.log(chalk.yellow('未找到 ## Baseline 或 ## 前置条件 section'));
+      log(io, chalk.yellow('未找到 ## Baseline 或 ## 前置条件 section'));
     }
-    return;
+    return { kind: 'skip', reason: '未找到 Baseline / 前置条件 section，无可判定项' };
   }
 
   // 验证每条前置条件
@@ -364,14 +365,18 @@ export async function specBaselineCheck(
 
   // 输出
   if (options.json) {
-    console.log(JSON.stringify(results, null, 2));
+    log(io, JSON.stringify(results, null, 2));
   } else {
-    console.log(formatTable(results));
+    log(io, formatTable(results));
   }
 
-  // 有未满足的前置条件时 exit 1
+  // 有未满足的前置条件时非零退出
   const failed = results.filter(r => !r.satisfied);
   if (failed.length > 0) {
-    process.exitCode = 1;
+    return {
+      kind: 'fail',
+      reason: `${failed.length} 条前置条件未满足: ${failed.map(f => f.prerequisite).join('; ')}`,
+    };
   }
+  return { kind: 'ok' };
 }

package/src/cli/commands/spec.ts

@@ -1,18 +1,22 @@
 /**
  * harness spec validate 命令
- * 
+ *
  * 验证 Spec 文件格式
- * 
+ *
  * 设计原则：
  * - 框架不包含具体 Schema 定义
  * - 项目需要定义自己的 Spec Schema
  * - 支持动态加载项目的 Schema
+ *
+ * 判定经返回值外溢（架构评审候选7）：批量验证的失败计数译成 fail（含失败数），
+ * 无 Spec 文件译成 skip；单文件验证维持历史退出码面（无效仍为 0）。
  */
 
 import chalk from 'chalk';
 import * as path from 'path';
 import { SpecValidator, validateAllSpecs } from '../../core/spec/validator';
 import type { BatchSpecValidationResult, SpecValidationResult } from '../../types/spec';
+import { log, processIO, type CommandIO, type CommandResult } from '../command-contract';
 
 export interface SpecValidateOptions {
   /** Schema 路径（项目定义） */
@@ -30,8 +34,11 @@ export interface SpecValidateOptions {
 /**
  * 执行 Spec 验证
  */
-export async function specValidate(options: SpecValidateOptions): Promise<void> {
-  console.log(chalk.blue('📋 验证 Spec 文件...'));
+export async function specValidate(
+  options: SpecValidateOptions,
+  io: CommandIO = processIO,
+): Promise<CommandResult> {
+  log(io, chalk.blue('📋 验证 Spec 文件...'));
 
   const projectPath = options.projectPath || process.cwd();
   const validator = SpecValidator.getInstance();
@@ -40,7 +47,7 @@ export async function specValidate(options: SpecValidateOptions): Promise<void>
   if (options.schema) {
     const absoluteSchemaPath = path.resolve(projectPath, options.schema);
     validator.setConfig({ schemaPath: absoluteSchemaPath });
-    console.log(chalk.gray(`Schema 路径: ${absoluteSchemaPath}`));
+    log(io, chalk.gray(`Schema 路径: ${absoluteSchemaPath}`));
   }
 
   let result: BatchSpecValidationResult | SpecValidationResult;
@@ -48,59 +55,63 @@ export async function specValidate(options: SpecValidateOptions): Promise<void>
   // 单文件验证
   if (options.file) {
     const absoluteFilePath = path.resolve(projectPath, options.file);
-    console.log(chalk.gray(`验证文件: ${absoluteFilePath}`));
+    log(io, chalk.gray(`验证文件: ${absoluteFilePath}`));
     result = await validator.validateFile(absoluteFilePath);
-    printSingleResult(result, options.verbose);
-    return;
+    printSingleResult(result, io, options.verbose);
+    return { kind: 'ok' };
   }
 
   // 批量验证
-  console.log(chalk.gray(`项目路径: ${projectPath}`));
-  console.log(chalk.gray(`仅暂存: ${options.staged ? '是' : '否'}`));
-  console.log();
+  log(io, chalk.gray(`项目路径: ${projectPath}`));
+  log(io, chalk.gray(`仅暂存: ${options.staged ? '是' : '否'}`));
+  log(io);
 
   result = await validateAllSpecs(projectPath, options.staged);
 
   // 打印结果
-  printBatchResult(result, options.verbose);
+  printBatchResult(result, io, options.verbose);
 
   // 根据失败级别决定退出码
   if (!options.staged && result.failed > 0) {
-    process.exitCode = 1;
+    return { kind: 'fail', reason: `${result.failed} 个 Spec 文件验证失败` };
   }
+  if (result.total === 0) {
+    return { kind: 'skip', reason: '没有找到 Spec 文件' };
+  }
+  return { kind: 'ok' };
 }
 
 /**
  * 打印单个文件验证结果
  */
-function printSingleResult(result: SpecValidationResult, verbose?: boolean): void {
+function printSingleResult(result: SpecValidationResult, io: CommandIO, verbose?: boolean): void {
   if (result.valid) {
-    console.log(chalk.green(`✅ ${result.file} 验证通过`));
+    log(io, chalk.green(`✅ ${result.file} 验证通过`));
   } else {
-    console.log(chalk.red(`❌ ${result.file} 验证失败`));
+    log(io, chalk.red(`❌ ${result.file} 验证失败`));
   }
 
   if (result.errors.length > 0) {
-    console.log();
-    console.log(chalk.red('错误:'));
+    log(io);
+    log(io, chalk.red('错误:'));
     for (const error of result.errors) {
-      console.log(chalk.red(`  - ${error.path ? error.path + ': ' : ''}${error.message}`));
+      log(io, chalk.red(`  - ${error.path ? error.path + ': ' : ''}${error.message}`));
     }
   }
 
   if (result.warnings.length > 0) {
-    console.log();
-    console.log(chalk.yellow('警告:'));
+    log(io);
+    log(io, chalk.yellow('警告:'));
     for (const warning of result.warnings) {
-      console.log(chalk.yellow(`  - ${warning.path ? warning.path + ': ' : ''}${warning.message}`));
+      log(io, chalk.yellow(`  - ${warning.path ? warning.path + ': ' : ''}${warning.message}`));
     }
   }
 
   if (verbose && result.metrics) {
-    console.log();
-    console.log(chalk.gray('指标:'));
+    log(io);
+    log(io, chalk.gray('指标:'));
     for (const [key, value] of Object.entries(result.metrics)) {
-      console.log(chalk.gray(`  - ${key}: ${value}`));
+      log(io, chalk.gray(`  - ${key}: ${value}`));
     }
   }
 }
@@ -108,51 +119,53 @@ function printSingleResult(result: SpecValidationResult, verbose?: boolean): voi
 /**
  * 打印批量验证结果
  */
-function printBatchResult(result: BatchSpecValidationResult, verbose?: boolean): void {
+function printBatchResult(result: BatchSpecValidationResult, io: CommandIO, verbose?: boolean): void {
   // 汇总
-  console.log(chalk.bold('验证结果:'));
-  console.log(chalk.gray(`  总文件数: ${result.total}`));
-  console.log(chalk.green(`  通过: ${result.passed}`));
-  console.log(chalk.red(`  失败: ${result.failed}`));
-  console.log(chalk.yellow(`  警告: ${result.warnings}`));
-  console.log();
+  log(io, chalk.bold('验证结果:'));
+  log(io, chalk.gray(`  总文件数: ${result.total}`));
+  log(io, chalk.green(`  通过: ${result.passed}`));
+  log(io, chalk.red(`  失败: ${result.failed}`));
+  log(io, chalk.yellow(`  警告: ${result.warnings}`));
+  log(io);
 
   // 详细结果
   if (verbose || result.failed > 0) {
     for (const r of result.results) {
       if (!r.valid || verbose) {
-        printSingleResult(r, verbose);
-        console.log();
+        printSingleResult(r, io, verbose);
+        log(io);
       }
     }
   }
 
   // 成功提示
   if (result.failed === 0 && result.total > 0) {
-    console.log(chalk.green('✅ 所有 Spec 文件验证通过'));
+    log(io, chalk.green('✅ 所有 Spec 文件验证通过'));
   } else if (result.total === 0) {
-    console.log(chalk.gray('没有找到 Spec 文件，跳过验证'));
-    console.log();
-    console.log(chalk.gray('提示: Spec 文件包括:'));
-    console.log(chalk.gray('  - ARCHITECTURE.md'));
-    console.log(chalk.gray('  - specs/ 目录下的 .yml/.yaml 文件'));
-    console.log();
-    console.log(chalk.gray('要定义自己的 Schema，请在项目中创建:'));
-    console.log(chalk.gray('  src/specs/schemas/index.ts'));
-    console.log(chalk.gray('  导出 validate 函数'));
+    log(io, chalk.gray('没有找到 Spec 文件，跳过验证'));
+    log(io);
+    log(io, chalk.gray('提示: Spec 文件包括:'));
+    log(io, chalk.gray('  - ARCHITECTURE.md'));
+    log(io, chalk.gray('  - specs/ 目录下的 .yml/.yaml 文件'));
+    log(io);
+    log(io, chalk.gray('要定义自己的 Schema，请在项目中创建:'));
+    log(io, chalk.gray('  src/specs/schemas/index.ts'));
+    log(io, chalk.gray('  导出 validate 函数'));
   }
 }
 
 /**
  * 列出支持的 Spec 类型
  */
-export function listSpecTypes(): void {
-  console.log(chalk.blue('📋 支持的 Spec 类型:'));
-  console.log();
-  console.log('  architecture  - ARCHITECTURE.md 架构文档');
-  console.log('  module        - 模块定义（specs/modules/*.yml）');
-  console.log('  api           - API 定义（specs/apis/*.yml）');
-  console.log('  custom        - 自定义 Spec');
-  console.log();
-  console.log(chalk.gray('提示: 项目可以定义自己的 Schema 进行验证'));
+/** 子命令实现一律以 (options) 调用；list 不消费验证选项，形参仅占位 */
+export function listSpecTypes(_options: Partial<SpecValidateOptions> = {}, io: CommandIO = processIO): CommandResult {
+  log(io, chalk.blue('📋 支持的 Spec 类型:'));
+  log(io);
+  log(io, '  architecture  - ARCHITECTURE.md 架构文档');
+  log(io, '  module        - 模块定义（specs/modules/*.yml）');
+  log(io, '  api           - API 定义（specs/apis/*.yml）');
+  log(io, '  custom        - 自定义 Spec');
+  log(io);
+  log(io, chalk.gray('提示: 项目可以定义自己的 Schema 进行验证'));
+  return { kind: 'ok' };
 }