@luizsantiago/spec-guardrails 3.3.0 → 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.3.x**
+npm: [`@luizsantiago/spec-guardrails`](https://www.npmjs.com/package/@luizsantiago/spec-guardrails) **3.4.x**
 
 ---
 
@@ -217,6 +217,7 @@ 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` |

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";
@@ -89,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
@@ -565,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/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.3.0",
+  "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> [--op write]` |
+| 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/references/implement.md

@@ -38,11 +38,12 @@ 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 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 check-path README.md --op read
 npx @luizsantiago/spec-guardrails execution-policy status
 ```