@voybio/ace-swarm 0.1.0

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

@@ -0,0 +1,203 @@
+---
+name: eval-harness
+description:
+  Run deterministic autonomy evaluations for schemas, routing, completeness, and regressions. Use when contracts change, a release candidate is being promoted, or post-incident verification is required.
+---
+
+# Eval Harness
+
+## Purpose
+
+Provide repeatable quality evidence for autonomy behavior, not just code behavior.
+Testing without baselines is hope. Testing with baselines and regression detection is engineering.
+
+## Canonical Use Cases
+
+1. A schema, handoff, or routing contract changed and the team needs deterministic conformance evidence before continuing.
+2. A release candidate is being promoted and someone needs a repeatable quality gate across schema, routing, completeness, and behavioral suites.
+3. An incident or routing anomaly just closed and the team wants proof that the failure mode no longer reproduces.
+
+---
+
+## MICE Boundaries
+
+| Rule | Enforcement |
+|---|---|
+| **Modular** | Runs evaluations; does NOT fix failures or change schemas. |
+| **Interoperable** | Eval results follow canonical report schema below. |
+| **Customizable** | Pass thresholds adapt to `TEAL_CONFIG.md` quality targets. |
+| **Extensible** | New eval suites added as suite definitions, not ad-hoc checks. |
+
+---
+
+## MICE/TEAL Alignment
+
+- Modular verification harness independent of any single builder instance.
+- TEAL-aware suites validate route correctness for configured topologies.
+
+---
+
+## Trigger Conditions
+
+Use when:
+
+- schema contracts changed
+- release candidate is being promoted
+- quality claims need objective proof
+- post-incident verification required
+- new agent or skill added to topology
+- regression suspected from failure pattern
+
+---
+
+## Inputs
+
+- schema files (`agent-state/MODULES/schemas/*`)
+- handoff/event samples (from `HANDOFF_HISTORY/`, `STATUS_EVENTS.ndjson`)
+- prior evaluation baseline (`agent-state/EVAL_BASELINE.json`)
+- `agent-state/TEAL_CONFIG.md` (for route topology)
+- `agent-state/QUALITY_GATES.md` (for pass criteria)
+
+---
+
+## Eval Suite Definition Schema
+
+Each eval suite is defined as:
+
+```markdown
+### SUITE-<NNN>: <name>
+- **Category:** <schema | routing | completeness | regression | behavioral>
+- **Target:** <what is being evaluated>
+- **Pass Threshold:** <numeric or boolean criterion>
+- **Inputs:** <what data is needed>
+- **Method:** <how evaluation is performed>
+- **Baseline:** <reference to prior result for regression comparison>
+```
+
+---
+
+## Standard Eval Suite Categories
+
+| Category | What It Tests | Example Checks |
+|---|---|---|
+| **Schema** | JSON schema validity of artifacts | All handoffs validate; all events validate; manifest validates |
+| **Routing** | Correct `from → to` transitions | Routes match TEAL topology; no orphan transitions |
+| **Completeness** | Required fields and evidence presence | Handoffs have evidence refs; decisions have rationale |
+| **Regression** | Comparison against baseline | No metrics worse than baseline; new failures not in baseline |
+| **Behavioral** | Agent protocol compliance | Clarity Protocol headers present; MICE boundaries respected |
+
+---
+
+## Confidence Scoring
+
+| Score | Label | Meaning |
+|---|---|---|
+| 95-100% | `HIGH` | All suites pass; no regression; full baseline coverage |
+| 80-94% | `MEDIUM` | Minor failures; no regression in critical suites |
+| 60-79% | `LOW` | Failures present; some regression detected |
+| < 60% | `CRITICAL` | Major failures; regression threshold exceeded; block release |
+
+---
+
+## Workflow — Mapped to Clarity Protocol
+
+### `[STATE_ANALYSIS]`
+1. Identify what triggered evaluation (schema change, release, post-incident).
+2. Load applicable eval suites from `EVAL_SUITES.md`.
+3. Load baseline from `EVAL_BASELINE.json` if available.
+
+### `[STRATEGY_SELECTOR]`
+4. Select suites relevant to trigger:
+   - Schema change → schema + routing suites.
+   - Release promotion → all suites.
+   - Post-incident → regression + behavioral suites.
+5. Plan execution order: schema first, then routing, then completeness, then regression.
+
+### `[EXECUTION_LOG]`
+6. Run each eval suite:
+   - Schema: validate sample payloads against schemas.
+   - Routing: check all transitions in `HANDOFF_HISTORY/` against `TEAL_CONFIG.md`.
+   - Completeness: verify required fields in all state artifacts.
+   - Regression: compare current metrics against baseline.
+   - Behavioral: check for Clarity Protocol headers and MICE compliance markers.
+7. Record pass/fail for each check with evidence.
+8. Compute confidence score.
+
+### `[ARTIFACT_UPDATE]`
+9. Write `agent-state/EVAL_REPORT.md`:
+
+```markdown
+# Evaluation Report
+Generated: <ISO8601>
+Trigger: <what caused this evaluation>
+Confidence: <score>% (<label>)
+
+## Suite Results
+| Suite | Category | Pass/Fail | Detail |
+|---|---|---|---|
+| SUITE-001 | schema | PASS/FAIL | <detail> |
+| ... | ... | ... | ... |
+
+## Regression Analysis
+| Metric | Baseline | Current | Delta | Status |
+|---|---|---|---|---|
+| Schema validity | <n>% | <n>% | <delta> | OK/REGRESSION |
+| ... | ... | ... | ... | ... |
+
+## Actionable Failures
+| Failure | Owner | Required Action |
+|---|---|---|
+| <failure> | <agent-role> | <what must happen> |
+
+## Residual Risk
+- <risks that remain even if all failures are fixed>
+```
+
+10. Update `agent-state/EVAL_BASELINE.json` with new baseline (if confidence >= MEDIUM).
+11. Write/update `agent-state/EVAL_SUITES.md` with suite definitions.
+12. Append evaluation evidence to `EVIDENCE_LOG.md`.
+
+### `[VERIFICATION]`
+13. Every suite produced a deterministic pass/fail result.
+14. Confidence score is mathematically consistent with suite results.
+15. Actionable failures have owner + required action.
+16. Regression analysis compares against actual baseline (not fabricated).
+
+---
+
+## Output Contract
+
+- `agent-state/EVAL_SUITES.md` (suite definitions)
+- `agent-state/EVAL_REPORT.md` (results, regression analysis, actionable failures)
+- `agent-state/EVAL_BASELINE.json` (updated baseline if criteria met)
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Correct Behavior |
+|---|---|
+| "All tests pass" without evidence | Every pass/fail has detail and evidence ref |
+| Regression comparison without baseline | First run establishes baseline; no regression claim possible |
+| Skipping behavioral suites | Autonomy behavior is tested, not just code |
+| Confidence score without math | Score = (passing checks / total checks) with category weights |
+| Fixing failures during evaluation | Report failures; do NOT fix them (route to owner) |
+
+---
+
+## Wrong-Stuff Protocol
+
+| Finding | Classification | Route To |
+|---|---|---|
+| Schema validation failure | `schema_violation` | `schema-forge` |
+| Routing topology mismatch | `routing_error` | `agent-ops` |
+| Missing evidence/completeness | `documentation_drift` | source agent |
+| Regression detected | `quality_regression` | `agent-qa` then `agent-builder` |
+| Behavioral non-compliance | `protocol_violation` | violating agent |
+
+---
+
+## Failure Policy
+
+If regression threshold is exceeded (confidence < 60%), emit `GATE_FAILED` and block release transition.
+Route each actionable failure to its owner via Wrong-Stuff Protocol.

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

@@ -0,0 +1,164 @@
+---
+name: handoff-lint
+description:
+  Enforce complete, schema-valid, evidence-linked handoffs before any module transition is persisted.
+---
+
+# Handoff Lint
+
+## Purpose
+
+Prevent malformed or context-losing transitions by applying strict handoff validation rules.
+A handoff without evidence is a broken telephone. This skill is the dial tone check.
+
+## Canonical Use Cases
+
+1. An agent is about to write `agent-state/HANDOFF.json` and needs a blocking validation pass first.
+2. A swarm handoff payload was generated after a complex routing cycle and someone needs to verify schema, evidence refs, and topology before persistence.
+3. Post-incident forensics found suspicious transitions and the team needs to replay handoff validity checks deterministically.
+
+---
+
+## MICE Boundaries
+
+| Rule | Enforcement |
+|---|---|
+| **Modular** | Validates handoff payloads; does NOT generate content or make routing decisions. |
+| **Interoperable** | Validates against canonical schemas in `agent-state/MODULES/schemas/`. |
+| **Customizable** | Lint rules adapt to handoff type (`swarm` vs `agent-state`). |
+| **Extensible** | New validation rules added as lint-rule rows, not prose. |
+
+---
+
+## MICE/TEAL Alignment
+
+- Interoperability guardrail for modular handoffs.
+- Enforces TEAL dependency integrity by blocking invalid route transitions.
+
+---
+
+## Trigger Conditions
+
+Use before writing:
+
+- `agent-state/HANDOFF.json`
+- `agent-state/HANDOFF_HISTORY/*.json`
+- `tasks/SWARM_HANDOFF.*.json`
+
+Also use when:
+
+- any agent emits a transition event
+- ops detects routing anomaly
+- post-incident handoff forensics
+
+---
+
+## Inputs
+
+- candidate handoff payload (JSON)
+- `agent-state/STATUS.md`
+- `agent-state/EVIDENCE_LOG.md`
+- schema files in `agent-state/MODULES/schemas/`
+- `agent-state/TEAL_CONFIG.md` (for valid route topology)
+
+---
+
+## Lint Rules Table
+
+| # | Rule | Check | On Fail |
+|---|---|---|---|
+| 1 | **Schema Validity** | Payload validates against applicable JSON schema | Reject with field-level errors |
+| 2 | **Required Fields** | `from`, `to`, `timestamp`, `context`, `evidence_refs` all present | Reject; list missing fields |
+| 3 | **Route Legitimacy** | `from` → `to` transition exists in `TEAL_CONFIG.md` topology | Reject; log invalid route |
+| 4 | **Evidence Freshness** | All `evidence_refs` point to entries < 24h old (or current sprint) | Warn if stale; reject if > 48h |
+| 5 | **Evidence Existence** | Every `evidence_ref` resolves to an actual entry in `EVIDENCE_LOG.md` | Reject; list dangling refs |
+| 6 | **Context Completeness** | `context.objective`, `context.blockers`, `context.artifacts` present | Reject; list missing context |
+| 7 | **Checksum Integrity** | If `checksum` field present, payload hash matches | Reject; integrity violation |
+| 8 | **Duplicate Detection** | No identical handoff in `HANDOFF_HISTORY/` within last 5 minutes | Warn; likely re-emission |
+| 9 | **Owner Consistency** | `from` matches current owner in `STATUS.md` | Warn; possible stale status |
+
+---
+
+## Workflow — Mapped to Clarity Protocol
+
+### `[STATE_ANALYSIS]`
+1. Receive candidate handoff payload.
+2. Determine handoff schema mode (`swarm` vs `agent-state`) from payload structure.
+3. Load applicable schema from `agent-state/MODULES/schemas/`.
+
+### `[STRATEGY_SELECTOR]`
+4. Plan lint pass: run all 9 rules in order.
+5. Classify each rule result as `PASS`, `WARN`, or `FAIL`.
+
+### `[EXECUTION_LOG]`
+6. Execute each lint rule against the payload.
+7. For schema validation: validate every field against JSON schema.
+8. For route legitimacy: check `TEAL_CONFIG.md` for valid `from → to` path.
+9. For evidence checks: resolve each `evidence_ref` to actual `EVIDENCE_LOG.md` entry.
+10. Collect all results.
+
+### `[ARTIFACT_UPDATE]`
+11. Produce lint report:
+
+```json
+{
+  "handoff_lint": {
+    "status": "PASS | WARN | FAIL",
+    "timestamp": "<ISO8601>",
+    "rules": [
+      {"id": 1, "name": "schema_validity", "status": "PASS|WARN|FAIL", "detail": "..."},
+      {"id": 2, "name": "required_fields", "status": "PASS|WARN|FAIL", "detail": "..."}
+    ],
+    "blocking_errors": [],
+    "warnings": []
+  }
+}
+```
+
+12. If PASS: allow handoff write to proceed.
+13. If FAIL: block handoff write; attach lint errors to `EVIDENCE_LOG.md`.
+
+### `[VERIFICATION]`
+14. Every lint rule produced a deterministic result.
+15. No FAIL-status handoff was written to disk.
+16. Lint report is attached to the evidence trail.
+
+---
+
+## Output Contract
+
+- On pass: `{ "status": "PASS", "rules": [...] }` — handoff write proceeds
+- On fail: `{ "status": "FAIL", "blocking_errors": [...] }` — handoff write blocked, `GATE_FAILED` emitted, lint errors appended to `EVIDENCE_LOG.md`
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Correct Behavior |
+|---|---|
+| Writing handoff without running lint | Every handoff write is lint-gated |
+| Ignoring WARN results | Warnings must be acknowledged; repeated warns escalate to FAIL |
+| Evidence refs to chat context | Evidence refs must point to durable state files, not ephemeral conversation |
+| "from: unknown" | `from` must match a real agent role in the registry |
+
+---
+
+## Wrong-Stuff Protocol
+
+| Finding | Classification | Route To |
+|---|---|---|
+| Schema violation | `schema_violation` | `schema-forge` |
+| Invalid route topology | `routing_error` | `agent-ops` |
+| Dangling evidence refs | `documentation_drift` | source agent that created handoff |
+| Stale evidence | `evidence_decay` | `agent-research` or source agent |
+
+---
+
+## Failure Policy
+
+On failure:
+
+- do not write handoff payload
+- emit `GATE_FAILED` with `failure_type: handoff_lint_failure`
+- attach lint errors to `EVIDENCE_LOG.md`
+- block downstream transition until all FAIL rules are resolved

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

@@ -0,0 +1,174 @@
+---
+name: incident-commander
+description:
+  Incident response protocol for autonomy failures: severity declaration, owner assignment, timeline reconstruction, and closure discipline.
+---
+
+# Incident Commander
+
+## Purpose
+
+Restore control during autonomy incidents while preserving forensic traceability and post-incident learning.
+An incident without a commander is chaos. An incident with a commander is a learning opportunity.
+
+## Canonical Use Cases
+
+1. Two or more consecutive gate failures indicate the normal recovery loop is not containing the issue.
+2. Multiple blockers or contradictory state files are stalling several agents and someone needs a single accountable incident owner plus timeline.
+3. Releases must remain paused after an incident until mitigation, blast radius, and closure evidence are explicit.
+
+---
+
+## MICE Boundaries
+
+| Rule | Enforcement |
+|---|---|
+| **Modular** | Coordinates incident response; does NOT fix code, rewrite specs, or change scope. |
+| **Interoperable** | Incident records follow canonical schema below; events validate against `STATUS_EVENT.schema.json`. |
+| **Customizable** | Severity thresholds adapt to `TEAL_CONFIG.md` pipeline criticality. |
+| **Extensible** | New incident categories added via schema, not ad-hoc prose. |
+
+---
+
+## MICE/TEAL Alignment
+
+- Modular incident layer that coordinates but does not rewrite role contracts.
+- TEAL-aware incident routing maps failures to the correct dependency owner.
+
+---
+
+## Trigger Conditions
+
+Use when:
+
+- repeated gate failures occur (>= 2 consecutive `GATE_FAILED` events)
+- blocker storms spread across dependencies (>= 3 active blockers)
+- reliability SLOs are breached
+- agent-ops circuit breaker has opened
+- contradictory state detected by state-auditor
+
+---
+
+## Inputs
+
+- `agent-state/STATUS_EVENTS.ndjson`
+- `agent-state/STATUS.md`
+- `agent-state/EVIDENCE_LOG.md`
+- `agent-state/RISKS.md`
+- open handoffs (current `HANDOFF.json`)
+- `agent-state/STATE_AUDIT_REPORT.md` (if available)
+
+---
+
+## Severity Classification Matrix
+
+| Severity | Criteria | Response SLA | Blast Radius |
+|---|---|---|---|
+| `SEV-1` | Objective failure; thesis invalidation; data loss; all pipelines blocked | Immediate; all other work paused | Full swarm |
+| `SEV-2` | Sprint-level delay; architecture change required; multi-agent blocker | Within current cycle | Multiple agents |
+| `SEV-3` | Single-agent blocker; quality regression detected | Within 2 cycles | Single agent + downstream |
+| `SEV-4` | Non-blocking quality concern; process deviation | Next available cycle | Informational |
+
+---
+
+## Incident Record Schema
+
+```markdown
+# INCIDENT-<NNN>
+- **Severity:** <SEV-1 | SEV-2 | SEV-3 | SEV-4>
+- **Declared:** <ISO8601>
+- **Status:** <open | investigating | mitigating | resolved | closed>
+- **Blast Radius:** <affected agents/modules>
+- **Owner:** <single accountable agent-role>
+- **Summary:** <1-2 sentence description>
+- **Root Cause:** <determined | investigating | unknown>
+- **Root Cause Detail:** <when determined>
+- **Trigger Event:** <STATUS_EVENTS.ndjson entry ref>
+- **Resolution:** <what fixed it>
+- **Closed:** <ISO8601 or N/A>
+- **Lessons:** <what changes to prevent recurrence>
+```
+
+---
+
+## Workflow — Mapped to Clarity Protocol
+
+### `[STATE_ANALYSIS]`
+1. Assess trigger condition. Determine severity using classification matrix.
+2. Identify blast radius: which agents/modules are affected or blocked.
+3. Read `STATUS_EVENTS.ndjson` for recent failure pattern.
+
+### `[STRATEGY_SELECTOR]`
+4. Assign single accountable owner (the agent closest to root cause).
+5. Choose response strategy:
+   - SEV-1/SEV-2: Immediate timeline reconstruction + corrective routing.
+   - SEV-3: Owner-routed fix with deadline.
+   - SEV-4: Log and monitor.
+6. Determine if circuit breaker should remain open or can be closed.
+
+### `[EXECUTION_LOG]`
+7. Declare incident ID and record in `global-state/INCIDENTS.md`.
+8. Build timeline from `STATUS_EVENTS.ndjson` and `EVIDENCE_LOG.md`:
+
+```markdown
+## Timeline: INCIDENT-<NNN>
+| Time | Event | Source | Detail |
+|---|---|---|---|
+| <ISO8601> | <event_type> | <agent> | <detail> |
+```
+
+9. Route corrective actions with due conditions to owner.
+10. For SEV-1/SEV-2: notify all affected agents via status event emission.
+
+### `[ARTIFACT_UPDATE]`
+11. Write/update `global-state/INCIDENTS.md` with incident record.
+12. Write `agent-state/INCIDENT_TIMELINE.md` with full timeline reconstruction.
+13. Append incident declaration and resolution to `EVIDENCE_LOG.md`.
+
+### `[VERIFICATION]`
+14. Owner has acknowledged and is working on corrective action.
+15. Timeline reconstruction is evidence-linked (every row has source ref).
+16. Blast radius assessment matches actual blocked agents.
+17. Severity classification is justified by criteria matrix.
+
+---
+
+## Closure Protocol
+
+No incident closure without ALL of:
+
+| # | Requirement | Verification |
+|---|---|---|
+| 1 | Owner sign-off | Owner confirms fix is deployed/applied |
+| 2 | Verified mitigation evidence | Evidence entry with before/after state |
+| 3 | Regression prevention | Action item to prevent recurrence recorded |
+| 4 | Post-incident review | Lessons documented in incident record |
+| 5 | Circuit breaker status | Confirmed closed or explicitly left open with reason |
+
+---
+
+## Output Contract
+
+- `global-state/INCIDENTS.md` (incident record with full lifecycle)
+- `agent-state/INCIDENT_TIMELINE.md` (forensic timeline)
+- closure entry in `agent-state/EVIDENCE_LOG.md`
+- status events: `INCIDENT_DECLARED`, `INCIDENT_MITIGATING`, `INCIDENT_RESOLVED`, `INCIDENT_CLOSED`
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Correct Behavior |
+|---|---|
+| Closing incident without lessons | Every closure includes prevention action |
+| Multiple owners | Single accountable owner; others are contributors |
+| Timeline from memory | Timeline from event logs and evidence only |
+| SEV-1 without pausing other work | SEV-1 means full swarm focuses on resolution |
+| Skipping post-incident review | No closure without review, even for SEV-4 |
+
+---
+
+## Failure Policy
+
+No incident closure without owner sign-off, verified mitigation evidence, and regression-prevention action item.
+If root cause cannot be determined, incident stays `open` with `investigating` status and escalation to next-higher severity after 2 cycles.

package/assets/.agents/skills/landing-review-watcher/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: landing-review-watcher
+description:
+  Watch review, CI, and landing loops for a change and use when the user needs a durable merge-readiness procedure rather than a one-off PR check.
+---
+
+# Landing Review Watcher
+
+## Purpose
+
+Make code-review and landing work observable, repeatable, and operator-safe.
+This skill does not own the release decision itself; it owns the watch loop that turns "waiting on review/CI/merge" into a deterministic procedure with artifacts.
+
+## Canonical Use Cases
+
+1. A change is open for review and someone needs a stable loop for comments, CI state, and merge blockers.
+2. A release candidate is waiting to land and the team wants a written handoff-safe landing procedure.
+3. A long-running review thread needs explicit acknowledgement, blocker tracking, and final landing evidence.
+
+## Inputs
+
+- active branch / change identifier
+- review comments or requested changes
+- CI status / failing checks
+- merge policy constraints
+- rollout or release artifact pointers when applicable
+
+## Workflow
+
+1. Define the watch target:
+   branch, PR, merge queue item, or review thread.
+2. Capture the current state:
+   reviewers, open comments, requested changes, CI state, merge policy, and known blockers.
+3. Classify the loop:
+   `reviewing`, `changes_requested`, `waiting_on_ci`, `ready_to_land`, or `blocked`.
+4. Write or update `agent-state/LANDING_REVIEW_WATCH.md` with:
+   owner, blockers, next checks, evidence refs, and explicit exit criteria.
+5. On every cycle, acknowledge new review input explicitly:
+   accepted, rebutted, deferred, or blocked with reason.
+6. If CI fails, route the failure to the responsible owner and record the remediation checkpoint.
+7. If merge is safe, hand off to [$release-sentry](/Users/voy/Desktop/dev-ace/.agents/skills/release-sentry/SKILL.md) for the actual approve/hold decision.
+8. After landing, record the final result, landing timestamp, and rollback pointer if one exists.
+
+## Outputs
+
+- `agent-state/LANDING_REVIEW_WATCH.md`
+- updated evidence pointer in `agent-state/EVIDENCE_LOG.md`
+- optional release routing note to `release-sentry`
+
+## Validation
+
+- Verify every open reviewer/blocker has an owner or explicit waiting reason.
+- Verify CI state is current and tied to a specific run/check reference.
+- Verify landing state is one of:
+  `reviewing`, `changes_requested`, `waiting_on_ci`, `ready_to_land`, `blocked`, `landed`.
+- Verify the watch artifact names the next action instead of only summarizing history.
+
+## Compatibility
+
+- `SKILL.md` is the portable source of truth for this workflow.
+- The skill remains useful without provider-specific PR adapters; branch names, plain-text review notes, and CI summaries are enough.
+- Client overlays may add launch shortcuts, but must not redefine the watch-state model.
+
+## Failure Policy
+
+- Do not claim a change is ready to land if requested changes or failing CI remain unresolved.
+- Do not collapse review feedback into a vague summary; every new blocker or accepted fix must be acknowledged explicitly.
+- If the change cannot be tied to a concrete watch target, stop and create the target definition first.