ace-swarm 2.1.2 → 2.2.0

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.  

package/assets/agent-state/ACE_WORKFLOW.md

@@ -20,6 +20,22 @@ executor:
   turn_timeout_ms: 300000
 tools:
   registry_path: "agent-state/runtime-tool-specs.json"
+autonomy:
+  orchestrator_preflight: true
+  recall_context: true
+  state_sources: ["agent-state/TASK.md", "agent-state/SCOPE.md", "agent-state/QUALITY_GATES.md", "agent-state/STATUS.md", "agent-state/HANDOFF.json", "agent-state/EVIDENCE_LOG.md"]
+  before_run_checks: []
+  stop_checks: []
+  review_mode: null
+continuity:
+  enabled: true
+  source_paths: ["agent-state/TASK.md", "agent-state/SCOPE.md", "agent-state/QUALITY_GATES.md", "agent-state/HANDOFF.json", "agent-state/STATUS.md", "agent-state/DECISIONS.md", "agent-state/RISKS.md", "agent-state/EVIDENCE_LOG.md"]
+  max_sources: 6
+  max_excerpt_chars: 450
+  max_total_chars: 2600
+  max_status_events: 6
+  max_run_ledger_entries: 4
+  include_snapshot: true
 tracker:
   kind: "none"
   config: {}
@@ -35,6 +51,11 @@ observability:
 
 Operate under ACE runtime profile `{{runtime.profile_name}}` in `{{runtime.mode}}` mode.
 
+## Runtime Intent
+- Use this profile for ACE execution that must stay aligned to file-backed state and managed workspace policy.
+- Treat front matter as execution policy. If a field is `null`, `false`, or empty, do not invent extra runtime machinery.
+- Preserve objective, boundary, evidence, and transition truth inside ACE artifacts rather than chat-local memory.
+
 ## Task
 {{task}}
 
@@ -52,6 +73,45 @@ Operate under ACE runtime profile `{{runtime.profile_name}}` in `{{runtime.mode}
 ## Runtime Tools
 - Registry: `{{tools.registry_path}}`
 
+## Autonomy
+- Orchestrator preflight: `{{autonomy.orchestrator_preflight}}`
+- Recall context: `{{autonomy.recall_context}}`
+- State sources: `{{autonomy.state_sources}}`
+- Before-run checks: `{{autonomy.before_run_checks}}`
+- Stop checks: `{{autonomy.stop_checks}}`
+- Review mode: `{{autonomy.review_mode}}`
+
+## Autonomy Guidance
+- `orchestrator_preflight` means validate ACE truth before substantial work or delegation.
+- `recall_context` means prefer current task, status, handoff, and evidence state over stale thread assumptions.
+- `before_run_checks` are blocking checks. If they fail, stop and surface the failure through ACE evidence and status channels.
+- `stop_checks` are terminal or handoff checks. If they fail, do not continue optimistically.
+- `review_mode` must stay inside existing ACE tools and artifacts; it is an overlay, not a second subsystem.
+
+## Continuity
+- Enabled: `{{continuity.enabled}}`
+- Source paths: `{{continuity.source_paths}}`
+- Max sources: `{{continuity.max_sources}}`
+- Max excerpt chars: `{{continuity.max_excerpt_chars}}`
+- Max total chars: `{{continuity.max_total_chars}}`
+- Max status events: `{{continuity.max_status_events}}`
+- Max run-ledger entries: `{{continuity.max_run_ledger_entries}}`
+- Include snapshot: `{{continuity.include_snapshot}}`
+
+## Continuity Guidance
+- Continuity packets are derived from current ACE truth; they are not a replacement source of truth.
+- Treat the configured budgets as source-side compaction rules for unattended execution and delegation, including recent status and run-ledger visibility.
+- If continuity is disabled, do not synthesize a replacement packet in chat or hidden state.
+
+## ACE Recall
+{{ace_state_recall_md}}
+
+## Context Snapshot
+{{ace_context_snapshot_md}}
+
+## Continuity Packet
+{{ace_continuity_packet_md}}
+
 ## Tracker
 - Kind: `{{tracker.kind}}`
 
@@ -64,3 +124,8 @@ Operate under ACE runtime profile `{{runtime.profile_name}}` in `{{runtime.mode}
 - Preserve ACE state artifacts as the durable source of truth.
 - Treat Vericify as an optional sidecar, not a required ACE runtime dependency.
 - Treat this template as additive execution guidance for future unattended flows.
+
+## Failure Handling
+- When the task contract, evidence, or hooks are contradictory, prefer hold/escalation over optimistic continuation.
+- Record blockers in ACE artifacts with owners and evidence refs before handing off or stopping.
+- If the profile is missing capabilities, keep the gap explicit rather than silently broadening the runtime contract.

package/assets/agent-state/INTERFACE_REGISTRY.md

@@ -19,6 +19,7 @@
 - `ACE_WORKFLOW.md` is the canonical workspace runtime profile artifact.
 - Its YAML front matter must validate against `MODULES/schemas/ACE_RUNTIME_PROFILE.schema.json`.
 - The markdown body after the closing front matter boundary is the active runtime prompt template.
+- The optional `continuity` block only budgets derived packet content; it must not redefine canonical ACE truth outside the existing state artifacts and sidecar-native stores.
 
 ## Workspace Session Contract
 

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

@@ -148,6 +148,85 @@
         }
       }
     },
+    "autonomy": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "orchestrator_preflight": {
+          "type": "boolean"
+        },
+        "recall_context": {
+          "type": "boolean"
+        },
+        "state_sources": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "before_run_checks": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "stop_checks": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "review_mode": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "minLength": 1
+        }
+      }
+    },
+    "continuity": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "type": "boolean"
+        },
+        "source_paths": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "max_sources": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "max_excerpt_chars": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "max_total_chars": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "max_status_events": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "max_run_ledger_entries": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "include_snapshot": {
+          "type": "boolean"
+        }
+      }
+    },
     "tracker": {
       "type": "object",
       "additionalProperties": false,

package/assets/scripts/copilot-hook-dispatch.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
 
 const DESTRUCTIVE_COMMAND_PATTERNS = [
@@ -82,6 +82,40 @@ function aceContext(workspaceRoot) {
   };
 }
 
+function readAutonomyHint(workspaceRoot) {
+  const workflowPath = resolve(workspaceRoot, "agent-state", "ACE_WORKFLOW.md");
+  const defaultHint =
+    "Runtime autonomy defaults are active: orchestrator preflight, context recall.";
+  if (!existsSync(workflowPath)) return defaultHint;
+
+  let raw = "";
+  try {
+    raw = readFileSync(workflowPath, "utf8");
+  } catch {
+    return defaultHint;
+  }
+
+  if (!/^\s*autonomy:\s*$/m.test(raw)) {
+    return defaultHint;
+  }
+
+  const signals = [];
+  if (/^\s*autonomy:\s*$/m.test(raw) && /^\s*orchestrator_preflight:\s*true\s*$/m.test(raw)) {
+    signals.push("orchestrator preflight");
+  }
+  if (/^\s*autonomy:\s*$/m.test(raw) && /^\s*recall_context:\s*true\s*$/m.test(raw)) {
+    signals.push("context recall");
+  }
+  const reviewMode = raw.match(/^\s*review_mode:\s*["']?([A-Za-z0-9_-]+)["']?\s*$/m)?.[1];
+  if (reviewMode) {
+    signals.push(`review mode ${reviewMode}`);
+  }
+
+  return signals.length > 0
+    ? `Runtime autonomy policy is active in agent-state/ACE_WORKFLOW.md: ${signals.join(", ")}.`
+    : "";
+}
+
 function buildAceMessage(workspaceRoot) {
   const context = aceContext(workspaceRoot);
   if (!context.hasAgentState && !context.hasSkills) return "";
@@ -103,6 +137,10 @@ function buildAceMessage(workspaceRoot) {
   if (context.hasSkills) {
     parts.push("Workspace skills are available under .agents/skills/.");
   }
+  const autonomyHint = readAutonomyHint(workspaceRoot);
+  if (autonomyHint) {
+    parts.push(autonomyHint);
+  }
   parts.push(
     "Copilot hook policy protects .github/hooks, .vscode/settings.json, and scripts/ace/copilot-hook-dispatch.mjs from silent self-modification."
   );

package/assets/tasks/README.md

@@ -14,9 +14,35 @@ This directory contains shared execution artifacts consumed by ACE prompts, tool
 - `agent-state/job-locks.json`: collision-free scheduler locks.
 - `agent-state/scheduler-lease.json`: active scheduler lease ownership.
 
+## When To Read This Directory
+
+- Before starting non-trivial work that needs explicit task, role, or handoff structure.
+- Before issuing or consuming a `SWARM_HANDOFF`.
+- When recovering blocked or deferred work through the scheduler and TODO surfaces.
+- When a repeated failure should become a durable lesson or guardrail.
+
+## Common Workflows
+
+1. Start work: check `todo.md`, then use `role_tasks.md` to confirm the bounded contract for the active role.
+2. Route work: begin from `SWARM_HANDOFF.template.json`, then compare with the example payloads before publishing.
+3. Recover work: inspect `agent-state/job-queue.json`, `agent-state/job-locks.json`, and `agent-state/scheduler-lease.json` together instead of in isolation.
+4. Harden work: write repeatable failures to `lessons.md` so the same mistake does not re-enter the loop.
+
 ## Operating Rules
 
 1. Update `todo.md` before non-trivial work and after verification.
 2. Log every repeatable correction pattern in `lessons.md`.
 3. Use `SWARM_HANDOFF.template.json` as the base for all routing payloads.
 4. Keep acceptance criteria measurable and tied to file-based evidence.
+
+## Validation Rules
+
+- Handoffs must reference real artifacts, owners, and acceptance criteria.
+- Scheduler state is advisory unless it matches current task and status artifacts.
+- Lessons should capture a failure pattern, a guardrail, and a verification check, not just an anecdote.
+
+## Common Failure Modes
+
+- `todo.md` is stale while work has already moved; refresh it before trusting downstream routing.
+- A handoff exists without evidence or acceptance criteria; treat it as incomplete, not merely “draft.”
+- Scheduler files disagree with task or status truth; route the contradiction through ops instead of guessing which surface won.