@luizsantiago/spec-guardrails 3.8.0 → 3.9.0

package/README.md

@@ -5,7 +5,7 @@
 
 **Keep AI coding agents honest — specify the work, prove each step, verify independently.**
 
-npm: [`@luizsantiago/spec-guardrails`](https://www.npmjs.com/package/@luizsantiago/spec-guardrails) **3.8.x**
+npm: [`@luizsantiago/spec-guardrails`](https://www.npmjs.com/package/@luizsantiago/spec-guardrails) **3.9.x**
 
 ---
 
@@ -106,7 +106,10 @@ Most projects start with Specify → Tasks → Loop → Verify only. Turn these
 | Capability | Plain purpose | Learn more |
 | --- | --- | --- |
 | **Memory search** | Find text in past specs and validations | [Memory guide](docs/guide/Memory.md) |
-| **Context guards** | Check scope before edit or “done” | [Agent commands](docs/guide/agent-commands.md) · **Cursor:** auto via hooks (3.8+) |
+| **Context guards** | Check scope before edit or “done” | [Agent commands](docs/guide/agent-commands.md) · **Cursor:** auto via hooks |
+| **Episodic memory** | Session notes → episodic → lessons | [Memory → Episodes](docs/guide/Memory.md#episodic-memory-lifecycle) |
+| **Code index** | Lightweight brownfield file/symbol map | [Brownfield context](docs/guide/brownfield-context.md) |
+| **Sandbox policy** | Block/warn destructive shell commands | [Overview → Safety](docs/guide/Overview.md#safety-and-limits) |
 | **Execution policy** | Limit paths, retries, dangerous ops | [Overview → Safety](docs/guide/Overview.md#safety-and-limits) |
 | **Solution exploration** | Compare two+ implementations before committing | [Overview → Exploration](docs/guide/Overview.md#optional-exploration-mode) |
 | **Semantic retrieval** | Search by meaning (needs OpenAI or Ollama) | [Memory → Semantic](docs/guide/Memory.md#semantic-search-optional) |

package/index.js

@@ -45,6 +45,11 @@ import {
   recordExplorationDecision,
   validateExplorationArtifact,
 } from "./lib/solution-exploration.js";
+import {
+  checkSandboxCommand,
+  formatSandboxCheck,
+  loadSandboxPolicy,
+} from "./lib/sandbox-policy.js";
 import {
   initProjectConfig,
   listPresets,
@@ -113,6 +118,13 @@ Commands:
   memory-retrieve "<query>"          Hybrid retrieval (FTS + graph + optional semantic)
     [--mode fts|hybrid|semantic]     Strategy (default: hybrid)
     [--json]                         Machine-readable output
+  episodes record --summary "…"      Capture working-session episodic memory
+  episodes list|archive|prune|promote  Episodic lifecycle (working → episodic → promoted)
+  code-index rebuild [--roots src,lib] Lightweight brownfield code map (not full RepoGraph)
+  code-index search "<query>"        Search indexed files/symbols/imports
+  sandbox status                     Show sandbox policy mode (off|warn|strict)
+  sandbox check-command "<cmd>"      Soft OS sandbox — block/warn destructive shell commands
+    [--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
@@ -614,6 +626,58 @@ if (command === "--version" || command === "-v" || command === "version") {
     console.error(`❌ ${err.message}`);
     process.exit(1);
   }
+} else if (command === "sandbox") {
+  try {
+    const sub = args[0];
+    let json = false;
+    /** @type {string[]} */
+    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 loadSandboxPolicy(cwd);
+
+    if (sub === "status") {
+      if (json) {
+        console.log(
+          JSON.stringify(
+            {
+              mode: policy.mode,
+              deny_rules: policy.deny_patterns.map((rule) => rule.id),
+            },
+            null,
+            2,
+          ),
+        );
+      } else {
+        console.log(
+          `Sandbox mode: ${policy.mode} (${policy.deny_patterns.length} deny rule(s))`,
+        );
+      }
+    } else if (sub === "check-command") {
+      const shellCommand = rest.join(" ").trim();
+      if (!shellCommand) {
+        throw new Error('Usage: sandbox check-command "<shell command>" [--json]');
+      }
+      const result = checkSandboxCommand(shellCommand, policy);
+      process.stdout.write(formatSandboxCheck(result, shellCommand, { json }));
+      if (!result.allowed) {
+        process.exit(1);
+      }
+    } else {
+      throw new Error('Usage: sandbox status | check-command "<cmd>" [--json]');
+    }
+  } catch (err) {
+    console.error(`❌ ${err.message}`);
+    process.exit(1);
+  }
 } else if (command === "context-guard") {
   try {
     const sub = args[0];

package/lib/constants.js

@@ -115,6 +115,8 @@ export const SCRIPT_ASSETS = [
   { file: "memory_retrieve.py", remotePath: "scripts/memory_retrieve.py" },
   { file: "_memory_config.py", remotePath: "scripts/_memory_config.py" },
   { file: "_memory_embed.py", remotePath: "scripts/_memory_embed.py" },
+  { file: "episodes.py", remotePath: "scripts/episodes.py" },
+  { file: "code_index.py", remotePath: "scripts/code_index.py" },
 ];
 
 /** @type {{ file: string, remotePath: string }[]} */

package/lib/cursor-hooks.js

@@ -4,9 +4,22 @@ import path from "node:path";
 import { packagedAssetPath } from "./assets.js";
 import { ensureDir, readFileSafe } from "./fs-utils.js";
 
-export const CURSOR_HOOK_SCRIPT = ".cursor/hooks/context-guard-edit.mjs";
+export const CURSOR_HOOK_EDIT = ".cursor/hooks/context-guard-edit.mjs";
+export const CURSOR_HOOK_SANDBOX = ".cursor/hooks/sandbox-shell.mjs";
 export const CURSOR_HOOKS_JSON = ".cursor/hooks.json";
 
+/** @type {readonly { source: string, dest: string }[]} */
+export const CURSOR_HOOK_SCRIPTS = [
+  {
+    source: "templates/cursor/hooks/context-guard-edit.mjs",
+    dest: CURSOR_HOOK_EDIT,
+  },
+  {
+    source: "templates/cursor/hooks/sandbox-shell.mjs",
+    dest: CURSOR_HOOK_SANDBOX,
+  },
+];
+
 /**
  * Merge shipped hook entries without removing user hooks.
  *
@@ -58,7 +71,7 @@ export function mergeCursorHooksConfig(existing, template) {
 }
 
 /**
- * Install Cursor hooks that auto-run context-guard before write/edit tools.
+ * Install Cursor hooks for context-guard and sandbox policy.
  *
  * @param {string} cwd
  * @param {{ log?: (message: string) => void }} [options]
@@ -68,14 +81,14 @@ export async function installCursorHooks(cwd, options = {}) {
   const hooksDir = path.join(cwd, ".cursor/hooks");
   await ensureDir(hooksDir);
 
-  const scriptSource = packagedAssetPath("templates/cursor/hooks/context-guard-edit.mjs");
-  const scriptDest = path.join(cwd, CURSOR_HOOK_SCRIPT);
-  await fs.copyFile(scriptSource, scriptDest);
-
-  try {
-    await fs.chmod(scriptDest, 0o755);
-  } catch {
-    // Windows may ignore chmod; node can still execute the script.
+  for (const script of CURSOR_HOOK_SCRIPTS) {
+    const scriptDest = path.join(cwd, script.dest);
+    await fs.copyFile(packagedAssetPath(script.source), scriptDest);
+    try {
+      await fs.chmod(scriptDest, 0o755);
+    } catch {
+      // Windows may ignore chmod; node can still execute the script.
+    }
   }
 
   const template = JSON.parse(
@@ -92,5 +105,5 @@ export async function installCursorHooks(cwd, options = {}) {
 
   const merged = mergeCursorHooksConfig(existing, template);
   await fs.writeFile(hooksJsonPath, `${JSON.stringify(merged, null, 2)}\n`, "utf8");
-  log(`✅ Cursor hooks → ${CURSOR_HOOKS_JSON} (context-guard on write/edit tools)`);
+  log(`✅ Cursor hooks → ${CURSOR_HOOKS_JSON} (context-guard + sandbox shell checks)`);
 }

package/lib/gates.js

@@ -45,6 +45,8 @@ const AUX_SCRIPTS = {
   "memory-query": "memory_query.py",
   "memory-search": "memory_search.py",
   "memory-retrieve": "memory_retrieve.py",
+  episodes: "episodes.py",
+  "code-index": "code_index.py",
 };
 
 const GUARDRAILS_SCRIPTS = { ...GATE_SCRIPTS, ...AUX_SCRIPTS };

package/lib/sandbox-policy.js

@@ -0,0 +1,173 @@
+import path from "node:path";
+
+import { readFileSafe } from "./fs-utils.js";
+
+export const SANDBOX_LOG_PATH = ".specs/state/sandbox-log.json";
+
+/** @type {readonly { id: string, pattern: RegExp, reason: string }[]} */
+export const DEFAULT_SANDBOX_DENIES = [
+  {
+    id: "rm-rf",
+    pattern: /\brm\s+(-[^\s]*f[^\s]*\s+-[^\s]*r|-[^\s]*r[^\s]*\s+-[^\s]*f|-rf|-fr)\s/i,
+    reason: "recursive force delete is blocked by sandbox policy",
+  },
+  {
+    id: "curl-pipe-sh",
+    pattern: /\bcurl\b[^\n|]*\|\s*(?:ba)?sh\b/i,
+    reason: "curl piped to shell is blocked by sandbox policy",
+  },
+  {
+    id: "wget-pipe-sh",
+    pattern: /\bwget\b[^\n|]*\|\s*(?:ba)?sh\b/i,
+    reason: "wget piped to shell is blocked by sandbox policy",
+  },
+  {
+    id: "force-push-main",
+    pattern: /\bgit\s+push\b[^\n]*(--force|--force-with-lease)[^\n]*\b(main|master)\b/i,
+    reason: "force push to main/master is blocked by sandbox policy",
+  },
+  {
+    id: "drop-database",
+    pattern: /\b(DROP\s+DATABASE|DROP\s+SCHEMA|TRUNCATE\s+TABLE)\b/i,
+    reason: "destructive SQL is blocked by sandbox policy",
+  },
+];
+
+/**
+ * @typedef {"off" | "warn" | "strict"} SandboxMode
+ */
+
+/**
+ * @typedef {{
+ *   mode: SandboxMode,
+ *   deny_patterns: { id: string, pattern: RegExp, reason: string }[],
+ * }} SandboxPolicy
+ */
+
+/**
+ * @param {string} text
+ * @returns {SandboxPolicy}
+ */
+export function parseSandboxPolicy(text) {
+  /** @type {SandboxPolicy} */
+  const policy = {
+    mode: "warn",
+    deny_patterns: [...DEFAULT_SANDBOX_DENIES],
+  };
+
+  let inSandbox = false;
+  let sandboxIndent = 0;
+  let inDenyList = false;
+
+  for (const line of text.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) {
+      continue;
+    }
+
+    const indent = line.length - line.trimStart().length;
+
+    if (trimmed === "sandbox:") {
+      inSandbox = true;
+      inDenyList = false;
+      sandboxIndent = indent;
+      continue;
+    }
+
+    if (inSandbox && indent <= sandboxIndent && trimmed !== "sandbox:") {
+      inSandbox = false;
+      inDenyList = false;
+    }
+
+    if (!inSandbox) {
+      continue;
+    }
+
+    const modeMatch = trimmed.match(/^mode:\s*(off|warn|strict)\s*$/i);
+    if (modeMatch) {
+      policy.mode = /** @type {SandboxMode} */ (modeMatch[1].toLowerCase());
+      continue;
+    }
+
+    if (trimmed === "deny_patterns:") {
+      inDenyList = true;
+      continue;
+    }
+
+    if (inDenyList && trimmed.startsWith("- ")) {
+      const raw = trimmed.slice(2).trim().replace(/^['"]|['"]$/g, "");
+      if (raw) {
+        try {
+          policy.deny_patterns.push({
+            id: `custom-${policy.deny_patterns.length + 1}`,
+            pattern: new RegExp(raw, "i"),
+            reason: `matched custom sandbox deny pattern: ${raw}`,
+          });
+        } catch {
+          // ignore invalid regex in config
+        }
+      }
+    }
+  }
+
+  return policy;
+}
+
+/**
+ * @param {string} cwd
+ * @returns {Promise<SandboxPolicy>}
+ */
+export async function loadSandboxPolicy(cwd) {
+  try {
+    const text = await readFileSafe(path.join(cwd, ".specs/config.yaml"));
+    return parseSandboxPolicy(text);
+  } catch {
+    return { mode: "warn", deny_patterns: [...DEFAULT_SANDBOX_DENIES] };
+  }
+}
+
+/**
+ * @param {string} command
+ * @param {SandboxPolicy} policy
+ * @returns {{ allowed: boolean, severity: "info" | "warning" | "blocking", reason: string | null, mode: SandboxMode }}
+ */
+export function checkSandboxCommand(command, policy) {
+  const mode = policy.mode ?? "warn";
+  if (mode === "off") {
+    return { allowed: true, severity: "info", reason: null, mode };
+  }
+
+  const normalized = String(command || "").trim();
+  if (!normalized) {
+    return { allowed: true, severity: "info", reason: null, mode };
+  }
+
+  for (const rule of policy.deny_patterns) {
+    if (rule.pattern.test(normalized)) {
+      if (mode === "strict") {
+        return { allowed: false, severity: "blocking", reason: rule.reason, mode };
+      }
+      return { allowed: true, severity: "warning", reason: rule.reason, mode };
+    }
+  }
+
+  return { allowed: true, severity: "info", reason: null, mode };
+}
+
+/**
+ * @param {Awaited<ReturnType<typeof checkSandboxCommand>>} result
+ * @param {string} command
+ * @param {{ json?: boolean }} [options]
+ */
+export function formatSandboxCheck(result, command, options = {}) {
+  if (options.json) {
+    return JSON.stringify({ command, ...result }, null, 2);
+  }
+
+  if (!result.reason) {
+    return `Sandbox [${result.mode}]: allowed\n`;
+  }
+
+  const label = result.allowed ? "warn" : "blocked";
+  return `Sandbox [${result.mode}]: ${label}\n  ${result.reason}\n`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luizsantiago/spec-guardrails",
-  "version": "3.8.0",
+  "version": "3.9.0",
   "description": "Spec-driven process kit for AI coding agents: write goals in .specs/, break into tasks, implement in waves, verify with proof. Process mode (Node) or Brakes mode (Node + Python gates). Works with Cursor, Claude, Copilot, and Codex.",
   "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/test_context_guard.test.js test/test_solution_exploration.test.js test/test_memory_doctor.test.js test/test_cursor_hooks.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/test_solution_exploration.test.js test/test_memory_doctor.test.js test/test_cursor_hooks.test.js test/test_sandbox_policy.test.js",
     "test:gates": "node test/run-gate-tests.mjs",
     "prepublishOnly": "npm test"
   },

package/scripts/_memory_config.py

@@ -21,6 +21,11 @@ DEFAULT_RETRIEVAL = {
     "graph_depth": 1,
 }
 
+DEFAULT_LIFECYCLE = {
+    "retention_days": 90,
+    "auto_archive_on_handoff": False,
+}
+
 BOOL = {"true", "false", "yes", "no", "on", "off"}
 
 
@@ -95,3 +100,60 @@ def load_memory_retrieval_config() -> dict:
         config[key] = _parse_scalar(raw_value)
 
     return config
+
+
+def load_memory_lifecycle_config() -> dict:
+    """Return memory.lifecycle settings with defaults."""
+
+    config = dict(DEFAULT_LIFECYCLE)
+    if not CONFIG_PATH.is_file():
+        return config
+
+    lines = CONFIG_PATH.read_text(encoding="utf-8").splitlines()
+    in_memory = False
+    in_lifecycle = False
+    memory_indent = 0
+    lifecycle_indent = 0
+
+    for line in lines:
+        if not line.strip() or line.lstrip().startswith("#"):
+            continue
+
+        indent = len(line) - len(line.lstrip())
+        stripped = line.strip()
+
+        if stripped == "memory:":
+            in_memory = True
+            in_lifecycle = False
+            memory_indent = indent
+            continue
+
+        if not in_memory:
+            continue
+
+        if indent <= memory_indent and stripped != "memory:":
+            in_memory = False
+            in_lifecycle = False
+            continue
+
+        if stripped == "lifecycle:":
+            in_lifecycle = True
+            lifecycle_indent = indent
+            continue
+
+        if in_lifecycle and indent <= lifecycle_indent and not stripped.startswith("lifecycle:"):
+            in_lifecycle = False
+
+        if not in_lifecycle:
+            continue
+
+        match = re.match(r"^([a-z_]+):\s*(.*)$", stripped)
+        if not match:
+            continue
+
+        key, raw_value = match.group(1), match.group(2)
+        if key not in config or raw_value == "":
+            continue
+        config[key] = _parse_scalar(raw_value)
+
+    return config

package/scripts/code_index.py

@@ -0,0 +1,228 @@
+#!/usr/bin/env python3
+"""Lightweight brownfield code index — shallow file/symbol map, not full RepoGraph.
+
+    python3 code_index.py rebuild [--roots src,lib] [--json]
+    python3 code_index.py search "auth" [--json]
+
+Exit codes: 0 ok, 1 failure, 2 usage error.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+from _common import EXIT_FAILED, EXIT_OK, EXIT_USAGE
+
+GATE = "code-index"
+INDEX_PATH = Path(".specs/memory/code-index.json")
+DEFAULT_ROOTS = ("src", "lib", "app", "packages", "internal", "cmd")
+SKIP_DIRS = {
+    ".git",
+    ".specs",
+    ".cursor",
+    "node_modules",
+    "dist",
+    "build",
+    "coverage",
+    "vendor",
+    "__pycache__",
+    ".next",
+    ".turbo",
+}
+CODE_EXTENSIONS = {
+    ".ts": "typescript",
+    ".tsx": "typescript",
+    ".js": "javascript",
+    ".jsx": "javascript",
+    ".py": "python",
+    ".go": "go",
+    ".rs": "rust",
+}
+SYMBOL_PATTERNS = {
+    "typescript": [
+        re.compile(r"^\s*(?:export\s+)?(?:async\s+)?function\s+([A-Za-z_]\w*)", re.MULTILINE),
+        re.compile(r"^\s*(?:export\s+)?class\s+([A-Za-z_]\w*)", re.MULTILINE),
+        re.compile(r"^\s*(?:export\s+)?(?:const|let|var)\s+([A-Za-z_]\w*)\s*=", re.MULTILINE),
+    ],
+    "python": [
+        re.compile(r"^\s*(?:async\s+)?def\s+([A-Za-z_]\w*)", re.MULTILINE),
+        re.compile(r"^\s*class\s+([A-Za-z_]\w*)", re.MULTILINE),
+    ],
+    "javascript": [
+        re.compile(r"^\s*(?:export\s+)?(?:async\s+)?function\s+([A-Za-z_]\w*)", re.MULTILINE),
+        re.compile(r"^\s*(?:export\s+)?class\s+([A-Za-z_]\w*)", re.MULTILINE),
+    ],
+    "go": [
+        re.compile(r"^\s*func\s+(?:\([^)]+\)\s+)?([A-Za-z_]\w*)", re.MULTILINE),
+        re.compile(r"^\s*type\s+([A-Za-z_]\w*)\s+", re.MULTILINE),
+    ],
+    "rust": [
+        re.compile(r"^\s*(?:pub\s+)?fn\s+([A-Za-z_]\w*)", re.MULTILINE),
+        re.compile(r"^\s*(?:pub\s+)?struct\s+([A-Za-z_]\w*)", re.MULTILINE),
+    ],
+}
+IMPORT_PATTERN = re.compile(
+    r"^\s*(?:import|from|require\(|use)\s+['\"]?([^'\";\n]+)",
+    re.MULTILINE,
+)
+
+
+def fail(message: str, code: int = EXIT_FAILED) -> int:
+    print(f"[{GATE}] FAIL - {INDEX_PATH}")
+    print(f"  error   {message}")
+    return code
+
+
+def ok(message: str) -> int:
+    print(f"[{GATE}] PASS - {message}")
+    return EXIT_OK
+
+
+def utc_now() -> str:
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat()
+
+
+def discover_roots(explicit: list[str] | None) -> list[Path]:
+    if explicit:
+        return [Path(root) for root in explicit if root.strip()]
+    return [Path(root) for root in DEFAULT_ROOTS if Path(root).is_dir()]
+
+
+def extract_symbols(language: str, text: str) -> list[str]:
+    symbols: list[str] = []
+    for pattern in SYMBOL_PATTERNS.get(language, []):
+        for match in pattern.finditer(text):
+            name = match.group(1)
+            if name and name not in symbols:
+                symbols.append(name)
+    return symbols[:40]
+
+
+def extract_imports(text: str) -> list[str]:
+    imports: list[str] = []
+    for match in IMPORT_PATTERN.finditer(text):
+        value = match.group(1).strip().strip("'\"")
+        if value and value not in imports:
+            imports.append(value)
+    return imports[:20]
+
+
+def scan_file(path: Path) -> dict | None:
+    suffix = path.suffix.lower()
+    language = CODE_EXTENSIONS.get(suffix)
+    if not language:
+        return None
+
+    try:
+        text = path.read_text(encoding="utf-8", errors="ignore")
+    except OSError:
+        return None
+
+    if len(text) > 250_000:
+        text = text[:250_000]
+
+    return {
+        "path": path.as_posix(),
+        "language": language,
+        "symbols": extract_symbols(language, text),
+        "imports": extract_imports(text),
+    }
+
+
+def rebuild(roots: list[str] | None, json_output: bool) -> int:
+    scan_roots = discover_roots(roots)
+    if not scan_roots:
+        return fail("no code roots found — pass --roots src,lib or run from a repo with src/")
+
+    files: list[dict] = []
+    for root in scan_roots:
+        if not root.is_dir():
+            continue
+        for path in root.rglob("*"):
+            if not path.is_file():
+                continue
+            if any(part in SKIP_DIRS for part in path.parts):
+                continue
+            entry = scan_file(path)
+            if entry:
+                files.append(entry)
+
+    payload = {
+        "updated_at": utc_now(),
+        "roots": [root.as_posix() for root in scan_roots],
+        "files": sorted(files, key=lambda item: item["path"]),
+        "file_count": len(files),
+    }
+
+    INDEX_PATH.parent.mkdir(parents=True, exist_ok=True)
+    INDEX_PATH.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+
+    if json_output:
+        print(json.dumps(payload, indent=2))
+    else:
+        ok(f"indexed {len(files)} file(s) -> {INDEX_PATH}")
+    return EXIT_OK
+
+
+def search(query: str, json_output: bool) -> int:
+    if not INDEX_PATH.is_file():
+        return fail(f"{INDEX_PATH} not found — run `code-index rebuild` first")
+
+    needle = query.lower().strip()
+    payload = json.loads(INDEX_PATH.read_text(encoding="utf-8"))
+    results = []
+    for entry in payload.get("files") or []:
+        haystack = " ".join(
+            [entry.get("path", ""), *entry.get("symbols", []), *entry.get("imports", [])]
+        ).lower()
+        if needle in haystack:
+            results.append(entry)
+
+    summary = {"query": query, "count": len(results), "results": results[:50]}
+    if json_output:
+        print(json.dumps(summary, indent=2))
+    else:
+        for entry in summary["results"]:
+            symbols = ", ".join(entry.get("symbols") or []) or "(no symbols)"
+            print(f"{entry['path']} [{entry['language']}] — {symbols}")
+    return EXIT_OK
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Lightweight brownfield code index")
+    sub = parser.add_subparsers(dest="command")
+
+    rebuild_cmd = sub.add_parser("rebuild", help="scan code roots and write code-index.json")
+    rebuild_cmd.add_argument("--roots")
+    rebuild_cmd.add_argument("--json", action="store_true")
+    rebuild_cmd.set_defaults(
+        func=lambda args: rebuild(
+            [part.strip() for part in args.roots.split(",")] if args.roots else None,
+            args.json,
+        )
+    )
+
+    search_cmd = sub.add_parser("search", help="search indexed files/symbols")
+    search_cmd.add_argument("query")
+    search_cmd.add_argument("--json", action="store_true")
+    search_cmd.set_defaults(func=lambda args: search(args.query, args.json))
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not args.command:
+        parser.print_help()
+        return EXIT_USAGE
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/episodes.py

@@ -0,0 +1,274 @@
+#!/usr/bin/env python3
+"""Episodic memory lifecycle for `.specs/state/episodes.json`.
+
+Working session notes graduate to episodic memory, then archive or promote to lessons.
+
+    python3 episodes.py record --summary "..." [--feature 001-auth] [--phase Execute]
+    python3 episodes.py list [--status episodic]
+    python3 episodes.py archive EP-001
+    python3 episodes.py prune [--days 90]
+    python3 episodes.py promote EP-001 --title "..." --rule "..."
+
+Exit codes: 0 ok, 1 failure, 2 usage error.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+from _common import EXIT_FAILED, EXIT_OK, EXIT_USAGE
+from _memory_config import load_memory_lifecycle_config
+
+GATE = "episodes"
+STORE_PATH = Path(".specs/state/episodes.json")
+STATE_PATH = Path(".specs/STATE.md")
+STATUSES = ("working", "episodic", "archived", "promoted")
+INDEXABLE_STATUSES = {"episodic", "archived", "promoted"}
+
+
+def fail(message: str, code: int = EXIT_FAILED) -> int:
+    print(f"[{GATE}] FAIL - {STORE_PATH}")
+    print(f"  error   {message}")
+    return code
+
+
+def ok(message: str) -> int:
+    print(f"[{GATE}] PASS - {message}")
+    return EXIT_OK
+
+
+def utc_now() -> str:
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat()
+
+
+def load_store() -> dict:
+    if not STORE_PATH.is_file():
+        return {"episodes": []}
+    return json.loads(STORE_PATH.read_text(encoding="utf-8"))
+
+
+def save_store(store: dict) -> None:
+    STORE_PATH.parent.mkdir(parents=True, exist_ok=True)
+    STORE_PATH.write_text(json.dumps(store, indent=2) + "\n", encoding="utf-8")
+
+
+def next_episode_id(store: dict) -> str:
+    max_id = 0
+    for episode in store.get("episodes") or []:
+        match = re.fullmatch(r"EP-(\d+)", str(episode.get("id") or ""), re.IGNORECASE)
+        if match:
+            max_id = max(max_id, int(match.group(1)))
+    return f"EP-{max_id + 1:03d}"
+
+
+def read_state_feature() -> str | None:
+    if not STATE_PATH.is_file():
+        return None
+    for line in STATE_PATH.read_text(encoding="utf-8").splitlines():
+        match = re.match(r"^-\s*Feature:\s*(.+)$", line.strip())
+        if match:
+            value = match.group(1).strip()
+            if value and value not in {"—", "-"}:
+                return value
+    return None
+
+
+def read_state_phase() -> str | None:
+    if not STATE_PATH.is_file():
+        return None
+    for line in STATE_PATH.read_text(encoding="utf-8").splitlines():
+        match = re.match(r"^-\s*Phase:\s*(.+)$", line.strip())
+        if match:
+            value = match.group(1).strip()
+            if value and value not in {"—", "-"}:
+                return value
+    return None
+
+
+def find_episode(store: dict, episode_id: str) -> dict | None:
+    target = episode_id.upper()
+    for episode in store.get("episodes") or []:
+        if str(episode.get("id") or "").upper() == target:
+            return episode
+    return None
+
+
+def record_episode(summary: str, feature_id: str | None, phase: str | None, json_output: bool) -> int:
+    summary = summary.strip()
+    if not summary:
+        return fail("summary is required")
+
+    store = load_store()
+    episode = {
+        "id": next_episode_id(store),
+        "feature_id": feature_id or read_state_feature(),
+        "phase": phase or read_state_phase(),
+        "summary": summary,
+        "status": "working",
+        "recorded_at": utc_now(),
+        "source": "manual",
+    }
+    store.setdefault("episodes", []).append(episode)
+    save_store(store)
+
+    if json_output:
+        print(json.dumps(episode, indent=2))
+    else:
+        ok(f"recorded {episode['id']} ({episode['status']})")
+    return EXIT_OK
+
+
+def list_episodes(status: str | None, json_output: bool) -> int:
+    store = load_store()
+    episodes = store.get("episodes") or []
+    if status:
+        episodes = [ep for ep in episodes if str(ep.get("status") or "").lower() == status.lower()]
+
+    if json_output:
+        print(json.dumps({"count": len(episodes), "episodes": episodes}, indent=2))
+    else:
+        for episode in episodes:
+            print(
+                f"{episode.get('id')} [{episode.get('status')}] "
+                f"{episode.get('feature_id') or '-'} — {episode.get('summary')}"
+            )
+    return EXIT_OK
+
+
+def archive_episode(episode_id: str, json_output: bool) -> int:
+    store = load_store()
+    episode = find_episode(store, episode_id)
+    if not episode:
+        return fail(f"episode not found: {episode_id}")
+
+    if episode.get("status") != "working":
+        return fail(f"only working episodes can be archived (current: {episode.get('status')})")
+
+    episode["status"] = "episodic"
+    episode["archived_at"] = utc_now()
+    save_store(store)
+
+    if json_output:
+        print(json.dumps(episode, indent=2))
+    else:
+        ok(f"archived {episode['id']} -> episodic")
+    return EXIT_OK
+
+
+def prune_episodes(days: int | None, json_output: bool) -> int:
+    config = load_memory_lifecycle_config()
+    retention = days if days is not None else int(config.get("retention_days") or 90)
+    cutoff = datetime.now(timezone.utc) - timedelta(days=retention)
+
+    store = load_store()
+    kept = []
+    removed = []
+    for episode in store.get("episodes") or []:
+        if str(episode.get("status") or "") != "episodic":
+            kept.append(episode)
+            continue
+        raw = str(episode.get("archived_at") or episode.get("recorded_at") or "")
+        try:
+            recorded = datetime.fromisoformat(raw.replace("Z", "+00:00"))
+        except ValueError:
+            kept.append(episode)
+            continue
+        if recorded < cutoff:
+            removed.append(episode)
+        else:
+            kept.append(episode)
+
+    store["episodes"] = kept
+    save_store(store)
+
+    summary = {"removed": len(removed), "retention_days": retention, "ids": [ep["id"] for ep in removed]}
+    if json_output:
+        print(json.dumps(summary, indent=2))
+    else:
+        ok(f"pruned {len(removed)} episodic episode(s) older than {retention} days")
+    return EXIT_OK
+
+
+def promote_episode(episode_id: str, title: str, rule: str, json_output: bool) -> int:
+    store = load_store()
+    episode = find_episode(store, episode_id)
+    if not episode:
+        return fail(f"episode not found: {episode_id}")
+
+    if episode.get("status") not in {"episodic", "archived"}:
+        return fail(f"only episodic/archived episodes can be promoted (current: {episode.get('status')})")
+
+    title = title.strip() or str(episode.get("summary") or episode_id)
+    rule = rule.strip() or str(episode.get("summary") or "")
+    if not rule:
+        return fail("rule is required for promotion")
+
+    episode["status"] = "promoted"
+    episode["promoted_at"] = utc_now()
+    episode["lesson_title"] = title
+    episode["lesson_rule"] = rule
+    save_store(store)
+
+    if json_output:
+        print(json.dumps(episode, indent=2))
+    else:
+        ok(f"promoted {episode['id']} — feed into lessons.py add when grounded in validation")
+    return EXIT_OK
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Episodic memory lifecycle")
+    sub = parser.add_subparsers(dest="command")
+
+    record = sub.add_parser("record", help="capture a working-session episode")
+    record.add_argument("--summary", required=True)
+    record.add_argument("--feature")
+    record.add_argument("--phase")
+    record.add_argument("--json", action="store_true")
+    record.set_defaults(
+        func=lambda args: record_episode(args.summary, args.feature, args.phase, args.json)
+    )
+
+    list_cmd = sub.add_parser("list", help="list episodes")
+    list_cmd.add_argument("--status", choices=STATUSES)
+    list_cmd.add_argument("--json", action="store_true")
+    list_cmd.set_defaults(func=lambda args: list_episodes(args.status, args.json))
+
+    archive = sub.add_parser("archive", help="move working -> episodic")
+    archive.add_argument("episode_id")
+    archive.add_argument("--json", action="store_true")
+    archive.set_defaults(func=lambda args: archive_episode(args.episode_id, args.json))
+
+    prune = sub.add_parser("prune", help="drop old episodic episodes")
+    prune.add_argument("--days", type=int)
+    prune.add_argument("--json", action="store_true")
+    prune.set_defaults(func=lambda args: prune_episodes(args.days, args.json))
+
+    promote = sub.add_parser("promote", help="mark episode promoted for lesson graduation")
+    promote.add_argument("episode_id")
+    promote.add_argument("--title")
+    promote.add_argument("--rule")
+    promote.add_argument("--json", action="store_true")
+    promote.set_defaults(
+        func=lambda args: promote_episode(args.episode_id, args.title or "", args.rule or "", args.json)
+    )
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not args.command:
+        parser.print_help()
+        return EXIT_USAGE
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/memory_index.py

@@ -404,6 +404,52 @@ def index_lessons(conn: sqlite3.Connection, now: str) -> tuple[int, int]:
     return entity_count, chunk_count
 
 
+def index_episodes(conn: sqlite3.Connection, now: str) -> tuple[int, int]:
+    episodes_path = SPECS_DIR / "state" / "episodes.json"
+    if not episodes_path.is_file():
+        return 0, 0
+
+    payload = json.loads(episodes_path.read_text(encoding="utf-8"))
+    entity_count = 0
+    chunk_count = 0
+
+    for episode in payload.get("episodes") or []:
+        episode_id = str(episode.get("id") or "").strip()
+        if not episode_id:
+            continue
+        status = str(episode.get("status") or "").strip().lower()
+        if status not in {"episodic", "archived", "promoted"}:
+            continue
+
+        feature_id = str(episode.get("feature_id") or "").strip() or None
+        summary = str(episode.get("summary") or episode_id)
+        upsert_entity(
+            conn,
+            episode_id,
+            "episode",
+            summary[:120],
+            str(episodes_path),
+            now,
+        )
+        entity_count += 1
+
+        if feature_id:
+            upsert_relation(conn, feature_id, episode_id, "contains")
+            upsert_relation(conn, episode_id, feature_id, "documents")
+
+        body_parts = [summary]
+        for key in ("phase", "lesson_title", "lesson_rule"):
+            value = episode.get(key)
+            if value:
+                body_parts.append(f"{key}: {value}")
+        body = "\n".join(body_parts).strip()
+        chunk_id = f"chunk:episode:{episode_id}"
+        upsert_chunk(conn, chunk_id, episode_id, "episode", str(episodes_path), body, now)
+        chunk_count += 1
+
+    return entity_count, chunk_count
+
+
 def rebuild(json_output: bool = False) -> int:
     if not SPECS_DIR.is_dir():
         return fail(".specs/ not found — run install first")
@@ -543,6 +589,9 @@ def rebuild(json_output: bool = False) -> int:
         lesson_entities, lesson_chunks = index_lessons(conn, now)
         entity_count += lesson_entities
         chunk_count += lesson_chunks
+        episode_entities, episode_chunks = index_episodes(conn, now)
+        entity_count += episode_entities
+        chunk_count += episode_chunks
         prune_embeddings(conn)
         conn.commit()
 

package/skills/agent-architecture.md

@@ -50,6 +50,9 @@ Structural gates run **before** owner review, so they cannot drift when the mode
 | After parallel wave merge | `npx @luizsantiago/spec-guardrails workspace-cleanup [feature] --force` |
 | Before editing paths outside task Files | `npx @luizsantiago/spec-guardrails context-guard check-edit <path> [--op write]` — **Cursor:** also auto-runs via `.cursor/hooks/` on write/edit tools |
 | Before claiming feature complete | `npx @luizsantiago/spec-guardrails context-guard check-complete [feature]` |
+| Session episodic note | `npx @luizsantiago/spec-guardrails episodes record --summary "…"` |
+| Brownfield code lookup | `npx @luizsantiago/spec-guardrails code-index rebuild` · `code-index search "…"` |
+| Shell safety check | `npx @luizsantiago/spec-guardrails sandbox check-command "<cmd>"` |
 | Solution exploration (explicit) | `npx @luizsantiago/spec-guardrails solution-explore init <feature> --candidates A,B` |
 | Before exploration decision | `npx @luizsantiago/spec-guardrails solution-explore validate [feature]` |
 | Retrieve related context | `npx @luizsantiago/spec-guardrails memory-retrieve "<query>"` |

package/templates/config.yaml.example

@@ -51,6 +51,9 @@ effects:
 
 # Memory retrieval (optional — hybrid FTS + graph + semantic)
 memory:
+  lifecycle:
+    retention_days: 90
+    auto_archive_on_handoff: false
   retrieval:
     semantic: false
     provider: none
@@ -60,6 +63,13 @@ memory:
     semantic_weight: 0.4
     graph_depth: 1
 
+# Soft OS sandbox (optional — policy, not containers)
+sandbox:
+  mode: warn
+  deny_patterns:
+    - "rm\\s+-rf"
+    - "curl.*\\|.*sh"
+
 # Project-specific overrides (appended on top of preset + rules above):
 # overrides:
 #   rules:

package/templates/cursor/hooks/sandbox-shell.mjs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+/**
+ * Cursor beforeShellExecution hook — soft sandbox for shell commands.
+ */
+import { readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { pathToFileURL } from "node:url";
+
+/**
+ * @param {Record<string, unknown>} input
+ * @returns {string | null}
+ */
+export function extractShellCommand(input) {
+  const command =
+    input.command ??
+    input.shellCommand ??
+    input.tool_input?.command ??
+    input.toolInput?.command;
+  return typeof command === "string" && command.trim() ? command.trim() : null;
+}
+
+function allow() {
+  process.stdout.write(`${JSON.stringify({ permission: "allow" })}\n`);
+  process.exit(0);
+}
+
+/**
+ * @param {string} reason
+ * @param {boolean} strict
+ */
+function respond(reason, strict) {
+  if (strict) {
+    process.stdout.write(
+      `${JSON.stringify({
+        permission: "deny",
+        user_message: `Spec Guardrails sandbox blocked this command: ${reason}`,
+        agent_message: `Sandbox policy blocked the shell command. ${reason}`,
+      })}\n`,
+    );
+    process.exit(2);
+  }
+
+  process.stdout.write(
+    `${JSON.stringify({
+      permission: "allow",
+      agent_message: `Sandbox warning: ${reason}`,
+    })}\n`,
+  );
+  process.exit(0);
+}
+
+function main() {
+  let input = null;
+  try {
+    input = JSON.parse(readFileSync(0, "utf8"));
+  } catch {
+    allow();
+  }
+
+  const command = extractShellCommand(input ?? {});
+  if (!command) {
+    allow();
+  }
+
+  const cli = process.env.SPEC_GUARDRAILS_CLI ?? "npx @luizsantiago/spec-guardrails";
+  const result = spawnSync(cli, ["sandbox", "check-command", command, "--json"], {
+    encoding: "utf8",
+    shell: process.platform === "win32",
+  });
+
+  if (result.status === 0 && result.stdout) {
+    try {
+      const parsed = JSON.parse(result.stdout);
+      if (parsed.reason && parsed.mode === "strict" && parsed.allowed === false) {
+        respond(parsed.reason, true);
+      }
+      if (parsed.reason && parsed.mode === "warn") {
+        respond(parsed.reason, false);
+      }
+    } catch {
+      allow();
+    }
+  }
+
+  if (result.status !== 0 && result.stdout) {
+    try {
+      const parsed = JSON.parse(result.stdout);
+      if (parsed.reason) {
+        respond(parsed.reason, parsed.mode === "strict");
+      }
+    } catch {
+      allow();
+    }
+  }
+
+  allow();
+}
+
+const entry = process.argv[1] ? pathToFileURL(process.argv[1]).href : "";
+if (entry && import.meta.url === entry) {
+  main();
+}

package/templates/cursor/hooks.json

@@ -7,6 +7,12 @@
         "matcher": "Write|StrReplace|search_replace|EditNotebook|ApplyPatch",
         "failClosed": false
       }
+    ],
+    "beforeShellExecution": [
+      {
+        "command": ".cursor/hooks/sandbox-shell.mjs",
+        "failClosed": false
+      }
     ]
   }
 }