@luizsantiago/spec-guardrails 3.5.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.5.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,58 +144,12 @@ Start after install: [Quick start](docs/guide/Quick-start.md) · [Agent commands
 npx @luizsantiago/spec-guardrails install
 ```
 
-| Version | What you gain |
-| --- | --- |
-| **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/index.js

@@ -103,12 +103,16 @@ Commands:
   execution-policy record-retry <task>  Increment retry counter for a task id (blocks at limit)
   execution-policy record-run        Increment agent-run counter (blocks at budget)
   memory-index rebuild               Rebuild SQLite memory index from .specs/ artifacts
+  memory-index embed [--force]       Optional semantic embeddings (requires config + provider)
   memory-query --from <id>           Bounded context package from the knowledge graph
     [--depth N]                      Traversal depth (default 2)
     [--json]                         Machine-readable output
-  memory-search <query>              Full-text search over the memory index (FTS5)
+  memory-search <query>              Full-text search over indexed artifact chunks (FTS5)
     [--limit N]                      Max results (default 10)
     [--json]                         Machine-readable output
+  memory-retrieve "<query>"          Hybrid retrieval (FTS + graph + optional semantic)
+    [--mode fts|hybrid|semantic]     Strategy (default: hybrid)
+    [--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

package/lib/constants.js

@@ -112,6 +112,9 @@ export const SCRIPT_ASSETS = [
   { file: "memory_index.py", remotePath: "scripts/memory_index.py" },
   { file: "memory_query.py", remotePath: "scripts/memory_query.py" },
   { file: "memory_search.py", remotePath: "scripts/memory_search.py" },
+  { 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" },
 ];
 
 /** @type {{ file: string, remotePath: string }[]} */

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

@@ -44,6 +44,7 @@ const AUX_SCRIPTS = {
   "memory-index": "memory_index.py",
   "memory-query": "memory_query.py",
   "memory-search": "memory_search.py",
+  "memory-retrieve": "memory_retrieve.py",
 };
 
 const GUARDRAILS_SCRIPTS = { ...GATE_SCRIPTS, ...AUX_SCRIPTS };
@@ -204,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")),