@luizsantiago/spec-guardrails 3.0.1

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@luizsantiago/spec-guardrails",
+  "version": "3.0.1",
+  "description": "Guardrails for AI coding agents — spec-driven phases, automatic gates, progressive skill loading (~70% fewer tokens per turn). Works in Cursor and Claude.",
+  "type": "module",
+  "bin": {
+    "spec-guardrails": "./index.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "guardrails": "node index.js",
+    "test": "npm run test:node && npm run test:gates",
+    "test:node": "node --test test/install.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:gates": "node test/run-gate-tests.mjs",
+    "prepublishOnly": "npm test"
+  },
+  "files": [
+    "index.js",
+    "lib/",
+    "skills/",
+    "rules/",
+    "scripts/*.py",
+    "templates/",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/luizssantiago92/spec-guardrails.git"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "cursor",
+    "claude",
+    "spec-driven",
+    "guardrails",
+    "cli"
+  ],
+  "author": "luizsantiago",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/rules/engineering-baseline.mdc

@@ -0,0 +1,56 @@
+---
+description: Engineering baseline and guardrails map for this repository
+alwaysApply: true
+---
+
+# Engineering Baseline
+
+- Follow existing codebase conventions before introducing new patterns.
+- Run tests and linters before considering work done.
+- Never commit secrets, API keys, or credentials.
+- Prefer small, focused diffs over large refactors.
+- Touch only the files the current task requires; park out-of-scope ideas in `.specs/STATE.md`.
+- Apply secure coding practices from `.cursor/skills/engineering-standards.md`.
+- Run the security checklist from `.cursor/skills/security-review.md` during `/verify`.
+
+# Artifact Language
+
+All project artifacts are written in English: source code, tests, comments, commit messages, PR titles and descriptions, `.specs/` documents, and identifier names.
+
+Chat language is a personal preference. Set it in your own agent settings if you want replies in another language.
+
+# Guardrails Skills
+
+<!-- guardrails-managed:skills-map:start -->
+| Skill | Purpose |
+| --- | --- |
+| `.cursor/skills/agent-architecture.md` | SDD hub — contract, phases, gates, complexity router |
+| `.cursor/skills/references/` | Phase procedures (explore, project-init, constitution, specify, discuss, design, tasks, analyze, implement, validate, converge, archive, memory, quick-mode, context-limits, lessons, sub-agents) |
+| `.cursor/skills/task-graph-engineering.md` | Task DAG, parallelism, verify topology |
+| `.cursor/skills/engineering-standards.md` | Code quality, secure coding, git hygiene |
+| `.cursor/skills/security-review.md` | Security checklist for verification |
+| `.cursor/skills/appsec.md` | Application security sister (load on demand) |
+| `.cursor/skills/qa-strategy.md` | QA strategy sister (load on demand) |
+| `.cursor/skills/code-simplify.md` | Simplification sister (load on demand) |
+| `.cursor/skills/ship-ready.md` | Ship-ready sister (load on demand) |
+| `.cursor/skills/git-handoff.md` | Git sync and session handoff |
+<!-- guardrails-managed:skills-map:end -->
+
+# Deterministic Gates
+
+<!-- guardrails-managed:gates-map:start -->
+Gates live in `.specs/guardrails/scripts/` (Python 3). **The agent runs them** at phase boundaries — see `agent-architecture.md`.
+
+| You run (human) | When |
+| --- | --- |
+| `install` | Once (or after upgrading the package) |
+| `feature-init "…"` | Optional — or ask the agent to `/specify` |
+| `project-init` | Optional — brownfield repo with existing code |
+| `doctor` | Install looks broken |
+
+Everything else (`validate-spec`, `validate-tasks`, `check-commit`, …) is normally run **by the agent**, not memorized from this file. Full list: `npx @luizsantiago/spec-guardrails --help` or `.specs/GETTING_STARTED.md`.
+
+Non-zero gate exit = STOP. Without Python, the agent performs the same checks manually.
+
+**Git tiers:** Tier 0 (branch, local commits, `.specs/`) is automatic after you approve spec/tasks. Push, PR, merge, and deploy need owner go-ahead. See `git-handoff.md`.
+<!-- guardrails-managed:gates-map:end -->

package/scripts/_common.py

@@ -0,0 +1,356 @@
+"""Shared helpers for the Spec Guardrails structural gates.
+
+Gates are deterministic: they read an artifact, apply structural checks, and exit
+non-zero when the artifact is not ready for the next phase. They never mutate
+project files.
+
+Exit codes:
+    0 - gate passed (warnings may still be printed)
+    1 - gate failed; fix the artifact before proceeding
+    2 - usage error (missing file, bad arguments)
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+EXIT_OK = 0
+EXIT_FAILED = 1
+EXIT_USAGE = 2
+
+# Angle brackets are ambiguous: `<fill me>` is an unfilled template, but
+# `Promise<void>` and `List<User>` are types a real acceptance criterion may
+# name. Only flag bracketed text that reads like prose (contains a space) or
+# matches a known template token, so typed specs are not rejected.
+ANGLE_TEMPLATE_TOKEN = (
+    r"tbd|todo|fixme|xxx|placeholder|fill[ -]?(?:me|in|this)?|"
+    r"your[ -][a-z0-9 _-]+|insert[ -][a-z0-9 _-]+"
+)
+
+PLACEHOLDER_PATTERNS = (
+    re.compile(r"\bTBD\b", re.IGNORECASE),
+    re.compile(r"\bTODO\b"),
+    re.compile(r"\bFIXME\b"),
+    re.compile(r"\bXXX\b"),
+    re.compile(rf"<\s*(?:{ANGLE_TEMPLATE_TOKEN})\s*>", re.IGNORECASE),
+    re.compile(r"<[a-z][a-z0-9_-]*(?:[ ][a-z0-9_-]+)+>", re.IGNORECASE),
+    # `[name]` style templates, but never a markdown link such as `[label](url)`
+    # and never a task checkbox such as `- [x]`.
+    re.compile(
+        r"\[(?:feature|name|description|fill me|placeholder)\](?!\()",
+        re.IGNORECASE,
+    ),
+)
+
+
+@dataclass
+class Report:
+    """Collects gate findings and renders a deterministic summary."""
+
+    gate: str
+    target: str
+    errors: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+    checks: list[str] = field(default_factory=list)
+
+    def error(self, message: str) -> None:
+        self.errors.append(message)
+
+    def warn(self, message: str) -> None:
+        self.warnings.append(message)
+
+    def ok(self, message: str) -> None:
+        self.checks.append(message)
+
+    @property
+    def passed(self) -> bool:
+        return not self.errors
+
+    def emit(self, strict: bool = False) -> int:
+        status = "PASS" if self.passed else "FAIL"
+        print(f"[{self.gate}] {status} - {self.target}")
+
+        for check in self.checks:
+            print(f"  ok      {check}")
+        for warning in self.warnings:
+            print(f"  warn    {warning}")
+        for error in self.errors:
+            print(f"  error   {error}")
+
+        if strict and self.warnings and self.passed:
+            print("  error   strict mode: warnings are treated as failures")
+            return EXIT_FAILED
+
+        if not self.passed:
+            print(
+                f"\n{len(self.errors)} blocking issue(s). "
+                "Fix the artifact and re-run this gate before proceeding."
+            )
+            return EXIT_FAILED
+
+        return EXIT_OK
+
+
+FEATURES_DIR = Path(".specs/features")
+
+REQUIREMENT_ID = re.compile(
+    r"^(?P<level>#{2,6})\s*(?P<id>[A-Z][A-Z0-9]{1,9}-\d{2,4})\b",
+    re.MULTILINE,
+)
+REQUIREMENTS_HEADING = re.compile(
+    r"^(?P<level>#{2,6})\s*Requirements\b",
+    re.MULTILINE | re.IGNORECASE,
+)
+ANY_HEADING = re.compile(r"^(?P<level>#{1,6})\s", re.MULTILINE)
+HTML_COMMENT = re.compile(r"<!--.*?-->", re.DOTALL)
+
+
+def section_body(text: str, heading: re.Pattern[str]) -> str | None:
+    """Return the body of the first matching section, or None if absent."""
+
+    match = heading.search(text)
+    if not match:
+        return None
+
+    level = len(match.group("level"))
+    start = match.end()
+    end = len(text)
+    for next_heading in ANY_HEADING.finditer(text, start):
+        if len(next_heading.group("level")) <= level:
+            end = next_heading.start()
+            break
+    return text[start:end]
+
+
+def requirement_ids(text: str) -> list[str]:
+    """Return requirement IDs from markdown headings under `## Requirements`.
+
+    Headings under Assumptions, Out of Scope, or other sections are ignored so
+    NOTE-001-style notes never become coverage obligations.
+    """
+
+    body = section_body(text, REQUIREMENTS_HEADING)
+    search_text = body if body is not None else text
+    seen: set[str] = set()
+    ordered: list[str] = []
+    for match in REQUIREMENT_ID.finditer(search_text):
+        requirement_id = match.group("id")
+        if requirement_id not in seen:
+            seen.add(requirement_id)
+            ordered.append(requirement_id)
+    return ordered
+
+
+def mask_fenced_blocks(text: str) -> str:
+    """Blank out fenced code so structural regexes ignore sample snippets.
+
+    Fence marker lines and their interiors become empty lines, so line numbers
+    stay aligned with the original document.
+    """
+
+    masked: list[str] = []
+    in_fence = False
+
+    for line in text.splitlines(keepends=True):
+        stripped = line.lstrip()
+        if stripped.startswith("```"):
+            in_fence = not in_fence
+            masked.append("\n" if line.endswith("\n") else "")
+            continue
+        if in_fence:
+            masked.append("\n" if line.endswith("\n") else "")
+            continue
+        masked.append(line)
+
+    return "".join(masked)
+
+
+def strip_html_comments(text: str) -> str:
+    """Blank HTML comments so evidence and verdicts inside them do not count."""
+
+    return HTML_COMMENT.sub(lambda match: "\n" * match.group(0).count("\n"), text)
+
+
+def visible_markdown(text: str) -> str:
+    """Markdown visible to structural gates: fences and HTML comments removed."""
+
+    return mask_fenced_blocks(strip_html_comments(text))
+
+
+def normalize_file_path(raw: str) -> str:
+    """Strip markdown/noise and collapse `./`, `/`, quotes, links, and `..`.
+
+    Result is case-folded so Auth/Token.ts and auth/token.ts collide on overlap
+    checks (macOS/Windows volumes; also stops casing dodges).
+    """
+
+    cleaned = raw.strip().strip("`\"'").replace("\\", "/")
+    link = re.fullmatch(r"\[([^\]]*)\]\(([^)]+)\)", cleaned)
+    if link:
+        cleaned = link.group(2).strip().strip("`\"'")
+    while cleaned.startswith("./"):
+        cleaned = cleaned[2:]
+    cleaned = cleaned.lstrip("/")
+    cleaned = re.sub(r"^[A-Za-z]:/", "", cleaned)
+    cleaned = cleaned.rstrip("/")
+
+    parts: list[str] = []
+    for part in cleaned.split("/"):
+        if part in ("", "."):
+            continue
+        if part == "..":
+            if parts:
+                parts.pop()
+            continue
+        parts.append(part)
+    return "/".join(parts).casefold()
+
+
+def _fail_usage(gate: str, target: str, message: str) -> None:
+    print(f"[{gate}] FAIL - {target}")
+    print(f"  error   {message}")
+    sys.exit(EXIT_USAGE)
+
+
+def list_features(root: Path = Path(".")) -> list[Path]:
+    """Return every feature directory under `.specs/features`, sorted by name."""
+
+    base = root / FEATURES_DIR
+
+    if not base.is_dir():
+        return []
+
+    return sorted(path for path in base.iterdir() if path.is_dir())
+
+
+def resolve_feature_dir(
+    raw: str | None, gate: str, root: Path = Path(".")
+) -> Path:
+    """Resolve a feature directory from a path, a bare feature name, or context.
+
+    Accepts `.specs/features/auth/spec.md`, `.specs/features/auth`, `auth`, or
+    nothing at all when the project has exactly one feature.
+    """
+
+    if raw:
+        candidate = Path(raw).expanduser()
+
+        if candidate.is_file():
+            return candidate.parent
+
+        if candidate.is_dir():
+            return candidate
+
+        named = root / FEATURES_DIR / raw
+        if named.is_dir():
+            return named
+
+        _fail_usage(gate, raw, f"no such feature or path: {raw}")
+
+    features = list_features(root)
+
+    if len(features) == 1:
+        return features[0]
+
+    if not features:
+        _fail_usage(
+            gate,
+            str(root / FEATURES_DIR),
+            "no features found - create .specs/features/[feature]/ first",
+        )
+
+    listed = "\n".join(f"            {path.name}" for path in features)
+    _fail_usage(
+        gate,
+        str(root / FEATURES_DIR),
+        f"{len(features)} features found - name the one to check:\n{listed}",
+    )
+
+    raise AssertionError("unreachable")
+
+
+def resolve_artifact(
+    raw: str | None, filename: str, gate: str, root: Path = Path(".")
+) -> tuple[Path, str]:
+    """Read `filename` from a feature resolved by path, name, or auto-detection."""
+
+    if raw:
+        candidate = Path(raw).expanduser()
+        if candidate.is_file():
+            if candidate.name != filename:
+                _fail_usage(
+                    gate,
+                    raw,
+                    f"expected {filename}, got {candidate.name}",
+                )
+            return read_artifact(str(candidate), gate)
+
+    feature_dir = resolve_feature_dir(raw, gate, root)
+    return read_artifact(str(feature_dir / filename), gate)
+
+
+def read_artifact(raw_path: str, report_gate: str) -> tuple[Path, str]:
+    """Resolve and read a required artifact.
+
+    Missing paths and directories exit with EXIT_USAGE. An empty file exits
+    with EXIT_FAILED — the path is valid, the artifact is not ready.
+    """
+
+    path = Path(raw_path).expanduser()
+
+    if not path.exists():
+        print(f"[{report_gate}] FAIL - {path}")
+        print(f"  error   file not found: {path}")
+        sys.exit(EXIT_USAGE)
+
+    if path.is_dir():
+        print(f"[{report_gate}] FAIL - {path}")
+        print(f"  error   expected a file, got a directory: {path}")
+        sys.exit(EXIT_USAGE)
+
+    text = path.read_text(encoding="utf-8")
+
+    if not text.strip():
+        print(f"[{report_gate}] FAIL - {path}")
+        print("  error   file is empty")
+        sys.exit(EXIT_FAILED)
+
+    return path, text
+
+
+def find_placeholders(text: str) -> list[str]:
+    """Return unresolved placeholder tokens found in visible markdown.
+
+    Fenced samples and HTML comments are ignored, matching the other gates.
+    """
+
+    found: list[str] = []
+
+    for line_number, line in enumerate(visible_markdown(text).splitlines(), start=1):
+        stripped = line.strip()
+        if not stripped:
+            continue
+        is_heading = stripped.startswith("#")
+        for pattern in PLACEHOLDER_PATTERNS:
+            match = pattern.search(line)
+            if not match:
+                continue
+            token = match.group(0)
+            # Task titles such as "Fix TODO later" describe the work; TBD and
+            # template holes in a heading are still unfilled and must block.
+            if is_heading and token.upper() in {"TODO", "FIXME"}:
+                continue
+            found.append(f"line {line_number}: {token}")
+            break
+
+    return found
+
+
+def has_section(text: str, heading: str) -> bool:
+    """Case-insensitive check for a markdown heading anywhere in the document."""
+
+    pattern = re.compile(rf"^#{{1,6}}\s+{re.escape(heading)}\s*$", re.IGNORECASE | re.MULTILINE)
+    return bool(pattern.search(text))

package/scripts/analyze_artifacts.py

@@ -0,0 +1,187 @@
+#!/usr/bin/env python3
+"""Cross-artifact consistency gate for a feature.
+
+Run after Tasks (and optionally before Implement):
+
+    python3 analyze_artifacts.py auth
+    python3 analyze_artifacts.py .specs/features/003-chat-system
+
+Checks structural alignment across spec.md, tasks.md, design.md, and STATE.md:
+  * every spec requirement ID appears in at least one task Requirement field
+  * every task Requirement references a spec requirement ID (when spec exists)
+  * open [NEEDS CLARIFICATION] markers (warning; blocking with --strict)
+  * STATE Active Feature branch matches current git branch when git is available
+  * design.md with only whitespace when tasks imply architecture (warning)
+
+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 (
+    Report,
+    requirement_ids,
+    resolve_feature_dir,
+    visible_markdown,
+)
+
+GATE = "analyze-artifacts"
+CLARIFICATION = re.compile(r"\[NEEDS CLARIFICATION(?:\s*:\s*[^\]]+)?\]", re.IGNORECASE)
+TASK_FIELD = re.compile(
+    r"^\s*[-*]?\s*\*{0,2}(?P<key>[A-Za-z][A-Za-z ]+?)\*{0,2}\s*:\s*(?P<value>.+?)\s*$",
+    re.MULTILINE,
+)
+REQUIREMENT_REF = re.compile(r"\b[A-Z][A-Z0-9]{1,9}-\d{2,4}\b")
+STATE_BRANCH = re.compile(
+    r"^\s*-\s*Branch:\s*(.+)$",
+    re.IGNORECASE | re.MULTILINE,
+)
+STATE_FEATURE = re.compile(
+    r"^\s*-\s*Feature:\s*(.+)$",
+    re.IGNORECASE | re.MULTILINE,
+)
+
+
+def git_branch(root: Path) -> str | None:
+    try:
+        result = subprocess.run(
+            ["git", "branch", "--show-current"],
+            cwd=root,
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except OSError:
+        return None
+
+    if result.returncode != 0:
+        return None
+
+    branch = result.stdout.strip()
+    return branch or None
+
+
+def task_requirement_ids(tasks_text: str) -> set[str]:
+    ids: set[str] = set()
+    for match in TASK_FIELD.finditer(tasks_text):
+        if match.group("key").strip().lower() != "requirement":
+            continue
+        ids.update(REQUIREMENT_REF.findall(match.group("value")))
+    return ids
+
+
+def read_optional(feature_dir: Path, filename: str) -> str | None:
+    path = feature_dir / filename
+    if not path.is_file():
+        return None
+    text = path.read_text(encoding="utf-8")
+    return text if text.strip() else None
+
+
+def build_report(feature_dir: Path, root: Path) -> Report:
+    report = Report(gate=GATE, target=str(feature_dir))
+    spec_text = read_optional(feature_dir, "spec.md")
+    tasks_text = read_optional(feature_dir, "tasks.md")
+    design_text = read_optional(feature_dir, "design.md")
+    state_path = root / ".specs/STATE.md"
+
+    if spec_text:
+        spec_ids = requirement_ids(spec_text)
+        report.ok(f"{len(spec_ids)} requirement ID(s) in spec.md")
+    else:
+        spec_ids = []
+        report.warn("spec.md missing or empty — REQ coverage checks skipped")
+
+    if tasks_text:
+        covered = task_requirement_ids(tasks_text)
+        report.ok(f"{len(covered)} requirement ID(s) referenced in tasks.md")
+
+        if spec_ids:
+            missing = [req for req in spec_ids if req not in covered]
+            if missing:
+                report.error(
+                    "requirements without task coverage: "
+                    + ", ".join(missing)
+                )
+            else:
+                report.ok("every spec requirement is referenced by a task")
+
+            orphan_tasks = sorted(covered - set(spec_ids))
+            if orphan_tasks:
+                report.error(
+                    "tasks reference unknown requirement IDs: "
+                    + ", ".join(orphan_tasks)
+                )
+    else:
+        report.warn("tasks.md missing or empty — task coverage checks skipped")
+
+    if design_text is not None and tasks_text:
+        visible_design = visible_markdown(design_text).strip()
+        if len(visible_design.splitlines()) < 5:
+            report.warn(
+                "design.md exists but looks empty — Complex work should document architecture"
+            )
+
+    searchable = "\n".join(filter(None, [spec_text, tasks_text, design_text]))
+    if searchable:
+        markers = CLARIFICATION.findall(searchable)
+        if markers:
+            report.warn(
+                f"{len(markers)} open [NEEDS CLARIFICATION] marker(s) — resolve before approval"
+            )
+        else:
+            report.ok("no open [NEEDS CLARIFICATION] markers")
+
+    if state_path.is_file():
+        state = state_path.read_text(encoding="utf-8")
+        feature_match = STATE_FEATURE.search(state)
+        branch_match = STATE_BRANCH.search(state)
+
+        if feature_match:
+            state_feature = feature_match.group(1).strip()
+            if state_feature not in {"—", "-", "none"} and state_feature != feature_dir.name:
+                report.warn(
+                    f"STATE.md Active Feature ({state_feature}) differs from "
+                    f"analyzed feature ({feature_dir.name})"
+                )
+
+        current = git_branch(root)
+        if branch_match and current:
+            state_branch = branch_match.group(1).strip()
+            if state_branch not in {"—", "-", "none"} and state_branch != current:
+                report.warn(
+                    f"STATE.md branch ({state_branch}) differs from git ({current}) — reconcile"
+                )
+            elif state_branch == current:
+                report.ok("STATE branch matches current git branch")
+
+    return report
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Analyze cross-artifact consistency")
+    parser.add_argument(
+        "feature",
+        nargs="?",
+        help="feature name, feature directory, or path to spec.md",
+    )
+    parser.add_argument(
+        "--strict",
+        action="store_true",
+        help="treat warnings as blocking failures",
+    )
+    args = parser.parse_args(argv)
+
+    feature_dir = resolve_feature_dir(args.feature, GATE)
+    report = build_report(feature_dir, Path("."))
+    return report.emit(strict=args.strict)
+
+
+if __name__ == "__main__":
+    sys.exit(main())