@luizsantiago/spec-guardrails 3.1.8 → 3.1.10

package/README.md

@@ -91,11 +91,14 @@ Install Python when you want gates to fire; run `doctor` to confirm Brakes are a
 | --- | --- | --- | --- |
 | Intent exists before code | `validate-spec` | Brakes | Hard gate |
 | Tasks derive from requirements | `analyze-artifacts` | Brakes | Hard gate |
+| Task shape and graph when needed | `validate-tasks` | Brakes | Hard gate |
 | Requirements stay traceable | `validate-traceability` | Brakes | Hard gate |
+| Quick evidence is complete | `validate-quick` | Brakes | Hard gate |
 | Dependencies respected in Execute | `loop-plan` | Brakes | Hard gate |
 | Parallel work is file-safe | `task-graph.md` + `validate-tasks` | Process + Brakes | Artifact + gate |
 | Completion cites evidence | `validate-state` | Brakes | Hard gate |
 | Commits follow policy | `check-commit` | Brakes | Hard gate |
+| Lessons grounded after FAIL | `lessons` | Brakes | Hard gate |
 | Verification is independent | `/verify` + `validate.md` | Process | Phase skill |
 | Knowledge survives chats | `.specs/` + `archive-feature` | Process | Install + CLI |
 

package/lib/archive.js

@@ -8,6 +8,7 @@ import {
 } from "./delta-merge.js";
 import { ensureDir, readFileSafe, writeFileSafe } from "./fs-utils.js";
 import { runGate } from "./gates.js";
+import { assertSafeDomainSlug } from "./slug-utils.js";
 import {
   featureDir,
   readFeatureArtifact,
@@ -112,7 +113,8 @@ async function resetState(cwd) {
  */
 export function inferDomainFromFeature(featureId) {
   const match = /^(\d{3})-(.+)$/.exec(featureId);
-  return match ? match[2] : featureId;
+  const slug = match ? match[2] : featureId;
+  return assertSafeDomainSlug(slug);
 }
 
 /**
@@ -178,7 +180,9 @@ export async function archiveFeature(featureArg, options = {}) {
   let mergeSummary = [];
 
   if (!options.skipDomainMerge) {
-    const domain = options.domain ?? inferDomainFromFeature(featureId);
+    const domain = options.domain
+      ? assertSafeDomainSlug(options.domain)
+      : inferDomainFromFeature(featureId);
     const domainDir = path.join(cwd, ".specs/domains", domain);
     const domainSpecPath = path.join(domainDir, "spec.md");
     domainRelPath = `.specs/domains/${domain}/spec.md`;

package/lib/brownfield.js

@@ -5,6 +5,7 @@ import { domainSpecStub } from "./delta-merge.js";
 import { ensureDir, readFileSafe, writeFileIfMissing, writeFileSafe } from "./fs-utils.js";
 import { initGuardrailsMemory } from "./memory.js";
 import { initProjectConfig } from "./presets.js";
+import { assertSafeDomainSlug, slugifyDomain } from "./slug-utils.js";
 
 const SKIP_DIRS = new Set([
   ".git",
@@ -49,18 +50,6 @@ Track milestones and archived features.
 
 `;
 
-/**
- * @param {string} name
- * @returns {string}
- */
-function slugifyDomain(name) {
-  return name
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, "-")
-    .replace(/^-+|-+$/g, "")
-    .slice(0, 48);
-}
-
 /**
  * @param {string} cwd
  * @returns {Promise<string>}
@@ -345,7 +334,7 @@ export async function projectInit(options = {}) {
   const repoName = await readRepoName(cwd);
 
   let domains = options.domains?.map((d) => ({
-    domain: slugifyDomain(d),
+    domain: assertSafeDomainSlug(d),
     hint: `(manual: ${d})`,
   }));
 

package/lib/doctor.js

@@ -18,8 +18,6 @@ const execFileAsync = promisify(execFile);
 export const DOCTOR_PROCESS_CHECK_IDS = [
   "skills-hub",
   "specs-scaffold",
-  "config",
-  "baseline-rule",
   "state-feature",
   "platform-adapters",
 ];
@@ -170,14 +168,16 @@ export async function runDoctorChecks(cwd) {
     weight: 10,
     pass: await pathExists(cwd, ".specs/config.yaml"),
     suggest: NPX("init-config --preset default"),
+    optional: true,
   });
 
   checks.push({
     id: "baseline-rule",
-    label: "engineering-baseline.mdc always-on rule",
+    label: "engineering-baseline.mdc always-on rule (Cursor)",
     weight: 8,
     pass: await pathExists(cwd, ".cursor/rules/engineering-baseline.mdc"),
     suggest: NPX("install"),
+    optional: true,
   });
 
   checks.push({

package/lib/gates.js

@@ -7,12 +7,25 @@ import { NPX, GUARDRAILS_SCRIPTS_DIR } from "./constants.js";
 
 /** @typedef {{ command: string, args: string[] }} PythonInterpreter */
 
-const PYTHON_CANDIDATES = [
+const PYTHON_CANDIDATES_UNIX = [
   { command: "python3", args: [] },
   { command: "python", args: [] },
   { command: "py", args: ["-3"] },
 ];
 
+const PYTHON_CANDIDATES_WINDOWS = [
+  { command: "py", args: ["-3"] },
+  { command: "python", args: [] },
+  { command: "python3", args: [] },
+];
+
+/**
+ * @returns {PythonInterpreter[]}
+ */
+export function getPythonCandidates() {
+  return process.platform === "win32" ? PYTHON_CANDIDATES_WINDOWS : PYTHON_CANDIDATES_UNIX;
+}
+
 const MIN_PYTHON = [3, 10];
 
 const GATE_SCRIPTS = {
@@ -57,7 +70,7 @@ function run(command, args, options = {}) {
  * @returns {[number, number] | null}
  */
 export function parsePythonVersion(output) {
-  const match = output.match(/(\d+)\.(\d+)/);
+  const match = output.match(/^Python\s+(\d+)\.(\d+)/im);
   if (!match) {
     return null;
   }
@@ -123,7 +136,7 @@ export async function resolveScriptsDir(_cwd) {
  * @returns {Promise<PythonInterpreter | null>}
  */
 export async function resolvePython() {
-  for (const candidate of PYTHON_CANDIDATES) {
+  for (const candidate of getPythonCandidates()) {
     try {
       const output = await readPythonVersion(candidate);
       const version = parsePythonVersion(output);

package/lib/slug-utils.js

@@ -0,0 +1,40 @@
+/** @typedef {string} DomainSlug */
+
+export const FEATURE_ID_PATTERN = /^\d{3}-[a-z0-9][a-z0-9-]*$/;
+
+/**
+ * @param {string} id
+ * @returns {boolean}
+ */
+export function isValidFeatureId(id) {
+  return FEATURE_ID_PATTERN.test(id);
+}
+
+/**
+ * @param {string} name
+ * @returns {DomainSlug}
+ */
+export function slugifyDomain(name) {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 48);
+}
+
+const DOMAIN_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+
+/**
+ * @param {string} raw
+ * @returns {DomainSlug}
+ */
+export function assertSafeDomainSlug(raw) {
+  if (/[/\\]|\.\./.test(raw)) {
+    throw new Error(`Invalid domain slug: ${raw}`);
+  }
+  const slug = slugifyDomain(raw);
+  if (!slug || !DOMAIN_SLUG_PATTERN.test(slug)) {
+    throw new Error(`Invalid domain slug: ${raw}`);
+  }
+  return slug;
+}

package/lib/specs-utils.js

@@ -2,6 +2,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 
 import { readFileSafe } from "./fs-utils.js";
+import { isValidFeatureId } from "./slug-utils.js";
 
 const FEATURES_DIR = ".specs/features";
 
@@ -15,7 +16,7 @@ export async function listFeatureIds(cwd) {
   try {
     const entries = await fs.readdir(featuresRoot, { withFileTypes: true });
     return entries
-      .filter((entry) => entry.isDirectory())
+      .filter((entry) => entry.isDirectory() && isValidFeatureId(entry.name))
       .map((entry) => entry.name)
       .sort();
   } catch (err) {
@@ -26,6 +27,38 @@ export async function listFeatureIds(cwd) {
   }
 }
 
+/**
+ * @param {string} trimmed
+ * @param {string} cwd
+ * @returns {Promise<string>}
+ */
+async function resolveFeatureIdFromPath(trimmed, cwd) {
+  const asPath = path.resolve(cwd, trimmed);
+  const featuresRoot = path.resolve(cwd, FEATURES_DIR);
+  const relative = path.relative(featuresRoot, asPath);
+
+  if (relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new Error(`No such feature or path: ${trimmed}`);
+  }
+
+  const featureId = relative.split(path.sep)[0];
+  if (!isValidFeatureId(featureId)) {
+    throw new Error(`No such feature or path: ${trimmed}`);
+  }
+
+  const named = path.join(featuresRoot, featureId);
+  try {
+    const stat = await fs.stat(named);
+    if (stat.isDirectory()) {
+      return featureId;
+    }
+  } catch {
+    // fall through
+  }
+
+  throw new Error(`No such feature or path: ${trimmed}`);
+}
+
 /**
  * @param {string | undefined} raw
  * @param {string} cwd
@@ -34,13 +67,13 @@ export async function listFeatureIds(cwd) {
 export async function resolveFeatureId(raw, cwd) {
   if (raw?.trim()) {
     const trimmed = raw.trim();
-    const asPath = path.resolve(cwd, trimmed);
 
     if (trimmed.endsWith(".md") || trimmed.includes("/") || trimmed.includes("\\")) {
-      const relative = path.relative(path.join(cwd, FEATURES_DIR), asPath);
-      if (!relative.startsWith("..") && !path.isAbsolute(relative)) {
-        return relative.split(path.sep)[0];
-      }
+      return resolveFeatureIdFromPath(trimmed, cwd);
+    }
+
+    if (!isValidFeatureId(trimmed)) {
+      throw new Error(`Invalid feature id: ${trimmed} (expected NNN-slug)`);
     }
 
     const named = path.join(cwd, FEATURES_DIR, trimmed);
@@ -58,6 +91,9 @@ export async function resolveFeatureId(raw, cwd) {
 
   const active = await readActiveFeatureFromState(cwd);
   if (active && active !== "—") {
+    if (!isValidFeatureId(active)) {
+      throw new Error(`Invalid active feature in STATE.md: ${active}`);
+    }
     return active;
   }
 
@@ -108,6 +144,9 @@ export async function readActiveFeatureFromState(cwd) {
  * @returns {string}
  */
 export function featureDir(featureId, cwd) {
+  if (!isValidFeatureId(featureId)) {
+    throw new Error(`Invalid feature id: ${featureId} (expected NNN-slug)`);
+  }
   return path.join(cwd, FEATURES_DIR, featureId);
 }
 
@@ -118,6 +157,5 @@ export function featureDir(featureId, cwd) {
  * @returns {Promise<string>}
  */
 export async function readFeatureArtifact(featureId, cwd, filename) {
-  const filePath = path.join(featureDir(featureId, cwd), filename);
-  return readFileSafe(filePath);
+  return readFileSafe(path.join(featureDir(featureId, cwd), filename));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luizsantiago/spec-guardrails",
-  "version": "3.1.8",
+  "version": "3.1.10",
   "description": "Keep AI coding agents honest — specify the work, prove each step, verify independently. Process mode (Node) for flexibility; Brakes mode (Node + Python) for structural gates and a Guarantees matrix. Progressive loading, independent verify — any AI agent.",
   "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_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: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/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:gates": "node test/run-gate-tests.mjs",
     "prepublishOnly": "npm test"
   },

package/scripts/_common.py

@@ -96,6 +96,8 @@ class Report:
 
 FEATURES_DIR = Path(".specs/features")
 
+FEATURE_ID_PATTERN = re.compile(r"^\d{3}-[a-z0-9][a-z0-9-]*$")
+
 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,
@@ -215,6 +217,22 @@ def _fail_usage(gate: str, target: str, message: str) -> None:
     sys.exit(EXIT_USAGE)
 
 
+def is_valid_feature_id(feature_id: str) -> bool:
+    return bool(FEATURE_ID_PATTERN.match(feature_id))
+
+
+def _feature_dir_under_root(feature_dir: Path, root: Path) -> bool:
+    features_root = (root / FEATURES_DIR).resolve()
+    try:
+        resolved = feature_dir.resolve()
+        relative = resolved.relative_to(features_root)
+    except ValueError:
+        return False
+    if not relative.parts:
+        return False
+    return is_valid_feature_id(relative.parts[0])
+
+
 def list_features(root: Path = Path(".")) -> list[Path]:
     """Return every feature directory under `.specs/features`, sorted by name."""
 
@@ -223,7 +241,11 @@ def list_features(root: Path = Path(".")) -> list[Path]:
     if not base.is_dir():
         return []
 
-    return sorted(path for path in base.iterdir() if path.is_dir())
+    return sorted(
+        path
+        for path in base.iterdir()
+        if path.is_dir() and is_valid_feature_id(path.name)
+    )
 
 
 def resolve_feature_dir(
@@ -231,19 +253,38 @@ def resolve_feature_dir(
 ) -> 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.
+    Accepts `.specs/features/001-auth/spec.md`, `.specs/features/001-auth`,
+    `001-auth`, or nothing at all when the project has exactly one feature.
     """
 
     if raw:
+        if raw in (".", "..") or ".." in Path(raw).parts:
+            _fail_usage(
+                gate,
+                raw,
+                f"invalid feature id: {raw} (expected NNN-slug)",
+            )
+
         candidate = Path(raw).expanduser()
 
         if candidate.is_file():
-            return candidate.parent
+            feature_dir = candidate.parent
+            if not _feature_dir_under_root(feature_dir, root):
+                _fail_usage(gate, raw, f"no such feature or path: {raw}")
+            return feature_dir
 
         if candidate.is_dir():
+            if not _feature_dir_under_root(candidate, root):
+                _fail_usage(gate, raw, f"no such feature or path: {raw}")
             return candidate
 
+        if not is_valid_feature_id(raw):
+            _fail_usage(
+                gate,
+                raw,
+                f"invalid feature id: {raw} (expected NNN-slug)",
+            )
+
         named = root / FEATURES_DIR / raw
         if named.is_dir():
             return named

package/scripts/validate_quick.py

@@ -22,7 +22,7 @@ import re
 import sys
 from pathlib import Path
 
-from _common import Report, visible_markdown
+from _common import Report, is_valid_feature_id, visible_markdown
 
 GATE = "validate-quick"
 QUICK_DIR = Path(".specs/quick")
@@ -43,38 +43,65 @@ EVIDENCE_LINE = re.compile(
 )
 
 
+def _fail_usage(message: str, target: str = ".") -> None:
+    print(f"[{GATE}] USAGE - {message}", file=sys.stderr)
+    raise SystemExit(2)
+
+
+def _quick_dir_under_root(quick_dir: Path, root: Path) -> bool:
+    quick_root = (root / QUICK_DIR).resolve()
+    try:
+        resolved = quick_dir.resolve()
+        relative = resolved.relative_to(quick_root)
+    except ValueError:
+        return False
+    if not relative.parts:
+        return False
+    return is_valid_feature_id(relative.parts[0])
+
+
 def resolve_quick_dir(raw: str | None, root: Path = Path(".")) -> Path:
     if raw:
+        if raw in (".", "..") or ".." in Path(raw).parts:
+            _fail_usage(f"invalid quick id: {raw} (expected NNN-slug)", raw)
+
         candidate = Path(raw).expanduser()
+
+        if candidate.is_file():
+            quick_dir = candidate.parent
+            if not _quick_dir_under_root(quick_dir, root):
+                _fail_usage(f"no such quick folder: {raw}", raw)
+            return quick_dir
+
         if candidate.is_dir():
+            if not _quick_dir_under_root(candidate, root):
+                _fail_usage(f"no such quick folder: {raw}", raw)
             return candidate
+
+        if not is_valid_feature_id(raw):
+            _fail_usage(f"invalid quick id: {raw} (expected NNN-slug)", raw)
+
         named = root / QUICK_DIR / raw
         if named.is_dir():
             return named
-        print(f"[{GATE}] USAGE - no such quick folder: {raw}", file=sys.stderr)
-        raise SystemExit(2)
+
+        _fail_usage(f"no such quick folder: {raw}", raw)
 
     base = root / QUICK_DIR
     if not base.is_dir():
-        print(
-            f"[{GATE}] USAGE - {base} missing — create .specs/quick/NNN-slug/ first",
-            file=sys.stderr,
-        )
-        raise SystemExit(2)
+        _fail_usage(f"{base} missing — create .specs/quick/NNN-slug/ first", str(base))
 
-    folders = sorted(p for p in base.iterdir() if p.is_dir())
+    folders = sorted(
+        p for p in base.iterdir() if p.is_dir() and is_valid_feature_id(p.name)
+    )
     if len(folders) == 1:
         return folders[0]
     if not folders:
-        print(f"[{GATE}] USAGE - no quick folders under {base}", file=sys.stderr)
-        raise SystemExit(2)
+        _fail_usage(f"no quick folders under {base}", str(base))
 
     listed = "\n".join(f"            {p.name}" for p in folders)
-    print(
-        f"[{GATE}] USAGE - {len(folders)} quick folders — name one:\n{listed}",
-        file=sys.stderr,
-    )
-    raise SystemExit(2)
+    _fail_usage(f"{len(folders)} quick folders — name one:\n{listed}", str(base))
+    raise AssertionError("unreachable")
 
 
 def field_map(text: str) -> dict[str, str]:

package/skills/agent-architecture.md

@@ -80,7 +80,7 @@ EXPLORE (optional) → SPECIFY → DISCUSS (conditional) → DESIGN (optional)
 | **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` |
+| **Quick** | Alternative | `references/quick-mode.md` | — | `check_commit.py`, `validate_quick.py` |
 | **Context** | Always | `references/context-limits.md` | — | — |
 | **Sub-agents** | When batched | `references/sub-agents.md` | `task-graph-engineering.md` | — |
 | **Lessons** | On FAIL | `references/lessons.md` | — | `lessons.py` |
@@ -104,7 +104,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; gate: `validate-quick` |
+| **Quick** | ≤3 files, no design decisions, no new dependencies | `references/quick-mode.md` — describe, implement, verify, commit; gates: `check_commit.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 |
@@ -114,7 +114,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 only `check_commit.py` as a structural 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` 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/GETTING_STARTED.md

@@ -20,7 +20,7 @@ You installed the **Spec Guardrails**. You do **not** need to memorize CLI comma
 
 ## Agent commands (chat — not terminal)
 
-Type these in **chat** in your agent environment. They load phase procedures from the installed skills tree (e.g. `.cursor/skills/references/`). In **Brakes mode**, the agent runs Python gates for you.
+Type these in **chat** in your agent environment. They load phase procedures from the installed skills tree (e.g. `.cursor/skills/references/`, `.github/skills/references/`, `.codex/skills/references/` — use the tree your agent loads). In **Brakes mode**, the agent runs Python gates for you.
 
 | Command | When |
 | --- | --- |
@@ -55,7 +55,8 @@ Everything else (`loop-plan`, `validate-tasks`, `check-commit`, …) is normally
 
 | Path | Purpose |
 | --- | --- |
-| `.cursor/skills/agent-architecture.md` | Hub — phase map |
+| `*/skills/agent-architecture.md` | Hub — phase map (`.cursor/`, `.claude/`, `.github/`, `.codex/`) |
+| Root `AGENTS.md` | Open-standard entry |
 | `.specs/STATE.md` | Where you left off |
 | `.specs/features/` | One folder per feature |
 | `.specs/guardrails/scripts/` | Automatic gates |