@voybio/ace-swarm 0.2.4 → 2.4.0

package/CHANGELOG.md

@@ -35,9 +35,19 @@
 - 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`.
 
+**Store-Unity Migration:**
+- Added `src/store/workspace-store-paths.ts` as the canonical resolver for the canonical/legacy ACE store transition. Every command that opens ACEPACK now uses this shared module; no command assembles `.agents/ACE/ace-state.ace` by hand.
+- `agent-state/ace-state.ace` is the canonical store for new and adopted workspaces. `.agents/ACE/ace-state.ace` is retained as a supported legacy input and fallback — not a second active write target.
+- Added `ensureCanonicalWorkspaceStore()`: legacy-only workspaces are atomically adopted into the canonical path on the first mutating operation (bootstrap, install, repair, compact, preconfig). The legacy file is preserved as a fallback after adoption.
+- Dual-store conflicts (both files exist with different content) surface an explicit warning and halt mutating commands rather than silently merging or overwriting.
+- Added `resolveWorkspaceStorePath()` for read-only resolution: returns the active path and mode without writing anything.
+- Bootstrap, skill install/list, repair, compact, and preconfig all updated to use the shared resolver.
+- CLI help text, doctor messages, and run-ledger artifacts updated to describe `agent-state/ace-state.ace` as canonical.
+- Added `test/store-unity-release.test.mjs` as a dedicated release gate covering legacy adoption, dual-store conflict, canonical-only skill install/repair/compact, and a source-scan guard that fails on new hard-coded legacy path references outside the resolver module.
+
 ### Validation
 
-- Verified `208/208` tests passing (up from 202) with full orchestrator supervisor, model bridge, and compliance enforcement coverage.
+- Verified `319/319` tests passing (up from 208) with full orchestrator supervisor, model bridge, compliance enforcement, and store-unity migration coverage.
 
 ## [2.2.0] - 2026-03-26
 

package/README.md

@@ -2,7 +2,7 @@
 
 Autonomous Coding Entity (ACE) is a local MCP server and CLI for agent-assisted coding.
 
-`ace-swarm` provides Claude Code, Codex, Cursor, VS Code, and provider-backed workflows with a shared runtime: durable workspace state, typed handoffs, scheduler support, change intelligence, and operator tooling. All state lives in a single binary file — `.agents/ACE/ace-state.ace` — so the workspace keeps one source of truth instead of a forest of generated state files.
+`ace-swarm` provides Claude Code, Codex, Cursor, GitHub Copilot CLI, VS Code, and provider-backed workflows with a shared runtime: durable workspace state, typed handoffs, scheduler support, change intelligence, and operator tooling. All state lives in a single binary file — `agent-state/ace-state.ace` — with `.agents/ACE/ace-state.ace` kept only as a legacy fallback for older workspaces.
 
 Modern coding agents can already read files, write code, run commands, and call tools. The missing layer is coordination that survives restarts, model switches, and multi-agent work. ACE keeps the workflow in the store and projects only the files external clients still need. For provider-backed runs, ACE provides task context, tool surfaces, status events, evidence trails, and resumable state.
 
@@ -13,7 +13,7 @@ Modern coding agents can already read files, write code, run commands, and call
 - Shared workflow state should live in the workspace, not only in chat history.
 - ACE-Orchestrator is the default entrypoint, and every provider can delegate through the full agent set.
 - Provider-backed runs should get the same structure and observability.
-- Bootstrap should be contained and reversible: ACE writes into `.agents/ACE/ace-state.ace`.
+- Bootstrap should be contained and reversible: ACE writes into `agent-state/ace-state.ace`, with legacy fallback reads from `.agents/ACE/ace-state.ace` where needed.
 
 ### Serving model providers
 
@@ -21,6 +21,8 @@ ACE provides model providers with the context they cannot infer on their own: ta
 
 - `ace init --llm <provider>` records the selected runtime profile in the store.
 - `ace doctor` validates local or hosted runtime wiring, checks the selected model when the provider exposes listings, and keeps the runtime honest.
+- `ace doctor --scan` probes common Ollama and llama.cpp endpoints and writes the selected profile back into the store.
+- `ace tui` is provider-aware for `ollama`, `llama.cpp`, `codex`, `claude`, `gemini`, and `copilot` when credentials or base URLs are configured.
 - `ace mcp` and `ace tui` expose the same workspace truth to the host, the terminal, and the model.
 
 ## Why This Exists Now
@@ -38,7 +40,7 @@ ACE also provides scheduler primitives for queued work, dependency gates, leases
 
 ## ACEPACK State Model
 
-ACE uses a custom binary format called ACEPACK to present `.agents/ACE/ace-state.ace` as a structured single-file store. The file has three regions:
+ACE uses a custom binary format called ACEPACK to present `agent-state/ace-state.ace` as a structured single-file store. Existing workspaces that still carry `.agents/ACE/ace-state.ace` are read through the legacy fallback path. The file has three regions:
 
 ```
 ace-state.ace
@@ -80,7 +82,7 @@ Every `appendEntry()` call — handoffs, status events, ledger entries, session
 - Per-event overhead is ~19 bytes fixed vs ~150 bytes for equivalent JSON.
 - At 100,000 events, the fixed columns are ~1.9 MB; a full JSON log would be ~15 MB.
 
-Events accumulate for the workspace lifetime and survive `compact()`. Full historical replay is always available. See `HOT_COLD_EVENT_TIERING.md` for the future branch that adds compressed batch archiving for very long-lived workspaces.
+Events accumulate for the workspace lifetime and survive `compact()`. Full historical replay is always available.
 
 ### Why one state file
 
@@ -98,7 +100,7 @@ The store holds runtime state, agent instructions, skills, topology, schemas, an
 Bootstrap a workspace:
 
 ```bash
-npx -y ace-swarm turnkey --project "My Project"
+npx -y @voybio/ace-swarm turnkey --project "My Project"
 ace mcp
 ```
 
@@ -111,7 +113,7 @@ initiate ACE
 Local-model path with Ollama:
 
 ```bash
-npx -y ace-swarm turnkey --project "My Project" --llm ollama --model llama3.1:8b --base-url http://localhost:11434
+npx -y @voybio/ace-swarm turnkey --project "My Project" --llm ollama --model llama3.1:8b --base-url http://localhost:11434
 ollama serve
 ollama pull llama3.1:8b
 ace doctor --llm ollama --model llama3.1:8b --base-url http://localhost:11434
@@ -121,7 +123,7 @@ ace mcp
 Local-model path with llama.cpp:
 
 ```bash
-npx -y ace-swarm turnkey --project "My Project" --llm llama.cpp --model local-model --base-url http://localhost:8080
+npx -y @voybio/ace-swarm turnkey --project "My Project" --llm llama.cpp --model local-model --base-url http://localhost:8080
 llama-server -m /path/to/model.gguf --port 8080
 ace doctor --llm llama.cpp --model local-model --base-url http://localhost:8080
 ace mcp
@@ -132,7 +134,7 @@ If you already have a local runtime running, `ace doctor --scan` will probe comm
 Hosted provider path with Codex:
 
 ```bash
-npx -y ace-swarm turnkey --project "My Project" --llm codex --model gpt-5
+npx -y @voybio/ace-swarm turnkey --project "My Project" --llm codex --model gpt-5
 export OPENAI_API_KEY=...
 ace doctor --llm codex --model gpt-5
 ace mcp
@@ -140,9 +142,10 @@ ace mcp
 
 ## What Bootstrap Writes
 
-ACE bootstrap is intentionally contained. The store is authoritative at `.agents/ACE/ace-state.ace`; only a few host-facing files land in the workspace when requested.
+ACE bootstrap is intentionally contained. The store is authoritative at `agent-state/ace-state.ace`; only a few host-facing files land in the workspace when requested.
 
-- `.agents/ACE/ace-state.ace` — runtime state, agent instructions, skills, topology, schemas, and the event log
+- `agent-state/ace-state.ace` — runtime state, agent instructions, skills, topology, schemas, and the event log
+- `.agents/ACE/ace-state.ace` — legacy fallback for existing workspaces
 - `.agents/ACE/ace-hook-context.json` — compact hook snapshot for external clients
 - `.agents/ACE/tasks/todo.md` — human-facing todo surface
 - Optional workspace-root stubs — `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, `.github/copilot-instructions.md`, and `.vscode/mcp.json`
@@ -159,6 +162,11 @@ Developer or MCP host
   |       |
   |       `-- calls ace-swarm over MCP
   |
+  +-- agent-state/
+  |       |
+  |       +-- ace-state.ace
+  |       +-- STATUS.md / TASK.md / HANDOFF.json projections
+  |
   +-- ace mcp
   |       |
   |       +-- tools, prompts, resources
@@ -168,7 +176,6 @@ Developer or MCP host
   |
   +-- .agents/ACE/
   |       |
-  |       +-- ace-state.ace
   |       +-- ace-hook-context.json
   |       +-- tasks/todo.md
   |       `-- host config bundles
@@ -190,7 +197,7 @@ Developer or MCP host
 | Runtime roles        | swarm and composable runtime roles                           |
 | Skills               | packaged skills                                              |
 | MCP server           | stdio surface for tools, prompts, resources, and workflows   |
-| Durable state        | single .ace authority for handoffs, status events, todos, run ledger, job queue, and discovery |
+| Durable state        | single `agent-state/ace-state.ace` authority for handoffs, status events, todos, run ledger, job queue, and discovery |
 | Projections          | hook context, todo surface, and host config bundles          |
 | Coordination         | scheduler queues, dependency gates, leases, and resource locks |
 | Change intelligence  | delta scan, semantic snapshots, drift reports, rewrite hints |
@@ -215,7 +222,7 @@ In that setup, the host remains the interface. ACE becomes the state contract un
 
 Local models are good at generating text. They usually need help seeing the workspace, hearing the handoff trail, and remembering what changed two turns ago. ACE closes that gap.
 
-- `ace init --llm <provider>` seeds the profile inside `.agents/ACE/ace-state.ace`.
+- `ace init --llm <provider>` seeds the profile inside `agent-state/ace-state.ace`.
 - `ace doctor` verifies that the selected runtime is configured and, when possible, reachable.
 - `ace tui` can talk to either local runtime and surface the same workspace state the MCP server sees.
 - The ACE model bridge gives local runs tool selection, execution flow, and persisted state instead of a fragile one-shot chat loop.

package/assets/.agents/skills/eval-harness/SKILL.md

@@ -173,6 +173,20 @@ Confidence: <score>% (<label>)
 
 ---
 
+## Validation Surface
+
+- Run this skill against at least one known-pass baseline and one known-fail fixture before trusting a promotion decision.
+- Validation command example: execute the configured eval harness runner and confirm deterministic suite counts in `agent-state/EVAL_REPORT.md`.
+
+---
+
+## Portability Notes
+
+- Keep this skill vendor-neutral: it should work across Codex, Claude, Cursor, and Antigravity runtimes.
+- Avoid provider-specific assumptions in suite execution or report parsing; rely on ACE artifacts as the source of truth.
+
+---
+
 ## Anti-Patterns
 
 | Anti-Pattern | Correct Behavior |

package/assets/.agents/skills/handoff-lint/SKILL.md

@@ -132,6 +132,20 @@ Also use when:
 
 ---
 
+## Validation Surface
+
+- Run this check with one valid and one intentionally broken handoff payload to verify deterministic PASS/FAIL behavior.
+- Validation command example: execute the handoff lint path used by the runtime and confirm schema, route, and evidence checks all emit rule-level outcomes.
+
+---
+
+## Portability Notes
+
+- Keep lint output schema and rule IDs stable so different clients can consume results uniformly.
+- Do not depend on provider-specific behavior; handoff validation must rely only on ACE artifacts and schemas.
+
+---
+
 ## Anti-Patterns
 
 | Anti-Pattern | Correct Behavior |

package/assets/.agents/skills/incident-commander/SKILL.md

@@ -156,6 +156,20 @@ No incident closure without ALL of:
 
 ---
 
+## Validation Surface
+
+- Run an incident simulation with synthetic `GATE_FAILED` events and verify severity classification, owner assignment, and timeline reconstruction are deterministic.
+- Validation command example: replay a known event stream and confirm `global-state/INCIDENTS.md` and `agent-state/INCIDENT_TIMELINE.md` contain matching evidence-linked rows.
+
+---
+
+## Portability Notes
+
+- Incident lifecycle states and emitted event names must remain stable across clients.
+- Keep the protocol provider-agnostic: all decisions should be derivable from ACE state artifacts and event logs.
+
+---
+
 ## Anti-Patterns
 
 | Anti-Pattern | Correct Behavior |

package/assets/.agents/skills/memory-curator/SKILL.md

@@ -161,6 +161,20 @@ Generated: <ISO8601>
 
 ---
 
+## Validation Surface
+
+- Run this skill on a fixture with known duplicates and contradictions, then verify the reconciliation report counts match expected values.
+- Validation command example: execute memory curation and confirm no source logs are modified while `MEMORY_INDEX.md` updates with provenance links.
+
+---
+
+## Portability Notes
+
+- Preserve schema and section labels so downstream consumers can parse curated memory artifacts consistently.
+- Keep curation logic independent of model/provider specifics; evidence linkage is the portable contract.
+
+---
+
 ## Anti-Patterns
 
 | Anti-Pattern | Correct Behavior |

package/assets/.agents/skills/release-sentry/SKILL.md

@@ -160,6 +160,20 @@ Reason: <one sentence>
 
 ---
 
+## Validation Surface
+
+- Validate this skill with one known-pass and one known-fail release packet to confirm gate outcomes are deterministic.
+- Validation command example: run release sentry checks and verify `RELEASE_DECISION.md` always includes explicit gate evidence rows.
+
+---
+
+## Portability Notes
+
+- Keep decision enums and gate names stable so any client can consume release outputs consistently.
+- Avoid provider-specific assumptions; release readiness must be computed from ACE artifacts only.
+
+---
+
 ## Anti-Patterns
 
 | Anti-Pattern | Correct Behavior |

package/assets/.agents/skills/risk-quant/SKILL.md

@@ -158,6 +158,20 @@ Every risk in `RISKS.md` must contain these fields:
 
 ---
 
+## Validation Surface
+
+- Run this skill against a fixture risk set with expected probability-impact scores and verify computed tiers match exactly.
+- Validation command example: execute risk quantification and confirm HIGH/CRITICAL entries always include owner, mitigation, and verification condition.
+
+---
+
+## Portability Notes
+
+- Keep scoring scales and tier thresholds explicit and stable across clients.
+- Quantification must remain vendor-neutral and based on ACE state artifacts, not model-specific behavior.
+
+---
+
 ## Anti-Patterns
 
 | Anti-Pattern | Correct Behavior |

package/assets/.agents/skills/schema-forge/SKILL.md

@@ -151,6 +151,20 @@ Use when:
 
 ---
 
+## Validation Surface
+
+- Validate schema updates against both old and new sample payload fixtures before promoting contract changes.
+- Validation command example: run JSON-schema validation for backward and forward compatibility samples and record results in `EVIDENCE_LOG.md`.
+
+---
+
+## Portability Notes
+
+- Preserve stable schema IDs, version fields, and migration metadata so any ACE client can consume updates.
+- Keep evolution rules provider-agnostic; compatibility decisions must be artifact-driven, not model-driven.
+
+---
+
 ## Anti-Patterns
 
 | Anti-Pattern | Correct Behavior |

package/assets/.agents/skills/state-auditor/SKILL.md

@@ -161,6 +161,20 @@ Overall: <PASS | WARN | CRITICAL>
 
 ---
 
+## Validation Surface
+
+- Run audits against fixtures with known contradictions to verify deterministic CRITICAL/WARN classification.
+- Validation command example: execute the state audit flow and confirm every checklist row maps to a concrete pass/fail artifact reference.
+
+---
+
+## Portability Notes
+
+- Keep report structure and checklist IDs stable so multiple clients can parse outputs consistently.
+- State drift checks must remain independent of model/provider implementation details.
+
+---
+
 ## Anti-Patterns
 
 | Anti-Pattern | Correct Behavior |

package/assets/agent-state/EVIDENCE_LOG.md

@@ -4,4 +4,4 @@ Append-only chain-of-custody for checks, decisions, and execution proofs.
 
 ## Entries
 
-- {{BOOTSTRAP_TIMESTAMP}} | bootstrap initialized | evidence_ref: `EVIDENCE_LOG.md#ts:{{BOOTSTRAP_TIMESTAMP}}`
+- 2026-03-03T00:00:00Z | bootstrap initialized | evidence_ref: `EVIDENCE_LOG.md#ts:2026-03-03T00:00:00Z`

package/assets/agent-state/MODULES/gates/gate-correctness.json

@@ -2,6 +2,6 @@
   "id": "gate-correctness",
   "type": "executable",
   "invariant": "All required tests pass",
-  "command": "cd ace-mcp-server && npm test --silent",
+  "command": "if [ -f ace-mcp-server/package.json ]; then cd ace-mcp-server && npm test --silent; elif [ -f package.json ]; then npm test --silent; else echo 'package.json not found for gate-correctness' && exit 1; fi",
   "evidence_requirement": "Command output snippet with exit code 0"
 }

package/assets/agent-state/MODULES/roles/capability-framework.json

@@ -0,0 +1,41 @@
+{
+  "id": "capability-framework",
+  "version": "1.0.0",
+  "objective": "Validate ACE framework contracts, execute gate bundles, and enforce state integrity checks",
+  "permissions": [
+    "allow_file_io",
+    "allow_shell_exec"
+  ],
+  "inputs": [
+    {
+      "file": "TEAL_CONFIG.md",
+      "critical": true
+    },
+    {
+      "file": "QUALITY_GATES.md",
+      "critical": true
+    },
+    {
+      "file": "HANDOFF.json",
+      "critical": true
+    },
+    {
+      "file": "MODULES/registry.json",
+      "critical": true
+    }
+  ],
+  "outputs": [
+    {
+      "file": "EVIDENCE_LOG.md",
+      "validation_gate": "gate-completeness"
+    },
+    {
+      "file": "STATUS_EVENTS.ndjson",
+      "validation_gate": "gate-autonomy"
+    }
+  ],
+  "failure_routing": {
+    "missing_input": "BLOCK_AND_REQUEST_INFO",
+    "gate_failure": "ESCALATE_TO_CAPABILITY_OPS"
+  }
+}

package/assets/agent-state/MODULES/roles/capability-git.json

@@ -0,0 +1,33 @@
+{
+  "id": "capability-git",
+  "version": "1.0.0",
+  "objective": "Execute repository initialization and commit operations with traceable evidence",
+  "permissions": [
+    "allow_file_io",
+    "allow_shell_exec"
+  ],
+  "inputs": [
+    {
+      "file": "STATUS.md",
+      "critical": false
+    },
+    {
+      "file": "EVIDENCE_LOG.md",
+      "critical": true
+    }
+  ],
+  "outputs": [
+    {
+      "file": "EVIDENCE_LOG.md",
+      "validation_gate": "gate-completeness"
+    },
+    {
+      "file": "STATUS_EVENTS.ndjson",
+      "validation_gate": "gate-autonomy"
+    }
+  ],
+  "failure_routing": {
+    "missing_input": "BLOCK_AND_REQUEST_INFO",
+    "gate_failure": "ESCALATE_TO_CAPABILITY_OPS"
+  }
+}

package/assets/agent-state/MODULES/roles/capability-safety.json

@@ -0,0 +1,37 @@
+{
+  "id": "capability-safety",
+  "version": "1.0.0",
+  "objective": "Apply safety checks and fail-closed validation before mutating critical ACE artifacts",
+  "permissions": [
+    "allow_file_io",
+    "allow_shell_exec"
+  ],
+  "inputs": [
+    {
+      "file": "HANDOFF.json",
+      "critical": false
+    },
+    {
+      "file": "QUALITY_GATES.md",
+      "critical": true
+    },
+    {
+      "file": "EVIDENCE_LOG.md",
+      "critical": true
+    }
+  ],
+  "outputs": [
+    {
+      "file": "EVIDENCE_LOG.md",
+      "validation_gate": "gate-completeness"
+    },
+    {
+      "file": "STATUS_EVENTS.ndjson",
+      "validation_gate": "gate-autonomy"
+    }
+  ],
+  "failure_routing": {
+    "missing_input": "BLOCK_AND_REQUEST_INFO",
+    "gate_failure": "BLOCK_AND_ESCALATE"
+  }
+}

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

@@ -145,6 +145,27 @@
         "registry_path": {
           "type": "string",
           "minLength": 1
+        },
+        "surgical_read_budgets": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "small_local": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "mid": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "frontier": {
+              "type": [
+                "integer",
+                "null"
+              ],
+              "minimum": 1
+            }
+          }
         }
       }
     },

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

@@ -163,6 +163,46 @@
           "items": {
             "$ref": "#/$defs/tool_call"
           }
+        },
+        "turn_outcome": {
+          "type": "string",
+          "enum": [
+            "no_op_success",
+            "meaningful_completion",
+            "escalation_blocker"
+          ]
+        },
+        "outcome_reason": {
+          "type": "string"
+        }
+      }
+    },
+    "output_policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "emit_to",
+        "silent_unless_blocked",
+        "require_approval_before_emit"
+      ],
+      "properties": {
+        "emit_to": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "tui",
+              "tracker",
+              "handoff",
+              "vericify"
+            ]
+          }
+        },
+        "silent_unless_blocked": {
+          "type": "boolean"
+        },
+        "require_approval_before_emit": {
+          "type": "boolean"
         }
       }
     },
@@ -278,6 +318,9 @@
             "failed"
           ]
         },
+        "output_policy": {
+          "$ref": "#/$defs/output_policy"
+        },
         "turns": {
           "type": "array",
           "items": {

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

@@ -72,6 +72,17 @@
           "last_error": {
             "type": "string"
           },
+          "hook_health": {
+            "type": "string",
+            "enum": [
+              "ok",
+              "degraded",
+              "failed"
+            ]
+          },
+          "hook_summary": {
+            "type": "string"
+          },
           "created_at": {
             "type": "string",
             "format": "date-time"

package/assets/agent-state/STATUS.md

@@ -1,8 +1,8 @@
 # STATUS
 
-- Current role: `ace-orchestrator`
+- Current role: `capability-skeptic`
 - Current phase: `STATE_ANALYSIS`
 - Active pipeline: `standard`
 - Blockers: `none`
 - Current objective delta: `bootstrap complete, awaiting first scoped objective`
-- Last update: `{{BOOTSTRAP_TIMESTAMP}}`
+- Last update: `2026-03-03T00:00:00Z`