@luizsantiago/spec-guardrails 3.8.0 → 4.0.0

package/README.md

@@ -3,153 +3,175 @@
 [![npm version](https://img.shields.io/npm/v/@luizsantiago/spec-guardrails.svg)](https://www.npmjs.com/package/@luizsantiago/spec-guardrails)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-**Keep AI coding agents honest — specify the work, prove each step, verify independently.**
+**Governed spec-driven development for AI coding agents.**
 
-npm: [`@luizsantiago/spec-guardrails`](https://www.npmjs.com/package/@luizsantiago/spec-guardrails) **3.8.x**
+Spec Guardrails is a process kit that installs phase guides, persistent project memory, and optional structural checks into your repository. Teams keep ownership of requirements and approval gates; agents follow a repeatable path from written intent to verified delivery.
 
----
+npm: [`@luizsantiago/spec-guardrails`](https://www.npmjs.com/package/@luizsantiago/spec-guardrails) **4.0.x**
 
-## What is Spec Guardrails?
+---
 
-**Spec Guardrails** is a **process kit** for AI-assisted software development. It does not replace your app, framework, or tests. It gives your agent a repeatable way to work:
+## What it is
 
-1. **Write down the goal** before coding (`spec.md`)
-2. **Break work into small jobs** (`tasks.md`)
-3. **Implement in waves** with real checks
-4. **Verify with fresh eyes** — proof, not “trust me”
+Spec Guardrails is **not** an application framework, a vector database, or a replacement for your stack. It is an **operating model** for AI-assisted engineering:
 
-Everything important lives in **`.specs/`** in your repo so the project remembers decisions across chats and teammates.
+| Layer | Role |
+| --- | --- |
+| **Phase guides** | Instructions the agent loads one step at a time |
+| **Project memory** | `.specs/` — specs, tasks, validation, and state that survive chat sessions |
+| **Structural checks** | Optional Python gates that enforce document shape and evidence hooks |
 
-**You** approve specs and tasks. **The agent** follows phase guides and runs checks. **Gates** (optional Python scripts) can **stop** the workflow when paperwork or evidence is missing.
+The default loop is **Specify → Tasks → Execute → Verify → Archive**. You approve specs and task plans; the agent implements in waves and produces proof before work is considered done.
 
-> **Plain-language guide:** [Overview](docs/guide/Overview.md) · [How it works](docs/guide/How-it-works.md) · [Quick start](docs/guide/Quick-start.md)
+Full narrative: [Overview](docs/guide/Overview.md) · [How it works](docs/guide/How-it-works.md)
 
 ---
 
-## What it is not
+## Why teams use it
+
+| Benefit | Outcome |
+| --- | --- |
+| **Traceability** | Requirements, jobs, and verification live in version-controlled artifacts |
+| **Controlled autonomy** | Agents propose and execute; humans approve scope, design forks, and git tiers |
+| **Progressive depth** | Quick fixes skip ceremony; complex work gets discuss, design, and task graphs |
+| **Platform-agnostic** | Cursor, Claude Code, GitHub Copilot, Codex, and other agents via root `AGENTS.md` |
+| **Token efficiency** | One phase guide per turn instead of dumping the entire playbook |
+| **Optional enforcement** | Process mode (Node only) or Brakes mode (Node + Python gates) |
 
-- Not a code generator or a new framework
-- Not a vector database or “AI memory” that reads your whole codebase
-- Not automatic push/merge/deploy — you stay in control of git tiers
-- Not a replacement for code review or product judgment
+Process vs Brakes: [FAQ](docs/guide/FAQ.md#process-vs-brakes) · Guarantees: [Guarantees matrix](docs/guide/Guarantees-matrix.md)
 
 ---
 
-## Install (once per project)
+## Install
+
+In your project root:
 
 ```bash
 npx @luizsantiago/spec-guardrails install
 ```
 
-| Requirement | Purpose |
+Re-run after upgrading the package; existing `.specs/` notes are preserved. Check readiness with `doctor`.
+
+| Requirement | Role |
 | --- | --- |
 | **Node.js 18+** | Required — CLI and install |
-| **Python 3.10+** | Optional — enables **Brakes mode** (automatic gates). Without Python you still get the full workflow in **Process mode** |
-
-Re-run `install` after upgrading the package. Your `.specs/` notes and `STATE.md` are kept.
+| **Python 3.10+** | Optional — enables Brakes mode (automatic gates) |
 
-Check readiness: `npx @luizsantiago/spec-guardrails doctor`
-
-Works with **Cursor, Claude Code, GitHub Copilot, OpenAI Codex**, and other agents via root `AGENTS.md`. See [Platform parity](docs/guide/Platform-parity.md).
+Platform setup: [Platform parity](docs/guide/Platform-parity.md) · Release notes: [CHANGELOG](docs/CHANGELOG.md)
 
 ---
 
-## How you use it day to day
+## How you work day to day
+
+Interaction happens in **agent chat**, not the terminal. The agent runs CLI helpers and gates when needed.
 
-You talk to the agent in **chat**, not the terminal. These are **agent commands** (phrases the agent understands):
+### Core commands
 
-| Command | When to use |
+| Command | Use when |
 | --- | --- |
-| `/specify` | Start a real feature — written requirements first |
-| `/tasks` | Shopping list of jobs after you approve the spec |
-| `/loop` | Implement — one wave at a time |
-| `/verify` | Proof after the last job — use a **fresh** chat when possible |
-| `/quick` | Tiny fix only (≤3 files, no big design decisions) |
+| `/specify` | Starting any non-trivial feature — requirements in writing first |
+| `/elicit` | Kickoff or request is vague — structured Q&A before Specify *(optional)* |
+| `/tasks` | Spec approved — break work into a job list |
+| `/loop` | Implementation — one wave at a time |
+| `/verify` | All jobs done — independent proof *(prefer a fresh chat)* |
+| `/archive` | Feature validated — fold into project memory |
+| `/quick` | Tiny fix only (≤3 files, no design fork) |
 
 **Typical path:** `/specify` → approve → `/tasks` → approve → `/loop` → `/verify` → `/archive`
 
-You do **not** need to memorize CLI commands. The agent runs gates and helpers for you when **Brakes mode** is available.
+When input is still exploratory, `/explore` or `/elicit` may come first. The agent suggests depth; it does not block Specify without approval.
 
-**Full command reference:** [Agent commands](docs/guide/agent-commands.md)
+Command reference: [Agent commands](docs/guide/agent-commands.md) · Entry paths: [Overview → Three ways to start](docs/guide/Overview.md#three-ways-to-start-pick-one)
 
----
+### Optional capabilities
 
-## Two modes (same product)
+Enable when the work warrants them — most teams start with the core loop only.
 
-| Mode | You need | What changes |
-| --- | --- | --- |
-| **Process** | Node only | Full workflow + `.specs/` memory + phase skills |
-| **Brakes** | Node + Python | Same + scripts that **exit non-zero** when specs, tasks, or evidence are incomplete |
-
-Both are intentional. Add Python when you want automatic stop signs, not just checklists.
+| Capability | Purpose |
+| --- | --- |
+| Memory search | Retrieve past specs, validations, and kickoff briefs |
+| Context guards | Scope check before edit or “done” (Cursor: hooks) |
+| Episodic memory | Session notes → lessons for future runs |
+| Code index | Lightweight brownfield file and symbol map |
+| Solution exploration | Compare implementation options before committing |
+| Sandbox / execution policy | Warn or block destructive shell commands and path drift |
+| Semantic retrieval | Search by meaning — off by default |
 
-Details: [FAQ → Process vs Brakes](docs/guide/FAQ.md#process-vs-brakes)
+Guides: [Memory](docs/guide/Memory.md) · [Brownfield context](docs/guide/brownfield-context.md) · [Safety & exploration](docs/guide/Overview.md)
 
 ---
 
-## What lands in your repo
+## What lands in your repository
 
 | Path | Role |
 | --- | --- |
-| `.cursor/skills/` (and Claude, Copilot, Codex trees) | Instructions the agent reads per phase |
-| `.specs/STATE.md` | Where you are — active feature, next step |
-| `.specs/features/NNN-slug/` | Spec, tasks, validation for each feature |
+| `.cursor/skills/` (+ Claude, Copilot, Codex trees) | Phase instructions for the agent |
+| `.specs/STATE.md` | Active feature and next step |
+| `.specs/features/NNN-slug/` | Spec, tasks, and validation per feature |
 | `.specs/guardrails/scripts/` | Python gates (Brakes mode) |
-| `.specs/config.yaml` | Optional project rules and policy |
+| `.specs/config.yaml` | Optional project rules and execution policy |
+
+Architecture: [Skills and hub](docs/guide/skills-and-hub.md) · [Architecture](docs/guide/Architecture.md)
 
 ---
 
-## Optional capabilities (use when you need them)
+## Documentation
 
-Most projects start with Specify → Tasks → Loop → Verify only. Turn these on when the work warrants it:
+Start with the guide that matches your question; each page links deeper where needed.
 
-| Capability | Plain purpose | Learn more |
+| Topic | Start here | Go deeper |
 | --- | --- | --- |
-| **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+) |
-| **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) |
+| Orientation | [Overview](docs/guide/Overview.md) | [Concepts](docs/guide/concepts.md) |
+| First session | [Quick start](docs/guide/Quick-start.md) | [Agent commands](docs/guide/agent-commands.md) |
+| Process model | [How it works](docs/guide/How-it-works.md) | [Loop patterns](docs/guide/loop-patterns.md) |
+| Enforcement | [Gates](docs/guide/gates.md) | [Gates and guarantees](docs/guide/Gates-and-guarantees.md) |
+| Long-running projects | [Memory](docs/guide/Memory.md) | [Brownfield context](docs/guide/brownfield-context.md) |
+| Questions | [FAQ](docs/guide/FAQ.md) | [Stability policy](docs/guide/Stability-policy.md) |
 
-**Default:** semantic search is **off**. FTS + graph search work without any API.
+Full index: [docs/guide/README.md](docs/guide/README.md)
 
 ---
 
-## Documentation
+## Contributing
 
-| Start here | Best for |
-| --- | --- |
-| **[Overview](docs/guide/Overview.md)** | Complete simple picture — workflow, layers, team use |
-| [Quick start](docs/guide/Quick-start.md) | First ten minutes |
-| [How it works](docs/guide/How-it-works.md) | Story from idea to archive |
-| [Memory](docs/guide/Memory.md) | `.specs/` memory and search — when and how much |
-| [FAQ](docs/guide/FAQ.md) | Common questions |
+We welcome focused improvements — skills, gates, CLI, docs, and tests. See [CONTRIBUTING.md](CONTRIBUTING.md) for layout, gate stability rules, and local checks.
 
-| Go deeper | Best for |
-| --- | --- |
-| [Agent commands](docs/guide/agent-commands.md) | Every `/specify`, `/loop`, CLI helper |
-| [Guarantees matrix](docs/guide/Guarantees-matrix.md) | Product promises → mechanisms |
-| [Gates](docs/guide/gates.md) | What each gate checks |
-| [Architecture](docs/guide/Architecture.md) | Core vs platform adapters |
-| [Concepts](docs/guide/concepts.md) | Spec-driven, loop, graph, tiers |
-| [Changelog](docs/CHANGELOG.md) | Version history |
+### Use Spec Guardrails to build your contribution
 
-Doc index: [docs/guide/README.md](docs/guide/README.md)
+The recommended workflow is to **dogfood the product**: install Spec Guardrails, describe your change through the agent phases, implement against approved artifacts, and verify before opening a PR.
 
----
+**In your own project or fork** — use the latest stable release from npm:
+
+```bash
+npx @luizsantiago/spec-guardrails@latest install
+npx @luizsantiago/spec-guardrails doctor
+```
+
+Then in chat: `/specify` (or `/elicit` if scope is unclear) → `/tasks` → `/loop` → `/verify`. Your `.specs/` folder holds the spec and proof that guided the change.
 
-## Upgrading
+**In this source repository** — work against the branch you are developing, not the published tarball:
 
 ```bash
-npx @luizsantiago/spec-guardrails install
+git clone https://github.com/luizssantiago92/spec-guardrails.git
+cd spec-guardrails
+npm install
+npm run guardrails -- install
+npm run guardrails -- doctor
 ```
 
-See [CHANGELOG](docs/CHANGELOG.md) for release notes.
+Edit source under `skills/`, `lib/`, `scripts/`, and `rules/`; re-run `npm run guardrails -- install` after skill or gate changes. Run `npm test` before every PR.
+
+| Path | Role |
+| --- | --- |
+| `skills/` | Hub and sister skills shipped to consumers |
+| `skills/references/` | Phase procedures (`specify.md`, `elicit.md`, …) |
+| `scripts/` | Deterministic Python gates |
+| `test/` | Node install tests and Python gate suites |
+
+Gate changes follow the adversarial test policy in [CONTRIBUTING.md](CONTRIBUTING.md). Credits: [docs/guide/credits.md](docs/guide/credits.md)
 
 ---
 
-## Contributing · Credits · License
+## License
 
-- [CONTRIBUTING.md](CONTRIBUTING.md)
-- [Credits](docs/guide/credits.md)
-- MIT — see [LICENSE](LICENSE)
+MIT — see [LICENSE](LICENSE).

package/index.js

@@ -35,6 +35,11 @@ import {
   listWorkspaces,
   prepareWorkspaces,
 } from "./lib/workspace-isolation.js";
+import {
+  formatDiscoverReport,
+  formatPromoteMessage,
+  reqAnalysisInit,
+} from "./lib/req-analysis.js";
 import {
   formatExplorationInit,
   formatExplorationStatus,
@@ -45,6 +50,11 @@ import {
   recordExplorationDecision,
   validateExplorationArtifact,
 } from "./lib/solution-exploration.js";
+import {
+  checkSandboxCommand,
+  formatSandboxCheck,
+  loadSandboxPolicy,
+} from "./lib/sandbox-policy.js";
 import {
   initProjectConfig,
   listPresets,
@@ -71,6 +81,12 @@ Commands:
   feature-init "<description>"       Allocate NNN-slug feature, STATE, local branch (Tier 0)
     [--no-branch]                    Skip git checkout -b
     [--no-spec]                      Skip spec.md stub
+  req-analysis init "<description>"    Scaffold requirements brief (/elicit phase)
+    [--scope project|feature]          project = macro brief; feature = one delivery (default: feature)
+    [--force]                          Replace existing brief scaffold
+  req-analysis discover                List local kickoff sources (prd.md, kickoff.md, …)
+  req-analysis promote                 Print next steps after brief approval
+    [--scope project|feature]          Match the brief scope
   archive-feature [feature]          Fold verified feature into ROADMAP + domain spec; reset STATE
     [--domain <slug>]                Domain folder under .specs/domains/ (default: feature slug)
     [--skip-verify]                  Skip validate-state (tests / recovery only)
@@ -113,6 +129,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 +637,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];
@@ -826,6 +901,65 @@ if (command === "--version" || command === "-v" || command === "version") {
     console.error(`❌ ${err.message}`);
     process.exit(1);
   }
+} else if (command === "req-analysis") {
+  try {
+    const sub = args[0];
+    const rest = args.slice(1);
+
+    if (sub === "init") {
+      let scope = "feature";
+      let force = false;
+      const positional = [];
+      for (let i = 0; i < rest.length; i += 1) {
+        const arg = rest[i];
+        if (arg === "--force") {
+          force = true;
+        } else if (arg === "--scope" && rest[i + 1]) {
+          scope = rest[i + 1];
+          i += 1;
+        } else if (arg.startsWith("--scope=")) {
+          scope = arg.slice("--scope=".length);
+        } else if (!arg.startsWith("--")) {
+          positional.push(arg);
+        }
+      }
+      const description = positional.join(" ").trim();
+      if (scope === "feature" && !description) {
+        throw new Error(
+          'Usage: req-analysis init "<description>" [--scope project|feature] [--force]',
+        );
+      }
+      const result = await reqAnalysisInit(description, { scope, force });
+      console.log(`✅ Elicitation scaffold (${result.scope})`);
+      for (const briefPath of result.paths) {
+        console.log(`   ${briefPath}`);
+      }
+      console.log("");
+      console.log(await formatDiscoverReport(process.cwd()));
+    } else if (sub === "discover") {
+      console.log(await formatDiscoverReport(process.cwd()));
+    } else if (sub === "promote") {
+      let scope = "feature";
+      let description = "";
+      for (let i = 0; i < rest.length; i += 1) {
+        const arg = rest[i];
+        if (arg.startsWith("--scope=")) {
+          scope = arg.slice("--scope=".length);
+        } else if (arg === "--scope" && rest[i + 1]) {
+          scope = rest[i + 1];
+          i += 1;
+        } else if (!arg.startsWith("--")) {
+          description = `${description} ${arg}`.trim();
+        }
+      }
+      console.log(formatPromoteMessage({ scope, description }));
+    } else {
+      throw new Error("Usage: req-analysis init | discover | promote");
+    }
+  } catch (err) {
+    console.error(`❌ ${err.message}`);
+    process.exit(1);
+  }
 } else if (command === "classify-change") {
   try {
     let json = false;

package/lib/constants.js

@@ -77,6 +77,7 @@ export const SKILL_ASSETS = [
 /** @type {{ file: string, remotePath: string }[]} */
 export const REFERENCE_ASSETS = [
   { file: "explore.md", remotePath: "skills/references/explore.md" },
+  { file: "elicitation.md", remotePath: "skills/references/elicitation.md" },
   { file: "solution-exploration.md", remotePath: "skills/references/solution-exploration.md" },
   { file: "project-init.md", remotePath: "skills/references/project-init.md" },
   { file: "constitution.md", remotePath: "skills/references/constitution.md" },
@@ -115,6 +116,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 };