@luizsantiago/spec-guardrails 3.9.0 → 4.1.0

package/README.md

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

package/index.js

@@ -35,6 +35,11 @@ import {
   listWorkspaces,
   prepareWorkspaces,
 } from "./lib/workspace-isolation.js";
+import {
+  formatDiscoverReport,
+  formatPromoteMessage,
+  reqAnalysisInit,
+} from "./lib/req-analysis.js";
 import {
   formatExplorationInit,
   formatExplorationStatus,
@@ -76,6 +81,17 @@ Commands:
   feature-init "<description>"       Allocate NNN-slug feature, STATE, local branch (Tier 0)
     [--no-branch]                    Skip git checkout -b
     [--no-spec]                      Skip spec.md stub
+  req-analysis init "<description>"    Scaffold requirements brief (/elicit phase)
+    [--scope project|feature]          project = macro brief; feature = one delivery (default: feature)
+    [--force]                          Replace existing brief scaffold
+  req-analysis discover                List local kickoff sources (prd.md, kickoff.md, …)
+  req-analysis promote                 Print next steps after brief approval
+    [--scope project|feature]          Match the brief scope
+  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)
@@ -157,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
@@ -890,6 +907,98 @@ if (command === "--version" || command === "-v" || command === "version") {
     console.error(`❌ ${err.message}`);
     process.exit(1);
   }
+} else if (command === "req-analysis") {
+  try {
+    const sub = args[0];
+    const rest = args.slice(1);
+
+    if (sub === "init") {
+      let scope = "feature";
+      let force = false;
+      const positional = [];
+      for (let i = 0; i < rest.length; i += 1) {
+        const arg = rest[i];
+        if (arg === "--force") {
+          force = true;
+        } else if (arg === "--scope" && rest[i + 1]) {
+          scope = rest[i + 1];
+          i += 1;
+        } else if (arg.startsWith("--scope=")) {
+          scope = arg.slice("--scope=".length);
+        } else if (!arg.startsWith("--")) {
+          positional.push(arg);
+        }
+      }
+      const description = positional.join(" ").trim();
+      if (scope === "feature" && !description) {
+        throw new Error(
+          'Usage: req-analysis init "<description>" [--scope project|feature] [--force]',
+        );
+      }
+      const result = await reqAnalysisInit(description, { scope, force });
+      console.log(`✅ Elicitation scaffold (${result.scope})`);
+      for (const briefPath of result.paths) {
+        console.log(`   ${briefPath}`);
+      }
+      console.log("");
+      console.log(await formatDiscoverReport(process.cwd()));
+    } else if (sub === "discover") {
+      console.log(await formatDiscoverReport(process.cwd()));
+    } else if (sub === "promote") {
+      let scope = "feature";
+      let description = "";
+      for (let i = 0; i < rest.length; i += 1) {
+        const arg = rest[i];
+        if (arg.startsWith("--scope=")) {
+          scope = arg.slice("--scope=".length);
+        } else if (arg === "--scope" && rest[i + 1]) {
+          scope = rest[i + 1];
+          i += 1;
+        } else if (!arg.startsWith("--")) {
+          description = `${description} ${arg}`.trim();
+        }
+      }
+      console.log(formatPromoteMessage({ scope, description }));
+    } else 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 | validate | context");
+    }
+  } catch (err) {
+    console.error(`❌ ${err.message}`);
+    process.exit(1);
+  }
 } else if (command === "classify-change") {
   try {
     let json = false;

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

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