maestro-flow 0.4.18 → 0.4.19

package/.claude/commands/maestro-next.md

@@ -12,70 +12,114 @@ allowed-tools:
 ---
 
 <purpose>
-单链推荐：根据用户输入意图，从 `.claude/commands/` 命令池中挑选**最匹配的单个命令**，确认后通过 `Skill()` 执行。
+单链推荐：解析 intent + project state → 路由表评分 → 推荐**单个原子命令** → 确认后通过 `Skill()` 执行。
 
-与 `/maestro` / `/maestro-ralph` 的区别：
-- `/maestro`、`/maestro-ralph`、`/maestro-ralph-execute`、`/maestro-ralph-beta`、`/maestro-player`、`/maestro-composer` 是**多步管线编排器**，本命令不会推荐它们
-- 本命令始终只推荐 **1 个原子命令**（top pick），最多列出 2-3 个备选；选定后直接执行，无 session、无 chain
-- 适用场景：用户意图清晰、只需单步即可完成；或不确定该走哪个具体命令时获取定向推荐
+与 `/maestro` / `/maestro-ralph` 区别：
+- 不创建 session、不构建 chain、不写 status.json
+- 始终只推 1 个 top pick，最多列 2-3 个备选
+- 适用场景：意图清晰且单步即可完成；或需要定向推荐时
 </purpose>
 
 <context>
-$ARGUMENTS — 用户意图文本 + 可选 flags。
+$ARGUMENTS — 意图文本 + 可选 flags。
 
 **Flags:**
-- `-y` / `--yes` — 自动模式：跳过确认，直接执行 top pick
+- `-y` / `--yes` — 跳过确认，直接执行 top pick
 - `--dry-run` — 仅显示推荐结果，不执行
-- `--top N` — 显示前 N 个候选供选择（默认 3）
+- `--top N` — 显示前 N 个候选（默认 3）
 - `--list` — 仅列出可推荐命令池，不做推荐
 
-**候选池：** 仅 Step 3 路由表中列出的命令参与推荐。表中未出现的命令（含管线编排器 `maestro` / `maestro-ralph*` / `maestro-player` / `maestro-composer` 等）不会被本命令推荐。
+**候选池：** 仅 A_SCORE_CANDIDATES 路由表中列出的命令。管线编排器（`maestro` / `maestro-ralph*` / `maestro-player` / `maestro-composer`）**永远不在候选池**。
 </context>
 
-<execution>
+<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>
 
-### Step 1: Parse Arguments
+<state_machine>
 
-解析 `-y` / `--dry-run` / `--top N` / `--list`，剩余文本作为 `intent`。
+<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   — AskUserQuestion 选择/修改参数（auto_mode 跳过）    PERSIST: —
+S_EXECUTE   — `Skill({ skill, args })` 单次调用                 PERSIST: —
+S_FALLBACK  — intent 空且 clarification 失败                    PERSIST: —
+</states>
 
-- `--list` 模式 → 跳到 Step 3（仅列表）
-- `intent` 为空且非 `--list` → `AskUserQuestion`：让用户输入意图（最多 1 轮，仍空则 E001）
+<transitions>
 
-### Step 2: 读取 Workflow 状态（智能推荐基础）
+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: AskUserQuestion
+  → S_FALLBACK   WHEN: clarification empty
 
-读取以下项目状态，用于推断"当前生命周期位置"和"自然下一步"：
+S_STATE:
+  → S_RANK       DO: A_INFER_LIFECYCLE
 
-```bash
-# 1. 当前 phase / milestone / 最新 artifact
-cat .workflow/state.json 2>$null
+S_RANK:
+  → S_PRESENT    DO: A_SCORE_CANDIDATES
 
-# 2. 最近 artifact 目录（按 mtime 倒序，取前 3）
-ls -la .workflow/scratch/ 2>$null | head -10
+S_LIST:
+  → END          DO: 按 workflow 簇分组列出全部候选 + description
 
-# 3. 是否有进行中的 ralph/maestro session
-ls -la .workflow/.maestro/ 2>$null | head -5
-```
+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: Skill({ skill: <chosen>, args: <args> }) → 输出 "✅ 已执行 /<command>"
+
+S_FALLBACK:
+  → END          DO: raise E001
 
-根据读取结果推断 **lifecycle_position**（用作下一步推荐的核心信号）：
-
-| 项目状态特征 | lifecycle_position | 自然下一步 |
-|--------------|-------------------|-----------|
-| 无 `.workflow/` + 无源码 | `brainstorm` | `maestro-brainstorm` |
-| 无 `.workflow/` + 有源码 | `init` | `maestro-init` |
-| 有 state.json，无 roadmap.md，无 milestones | `analyze-macro` | `maestro-analyze` (宏观调研) |
-| 有 macro analyze artifact，无 roadmap.md | `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}` |
-| 最新 artifact = `verify`，passed | `review` | `quality-review {phase}` |
-| 最新 artifact = `review`，verdict=PASS | `test-gen` | `quality-auto-test {phase}` |
-| 最新 artifact = `test`，全绿 | `milestone-audit` | `maestro-milestone-audit` |
-| 当前 milestone 全部 phase 完成 | `milestone-complete` | `maestro-milestone-complete` |
-| 任一 stage 产物含 gaps/failed | `debug` | `quality-debug {gap}` |
-
-**Maestro Lifecycle 主线（核心 workflow，供推断"下一步"使用）：**
+</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
@@ -83,41 +127,28 @@ brainstorm → blueprint → init → analyze-macro → roadmap
    → milestone-audit → milestone-complete → milestone-release
 ```
 
-**辅助 workflow 簇**（按场景触发，非主线）：
-
-| 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` |
-
-### Step 2.5: Semantic Match & Rank
+### A_SCORE_CANDIDATES
 
-综合以下信号对路由表中的命令评分（高→低）：
+**评分信号**（高→低）：
 
 | 信号 | 权重 | 说明 |
 |------|------|------|
-| intent 命中路由表行的关键词 | 高 | 字面匹配主依据 |
-| **lifecycle_position 的"自然下一步"** | **高** | 当 intent 含"继续/下一步/next/接下来"或为空时，此信号上升为决定性 |
-| `name` 关键词命中 intent | 中 | 如 intent 含 "test" → quality-test/quality-auto-test 加分 |
-| Workflow 簇匹配 | 中 | intent 涉及学习/知识/issue 等场景时触发对应簇 |
-| Recent activity 反向避免 | 低 | 刚完成的 stage 在短期内降权 |
+| intent 命中路由表关键词 | 高 | 字面匹配主依据 |
+| **lifecycle 自然下一步** | **高** | 空 intent / "继续" / "next" 时为决定性 |
+| `name` 关键词命中 intent | 中 | intent 含 "test" → quality-test/quality-auto-test 加分 |
+| Workflow 簇匹配 | 中 | intent 涉及学习/知识/issue 等场景触发对应簇 |
+| Recent activity 反向避免 | 低 | 刚完成的 stage 短期内降权 |
 
 **特殊意图处理：**
 
-| Intent 模式 | 处理 |
-|------------|------|
-| 空 / "继续" / "下一步" / "next" / "接下来怎么走" | 直接按 lifecycle_position 的"自然下一步"作为 top pick |
-| "什么状态" / "现在到哪了" / "status" | top pick = `manage-status` |
-| 字面命中路由表关键词 | 路由表优先，lifecycle 作为加分项 |
-| 无任何匹配 | top pick = lifecycle 自然下一步 + W002 警告 |
+| Intent 模式 | top pick |
+|------------|---------|
+| 空 / "继续" / "下一步" / "next" / "接下来" | lifecycle 自然下一步 |
+| "什么状态" / "现在到哪了" / "status" | `manage-status` |
+| 字面命中路由表 | 路由表优先（lifecycle 仅加分） |
+| 无任何匹配 | lifecycle 下一步 + raise W002 |
 
-**意图 → 命令路由表**（候选池等于本表 + 上方"自然下一步"建议）：
+**意图 → 命令路由表**（候选池）：
 
 | 意图关键词 | 推荐命令 |
 |-----------|---------|
@@ -148,70 +179,74 @@ brainstorm → blueprint → init → analyze-macro → roadmap
 | 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）。
 
-### Step 3: Present & Confirm
+</actions>
+
+</state_machine>
+
+<presentation>
 
-**`--list` 模式：** 按类别（maestro / manage / quality / learn / spec / wiki / security）分组展示所有候选 + description，结束。
+### `--list` 模式
 
-**正常模式：**
+按 workflow 簇（主线 / Learning / Knowledge / Wiki / Issue / 文档 / 重构 / 发布 / 并行）分组展示全部候选 + description，结束。
+
+### 正常模式
 
-显示：
 ```
 🎯 推荐 (top pick): /<command-name>
    <description>
-   推荐理由: <一句话说明为什么命中>
+   推荐理由: <命中规则 + lifecycle 位置一句话>
 
 备选:
   2. /<alt-1> — <description>
   3. /<alt-2> — <description>
 
-执行参数: <args-to-pass>
+执行参数: <args>
 ```
 
-- `--dry-run` → 显示后结束
-- `-y` → 直接执行 top pick
-- 否则 → `AskUserQuestion` 让用户：执行 top pick / 选备选 / 修改参数 / 取消
-
-### Step 4: Execute
-
-通过 `Skill({ skill: "<chosen-command-name>", args: "<args>" })` 执行。
+`--dry-run` 展示后结束；`-y` 直接 S_EXECUTE；否则 AskUserQuestion 提供：执行 top pick / 选备选 / 修改参数 / 取消。
 
-**参数传递：**
-- 默认把 intent 原文作为第一个参数传给目标命令
-- 若用户在 Step 3 修改了参数，使用修改后的版本
-- `-y` flag 透传给目标命令（如果目标命令支持）
+</presentation>
 
-执行完成后显示：
-```
-✅ 已执行 /<command-name>
-```
+<appendix>
 
-不创建 session、不写 status.json、不做后续 chain — 由目标命令自行管理其产出。
+### Error Codes
 
-</execution>
-
-<error_codes>
 | Code | Severity | Condition | Recovery |
 |------|----------|-----------|----------|
-| E001 | error | 未提供 intent 且 clarification 后仍为空 | 提供意图描述或使用 `--list` 浏览命令池 |
-| E002 | error | 候选池为空（commands 目录不存在或无 .md 文件） | 检查 `.claude/commands/` 是否存在 |
-| E003 | error | 用户选择的命令名无法解析为有效 skill | 列出有效命令名让用户重选 |
-| W001 | warning | 多个命令得分接近（top1 与 top2 差距 < 阈值） | 强制展示前 3，让用户裁决 |
-| W002 | warning | intent 与所有候选匹配度均低 | 提示用户考虑 `/maestro` 或 `/maestro-ralph` 走管线 |
-</error_codes>
-
-<success_criteria>
+| 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 下一步 + workflow 簇 + recent activity
 - [ ] 空 intent / "继续" / "下一步" → 直接采用 lifecycle 推断的下一步
-- [ ] top pick 展示时附"推荐理由"（命中规则 + lifecycle 位置）
+- [ ] top pick 展示附"推荐理由"（命中规则 + lifecycle 位置）
 - [ ] `--dry-run` 仅展示，不执行
-- [ ] `-y` 自动执行 top pick
-- [ ] 非自动模式下，用户通过 AskUserQuestion 确认或选择备选
-- [ ] 选定命令通过 `Skill()` 单次调用执行
-- [ ] 不创建 session、不生成 status.json、不触发后续 chain
-- [ ] `--list` 模式按 workflow 簇（主线 / Learning / Knowledge / Wiki / Issue / 文档 / 重构 / 发布 / 并行）分组展示
-</success_criteria>
+- [ ] `-y` 自动执行 top pick；用户传入时透传到 skill args
+- [ ] 非自动模式通过 AskUserQuestion 确认或选备选
+- [ ] 选定命令通过单次 `Skill()` 调用执行
+- [ ] 不创建 session / 不生成 status.json / 不触发后续 chain
+- [ ] `--list` 模式按 workflow 簇分组展示
+
+</appendix>

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

@@ -0,0 +1,178 @@
+---
+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: TeamCreate(*), TeamDelete(*), SendMessage(*), TaskCreate(*), TaskUpdate(*), TaskList(*), TaskGet(*), Agent(*), AskUserQuestion(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*), mcp__ccw-tools__team_msg(*)
+---
+
+# 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
+
+```
+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:
+
+```
+Agent({
+  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 SendMessage.
+
+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:
+
+```
+AskUserQuestion({
+  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 | AskUserQuestion to fix, regenerate, retry |
+| All ants fail in iteration | Halt, AskUserQuestion (retry / abort / refine config) |
+| Hallucination cluster (>50%) | Pause, AskUserQuestion (continue / refine scoring) |
+| Convergence never trips | `max_iterations` safety net always fires |
+| Session corruption | Phase 0 reconciliation; archive if irrecoverable |