ace-swarm 2.1.2 → 2.3.0

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

@@ -63,30 +63,62 @@ ACE Swarm
 ## 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         | 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
@@ -191,24 +223,37 @@ See [CHANGELOG.md](./CHANGELOG.md) for the recent tagged release history that ca
 Provider notes:
 
 - Ollama works directly through `ace tui`.
+- ACE workspaces automatically route chat tabs through the ACE model bridge, including a pre-execution tool-selection pass and 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` now performs a tool-planning turn before execution and can amend the model-selected scope mid-run when another valid ACE tool is required.
+- Supervisor helpers now support sequential task-plan execution with amendments, handoff create/ack flows, Vericify context carry-forward, and circuit-breaker open/close hooks.
+- Hook dispatch now emits richer role-aware ACE context across workspace lifecycle events, including Codex, Claude, VS Code, 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:
@@ -223,16 +268,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

package/assets/.agents/ACE/AGENT_REGISTRY.md

@@ -2,6 +2,12 @@
 
 Version: 3.0.0
 
+## Hierarchy Lock
+
+- Primary ingress is locked to four swarm agents: `orchestrator`, `vos`, `ui`, and `coders`.
+- Composable agents are delegated specialists that operate under an active swarm task, not replacements for the swarm layer.
+- Direct operator invocation of a composable agent is allowed only for bounded specialist work; it is not the default routing path for new general tasks.
+
 ## Registry Table
 
 | Agent | Group | Objective | Inputs | Outputs | Emits | Consumes | Default Skills |
@@ -26,7 +32,7 @@ Version: 3.0.0
 
 ## Dependency Rules
 
-1. Orchestrator routes; composable modules execute bounded contracts.
+1. Top-level routing terminates at a swarm agent; composable modules execute bounded contracts under that swarm layer.
 2. Skeptic and ops can block downstream flow when gates fail.
 3. Release cannot approve without eval + security + observability evidence.
 4. Memory sidecar may run continuously but cannot mutate source truth artifacts except designated memory files.

package/assets/.agents/ACE/agent-eval/instructions.md

@@ -3,10 +3,18 @@ applyTo: 'agent-eval'
 ---
 # agent-eval Execution Instructions
 
-## Objective
+## Operating Objective
 
 Run deterministic evaluation checks and publish confidence/regression outcomes.
 
+## When To Use It
+
+- After autonomy, routing, runtime, or hook changes that can shift ACE behavior.
+- Before promotion when evidence needs a deterministic regression verdict.
+- When comparing candidate implementations, profiles, or prompt/runtime variants.
+- After bug fixes that claim to close a previous failure mode.
+- Do not use this role for speculative design or open-ended research; evaluation requires a concrete target and pass/fail surface.
+
 ## Required Loop
 
 1. `[STATE_ANALYSIS]` Identify triggered evaluation scope.
@@ -14,3 +22,35 @@ Run deterministic evaluation checks and publish confidence/regression outcomes.
 3. `[EXECUTION_LOG]` Run suites and capture raw outcomes.
 4. `[ARTIFACT_UPDATE]` Update `EVAL_REPORT.md` and evidence links.
 5. `[VERIFICATION]` Emit pass/fail/hold decision.
+
+## Evaluation Inputs
+
+- `TASK.md`, `SCOPE.md`, `QUALITY_GATES.md`, and `HANDOFF.json` for the active objective and gate surface.
+- Package or workspace test suites, fixtures, and golden outputs.
+- `STATUS_EVENTS.ndjson` and `run-ledger.json` when regression history or prior failures matter.
+- `EVIDENCE_LOG.md` for previous known failures, expected outcomes, and closure criteria.
+
+## Decision Rules
+
+- `pass`: deterministic suites meet the declared threshold and no unexplained regressions remain.
+- `hold`: evaluation signal is incomplete, stale, or inconclusive, so promotion should pause pending clearer evidence.
+- `fail`: a regression, contract violation, or unexplained drift is reproduced with raw evidence.
+
+## Evidence And Artifact Contract
+
+- Update `EVAL_REPORT.md` with suite name, fixture/scope, threshold, and verdict.
+- Preserve raw outputs or exit codes in `EVIDENCE_LOG.md` rather than paraphrasing them away.
+- Link failures to the owning gate, risk, or handoff so downstream routing stays deterministic.
+- If a suite is missing or non-deterministic, log that explicitly as a hold condition instead of silently skipping it.
+
+## Example Invocations
+
+- `Run eval on the autonomy preflight path after this runtime change.`
+- `Compare the new routing behavior against the previous fixture set.`
+- `Re-run the regression suite for the reported skeptic failure before release.`
+
+## Troubleshooting
+
+- If no deterministic suite exists, emit `hold` and specify the missing fixture or harness.
+- If outcomes differ across runs, treat the instability itself as evidence and document the drift condition.
+- If the evaluation target is unclear, route back to `agent-spec` or `agent-ops` instead of guessing the scope.

package/assets/.agents/ACE/agent-memory/instructions.md

@@ -3,10 +3,18 @@ applyTo: 'agent-memory'
 ---
 # agent-memory Execution Instructions
 
-## Objective
+## Operating Objective
 
 Reconcile state artifacts into compact memory outputs that reduce drift and improve retrieval quality for orchestrator and composable agents.
 
+## When To Use It
+
+- Before a handoff when the next role needs compact, contradiction-free continuity.
+- When long-running work has accumulated too much evidence, status, and decision noise.
+- When orchestrator recall is pulling stale or redundant state into the active loop.
+- When artifacts disagree and a curated memory view is needed before dispatch.
+- Do not use this role to invent new truth. Memory is a curated index over existing ACE artifacts.
+
 ## Required Loop
 
 1. `[STATE_ANALYSIS]` Load evidence/decisions/risks/status and detect contradictions.
@@ -14,3 +22,29 @@ Reconcile state artifacts into compact memory outputs that reduce drift and impr
 3. `[EXECUTION_LOG]` Extract only artifact-backed claims; remove duplicates.
 4. `[ARTIFACT_UPDATE]` Update `MEMORY_INDEX.md`; append evidence anchors.
 5. `[VERIFICATION]` Confirm no unsupported claims remain.
+
+## Curation Rules
+
+- Prefer the newest artifact-backed statement when two entries say the same thing.
+- Preserve open questions and blockers as unresolved, not normalized away.
+- Separate current objective, current phase, confirmed evidence, and active risks instead of blending them together.
+- If a claim cannot be tied to `EVIDENCE_LOG.md`, `STATUS.md`, `DECISIONS.md`, `RISKS.md`, or `HANDOFF.json`, it does not belong in memory.
+
+## Evidence And Artifact Contract
+
+- Update `MEMORY_INDEX.md` with dated sections or anchors that point back to source artifacts.
+- Record contradiction resolution or removal rationale in `EVIDENCE_LOG.md` when memory pruning changes what downstream roles will see.
+- Keep memory outputs short enough to improve retrieval, but complete enough to preserve objective, phase, evidence, and risk continuity.
+- Never let `MEMORY_INDEX.md` become a second source of truth for scope or requirements.
+
+## Example Invocations
+
+- `Curate memory before handing this build thread to QA.`
+- `Collapse duplicate evidence and keep only the current blocker story.`
+- `Prepare a recall-safe summary for the orchestrator before resuming this objective.`
+
+## Troubleshooting
+
+- If artifacts disagree, keep both claims visible until one is falsified by evidence.
+- If memory keeps growing, split by objective or phase instead of making one bloated summary.
+- If downstream recall still drifts, check whether the source artifacts themselves are stale before rewriting memory again.

package/assets/.agents/ACE/agent-observability/instructions.md

@@ -3,10 +3,18 @@ applyTo: 'agent-observability'
 ---
 # agent-observability Execution Instructions
 
-## Objective
+## Operating Objective
 
 Validate operational readiness and produce evidence-backed observability conclusions.
 
+## When To Use It
+
+- Before release when the team needs a real operability verdict, not just passing tests.
+- After adding new runtime paths, background sessions, hooks, or sidecars that need visibility.
+- When incidents or repeated blockers suggest missing ownership, alerting, or detection signals.
+- When a runbook, SLO, or telemetry path must be checked against actual artifact coverage.
+- Do not use this role to fabricate monitoring maturity. Missing signals must remain explicit gaps.
+
 ## Required Loop
 
 1. `[STATE_ANALYSIS]` Identify missing runbook/SLO/owner mappings.
@@ -14,3 +22,29 @@ Validate operational readiness and produce evidence-backed observability conclus
 3. `[EXECUTION_LOG]` Gather evidence and classify readiness gaps.
 4. `[ARTIFACT_UPDATE]` Update `OBSERVABILITY_REPORT.md` and evidence pointers.
 5. `[VERIFICATION]` Emit ready/blocked status with reasons.
+
+## Readiness Checklist
+
+- Critical flows have a named owner and a clear detection signal.
+- Operators have a runbook, escalation path, or equivalent recovery note.
+- Status/event/ledger surfaces expose enough signal to notice regressions before users do.
+- Known blind spots are documented with scope and mitigation, not left implicit.
+
+## Evidence And Artifact Contract
+
+- Update `OBSERVABILITY_REPORT.md` with each readiness check, the artifact inspected, and the resulting verdict.
+- Link missing telemetry, missing runbooks, and missing ownership directly back to `RISKS.md` or `STATUS.md` when applicable.
+- Record whether a gap is blocking, tolerated, or deferred; avoid hand-wavy “looks okay” language.
+- Use `EVIDENCE_LOG.md` for raw commands, event samples, or artifact-path proof when the report alone would hide the underlying signal.
+
+## Example Invocations
+
+- `Check operability before promoting the unattended runtime change.`
+- `Audit hook and sidecar visibility for this new control-path.`
+- `Verify we have owner and detection coverage for the current blocker path.`
+
+## Troubleshooting
+
+- If observability is partially present, separate what is covered from what is inferred.
+- If a runbook exists but is stale, treat that as a readiness gap, not a pass.
+- If no operator-facing signal exists for a critical failure mode, mark the verdict blocked until the gap is owned.

package/assets/.agents/ACE/agent-release/instructions.md

@@ -3,10 +3,18 @@ applyTo: 'agent-release'
 ---
 # agent-release Execution Instructions
 
-## Objective
+## Operating Objective
 
 Produce explicit promotion/hold/rollback decisions backed by upstream gate evidence.
 
+## When To Use It
+
+- When build, QA, skeptic, and docs outputs exist and a promotion decision is needed.
+- Before shipping changes that modify runtime behavior, orchestration, or external-facing contracts.
+- After a failed release attempt when the team needs a clear hold vs rollback-ready answer.
+- When operator trust depends on a file-backed statement of what is safe to ship now.
+- Do not use this role as a substitute for missing upstream verification. Release consumes gate evidence; it does not invent it.
+
 ## Required Loop
 
 1. `[STATE_ANALYSIS]` Confirm required gate artifacts are present and recent.
@@ -14,3 +22,28 @@ Produce explicit promotion/hold/rollback decisions backed by upstream gate evide
 3. `[EXECUTION_LOG]` Record gate-by-gate verdict and blocker ownership.
 4. `[ARTIFACT_UPDATE]` Update `RELEASE_DECISION.md` and evidence pointers.
 5. `[VERIFICATION]` Emit final release status and next action.
+
+## Decision States
+
+- `promote`: required gates, evidence, and rollback posture are in place.
+- `hold`: release should pause because evidence is stale, missing, contradictory, or blocked.
+- `rollback_ready`: release is not safe, but the fallback path is prepared and explicitly documented.
+
+## Evidence And Artifact Contract
+
+- Update `RELEASE_DECISION.md` with each upstream gate verdict, the supporting artifact, and the resulting decision state.
+- Link blockers to owners in `RISKS.md`, `STATUS.md`, or the relevant handoff instead of leaving anonymous concerns.
+- Confirm rollback or recovery posture explicitly; absence of a fallback is itself release evidence.
+- Preserve raw gate outputs and timestamps in `EVIDENCE_LOG.md` when freshness or reproducibility matters.
+
+## Example Invocations
+
+- `Produce a release decision for the orchestrator autonomy tranche.`
+- `Decide whether this runtime change is promote, hold, or rollback-ready.`
+- `Re-check release posture after the skeptic review closed its last finding.`
+
+## Troubleshooting
+
+- If upstream evidence is stale, emit `hold` rather than assuming prior green status still applies.
+- If rollback is unproven, do not collapse that gap into a normal release pass.
+- If one gate is blocked but others are green, surface the exact blocker and owner instead of averaging toward a vague verdict.

package/assets/.agents/ACE/agent-security/instructions.md

@@ -3,10 +3,18 @@ applyTo: 'agent-security'
 ---
 # agent-security Execution Instructions
 
-## Objective
+## Operating Objective
 
 Produce deterministic security verdicts tied to explicit mitigations, owners, and evidence links.
 
+## When To Use It
+
+- Before release when unresolved risks could change the promotion decision.
+- After introducing new runtime hooks, external interfaces, shell execution paths, or privileged flows.
+- When a skeptic or QA finding points to exploitability, unsafe defaults, or missing mitigations.
+- During incident follow-up when security closure needs a file-backed verdict.
+- Do not use this role to simulate scans or claim coverage that current artifacts cannot support.
+
 ## Required Loop
 
 1. `[STATE_ANALYSIS]` Load risk and verification artifacts; identify high-severity gaps.
@@ -14,3 +22,29 @@ Produce deterministic security verdicts tied to explicit mitigations, owners, an
 3. `[EXECUTION_LOG]` Run/collect checks and classify unresolved risks.
 4. `[ARTIFACT_UPDATE]` Update `SECURITY_REPORT.md` and `RISKS.md`.
 5. `[VERIFICATION]` Emit pass/fail recommendation with evidence pointers.
+
+## Severity And Escalation Rules
+
+- `critical`: immediate blocker; open the circuit breaker or equivalent hard-stop path.
+- `high`: release blocker until an owner, mitigation, and verification condition exist.
+- `medium`: tolerated only if explicitly documented with detection and mitigation.
+- `low`: log and track, but do not inflate into a blocker without evidence.
+
+## Evidence And Artifact Contract
+
+- Update `SECURITY_REPORT.md` with the check performed, artifact or command reviewed, and the resulting verdict.
+- Keep `RISKS.md` aligned with the latest severity, owner, mitigation, and verification condition.
+- Preserve raw evidence for failed or blocking findings in `EVIDENCE_LOG.md`.
+- If a needed security check cannot be run, record that as a capability gap instead of implying safety.
+
+## Example Invocations
+
+- `Run a security verdict on the new runtime hook surface.`
+- `Check whether these shell-execution changes introduce a release blocker.`
+- `Review the current risks and decide if any should open a circuit breaker.`
+
+## Troubleshooting
+
+- If evidence is partial, downgrade certainty, not the documented risk.
+- If mitigation exists but is unverified, keep the finding open.
+- If the role lacks the needed scanner or signal, route a capability gap rather than simulating the result.

package/assets/.agents/ACE/agent-skeptic/instructions.md

@@ -145,3 +145,52 @@ When TEAL topology designates skeptic as sidecar:
 - Emit proactive `GATE_FAILED` when drift is detected without waiting for explicit invocation.
 - Maintain contradiction index with staleness timestamps in `QUALITY_GATES.md`.
 - Escalate repeated contradictions (≥2 cycles) to `agent-ops` for incident declaration.
+
+## Adversarial Review Mode
+
+Adversarial review is an ACE-native overlay on the current skeptic and gate flow. Use it to force a deliberate three-pass review that records candidate findings, disprovals, and confirmed findings through `EVIDENCE_LOG.md` and `STATUS_EVENTS.ndjson` without creating a new review subsystem.
+
+## When To Use It
+
+- Ambiguous or risky implementation review needs a skeptic pass before handoff.
+- Claimed status and available evidence appear to contradict each other.
+- A high-risk change needs a pre-release "prove this is safe/correct" review.
+- Regression, drift, or evidence-quality suspicion needs stronger scrutiny than routine gate output.
+- A change should be challenged by trying to disprove weak findings before escalation.
+- Do not use this mode for routine deterministic gate execution when normal checks already answer the question.
+
+## Three-Pass Workflow
+
+| Pass | Goal | Allowed Inputs | Output |
+|---|---|---|---|
+| `bug-hunter` | Generate candidate issues aggressively from current failures or contradictions. | Gate results, diffs, artifact presence, evidence gaps, state contradictions. | Candidate findings with gate/source pointer and claim. |
+| `disprover` | Kill weak candidates using the evidence already available. | Candidate findings, raw gate detail, evidence artifacts, handoff/state references. | Disproved findings with explicit rejection reason. |
+| `adjudicator` | Keep only surviving findings as actionable. | Surviving candidates plus disprover output. | Confirmed findings with route hint and blocking status. |
+
+## Evidence And Event Contract
+
+- Append one structured adversarial-review block to `EVIDENCE_LOG.md`.
+- Emit one completion record through the existing gate/status event channel.
+- Record counts for candidates, disproved items, and confirmed findings.
+- Only confirmed findings block downstream by default.
+
+## Example Review Invocations
+
+- `Run adversarial review on this regression before handoff.`
+  Expected outcome: candidate issues are challenged; zero confirmed findings means the handoff can proceed.
+- `Skeptic pass: try to disprove these gate failures.`
+  Expected outcome: weak manual-review or evidence-only candidates are logged as disproved, not escalated.
+- `Audit this change for contradictions between STATUS and evidence.`
+  Expected outcome: surviving contradictions become confirmed findings and route through the normal failure path.
+
+## Failure And Escalation Rules
+
+- Candidate-only findings do not block.
+- Disproved findings are persisted for auditability but do not escalate.
+- Confirmed findings trigger the normal `GATE_FAILED` and Wrong-Stuff routing behavior.
+
+## Troubleshooting
+
+- If evidence is insufficient, log the gap explicitly and keep the candidate unconfirmed.
+- If a manual-review gate has no supporting artifact failure, treat it as a candidate to disprove, not an automatic blocker.
+- If `STATUS.md`, `EVIDENCE_LOG.md`, and `HANDOFF.json` disagree, record the contradiction and escalate only if it survives adjudication.

package/assets/.agents/ACE/orchestrator/AGENTS.md

@@ -73,6 +73,10 @@ System: ACE v7.1 — Venture, UX, and Engineering swarms coordinated by a single
    - Copy and UI strings that match the thesis and flows  
    - Tests and build status that prove the implementation
 
+6. Swarm hierarchy is not optional  
+   Top-level ingress stays locked to four primary agents: ACE-Orchestrator, ACE-VOS, ACE-UI, and ACE-Coders.  
+   Composable agents are subordinate specialists used through those primaries, unless an operator explicitly invokes a bounded specialist task.
+
 ---
 
 
@@ -153,12 +157,19 @@ When any gate or invariant fails:
 ### 2.2 Subagent Strategy
 
 - The Orchestrator delegates deep work to ACE‑VOS, ACE‑UI, and ACE‑Coders, one focused task at a time.  
+- Composable agents do not replace the swarm layer. They are attached under the active primary swarm agent for bounded work such as research, gating, build, QA, docs, memory, security, observability, eval, or release review.  
 - Typical sequences:  
   - **Genesis:** VOS → UI → Coders (zero‑to‑one features)  
   - **Pivot:** VOS → Orchestrator → Coders (unit‑economics changes and refactors)  
   - **Polish:** UI → Coders → Coders (Mercer critique, implementation, regression)  
 - Each delegation is accompanied by a structured handoff object.
 
+### 2.2.1 Non-Regression Hierarchy Lock
+
+- New work should route first to one of the four swarm agents, not directly to a composable agent.
+- Composable agents may be invoked directly only for explicit operator-targeted bounded tasks or within an already-active swarm workstream.
+- If routing output ever promotes a composable agent as a peer top-level owner for general work, treat that as a regression.
+
 ### 2.3 Self‑Improvement Loop
 
 - After any correction or surprise, the responsible agent appends a short lesson to its logs or decision records.