@luizsantiago/spec-guardrails 3.6.0 → 3.8.0

package/README.md

@@ -5,207 +5,136 @@
 
 **Keep AI coding agents honest — specify the work, prove each step, verify independently.**
 
-| | |
-| --- | --- |
-| **Problem** | Agents ship “looks good” with thin specs, missing evidence, and the same context that wrote the code declaring victory. |
-| **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.6.x**
+npm: [`@luizsantiago/spec-guardrails`](https://www.npmjs.com/package/@luizsantiago/spec-guardrails) **3.8.x**
 
 ---
 
-## Install
-
-```bash
-npx @luizsantiago/spec-guardrails install
-```
+## What is Spec Guardrails?
 
-### What you need
+**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:
 
-| Requirement | Role |
-| --- | --- |
-| **Node.js 18+** | Required — runs the CLI and `install` |
-| **Python 3.10+** | Activates **Brakes mode** — the **full** kit with Python structural gates (`validate-spec`, `validate-tasks`, …). Gates stay Python by design. Without Python you stay in **Process mode**: same phases and checklists, no exit-code enforcement. Run [`doctor`](#install) to see which mode you are in |
+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”
 
-### What install does
+Everything important lives in **`.specs/`** in your repo so the project remembers decisions across chats and teammates.
 
-| Lands in your project | Purpose |
-| --- | --- |
-| `.cursor/skills/` + `.claude/skills/` + `.github/skills/` + `.codex/skills/` | Hub, phase references, sister skills (**shipped adapters** — same content, product-specific paths) |
-| `.specs/guardrails/scripts/` | Python gate scripts (Brakes mode) |
-| `.specs/STATE.md`, `.specs/features/`, … | Project memory (any agent) |
-| `.cursor/rules/engineering-baseline.mdc` | Always-on Cursor rule |
+**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.
 
-**Agent environments:** the **core** (`.specs/`, CLI, hub, Python gates) works with any AI agent. **Install** ships adapters for **Cursor, Claude Code, GitHub Copilot, and OpenAI Codex** (plus root `AGENTS.md`). See [Architecture](docs/guide/Architecture.md).
-
-Re-run `install` anytime to refresh skills; your `.specs/` decisions and `STATE.md` are kept.
-
-### Governance focus (3.2+)
-
-Spec Guardrails is a **single product**: governance, evidence, verification, and controlled execution for agentic software development — not a bundle of companion packages.
-
-| Capability | What it does |
-| --- | --- |
-| **Artifact gates** | Structural quality for spec, tasks, and cross-artifact consistency — with **blocking / warning / info** severity |
-| **Parallel waves** | `loop-plan` computes safe parallel groups; `workspace-prepare` isolates tasks in git worktrees |
-| **Execution policy** | Budgets, path scope, and escalation rules in `.specs/config.yaml` — consult via `execution-policy` |
-| **Independent verify** | Fresh-context verification with evidence-or-zero (`validate-state`) |
-
-| Need | Command |
-| --- | --- |
-| First time / upgrade | `install` |
-| Existing codebase | `project-init` (optional) |
-| Something looks wrong | `doctor` |
-| Full CLI list | `--help` |
+> **Plain-language guide:** [Overview](docs/guide/Overview.md) · [How it works](docs/guide/How-it-works.md) · [Quick start](docs/guide/Quick-start.md)
 
 ---
 
-## How it works in one screen
+## What it is not
 
-Four ideas stack — full explanation: **[Concepts](docs/guide/concepts.md)**
-
-| Idea | What it is | What it does |
-| --- | --- | --- |
-| **Spec-driven** | Written plan before code | `spec.md` + `tasks.md`; evidence before “done” |
-| **Brakes / Gates** | Structural stop-gates | Python scripts exit non-zero when paperwork or evidence is missing |
-| **Loop** | Execute in waves | `loop-plan` picks the next jobs; sub-agents when files don’t overlap |
-| **Graph** | Parallel task map | `task-graph.md` — safe parallelism without file collisions |
-| **Memory** | Persistent project state | `.specs/` — specs, decisions, and handoff survive across chats |
-
-**You** approve specs and tasks. **The agent** runs gates and implements. **Gates** exit non-zero when paperwork or evidence is missing.
-
-Plain-language tour: [Home](docs/guide/Home.md) · [How it works](docs/guide/How-it-works.md) · [Quick start](docs/guide/Quick-start.md)
+- 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
 
 ---
 
-## Operating modes
-
-Two modes, one package — pick how much rigor you want:
-
-| Mode | Runtime | What you get | Best for |
-| --- | --- | --- | --- |
-| **Process** | Node.js 18+ | Spec-driven workflow, `.specs/` memory, progressive loading, independent `/verify` | Flexible ceremony, exploration, teams that enforce by review |
-| **Brakes** | Node + **Python 3.10+** | Everything in Process **plus** Python gates from the [Guarantees matrix](#guarantees-matrix) — exit ≠ 0 → stop and fix | The **full Spec Guardrails** — traceability, evidence, and structural guarantees enforced automatically |
-
-**Gates stay Python.** That is the product: Brakes mode is the complete version with automated enforcement. Process mode is the same loop without exit-code brakes — intentional, not incomplete.
-
-Install Python when you want gates to fire; run `doctor` to confirm Brakes are available.
+## Install (once per project)
 
----
+```bash
+npx @luizsantiago/spec-guardrails install
+```
 
-## Guarantees matrix
+| Requirement | Purpose |
+| --- | --- |
+| **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** |
 
-**Guarantees are the product.** Commands are implementation.
+Re-run `install` after upgrading the package. Your `.specs/` notes and `STATE.md` are kept.
 
-| Guarantee | Mechanism | Mode | Enforcement |
-| --- | --- | --- | --- |
-| Intent exists before code | `validate-spec` | Brakes | Hard gate |
-| Tasks derive from requirements | `analyze-artifacts` | Brakes | Hard gate |
-| Task shape and graph when needed | `validate-tasks` | Brakes | Hard gate |
-| Requirements stay traceable | `validate-traceability` | Brakes | Hard gate |
-| Quick evidence is complete | `validate-quick` | Brakes | Hard gate |
-| Dependencies respected in Execute | `loop-plan` | Brakes | Hard gate |
-| Parallel work is file-safe | `task-graph.md` + `validate-tasks` | Process + Brakes | Artifact + gate |
-| Completion cites evidence | `validate-state` | Brakes | Hard gate |
-| Commits follow policy | `check-commit` | Brakes | Hard gate |
-| Lessons grounded after FAIL | `lessons` | Brakes | Hard gate |
-| Verification is independent | `/verify` + `validate.md` | Process | Phase skill |
-| Knowledge survives chats | `.specs/` + `archive-feature` | Process | Install + CLI |
+Check readiness: `npx @luizsantiago/spec-guardrails doctor`
 
-Full matrix, limits, and phase diagram → **[Guarantees matrix](docs/guide/Guarantees-matrix.md)** · [Architecture](docs/guide/Architecture.md) (Core + adapters)
+Works with **Cursor, Claude Code, GitHub Copilot, OpenAI Codex**, and other agents via root `AGENTS.md`. See [Platform parity](docs/guide/Platform-parity.md).
 
 ---
 
-## Token cost
+## How you use it day to day
 
-Progressive loading is the main cost win: **one working set per turn**, not the entire playbook.
+You talk to the agent in **chat**, not the terminal. These are **agent commands** (phrases the agent understands):
 
-| Profile | Est. tokens | When |
-| ---: | ---: | --- |
-| Naive full dump (don’t) | ~31k | Loading every skill + reference every message |
-| Specify turn | ~9k | `/specify` — hub + `specify.md` + standards |
-| Tasks turn | ~10k | `/tasks` — hub + `tasks.md` + task-graph skill |
-| Execute `/loop` (one wave) | ~4k | One implement wave (inline or parallel) |
-| Verify turn | ~6k | Independent reviewer stack |
+| Command | When to use |
+| --- | --- |
+| `/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) |
 
-Savings vs full dump: **~72%** (Specify), **~86%** (Execute). Numbers from `lib/token-cost.js`; CI guardrails in `test/test_token_cost.test.js`. Order-of-magnitude only — not a billing API.
+**Typical path:** `/specify` → approve → `/tasks` → approve → `/loop` → `/verify` → `/archive`
 
-More: [Token efficiency](docs/guide/Token-efficiency.md)
+You do **not** need to memorize CLI commands. The agent runs gates and helpers for you when **Brakes mode** is available.
 
----
+**Full command reference:** [Agent commands](docs/guide/agent-commands.md)
 
-## Complexity tiers (how work flows)
+---
 
-The hub **Complexity Router** picks how much ceremony a feature needs — Quick, Simple, Medium, Complex, or Parallel. It is **not** a separate product feature; it is how the agent decides which phases to run.
+## Two modes (same product)
 
-| Tier | Typical scope | Path |
+| Mode | You need | What changes |
 | --- | --- | --- |
-| **Quick** | ≤3 files, no new deps | `/quick` → verify → commit |
-| **Simple** | Small localized change | `/specify` → `/loop` → `/verify` |
-| **Medium** | New feature, <10 tasks | `/specify` → `/tasks` → `/loop` → `/verify` → `/archive` |
-| **Complex** | APIs, architecture, infra | + `/discuss`, `/plan`, optional security/QA on verify |
-| **Parallel** | Splittable work | Above + `/task-graph` when 3+ tasks |
-
-Rules and examples: [Concepts → Complexity tiers](docs/guide/concepts.md#complexity-tiers--how-the-agent-chooses-depth)
-
----
+| **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 |
 
-## Hub and skills (summary)
+Both are intentional. Add Python when you want automatic stop signs, not just checklists.
 
-Install copies a **hub** (`agent-architecture.md`), **phase references** (`references/*.md`), and **sister skills** (security, task-graph, …). The agent loads **one phase file at a time**.
+Details: [FAQ → Process vs Brakes](docs/guide/FAQ.md#process-vs-brakes)
 
-| Load order | Layer | Role | Examples |
-| ---: | --- | --- | --- |
-| 1 | **Hub** | Contract, complexity router, gate schedule | `agent-architecture.md` |
-| 2 | **Reference** | One phase procedure per turn | `specify.md`, `implement.md`, `validate.md` |
-| 3 | **Sister** (optional) | Cross-cutting depth, on demand | `engineering-standards.md`, `task-graph-engineering.md` |
-| 4 | **Gate** | Automatic check at the boundary | `validate-spec`, `loop-plan`, `check-commit` |
+---
 
-Conditional sisters (`appsec.md`, `qa-strategy.md`, …) load **one at a time** on Verify when risk warrants it.
+## What lands in your repo
 
-Full map: **[Skills and hub](docs/guide/skills-and-hub.md)**
+| 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 |
+| `.specs/guardrails/scripts/` | Python gates (Brakes mode) |
+| `.specs/config.yaml` | Optional project rules and policy |
 
 ---
 
-## Gates (summary)
+## Optional capabilities (use when you need them)
 
-Commands implement the guarantees above. Scripts in `.specs/guardrails/scripts/`. **Exit ≠ 0 → stop and fix.**
+Most projects start with Specify → Tasks → Loop → Verify only. Turn these on when the work warrants it:
 
-| When | Gate | What it blocks |
+| Capability | Plain purpose | Learn more |
 | --- | --- | --- |
-| Before approving spec | `validate-spec` | Incomplete or untestable spec |
-| Before approving tasks | `analyze-artifacts` | Spec ↔ tasks drift |
-| Before approving tasks | `validate-tasks` | Bad tasks; missing graph when 3+ tasks |
-| After tasks / with validation | `validate-traceability` | REQ missing from tasks or coverage lines |
-| End of `/quick` | `validate-quick` | Incomplete Quick TASK/SUMMARY; >3 files; sensitive paths |
-| Each `/loop` wave | `loop-plan` | Blocked dependencies; shows parallel groups |
-| Each commit | `check-commit` | Non-Conventional commit message |
-| Before “done” | `validate-state` | Fake PASS without test evidence |
-| After Verify FAIL | `lessons` | Ungrounded “lessons learned” |
-| After Verify PASS | `archive-feature` | (CLI) folds feature into domain memory |
-
-Full reference: **[Gates](docs/guide/gates.md)** · [Guarantees matrix](docs/guide/Guarantees-matrix.md) · [Gates and guarantees](docs/guide/Gates-and-guarantees.md)
+| **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) |
+
+**Default:** semantic search is **off**. FTS + graph search work without any API.
 
 ---
 
 ## Documentation
 
-| Doc | For |
+| Start here | Best for |
 | --- | --- |
-| [Guarantees matrix](docs/guide/Guarantees-matrix.md) | Product promises → mechanisms |
-| [Architecture](docs/guide/Architecture.md) | Core vs platform adapters |
-| [Agent commands](docs/guide/agent-commands.md) | Every `/specify`, `/loop`, `/verify`, … — purpose, when, examples |
+| **[Overview](docs/guide/Overview.md)** | Complete simple picture — workflow, layers, team use |
 | [Quick start](docs/guide/Quick-start.md) | First ten minutes |
-| [Concepts](docs/guide/concepts.md) | Spec-driven + guardrails + loop + graph |
-| [Skills and hub](docs/guide/skills-and-hub.md) | What each skill file does |
-| [Gates](docs/guide/gates.md) | How each gate works |
-| [Platform parity](docs/guide/Platform-parity.md) | Shipped adapters (Cursor, Claude, Copilot, Codex) — core works with any agent |
-| [Restart PRD seed](docs/guide/Restart-prd-seed.md) | Clean-project PRD template for a single-package restart |
+| [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 |
-| [Changelog](docs/CHANGELOG.md) | Full version history |
 
-Start after install: [Quick start](docs/guide/Quick-start.md) · [Agent commands](docs/guide/agent-commands.md)
+| 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 |
+
+Doc index: [docs/guide/README.md](docs/guide/README.md)
 
 ---
 
@@ -215,59 +144,12 @@ Start after install: [Quick start](docs/guide/Quick-start.md) · [Agent commands
 npx @luizsantiago/spec-guardrails install
 ```
 
-| Version | What you gain |
-| --- | --- |
-| **3.6.x** | Hybrid retrieval (`memory-retrieve`); chunk FTS; optional semantic embed |
-| **3.5.x** | Solution exploration (`solution-explore`) — compare candidates from approved spec |
-| **3.4.x** | Contextual guards (`context-guard`); FTS memory search (`memory-search`) |
-| **3.3.x** | Intent/effect policy — `check-path --op read|write|delete` and `effects` config block |
-| **3.2.x** | Single-package focus; artifact gate severity labels; git worktree isolation CLI; execution policy (budget/scope/escalation) |
-| **3.1.x** | Copilot/Codex/AGENTS.md adapters; doctor Process + Brakes scores; `validate-traceability` / `validate-quick`; `classify-change` / `feature-status` |
-| **3.0.x** | Final name Spec Guardrails; `.specs/guardrails/`; no dual-path ([Migration](docs/guide/Migration.md)) |
-| **2.2.x** | Seatbelt-era paths & markers; `doctor` Execute hints; docs split from README |
-| **2.1.x** | `loop-plan` + parallel `/loop` waves |
-| **2.0.x** | Package rename → `@luizsantiago/spec-seatbelt` (superseded by 3.0) |
-| **1.1.x** | `project-init` for brownfield repos |
-| **0.9.x** | `archive-feature` + domain memory merge |
-
-Full history: [CHANGELOG](docs/CHANGELOG.md) · [Releases](https://github.com/luizssantiago92/spec-guardrails/releases) · [Stability policy](docs/guide/Stability-policy.md)
-
-Lineage: `agentic-harness` → `spec-seatbelt` → **`spec-guardrails` (final)**. Run `install` once after switching. See [Migration](docs/guide/Migration.md).
+See [CHANGELOG](docs/CHANGELOG.md) for release notes.
 
 ---
 
-## Contributing
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) — tests, gate freeze policy, local `npm run guardrails -- install`.
-
----
-
-## Credits
-
-Spec Guardrails adapts open ideas; we did not invent spec-driven phases, loop design, or task-graph rules.
-
-### Core lineage
-
-| Source | License | How we use it |
-| --- | --- | --- |
-| [tlc-spec-driven](https://github.com/tech-leads-club/agent-skills/tree/main/packages/skills-catalog/skills/(development)/tlc-spec-driven) | CC-BY-4.0 | Phase model, `.specs/` memory, gate lineage |
-| [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) | MIT | Discuss patterns, definition-of-done |
-| [graph-engineering](https://github.com/codejunkie99/graph-engineering) | MIT | Task-graph topology, stop rules, parallel merge |
-
-### Loop & ecosystem
-
-| Source | License | How we use it |
-| --- | --- | --- |
-| [loop-engineering](https://github.com/cobusgreyling/loop-engineering) | MIT | Operational loop patterns; `doctor` score metaphor |
-| [Addy Osmani — Loop engineering](https://addyosmani.com/blog/loop-engineering/) | — | Essay lineage |
-| [awesome-harness-engineering](https://github.com/ai-boost/awesome-harness-engineering) | CC0 | Ecosystem taxonomy |
-
-### Adjacent (not vendored)
-
-[DeepCode](https://github.com/HKUDS/DeepCode) · [RepoGraph](https://github.com/ozyyshr/RepoGraph)
-
-Extended attribution: [docs/guide/credits.md](docs/guide/credits.md)
-
-## License
+## Contributing · Credits · License
 
-MIT
+- [CONTRIBUTING.md](CONTRIBUTING.md)
+- [Credits](docs/guide/credits.md)
+- MIT — see [LICENSE](LICENSE)

package/lib/cursor-hooks.js

@@ -0,0 +1,96 @@
+import fs from "node:fs/promises";
+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_HOOKS_JSON = ".cursor/hooks.json";
+
+/**
+ * Merge shipped hook entries without removing user hooks.
+ *
+ * @param {Record<string, unknown> | null | undefined} existing
+ * @param {Record<string, unknown>} template
+ * @returns {Record<string, unknown>}
+ */
+export function mergeCursorHooksConfig(existing, template) {
+  /** @type {Record<string, unknown>} */
+  const result =
+    existing && typeof existing === "object"
+      ? structuredClone(existing)
+      : { version: 1, hooks: {} };
+
+  result.version = result.version ?? template.version ?? 1;
+  /** @type {Record<string, unknown[]>} */
+  const hooks =
+    result.hooks && typeof result.hooks === "object"
+      ? /** @type {Record<string, unknown[]>} */ (result.hooks)
+      : {};
+  result.hooks = hooks;
+
+  /** @type {Record<string, unknown[]>} */
+  const templateHooks =
+    template.hooks && typeof template.hooks === "object"
+      ? /** @type {Record<string, unknown[]>} */ (template.hooks)
+      : {};
+
+  for (const [event, entries] of Object.entries(templateHooks)) {
+    if (!Array.isArray(entries)) {
+      continue;
+    }
+
+    const current = Array.isArray(hooks[event]) ? [...hooks[event]] : [];
+    for (const entry of entries) {
+      if (!entry || typeof entry !== "object") {
+        continue;
+      }
+      const command = /** @type {{ command?: string }} */ (entry).command;
+      if (!command || current.some((item) => item?.command === command)) {
+        continue;
+      }
+      current.push(entry);
+    }
+    hooks[event] = current;
+  }
+
+  return result;
+}
+
+/**
+ * Install Cursor hooks that auto-run context-guard before write/edit tools.
+ *
+ * @param {string} cwd
+ * @param {{ log?: (message: string) => void }} [options]
+ */
+export async function installCursorHooks(cwd, options = {}) {
+  const log = options.log ?? (() => {});
+  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.
+  }
+
+  const template = JSON.parse(
+    await readFileSafe(packagedAssetPath("templates/cursor/hooks.json")),
+  );
+
+  const hooksJsonPath = path.join(cwd, CURSOR_HOOKS_JSON);
+  let existing = null;
+  try {
+    existing = JSON.parse(await readFileSafe(hooksJsonPath));
+  } catch {
+    existing = null;
+  }
+
+  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)`);
+}

package/lib/doctor.js

@@ -11,6 +11,7 @@ import {
 import { resolvePython, resolveScriptsDir } from "./gates.js";
 import { readFileSafe } from "./fs-utils.js";
 import { listFeatureIds, readActiveFeatureFromState } from "./specs-utils.js";
+import { resolveMemoryHint } from "./memory-doctor.js";
 
 const execFileAsync = promisify(execFile);
 
@@ -368,7 +369,7 @@ export function topDoctorSuggestions(checks, limit = 3) {
 /**
  * @param {string} cwd
  * @param {{ suggest?: boolean, json?: boolean }} [options]
- * @returns {Promise<{ score: number, modes: ReturnType<typeof scoreDoctorModes>, checks: DoctorCheck[], suggestions: DoctorCheck[], executeHint: string | null, pythonMissing: boolean }>}
+ * @returns {Promise<{ score: number, modes: ReturnType<typeof scoreDoctorModes>, checks: DoctorCheck[], suggestions: DoctorCheck[], executeHint: string | null, memoryHint: string | null, pythonMissing: boolean }>}
  */
 export async function doctor(cwd, options = {}) {
   const checks = await runDoctorChecks(cwd);
@@ -377,18 +378,19 @@ export async function doctor(cwd, options = {}) {
   const suggestions = topDoctorSuggestions(checks);
   const activeFeature = await readActiveFeature(cwd);
   const executeHint = await resolveExecuteHint(cwd, activeFeature);
+  const memoryHint = await resolveMemoryHint(cwd);
   const pythonCheck = checks.find((check) => check.id === "python");
   const pythonMissing = pythonCheck ? !pythonCheck.pass : false;
 
   if (options.json) {
     console.log(
       JSON.stringify(
-        { score, modes, checks, suggestions, executeHint, pythonMissing },
+        { score, modes, checks, suggestions, executeHint, memoryHint, pythonMissing },
         null,
         2,
       ),
     );
-    return { score, modes, checks, suggestions, executeHint, pythonMissing };
+    return { score, modes, checks, suggestions, executeHint, memoryHint, pythonMissing };
   }
 
   if (pythonMissing) {
@@ -427,5 +429,9 @@ export async function doctor(cwd, options = {}) {
     console.log(`\nExecute hint:\n  → ${executeHint}`);
   }
 
-  return { score, modes, checks, suggestions, executeHint, pythonMissing };
+  if (memoryHint) {
+    console.log(`\nMemory hint:\n  → ${memoryHint}`);
+  }
+
+  return { score, modes, checks, suggestions, executeHint, memoryHint, pythonMissing };
 }

package/lib/gates.js

@@ -205,6 +205,47 @@ export async function runGuardrailsScript(command, args, options = {}) {
   });
 }
 
+/**
+ * Run a guardrails Python script and capture stdout/stderr.
+ *
+ * @param {string} command gate or aux command name
+ * @param {string[]} args forwarded to the Python script
+ * @param {{ cwd?: string }} [options]
+ * @returns {Promise<{ code: number, stdout: string, stderr: string }>}
+ */
+export async function runGuardrailsScriptCapture(command, args, options = {}) {
+  const scriptName = GUARDRAILS_SCRIPTS[command];
+
+  if (!scriptName) {
+    throw new Error(`Unknown guardrails command: ${command}`);
+  }
+
+  const cwd = options.cwd ?? process.cwd();
+  const scriptsDir = await resolveScriptsDir(cwd);
+  const scriptPath = path.join(cwd, scriptsDir, scriptName);
+  const python = await resolvePython();
+
+  if (!python) {
+    throw new Error("Python 3.10+ not found.");
+  }
+
+  return new Promise((resolve, reject) => {
+    let stdout = "";
+    let stderr = "";
+    const child = spawn(python.command, [...python.args, scriptPath, ...args], { cwd });
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    child.on("error", reject);
+    child.on("close", (code) => {
+      resolve({ code: code ?? 1, stdout, stderr });
+    });
+  });
+}
+
 /**
  * Run a structural gate script installed under `.specs/guardrails/scripts/`.
  *

package/lib/install.js

@@ -13,6 +13,7 @@ import {
   resolveAssetOverride,
 } from "./constants.js";
 import { installPlatformAdapters } from "./adapters.js";
+import { installCursorHooks } from "./cursor-hooks.js";
 import { ensureDir, readFileSafe, writeFileIfMissing } from "./fs-utils.js";
 import { hasPython } from "./gates.js";
 import { initGuardrailsMemory } from "./memory.js";
@@ -118,6 +119,8 @@ export async function install(options = {}) {
   await installPlatformAdapters(cwd);
   log("✅ Adapters → .cursorrules, CLAUDE.md, copilot-instructions.md, AGENTS.md, .codex/AGENTS.md");
 
+  await installCursorHooks(cwd, { log });
+
   const gettingStartedCreated = await writeFileIfMissing(
     path.join(cwd, ".specs/GETTING_STARTED.md"),
     await readFileSafe(packagedAssetPath("templates/GETTING_STARTED.md")),

package/lib/memory-doctor.js

@@ -0,0 +1,80 @@
+import { NPX } from "./constants.js";
+import { hasPython, runGuardrailsScriptCapture } from "./gates.js";
+
+/**
+ * @typedef {{
+ *   database: string,
+ *   exists: boolean,
+ *   semantic_enabled: boolean,
+ *   provider: string,
+ *   entities: number,
+ *   chunks: number,
+ *   embeddings: number,
+ *   has_artifacts: boolean,
+ *   stale: boolean,
+ * }} MemoryStatus
+ */
+
+/**
+ * @param {string} cwd
+ * @returns {Promise<MemoryStatus | null>}
+ */
+export async function readMemoryStatus(cwd) {
+  if (!(await hasPython())) {
+    return null;
+  }
+
+  try {
+    const { code, stdout } = await runGuardrailsScriptCapture(
+      "memory-index",
+      ["status", "--json"],
+      { cwd },
+    );
+    if (code !== 0) {
+      return null;
+    }
+    return JSON.parse(stdout);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {MemoryStatus} status
+ * @returns {string | null}
+ */
+export function memoryHintFromStatus(status) {
+  if (!status.has_artifacts) {
+    return null;
+  }
+
+  if (!status.exists) {
+    return `${NPX("memory-index rebuild")} — project artifacts exist but the search index is missing`;
+  }
+
+  if (status.stale) {
+    return `${NPX("memory-index rebuild")} — .specs/ changed since the last index rebuild`;
+  }
+
+  if (
+    status.semantic_enabled &&
+    status.chunks > 0 &&
+    status.embeddings < Math.max(1, Math.ceil(status.chunks * 0.5))
+  ) {
+    return `${NPX("memory-index embed")} — semantic search is enabled but most chunks lack embeddings`;
+  }
+
+  return null;
+}
+
+/**
+ * @param {string} cwd
+ * @returns {Promise<string | null>}
+ */
+export async function resolveMemoryHint(cwd) {
+  const status = await readMemoryStatus(cwd);
+  if (!status) {
+    return null;
+  }
+  return memoryHintFromStatus(status);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@luizsantiago/spec-guardrails",
-  "version": "3.6.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.",
+  "version": "3.8.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": {
     "spec-guardrails": "./index.js"
@@ -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: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:gates": "node test/run-gate-tests.mjs",
     "prepublishOnly": "npm test"
   },

package/scripts/memory_index.py

@@ -260,6 +260,82 @@ def chunk_spec_requirements(
     return count
 
 
+def chunk_task_bodies(
+    conn: sqlite3.Connection,
+    feature_id: str,
+    tasks_path: Path,
+    tasks_text: str,
+    now: str,
+) -> int:
+    count = 0
+    matches = list(TASK_HEADING.finditer(tasks_text))
+    for index, match in enumerate(matches):
+        task_id = match.group("id").upper()
+        start = match.end()
+        end = matches[index + 1].start() if index + 1 < len(matches) else len(tasks_text)
+        body = tasks_text[start:end].strip()
+        if not body:
+            body = match.group("title").strip() or task_id
+        chunk_id = f"chunk:{feature_id}:task:{task_id}"
+        upsert_chunk(conn, chunk_id, task_id, "task", str(tasks_path), body, now)
+        count += 1
+    return count
+
+
+def prune_embeddings(conn: sqlite3.Connection) -> None:
+    conn.execute(
+        """
+        DELETE FROM embeddings
+        WHERE chunk_id NOT IN (SELECT id FROM chunks)
+           OR chunk_id IN (
+               SELECT e.chunk_id
+               FROM embeddings e
+               JOIN chunks c ON c.id = e.chunk_id
+               WHERE e.text_hash != c.text_hash
+           )
+        """
+    )
+
+
+def latest_artifact_mtime() -> float | None:
+    latest: float | None = None
+    candidates = [SPECS_DIR / "lessons.json", SPECS_DIR / "STATE.md"]
+    if FEATURES_DIR.is_dir():
+        for feature_dir in FEATURES_DIR.iterdir():
+            if not feature_dir.is_dir():
+                continue
+            for name in (
+                "spec.md",
+                "tasks.md",
+                "design.md",
+                "validation.md",
+                "exploration.md",
+            ):
+                path = feature_dir / name
+                if path.is_file():
+                    candidates.append(path)
+
+    for path in candidates:
+        if path.is_file():
+            mtime = path.stat().st_mtime
+            latest = mtime if latest is None else max(latest, mtime)
+    return latest
+
+
+def has_indexable_artifacts() -> bool:
+    if (SPECS_DIR / "lessons.json").is_file():
+        return True
+    if not FEATURES_DIR.is_dir():
+        return False
+    for feature_dir in FEATURES_DIR.iterdir():
+        if not feature_dir.is_dir():
+            continue
+        for name in ("spec.md", "tasks.md", "design.md", "validation.md", "exploration.md"):
+            if (feature_dir / name).is_file():
+                return True
+    return False
+
+
 def chunk_markdown_sections(
     conn: sqlite3.Connection,
     feature_id: str,
@@ -343,7 +419,6 @@ def rebuild(json_output: bool = False) -> int:
         conn.execute("DELETE FROM entity_fts")
         conn.execute("DELETE FROM chunks")
         conn.execute("DELETE FROM chunk_fts")
-        conn.execute("DELETE FROM embeddings")
 
         entity_count = 0
         relation_count = 0
@@ -397,6 +472,19 @@ def rebuild(json_output: bool = False) -> int:
                         now,
                     )
 
+                design_path = feature_dir / "design.md"
+                if design_path.is_file():
+                    design_text = design_path.read_text(encoding="utf-8")
+                    chunk_count += chunk_markdown_sections(
+                        conn,
+                        feature_id,
+                        design_path,
+                        design_text,
+                        "design",
+                        feature_id,
+                        now,
+                    )
+
                 exploration_path = feature_dir / "exploration.md"
                 if exploration_path.is_file():
                     exploration_text = exploration_path.read_text(encoding="utf-8")
@@ -448,9 +536,14 @@ def rebuild(json_output: bool = False) -> int:
                             upsert_relation(conn, task_id, file_entity, "touches")
                             relation_count += 1
 
+                    chunk_count += chunk_task_bodies(
+                        conn, feature_id, tasks_path, tasks_text, now
+                    )
+
         lesson_entities, lesson_chunks = index_lessons(conn, now)
         entity_count += lesson_entities
         chunk_count += lesson_chunks
+        prune_embeddings(conn)
         conn.commit()
 
         summary = {
@@ -545,6 +638,46 @@ def embed_chunks(force: bool = False, json_output: bool = False) -> int:
     return EXIT_OK
 
 
+def memory_status(json_output: bool = False) -> int:
+    config = load_memory_retrieval_config()
+    latest = latest_artifact_mtime()
+    summary = {
+        "database": str(DB_PATH),
+        "exists": DB_PATH.is_file(),
+        "semantic_enabled": bool(config.get("semantic")),
+        "provider": str(config.get("provider") or "none"),
+        "entities": 0,
+        "chunks": 0,
+        "embeddings": 0,
+        "has_artifacts": has_indexable_artifacts(),
+        "stale": False,
+    }
+
+    if DB_PATH.is_file():
+        conn = sqlite3.connect(DB_PATH)
+        try:
+            init_schema(conn)
+            summary["entities"] = conn.execute("SELECT COUNT(*) FROM entities").fetchone()[0]
+            summary["chunks"] = conn.execute("SELECT COUNT(*) FROM chunks").fetchone()[0]
+            summary["embeddings"] = conn.execute("SELECT COUNT(*) FROM embeddings").fetchone()[0]
+        finally:
+            conn.close()
+        if latest is not None:
+            summary["stale"] = DB_PATH.stat().st_mtime < latest
+    else:
+        summary["stale"] = summary["has_artifacts"]
+
+    if json_output:
+        print(json.dumps(summary, indent=2))
+    else:
+        state = "ready" if summary["exists"] and not summary["stale"] else "needs attention"
+        print(
+            f"[{GATE}] memory index {state} — "
+            f"{summary['chunks']} chunk(s), {summary['embeddings']} embedding(s)"
+        )
+    return EXIT_OK
+
+
 def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(description="Rebuild SQLite memory index from .specs/")
     sub = parser.add_subparsers(dest="command")
@@ -558,6 +691,10 @@ def build_parser() -> argparse.ArgumentParser:
     embed_cmd.add_argument("--json", action="store_true")
     embed_cmd.set_defaults(func=lambda args: embed_chunks(force=args.force, json_output=args.json))
 
+    status_cmd = sub.add_parser("status", help="report index stats for doctor and tooling")
+    status_cmd.add_argument("--json", action="store_true")
+    status_cmd.set_defaults(func=lambda args: memory_status(json_output=args.json))
+
     return parser
 
 

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 context-guard check-edit <path> [--op write]` |
+| 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]` |
 | 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]` |

package/templates/GETTING_STARTED.md

@@ -16,6 +16,8 @@ You installed the **Spec Guardrails**. You do **not** need to memorize CLI comma
 
 3. Review `.specs/features/…/spec.md` and **approve** before implementation.
 
+**Plain-language guide:** [Overview](https://github.com/luizssantiago92/spec-guardrails/blob/main/docs/guide/Overview.md) · [Memory](https://github.com/luizssantiago92/spec-guardrails/blob/main/docs/guide/Memory.md)
+
 ---
 
 ## Agent commands (chat — not terminal)

package/templates/cursor/hooks/context-guard-edit.mjs

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+/**
+ * Cursor preToolUse hook — runs context-guard before file write/edit tools.
+ * Installed to .cursor/hooks/ by spec-guardrails install.
+ */
+import { existsSync } from "node:fs";
+import { readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { pathToFileURL } from "node:url";
+
+const GUARDRAILS_SCRIPTS = ".specs/guardrails/scripts";
+const SKIP_PREFIXES = [".specs/", ".cursor/", "node_modules/"];
+const WRITE_TOOLS = new Set([
+  "write",
+  "strreplace",
+  "search_replace",
+  "editnotebook",
+  "applypatch",
+  "edit",
+]);
+
+/**
+ * @param {unknown} input
+ * @returns {Record<string, unknown> | null}
+ */
+function readHookInput(input) {
+  if (input && typeof input === "object") {
+    return /** @type {Record<string, unknown>} */ (input);
+  }
+  return null;
+}
+
+/**
+ * @param {Record<string, unknown>} input
+ * @returns {string | null}
+ */
+export function extractEditPath(input) {
+  const toolName = String(input.tool_name ?? input.toolName ?? "").toLowerCase();
+  if (toolName && !WRITE_TOOLS.has(toolName)) {
+    return null;
+  }
+
+  const rawInput = input.tool_input ?? input.toolInput ?? input.arguments ?? {};
+  /** @type {Record<string, unknown>} */
+  let toolInput = {};
+
+  if (typeof rawInput === "string") {
+    try {
+      toolInput = JSON.parse(rawInput);
+    } catch {
+      return null;
+    }
+  } else if (rawInput && typeof rawInput === "object") {
+    toolInput = /** @type {Record<string, unknown>} */ (rawInput);
+  }
+
+  const pathValue =
+    toolInput.path ??
+    toolInput.file_path ??
+    toolInput.filePath ??
+    toolInput.target_notebook ??
+    toolInput.notebook_path;
+
+  return typeof pathValue === "string" && pathValue.trim() ? pathValue.trim() : null;
+}
+
+/**
+ * @param {string | null} relativePath
+ * @returns {boolean}
+ */
+export function shouldSkipPath(relativePath) {
+  if (!relativePath) {
+    return true;
+  }
+
+  const normalized = relativePath.replace(/\\/g, "/").replace(/^\.\//, "");
+  return SKIP_PREFIXES.some((prefix) => normalized === prefix.slice(0, -1) || normalized.startsWith(prefix));
+}
+
+/**
+ * @param {{ permission: string, user_message?: string, agent_message?: string }} payload
+ */
+function respond(payload) {
+  process.stdout.write(`${JSON.stringify(payload)}\n`);
+}
+
+function allow() {
+  respond({ permission: "allow" });
+  process.exit(0);
+}
+
+/**
+ * @param {string[]} messages
+ */
+function deny(messages) {
+  const detail = messages.filter(Boolean).join("; ") || "context-guard blocked this edit";
+  respond({
+    permission: "deny",
+    user_message: `Spec Guardrails blocked this edit: ${detail}`,
+    agent_message:
+      `Context guard blocked the edit. Align with .specs/STATE.md and task Files, or update tasks.md. ${detail}`,
+  });
+  process.exit(2);
+}
+
+/**
+ * @param {Record<string, unknown>} input
+ * @returns {{ allowed: boolean, messages: string[] }}
+ */
+export function evaluateHookInput(input) {
+  const editPath = extractEditPath(input);
+  if (shouldSkipPath(editPath)) {
+    return { allowed: true, messages: [] };
+  }
+
+  if (!existsSync(GUARDRAILS_SCRIPTS)) {
+    return { allowed: true, messages: [] };
+  }
+
+  const cli = process.env.SPEC_GUARDRAILS_CLI ?? "npx @luizsantiago/spec-guardrails";
+  const result = spawnSync(
+    cli,
+    ["context-guard", "check-edit", editPath, "--op", "write", "--json"],
+    { encoding: "utf8", shell: process.platform === "win32" },
+  );
+
+  if (result.status === 0) {
+    return { allowed: true, messages: [] };
+  }
+
+  /** @type {string[]} */
+  let messages = ["context-guard check failed"];
+  try {
+    const parsed = JSON.parse(result.stdout || "{}");
+    if (Array.isArray(parsed.messages) && parsed.messages.length > 0) {
+      messages = parsed.messages.map(String);
+    }
+  } catch {
+    if (result.stderr?.trim()) {
+      messages = [result.stderr.trim()];
+    }
+  }
+
+  return { allowed: false, messages };
+}
+
+function main() {
+  let parsed = null;
+  try {
+    parsed = readHookInput(JSON.parse(readFileSync(0, "utf8")));
+  } catch {
+    allow();
+  }
+
+  if (!parsed) {
+    allow();
+  }
+
+  const decision = evaluateHookInput(parsed);
+  if (decision.allowed) {
+    allow();
+  }
+
+  deny(decision.messages);
+}
+
+const entry = process.argv[1] ? pathToFileURL(process.argv[1]).href : "";
+if (entry && import.meta.url === entry) {
+  main();
+}

package/templates/cursor/hooks.json

@@ -0,0 +1,12 @@
+{
+  "version": 1,
+  "hooks": {
+    "preToolUse": [
+      {
+        "command": ".cursor/hooks/context-guard-edit.mjs",
+        "matcher": "Write|StrReplace|search_replace|EditNotebook|ApplyPatch",
+        "failClosed": false
+      }
+    ]
+  }
+}