@luizsantiago/spec-guardrails 3.2.1 → 3.4.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.2.x**
+npm: [`@luizsantiago/spec-guardrails`](https://www.npmjs.com/package/@luizsantiago/spec-guardrails) **3.4.x**
 
 ---
 
@@ -217,6 +217,8 @@ npx @luizsantiago/spec-guardrails install
 
 | Version | What you gain |
 | --- | --- |
+| **3.4.x** | Contextual guards (`context-guard`); FTS memory search (`memory-search`) |
+| **3.3.x** | Intent/effect policy — `check-path --op read|write|delete` and `effects` config block |
 | **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)) |

package/index.js

@@ -5,6 +5,13 @@ import path from "node:path";
 import { archiveFeature } from "./lib/archive.js";
 import { projectInit } from "./lib/brownfield.js";
 import { classifyChange, formatClassifyChange } from "./lib/classify-change.js";
+import {
+  checkBeforeComplete,
+  checkBeforeEdit,
+  evaluateExecuteContext,
+  formatCheckBeforeEdit,
+  formatContextGuardStatus,
+} from "./lib/context-guard.js";
 import { PACKAGE_VERSION, CLI_NAME } from "./lib/constants.js";
 import { phaseContext } from "./lib/config.js";
 import { doctor } from "./lib/doctor.js";
@@ -81,6 +88,7 @@ Commands:
   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
+    [--op read|write|delete]         Intended operation (default: inferred from path)
     [--json]                         Machine-readable output
   execution-policy record-retry <task>  Increment retry counter for a task id (blocks at limit)
   execution-policy record-run        Increment agent-run counter (blocks at budget)
@@ -88,6 +96,18 @@ Commands:
   memory-query --from <id>           Bounded context package from the knowledge graph
     [--depth N]                      Traversal depth (default 2)
     [--json]                         Machine-readable output
+  memory-search <query>              Full-text search over the memory index (FTS5)
+    [--limit N]                      Max results (default 10)
+    [--json]                         Machine-readable output
+  context-guard status               Execute readiness from STATE + tasks.md
+    [--json]                         Machine-readable output
+  context-guard check-edit <path>    Contextual guard before editing a file
+    [--op read|write|delete]         Intended operation (default: inferred)
+    [--no-strict-files]              Skip task Files allowlist check
+    [--json]                         Machine-readable output
+  context-guard check-complete       Contextual guard before claiming feature done
+    [feature]                        Feature id (default: active in STATE)
+    [--json]                         Machine-readable output
   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
@@ -482,20 +502,41 @@ if (command === "--version" || command === "-v" || command === "version") {
     if (sub === "status") {
       process.stdout.write(formatPolicyStatus(policy, state, { json }));
     } else if (sub === "check-path") {
-      const relativePath = rest[0];
+      let operation;
+      const positional = [];
+
+      for (let i = 0; i < rest.length; i++) {
+        const arg = rest[i];
+        if (arg === "--op") {
+          operation = rest[++i];
+          if (!operation) {
+            throw new Error("--op requires read, write, or delete");
+          }
+        } else {
+          positional.push(arg);
+        }
+      }
+
+      const relativePath = positional[0];
       if (!relativePath) {
-        throw new Error("Usage: execution-policy check-path <relative-path>");
+        throw new Error(
+          "Usage: execution-policy check-path <relative-path> [--op read|write|delete]",
+        );
       }
-      const result = resolvePathCheck(relativePath, policy);
+      const result = resolvePathCheck(relativePath, policy, { operation });
       if (json) {
         console.log(JSON.stringify({ path: relativePath, ...result }, null, 2));
       } else {
         const label = result.allowed
-          ? "allowed"
+          ? result.severity === "warning"
+            ? "allowed (warn)"
+            : "allowed"
           : result.severity === "warning"
             ? "blocked (warn)"
             : "blocked";
-        console.log(`${relativePath}: ${label} (${result.reason})`);
+        console.log(
+          `${relativePath} [${result.operation}]: ${label} (${result.reason})`,
+        );
       }
       if (result.exitCode !== 0) {
         process.exit(result.exitCode);
@@ -543,6 +584,83 @@ if (command === "--version" || command === "-v" || command === "version") {
     console.error(`❌ ${err.message}`);
     process.exit(1);
   }
+} else if (command === "context-guard") {
+  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();
+
+    if (sub === "status") {
+      const context = await evaluateExecuteContext(cwd);
+      process.stdout.write(formatContextGuardStatus(context, { json }));
+      if (!context.ok && context.severity === "blocking") {
+        process.exit(1);
+      }
+    } else if (sub === "check-edit") {
+      let operation;
+      let strictFiles = true;
+      const positional = [];
+
+      for (let i = 0; i < rest.length; i++) {
+        const arg = rest[i];
+        if (arg === "--no-strict-files") {
+          strictFiles = false;
+        } else if (arg === "--op") {
+          operation = rest[++i];
+          if (!operation) {
+            throw new Error("--op requires read, write, or delete");
+          }
+        } else {
+          positional.push(arg);
+        }
+      }
+
+      const relativePath = positional[0];
+      if (!relativePath) {
+        throw new Error(
+          "Usage: context-guard check-edit <relative-path> [--op read|write|delete] [--no-strict-files]",
+        );
+      }
+
+      const result = await checkBeforeEdit(cwd, relativePath, { operation, strictFiles });
+      process.stdout.write(formatCheckBeforeEdit(result, relativePath, { json }));
+      if (result.exitCode !== 0) {
+        process.exit(result.exitCode);
+      }
+    } else if (sub === "check-complete") {
+      const featureId = rest[0];
+      const result = await checkBeforeComplete(cwd, featureId);
+      if (json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        const label = result.allowed ? "ready" : "blocked";
+        console.log(`Feature ${result.featureId}: ${label}`);
+        for (const message of result.messages) {
+          console.log(`  ${message}`);
+        }
+      }
+      if (result.exitCode !== 0) {
+        process.exit(result.exitCode);
+      }
+    } else {
+      throw new Error(
+        "Usage: context-guard status | check-edit <path> | check-complete [feature]",
+      );
+    }
+  } catch (err) {
+    console.error(`❌ ${err.message}`);
+    process.exit(1);
+  }
 } else if (command === "classify-change") {
   try {
     let json = false;

package/lib/constants.js

@@ -110,6 +110,7 @@ export const SCRIPT_ASSETS = [
   { file: "loop_plan.py", remotePath: "scripts/loop_plan.py" },
   { file: "memory_index.py", remotePath: "scripts/memory_index.py" },
   { file: "memory_query.py", remotePath: "scripts/memory_query.py" },
+  { file: "memory_search.py", remotePath: "scripts/memory_search.py" },
 ];
 
 /** @type {{ file: string, remotePath: string }[]} */

package/lib/context-guard.js

@@ -0,0 +1,340 @@
+import path from "node:path";
+
+import { loadExecutionPolicy, resolvePathCheck } from "./execution-policy.js";
+import { readFileSafe } from "./fs-utils.js";
+import { featureDir, readActiveFeatureFromState, resolveFeatureId } from "./specs-utils.js";
+import { findVerdict } from "./validation-verdict.js";
+
+const TASK_FILES = /^\s*[-*]?\s*\*{0,2}Files\*{0,2}\s*:\s*(.+)$/gim;
+
+/**
+ * @param {string} cwd
+ * @returns {Promise<{ featureId: string | null, phase: string | null }>}
+ */
+export async function readStateContext(cwd) {
+  const statePath = path.join(cwd, ".specs/STATE.md");
+  let content = "";
+
+  try {
+    content = await readFileSafe(statePath);
+  } catch {
+    return { featureId: null, phase: null };
+  }
+
+  const featureId = await readActiveFeatureFromState(cwd);
+  const phaseMatch = content.match(/^-\s*Phase:\s*(.+)$/m);
+  const phase = phaseMatch ? phaseMatch[1].trim() : null;
+
+  return { featureId, phase: phase && !/^—|-$/i.test(phase) ? phase : null };
+}
+
+/**
+ * @param {string} tasksText
+ * @returns {number}
+ */
+export function countOpenTasks(tasksText) {
+  return [...tasksText.matchAll(/^\s*[-*]\s*\[ \]\s+/gm)].length;
+}
+
+/**
+ * @param {string} tasksText
+ * @returns {Set<string>}
+ */
+export function collectTaskFilePaths(tasksText) {
+  /** @type {Set<string>} */
+  const files = new Set();
+
+  for (const match of tasksText.matchAll(TASK_FILES)) {
+    const raw = match[1].trim();
+    if (!raw || /^—|-$|none|n\/a$/i.test(raw)) {
+      continue;
+    }
+    for (const part of raw.split(/[,;]/)) {
+      const cleaned = part.trim().replace(/^`|`$/g, "");
+      if (cleaned) {
+        files.add(cleaned.replace(/\\/g, "/"));
+      }
+    }
+  }
+
+  return files;
+}
+
+/**
+ * @param {string} relativePath
+ * @param {Set<string>} approvedFiles
+ * @returns {boolean}
+ */
+export function pathInApprovedTaskFiles(relativePath, approvedFiles) {
+  if (!approvedFiles.size) {
+    return true;
+  }
+
+  const normalized = relativePath.replace(/\\/g, "/").replace(/^\.\//, "");
+  for (const approved of approvedFiles) {
+    const pattern = approved.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*/g, ".*").replace(/\*/g, "[^/]*");
+    if (new RegExp(`^${pattern}$`).test(normalized)) {
+      return true;
+    }
+    if (normalized === approved || normalized.endsWith(`/${approved}`)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * @param {string} cwd
+ * @param {{ featureId?: string }} [options]
+ * @returns {Promise<{
+ *   ok: boolean,
+ *   severity: "blocking" | "warning" | "info",
+ *   featureId: string | null,
+ *   phase: string | null,
+ *   openTasks: number,
+ *   messages: string[],
+ * }>}
+ */
+export async function evaluateExecuteContext(cwd, options = {}) {
+  const messages = [];
+  const state = await readStateContext(cwd);
+  let featureId = options.featureId ?? state.featureId;
+
+  if (!featureId) {
+    return {
+      ok: false,
+      severity: "blocking",
+      featureId: null,
+      phase: state.phase,
+      openTasks: 0,
+      messages: ["no active feature in .specs/STATE.md — run feature-init or /specify first"],
+    };
+  }
+
+  const tasksPath = path.join(featureDir(featureId, cwd), "tasks.md");
+  let tasksText = "";
+
+  try {
+    tasksText = await readFileSafe(tasksPath);
+  } catch {
+    return {
+      ok: false,
+      severity: "blocking",
+      featureId,
+      phase: state.phase,
+      openTasks: 0,
+      messages: [`tasks.md missing for active feature ${featureId}`],
+    };
+  }
+
+  const openTasks = countOpenTasks(tasksText);
+  if (openTasks === 0) {
+    messages.push("no open tasks in tasks.md — Execute may be complete; run /verify instead");
+  } else {
+    messages.push(`${openTasks} open task(s) in tasks.md`);
+  }
+
+  const severity = openTasks === 0 ? "warning" : "info";
+  return {
+    ok: openTasks > 0,
+    severity,
+    featureId,
+    phase: state.phase,
+    openTasks,
+    messages,
+  };
+}
+
+/**
+ * @param {string} cwd
+ * @param {string} relativePath
+ * @param {{ operation?: string, featureId?: string, strictFiles?: boolean }} [options]
+ */
+export async function checkBeforeEdit(cwd, relativePath, options = {}) {
+  const execute = await evaluateExecuteContext(cwd, { featureId: options.featureId });
+  const policy = await loadExecutionPolicy(cwd);
+  const pathCheck = resolvePathCheck(relativePath, policy, {
+    operation: options.operation,
+  });
+
+  /** @type {string[]} */
+  const messages = [...execute.messages];
+
+  if (!execute.ok && execute.severity === "blocking") {
+    return {
+      allowed: false,
+      exitCode: 1,
+      severity: "blocking",
+      operation: pathCheck.operation,
+      featureId: execute.featureId,
+      messages,
+    };
+  }
+
+  if (!pathCheck.allowed) {
+    messages.push(pathCheck.reason);
+    return {
+      allowed: false,
+      exitCode: pathCheck.exitCode,
+      severity: pathCheck.severity,
+      operation: pathCheck.operation,
+      featureId: execute.featureId,
+      messages,
+    };
+  }
+
+  if (options.strictFiles !== false && execute.featureId) {
+    const tasksText = await readFileSafe(
+      path.join(featureDir(execute.featureId, cwd), "tasks.md"),
+    );
+    const approved = collectTaskFilePaths(tasksText);
+    if (approved.size && !pathInApprovedTaskFiles(relativePath, approved)) {
+      messages.push("path is not listed in any task Files field — escalate or update tasks.md");
+      const mode = policy.escalation.on_scope_expansion ?? "human";
+      if (mode === "human") {
+        return {
+          allowed: false,
+          exitCode: 1,
+          severity: "blocking",
+          operation: pathCheck.operation,
+          featureId: execute.featureId,
+          messages,
+        };
+      }
+    }
+  }
+
+  if (pathCheck.severity === "warning") {
+    messages.push(pathCheck.reason);
+  }
+
+  if (!execute.ok && execute.severity === "warning") {
+    messages.push(...execute.messages);
+  }
+
+  return {
+    allowed: true,
+    exitCode: 0,
+    severity: pathCheck.severity === "warning" || execute.severity === "warning" ? "warning" : "info",
+    operation: pathCheck.operation,
+    featureId: execute.featureId,
+    messages,
+  };
+}
+
+/**
+ * @param {string} cwd
+ * @param {string} [featureRaw]
+ */
+export async function checkBeforeComplete(cwd, featureRaw) {
+  const featureId = featureRaw ? await resolveFeatureId(featureRaw, cwd) : await resolveFeatureId(undefined, cwd);
+  const dir = featureDir(featureId, cwd);
+  /** @type {string[]} */
+  const messages = [];
+
+  let tasksText = "";
+  try {
+    tasksText = await readFileSafe(path.join(dir, "tasks.md"));
+  } catch {
+    return {
+      allowed: false,
+      exitCode: 1,
+      severity: "blocking",
+      featureId,
+      messages: ["tasks.md missing — cannot claim completion"],
+    };
+  }
+
+  const openTasks = countOpenTasks(tasksText);
+  if (openTasks > 0) {
+    messages.push(`${openTasks} task(s) still open in tasks.md`);
+    return {
+      allowed: false,
+      exitCode: 1,
+      severity: "blocking",
+      featureId,
+      messages,
+    };
+  }
+
+  const validationPath = path.join(dir, "validation.md");
+  let validationText = "";
+  try {
+    validationText = await readFileSafe(validationPath);
+  } catch {
+    messages.push("validation.md missing — run independent /verify first");
+    return {
+      allowed: false,
+      exitCode: 1,
+      severity: "blocking",
+      featureId,
+      messages,
+    };
+  }
+
+  const verdict = findVerdict(validationText);
+  if (!verdict || !["PASS", "PASSED"].includes(verdict)) {
+    messages.push(verdict ? `validation verdict is ${verdict}, not PASS` : "validation.md has no PASS/FAIL verdict");
+    return {
+      allowed: false,
+      exitCode: 1,
+      severity: "blocking",
+      featureId,
+      messages,
+    };
+  }
+
+  messages.push("tasks complete and validation PASS recorded");
+  return {
+    allowed: true,
+    exitCode: 0,
+    severity: "info",
+    featureId,
+    messages,
+  };
+}
+
+/**
+ * @param {Awaited<ReturnType<typeof evaluateExecuteContext>>} context
+ * @param {{ json?: boolean }} [options]
+ */
+export function formatContextGuardStatus(context, options = {}) {
+  if (options.json) {
+    return JSON.stringify(context, null, 2);
+  }
+
+  const lines = ["Context guard status:"];
+  lines.push(`  feature: ${context.featureId ?? "(none)"}`);
+  lines.push(`  phase: ${context.phase ?? "(unknown)"}`);
+  lines.push(`  open_tasks: ${context.openTasks}`);
+  lines.push(`  execute_ready: ${context.ok ? "yes" : "no"}`);
+  for (const message of context.messages) {
+    lines.push(`  note: ${message}`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+/**
+ * @param {Awaited<ReturnType<typeof checkBeforeEdit>>} result
+ * @param {string} relativePath
+ * @param {{ json?: boolean }} [options]
+ */
+export function formatCheckBeforeEdit(result, relativePath, options = {}) {
+  if (options.json) {
+    return JSON.stringify({ path: relativePath, ...result }, null, 2);
+  }
+
+  const label = result.allowed
+    ? result.severity === "warning"
+      ? "allowed (warn)"
+      : "allowed"
+    : result.severity === "warning"
+      ? "blocked (warn)"
+      : "blocked";
+
+  const lines = [`${relativePath} [${result.operation}]: ${label}`];
+  for (const message of result.messages) {
+    lines.push(`  ${message}`);
+  }
+  return `${lines.join("\n")}\n`;
+}

package/lib/execution-policy.js

@@ -21,6 +21,14 @@ export const DEFAULT_POLICY = {
     on_budget_exhaustion: "stop",
     on_policy_violation: "block",
   },
+  effects: {
+    deny_read: [],
+    deny_write: [],
+    deny_delete: ["**/.git/**"],
+    warn_read: [],
+    warn_write: [],
+    warn_delete: [],
+  },
 };
 
 /**
@@ -28,9 +36,15 @@ export const DEFAULT_POLICY = {
  *   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 },
+ *   effects: {
+ *     deny_read: string[], deny_write: string[], deny_delete: string[],
+ *     warn_read: string[], warn_write: string[], warn_delete: string[],
+ *   },
  * }} ExecutionPolicy
  */
 
+/** @typedef {"read" | "write" | "delete"} PathOperation */
+
 /**
  * @typedef {{
  *   iterations: number,
@@ -48,7 +62,7 @@ export const DEFAULT_POLICY = {
 export function parseExecutionPolicySections(text) {
   /** @type {Partial<ExecutionPolicy>} */
   const result = {};
-  /** @type {"budget" | "scope" | "escalation" | null} */
+  /** @type {"budget" | "scope" | "escalation" | "effects" | null} */
   let section = null;
   /** @type {string | null} */
   let listKey = null;
@@ -59,9 +73,9 @@ export function parseExecutionPolicySections(text) {
       continue;
     }
 
-    const sectionMatch = trimmed.match(/^(budget|scope|escalation):\s*$/);
+    const sectionMatch = trimmed.match(/^(budget|scope|escalation|effects):\s*$/);
     if (sectionMatch) {
-      section = /** @type {"budget" | "scope" | "escalation"} */ (sectionMatch[1]);
+      section = /** @type {"budget" | "scope" | "escalation" | "effects"} */ (sectionMatch[1]);
       result[section] = result[section] ?? {};
       listKey = null;
       continue;
@@ -112,6 +126,14 @@ export function mergeExecutionPolicy(base, overlay) {
       denied_paths: overlay.scope?.denied_paths ?? base.scope.denied_paths,
     },
     escalation: { ...base.escalation, ...(overlay.escalation ?? {}) },
+    effects: {
+      deny_read: overlay.effects?.deny_read ?? base.effects.deny_read,
+      deny_write: overlay.effects?.deny_write ?? base.effects.deny_write,
+      deny_delete: overlay.effects?.deny_delete ?? base.effects.deny_delete,
+      warn_read: overlay.effects?.warn_read ?? base.effects.warn_read,
+      warn_write: overlay.effects?.warn_write ?? base.effects.warn_write,
+      warn_delete: overlay.effects?.warn_delete ?? base.effects.warn_delete,
+    },
   };
 }
 
@@ -191,6 +213,154 @@ export function checkPathScope(relativePath, policy) {
   };
 }
 
+const PATH_OPERATIONS = new Set(["read", "write", "delete"]);
+
+/**
+ * @param {string | undefined | null} raw
+ * @returns {PathOperation}
+ */
+export function normalizePathOperation(raw) {
+  const value = String(raw ?? "write").trim().toLowerCase();
+  if (!PATH_OPERATIONS.has(value)) {
+    throw new Error(`unknown operation '${raw}' — use read, write, or delete`);
+  }
+  return /** @type {PathOperation} */ (value);
+}
+
+/**
+ * Heuristic intent when the agent did not declare an operation explicitly.
+ *
+ * @param {string} relativePath
+ * @returns {PathOperation}
+ */
+export function inferPathOperation(relativePath) {
+  const normalized = relativePath.replace(/\\/g, "/").replace(/^\.\//, "");
+  const readOnly = /\.(md|txt|json|yaml|yml|lock)$/i.test(normalized);
+  return readOnly ? "read" : "write";
+}
+
+/**
+ * @param {PathOperation} operation
+ * @param {ExecutionPolicy["effects"]} effects
+ * @returns {{ deny: string[], warn: string[] }}
+ */
+export function effectRulesForOperation(operation, effects) {
+  return {
+    deny: effects[`deny_${operation}`] ?? [],
+    warn: effects[`warn_${operation}`] ?? [],
+  };
+}
+
+/**
+ * @param {string} relativePath
+ * @param {PathOperation} operation
+ * @param {ExecutionPolicy} policy
+ * @returns {{ allowed: boolean, severity: "blocking" | "warning" | "info", reason: string, operation: PathOperation }}
+ */
+export function checkPathEffect(relativePath, operation, policy) {
+  const normalized = relativePath.replace(/\\/g, "/").replace(/^\.\//, "");
+  const { deny, warn } = effectRulesForOperation(operation, policy.effects);
+
+  for (const pattern of deny) {
+    if (matchGlobPattern(pattern, normalized)) {
+      return {
+        allowed: false,
+        severity: "blocking",
+        reason: `${operation.toUpperCase()} denied for path matching ${pattern}`,
+        operation,
+      };
+    }
+  }
+
+  for (const pattern of warn) {
+    if (matchGlobPattern(pattern, normalized)) {
+      return {
+        allowed: true,
+        severity: "warning",
+        reason: `${operation.toUpperCase()} warned for path matching ${pattern}`,
+        operation,
+      };
+    }
+  }
+
+  return {
+    allowed: true,
+    severity: "info",
+    reason: `no ${operation} effect rules matched`,
+    operation,
+  };
+}
+
+/**
+ * @param {string} relativePath
+ * @param {ExecutionPolicy} policy
+ * @param {{ operation?: string | null }} [options]
+ * @returns {{
+ *   allowed: boolean,
+ *   exitCode: number,
+ *   severity: "blocking" | "warning" | "info",
+ *   reason: string,
+ *   operation: PathOperation,
+ *   scope: ReturnType<typeof checkPathScope>,
+ *   effect: ReturnType<typeof checkPathEffect>,
+ * }}
+ */
+export function resolvePathCheck(relativePath, policy, options = {}) {
+  const operation = options.operation
+    ? normalizePathOperation(options.operation)
+    : inferPathOperation(relativePath);
+  const scope = checkPathScope(relativePath, policy);
+  const effect = checkPathEffect(relativePath, operation, policy);
+
+  if (!scope.allowed) {
+    const mode = policy.escalation.on_policy_violation ?? "block";
+    return {
+      allowed: false,
+      severity: mode === "warn" ? "warning" : "blocking",
+      reason: scope.reason,
+      operation,
+      scope,
+      effect,
+      exitCode: mode === "warn" ? 0 : 1,
+    };
+  }
+
+  if (!effect.allowed) {
+    const mode = policy.escalation.on_policy_violation ?? "block";
+    return {
+      allowed: false,
+      severity: mode === "warn" ? "warning" : "blocking",
+      reason: effect.reason,
+      operation,
+      scope,
+      effect,
+      exitCode: mode === "warn" ? 0 : 1,
+    };
+  }
+
+  if (effect.severity === "warning") {
+    return {
+      allowed: true,
+      severity: "warning",
+      reason: effect.reason,
+      operation,
+      scope,
+      effect,
+      exitCode: 0,
+    };
+  }
+
+  return {
+    allowed: true,
+    severity: "info",
+    reason: scope.reason,
+    operation,
+    scope,
+    effect,
+    exitCode: 0,
+  };
+}
+
 /**
  * @param {string} cwd
  * @returns {Promise<ExecutionPolicyState>}
@@ -235,25 +405,6 @@ export function checkBudget(state, policy) {
   return { ok: issues.length === 0, issues };
 }
 
-/**
- * @param {string} relativePath
- * @param {ExecutionPolicy} policy
- * @returns {{ allowed: boolean, exitCode: number, severity: "blocking" | "warning" | "info", reason: string }}
- */
-export function resolvePathCheck(relativePath, policy) {
-  const result = checkPathScope(relativePath, policy);
-  if (result.allowed) {
-    return { ...result, exitCode: 0 };
-  }
-
-  const mode = policy.escalation.on_policy_violation ?? "block";
-  if (mode === "warn") {
-    return { ...result, severity: "warning", exitCode: 0 };
-  }
-
-  return { ...result, exitCode: 1 };
-}
-
 /**
  * @param {string} taskId
  * @param {ExecutionPolicyState} state
@@ -361,6 +512,7 @@ export function formatPolicyStatus(policy, state, options = {}) {
     `  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(", ")}`,
+    `  deny_delete: ${policy.effects.deny_delete.join(", ") || "(default .git only)"}`,
     `  budget_ok: ${budget.ok ? "yes" : "no"}`,
   ];
 

package/lib/gates.js

@@ -43,6 +43,7 @@ const AUX_SCRIPTS = {
   "loop-plan": "loop_plan.py",
   "memory-index": "memory_index.py",
   "memory-query": "memory_query.py",
+  "memory-search": "memory_search.py",
 };
 
 const GUARDRAILS_SCRIPTS = { ...GATE_SCRIPTS, ...AUX_SCRIPTS };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luizsantiago/spec-guardrails",
-  "version": "3.2.1",
+  "version": "3.4.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/test_validation_verdict.test.js test/test_execution_policy.test.js test/test_workspace_isolation.test.js test/test_adapter_registry.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/test_adapter_registry.test.js test/test_context_guard.test.js",
     "test:gates": "node test/run-gate-tests.mjs",
     "prepublishOnly": "npm test"
   },

package/scripts/memory_search.py

@@ -0,0 +1,119 @@
+#!/usr/bin/env python3
+"""Full-text search over the SQLite memory index (entity_fts).
+
+    python3 memory_search.py "authentication route"
+    python3 memory_search.py "REQ-001" --limit 5 --json
+
+Exit codes: 0 ok, 1 failure, 2 usage error.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sqlite3
+import sys
+from pathlib import Path
+
+from _common import EXIT_FAILED, EXIT_OK, EXIT_USAGE
+
+GATE = "memory-search"
+DB_PATH = Path(".specs/memory/memory.db")
+DEFAULT_LIMIT = 10
+MAX_LIMIT = 50
+
+
+def fail(message: str, code: int = EXIT_FAILED) -> int:
+    print(f"[{GATE}] FAIL - {DB_PATH}")
+    print(f"  error   {message}")
+    return code
+
+
+def sanitize_fts_query(raw: str) -> str:
+    """Return an FTS5-safe query string (token AND chain)."""
+
+    tokens = re.findall(r"[A-Za-z0-9_\-]+", raw)
+    if not tokens:
+        raise ValueError("query must contain at least one searchable token")
+    return " AND ".join(f'"{token}"' for token in tokens)
+
+
+def search(query: str, limit: int = DEFAULT_LIMIT) -> list[dict]:
+    if not DB_PATH.is_file():
+        raise FileNotFoundError(
+            f"{DB_PATH} not found — run `memory-index rebuild` after install"
+        )
+
+    fts_query = sanitize_fts_query(query)
+    conn = sqlite3.connect(DB_PATH)
+    try:
+        rows = conn.execute(
+            """
+            SELECT e.id, e.kind, e.label, e.source_path, e.updated_at
+            FROM entity_fts f
+            JOIN entities e ON e.id = f.id
+            WHERE entity_fts MATCH ?
+            ORDER BY rank
+            LIMIT ?
+            """,
+            (fts_query, limit),
+        ).fetchall()
+    finally:
+        conn.close()
+
+    return [
+        {
+            "id": row[0],
+            "kind": row[1],
+            "label": row[2],
+            "source_path": row[3],
+            "updated_at": row[4],
+        }
+        for row in rows
+    ]
+
+
+def cmd_search(args: argparse.Namespace) -> int:
+    try:
+        results = search(args.query, limit=args.limit)
+    except FileNotFoundError as err:
+        return fail(str(err))
+    except ValueError as err:
+        return fail(str(err), EXIT_USAGE)
+
+    payload = {"query": args.query, "count": len(results), "results": results}
+
+    if args.json:
+        print(json.dumps(payload, indent=2))
+    else:
+        print(f"[{GATE}] {len(results)} match(es) for {args.query!r}")
+        for item in results:
+            print(f"  {item['id']} ({item['kind']}): {item['label']}")
+            if item.get("source_path"):
+                print(f"           {item['source_path']}")
+
+    return EXIT_OK
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Search the SQLite memory index (FTS5)")
+    parser.add_argument("query", help="search terms")
+    parser.add_argument("--limit", type=int, default=DEFAULT_LIMIT)
+    parser.add_argument("--json", action="store_true")
+    parser.set_defaults(func=cmd_search)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.limit < 1 or args.limit > MAX_LIMIT:
+        return fail(f"--limit must be between 1 and {MAX_LIMIT}", EXIT_USAGE)
+
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/agent-architecture.md

@@ -48,7 +48,9 @@ Structural gates run **before** owner review, so they cannot drift when the mode
 | Before Execute waves (3+ tasks) | `npx @luizsantiago/spec-guardrails loop-plan [feature]` |
 | Parallel wave (2+ tasks, disjoint Files) | `npx @luizsantiago/spec-guardrails workspace-prepare [feature] --tasks T1,T2` |
 | After parallel wave merge | `npx @luizsantiago/spec-guardrails workspace-cleanup [feature] --force` |
-| Before editing paths outside task Files | `npx @luizsantiago/spec-guardrails execution-policy check-path <path>` |
+| Before editing paths outside task Files | `npx @luizsantiago/spec-guardrails context-guard check-edit <path> [--op write]` |
+| Before claiming feature complete | `npx @luizsantiago/spec-guardrails context-guard check-complete [feature]` |
+| Retrieve related context | `npx @luizsantiago/spec-guardrails memory-search "<terms>"` |
 | On gate retry (Execute playbook) | `npx @luizsantiago/spec-guardrails execution-policy record-retry Tn` |
 | On each commit | `python3 .specs/guardrails/scripts/check_commit.py --message "<message>"` |
 | Before declaring a feature done | `python3 .specs/guardrails/scripts/validate_state.py [feature]` |

package/skills/git-handoff.md

@@ -72,6 +72,7 @@ npx @luizsantiago/spec-guardrails execution-policy check-path src/auth.ts
 ```
 
 - **Scope:** denied paths block with exit 1; allowed_paths (when set) restrict edits to listed globs.
+- **Intent/effect:** pass `--op read|write|delete` to `check-path`; configure `effects.deny_*` and `effects.warn_*` globs per operation in `.specs/config.yaml`.
 - **Retries:** after a task gate failure, run `execution-policy record-retry Tn`; stop at `max_retries_per_task` (default 3) and escalate per the Execute playbook — do not bypass with `--no-verify`.
 - **Agent runs:** orchestrators may call `execution-policy record-run` when dispatching sub-agents; stop when budgets exhaust.
 

package/skills/references/implement.md

@@ -38,13 +38,17 @@ Each worker runs in its own git worktree under `.specs/workspaces/[feature]/`. A
 npx @luizsantiago/spec-guardrails workspace-cleanup [feature] --tasks T1,T2 --force
 ```
 
-7. Consult execution policy before touching files outside the task list:
+7. Consult execution policy and contextual guards before touching files:
 
 ```bash
-npx @luizsantiago/spec-guardrails execution-policy check-path src/auth.ts
+npx @luizsantiago/spec-guardrails context-guard status
+npx @luizsantiago/spec-guardrails context-guard check-edit src/auth.ts --op write
+npx @luizsantiago/spec-guardrails execution-policy check-path src/auth.ts --op write
 npx @luizsantiago/spec-guardrails execution-policy status
 ```
 
+Declare the intended operation (`read`, `write`, or `delete`). When `--op` is omitted, the CLI infers `read` for common doc/config extensions and `write` otherwise. Effect rules in `.specs/config.yaml` (`effects.deny_*`, `effects.warn_*`) apply after scope checks.
+
 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.

package/templates/config.yaml.example

@@ -39,6 +39,16 @@ escalation:
   on_budget_exhaustion: stop
   on_policy_violation: block
 
+# Intent/effect rules (optional — pair with check-path --op read|write|delete)
+effects:
+  deny_delete:
+    - "**/.git/**"
+  deny_write: []
+  deny_read: []
+  warn_write: []
+  warn_read: []
+  warn_delete: []
+
 # Project-specific overrides (appended on top of preset + rules above):
 # overrides:
 #   rules: