@luizsantiago/spec-guardrails 4.4.0 → 4.5.0

package/README.md

@@ -1,13 +1,17 @@
 # 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)
 
+![Spec Guardrails — governed spec-driven development for AI coding agents](https://raw.githubusercontent.com/luizssantiago92/spec-guardrails/main/.assets/banner.svg)
+
 **Governed spec-driven development for AI coding agents.**
 
 Spec Guardrails installs a working method into your repository: the agent writes down what it is going to build, gets your approval, implements in small waves, and proves the result before calling it done. Nothing about your stack changes — you get written requirements, a task plan, and verification evidence stored as files in the project.
 
-npm: [`@luizsantiago/spec-guardrails`](https://www.npmjs.com/package/@luizsantiago/spec-guardrails) **4.4.x**
+npm: [`@luizsantiago/spec-guardrails`](https://www.npmjs.com/package/@luizsantiago/spec-guardrails) **4.5.x**
 
 ---
 
@@ -63,64 +67,11 @@ Read more: [Quick start](docs/guide/Quick-start.md) · [Platform parity](docs/gu
 
 You describe your project or the feature you want — in chat, or by pointing the agent at a file such as `prd.md` or `docs/brief.md`. With Spec Guardrails already installed, the agent reads that material plus what is already in the repo and picks up from there if work is in progress (`STATE.md` tells it where you left off).
 
-```
-     YOU describe the project or feature
-     (chat, prd.md, docs/brief.md, kickoff paste)
-              │
-              ▼
-   ┌──────────────────────┐
-   │  READ & CLASSIFY     │   Agent reads your inputs and the repo,
-   │                      │   then sizes the change (see table below).
-   └──────────┬───────────┘
-              │
-        Still vague? ──► Requirements analysis (optional)
-              │          Up to 5 questions per round, one topic at a time,
-              │          with suggested options — never repeats what your
-              │          document already answered.
-              ▼
-   ┌──────────────────────┐
-   │  REQUIREMENTS BRIEF  │   Captured gaps and decisions in writing.
-   └──────────┬───────────┘
-              │
-        ◆ YOU APPROVE ◆        (1 of 3 — when elicitation ran)
-              │
-              ▼
-   ┌──────────────────────┐
-   │  SPECIFY             │   What must happen, what "done" means,
-   │                      │   what is out of scope → spec.md
-   └──────────┬───────────┘
-              │
-        ◆ YOU APPROVE ◆        (2 of 3)
-              │
-              ▼
-   ┌──────────────────────┐
-   │  TASKS               │   Small checkable jobs → tasks.md
-   │                      │   (+ task-graph.md when work can split)
-   └──────────┬───────────┘
-              │
-        ◆ YOU APPROVE ◆        (3 of 3)
-              │
-              ▼
-   ┌──────────────────────┐
-   │  BUILD (loop)        │   One wave at a time: test, implement,
-   │        ↺             │   check, commit — repeat until done.
-   └──────────┬───────────┘
-              ▼
-   ┌──────────────────────┐
-   │  VERIFY              │   Independent review with proof → validation.md
-   └──────────┬───────────┘
-              ▼
-   ┌──────────────────────┐
-   │  ARCHIVE             │   Fold outcome into project memory.
-   └──────────────────────┘
-
-   Tiny fix (≤3 files, no new dependency)?
-   Express lane: build → verify → commit (no spec/tasks ceremony).
-```
+![Spec Guardrails phase flow — classify, optional elicitation, three human approvals, build loop, verify, archive](https://raw.githubusercontent.com/luizssantiago92/spec-guardrails/main/.assets/flow.svg)
 
 The agent never skips your approvals on the full path. Requirements analysis is **suggested**, not forced — if the request is already clear, it goes straight to Specify.
 
-Read more: [How it works](docs/guide/How-it-works.md) · [Agent commands](docs/guide/agent-commands.md)
+Read more: [How it works](docs/guide/How-it-works.md) · [Agent commands](docs/guide/agent-commands.md) · [Glossary](docs/guide/Glossary.md)
 
 ---
 
@@ -128,6 +79,8 @@ Read more: [How it works](docs/guide/How-it-works.md) · [Agent commands](docs/g
 
 Before starting, the agent classifies the change and loads only what that change needs. A typo does not get a task graph; a payments integration does not skip review.
 
+![Complexity tiers — Quick, Simple, Medium, Complex, Parallel](https://raw.githubusercontent.com/luizssantiago92/spec-guardrails/main/.assets/tiers.svg)
+
 | Complexity | Typical scope | What gets created | Your approvals |
 | --- | --- | --- | --- |
 | **Quick** | ≤3 files, no new dependency, no auth/payments | Code + quick evidence | None (express lane) |
@@ -173,7 +126,7 @@ Instructions the agent loads **one at a time** — hub `agent-architecture.md` (
 
 → [Skills and hub](docs/guide/skills-and-hub.md)
 
-### Gates (9)
+### Gates (11)
 
 Automatic checks at step boundaries — each one blocks a specific kind of shortcut:
 
@@ -187,6 +140,8 @@ Automatic checks at step boundaries — each one blocks a specific kind of short
 | `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-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)
@@ -223,7 +178,7 @@ Implementation happens in **small waves**: pick the next runnable jobs, test, im
 
 | Path | Role |
 | --- | --- |
-| `.cursor/skills/` (+ Claude, Copilot, Codex trees) | Phase instructions for the agent |
+| `.cursor/skills/` (or detected platform tree) | Phase instructions for your agent |
 | `.specs/STATE.md` | Active feature and next step |
 | `.specs/features/NNN-slug/` | Spec, tasks, and validation per feature |
 | `.specs/guardrails/scripts/` | Python checks (when Brakes mode is on) |
@@ -231,6 +186,21 @@ Implementation happens in **small waves**: pick the next runnable jobs, test, im
 
 ---
 
+## Honest limits
+
+Gates enforce **structure and evidence in `.specs/`** — not product taste, not whether your tests are clever, and not a full AST review of implementation code. A green gate means the artifact shape and cited proof look complete; you still approve specs and tasks.
+
+| Gates check | Gates do **not** check |
+| --- | --- |
+| Spec sections and `SHALL`/`MUST` criteria | Semantic alignment between tests and requirements |
+| REQ → task → validation traceability | Stub or broken source outside cited paths |
+| Commit message shape and suppression patterns | Whether coverage % equals test quality |
+| Commands you list under `quality.checks` | Commands you never configured |
+
+See [Guarantees matrix](docs/guide/Guarantees-matrix.md) for the full product view.
+
+---
+
 ## Documentation
 
 | Topic | Start here | Go deeper |
@@ -241,7 +211,7 @@ Implementation happens in **small waves**: pick the next runnable jobs, test, im
 | Enforcement | [Gates](docs/guide/gates.md) | [Gates and guarantees](docs/guide/Gates-and-guarantees.md) |
 | Requirements | [Requirements analysis](docs/guide/requirements-analysis.md) | [Agent commands → /elicit](docs/guide/agent-commands.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) |
+| Questions | [FAQ](docs/guide/FAQ.md) | [Glossary](docs/guide/Glossary.md) · [Stability policy](docs/guide/Stability-policy.md) |
 
 Full index: [docs/guide/README.md](docs/guide/README.md)
 

package/index.js

@@ -180,6 +180,9 @@ Commands:
   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
+    [--staged]                       Also reject empty commits and oversized staged diffs
+  check-suppressions                 Block noqa/eslint-disable/ts-ignore/skip in staged diff
+  quality-checks [--json]            Run quality.checks from .specs/config.yaml (/verify)
   lessons <add|list|penalize|prune|promote|graduate|status>  Lessons engine
   --help                             Show this message
   --version                          Print the package version

package/lib/constants.js

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

package/lib/doctor.js

@@ -47,6 +47,9 @@ async function hasPlatformAdapterContract(cwd, adapterIds) {
     }
 
     for (const relativePath of adapter.entryFiles) {
+      if (relativePath.endsWith(".mdc")) {
+        continue;
+      }
       try {
         const content = await readFileSafe(path.join(cwd, relativePath));
         if (!content.includes(CURSORRULES_MARKER_BEGIN)) {

package/lib/gates.js

@@ -37,6 +37,8 @@ const GATE_SCRIPTS = {
   "validate-req-analysis": "validate_req_analysis.py",
   "analyze-artifacts": "analyze_artifacts.py",
   "check-commit": "check_commit.py",
+  "check-suppressions": "check_suppressions.py",
+  "quality-checks": "run_quality_checks.py",
   lessons: "lessons.py",
 };
 

package/lib/install.js

@@ -173,8 +173,14 @@ export async function install(options = {}) {
   }
 
   if (!options.silent) {
-    printInstallNextSteps({ pythonAvailable, preset: options.preset });
+    printInstallNextSteps({
+      pythonAvailable,
+      preset: options.preset,
+      detected,
+      skillDirs,
+      allPlatforms: options.allPlatforms,
+    });
   }
 
-  return { pythonAvailable };
+  return { pythonAvailable, detected, skillDirs };
 }

package/lib/next-steps.js

@@ -5,8 +5,33 @@
 const DOCS_BASE =
   "https://github.com/luizssantiago92/spec-guardrails/blob/main/docs/guide";
 
+/** @type {Record<string, string>} */
+const PLATFORM_LABELS = {
+  cursor: "Cursor",
+  claude: "Claude Code",
+  copilot: "GitHub Copilot",
+  codex: "OpenAI Codex",
+};
+
+/**
+ * @param {string | null | undefined} platformId
+ * @returns {string}
+ */
+function formatPlatformLabel(platformId) {
+  if (!platformId) {
+    return "Cursor (default)";
+  }
+  return PLATFORM_LABELS[platformId] ?? platformId;
+}
+
 /**
- * @param {{ pythonAvailable?: boolean, preset?: string }} [options]
+ * @param {{
+ *   pythonAvailable?: boolean,
+ *   preset?: string,
+ *   detected?: string | null,
+ *   skillDirs?: string[],
+ *   allPlatforms?: boolean,
+ * }} [options]
  * @returns {string[]}
  */
 export function formatInstallNextSteps(options = {}) {
@@ -15,12 +40,35 @@ export function formatInstallNextSteps(options = {}) {
     "✨ Setup complete.",
     "",
     "Next:",
-    "  1. Open your AI coding agent in this project (Cursor, Claude, Copilot, Codex, or AGENTS.md adapters install automatically).",
+  ];
+
+  if (options.allPlatforms) {
+    lines.push(
+      "  1. Open your AI coding agent — skills installed for Cursor, Claude, Copilot, and Codex.",
+    );
+  } else if (options.skillDirs?.length === 1) {
+    lines.push(
+      `  1. Open ${formatPlatformLabel(options.detected)} — skills installed under ${options.skillDirs[0]}/.`,
+    );
+    lines.push(
+      "     Need more agents? Re-run with `--all-platforms` or `--platform <cursor|claude|copilot|codex>`.",
+    );
+  } else {
+    const trees = options.skillDirs?.join(", ") ?? ".cursor/skills";
+    lines.push(
+      `  1. Open your AI coding agent — skills refreshed under: ${trees}.`,
+    );
+    lines.push(
+      "     Existing platform trees were preserved. Use `--all-platforms` to install every tree.",
+    );
+  }
+
+  lines.push(
     "  2. Run **Specify** (`/specify` or “Specify a feature: …”).",
     "",
     `  Architecture: ${DOCS_BASE}/Architecture.md`,
     `  Quick start: ${DOCS_BASE}/Quick-start.md · .specs/GETTING_STARTED.md (this project)`,
-  ];
+  );
 
   if (options.preset) {
     lines.push(`  Config: .specs/config.yaml (preset: ${options.preset})`);
@@ -46,7 +94,13 @@ export function formatInstallNextSteps(options = {}) {
 }
 
 /**
- * @param {{ pythonAvailable?: boolean, preset?: string }} [options]
+ * @param {{
+ *   pythonAvailable?: boolean,
+ *   preset?: string,
+ *   detected?: string | null,
+ *   skillDirs?: string[],
+ *   allPlatforms?: boolean,
+ * }} [options]
  */
 export function printInstallNextSteps(options = {}) {
   for (const line of formatInstallNextSteps(options)) {

package/package.json

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

@@ -0,0 +1,126 @@
+"""Project config helpers for quality checks and suppression patterns."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+CONFIG_PATH = Path(".specs/config.yaml")
+
+DEFAULT_SUPPRESSION_PATTERNS = [
+    r"#\s*noqa\b",
+    r"nosemgrep\b",
+    r"eslint-disable(?:-next-line|-line)?",
+    r"@ts-ignore\b",
+    r"@ts-expect-error\b",
+    r"\bxit\s*\(",
+    r"\bxdescribe\s*\(",
+    r"\bpytest\.mark\.skip\b",
+    r"--no-verify\b",
+]
+
+DEFAULT_MAX_STAGED_LINES = 500
+
+
+def _parse_scalar(raw: str):
+    value = raw.strip().strip("'\"")
+    lower = value.lower()
+    if lower in {"true", "yes", "on"}:
+        return True
+    if lower in {"false", "no", "off"}:
+        return False
+    if re.fullmatch(r"-?\d+", value):
+        return int(value)
+    return value
+
+
+def _parse_list_block(lines: list[str], start_index: int, parent_indent: int) -> tuple[list[str], int]:
+    items: list[str] = []
+    index = start_index
+    while index < len(lines):
+        line = lines[index]
+        if not line.strip() or line.lstrip().startswith("#"):
+            index += 1
+            continue
+        indent = len(line) - len(line.lstrip())
+        if indent <= parent_indent:
+            break
+        match = re.match(r"^\s*-\s+(.+)$", line)
+        if match:
+            items.append(_parse_scalar(match.group(1)))
+        index += 1
+    return items, index
+
+
+def load_project_config() -> dict:
+    """Return quality, suppressions, and commit policy blocks with defaults."""
+
+    config = {
+        "quality": {"checks": []},
+        "suppressions": {"patterns": list(DEFAULT_SUPPRESSION_PATTERNS)},
+        "commit": {"max_staged_lines": DEFAULT_MAX_STAGED_LINES},
+    }
+
+    if not CONFIG_PATH.is_file():
+        return config
+
+    lines = CONFIG_PATH.read_text(encoding="utf-8").splitlines()
+    section = None
+    section_indent = 0
+    subsection = None
+    subsection_indent = 0
+
+    index = 0
+    while index < len(lines):
+        line = lines[index]
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            index += 1
+            continue
+
+        indent = len(line) - len(line.lstrip())
+
+        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)
+            config["quality"]["checks"] = items
+            continue
+
+        if section == "suppressions" and stripped == "patterns:":
+            items, index = _parse_list_block(lines, index + 1, indent)
+            if items:
+                config["suppressions"]["patterns"] = items
+            continue
+
+        if section == "commit":
+            match = re.match(r"^max_staged_lines:\s*(.+)$", stripped)
+            if match:
+                config["commit"]["max_staged_lines"] = int(_parse_scalar(match.group(1)))
+
+        index += 1
+
+    return config

package/scripts/check_commit.py

@@ -24,10 +24,12 @@ from __future__ import annotations
 
 import argparse
 import re
+import subprocess
 import sys
 from pathlib import Path
 
-from _common import EXIT_USAGE, Report
+from _common import EXIT_OK, EXIT_USAGE, Report
+from _project_config import load_project_config
 
 GATE = "check-commit"
 
@@ -51,6 +53,61 @@ HEADER = re.compile(
 MAX_SUBJECT_LENGTH = 72
 
 
+def read_staged_diff(cwd: Path) -> str:
+    result = subprocess.run(
+        ["git", "diff", "--cached", "--numstat"],
+        cwd=cwd,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode not in (0, 1):
+        raise RuntimeError(result.stderr.strip() or "git diff --cached --numstat failed")
+    return result.stdout
+
+
+def count_staged_lines(numstat_text: str) -> int:
+    total = 0
+    for line in numstat_text.splitlines():
+        parts = line.split("\t")
+        if len(parts) < 3:
+            continue
+        added, deleted = parts[0], parts[1]
+        if added == "-" or deleted == "-":
+            continue
+        total += int(added) + int(deleted)
+    return total
+
+
+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)
+
+    if not (cwd / ".git").exists():
+        report.error("not a git repository")
+        return report
+
+    try:
+        numstat = read_staged_diff(cwd)
+    except RuntimeError as err:
+        report.error(str(err))
+        return report
+
+    if not numstat.strip():
+        report.error("empty commit blocked — no staged changes")
+        return report
+
+    lines = count_staged_lines(numstat)
+    report.ok(f"staged diff spans {lines} line(s)")
+    if lines > max_lines:
+        report.error(
+            f"staged diff is {lines} lines — limit is {max_lines} "
+            "(split the commit or raise commit.max_staged_lines in config)"
+        )
+    return report
+
+
 def build_report(message: str) -> Report:
     lines = message.rstrip().splitlines()
     header = lines[0].strip() if lines else ""
@@ -107,33 +164,60 @@ def build_report(message: str) -> Report:
 
 
 def main(argv: list[str] | None = None) -> int:
-    parser = argparse.ArgumentParser(description="Validate a commit message")
-    source = parser.add_mutually_exclusive_group(required=True)
-    source.add_argument("--message", help="commit message text")
-    source.add_argument("--file", help="path to a file holding the commit message")
+    parser = argparse.ArgumentParser(description="Validate a commit message and/or staged diff")
+    parser.add_argument("--message", help="commit message text")
+    parser.add_argument("--file", help="path to a file holding the commit message")
+    parser.add_argument(
+        "--staged",
+        action="store_true",
+        help="validate staged diff size and reject empty commits",
+    )
     parser.add_argument(
         "--strict",
         action="store_true",
         help="treat warnings as blocking failures",
     )
+    parser.add_argument(
+        "--cwd",
+        default=".",
+        help="repository root for --staged (default: current directory)",
+    )
     args = parser.parse_args(argv)
 
-    if args.file:
-        path = Path(args.file).expanduser()
-        if not path.exists():
-            print(f"[{GATE}] FAIL - {path}")
-            print(f"  error   file not found: {path}")
-            return EXIT_USAGE
-        message = path.read_text(encoding="utf-8")
-    else:
-        message = args.message or ""
+    if args.message and args.file:
+        print(f"[{GATE}] FAIL - arguments")
+        print("  error   use either --message or --file, not both")
+        return EXIT_USAGE
+
+    if not args.staged and not args.message and not args.file:
+        print(f"[{GATE}] FAIL - arguments")
+        print("  error   provide --message, --file, or --staged")
+        return EXIT_USAGE
+
+    exit_code = EXIT_OK
+
+    if args.staged:
+        staged_report = build_staged_report(Path(args.cwd).resolve())
+        exit_code = max(exit_code, staged_report.emit(strict=args.strict))
+
+    if args.message or args.file:
+        if args.file:
+            path = Path(args.file).expanduser()
+            if not path.exists():
+                print(f"[{GATE}] FAIL - {path}")
+                print(f"  error   file not found: {path}")
+                return EXIT_USAGE
+            message = path.read_text(encoding="utf-8")
+        else:
+            message = args.message or ""
 
-    comment_free = "\n".join(
-        line for line in message.splitlines() if not line.startswith("#")
-    )
+        comment_free = "\n".join(
+            line for line in message.splitlines() if not line.startswith("#")
+        )
+        message_report = build_report(comment_free)
+        exit_code = max(exit_code, message_report.emit(strict=args.strict))
 
-    report = build_report(comment_free)
-    return report.emit(strict=args.strict)
+    return exit_code
 
 
 if __name__ == "__main__":

package/scripts/check_suppressions.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+"""Block verification suppressions in staged diffs.
+
+Run before commit when agents might silence linters or skip hooks:
+
+    python3 check_suppressions.py
+    python3 check_suppressions.py --strict
+
+Scans `git diff --cached` for patterns such as `# noqa`, `eslint-disable`,
+`@ts-ignore`, skipped tests, or `--no-verify`. Patterns are configurable under
+`.specs/config.yaml` → `suppressions.patterns`.
+
+Exit codes: 0 pass, 1 blocking issues, 2 usage error.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+from _common import EXIT_USAGE, Report
+from _project_config import DEFAULT_SUPPRESSION_PATTERNS, load_project_config
+
+GATE = "check-suppressions"
+
+
+def read_staged_diff(cwd: Path) -> str:
+    result = subprocess.run(
+        ["git", "diff", "--cached", "--unified=0", "--no-color"],
+        cwd=cwd,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode not in (0, 1):
+        raise RuntimeError(result.stderr.strip() or "git diff --cached failed")
+    return result.stdout
+
+
+def added_lines(diff_text: str) -> list[tuple[str, str]]:
+    """Return (file, line) pairs for added lines in a unified diff."""
+
+    entries: list[tuple[str, str]] = []
+    current_file = "(unknown)"
+    for line in diff_text.splitlines():
+        if line.startswith("+++ b/"):
+            current_file = line[6:].strip()
+            continue
+        if line.startswith("+") and not line.startswith("+++"):
+            entries.append((current_file, line[1:]))
+    return entries
+
+
+def build_report(diff_text: str, patterns: list[str]) -> Report:
+    report = Report(gate=GATE, target="staged diff")
+    compiled = [(pattern, re.compile(pattern, re.IGNORECASE)) for pattern in patterns]
+
+    if not diff_text.strip():
+        report.ok("no staged changes — suppression scan skipped")
+        return report
+
+    additions = added_lines(diff_text)
+    hits = 0
+    for file_path, content in additions:
+        for pattern, regex in compiled:
+            if regex.search(content):
+                hits += 1
+                report.error(f"{file_path}: added line matches forbidden pattern /{pattern}/")
+
+    if hits == 0:
+        report.ok(f"no forbidden suppressions in {len(additions)} added line(s)")
+
+    return report
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Block linter/test suppressions in staged diff")
+    parser.add_argument(
+        "--cwd",
+        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()
+    if not (cwd / ".git").exists():
+        print(f"[{GATE}] FAIL - {cwd}")
+        print("  error   not a git repository")
+        return EXIT_USAGE
+
+    config = load_project_config()
+    patterns = config.get("suppressions", {}).get("patterns") or DEFAULT_SUPPRESSION_PATTERNS
+
+    try:
+        diff_text = read_staged_diff(cwd)
+    except RuntimeError as err:
+        print(f"[{GATE}] FAIL - staged diff")
+        print(f"  error   {err}")
+        return EXIT_USAGE
+
+    report = build_report(diff_text, patterns)
+    return report.emit(strict=args.strict)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/run_quality_checks.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+"""Run project quality commands declared in `.specs/config.yaml`.
+
+Used during /verify to execute the owner's test/lint commands and attach
+evidence that commands actually ran:
+
+    python3 run_quality_checks.py
+    python3 run_quality_checks.py --json
+
+Configure under:
+
+    quality:
+      checks:
+        - npm test
+        - npm run lint
+
+Exit codes: 0 all passed, 1 one or more failed, 2 usage/config error.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+from _common import EXIT_FAILED, EXIT_OK
+from _project_config import load_project_config
+
+GATE = "quality-checks"
+
+
+def run_command(command: str, cwd: Path) -> dict:
+    completed = subprocess.run(
+        command,
+        cwd=cwd,
+        shell=True,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    output = (completed.stdout or "") + (completed.stderr or "")
+    if len(output) > 8000:
+        output = output[:8000] + "\n… (truncated)"
+    return {
+        "command": command,
+        "exit_code": completed.returncode,
+        "output": output,
+        "passed": completed.returncode == 0,
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Run configured project quality checks")
+    parser.add_argument("--cwd", default=".", help="repository root")
+    parser.add_argument("--json", action="store_true", help="machine-readable output")
+    args = parser.parse_args(argv)
+
+    cwd = Path(args.cwd).resolve()
+    checks = load_project_config().get("quality", {}).get("checks") or []
+
+    if not checks:
+        message = {
+            "gate": GATE,
+            "status": "skipped",
+            "reason": "no quality.checks configured in .specs/config.yaml",
+            "results": [],
+        }
+        if args.json:
+            print(json.dumps(message, indent=2))
+        else:
+            print(f"[{GATE}] SKIP - no quality.checks configured")
+            print("  info      add commands under quality.checks in .specs/config.yaml")
+        return EXIT_OK
+
+    results = [run_command(command, cwd) for command in checks]
+    failed = [item for item in results if not item["passed"]]
+
+    payload = {
+        "gate": GATE,
+        "status": "pass" if not failed else "fail",
+        "results": results,
+    }
+
+    if args.json:
+        print(json.dumps(payload, indent=2))
+    else:
+        status = "PASS" if not failed else "FAIL"
+        print(f"[{GATE}] {status} - {len(checks)} command(s)")
+        for item in results:
+            label = "ok" if item["passed"] else "blocking"
+            print(f"  {label:<9} {item['command']} (exit {item['exit_code']})")
+            if not item["passed"] and item["output"].strip():
+                for line in item["output"].strip().splitlines()[-8:]:
+                    print(f"            {line}")
+
+    return EXIT_OK if not failed else EXIT_FAILED
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/references/implement.md

@@ -84,6 +84,8 @@ Plan → Test → Implement → Gate → Commit → Next
 
 ```bash
 python3 .specs/guardrails/scripts/check_commit.py --message "feat(auth): add token refresh"
+python3 .specs/guardrails/scripts/check_commit.py --staged
+python3 .specs/guardrails/scripts/check_suppressions.py
 git add [files] .specs/features/[feature]/tasks.md
 git commit -m "feat(auth): add token refresh"
 ```

package/skills/references/validate.md

@@ -113,11 +113,12 @@ The completion gate searches for `file:line` (for example `test/routes/login.tes
 python3 .specs/guardrails/scripts/validate_state.py .specs/features/[feature]
 python3 .specs/guardrails/scripts/validate_state.py [feature]
 python3 .specs/guardrails/scripts/validate_state.py          # single-feature projects
+npx @luizsantiago/spec-guardrails quality-checks             # when quality.checks is configured
 ```
 
 Checks that the report exists, the verdict is exactly PASS in the **preamble** (before the first `##` section) or under a dedicated `## Verdict` / `## Result` / `## Status` heading, every spec requirement ID shares a line with test `file:line` evidence, and no task remains open. A `- Verdict: PASS` buried under Discrimination Sensor or Coverage does not count. Preamble and `## Verdict` must not disagree. Evidence inside fenced samples or HTML comments does not count. `PASS` with any surviving mutant on a sensor/mutant line fails. `PASS` with open `Gaps` bullets or Security Review `Result: fail` fails. On Medium+ features (`design.md` with content, 4+ tasks, or 2+ phases) a discrimination-sensor **outcome** is **blocking** — the section heading alone is not enough — and a Medium+ `PASS` requires at least one `killed` mutant in the sensor focus (`injected` alone, or `killed` only under Gaps, is not enough). Below Medium+ a missing outcome is a warning (`--strict` still promotes warnings). Non-zero exit means the feature is not done.
 
-The gate cannot judge whether a cited test actually asserts the criterion. That judgment is the verifier's; a green gate with a weak assertion is still a FAIL in the report.
+The gate cannot judge whether a cited test actually asserts the criterion. Run `quality-checks` when `.specs/config.yaml` lists project commands (`npm test`, …) and cite the passing output in the validation report. That judgment is still the verifier's; a green gate with a weak assertion is still a FAIL in the report.
 
 **Gate-enforced vs verifier judgment.** `validate_state.py` enforces form: verdict scope, test-path evidence, REQ↔evidence lines, sensor outcomes on Medium+, open Gaps, Security `Result: fail`, open tasks. The following stay **verifier judgment** (not structural gates): whether each coverage row's test truly asserts the outcome, whether a lightweight Security path is justified, Interactive UAT / walkthrough success, and optional `## AppSec` / `## QA` sections. See the [gate stability contract](https://github.com/luizssantiago92/spec-guardrails/blob/main/prd/gate-stability.md).
 

package/templates/config.yaml.example

@@ -82,6 +82,24 @@ sandbox:
     - "git\\s+push\\b[^\\n]*(--force|--force-with-lease)[^\\n]*\\b(main|master)\\b"
     - "\\b(DROP\\s+DATABASE|DROP\\s+SCHEMA|TRUNCATE\\s+TABLE)\\b"
 
+# Verification suppressions (optional — block agents from silencing linters/tests)
+suppressions:
+  patterns:
+    - "#\\s*noqa\\b"
+    - "eslint-disable"
+    - "@ts-ignore\\b"
+    - "\\bxit\\s*\\("
+    - "--no-verify\\b"
+
+# Project quality commands (optional — run during /verify)
+quality:
+  checks:
+    - npm test
+
+# Commit policy (optional — used with check-commit --staged)
+commit:
+  max_staged_lines: 500
+
 # Project-specific overrides (appended on top of preset + rules above):
 # overrides:
 #   rules: