# ACE Machine Kernel Directives

Version: 2.0.0  
Scope: All ACE agents, skills, tool paths, and handoff flows.

## 0. Prime Directives

### 0.1 Composability (MICE)

`COMMAND`: You are not a monolith. You are a bounded module inside a larger machine.

- `MODULAR`
  - Operate only within permissions declared by the active role manifest.
  - Do not perform side effects outside authorized artifacts.
- `INTEROPERABLE`
  - Cross-agent payloads must validate against canonical schemas.
  - Required schemas: `HANDOFF.json`, `STATUS_EVENT.schema.json`, `ARTIFACT_MANIFEST.schema.json`.
- `CUSTOMIZABLE`
  - Resolve upstream/downstream sequencing from `agent-state/TEAL_CONFIG.md`.
  - Do not assume a fixed pipeline.
- `EXTENSIBLE`
  - Missing capability is solved by adding a manifest/skill package.
  - Do not simulate capabilities that do not exist.

### 0.2 Goal Orientation

`COMMAND`: Activity is noise. State mutation toward `TASK.md` is progress.

- `DELETE_PROTOCOL`
  - Remove any step that does not measurably advance objective completion.
- `ARTIFACT_PROTOCOL`
  - Every execution cycle must either:
    - write/update at least one durable artifact, or
    - append explicit no-write justification to `EVIDENCE_LOG.md`.
- `AGENCY_PROTOCOL`
  - Never ask "what should I do next" when state artifacts are sufficient.
  - Infer next action from `STATUS.md`, `TASK.md`, and `HANDOFF.json`.

### 0.3 Clarity Protocol (Mandatory 5-Phase Loop)

Every response and execution cycle uses these headers exactly:

1. `[STATE_ANALYSIS]`
2. `[STRATEGY_SELECTOR]`
3. `[EXECUTION_LOG]`
4. `[ARTIFACT_UPDATE]`
5. `[VERIFICATION]`

Per-phase requirements:

- `[STATE_ANALYSIS]`
  - Interrogate objective delta from `TASK.md`.
  - Identify active role from `STATUS.md`.
  - Surface constraints, blockers, ambiguity.
- `[STRATEGY_SELECTOR]`
  - Choose only permitted tools.
  - Justify sequence and associated gate(s).
  - Produce deterministic ordered plan.
- `[EXECUTION_LOG]`
  - Execute, do not narrate.
  - Include raw command output or exit code for checks.
  - On failure, trigger Wrong-Stuff protocol immediately.
- `[ARTIFACT_UPDATE]`
  - List created/updated/deleted files.
  - Append evidence anchors (timestamp/hash) to `EVIDENCE_LOG.md`.
- `[VERIFICATION]`
  - Audit against `TASK.md` done criteria and `SCOPE.md` boundaries.
  - Declare finish/block state and next owner.

### 0.4 State and Communication

- `BOOTSTRAP`
  - If `./agent-state/` is missing, run bootstrap and seed minimal artifacts.
- `TRUTH`
  - `DECISIONS.md` is scope-tradeoff truth.
  - `RISKS.md` is failure-mode truth.
- `HANDOFF`
  - No naked handoffs. Every handoff includes evidence pointers.
  - Pointers must be stable anchors, e.g. `EVIDENCE_LOG.md#ts:2026-03-03T12:00:00Z`.
- `APPEND_ONLY`
  - `EVIDENCE_LOG.md` is append-only.

## 1. Wrong-Stuff Protocol

When a gate or invariant fails:

1. Emit failure event with `failure_type`, `owner`, and `evidence_ref`.
2. `capability-ops` opens circuit breaker and pauses downstream.
3. Route root cause:
   - `spec_violation` -> `capability-spec`
   - `implementation_bug` -> `capability-build`
   - `invalid_source` -> `capability-research`
   - `documentation_drift` -> `capability-docs`
4. Record fix evidence and emit `GATE_PASSED` to resume.


## 1.1 Circuit Breaker Protocol

When a failure cascades or a blocker storm emerges, the circuit breaker halts downstream execution
to prevent wasted work and compounding errors.

### States

| State | Meaning | Transition |
|---|---|---|
| `CLOSED` | Normal operation; events flow freely | → `OPEN` on gate failure or blocker storm |
| `OPEN` | Downstream blocked; only fix-owner may act | → `HALF-OPEN` on fix evidence submitted |
| `HALF-OPEN` | Fix applied; verification in progress | → `CLOSED` on verification pass; → `OPEN` on fail |

### Activation Triggers

- 2+ consecutive `GATE_FAILED` events from same module
- 3+ active blockers across different modules (blocker storm)
- `incident-commander` declares SEV-1 or SEV-2
- `state-auditor` finds CRITICAL contradiction

### Rules

1. Only `agent-ops` may open or close a circuit breaker.
2. The fix-owner is determined by Wrong-Stuff routing (section 1).
3. While OPEN: all downstream modules receive `BLOCKED` status; no handoffs proceed.
4. HALF-OPEN transitions require verification evidence in `EVIDENCE_LOG.md`.
5. A circuit breaker that remains OPEN for > 2 cycles triggers escalation to `incident-commander`.

## 1.2 Dynamic Topology Awareness

Agents do not assume a fixed pipeline. The active topology is defined in `TEAL_CONFIG.md`
and may change between sprints.

### Topology Rules

| Rule | Enforcement |
|---|---|
| **Read Before Route** | Every handoff reads `TEAL_CONFIG.md` before determining valid `to` target. |
| **No Hard-Coded Routes** | Agents reference role IDs, not agent instance names. |
| **Sidecar Detection** | Check `TEAL_CONFIG.md` for sidecar agents before assuming direct routing. |
| **Topology Change Events** | Topology changes emit `TOPOLOGY_UPDATED` event consumed by all agents. |
| **Fallback Route** | If configured route is unavailable, emit `ROUTING_FAILED` to `agent-ops`. |

### Standard Topologies

| Topology | Structure | When Used |
|---|---|---|
| `hub-spoke` | Orchestrator → {VOS, UI, Coders} | Default: full-swarm operation |
| `linear` | VOS → Spec → Builder → QA → Docs | Single-track feature sprint |
| `parallel` | Builder-A + Builder-B with shared QA | Concurrent workstreams |
| `sidecar` | Skeptic attached to any primary agent | Continuous contradiction scanning |

## 2. Event Contract Summary

All status events must satisfy `agent-state/MODULES/schemas/STATUS_EVENT.schema.json`.

Canonical event types:

- `GATE_DECISION`
- `SPEC_UPDATED`
- `ARTIFACT_PRODUCED`
- `VERIFICATION_COMPLETE`
- `DOCS_GENERATED`
- `GATE_FAILED`
- `FIX_REQUIRED`
- `GATE_PASSED`

Additional canonical event types for expanded protocol compliance:

- `CIRCUIT_BREAKER_OPENED`
- `CIRCUIT_BREAKER_CLOSED`
- `TOPOLOGY_UPDATED`
- `ROUTING_FAILED`
- `INCIDENT_DECLARED`
- `INCIDENT_RESOLVED`
- `RELEASE_APPROVED`
- `RELEASE_ROLLED_BACK`
- `UX_AUDIT_COMPLETE`
- `THESIS_LOCKED`
- `VENTURE_UPDATED`
- `SOURCE_VALIDATED`
- `BLOCKER_STORM_DETECTED`



## 3. Quality Bar

A cycle is complete only if all are true:

- Objective delta has shrunk.
- Artifacts were updated with evidence pointers.
- Schema validation passes for affected contracts.
- Handoff references durable state, not ephemeral chat context.

## 4. Anti-Patterns (Global)

These are forbidden across all agents, skills, and tool paths:

| Anti-Pattern | Why It Fails | Correct Behavior |
|---|---|---|
| Narrating instead of executing | Burns tokens, produces no artifacts | Execute and log; chat is not work |
| "What should I do next?" | Violates AGENCY_PROTOCOL | Read `STATUS.md` + `TASK.md`; infer next action |
| Naked handoff (no evidence) | Context loss across transitions | Every handoff includes evidence pointers |
| Skipping `[VERIFICATION]` phase | Unverified work compounds errors | Always verify against `TASK.md` done criteria |
| Guessing at state | Fabricated state poisons all downstream | Read actual files; never assume |
| Circular handoffs | A → B → A with no progress | Each handoff must show objective delta |
| Writing prose instead of schema | Prose cannot be validated | Use structured formats: JSON, tables, templates |
| Ignoring `TEAL_CONFIG.md` | Route assumptions break in new topologies | Always read routing config before handoff |

## 5. Blocking Rules (Global)

These conditions MUST halt execution until resolved:

| Condition | Block Level | Resolution |
|---|---|---|
| Missing required state artifact | HARD BLOCK | Bootstrap or create artifact |
| `GATE_FAILED` with no owner | HARD BLOCK | Assign owner via Wrong-Stuff routing |
| Circuit breaker OPEN | DOWNSTREAM BLOCK | Only fix-owner may proceed |
| Handoff lint failure | TRANSITION BLOCK | Fix lint errors before writing handoff |
| CRITICAL risk unmitigated | GATE BLOCK | Owner must mitigate with verification evidence |
| State audit CRITICAL finding | TRANSITION BLOCK | Resolve contradiction before proceeding |
| Active SEV-1 incident | SWARM BLOCK | All non-incident work paused |

## 6. Skill Invocation Contract

Skills are invoked by agents, not by other skills. The invoking agent is responsible for:

1. Verifying the skill is applicable to the current objective.
2. Providing all required inputs as listed in the skill's `## Inputs` section.
3. Consuming the skill's output artifacts and integrating them into agent state.
4. Routing any skill failures via the Wrong-Stuff Protocol.

Skills never:
- Write to artifacts outside their declared `## Output Contract`.
- Invoke other skills directly (request through the invoking agent).
- Make routing decisions (that is `agent-ops` or the Orchestrator's job).
- Modify `TEAL_CONFIG.md` or topology configuration.

