@ludecker/aaac 1.1.5 → 1.2.0

package/templates/cursor/skills/shared/remediation/orchestrator/contract.yaml

@@ -0,0 +1,116 @@
+version: 1
+command: remediate-app
+orchestrator: remediate-app
+description: Campaign loop — Fallow, check swarm, fix waves, regression gates, debt sweep, satisfaction
+
+phases:
+  - campaign_init
+  - scan
+  - check_swarm
+  - plan_waves
+  - execute
+  - debt_sweep
+  - satisfaction_gate
+  - report
+
+requires:
+  - remediation
+  - discovery
+  - check
+  - execution
+  - testing
+  - verification
+  - reporting
+
+invariants:
+  exit_3_is_continue: true
+  wave_gate_mode: regression
+  debt_gate_mode: strict
+  validate_before_report: true
+
+blocking_gates:
+  - verify_wave_regression_after_each_fix
+  - remediator_subloop_per_wave
+  - debt_sweep_strict_mandatory
+  - satisfaction_threshold
+
+remediator:
+  gate_script: remediation/remediator-gate.mjs
+  debt_sweep_script: remediation/debt-sweep-gate.mjs
+  validate_script: remediation/validate-campaign-complete.mjs
+  baseline_script: remediation/capture-verify-baseline.mjs
+  wave_snapshot_script: remediation/capture-wave-snapshot.mjs
+  classify_script: remediation/classify-verify-failure.mjs
+  dispatch_rules: remediation/dispatch-rules.json
+  agent: agents/remediation-remediator.md
+  exit_codes:
+    promote: 0
+    block: 1
+    runtime_error: 2
+    remediate_required: 3
+  defaults:
+    max_remediator_attempts_per_wave: 3
+    max_remediator_attempts_per_debt_round: 3
+    max_debt_sweep_rounds: 10
+    wave_gate_mode: regression
+
+artifacts:
+  campaign_init: [artifacts/campaign.json, artifacts/verify_baseline.json, artifacts/autonomous_bootstrap.json]
+  scan: [artifacts/fallow_scan.json, artifacts/fallow_dupes.json, artifacts/fallow_health.json, artifacts/fallow_scan_bundle.json, artifacts/fallow_classification.json]
+  check_swarm: [artifacts/check_synthesis.md, artifacts/dispatch-queue.yaml, artifacts/check_app_validate.yaml, artifacts/check_architecture_fitness.yaml, artifacts/protected_paths.yaml, artifacts/check_swarm_merge.json]
+  plan_waves: [artifacts/plan_waves.yaml]
+  execute: [artifacts/execute_waves.yaml]
+  debt_sweep: [artifacts/debt_sweep.json, artifacts/verify_debt.json]
+  satisfaction_gate: [artifacts/satisfaction.json, artifacts/satisfaction_loop_gate.json]
+  report: [artifacts/report.md]
+
+scripts:
+  init: remediation/init-campaign.mjs
+  baseline: remediation/capture-verify-baseline.mjs
+  wave_snapshot: remediation/capture-wave-snapshot.mjs
+  fallow_scan: remediation/fallow-scan.mjs
+  verify: remediation/verify-remediation-iteration.mjs
+  remediator_gate: remediation/remediator-gate.mjs
+  debt_sweep: remediation/debt-sweep-gate.mjs
+  satisfaction_loop: remediation/satisfaction-loop-gate.mjs
+  repair_fallow_start: remediation/repair-fallow-start-baseline.mjs
+  validate_complete: remediation/validate-campaign-complete.mjs
+  classify_failure: remediation/classify-verify-failure.mjs
+  satisfaction: remediation/compute-satisfaction.mjs
+  journal: remediation/record-iteration-step.mjs
+  bootstrap_autonomous: remediation/bootstrap-autonomous.mjs
+  runner: remediation/remediation-runner.mjs
+  runner_health: remediation/runner-health-check.mjs
+
+satisfaction_weights:
+  fallow_dead_code: 0.25
+  fallow_dupes: 0.10
+  fallow_health: 0.05
+  structural_clean: 0.15
+  unit_tests: 0.15
+  build: 0.10
+  e2e: 0.20
+
+defaults:
+  max_iterations: 5
+  max_waves_per_iteration: 3
+  max_remediator_attempts_per_wave: 3
+  max_remediator_attempts_per_debt_round: 3
+  max_debt_sweep_rounds: 10
+  wave_gate_mode: regression
+  satisfaction_threshold: 85
+  scope: whole-repo
+  autonomous_max_iterations: 10
+  autonomous_satisfaction_threshold: 100
+
+autonomous:
+  enabled_when:
+    - intent_token: autonomous
+    - satisfaction_threshold_gte: 100
+    - max_iterations_gte: 10
+  disabled_when:
+    - intent_token: manual
+  skill: skills/shared/remediation/babysit/SKILL.md
+  bootstrap_script: remediation/bootstrap-autonomous.mjs
+  runner_script: remediation/remediation-runner.mjs
+  health_script: remediation/runner-health-check.mjs

package/templates/cursor/skills/shared/test-authoring/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: shared-test-authoring
+description: >-
+  Phase test_execute — separate Task agent authors tests after execute.
+  Parent must not write test files. Not user-facing.
+disable-model-invocation: true
+---
+
+# Test authoring (test_execute phase)
+
+## When
+
+After `execute`, before `verify`, on **create / update / fix / remove** (mutating verbs).
+
+**Hard rule:** Parent orchestrator must **not** Write/StrReplace test paths in `execute` — hooks deny them. Only `test_execute` phase (or test-author Task subagent in that phase) may author tests.
+
+## Swarm (mandatory)
+
+Launch **1** `Task` subagent in **one message**:
+
+| Agent spec | `subagent_type` | Role |
+|------------|-----------------|------|
+| [test-author.md](../../../agents/test-author.md) | `generalPurpose` | Author tests from plan |
+
+Every Task prompt **must** include [_task-prompt-policy.md](../_task-prompt-policy.md) plus: Run `artifacts/plan.yaml` path, list of files changed in execute, domain inventory test paths.
+
+## Plan input
+
+Run `artifacts.plan` must include:
+
+```yaml
+tests_to_add:
+  - behavior: "<from requirement_map>"
+    kind: unit | integration | e2e
+    target_path: "<package test file path>"
+```
+
+If `tests_to_add` is empty and no tests are required, record on artifact:
+
+```yaml
+tests_to_add: []
+skipped_reason: "<why no new tests — e.g. docs-only change>"
+```
+
+Store merged result on Run `artifacts/test_plan.yaml` before advancing.
+
+## Output
+
+```yaml
+files_written: ["<test paths>"]
+behaviors_covered: ["<strings>"]
+gaps: ["<untested behaviors>"]
+author_agent: test-author
+```
+
+## Fail
+
+Do not advance if tests were required by plan but `files_written` is empty.

package/templates/cursor/skills/shared/testing/SKILL.md

@@ -12,6 +12,8 @@ disable-model-invocation: true
 
 Phase `verify` (and `test_only` orchestrators). On **fix** paths, run fix verify swarm **before** declaring tests complete.
 
+**Agent separation:** Test **authorship** happens in `test_execute` ([test-authoring](../test-authoring/SKILL.md)). This phase **runs** tests only — parent and subagents must not author new test files here.
+
 ## Standard steps
 
 1. Run tests from domain inventory relevant to change
@@ -28,6 +30,10 @@ Phase `verify` (and `test_only` orchestrators). On **fix** paths, run fix verify
 
 After unit tests, launch **3 parallel** `Task` subagents in **one message**. Each prompt **must** include [_task-prompt-policy.md](../_task-prompt-policy.md) and investigation artifact paths.
 
+## Verify swarm (mandatory on all mutating verbs)
+
+After `test_execute`, launch **3 parallel** `Task` subagents in **one message** (same roster as fix verify when on fix paths; on create/update use run + static checks):
+
 | # | Agent spec | `subagent_type` | Role |
 |---|------------|-----------------|------|
 | 1 | [fix-repro-verify.md](../../../agents/fix-repro-verify.md) | `shell` | Re-run repro steps from investigation artifact |

package/templates/cursor/skills/shared/verbs/create/orchestrator/SKILL.md

@@ -30,9 +30,11 @@ Lifecycle: graph `verb_runtime.create` (work + gates on Run)
 9. **fitness_functions** — [fitness-functions](../../fitness-functions/SKILL.md)
 10. **rollback** — [rollback](../../rollback/SKILL.md) when object maturity protected or impact high
 11. **execute** — [execution](../../execution/SKILL.md) + object_skills + module-authoring when listed
-12. **verify** — [testing](../../testing/SKILL.md) + [verification](../../verification/SKILL.md)
-13. **sync_inventory** — when domain inventory exists and execute ran
-14. **report** — [reporting](../../reporting/SKILL.md)
+12. **test_execute** — [test-authoring](../../test-authoring/SKILL.md) — **1** test-author Task agent; parent must not write tests
+13. **verify** — [testing](../../testing/SKILL.md) + [verification](../../verification/SKILL.md) — **3** verify subagents (all mutating verbs)
+14. **review_swarm** — [implementation-review](../../implementation-review/SKILL.md) — **3** readonly reviewers; block on critical findings
+15. **sync_inventory** — when domain inventory exists and execute ran
+16. **report** — [reporting](../../reporting/SKILL.md)
 
 Domain slugs with graph resolver use domain orchestrator instead (e.g. `create-feature` → `create-feature-by-slug`).
 

package/templates/cursor/skills/shared/verbs/fix/orchestrator/SKILL.md

@@ -29,9 +29,11 @@ Lifecycle: graph `verb_runtime.fix` or `command_workflows.fix-module` on Run
 10. **fitness_functions** — [fitness-functions](../../fitness-functions/SKILL.md)
 11. **rollback** — [rollback](../../rollback/SKILL.md) when maturity protected/critical or blast_radius ≥ medium
 12. **execute** — [execution](../../execution/SKILL.md)
-13. **verify** — [testing](../../testing/SKILL.md) fix verify swarm + [verification](../../verification/SKILL.md)
-14. **sync_inventory** — when domain inventory exists
-15. **report** — [reporting](../../reporting/SKILL.md)
+13. **test_execute** — [test-authoring](../../test-authoring/SKILL.md) — **1** test-author Task agent
+14. **verify** — [testing](../../testing/SKILL.md) fix verify swarm + [verification](../../verification/SKILL.md) — **3** subagents
+15. **review_swarm** — [implementation-review](../../implementation-review/SKILL.md) — **3** readonly reviewers
+16. **sync_inventory** — when domain inventory exists
+17. **report** — [reporting](../../reporting/SKILL.md)
 
 ## Swarm anti-patterns (hard fail)
 

package/templates/cursor/skills/shared/verbs/update/orchestrator/SKILL.md

@@ -25,9 +25,11 @@ Lifecycle: graph `verb_runtime.update` (work + gates on Run)
 9. **fitness_functions** — [fitness-functions](../../fitness-functions/SKILL.md)
 10. **rollback** — [rollback](../../rollback/SKILL.md) when maturity protected or blast_radius high
 11. **execute** — [execution](../../execution/SKILL.md); `design_mode` when component + design resolver
-12. **verify** — [testing](../../testing/SKILL.md) + [verification](../../verification/SKILL.md)
-13. **sync_inventory**
-14. **report** — [reporting](../../reporting/SKILL.md)
+12. **test_execute** — [test-authoring](../../test-authoring/SKILL.md) — **1** test-author Task agent
+13. **verify** — [testing](../../testing/SKILL.md) + [verification](../../verification/SKILL.md) — **3** verify subagents
+14. **review_swarm** — [implementation-review](../../implementation-review/SKILL.md) — **3** readonly reviewers
+15. **sync_inventory**
+16. **report** — [reporting](../../reporting/SKILL.md)
 
 Intent `Sync inventory only` → inventory sync only, no execution.
 

package/templates/cursor/skills/shared/verification/SKILL.md

@@ -10,12 +10,14 @@ disable-model-invocation: true
 
 ## When
 
-After `testing`. Before `report`.
+After `testing`. Before `review_swarm` (mutating verbs) or `report`.
+
+**Agent separation:** Intent and contract checks here are orchestrator duties. Architecture/doc conformance review is **only** in [implementation-review](../implementation-review/SKILL.md) — not the execute agent.
 
 ## Checks
 
-- **App build gate** (create / update / fix, when `project.config.json` `verify.enabled`): `artifacts/verify.yaml` from [verify-website-build.mjs](../../../aaac/scripts/run-engine/verify-website-build.mjs)
-- **E2E smoke** (optional): launch [playwright-check-run](../../../agents/playwright-check-run.md) when project defines Playwright targets; set `PLAYWRIGHT_BASE_URL` for public-route smoke
+- **Website build gate** (create / update / fix): `artifacts/verify.yaml` from [verify-website-build.mjs](../../../aaac/scripts/run-engine/verify-website-build.mjs) — static assets in `index.html` must exist; `pnpm --filter @ludecker/website build` must pass
+- **Playwright verb checks** (create / update / fix): launch [playwright-check-run](../../../agents/playwright-check-run.md) — `pnpm --filter @ludecker/aaac test:e2e` must pass; set `PLAYWRIGHT_BASE_URL` for public-route smoke
 - Run artifact `artifacts.testing.repro_status` is **fixed** or **partial** with documented follow-up (fix paths)
 - Orchestrator `contract.yaml` `success_criteria`
 - Graph `object_skills` / `object_skill_verbs` skills were loaded for command object + verb

package/templates/docs/agentic_architecture.md

@@ -10,97 +10,79 @@ You express intent; the architecture determines execution.
 
 ## Part 1 — For everyone
 
+### Get started
+
+1. **Install** — `npx @ludecker/aaac@latest init` (or `pnpm dlx @ludecker/aaac@latest init --yes`)
+2. **Open in Cursor** — Settings → **Hooks** → enable → restart Cursor
+3. **Run a command** — graph and slash commands are already generated; no manual `generate` step
+
+`init` also writes **`.cursor/aaac/state/install-sweep-report.md`** — a read-only inventory of project docs, Cursor rules, and AAAC framework markdown, with recommendations only (no merges).
+
+Optional later: add **domain slugs** and `.cursor/domains/<slug>/` for project-specific routing (Part 2).
+
 ### What you do
 
 > **Call a command. The system figures out the rest.**
 
-Ask: *What do I want?* Then type:
-
 ```text
-/<verb>-<object> <domain> "<intent>"
+/<verb>-<object> [domain] "<intent>"
 ```
 
 | Part | Meaning | Example |
 |------|---------|---------|
 | Command | Kind of work | `update-module` |
-| Domain | Which area (optional until you add domains) | `payments` |
-| Intent | Goal in plain language | `"Add idempotency key to webhook handler"` |
-
-### Command matrix (ships with every install)
+| Domain | Optional bounded area | `payments` (only when your overlay defines slug resolvers) |
+| Intent | Goal in plain language | `"Add webhook retry with idempotency key"` |
 
-AAAC generates ~130 commands from **8 verbs × 12 objects**:
-
-| Verb | Meaning | Example |
-|------|---------|---------|
-| `create` | Add something new | `/create-module api "Add rate limiter"` |
-| `update` | Change existing | `/update-component ui "Extract Button variants"` |
-| `fix` | Repair broken behavior | `/fix-module auth "Session expires on refresh"` |
-| `review` | Readonly quality check | `/review-architecture system "Check layer boundaries"` |
-| `check` | Readonly capability trace | `/check-module api "Can we add OAuth?"` |
-| `test` | Run verification | `/test-module api "Contract tests for webhooks"` |
-| `release` | Ship to production | `/release-app production "Ship v2.1.0"` |
-| `remove` | Delete safely | `/remove-module legacy "Drop v1 export path"` |
+Without a domain overlay, commands route to **generic verb orchestrators** (`verb-create`, `verb-update`, `verb-fix`, …) — enough to create, fix, check, and review work in any repo.
 
-**Exception commands** (dedicated orchestrators):
+### Common commands
 
 | Command | When to use |
 |---------|-------------|
-| `update-doc` | Update architecture documentation (no code) |
-| `review-module` | Quality/architecture review (no code) |
+| `create-module` | Add a new bounded module or package |
+| `update-module` | Change existing module behavior |
+| `fix-module` / `fix-bug` | Repair something broken (fix-bug: domain optional) |
+| `check-module` | Validate or inspect (readonly) |
+| `review-module` | Architecture / quality review (readonly) |
 | `review-incident` | Investigate production or deploy issue |
-| `test-function` | Test a user journey end-to-end |
-| `release-app` | Phased release swarm (git → deploy) |
-| `fix-module` / `fix-bug` | Full fix swarm — domain optional until you add resolvers |
-
-### Out of the box — no setup after install
-
-Install copies everything you need. Open the project in Cursor and run commands.
-
-- ~130 slash commands and the full shared pipeline (discover → plan → execute → verify → report)
-- Generic `master_rules.md`, `ui_design.md`, `project_context.md`, and `architecture.md` in your docs folder — **already filled in**, not empty stubs
-- Hook scripts and Run lifecycle under `.cursor/`
-- Generic capability registry (shared skills only)
-- **No** project domains required; **no** app build gate until you opt in (`verify.enabled: false` in `project.config.json`)
-
-You do **not** need to enable hooks manually, write rules, add domains, or configure a stack before your first command.
-
-### Optional — when you want more (any stack)
-
-1. Fill in `docs/project_context.md` with your repo layout and SSOT anchors; extend `docs/master_rules.md` and `docs/architecture.md` when needed
-2. Add `domains/<slug>/update/` (orchestrator + inventory) — see Part 2
-3. Extend `graph.project.yaml` with resolvers and project skills
-4. Enable verify in `project.config.json` when you have a web app to gate:
-
-```json
-{
-  "verify": {
-    "enabled": true,
-    "app_root": "apps/web",
-    "index_html": "apps/web/index.html",
-    "build": { "command": "pnpm", "args": ["--filter", "web", "build"] }
-  }
-}
-```
+| `test-module` / `test-function` | Verify behavior |
+| `update-doc` | Update architecture documentation (no code) |
+| `release-app` | Phased release swarm (git push + deploy steps) |
+| `remediate-app` | Long-running tech-debt campaign (Fallow + fix waves + satisfaction loop) |
+
+See [`.cursor/aaac/ontology.md`](../.cursor/aaac/ontology.md) for the full verb × object matrix (~130 commands).
 
 ### Examples (generic)
 
 ```text
-/create-module billing "Add invoice PDF export"
-/update-component ui "Tokenize spacing scale"
-/fix-module api "Webhook signature validation fails on chunked bodies"
-/review-module billing "Check SSOT for tax rates"
-/test-function checkout "Guest can complete purchase"
-/release-app staging "Deploy with migration"
-/update-doc architecture "Document event bus boundaries"
+/create-module api "Add health check endpoint"
+/update-module auth "Refresh session TTL configuration"
+/fix-bug payments "Webhook handler drops events on retry"
+/check-module billing "Confirm idempotency on duplicate events"
+/review-module core "Check layer boundaries and module size budgets"
+/test-function checkout "Verify cart → pay → confirmation journey"
+/update-doc architecture "Document service boundaries"
+/release-app production "Ship with typecheck and smoke test"
 ```
 
-### What you should not need to know
+### Deprecated (still work one release)
 
-skill, agent, subagent, tool, workflow, graph, orchestrator — infrastructure only.
+| Old | New |
+|-----|-----|
+| `/ship-ludecker` | `/release-app` |
+| `/module-update` | `/update-module` |
+| `/architecture` | `/update-doc` |
+| `/swarm-check` | `/review-incident` or `/fix-bug` |
+| `/refactor` | `/review-module` |
+
+### Reference: [Lüdecker](https://ludecker.com) (optional domain overlay)
+
+The [Lüdecker monorepo](https://github.com/eriklydecker/ludecker) adds slug resolvers (`cms`, `ui`, `database`, `aaac`) and domain orchestrators under `.cursor/domains/`. That pattern is **not** required for a fresh install — copy it when you want bounded-context routing like `/update-module cms "…"`.
 
-### Reference implementation
+### What you should not need to know
 
-[Lüdecker](https://ludecker.com) dogfoods AAAC with `cms`, `ui`, `database`, and `aaac` domains. That overlay lives in the Lüdecker repo — not in the generic npm template.
+skill, agent, subagent, tool, workflow, graph, orchestrator — infrastructure only.
 
 ---
 
@@ -130,7 +112,7 @@ Knowledge Layer     → docs/
 | Lifecycle | **Work** phase configuration |
 | Gate stacks | **Approval** checkpoints |
 | Run | Primary execution object; decisions, log, checkpoints |
-| Domain orchestrators | Domain coordination (you add these) |
+| Domain orchestrators | Domain coordination |
 | Shared pipeline skills | Phase execution |
 | Capability registry | object → capability → provider |
 | Object skills | Skill-type providers |
@@ -149,7 +131,7 @@ Intent → Command → Execution Graph → Result
 
 **Execution graph** = orchestrator + skills + agents + tools + rules + documentation.
 
-**SSOT:** [`.cursor/aaac/graph.yaml`](../.cursor/aaac/graph.yaml) (generated — edit `graph.project.yaml` instead)
+**SSOT:** [`.cursor/aaac/graph.yaml`](../.cursor/aaac/graph.yaml)
 
 **Dispatch procedure:** [`.cursor/aaac/dispatch.md`](../.cursor/aaac/dispatch.md)
 
@@ -158,32 +140,16 @@ Intent → Command → Execution Graph → Result
 ```text
 .cursor/
   commands/          # thin routers (public)
-  aaac/
-    graph.project.yaml # your overlay (resolvers, orchestrators)
-    graph.yaml         # generated wiring
+  aaac/graph.yaml    # wiring (private OS)
   domains/<slug>/update/
     orchestrator/    # what happens
     inventory/       # what exists
-  skills/shared/     # framework pipeline
-  skills/<project>/  # your object-capability skills (optional)
+  skills/shared/     # framework (discovery, planning, execution, …)
+  skills/<project>/  # optional project-specific object skills
   agents/            # subagent prompt specs
   policies/          # rules all skills inherit
 ```
 
-### Generic kernel vs project overlay
-
-| Layer | Location | Owner |
-|-------|----------|-------|
-| Generic kernel | `@ludecker/aaac` npm templates | Package maintainers |
-| Project overlay | `.cursor/aaac/graph.project.yaml`, `ontology.json`, `project.config.json` | Your repo |
-| Domains | `.cursor/domains/<slug>/` | Your repo |
-
-Regenerate after ontology or overlay edits:
-
-```bash
-npx @ludecker/aaac@latest generate
-```
-
 ### Orchestrator vs inventory
 
 | | Orchestrator | Inventory |
@@ -191,49 +157,155 @@ npx @ludecker/aaac@latest generate
 | Question | What should happen? | What exists? |
 | Updates when | Workflow changes | After every code-changing `update-module` |
 
+Inventory documents constraints and file maps. **Dependency reasoning** uses [`.cursor/aaac/dependencies.yaml`](../.cursor/aaac/dependencies.yaml) via the `dependency_graph` phase — not inventory alone.
+
 ### Execution determinism (create / update / fix)
 
+Commands define *what* to load; **work lifecycle** defines phases of work; **gate stacks** define approval checkpoints; the **Run** holds state and observability.
+
+**Mature stack (composed on Run):**
+
+```text
+Policies → Ontology → Graph → Create Run
+→ Work: Discovery → Investigation → Planning
+→ Gates: Validation → Impact → Deps → Fitness → Rollback
+→ Work: Execute → Test execute → Verify → Review swarm → Report
+```
+
+**Agent separation (create / update / fix):** production code in `execute`; tests in `test_execute` (separate test-author agent); readonly review swarm before report. Hooks enforce path scopes via `enforcement.json` `phase_edit_scopes`.
+
 **Work lifecycles** (SSOT: [`.cursor/aaac/lifecycle/lifecycle.json`](../.cursor/aaac/lifecycle/lifecycle.json)):
 
 | Verb | Work | Gate stack |
 |------|------|------------|
-| create | discover → investigate_lite → plan → execute → verify → report | pre_execute |
+| create | discover → investigate_lite → plan → execute → test_execute → verify → review_swarm → report | pre_execute |
 | update | same | pre_execute |
-| fix | discover → investigate_swarm → root_cause → plan → execute → verify → report | pre_execute |
+| fix | discover → investigate_swarm → root_cause → plan → execute → test_execute → verify → review_swarm → report | pre_execute |
 | release | execute → verify → report | release |
 
-**Gate stacks** (SSOT: [`.cursor/aaac/governance/gates.json`](../.cursor/aaac/governance/gates.json))
+**Gate stacks** (SSOT: [`.cursor/aaac/governance/gates.json`](../.cursor/aaac/governance/gates.json)) — approval, not work.
+
+Composed runtime in graph `verb_runtime`. Human approval at gate boundaries: Run `status: blocked`, `awaiting_approval: true`.
+
+**Confidence gates** — before execute, if any score is below threshold → `STOP, REQUEST CLARIFICATION`:
+
+| Dimension | Minimum |
+|-----------|---------|
+| architecture | 0.9 |
+| requirements | 0.8 |
+| scope | 0.8 |
+
+**Object maturity** — harder objects require more phases:
+
+| Level | Objects (examples) | Extra requirements |
+|-------|-------------------|-------------------|
+| protected | schema, migration, architecture | impact + deps + rollback |
+| critical | module, integration, app | impact + deps |
+| stable | feature, workflow | impact on fix |
+| evolving | component, function | lifecycle only |
+
+**Fitness functions** — [`.cursor/aaac/fitness-functions.yaml`](../.cursor/aaac/fitness-functions.yaml): api_first, design_system, accessibility, security, layer_boundaries, performance. Scored `pass` / `warning` / `fail` before execute.
+
+Lifecycle reference: [`.cursor/skills/shared/verbs/_lifecycle.md`](../.cursor/skills/shared/verbs/_lifecycle.md)
+
+### Fix swarm (`/fix-module`, `/fix-bug`, `fix_mode`)
+
+Same rigor as `write-article` research — parallel Task subagents, one message per wave.
+
+| Phase | Agent specs | Count |
+|-------|-------------|-------|
+| discover | discovery-inventory, discovery-boundaries, discovery-ssot | 4–6 |
+| investigate_swarm | fix-repro, fix-code-path, fix-recent-changes, fix-test-failures, fix-regression-scope, fix-runtime-evidence, fix-inventory-confirm | **7** |
+| root_cause | parent + optional fix-hypothesis-validate | 0–1 |
+| verify | fix-repro-verify, unit-test-run, fallow-check-changed | **3** (all mutating verbs) |
+| test_execute | test-author | **1** |
+| review_swarm | boundary-review, doc-conformance, implementation-review | **3** |
+
+Skills: [investigation/SKILL.md](../.cursor/skills/shared/investigation/SKILL.md), [testing/SKILL.md](../.cursor/skills/shared/testing/SKILL.md), [test-authoring/SKILL.md](../.cursor/skills/shared/test-authoring/SKILL.md), [implementation-review/SKILL.md](../.cursor/skills/shared/implementation-review/SKILL.md).  
+Contracts: [fix-module.yaml](../.cursor/aaac/contracts/commands/fix-module.yaml), [fix-bug.yaml](../.cursor/aaac/contracts/commands/fix-bug.yaml).
+
+Resolver: `fix-domain-by-slug` (`fix-module`) and `fix-bug-by-slug` → `cms-fix-bug` | `ui-fix-bug` | `database-fix-bug` | `aaac-fix-bug`.
 
 ### Capability registry
 
 Objects declare capabilities in ontology; providers resolve from [`.cursor/aaac/capabilities/registry.json`](../.cursor/aaac/capabilities/registry.json):
 
 ```text
-object → capability → provider (skill | mcp)
+object → capability → provider (skill | mcp | expert)
+```
+
+Graph `object_skills` includes skill-type providers only. MCP providers (e.g. `supabase-mcp` on `database-design`) are recorded on the Run.
+
+**Capability lifecycle (evidence-driven):** State belongs to the **capability**, not the provider. After each completed Run, `capability-evidence.mjs` aggregates per-run evidence into [`.cursor/aaac/state/capability-stats.json`](../.cursor/aaac/state/capability-stats.json) and evaluates deterministic promotion using [`.cursor/aaac/capabilities/promotion-rules.json`](../.cursor/aaac/capabilities/promotion-rules.json):
+
+```text
+experimental → validated → trusted → canonical → deprecated
 ```
 
-Replace generic shared-skill providers with project skills as you mature.
+Promotion uses accumulated metrics: `invocations`, `success_rate`, `rollback_rate`, `gate_failure_rate`, `avg_fitness`. `canonical` requires `manual_approval` (human override on the capability entry). Providers contribute evidence; governance changes state.
+
+**Runtime behavior:** At dispatch and before `execute`, `promotion-rules.json` `runtime` section is evaluated — `deprecated` blocks execute; `experimental` on `critical`/`protected` objects requires user approval; low `success_rate` or `avg_fitness` triggers approval. Set `capability_runtime_approved: true` on the Run after user approves.
 
 ### Run (primary execution object)
 
 **SSOT:** [`.cursor/aaac/run/schema.json`](../.cursor/aaac/run/schema.json), [`.cursor/aaac/run/RUN.md`](../.cursor/aaac/run/RUN.md)
 
+Every command executes within a Run at `state/runs/{run_id}/run.json`:
+
+| Field | Purpose |
+|-------|---------|
+| `phase`, `pending`, `completed` | Where we are |
+| `decisions[]` | Why routes and gates |
+| `log[]` | Phase events |
+| `checkpoints[]` | Resume points |
+| `artifacts{}` | Plan, impact, report, … |
+| `awaiting_approval` | Human gate approval |
+
+Observability: [`.cursor/aaac/observability/telemetry.yaml`](../.cursor/aaac/observability/telemetry.yaml) — all telemetry on Run, no standalone logs.
+
+### Contracts
+
+Command contracts: [`.cursor/aaac/contracts/commands/`](../.cursor/aaac/contracts/commands/). Skill contracts: [`.cursor/aaac/contracts/skills/`](../.cursor/aaac/contracts/skills/). Schema: [`.cursor/aaac/contract-schema.md`](../.cursor/aaac/contract-schema.md)
+
+### Implementation governance
+
+Not a slash command. Loaded by `shared/execution` on code changes:
+
+[`.cursor/skills/shared/governance/implementation/SKILL.md`](../.cursor/skills/shared/governance/implementation/SKILL.md)
+
 ### Adding a product domain
 
 1. Add `domains/<slug>/update/` (inventory + orchestrator)
-2. Add resolver entries to `graph.project.yaml` — **no new command shape**
-3. Regenerate: `npx @ludecker/aaac@latest generate`
+2. Add slug to `graph.yaml` resolvers — **no new command shape**
+3. Regenerate: `node .cursor/aaac/generate-graph.mjs && node .cursor/aaac/generate-commands.mjs`
+
+### Contracts
 
-See [module-authoring/SKILL.md](../.cursor/skills/shared/module-authoring/SKILL.md).
+Plugins may include `contract.yaml` beside `SKILL.md`. Central contracts: [`.cursor/aaac/contracts/`](../.cursor/aaac/contracts/). Schema: [`.cursor/aaac/contract-schema.md`](../.cursor/aaac/contract-schema.md)
 
 ### Release swarm (`release-app`)
 
-Wave 1: `release-git` (blocking). Add deploy agents in your overlay (e.g. `release-render`, `release-k8s`) — generic template ships git only.
+Expert subagents run in **waves**, not one monolithic agent:
+
+| Wave | Agents | Notes |
+|------|--------|-------|
+| 0 | Preflight typecheck (optional) | From intent, e.g. "with tests" |
+| 1 | `release-git` | **Blocking** — must return `commit_sha` before wave 2 |
+| 2 | `release-render` | Poll `ludecker-website` until `live`; smoke-check `/` |
+
+Wiring: `graph.yaml` agents `release-*`. Orchestrator: [platform-release/orchestrator](../.cursor/skills/shared/platform-release/orchestrator/SKILL.md). DAG: [platform-release/SKILL.md](../.cursor/skills/shared/platform-release/SKILL.md).
 
 ### Regenerating commands
 
 ```bash
-npx @ludecker/aaac@latest generate
+pnpm aaac:generate
+```
+
+Or:
+
+```bash
+node .cursor/aaac/generate-graph.mjs
+node .cursor/aaac/generate-commands.mjs
 ```
 
 Ontology reference: [`.cursor/aaac/ontology.md`](../.cursor/aaac/ontology.md)