maestro-flow 0.4.17 → 0.4.19

package/.agents/skills/maestro/SKILL.md

@@ -25,7 +25,7 @@ Entry points:
 - **`/maestro --dry-run "intent"`** — Show chain, no execution
 - **`/maestro --super "intent"`** — Production-ready mode (read maestro-super.md)
 
-Session: `.workflow/.maestro/{session_id}/status.json`
+**Session**: `.workflow/.maestro/{session_id}/status.json` — 工作流唯一真源。session_id 格式 `maestro-{YYYYMMDD-HHmmss}`（本 command 创建，静态链）或 `ralph-{YYYYMMDD-HHmmss}`（`/maestro-ralph` 创建，自适应链）。两类都由 `/maestro-ralph-execute` 推进；schema 与 ralph 共用（含 `ralph_protocol_version: "1"` + `active_step_index`）。
 </purpose>
 
 <deferred_reading>

package/.agents/skills/maestro-analyze/SKILL.md

@@ -165,4 +165,9 @@ Both modes (full + quick):
 - [ ] Deferred items auto-created as issues (if any)
 - [ ] Artifact registered in state.json with correct scope/milestone/phase
 - [ ] Next step routed (impeccable/plan for Go, brainstorm for No-Go)
+- [ ] Session sealed via finish-work (archive.json written, optional spec/knowhow extraction)
 </success_criteria>
+
+<on_complete>
+@~/.maestro/workflows/finish-work.md — SESSION_DIR=OUTPUT_DIR, SESSION_TYPE=analyze, SESSION_ID={artifact_id}, LINKED_MILESTONE={target_milestone or null}
+</on_complete>

package/.agents/skills/maestro-blueprint/SKILL.md

@@ -130,4 +130,9 @@ P6 gate: Pass (>=80%) → Handoff | Review (60-79%) → Handoff w/caveats | Fail
 - [ ] Readiness gate: Pass (>=80%) or Review (>=60%) with documented caveats
 - [ ] Artifact registered in state.json (type=blueprint)
 - [ ] context-package.json generated for downstream consumption
+- [ ] On gate Pass/Review: session sealed via finish-work (archive.json + optional spec/knowhow extraction). On Fail: skip — session stays active, excluded from wiki search.
 </success_criteria>
+
+<on_complete>
+@~/.maestro/workflows/finish-work.md — SESSION_DIR={session_dir}, SESSION_TYPE=blueprint, SESSION_ID={session_id}, LINKED_MILESTONE=null
+</on_complete>

package/.agents/skills/maestro-brainstorm/SKILL.md

@@ -132,4 +132,9 @@ Single role mode:
 - [ ] `{role}/analysis-F-*.md` written when guidance §10 feature list available
 - [ ] §2 Decisions table references guidance decision IDs
 - [ ] Session metadata updated
+- [ ] Session sealed via finish-work (auto mode only)
 </success_criteria>
+
+<on_complete>
+@~/.maestro/workflows/finish-work.md — SESSION_DIR={output_dir}, SESSION_TYPE=brainstorm, SESSION_ID={artifact_id}, LINKED_MILESTONE=null
+</on_complete>

package/.agents/skills/maestro-next/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: maestro-next
+description: Single-command recommendation — pick the best next command from the pool and execute it
+argument-hint: "<intent> [-y] [--dry-run] [--top N] [--list]"
+allowed-tools:
+  - read_file
+  - shell
+  - find_files
+  - search
+  - invoke_skill
+  - ask_user
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+
+<purpose>
+单链推荐：解析 intent + project state → 路由表评分 → 推荐**单个原子命令** → 确认后通过 `invoke_skill()` 执行。
+
+与 `/maestro` / `/maestro-ralph` 区别：
+- 不创建 session、不构建 chain、不写 status.json
+- 始终只推 1 个 top pick，最多列 2-3 个备选
+- 适用场景：意图清晰且单步即可完成；或需要定向推荐时
+</purpose>
+
+<context>
+$ARGUMENTS — 意图文本 + 可选 flags。
+
+**Flags:**
+- `-y` / `--yes` — 跳过确认，直接执行 top pick
+- `--dry-run` — 仅显示推荐结果，不执行
+- `--top N` — 显示前 N 个候选（默认 3）
+- `--list` — 仅列出可推荐命令池，不做推荐
+
+**候选池：** 仅 A_SCORE_CANDIDATES 路由表中列出的命令。管线编排器（`maestro` / `maestro-ralph*` / `maestro-player` / `maestro-composer`）**永远不在候选池**。
+</context>
+
+<invariants>
+1. **不创建 session / 不写 status.json / 不触发后续 chain** — 单次原子执行，产出由目标命令自行管理
+2. **管线编排器不在候选池** — 仅推荐原子命令
+3. **空 intent 或 "继续/下一步/next/接下来"** → 直接采用 lifecycle_position 推断的自然下一步
+4. **字面命中路由表优先** — lifecycle 仅作加分；命中失败时 lifecycle 上升为决定性信号
+5. **参数传递** — 默认 intent 原文作为第一个 arg；用户可在确认环节修改；`-y` 仅当用户传入时透传到 skill args
+6. **`--list` 模式跳过 lifecycle 推断与评分**，仅按 workflow 簇分组列出全部候选
+</invariants>
+
+<state_machine>
+
+<states>
+S_PARSE     — 解析 ARGUMENTS、提取 flags                       PERSIST: —
+S_STATE     — 读 project state、推断 lifecycle_position         PERSIST: —
+S_RANK      — 路由表评分、生成 top-N candidates                 PERSIST: —
+S_LIST      — `--list` 模式：分组展示候选池                     PERSIST: —
+S_PRESENT   — 显示 top pick + 备选 + 推荐理由 + 执行参数        PERSIST: —
+S_CONFIRM   — ask_user 选择/修改参数（auto_mode 跳过）    PERSIST: —
+S_EXECUTE   — `invoke_skill({ skill, args })` 单次调用                 PERSIST: —
+S_FALLBACK  — intent 空且 clarification 失败                    PERSIST: —
+</states>
+
+<transitions>
+
+S_PARSE:
+  → S_LIST       WHEN: --list flag
+  → S_STATE      WHEN: intent text present
+  → S_STATE      WHEN: keyword "continue"/"next"/"go"/"继续"/"下一步"/"接下来"
+  → S_PARSE      WHEN: no intent (max 1 clarify round)    DO: ask_user
+  → S_FALLBACK   WHEN: clarification empty
+
+S_STATE:
+  → S_RANK       DO: A_INFER_LIFECYCLE
+
+S_RANK:
+  → S_PRESENT    DO: A_SCORE_CANDIDATES
+
+S_LIST:
+  → END          DO: 按 workflow 簇分组列出全部候选 + description
+
+S_PRESENT:
+  → END          WHEN: --dry-run
+  → S_EXECUTE    WHEN: -y / --yes
+  → S_CONFIRM    WHEN: not auto_mode
+
+S_CONFIRM:
+  → S_EXECUTE    WHEN: 用户确认 top pick / 选备选 / 改参数
+  → END          WHEN: 用户取消
+
+S_EXECUTE:
+  → END          DO: invoke_skill({ skill: <chosen>, args: <args> }) → 输出 "✅ 已执行 /<command>"
+
+S_FALLBACK:
+  → END          DO: raise E001
+
+</transitions>
+
+<actions>
+
+### A_INFER_LIFECYCLE
+
+读 project state 推断 `lifecycle_position`（核心信号）：
+
+```bash
+cat .workflow/state.json 2>$null              # phase / milestone / artifacts
+ls -la .workflow/scratch/ 2>$null | head -10  # 最近 artifact (mtime DESC)
+ls -la .workflow/.maestro/ 2>$null | head -5  # 进行中的 session
+```
+
+**项目状态 → lifecycle_position → 自然下一步：**
+
+| 项目状态 | lifecycle_position | 自然下一步 |
+|---------|-------------------|-----------|
+| 无 `.workflow/` + 无源码 | brainstorm | `maestro-brainstorm` |
+| 无 `.workflow/` + 有源码 | init | `maestro-init` |
+| 有 state.json，无 roadmap，无 milestones | analyze-macro | `maestro-analyze` (宏观调研) |
+| 有 macro analyze artifact，无 roadmap | roadmap | `maestro-roadmap` |
+| 有 roadmap，未启动 phase | analyze | `maestro-analyze {phase}` |
+| 最新 artifact = analyze | plan | `maestro-plan {phase}` |
+| 最新 artifact = plan | execute | `maestro-execute {phase}` |
+| 最新 artifact = execute | verify | `maestro-verify {phase}` |
+| verify passed | review | `quality-review {phase}` |
+| review verdict=PASS | test-gen | `quality-auto-test {phase}` |
+| 测试全绿 | milestone-audit | `maestro-milestone-audit` |
+| 当前 milestone 全 phase 完成 | milestone-complete | `maestro-milestone-complete` |
+| 任一 stage 产物含 gaps/failed | debug | `quality-debug {gap}` |
+
+**Maestro Lifecycle 主线：**
+```
+brainstorm → blueprint → init → analyze-macro → roadmap
+   → [per phase] analyze → plan → execute → verify
+   → [quality gate] review → auto-test → test
+   → milestone-audit → milestone-complete → milestone-release
+```
+
+### A_SCORE_CANDIDATES
+
+**评分信号**（高→低）：
+
+| 信号 | 权重 | 说明 |
+|------|------|------|
+| intent 命中路由表关键词 | 高 | 字面匹配主依据 |
+| **lifecycle 自然下一步** | **高** | 空 intent / "继续" / "next" 时为决定性 |
+| `name` 关键词命中 intent | 中 | intent 含 "test" → quality-test/quality-auto-test 加分 |
+| Workflow 簇匹配 | 中 | intent 涉及学习/知识/issue 等场景触发对应簇 |
+| Recent activity 反向避免 | 低 | 刚完成的 stage 短期内降权 |
+
+**特殊意图处理：**
+
+| Intent 模式 | top pick |
+|------------|---------|
+| 空 / "继续" / "下一步" / "next" / "接下来" | lifecycle 自然下一步 |
+| "什么状态" / "现在到哪了" / "status" | `manage-status` |
+| 字面命中路由表 | 路由表优先（lifecycle 仅加分） |
+| 无任何匹配 | lifecycle 下一步 + raise W002 |
+
+**意图 → 命令路由表**（候选池）：
+
+| 意图关键词 | 推荐命令 |
+|-----------|---------|
+| 头脑风暴 / 探索 / brainstorm / ideate | `maestro-brainstorm` |
+| 规格 / 正式文档 / spec-generate / blueprint | `maestro-blueprint` |
+| 分析 / analyze / 多维度调研 | `maestro-analyze` |
+| 规划 / plan / 任务分解 | `maestro-plan` |
+| 实现 / 执行 / execute | `maestro-execute` |
+| 验证 / verify / 验收 | `maestro-verify` |
+| 调试 / debug / 排查 / bug | `quality-debug` |
+| 审查 / review / 代码审查 | `quality-review` |
+| 测试 / test / UAT | `quality-test` / `quality-auto-test` |
+| 重构 / refactor / 技术债 | `quality-refactor` |
+| 同步文档 / sync docs | `quality-sync` |
+| 回顾 / retro | `quality-retrospective` / `learn-retro` |
+| issue / 缺陷管理 | `manage-issue` / `manage-issue-discover` |
+| wiki / 知识图谱 | `manage-wiki` / `wiki-connect` / `wiki-digest` |
+| spec / 规则 / 约束 | `spec-load` / `spec-add` / `spec-setup` |
+| 项目初始化 / init | `maestro-init` |
+| 状态 / status / 仪表盘 | `manage-status` |
+| 文档重建 / codebase 文档 | `manage-codebase-rebuild` / `manage-codebase-refresh` |
+| 安全 / security / OWASP | `security-audit` |
+| 跟读 / 学习 / 阅读源码 | `learn-follow` / `learn-investigate` |
+| 第二意见 / challenge / consult | `learn-second-opinion` |
+| 提取知识 / harvest | `manage-harvest` / `manage-knowhow-capture` |
+| 设计 / UI / 前端打磨 | `maestro-impeccable` |
+| 里程碑 / milestone | `maestro-milestone-audit` / `maestro-milestone-release` / `maestro-milestone-complete` |
+| fork / 分支 / 并行开发 | `maestro-fork` / `maestro-merge` |
+| 覆盖层 / overlay / amend | `maestro-overlay` / `maestro-amend` |
+
+**辅助 workflow 簇**（场景触发，非主线）：
+
+| 簇 | 触发 | 主推链路 |
+|----|------|---------|
+| Learning | 接触新代码/未知模块 | `learn-follow` → `learn-decompose` → `learn-second-opinion` |
+| Knowledge | 提炼经验 / 沉淀知识 | `manage-harvest` → `manage-knowhow-capture` → `spec-add` |
+| Wiki | 知识图谱整理 | `manage-wiki` → `wiki-connect` → `wiki-digest` |
+| Issue | 缺陷管理 | `manage-issue-discover` → `manage-issue` |
+| 文档同步 | 代码大改后 | `quality-sync` → `manage-codebase-refresh` |
+| 重构 | 技术债积累 | `quality-refactor` → `quality-review` |
+| 发布 | 里程碑结束 | `maestro-milestone-audit` → `maestro-milestone-release` |
+| 并行开发 | 多 milestone 并行 | `maestro-fork` → ... → `maestro-merge` |
+
+输出 ranked candidates，取 top N（默认 3）。
+
+</actions>
+
+</state_machine>
+
+<presentation>
+
+### `--list` 模式
+
+按 workflow 簇（主线 / Learning / Knowledge / Wiki / Issue / 文档 / 重构 / 发布 / 并行）分组展示全部候选 + description，结束。
+
+### 正常模式
+
+```
+🎯 推荐 (top pick): /<command-name>
+   <description>
+   推荐理由: <命中规则 + lifecycle 位置一句话>
+
+备选:
+  2. /<alt-1> — <description>
+  3. /<alt-2> — <description>
+
+执行参数: <args>
+```
+
+`--dry-run` 展示后结束；`-y` 直接 S_EXECUTE；否则 ask_user 提供：执行 top pick / 选备选 / 修改参数 / 取消。
+
+</presentation>
+
+<appendix>
+
+### Error Codes
+
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | intent 空且 clarification 后仍空 | 提供意图描述或使用 `--list` 浏览 |
+| E002 | error | 候选池为空（`.claude/commands/` 缺失或无 .md） | 检查 commands 目录 |
+| E003 | error | 选定命令名无法解析为有效 skill | 列出有效命令重选 |
+| W001 | warning | top1 与 top2 得分差距 < 阈值 | 强制展示前 3 让用户裁决 |
+| W002 | warning | intent 与所有候选匹配度均低 | 提示考虑 `/maestro` 或 `/maestro-ralph` 走管线 |
+
+### Success Criteria
+
+- [ ] Intent 解析 + flags 提取完成
+- [ ] 读取 `.workflow/state.json` + scratch artifacts 推断 lifecycle_position
+- [ ] 候选池等于路由表（管线编排器不在）
+- [ ] 评分综合：intent 字面匹配 + lifecycle 下一步 + workflow 簇 + recent activity
+- [ ] 空 intent / "继续" / "下一步" → 直接采用 lifecycle 推断的下一步
+- [ ] top pick 展示附"推荐理由"（命中规则 + lifecycle 位置）
+- [ ] `--dry-run` 仅展示，不执行
+- [ ] `-y` 自动执行 top pick；用户传入时透传到 skill args
+- [ ] 非自动模式通过 ask_user 确认或选备选
+- [ ] 选定命令通过单次 `invoke_skill()` 调用执行
+- [ ] 不创建 session / 不生成 status.json / 不触发后续 chain
+- [ ] `--list` 模式按 workflow 簇分组展示
+
+</appendix>

package/.agents/skills/team-swarm/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: team-swarm
+description: Swarm intelligence team skill — ACO-driven multi-agent exploration with hybrid LLM coordinator + Python optimization controller. Coordinator generates swarm-config from user task, then runs K iterations of N parallel ants guided by pheromone state. Universal task space via config (nodes + scoring rule). Triggers on "team swarm", "swarm intelligence", "蚁群".
+allowed-tools: team_create(*), team_delete(*), send_message(*), task_create(*), task_update(*), task_list(*), task_get(*), agent(*), ask_user_question(*), read(*), write(*), edit(*), bash(*), glob(*), grep(*), mcp__ccw-tools__team_msg(*)
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+
+# Team Swarm
+
+Orchestrate ant-colony-style exploration over a user-defined task space. **Hybrid coordinator**: LLM handles task translation + worker spawning; Python script owns all numeric decisions (selection / pheromone update / convergence). Universal — task space and scoring rule come from `swarm-config.json`.
+
+## Architecture
+
+```
+invoke_skill(skill="team-swarm", args="task description")
+                    |
+         SKILL.md (this file) = Router
+                    |
+     +--------------+--------------+
+     |                             |
+  no --role flag              --role <name>
+     |                             |
+  Coordinator                  Worker
+  roles/coordinator/role.md    roles/<name>/role.md
+     |
+     +-- Phase 1: gen swarm-config
+     +-- Phase 2: init  --> Bash: scripts/aco.py init
+     +-- Phase 3: iterate (K rounds, each = spawn-and-stop)
+     |   |
+     |   +-- Bash: aco.py select --iter k  -> N assignments
+     |   +-- Spawn N x team-worker(ant)
+     |   +-- [callback when all ants done]
+     |   +-- (optional) Spawn team-worker(scorer)
+     |   +-- Bash: aco.py update --iter k
+     |   +-- Bash: aco.py converged
+     |   +-- branch: loop k+1 OR Phase 4
+     |
+     +-- Phase 4: converge --> Bash: aco.py report -> Spawn team-worker(analyst)
+                                                    -> best-solution.md
+```
+
+## Role Registry
+
+| Role | Path | Prefix | Inner Loop |
+|------|------|--------|------------|
+| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | — | — |
+| ant | [roles/ant/role.md](roles/ant/role.md) | ANT-* | false |
+| scorer | [roles/scorer/role.md](roles/scorer/role.md) | SCORE-* | false |
+| analyst | [roles/analyst/role.md](roles/analyst/role.md) | ANALYST-* | false |
+
+## Role Router
+
+Parse `$ARGUMENTS`:
+- Has `--role <name>` -> Read `roles/<name>/role.md`, execute Phase 2-4
+- No `--role` -> `@roles/coordinator/role.md`, execute entry router
+
+## Shared Constants
+
+- **Session prefix**: `TS`
+- **Session path**: `.workflow/.team/TS-<slug>-<date>/`
+- **Team name**: `swarm`
+- **Script root**: `<skill_root>/scripts/aco.py` (Python 3.10+)
+- **Message bus**: `mcp__ccw-tools__team_msg(session_id=<session-id>, ...)`
+
+## Worker Spawn Template
+
+Coordinator spawns workers using this template:
+
+```
+delegate_subagent({
+  subagent_type: "team-worker",
+  description: "Spawn <role> worker",
+  team_name: "swarm",
+  name: "<role>",
+  run_in_background: true,
+  prompt: `## Role Assignment
+role: <role>
+role_spec: <skill_root>/roles/<role>/role.md
+session: <session-folder>
+session_id: <session-id>
+team_name: swarm
+requirement: <task-description>
+inner_loop: false
+
+## Assignment (ant only)
+<assignment JSON from aco.py select>
+
+## Progress Milestones
+session_id: <session-id>
+Report progress via team_msg at natural phase boundaries.
+Report blockers immediately via team_msg type="blocker".
+Report completion via team_msg type="task_complete" after final send_message.
+
+Read role_spec file (@<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.
+Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
+})
+```
+
+## User Commands
+
+| Command | Action |
+|---------|--------|
+| `check` / `status` | View iteration progress + convergence curve |
+| `resume` / `continue` | Resume interrupted iteration |
+| `feedback <text>` | Inject feedback into wisdom; applies at next iteration |
+| `revise <ITER>` | Re-run a specific iteration (rare) |
+
+## Specs Reference
+
+| Spec | Purpose |
+|------|---------|
+| [specs/swarm-protocol.md](specs/swarm-protocol.md) | Master protocol: script <-> coordinator interface, data flow |
+| [specs/pheromone-schema.md](specs/pheromone-schema.md) | Pheromone JSON structure, update formula, evaporation |
+| [specs/ant-output-schema.md](specs/ant-output-schema.md) | Critical contract for ant JSON artifacts |
+| [specs/convergence-criteria.md](specs/convergence-criteria.md) | Stop conditions, multi-criterion logic |
+| [specs/swarm-config-template.json](specs/swarm-config-template.json) | User-facing config template with all knobs |
+
+## Scripts
+
+| Script | Purpose | Invocation |
+|--------|---------|------------|
+| `scripts/aco.py` | Main CLI: init / select / update / converged / report | `python aco.py --session <path> <cmd>` |
+| `scripts/pheromone.py` | Pheromone matrix module (imported by aco.py) | — |
+| `scripts/scoring.py` | Pluggable scorer (script + fallback modes) | — |
+
+## Session Directory
+
+```
+.workflow/.team/TS-<slug>-<date>/
+├── team-session.json           # Session state
+├── swarm-config.json           # User-facing config (Phase 1 output)
+├── role-binding.json           # Worker role_spec path map
+├── task-space.json             # Resolved nodes list
+├── pheromone/
+│   ├── current.json            # Latest pheromone (each iter overwrites)
+│   ├── init.json               # Frozen initial state
+│   └── history/<iter>.json     # Per-iter snapshot
+├── trails/<iter>.jsonl         # Per-iter all-ant paths + scores
+├── scores/iter-<iter>-scores.json  # Scorer output (if mode == llm)
+├── artifacts/
+│   ├── ant-<iter>-<id>.json    # Per-ant schema-locked output
+│   ├── swarm-report.json       # Phase 4 full report dump
+│   └── best-solution.md        # Analyst final synthesis
+├── best.json                   # Canonical best solution
+├── wisdom/                     # learnings / decisions / issues
+└── .msg/                       # Message bus
+```
+
+## Completion Action
+
+When swarm converges, coordinator presents:
+
+```
+ask_user({
+  questions: [{
+    question: "Swarm pipeline complete. What would you like to do?",
+    header: "Completion",
+    multiSelect: false,
+    options: [
+      { label: "Archive & Clean (Recommended)", description: "Archive session, delete team" },
+      { label: "Keep Active", description: "Preserve for follow-up" },
+      { label: "Export Best Solution", description: "Copy best-solution.md to target" },
+      { label: "Run Another Round", description: "Reset convergence, K more iterations" }
+    ]
+  }]
+})
+```
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| `aco.py` not found | Verify `<skill_root>/scripts/aco.py`; check Python install |
+| Python version < 3.10 | Use `python3` or report dependency error |
+| Config validation fails | ask_user to fix, regenerate, retry |
+| All ants fail in iteration | Halt, ask_user (retry / abort / refine config) |
+| Hallucination cluster (>50%) | Pause, ask_user (continue / refine scoring) |
+| Convergence never trips | `max_iterations` safety net always fires |
+| Session corruption | Phase 0 reconciliation; archive if irrecoverable |

package/.agents/skills/team-swarm/roles/analyst/role.md

@@ -0,0 +1,187 @@
+---
+role: analyst
+prefix: ANALYST
+inner_loop: false
+output_tag: "[analyst]"
+message_types:
+  success: analysis_ready
+  error: error
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+
+# Analyst Role — Phase 2-4
+
+Tag: `[analyst]` | Prefix: `ANALYST-*`
+Responsibility: After swarm converges, synthesize the best solution + top trails + convergence curve into a human-readable `best-solution.md` report. Provides interpretation, not just data dump.
+
+## Boundaries
+
+### MUST
+- Read `<session>/best.json`, `<session>/artifacts/swarm-report.json`, all `<session>/trails/*.jsonl`
+- Produce `<session>/artifacts/best-solution.md` as the final deliverable
+- Explain WHY the best path won (which decisions mattered, evidence chain)
+- Compare best vs runner-ups to surface stability vs luck
+- Document convergence story (entropy curve, when stagnation hit)
+
+### MUST NOT
+- Re-score solutions (that is scorer's job — analyst takes verified_score as given)
+- Modify best.json, trails, or pheromone state
+- Generate solutions of its own — analyst synthesizes existing ant outputs
+- Exceed ~150 lines in best-solution.md (be sharp, not verbose)
+
+## Phase 2: Context Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Original objective | `<session>/swarm-config.json#ant_prompt.objective` | Yes |
+| Best solution | `<session>/best.json` | Yes |
+| Full swarm report | `<session>/artifacts/swarm-report.json` | Yes |
+| All trails | `<session>/trails/*.jsonl` | Yes |
+| Convergence reason | swarm-report.json or `aco.py converged` output | Yes |
+| Best ant artifact | `<session>/artifacts/ant-<best.iteration>-<best.id>.json` (full evidence) | Yes |
+| Issues log | `<session>/wisdom/issues.md` | Optional |
+
+Workflow:
+1. Extract session path from task description
+2. Read swarm-config.json -> capture objective
+3. Read best.json -> identify best ant
+4. Read full swarm-report.json -> get top_k + convergence_curve
+5. Read the best ant's full artifact for evidence chain
+6. Read all trails/*.jsonl into a list (chronological)
+
+## Phase 3: Synthesis
+
+### 3.1 Structure the report
+
+Layout for `best-solution.md`:
+
+```markdown
+# Swarm Result — <objective_short_form>
+
+## Best Solution
+
+**Path**: node_a → node_c → node_f
+**Verified Score**: 0.82
+**Iteration**: 3 of 5
+**Ant**: ANT-3-2
+
+### Summary
+<one paragraph — what the best solution proposes and why it answers the objective>
+
+### Evidence Chain
+- `src/foo.ts:42` — <how this evidence supports the decision>
+- `tests/foo.spec.ts:18` — <...>
+
+### Candidate Artifact
+<extract from best.candidate_solution — quote or summarize, link to file if file_ref>
+
+## Why This Path Won
+
+| Decision | Pheromone-guided? | Why it mattered |
+|----------|-------------------|-----------------|
+| start = node_a | weighted | <reason> |
+| a → c | yes (0.45 hint) | <reason> |
+| c → f | NO (deviation) | <reason> — this was the key call |
+
+## Runner-Up Solutions
+
+| Rank | Ant | Path | Score | Diff from best |
+|------|-----|------|-------|----------------|
+| 2 | ANT-2-1 | a → b → e | 0.74 | -0.08; weaker evidence at e |
+| 3 | ANT-4-3 | a → c → g | 0.71 | -0.11; valid but less specific |
+
+## Convergence Story
+
+Iterations: 4 of 5 max
+Trigger: stagnation (best unchanged for 2 iterations)
+
+Entropy curve:
+- iter 1: 3.21 (broad exploration)
+- iter 2: 2.45 (narrowing on node_a region)
+- iter 3: 1.85 (best emerges at ANT-3-2)
+- iter 4: 1.72 (consensus around best, no improvement)
+
+Interpretation: <2-3 sentences on whether the swarm converged on a genuine optimum or got stuck>
+
+## Caveats
+
+- <e.g., 40% of ants in iter 2 flagged as hallucinations>
+- <e.g., evidence for node_f is single-source — recommend manual verification>
+- <e.g., search space had only N nodes — larger space may surface better solutions>
+
+## Reproducibility
+
+- Config: `swarm-config.json` (pinned)
+- Best path: `best.json`
+- Full trails: `trails/<iter>.jsonl`
+- Random seed: <if used>
+```
+
+### 3.2 Interpretation rules
+
+- **Why-it-won analysis** is the highest-value content. Don't just describe the path — explain which decisions were pivotal.
+- **Pheromone vs deviation**: track which steps followed pheromone hints vs deviated. Deviations that produced higher scores are the most interesting signal.
+- **Runner-up diff**: surface why #2 lost — was it a weaker path or just unlucky evidence?
+- **Caveats are mandatory**: every swarm result has limitations. List them honestly.
+
+### 3.3 Constraints
+
+- Target ≤ 150 lines
+- No prose padding — every section earns its place
+- Quote evidence verbatim where possible (file:line refs)
+- Don't editorialize beyond what evidence supports
+
+## Phase 4: Verify + Publish
+
+### Behavioral Traits
+
+#### Accuracy
+- Every cited path/score MUST match best.json or trails source
+- Every evidence reference MUST be verifiable (Read to confirm if file_ref)
+- Convergence curve numbers MUST match swarm-report.json#convergence_curve
+
+#### Feedback Contract
+| Field | Required | Content |
+|-------|----------|---------|
+| artifacts_written | Always | `<session>/artifacts/best-solution.md` |
+| line_count | Always | int (target ≤ 150) |
+| verification_method | Always | "cross_ref_with_best.json + evidence_verified" |
+
+#### Quality Gate
+- Final report file exists and parses as markdown
+- All sections present (Best Solution / Why Won / Runner-Ups / Convergence / Caveats / Reproducibility)
+- Line count ≤ 200 (hard cap — fail if exceeded, retry with sharper edit)
+
+### Verification Steps
+
+1. Read written best-solution.md back
+2. Cross-check best.score against best.json
+3. Confirm runner-up scores against trails
+4. If file_ref evidence in best.candidate_solution -> Read to confirm file exists
+5. Count lines — if > 200, condense and rewrite
+
+### State Update
+
+```json
+{
+  "task_id": "ANALYST-1",
+  "role": "analyst",
+  "status": "completed",
+  "artifact_path": "<session>/artifacts/best-solution.md",
+  "best_score": <float>,
+  "best_ant_id": "<id>",
+  "line_count": <int>,
+  "verification": "cross_ref_pass + evidence_verified"
+}
+```
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| best.json missing | Pipeline produced no valid ant — write minimal report with `status: no_solution` |
+| Trails empty | Same as above — no exploration data to analyze |
+| Best ant artifact missing | Use only best.json fields; note as caveat |
+| Cross-ref mismatch (score discrepancy) | Trust best.json; note discrepancy in caveats |
+| Line count > 200 after rewrite | Hard-fail report; coordinator decides retry vs accept |