aigroup-workflow 1.2.7 → 1.3.0

package/.claude/agents/init-architect.md

@@ -20,30 +20,15 @@ color: orange
 
 ## 一.5、aiGroup 框架保护（铁律）
 
-当调用方传入 `preserve_framework=true` 时，写入**根** `CLAUDE.md` 必须遵守以下规则：
+当调用方传入 `preserve_framework=true` 时：
 
-1. **先读后写**：写入前读取现有根 `CLAUDE.md`，定位框架特征标记（任一命中即判定为框架内容）：
-   - `## 角色：麦克斯 (Max)`
-   - `## 全局铁律`
-   - `## 行为门控`
-   - `## 团队派遣`
-   - `<!-- aiGroup 框架边界` 注释行
-2. **保留区间**：从文件开头到 `<!-- aiGroup 框架边界 ... -->` 注释行（含）的全部内容**原样保留**，禁止覆盖、删除、重排、润色。若文件不含该注释但命中其他框架特征标记，则保留从开头到最后一个 `##` 框架章节末尾的全部内容。
-3. **追加区间**：仅在框架区块末尾之后追加（或更新）以下结构：
+1. **根 `CLAUDE.md` 全文受保护** — 不得覆盖、删除、追加、润色任何内容。根 CLAUDE.md 是 aiGroup 框架的导航入口，保持 ≤100 行的精简形态。
+2. **项目上下文独立存放** — 本代理生成的"项目愿景、架构总览、Mermaid 结构图、模块索引、编码规范、变更记录"等内容**全部写入 `docs/PROJECT_CONTEXT.md`**，不再追加到根 CLAUDE.md。
+3. **根 CLAUDE.md 已内置指引** — "知识库地图"表格中已有指向 `docs/PROJECT_CONTEXT.md` 的条目，无需再动。
+4. **模块级不受限** — 模块级 `<module>/CLAUDE.md` 不适用本保护规则，正常按第三节结构生成/更新。
+5. **全新项目（`preserve_framework=false`）** — 按常规方式生成完整根 `CLAUDE.md`（此时不存在框架保护需求）。
 
-   ```markdown
-   ---
-
-   # 项目上下文（由 /init-project 生成）
-
-   [项目愿景、架构总览、Mermaid 结构图、模块索引、编码规范、变更记录等]
-   ```
-
-4. **增量更新**：若 `# 项目上下文（由 /init-project 生成）` 区块已存在，仅更新该区块内容，禁止触碰上方框架区块。
-5. **全新项目**：当 `preserve_framework=false` 或未检测到框架特征标记时，按常规方式生成完整根 `CLAUDE.md`，无需保护。
-6. **模块级不受限**：模块级 `<module>/CLAUDE.md` 不适用本保护规则，正常按第三节结构生成/更新。
-
-> 违反本节任何一条 = 破坏 aiGroup 框架 = 必须回滚。
+> 违反第 1 条 = 破坏 aiGroup 框架 = 必须回滚。
 
 ## 二、分阶段策略（自动选择强度）
 
@@ -71,19 +56,19 @@ color: orange
 
 ## 三、产物与增量更新
 
-1.  **写入根级 `CLAUDE.md`**
+1.  **写入 `docs/PROJECT_CONTEXT.md`（preserve_framework=true 时）**
     - 如果已存在，则在顶部插入/更新 `变更记录 (Changelog)`。
-    - 根级结构（精简而全局）：
+    - 结构（精简而全局）：
       - 项目愿景
       - 架构总览
-      - **✨ 新增：模块结构图（Mermaid）**
+      - **✨ 模块结构图（Mermaid）**
         - 在"模块索引"表格**上方**，根据识别出的模块路径，生成一个 Mermaid `graph TD` 树形图。
         - 每个节点应可点击，并链接到对应模块的 `CLAUDE.md` 文件。
         - 示例语法：
 
           ```mermaid
           graph TD
-              A["(根) 我的项目"] --> B["packages"];
+              A["(根) [项目名]"] --> B["packages"];
               B --> C["auth"];
               B --> D["ui-library"];
               A --> E["services"];
@@ -101,6 +86,8 @@ color: orange
       - AI 使用指引
       - 变更记录 (Changelog)
 
+    > **preserve_framework=false 场景**：若调用方明确不保护框架（新项目），则按原方式写入根 `CLAUDE.md`。
+
 2.  **写入模块级 `CLAUDE.md`**
     - 放在每个模块目录下，结构建议：
       - **✨ 新增：相对路径面包屑**

package/.claude/commands/init-project.md

@@ -18,38 +18,22 @@ argument-hint: <项目摘要或名称>
 
 ## ⚠️ aiGroup 框架保护（铁律）
 
-根 `CLAUDE.md` 中存在 aiGroup 框架内容时，**必须保留**，不可覆盖或删除。
+根 `CLAUDE.md` 是 aiGroup 框架的导航入口（≤ 100 行），**绝对禁止**追加项目上下文内容。
 
 ### 检测方法
 
-在写入根 `CLAUDE.md` 前，先读取现有内容，检查是否包含以下特征标记（任一命中即为框架内容）：
+读取现有根 `CLAUDE.md`，检查以下任一特征标记：
 
 - `## 角色：麦克斯 (Max)`
 - `## 全局铁律`
 - `## 行为门控`
 - `## 团队派遣`
-- `<!-- aiGroup 框架边界` 注释行
 
 ### 保护策略
 
-**如果检测到框架内容**：
+**检测到框架内容**：设置 `preserve_framework=true` 调用 `init-architect`。该代理会把项目上下文写入 `docs/PROJECT_CONTEXT.md`，**不碰**根 `CLAUDE.md`。
 
-1. **完整保留**从文件开头到 `<!-- aiGroup 框架边界 ... -->` 注释行（含）的全部内容。若文件不含该注释但命中其他框架标记，则保留到最后一个框架 `##` 章节末尾
-2. 在框架内容**末尾之后**追加分隔线和项目上下文：
-
-```markdown
----
-
-# 项目上下文（由 /init-project 生成）
-
-[项目愿景、技术栈、Mermaid 架构图、模块索引、编码规范等]
-```
-
-3. 如果已有 `# 项目上下文` 区块，只更新该区块内容，不触碰框架区块
-
-**如果未检测到框架内容**（全新项目、未安装 aiGroup）：
-
-- 正常生成完整的 `CLAUDE.md`，无需保护
+**未检测到框架内容**（全新项目）：设置 `preserve_framework=false`，按常规方式在根 `CLAUDE.md` 生成完整项目上下文。
 
 ### 模块级 CLAUDE.md
 
@@ -86,7 +70,8 @@ argument-hint: <项目摘要或名称>
 ## 输出要求
 
 - 在主对话中打印"初始化结果摘要"，包含：
-  - 根级 `CLAUDE.md` 是否创建/更新、主要栏目概览。
+  - 根级 CLAUDE.md 保护状态（preserve_framework 值；是否已检测并跳过写入）。
+  - `docs/PROJECT_CONTEXT.md` 是否创建/更新、主要栏目概览。
   - ✨ **是否检测到 aiGroup 框架并已保护**（明确说明）。
   - 识别的模块数量及其路径列表。
   - 每个模块 `CLAUDE.md` 的生成/更新情况。

package/CLAUDE.md

@@ -2,6 +2,15 @@
 
 你是麦克斯 (Max)，项目经理兼用户个人助理。不直接写代码、做设计或做测试，价值在于需求分析、任务拆解、驱动工作流、进度跟踪、风险预警、熵管理，以及通过 Agent 工具派遣子代理整合成果。
 
+## 会话启动协议
+
+Max 每次会话启动时必须：
+1. 读取 `.dev-agents/shared/memory/activeContext.md`（若存在）了解上次工作状态
+2. 读取 `.dev-agents/shared/.workflow-state`（若存在）确认活跃工作流
+3. 怀疑反复错误时运行 `bash scripts/harness/logs-query.sh --hotspots`
+
+首次使用：若 `.dev-agents/shared/memory/` 下无文件，从 `docs/templates/memory/` 复制模板（去掉 `.template` 后缀）。
+
 ## 全局铁律
 
 ```
@@ -41,6 +50,7 @@
 | 质量评分与健康度追踪 | `docs/QUALITY_SCORE.md` |
 | 技术债追踪 | `docs/tech-debt-tracker.md` |
 | Harness 转向循环 | `docs/steering-loop.md` |
+| 项目实例上下文（/init-project 生成） | `docs/PROJECT_CONTEXT.md` |
 
 ## 工作流技能
 
@@ -82,5 +92,3 @@
 ## Harness 自检
 
 开发完成后运行 `scripts/harness/run-all.sh`，按 [FAIL] 提示的 [FIX] 修复直至全部通过。
-
-<!-- aiGroup 框架边界（init-architect 保留区至此，以下由 /init-project 生成） -->

package/cli/utils/scaffold.mjs

@@ -28,7 +28,7 @@ export const BASE_DIRS = [
   '.dev-agents/shared/tasks',
   '.dev-agents/shared/designs',
   '.dev-agents/shared/reviews',
-  '.dev-agents/shared/templates',
+  'docs/templates',
   'skills/max/workflow/brainstorming',
   'skills/max/workflow/requirement-validation',
   'skills/max/workflow/solution-design',

package/docs/ARCHITECTURE.md

@@ -12,6 +12,7 @@ ai-agent-workflowGroup/
 ├── docs/                      # 知识库：详细规范与标准
 │   ├── README.md              # 知识库索引
 │   ├── ARCHITECTURE.md        # 本文件
+│   ├── templates/             # 静态文档模板（prd/implementation-plan/code-review 等）
 │   ├── workflow-pipeline.md   # 工作流管道详细规则
 │   ├── dispatch-rules.md      # 派遣规则与上下文传递
 │   ├── coding-standards.md    # 编码与 Git 规范
@@ -19,11 +20,12 @@ ai-agent-workflowGroup/
 │   ├── QUALITY_SCORE.md       # 质量评分追踪
 │   ├── tech-debt-tracker.md   # 技术债追踪
 │   └── steering-loop.md       # 转向循环机制
-├── .dev-agents/shared/        # Agent 间协作产物工作区
+├── .dev-agents/shared/        # Agent 间协作产物工作区（运行时动态）
 │   ├── tasks/                 # 实现计划
 │   ├── designs/               # 设计方案与设计稿
 │   ├── reviews/               # 审查报告
-│   └── templates/             # 文档模板
+│   ├── memory/                # 长期记忆（projectContext/activeContext/systemPatterns）
+│   └── logs/                  # 运行时事件日志（JSONL 按日滚动）
 ├── skills/                    # 技能库
 │   ├── max/                   # PM 技能
 │   │   ├── workflow/          # 工作流技能（8 阶段管道 + 横切技能）
@@ -84,3 +86,32 @@ Agent 的自由度在约束边界内最大化。
 **重要区别**：
 - **Claude Code CLI**：Hooks 自动执行，如同 git hook，Agent 无法跳过
 - **Cursor / 其他 IDE**：不支持 hooks.json，传感器需要 Agent 根据 CLAUDE.md 指令主动运行
+
+## 六层架构实现映射
+
+本项目完整实现 Harness Engineering 定义的六层架构：
+
+| 层 | 职责 | 本项目实现 |
+|----|------|-----------|
+| ① 上下文边界层 | 角色定义、信息裁剪、分层管理 | `CLAUDE.md`（< 100 行入口）+ `.claude/agents/*.md`（角色） + `docs/`（按需加载） + `skills/`（渐进式披露） |
+| ② 工具系统层 | 连接模型与现实 | `Agent(subagent_type)` 派遣 + `.dev-agents/shared/` 文件邮箱 + CLI 工具（Gemini/Qwen/Codex） |
+| ③ 执行编排层 | 任务分解为可执行步骤 | `scripts/harness/workflow-state.sh` 8 阶段状态机 + `docs/workflow-pipeline.md` + `skills/max/workflow/*` |
+| ④ 记忆与状态层 | 解决 Agent 失忆 | `.dev-agents/shared/.workflow-state`（会话状态） + `.dev-agents/shared/memory/`（长期记忆 3 件套） |
+| ⑤ 评估与观测层 | 建立质量反馈 | `scripts/harness/lint-*.sh`（5 个静态传感器） + Kyle 两阶段审查 + `.dev-agents/shared/logs/`（JSONL 事件日志） + `scripts/harness/logs-query.sh`（查询工具） |
+| ⑥ 约束校验与恢复层 | 保障鲁棒性 | `.claude/hooks.json`（运行时约束） + `docs/red-flags.md`（10 条危险信号） + `docs/steering-loop.md`（转向循环将重复错误编码为规则） |
+
+### 记忆系统详解（L4）
+
+- `memory/projectContext.md` — 项目级记忆：产品愿景、架构决策、技术栈
+- `memory/activeContext.md` — 会话级记忆：当前焦点、上次做到哪、下一步（不入 git）
+- `memory/systemPatterns.md` — 模式级记忆：代码模式、重构手法、团队约定
+
+Max 每次会话启动必读 `activeContext.md`（见 CLAUDE.md 会话启动协议）。
+
+### 观测系统详解（L5）
+
+- JSONL 按日滚动：`.dev-agents/shared/logs/events-YYYY-MM-DD.jsonl`
+- 10 种 event_type：`workflow_start/reset/exempt/complete`、`stage_enter/exit`、`dispatch`、`loop_iter`、`lint_fail`、`red_flag`
+- 写入工具：`scripts/harness/log-event.sh`（fail-silent，不阻塞主流程）
+- 查询工具：`scripts/harness/logs-query.sh`（`--stats` / `--hotspots` / `--export`）
+- Schema 详见 `.dev-agents/shared/logs/README.md`

package/docs/PROJECT_CONTEXT.md

@@ -0,0 +1,25 @@
+# 项目上下文（占位）
+
+> 此文件由 `/init-project` 首次运行时生成完整内容。
+
+## 将自动生成的内容
+
+- 项目愿景与核心价值
+- 架构总览
+- Mermaid 结构图
+- 模块索引（表格）
+- 运行与开发
+- 测试策略
+- 编码规范
+- AI 使用指引
+- 变更记录 (Changelog)
+
+## 使用
+
+消费方克隆本框架后运行：
+
+```bash
+/init-project <你的项目名或摘要>
+```
+
+即可自动填充上述内容。aiGroup 框架本身不包含任何项目实例数据。

package/docs/QUALITY_SCORE.md

@@ -14,7 +14,7 @@
 
 ## 当前质量评分
 
-> 最后更新：2026-04-11
+> 最后更新：2026-04-23
 
 | 维度 | 当前评分 | 说明 | 改进方向 |
 |------|---------|------|---------|
@@ -34,6 +34,7 @@
 | 日期 | 综合评分 | 关键变更 |
 |------|---------|---------|
 | 2026-04-11 | C+ (66) | 初始化 Harness Engineering 改造：添加 docs/ 知识库、harness 传感器、熵管理 |
+| 2026-04-23 | C+ (66) | L4 记忆层 + L5 观测层补强（commit 09f36f4...7441373） |
 
 ## 更新规则
 

package/docs/README.md

@@ -16,6 +16,11 @@ Agent 应按需检索本目录下的文档，而非依赖 CLAUDE.md 中的简短
 | [QUALITY_SCORE.md](QUALITY_SCORE.md) | 各模块质量评分与健康度追踪 | 每次审查后 |
 | [tech-debt-tracker.md](tech-debt-tracker.md) | 已知技术债与偿还计划 | 持续更新 |
 | [steering-loop.md](steering-loop.md) | Harness 转向循环：问题→编码为规则→自动执行 | 发现重复问题时 |
+| [PROJECT_CONTEXT.md](PROJECT_CONTEXT.md) | 项目实例上下文（/init-project 生成） | 项目初始化时 |
+
+## 子目录
+
+- `templates/` — 静态文档模板（PRD / 实现计划 / 代码审查等）
 
 ## 使用原则
 

package/docs/red-flags.md

@@ -13,7 +13,7 @@ Max 在工作流中必须持续监测以下危险信号。检测到任何一个
 | 5 | 审查发现问题但直接跳过 | 要求 Jarvis 修复后重新审查 | 🔴 高 |
 | 6 | 有人想跳过工作流环节 | 拒绝，除非符合简单任务豁免 | 🔴 高 |
 | 7 | 使用"应该没问题""看起来对了" | 要求提供验证命令和输出证据 | 🟡 中 |
-| 8 | 同一类错误反复出现 | 触发 [转向循环](steering-loop.md)，将修复编码为规则 | 🟡 中 |
+| 8 | 同一类错误反复出现 | 运行 `bash scripts/harness/logs-query.sh --hotspots --days 30` 查看高频失败项，再触发 [转向循环](steering-loop.md) | 🟡 中 |
 | 9 | 文档与代码不一致 | 触发 [熵管理](../skills/max/workflow/entropy-management/SKILL.md)，修复漂移 | 🟡 中 |
 | 10 | Harness 传感器长期无告警 | 审查传感器有效性，可能检测不足 | 🟡 中 |
 

package/docs/templates/memory/activeContext.template.md

@@ -0,0 +1,30 @@
+---
+last_updated: YYYY-MM-DD
+updated_by: <stage-name>
+workflow_id: <workflow-name 或 none>
+version: 1
+---
+
+# 当前工作上下文
+
+> Max 每次 advance 后更新此文件。下次会话启动时优先读取。
+
+## 当前焦点
+
+<当前工作流 ID + 阶段 + 正在做什么>
+
+## 上次做到哪
+
+<具体产出位置和关键决策>
+
+## 下一步动作
+
+<下次启动第一件事>
+
+## 开放的阻塞问题
+
+<需要用户决定的问题，如无则"无">
+
+## 近期学到的
+
+<非系统性的临时笔记，稳定后转入 systemPatterns>

package/docs/templates/memory/projectContext.template.md

@@ -0,0 +1,36 @@
+---
+last_updated: YYYY-MM-DD
+updated_by: <stage-name>
+version: 1
+---
+
+# 项目上下文
+
+> Max 在 design 阶段完成后更新此文件，记录架构决策。
+
+## 产品愿景
+
+<一句话描述本项目的使命与核心价值>
+
+## 核心架构决策
+
+| 决策 | 时间 | 上下文 | 放弃的替代方案 |
+|------|------|--------|---------------|
+| <决策名> | YYYY-MM-DD | <为什么做这个决策> | <放弃了什么> |
+
+## 技术栈
+
+- **运行时**：<语言/框架>
+- **语言**：<主要编程语言>
+- **依赖**：<关键第三方库>
+- **版本控制**：<git 策略>
+
+## 关键约束
+
+- <硬约束 1：性能/合规/兼容性>
+- <硬约束 2>
+
+## 团队惯例
+
+- <非文档化的团队约定 1>
+- <团队约定 2>

package/docs/templates/memory/systemPatterns.template.md

@@ -0,0 +1,26 @@
+---
+last_updated: YYYY-MM-DD
+updated_by: <stage-name>
+version: 1
+---
+
+# 系统模式
+
+> Kyle 审查通过后，Max 将反复出现的好/坏模式沉淀至此。
+
+## 代码模式
+
+| 模式名 | 类型 | 场景 | 示例位置 | 首次发现 |
+|--------|------|------|---------|---------|
+| <模式名> | 推荐/反模式 | <触发场景> | `<文件路径>` | YYYY-MM-DD |
+
+## 常用重构手法
+
+| 场景 | 重构方法 |
+|------|---------|
+| <场景描述> | <方法名 + 要点> |
+
+## 已沉淀的团队约定
+
+- **<约定名>**：<约定内容>
+  - *为什么*：<背后的原因或引发该约定的事件>

package/docs/workflow-pipeline.md

@@ -9,6 +9,15 @@
 
 状态机命令：`bash scripts/harness/workflow-state.sh {init|advance|gate|status|reset|exempt}`
 
+## advance 命令副作用
+
+自 2026-04-23 起，`workflow-state.sh {init|advance|reset|exempt}` 会：
+1. 写入事件到 `.dev-agents/shared/logs/events-YYYY-MM-DD.jsonl`（见 `docs/ARCHITECTURE.md` 六层架构映射）
+2. 在特定阶段切换时输出 `[REMIND]` 文案提示更新记忆文件：
+   - → design：提示更新 `projectContext.md` 记录架构决策
+   - → documentation：提示更新 `systemPatterns.md` 沉淀代码模式
+   - 所有 advance：提示更新 `activeContext.md` 反映当前状态
+
 ## 各环节详细规则
 
 ### 1. 需求收集 (brainstorming)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aigroup-workflow",
-  "version": "1.2.7",
+  "version": "1.3.0",
   "description": "AI 团队协作框架 — 通过角色派遣、工作流管道和 Harness 传感器驱动 AI 协作开发",
   "type": "module",
   "bin": {
@@ -13,7 +13,6 @@
     "docs/",
     "skills/",
     "scripts/",
-    ".dev-agents/",
     ".claude/commands/",
     ".claude/agents/",
     ".claude/hooks.json",

package/scripts/harness/lint-delegation.sh

@@ -19,7 +19,11 @@ ERRORS=0
 WARNINGS=0
 
 pass() { echo -e "  [PASS] $1"; }
-fail() { echo -e "  [FAIL] $1"; ERRORS=$((ERRORS + 1)); }
+fail() {
+    echo -e "  [FAIL] $1"
+    ERRORS=$((ERRORS + 1))
+    bash "$(dirname "${BASH_SOURCE[0]}")/log-event.sh" lint_fail --actor harness --payload "lint=delegation" 2>/dev/null || true
+}
 warn() { echo -e "  [WARN] $1"; WARNINGS=$((WARNINGS + 1)); }
 fix()  { echo -e "        [FIX] $1"; }
 
@@ -31,7 +35,7 @@ echo ""
 # ─────────────────────────────────────────
 # 扫描目标：CLAUDE.md + docs/ + skills/
 # 排除目标：.claude/agents/（规范定义自身）
-#          .dev-agents/shared/templates/（模板允许示例）
+#          docs/templates/（模板允许示例）
 #          .git/、node_modules/、.idea/
 # ─────────────────────────────────────────
 SCAN_INCLUDE=("CLAUDE.md" "docs" "skills")
@@ -42,7 +46,7 @@ scan_files() {
         | grep -v "^\.git/" \
         | grep -v "node_modules/" \
         | grep -v "\.idea/" \
-        | grep -v "/shared/templates/" \
+        | grep -v "docs/templates/" \
         || true
 }
 

package/scripts/harness/lint-docs.sh

@@ -12,7 +12,11 @@ ERRORS=0
 WARNINGS=0
 
 pass() { echo -e "  [PASS] $1"; }
-fail() { echo -e "  [FAIL] $1"; ERRORS=$((ERRORS + 1)); }
+fail() {
+    echo -e "  [FAIL] $1"
+    ERRORS=$((ERRORS + 1))
+    bash "$(dirname "${BASH_SOURCE[0]}")/log-event.sh" lint_fail --actor harness --payload "lint=docs" 2>/dev/null || true
+}
 warn() { echo -e "  [WARN] $1"; WARNINGS=$((WARNINGS + 1)); }
 fix()  { echo -e "        [FIX] $1"; }
 

package/scripts/harness/lint-process.sh

@@ -16,7 +16,11 @@ ERRORS=0
 WARNINGS=0
 
 pass() { echo -e "  [PASS] $1"; }
-fail() { echo -e "  [FAIL] $1"; ERRORS=$((ERRORS + 1)); }
+fail() {
+    echo -e "  [FAIL] $1"
+    ERRORS=$((ERRORS + 1))
+    bash "$(dirname "${BASH_SOURCE[0]}")/log-event.sh" lint_fail --actor harness --payload "lint=process" 2>/dev/null || true
+}
 warn() { echo -e "  [WARN] $1"; WARNINGS=$((WARNINGS + 1)); }
 fix()  { echo -e "        [FIX] $1"; }
 

package/scripts/harness/lint-structure.sh

@@ -12,7 +12,11 @@ ERRORS=0
 WARNINGS=0
 
 pass() { echo -e "  [PASS] $1"; }
-fail() { echo -e "  [FAIL] $1"; ERRORS=$((ERRORS + 1)); }
+fail() {
+    echo -e "  [FAIL] $1"
+    ERRORS=$((ERRORS + 1))
+    bash "$(dirname "${BASH_SOURCE[0]}")/log-event.sh" lint_fail --actor harness --payload "lint=structure" 2>/dev/null || true
+}
 warn() { echo -e "  [WARN] $1"; WARNINGS=$((WARNINGS + 1)); }
 fix()  { echo -e "        [FIX] $1"; }
 
@@ -51,7 +55,7 @@ done
 echo ""
 echo "▸ 协作产物目录检查"
 
-for dir in ".dev-agents/shared/tasks" ".dev-agents/shared/designs" ".dev-agents/shared/reviews" ".dev-agents/shared/templates"; do
+for dir in ".dev-agents/shared/tasks" ".dev-agents/shared/designs" ".dev-agents/shared/reviews" ".dev-agents/shared/memory" ".dev-agents/shared/logs" "docs/templates"; do
     if [ -d "$dir" ]; then
         pass "$dir/ 存在"
     else

package/scripts/harness/lint-workflow-artifacts.sh

@@ -12,7 +12,11 @@ ERRORS=0
 WARNINGS=0
 
 pass() { echo -e "  [PASS] $1"; }
-fail() { echo -e "  [FAIL] $1"; ERRORS=$((ERRORS + 1)); }
+fail() {
+    echo -e "  [FAIL] $1"
+    ERRORS=$((ERRORS + 1))
+    bash "$(dirname "${BASH_SOURCE[0]}")/log-event.sh" lint_fail --actor harness --payload "lint=workflow-artifacts" 2>/dev/null || true
+}
 warn() { echo -e "  [WARN] $1"; WARNINGS=$((WARNINGS + 1)); }
 fix()  { echo -e "        [FIX] $1"; }
 
@@ -38,7 +42,7 @@ if [ -d "$SHARED_DIR/tasks" ]; then
                 pass "$filename 有结构化标题"
             else
                 warn "$filename 缺少结构化标题"
-                fix "参考 .dev-agents/shared/templates/implementation-plan.md 模板重构 $plan"
+                fix "参考 docs/templates/implementation-plan.md 模板重构 $plan"
             fi
 
             if grep -q -iE "(验收|acceptance|完成标准|done)" "$plan" 2>/dev/null; then
@@ -102,10 +106,10 @@ if [ -d "$SHARED_DIR/reviews" ]; then
                 pass "$filename 包含两阶段审查"
             elif [ "$HAS_STAGE1" -gt 0 ]; then
                 warn "$filename 只有 Stage 1，缺少 Stage 2"
-                fix "补充 Stage 2 代码质量审查，参考 .dev-agents/shared/templates/code-review.md"
+                fix "补充 Stage 2 代码质量审查，参考 docs/templates/code-review.md"
             else
                 warn "$filename 审查结构不完整"
-                fix "参考 .dev-agents/shared/templates/code-review.md 重构审查报告"
+                fix "参考 docs/templates/code-review.md 重构审查报告"
             fi
         done
     else
@@ -120,13 +124,14 @@ fi
 echo ""
 echo "▸ 模板完整性检查"
 
+TEMPLATES_DIR="docs/templates"
 REQUIRED_TEMPLATES=("prd.md" "implementation-plan.md" "code-review.md")
 for tmpl in "${REQUIRED_TEMPLATES[@]}"; do
-    if [ -f "$SHARED_DIR/templates/$tmpl" ]; then
+    if [ -f "$TEMPLATES_DIR/$tmpl" ]; then
         pass "模板 $tmpl 存在"
     else
         fail "模板 $tmpl 缺失"
-        fix "创建 $SHARED_DIR/templates/$tmpl"
+        fix "创建 $TEMPLATES_DIR/$tmpl"
     fi
 done
 

package/scripts/harness/log-event.sh

@@ -0,0 +1,120 @@
+#!/bin/bash
+# ================================================================
+# Harness 事件写入工具
+#
+# 职责：将 harness 事件以 JSONL 格式追加到日志文件
+# 调用者：workflow-state.sh / lint-*.sh / Max（主动调用）
+# 设计原则：fail-silent — 写入失败不得中断调用方主流程
+#
+# 用法：
+#   log-event.sh <event_type> [--stage S] [--actor A] [--duration-ms D] [--payload k=v,k=v,...]
+#
+# 示例：
+#   log-event.sh stage_enter --actor harness
+#   log-event.sh dispatch --actor max --payload "target=jarvis,task_id=T5"
+#   log-event.sh lint_fail --payload "rule=template-missing,file=prd.md"
+#
+# 输出：.dev-agents/shared/logs/events-YYYY-MM-DD.jsonl（追加一行）
+# ================================================================
+
+EVENT_TYPE="${1:-}"
+
+if [ -z "$EVENT_TYPE" ]; then
+    echo "[log-event] ERROR: 必须提供 event_type" >&2
+    exit 1
+fi
+
+shift
+
+# ── 解析参数 ──
+STAGE_ARG=""
+ACTOR_ARG=""
+DURATION_ARG=""
+PAYLOAD_ARG=""
+
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --stage) STAGE_ARG="$2"; shift 2 ;;
+        --actor) ACTOR_ARG="$2"; shift 2 ;;
+        --duration-ms) DURATION_ARG="$2"; shift 2 ;;
+        --payload) PAYLOAD_ARG="$2"; shift 2 ;;
+        *) shift ;;
+    esac
+done
+
+# ── 读取 state 文件作为默认值 ──
+STATE_FILE=".dev-agents/shared/.workflow-state"
+DEFAULT_WORKFLOW_ID="idle"
+DEFAULT_STAGE="idle"
+
+if [ -f "$STATE_FILE" ]; then
+    WORKFLOW_ID_FROM_STATE=$(grep '^task=' "$STATE_FILE" 2>/dev/null | cut -d'=' -f2-)
+    STAGE_FROM_STATE=$(grep '^stage=' "$STATE_FILE" 2>/dev/null | cut -d'=' -f2-)
+    [ -n "$WORKFLOW_ID_FROM_STATE" ] && DEFAULT_WORKFLOW_ID="$WORKFLOW_ID_FROM_STATE"
+    [ -n "$STAGE_FROM_STATE" ] && DEFAULT_STAGE="$STAGE_FROM_STATE"
+fi
+
+STAGE="${STAGE_ARG:-$DEFAULT_STAGE}"
+ACTOR="${ACTOR_ARG:-harness}"
+WORKFLOW_ID="$DEFAULT_WORKFLOW_ID"
+
+# ── 时间戳（ISO-8601 带时区）──
+TS=$(date +%Y-%m-%dT%H:%M:%S%z)
+
+# ── JSON 字符串转义函数 ──
+json_escape() {
+    # 转义顺序：\ 先转，再转 "
+    local s="$1"
+    s="${s//\\/\\\\}"
+    s="${s//\"/\\\"}"
+    # 换行/制表符转义
+    s="${s//$'\n'/\\n}"
+    s="${s//$'\t'/\\t}"
+    echo "$s"
+}
+
+# ── 拼接 payload ──
+PAYLOAD_JSON="{}"
+if [ -n "$PAYLOAD_ARG" ]; then
+    PAYLOAD_JSON="{"
+    FIRST=1
+    # payload 用 "," 分隔 k=v 对；v 内含 "," 需用户调用方避免（本轮不支持复杂 payload）
+    IFS=',' read -ra PAIRS <<< "$PAYLOAD_ARG"
+    for pair in "${PAIRS[@]}"; do
+        K="${pair%%=*}"
+        V="${pair#*=}"
+        K_ESC=$(json_escape "$K")
+        V_ESC=$(json_escape "$V")
+        if [ "$FIRST" -eq 1 ]; then
+            PAYLOAD_JSON="${PAYLOAD_JSON}\"${K_ESC}\":\"${V_ESC}\""
+            FIRST=0
+        else
+            PAYLOAD_JSON="${PAYLOAD_JSON},\"${K_ESC}\":\"${V_ESC}\""
+        fi
+    done
+    PAYLOAD_JSON="${PAYLOAD_JSON}}"
+fi
+
+# ── duration_ms 字段（可选）──
+DURATION_FIELD=""
+if [ -n "$DURATION_ARG" ]; then
+    # 仅接受数字
+    if echo "$DURATION_ARG" | grep -qE '^[0-9]+$'; then
+        DURATION_FIELD=",\"duration_ms\":${DURATION_ARG}"
+    fi
+fi
+
+# ── 拼接最终 JSON（字段顺序固定）──
+JSON="{\"ts\":\"${TS}\",\"workflow_id\":\"$(json_escape "$WORKFLOW_ID")\",\"stage\":\"$(json_escape "$STAGE")\",\"event_type\":\"$(json_escape "$EVENT_TYPE")\",\"actor\":\"$(json_escape "$ACTOR")\"${DURATION_FIELD},\"payload\":${PAYLOAD_JSON}}"
+
+# ── 写入（fail-silent）──
+LOG_DIR=".dev-agents/shared/logs"
+LOG_FILE="${LOG_DIR}/events-$(date +%Y-%m-%d).jsonl"
+
+{
+    mkdir -p "$LOG_DIR" 2>/dev/null
+    echo "$JSON" >> "$LOG_FILE" 2>/dev/null
+} || true
+
+# 永远返回 0，即使写入失败
+exit 0

package/scripts/harness/logs-query.sh

@@ -0,0 +1,189 @@
+#!/bin/bash
+# ================================================================
+# Harness 日志查询工具
+#
+# 用法：
+#   logs-query.sh --stats [workflow_id]
+#   logs-query.sh --hotspots [--days N]
+#   logs-query.sh --export [--days N] [--out PATH]
+#
+# 实现：纯 bash + grep + sed，无 jq 依赖
+# ================================================================
+
+LOG_DIR=".dev-agents/shared/logs"
+
+# ── 辅助：返回近 N 天内的日志文件路径（一行一个）──
+# 基于文件名 events-YYYY-MM-DD.jsonl 解析日期并与 (today - N 天) 比较。
+# date -d 不可用时（非 GNU date 环境）兜底为返回全部文件。
+get_log_files_within_days() {
+    local days="$1"
+    local cutoff_ts
+    cutoff_ts=$(date -d "$days days ago" +%s 2>/dev/null || echo "0")
+    if [ "$cutoff_ts" -eq 0 ]; then
+        ls -1 "$LOG_DIR"/events-*.jsonl 2>/dev/null
+        return
+    fi
+    for f in "$LOG_DIR"/events-*.jsonl; do
+        [ -f "$f" ] || continue
+        local fname
+        fname=$(basename "$f")
+        local fdate
+        fdate=$(echo "$fname" | sed -n 's/^events-\([0-9]\{4\}-[0-9]\{2\}-[0-9]\{2\}\)\.jsonl$/\1/p')
+        [ -z "$fdate" ] && continue
+        local fts
+        fts=$(date -d "$fdate" +%s 2>/dev/null || echo "0")
+        if [ "$fts" -ge "$cutoff_ts" ]; then
+            echo "$f"
+        fi
+    done
+}
+
+cmd_stats() {
+    local wf_id="$1"
+    local state_file=".dev-agents/shared/.workflow-state"
+    if [ -z "$wf_id" ] && [ -f "$state_file" ]; then
+        wf_id=$(grep '^task=' "$state_file" 2>/dev/null | cut -d'=' -f2-)
+    fi
+    wf_id="${wf_id:-unknown}"
+
+    if [ ! -d "$LOG_DIR" ]; then
+        echo "[INFO] 无匹配事件（logs 目录不存在）"
+        return 0
+    fi
+
+    local files
+    files=$(ls -1 "$LOG_DIR"/events-*.jsonl 2>/dev/null)
+    if [ -z "$files" ]; then
+        echo "[INFO] 无匹配事件"
+        return 0
+    fi
+
+    echo "======================================"
+    echo "  工作流统计: $wf_id"
+    echo "======================================"
+    echo ""
+    echo "▸ 阶段耗时（ms）"
+
+    # 提取 stage_exit 事件，按 stage 聚合 duration_ms
+    grep -h "\"workflow_id\":\"${wf_id}\"" $files 2>/dev/null \
+        | grep "\"event_type\":\"stage_exit\"" \
+        | while IFS= read -r line; do
+            stage=$(echo "$line" | sed -n 's/.*"stage":"\([^"]*\)".*/\1/p')
+            dur=$(echo "$line" | sed -n 's/.*"duration_ms":\([0-9]*\).*/\1/p')
+            [ -n "$stage" ] && [ -n "$dur" ] && echo "$stage $dur"
+        done \
+        | sort \
+        | awk '
+            {
+                sum[$1] += $2
+                cnt[$1] += 1
+            }
+            END {
+                for (s in sum) printf "  %-16s %10d ms (× %d)\n", s, sum[s], cnt[s]
+            }
+        '
+
+    echo ""
+    echo "▸ 循环次数"
+    local loop_count
+    loop_count=$(grep -h "\"workflow_id\":\"${wf_id}\"" $files 2>/dev/null \
+        | grep -c "\"event_type\":\"loop_iter\"")
+    echo "  Kyle 审查-修复循环: $loop_count 次"
+}
+
+cmd_hotspots() {
+    local days="${1:-30}"
+    if [ ! -d "$LOG_DIR" ]; then
+        echo "[INFO] 无匹配事件"
+        return 0
+    fi
+
+    local files
+    files=$(get_log_files_within_days "$days")
+    if [ -z "$files" ]; then
+        echo "[INFO] 无匹配事件"
+        return 0
+    fi
+
+    echo "======================================"
+    echo "  失败热点（近 $days 天 top 10）"
+    echo "======================================"
+    echo ""
+    echo "▸ lint_fail 规则 top 10"
+
+    # 字段契约：lint_fail 事件 payload 使用 lint=<name>（任务 8.1 修正后）；
+    # red_flag 事件 payload 使用 flag_id=<id>。两种事件按各自字段聚合。
+    grep -h -E '"event_type":"(lint_fail|red_flag)"' $files 2>/dev/null \
+        | while IFS= read -r line; do
+            lint=$(echo "$line" | sed -n 's/.*"lint":"\([^"]*\)".*/\1/p')
+            flag=$(echo "$line" | sed -n 's/.*"flag_id":"\([^"]*\)".*/\1/p')
+            type=$(echo "$line" | sed -n 's/.*"event_type":"\([^"]*\)".*/\1/p')
+            key="${lint}${flag}"
+            [ -n "$key" ] && echo "${type}:${key}"
+        done \
+        | sort | uniq -c | sort -rn | head -10 \
+        | awk '{printf "  %-40s %d 次\n", $2, $1}'
+}
+
+cmd_export() {
+    local days=30
+    local out="events-export.csv"
+    while [ $# -gt 0 ]; do
+        case "$1" in
+            --days) days="$2"; shift 2 ;;
+            --out) out="$2"; shift 2 ;;
+            *) shift ;;
+        esac
+    done
+
+    if [ ! -d "$LOG_DIR" ]; then
+        echo "ts,workflow_id,stage,event_type,actor,duration_ms" > "$out"
+        echo "[INFO] 无事件数据，已生成空 CSV: $out"
+        return 0
+    fi
+
+    echo "ts,workflow_id,stage,event_type,actor,duration_ms" > "$out"
+
+    # --days N 真实过滤：只导出近 N 天内的日志文件
+    while IFS= read -r f; do
+        [ -f "$f" ] || continue
+        while IFS= read -r line; do
+            ts=$(echo "$line" | sed -n 's/.*"ts":"\([^"]*\)".*/\1/p')
+            wf=$(echo "$line" | sed -n 's/.*"workflow_id":"\([^"]*\)".*/\1/p')
+            stg=$(echo "$line" | sed -n 's/.*"stage":"\([^"]*\)".*/\1/p')
+            et=$(echo "$line" | sed -n 's/.*"event_type":"\([^"]*\)".*/\1/p')
+            ac=$(echo "$line" | sed -n 's/.*"actor":"\([^"]*\)".*/\1/p')
+            dur=$(echo "$line" | sed -n 's/.*"duration_ms":\([0-9]*\).*/\1/p')
+            echo "$ts,$wf,$stg,$et,$ac,$dur" >> "$out"
+        done < "$f"
+    done <<< "$(get_log_files_within_days "$days")"
+
+    echo "[OK] 已导出到 $out（$(wc -l < "$out") 行）"
+}
+
+# ── 入口 ──
+case "${1:-}" in
+    --stats)
+        shift
+        cmd_stats "$@"
+        ;;
+    --hotspots)
+        shift
+        DAYS=30
+        while [ $# -gt 0 ]; do
+            case "$1" in
+                --days) DAYS="$2"; shift 2 ;;
+                *) shift ;;
+            esac
+        done
+        cmd_hotspots "$DAYS"
+        ;;
+    --export)
+        shift
+        cmd_export "$@"
+        ;;
+    *)
+        echo "用法: logs-query.sh {--stats [workflow_id]|--hotspots [--days N]|--export [--days N] [--out PATH]}" >&2
+        exit 1
+        ;;
+esac

package/scripts/harness/tests/test-log-event.sh

@@ -0,0 +1,86 @@
+#!/bin/bash
+# 单元测试：log-event.sh
+# 运行：bash scripts/harness/tests/test-log-event.sh
+
+set -e
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
+LOG_EVENT="$ROOT/scripts/harness/log-event.sh"
+
+# 用临时目录做隔离测试
+TMP=$(mktemp -d)
+trap "rm -rf $TMP" EXIT
+
+cd "$TMP"
+mkdir -p .dev-agents/shared
+cat > .dev-agents/shared/.workflow-state <<EOF
+stage=testing
+task=test-task
+started=2026-04-23 00:00:00
+exempt=false
+updated=2026-04-23 00:00:00
+EOF
+
+PASS=0
+FAIL=0
+
+assert() {
+    local msg="$1"
+    local cond="$2"
+    if eval "$cond"; then
+        echo "  [PASS] $msg"
+        PASS=$((PASS + 1))
+    else
+        echo "  [FAIL] $msg"
+        echo "         条件: $cond"
+        FAIL=$((FAIL + 1))
+    fi
+}
+
+echo "▸ 测试 1：基础事件写入"
+bash "$LOG_EVENT" stage_enter --actor harness
+LOG_FILE=".dev-agents/shared/logs/events-$(date +%Y-%m-%d).jsonl"
+assert "日志文件已创建" "[ -f '$LOG_FILE' ]"
+assert "事件类型正确" "grep -q '\"event_type\":\"stage_enter\"' '$LOG_FILE'"
+assert "workflow_id 从 state 读取" "grep -q '\"workflow_id\":\"test-task\"' '$LOG_FILE'"
+assert "stage 从 state 读取" "grep -q '\"stage\":\"testing\"' '$LOG_FILE'"
+assert "actor 正确" "grep -q '\"actor\":\"harness\"' '$LOG_FILE'"
+
+echo ""
+echo "▸ 测试 2：payload 解析"
+bash "$LOG_EVENT" dispatch --actor max --payload "target=jarvis,task_id=T5"
+assert "payload 包含 target" "grep -q '\"target\":\"jarvis\"' '$LOG_FILE'"
+assert "payload 包含 task_id" "grep -q '\"task_id\":\"T5\"' '$LOG_FILE'"
+
+echo ""
+echo "▸ 测试 3：duration_ms 字段"
+bash "$LOG_EVENT" stage_exit --duration-ms 12345
+assert "duration_ms 存在且为数字" "grep -q '\"duration_ms\":12345' '$LOG_FILE'"
+
+echo ""
+echo "▸ 测试 4：state 文件缺失时 fallback 为 idle"
+rm .dev-agents/shared/.workflow-state
+bash "$LOG_EVENT" workflow_reset
+assert "无 state 时 workflow_id 为 idle" "grep -q '\"workflow_id\":\"idle\"' '$LOG_FILE'"
+assert "无 state 时 stage 为 idle" "tail -1 '$LOG_FILE' | grep -q '\"stage\":\"idle\"'"
+
+echo ""
+echo "▸ 测试 5：特殊字符转义"
+cat > .dev-agents/shared/.workflow-state <<EOF
+stage=design
+task=test-task
+started=2026-04-23 00:00:00
+exempt=false
+EOF
+bash "$LOG_EVENT" red_flag --actor max --payload 'msg=has "quotes" and \ backslash'
+assert "双引号被转义" "tail -1 '$LOG_FILE' | grep -q '\\\\\"quotes\\\\\"'"
+
+echo ""
+echo "▸ 测试 6：ts 字段 ISO-8601 格式"
+assert "ts 字段格式合法" "tail -1 '$LOG_FILE' | grep -qE '\"ts\":\"[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}[+-][0-9]{4}\"'"
+
+echo ""
+echo "======================================"
+echo "  结果: $PASS 通过 / $FAIL 失败"
+echo "======================================"
+[ "$FAIL" -eq 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 .dev-agents/shared/logs
+TODAY=$(date +%Y-%m-%d)
+LOG="$TMP/.dev-agents/shared/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/.dev-agents/shared/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/.dev-agents/shared/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/harness/workflow-state.sh

@@ -83,6 +83,32 @@ updated=$(date '+%Y-%m-%d %H:%M:%S')
 EOF
 }
 
+# 计算自上次 updated 以来的毫秒数（用于 stage_exit duration）
+compute_stage_duration_ms() {
+    local last_updated
+    last_updated=$(get_field "updated")
+    if [ -z "$last_updated" ]; then
+        echo "0"
+        return
+    fi
+    local last_ts
+    last_ts=$(date -d "$last_updated" +%s 2>/dev/null || echo "0")
+    local now_ts
+    now_ts=$(date +%s)
+    if [ "$last_ts" -eq 0 ]; then
+        echo "0"
+    else
+        echo $(( (now_ts - last_ts) * 1000 ))
+    fi
+}
+
+# 调用 log-event.sh（失败不报错）
+log_event() {
+    local script_dir
+    script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+    bash "$script_dir/log-event.sh" "$@" 2>/dev/null || true
+}
+
 stage_index() {
     local target="$1"
     for i in "${!STAGES[@]}"; do
@@ -146,9 +172,12 @@ cmd_init() {
     fi
 
     write_state "brainstorming" "$task_name" "$(date '+%Y-%m-%d %H:%M:%S')"
+    log_event workflow_start --stage brainstorming --payload "task_name=$task_name"
+    log_event stage_enter --stage brainstorming
     echo "[OK] 工作流已启动: $task_name"
     echo "[STATE] 当前阶段: brainstorming（需求收集）"
     echo "[NEXT] 收集和分析功能需求，记录到 .dev-agents/shared/designs/ 后运行 advance"
+    echo "[REMIND] 若本工作流涉及架构决策，完成后请更新 .dev-agents/shared/memory/activeContext.md"
 }
 
 cmd_advance() {
@@ -235,12 +264,18 @@ cmd_advance() {
     local next
     next=$(next_stage "$current_stage")
 
+    local stage_duration_ms
+    stage_duration_ms=$(compute_stage_duration_ms)
+    log_event stage_exit --stage "$current_stage" --duration-ms "$stage_duration_ms" --payload "next_stage=$next"
+
     if [ "$next" = "idle" ]; then
         write_state "idle" "" "" "false"
+        log_event workflow_complete --stage idle --payload "prev_stage=$current_stage"
         echo "[OK] 工作流已完成: $task"
         echo "[STATE] 状态已重置为 idle"
     else
         write_state "$next" "$task" "$(get_field 'started')"
+        log_event stage_enter --stage "$next" --payload "prev_stage=$current_stage"
         echo "[OK] 阶段推进: $current_stage（$(stage_label "$current_stage")） → $next（$(stage_label "$next")）"
         echo "[STATE] 当前阶段: $next（$(stage_label "$next")）"
 
@@ -250,16 +285,19 @@ cmd_advance() {
             design)
                 echo "[NEXT] 设计技术方案和架构，产出方案决策文档后 advance" ;;
             planning)
-                echo "[NEXT] 将需求拆解为可执行任务，保存到 .dev-agents/shared/tasks/" ;;
+                echo "[NEXT] 将需求拆解为可执行任务，保存到 .dev-agents/shared/tasks/"
+                echo "[REMIND] 方案设计已完成，请更新 .dev-agents/shared/memory/projectContext.md 记录架构决策" ;;
             development)
                 echo "[NEXT] 派遣 Jarvis 子代理按任务执行开发" ;;
             testing)
                 echo "[NEXT] 派遣 Kyle 编写和执行测试用例，进行两阶段审查" ;;
             documentation)
-                echo "[NEXT] 更新相关文档（API 文档、README、ARCHITECTURE 等）" ;;
+                echo "[NEXT] 更新相关文档（API 文档、README、ARCHITECTURE 等）"
+                echo "[REMIND] Kyle 已通过审查，若发现值得沉淀的代码模式，请更新 .dev-agents/shared/memory/systemPatterns.md" ;;
             finishing)
                 echo "[NEXT] 执行分支收尾流程（集成/PR/归档）" ;;
         esac
+        echo "[REMIND] 阶段已推进，请同步更新 .dev-agents/shared/memory/activeContext.md 反映当前状态"
     fi
 }
 
@@ -315,6 +353,7 @@ cmd_reset() {
         return 0
     fi
 
+    log_event workflow_reset --stage "$current_stage" --payload "prev_task=${task:-unnamed}"
     write_state "idle" "" "" "false"
     echo "[OK] 工作流已重置（原任务: ${task:-未命名}，原阶段: $current_stage）"
 }
@@ -328,6 +367,7 @@ cmd_exempt() {
     fi
 
     write_state "idle" "exempt: $reason" "$(date '+%Y-%m-%d %H:%M:%S')" "true"
+    log_event workflow_exempt --stage idle --payload "reason=$reason"
     echo "[OK] 已标记为简单任务豁免: $reason"
     echo "[INFO] 豁免任务完成后请运行 workflow-state.sh reset 恢复正常模式"
 }

package/.dev-agents/shared/.workflow-state

@@ -1,5 +0,0 @@
-stage=idle
-task=exempt: 合并 Karpathy 四条编码守则到 jarvis.md（单文件配置调整，方案已对齐）
-started=2026-04-22 09:08:06
-exempt=true
-updated=2026-04-22 09:08:06