@luizsantiago/spec-guardrails 4.0.0 → 4.1.0

package/README.md

@@ -7,7 +7,7 @@
 
 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**
+npm: [`@luizsantiago/spec-guardrails`](https://www.npmjs.com/package/@luizsantiago/spec-guardrails) **4.1.x**
 
 ---
 
@@ -94,10 +94,11 @@ Enable when the work warrants them — most teams start with the core loop only.
 | 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 |
+| Sandbox policy | Warn or block destructive shell commands (Cursor hook) |
+| Execution policy | Path allowlists, budgets, read/write/delete effects |
 | Semantic retrieval | Search by meaning — off by default |
 
-Guides: [Memory](docs/guide/Memory.md) · [Brownfield context](docs/guide/brownfield-context.md) · [Safety & exploration](docs/guide/Overview.md)
+Guides: [Memory](docs/guide/Memory.md) · [Cursor hooks and sandbox](docs/guide/Cursor-hooks-and-sandbox.md) · [Brownfield context](docs/guide/brownfield-context.md)
 
 ---
 
@@ -123,6 +124,7 @@ Start with the guide that matches your question; each page links deeper where ne
 | --- | --- | --- |
 | 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) |
+| Cursor IDE protection | [Cursor hooks and sandbox](docs/guide/Cursor-hooks-and-sandbox.md) | [Guarantees matrix](docs/guide/Guarantees-matrix.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) |

package/index.js

@@ -87,6 +87,11 @@ Commands:
   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
+  req-analysis validate [brief.md]     Gate: approved requirements brief before /specify
+  req-analysis context                 Assemble kickoff + brief context for Specify
+    [--scope project|feature]          Scope (default: project)
+    [--slug <feature-slug>]            Feature slug when scope=feature
+    [--json]                           Machine-readable output
   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)
@@ -168,6 +173,7 @@ Commands:
     [--json]                         Machine-readable plan for agents
   validate-traceability [feature]    REQ → tasks → validation coverage chain
   validate-quick [quick-folder]      Quick-mode TASK.md / SUMMARY.md structural gate
+  validate-req-analysis [brief.md]   Requirements brief gate before /specify (/elicit)
   validate-state [feature]           Completion gate before declaring a feature done
   check-commit --message "<msg>"     Conventional Commits gate
   lessons <add|list|penalize|prune|promote|graduate|status>  Lessons engine
@@ -953,8 +959,41 @@ if (command === "--version" || command === "-v" || command === "version") {
         }
       }
       console.log(formatPromoteMessage({ scope, description }));
+    } else if (sub === "validate") {
+      const briefPath = rest.find((arg) => !arg.startsWith("--"));
+      const code = await runGate("validate-req-analysis", briefPath ? [briefPath] : []);
+      process.exit(code);
+    } else if (sub === "context") {
+      let scope = "project";
+      let slug = "";
+      let json = false;
+      for (let i = 0; i < rest.length; i += 1) {
+        const arg = rest[i];
+        if (arg === "--json") {
+          json = 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 === "--slug" && rest[i + 1]) {
+          slug = rest[i + 1];
+          i += 1;
+        } else if (arg.startsWith("--slug=")) {
+          slug = arg.slice("--slug=".length);
+        }
+      }
+      const scriptArgs = ["--scope", scope];
+      if (slug) {
+        scriptArgs.push("--slug", slug);
+      }
+      if (json) {
+        scriptArgs.push("--json");
+      }
+      const code = await runGuardrailsScript("req-context", scriptArgs);
+      process.exit(code);
     } else {
-      throw new Error("Usage: req-analysis init | discover | promote");
+      throw new Error("Usage: req-analysis init | discover | promote | validate | context");
     }
   } catch (err) {
     console.error(`❌ ${err.message}`);

package/lib/classify-change.js

@@ -26,12 +26,21 @@ const DEPENDENCY_SIGNALS = [
   /\badd\s+package\b/i,
 ];
 
+const VAGUE_SIGNALS = [
+  /\bimprove\b/i,
+  /\bmake\s+(?:it|this|things?)\s+better\b/i,
+  /\badd\s+(?:a\s+)?(?:interface|page|screen|ui|dashboard)\b/i,
+  /\b(?:somehow|something|stuff)\b/i,
+  /\bwithout\s+(?:criteria|details|spec)\b/i,
+];
+
 /**
  * @param {{ description?: string, files?: string[] }} input
  * @returns {{
  *   tier: "quick" | "simple" | "medium" | "complex",
  *   reasons: string[],
  *   next: string,
+ *   suggestElicit: boolean,
  *   fileCount: number,
  * }}
  */
@@ -45,6 +54,7 @@ export function classifyChange(input = {}) {
   const hasComplex = COMPLEX_SIGNALS.some((re) => re.test(haystack));
   const hasMedium = MEDIUM_SIGNALS.some((re) => re.test(haystack));
   const hasNewDep = DEPENDENCY_SIGNALS.some((re) => re.test(haystack));
+  const hasVague = VAGUE_SIGNALS.some((re) => re.test(haystack));
 
   if (hasComplex) {
     reasons.push("sensitive surface or architecture signal in description/paths");
@@ -103,10 +113,15 @@ export function classifyChange(input = {}) {
       'feature-init → full pipeline (+ /discuss, /plan; optional AppSec/QA on verify)',
   };
 
+  if (hasVague) {
+    reasons.push("vague delivery language — consider /elicit before /specify");
+  }
+
   return {
     tier,
     reasons,
     next: nextByTier[tier],
+    suggestElicit: hasVague && !hasComplex,
     fileCount,
   };
 }
@@ -123,5 +138,8 @@ export function formatClassifyChange(result) {
     ...result.reasons.map((r) => `  - ${r}`),
     `Next: ${result.next}`,
   ];
+  if (result.suggestElicit) {
+    lines.push("Suggest: /elicit (structured Q&A) or /specify if scope is already clear");
+  }
   return `${lines.join("\n")}\n`;
 }

package/lib/constants.js

@@ -118,6 +118,8 @@ export const SCRIPT_ASSETS = [
   { 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" },
+  { file: "validate_req_analysis.py", remotePath: "scripts/validate_req_analysis.py" },
+  { file: "req_context.py", remotePath: "scripts/req_context.py" },
 ];
 
 /** @type {{ file: string, remotePath: string }[]} */

package/lib/gates.js

@@ -34,6 +34,7 @@ const GATE_SCRIPTS = {
   "validate-state": "validate_state.py",
   "validate-traceability": "validate_traceability.py",
   "validate-quick": "validate_quick.py",
+  "validate-req-analysis": "validate_req_analysis.py",
   "analyze-artifacts": "analyze_artifacts.py",
   "check-commit": "check_commit.py",
   lessons: "lessons.py",
@@ -47,6 +48,7 @@ const AUX_SCRIPTS = {
   "memory-retrieve": "memory_retrieve.py",
   episodes: "episodes.py",
   "code-index": "code_index.py",
+  "req-context": "req_context.py",
 };
 
 const GUARDRAILS_SCRIPTS = { ...GATE_SCRIPTS, ...AUX_SCRIPTS };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luizsantiago/spec-guardrails",
-  "version": "4.0.0",
+  "version": "4.1.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": {

package/scripts/req_context.py

@@ -0,0 +1,145 @@
+#!/usr/bin/env python3
+"""Assemble kickoff + requirements brief context for the Specify phase.
+
+    python3 req_context.py --scope project
+    python3 req_context.py --scope feature --slug settings-page
+    python3 req_context.py --json
+
+Read-only: lists discovered sources and brief paths; does not mutate files.
+Exit codes: 0 success, 2 usage error.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+PROJECT_DIR = Path(".specs/project")
+KICKOFF_PATHS = (
+    Path("prd.md"),
+    Path("docs/brief.md"),
+    Path("docs/prd.md"),
+    PROJECT_DIR / "kickoff.md",
+)
+PROJECT_BRIEF = PROJECT_DIR / "requirements-brief.md"
+FEATURE_BRIEFS = PROJECT_DIR / "feature-briefs"
+
+
+def discover_sources(root: Path) -> list[dict[str, str | bool]]:
+    entries: list[dict[str, str | bool]] = []
+    seen: set[str] = set()
+    for rel in KICKOFF_PATHS:
+        key = rel.as_posix()
+        if key in seen:
+            continue
+        seen.add(key)
+        path = root / rel
+        entries.append({"path": key, "exists": path.is_file()})
+    return entries
+
+
+def resolve_brief(root: Path, scope: str, slug: str | None) -> Path | None:
+    if scope == "project":
+        candidate = root / PROJECT_BRIEF
+        return candidate if candidate.is_file() else None
+
+    if not slug:
+        briefs_root = root / FEATURE_BRIEFS
+        if not briefs_root.is_dir():
+            return None
+        matches = sorted(briefs_root.rglob("requirements-brief.md"))
+        return matches[0] if len(matches) == 1 else None
+
+    candidate = root / FEATURE_BRIEFS / slug / "requirements-brief.md"
+    return candidate if candidate.is_file() else None
+
+
+def excerpt(path: Path, max_chars: int = 1200) -> str:
+    text = path.read_text(encoding="utf-8")
+    trimmed = text.strip()
+    if len(trimmed) <= max_chars:
+        return trimmed
+    return f"{trimmed[: max_chars - 3].rstrip()}..."
+
+
+def build_context(root: Path, scope: str, slug: str | None) -> dict:
+    sources = discover_sources(root)
+    brief = resolve_brief(root, scope, slug)
+    payload: dict = {
+        "scope": scope,
+        "sources": sources,
+        "brief_path": brief.relative_to(root).as_posix() if brief else None,
+    }
+    if brief:
+        payload["brief_excerpt"] = excerpt(brief)
+    if scope == "feature" and slug:
+        payload["slug"] = slug
+    return payload
+
+
+def format_markdown(ctx: dict) -> str:
+    lines = [
+        "# Requirements context",
+        "",
+        f"Scope: **{ctx['scope']}**",
+        "",
+        "## Kickoff sources",
+        "",
+    ]
+    for entry in ctx["sources"]:
+        label = "found" if entry["exists"] else "missing"
+        lines.append(f"- [{label}] {entry['path']}")
+
+    lines.extend(["", "## Requirements brief", ""])
+    if ctx.get("brief_path"):
+        lines.append(f"- Path: `{ctx['brief_path']}`")
+        if ctx.get("brief_excerpt"):
+            lines.extend(["", "### Excerpt", "", "```markdown", ctx["brief_excerpt"], "```"])
+    else:
+        lines.append("- No requirements brief found for this scope.")
+
+    lines.extend(
+        [
+            "",
+            "## Next",
+            "",
+            "- Run `validate-req-analysis` on the brief before `/specify`",
+            "- Derive spec.md from the brief — do not re-ask resolved questions",
+        ]
+    )
+    return "\n".join(lines) + "\n"
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Requirements context for Specify")
+    parser.add_argument(
+        "--scope",
+        choices=("project", "feature"),
+        default="project",
+        help="Elicitation scope (default: project)",
+    )
+    parser.add_argument(
+        "--slug",
+        help="Feature slug when scope=feature (default: sole feature brief if only one exists)",
+    )
+    parser.add_argument("--json", action="store_true", help="Emit JSON instead of markdown")
+    args = parser.parse_args(argv)
+
+    if args.scope == "feature" and args.slug and not args.slug.strip():
+        print("[req-context] USAGE - --slug must not be empty", file=sys.stderr)
+        return 2
+
+    ctx = build_context(Path("."), args.scope, args.slug.strip() if args.slug else None)
+
+    if args.json:
+        print(json.dumps(ctx, indent=2))
+    else:
+        print(format_markdown(ctx), end="")
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/validate_req_analysis.py

@@ -0,0 +1,191 @@
+#!/usr/bin/env python3
+"""Structural gate for requirements briefs produced by /elicit.
+
+    python3 validate_req_analysis.py .specs/project/requirements-brief.md
+    python3 validate_req_analysis.py .specs/project/feature-briefs/settings-page/requirements-brief.md
+
+Checks (markdown structure only):
+  * Required sections: Goal, Context sources, Owner approval
+  * Context sources lists at least one non-placeholder entry
+  * Open questions is empty or explicitly "- none"
+  * Owner approval indicates yes with a date
+  * No [NEEDS CLARIFICATION] or [OPEN QUESTION] markers remain
+
+Exit codes: 0 pass, 1 blocking issues, 2 usage error.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+from _common import Report, visible_markdown
+
+GATE = "validate-req-analysis"
+PROJECT_DIR = Path(".specs/project")
+PROJECT_BRIEF = PROJECT_DIR / "requirements-brief.md"
+FEATURE_BRIEFS = PROJECT_DIR / "feature-briefs"
+
+HEADING = re.compile(r"^##\s+(.+?)\s*$", re.MULTILINE)
+APPROVAL_YES = re.compile(
+    r"\b(?:approved|approval)\b[^\n]*:\s*(?:yes|approved|true)\b",
+    re.IGNORECASE,
+)
+APPROVAL_DATE = re.compile(
+    r"\bdate\b\s*:\s*(\d{4}-\d{2}-\d{2}|YYYY-MM-DD)",
+    re.IGNORECASE,
+)
+OPEN_NONE = re.compile(r"^\s*[-*]\s*(?:none|n/a)\s*$", re.IGNORECASE | re.MULTILINE)
+CLARIFICATION = re.compile(r"\[(?:NEEDS CLARIFICATION|OPEN QUESTION)\]", re.IGNORECASE)
+PLACEHOLDER_SOURCE = re.compile(
+    r"^\s*[-*]\s*\(\s*list every file",
+    re.IGNORECASE | re.MULTILINE,
+)
+
+
+def _fail_usage(message: str, target: str = ".") -> None:
+    print(f"[{GATE}] USAGE - {message}", file=sys.stderr)
+    raise SystemExit(2)
+
+
+def resolve_brief_path(raw: str | None, root: Path = Path(".")) -> Path:
+    if not raw:
+        candidate = root / PROJECT_BRIEF
+        if candidate.is_file():
+            return candidate
+        _fail_usage(
+            "no brief path given and .specs/project/requirements-brief.md is missing",
+            str(PROJECT_BRIEF),
+        )
+
+    candidate = Path(raw).expanduser()
+    if candidate.is_absolute():
+        brief = candidate
+    else:
+        brief = root / candidate
+
+    if not brief.is_file():
+        _fail_usage(f"no such requirements brief: {raw}", raw or str(PROJECT_BRIEF))
+
+    rel = brief.resolve()
+    project_root = (root / PROJECT_DIR).resolve()
+    try:
+        rel.relative_to(project_root)
+    except ValueError:
+        _fail_usage(
+            f"brief must live under {PROJECT_DIR.as_posix()}/",
+            str(brief),
+        )
+
+    if brief.name != "requirements-brief.md":
+        _fail_usage(
+            "expected a requirements-brief.md file under .specs/project/",
+            str(brief),
+        )
+
+    return brief
+
+
+def section_body(text: str, title: str) -> str:
+    match = HEADING.search(text)
+    if not match:
+        return ""
+
+    pattern = re.compile(
+        rf"^##\s+{re.escape(title)}\s*$",
+        re.MULTILINE | re.IGNORECASE,
+    )
+    start = pattern.search(text)
+    if not start:
+        return ""
+
+    rest = text[start.end() :]
+    next_heading = HEADING.search(rest)
+    body = rest[: next_heading.start()] if next_heading else rest
+    return body.strip()
+
+
+def build_report(brief_path: Path) -> Report:
+    report = Report(GATE, brief_path.as_posix())
+    text = brief_path.read_text(encoding="utf-8")
+    visible = visible_markdown(text)
+
+    for section in ("Goal", "Context sources", "Owner approval"):
+        if not section_body(text, section):
+            report.error(f"missing ## {section} section")
+
+    goal_body = section_body(text, "Goal")
+    if goal_body and len(goal_body.strip()) < 8:
+        report.error("Goal section is too short to be actionable")
+
+    sources_body = section_body(text, "Context sources")
+    if sources_body:
+        if PLACEHOLDER_SOURCE.search(sources_body):
+            report.error("Context sources still contains the scaffold placeholder")
+        elif not re.search(r"^\s*[-*]\s+\S", sources_body, re.MULTILINE):
+            report.error("Context sources must list at least one bullet entry")
+        else:
+            report.ok("Context sources lists at least one entry")
+    else:
+        report.error("Context sources section is empty")
+
+    open_body = section_body(text, "Open questions")
+    if open_body:
+        bullets = [
+            line.strip()
+            for line in open_body.splitlines()
+            if line.strip().startswith(("-", "*"))
+        ]
+        if bullets and not all(OPEN_NONE.match(line) for line in bullets):
+            report.error(
+                'Open questions must be "- none" or empty before /specify'
+            )
+        else:
+            report.ok("Open questions closed")
+    else:
+        report.ok("Open questions section absent or empty")
+
+    approval_body = section_body(text, "Owner approval")
+    if approval_body:
+        if not APPROVAL_YES.search(approval_body):
+            report.error('Owner approval must include "Approved: yes" (or equivalent)')
+        if APPROVAL_DATE.search(approval_body) and "YYYY-MM-DD" in approval_body:
+            report.error("Owner approval date is still the scaffold placeholder")
+        elif not re.search(r"\d{4}-\d{2}-\d{2}", approval_body):
+            report.warn("Owner approval has no YYYY-MM-DD date")
+        else:
+            report.ok("Owner approval recorded")
+    else:
+        report.error("Owner approval section is empty")
+
+    if CLARIFICATION.search(visible):
+        report.error("[NEEDS CLARIFICATION] or [OPEN QUESTION] marker remains")
+    else:
+        report.ok("no clarification markers in brief")
+
+    return report
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Validate a requirements brief from /elicit")
+    parser.add_argument(
+        "brief",
+        nargs="?",
+        help="Path to requirements-brief.md (default: .specs/project/requirements-brief.md)",
+    )
+    parser.add_argument(
+        "--strict",
+        action="store_true",
+        help="Treat warnings as blocking failures",
+    )
+    args = parser.parse_args(argv)
+
+    brief = resolve_brief_path(args.brief)
+    report = build_report(brief)
+    return report.emit(strict=args.strict)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/agent-architecture.md

@@ -82,7 +82,7 @@ EXPLORE (optional) → ELICIT (optional) → SPECIFY → DISCUSS (conditional)
 | Phase | Required | Reference | Sister skill | Gate |
 | --- | --- | --- | --- | --- |
 | **Explore** | Optional | `references/explore.md` | — | — |
-| **Elicit** | Optional | `references/elicitation.md` | — | — (v1 skill checklist; gate in 4.x wave 2) |
+| **Elicit** | Optional | `references/elicitation.md` | `validate-req-analysis` | — (before `/specify`; suggest-only entry) |
 | **Constitution** | Once per project | `references/constitution.md` | — | — |
 | **Specify** | Yes | `references/specify.md` | — | `validate_spec.py` |
 | **Discuss** | Conditional | `references/discuss.md` | — | — |

package/skills/references/elicitation.md

@@ -136,8 +136,14 @@ Use the template from `req-analysis init`. Required sections:
 
 Present the brief summary. Wait for explicit approval before `/specify`.
 
-**v1 checklist (no Python gate yet):**
+**Gate before `/specify` (Brakes mode):**
 
+```bash
+npx @luizsantiago/spec-guardrails req-analysis validate
+# or: validate-req-analysis .specs/project/requirements-brief.md
+```
+
+**Checklist (Process mode — agent verifies when Python is unavailable):**
 - [ ] Open questions is `- none` or empty
 - [ ] Owner approval filled
 - [ ] Context sources lists at least one input
@@ -160,6 +166,12 @@ Copy or link brief → `.specs/features/NNN-slug/requirements-brief.md` (optiona
 
 Open `specify.md` — derive `spec.md` from brief; do **not** re-ask resolved questions.
 
+Optional context bundle for Specify:
+
+```bash
+npx @luizsantiago/spec-guardrails req-analysis context --scope feature --slug settings-page
+```
+
 ```bash
 npx @luizsantiago/spec-guardrails req-analysis promote --scope feature
 ```