@luizsantiago/spec-guardrails 3.0.1 → 3.1.2

package/README.md

@@ -7,7 +7,7 @@
 
 **Token-efficient by design:** the agent loads **one phase guide per turn** (~9k est. tokens on Specify) instead of dumping the full skill library (~31k). Measured savings: **~72%** on planning, **~86%** on Execute vs a naive full reload ([details below](#token-cost)).
 
-npm: [`@luizsantiago/spec-guardrails`](https://www.npmjs.com/package/@luizsantiago/spec-guardrails) **3.0.x**
+npm: [`@luizsantiago/spec-guardrails`](https://www.npmjs.com/package/@luizsantiago/spec-guardrails) **3.1.x**
 
 ---
 
@@ -122,6 +122,8 @@ Scripts in `.specs/guardrails/scripts/`. **Exit ≠ 0 → stop and fix.**
 | Before approving spec | `validate-spec` | Incomplete or untestable spec |
 | Before approving tasks | `analyze-artifacts` | Spec ↔ tasks drift |
 | Before approving tasks | `validate-tasks` | Bad tasks; missing graph when 3+ tasks |
+| After tasks / with validation | `validate-traceability` | REQ missing from tasks or coverage lines |
+| End of `/quick` | `validate-quick` | Incomplete Quick TASK/SUMMARY; >3 files; sensitive paths |
 | Each `/loop` wave | `loop-plan` | Blocked dependencies; shows parallel groups |
 | Each commit | `check-commit` | Non-Conventional commit message |
 | Before “done” | `validate-state` | Fake PASS without test evidence |
@@ -141,6 +143,7 @@ Full reference: **[Gates](docs/guide/gates.md)** · [Gates and guarantees](docs/
 | [Concepts](docs/guide/concepts.md) | Spec-driven + guardrails + loop + graph |
 | [Skills and hub](docs/guide/skills-and-hub.md) | What each skill file does |
 | [Gates](docs/guide/gates.md) | How each gate works |
+| [Platform parity](docs/guide/Platform-parity.md) | Cursor vs Claude Code |
 | [FAQ](docs/guide/FAQ.md) | Common questions |
 | [Changelog](docs/CHANGELOG.md) | Full version history |
 
@@ -156,6 +159,7 @@ npx @luizsantiago/spec-guardrails install
 
 | Version | What you gain |
 | --- | --- |
+| **3.1.x** | Doctor STATE fix; `validate-traceability` / `validate-quick`; `classify-change` / `feature-status`; Claude `CLAUDE.md` |
 | **3.0.x** | Final name Spec Guardrails; `.specs/guardrails/`; no dual-path ([Migration](docs/guide/Migration.md)) |
 | **2.2.x** | Seatbelt-era paths & markers; `doctor` Execute hints; docs split from README |
 | **2.1.x** | `loop-plan` + parallel `/loop` waves |

package/index.js

@@ -4,10 +4,12 @@ import path from "node:path";
 
 import { archiveFeature } from "./lib/archive.js";
 import { projectInit } from "./lib/brownfield.js";
+import { classifyChange, formatClassifyChange } from "./lib/classify-change.js";
 import { PACKAGE_VERSION, CLI_NAME } from "./lib/constants.js";
 import { phaseContext } from "./lib/config.js";
 import { doctor } from "./lib/doctor.js";
 import { featureInit } from "./lib/feature.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";
 import {
@@ -42,6 +44,10 @@ 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)
+    [--json]                         Machine-readable output
+  feature-status [feature]           Artifact checklist + next step for a feature
+    [--json]                         Machine-readable output
   phase-context <phase>              Print .specs/config.yaml context + rules for a phase
   doctor [path]                      Audit guardrails readiness (score + next actions)
     [--json]                         Machine-readable output
@@ -51,6 +57,8 @@ Commands:
   validate-tasks [tasks.md|feature]  Granularity gate for a task breakdown
   loop-plan [tasks.md|feature]       Next Execute wave — parallel groups + sub-agent hints
     [--json]                         Machine-readable plan for agents
+  validate-traceability [feature]    REQ → tasks → validation coverage chain
+  validate-quick [quick-folder]      Quick-mode TASK.md / SUMMARY.md structural gate
   validate-state [feature]           Completion gate before declaring a feature done
   check-commit --message "<msg>"     Conventional Commits gate
   lessons <add|list|penalize|prune|status>  Lessons engine
@@ -313,8 +321,59 @@ if (command === "--version" || command === "-v" || command === "version") {
     console.error(`❌ ${err.message}`);
     process.exit(1);
   }
-} else if (AUX_COMMANDS.includes(command)) {
+} else if (command === "classify-change") {
+  try {
+    let json = false;
+    const positional = [];
+    for (const arg of args) {
+      if (arg === "--json") {
+        json = true;
+      } else {
+        positional.push(arg);
+      }
+    }
+    if (positional.length === 0) {
+      throw new Error(
+        'Description or files required. Example: classify-change "fix theme toggle" src/hooks/useTheme.ts',
+      );
+    }
+    const files = positional.filter((item) => /[\\/]|\.[a-z0-9]+$/i.test(item));
+    const descriptionParts = positional.filter((item) => !files.includes(item));
+    const result = classifyChange({
+      description: descriptionParts.join(" "),
+      files,
+    });
+    if (json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      process.stdout.write(formatClassifyChange(result));
+    }
+  } catch (err) {
+    console.error(`❌ ${err.message}`);
+    process.exit(1);
+  }
+} else if (command === "feature-status") {
   try {
+    let json = false;
+    const positional = [];
+    for (const arg of args) {
+      if (arg === "--json") {
+        json = true;
+      } else {
+        positional.push(arg);
+      }
+    }
+    const status = await featureStatus(positional[0]);
+    if (json) {
+      console.log(JSON.stringify(status, null, 2));
+    } else {
+      process.stdout.write(formatFeatureStatus(status));
+    }
+  } catch (err) {
+    console.error(`❌ ${err.message}`);
+    process.exit(1);
+  }
+} else if (AUX_COMMANDS.includes(command)) {  try {
     const code = await runGuardrailsScript(command, args);
     process.exit(code);
   } catch (err) {

package/lib/archive.js

@@ -154,6 +154,16 @@ export async function archiveFeature(featureArg, options = {}) {
       );
     }
 
+    const traceCode = await runGate("validate-traceability", [featureId], {
+      cwd,
+      stdio: "pipe",
+    });
+    if (traceCode !== 0) {
+      throw new Error(
+        `validate-traceability failed for ${featureId}. Fix REQ coverage before archive.`,
+      );
+    }
+
     const gateCode = await runGate("validate-state", [featureId], {
       cwd,
       stdio: "pipe",

package/lib/classify-change.js

@@ -0,0 +1,127 @@
+/**
+ * Heuristic complexity classifier (no LLM) — mirrors the hub Complexity Router.
+ */
+
+const COMPLEX_SIGNALS = [
+  /\bauth(entication|orization)?\b/i,
+  /\bpayment|billing|checkout|stripe\b/i,
+  /\bmigration|schema\b/i,
+  /\binfra(structure)?|kubernetes|terraform\b/i,
+  /\barchitecture|redesign\b/i,
+  /\bssrf|upload|pii|secret|oauth\b/i,
+  /\bapi\s+gateway|multi-tenant\b/i,
+];
+
+const MEDIUM_SIGNALS = [
+  /\bfeature\b/i,
+  /\bnew\s+(endpoint|page|screen|module|service)\b/i,
+  /\brefactor\b/i,
+  /\bintegration\b/i,
+];
+
+const DEPENDENCY_SIGNALS = [
+  /\bnew\s+dependenc/i,
+  /\bnpm\s+install\b/i,
+  /\bpip\s+install\b/i,
+  /\badd\s+package\b/i,
+];
+
+/**
+ * @param {{ description?: string, files?: string[] }} input
+ * @returns {{
+ *   tier: "quick" | "simple" | "medium" | "complex",
+ *   reasons: string[],
+ *   next: string,
+ *   fileCount: number,
+ * }}
+ */
+export function classifyChange(input = {}) {
+  const description = (input.description ?? "").trim();
+  const files = (input.files ?? []).map((f) => f.trim()).filter(Boolean);
+  const haystack = [description, ...files].join("\n");
+  const reasons = [];
+  const fileCount = files.length;
+
+  const hasComplex = COMPLEX_SIGNALS.some((re) => re.test(haystack));
+  const hasMedium = MEDIUM_SIGNALS.some((re) => re.test(haystack));
+  const hasNewDep = DEPENDENCY_SIGNALS.some((re) => re.test(haystack));
+
+  if (hasComplex) {
+    reasons.push("sensitive surface or architecture signal in description/paths");
+  }
+  if (hasNewDep) {
+    reasons.push("new dependency signal");
+  }
+  if (fileCount > 3) {
+    reasons.push(`${fileCount} files listed (Quick max is 3)`);
+  }
+  if (fileCount > 0 && fileCount <= 3) {
+    reasons.push(`${fileCount} file(s) listed`);
+  }
+  if (!description && fileCount === 0) {
+    reasons.push("no description or files — defaulting to medium");
+  }
+
+  /** @type {"quick" | "simple" | "medium" | "complex"} */
+  let tier = "medium";
+
+  if (hasComplex) {
+    tier = "complex";
+  } else if (
+    !hasNewDep &&
+    fileCount > 0 &&
+    fileCount <= 3 &&
+    description.length > 0 &&
+    !hasMedium
+  ) {
+    tier = "quick";
+    reasons.push("≤3 files, no sensitive/architecture signals");
+  } else if (
+    !hasNewDep &&
+    (fileCount === 0 || fileCount <= 5) &&
+    !hasMedium &&
+    description.length > 0
+  ) {
+    tier = "simple";
+    reasons.push("localized change without feature/architecture signals");
+  } else if (hasMedium || hasNewDep || fileCount > 5) {
+    tier = "medium";
+    if (hasMedium) {
+      reasons.push("feature / module signal");
+    }
+  }
+
+  if (reasons.length === 0) {
+    reasons.push("default medium tier");
+  }
+
+  const nextByTier = {
+    quick: 'Use /quick (references/quick-mode.md), then validate-quick',
+    simple: 'feature-init → /specify → /loop → /verify',
+    medium: 'feature-init → /specify → /tasks → /loop → /verify → /archive',
+    complex:
+      'feature-init → full pipeline (+ /discuss, /plan; optional AppSec/QA on verify)',
+  };
+
+  return {
+    tier,
+    reasons,
+    next: nextByTier[tier],
+    fileCount,
+  };
+}
+
+/**
+ * @param {{ tier: string, reasons: string[], next: string, fileCount: number }} result
+ * @returns {string}
+ */
+export function formatClassifyChange(result) {
+  const lines = [
+    `Tier: ${result.tier}`,
+    `Files considered: ${result.fileCount}`,
+    "Reasons:",
+    ...result.reasons.map((r) => `  - ${r}`),
+    `Next: ${result.next}`,
+  ];
+  return `${lines.join("\n")}\n`;
+}

package/lib/claude-md.js

@@ -0,0 +1,103 @@
+import path from "node:path";
+
+import {
+  CURSORRULES_MARKER_BEGIN,
+  CURSORRULES_MARKER_END,
+  LEGACY_CURSORRULES_MARKER_PAIRS,
+} from "./constants.js";
+import {
+  appendFileSafe,
+  readFileSafe,
+  writeFileSafe,
+} from "./fs-utils.js";
+
+export const CLAUDE_MD_MARKER_BEGIN = CURSORRULES_MARKER_BEGIN;
+export const CLAUDE_MD_MARKER_END = CURSORRULES_MARKER_END;
+
+export const CLAUDE_MD_BLOCK = `${CLAUDE_MD_MARKER_BEGIN}
+# Execution Contract (Spec Guardrails)
+
+When planning architecture, specs, or multi-step features, read the hub first:
+
+- \`.claude/skills/agent-architecture.md\` — SDD hub: contract, phases, gates, complexity router
+- \`.claude/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)
+- \`.claude/skills/task-graph-engineering.md\` — task DAG, parallelism, verify topology
+- \`.claude/skills/engineering-standards.md\` — secure coding, code quality, artifact language
+- \`.claude/skills/security-review.md\` — security checklist for /verify
+- Sister skills (\`appsec\`, \`qa-strategy\`, \`code-simplify\`, \`ship-ready\`, \`git-handoff\`) — load **one conditional** at a time
+
+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\`.
+- Full CLI: \`npx @luizsantiago/spec-guardrails --help\`
+- Onboarding: \`.specs/GETTING_STARTED.md\`
+
+All project artifacts are written in English.
+Persistent state: \`.specs/STATE.md\`, \`.specs/lessons.json\`, \`.specs/LESSONS.md\`.
+
+Cursor users also get \`.cursorrules\` + \`.cursor/rules/engineering-baseline.mdc\` — same contract, different entrypoint. See \`docs/guide/Platform-parity.md\` in the package repo.
+${CLAUDE_MD_MARKER_END}
+`;
+
+const MARKER_PAIRS = [
+  [CLAUDE_MD_MARKER_BEGIN, CLAUDE_MD_MARKER_END],
+  ...LEGACY_CURSORRULES_MARKER_PAIRS,
+];
+
+/**
+ * @param {string} content
+ */
+function locateBlock(content) {
+  for (const [begin, endMarker] of MARKER_PAIRS) {
+    const start = content.indexOf(begin);
+    const end = content.indexOf(endMarker);
+    if (start !== -1 && end !== -1 && end >= start) {
+      return { start, end, endMarker };
+    }
+  }
+  return null;
+}
+
+/**
+ * Install or refresh `.claude/CLAUDE.md` with the Spec Guardrails contract.
+ *
+ * @param {string} cwd
+ */
+export async function injectClaudeMd(cwd) {
+  const target = path.join(cwd, ".claude", "CLAUDE.md");
+  const expected = CLAUDE_MD_BLOCK.trim();
+
+  try {
+    const existing = await readFileSafe(target);
+    const located = locateBlock(existing);
+    if (located) {
+      const current = existing.slice(
+        located.start,
+        located.end + located.endMarker.length,
+      );
+      if (current.trim() === expected) {
+        return { created: false, updated: false };
+      }
+      const before = existing.slice(0, located.start);
+      const after = existing.slice(located.end + located.endMarker.length);
+      const replaced = `${before}${expected}\n${after.replace(/^\n+/, "")}`;
+      await writeFileSafe(
+        target,
+        replaced.endsWith("\n") ? replaced : `${replaced}\n`,
+      );
+      return { created: false, updated: true };
+    }
+
+    const separator = existing.endsWith("\n") ? "\n" : "\n\n";
+    await appendFileSafe(target, `${separator}${CLAUDE_MD_BLOCK}\n`);
+    return { created: false, updated: true };
+  } catch (err) {
+    if (err.code !== "ENOENT") {
+      throw err;
+    }
+  }
+
+  await writeFileSafe(target, `${CLAUDE_MD_BLOCK}\n`);
+  return { created: true, updated: false };
+}

package/lib/constants.js

@@ -97,6 +97,8 @@ export const SCRIPT_ASSETS = [
   { file: "validate_spec.py", remotePath: "scripts/validate_spec.py" },
   { file: "validate_tasks.py", remotePath: "scripts/validate_tasks.py" },
   { file: "validate_state.py", remotePath: "scripts/validate_state.py" },
+  { file: "validate_traceability.py", remotePath: "scripts/validate_traceability.py" },
+  { file: "validate_quick.py", remotePath: "scripts/validate_quick.py" },
   { file: "analyze_artifacts.py", remotePath: "scripts/analyze_artifacts.py" },
   { file: "check_commit.py", remotePath: "scripts/check_commit.py" },
   { file: "lessons.py", remotePath: "scripts/lessons.py" },

package/lib/doctor.js

@@ -4,9 +4,9 @@ import path from "node:path";
 import { promisify } from "node:util";
 
 import { NPX, SKILL_DIRS } from "./constants.js";
-import { resolveScriptsDir } from "./gates.js";
+import { resolvePython, resolveScriptsDir } from "./gates.js";
 import { readFileSafe } from "./fs-utils.js";
-import { listFeatureIds } from "./specs-utils.js";
+import { listFeatureIds, readActiveFeatureFromState } from "./specs-utils.js";
 
 const execFileAsync = promisify(execFile);
 
@@ -40,44 +40,17 @@ async function pathExists(cwd, relativePath) {
  * @returns {Promise<boolean>}
  */
 async function pythonAvailable() {
-  for (const bin of ["python3", "python"]) {
-    try {
-      const { stdout } = await execFileAsync(bin, ["--version"]);
-      const match = stdout.match(/(\d+)\.(\d+)/);
-      if (!match) {
-        continue;
-      }
-      const major = Number(match[1]);
-      const minor = Number(match[2]);
-      if (major > 3 || (major === 3 && minor >= 10)) {
-        return true;
-      }
-    } catch {
-      // try next binary
-    }
-  }
-  return false;
+  return (await resolvePython()) !== null;
 }
 
 /**
+ * Prefer canonical STATE `- Feature:`; also accept legacy `- **Active feature**:`.
+ *
  * @param {string} cwd
  * @returns {Promise<string | null>}
  */
 async function readActiveFeature(cwd) {
-  try {
-    const state = await readFileSafe(path.join(cwd, ".specs/STATE.md"));
-    const match = state.match(/^\s*[-*]\s*\*\*Active feature\*\*:\s*(.+)$/im);
-    if (!match) {
-      return null;
-    }
-    const value = match[1].trim();
-    if (!value || /^none|idle|—|-$/i.test(value)) {
-      return null;
-    }
-    return value.replace(/^`|`$/g, "");
-  } catch {
-    return null;
-  }
+  return readActiveFeatureFromState(cwd);
 }
 
 /**
@@ -192,12 +165,15 @@ export async function runDoctorChecks(cwd) {
   if (gatesPresent && pythonOk) {
     try {
       const script = path.join(cwd, scriptsDir, "check_commit.py");
-      await execFileAsync("python3", [
-        script,
-        "--message",
-        "chore(guardrails): doctor smoke test",
-      ], { cwd });
-      gateSmoke = true;
+      const python = await resolvePython();
+      if (python) {
+        await execFileAsync(python, [
+          script,
+          "--message",
+          "chore(guardrails): doctor smoke test",
+        ], { cwd });
+        gateSmoke = true;
+      }
     } catch {
       gateSmoke = false;
     }
@@ -309,12 +285,26 @@ export async function doctor(cwd, options = {}) {
   const suggestions = topDoctorSuggestions(checks);
   const activeFeature = await readActiveFeature(cwd);
   const executeHint = await resolveExecuteHint(cwd, activeFeature);
+  const pythonCheck = checks.find((check) => check.id === "python");
+  const pythonMissing = pythonCheck ? !pythonCheck.pass : false;
 
   if (options.json) {
     console.log(
-      JSON.stringify({ score, checks, suggestions, executeHint }, null, 2),
+      JSON.stringify(
+        { score, checks, suggestions, executeHint, pythonMissing },
+        null,
+        2,
+      ),
+    );
+    return { score, checks, suggestions, executeHint, pythonMissing };
+  }
+
+  if (pythonMissing) {
+    console.log(
+      "⚠ PYTHON MISSING — structural gates will not run automatically.\n" +
+        "  Install Python 3.10+ (python3 or python on PATH), then re-run doctor.\n" +
+        "  Until then the agent must perform the same checklists manually from skills/references/.\n",
     );
-    return { score, checks, suggestions, executeHint };
   }
 
   console.log(`Guardrails Ready: ${score}/100\n`);
@@ -339,5 +329,5 @@ export async function doctor(cwd, options = {}) {
     console.log(`\nExecute hint:\n  → ${executeHint}`);
   }
 
-  return { score, checks, suggestions, executeHint };
+  return { score, checks, suggestions, executeHint, pythonMissing };
 }

package/lib/feature-status.js

@@ -0,0 +1,160 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { NPX } from "./constants.js";
+import { resolveExecuteHint } from "./doctor.js";
+import { readFileSafe } from "./fs-utils.js";
+import {
+  featureDir,
+  readActiveFeatureFromState,
+  resolveFeatureId,
+} from "./specs-utils.js";
+
+/**
+ * @param {string} cwd
+ * @param {string} featureId
+ * @param {string} filename
+ * @returns {Promise<boolean>}
+ */
+async function artifactExists(cwd, featureId, filename) {
+  try {
+    await fs.access(path.join(featureDir(featureId, cwd), filename));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {string} tasksText
+ * @returns {{ total: number, complete: number, open: number }}
+ */
+function summarizeTasks(tasksText) {
+  const total = (tasksText.match(/^#{2,6}\s*T\d+/gim) ?? []).length;
+  const complete = (tasksText.match(/-\s*\[x\]\s*complete\b/gi) ?? []).length;
+  return {
+    total,
+    complete,
+    open: Math.max(0, total - complete),
+  };
+}
+
+/**
+ * @param {string} validationText
+ * @returns {string | null}
+ */
+function readVerdict(validationText) {
+  const match = validationText.match(
+    /^\s*[-*]?\s*\*{0,2}(?:verdict|result|status)\*{0,2}\s*:\s*\*{0,2}([A-Za-z ]+)/im,
+  );
+  return match ? match[1].trim().toUpperCase() : null;
+}
+
+/**
+ * @param {string} [featureArg]
+ * @param {{ cwd?: string }} [options]
+ */
+export async function featureStatus(featureArg, options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const featureId = await resolveFeatureId(
+    featureArg ?? (await readActiveFeatureFromState(cwd)) ?? undefined,
+    cwd,
+  );
+
+  const dir = featureDir(featureId, cwd);
+  try {
+    await fs.access(dir);
+  } catch {
+    throw new Error(`Feature directory not found: ${dir}`);
+  }
+
+  let phase = null;
+  let branch = null;
+  try {
+    const state = await readFileSafe(path.join(cwd, ".specs/STATE.md"));
+    phase = state.match(/^-\s*Phase:\s*(.+)$/m)?.[1]?.trim() ?? null;
+    branch = state.match(/^-\s*Branch:\s*(.+)$/m)?.[1]?.trim() ?? null;
+  } catch {
+    // STATE optional for status
+  }
+
+  const artifacts = {
+    spec: await artifactExists(cwd, featureId, "spec.md"),
+    tasks: await artifactExists(cwd, featureId, "tasks.md"),
+    design: await artifactExists(cwd, featureId, "design.md"),
+    validation: await artifactExists(cwd, featureId, "validation.md"),
+    taskGraph: await artifactExists(cwd, featureId, "task-graph.md"),
+  };
+
+  /** @type {{ total: number, complete: number, open: number } | null} */
+  let tasks = null;
+  if (artifacts.tasks) {
+    const text = await readFileSafe(path.join(dir, "tasks.md"));
+    tasks = summarizeTasks(text);
+  }
+
+  /** @type {string | null} */
+  let verdict = null;
+  if (artifacts.validation) {
+    const text = await readFileSafe(path.join(dir, "validation.md"));
+    verdict = readVerdict(text);
+  }
+
+  const executeHint = await resolveExecuteHint(cwd, featureId);
+
+  /** @type {string} */
+  let next;
+  if (!artifacts.spec) {
+    next = `${NPX(`validate-spec ${featureId}`)} — draft/approve spec.md first`;
+  } else if (!artifacts.tasks) {
+    next = `${NPX(`validate-spec ${featureId}`)} then /tasks`;
+  } else if (tasks && tasks.open > 0) {
+    next = executeHint ?? `${NPX(`loop-plan ${featureId}`)} — next Execute wave`;
+  } else if (!artifacts.validation || !verdict || !/^PASS/.test(verdict)) {
+    next =
+      executeHint ??
+      `${NPX(`validate-traceability ${featureId}`)} then ${NPX(`validate-state ${featureId}`)}`;
+  } else {
+    next = `${NPX(`archive-feature ${featureId}`)} — fold into domain memory`;
+  }
+
+  return {
+    featureId,
+    phase,
+    branch,
+    artifacts,
+    tasks,
+    verdict,
+    next,
+    executeHint,
+  };
+}
+
+/**
+ * @param {Awaited<ReturnType<typeof featureStatus>>} status
+ * @returns {string}
+ */
+export function formatFeatureStatus(status) {
+  const artifactLine = Object.entries(status.artifacts)
+    .map(([name, present]) => `${present ? "✓" : "✗"} ${name}`)
+    .join("  ");
+
+  const lines = [
+    `Feature: ${status.featureId}`,
+    `Phase: ${status.phase ?? "—"}`,
+    `Branch: ${status.branch ?? "—"}`,
+    `Artifacts: ${artifactLine}`,
+  ];
+
+  if (status.tasks) {
+    lines.push(
+      `Tasks: ${status.tasks.complete}/${status.tasks.total} complete (${status.tasks.open} open)`,
+    );
+  } else {
+    lines.push("Tasks: —");
+  }
+
+  lines.push(`Validation verdict: ${status.verdict ?? "—"}`);
+  lines.push(`Next: ${status.next}`);
+  return `${lines.join("\n")}\n`;
+}

package/lib/gates.js

@@ -11,6 +11,8 @@ const GATE_SCRIPTS = {
   "validate-spec": "validate_spec.py",
   "validate-tasks": "validate_tasks.py",
   "validate-state": "validate_state.py",
+  "validate-traceability": "validate_traceability.py",
+  "validate-quick": "validate_quick.py",
   "analyze-artifacts": "analyze_artifacts.py",
   "check-commit": "check_commit.py",
   lessons: "lessons.py",

package/lib/install.js

@@ -12,6 +12,7 @@ import {
   DISPLAY_NAME,
   resolveAssetOverride,
 } from "./constants.js";
+import { injectClaudeMd } from "./claude-md.js";
 import { injectCursorRules } from "./cursorrules.js";
 import { ensureDir, readFileSafe, writeFileIfMissing } from "./fs-utils.js";
 import { hasPython } from "./gates.js";
@@ -115,6 +116,7 @@ export async function install(options = {}) {
   }
 
   await injectCursorRules(cwd);
+  await injectClaudeMd(cwd);
 
   const gettingStartedCreated = await writeFileIfMissing(
     path.join(cwd, ".specs/GETTING_STARTED.md"),

package/lib/specs-utils.js

@@ -85,12 +85,18 @@ export async function readActiveFeatureFromState(cwd) {
 
   try {
     const content = await readFileSafe(statePath);
-    const match = content.match(/^-\s*Feature:\s*(.+)$/m);
+    // Canonical STATE_HEADER uses "- Feature:". Older fixtures used "- **Active feature**:".
+    const match =
+      content.match(/^-\s*Feature:\s*(.+)$/m) ??
+      content.match(/^\s*[-*]\s*\*\*Active feature\*\*:\s*(.+)$/im);
     if (!match) {
       return null;
     }
-    const value = match[1].trim();
-    return value === "—" ? null : value;
+    const value = match[1].trim().replace(/^`|`$/g, "");
+    if (!value || /^none|idle|—|-$/i.test(value)) {
+      return null;
+    }
+    return value;
   } catch {
     return null;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luizsantiago/spec-guardrails",
-  "version": "3.0.1",
+  "version": "3.1.2",
   "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": {
@@ -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: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:gates": "node test/run-gate-tests.mjs",
     "prepublishOnly": "npm test"
   },

package/scripts/validate_quick.py

@@ -0,0 +1,159 @@
+#!/usr/bin/env python3
+"""Structural gate for Quick-mode artifacts under `.specs/quick/`.
+
+    python3 validate_quick.py .specs/quick/001-theme-persist
+    python3 validate_quick.py 001-theme-persist
+
+Checks (markdown structure only):
+  * TASK.md present with Files / Approach / Verify fields
+  * Files list has 1–3 paths
+  * Sensitive paths (auth/payment/migration) → promote to specify
+  * SUMMARY.md present with Changed + Evidence (file:line or manual steps)
+
+Does not run validate-state / discrimination sensor / REQ coverage.
+
+Exit codes: 0 pass, 1 blocking issues, 2 usage error.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+from _common import Report, visible_markdown
+
+GATE = "validate-quick"
+QUICK_DIR = Path(".specs/quick")
+
+FIELD = re.compile(
+    r"^\s*[-*]?\s*\*{0,2}(?P<key>Files|Approach|Verify|Changed|Commit|Evidence)"
+    r"\*{0,2}\s*:\s*(?P<value>.+?)\s*$",
+    re.MULTILINE | re.IGNORECASE,
+)
+SENSITIVE = re.compile(
+    r"(?:^|/)(?:auth|oauth|payment|billing|migration|migrate)(?:/|$)|"
+    r"(?:^|/)(?:schema|secrets?)(?:/|$)",
+    re.IGNORECASE,
+)
+EVIDENCE_LINE = re.compile(
+    r"[\w./\\-]+\.[A-Za-z][A-Za-z0-9]{0,9}:\d{1,6}\b|manual\b|reload\b|steps?\b",
+    re.IGNORECASE,
+)
+
+
+def resolve_quick_dir(raw: str | None, root: Path = Path(".")) -> Path:
+    if raw:
+        candidate = Path(raw).expanduser()
+        if candidate.is_dir():
+            return candidate
+        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)
+
+    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)
+
+    folders = sorted(p for p in base.iterdir() if p.is_dir())
+    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)
+
+    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)
+
+
+def field_map(text: str) -> dict[str, str]:
+    found: dict[str, str] = {}
+    for match in FIELD.finditer(visible_markdown(text)):
+        key = match.group("key").strip().lower()
+        found[key] = match.group("value").strip()
+    return found
+
+
+def split_files(value: str) -> list[str]:
+    parts = re.split(r"[,;\n]+", value)
+    return [p.strip().strip("`") for p in parts if p.strip()]
+
+
+def build_report(quick_dir: Path) -> Report:
+    report = Report(gate=GATE, target=str(quick_dir))
+
+    task_path = quick_dir / "TASK.md"
+    summary_path = quick_dir / "SUMMARY.md"
+
+    if not task_path.is_file() or not task_path.read_text(encoding="utf-8").strip():
+        report.error("TASK.md missing or empty")
+        return report
+
+    task_fields = field_map(task_path.read_text(encoding="utf-8"))
+    for required in ("files", "approach", "verify"):
+        if required not in task_fields or not task_fields[required]:
+            report.error(f"TASK.md missing required field: {required.title()}")
+
+    files = split_files(task_fields.get("files", ""))
+    if files:
+        report.ok(f"{len(files)} file(s) listed")
+        if len(files) > 3:
+            report.error(
+                f"{len(files)} files listed — Quick max is 3; promote to /specify"
+            )
+        for path in files:
+            if SENSITIVE.search(path.replace("\\", "/")):
+                report.error(
+                    f"sensitive path '{path}' — promote to full pipeline + security-review"
+                )
+    elif "files" in task_fields:
+        report.error("Files field is empty")
+
+    if not summary_path.is_file() or not summary_path.read_text(encoding="utf-8").strip():
+        report.error("SUMMARY.md missing or empty")
+        return report
+
+    summary_fields = field_map(summary_path.read_text(encoding="utf-8"))
+    if "changed" not in summary_fields or not summary_fields["changed"]:
+        report.error("SUMMARY.md missing Changed field")
+    else:
+        report.ok("Changed field present")
+
+    evidence = summary_fields.get("evidence", "")
+    if not evidence:
+        report.error("SUMMARY.md missing Evidence field")
+    elif not EVIDENCE_LINE.search(evidence):
+        report.error(
+            "Evidence must cite file:line or explicit manual verification steps"
+        )
+    else:
+        report.ok("Evidence recorded")
+
+    return report
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Validate Quick-mode artifacts")
+    parser.add_argument(
+        "target",
+        nargs="?",
+        help="quick folder name or path under .specs/quick/",
+    )
+    args = parser.parse_args(argv)
+    quick_dir = resolve_quick_dir(args.target)
+    return build_report(quick_dir).emit()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/validate_traceability.py

@@ -0,0 +1,167 @@
+#!/usr/bin/env python3
+"""REQ → tasks → validation coverage chain (structural).
+
+Run after Tasks, and again when validation.md exists:
+
+    python3 validate_traceability.py auth
+    python3 validate_traceability.py .specs/features/003-chat-system
+
+Checks (markdown structure only — not that tests assert criteria):
+  * every spec requirement ID appears in at least one task Requirement field
+  * every task Requirement references a known spec requirement ID
+  * when validation.md exists: every spec REQ has test file:line on the same
+    coverage line (evidence pattern only)
+
+Does not require Verdict PASS, discrimination sensor, or open-gap checks —
+use validate-state for completion.
+
+Exit codes: 0 pass, 1 blocking issues, 2 usage error.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+from _common import (
+    Report,
+    requirement_ids,
+    resolve_feature_dir,
+    visible_markdown,
+)
+
+GATE = "validate-traceability"
+
+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")
+EVIDENCE = re.compile(r"[\w./\\-]+\.[A-Za-z][A-Za-z0-9]{0,9}:\d{1,6}\b")
+URL = re.compile(r"\b[a-z][a-z0-9+.-]*://\S+", re.IGNORECASE)
+TEST_EVIDENCE = re.compile(
+    r"(?:^|/)(?:tests?|__tests__|spec)(?:/|$)|[._-](?:test|spec)\.|test_[^/]+\.",
+    re.IGNORECASE,
+)
+
+
+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 find_test_evidence(text: str) -> list[str]:
+    visible = visible_markdown(text)
+    hits = EVIDENCE.findall(URL.sub(" ", visible))
+    return [hit for hit in hits if TEST_EVIDENCE.search(hit.replace("\\", "/"))]
+
+
+def requirement_evidence_gaps(spec_ids: list[str], validation: str) -> list[str]:
+    missing: list[str] = []
+    visible = visible_markdown(validation)
+    for requirement_id in spec_ids:
+        covered = False
+        for line in visible.splitlines():
+            if requirement_id not in line:
+                continue
+            if find_test_evidence(line):
+                covered = True
+                break
+        if not covered:
+            missing.append(requirement_id)
+    return missing
+
+
+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) -> 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")
+    validation = read_optional(feature_dir, "validation.md")
+
+    if not spec_text:
+        report.error("spec.md missing or empty — cannot check REQ traceability")
+        return report
+
+    spec_ids = requirement_ids(spec_text)
+    if not spec_ids:
+        report.error(
+            "no requirement headings found - use '### REQ-001: Title' (prefix-NNN)"
+        )
+        return report
+
+    report.ok(f"{len(spec_ids)} requirement ID(s) in spec.md")
+
+    if not tasks_text:
+        report.error("tasks.md missing or empty — every REQ needs a task Requirement")
+        return report
+
+    covered = task_requirement_ids(tasks_text)
+    report.ok(f"{len(covered)} requirement ID(s) referenced in tasks.md")
+
+    missing_tasks = [req for req in spec_ids if req not in covered]
+    if missing_tasks:
+        report.error(
+            "requirements without task coverage: " + ", ".join(missing_tasks)
+        )
+    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.ok("every task Requirement maps to a spec requirement")
+
+    if validation is None:
+        report.warn(
+            "validation.md missing — coverage evidence check skipped "
+            "(run again after /verify drafts validation.md)"
+        )
+        return report
+
+    gaps = requirement_evidence_gaps(spec_ids, validation)
+    if gaps:
+        for requirement_id in gaps:
+            report.error(
+                f"{requirement_id} has no test file:line on the same coverage line"
+            )
+    else:
+        report.ok("every spec requirement has test evidence on a coverage line")
+
+    return report
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Validate REQ → tasks → validation coverage chain"
+    )
+    parser.add_argument(
+        "feature",
+        nargs="?",
+        help="feature name, feature directory, or path to spec.md",
+    )
+    args = parser.parse_args(argv)
+
+    feature_dir = resolve_feature_dir(args.feature, GATE)
+    return build_report(feature_dir).emit()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/agent-architecture.md

@@ -101,7 +101,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 |
+| **Quick** | ≤3 files, no design decisions, no new dependencies | `references/quick-mode.md` — describe, implement, verify, commit; gate: `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 |

package/skills/references/quick-mode.md

@@ -57,7 +57,11 @@ Announce the switch — do not silently expand a quick task into a feature.
 Quick mode compresses ceremony, not carelessness — but it is **not** the full Verify gate:
 
 - Prove the change with a test or an explicit, documented manual check.
-- Record evidence in `SUMMARY.md` (`file:line` or the exact manual steps). That is a **process** requirement; `validate_state.py` does not run on Quick artifacts.
+- Record evidence in `SUMMARY.md` (`file:line` or the exact manual steps). Run the Quick structural gate:
+  ```bash
+  npx @luizsantiago/spec-guardrails validate-quick 001-theme-persist
+  ```
+  `validate_state.py` does **not** run on Quick artifacts — that gate is for full-pipeline features.
 - Blast radius still applies — local commit only; `git push` and deploy need an explicit go-ahead.
 - If any Quick guardrail is exceeded, stop and route to `specify.md` (see When NOT to Use).
 

package/templates/GETTING_STARTED.md

@@ -43,7 +43,9 @@ Type these in **Cursor or Claude Code**. They load phase procedures from `.curso
 | `install` | First time or upgrade |
 | `project-init` | Brownfield repo (optional) |
 | `doctor` | Install looks broken |
-| `validate-spec` / `validate-state` | Double-check gates manually |
+| `classify-change` / `feature-status` | Pick a tier or see next step |
+| `validate-spec` / `validate-traceability` / `validate-state` | Double-check feature gates |
+| `validate-quick` | Double-check a Quick TASK/SUMMARY |
 
 Everything else (`loop-plan`, `validate-tasks`, `check-commit`, …) is normally run **by the agent**.