aigroup-workflow 1.2.7 → 2.0.0

package/scripts/harness/tests/test-logs-query.sh

@@ -0,0 +1,77 @@
+#!/bin/bash
+# 单元测试：logs-query.sh
+set -e
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
+QUERY="$ROOT/scripts/harness/logs-query.sh"
+
+TMP=$(mktemp -d)
+trap "rm -rf $TMP" EXIT
+cd "$TMP"
+
+# 构造 mock 日志
+mkdir -p .orchestration/.logs
+TODAY=$(date +%Y-%m-%d)
+LOG="$TMP/.orchestration/.logs/events-$TODAY.jsonl"
+
+cat > "$LOG" <<EOF
+{"ts":"2026-04-23T10:00:00+0800","workflow_id":"wf1","stage":"brainstorming","event_type":"stage_enter","actor":"harness","payload":{}}
+{"ts":"2026-04-23T10:15:00+0800","workflow_id":"wf1","stage":"brainstorming","event_type":"stage_exit","actor":"harness","duration_ms":900000,"payload":{"next_stage":"design"}}
+{"ts":"2026-04-23T10:15:01+0800","workflow_id":"wf1","stage":"design","event_type":"stage_enter","actor":"harness","payload":{}}
+{"ts":"2026-04-23T10:45:00+0800","workflow_id":"wf1","stage":"design","event_type":"stage_exit","actor":"harness","duration_ms":1800000,"payload":{"next_stage":"planning"}}
+{"ts":"2026-04-23T11:00:00+0800","workflow_id":"wf1","stage":"testing","event_type":"lint_fail","actor":"harness","payload":{"lint":"structure"}}
+{"ts":"2026-04-23T11:05:00+0800","workflow_id":"wf1","stage":"testing","event_type":"lint_fail","actor":"harness","payload":{"lint":"structure"}}
+{"ts":"2026-04-23T11:10:00+0800","workflow_id":"wf1","stage":"testing","event_type":"lint_fail","actor":"harness","payload":{"lint":"docs"}}
+{"ts":"2026-04-23T11:15:00+0800","workflow_id":"wf1","stage":"testing","event_type":"red_flag","actor":"max","payload":{"flag_id":"3"}}
+EOF
+
+PASS=0; FAIL=0
+assert() {
+    if eval "$2"; then echo "  [PASS] $1"; PASS=$((PASS+1))
+    else echo "  [FAIL] $1 — cond: $2"; FAIL=$((FAIL+1)); fi
+}
+
+echo "▸ 测试 1：--stats 输出包含阶段耗时"
+OUT=$(bash "$QUERY" --stats wf1)
+assert "含 brainstorming 900000 ms" "echo '$OUT' | grep -q 'brainstorming.*900000'"
+assert "含 design 1800000 ms" "echo '$OUT' | grep -q 'design.*1800000'"
+
+echo ""
+echo "▸ 测试 2：--hotspots 输出按次数降序"
+OUT=$(bash "$QUERY" --hotspots --days 30)
+assert "structure 出现 2 次排第一" "echo '$OUT' | grep -E 'structure.*2|2.*structure'"
+assert "docs 出现 1 次" "echo '$OUT' | grep -E 'docs.*1|1.*docs'"
+assert "red_flag 按 flag_id 聚合" "echo '$OUT' | grep -E 'red_flag.*3|3.*red_flag'"
+
+echo ""
+echo "▸ 测试 2b：--days 过滤真实生效"
+# 创建一个旧日期的日志文件，验证 --days N 是否真实按日期过滤
+OLD_LOG="$TMP/.orchestration/.logs/events-2025-01-01.jsonl"
+echo '{"ts":"2025-01-01T00:00:00+0800","workflow_id":"wfold","stage":"testing","event_type":"lint_fail","actor":"harness","payload":{"lint":"ancient"}}' > "$OLD_LOG"
+
+# --days 3650 应包含 ancient（近 10 年窗口覆盖 2025-01-01）
+OUT=$(bash "$QUERY" --hotspots --days 3650)
+assert "3650 天窗口包含 ancient" "echo '$OUT' | grep -q ancient"
+
+# --days 1 应排除 ancient（2025-01-01 远早于今天前 1 天）
+OUT=$(bash "$QUERY" --hotspots --days 1)
+assert "--days 1 排除 ancient" "! echo '$OUT' | grep -q ancient"
+
+echo ""
+echo "▸ 测试 3：--export 生成 CSV"
+bash "$QUERY" --export --out "$TMP/out.csv"
+assert "CSV 文件生成" "[ -f '$TMP/out.csv' ]"
+assert "CSV 含表头" "head -1 '$TMP/out.csv' | grep -q 'ts,workflow_id,stage,event_type'"
+assert "CSV 行数 >= 8" "[ \$(wc -l < '$TMP/out.csv') -ge 8 ]"
+
+echo ""
+echo "▸ 测试 4：空日志不报错"
+# 清空所有 mock 日志文件（包括测试 2b 创建的历史日志），确保目录为空
+rm -f "$TMP/.orchestration/.logs"/events-*.jsonl
+OUT=$(bash "$QUERY" --stats 2>&1)
+assert "空日志返回码 0" "bash '$QUERY' --stats >/dev/null 2>&1"
+assert "含 '无匹配事件' 提示" "echo '$OUT' | grep -qE '无匹配|无事件|no events'"
+
+echo ""
+echo "结果: $PASS 通过 / $FAIL 失败"
+[ "$FAIL" -eq 0 ]

package/scripts/hooks/README.md

@@ -0,0 +1,49 @@
+# scripts/hooks — Hook Dispatcher
+
+**单一入口**：`dispatcher.cjs <event>` 读 stdin JSON、路由到对应 checks、失败 `exit 2`（错误回注 Claude 上下文）。
+
+## 事件 → Checks 映射
+
+| 事件 | 触发时机 | 执行的 checks |
+|------|----------|---------------|
+| `post-edit` | `PostToolUse: Write\|Edit` | `claude-md-size`, `empty-docs` |
+| `subagent-stop` | `SubagentStop` | `structure`, `orchestration-artifacts` |
+| `stop` | `Stop` | `structure`, `claude-md-size`, `empty-docs`, `delegation-antipatterns`, `workflow-state`, `orchestration-artifacts` |
+
+## 添加新检查
+
+1. 在 `checks/` 下新建 `<name>.cjs`，导出 `{ run(): Report, section: string }`。
+2. 在 `dispatcher.cjs` 的 `DISPATCH` 中把它加入对应事件。
+
+Report API：
+
+```js
+const { createReport } = require('../lib/runner.cjs');
+function run() {
+  const report = createReport();
+  if (badCondition) {
+    report.fail('说人话的问题描述', '说人话的修复提示');
+  }
+  return report;
+}
+```
+
+## 直接调用（调试）
+
+```bash
+echo '{}' | node scripts/hooks/dispatcher.cjs stop
+echo '{}' | node scripts/hooks/dispatcher.cjs post-edit
+echo '{}' | node scripts/hooks/dispatcher.cjs subagent-stop
+```
+
+## 退出码
+
+- `0`：无问题 或 仅 WARN
+- `1`：未知事件（调用错误）
+- `2`：有 FAIL，错误信息回注 Claude 上下文以便修复
+
+## 与 harness/ 的分工
+
+- `scripts/hooks/` — 由 `.claude/hooks.json` 自动触发的 check 集合（只读，快速）
+- `scripts/orchestration/session.cjs` — 协调会话 / worker 三件套管理（状态真相源）
+- `scripts/harness/log-event.sh` / `logs-query.sh` — 事件日志落盘与查询（CLI，可选）

package/scripts/hooks/checks/claude-md-size.cjs

@@ -0,0 +1,21 @@
+'use strict';
+
+const { createReport, readFileSafe } = require('../lib/runner.cjs');
+
+const MAX_LINES = 100;
+
+function run() {
+  const report = createReport();
+  const content = readFileSafe('CLAUDE.md');
+  if (content === null) return report;
+  const lines = content.split('\n').length;
+  if (lines > MAX_LINES) {
+    report.fail(
+      `CLAUDE.md 超过 ${MAX_LINES} 行（当前 ${lines} 行）`,
+      'CLAUDE.md 应保持为目录式入口，详细内容移至 docs/'
+    );
+  }
+  return report;
+}
+
+module.exports = { run, section: 'CLAUDE.md 体积检查' };

package/scripts/hooks/checks/delegation-antipatterns.cjs

@@ -0,0 +1,66 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { createReport, ROOT, relPosix } = require('../lib/runner.cjs');
+
+const SCAN_DIRS = ['docs', 'skills', '.claude'];
+const EXCLUDE_FILES = new Set([
+  'docs/rules/agents.md',
+  'docs/red-flags.md',
+  'scripts/hooks/checks/delegation-antipatterns.cjs'
+]);
+
+const PATTERNS = [
+  {
+    re: /\.dev-agents\//g,
+    fix: '旧目录已移除；使用 .orchestration/<session>/<worker>/ 或 docs/PROJECT_CONTEXT.md'
+  },
+  {
+    re: /\.orchestration\/(ella|jarvis|kyle)\//g,
+    fix: '禁止按角色建协调目录；worker 应按职能（planner/architect/code-reviewer...）命名'
+  },
+  {
+    re: /(读取|加载|load|read)[^\n]{0,20}\.claude\/agents\/[a-z-]+\.md[^\n]{0,20}(你的角色|角色|persona|role)/gi,
+    fix: 'Claude Code 原生已自动加载 agent frontmatter，prompt 里不要再让 agent 读自己的定义'
+  }
+];
+
+function walk(dir, acc = []) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch (_error) {
+    return acc;
+  }
+  for (const entry of entries) {
+    if (entry.name.startsWith('.') && entry.name !== '.claude') continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === 'node_modules' || entry.name === 'everything-claude-code') continue;
+      walk(full, acc);
+    } else if (entry.isFile() && (full.endsWith('.md') || full.endsWith('.toml'))) {
+      acc.push(full);
+    }
+  }
+  return acc;
+}
+
+function run() {
+  const report = createReport();
+  const files = SCAN_DIRS.flatMap(dir => walk(path.join(ROOT, dir)));
+  for (const file of files) {
+    const rel = relPosix(file);
+    if (EXCLUDE_FILES.has(rel)) continue;
+    const content = fs.readFileSync(file, 'utf8');
+    for (const { re, fix } of PATTERNS) {
+      re.lastIndex = 0;
+      if (re.test(content)) {
+        report.fail(`${rel}: 命中反模式 /${re.source}/`, fix);
+      }
+    }
+  }
+  return report;
+}
+
+module.exports = { run, section: '派遣契约反模式检查' };

package/scripts/hooks/checks/empty-docs.cjs

@@ -0,0 +1,32 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { createReport, ROOT, relPosix } = require('../lib/runner.cjs');
+
+const MIN_BYTES = 50;
+
+function run() {
+  const report = createReport();
+  const docsDir = path.join(ROOT, 'docs');
+  let entries;
+  try {
+    entries = fs.readdirSync(docsDir, { withFileTypes: true });
+  } catch (_error) {
+    return report;
+  }
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+    const full = path.join(docsDir, entry.name);
+    const size = fs.statSync(full).size;
+    if (size < MIN_BYTES) {
+      report.fail(
+        `${relPosix(full)} 内容过少（${size} bytes）`,
+        '文档不应为空壳，请补充实质内容或删除'
+      );
+    }
+  }
+  return report;
+}
+
+module.exports = { run, section: 'docs 空壳检查' };

package/scripts/hooks/checks/orchestration-artifacts.cjs

@@ -0,0 +1,65 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { createReport, ROOT, relPosix, dirExists } = require('../lib/runner.cjs');
+
+const COORD_ROOT = path.join(ROOT, '.orchestration');
+const STAGE1_RE = /(stage.?1|阶段.?1|规格符合)/i;
+const STAGE2_RE = /(stage.?2|阶段.?2|代码质量)/i;
+
+function run() {
+  const report = createReport();
+  if (!dirExists('.orchestration')) return report;
+
+  const sessions = fs.readdirSync(COORD_ROOT, { withFileTypes: true })
+    .filter(entry => entry.isDirectory() && !entry.name.startsWith('.'));
+
+  for (const session of sessions) {
+    const sessionDir = path.join(COORD_ROOT, session.name);
+    const workers = fs.readdirSync(sessionDir, { withFileTypes: true })
+      .filter(entry => entry.isDirectory());
+
+    for (const worker of workers) {
+      const workerDir = path.join(sessionDir, worker.name);
+      const statusFile = path.join(workerDir, 'status.md');
+
+      // 轻量 worker：只要求 handoff + status，跳过 task.md
+      let lightweight = false;
+      try {
+        const raw = fs.readFileSync(statusFile, 'utf8');
+        lightweight = /^\s*-\s*Lightweight:\s*true/m.test(raw);
+      } catch (_error) { /* fall through */ }
+
+      const required = lightweight
+        ? ['handoff.md', 'status.md']
+        : ['task.md', 'handoff.md', 'status.md'];
+
+      for (const file of required) {
+        const full = path.join(workerDir, file);
+        if (!fs.existsSync(full)) {
+          report.fail(
+            `${relPosix(workerDir)}/ 缺失 ${file}${lightweight ? '（轻量 worker）' : ''}`,
+            '用 node scripts/orchestration/session.cjs add-worker 创建（轻量加 --lightweight）'
+          );
+        }
+      }
+
+      if (worker.name === 'code-reviewer') {
+        const handoff = path.join(workerDir, 'handoff.md');
+        if (fs.existsSync(handoff)) {
+          const content = fs.readFileSync(handoff, 'utf8');
+          if (!STAGE1_RE.test(content) && !STAGE2_RE.test(content)) {
+            report.fail(
+              `${relPosix(handoff)} 缺少阶段标识`,
+              '审查报告必须含 Stage 1 (规格符合性) 和 Stage 2 (代码质量)'
+            );
+          }
+        }
+      }
+    }
+  }
+  return report;
+}
+
+module.exports = { run, section: 'Orchestration 产物检查' };

package/scripts/hooks/checks/structure.cjs

@@ -0,0 +1,23 @@
+'use strict';
+
+const { createReport, dirExists } = require('../lib/runner.cjs');
+
+const REQUIRED_DIRS = [
+  { path: '.orchestration', hint: 'mkdir -p .orchestration' },
+  { path: '.orchestration/.logs', hint: 'mkdir -p .orchestration/.logs' },
+  { path: '.claude/agents', hint: 'agent 定义根' },
+  { path: 'skills', hint: 'skill 根（扁平结构）' },
+  { path: 'docs/rules', hint: '强制规则集' }
+];
+
+function run() {
+  const report = createReport();
+  for (const entry of REQUIRED_DIRS) {
+    if (!dirExists(entry.path)) {
+      report.fail(`缺失目录 ${entry.path}/`, entry.hint);
+    }
+  }
+  return report;
+}
+
+module.exports = { run, section: '基础结构检查' };

package/scripts/hooks/checks/workflow-state.cjs

@@ -0,0 +1,56 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { createReport, ROOT, relPosix, dirExists } = require('../lib/runner.cjs');
+
+// 真相源：.orchestration/<session>/<worker>/status.md
+// 在 Stop 事件中：若任一 worker state=running，说明主会话要停但 worker 没走到终态。
+// 终态：completed | failed | blocked （完成、失败、主动阻塞都允许 Stop）
+
+const TERMINAL_STATES = new Set(['completed', 'failed', 'blocked']);
+
+function readState(statusFile) {
+  try {
+    const content = fs.readFileSync(statusFile, 'utf8');
+    const match = content.match(/^\s*-\s*State:\s*(\S+)/m);
+    return match ? match[1].toLowerCase() : null;
+  } catch (_error) {
+    return null;
+  }
+}
+
+function run() {
+  const report = createReport();
+  if (!dirExists('.orchestration')) return report;
+
+  const coordRoot = path.join(ROOT, '.orchestration');
+  const sessions = fs.readdirSync(coordRoot, { withFileTypes: true })
+    .filter(entry => entry.isDirectory() && !entry.name.startsWith('.'));
+
+  const stuck = [];
+  for (const session of sessions) {
+    const sessionDir = path.join(coordRoot, session.name);
+    const workers = fs.readdirSync(sessionDir, { withFileTypes: true })
+      .filter(entry => entry.isDirectory());
+
+    for (const worker of workers) {
+      const statusFile = path.join(sessionDir, worker.name, 'status.md');
+      const state = readState(statusFile);
+      if (state === 'running') {
+        stuck.push(relPosix(statusFile));
+      }
+    }
+  }
+
+  if (stuck.length > 0) {
+    report.fail(
+      `以下 worker 仍在 running：${stuck.join(', ')}`,
+      '完成 worker 后运行 `node scripts/orchestration/session.cjs set-status <session> <worker> completed`；主动放弃用 `failed` 或 `blocked`'
+    );
+  }
+
+  return report;
+}
+
+module.exports = { run, section: '工作流 worker 状态检查' };

package/scripts/hooks/dispatcher.cjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+'use strict';
+
+// Hook dispatcher —— 按事件类型路由到对应 checks。
+// 每个 check 模块必须导出 { run(): Report, section: string }。
+// 任一 FAIL → exit 2（错误回注 Claude 上下文）；仅 WARN → exit 0。
+
+const { readJsonStdinSync } = require('./lib/runner.cjs');
+
+const DISPATCH = {
+  'post-edit': [
+    require('./checks/claude-md-size.cjs'),
+    require('./checks/empty-docs.cjs')
+  ],
+  stop: [
+    require('./checks/structure.cjs'),
+    require('./checks/claude-md-size.cjs'),
+    require('./checks/empty-docs.cjs'),
+    require('./checks/delegation-antipatterns.cjs'),
+    require('./checks/workflow-state.cjs'),
+    require('./checks/orchestration-artifacts.cjs')
+  ],
+  'subagent-stop': [
+    require('./checks/structure.cjs'),
+    require('./checks/orchestration-artifacts.cjs')
+  ]
+};
+
+function main() {
+  const [, , event] = process.argv;
+  const checks = DISPATCH[event];
+  if (!checks) {
+    console.error(`unknown event: ${event}`);
+    process.exit(1);
+  }
+
+  readJsonStdinSync();
+
+  const sections = [];
+  let hasFail = false;
+  for (const check of checks) {
+    const report = check.run();
+    if (!report.hasAny()) continue;
+    sections.push(report.render(check.section));
+    if (report.hasFail()) hasFail = true;
+  }
+
+  if (sections.length === 0) process.exit(0);
+
+  const output = sections.join('\n\n');
+  if (hasFail) {
+    console.error('Harness 检测到问题：');
+    console.error('');
+    console.error(output);
+    console.error('');
+    console.error('修复上述 [FAIL] 项后重试。');
+    process.exit(2);
+  }
+
+  console.log(output);
+  process.exit(0);
+}
+
+main();

package/scripts/hooks/lib/runner.cjs

@@ -0,0 +1,81 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.resolve(__dirname, '..', '..', '..');
+
+function readJsonStdinSync() {
+  try {
+    const raw = fs.readFileSync(0, 'utf8');
+    if (!raw.trim()) return {};
+    return JSON.parse(raw);
+  } catch (_error) {
+    return {};
+  }
+}
+
+function createReport() {
+  const issues = [];
+  return {
+    fail(msg, fix) {
+      issues.push({ level: 'FAIL', msg, fix });
+    },
+    warn(msg, fix) {
+      issues.push({ level: 'WARN', msg, fix });
+    },
+    hasFail() {
+      return issues.some(i => i.level === 'FAIL');
+    },
+    hasAny() {
+      return issues.length > 0;
+    },
+    render(section) {
+      if (issues.length === 0) return '';
+      const lines = [`--- ${section} ---`];
+      for (const i of issues) {
+        lines.push(`[${i.level}] ${i.msg}`);
+        if (i.fix) lines.push(`[FIX] ${i.fix}`);
+      }
+      return lines.join('\n');
+    }
+  };
+}
+
+function relPosix(p) {
+  return path.relative(ROOT, p).split(path.sep).join('/');
+}
+
+function fileExists(p) {
+  try {
+    return fs.statSync(path.resolve(ROOT, p)).isFile();
+  } catch (_error) {
+    return false;
+  }
+}
+
+function dirExists(p) {
+  try {
+    return fs.statSync(path.resolve(ROOT, p)).isDirectory();
+  } catch (_error) {
+    return false;
+  }
+}
+
+function readFileSafe(p) {
+  try {
+    return fs.readFileSync(path.resolve(ROOT, p), 'utf8');
+  } catch (_error) {
+    return null;
+  }
+}
+
+module.exports = {
+  ROOT,
+  readJsonStdinSync,
+  createReport,
+  relPosix,
+  fileExists,
+  dirExists,
+  readFileSafe
+};