@luizsantiago/spec-guardrails 3.1.10 → 3.2.0

package/README.md

@@ -11,7 +11,7 @@
 | **Solution** | One kit, two deliberate modes: **Process** (Node only) for a flexible spec-driven workflow; **Brakes** (Node + Python) for the **full product** — structural gates that exit non-zero when paperwork or evidence is missing. You approve specs/tasks in both. |
 | **Result** | Traceable `.specs/` memory, fewer fake finishes, cheaper turns (~70% less skill text on planning). Choose Process for light ceremony; add Python when you want the [Guarantees matrix](#guarantees-matrix) enforced automatically. |
 
-npm: [`@luizsantiago/spec-guardrails`](https://www.npmjs.com/package/@luizsantiago/spec-guardrails) **3.1.x**
+npm: [`@luizsantiago/spec-guardrails`](https://www.npmjs.com/package/@luizsantiago/spec-guardrails) **3.2.x**
 
 ---
 
@@ -41,6 +41,17 @@ npx @luizsantiago/spec-guardrails install
 
 Re-run `install` anytime to refresh skills; your `.specs/` decisions and `STATE.md` are kept.
 
+### Governance focus (3.2+)
+
+Spec Guardrails is a **single product**: governance, evidence, verification, and controlled execution for agentic software development — not a bundle of companion packages.
+
+| Capability | What it does |
+| --- | --- |
+| **Artifact gates** | Structural quality for spec, tasks, and cross-artifact consistency — with **blocking / warning / info** severity |
+| **Parallel waves** | `loop-plan` computes safe parallel groups; `workspace-prepare` isolates tasks in git worktrees |
+| **Execution policy** | Budgets, path scope, and escalation rules in `.specs/config.yaml` — consult via `execution-policy` |
+| **Independent verify** | Fresh-context verification with evidence-or-zero (`validate-state`) |
+
 | Need | Command |
 | --- | --- |
 | First time / upgrade | `install` |
@@ -190,6 +201,7 @@ Full reference: **[Gates](docs/guide/gates.md)** · [Guarantees matrix](docs/gui
 | [Skills and hub](docs/guide/skills-and-hub.md) | What each skill file does |
 | [Gates](docs/guide/gates.md) | How each gate works |
 | [Platform parity](docs/guide/Platform-parity.md) | Shipped adapters (Cursor, Claude, Copilot, Codex) — core works with any agent |
+| [Restart PRD seed](docs/guide/Restart-prd-seed.md) | Clean-project PRD template for a single-package restart |
 | [FAQ](docs/guide/FAQ.md) | Common questions |
 | [Changelog](docs/CHANGELOG.md) | Full version history |
 
@@ -205,7 +217,8 @@ npx @luizsantiago/spec-guardrails install
 
 | Version | What you gain |
 | --- | --- |
-| **3.1.x** | Copilot/Codex/AGENTS.md adapters; doctor Process + Brakes scores; unified execution contracts; `validate-traceability` / `validate-quick`; `classify-change` / `feature-status` |
+| **3.2.x** | Single-package focus; artifact gate severity labels; git worktree isolation CLI; execution policy (budget/scope/escalation) |
+| **3.1.x** | Copilot/Codex/AGENTS.md adapters; doctor Process + Brakes scores; `validate-traceability` / `validate-quick`; `classify-change` / `feature-status` |
 | **3.0.x** | Final name Spec Guardrails; `.specs/guardrails/`; no dual-path ([Migration](docs/guide/Migration.md)) |
 | **2.2.x** | Seatbelt-era paths & markers; `doctor` Execute hints; docs split from README |
 | **2.1.x** | `loop-plan` + parallel `/loop` waves |

package/index.js

@@ -8,10 +8,22 @@ import { classifyChange, formatClassifyChange } from "./lib/classify-change.js";
 import { PACKAGE_VERSION, CLI_NAME } from "./lib/constants.js";
 import { phaseContext } from "./lib/config.js";
 import { doctor } from "./lib/doctor.js";
+import {
+  checkPathScope,
+  formatPolicyStatus,
+  loadExecutionPolicy,
+  loadPolicyState,
+  savePolicyState,
+} from "./lib/execution-policy.js";
 import { featureInit } from "./lib/feature.js";
 import { featureStatus, formatFeatureStatus } from "./lib/feature-status.js";
 import { GATE_COMMANDS, AUX_COMMANDS, runGate, runGuardrailsScript } from "./lib/gates.js";
 import { install } from "./lib/install.js";
+import {
+  cleanupWorkspaces,
+  formatWorkspaceResults,
+  prepareWorkspaces,
+} from "./lib/workspace-isolation.js";
 import {
   initProjectConfig,
   listPresets,
@@ -52,6 +64,19 @@ Commands:
   doctor [path]                      Audit guardrails readiness (score + next actions)
     [--json]                         Machine-readable output
     [--no-suggest]                   Hide per-check remediation hints
+  workspace-prepare <feature>        Create isolated git worktrees for parallel tasks
+    --tasks T1,T2                    Task ids to isolate (required)
+    [--base-ref HEAD]                Base ref for new worktrees
+    [--json]                         Machine-readable output
+  workspace-cleanup <feature>        Remove isolated worktrees for a feature
+    [--tasks T1,T2]                  Limit cleanup to specific tasks
+    [--force]                        Force-remove dirty worktrees
+    [--json]                         Machine-readable output
+  execution-policy status            Show configured budgets, scope, and runtime counters
+    [--json]                         Machine-readable output
+  execution-policy check-path <path> Check whether a relative path is allowed by scope policy
+    [--json]                         Machine-readable output
+  execution-policy record-retry <task>  Increment retry counter for a task id
   validate-spec [spec.md|feature]    Closure gate for a feature spec
   analyze-artifacts [feature]        Cross-artifact consistency before task approval
   validate-tasks [tasks.md|feature]  Granularity gate for a task breakdown
@@ -321,6 +346,144 @@ if (command === "--version" || command === "-v" || command === "version") {
     console.error(`❌ ${err.message}`);
     process.exit(1);
   }
+} else if (command === "workspace-prepare") {
+  try {
+    let json = false;
+    let baseRef = "HEAD";
+    let tasksRaw = "";
+    const positional = [];
+
+    for (let i = 0; i < args.length; i++) {
+      const arg = args[i];
+      if (arg === "--json") {
+        json = true;
+      } else if (arg === "--base-ref") {
+        baseRef = args[++i];
+        if (!baseRef) {
+          throw new Error("--base-ref requires a git ref");
+        }
+      } else if (arg === "--tasks") {
+        tasksRaw = args[++i] ?? "";
+        if (!tasksRaw) {
+          throw new Error("--tasks requires a comma-separated list (e.g. T1,T2)");
+        }
+      } else {
+        positional.push(arg);
+      }
+    }
+
+    const featureId = positional[0];
+    if (!featureId) {
+      throw new Error("Usage: workspace-prepare <feature> --tasks T1,T2");
+    }
+
+    const taskIds = tasksRaw.split(",").map((item) => item.trim()).filter(Boolean);
+    const results = await prepareWorkspaces(process.cwd(), { featureId, taskIds, baseRef });
+    process.stdout.write(formatWorkspaceResults(results, { json }));
+
+    if (results.some((item) => item.status === "failed")) {
+      process.exit(1);
+    }
+  } catch (err) {
+    console.error(`❌ ${err.message}`);
+    process.exit(1);
+  }
+} else if (command === "workspace-cleanup") {
+  try {
+    let json = false;
+    let force = false;
+    let tasksRaw = "";
+    const positional = [];
+
+    for (let i = 0; i < args.length; i++) {
+      const arg = args[i];
+      if (arg === "--json") {
+        json = true;
+      } else if (arg === "--force") {
+        force = true;
+      } else if (arg === "--tasks") {
+        tasksRaw = args[++i] ?? "";
+      } else {
+        positional.push(arg);
+      }
+    }
+
+    const featureId = positional[0];
+    if (!featureId) {
+      throw new Error("Usage: workspace-cleanup <feature> [--tasks T1,T2] [--force]");
+    }
+
+    const taskIds = tasksRaw
+      ? tasksRaw.split(",").map((item) => item.trim()).filter(Boolean)
+      : undefined;
+    const results = await cleanupWorkspaces(process.cwd(), { featureId, taskIds, force });
+    process.stdout.write(formatWorkspaceResults(results, { json }));
+
+    if (results.some((item) => item.status === "failed")) {
+      process.exit(1);
+    }
+  } catch (err) {
+    console.error(`❌ ${err.message}`);
+    process.exit(1);
+  }
+} else if (command === "execution-policy") {
+  try {
+    const sub = args[0];
+    let json = false;
+    const rest = [];
+
+    for (let i = 1; i < args.length; i++) {
+      if (args[i] === "--json") {
+        json = true;
+      } else {
+        rest.push(args[i]);
+      }
+    }
+
+    const cwd = process.cwd();
+    const policy = await loadExecutionPolicy(cwd);
+    const state = await loadPolicyState(cwd);
+
+    if (sub === "status") {
+      process.stdout.write(formatPolicyStatus(policy, state, { json }));
+    } else if (sub === "check-path") {
+      const relativePath = rest[0];
+      if (!relativePath) {
+        throw new Error("Usage: execution-policy check-path <relative-path>");
+      }
+      const result = checkPathScope(relativePath, policy);
+      if (json) {
+        console.log(JSON.stringify({ path: relativePath, ...result }, null, 2));
+      } else {
+        console.log(
+          `${relativePath}: ${result.allowed ? "allowed" : "blocked"} (${result.reason})`,
+        );
+      }
+      if (!result.allowed) {
+        process.exit(1);
+      }
+    } else if (sub === "record-retry") {
+      const taskId = rest[0];
+      if (!taskId) {
+        throw new Error("Usage: execution-policy record-retry <task-id>");
+      }
+      state.retries[taskId] = (state.retries[taskId] ?? 0) + 1;
+      state.iterations += 1;
+      await savePolicyState(cwd, state);
+      if (json) {
+        console.log(JSON.stringify({ taskId, retries: state.retries[taskId], state }, null, 2));
+      } else {
+        console.log(`Recorded retry for ${taskId}: ${state.retries[taskId]}`);
+      }
+    } else {
+      throw new Error(
+        "Usage: execution-policy status | check-path <path> | record-retry <task>",
+      );
+    }
+  } catch (err) {
+    console.error(`❌ ${err.message}`);
+    process.exit(1);
+  }
 } else if (command === "classify-change") {
   try {
     let json = false;

package/lib/archive.js

@@ -9,6 +9,7 @@ import {
 import { ensureDir, readFileSafe, writeFileSafe } from "./fs-utils.js";
 import { runGate } from "./gates.js";
 import { assertSafeDomainSlug } from "./slug-utils.js";
+import { isPassVerdict } from "./validation-verdict.js";
 import {
   featureDir,
   readFeatureArtifact,
@@ -23,15 +24,6 @@ Track milestones and archived features.
 
 `;
 
-/**
- * @param {string} text
- * @returns {boolean}
- */
-function validationPassed(text) {
-  const visible = text.replace(/<!--[\s\S]*?-->/g, "");
-  return /\b(?:PASS|PASSED)\b/.test(visible);
-}
-
 /**
  * @param {string} cwd
  * @param {string} featureId
@@ -150,7 +142,7 @@ export async function archiveFeature(featureArg, options = {}) {
       },
     );
 
-    if (!validationPassed(validationText)) {
+    if (!isPassVerdict(validationText)) {
       throw new Error(
         `validation.md for ${featureId} does not contain PASS/PASSED. Run validate-state first.`,
       );

package/lib/assets.js

@@ -55,8 +55,9 @@ export function resolveInstallSource(repoUrl) {
 /**
  * @param {string} remotePath
  * @param {string} destPath
+ * @param {{ boundary?: string }} [options]
  */
-export async function copyPackagedAsset(remotePath, destPath) {
+export async function copyPackagedAsset(remotePath, destPath, options = {}) {
   const source = packagedAssetPath(remotePath);
 
   try {
@@ -71,7 +72,7 @@ export async function copyPackagedAsset(remotePath, destPath) {
     throw err;
   }
 
-  await assertSafeWriteTarget(destPath);
+  await assertSafeWriteTarget(destPath, options);
 
   try {
     await fs.copyFile(source, destPath);
@@ -91,7 +92,7 @@ export async function copyPackagedAsset(remotePath, destPath) {
  * repo with no override (kept for the remote path; the default install no
  * longer uses it).
  *
- * @param {{ remotePath: string, destPath: string, repoUrl?: string, state: { warned: boolean }, log: (msg: string) => void }} params
+ * @param {{ remotePath: string, destPath: string, repoUrl?: string, state: { warned: boolean }, log: (msg: string) => void, boundary?: string }} params
  */
 export async function downloadRemoteAsset({
   remotePath,
@@ -99,9 +100,10 @@ export async function downloadRemoteAsset({
   repoUrl,
   state,
   log,
+  boundary,
 }) {
   try {
-    await downloadToFile(resolveAssetUrl(remotePath, repoUrl), destPath);
+    await downloadToFile(resolveAssetUrl(remotePath, repoUrl), destPath, { boundary });
     return;
   } catch (err) {
     const missingPinnedAsset =
@@ -123,15 +125,16 @@ export async function downloadRemoteAsset({
   await downloadToFile(
     resolveAssetUrl(remotePath, FALLBACK_REPO_URL),
     destPath,
+    { boundary },
   );
 }
 
 /**
- * @param {{ remotePath: string, destPath: string, source: ReturnType<typeof resolveInstallSource>, state: { warned: boolean }, log: (msg: string) => void }} params
+ * @param {{ remotePath: string, destPath: string, source: ReturnType<typeof resolveInstallSource>, state: { warned: boolean }, log: (msg: string) => void, boundary?: string }} params
  */
-export async function installAsset({ remotePath, destPath, source, state, log }) {
+export async function installAsset({ remotePath, destPath, source, state, log, boundary }) {
   if (source.mode === "package") {
-    await copyPackagedAsset(remotePath, destPath);
+    await copyPackagedAsset(remotePath, destPath, { boundary });
     return;
   }
 
@@ -141,5 +144,6 @@ export async function installAsset({ remotePath, destPath, source, state, log })
     repoUrl: source.repoUrl,
     state,
     log,
+    boundary,
   });
 }

package/lib/download.js

@@ -98,8 +98,8 @@ async function fetchWithSafeRedirects(startUrl) {
   );
 }
 
-export async function downloadToFile(url, destPath) {
-  await assertSafeWriteTarget(destPath);
+export async function downloadToFile(url, destPath, options = {}) {
+  await assertSafeWriteTarget(destPath, options);
 
   const response = await fetchWithSafeRedirects(url);
 

package/lib/execution-policy.js

@@ -0,0 +1,291 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { readFileSafe, writeFileSafe } from "./fs-utils.js";
+
+export const POLICY_STATE_PATH = ".specs/state/execution-policy.json";
+
+/** @type {import("./execution-policy.js").ExecutionPolicy} */
+export const DEFAULT_POLICY = {
+  budget: {
+    max_iterations: 5,
+    max_agent_runs: 12,
+    max_retries_per_task: 3,
+  },
+  scope: {
+    allowed_paths: [],
+    denied_paths: ["**/.env", "**/secrets/**", "**/production/**"],
+  },
+  escalation: {
+    on_scope_expansion: "human",
+    on_budget_exhaustion: "stop",
+    on_policy_violation: "block",
+  },
+};
+
+/**
+ * @typedef {{
+ *   budget: { max_iterations: number, max_agent_runs: number, max_retries_per_task: number },
+ *   scope: { allowed_paths: string[], denied_paths: string[] },
+ *   escalation: { on_scope_expansion: string, on_budget_exhaustion: string, on_policy_violation: string },
+ * }} ExecutionPolicy
+ */
+
+/**
+ * @typedef {{
+ *   iterations: number,
+ *   agent_runs: number,
+ *   retries: Record<string, number>,
+ * }} ExecutionPolicyState
+ */
+
+/**
+ * Parse budget/scope/escalation blocks from `.specs/config.yaml` text.
+ *
+ * @param {string} text
+ * @returns {Partial<ExecutionPolicy>}
+ */
+export function parseExecutionPolicySections(text) {
+  /** @type {Partial<ExecutionPolicy>} */
+  const result = {};
+  /** @type {"budget" | "scope" | "escalation" | null} */
+  let section = null;
+  /** @type {string | null} */
+  let listKey = null;
+
+  for (const line of text.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) {
+      continue;
+    }
+
+    const sectionMatch = trimmed.match(/^(budget|scope|escalation):\s*$/);
+    if (sectionMatch) {
+      section = /** @type {"budget" | "scope" | "escalation"} */ (sectionMatch[1]);
+      result[section] = result[section] ?? {};
+      listKey = null;
+      continue;
+    }
+
+    const kv = trimmed.match(/^([a-z_]+):\s*(.*)$/);
+    if (kv && section) {
+      const key = kv[1];
+      const rawValue = kv[2].replace(/^['"]|['"]$/g, "");
+      const bucket = /** @type {Record<string, unknown>} */ (result[section]);
+
+      if (rawValue === "") {
+        listKey = key;
+        bucket[listKey] = [];
+        continue;
+      }
+
+      if (/^\d+$/.test(rawValue)) {
+        bucket[key] = Number(rawValue);
+      } else {
+        bucket[key] = rawValue;
+      }
+      listKey = null;
+      continue;
+    }
+
+    const listItem = trimmed.match(/^-\s+(.+)$/);
+    if (listItem && section && listKey) {
+      const bucket = /** @type {Record<string, string[]>} */ (result[section]);
+      bucket[listKey] = bucket[listKey] ?? [];
+      bucket[listKey].push(listItem[1].replace(/^['"]|['"]$/g, ""));
+    }
+  }
+
+  return result;
+}
+
+/**
+ * @param {ExecutionPolicy} base
+ * @param {Partial<ExecutionPolicy>} overlay
+ * @returns {ExecutionPolicy}
+ */
+export function mergeExecutionPolicy(base, overlay) {
+  return {
+    budget: { ...base.budget, ...(overlay.budget ?? {}) },
+    scope: {
+      allowed_paths: overlay.scope?.allowed_paths ?? base.scope.allowed_paths,
+      denied_paths: overlay.scope?.denied_paths ?? base.scope.denied_paths,
+    },
+    escalation: { ...base.escalation, ...(overlay.escalation ?? {}) },
+  };
+}
+
+/**
+ * @param {string} cwd
+ * @returns {Promise<ExecutionPolicy>}
+ */
+export async function loadExecutionPolicy(cwd = process.cwd()) {
+  const configPath = path.join(cwd, ".specs/config.yaml");
+  let policy = structuredClone(DEFAULT_POLICY);
+
+  try {
+    const text = await readFileSafe(configPath);
+    policy = mergeExecutionPolicy(policy, parseExecutionPolicySections(text));
+  } catch (err) {
+    if (!/cannot read/i.test(String(err.message)) && err.code !== "ENOENT") {
+      throw err;
+    }
+  }
+
+  return policy;
+}
+
+/**
+ * @param {string} pattern
+ * @param {string} value
+ * @returns {boolean}
+ */
+export function matchGlobPattern(pattern, value) {
+  const normalizedPattern = pattern.replace(/\\/g, "/");
+  const normalizedValue = value.replace(/\\/g, "/");
+  const regex = new RegExp(
+    `^${normalizedPattern
+      .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+      .replace(/\*\*/g, ".*")
+      .replace(/\*/g, "[^/]*")}$`,
+  );
+  return regex.test(normalizedValue);
+}
+
+/**
+ * @param {string} relativePath
+ * @param {ExecutionPolicy} policy
+ * @returns {{ allowed: boolean, severity: "blocking" | "info", reason: string }}
+ */
+export function checkPathScope(relativePath, policy) {
+  const normalized = relativePath.replace(/\\/g, "/").replace(/^\.\//, "");
+
+  for (const denied of policy.scope.denied_paths) {
+    if (matchGlobPattern(denied, normalized)) {
+      return {
+        allowed: false,
+        severity: "blocking",
+        reason: `path matches denied pattern: ${denied}`,
+      };
+    }
+  }
+
+  if (!policy.scope.allowed_paths.length) {
+    return { allowed: true, severity: "info", reason: "no allowlist configured" };
+  }
+
+  for (const allowed of policy.scope.allowed_paths) {
+    if (matchGlobPattern(allowed, normalized)) {
+      return {
+        allowed: true,
+        severity: "info",
+        reason: `path matches allowed pattern: ${allowed}`,
+      };
+    }
+  }
+
+  return {
+    allowed: false,
+    severity: "blocking",
+    reason: "path outside configured allowed_paths",
+  };
+}
+
+/**
+ * @param {string} cwd
+ * @returns {Promise<ExecutionPolicyState>}
+ */
+export async function loadPolicyState(cwd = process.cwd()) {
+  const statePath = path.join(cwd, POLICY_STATE_PATH);
+  try {
+    const raw = await readFileSafe(statePath);
+    return /** @type {ExecutionPolicyState} */ (JSON.parse(raw));
+  } catch {
+    return { iterations: 0, agent_runs: 0, retries: {} };
+  }
+}
+
+/**
+ * @param {string} cwd
+ * @param {ExecutionPolicyState} state
+ */
+export async function savePolicyState(cwd, state) {
+  const statePath = path.join(cwd, POLICY_STATE_PATH);
+  await fs.mkdir(path.dirname(statePath), { recursive: true });
+  await writeFileSafe(statePath, `${JSON.stringify(state, null, 2)}\n`);
+}
+
+/**
+ * @param {ExecutionPolicyState} state
+ * @param {ExecutionPolicy} policy
+ * @returns {{ ok: boolean, issues: Array<{ severity: "blocking", message: string }> }}
+ */
+export function checkBudget(state, policy) {
+  /** @type {Array<{ severity: "blocking", message: string }>} */
+  const issues = [];
+
+  if (state.iterations >= policy.budget.max_iterations) {
+    issues.push({ severity: "blocking", message: "max_iterations budget exhausted" });
+  }
+
+  if (state.agent_runs >= policy.budget.max_agent_runs) {
+    issues.push({ severity: "blocking", message: "max_agent_runs budget exhausted" });
+  }
+
+  return { ok: issues.length === 0, issues };
+}
+
+/**
+ * @param {string} taskId
+ * @param {ExecutionPolicyState} state
+ * @param {ExecutionPolicy} policy
+ * @returns {{ ok: boolean, severity?: "blocking", message?: string, retries: number }}
+ */
+export function checkTaskRetries(taskId, state, policy) {
+  const retries = state.retries[taskId] ?? 0;
+  if (retries >= policy.budget.max_retries_per_task) {
+    return {
+      ok: false,
+      severity: "blocking",
+      message: `max_retries_per_task exhausted for ${taskId}`,
+      retries,
+    };
+  }
+  return { ok: true, retries };
+}
+
+/**
+ * @param {ExecutionPolicy} policy
+ * @param {ExecutionPolicyState} state
+ * @param {{ json?: boolean }} [options]
+ */
+export function formatPolicyStatus(policy, state, options = {}) {
+  const budget = checkBudget(state, policy);
+  const payload = {
+    policy,
+    state,
+    budget,
+    escalation: policy.escalation,
+  };
+
+  if (options.json) {
+    return JSON.stringify(payload, null, 2);
+  }
+
+  const lines = [
+    "Execution policy status:",
+    `  iterations: ${state.iterations}/${policy.budget.max_iterations}`,
+    `  agent_runs: ${state.agent_runs}/${policy.budget.max_agent_runs}`,
+    `  allowed_paths: ${policy.scope.allowed_paths.length ? policy.scope.allowed_paths.join(", ") : "(none — all non-denied paths allowed)"}`,
+    `  denied_paths: ${policy.scope.denied_paths.join(", ")}`,
+    `  budget_ok: ${budget.ok ? "yes" : "no"}`,
+  ];
+
+  if (!budget.ok) {
+    for (const issue of budget.issues) {
+      lines.push(`  blocking: ${issue.message}`);
+    }
+  }
+
+  return `${lines.join("\n")}\n`;
+}

package/lib/feature-status.js

@@ -9,6 +9,7 @@ import {
   readActiveFeatureFromState,
   resolveFeatureId,
 } from "./specs-utils.js";
+import { findVerdict } from "./validation-verdict.js";
 
 /**
  * @param {string} cwd
@@ -39,17 +40,6 @@ function summarizeTasks(tasksText) {
   };
 }
 
-/**
- * @param {string} validationText
- * @returns {string | null}
- */
-function readVerdict(validationText) {
-  const match = validationText.match(
-    /^\s*[-*]?\s*\*{0,2}(?:verdict|result|status)\*{0,2}\s*:\s*\*{0,2}([A-Za-z ]+)/im,
-  );
-  return match ? match[1].trim().toUpperCase() : null;
-}
-
 /**
  * @param {string} [featureArg]
  * @param {{ cwd?: string }} [options]
@@ -97,7 +87,7 @@ export async function featureStatus(featureArg, options = {}) {
   let verdict = null;
   if (artifacts.validation) {
     const text = await readFileSafe(path.join(dir, "validation.md"));
-    verdict = readVerdict(text);
+    verdict = findVerdict(text);
   }
 
   const executeHint = await resolveExecuteHint(cwd, featureId);

package/lib/feature.js

@@ -220,6 +220,39 @@ ${description.trim()}
   await writeFileSafe(specPath, stub);
 }
 
+/**
+ * Allocate a unique feature directory using exclusive mkdir (race-safe).
+ *
+ * @param {string} cwd
+ * @param {string} slug
+ * @param {number} [maxAttempts]
+ * @returns {Promise<{ featureId: string, featureDir: string }>}
+ */
+export async function allocateFeatureWorkspace(cwd, slug, maxAttempts = 10) {
+  const featuresRoot = path.join(cwd, FEATURES_DIR);
+  await ensureDir(featuresRoot);
+
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    const number = await nextFeatureNumber(cwd);
+    const featureId = formatFeatureId(number, slug);
+    const featureDirPath = path.join(featuresRoot, featureId);
+
+    try {
+      await fs.mkdir(featureDirPath);
+      return { featureId, featureDir: featureDirPath };
+    } catch (err) {
+      if (err.code === "EEXIST") {
+        continue;
+      }
+      throw err;
+    }
+  }
+
+  throw new Error(
+    `Could not allocate a unique feature id for "${slug}" after ${maxAttempts} attempts.`,
+  );
+}
+
 /**
  * Initialize a numbered feature workspace (Tier 0).
  *
@@ -235,19 +268,15 @@ export async function featureInit(description, options = {}) {
   }
 
   const slug = slugifyDescription(trimmed);
-  const number = await nextFeatureNumber(cwd);
-  const featureId = formatFeatureId(number, slug);
+  const { featureId, featureDir: featureDirPath } = await allocateFeatureWorkspace(cwd, slug);
 
   const resolvedConfig = await loadResolvedConfig(cwd);
   const branchPrefix =
     options.branchPrefix ?? readBranchPrefix(resolvedConfig) ?? DEFAULT_BRANCH_PREFIX;
   const branchName = featureBranchName(featureId, branchPrefix);
-  const featureDir = path.join(cwd, FEATURES_DIR, featureId);
-
-  await ensureDir(featureDir);
 
   if (!options.skipSpec) {
-    const specPath = path.join(featureDir, "spec.md");
+    const specPath = path.join(featureDirPath, "spec.md");
     try {
       await fs.access(specPath);
     } catch {

package/lib/fs-utils.js

@@ -1,16 +1,74 @@
 import fs from "node:fs/promises";
+import path from "node:path";
 
 function isPermissionError(err) {
   return err && (err.code === "EACCES" || err.code === "EPERM");
 }
 
+/**
+ * @param {string} child
+ * @param {string} parent
+ * @returns {boolean}
+ */
+function isInsidePath(child, parent) {
+  const resolvedChild = path.resolve(child);
+  const resolvedParent = path.resolve(parent);
+  if (resolvedChild === resolvedParent) {
+    return true;
+  }
+  const rel = path.relative(resolvedParent, resolvedChild);
+  return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
+}
+
+/**
+ * Refuse writes when an existing ancestor directory under `boundary` is a symlink.
+ *
+ * @param {string} destPath
+ * @param {string} boundary
+ */
+export async function assertNoSymlinkAncestors(destPath, boundary) {
+  const resolvedBoundary = path.resolve(boundary);
+  let current = path.dirname(path.resolve(destPath));
+
+  while (isInsidePath(current, resolvedBoundary) && current !== resolvedBoundary) {
+    try {
+      const st = await fs.lstat(current);
+      if (st.isSymbolicLink()) {
+        throw new Error(
+          `Refusing to write under symlinked directory: ${current} — ` +
+            "remove the link or choose another destination before installing.",
+        );
+      }
+    } catch (err) {
+      if (err.code === "ENOENT") {
+        // Parent not created yet — keep walking toward the boundary.
+      } else if (isPermissionError(err)) {
+        throw new Error(`Permission denied: cannot access ${current}`);
+      } else {
+        throw err;
+      }
+    }
+
+    const parent = path.dirname(current);
+    if (parent === current) {
+      break;
+    }
+    current = parent;
+  }
+}
+
 /**
  * Refuse to overwrite through a symlink (install must not clobber .env etc.).
  * Used for packaged copies, remote downloads, memory files, and `.cursorrules`.
  *
  * @param {string} destPath
+ * @param {{ boundary?: string }} [options]
  */
-export async function assertSafeWriteTarget(destPath) {
+export async function assertSafeWriteTarget(destPath, options = {}) {
+  if (options.boundary) {
+    await assertNoSymlinkAncestors(destPath, options.boundary);
+  }
+
   let st;
   try {
     st = await fs.lstat(destPath);
@@ -43,8 +101,8 @@ export async function ensureDir(dirPath) {
   }
 }
 
-export async function writeFileIfMissing(filePath, content) {
-  await assertSafeWriteTarget(filePath);
+export async function writeFileIfMissing(filePath, content, options = {}) {
+  await assertSafeWriteTarget(filePath, options);
 
   try {
     await fs.writeFile(filePath, content, { encoding: "utf8", flag: "wx" });
@@ -60,8 +118,8 @@ export async function writeFileIfMissing(filePath, content) {
   }
 }
 
-export async function appendFileSafe(filePath, content) {
-  await assertSafeWriteTarget(filePath);
+export async function appendFileSafe(filePath, content, options = {}) {
+  await assertSafeWriteTarget(filePath, options);
 
   try {
     await fs.appendFile(filePath, content, "utf8");
@@ -73,8 +131,8 @@ export async function appendFileSafe(filePath, content) {
   }
 }
 
-export async function writeFileSafe(filePath, content) {
-  await assertSafeWriteTarget(filePath);
+export async function writeFileSafe(filePath, content, options = {}) {
+  await assertSafeWriteTarget(filePath, options);
 
   try {
     await fs.writeFile(filePath, content, "utf8");

package/lib/install.js

@@ -40,7 +40,7 @@ export async function install(options = {}) {
   }
 
   const fetchAsset = (remotePath, destPath) =>
-    installAsset({ remotePath, destPath, source, state, log });
+    installAsset({ remotePath, destPath, source, state, log, boundary: cwd });
 
   log(`🚀 Installing ${DISPLAY_NAME}...`);
 

package/lib/memory.js

@@ -7,7 +7,9 @@ import {
 } from "./constants.js";
 import { ensureDir, readFileSafe, writeFileIfMissing } from "./fs-utils.js";
 
-export async function initGuardrailsMemory(cwd) {
+export async function initGuardrailsMemory(cwd, options = {}) {
+  const boundary = options.boundary ?? cwd;
+  const writeOptions = { boundary };
   const specsDir = path.join(cwd, ".specs");
   const featuresDir = path.join(specsDir, "features");
   const projectDir = path.join(specsDir, "project");
@@ -20,14 +22,17 @@ export async function initGuardrailsMemory(cwd) {
   const stateCreated = await writeFileIfMissing(
     path.join(specsDir, "STATE.md"),
     STATE_HEADER,
+    writeOptions,
   );
   const lessonsCreated = await writeFileIfMissing(
     path.join(specsDir, "LESSONS.md"),
     LESSONS_HEADER,
+    writeOptions,
   );
   await writeFileIfMissing(
     path.join(specsDir, "config.yaml.example"),
     await readFileSafe(packagedAssetPath("templates/config.yaml.example")),
+    writeOptions,
   );
 
   return { stateCreated, lessonsCreated };

package/lib/project-rules.js

@@ -194,14 +194,14 @@ export async function installProjectRules(cwd, options) {
       }
 
       if (!exists) {
-        await assertSafeWriteTarget(destPath);
+        await assertSafeWriteTarget(destPath, { boundary: cwd });
         await fs.rename(tmpPath, destPath);
         continue;
       }
 
       const existing = await fs.readFile(destPath, "utf8");
       const merged = mergeBaselineRule(existing, shipped);
-      await assertSafeWriteTarget(destPath);
+      await assertSafeWriteTarget(destPath, { boundary: cwd });
       await fs.writeFile(destPath, merged, "utf8");
       await fs.rm(tmpPath, { force: true });
     } catch (err) {

package/lib/validation-verdict.js

@@ -0,0 +1,101 @@
+const SECTION_START = /^#{2,6}\s/m;
+
+const VERDICT_INLINE =
+  /^\s*[-*]?\s*\*{0,2}(?:verdict|result|status)\*{0,2}\s*:\s*\*{0,2}([A-Za-z ]+)/im;
+
+const VERDICT_HEADING =
+  /^#{1,6}\s*(?:verdict|result|status)\s*$\s*\n+\s*\*{0,2}([A-Za-z ]+)/im;
+
+const PASS_VERDICTS = new Set(["PASS", "PASSED"]);
+
+/**
+ * @param {string} text
+ * @returns {string}
+ */
+function stripHtmlComments(text) {
+  return text.replace(/<!--[\s\S]*?-->/g, (match) =>
+    "\n".repeat((match.match(/\n/g) ?? []).length),
+  );
+}
+
+/**
+ * Blank fenced code so structural regexes ignore sample snippets.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+function maskFencedBlocks(text) {
+  const lines = text.split("\n");
+  const masked = [];
+  let inFence = false;
+
+  for (const line of lines) {
+    if (line.trimStart().startsWith("```")) {
+      inFence = !inFence;
+      masked.push("");
+      continue;
+    }
+    masked.push(inFence ? "" : line);
+  }
+
+  return masked.join("\n");
+}
+
+/**
+ * @param {string} text
+ * @returns {string}
+ */
+export function visibleMarkdown(text) {
+  return maskFencedBlocks(stripHtmlComments(text));
+}
+
+/**
+ * @param {string} text
+ * @returns {string}
+ */
+function validationPreamble(text) {
+  const visible = visibleMarkdown(text);
+  const match = SECTION_START.exec(visible);
+  if (!match) {
+    return visible;
+  }
+  return visible.slice(0, match.index);
+}
+
+/**
+ * @param {string} raw
+ * @returns {string}
+ */
+function normalizeVerdict(raw) {
+  return raw.trim().replace(/\s+/g, " ").toUpperCase();
+}
+
+/**
+ * Match validate_state.py: verdict only in preamble or under a ## Verdict heading.
+ *
+ * @param {string} text
+ * @returns {string | null}
+ */
+export function findVerdict(text) {
+  const preamble = validationPreamble(text);
+  const inlineMatch = preamble.match(VERDICT_INLINE);
+  if (inlineMatch) {
+    return normalizeVerdict(inlineMatch[1]);
+  }
+
+  const headingMatch = visibleMarkdown(text).match(VERDICT_HEADING);
+  if (headingMatch) {
+    return normalizeVerdict(headingMatch[1]);
+  }
+
+  return null;
+}
+
+/**
+ * @param {string} text
+ * @returns {boolean}
+ */
+export function isPassVerdict(text) {
+  const verdict = findVerdict(text);
+  return verdict !== null && PASS_VERDICTS.has(verdict);
+}

package/lib/workspace-isolation.js

@@ -0,0 +1,156 @@
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+export const WORKSPACES_ROOT = ".specs/workspaces";
+
+/**
+ * @param {string} cwd
+ * @param {string} featureId
+ * @param {string} taskId
+ * @returns {string}
+ */
+export function workspacePath(cwd, featureId, taskId) {
+  return path.join(cwd, WORKSPACES_ROOT, featureId, taskId);
+}
+
+/**
+ * @param {string} cwd
+ * @returns {Promise<boolean>}
+ */
+export async function isGitRepository(cwd) {
+  try {
+    await execFileAsync("git", ["rev-parse", "--git-dir"], { cwd });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {string} cwd
+ * @param {string} featureId
+ * @returns {Promise<string[]>}
+ */
+export async function listWorkspacePaths(cwd, featureId) {
+  const base = path.join(cwd, WORKSPACES_ROOT, featureId);
+  try {
+    const entries = await fs.readdir(base, { withFileTypes: true });
+    return entries.filter((entry) => entry.isDirectory()).map((entry) => path.join(base, entry.name));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Create isolated git worktrees for parallel Execute tasks.
+ *
+ * @param {string} cwd
+ * @param {{ featureId: string, taskIds: string[], baseRef?: string }} options
+ * @returns {Promise<Array<{ taskId: string, path: string, branch?: string, status: string, error?: string }>>}
+ */
+export async function prepareWorkspaces(cwd, { featureId, taskIds, baseRef = "HEAD" }) {
+  if (!(await isGitRepository(cwd))) {
+    throw new Error("workspace-prepare requires a git repository");
+  }
+
+  if (!taskIds.length) {
+    throw new Error("workspace-prepare requires at least one task id (e.g. T1,T2)");
+  }
+
+  /** @type {Array<{ taskId: string, path: string, branch?: string, status: string, error?: string }>} */
+  const results = [];
+
+  for (const taskId of taskIds) {
+    const wtPath = workspacePath(cwd, featureId, taskId);
+    await fs.mkdir(path.dirname(wtPath), { recursive: true });
+
+    try {
+      await fs.access(wtPath);
+      results.push({ taskId, path: wtPath, status: "exists" });
+      continue;
+    } catch {
+      // create new worktree
+    }
+
+    const branchName = `guardrails/ws-${featureId}-${taskId}`;
+    try {
+      await execFileAsync(
+        "git",
+        ["worktree", "add", "-B", branchName, wtPath, baseRef],
+        { cwd },
+      );
+      results.push({ taskId, path: wtPath, branch: branchName, status: "created" });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      results.push({ taskId, path: wtPath, status: "failed", error: message });
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Remove prepared worktrees for a feature.
+ *
+ * @param {string} cwd
+ * @param {{ featureId: string, taskIds?: string[], force?: boolean }} options
+ * @returns {Promise<Array<{ path: string, status: string, error?: string }>>}
+ */
+export async function cleanupWorkspaces(cwd, { featureId, taskIds, force = false }) {
+  if (!(await isGitRepository(cwd))) {
+    throw new Error("workspace-cleanup requires a git repository");
+  }
+
+  const targets = taskIds?.length
+    ? taskIds.map((taskId) => workspacePath(cwd, featureId, taskId))
+    : await listWorkspacePaths(cwd, featureId);
+
+  /** @type {Array<{ path: string, status: string, error?: string }>} */
+  const results = [];
+
+  for (const wtPath of targets) {
+    try {
+      await fs.access(wtPath);
+    } catch {
+      results.push({ path: wtPath, status: "missing" });
+      continue;
+    }
+
+    const args = ["worktree", "remove", wtPath];
+    if (force) {
+      args.push("--force");
+    }
+
+    try {
+      await execFileAsync("git", args, { cwd });
+      results.push({ path: wtPath, status: "removed" });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      results.push({ path: wtPath, status: "failed", error: message });
+    }
+  }
+
+  return results;
+}
+
+/**
+ * @param {ReturnType<typeof prepareWorkspaces> extends Promise<infer T> ? T : never} results
+ * @param {{ json?: boolean }} [options]
+ */
+export function formatWorkspaceResults(results, options = {}) {
+  if (options.json) {
+    return JSON.stringify({ workspaces: results }, null, 2);
+  }
+
+  const lines = ["Workspace isolation results:"];
+  for (const item of results) {
+    const branch = item.branch ? ` (${item.branch})` : "";
+    const error = item.error ? ` — ${item.error}` : "";
+    lines.push(`  ${item.taskId ?? path.basename(item.path)}: ${item.status}${branch}${error}`);
+  }
+  return `${lines.join("\n")}\n`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luizsantiago/spec-guardrails",
-  "version": "3.1.10",
+  "version": "3.2.0",
   "description": "Keep AI coding agents honest — specify the work, prove each step, verify independently. Process mode (Node) for flexibility; Brakes mode (Node + Python) for structural gates and a Guarantees matrix. Progressive loading, independent verify — any AI agent.",
   "type": "module",
   "bin": {
@@ -12,7 +12,7 @@
   "scripts": {
     "guardrails": "node index.js",
     "test": "npm run test:node && npm run test:gates",
-    "test:node": "node --test test/install.test.js test/test_feature_init.test.js test/test_config.test.js test/test_archive.test.js test/test_delta_merge.test.js test/test_presets.test.js test/test_brownfield.test.js test/test_doctor.test.js test/test_token_cost.test.js test/test_next_steps.test.js test/test_classify_change.test.js test/test_feature_status.test.js test/test_agent_contract.test.js test/test_gates_python.test.js test/test_specs_utils.test.js",
+    "test:node": "node --test test/install.test.js test/test_feature_init.test.js test/test_config.test.js test/test_archive.test.js test/test_delta_merge.test.js test/test_presets.test.js test/test_brownfield.test.js test/test_doctor.test.js test/test_token_cost.test.js test/test_next_steps.test.js test/test_classify_change.test.js test/test_feature_status.test.js test/test_agent_contract.test.js test/test_gates_python.test.js test/test_specs_utils.test.js test/test_validation_verdict.test.js test/test_execution_policy.test.js test/test_workspace_isolation.test.js",
     "test:gates": "node test/run-gate-tests.mjs",
     "prepublishOnly": "npm test"
   },

package/scripts/_common.py

@@ -74,14 +74,14 @@ class Report:
         print(f"[{self.gate}] {status} - {self.target}")
 
         for check in self.checks:
-            print(f"  ok      {check}")
+            print(f"  info      {check}")
         for warning in self.warnings:
-            print(f"  warn    {warning}")
+            print(f"  warning   {warning}")
         for error in self.errors:
-            print(f"  error   {error}")
+            print(f"  blocking  {error}")
 
         if strict and self.warnings and self.passed:
-            print("  error   strict mode: warnings are treated as failures")
+            print("  blocking  strict mode: warnings are treated as failures")
             return EXIT_FAILED
 
         if not self.passed:
@@ -91,6 +91,12 @@ class Report:
             )
             return EXIT_FAILED
 
+        if self.warnings:
+            print(
+                f"\n{len(self.warnings)} warning(s), 0 blocking — gate passed "
+                "(use --strict to treat warnings as blocking)"
+            )
+
         return EXIT_OK
 
 

package/scripts/validate_spec.py

@@ -71,6 +71,14 @@ DELTA_SECTIONS = (
     ("REMOVED Requirements", "removed"),
 )
 CLARIFICATION = re.compile(r"\[NEEDS CLARIFICATION(?:\s*:\s*[^\]]+)?\]", re.IGNORECASE)
+AMBIGUOUS_TERMS = re.compile(
+    r"\b(etc\.?|and so on|as appropriate|as needed|somehow|maybe|when possible)\b",
+    re.IGNORECASE,
+)
+OUT_OF_SCOPE_HEADING = re.compile(
+    r"^(?P<level>#{2,6})\s*Out of Scope\b",
+    re.MULTILINE | re.IGNORECASE,
+)
 REMOVED_ID = re.compile(r"^\s*(?:-\s*)?(?P<id>[A-Z][A-Z0-9]{1,9}-\d{2,4})\b", re.MULTILINE)
 
 
@@ -159,6 +167,11 @@ def validate_requirement_block(
 
         for item in criteria:
             excerpt = item if len(item) <= 70 else f"{item[:67]}..."
+            if AMBIGUOUS_TERMS.search(item):
+                report.warn(
+                    f"{label} {requirement_id}: ambiguous acceptance criterion "
+                    f"(prefer concrete, testable language): '{excerpt}'"
+                )
             if not NORMATIVE_VERB.search(item):
                 report.error(
                     f"{label} {requirement_id}: criterion is not testable, it states no "
@@ -248,6 +261,21 @@ def acceptance_lines(body: str) -> list[str]:
     return lines
 
 
+def validate_out_of_scope(report: Report, text: str) -> None:
+    body = section_body(text, OUT_OF_SCOPE_HEADING)
+    if body is None:
+        return
+
+    stripped = body.strip()
+    if not stripped or re.fullmatch(r"-\s*(none|n/a)\s*", stripped, re.IGNORECASE):
+        report.warn(
+            "Out of Scope section is empty or 'none' — explicit scope boundaries are recommended"
+        )
+        return
+
+    report.ok("Out of Scope section documents explicit boundaries")
+
+
 def build_report(target: str, text: str) -> Report:
     report = Report(gate=GATE, target=target)
     visible = visible_markdown(text)
@@ -299,6 +327,8 @@ def build_report(target: str, text: str) -> Report:
         else:
             validate_requirement_block(report, requirements, "Requirements")
 
+        validate_out_of_scope(report, visible)
+
     for malformed in MALFORMED_ID.finditer(visible):
         raw = malformed.group(0).lstrip("# ").strip()
         if not REQUIREMENT_HEADING.match(f"### {raw}"):

package/skills/references/implement.md

@@ -26,8 +26,29 @@ Orchestrate tasks from `tasks.md` and `task-graph.md`: **parallel waves with sub
 3. Run `python3 .specs/guardrails/scripts/validate_tasks.py` when a formal `tasks.md` exists.
 4. If Tasks was skipped, list the atomic steps inline now. More than 5 steps or real dependencies means the Tasks phase was skipped in error — stop and create `tasks.md`.
 5. **Plan the wave** — run `python3 .specs/guardrails/scripts/loop_plan.py [feature]` (or `loop-plan --json`) at the start of Execute and after every batch completes. It lists the next runnable tasks and marks **parallel groups** (disjoint `Files`) vs inline work.
-6. When `loop-plan` shows a **parallel group** (2+ tasks), offer sub-agent dispatch per `task-graph-engineering.md` and `sub-agents.md`. Offer and wait; never auto-spawn. Large features (roughly 8+ tasks total) also warrant batching across waves.
-7. Confirm you are the only writer for each file this task names. Two parallel tasks never share a file in the same round.
+6. When `loop-plan` shows a **parallel group** (2+ tasks), prepare isolated workspaces before dispatch:
+
+```bash
+npx @luizsantiago/spec-guardrails workspace-prepare [feature] --tasks T1,T2
+```
+
+Each worker runs in its own git worktree under `.specs/workspaces/[feature]/`. After local verification and merge, clean up:
+
+```bash
+npx @luizsantiago/spec-guardrails workspace-cleanup [feature] --tasks T1,T2 --force
+```
+
+7. Consult execution policy before touching files outside the task list:
+
+```bash
+npx @luizsantiago/spec-guardrails execution-policy check-path src/auth.ts
+npx @luizsantiago/spec-guardrails execution-policy status
+```
+
+Record gate retries with `execution-policy record-retry T1` when a task fails its gate (respects `max_retries_per_task` in `.specs/config.yaml`).
+
+8. When `loop-plan` shows a **parallel group** (2+ tasks), offer sub-agent dispatch per `task-graph-engineering.md` and `sub-agents.md`. Offer and wait; never auto-spawn. Large features (roughly 8+ tasks total) also warrant batching across waves.
+9. Confirm you are the only writer for each file this task names. Two parallel tasks never share a file in the same round.
 
 ## Orchestration (each /loop round)
 

package/skills/references/sub-agents.md

@@ -35,12 +35,15 @@ Hand each worker exactly this and nothing else from sibling features:
 - Feature: [feature]
 - Batch: B[n] of [total]
 - Tasks: T[a] … T[b] (in order)
+- Workspace: `.specs/workspaces/[feature]/T[n]` (git worktree — do not edit the main tree)
 - Spec excerpt: only the REQ IDs those tasks name
 - Files ownership: the union of those tasks' Files fields (exclusive)
 - Constraints: AD-NNN that apply; confirmed lessons that apply
 - Forbidden: git push, deploy, editing files outside ownership, spawning further sub-agents
 ```
 
+Before dispatch, the orchestrator runs `workspace-prepare [feature] --tasks …`. Each worker verifies and commits inside its worktree only. The merge owner integrates into the main tree, runs the project harness once, then `workspace-cleanup [feature] --force`.
+
 Load per `context-limits.md`. Do not paste the author's chat.
 
 ## Worker loop

package/templates/config.yaml.example

@@ -21,6 +21,24 @@ rules:
   verify:
     - Evidence must cite test file:line paths
 
+# Execution policy (optional — soft enforcement via CLI + skills)
+budget:
+  max_iterations: 5
+  max_agent_runs: 12
+  max_retries_per_task: 3
+
+scope:
+  allowed_paths: []
+  denied_paths:
+    - "**/.env"
+    - "**/secrets/**"
+    - "**/production/**"
+
+escalation:
+  on_scope_expansion: human
+  on_budget_exhaustion: stop
+  on_policy_violation: block
+
 # Project-specific overrides (appended on top of preset + rules above):
 # overrides:
 #   rules: