@luizsantiago/spec-guardrails 4.5.0 → 4.5.2

package/README.md

@@ -1,7 +1,6 @@
 # Spec Guardrails
 
 [![npm version](https://img.shields.io/npm/v/@luizsantiago/spec-guardrails.svg)](https://www.npmjs.com/package/@luizsantiago/spec-guardrails)
-[![npm downloads](https://img.shields.io/npm/dm/@luizsantiago/spec-guardrails.svg)](https://www.npmjs.com/package/@luizsantiago/spec-guardrails)
 [![CI](https://github.com/luizssantiago92/spec-guardrails/actions/workflows/ci.yml/badge.svg)](https://github.com/luizssantiago92/spec-guardrails/actions/workflows/ci.yml)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
@@ -39,7 +38,9 @@ npx @luizsantiago/spec-guardrails install
 npx @luizsantiago/spec-guardrails doctor
 ```
 
-`install` writes the phase guides for your agent and creates the `.specs/` folder. Re-run it after upgrading the package — your existing `.specs/` notes are preserved. After that, you work in **agent chat**, not in the terminal; the agent calls the CLI and checks when needed.
+`install` writes the phase guides for your agent and creates the `.specs/` folder. By default it detects your platform (Cursor, Claude Code, Copilot, or Codex) and installs **one** skill tree plus that platform's adapter entry file. Existing trees are preserved when you switch IDEs. Use `install --all-platforms` for every tree, or `install --platform <id>` to force one.
+
+Re-run `install` after upgrading the package — your existing `.specs/` notes are preserved. After that, you work in **agent chat**, not in the terminal; the agent calls the CLI and checks when needed.
 
 | Requirement | Role |
 | --- | --- |
@@ -139,12 +140,12 @@ Automatic checks at step boundaries — each one blocks a specific kind of short
 | `validate-traceability` | REQ → task → proof chain is broken |
 | `validate-state` | Feature is declared done without evidence |
 | `validate-quick` | Quick-mode fix broke its size or shape rules |
-| `check-commit` | Commit message does not follow the agreed format |
+| `check-commit` | Commit message is not conventional, staged diff is empty, or exceeds `commit.max_staged_lines` |
 | `check-suppressions` | Staged diff adds `# noqa`, `eslint-disable`, `@ts-ignore`, skipped tests, or `--no-verify` |
 | `quality-checks` | Configured project commands (`npm test`, …) fail during `/verify` |
 | `lessons` | A failed verify tries to skip the lesson step |
 
-→ [Gates](docs/guide/gates.md) · [Garantees matrix](docs/guide/Guarantees-matrix.md)
+→ [Gates](docs/guide/gates.md) · [Guarantees matrix](docs/guide/Guarantees-matrix.md)
 
 ### Requirements analysis
 
@@ -235,6 +236,7 @@ Spec Guardrails adapts patterns from open-source work. These are the projects wh
 | [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) | MIT | Design-discussion patterns and definition-of-done framing |
 | [graph-engineering](https://github.com/codejunkie99/graph-engineering) | MIT | Task-graph rules behind safe parallel waves |
 | [loop-engineering](https://github.com/cobusgreyling/loop-engineering) | MIT | Wave-based execution model |
+| [loopgate_harness](https://github.com/rxdt/loopgate_harness) | MIT | Suppression-bypass blocking, project-configured quality commands as verify evidence, honest-limits framing, and README diagram layout (proxy-safe SVG; SMIL animation on GitHub) |
 
 Everything else — the CLI, the Python checks, the platform adapters, and the requirements-analysis phase — is original work in this repository. Full lineage, including references we cite but do not bundle: [Credits and lineage](docs/guide/credits.md).
 

package/index.js

@@ -101,7 +101,7 @@ Commands:
     [--no-roadmap]                   Skip ROADMAP update
     [--no-domain]                    Skip domain spec merge
     [--no-state]                     Skip STATE reset
-  classify-change [desc] [files...]  Heuristic complexity tier (quick/simple/medium/complex)
+  classify-change <desc> [files...]  Heuristic complexity tier (quick/simple/medium/complex)
     [--json]                         Machine-readable output
   feature-status [feature]           Artifact checklist + next step for a feature
     [--json]                         Machine-readable output
@@ -872,9 +872,6 @@ if (command === "--version" || command === "-v" || command === "version") {
       process.stdout.write(formatExplorationStatus(status, { json }));
     } else if (sub === "validate") {
       const featureId = rest[0];
-      if (!featureId) {
-        throw new Error("Usage: solution-explore validate <feature>");
-      }
       const result = await validateExplorationArtifact(cwd, featureId);
       process.stdout.write(formatExplorationValidation(result, { json }));
       if (!result.ok) {

package/lib/gates.js

@@ -229,6 +229,18 @@ export async function runGuardrailsScriptCapture(command, args, options = {}) {
   const cwd = options.cwd ?? process.cwd();
   const scriptsDir = await resolveScriptsDir(cwd);
   const scriptPath = path.join(cwd, scriptsDir, scriptName);
+
+  for (const required of [scriptName, "_common.py"]) {
+    try {
+      await access(path.join(cwd, scriptsDir, required), constants.R_OK);
+    } catch {
+      throw new Error(
+        `Guardrails script not found at ${path.join(scriptsDir, required)}. ` +
+          `Run \`${NPX("install")}\` in this project first.`,
+      );
+    }
+  }
+
   const python = await resolvePython();
 
   if (!python) {

package/lib/install.js

@@ -167,7 +167,7 @@ export async function install(options = {}) {
   const pythonAvailable = await hasPython();
   if (!pythonAvailable) {
     log(
-      "⚠️  Python 3 not found — Process mode only (flexible workflow, manual checkpoints). " +
+      "⚠️  Python 3.10+ not found — Process mode only (flexible workflow, manual checkpoints). " +
         "Install Python 3.10+ for Brakes mode (full kit with automatic gates).",
     );
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luizsantiago/spec-guardrails",
-  "version": "4.5.0",
+  "version": "4.5.2",
   "description": "Governed spec-driven development for AI coding agents. Your agent writes the spec, gets your approval, builds in small waves, and proves the result — plans and project memory stored as files in your repo.",
   "type": "module",
   "bin": {

package/scripts/_project_config.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import re
 from pathlib import Path
 
-CONFIG_PATH = Path(".specs/config.yaml")
+CONFIG_RELATIVE = Path(".specs") / "config.yaml"
 
 DEFAULT_SUPPRESSION_PATTERNS = [
     r"#\s*noqa\b",
@@ -22,6 +22,11 @@ DEFAULT_SUPPRESSION_PATTERNS = [
 DEFAULT_MAX_STAGED_LINES = 500
 
 
+def config_path(cwd: Path | str | None = None) -> Path:
+    root = Path(cwd) if cwd is not None else Path.cwd()
+    return root / CONFIG_RELATIVE
+
+
 def _parse_scalar(raw: str):
     value = raw.strip().strip("'\"")
     lower = value.lower()
@@ -52,7 +57,7 @@ def _parse_list_block(lines: list[str], start_index: int, parent_indent: int) ->
     return items, index
 
 
-def load_project_config() -> dict:
+def load_project_config(cwd: Path | str | None = None) -> dict:
     """Return quality, suppressions, and commit policy blocks with defaults."""
 
     config = {
@@ -61,14 +66,13 @@ def load_project_config() -> dict:
         "commit": {"max_staged_lines": DEFAULT_MAX_STAGED_LINES},
     }
 
-    if not CONFIG_PATH.is_file():
+    path = config_path(cwd)
+    if not path.is_file():
         return config
 
-    lines = CONFIG_PATH.read_text(encoding="utf-8").splitlines()
+    lines = path.read_text(encoding="utf-8").splitlines()
     section = None
     section_indent = 0
-    subsection = None
-    subsection_indent = 0
 
     index = 0
     while index < len(lines):
@@ -83,27 +87,23 @@ def load_project_config() -> dict:
         if stripped == "quality:":
             section = "quality"
             section_indent = indent
-            subsection = None
             index += 1
             continue
 
         if stripped == "suppressions:":
             section = "suppressions"
             section_indent = indent
-            subsection = None
             index += 1
             continue
 
         if stripped == "commit:":
             section = "commit"
             section_indent = indent
-            subsection = None
             index += 1
             continue
 
         if section and indent <= section_indent and not stripped.endswith(":"):
             section = None
-            subsection = None
 
         if section == "quality" and stripped == "checks:":
             items, index = _parse_list_block(lines, index + 1, indent)

package/scripts/analyze_artifacts.py

@@ -64,6 +64,8 @@ def git_branch(root: Path) -> str | None:
             cwd=root,
             capture_output=True,
             text=True,
+            encoding="utf-8",
+            errors="replace",
             check=False,
         )
     except OSError:

package/scripts/check_commit.py

@@ -29,7 +29,7 @@ import sys
 from pathlib import Path
 
 from _common import EXIT_OK, EXIT_USAGE, Report
-from _project_config import load_project_config
+from _project_config import DEFAULT_MAX_STAGED_LINES, load_project_config
 
 GATE = "check-commit"
 
@@ -59,11 +59,14 @@ def read_staged_diff(cwd: Path) -> str:
         cwd=cwd,
         capture_output=True,
         text=True,
+        # Paths can carry bytes the platform locale cannot decode.
+        encoding="utf-8",
+        errors="replace",
         check=False,
     )
     if result.returncode not in (0, 1):
-        raise RuntimeError(result.stderr.strip() or "git diff --cached --numstat failed")
-    return result.stdout
+        raise RuntimeError((result.stderr or "").strip() or "git diff --cached --numstat failed")
+    return result.stdout or ""
 
 
 def count_staged_lines(numstat_text: str) -> int:
@@ -81,8 +84,8 @@ def count_staged_lines(numstat_text: str) -> int:
 
 def build_staged_report(cwd: Path) -> Report:
     report = Report(gate=GATE, target="staged changes")
-    config = load_project_config()
-    max_lines = int(config.get("commit", {}).get("max_staged_lines") or 500)
+    config = load_project_config(cwd)
+    max_lines = int(config.get("commit", {}).get("max_staged_lines") or DEFAULT_MAX_STAGED_LINES)
 
     if not (cwd / ".git").exists():
         report.error("not a git repository")

package/scripts/check_suppressions.py

@@ -4,7 +4,7 @@
 Run before commit when agents might silence linters or skip hooks:
 
     python3 check_suppressions.py
-    python3 check_suppressions.py --strict
+    python3 check_suppressions.py --cwd /path/to/repo
 
 Scans `git diff --cached` for patterns such as `# noqa`, `eslint-disable`,
 `@ts-ignore`, skipped tests, or `--no-verify`. Patterns are configurable under
@@ -33,11 +33,14 @@ def read_staged_diff(cwd: Path) -> str:
         cwd=cwd,
         capture_output=True,
         text=True,
+        # Diffs can carry bytes the platform locale cannot decode (SVG, em dashes).
+        encoding="utf-8",
+        errors="replace",
         check=False,
     )
     if result.returncode not in (0, 1):
-        raise RuntimeError(result.stderr.strip() or "git diff --cached failed")
-    return result.stdout
+        raise RuntimeError((result.stderr or "").strip() or "git diff --cached failed")
+    return result.stdout or ""
 
 
 def added_lines(diff_text: str) -> list[tuple[str, str]]:
@@ -83,11 +86,6 @@ def main(argv: list[str] | None = None) -> int:
         default=".",
         help="repository root (default: current directory)",
     )
-    parser.add_argument(
-        "--strict",
-        action="store_true",
-        help="treat warnings as blocking failures",
-    )
     args = parser.parse_args(argv)
 
     cwd = Path(args.cwd).resolve()
@@ -96,7 +94,7 @@ def main(argv: list[str] | None = None) -> int:
         print("  error   not a git repository")
         return EXIT_USAGE
 
-    config = load_project_config()
+    config = load_project_config(cwd)
     patterns = config.get("suppressions", {}).get("patterns") or DEFAULT_SUPPRESSION_PATTERNS
 
     try:
@@ -107,7 +105,7 @@ def main(argv: list[str] | None = None) -> int:
         return EXIT_USAGE
 
     report = build_report(diff_text, patterns)
-    return report.emit(strict=args.strict)
+    return report.emit()
 
 
 if __name__ == "__main__":

package/scripts/run_quality_checks.py

@@ -14,7 +14,7 @@ Configure under:
         - npm test
         - npm run lint
 
-Exit codes: 0 all passed, 1 one or more failed, 2 usage/config error.
+Exit codes: 0 all passed or skipped (no checks configured), 1 one or more failed.
 """
 
 from __future__ import annotations
@@ -38,6 +38,9 @@ def run_command(command: str, cwd: Path) -> dict:
         shell=True,
         capture_output=True,
         text=True,
+        # Test runners emit symbols the platform locale cannot always decode.
+        encoding="utf-8",
+        errors="replace",
         check=False,
     )
     output = (completed.stdout or "") + (completed.stderr or "")
@@ -58,7 +61,7 @@ def main(argv: list[str] | None = None) -> int:
     args = parser.parse_args(argv)
 
     cwd = Path(args.cwd).resolve()
-    checks = load_project_config().get("quality", {}).get("checks") or []
+    checks = load_project_config(cwd).get("quality", {}).get("checks") or []
 
     if not checks:
         message = {

package/skills/agent-architecture.md

@@ -59,7 +59,9 @@ Structural gates run **before** owner review, so they cannot drift when the mode
 | Retrieve related context | `npx @luizsantiago/spec-guardrails memory-retrieve "<query>"` |
 | Rebuild / embed memory index | `npx @luizsantiago/spec-guardrails memory-index rebuild` · `memory-index embed` |
 | On gate retry (Execute playbook) | `npx @luizsantiago/spec-guardrails execution-policy record-retry Tn` |
-| On each commit | `python3 .specs/guardrails/scripts/check_commit.py --message "<message>"` |
+| On each commit | `python3 .specs/guardrails/scripts/check_commit.py --message "<message>"` · `check_commit.py --staged` |
+| Before each commit (staged diff) | `python3 .specs/guardrails/scripts/check_suppressions.py` |
+| During Verify, when `quality.checks` is configured | `python3 .specs/guardrails/scripts/run_quality_checks.py` |
 | Before declaring a feature done | `python3 .specs/guardrails/scripts/validate_state.py [feature]` |
 | Traceability (Medium+ features) | `python3 .specs/guardrails/scripts/validate_traceability.py [feature]` |
 | Quick mode evidence | `python3 .specs/guardrails/scripts/validate_quick.py [feature]` |
@@ -82,19 +84,19 @@ EXPLORE (optional) → ELICIT (optional) → SPECIFY → DISCUSS (conditional)
 | Phase | Required | Reference | Sister skill | Gate |
 | --- | --- | --- | --- | --- |
 | **Explore** | Optional | `references/explore.md` | — | — |
-| **Elicit** | Optional | `references/elicitation.md` | `validate-req-analysis` | — (before `/specify`; suggest-only entry) |
+| **Elicit** | Optional | `references/elicitation.md` | — | `validate_req_analysis.py` (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` | — | — |
 | **Design** | No | `references/design.md` | — | — |
 | **Tasks** | No | `references/tasks.md` | `task-graph-engineering.md` | `validate_tasks.py` |
 | **Analyze** | Before task approval | `references/analyze.md` | — | `analyze_artifacts.py` |
-| **Execute** | Yes | `references/implement.md` | `engineering-standards.md` | `check_commit.py` |
-| **Verify** | Yes | `references/validate.md` | `security-review.md` | `validate_state.py` |
+| **Execute** | Yes | `references/implement.md` | `engineering-standards.md` | `check_commit.py`, `check_suppressions.py` |
+| **Verify** | Yes | `references/validate.md` | `security-review.md` | `validate_traceability.py`, `validate_state.py`, `run_quality_checks.py` |
 | **Archive** | After Verify PASS | `references/archive.md` | `git-handoff.md` | `archive-feature` |
 | **Converge** | On drift | `references/converge.md` | — | `analyze_artifacts.py` |
 | **Handoff** | Yes | `references/memory.md` | `git-handoff.md` | — |
-| **Quick** | Alternative | `references/quick-mode.md` | — | `check_commit.py`, `validate_quick.py` |
+| **Quick** | Alternative | `references/quick-mode.md` | — | `check_commit.py`, `check_suppressions.py`, `validate_quick.py` |
 | **Context** | Always | `references/context-limits.md` | — | — |
 | **Sub-agents** | When batched | `references/sub-agents.md` | `task-graph-engineering.md` | — |
 | **Solution exploration** | Explicit fork | `references/solution-exploration.md` | — | `solution-explore validate` |
@@ -119,7 +121,7 @@ Complexity determines depth. Do not run every phase on every change.
 
 | Tier | Scope | Path |
 | --- | --- | --- |
-| **Quick** | ≤3 files, no design decisions, no new dependencies | `references/quick-mode.md` — describe, implement, verify, commit; gates: `check_commit.py` + `validate-quick` |
+| **Quick** | ≤3 files, no design decisions, no new dependencies | `references/quick-mode.md` — describe, implement, verify, commit; gates: `check_commit.py`, `check_suppressions.py`, `validate-quick` |
 | **Simple** | 2–5 files, localized change | Specify → Execute → Verify |
 | **Medium** | New feature, <10 tasks | Specify → Tasks → Execute → Verify |
 | **Complex** | New architecture, API surface, infra | Specify → Discuss → Design → Tasks → Execute → Verify |
@@ -129,7 +131,7 @@ Complexity determines depth. Do not run every phase on every change.
 
 **Rules**
 
-- **Specify and Verify are always required on the full pipeline** — you must know WHAT was asked and prove it was delivered. **Quick** is the exception: the express lane in `references/quick-mode.md` (describe → implement → verify → commit) with `check_commit.py` on each commit and `validate-quick` as the close/evidence gate.
+- **Specify and Verify are always required on the full pipeline** — you must know WHAT was asked and prove it was delivered. **Quick** is the exception: the express lane in `references/quick-mode.md` (describe → implement → verify → commit) with `check_commit.py`, `check_suppressions.py` on each commit, and `validate-quick` as the close/evidence gate.
 - **Design is skipped** when there are no architectural decisions and no new patterns.
 - **Tasks is skipped** when there are ≤3 obvious steps.
 - **Discuss is triggered inside Specify** when the feature touches persistence, external calls, auth, payments, concurrency, or state transitions, or when the owner's intent is ambiguous.

package/templates/config.yaml.example

@@ -83,12 +83,17 @@ sandbox:
     - "\\b(DROP\\s+DATABASE|DROP\\s+SCHEMA|TRUNCATE\\s+TABLE)\\b"
 
 # Verification suppressions (optional — block agents from silencing linters/tests)
+# Omit this block to keep runtime defaults from _project_config.py (9 patterns).
 suppressions:
   patterns:
     - "#\\s*noqa\\b"
-    - "eslint-disable"
+    - "nosemgrep\\b"
+    - "eslint-disable(?:-next-line|-line)?"
     - "@ts-ignore\\b"
+    - "@ts-expect-error\\b"
     - "\\bxit\\s*\\("
+    - "\\bxdescribe\\s*\\("
+    - "\\bpytest\\.mark\\.skip\\b"
     - "--no-verify\\b"
 
 # Project quality commands (optional — run during /verify)