@ludecker/aaac 1.1.4 → 1.1.6

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,78 @@ 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) |
+
+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 +111,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 +130,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 +139,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 +156,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)