@ludecker/aaac 1.0.0 → 1.1.1

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

@@ -1,46 +1,119 @@
 ---
 name: shared-investigation
 description: >-
-  Deep investigation for fix paths and review-incident. Not user-facing.
+  Deep fix investigation swarm — mandatory parallel subagents for fix paths.
+  Incident subset for review-incident. Not user-facing.
 disable-model-invocation: true
 ---
 
 # Shared investigation (deep)
 
-**When:** fix verb lifecycle, `fix_mode` domain orchestrators, `review-incident`.
+**When:** fix verb lifecycle, `fix_mode` domain orchestrators, optional deep path on `review-incident`.
 
 For create/update use [investigation-lite](../investigation-lite/SKILL.md) instead.
 
-Adapted from legacy swarm-check. **Default: readonly.**
+**Default: readonly.** Artifacts stored on Run under `artifacts.investigation`.
 
-## Frame
+Contract: [investigation.yaml](../../../aaac/contracts/skills/investigation.yaml)
 
+## Frame (parent — before swarm)
+
+```yaml
+issue: one line
+symptoms: user-visible
+expected: if known
+scope: files/features/routes
+questions: 3–5 open questions
+domain: cms | ui | database | aaac | unknown
 ```
-Issue:     one line
-Symptoms:  user-visible
-Expected:  if known
-Scope:     files/features
-Questions: 3–5
+
+Create Run artifact stub at `state/runs/{run_id}/artifacts/investigation-frame.yaml`.
+
+---
+
+## Mode A — Fix path (mandatory)
+
+**Applies to:** `fix`, `fix_mode`, `/fix-module`, `/fix-bug`, resolver paths `*-fix-bug`, generic `verb-fix`.
+
+### Phase 0 — Discovery swarm (prerequisite)
+
+Run [discovery](../discovery/SKILL.md) first — **4–6 parallel** agents in one message. Do not start fix swarm until discovery brief exists on Run.
+
+### Phase 1 — Fix investigation swarm (mandatory)
+
+Launch **7 parallel** `Task` subagents in **one message**. `readonly: true` unless agent spec allows test runs.
+
+| # | Agent spec | `subagent_type` | Angle |
+|---|------------|-----------------|-------|
+| 1 | [fix-repro.md](../../../agents/fix-repro.md) | `explore` | Repro steps + confirmation |
+| 2 | [fix-code-path.md](../../../agents/fix-code-path.md) | `explore` | Execution trace + suspects |
+| 3 | [fix-recent-changes.md](../../../agents/fix-recent-changes.md) | `shell` | Git log/blame on suspect paths |
+| 4 | [fix-test-failures.md](../../../agents/fix-test-failures.md) | `shell` | Tests + failures + gaps |
+| 5 | [fix-regression-scope.md](../../../agents/fix-regression-scope.md) | `explore` | Blast radius + dependents |
+| 6 | [fix-runtime-evidence.md](../../../agents/fix-runtime-evidence.md) | `generalPurpose` | CI/logs/MCP evidence |
+| 7 | [fix-inventory-confirm.md](../../../agents/fix-inventory-confirm.md) | `explore` | Inventory scope + constraints |
+
+**Parent prompt must include:** intent, domain, inventory path, discovery brief summary, frame fields.
+
+**Anti-patterns (hard fail):**
+
+- Skipping swarm because "issue looks simple"
+- Launching agents sequentially
+- Planning or executing before swarm merge
+- Fewer than 7 agents without documented gap + second wave
+
+**Second wave (optional, max 2):** when any agent returns `confidence: low` — target the gap only.
+
+### Parent merge (mandatory)
+
+Write `state/runs/{run_id}/artifacts/investigation.md`:
+
+```yaml
+repro_steps: [numbered]
+repro_confirmed: yes | partial | no
+suspect_files: [path:line]
+candidate_commits: [{ hash, likelihood, summary }]
+test_failures: []
+coverage_gaps: []
+blast_radius: low | medium | high
+runtime_evidence: [bullets]
+constraints: [from inventory]
+findings: [merged bullets]
+risks: [bullets]
+recommendations: [bullets]
+confidence:
+  architecture: 0.0–1.0
+  requirements: 0.0–1.0
+  scope: 0.0–1.0
 ```
 
-## Swarm
+Pass to [validation](../validation/SKILL.md) and [root-cause](../root-cause/SKILL.md).
+
+---
 
-3–6 parallel readonly agents: code path, recent changes, tests, CI (`ci-investigator` if `--ci`), logs, state flow.
+## Mode B — Incident path (review-incident)
 
-Use [discovery](../discovery/SKILL.md) agent specs where overlapping.
+**Applies to:** `/review-incident`, `swarm-check` alias — investigation only unless `--fix`.
 
-## Confidence output
+Launch **4 parallel** `Task` subagents in one message:
 
-Include `confidence.architecture`, `confidence.requirements`, `confidence.scope` for [validation](../validation/SKILL.md).
+| Agent | Spec |
+|-------|------|
+| Repro | [fix-repro.md](../../../agents/fix-repro.md) |
+| Code path | [fix-code-path.md](../../../agents/fix-code-path.md) |
+| Runtime | [fix-runtime-evidence.md](../../../agents/fix-runtime-evidence.md) |
+| Recent changes | [fix-recent-changes.md](../../../agents/fix-recent-changes.md) |
 
-## Report
+Layman report via [reporting](../reporting/SKILL.md) — <250 words unless user asked for detail.
 
-[reporting](../reporting/SKILL.md) — layman first, <250 words unless user asked for detail.
+If intent includes `--fix` or explicit fix request → continue full **Mode A** swarm + fix lifecycle after report approval.
+
+---
 
 ## Next phase (fix only)
 
-Hand off to [root-cause](../root-cause/SKILL.md) before planning.
+Hand off to [root-cause](../root-cause/SKILL.md) before planning. Do not skip even when root cause seems obvious.
 
 ## Fix path execution
 
-If intent includes fix or `fix-bug` command: after full lifecycle gates pass, orchestrator invokes `execution` + `testing` + `verification`.
+After full lifecycle gates pass, orchestrator invokes `execution` + [testing](../testing/SKILL.md) (fix verify swarm) + [verification](../verification/SKILL.md).

package/templates/cursor/skills/shared/investigation/orchestrator/SKILL.md

@@ -15,8 +15,16 @@ disable-model-invocation: true
 
 ## Phases
 
-1. [investigation](../SKILL.md) — layman report
-2. If fix requested: discovery → planning → execution → testing → verification
-3. [reporting](../reporting/SKILL.md)
+1. **discover** (optional, 2 agents max) when domain unknown
+2. [investigation](../SKILL.md) **Mode B** — **4 parallel** agents in one message (repro, code-path, runtime, recent-changes)
+3. [reporting](../../reporting/SKILL.md) — layman first; set Run `status: completed` unless fix path active
 
-Stop after report unless fix path active.
+## Fix escalation
+
+If intent includes `--fix`, explicit "fix this", or user approves after report:
+
+1. Switch command workflow to `fix-module` / `fix-bug` lifecycle on same Run
+2. Run investigation **Mode A** (full 7-agent swarm) if not already done
+3. Continue: root_cause → plan → gates → execute → verify (fix verify swarm) → report
+
+Do not execute code changes on incident path without explicit fix request or approval.

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

@@ -1,8 +1,8 @@
 ---
 name: shared-planning
 description: >-
-  Plans AAAC changes: SSOT, layers, size budgets, state machines. Readonly until
-  orchestrator approves. Invoked by graph — not user-facing.
+  Plans AAAC changes: SSOT, layers, size budgets, complexity score, requirement map.
+  Readonly until orchestrator approves. Mutating verbs only.
 disable-model-invocation: true
 ---
 
@@ -10,7 +10,16 @@ disable-model-invocation: true
 
 ## When
 
-After `discovery_swarm`. **Does not edit files.**
+After `discover` / `investigate*` on **`create`, `update`, `fix`** commands. **Does not edit files.**
+
+Other verbs: lightweight plan only (no complexity artifact).
+
+## Policies (mutating verbs)
+
+Read before planning:
+
+- [minimal-complexity.md](../../../policies/minimal-complexity.md)
+- [complexity.yaml](../../../aaac/complexity.yaml) — weights and thresholds
 
 ## Agents
 
@@ -19,12 +28,69 @@ Optional parallel readonly:
 - [plan-layer-map.md](../../../agents/plan-layer-map.md)
 - [plan-state-machines.md](../../../agents/plan-state-machines.md)
 
-## Plan document (internal)
+## Strategy (mandatory for create / update / fix)
+
+Search codebase first. Document in plan **before** proposing new artifacts:
+
+```text
+1. reuse_existing
+2. extend_existing
+3. modify_existing
+4. create_new  ← last resort; each entry needs requirement_ref + why_not_reuse
+```
+
+Prefer **lower complexity score** when multiple options satisfy requirements.
+
+## Plan artifact (store on Run `artifacts.plan`)
+
+Contract: [contracts/skills/planning.yaml](../../../aaac/contracts/skills/planning.yaml)
+
+```yaml
+requirement_map:
+  - requirement: "<from user intent — quoted if possible>"
+    satisfies_with: ["<artifact ids>"]
+complexity_score: <sum of weights for net-new items>
+complexity_breakdown:
+  new_file: 0
+  new_api_endpoint: 0
+  # … per complexity.yaml weights
+reuse: ["<existing paths or symbols>"]
+modify: ["<existing paths to edit>"]
+create:
+  - artifact: "<name>"
+    kind: <weight key from complexity.yaml>
+    requirement_ref: "<requirement text>"
+    why_not_reuse: "<one line>"
+rejected_alternatives:
+  - option: "<heavier approach>"
+    complexity_score: <number>
+    rejected_because: "<no requirement / reuse suffices>"
+paths_to_touch: ["<concrete file paths>"]
+rollback_notes: "<when protected/critical object>"
+```
+
+Also include:
 
-- User intent → concrete paths (from domain inventory)
 - SSOT owner for new state
 - Extract before add if any file ≥80% budget
-- Named machine states/events if async coordination added
-- Migration + schema steps if DB changes
+- Named machine states/events **only** if user requirement demands async coordination
+
+## Complexity score
+
+Sum `complexity.yaml` weights for each net-new artifact in `create`. **Edits to existing files do not add weight** (count under `modify`).
+
+Compare to verb threshold:
+
+| Verb | Max |
+|------|-----|
+| fix | 5 |
+| update | 8 |
+| create | 12 |
+
+If over threshold: revise plan toward reuse/modify or document in `rejected_alternatives` and stop for gate — do not proceed to execute silently.
+
+## YAGNI
+
+Do not plan for unstated future needs. See [minimal-complexity.md](../../../policies/minimal-complexity.md).
 
-Orchestrator gates `execute` — no implementation until plan respects domain constraints.
+Orchestrator gates `execute` — no implementation until plan passes **validate** and **fitness_functions** (`minimal_complexity`).

package/templates/cursor/skills/shared/platform-release/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: shared-platform-release
 description: >-
-  Phased release swarm coordination for release-app. Wave 1 git (blocking),
-  Wave 2 Render deploy. Internal only.
+  Phased release for release-app: mandatory preflight, git, optional conditional
+  package publish, Render poll, verify, report.
 disable-model-invocation: true
 ---
 
@@ -11,36 +11,39 @@ disable-model-invocation: true
 ## Swarm DAG
 
 ```text
-Preflight (optional tests)
+Wave 0: pnpm typecheck (mandatory)
   ↓
 Wave 1: release-git  ← BLOCKING
   ↓
-Wave 2: release-render
+Wave 1.5: conditional package publish ← OPTIONAL (project overlay; blocking when triggered)
   ↓
-Parent: verification + reporting
+Wave 2: release-render ← BLOCKING (poll until live or fail)
+  ↓
+Wave 3: verification + reporting
 ```
 
-## Wave 1 — launch one agent
+## Wave 0 — preflight
 
+```bash
+pnpm typecheck
 ```
-Task (shell or generalPurpose): release-git
-Read: agents/release-git.md, ship-procedure.md
-Return: commit_sha, commit_message_*
-On failure: abort pipeline
-```
 
-## Wave 2 — Render deploy
+Always. Optional extra tests when intent requests them.
+
+## Wave 1 — git
+
+Execute [agents/release-git.md](../../../agents/release-git.md) or spawn shell subagent.
+
+## Wave 1.5 — conditional publish (project overlay)
 
-Only after Wave 1 `status: success`. Pass `commit_sha` and messages.
+When the project ships an npm package with the app (e.g. `@ludecker/aaac`), the project overlay supplies a conditional publish agent and detection scripts. Skip when no changes detected.
 
-| Agent spec | Tool |
-|------------|------|
-| [release-render.md](../../../agents/release-render.md) | generalPurpose or render-assistant MCP |
+## Wave 2 — Render (mandatory)
 
-## Preflight
+Execute [agents/release-render.md](../../../agents/release-render.md).
 
-If intent contains "test" / "with tests": run `pnpm typecheck` before Wave 1.
+**Never** end ship without polled deploy status.
 
 ## Reference
 
-Full step detail: [ship-procedure.md](ship-procedure.md)
+Full steps: [ship-procedure.md](ship-procedure.md)

package/templates/cursor/skills/shared/platform-release/orchestrator/contract.yaml

@@ -1,5 +1,5 @@
 name: release-app-orchestrator
-purpose: Ship to main with phased expert subagents (git, then parallel integrations)
+purpose: Ship to main with preflight, git push, optional conditional package publish, mandatory Render deploy poll, smoke check, report
 inputs:
   domain:
     required: false
@@ -9,21 +9,41 @@ inputs:
 outputs:
   commit_sha:
     type: string
+  package_publish_skipped:
+    type: boolean
+  package_version:
+    type: string
+  package_tag:
+    type: string
+  package_publish_status:
+    type: string
   deploy_status:
     type: string
+  deploy_id:
+    type: string
+  smoke_http_code:
+    type: number
   report:
     type: markdown
 success_criteria:
-  - git push to main succeeded
-  - render deploy reached live or build failure reported with logs
-  - posthog and linear agents run after git (parallel wave)
+  - pnpm typecheck passed
+  - git push to main succeeded (or HEAD already on remote)
+  - when package changes detected, ship checks passed and version published
+  - render deploy reached live for commit_sha
+  - smoke check returned 200
 failure_conditions:
+  - typecheck failed
   - git push failed
-  - wave 2 started before commit_sha known
+  - wave 1.5 or 2 started before commit_sha known
+  - package ship checks failed when triggered
+  - package publish monitor timeout when triggered
+  - render build_failed or poll timeout
+  - smoke check not 200
 dependencies:
   skills: [platform-release, testing, verification, reporting]
   policies: [master-rules, mcp-and-deploy]
 verification:
+  - typecheck_passed
   - git_pushed
-  - render_polled
-  - agent_wave_order_respected
+  - render_polled_until_live
+  - smoke_200

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

@@ -21,7 +21,8 @@ disable-model-invocation: true
 - Tests: …
 - Intent: …
 - Confidence: architecture / requirements / scope
-- Fitness: pass/warning/fail summary
+- Complexity: score / threshold / pass (create/update/fix only)
+- Fitness: pass/warning/fail summary (include minimal_complexity)
 - Impact: blast_radius, affected domains
 
 ### Rollback (if applicable)

package/templates/cursor/skills/shared/root-cause/SKILL.md

@@ -1,13 +1,22 @@
 ---
 name: shared-root-cause
 description: >-
-  Deep root-cause framing after investigation on fix paths. Not user-facing.
+  Deep root-cause framing after investigation swarm on fix paths. Not user-facing.
 disable-model-invocation: true
 ---
 
 # Root cause (fix only)
 
-**When:** fix verb lifecycle — after [investigation](../investigation/SKILL.md), before planning.
+**When:** fix verb lifecycle — after [investigation](../investigation/SKILL.md) Mode A merge, before planning.
+
+**Input:** Run artifact `artifacts/investigation.md` (required).
+
+## Procedure
+
+1. Synthesize swarm outputs into one hypothesis — cite `path:line` evidence
+2. If any investigation agent had `confidence: low` **or** merged architecture confidence < 0.85 → launch **1 parallel** [fix-hypothesis-validate.md](../../../agents/fix-hypothesis-validate.md) (`explore`, readonly)
+3. If validator returns `investigate_more` → **STOP, REQUEST CLARIFICATION** or run second investigation wave (max 2 agents)
+4. Write Run artifact `artifacts/root_cause.yaml`
 
 ## Output (mandatory)
 
@@ -17,8 +26,10 @@ root_cause: hypothesis with evidence (path:line)
 contributing_factors: [optional bullets]
 fix_strategy: minimal correct change (not symptom patch)
 regression_risk: low | medium | high
+root_cause_confidence: 0.0–1.0
+validator_action: proceed | investigate_more | skipped
 ```
 
-If root cause confidence < 0.7 → **STOP, REQUEST CLARIFICATION** — do not plan or execute.
+If `root_cause_confidence` < **0.7** → **STOP, REQUEST CLARIFICATION** — do not plan or execute.
 
 Feed `fix_strategy` and `regression_risk` into [impact-analysis](../impact-analysis/SKILL.md) and [rollback](../rollback/SKILL.md).

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

@@ -1,8 +1,8 @@
 ---
 name: shared-testing
 description: >-
-  Runs vitest and Fallow check_changed for AAAC workflows. Software pass/fail —
-  not goal verification. Not user-facing.
+  Runs vitest, Fallow check_changed, and fix repro verification swarm.
+  Software pass/fail — not goal verification. Not user-facing.
 disable-model-invocation: true
 ---
 
@@ -10,15 +10,41 @@ disable-model-invocation: true
 
 ## When
 
-Phase `test` (and `test_only` orchestrators).
+Phase `verify` (and `test_only` orchestrators). On **fix** paths, run fix verify swarm **before** declaring tests complete.
 
-## Steps
+## Standard steps
 
 1. Run tests from domain inventory relevant to change
 2. Invoke [unit-test-run.md](../../../agents/unit-test-run.md) pattern for targeted vitest
 3. Fallow MCP → `check_changed` on touched files when configured
 4. `ReadLints` on edited paths
+5. **Website build gate (mandatory on create / update / fix):** before advancing `verify`, run:
+   ```bash
+   node .cursor/aaac/scripts/run-engine/verify-website-build.mjs --run-id <run_id>
+   ```
+   This checks `index.html` static asset paths resolve under `apps/website/public/` (or project root for Vite dev) and runs `pnpm --filter @ludecker/website build`. `advance-phase.mjs verify` **blocks** until this passes and writes `artifacts/verify.yaml`.
+
+## Fix verify swarm (mandatory on fix verb / fix_mode)
+
+After unit tests, launch **3 parallel** `Task` subagents in **one message**:
+
+| # | Agent spec | `subagent_type` | Role |
+|---|------------|-----------------|------|
+| 1 | [fix-repro-verify.md](../../../agents/fix-repro-verify.md) | `shell` | Re-run repro steps from investigation artifact |
+| 2 | [unit-test-run.md](../../../agents/unit-test-run.md) | `shell` | Targeted vitest for suspect area |
+| 3 | [fallow-check-changed.md](../../../agents/fallow-check-changed.md) | `generalPurpose` | Static health on touched files |
+
+Parent merges into Run `artifacts.testing`:
+
+```yaml
+repro_status: fixed | partial | not_fixed
+tests: { pass, fail, names: [] }
+fallow: pass | warn | fail
+lints: clean | issues
+```
+
+If `repro_status: not_fixed` → verification must **fail** even when unit tests pass.
 
 ## Output
 
-Pass/fail summary with test names and Fallow verdict for `verification` skill.
+Pass/fail summary with test names, repro_status, and Fallow verdict for [verification](../verification/SKILL.md).

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

@@ -1,16 +1,18 @@
 ---
 name: shared-validation
 description: >-
-  Confidence gates before execute. STOP and request clarification when thresholds
-  not met. Not user-facing.
+  Confidence and complexity gates before execute on create/update/fix.
+  STOP and request clarification when thresholds not met. Not user-facing.
 disable-model-invocation: true
 ---
 
-# Validation (confidence gates)
+# Validation (confidence + complexity gates)
 
-**When:** After plan, **before** impact_analysis / execute.
+**When:** After `plan`, **before** impact_analysis / execute.
 
-## Thresholds (SSOT)
+**Applies to:** `create`, `update`, `fix` (see [complexity.yaml](../../../aaac/complexity.yaml) `mutating_verbs`).
+
+## Thresholds — confidence (SSOT)
 
 From [ontology.json](../../../aaac/ontology.json) `confidence`:
 
@@ -20,22 +22,47 @@ From [ontology.json](../../../aaac/ontology.json) `confidence`:
 | requirements | 0.8 |
 | scope | 0.8 |
 
+## Thresholds — complexity (SSOT)
+
+From [complexity.yaml](../../../aaac/complexity.yaml):
+
+| Verb | Max `complexity_score` |
+|------|------------------------|
+| fix | 5 |
+| update | 8 |
+| create | 12 |
+
 ## Inputs
 
-- Plan from [planning](../planning/SKILL.md)
-- Confidence scores from [investigation-lite](../investigation-lite/SKILL.md) or [investigation](../investigation/SKILL.md) + [root-cause](../root-cause/SKILL.md)
+- Plan from [planning](../planning/SKILL.md) → Run `artifacts.plan`
+- Confidence scores from investigation path
 - Domain inventory constraints
+- [minimal-complexity.md](../../../policies/minimal-complexity.md)
 
 ## Procedure
 
+### 1. Confidence
+
 1. Score each dimension 0.0–1.0 with one-line evidence
 2. Compare to thresholds
-3. If **any** below threshold:
+
+### 2. Plan / complexity (mutating verbs only)
+
+1. Verify Run `artifacts.plan` has: `requirement_map`, `complexity_score`, `reuse`, `modify`, `create`, `rejected_alternatives`
+2. Every `create[]` entry must have `requirement_ref` and `why_not_reuse`
+3. Each requirement in user intent must appear in `requirement_map`
+4. Compare `complexity_score` to verb threshold
+5. Scan plan for YAGNI phrases ([complexity.yaml](../../../aaac/complexity.yaml) `yagni.reject_without_user_evidence`) — fail unless user intent cites the same need
+6. **fix:** plan must prioritize `modify` over `create`; score > 5 → fail
+
+### 3. Fail → block Run
+
+If confidence below threshold **or** complexity checks fail:
 
 ```yaml
 status: blocked
 awaiting_approval: true
-blocked_reason: "confidence.{dimension} {score} below {threshold}"
+blocked_reason: "<specific reason>"
 ```
 
 ```text
@@ -44,13 +71,21 @@ Reason: {blocked_reason}
 Run: {run_id}
 ```
 
-List specific questions for the user. **Do not proceed to execute** until user approves in chat.
+List specific questions. **Do not proceed to execute** until user approves or plan is revised.
+
+### 4. Pass
+
+Record on Run:
+
+- `confidence` scores
+- `gates.results.validate`
+- `artifacts.plan` complexity fields
 
-4. Record scores on Run `confidence` and gate result in `gates.results.validate`
-5. If at threshold: emit gate pass, continue gate stack
+Continue gate stack.
 
 ## Plan sanity checks
 
 - Plan respects inventory out-of-scope
 - Plan names files to touch (no vague "update CMS")
-- Protected/critical objects include rollback mention in plan or next rollback phase
+- Protected/critical objects include rollback mention
+- No new service/table/queue/state machine without matching `requirement_map` entry

package/templates/cursor/skills/shared/verbs/_dispatch-utils.md

@@ -18,6 +18,25 @@ Read before any phase:
 1. [.cursor/policies/master-rules.md](../../../policies/master-rules.md)
 2. [.cursor/policies/implementation.md](../../../policies/implementation.md)
 3. [.cursor/policies/mcp-and-deploy.md](../../../policies/mcp-and-deploy.md)
+4. [.cursor/policies/minimal-complexity.md](../../../policies/minimal-complexity.md) — **required for create / update / fix**
+
+## Minimal complexity (create / update / fix)
+
+SSOT: [complexity.yaml](../../../aaac/complexity.yaml), [minimal-complexity.md](../../../policies/minimal-complexity.md)
+
+| Phase | Responsibility |
+|-------|----------------|
+| **plan** | `requirement_map`, `complexity_score`, reuse/modify/create, rejected alternatives → Run `artifacts.plan` |
+| **validate** | Confidence + plan fields + score ≤ threshold + YAGNI |
+| **fitness_functions** | `minimal_complexity` pass (blocking) |
+
+Optimization: **capability / complexity**, not capability alone. Default to reuse → extend → modify → create.
+
+| Verb | Max complexity score |
+|------|----------------------|
+| fix | 5 |
+| update | 8 |
+| create | 12 |
 
 ## Confidence gates
 
@@ -49,7 +68,7 @@ When `$DOMAIN` slug maps to `domains/<slug>/update/inventory/SKILL.md`:
 1. Read inventory **first** (constraints, out-of-scope, file map)
 2. Pass inventory constraints into discovery, investigation-lite/investigation, planning, validation, execution, verification
 
-If inventory missing and command is `fix-bug` / `create-feature` / `update-module`:
+If inventory missing and command is `fix-bug` / `fix-module` / `create-feature` / `update-module`:
 
 - Run [module-authoring](../../module-authoring/SKILL.md) discovery to bootstrap domain, **or**
 - Tell user to use generic verb command with intent

package/templates/cursor/skills/shared/verbs/_lifecycle.md

@@ -30,7 +30,8 @@ Everything executes within a Run. Observability (`decisions`, `log`, `checkpoint
 |-------|------|-------|
 | `discover` | work | discovery |
 | `investigate_lite` | work | investigation-lite |
-| `investigate` | work | investigation |
+| `investigate` | work | investigation (legacy id; use investigate_swarm) |
+| `investigate_swarm` | work | investigation Mode A |
 | `root_cause` | work | root-cause |
 | `plan` | work | planning |
 | `validate` | gate | validation |
@@ -48,7 +49,7 @@ Everything executes within a Run. Observability (`decisions`, `log`, `checkpoint
 |------|------|------------|
 | create | discover → investigate_lite → plan → execute → verify → report | pre_execute |
 | update | same | pre_execute |
-| fix | discover → investigate → root_cause → plan → execute → verify → report | pre_execute |
+| fix | discover → investigate_swarm → root_cause → plan → execute → verify → report | pre_execute |
 | review | discover → plan → report | none |
 | check | discover → report | pre_execute_minimal |
 | test | discover → plan → verify → report | none |

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

@@ -17,6 +17,9 @@ Read [_dispatch-utils.md](../_dispatch-utils.md) first.
 3. **load_inventory** — when domain slug maps to inventory
 4. **object_skills** — from graph `object_skills.<object>`
 5. [check](../../check/SKILL.md) — swarm per check skill
-6. [reporting](../../reporting/SKILL.md) — **Answer** (yes/no/partial) then **How**
+6. **contract_checks** — `pnpm --filter @ludecker/aaac test` and `pnpm --filter @ludecker/aaac test:e2e` (includes `check-verb.check.spec.ts`); launch [playwright-check-run](../../../agents/playwright-check-run.md) at report phase
+7. [reporting](../../reporting/SKILL.md) — **Answer** (yes/no/partial) then **How**
 
 No code changes. For test runs use `test-*`; for fixes use `fix-*`.
+
+Debug blocked runs: [aaac-log-debug](../../../agents/aaac-log-debug.md) — `debug-run`, `log-dump`, `log-trace`.