@ludecker/aaac 1.0.0 → 1.1.0

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,36 @@ 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
 
+## 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`.

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

@@ -23,8 +23,8 @@ Lifecycle: graph `verb_runtime.create` (work + gates on Run)
 2. **load_inventory** — when `domains/<slug>/update/inventory/SKILL.md` exists
 3. **discover** — [discovery](../../discovery/SKILL.md) readonly
 4. **investigate_lite** — [investigation-lite](../../investigation-lite/SKILL.md)
-5. **plan** — [planning](../../planning/SKILL.md)
-6. **validate** — [validation](../../validation/SKILL.md) — confidence gates
+5. **plan** — [planning](../../planning/SKILL.md) — **requirement_map + complexity_score** on Run
+6. **validate** — [validation](../../validation/SKILL.md) — confidence + complexity gates
 7. **impact_analysis** — [impact-analysis](../../impact-analysis/SKILL.md)
 8. **dependency_graph** — [dependency-graph](../../dependency-graph/SKILL.md)
 9. **fitness_functions** — [fitness-functions](../../fitness-functions/SKILL.md)

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

@@ -1,33 +1,43 @@
 ---
 name: verb-fix-orchestrator
-description: Orchestrates fix-* except fix-bug resolver paths. Internal only.
+description: Orchestrates fix-* resolver fallbacks and generic fix-{object} commands. Internal only.
 disable-model-invocation: true
 ---
 
 # fix-* orchestrator
 
-**Object** from graph. `fix-bug` uses domain resolver (see [dispatch.md](../../../aaac/dispatch.md) for fallback).
+**Object** from graph or resolver `default_object`. Domain resolver paths (`fix-module`, `fix-bug`, …) prefer `*-fix-bug` orchestrators — see [dispatch.md](../../../aaac/dispatch.md).
 
 Read [_dispatch-utils.md](../_dispatch-utils.md) and [_lifecycle.md](../_lifecycle.md) first.
 
-Lifecycle: graph `verb_runtime.fix` (work + gates on Run)
+Contract: [contract.yaml](./contract.yaml)  
+Command contracts: [fix-module.yaml](../../../aaac/contracts/commands/fix-module.yaml), [fix-bug.yaml](../../../aaac/contracts/commands/fix-bug.yaml)
+
+Lifecycle: graph `verb_runtime.fix` or `command_workflows.fix-module` on Run
 
 ## Phases (deterministic — do not skip)
 
-1. **policies**
-2. **load_inventory** — when domain inventory exists
-3. **discover** — [discovery](../../discovery/SKILL.md) readonly
-4. **investigate** — [investigation](../../investigation/SKILL.md) deep
-5. **root_cause** — [root-cause](../../root-cause/SKILL.md)
-6. **plan** — [planning](../../planning/SKILL.md)
+1. **policies** — all four including [minimal-complexity.md](../../../policies/minimal-complexity.md)
+2. **load_inventory** — when `domains/<slug>/update/inventory/SKILL.md` exists
+3. **discover** — [discovery](../../discovery/SKILL.md) — **4–6 parallel** agents, one message
+4. **investigate_swarm** — [investigation](../../investigation/SKILL.md) Mode A — **7 parallel** agents, one message
+5. **root_cause** — [root-cause](../../root-cause/SKILL.md) — optional [fix-hypothesis-validate](../../../agents/fix-hypothesis-validate.md)
+6. **plan** — [planning](../../planning/SKILL.md) — minimal diff; `complexity_score` max **5**
 7. **validate** — [validation](../../validation/SKILL.md)
 8. **impact_analysis** — [impact-analysis](../../impact-analysis/SKILL.md)
 9. **dependency_graph** — [dependency-graph](../../dependency-graph/SKILL.md)
 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) + [verification](../../verification/SKILL.md)
-14. **sync_inventory**
+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)
 
+## Swarm anti-patterns (hard fail)
+
+- Skipping discovery or investigate_swarm because the issue "looks simple"
+- Sequential Task launches when parallel is required
+- Execute before `root_cause_confidence` ≥ 0.7
+- Claim success when `repro_status: not_fixed`
+
 Gate failure → **STOP, REQUEST CLARIFICATION**

package/templates/cursor/skills/shared/verbs/fix/orchestrator/contract.yaml

@@ -6,28 +6,42 @@ inputs:
   intent:
     required: true
 outputs:
+  investigation:
+    type: markdown
+    required: true
+  root_cause:
+    type: markdown
+    required: true
   code_changes:
     type: boolean
   inventory_synced:
     type: boolean
+  repro_status:
+    type: string
+    required: true
+    enum: [fixed, partial, not_fixed]
   report:
     type: markdown
 success_criteria:
   - All policies loaded before execute
-  - investigation completed before planning
+  - discovery swarm completed (4-6 parallel agents)
+  - investigate_swarm completed (7 parallel fix agents)
+  - root_cause_confidence at least 0.7 before plan
   - domain inventory loaded when domains/<slug>/update/inventory exists
   - object skills from graph object_skills / object_skill_verbs loaded
   - governance/implementation followed for all edits
+  - repro_status fixed or partial with documented follow-up
   - fallow check_changed clean on touched files
   - user intent satisfied per verification
 failure_conditions:
   - execute without approved plan
-  - skip investigation phase
+  - skip discover or investigate_swarm phase
   - skip governance/implementation on code changes
   - skip domain inventory when slug resolves to inventory file
+  - repro_status not_fixed while claiming success
 dependencies:
-  skills: [investigation, discovery, planning, execution, testing, verification, reporting]
-  policies: [master-rules, implementation, mcp-and-deploy]
+  skills: [discovery, investigation, root-cause, planning, execution, testing, verification, reporting]
+  policies: [master-rules, implementation, mcp-and-deploy, minimal-complexity]
   docs:
     - docs/master_rules.md
     - docs/architecture.md
@@ -35,4 +49,5 @@ dependencies:
 verification:
   - sync_inventory
   - run_tests
+  - fix_repro_verify_swarm
   - fallow_check_changed

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

@@ -18,8 +18,8 @@ Lifecycle: graph `verb_runtime.update` (work + gates on Run)
 2. **load_inventory** — when domain inventory exists
 3. **discover** — [discovery](../../discovery/SKILL.md)
 4. **investigate_lite** — [investigation-lite](../../investigation-lite/SKILL.md) — **mandatory** (what exists, depends on, constraints)
-5. **plan** — [planning](../../planning/SKILL.md)
-6. **validate** — [validation](../../validation/SKILL.md)
+5. **plan** — [planning](../../planning/SKILL.md) — **requirement_map + complexity_score** (max 8)
+6. **validate** — [validation](../../validation/SKILL.md) — confidence + complexity gates
 7. **impact_analysis** — [impact-analysis](../../impact-analysis/SKILL.md)
 8. **dependency_graph** — [dependency-graph](../../dependency-graph/SKILL.md)
 9. **fitness_functions** — [fitness-functions](../../fitness-functions/SKILL.md)

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

@@ -14,6 +14,8 @@ After `testing`. Before `report`.
 
 ## Checks
 
+- **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
 - User instruction satisfied (spot-check 2–3 behaviors in code or tests)