@ludecker/aaac 1.1.4 → 1.1.6

package/README.md

@@ -4,40 +4,55 @@
 
 > Commands are the public API. Skills, agents, and orchestrators are private implementation.
 
-## Install
+## Quick start
 
-No `npm` CLI required. Use `npx` or `pnpm dlx`:
+**1. Install into your repo** (no global `npm` CLI required):
 
 ```bash
 npx @ludecker/aaac@latest init
 ```
 
 ```bash
-pnpm dlx @ludecker/aaac@latest init
+pnpm dlx @ludecker/aaac@latest init --yes
 ```
 
-Non-interactive:
+Non-interactive with a target path:
 
 ```bash
 npx @ludecker/aaac@latest init --yes --dir /path/to/your/repo
 ```
 
-## What you get
+**2. Open the project in Cursor** and **enable Hooks once**: Settings → Hooks, then restart Cursor.
+
+After that, slash commands work — no domain overlay, resolvers, or manual `generate` step required. `init` already generates `graph.yaml` and all commands.
+
+**Install report:** `init` writes `.cursor/aaac/state/install-sweep-report.md` — a read-only inventory of docs, Cursor rules, and AAAC framework markdown in your repo, with recommendations (no merges or aliases).
+
+**Install report:** `init` writes `.cursor/aaac/state/install-sweep-report.md` — a read-only inventory of docs, Cursor rules, and AAAC framework markdown in your repo, with recommendations (no merges or aliases).
 
-Works **out of the box** after `init` — open in Cursor and run commands. No post-install setup.
+## Example commands
+
+```text
+/create-module api "Add health check endpoint"
+/fix-bug auth "Session expires too soon"
+/check-module payments "Validate webhook idempotency"
+/review-architecture system "Check layer boundaries"
+```
+
+## What you get
 
-- `.cursor/hooks.json` — Run lifecycle and edit enforcement (installed with the project)
+- `.cursor/hooks.json` — Run lifecycle and edit enforcement
 - `.cursor/aaac/` — ontology, graph, lifecycle, run model, enforcement
 - `.cursor/skills/shared/` — full pipeline (discovery → execute → verify → report)
-- `.cursor/agents/` — 13 generic subagent specs
+- `.cursor/agents/` — generic subagent specs
 - `.cursor/commands/` — ~130 generated slash commands
-- `docs/` — ready-to-use `master_rules.md`, `ui_design.md`, `project_context.md`, `architecture.md`, and `agentic_architecture.md`
+- `docs/` — `master_rules.md`, `ui_design.md`, `project_context.md`, `architecture.md`, `agentic_architecture.md`
 
-Optional later: add **domains** under `.cursor/domains/<slug>/` (see maintainer appendix in `agentic_architecture.md`).
+**Optional later:** add **domains** under `.cursor/domains/<slug>/` and resolvers in `graph.project.yaml` for slug routing (e.g. `/update-module cms "…"`). See `docs/agentic_architecture.md` Part 2.
 
 ## Regenerate
 
-After editing `ontology.json` or `graph.project.yaml`:
+Only needed after you edit `ontology.json` or `graph.project.yaml`:
 
 ```bash
 npx @ludecker/aaac@latest generate
@@ -48,7 +63,7 @@ pnpm dlx @ludecker/aaac@latest generate
 
 - [Install guide](https://ludecker.com/guide/install-aaac)
 - [Package on npm](https://www.npmjs.com/package/@ludecker/aaac)
-- [Lüdecker](https://ludecker.com) — reference implementation
+- [Lüdecker](https://ludecker.com) — reference implementation (domain overlays, production deploy)
 
 ## Publish (maintainers)
 

package/package.json

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

package/src/cli.mjs

@@ -15,11 +15,16 @@ Usage:
   aaac generate [options]
 
 Commands:
-  init      Copy AAAC kernel into .cursor/ and docs/ (default)
+  init        Copy AAAC kernel into .cursor/ and docs/ (default)
   generate    Regenerate graph.yaml and commands from ontology
   log-dump    Print Run manifest log + decisions
   debug-run   One-shot Run status summary
 
+Quick start:
+  1. npx @ludecker/aaac@latest init   (or: pnpm dlx @ludecker/aaac@latest init --yes)
+  2. Open project in Cursor → Settings → Hooks → enable → restart Cursor
+  3. Use any slash command (graph + commands generated during init)
+
 Options:
   --dir <path>   Target project directory (default: cwd)
   --yes, -y      Non-interactive defaults
@@ -78,7 +83,7 @@ async function cmdInit(args) {
   const options = await promptInitOptions(args);
   console.log(`\nInstalling AAAC into ${options.targetDir}...\n`);
 
-  const { cursorDest, docsDest } = installAaac({
+  const { cursorDest, docsDest, sweepReportPath } = installAaac({
     targetDir: options.targetDir,
     projectName: options.projectName,
     docsRoot: options.docsRoot,
@@ -90,17 +95,24 @@ Agentic OS is ready.
 
   .cursor/     → ${cursorDest}
   docs/        → ${docsDest}
+  sweep report → ${sweepReportPath}
+
+Next steps:
+
+  1. Open this project in Cursor
+  2. Settings → Hooks → enable Hooks, then restart Cursor
+  3. Read the install sweep report (docs/rules/framework inventory + recommendations)
 
-Open this project in Cursor and use any command, for example:
+Then use any command, for example:
 
   /create-module api "Add health check endpoint"
-  /fix-module auth "Session expires too soon"
+  /fix-bug auth "Session expires too soon"
   /review-architecture system "Check structure"
 
-No setup required after install. Rules and architecture docs are already in place.
-To go deeper later, read ${options.docsRoot}/agentic_architecture.md (Part 2 — optional).
+Graph and commands were generated during init — no manual setup required.
+Optional: add domain resolvers later (see ${options.docsRoot}/agentic_architecture.md Part 2).
 
-Regenerate commands after ontology edits:
+Regenerate only after ontology or graph.project.yaml edits:
   npx @ludecker/aaac@latest generate
 `);
 }

package/src/generators/generate-commands.mjs

@@ -96,7 +96,7 @@ Contract: [${canonical}.yaml](../aaac/contracts/commands/${canonical}.yaml)
 /${cmd} payments "Webhook handler drops events on retry"
 /${cmd} api "Auth middleware returns 500 on expired token"
 \`\`\`
-`;
+${testExecuteAppendix()}`;
   fs.writeFileSync(path.join(commandsDir, `${cmd}.md`), body);
 }
 
@@ -203,6 +203,29 @@ function domainLine(cmd) {
   return "Domain slug recommended.";
 }
 
+const MUTATING_VERBS = new Set(["create", "update", "fix"]);
+
+function testExecuteAppendix() {
+  return `
+
+## Execute vs test_execute (mandatory)
+
+| Phase | Allowed edits | Blocked |
+|-------|---------------|---------|
+| **execute** | Production/source files | \`*.test.*\`, \`*.spec.*\`, \`__tests__/\` |
+| **test_execute** | Test files only | Production/source paths |
+
+**Rules:**
+
+1. \`artifacts/plan.yaml\` must include **\`tests_to_add\`** (behaviors to cover, or \`tests_to_add: []\` when truly none).
+2. In **test_execute**, launch **1** [test-author](../../agents/test-author.md) Task agent — parent must not author tests in execute.
+3. \`artifacts/test_plan.yaml\` must list **\`files_written\`** when \`tests_to_add\` is non-empty, or **\`skipped_reason\`** when \`tests_to_add: []\`.
+4. **\`status: deferred\` is invalid** — hooks block test writes in execute; deferral is not a substitute for the test_execute phase.
+
+If execute hits \`phase cannot edit this path\` for a test file, **advance to test_execute** and author tests there — do not bypass with a hollow \`test_plan.yaml\`.
+`;
+}
+
 function writeCmd(cmd, entry = null) {
   if (isContentWriter(cmd, entry)) {
     writeContentWriterCmd(cmd, entry);
@@ -242,6 +265,7 @@ ${layerLine}**${cap(vDesc)}** a **${object}**${aliasNote} — ${description}.
 3. ${orchestratorHint(cmd, entry ?? {})}
 
 ${domainLine(cmd)}
+${MUTATING_VERBS.has(verb) ? testExecuteAppendix() : ""}
 `;
   fs.writeFileSync(path.join(commandsDir, `${cmd}.md`), body);
 }

package/src/generators/generate-graph.mjs

@@ -13,6 +13,14 @@ import {
 
 const INJECT_MARKER = "{{INJECT_OBJECT_BLOCKS}}";
 
+/** Drop `#` comment lines from graph.project.yaml — comments are not valid in merged graph.yaml tail. */
+function stripProjectOverlayComments(text) {
+  return text
+    .split("\n")
+    .filter((line) => !/^\s*#/.test(line))
+    .join("\n");
+}
+
 const args = parseArgs(process.argv);
 const cursorRoot = resolveCursorRoot(args.root);
 const aaac = aaacDir(cursorRoot);
@@ -242,7 +250,7 @@ contracts: aaac/contracts/
 
 `;
 
-let tail = projectTail.trim();
+let tail = stripProjectOverlayComments(projectTail.trim());
 if (tail.includes(INJECT_MARKER)) {
   tail = tail.replace(INJECT_MARKER, injectBlock.trim());
 } else {

package/src/lib/install.mjs

@@ -7,6 +7,10 @@ import {
   packageGeneratorsDir,
   packageTemplatesDir,
 } from "./paths.mjs";
+import {
+  runInstallSweep,
+  snapshotProjectDocs,
+} from "./sweep-project-docs.mjs";
 
 export function runGenerators(cursorRoot) {
   const generatorsDir = packageGeneratorsDir();
@@ -45,6 +49,8 @@ export function installAaac({
     );
   }
 
+  const beforeSweep = snapshotProjectDocs(resolvedTarget, { docsRoot });
+
   if (fs.existsSync(cursorDest) && force) {
     const backup = `${cursorDest}.aaac-backup-${Date.now()}`;
     fs.renameSync(cursorDest, backup);
@@ -73,5 +79,11 @@ export function installAaac({
 
   runGenerators(cursorDest);
 
-  return { cursorDest, docsDest };
+  const sweep = runInstallSweep(resolvedTarget, {
+    docsRoot,
+    projectName,
+    before: beforeSweep,
+  });
+
+  return { cursorDest, docsDest, sweepReportPath: sweep.reportPath };
 }

package/src/lib/sweep-project-docs.mjs

@@ -0,0 +1,348 @@
+import fs from "fs";
+import path from "path";
+
+/** @typedef {'docs' | 'rules' | 'framework'} SweepCategory */
+
+const SKIP_DIR_NAMES = new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  ".next",
+  "coverage",
+  "vendor",
+  ".turbo",
+  ".cache",
+]);
+
+const DOC_DIR_NAMES = new Set(["docs", "doc", "documentation"]);
+
+const ROOT_DOC_FILES = new Set([
+  "README.md",
+  "CONTRIBUTING.md",
+  "ARCHITECTURE.md",
+  "CHANGELOG.md",
+  "CODE_OF_CONDUCT.md",
+  "SECURITY.md",
+  "AGENTS.md",
+  "CLAUDE.md",
+  "GEMINI.md",
+]);
+
+const AAAC_TEMPLATE_DOCS = new Set([
+  "master_rules.md",
+  "project_context.md",
+  "ui_design.md",
+  "architecture.md",
+  "agentic_architecture.md",
+]);
+
+const FRAMEWORK_PREFIXES = [
+  ".cursor/aaac/",
+  ".cursor/skills/",
+  ".cursor/agents/",
+  ".cursor/policies/",
+  ".cursor/commands/",
+];
+
+const RULES_PREFIXES = [".cursor/rules/"];
+
+const MARKDOWN_EXT = /\.(md|mdc)$/i;
+
+/**
+ * @param {string} root
+ * @param {{ docsRoot?: string; includeFramework?: boolean }} [options]
+ */
+export function snapshotProjectDocs(root, options = {}) {
+  return sweepProjectDocs(root, { ...options, includeFramework: false });
+}
+
+/**
+ * @param {string} root
+ * @param {{ docsRoot?: string; includeFramework?: boolean }} [options]
+ */
+export function sweepProjectDocs(root, options = {}) {
+  const resolvedRoot = path.resolve(root);
+  const docsRoot = normalizeRel(options.docsRoot ?? "docs");
+  const includeFramework = options.includeFramework !== false;
+  /** @type {Record<SweepCategory, string[]>} */
+  const inventory = { docs: [], rules: [], framework: [] };
+
+  walk(resolvedRoot, "", (rel, isDir) => {
+    if (isDir) {
+      if (SKIP_DIR_NAMES.has(path.basename(rel))) return "skip";
+      if (rel.includes(".cursor/aaac/state/runs")) return "skip";
+      return;
+    }
+    if (!MARKDOWN_EXT.test(rel)) return;
+
+    const category = classify(rel, docsRoot, includeFramework);
+    if (category) inventory[category].push(rel);
+  });
+
+  for (const key of Object.keys(inventory)) {
+    inventory[key].sort();
+  }
+  return inventory;
+}
+
+/**
+ * @param {{
+ *   before: Record<SweepCategory, string[]>;
+ *   after: Record<SweepCategory, string[]>;
+ *   docsRoot: string;
+ *   projectName?: string;
+ *   installedAt?: string;
+ * }} ctx
+ */
+export function buildRecommendations(ctx) {
+  const { before, after, docsRoot } = ctx;
+  const recs = [];
+  const docsRootNorm = normalizeRel(docsRoot);
+
+  const overwritten = before.docs.filter((rel) => {
+    const base = path.basename(rel);
+    return (
+      AAAC_TEMPLATE_DOCS.has(base) &&
+      after.docs.includes(`${docsRootNorm}/${base}`)
+    );
+  });
+
+  if (overwritten.length > 0) {
+    recs.push({
+      kind: "review_overwrite",
+      message: `These doc paths existed before init and were replaced by AAAC templates: ${overwritten.join(", ")}. Review content if you had custom rules there (restore from backup or merge manually).`,
+    });
+  }
+
+  const extraDocDirs = new Set();
+  for (const rel of after.docs) {
+    const top = rel.split("/")[0];
+    if (
+      DOC_DIR_NAMES.has(top) &&
+      top !== docsRootNorm &&
+      !rel.startsWith(`${docsRootNorm}/`)
+    ) {
+      extraDocDirs.add(top);
+    }
+  }
+  if (extraDocDirs.size > 0) {
+    recs.push({
+      kind: "extra_doc_dirs",
+      message: `Additional documentation directories found: ${[...extraDocDirs].join(", ")}. AAAC policies point at ${docsRootNorm}/ — add SSOT anchors in ${docsRootNorm}/project_context.md if those dirs hold project truth.`,
+    });
+  }
+
+  if (after.rules.some((r) => r === "AGENTS.md" || r.endsWith("/AGENTS.md"))) {
+    recs.push({
+      kind: "agents_md",
+      message:
+        "AGENTS.md is present. Cursor loads it alongside AAAC policies — keep both aligned or document division of responsibility in project_context.md.",
+    });
+  }
+
+  const customRules = after.rules.filter((r) =>
+    r.startsWith(".cursor/rules/"),
+  );
+  const aaacRule = customRules.find((r) =>
+    r.includes("aaac-enforcement"),
+  );
+  if (customRules.length > 1) {
+    recs.push({
+      kind: "cursor_rules",
+      message: `${customRules.length} Cursor rule files under .cursor/rules/. Review for overlap with docs/master_rules.md${aaacRule ? " and aaac-enforcement" : ""}.`,
+    });
+  }
+
+  const projectContext = `${docsRootNorm}/project_context.md`;
+  if (after.docs.includes(projectContext)) {
+    recs.push({
+      kind: "fill_project_context",
+      message: `Fill in ${projectContext} with your repo paths and SSOT anchors when ready — until then agents use generic master rules only.`,
+    });
+  }
+
+  const archPaths = after.docs.filter((rel) =>
+    /architecture\.md$/i.test(rel),
+  );
+  if (archPaths.length > 1) {
+    recs.push({
+      kind: "multiple_architecture",
+      message: `Multiple architecture docs: ${archPaths.join(", ")}. Pick one SSOT for structure or cross-link from ${docsRootNorm}/architecture.md.`,
+    });
+  }
+
+  if (before.docs.length === 0 && before.rules.length === 0) {
+    recs.push({
+      kind: "greenfield",
+      message:
+        "No pre-existing project docs or Cursor rules detected — AAAC template docs are your starting SSOT.",
+    });
+  } else {
+    recs.push({
+      kind: "no_auto_merge",
+      message:
+        "Init did not merge or alias any existing files. This report is informational only — wire existing docs into project_context.md manually if needed.",
+    });
+  }
+
+  return recs;
+}
+
+/**
+ * @param {Parameters<typeof buildRecommendations>[0]} ctx
+ */
+export function formatInstallSweepReport(ctx) {
+  const { after, docsRoot, projectName = "project", installedAt } = ctx;
+  const recommendations = buildRecommendations(ctx);
+  const lines = [
+    "# AAAC install — docs / rules / framework inventory",
+    "",
+    `Project: **${projectName}**`,
+    installedAt ? `Generated: ${installedAt}` : "",
+    "",
+    "Read-only sweep after `aaac init`. No merges or aliases were applied.",
+    "",
+    "## Summary",
+    "",
+    `| Category | Files |`,
+    `|----------|------:|`,
+    `| Docs | ${after.docs.length} |`,
+    `| Rules | ${after.rules.length} |`,
+    `| Framework (AAAC) | ${after.framework.length} |`,
+    "",
+    "## Docs",
+    "",
+  ];
+
+  lines.push(
+    ...(after.docs.length
+      ? after.docs.map((f) => `- \`${f}\``)
+      : ["_None found._"]),
+  );
+  lines.push("", "## Rules", "");
+  lines.push(
+    ...(after.rules.length
+      ? after.rules.map((f) => `- \`${f}\``)
+      : ["_None found._"]),
+  );
+  lines.push("", "## Framework (AAAC markdown)", "");
+  lines.push(
+    ...(after.framework.length
+      ? after.framework.map((f) => `- \`${f}\``)
+      : ["_None found._"]),
+  );
+
+  lines.push("", "## Recommendations", "");
+  for (const [i, rec] of recommendations.entries()) {
+    lines.push(`${i + 1}. **${rec.kind}** — ${rec.message}`);
+  }
+  lines.push(
+    "",
+    "## Next steps",
+    "",
+    `- Edit \`${normalizeRel(docsRoot)}/project_context.md\` for project-specific paths.`,
+    "- Enable Cursor Hooks (Settings → Hooks) and restart Cursor.",
+    "- Optional: add domain resolvers in `.cursor/aaac/graph.project.yaml`.",
+    "",
+  );
+
+  return `${lines.filter((l) => l !== undefined).join("\n")}\n`;
+}
+
+/**
+ * @param {string} targetDir
+ * @param {string} markdown
+ * @returns {string} absolute report path
+ */
+export function writeInstallSweepReport(targetDir, markdown) {
+  const reportDir = path.join(targetDir, ".cursor", "aaac", "state");
+  fs.mkdirSync(reportDir, { recursive: true });
+  const reportPath = path.join(reportDir, "install-sweep-report.md");
+  fs.writeFileSync(reportPath, markdown);
+  return reportPath;
+}
+
+/**
+ * @param {string} root
+ * @param {{ docsRoot: string; projectName: string; before?: ReturnType<typeof snapshotProjectDocs> }} params
+ */
+export function runInstallSweep(root, params) {
+  const after = sweepProjectDocs(root, {
+    docsRoot: params.docsRoot,
+    includeFramework: true,
+  });
+  const before =
+    params.before ??
+    snapshotProjectDocs(root, { docsRoot: params.docsRoot });
+  const markdown = formatInstallSweepReport({
+    before,
+    after,
+    docsRoot: params.docsRoot,
+    projectName: params.projectName,
+    installedAt: new Date().toISOString(),
+  });
+  const reportPath = writeInstallSweepReport(root, markdown);
+  return { after, before, reportPath, markdown };
+}
+
+function normalizeRel(rel) {
+  return rel.replace(/\\/g, "/").replace(/\/$/, "") || "docs";
+}
+
+/**
+ * @param {string} rel POSIX relative path
+ * @param {string} docsRoot
+ * @param {boolean} includeFramework
+ * @returns {SweepCategory | null}
+ */
+function classify(rel, docsRoot, includeFramework) {
+  const norm = rel.replace(/\\/g, "/");
+
+  if (RULES_PREFIXES.some((p) => norm.startsWith(p))) return "rules";
+  if (norm === "AGENTS.md" || norm === "CLAUDE.md" || norm === "GEMINI.md") {
+    return "rules";
+  }
+  if (norm.startsWith(".cursor/policies/")) return "rules";
+
+  if (includeFramework && FRAMEWORK_PREFIXES.some((p) => norm.startsWith(p))) {
+    if (norm.includes(".cursor/aaac/state/")) return null;
+    return "framework";
+  }
+
+  if (norm.startsWith(`${docsRoot}/`)) return "docs";
+  const top = norm.split("/")[0];
+  if (DOC_DIR_NAMES.has(top)) return "docs";
+  if (!norm.includes("/") && ROOT_DOC_FILES.has(norm)) return "docs";
+  if (/^(README|ARCHITECTURE|CONTRIBUTING|SECURITY|CHANGELOG)/i.test(norm)) {
+    return "docs";
+  }
+
+  return null;
+}
+
+/**
+ * @param {string} root
+ * @param {string} dirRel
+ * @param {(rel: string, isDir: boolean) => 'skip' | void} visit
+ */
+function walk(root, dirRel, visit) {
+  const abs = dirRel === "" ? root : path.join(root, dirRel);
+  let entries;
+  try {
+    entries = fs.readdirSync(abs, { withFileTypes: true });
+  } catch {
+    return;
+  }
+
+  for (const entry of entries) {
+    const rel = dirRel ? `${dirRel}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      const action = visit(rel, true);
+      if (action === "skip") continue;
+      walk(root, rel, visit);
+    } else {
+      visit(rel, false);
+    }
+  }
+}

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

@@ -16,6 +16,8 @@ import {
   phaseKind,
   isEditPhase,
   isGatePhase,
+  resolveSwarmMinimum,
+  validatePhaseArtifactContent,
   writeJson,
   saveActiveRun,
 } from "./lib.mjs";
@@ -55,11 +57,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, {
@@ -135,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/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/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();
   }