@ludecker/aaac 1.1.4 → 1.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ludecker/aaac",
-  "version": "1.1.4",
+  "version": "1.1.5",
   "description": "Agentic Architecture as Code (AAAC) — installable Cursor agent framework",
   "type": "module",
   "license": "MIT",

package/src/run-engine/advance-phase.mjs

@@ -16,6 +16,7 @@ import {
   phaseKind,
   isEditPhase,
   isGatePhase,
+  resolveSwarmMinimum,
   writeJson,
   saveActiveRun,
 } from "./lib.mjs";
@@ -55,11 +56,7 @@ if (manifest.phase !== completedPhase) {
   process.exit(1);
 }
 
-const minAgents =
-  completedPhase === "verify" &&
-  (enforcement.fix_commands?.includes(manifest.command) || manifest.verb === "fix")
-    ? enforcement.swarm_min_agents?.verify_fix
-    : enforcement.swarm_min_agents?.[completedPhase];
+const minAgents = resolveSwarmMinimum(completedPhase, manifest, enforcement);
 const launches = manifest.swarm?.task_launches_this_phase ?? 0;
 if (minAgents && launches < minAgents && !force) {
   recordLog(manifest, {

package/src/run-engine/debug-run.mjs

@@ -31,6 +31,12 @@ if (summary.blocked_reason) console.log(`Blocked: ${summary.blocked_reason}`);
 console.log(`Completed: ${summary.completed.join(" → ") || "(none)"}`);
 console.log(`Pending: ${summary.pending.join(" → ") || "(none)"}`);
 console.log(`Swarm: phase=${summary.swarm.phase} count=${summary.swarm.task_launches_this_phase}`);
+if (summary.swarm.agents?.length) {
+  console.log(`Agents: ${summary.swarm.agents.length} recorded this phase`);
+  for (const a of summary.swarm.agents.slice(-5)) {
+    console.log(`  #${a.index} ${a.subagent_type ?? "?"} ${a.description ?? ""} @ ${a.at}`);
+  }
+}
 console.log(`Log: ${summary.log_count} entries  Decisions: ${summary.decisions_count}`);
 console.log("--- last 10 log entries ---");
 for (const e of summary.last_log_entries) {

package/src/run-engine/lib.mjs

@@ -136,6 +136,23 @@ 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) {
+  if (
+    completedPhase === "verify" &&
+    (enforcement.fix_commands?.includes(manifest.command) || manifest.verb === "fix")
+  ) {
+    return enforcement.swarm_min_agents?.verify_fix;
+  }
+  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 ?? "";
 }

package/src/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/src/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/aaac/enforcement.json

@@ -6,6 +6,7 @@
   "verify_verbs": ["create", "update", "fix"],
   "swarm_min_agents": {
     "discover": 4,
+    "check_swarm": 3,
     "investigate_swarm": 7,
     "research_swarm": 6,
     "verify_fix": 3
@@ -14,6 +15,11 @@
     "investigate_swarm": ["artifacts/investigation.md"],
     "root_cause": ["artifacts/root_cause.yaml"],
     "plan": ["artifacts/plan.yaml"],
+    "validate": ["artifacts/validate.yaml"],
+    "impact_analysis": ["artifacts/impact.yaml"],
+    "dependency_graph": ["artifacts/dependency_graph.yaml"],
+    "fitness_functions": ["artifacts/fitness.yaml"],
+    "rollback": ["artifacts/rollback.yaml"],
     "verify": ["artifacts/verify.yaml"],
     "report": ["artifacts/report.md"]
   },

package/templates/cursor/aaac/run/schema.json

@@ -35,6 +35,11 @@
       "stack": "string | null",
       "results": {}
     },
+    "swarm": {
+      "task_launches_this_phase": 0,
+      "phase": "string | null",
+      "agents": []
+    },
     "created_at": "iso8601",
     "updated_at": "iso8601"
   },

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

@@ -16,6 +16,7 @@ import {
   phaseKind,
   isEditPhase,
   isGatePhase,
+  resolveSwarmMinimum,
   writeJson,
   saveActiveRun,
 } from "./lib.mjs";
@@ -55,11 +56,7 @@ if (manifest.phase !== completedPhase) {
   process.exit(1);
 }
 
-const minAgents =
-  completedPhase === "verify" &&
-  (enforcement.fix_commands?.includes(manifest.command) || manifest.verb === "fix")
-    ? enforcement.swarm_min_agents?.verify_fix
-    : enforcement.swarm_min_agents?.[completedPhase];
+const minAgents = resolveSwarmMinimum(completedPhase, manifest, enforcement);
 const launches = manifest.swarm?.task_launches_this_phase ?? 0;
 if (minAgents && launches < minAgents && !force) {
   recordLog(manifest, {

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

@@ -31,6 +31,12 @@ if (summary.blocked_reason) console.log(`Blocked: ${summary.blocked_reason}`);
 console.log(`Completed: ${summary.completed.join(" → ") || "(none)"}`);
 console.log(`Pending: ${summary.pending.join(" → ") || "(none)"}`);
 console.log(`Swarm: phase=${summary.swarm.phase} count=${summary.swarm.task_launches_this_phase}`);
+if (summary.swarm.agents?.length) {
+  console.log(`Agents: ${summary.swarm.agents.length} recorded this phase`);
+  for (const a of summary.swarm.agents.slice(-5)) {
+    console.log(`  #${a.index} ${a.subagent_type ?? "?"} ${a.description ?? ""} @ ${a.at}`);
+  }
+}
 console.log(`Log: ${summary.log_count} entries  Decisions: ${summary.decisions_count}`);
 console.log("--- last 10 log entries ---");
 for (const e of summary.last_log_entries) {

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

@@ -136,6 +136,23 @@ 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) {
+  if (
+    completedPhase === "verify" &&
+    (enforcement.fix_commands?.includes(manifest.command) || manifest.verb === "fix")
+  ) {
+    return enforcement.swarm_min_agents?.verify_fix;
+  }
+  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 ?? "";
 }

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/rules/aaac-enforcement.mdc

@@ -11,8 +11,8 @@ 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)
 
@@ -31,11 +31,16 @@ 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.
+4. **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. **Code edits only in `execute`** (hook-enforced). Before execute: artifacts only under `.cursor/aaac/state/runs/`.
+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/investigation/SKILL.md

@@ -53,7 +53,7 @@ Launch **7 parallel** `Task` subagents in **one message**. `readonly: true` unle
 | 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.
+**Parent prompt must include:** intent, domain, inventory path, discovery brief summary, frame fields, and the policy excerpt from [_task-prompt-policy.md](../_task-prompt-policy.md).
 
 **Anti-patterns (hard fail):**
 

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

@@ -36,3 +36,5 @@ Pass output to [validation](../validation/SKILL.md). If any confidence below thr
 ## Agents
 
 Reuse readonly specs: [discovery-inventory.md](../../../agents/discovery-inventory.md), [discovery-ssot.md](../../../agents/discovery-ssot.md), [dependency-analysis.md](../../../agents/dependency-analysis.md) — 2–3 parallel max for lite path.
+
+Every Task prompt **must** include the policy excerpt from [_task-prompt-policy.md](../_task-prompt-policy.md).

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

@@ -18,15 +18,15 @@ Phase `verify` (and `test_only` orchestrators). On **fix** paths, run fix verify
 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. **App build gate (when enabled):** before advancing `verify`, run:
+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>
    ```
-   Reads `verify` from `.cursor/aaac/project.config.json`. Skips when `verify.enabled: false` (default on fresh install). When enabled, checks `index_html` static assets and runs the configured build command. `advance-phase.mjs verify` **blocks** until this passes and writes `artifacts/verify.yaml`.
+   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**:
+After unit tests, launch **3 parallel** `Task` subagents in **one message**. Each prompt **must** include [_task-prompt-policy.md](../_task-prompt-policy.md) and investigation artifact paths.
 
 | # | Agent spec | `subagent_type` | Role |
 |---|------------|-----------------|------|