@winspan/claude-forge 8.41.0 → 8.51.0

package/scripts/e2e-mcp-link.ts

@@ -0,0 +1,423 @@
+#!/usr/bin/env tsx
+/**
+ * E2E Verification: MCP call chain → skill_invoke → DB persistence
+ *
+ * Black-box verification of the full pipeline:
+ *
+ *   MCP Client (this script)
+ *     → HTTP POST /mcp (Bearer auth)
+ *     → StreamableHTTPServerTransport
+ *     → McpServer.callTool('skill_invoke' / 'skill_list')
+ *     → skillInvoke() / skillList()
+ *     → SQLiteStorage.writeSkillInvocation()
+ *
+ * Steps:
+ *   1. Start a standalone WebServer (independent of system daemon)
+ *   2. Use MCP SDK Client to connect via HTTP
+ *   3. Call skill_invoke / skill_list
+ *   4. Query SQLite directly to verify skill_invocations table
+ *   5. Print verification report
+ *
+ * Isolation: temp dir for DB, swaps in test daemon.token (restored on exit).
+ */
+
+import { mkdtempSync, rmSync, writeFileSync, readFileSync, existsSync, mkdirSync, unlinkSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { AddressInfo } from 'node:net';
+
+import { SQLiteStorage } from '../src/core/storage/sqlite.js';
+import { RuleEngine } from '../src/engine/rule-engine.js';
+import { SkillRegistry } from '../src/skills/registry.js';
+import { InvocationGuard } from '../src/skills/invocation-guard.js';
+import { WebServer } from '../src/web/server.js';
+import { FORGE_PATHS } from '../src/core/constants.js';
+import { routingState } from '../src/daemon/routing-state.js';
+
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+
+// ─── Test infra ────────────────────────────────────────────────────────────
+
+const TEST_TOKEN = `e2e-mcp-token-${Date.now()}`;
+const TOKEN_FILE = join(FORGE_PATHS.home(), 'daemon.token');
+
+const tmp = mkdtempSync(join(tmpdir(), 'forge-e2e-mcp-'));
+const dbPath = join(tmp, 'data.db');
+
+interface TestResult {
+  step: string;
+  pass: boolean;
+  details: string;
+}
+const results: TestResult[] = [];
+function record(step: string, pass: boolean, details: string): void {
+  results.push({ step, pass, details });
+  const mark = pass ? 'PASS' : 'FAIL';
+  console.log(`[${mark}] ${step}: ${details}`);
+}
+
+// Backup user's daemon.token, install test token (mirrors mcp-server.test.ts pattern).
+let backupToken: string | null = null;
+function installTestToken(): void {
+  if (existsSync(TOKEN_FILE)) {
+    backupToken = readFileSync(TOKEN_FILE, 'utf-8');
+  } else {
+    backupToken = null;
+    mkdirSync(FORGE_PATHS.home(), { recursive: true });
+  }
+  writeFileSync(TOKEN_FILE, TEST_TOKEN, { mode: 0o600 });
+}
+function restoreTestToken(): void {
+  if (backupToken !== null) {
+    writeFileSync(TOKEN_FILE, backupToken, { mode: 0o600 });
+  } else if (existsSync(TOKEN_FILE)) {
+    unlinkSync(TOKEN_FILE);
+  }
+}
+
+function authHeaders(extra: Record<string, string> = {}): Record<string, string> {
+  return { Authorization: `Bearer ${TEST_TOKEN}`, ...extra };
+}
+
+async function newClient(port: number, headers: Record<string, string>): Promise<Client> {
+  const transport = new StreamableHTTPClientTransport(new URL(`http://127.0.0.1:${port}/mcp`), {
+    requestInit: { headers },
+  });
+  const client = new Client({ name: 'forge-e2e-client', version: '1.0.0' });
+  await client.connect(transport);
+  return client;
+}
+
+// ─── Main ──────────────────────────────────────────────────────────────────
+
+async function main(): Promise<void> {
+  console.log('=== E2E MCP Link Verification ===\n');
+  console.log(`tmp dir: ${tmp}`);
+  console.log(`db:      ${dbPath}`);
+  console.log(`token:   ${TEST_TOKEN}\n`);
+
+  installTestToken();
+
+  const storage = new SQLiteStorage(dbPath);
+  const ruleEngine = new RuleEngine();
+  const skillRegistry = new SkillRegistry();
+  const guard = new InvocationGuard();
+
+  const allSkills = skillRegistry.getAll();
+  console.log(`Registry loaded ${allSkills.length} skills`);
+
+  // ── Start WebServer ──────────────────────────────────────────────────────
+  const server = new WebServer({
+    port: 0,
+    storage,
+    ruleEngine,
+    skillRegistry,
+    invocationGuard: guard,
+  });
+
+  // Pull the express app out and listen on a random port (matches mcp-server.test.ts).
+  const app = (server as unknown as { app: import('express').Application }).app;
+  const port: number = await new Promise<number>((resolve) => {
+    const handle = app.listen(0, () => {
+      const addr = handle.address() as AddressInfo;
+      // Also give server.server back so afterEach-style cleanup keeps a handle.
+      (server as unknown as { server: ReturnType<typeof app.listen> | null }).server = handle;
+      resolve(addr.port);
+    });
+  });
+  console.log(`Server listening on http://127.0.0.1:${port}/mcp\n`);
+
+  const activeClients: Client[] = [];
+
+  let exitCode = 0;
+  try {
+    // ── Test 1: tools/list ────────────────────────────────────────────────
+    {
+      const client = await newClient(port, authHeaders());
+      activeClients.push(client);
+      const r = await client.listTools();
+      const names = r.tools.map((t) => t.name);
+      record(
+        'list tools',
+        names.includes('skill_invoke') && names.includes('skill_list'),
+        `tools: ${names.join(', ')}`,
+      );
+    }
+
+    // ── Test 2: skill_list returns skills ─────────────────────────────────
+    {
+      const client = await newClient(port, authHeaders());
+      activeClients.push(client);
+      const r = await client.callTool({ name: 'skill_list', arguments: {} });
+      const content = r.content as Array<{ type: string; text: string }>;
+      const parsed = JSON.parse(content[0].text) as { skills: unknown[]; total: number };
+      record(
+        'skill_list returns skills',
+        parsed.total > 0 && parsed.skills.length === parsed.total,
+        `${parsed.total} skills returned`,
+      );
+    }
+
+    // ── Test 3: skill_invoke base call (with explicit X-Forge-* headers) ──
+    const baseSession = 'e2e-session-1';
+    const baseRouteId = 'e2e-route-1';
+    const baseAgent = 'e2e-agent-bmad';
+    let invokeContentLen = 0;
+    {
+      const client = await newClient(
+        port,
+        authHeaders({
+          'X-Forge-Session-Id': baseSession,
+          'X-Forge-Route-Request-Id': baseRouteId,
+          'X-Forge-Agent-Id': baseAgent,
+        }),
+      );
+      activeClients.push(client);
+      const r = await client.callTool({
+        name: 'skill_invoke',
+        arguments: { skill_id: 'official-tdd', reason: 'bmad/implement:e2e-test' },
+      });
+      const content = r.content as Array<{ type: string; text: string }>;
+      invokeContentLen = content[0]?.text?.length ?? 0;
+      record(
+        'skill_invoke base',
+        !r.isError && invokeContentLen > 100 && content[0].text.startsWith('# '),
+        `content length ${invokeContentLen}`,
+      );
+    }
+
+    // ── Test 4: DB row inserted with all linkage fields ───────────────────
+    {
+      const rows = storage.querySkillInvocations({ session_id: baseSession });
+      const row = rows[0];
+      record('DB row inserted', rows.length === 1, `rows count = ${rows.length}`);
+      record(
+        'workflow parsed',
+        row?.workflow === 'bmad' && row?.phase === 'implement',
+        `workflow=${row?.workflow}, phase=${row?.phase}`,
+      );
+      record(
+        'feature_slug parsed',
+        row?.feature_slug === 'e2e-test',
+        `feature_slug=${row?.feature_slug}`,
+      );
+      record(
+        'session/route/agent linkage',
+        row?.session_id === baseSession &&
+          row?.route_request_id === baseRouteId &&
+          row?.agent_id === baseAgent,
+        `session=${row?.session_id}, route=${row?.route_request_id}, agent=${row?.agent_id}`,
+      );
+      record(
+        'invocation_type=dynamic + success=1',
+        row?.invocation_type === 'dynamic' && row?.success === 1,
+        `invocation_type=${row?.invocation_type}, success=${row?.success}`,
+      );
+    }
+
+    // ── Test 5: Multi-phase aggregation via queryWorkflowProgress ─────────
+    // Use a fresh session to avoid the per-session idempotency guard, and
+    // a single shared route_request_id so all phases group together.
+    const multiSession = 'e2e-session-multi';
+    const multiRouteId = 'e2e-route-multi';
+    const multiAgent = 'e2e-agent-multi';
+    {
+      const phaseSkills: Array<[string, string]> = [
+        ['analyze', 'official-spec-driven-design'],
+        ['design', 'official-architecture-decision'],
+        ['implement', 'official-tdd'],
+      ];
+      for (const [phase, skill] of phaseSkills) {
+        const c = await newClient(
+          port,
+          authHeaders({
+            'X-Forge-Session-Id': multiSession,
+            'X-Forge-Route-Request-Id': multiRouteId,
+            'X-Forge-Agent-Id': multiAgent,
+          }),
+        );
+        activeClients.push(c);
+        await c.callTool({
+          name: 'skill_invoke',
+          arguments: { skill_id: skill, reason: `bmad/${phase}:multi-phase-test` },
+        });
+      }
+      const progress = storage.queryWorkflowProgress({ session_id: multiSession });
+      const ok =
+        progress.length === 1 &&
+        progress[0].workflow === 'bmad' &&
+        progress[0].route_request_id === multiRouteId &&
+        progress[0].phases_completed.length === 3 &&
+        progress[0].phases_completed.includes('analyze') &&
+        progress[0].phases_completed.includes('design') &&
+        progress[0].phases_completed.includes('implement') &&
+        progress[0].feature_slug === 'multi-phase-test';
+      record(
+        'multi-phase aggregation',
+        ok,
+        `routes=${progress.length}, phases=[${progress[0]?.phases_completed.join(', ')}], feature=${progress[0]?.feature_slug}`,
+      );
+    }
+
+    // ── Test 6: Error path — non-existent skill records success=0 ────────
+    const errSession = 'e2e-session-error';
+    {
+      const client = await newClient(
+        port,
+        authHeaders({ 'X-Forge-Session-Id': errSession }),
+      );
+      activeClients.push(client);
+      const r = await client.callTool({
+        name: 'skill_invoke',
+        arguments: { skill_id: 'nonexistent-skill-xyz', reason: 'bmad/analyze' },
+      });
+      const isErrorFlag = r.isError === true;
+      const rows = storage.querySkillInvocations({ session_id: errSession });
+      const row = rows[0];
+      record(
+        'error skill returns isError + records success=0',
+        isErrorFlag &&
+          rows.length === 1 &&
+          row.success === 0 &&
+          (row.error?.includes('Skill not found') ?? false),
+        `isError=${isErrorFlag}, rows=${rows.length}, success=${row?.success}, error="${row?.error?.slice(0, 60) ?? ''}"`,
+      );
+    }
+
+    // ── Test 7: Guard blocks repeated calls (idempotency) ─────────────────
+    const dupSession = 'e2e-session-dup';
+    {
+      // First invocation succeeds
+      const c1 = await newClient(
+        port,
+        authHeaders({ 'X-Forge-Session-Id': dupSession }),
+      );
+      activeClients.push(c1);
+      await c1.callTool({
+        name: 'skill_invoke',
+        arguments: { skill_id: 'official-tdd', reason: 'first call' },
+      });
+
+      // Second invocation of same skill in same session should be blocked
+      const c2 = await newClient(
+        port,
+        authHeaders({ 'X-Forge-Session-Id': dupSession }),
+      );
+      activeClients.push(c2);
+      const r2 = await c2.callTool({
+        name: 'skill_invoke',
+        arguments: { skill_id: 'official-tdd', reason: 'duplicate' },
+      });
+
+      const rows = storage.querySkillInvocations({ session_id: dupSession });
+      // Rows ordered by timestamp DESC: rows[0] is the duplicate (Blocked), rows[1] is the first
+      const blockedRow = rows.find((r) => r.success === 0 && r.error?.includes('Blocked'));
+      const successRow = rows.find((r) => r.success === 1);
+      record(
+        'guard blocks repeated calls',
+        r2.isError === true &&
+          rows.length === 2 &&
+          blockedRow !== undefined &&
+          successRow !== undefined,
+        `2 rows; isError=${r2.isError}; success=${successRow?.success}, blocked.error="${blockedRow?.error?.slice(0, 60) ?? ''}"`,
+      );
+    }
+
+    // ── Test 8: Fallback to routingState when X-Forge-Session-Id missing ──
+    const fallbackSession = 'e2e-session-fallback';
+    const fallbackRouteId = 'e2e-route-fallback';
+    {
+      routingState.setRouting(fallbackSession, {
+        agentName: 'fallback-agent',
+        agentDescription: 'desc',
+        timestamp: Date.now(),
+        routeRequestId: fallbackRouteId,
+      });
+      // No X-Forge-* headers — server should fall back to routingState.getMostRecent().
+      const client = await newClient(port, authHeaders());
+      activeClients.push(client);
+      await client.callTool({
+        name: 'skill_invoke',
+        arguments: { skill_id: 'official-refactor', reason: 'fallback test' },
+      });
+
+      const rows = storage.querySkillInvocations({ session_id: fallbackSession });
+      const row = rows[0];
+      record(
+        'routingState fallback (no headers)',
+        rows.length === 1 &&
+          row?.route_request_id === fallbackRouteId &&
+          row?.agent_id === 'fallback-agent',
+        `rows=${rows.length}, route=${row?.route_request_id}, agent=${row?.agent_id}`,
+      );
+      routingState.clearRouting(fallbackSession);
+    }
+
+    // ── Test 9: mcp-anon-* fallback when neither header nor routingState ──
+    {
+      // routingState should be empty by now (we cleared the fallback above and
+      // no daemon is feeding it). Issue a call and look for an mcp-anon-* row.
+      const before = Date.now();
+      const client = await newClient(port, authHeaders());
+      activeClients.push(client);
+      await client.callTool({
+        name: 'skill_invoke',
+        arguments: { skill_id: 'official-debug', reason: 'anon test' },
+      });
+
+      // Fetch all rows and filter for mcp-anon-* with timestamp >= before.
+      // querySkillInvocations is keyed by session_id so we use a wide query.
+      const allRows = storage.querySkillInvocations({});
+      const anonRow = allRows.find(
+        (r) => r.session_id.startsWith('mcp-anon-') && r.timestamp >= before,
+      );
+      record(
+        'mcp-anon-* fallback (no header, no routingState)',
+        anonRow !== undefined && anonRow.success === 1,
+        `session_id=${anonRow?.session_id ?? '<none>'}`,
+      );
+    }
+  } catch (err) {
+    console.error('\n[FATAL] Unhandled error during tests:', err);
+    record('e2e-script', false, err instanceof Error ? err.message : String(err));
+    exitCode = 1;
+  } finally {
+    // Cleanup: clients first, then HTTP server, then storage, then tmp dir.
+    for (const c of activeClients) {
+      try {
+        await c.close();
+      } catch {
+        /* ignore */
+      }
+    }
+    const httpServer = (server as unknown as { server: import('node:net').Server | null }).server;
+    if (httpServer) {
+      (httpServer as unknown as { closeAllConnections?: () => void }).closeAllConnections?.();
+      await new Promise<void>((res) => httpServer.close(() => res()));
+    }
+    storage.close();
+    rmSync(tmp, { recursive: true, force: true });
+    restoreTestToken();
+  }
+
+  // ── Final report ─────────────────────────────────────────────────────────
+  const passed = results.filter((r) => r.pass).length;
+  const total = results.length;
+  console.log(`\n=== Result: ${passed}/${total} passed ===`);
+  if (passed !== total) {
+    console.log('\nFailures:');
+    for (const r of results.filter((x) => !x.pass)) {
+      console.log(`  - ${r.step}: ${r.details}`);
+    }
+  }
+
+  process.exit(passed === total && exitCode === 0 ? 0 : 1);
+}
+
+main().catch((err) => {
+  console.error('E2E failed:', err);
+  restoreTestToken();
+  rmSync(tmp, { recursive: true, force: true });
+  process.exit(1);
+});

package/scripts/e2e-methodology-quality.ts

@@ -0,0 +1,253 @@
+#!/usr/bin/env tsx
+/**
+ * E2E 验证：6 个方法论 Agent 的 prompt 质量
+ */
+
+import { OFFICIAL_AGENTS, findOfficialAgent } from '../src/agents/index.js';
+import { METHODOLOGY_PRESETS } from '../src/agents/methodologies/presets.js';
+import { getPhase, getAllPhases, buildMethodologyAgent } from '../src/agents/methodologies/agent-builder.js';
+import { OFFICIAL_SKILL_KEYWORDS } from '../src/skills/official-skills.js';
+import { parseWorkflowMeta } from '../src/skills/tools/skill-invoke.js';
+
+interface Issue {
+  agent: string;
+  severity: 'error' | 'warning' | 'info';
+  message: string;
+}
+
+const issues: Issue[] = [];
+
+function record(agent: string, severity: Issue['severity'], message: string) {
+  issues.push({ agent, severity, message });
+}
+
+const PRESET_IDS = [
+  'bmad-feature-full',
+  'bmad-feature-quick',
+  'bmad-spec-only',
+  'harness-debug-full',
+  'harness-hotfix',
+  'harness-investigate',
+];
+
+const VALID_SKILLS = new Set(Object.keys(OFFICIAL_SKILL_KEYWORDS));
+
+console.log('=== 方法论 Agent Prompt 质量 E2E 验证 ===\n');
+
+// ── Check 1: 6 个 preset 都注册成功 ──────────────────────
+console.log('-- Check 1: Preset 注册检查 --');
+for (const id of PRESET_IDS) {
+  const agent = findOfficialAgent(id);
+  if (!agent) {
+    record(id, 'error', '未注册到 OFFICIAL_AGENTS');
+  } else {
+    console.log(`✓ ${id}: 已注册 (version=${agent.version}, skills=${agent.skills?.length ?? 0})`);
+  }
+}
+
+// ── Check 2: 每个 preset 的 phase 列表合法 ────────────────
+console.log('\n-- Check 2: Phase 列表合法性 --');
+for (const preset of METHODOLOGY_PRESETS) {
+  for (const phaseId of preset.phases) {
+    const phase = getPhase(phaseId);
+    if (!phase) {
+      record(preset.id, 'error', `phase ${phaseId} 不存在`);
+    }
+  }
+}
+console.log(`(已检查 ${METHODOLOGY_PRESETS.length} 个 preset 的 phase 列表)`);
+
+// ── Check 3: prompt 内容质量 ─────────────────────────────
+console.log('\n-- Check 3: prompt 内容质量 --');
+for (const id of PRESET_IDS) {
+  const agent = findOfficialAgent(id);
+  if (!agent) continue;
+  const content = agent.content;
+
+  // 必须包含
+  if (!content.includes('软性建议') && !content.includes('软性')) {
+    record(id, 'warning', 'prompt 未明确"软性建议"语义');
+  }
+  if (content.length < 500) {
+    record(id, 'warning', `prompt 过短（${content.length} 字符），可能内容缺失`);
+  }
+
+  // 每个 phase 都该出现在 prompt 里
+  const preset = METHODOLOGY_PRESETS.find(p => p.id === id);
+  if (preset) {
+    for (const phaseId of preset.phases) {
+      const phase = getPhase(phaseId);
+      if (phase && !content.includes(`Phase: ${phase.id}`)) {
+        record(id, 'error', `prompt 缺少 "Phase: ${phase.id}" 标识`);
+      }
+    }
+  }
+  console.log(`  ${id}: ${content.length} 字符`);
+}
+
+// ── Check 4: reason 格式约定一致 ─────────────────────────
+// Prompt 里的 reason 用 <feature-slug> / <bug-slug> 当模板占位符。
+// 运行时 LLM 会替换成实际 slug，再传给 skill_invoke。
+// 因此校验时把占位符替换成示例 slug，再过 parseWorkflowMeta。
+console.log('\n-- Check 4: reason 格式 --');
+const TEMPLATE_PLACEHOLDERS = /<(feature-slug|bug-slug)>/g;
+const PLACEHOLDER_SUBSTITUTE = 'example-slug';
+
+for (const id of PRESET_IDS) {
+  const agent = findOfficialAgent(id);
+  if (!agent) continue;
+
+  // 提取所有 reason: "..." 出现
+  const reasonMatches = [...agent.content.matchAll(/reason:\s*"([^"]+)"/g)];
+  for (const match of reasonMatches) {
+    const reasonTemplate = match[1];
+    const reasonResolved = reasonTemplate.replace(TEMPLATE_PLACEHOLDERS, PLACEHOLDER_SUBSTITUTE);
+
+    // 子检查 4a：原始模板必须含 <feature-slug> 或 <bug-slug>（强制带 slug 元数据）
+    const hasSlugPlaceholder = reasonTemplate.includes('<feature-slug>') || reasonTemplate.includes('<bug-slug>');
+    if (!hasSlugPlaceholder) {
+      record(id, 'info', `reason "${reasonTemplate}" 缺少 <feature-slug>/<bug-slug> 占位符（仍可工作，但 slug 元数据会缺失）`);
+    }
+
+    // 子检查 4b：占位符替换后必须能被解析
+    const meta = parseWorkflowMeta(reasonResolved);
+    if (!meta.workflow) {
+      record(id, 'error', `reason "${reasonTemplate}" 替换占位符后 ("${reasonResolved}") 仍无法被 parseWorkflowMeta 解析`);
+    } else if (meta.workflow !== 'bmad' && meta.workflow !== 'harness') {
+      record(id, 'error', `reason "${reasonTemplate}" workflow=${meta.workflow}（应为 bmad/harness）`);
+    } else {
+      // 子检查 4c：解析出来的 workflow 应该跟 preset 主线一致
+      const preset = METHODOLOGY_PRESETS.find(p => p.id === id);
+      const presetWorkflow = id.startsWith('bmad-') ? 'bmad' : id.startsWith('harness-') ? 'harness' : null;
+      if (presetWorkflow && meta.workflow !== presetWorkflow) {
+        record(id, 'warning', `reason "${reasonTemplate}" workflow=${meta.workflow}（preset 主线=${presetWorkflow}）`);
+      }
+    }
+  }
+
+  if (reasonMatches.length === 0) {
+    const preset = METHODOLOGY_PRESETS.find(p => p.id === id);
+    const needsSkill = preset?.phases.some(p => getPhase(p)?.skillId);
+    if (needsSkill) {
+      record(id, 'warning', '至少有 phase 需要调用 skill 但 prompt 里找不到 reason: "..." 字面量');
+    }
+  }
+  console.log(`  ${id}: 发现 ${reasonMatches.length} 个 reason 引用`);
+}
+
+// ── Check 5: 所有引用的 skill 都真实存在 ─────────────────
+console.log('\n-- Check 5: Skill 引用有效性 --');
+let phaseSkillCount = 0;
+for (const phase of getAllPhases()) {
+  if (phase.skillId) {
+    phaseSkillCount++;
+    if (!VALID_SKILLS.has(phase.skillId)) {
+      record(`phase:${phase.workflow}/${phase.id}`, 'error',
+        `skillId "${phase.skillId}" 不在 OFFICIAL_SKILL_KEYWORDS`);
+    }
+  }
+}
+console.log(`  共 ${getAllPhases().length} 个 phase，其中 ${phaseSkillCount} 个引用 skill`);
+
+// ── Check 6: artifact 路径模板合理 ───────────────────────
+console.log('\n-- Check 6: artifact 路径模板 --');
+for (const phase of getAllPhases()) {
+  if (phase.artifactHint) {
+    // 检查路径是否在 docs/ 下（按用户决策）
+    if (!phase.artifactHint.startsWith('docs/') && !phase.artifactHint.startsWith('src/') && !phase.artifactHint.startsWith('tests/')) {
+      record(`phase:${phase.workflow}/${phase.id}`, 'warning',
+        `artifact 路径 "${phase.artifactHint}" 不在 docs/src/tests 下`);
+    }
+    // 检查是否含 <feature-slug> 或 <bug-slug> 占位符
+    if (!phase.artifactHint.includes('<')) {
+      record(`phase:${phase.workflow}/${phase.id}`, 'info',
+        `artifact 路径 "${phase.artifactHint}" 没有占位符（不可变路径？）`);
+    }
+  }
+}
+console.log(`  (已检查所有 phase 的 artifactHint)`);
+
+// ── Check 7: 跨方法论 Phase 没混淆 ───────────────────────
+console.log('\n-- Check 7: 跨方法论组合 --');
+for (const preset of METHODOLOGY_PRESETS) {
+  const workflows = new Set(preset.phases.map(p => getPhase(p)?.workflow));
+  // official preset 应该是单方法论的
+  if (workflows.size > 1) {
+    record(preset.id, 'info',
+      `跨方法论组合：${[...workflows].join(', ')}（official 预设建议单方法论）`);
+  }
+}
+console.log(`  (已检查 ${METHODOLOGY_PRESETS.length} 个 preset 的 workflow 一致性)`);
+
+// ── Check 8: Phase 的 skillId 跟 workflow 一致性 ──────────
+console.log('\n-- Check 8: Skill 与 workflow 一致性 --');
+for (const phase of getAllPhases()) {
+  if (phase.skillId) {
+    // 简单检查：bmad phase 的 skill 不该是纯 harness 类的
+    // （这是 heuristic，不是硬规则）
+    if (phase.workflow === 'bmad' && phase.skillId.includes('harness')) {
+      record(`phase:${phase.workflow}/${phase.id}`, 'warning',
+        `bmad phase 引用 harness skill "${phase.skillId}"`);
+    }
+  }
+}
+console.log(`  (已检查所有 phase 的 skill 归属)`);
+
+// ── Check 9: buildMethodologyAgent 是确定性的 ────────────
+console.log('\n-- Check 9: buildMethodologyAgent 确定性 --');
+const preset = METHODOLOGY_PRESETS[0];
+const built1 = buildMethodologyAgent(preset);
+const built2 = buildMethodologyAgent(preset);
+if (built1.content !== built2.content) {
+  record(preset.id, 'error', 'buildMethodologyAgent 输出不确定');
+} else {
+  console.log(`  ✓ ${preset.id} 多次构建结果一致`);
+}
+
+// ── Check 10: harness 系列的 slug 占位符在整份 prompt 里保持一致 ──
+// agent-builder 的"软性建议"行硬编码 `<feature-slug>`，但 harness phase body
+// 全部使用 `<bug-slug>`。同一份 prompt 混用两种 slug 名会误导 LLM。
+console.log('\n-- Check 10: slug 占位符在 prompt 内部一致 --');
+for (const id of PRESET_IDS) {
+  const agent = findOfficialAgent(id);
+  if (!agent) continue;
+  const content = agent.content;
+  const hasFeatureSlug = content.includes('<feature-slug>');
+  const hasBugSlug = content.includes('<bug-slug>');
+  const isHarness = id.startsWith('harness-');
+  const isBmad = id.startsWith('bmad-');
+
+  if (isHarness && hasFeatureSlug) {
+    record(id, 'warning',
+      `harness preset 里出现 <feature-slug>（应为 <bug-slug>）— 可能来自 agent-builder 模板硬编码`);
+  }
+  if (isBmad && hasBugSlug) {
+    record(id, 'warning',
+      `bmad preset 里出现 <bug-slug>（应为 <feature-slug>）`);
+  }
+  if (hasFeatureSlug && hasBugSlug) {
+    record(id, 'warning',
+      `prompt 同时出现 <feature-slug> 和 <bug-slug>，会让 LLM 困惑`);
+  }
+}
+
+// ── 输出报告 ─────────────────────────────────────────────
+const errors = issues.filter(i => i.severity === 'error');
+const warnings = issues.filter(i => i.severity === 'warning');
+const infos = issues.filter(i => i.severity === 'info');
+
+console.log('\n=== 问题汇总 ===');
+console.log(`Errors:   ${errors.length}`);
+console.log(`Warnings: ${warnings.length}`);
+console.log(`Infos:    ${infos.length}`);
+
+if (issues.length > 0) {
+  console.log('\n=== 问题详情 ===');
+  for (const issue of issues) {
+    const icon = issue.severity === 'error' ? '✗' : issue.severity === 'warning' ? '⚠' : 'ℹ';
+    console.log(`${icon} [${issue.agent}] ${issue.message}`);
+  }
+}
+
+console.log(`\n=== Result: ${errors.length === 0 ? 'PASS' : 'FAIL'} ===`);
+process.exit(errors.length === 0 ? 0 : 1);