@xulthekl/team-flow 0.29.2 → 0.31.0

package/scripts/lib/cmd-doctor.mjs

@@ -3,6 +3,8 @@ import { readFileSync, readdirSync, existsSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { loadConfig } from './config-loader.mjs';
 import { PLATFORM_RUNTIME_INVENTORY } from './platform-runtime-inventory.mjs';
+// 非法 state 巡检所需的共享常量与读取器(来源:workflow-feedback 2026-08-01,#100004)。
+import { readState, VALID_STATES } from './state-loader.mjs';
 
 const RUNTIME_SKILLS = new Set([
   'workflow-start', 'need-explorer', 'spec-writer', 'contract-builder',
@@ -220,6 +222,42 @@ function checkDocs(root) {
   return { pass: false, message: warnings.join('; ') };
 }
 
+// 非法 state 巡检(来源:workflow-feedback 2026-08-01,#100004):
+// 扫描 changes/<name>/.team-flow.yaml,若 state 字段不在 VALID_STATES 则报 FAIL。
+// 非法值通常由子代理绕过 CLI 直接 Edit .team-flow.yaml 导致,提示修复为合法值。
+// 沿用 checkSkills 的目录扫描 + 计数报告风格。
+function checkChangeStates(root) {
+  const changesDir = join(root, 'changes');
+  if (!existsSync(changesDir)) {
+    return { pass: true, message: 'no changes/ directory (skipped)' };
+  }
+  const dirs = readdirSync(changesDir).filter(f => {
+    try { return statSync(join(changesDir, f)).isDirectory(); } catch { return false; }
+  });
+  const invalid = [];
+  let checked = 0;
+  for (const d of dirs) {
+    if (!existsSync(join(changesDir, d, '.team-flow.yaml'))) continue;
+    checked += 1;
+    const current = readState(join(changesDir, d)).state;
+    if (!VALID_STATES.includes(current)) {
+      invalid.push(`${d}='${current}'`);
+    }
+  }
+  if (checked === 0) {
+    return { pass: true, message: 'no state files under changes/ (skipped)' };
+  }
+  if (invalid.length > 0) {
+    return {
+      pass: false,
+      message:
+        `state 值非法(可能是子代理绕过 CLI 直接 Edit .team-flow.yaml 所致):${invalid.join('; ')}。` +
+        `请修复为合法值:${VALID_STATES.join('/')}`,
+    };
+  }
+  return { pass: true, message: `${checked} change(s) have legal state values` };
+}
+
 export async function run(args) {
   const root = process.cwd();
   const config = loadConfig(root);
@@ -236,6 +274,7 @@ export async function run(args) {
     ['dist/', checkDist(root)],
     ['Node.js', checkNodeVersion()],
     ['Docs', checkDocs(root)],
+    ['Change states', checkChangeStates(root)],
   ];
 
   // Config check
@@ -264,4 +303,4 @@ export async function run(args) {
   }
 }
 
-export { checkVersionConsistency, checkHooks, checkCodexManifest, checkSkills, checkRuntimeDistribution, checkDist, checkRootPluginAuthor, checkNodeVersion, checkDocs };
+export { checkVersionConsistency, checkHooks, checkCodexManifest, checkSkills, checkRuntimeDistribution, checkDist, checkRootPluginAuthor, checkNodeVersion, checkDocs, checkChangeStates };

package/scripts/lib/cmd-state.mjs

@@ -2,18 +2,15 @@
 import { parseArgs } from 'node:util';
 import { spawnSync } from 'node:child_process';
 import { existsSync, mkdirSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import path, { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { readState, writeState, updateField, rebuildState } from './state-loader.mjs';
-import { computeArtifactsHash, computeContractHash } from './hash.mjs';
+// VALID_STATES 统一从 state-loader.mjs 引入(状态机合法值唯一真相源),不再本地硬编码。
+// 来源:workflow-feedback 2026-08-01,#100005。
+import { readState, writeState, updateField, rebuildState, VALID_STATES } from './state-loader.mjs';
+import { computeArtifactsHash, computeContractHash, computeTestMatrixHash } from './hash.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
-const VALID_STATES = [
-  'exploring', 'specifying', 'bridging', 'approved-for-build',
-  'executing', 'debugging', 'closing', 'abandoned',
-];
-
 const SETTABLE_FIELDS = [
   'workflow', 'test_result', 'batches_completed', 'spec_merged',
   'dp_0_decisions', 'dp_0_confirmed', 'dp_0_timestamp', 'dp_0_result',
@@ -32,6 +29,8 @@ const SETTABLE_FIELDS = [
   'dp_a_result', 'dp_a_timestamp', 'dp_a_adjustments',
   // Compound engineering capture gate (v0.24.0 复利贯穿强制化)
   'compound_skipped',
+  // Test matrix gate (v0.12 §45.4)
+  'test_matrix_skipped',
 ];
 
 export async function run(args) {
@@ -44,7 +43,7 @@ export async function run(args) {
   });
 
   const sub = positionals[0];  // init | check | transition | get | rebuild | set
-  const changeDir = positionals[1];
+  let changeDir = positionals[1];
   const arg = positionals[2];  // <to-state> for transition, <field> for get
 
   if (!changeDir) {
@@ -53,6 +52,13 @@ export async function run(args) {
     process.exit(2);
   }
 
+  // 修复相对路径 bug(来源:workflow-feedback 2026-08-01,#100005)。
+  // 根因:readState 用 path.join(changeDir,...) 按用户 cwd 解析,而 transition 分支 spawn guard
+  // 子进程时 cwd 设为包根(join(__dirname,'..','..'))+ 原样 changeDir,两处基准不一致——用户传
+  // 相对路径时 guard 在包根下找不到产物。统一在入口 resolve 为绝对路径,使后续 readState /
+  // guard spawn / existsSync 全部基于同一绝对基准,消除 cwd 歧义。
+  changeDir = path.resolve(changeDir);
+
   // Unknown subcommand: report a usage error (exit 2) BEFORE the BUG-B
   // state-file existence check, so a bad subcommand is not masked by the
   // "No state file" error (which would return exit 1 instead of exit 2).
@@ -80,15 +86,18 @@ export async function run(args) {
       }
       const hash = computeArtifactsHash(changeDir);
       const ch = computeContractHash(changeDir);
+      const tmh = computeTestMatrixHash(changeDir);
       const state = readState(changeDir);
       state.artifacts_hash = hash;
       state.contract_hash = ch;
+      // v0.12 §42.5: test_matrix_hash is independent from artifacts_hash
+      state.test_matrix_hash = tmh;
       state.last_transition = new Date().toISOString();
       writeState(changeDir, state);
       if (values.json) {
-        console.log(JSON.stringify({ ok: true, artifacts_hash: hash, contract_hash: ch }));
+        console.log(JSON.stringify({ ok: true, artifacts_hash: hash, contract_hash: ch, test_matrix_hash: tmh }));
       } else {
-        console.log(`State initialized. artifacts_hash: ${hash}`);
+        console.log(`State initialized. artifacts_hash: ${hash}` + (tmh ? `, test_matrix_hash: ${tmh}` : ''));
       }
       break;
     }
@@ -205,7 +214,7 @@ export async function run(args) {
       break;
     }
     case 'rebuild': {
-      const state = rebuildState(changeDir, { computeArtifactsHash, computeContractHash });
+      const state = rebuildState(changeDir, { computeArtifactsHash, computeContractHash, computeTestMatrixHash });
       if (values.json) {
         console.log(JSON.stringify({ ok: true, state: state.state }));
       } else {
@@ -222,7 +231,18 @@ export async function run(args) {
         process.exit(2);
       }
       if (!SETTABLE_FIELDS.includes(field)) {
-        console.error(`⛔ Field '${field}' is not settable (use 'transition' for state, or check SETTABLE_FIELDS)`);
+        // 错误提示升级(来源:workflow-feedback 2026-08-01,#100005):
+        // 'state' 是最常被误用 set 的字段,专门给出完整 transition 语法示例;合法状态清单
+        // 引用 VALID_STATES(唯一真相源),不硬编码。保留 'not settable' 措辞以兼容既有回归测试。
+        if (field === 'state') {
+          console.error(
+            `⛔ 'state' 不是可 set 的字段(not settable)。状态转换请用完整语法:\n` +
+            `   tf state transition <change-dir 绝对路径> <目标状态>\n` +
+            `   合法状态:${VALID_STATES.join('/')}`
+          );
+        } else {
+          console.error(`⛔ Field '${field}' is not settable (use 'transition' for state, or check SETTABLE_FIELDS)`);
+        }
         process.exit(1);
       }
       updateField(changeDir, field, value);

package/scripts/lib/hash.mjs

@@ -67,6 +67,17 @@ export function computeContractHash(changeDir) {
   return `sha256:${hash.digest('hex')}`;
 }
 
+// Compute SHA256 hash of test-matrix.md alone (v0.12 §42.5).
+// Independent from artifacts_hash to avoid self-circulation:
+// modify matrix → contract stale → rollback bridging → regenerate matrix.
+export function computeTestMatrixHash(changeDir) {
+  const matrix = path.join(changeDir, 'test-matrix.md');
+  if (!fs.existsSync(matrix)) return null;
+  const hash = crypto.createHash('sha256');
+  hash.update(fs.readFileSync(matrix, 'utf-8'));
+  return `sha256:${hash.digest('hex')}`;
+}
+
 // Fast staleness check: compare stored artifacts_hash against current.
 export function isContractFresh(changeDir, stateLoader) {
   const stateFile = path.join(changeDir, '.team-flow.yaml');

package/scripts/lib/state-loader.mjs

@@ -4,6 +4,14 @@ import path from 'node:path';
 
 const STATE_FILE = '.team-flow.yaml';
 
+// 状态机合法值唯一真相源 (来源:workflow-feedback 2026-08-01,#100005)。
+// 所有状态枚举校验统一引用此常量,禁止在各处硬编码状态字符串数组,避免多处定义漂移。
+// cmd-state.mjs(transition 校验 / set 报错)、cmd-doctor.mjs(非法 state 巡检)均从这里 import。
+export const VALID_STATES = [
+  'exploring', 'specifying', 'bridging', 'approved-for-build',
+  'executing', 'debugging', 'closing', 'abandoned',
+];
+
 const BUILTIN_DEFAULTS = {
   state: 'exploring',
   workflow: 'auto',
@@ -53,6 +61,9 @@ const BUILTIN_DEFAULTS = {
   dp_a_adjustments: null,
   // Compound engineering capture gate (v0.24.0 复利贯穿强制化)
   compound_skipped: null,
+  // Test matrix gate (v0.12 §42.5 + §45.4)
+  test_matrix_hash: null,
+  test_matrix_skipped: null,
 };
 
 /**
@@ -74,6 +85,20 @@ export function readState(changeDir) {
  * Write state object to .team-flow.yaml.
  */
 export function writeState(changeDir, state) {
+  // Defense-in-depth 状态合法性校验 (来源:workflow-feedback 2026-08-01,#100004)。
+  // 主修复是子代理 prompt 禁令(禁止绕过 CLI 直接 Edit .team-flow.yaml);此处是最后一道防线,
+  // 拦截任何非法 state 落盘。init/transition/rebuild/updateField 等 CLI 路径产生的 state 均合法
+  // (缺失时回退 'exploring'),不会误伤;仅当出现非法值时抛错,提示用 tf doctor 排查。
+  const effectiveState = state.state || 'exploring';
+  if (!VALID_STATES.includes(effectiveState)) {
+    throw new Error(
+      `Refusing to write illegal state '${effectiveState}' to ${path.join(changeDir, STATE_FILE)}. ` +
+      `Legal states: ${VALID_STATES.join(', ')}. ` +
+      `This is usually caused by a subagent bypassing the CLI and editing .team-flow.yaml directly — ` +
+      `restore a legal value or run 'tf doctor' to diagnose.`
+    );
+  }
+
   const filePath = path.join(changeDir, STATE_FILE);
   const lines = [];
   lines.push('# .team-flow.yaml — lightweight state machine');
@@ -140,6 +165,10 @@ export function writeState(changeDir, state) {
   lines.push('');
   lines.push('# === Compound engineering capture gate (v0.24.0) ===');
   lines.push(`compound_skipped: ${state.compound_skipped ?? 'null'}`);
+  lines.push('');
+  lines.push('# === Test matrix gate (v0.12 §42.5) ===');
+  lines.push(`test_matrix_hash: ${state.test_matrix_hash ?? 'null'}`);
+  lines.push(`test_matrix_skipped: ${state.test_matrix_skipped ?? 'null'}`);
 
   fs.writeFileSync(filePath, lines.join('\n') + '\n', 'utf-8');
 }
@@ -157,10 +186,14 @@ export function updateField(changeDir, field, value) {
  * Rebuild state file from artifacts — recomputes hashes.
  * Requires hash functions to be passed in (avoids circular dependency).
  */
-export function rebuildState(changeDir, { computeArtifactsHash, computeContractHash }) {
+export function rebuildState(changeDir, { computeArtifactsHash, computeContractHash, computeTestMatrixHash }) {
   const state = readState(changeDir);
   state.artifacts_hash = computeArtifactsHash(changeDir);
   state.contract_hash = computeContractHash(changeDir);
+  // v0.12 §42.5: test_matrix_hash is independent from artifacts_hash
+  if (computeTestMatrixHash) {
+    state.test_matrix_hash = computeTestMatrixHash(changeDir);
+  }
   writeState(changeDir, state);
   return state;
 }

package/scripts/lib/test-matrix-export.mjs

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+/**
+ * test-matrix-export — glaf4 test-matrix.json → team-flow test-matrix.md 格式转换
+ *
+ * v0.12 §46.1 定义，v0.31.0 实现为 CLI 子命令
+ * 用法：tf test-matrix-export <input.json> <output.md> [--change-id <id>] [--batch-id <id>]
+ *
+ * 功能：
+ * - 读取 glaf4 的 test-matrix.json
+ * - 保留全部 14 字段 + 包装 team_flow_context
+ * - 从 test_kind 派生 test_tier（unit/integration）
+ * - 输出 team-flow 格式的 test-matrix.md
+ */
+
+import { readFileSync, writeFileSync } from 'node:fs';
+import { resolve, basename } from 'node:path';
+
+/**
+ * 解析 CLI 参数
+ */
+function parseArgv(argv) {
+  const parsed = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--change-id' && argv[i + 1]) {
+      parsed.changeId = argv[++i];
+    } else if (argv[i] === '--batch-id' && argv[i + 1]) {
+      parsed.batchId = argv[++i];
+    } else if (argv[i] === '--ledger-ref' && argv[i + 1]) {
+      parsed.ledgerRef = argv[++i];
+    } else if (!argv[i].startsWith('--')) {
+      parsed._.push(argv[i]);
+    }
+  }
+  return parsed;
+}
+
+/**
+ * test_kind → test_tier 映射（v0.12 §42.4）
+ */
+const TEST_KIND_TO_TIER = {
+  // unit tier
+  pure_unit: 'unit',
+  mockito_unit: 'unit',
+  spring_assisted_unit: 'unit',
+  vitest_unit: 'unit',
+  vue_test_utils_mount: 'unit',
+  // integration tier
+  api_mockmvc_standalone: 'integration',
+  api_mockmvc_slice: 'integration',
+  api_mockmvc_boot: 'integration',
+  service_social: 'integration',
+  repository_h2: 'integration',
+  rabbitmq_social: 'integration',
+  redis_social: 'integration',
+  external_api_stub: 'integration',
+  test_infrastructure: 'integration',
+};
+
+/**
+ * 从 glaf4 case 派生 test_tier
+ */
+function deriveTestTier(testKind) {
+  return TEST_KIND_TO_TIER[testKind] || 'unit';
+}
+
+/**
+ * 转义 markdown 表格单元格
+ */
+function escapeCell(str) {
+  if (typeof str !== 'string') return String(str ?? '');
+  return str.replace(/\|/g, '\\|').replace(/\n/g, ' ');
+}
+
+/**
+ * 转换单个 case 为 markdown 行
+ */
+function caseToRow(c) {
+  const tier = deriveTestTier(c.test_kind);
+  return [
+    c.case_id || '',
+    escapeCell(c.behavior || c.display_name || ''),
+    c.design_method || '',
+    escapeCell(typeof c.input === 'object' ? JSON.stringify(c.input) : (c.input || '')),
+    escapeCell(typeof c.expected === 'object' ? JSON.stringify(c.expected) : (c.expected || '')),
+    c.test_kind || '',
+    tier,
+    escapeCell(Array.isArray(c.required_stubs) ? c.required_stubs.join(', ') : (c.mock || '')),
+    c.work_mode || 'TDD',
+    c.test_file || '',
+    c.test_method_name || '',
+    c.run_command || '',
+  ].join(' | ');
+}
+
+/**
+ * 提取模块名（从 target 或 case_id 前缀）
+ */
+function extractModuleName(matrix) {
+  if (matrix.target) {
+    // e.g., "com.example.service.OrderService" → "OrderService"
+    const parts = matrix.target.split('.');
+    return parts[parts.length - 1];
+  }
+  // fallback: from first case_id
+  if (matrix.cases?.[0]?.case_id) {
+    const id = matrix.cases[0].case_id;
+    const match = id.match(/^([A-Z][a-zA-Z]+)/);
+    if (match) return match[1];
+  }
+  return 'Unknown';
+}
+
+/**
+ * 转换 glaf4 matrix → team-flow markdown
+ */
+export function convert(matrix, options = {}) {
+  const moduleName = extractModuleName(matrix);
+  const cases = matrix.cases || [];
+
+  // 统计
+  const unitCases = cases.filter(c => deriveTestTier(c.test_kind) === 'unit');
+  const integrationCases = cases.filter(c => deriveTestTier(c.test_kind) === 'integration');
+
+  // 提取 complexity
+  const complexity = matrix.target_complexity || {};
+  let complexityTier = 'medium';
+  if (complexity.is_trivial) complexityTier = 'trivial';
+  else if ((complexity.public_methods || 0) > 15 || (complexity.lines || 0) > 800 || (complexity.param_count || 0) > 6) {
+    complexityTier = 'complex';
+  }
+
+  // 提取 candidate ledger
+  const candidateLedger = matrix.source_candidate_ledger || [];
+
+  // 构建 markdown
+  const lines = [];
+  lines.push(`# Test Matrix — ${options.changeId || 'unknown'}`);
+  lines.push('');
+  lines.push('## Summary');
+  lines.push(`- Total cases: ${cases.length}`);
+  lines.push(`- Modules covered: 1 (${moduleName}, complexity: ${complexityTier})`);
+  lines.push(`- Unit cases: ${unitCases.length} (${Math.round(unitCases.length / cases.length * 100) || 0}%)`);
+  lines.push(`- Integration cases: ${integrationCases.length} (${Math.round(integrationCases.length / cases.length * 100) || 0}%)`);
+  lines.push(`- Deferred items: ${candidateLedger.filter(c => c.decision === 'deferred').length}`);
+  lines.push(`- Matrix revision: 1`);
+  lines.push('');
+
+  // Candidate Coverage Ledger
+  if (candidateLedger.length > 0) {
+    lines.push('## Candidate Coverage Ledger');
+    lines.push('');
+    lines.push('| candidate | category | decision | case_ids | reason |');
+    lines.push('|---|---|---|---|---|');
+    for (const c of candidateLedger) {
+      lines.push(`| ${escapeCell(c.candidate)} | ${c.category || ''} | ${c.decision} | ${escapeCell(Array.isArray(c.case_ids) ? c.case_ids.join(', ') : (c.case_ids || ''))} | ${escapeCell(c.reason || '')} |`);
+    }
+    lines.push('');
+  }
+
+  // Cases
+  lines.push('## Cases');
+  lines.push('');
+  lines.push(`### ${moduleName}`);
+  lines.push('');
+  lines.push('| case_id | behavior | design_method | input | expected | test_kind | test_tier | mock | work_mode | test_file | test_method_name | run_command |');
+  lines.push('|---|---|---|---|---|---|---|---|---|---|---|---|');
+  for (const c of cases) {
+    lines.push(`| ${caseToRow(c)} |`);
+  }
+  lines.push('');
+
+  // Deferred Items
+  const deferred = candidateLedger.filter(c => c.decision === 'deferred');
+  if (deferred.length > 0) {
+    lines.push('## Deferred Items');
+    lines.push('');
+    lines.push('| case_id | behavior | design_method | reason | deferred_since |');
+    lines.push('|---|---|---|---|---|');
+    for (const d of deferred) {
+      lines.push(`| ${escapeCell(Array.isArray(d.case_ids) ? d.case_ids[0] : (d.case_ids || ''))} | ${escapeCell(d.candidate)} | — | ${escapeCell(d.reason || '')} | ${new Date().toISOString().slice(0, 10)} |`);
+    }
+    lines.push('');
+  }
+
+  // team_flow_context footer
+  lines.push('---');
+  lines.push('');
+  lines.push('<!-- team_flow_context:');
+  lines.push(`  change_id: ${options.changeId || 'unknown'}`);
+  if (options.batchId) lines.push(`  batch_id: ${options.batchId}`);
+  lines.push(`  closing_stage: test-merge`);
+  if (options.ledgerRef) lines.push(`  ledger_ref: ${options.ledgerRef}`);
+  lines.push(`  source: glaf4-tests-export`);
+  lines.push('-->');
+
+  return lines.join('\n') + '\n';
+}
+
+/**
+ * CLI entry point
+ */
+export async function run(args) {
+  const argv = parseArgv(args || process.argv.slice(2));
+  const inputFile = argv._[0];
+  const outputFile = argv._[1];
+
+  if (!inputFile) {
+    console.error('Usage: tf test-matrix-export <input.json> <output.md> [--change-id <id>] [--batch-id <id>]');
+    process.exit(2);
+  }
+
+  if (!outputFile) {
+    console.error('Usage: tf test-matrix-export <input.json> <output.md>');
+    process.exit(2);
+  }
+
+  try {
+    const raw = readFileSync(resolve(inputFile), 'utf-8');
+    const matrix = JSON.parse(raw);
+    const md = convert(matrix, {
+      changeId: argv.changeId || basename(inputFile, '.json'),
+      batchId: argv.batchId,
+      ledgerRef: argv.ledgerRef,
+    });
+    writeFileSync(resolve(outputFile), md, 'utf-8');
+    console.log(`✅ test-matrix-export: ${inputFile} → ${outputFile}`);
+  } catch (err) {
+    console.error(`❌ test-matrix-export error: ${err.message}`);
+    process.exit(1);
+  }
+}