@ludecker/aaac 1.1.4 → 1.1.6

package/templates/cursor/aaac/scripts/run-engine/lib.mjs

@@ -123,6 +123,28 @@ export function isEditPhase(phase, enforcement) {
   return enforcement.edit_phases.includes(phase);
 }
 
+/** Test/spec file paths — used for writer vs tester phase scoping. */
+export function isTestPath(filePath) {
+  if (!filePath) return false;
+  const normalized = filePath.replace(/\\/g, "/");
+  return (
+    /\.(test|spec)\.(mjs|cjs|js|ts|tsx)$/.test(normalized) ||
+    /(?:^|\/)__tests__(?:\/|$)/.test(normalized) ||
+    /(?:^|\/)tests\/(?:unit|integration|e2e|fixtures)\//.test(normalized)
+  );
+}
+
+/** Phase-scoped edit rules from enforcement.phase_edit_scopes (v3+). */
+export function isPathAllowedForPhase(filePath, phase, enforcement) {
+  if (!filePath) return true;
+  const scopes = enforcement.phase_edit_scopes?.[phase];
+  if (!scopes) return true;
+  const isTest = isTestPath(filePath);
+  if (scopes.deny_test_paths && isTest) return false;
+  if (scopes.test_paths_only && !isTest) return false;
+  return true;
+}
+
 export function isArtifactPath(filePath, enforcement) {
   const normalized = filePath.replace(/\\/g, "/");
   const prefixes = [
@@ -136,6 +158,34 @@ export function phaseKind(phase, registry) {
   return isGatePhase(phase, registry) ? "gate" : "work";
 }
 
+/** Swarm minimum for completed phase — check verb uses check_swarm on discover. */
+export function resolveSwarmMinimum(completedPhase, manifest, enforcement) {
+  const mutating = enforcement.mutating_verbs ?? ["create", "update", "fix"];
+  const isMutating =
+    mutating.includes(manifest.verb) ||
+    enforcement.fix_commands?.includes(manifest.command);
+
+  if (completedPhase === "verify" && isMutating) {
+    return (
+      enforcement.swarm_min_agents?.verify ??
+      enforcement.swarm_min_agents?.verify_fix
+    );
+  }
+  if (completedPhase === "test_execute" && isMutating) {
+    return enforcement.swarm_min_agents?.test_execute;
+  }
+  if (completedPhase === "review_swarm" && isMutating) {
+    return enforcement.swarm_min_agents?.review_swarm;
+  }
+  if (completedPhase === "discover" && manifest.verb === "check") {
+    return (
+      enforcement.swarm_min_agents?.check_swarm ??
+      enforcement.swarm_min_agents?.discover
+    );
+  }
+  return enforcement.swarm_min_agents?.[completedPhase];
+}
+
 export function promptFromHook(hook) {
   return hook?.prompt ?? hook?.text ?? hook?.content ?? "";
 }
@@ -172,3 +222,118 @@ export function clearActiveRun(conversationId) {
     // already cleared
   }
 }
+
+export function isMutatingVerb(manifest, enforcement) {
+  const mutating = enforcement.mutating_verbs ?? ["create", "update", "fix"];
+  return (
+    mutating.includes(manifest.verb) ||
+    (enforcement.fix_commands ?? []).includes(manifest.command)
+  );
+}
+
+/** List items under a YAML field (lines starting with `-` before next top-level key). */
+export function readYamlListField(content, fieldName) {
+  if (!content) return [];
+  const lines = content.split("\n");
+  const start = lines.findIndex((line) => line.startsWith(`${fieldName}:`));
+  if (start < 0) return [];
+
+  const inline = lines[start].slice(`${fieldName}:`.length).trim();
+  if (inline === "[]") return [];
+  if (inline && !inline.startsWith("-")) return [inline];
+
+  const items = [];
+  for (let i = start + 1; i < lines.length; i += 1) {
+    const line = lines[i];
+    if (/^\S/.test(line) && line.trim()) break;
+    const itemMatch = line.match(/^\s+-\s+(.*)$/);
+    if (itemMatch) items.push(itemMatch[1].trim());
+  }
+  return items;
+}
+
+export function readYamlScalarField(content, fieldName) {
+  if (!content) return null;
+  const match = content.match(new RegExp(`^${fieldName}:\\s*(.+)$`, "m"));
+  if (!match) return null;
+  return match[1].trim().replace(/^["']|["']$/g, "");
+}
+
+export function hasYamlField(content, fieldName) {
+  if (!content) return false;
+  return new RegExp(`^${fieldName}:`, "m").test(content);
+}
+
+export function planRequiresTests(planContent) {
+  if (!planContent) return false;
+  if (hasYamlField(planContent, "tests_to_add")) {
+    return readYamlListField(planContent, "tests_to_add").length > 0;
+  }
+  return /^\s*create:[\s\S]*?^\s+-\s+path:.*\/lib\//m.test(planContent);
+}
+
+export function validatePhaseArtifactContent(runId, completedPhase, manifest, enforcement) {
+  if (!isMutatingVerb(manifest, enforcement)) {
+    return { ok: true };
+  }
+
+  const planPath = path.join(runDir(runId), "artifacts/plan.yaml");
+  const planContent = fs.existsSync(planPath)
+    ? fs.readFileSync(planPath, "utf8")
+    : "";
+
+  if (completedPhase === "plan") {
+    if (!hasYamlField(planContent, "tests_to_add")) {
+      return {
+        ok: false,
+        reason:
+          "plan.yaml must include tests_to_add (behaviors to cover, or tests_to_add: [] when no tests are needed)",
+      };
+    }
+    return { ok: true };
+  }
+
+  if (completedPhase === "test_execute") {
+    const testPlanPath = path.join(runDir(runId), "artifacts/test_plan.yaml");
+    const testPlanContent = fs.existsSync(testPlanPath)
+      ? fs.readFileSync(testPlanPath, "utf8")
+      : "";
+
+    const filesWritten = readYamlListField(testPlanContent, "files_written");
+    const skippedReason = readYamlScalarField(testPlanContent, "skipped_reason");
+    const testsRequired = planRequiresTests(planContent);
+
+    if (/status:\s*deferred/i.test(testPlanContent) && filesWritten.length === 0) {
+      return {
+        ok: false,
+        reason:
+          "test_plan.yaml cannot defer tests — author test files in test_execute (files_written required)",
+      };
+    }
+
+    if (testsRequired && filesWritten.length === 0) {
+      return {
+        ok: false,
+        reason:
+          "plan.yaml tests_to_add requires non-empty test_plan.files_written — launch test-author Task in test_execute",
+      };
+    }
+
+    if (
+      hasYamlField(planContent, "tests_to_add") &&
+      /tests_to_add:\s*\[\]/m.test(planContent) &&
+      filesWritten.length === 0 &&
+      !skippedReason
+    ) {
+      return {
+        ok: false,
+        reason:
+          "tests_to_add is empty — test_plan.yaml must include skipped_reason explaining why no tests were authored",
+      };
+    }
+
+    return { ok: true };
+  }
+
+  return { ok: true };
+}

package/templates/cursor/aaac/scripts/run-engine/log.mjs

@@ -334,7 +334,7 @@ export function debugRunSummary(manifest) {
     awaiting_approval: manifest.awaiting_approval,
     completed: manifest.completed ?? [],
     pending: manifest.pending ?? [],
-    swarm: { phase: swarmPhase, task_launches_this_phase: swarmCount },
+    swarm: { phase: swarmPhase, task_launches_this_phase: swarmCount, agents: manifest.swarm?.agents ?? [] },
     edit_allowed: manifest.enforcement?.edit_allowed ?? false,
     last_log_entries: log.slice(-10),
     decisions_count: (manifest.decisions ?? []).length,

package/templates/cursor/aaac/scripts/run-engine/record-task.mjs

@@ -44,19 +44,40 @@ process.stdin.on("end", () => {
   if (manifest.conversation_id && manifest.conversation_id !== conversationId) allow();
 
   manifest.swarm = manifest.swarm ?? {};
-  manifest.swarm.task_launches_this_phase = (manifest.swarm.task_launches_this_phase ?? 0) + 1;
+  const launchIndex = (manifest.swarm.task_launches_this_phase ?? 0) + 1;
+  manifest.swarm.task_launches_this_phase = launchIndex;
   manifest.swarm.phase = manifest.phase;
-  manifest.updated_at = isoNow();
+
+  const agentEntry = {
+    at: isoNow(),
+    index: launchIndex,
+    phase: manifest.phase,
+    subagent_type: hook.subagent_type ?? hook.subagentType ?? null,
+    description: hook.description ?? hook.subagent_description ?? null,
+    model: hook.model ?? null,
+    readonly: hook.readonly ?? null,
+  };
+  manifest.swarm.agents = manifest.swarm.agents ?? [];
+  manifest.swarm.agents.push(agentEntry);
+
+  const telemetryDetail = JSON.stringify({
+    count: launchIndex,
+    subagent_type: agentEntry.subagent_type,
+    index: launchIndex,
+  });
 
   recordLog(manifest, {
     event: "agent_spawned",
     phase: manifest.phase,
     phase_kind: manifest.phase_kind,
-    detail: `count=${manifest.swarm.task_launches_this_phase}`,
+    detail: telemetryDetail,
     level: "debug",
   });
 
   writeJson(path.join(runDir(active.run_id), "run.json"), manifest);
-  saveActiveRun(conversationId, { ...active, task_launches_this_phase: manifest.swarm.task_launches_this_phase });
+  saveActiveRun(conversationId, {
+    ...active,
+    task_launches_this_phase: manifest.swarm.task_launches_this_phase,
+  });
   allow();
 });

package/templates/cursor/agents/doc-conformance.md

@@ -0,0 +1,25 @@
+# Agent: doc-conformance
+
+**Readonly.**
+
+## Role
+
+Compare implementation diff against supporting docs and policies — not layer boundaries (see boundary-review).
+
+## Sources (read before judging)
+
+- [docs/master_rules.md](../../docs/master_rules.md)
+- [docs/architecture.md](../../docs/architecture.md) when present
+- Domain inventory under `.cursor/domains/<slug>/update/inventory/` when available
+- [.cursor/policies/](../../.cursor/policies/)
+
+## Check
+
+- SSOT violations (duplicated constants, mirrored state)
+- Undocumented exceptions to master rules
+- Plan `requirement_map` entries satisfied in code
+- Missing validation at boundaries when plan promised schemas
+
+## Return
+
+Findings, Evidence (`path:line`), Severity (critical | suggestion), Confidence.

package/templates/cursor/agents/implementation-review.md

@@ -0,0 +1,21 @@
+# Agent: implementation-review
+
+**Readonly.**
+
+## Role
+
+Independent post-execute review of the diff — **not** the agent that wrote the code. Spot-check that the change matches plan and does not introduce obvious defects.
+
+## Check
+
+- Plan `paths_to_touch` vs actual diff scope
+- No drive-by refactors outside plan
+- Error paths logged, not swallowed
+- Async flows use explicit state machines where plan required
+- Size budgets not violated on touched files (flag if file grew past 80% budget)
+
+## Return
+
+Findings, Evidence (`path:line`), Severity (critical | suggestion), Confidence.
+
+**Blocking:** any **critical** finding must be fixed before `report` on mutating verbs.

package/templates/cursor/agents/test-author.md

@@ -0,0 +1,27 @@
+# Agent: test-author
+
+**Phase:** `test_execute` only. Parent orchestrator must **not** write test files — this agent does.
+
+## Role
+
+Author behavioral tests for changes made in `execute`. Read plan `tests_to_add[]`, implementation diff, and domain inventory test conventions.
+
+## Must
+
+- Write only `*.test.*`, `*.spec.*`, or paths under `__tests__/` / `tests/`
+- Cover behaviors from `requirement_map`, not implementation details
+- Match existing test framework (vitest, playwright) in the touched package
+- Include [_task-prompt-policy.md](../skills/shared/_task-prompt-policy.md) policies
+
+## Must not
+
+- Edit production/source files (non-test paths)
+- Weaken assertions to make tests pass
+- Duplicate tests that already cover the behavior
+
+## Return
+
+- Files created/modified (paths only)
+- Behaviors covered (one line each)
+- Gaps — behaviors still untested
+- Confidence: high | medium | low

package/templates/cursor/rules/aaac-enforcement.mdc

@@ -11,15 +11,15 @@ Every AAAC slash command (`/fix-module`, `/update-module`, `/write-article`, …
 
 ## Prerequisites
 
-1. **Project opened in Cursor** — `.cursor/hooks.json` is installed by `init`; hooks run when the project is open
-2. **Registry current** — after ontology edits: `npx @ludecker/aaac@latest generate`
+1. **Cursor Hooks enabled** — Settings → Hooks; restart Cursor after `.cursor/hooks.json` changes
+2. **Registry current** — `node .cursor/aaac/generate-graph.mjs`
 
 ## Hook behavior (automatic)
 
 | Hook | Effect |
 |------|--------|
 | `beforeSubmitPrompt` | Detects `/command` → creates Run scoped to **`conversation_id`** (this chat only) |
-| `preToolUse` | **Denies** Write/StrReplace/Delete for **this chat only** until execute phase |
+| `preToolUse` | **Denies** edits outside allowed phases; **phase-scoped paths** — `execute` = prod only, `test_execute` = tests only |
 | `subagentStart` | Counts Task launches for swarm phase validation |
 | `stop` | Follow-up if Run not `completed` |
 
@@ -31,11 +31,23 @@ Every AAAC slash command (`/fix-module`, `/update-module`, `/write-article`, …
    node .cursor/aaac/scripts/run-engine/advance-phase.mjs <run_id> <phase>
    ```
 3. **Swarm minimums** (enforced by advance-phase):
-   - `discover`: 4 Task agents
+   - `discover`: 4 Task agents (check verbs: `check_swarm` 3)
    - `investigate_swarm`: 7 Task agents
    - `research_swarm`: 6 Task agents
-4. **Code edits only in `execute`** (hook-enforced). Before execute: artifacts only under `.cursor/aaac/state/runs/`.
-5. **Complete the Run** — advance through `report`, set status completed.
+   - `test_execute`: 1 test-author Task agent (mutating verbs)
+   - `verify`: 3 Task agents (all create/update/fix — not fix-only)
+   - `review_swarm`: 3 readonly reviewers (mutating verbs)
+4. **Agent separation (mutating verbs):**
+   - **Writer** — parent in `execute` only (no test files)
+   - **Tester** — test-author subagent in `test_execute` only
+   - **Reviewer** — readonly swarm in `review_swarm` (not the execute agent)
+5. **Verify gate (create / update / fix):** before advancing past `verify`, run:
+   ```bash
+   node .cursor/aaac/scripts/run-engine/verify-website-build.mjs --run-id <run_id>
+   ```
+   `advance-phase.mjs verify` runs this automatically and blocks on missing static assets or failed `vite build` (catches favicon/path regressions).
+5. **Edits:** prod code in `execute`; test files in `test_execute` only. Run artifacts under `.cursor/aaac/state/runs/` anytime.
+6. **Complete the Run** — advance through `report`, set status completed.
 
 ## If edit is denied
 

package/templates/cursor/skills/shared/_task-prompt-policy.md

@@ -0,0 +1,18 @@
+# Task prompt policy excerpt (mandatory)
+
+Append this block to **every** Task sub-agent prompt the orchestrator sends.
+
+## Policies (mandatory)
+
+- **Readonly** unless the agent spec explicitly allows test runs or shell commands.
+- **Evidence:** every claim needs `path:line` citations the parent can spot-check.
+- **SSOT:** do not invent constants, routes, or file paths — read the repo.
+- **Prime directive** (master rules): clarity beats cleverness; predictability beats shortcuts; one truth beats convenience.
+- **Layer boundaries:** `packages/ui` must not import `apps/website`; `packages/types` and `packages/utils` stay runtime-free.
+- **Errors:** never silent — state gaps explicitly in the return block.
+
+Full policy chain: [.cursor/policies/master-rules.md](../../policies/master-rules.md) → [docs/master_rules.md](../../../docs/master_rules.md)
+
+## Return shape
+
+Follow the agent spec (`Findings`, `Evidence`, `Gaps`, `Confidence`). Do not edit files unless the spec allows it.

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

@@ -34,6 +34,10 @@ Launch **3** parallel `Task` subagents (`explore`, `readonly: true`) in **one me
 
 Optional **4th** agent (second wave, only if intent names external system): `discovery-boundaries.md` for integration edges.
 
+## Task prompt (mandatory)
+
+Every Task prompt **must** include the policy excerpt from [_task-prompt-policy.md](../_task-prompt-policy.md) plus: question, scope, agent spec path, and inventory path when available.
+
 ## Merge
 
 Parent synthesizes one brief:

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

@@ -24,6 +24,10 @@ Launch **4–6** parallel `Task` subagents (`explore`, `readonly: true`) in **on
 
 Add domain-specific angles from inventory skill. Max **8** agents total; second wave ≤2 for critical gaps.
 
+## Task prompt (mandatory)
+
+Every Task prompt **must** include the policy excerpt from [_task-prompt-policy.md](../_task-prompt-policy.md) plus: intent, domain, inventory constraints, and the linked agent spec path.
+
 ## Output
 
 Merged brief for `planning`: findings, evidence, gaps, confidence. Parent spot-checks `path:line` claims.

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

@@ -15,18 +15,22 @@ Orchestrator phase `execute` after approved plan.
 ## Mandatory
 
 1. Read [governance/implementation/SKILL.md](../governance/implementation/SKILL.md)
-2. Read domain inventory when present (`domains/<slug>/update/inventory/`)
+2. Read domain [inventory](../../../domains/) constraints
 3. Read [policies/](../../../policies/)
 
 ## Actions
 
-- Edit files per plan and implementation skill
-- Apply database migrations via configured MCP when your project uses one (see [mcp-and-deploy.md](../../../policies/mcp-and-deploy.md) and `{{DOCS_ROOT}}/project_context.md`)
+- Edit **production/source** files per plan and implementation skill
+- **Do not** create or edit test files (`*.test.*`, `*.spec.*`, `__tests__/`) — deferred to `test_execute` / [test-authoring](../test-authoring/SKILL.md)
+- `apply_migration` for new/changed `supabase/migrations/` (project `anseivwusnyiwopihnqu` — see [supabase-mcp.mdc](../../../rules/supabase-mcp.mdc))
+- `track()` for user-facing mutations
 - Structured logging on server async paths
 
 ## Must not
 
 - Invent plan during execution
+- Write or edit test files (hooks block in `execute`; use `test_execute`)
+- Self-review implementation (use [implementation-review](../implementation-review/SKILL.md) in `review_swarm`)
 - Race guards or useEffect-driven mutations (implementation ban)
 - Skip schema validation at boundaries