ace-swarm 2.2.0 → 2.3.1

package/CHANGELOG.md

@@ -1,6 +1,57 @@
 # Changelog
 
-This changelog is based on local tagged release history and repository diffs.
+## [2.3.0] - 2026-03-28
+
+### Added
+
+**Orchestrator Supervisor:**
+- Added `run_orchestrator` MCP tool for full task-plan execution with explicit step routing, sequential/parallel dispatch, and handoff create/ack flows.
+- Added Vericify context carry-forward and delta recovery for state continuity across plan execution.
+- Added circuit breaker open/close hooks for upstream failure handling.
+- Added plan amendment support during mid-execution.
+
+**Model Bridge Context Management:**
+- Added context budget calculation with configurable reserve (default 25%) to prevent overflow.
+- Added tier fallback (full → compressed → brief) when context exceeds budget.
+- Added automatic conversation history compaction (summarize older messages, retain recent messages + system).
+- Added large tool-result write-through to disk with configurable truncation (default 3000 chars).
+- Added retry-once on transient provider errors (abort, timeout, rate-limit).
+
+**ACE Compliance Enforcement:**
+- Added 5-layer ACE compliance enforcement: MCP instructions, per-host instruction files, lifecycle hooks, tool-level guidance, and bootstrap-on-first-tool.
+- Added per-host instruction file generation for CLAUDE.md, .cursorrules, .github/copilot-instructions.md, and Codex AGENTS.md.
+- Added lifecycle hook dispatcher (`ace-hook-dispatch.mjs`) with role-aware tool hints for 7 hosts.
+- Added tool-level soft enforcement via guidance appended to all tool results.
+- Added bootstrap nudge lifecycle for lazy ACE context loading on first mutation tool.
+
+**Tool Governance:**
+- Added named sets for explicit tool classification: BOOTSTRAP_TOOLS, REFRESH_TOOLS, NAMED_MUTATION_TOOLS.
+- Added maintenance comments on mutable tool sets to prevent accidental out-of-sync registrations.
+- Added Vericify resolution scoping with `startsWith` validation to prevent parent-directory leakage.
+
+### Changed
+
+- Changed agent worker and runner behavior so blocked or idle TUI agents can accept new input and resume without relaunching.
+- Expanded hook dispatch context to emit role-aware ACE tool hints from session, subagent, and tool lifecycle events.
+- Updated bootstrap and config rendering to generate multi-host hook artifacts under `.vscode`, `.cursor`, and `.mcp-config`.
+
+### Validation
+
+- Verified `208/208` tests passing (up from 202) with full orchestrator supervisor, model bridge, and compliance enforcement coverage.
+
+## [2.2.0] - 2026-03-26
+
+### Added
+- Added `ace turnkey` command for rapid workspace bootstrap with one command.
+- Added `ace tui` command for a full terminal operator surface with status, tasks, chat, and telemetry.
+- Expanded the packaged skill system to 15 skills, including `landing-review-watcher`, `problem-triage`, `skill-auditor`, and `astgrep-index`.
+- Finalized the 17-agent role system (4 swarm, 13 composable).
+- Added automatic MCP client configuration for Codex, VS Code, Claude Desktop, Cursor, and Antigravity.
+- Expanded the MCP tool surface to 70+ tools across 12 domain-specific modules.
+
+### Packaging
+- Bumped package version from `2.1.0` to `2.2.0`.
+- Verified 170/170 tests passing on the final v2.2.0 release candidate.
 
 ## [2.1.0] - 2026-03-13
 

package/README.md

@@ -1,8 +1,8 @@
 # ACE Swarm MCP Server
 
-ACE Swarm is an MCP server and terminal-first CLI for durable agent orchestration.
+ACE Swarm is an MCP server and terminal-first CLI for durable multi-agent orchestration and agent runtime infrastructure.
 
-It turns agent workflows into a local control plane with explicit state, handoffs, locks, diffs, runtime profiles, and operator tooling.
+It exposes 90+ MCP tools that turn agent workflow coordination into a local control plane with explicit state, typed handoffs, resource locks, semantic diffs, runtime profiles, and operator tooling. No signup. No API key required for the Ollama path. One command to bootstrap.
 
 ## System Map
 
@@ -60,33 +60,67 @@ ACE Swarm
 +----+-----------------------------------------------+-----------------------------------------------+
 ```
 
+30 seconds later the workspace has 17 agent roles, 15 packaged skills, a durable state layer, and MCP client configs for Codex, VS Code, Claude Desktop, Cursor, Gemini, and Antigravity.
+
 ## Recent Releases
 
 ```text
-+---------+------------+------------------------------------------------------+
-| Version | Date       | Highlights                                           |
-+---------+------------+------------------------------------------------------+
-| 2.1.0   | 2026-03-13 | README redesign, ASCII docs, packaged changelog      |
-| 2.0.7   | 2026-03-13 | runtime executor/profile/tools, trackers, workspace  |
-| 2.0.6   | 2026-03-10 | bootstrap/workspace helper hardening                 |
-+---------+------------+------------------------------------------------------+
++------------+------------+------------------------------------------------------------------+
+| Version    | Date       | Highlights                                                       |
++------------+------------+------------------------------------------------------------------+
+| 2.3.0      | 2026-03-28 | Orchestrator supervisor, context-aware model bridge, ACE         |
+|            |            | compliance enforcement, Vericify integration, tool governance    |
+| 2.2.0      | 2026-03-26 | turnkey bootstrap, TUI, expanded skills/roles, client configs    |
+| 2.1.0      | 2026-03-13 | README redesign, ASCII docs, packaged changelog                  |
++------------+------------+------------------------------------------------------------------+
 ```
 
-See [CHANGELOG.md](./CHANGELOG.md) for the recent tagged release history that can be verified from the local repository.
+See [CHANGELOG.md](./CHANGELOG.md) for detailed release notes.
+
+### What's New in 2.3.0
+
+**Orchestrator Supervisor (`run_orchestrator` MCP tool):**
+- Full task-plan execution loop with explicit step routing and sequential/parallel dispatch
+- Handoff create/ack flows with fallback ID generation
+- Vericify context carry-forward and delta recovery for state continuity
+- Circuit breaker open/close for upstream failure handling
+- Plan amendment support during execution
+
+**Model Bridge Context Management:**
+- Context budget calculation with configurable reserve (default 25%)
+- Tier fallback (full → compressed → brief) when context overflows
+- Automatic conversation history compaction (summarize older messages, retain recent + system)
+- Large tool-result write-through to disk with configurable truncation
+- Retry-once on transient provider errors (abort, timeout, rate-limit)
+
+**ACE Compliance Enforcement (5 Stacked Layers):**
+- Layer 1: MCP server initialization instructions (all hosts)
+- Layer 2: Per-host instruction files (CLAUDE.md, .cursorrules, .github/copilot-instructions.md)
+- Layer 3: Lifecycle hooks with role-aware tool hints (7 hosts)
+- Layer 4: Tool-level soft enforcement (guidance on all tool results)
+- Layer 5: Bootstrap-on-first-tool lazy enforcement
+
+**Tool Governance & Vericify:**
+- Named sets for explicit tool classification (BOOTSTRAP_TOOLS, REFRESH_TOOLS, NAMED_MUTATION_TOOLS)
+- Vericify resolution scoping to prevent parent-directory leakage
+- Full Vericify API integration with graceful degradation fallback
+
+**Test Coverage:** 208 passing tests (up from 202)
 
 ## Core Surfaces
 
 ```text
-+------------------+------------------------------------------+--------------------------------------------------+
-| Surface          | Internals                                | Public entrypoints                               |
-+------------------+------------------------------------------+--------------------------------------------------+
-| Bootstrap        | workspace state, tasks, configs          | `ace init`, `ace turnkey`, `ace mcp-config`      |
-| Agent runtime    | swarm + composable roles                 | MCP server, TUI `/agent`, packaged agent assets  |
-| Durable state    | ledgers, TODOs, handoffs, status events  | runtime stores under `agent-state/*`             |
-| Dispatch         | queue, lock table, lease, recovery       | `enqueue_job`, `dispatch_jobs`, `complete_job`   |
-| Change analysis  | delta scan, semantic diff, rewrite hints | `scan_workspace_delta`, `semantic_diff`, etc.    |
-| Operator UI      | tabs, chat, telemetry, model switching   | `ace tui`                                        |
-+------------------+------------------------------------------+--------------------------------------------------+
++------------------+----------------------------------------------+------------------------------------------------------+
+| Surface          | Internals                                    | Public entrypoints                                   |
++------------------+----------------------------------------------+------------------------------------------------------+
+| Bootstrap        | workspace state, tasks, configs              | `ace init`, `ace turnkey`, `ace mcp-config`          |
+| Agent runtime    | swarm roles, model bridge, tool planning     | MCP server, TUI `/agent`, packaged agent assets      |
+| Durable state    | ledgers, TODOs, handoffs, status events      | runtime stores under `agent-state/*`                 |
+| Dispatch         | job queue, lock table, lease, recovery       | `enqueue_job`, `dispatch_jobs`, `complete_job`       |
+| Supervision      | plan amendment, handoff, Vericify, breakers  | `superviseTaskPlan`, `amendTaskPlan`                 |
+| Change analysis  | delta scan, semantic diff, rewrite hints     | `scan_workspace_delta`, `semantic_diff`, etc.        |
+| Operator UI      | tabs, ACE chat bridge, telemetry, providers  | `ace tui`                                            |
++------------------+----------------------------------------------+------------------------------------------------------+
 ```
 
 ## Workspace Internals
@@ -190,28 +224,41 @@ See [CHANGELOG.md](./CHANGELOG.md) for the recent tagged release history that ca
 
 Provider notes:
 
-- Ollama works directly through `ace tui`.
+- Ollama works directly through `ace tui` — a zero-cost local AI agent runtime with no API keys required.
+- ACE workspaces automatically route chat tabs through the ACE model bridge, handling the full AI agent lifecycle from tool selection through execution, with streamed tool/result updates in the transcript.
 - OpenAI-compatible providers use `OPENAI_API_KEY` and optional `OPENAI_BASE_URL`, or provider-scoped equivalents such as `CODEX_API_KEY` and `CODEX_BASE_URL`.
+- `/agent` sessions can now accept follow-up input while blocked or idle, so operators can continue a run without relaunching the worker tab.
 - VS Code Copilot model hints may appear in discovery, but the standalone TUI does not directly execute through the VS Code chat runtime without an extension-side bridge.
 
+## Supervisor And Bridge Notes
+
+- `ModelBridge` performs a tool-planning turn before execution — selecting from the 90+ registered tools — and can amend the model-selected scope mid-run when another valid ACE tool is required.
+- Supervisor helpers support sequential task-plan execution with amendments, typed agent handoff protocol flows with schema validation, Vericify context carry-forward for state continuity, and circuit-breaker open/close hooks for upstream failure handling.
+- Hook dispatch emits richer role-aware ACE context across workspace lifecycle events, including Codex, Claude Code, VS Code Copilot, Cursor, Gemini, and Antigravity hook bundles.
+
 ## Bootstrap Outputs
 
 ```text
-+----------------------------------+----------------------------------------------+
-| Path                             | Output                                       |
-+----------------------------------+----------------------------------------------+
-| `agent-state/*`                  | state, ledgers, schemas, reports             |
-| `.agents/ACE/*`                  | packaged agent instructions                  |
-| `.agents/skills/*`               | packaged skills                              |
-| `tasks/*`                        | task packs, examples, handoff templates      |
-| `scripts/ace/*`                  | helper scripts                               |
-| `.vscode/mcp.json`               | VS Code MCP config                           |
-| `.mcp-config/*`                  | Codex / VS Code / Claude / Cursor / Antigravity |
-| `.github/hooks/*.json`           | optional workspace hook policies             |
-+----------------------------------+----------------------------------------------+
++-----------------------------------+------------------------------------------------------+
+| Path                              | Output                                               |
++-----------------------------------+------------------------------------------------------+
+| `agent-state/*`                   | state, ledgers, schemas, reports                     |
+| `.agents/ACE/*`                   | packaged agent instructions                          |
+| `.agents/skills/*`                | packaged skills                                      |
+| `tasks/*`                         | task packs, examples, handoff templates              |
+| `scripts/ace/*`                   | helper scripts                                       |
+| `.vscode/mcp.json`                | VS Code MCP config                                   |
+| `.vscode/ace-hooks.json`          | VS Code hook bundle                                  |
+| `.cursor/hooks.json`              | Cursor hook bundle                                   |
+| `.mcp-config/codex.hooks.toml`    | Codex hook config                                    |
+| `.mcp-config/gemini.hooks.json`   | Gemini hook bundle                                   |
+| `.mcp-config/antigravity.hooks.json` | Antigravity hook bundle                          |
+| `.mcp-config/*`                   | client configs for Codex / VS Code / Claude / Cursor / Gemini / Antigravity |
+| `.github/hooks/*.json`            | optional workspace hook policies                     |
++-----------------------------------+------------------------------------------------------+
 ```
 
-Local-model bootstrap:
+Local-model bootstrap (no API key, no cloud dependency):
 
 ```bash
 npx -y ace-swarm turnkey --project "My Project" --llm ollama --model llama3.1:8b
@@ -223,16 +270,17 @@ ace doctor --llm ollama --model llama3.1:8b
 ## Client Config Targets
 
 ```text
-+---------------+--------------------------------------------------------------+
-| Client        | Target                                                       |
-+---------------+--------------------------------------------------------------+
-| Codex         | `$CODEX_HOME/config.toml` or `~/.codex/config.toml`         |
-| VS Code       | `.vscode/mcp.json`                                          |
-| Claude        | macOS: `~/Library/Application Support/Claude/...`           |
-|               | Linux: `~/.config/Claude/claude_desktop_config.json`        |
-| Cursor        | `~/.cursor/mcp.json`                                        |
-| Antigravity   | import `.mcp-config/antigravity.mcp.json` in client UI      |
-+---------------+--------------------------------------------------------------+
++---------------+---------------------------------------------------------------------+
+| Client        | Target                                                              |
++---------------+---------------------------------------------------------------------+
+| Codex         | `$CODEX_HOME/config.toml` or `~/.codex/config.toml`                |
+| VS Code       | `.vscode/mcp.json` and `.vscode/ace-hooks.json`                    |
+| Claude        | macOS: `~/Library/Application Support/Claude/...`                  |
+|               | Linux: `~/.config/Claude/claude_desktop_config.json`               |
+| Cursor        | `~/.cursor/mcp.json` or workspace `.cursor/hooks.json`             |
+| Gemini        | import `.mcp-config/gemini.hooks.json` with the generated MCP config |
+| Antigravity   | import `.mcp-config/antigravity.mcp.json` and `.mcp-config/antigravity.hooks.json` |
++---------------+---------------------------------------------------------------------+
 ```
 
 ## Included Assets
@@ -243,7 +291,7 @@ ace doctor --llm ollama --model llama3.1:8b
 +----------------------+-----------------------------------------------------------+
 | Swarm agents         | 4: orchestrator, vos, ui, coders                         |
 | Composable agents    | 13: astgrep, skeptic, ops, research, spec, builder, ... |
-| Skills               | 11 packaged skills including orchestrator, codemunch,   |
+| Skills               | 15 packaged skills including orchestrator, codemunch,   |
 |                      | codesnipe, state-auditor, schema-forge, release-sentry  |
 | Tasks / templates    | `todo.md`, `lessons.md`, `role_tasks.md`,               |
 |                      | `cli_work_split.md`, `SWARM_HANDOFF.template.json`      |

package/assets/.github/hooks/ace-copilot.json

@@ -3,64 +3,64 @@
     "SessionStart": [
       {
         "type": "command",
-        "command": "node ./scripts/ace/copilot-hook-dispatch.mjs",
-        "windows": "node .\\\\scripts\\\\ace\\\\copilot-hook-dispatch.mjs",
+        "command": "node ./scripts/ace/ace-hook-dispatch.mjs",
+        "windows": "node .\\\\scripts\\\\ace\\\\ace-hook-dispatch.mjs",
         "timeout": 10
       }
     ],
     "UserPromptSubmit": [
       {
         "type": "command",
-        "command": "node ./scripts/ace/copilot-hook-dispatch.mjs",
-        "windows": "node .\\\\scripts\\\\ace\\\\copilot-hook-dispatch.mjs",
+        "command": "node ./scripts/ace/ace-hook-dispatch.mjs",
+        "windows": "node .\\\\scripts\\\\ace\\\\ace-hook-dispatch.mjs",
         "timeout": 10
       }
     ],
     "PreToolUse": [
       {
         "type": "command",
-        "command": "node ./scripts/ace/copilot-hook-dispatch.mjs",
-        "windows": "node .\\\\scripts\\\\ace\\\\copilot-hook-dispatch.mjs",
+        "command": "node ./scripts/ace/ace-hook-dispatch.mjs",
+        "windows": "node .\\\\scripts\\\\ace\\\\ace-hook-dispatch.mjs",
         "timeout": 10
       }
     ],
     "PostToolUse": [
       {
         "type": "command",
-        "command": "node ./scripts/ace/copilot-hook-dispatch.mjs",
-        "windows": "node .\\\\scripts\\\\ace\\\\copilot-hook-dispatch.mjs",
+        "command": "node ./scripts/ace/ace-hook-dispatch.mjs",
+        "windows": "node .\\\\scripts\\\\ace\\\\ace-hook-dispatch.mjs",
         "timeout": 10
       }
     ],
     "PreCompact": [
       {
         "type": "command",
-        "command": "node ./scripts/ace/copilot-hook-dispatch.mjs",
-        "windows": "node .\\\\scripts\\\\ace\\\\copilot-hook-dispatch.mjs",
+        "command": "node ./scripts/ace/ace-hook-dispatch.mjs",
+        "windows": "node .\\\\scripts\\\\ace\\\\ace-hook-dispatch.mjs",
         "timeout": 10
       }
     ],
     "SubagentStart": [
       {
         "type": "command",
-        "command": "node ./scripts/ace/copilot-hook-dispatch.mjs",
-        "windows": "node .\\\\scripts\\\\ace\\\\copilot-hook-dispatch.mjs",
+        "command": "node ./scripts/ace/ace-hook-dispatch.mjs",
+        "windows": "node .\\\\scripts\\\\ace\\\\ace-hook-dispatch.mjs",
         "timeout": 10
       }
     ],
     "SubagentStop": [
       {
         "type": "command",
-        "command": "node ./scripts/ace/copilot-hook-dispatch.mjs",
-        "windows": "node .\\\\scripts\\\\ace\\\\copilot-hook-dispatch.mjs",
+        "command": "node ./scripts/ace/ace-hook-dispatch.mjs",
+        "windows": "node .\\\\scripts\\\\ace\\\\ace-hook-dispatch.mjs",
         "timeout": 10
       }
     ],
     "Stop": [
       {
         "type": "command",
-        "command": "node ./scripts/ace/copilot-hook-dispatch.mjs",
-        "windows": "node .\\\\scripts\\\\ace\\\\copilot-hook-dispatch.mjs",
+        "command": "node ./scripts/ace/ace-hook-dispatch.mjs",
+        "windows": "node .\\\\scripts\\\\ace\\\\ace-hook-dispatch.mjs",
         "timeout": 10
       }
     ]

package/assets/agent-state/MODULES/schemas/VERICIFY_PROCESS_POST_LOG.schema.json

@@ -59,6 +59,7 @@
               "progress",
               "blocker",
               "handoff_note",
+              "stale_ack",
               "completion"
             ]
           },