@luizsantiago/spec-guardrails 4.5.1 → 4.6.0

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)
 
@@ -11,7 +10,7 @@
 
 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.5.x**
+npm: [`@luizsantiago/spec-guardrails`](https://www.npmjs.com/package/@luizsantiago/spec-guardrails) **4.6.x**
 
 ---
 
@@ -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 |
 | --- | --- |
@@ -59,7 +60,7 @@ In short: Python turns "trust the agent" into "the agent has to prove it."
 
 Which checks exist and what each one requires: [Gates](docs/guide/gates.md) · [Guarantees matrix](docs/guide/Guarantees-matrix.md)
 
-Read more: [Quick start](docs/guide/Quick-start.md) · [Platform parity](docs/guide/Platform-parity.md) · [CHANGELOG](docs/CHANGELOG.md)
+Read more: [Quick start](docs/guide/Quick-start.md) · [Tutorials](docs/guide/tutorials/README.md) · [Platform parity](docs/guide/Platform-parity.md) · [CHANGELOG](docs/CHANGELOG.md)
 
 ---
 
@@ -139,7 +140,7 @@ 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 |
@@ -235,7 +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 and theme-aware diagram presentation |
+| [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

@@ -25,6 +25,10 @@ import {
   savePolicyState,
 } from "./lib/execution-policy.js";
 import { featureInit } from "./lib/feature.js";
+import {
+  featureOverview,
+  formatFeatureOverview,
+} from "./lib/feature-overview.js";
 import { featureStatus, formatFeatureStatus } from "./lib/feature-status.js";
 import { GATE_COMMANDS, AUX_COMMANDS, runGate, runGuardrailsScript } from "./lib/gates.js";
 import { install } from "./lib/install.js";
@@ -101,10 +105,13 @@ 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
+  feature-overview [feature]           REQ → task → evidence dashboard (markdown)
+    [--write]                        Save .specs/features/<feature>/overview.md
+    [--json]                         Machine-readable output (no markdown body)
   phase-context <phase>              Print .specs/config.yaml context + rules for a phase
   doctor [path]                      Audit guardrails readiness (score + next actions)
     [--json]                         Machine-readable output
@@ -872,9 +879,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) {
@@ -1082,6 +1086,33 @@ if (command === "--version" || command === "-v" || command === "version") {
     console.error(`❌ ${err.message}`);
     process.exit(1);
   }
+} else if (command === "feature-overview") {
+  try {
+    let json = false;
+    let write = false;
+    const positional = [];
+    for (const arg of args) {
+      if (arg === "--json") {
+        json = true;
+      } else if (arg === "--write") {
+        write = true;
+      } else {
+        positional.push(arg);
+      }
+    }
+    const overview = await featureOverview(positional[0], { write });
+    if (json) {
+      console.log(JSON.stringify(overview, null, 2));
+    } else {
+      process.stdout.write(formatFeatureOverview(overview));
+      if (overview.writtenTo) {
+        process.stderr.write(`\nWrote ${overview.writtenTo}\n`);
+      }
+    }
+  } catch (err) {
+    console.error(`❌ ${err.message}`);
+    process.exit(1);
+  }
 } else if (AUX_COMMANDS.includes(command)) {
   try {
     const code = await runGuardrailsScript(command, args);

package/lib/agent-contract.js

@@ -28,7 +28,7 @@ When planning architecture, specs, or multi-step features, read the hub first:
 Deterministic gates (\`python3\`, non-zero exit means STOP):
 
 - Scripts in \`.specs/guardrails/scripts/\` — the **agent** runs them at phase boundaries (see hub).
-- Humans: \`install\` once; optional \`feature-init\`, \`project-init\`, \`doctor\`, \`classify-change\`, \`feature-status\`.
+- Humans: \`install\` once; optional \`feature-init\`, \`project-init\`, \`doctor\`, \`classify-change\`, \`feature-status\`, \`feature-overview\`.
 - Full CLI: \`npx @luizsantiago/spec-guardrails --help\`
 - Onboarding: \`.specs/GETTING_STARTED.md\`
 

package/lib/feature-overview.js

@@ -0,0 +1,237 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { readFileSafe } from "./fs-utils.js";
+import { featureStatus } from "./feature-status.js";
+import { featureDir, resolveFeatureId } from "./specs-utils.js";
+
+const REQ_ID = /\b[A-Z][A-Z0-9]{1,9}-\d{2,4}\b/g;
+const TASK_HEADING = /^#{2,6}\s*(T\d+)[:\s]+(.+)$/gim;
+const TASK_FIELD =
+  /^\s*[-*]?\s*\*{0,2}([A-Za-z][A-Za-z ]+?)\*{0,2}\s*:\s*(.+?)\s*$/gim;
+const EVIDENCE = /[\w./\\-]+\.[A-Za-z][A-Za-z0-9]{0,9}:\d{1,6}\b/g;
+
+/**
+ * @param {string} text
+ * @returns {string[]}
+ */
+function uniqueReqIds(text) {
+  return [...new Set(text.match(REQ_ID) ?? [])];
+}
+
+/**
+ * @param {string} tasksText
+ * @returns {Array<{ id: string, title: string, requirement: string | null, complete: boolean }>}
+ */
+function parseTasks(tasksText) {
+  const headings = [...tasksText.matchAll(TASK_HEADING)];
+  /** @type {Array<{ id: string, title: string, requirement: string | null, complete: boolean }>} */
+  const tasks = [];
+
+  for (let i = 0; i < headings.length; i += 1) {
+    const start = headings[i].index ?? 0;
+    const end = headings[i + 1]?.index ?? tasksText.length;
+    const block = tasksText.slice(start, end);
+    const id = headings[i][1];
+    const title = headings[i][2].trim();
+    let requirement = null;
+    for (const match of block.matchAll(TASK_FIELD)) {
+      if (match[1].trim().toLowerCase() === "requirement") {
+        requirement = match[2].trim();
+        break;
+      }
+    }
+    const complete = /-\s*\[x\]\s*complete\b/i.test(block);
+    tasks.push({ id, title, requirement, complete });
+  }
+  return tasks;
+}
+
+/**
+ * @param {string} validationText
+ * @param {string} reqId
+ * @returns {string | null}
+ */
+function evidenceForReq(validationText, reqId) {
+  for (const line of validationText.split(/\r?\n/)) {
+    if (!line.includes(reqId)) {
+      continue;
+    }
+    const hit = line.match(EVIDENCE);
+    if (hit?.[0]) {
+      return hit[0];
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {string} specText
+ * @returns {string | null}
+ */
+function summarizeGoal(specText) {
+  const title = specText.match(/^#\s+(.+)$/m)?.[1]?.trim();
+  if (title && !/^spec/i.test(title)) {
+    return title;
+  }
+  const firstReq = specText.match(
+    /^###\s+([A-Z][A-Z0-9]{1,9}-\d{2,4})\b[^\n]*\n+([^\n#]+)/m,
+  );
+  if (firstReq) {
+    return `${firstReq[1]} — ${firstReq[2].trim()}`;
+  }
+  return title ?? null;
+}
+
+/**
+ * @param {string} [featureArg]
+ * @param {{ cwd?: string }} [options]
+ */
+export async function buildFeatureOverview(featureArg, options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const featureId = await resolveFeatureId(featureArg, cwd);
+  const status = await featureStatus(featureId, { cwd });
+  const dir = featureDir(featureId, cwd);
+
+  let specText = "";
+  let tasksText = "";
+  let validationText = "";
+
+  try {
+    specText = await readFileSafe(path.join(dir, "spec.md"));
+  } catch {
+    // optional until Specify
+  }
+  try {
+    tasksText = await readFileSafe(path.join(dir, "tasks.md"));
+  } catch {
+    // optional until Tasks
+  }
+  try {
+    validationText = await readFileSafe(path.join(dir, "validation.md"));
+  } catch {
+    // optional until Verify
+  }
+
+  const reqIds = uniqueReqIds(specText);
+  const tasks = tasksText ? parseTasks(tasksText) : [];
+  const reqToTasks = new Map();
+  for (const task of tasks) {
+    if (!task.requirement) {
+      continue;
+    }
+    for (const reqId of uniqueReqIds(task.requirement)) {
+      const list = reqToTasks.get(reqId) ?? [];
+      list.push(task.id);
+      reqToTasks.set(reqId, list);
+    }
+  }
+
+  const traceability = reqIds.map((reqId) => ({
+    reqId,
+    tasks: reqToTasks.get(reqId) ?? [],
+    evidence: validationText ? evidenceForReq(validationText, reqId) : null,
+  }));
+
+  return {
+    featureId,
+    generatedAt: new Date().toISOString(),
+    goal: specText ? summarizeGoal(specText) : null,
+    status,
+    tasks,
+    traceability,
+  };
+}
+
+/**
+ * @param {Awaited<ReturnType<typeof buildFeatureOverview>>} overview
+ * @returns {string}
+ */
+export function formatFeatureOverview(overview) {
+  const { status } = overview;
+  const artifactRows = Object.entries(status.artifacts)
+    .map(([name, present]) => `| ${name} | ${present ? "present" : "missing"} |`)
+    .join("\n");
+
+  const taskRows =
+    overview.tasks.length > 0
+      ? overview.tasks
+          .map(
+            (task) =>
+              `| ${task.id} | ${task.title} | ${task.requirement ?? "—"} | ${task.complete ? "done" : "open"} |`,
+          )
+          .join("\n")
+      : "| — | — | — | — |";
+
+  const traceRows =
+    overview.traceability.length > 0
+      ? overview.traceability
+          .map((row) => {
+            const tasks =
+              row.tasks.length > 0 ? row.tasks.join(", ") : "—";
+            return `| ${row.reqId} | ${tasks} | ${row.evidence ?? "—"} |`;
+          })
+          .join("\n")
+      : "| — | — | — |";
+
+  const taskSummary = status.tasks
+    ? `${status.tasks.complete}/${status.tasks.total} complete (${status.tasks.open} open)`
+    : "—";
+
+  return `# Feature overview: ${overview.featureId}
+
+> Generated ${overview.generatedAt}. Refresh with \`feature-overview ${overview.featureId} --write\`.
+
+## Summary
+
+| Field | Value |
+| --- | --- |
+| Goal | ${overview.goal ?? "—"} |
+| Phase | ${status.phase ?? "—"} |
+| Branch | ${status.branch ?? "—"} |
+| Tasks | ${taskSummary} |
+| Validation | ${status.verdict ?? "—"} |
+| Next | ${status.next} |
+
+## Artifacts
+
+| Artifact | Status |
+| --- | --- |
+${artifactRows}
+
+## Tasks
+
+| Task | Title | Requirement | Status |
+| --- | --- | --- | --- |
+${taskRows}
+
+## Traceability (REQ → task → evidence)
+
+| REQ | Task(s) | Test evidence |
+| --- | --- | --- |
+${traceRows}
+
+_Evidence rows populate after \`validation.md\` exists. Structural gaps are caught by \`validate-traceability\`._
+`;
+}
+
+/**
+ * @param {string} [featureArg]
+ * @param {{ cwd?: string; write?: boolean }} [options]
+ */
+export async function featureOverview(featureArg, options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const overview = await buildFeatureOverview(featureArg, { cwd });
+  const markdown = formatFeatureOverview(overview);
+
+  if (options.write) {
+    const outPath = path.join(
+      featureDir(overview.featureId, cwd),
+      "overview.md",
+    );
+    await fs.writeFile(outPath, markdown, "utf8");
+    overview.writtenTo = outPath;
+  }
+
+  return overview;
+}

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.1",
+  "version": "4.6.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": {
@@ -12,7 +12,7 @@
   "scripts": {
     "guardrails": "node index.js",
     "test": "npm run test:node && npm run test:gates",
-    "test:node": "node --test test/install.test.js test/test_platform_detect.test.js test/test_feature_init.test.js test/test_config.test.js test/test_archive.test.js test/test_delta_merge.test.js test/test_presets.test.js test/test_brownfield.test.js test/test_doctor.test.js test/test_token_cost.test.js test/test_next_steps.test.js test/test_classify_change.test.js test/test_feature_status.test.js test/test_agent_contract.test.js test/test_gates_python.test.js test/test_specs_utils.test.js test/test_validation_verdict.test.js test/test_execution_policy.test.js test/test_workspace_isolation.test.js test/test_adapter_registry.test.js test/test_context_guard.test.js test/test_solution_exploration.test.js test/test_memory_doctor.test.js test/test_cursor_hooks_cleanup.test.js test/test_sandbox_policy.test.js test/test_req_analysis.test.js",
+    "test:node": "node --test test/install.test.js test/test_platform_detect.test.js test/test_feature_init.test.js test/test_config.test.js test/test_archive.test.js test/test_delta_merge.test.js test/test_presets.test.js test/test_brownfield.test.js test/test_doctor.test.js test/test_token_cost.test.js test/test_next_steps.test.js test/test_classify_change.test.js test/test_feature_status.test.js test/test_feature_overview.test.js test/test_agent_contract.test.js test/test_gates_python.test.js test/test_specs_utils.test.js test/test_validation_verdict.test.js test/test_execution_policy.test.js test/test_workspace_isolation.test.js test/test_adapter_registry.test.js test/test_context_guard.test.js test/test_solution_exploration.test.js test/test_memory_doctor.test.js test/test_cursor_hooks_cleanup.test.js test/test_sandbox_policy.test.js test/test_req_analysis.test.js",
     "test:gates": "node test/run-gate-tests.mjs",
     "prepublishOnly": "npm test"
   },

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"
 
@@ -84,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
@@ -86,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()
@@ -99,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:
@@ -110,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
@@ -61,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,7 @@ 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]` |
@@ -67,6 +67,7 @@ Structural gates run **before** owner review, so they cannot drift when the mode
 | Quick mode evidence | `python3 .specs/guardrails/scripts/validate_quick.py [feature]` |
 | After Verify PASS | `npx @luizsantiago/spec-guardrails archive-feature [feature]` (Tier 0) |
 | Before a phase procedure (optional) | `npx @luizsantiago/spec-guardrails phase-context <phase>` |
+| Feature dashboard (human-readable) | `npx @luizsantiago/spec-guardrails feature-overview [feature] [--write]` |
 | After a FAIL verdict | `python3 .specs/guardrails/scripts/lessons.py add --source .specs/features/[feature]/validation.md` |
 
 Gates accept a feature name, a feature directory, or a path to the artifact. With no argument they auto-detect when the project has exactly one feature; with several they list candidates and exit 2. A spec is rejected unless every criterion uses `SHALL` or `MUST` and `## Assumptions` is present.
@@ -92,11 +93,11 @@ EXPLORE (optional) → ELICIT (optional) → SPECIFY → DISCUSS (conditional)
 | **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`, `check_suppressions.py` |
-| **Verify** | Yes | `references/validate.md` | `security-review.md` | `validate_state.py`, `run_quality_checks.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` |
@@ -121,7 +122,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 |
@@ -131,7 +132,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/skills/references/converge.md

@@ -28,10 +28,12 @@ Updated `tasks.md` with new tasks for uncovered work (append only — do not rew
 
 1. **Re-read the spec** — list every REQ and whether tests exist for its outcome.
 2. **Audit the diff** — files changed outside task `Files` fields are scope drift or missing tasks.
-3. **Run analyze** — `analyze_artifacts.py [feature]`.
-4. **Append tasks** for gaps using the standard task template in `tasks.md`.
-5. **Update STATE** Next Step to the first open task.
-6. **Commit** `.specs/` changes (Tier 0) — no push.
+3. **Living-spec drift (lightweight)** — when `domains/<slug>/spec.md` exists, spot-check that files still match declared globs or modules; append a task if production code moved without updating domain memory.
+4. **Run analyze** — `analyze_artifacts.py [feature]`.
+5. **Append tasks** for gaps using the standard task template in `tasks.md`.
+6. **Refresh dashboard** — `npx @luizsantiago/spec-guardrails feature-overview [feature] --write`.
+7. **Update STATE** Next Step to the first open task.
+8. **Commit** `.specs/` changes (Tier 0) — no push.
 
 ## Rules
 

package/skills/references/implement.md

@@ -64,8 +64,9 @@ loop-plan → dispatch (parallel sub-agents | inline) → merge → loop-plan
 2. **Dispatch**
    - **Parallel group (2+ tasks):** one sub-agent per task with the worker brief in `sub-agents.md`. Cap at 3 workers + 1 verifier (see `task-graph-engineering.md`).
    - **Single task:** run the per-task cycle below inline (or as sole worker).
-3. **Merge** — After a parallel round, confirm every task is `[x]`, commits exist, and the project harness passes once on the integrated tree.
-4. **Repeat** — Run `loop-plan` again until all tasks are complete, then close Execute.
+3. **Two-stage batch review** — After workers return and before merge, the orchestrator reviews each batch twice (see `sub-agents.md`): spec compliance, then code quality. Do not merge until both pass.
+4. **Merge** — Confirm every task is `[x]`, commits exist, and the project harness passes once on the integrated tree.
+5. **Repeat** — Run `loop-plan` again until all tasks are complete, then close Execute.
 
 Do not start the next wave until the current wave is fully committed. Parallelism is **inside** a wave only when `Files` do not overlap.
 
@@ -194,8 +195,9 @@ docs(spec): record validation report for auth
 When the last task is complete:
 
 1. Run the full project harness once more (tests, linter, build).
-2. Trigger `/verify` with a fresh context — mandatory, never prompted. See `validate.md`.
-3. Do not declare the feature done until `validate_state.py` passes.
+2. Refresh the feature dashboard: `npx @luizsantiago/spec-guardrails feature-overview [feature] --write` (writes `overview.md`).
+3. Trigger `/verify` with a fresh context — mandatory, never prompted. See `validate.md`.
+4. Do not declare the feature done until `validate_state.py` passes.
 
 ## Next
 

package/skills/references/sub-agents.md

@@ -69,6 +69,23 @@ Every worker returns this shape — no narrative dump:
 - Blockers: none | [gate output excerpt]
 ```
 
+## Two-stage batch review (orchestrator)
+
+After workers return and **before** merge, the orchestrator runs both stages. Workers do not self-certify merge readiness.
+
+| Stage | Question | Evidence |
+| --- | --- | --- |
+| **1 — Spec compliance** | Does each commit satisfy its task `Done when` and the REQ IDs on that task? | Re-read task blocks + diff; compare to spec criteria |
+| **2 — Code quality** | Is the integrated harness green, free of new suppressions, and scoped to task `Files`? | Project harness + `check_suppressions.py` on staged diff |
+
+| Outcome | Action |
+| --- | --- |
+| Stage 1 FAIL | Send worker back, or rewrite the task — do not merge |
+| Stage 2 FAIL | Fix or revert before merge — do not weaken tests |
+| Both PASS | Merge owner integrates worktrees, runs harness once, proceeds |
+
+Pattern adapted from [Superpowers subagent-driven-development](https://github.com/obra/superpowers) — compliance before polish.
+
 ## Failure handling
 
 | Event | Action |

package/skills/security-review.md

@@ -26,6 +26,22 @@ For changes with **no** auth, API, user input, payments, or infrastructure impac
 
 Full OWASP checklist remains mandatory for anything touching auth, data, APIs, or infra.
 
+## Third-party agent skills (supply chain)
+
+Spec Guardrails ships skills you install with `npx @luizsantiago/spec-guardrails install`. When adding **other** skill packs from GitHub, marketplaces (`skills.sh`, plugin stores), or zip files:
+
+1. **Read before trust** — inspect `SKILL.md` and any bundled scripts; skills run with agent privileges.
+2. **Scan when risk is non-trivial** — use [NVIDIA SkillSpector](https://github.com/NVIDIA/SkillSpector) for static (and optional LLM) analysis before install:
+
+   ```bash
+   skillspector scan https://github.com/user/some-skill --no-llm
+   ```
+
+3. **Prefer signed catalogs** — NVIDIA Verified Skills and official plugin marketplaces reduce supply-chain risk; still review high-privilege skills.
+4. **Never bypass Brakes** — third-party skills do not replace Spec Guardrails gates (`check-suppressions`, `validate-state`, …).
+
+For publication-quality skill evaluation (overlap detection, live agent eval), see [SkillEvaluator](https://github.com/NVIDIA/SkillEvaluator) — complementary to this package, not a replacement.
+
 ## Pre-Review Setup
 
 - Verifier must have **clean context** (not the code author).

package/skills/task-graph-engineering.md

@@ -72,6 +72,7 @@ The shape serious systems converge to for splittable work:
 | --- | --- | --- |
 | Plan | Single planner | Produces `tasks.md` + `task-graph.md` |
 | Workers | 1–3 parallel agents | Disjoint file ownership only |
+| Batch review | Orchestrator (two stages) | Spec compliance, then code quality — before merge |
 | Verify | Fresh verifier context | Never the code author |
 | Merge | One merge owner | Resolves conflicts, runs harness |
 | Result | Commits + evidence | Handoff to `/archive` when done |

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)