@ludecker/aaac 1.1.5 → 1.1.6

package/src/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 = [
@@ -138,11 +160,22 @@ export function phaseKind(phase, registry) {
 
 /** Swarm minimum for completed phase — check verb uses check_swarm on discover. */
 export function resolveSwarmMinimum(completedPhase, manifest, enforcement) {
-  if (
-    completedPhase === "verify" &&
-    (enforcement.fix_commands?.includes(manifest.command) || manifest.verb === "fix")
-  ) {
-    return enforcement.swarm_min_agents?.verify_fix;
+  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 (
@@ -189,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/enforcement.json

@@ -1,15 +1,23 @@
 {
-  "version": 2,
+  "version": 3,
   "description": "AAAC runtime enforcement — SSOT for hooks and run engine",
-  "edit_phases": ["execute", "sync_inventory", "persist", "write"],
-  "artifact_write_phases": ["plan", "report", "verify"],
+  "edit_phases": ["execute", "test_execute", "sync_inventory", "persist", "write"],
+  "artifact_write_phases": ["plan", "report"],
+  "mutating_verbs": ["create", "update", "fix"],
+  "phase_edit_scopes": {
+    "execute": { "deny_test_paths": true },
+    "test_execute": { "test_paths_only": true }
+  },
   "verify_verbs": ["create", "update", "fix"],
   "swarm_min_agents": {
     "discover": 4,
     "check_swarm": 3,
     "investigate_swarm": 7,
     "research_swarm": 6,
-    "verify_fix": 3
+    "test_execute": 1,
+    "verify": 3,
+    "verify_fix": 3,
+    "review_swarm": 3
   },
   "phase_artifacts": {
     "investigate_swarm": ["artifacts/investigation.md"],
@@ -20,7 +28,9 @@
     "dependency_graph": ["artifacts/dependency_graph.yaml"],
     "fitness_functions": ["artifacts/fitness.yaml"],
     "rollback": ["artifacts/rollback.yaml"],
+    "test_execute": ["artifacts/test_plan.yaml"],
     "verify": ["artifacts/verify.yaml"],
+    "review_swarm": ["artifacts/review.yaml"],
     "report": ["artifacts/report.md"]
   },
   "allowed_path_prefixes": {

package/templates/cursor/aaac/graph.project.yaml

@@ -1,5 +1,6 @@
-# Generic AAAC project overlay — verb orchestrators + exception commands only.
-# Add domain resolvers, orchestrators, and project skills in your repo after init.
+# Generic AAAC project overlay — copied into consumer repos by `aaac init`.
+# Add `resolvers:` and domain orchestrators when you create `.cursor/domains/<slug>/`.
+# Reference implementation (Lüdecker cms/ui/database): ludecker repo `.cursor/aaac/graph.project.yaml`
 
 orchestrators:
   update-doc:
@@ -41,7 +42,7 @@ orchestrators:
   verb-fix:
     path: skills/shared/verbs/fix/orchestrator
     requires: [discovery, investigation, root-cause, planning, validation, impact-analysis, dependency-graph, fitness-functions, rollback, execution, testing, verification, reporting]
-    phases: [load_inventory, discover, investigate_swarm, root_cause, plan, validate, impact_analysis, dependency_graph, fitness_functions, rollback, execute, verify, sync_inventory, report]
+    phases: [load_inventory, discover, investigate_swarm, root_cause, plan, validate, impact_analysis, dependency_graph, fitness_functions, rollback, execute, test_execute, verify, review_swarm, sync_inventory, report]
 
   verb-review:
     path: skills/shared/verbs/review/orchestrator
@@ -72,11 +73,17 @@ skills:
   execution:
     path: skills/shared/execution
     depends: [governance/implementation]
+  test-authoring:
+    path: skills/shared/test-authoring
+    agents: [test-author]
   testing:
     path: skills/shared/testing
     agents: [unit-test-run, fallow-check-changed, fix-repro-verify]
   verification:
     path: skills/shared/verification
+  implementation-review:
+    path: skills/shared/implementation-review
+    agents: [boundary-review, doc-conformance, implementation-review]
   reporting:
     path: skills/shared/reporting
   architecture:
@@ -182,6 +189,12 @@ agents:
     path: agents/fix-repro-verify.md
   fix-hypothesis-validate:
     path: agents/fix-hypothesis-validate.md
+  test-author:
+    path: agents/test-author.md
+  doc-conformance:
+    path: agents/doc-conformance.md
+  implementation-review:
+    path: agents/implementation-review.md
   release-git:
     path: agents/release-git.md
     wave: 1
@@ -189,7 +202,5 @@ agents:
 
 policies:
   - policies/master-rules.md
-  - policies/project-context.md
-  - policies/ui-design.md
   - policies/implementation.md
   - policies/mcp-and-deploy.md

package/templates/cursor/aaac/lifecycle/lifecycle.json

@@ -8,7 +8,9 @@
         "investigate_lite",
         "plan",
         "execute",
+        "test_execute",
         "verify",
+        "review_swarm",
         "report"
       ],
       "gate_stack": "pre_execute"
@@ -19,7 +21,9 @@
         "investigate_lite",
         "plan",
         "execute",
+        "test_execute",
         "verify",
+        "review_swarm",
         "report"
       ],
       "gate_stack": "pre_execute"
@@ -31,7 +35,9 @@
         "root_cause",
         "plan",
         "execute",
+        "test_execute",
         "verify",
+        "review_swarm",
         "report"
       ],
       "gate_stack": "pre_execute"
@@ -58,7 +64,9 @@
         "investigate_lite",
         "plan",
         "execute",
+        "test_execute",
         "verify",
+        "review_swarm",
         "report"
       ],
       "gate_stack": "pre_execute"
@@ -96,7 +104,9 @@
         "root_cause",
         "plan",
         "execute",
+        "test_execute",
         "verify",
+        "review_swarm",
         "report"
       ],
       "gate_stack": "pre_execute"
@@ -109,7 +119,9 @@
         "root_cause",
         "plan",
         "execute",
+        "test_execute",
         "verify",
+        "review_swarm",
         "report"
       ],
       "gate_stack": "pre_execute"

package/templates/cursor/aaac/lifecycle/phases.json

@@ -14,7 +14,9 @@
     "fitness_functions": { "skill": "fitness-functions", "gate": true },
     "rollback": { "skill": "rollback", "gate": true },
     "execute": { "skill": "execution" },
+    "test_execute": { "skill": "test-authoring" },
     "verify": { "skills": ["testing", "verification"] },
+    "review_swarm": { "skill": "implementation-review", "readonly": true },
     "report": { "skill": "reporting" }
   }
 }

package/templates/cursor/aaac/scripts/run-engine/advance-phase.mjs

@@ -17,6 +17,7 @@ import {
   isEditPhase,
   isGatePhase,
   resolveSwarmMinimum,
+  validatePhaseArtifactContent,
   writeJson,
   saveActiveRun,
 } from "./lib.mjs";
@@ -132,6 +133,28 @@ for (const rel of requiredArtifacts) {
   }
 }
 
+if (!force) {
+  const contentGate = validatePhaseArtifactContent(
+    runId,
+    completedPhase,
+    manifest,
+    enforcement,
+  );
+  if (!contentGate.ok) {
+    recordLog(manifest, {
+      event: "gate_fail",
+      phase: completedPhase,
+      phase_kind: manifest.phase_kind,
+      detail: contentGate.reason,
+      level: "warn",
+    });
+    manifest.updated_at = isoNow();
+    writeJson(manifestPath, manifest);
+    console.error(contentGate.reason);
+    process.exit(2);
+  }
+}
+
 const now = isoNow();
 const completedIsGate = isGatePhase(completedPhase, registry);
 

package/templates/cursor/aaac/scripts/run-engine/gate-write.mjs

@@ -7,6 +7,7 @@ import {
   loadEnforcement,
   isEditPhase,
   isArtifactPath,
+  isPathAllowedForPhase,
   conversationIdFromHook,
   runDir,
   writeJson,
@@ -86,6 +87,18 @@ process.stdin.on("end", () => {
   }
 
   if (isEditPhase(manifest.phase, enforcement)) {
+    if (filePath && !isPathAllowedForPhase(filePath, manifest.phase, enforcement)) {
+      persistEditEvent(
+        manifest,
+        active.run_id,
+        "edit_denied",
+        `${toolName} path not allowed in phase ${manifest.phase}: ${filePath}`,
+      );
+      deny(
+        `AAAC: ${manifest.phase} phase cannot edit this path. Run: ${active.run_id}`,
+        `Phase "${manifest.phase}" scope violation${filePath ? `: ${filePath}` : ""}. Use test_execute for tests; execute for prod code only.`,
+      );
+    }
     persistEditEvent(manifest, active.run_id, "edit_allowed", `${toolName} in phase ${manifest.phase}`);
     allow();
   }

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 = [
@@ -138,11 +160,22 @@ export function phaseKind(phase, registry) {
 
 /** Swarm minimum for completed phase — check verb uses check_swarm on discover. */
 export function resolveSwarmMinimum(completedPhase, manifest, enforcement) {
-  if (
-    completedPhase === "verify" &&
-    (enforcement.fix_commands?.includes(manifest.command) || manifest.verb === "fix")
-  ) {
-    return enforcement.swarm_min_agents?.verify_fix;
+  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 (
@@ -189,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/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