@luizsantiago/spec-guardrails 3.2.1 → 3.3.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.3.x**
 
 ---
 
@@ -217,6 +217,7 @@ npx @luizsantiago/spec-guardrails install
 
 | Version | What you gain |
 | --- | --- |
+| **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

@@ -81,6 +81,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)
@@ -482,20 +483,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);

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

@@ -1,6 +1,6 @@
 {
   "name": "@luizsantiago/spec-guardrails",
-  "version": "3.2.1",
+  "version": "3.3.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": {

package/skills/agent-architecture.md

@@ -48,7 +48,7 @@ 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 execution-policy check-path <path> [--op write]` |
 | 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

@@ -41,10 +41,13 @@ npx @luizsantiago/spec-guardrails workspace-cleanup [feature] --tasks T1,T2 --fo
 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 check-path src/auth.ts --op write
+npx @luizsantiago/spec-guardrails execution-policy check-path README.md --op read
 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: