@luizsantiago/spec-guardrails 3.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luiz Santiago
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,206 @@
+# Spec Guardrails
+
+[![npm version](https://img.shields.io/npm/v/@luizsantiago/spec-guardrails.svg)](https://www.npmjs.com/package/@luizsantiago/spec-guardrails)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**Guardrails for AI coding agents** — agree on the goal in writing, break work into provable steps, run automatic checks before calling anything “done”, and verify with a fresh context that did not write the code.
+
+**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**
+
+---
+
+## Install
+
+```bash
+npx @luizsantiago/spec-guardrails install
+```
+
+### What you need
+
+| Requirement | Role |
+| --- | --- |
+| **Node.js 18+** | Required — runs the CLI and `install` |
+| **Python 3.10+** | Recommended — runs automatic **gates** (`validate-spec`, `validate-tasks`, …). Without Python the agent still follows the same checklists manually |
+
+### What install does
+
+| Lands in your project | Purpose |
+| --- | --- |
+| `.cursor/skills/` + `.claude/skills/` | Hub, phase references, sister skills |
+| `.specs/guardrails/scripts/` | Python gate scripts |
+| `.specs/STATE.md`, `.specs/features/`, … | Project memory |
+| `.cursor/rules/engineering-baseline.mdc` | Always-on Cursor rule |
+
+Re-run `install` anytime to refresh skills; your `.specs/` decisions and `STATE.md` are kept.
+
+| Need | Command |
+| --- | --- |
+| First time / upgrade | `install` |
+| Existing codebase | `project-init` (optional) |
+| Something looks wrong | `doctor` |
+| Full CLI list | `--help` |
+
+---
+
+## Token cost
+
+Progressive loading is the main cost win: **one working set per turn**, not the entire playbook.
+
+| Profile | Est. tokens | When |
+| ---: | ---: | --- |
+| Naive full dump (don’t) | ~31k | Loading every skill + reference every message |
+| Specify turn | ~9k | `/specify` — hub + `specify.md` + standards |
+| Tasks turn | ~10k | `/tasks` — hub + `tasks.md` + task-graph skill |
+| Execute `/loop` (one wave) | ~4k | One implement wave (inline or parallel) |
+| Verify turn | ~6k | Independent reviewer stack |
+
+Savings vs full dump: **~72%** (Specify), **~86%** (Execute). Numbers from `lib/token-cost.js`; CI guardrails in `test/test_token_cost.test.js`. Order-of-magnitude only — not a billing API.
+
+More: [Token efficiency](docs/guide/Token-efficiency.md)
+
+---
+
+## How the pieces fit together
+
+Four ideas stack — full explanation: **[Concepts](docs/guide/concepts.md)**
+
+| Idea | What it is | What it does |
+| --- | --- | --- |
+| **Spec-driven** | Written plan before code | `spec.md` + `tasks.md`; evidence before “done” |
+| **Guardrails** | This package | Skills + Python gates that stop incomplete work |
+| **Loop** | Execute in waves | `loop-plan` picks the next jobs; sub-agents when files don’t overlap |
+| **Graph** | Parallel task map | `task-graph.md` — safe parallelism without file collisions |
+| **Memory** | Repo-local state | `.specs/` — specs, decisions, and handoff survive across chats |
+
+**You** approve specs and tasks. **The agent** runs gates and implements. **Gates** exit non-zero when paperwork or evidence is missing.
+
+Plain-language tour: [Home](docs/guide/Home.md) · [How it works](docs/guide/How-it-works.md) · [Quick start](docs/guide/Quick-start.md)
+
+---
+
+## Complexity tiers (how work flows)
+
+The hub **Complexity Router** picks how much ceremony a feature needs — Quick, Simple, Medium, Complex, or Parallel. It is **not** a separate product feature; it is how the agent decides which phases to run.
+
+| Tier | Typical scope | Path |
+| --- | --- | --- |
+| **Quick** | ≤3 files, no new deps | `/quick` → verify → commit |
+| **Simple** | Small localized change | `/specify` → `/loop` → `/verify` |
+| **Medium** | New feature, <10 tasks | `/specify` → `/tasks` → `/loop` → `/verify` → `/archive` |
+| **Complex** | APIs, architecture, infra | + `/discuss`, `/plan`, optional security/QA on verify |
+| **Parallel** | Splittable work | Above + `/task-graph` when 3+ tasks |
+
+Rules and examples: [Concepts → Complexity tiers](docs/guide/concepts.md#complexity-tiers--how-the-agent-chooses-depth)
+
+---
+
+## Hub and skills (summary)
+
+Install copies a **hub** (`agent-architecture.md`), **phase references** (`references/*.md`), and **sister skills** (security, task-graph, …). The agent loads **one phase file at a time**.
+
+| Load order | Layer | Role | Examples |
+| ---: | --- | --- | --- |
+| 1 | **Hub** | Contract, complexity router, gate schedule | `agent-architecture.md` |
+| 2 | **Reference** | One phase procedure per turn | `specify.md`, `implement.md`, `validate.md` |
+| 3 | **Sister** (optional) | Cross-cutting depth, on demand | `engineering-standards.md`, `task-graph-engineering.md` |
+| 4 | **Gate** | Automatic check at the boundary | `validate-spec`, `loop-plan`, `check-commit` |
+
+Conditional sisters (`appsec.md`, `qa-strategy.md`, …) load **one at a time** on Verify when risk warrants it.
+
+Full map: **[Skills and hub](docs/guide/skills-and-hub.md)**
+
+---
+
+## Gates (summary)
+
+Scripts in `.specs/guardrails/scripts/`. **Exit ≠ 0 → stop and fix.**
+
+| When | Gate | What it blocks |
+| --- | --- | --- |
+| 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 |
+| 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 |
+| After Verify FAIL | `lessons` | Ungrounded “lessons learned” |
+| After Verify PASS | `archive-feature` | (CLI) folds feature into domain memory |
+
+Full reference: **[Gates](docs/guide/gates.md)** · [Gates and guarantees](docs/guide/Gates-and-guarantees.md)
+
+---
+
+## Documentation
+
+| Doc | For |
+| --- | --- |
+| [Agent commands](docs/guide/agent-commands.md) | Every `/specify`, `/loop`, `/verify`, … — purpose, when, examples |
+| [Quick start](docs/guide/Quick-start.md) | First ten minutes |
+| [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 |
+| [FAQ](docs/guide/FAQ.md) | Common questions |
+| [Changelog](docs/CHANGELOG.md) | Full version history |
+
+Start after install: [Quick start](docs/guide/Quick-start.md) · [Agent commands](docs/guide/agent-commands.md)
+
+---
+
+## Upgrading
+
+```bash
+npx @luizsantiago/spec-guardrails install
+```
+
+| Version | What you gain |
+| --- | --- |
+| **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 |
+| **2.0.x** | Package rename → `@luizsantiago/spec-seatbelt` (superseded by 3.0) |
+| **1.1.x** | `project-init` for brownfield repos |
+| **0.9.x** | `archive-feature` + domain memory merge |
+
+Full history: [CHANGELOG](docs/CHANGELOG.md) · [Releases](https://github.com/luizssantiago92/spec-guardrails/releases) · [Stability policy](docs/guide/Stability-policy.md)
+
+Lineage: `agentic-harness` → `spec-seatbelt` → **`spec-guardrails` (final)**. Run `install` once after switching. See [Migration](docs/guide/Migration.md).
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) — tests, gate freeze policy, local `npm run guardrails -- install`.
+
+---
+
+## Credits
+
+Spec Guardrails adapts open ideas; we did not invent spec-driven phases, loop design, or task-graph rules.
+
+### Core lineage
+
+| Source | License | How we use it |
+| --- | --- | --- |
+| [tlc-spec-driven](https://github.com/tech-leads-club/agent-skills/tree/main/packages/skills-catalog/skills/(development)/tlc-spec-driven) | CC-BY-4.0 | Phase model, `.specs/` memory, gate lineage |
+| [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) | MIT | Discuss patterns, definition-of-done |
+| [graph-engineering](https://github.com/codejunkie99/graph-engineering) | MIT | Task-graph topology, stop rules, parallel merge |
+
+### Loop & ecosystem
+
+| Source | License | How we use it |
+| --- | --- | --- |
+| [loop-engineering](https://github.com/cobusgreyling/loop-engineering) | MIT | Operational loop patterns; `doctor` score metaphor |
+| [Addy Osmani — Loop engineering](https://addyosmani.com/blog/loop-engineering/) | — | Essay lineage |
+| [awesome-harness-engineering](https://github.com/ai-boost/awesome-harness-engineering) | CC0 | Ecosystem taxonomy |
+
+### Adjacent (not vendored)
+
+[DeepCode](https://github.com/HKUDS/DeepCode) · [RepoGraph](https://github.com/ozyyshr/RepoGraph)
+
+Extended attribution: [docs/guide/credits.md](docs/guide/credits.md)
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,335 @@
+#!/usr/bin/env node
+
+import path from "node:path";
+
+import { archiveFeature } from "./lib/archive.js";
+import { projectInit } from "./lib/brownfield.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 { GATE_COMMANDS, AUX_COMMANDS, runGate, runGuardrailsScript } from "./lib/gates.js";
+import { install } from "./lib/install.js";
+import {
+  initProjectConfig,
+  listPresets,
+  loadPresetText,
+} from "./lib/presets.js";
+
+const USAGE = `Usage: ${CLI_NAME} <command> [args]
+
+Commands:
+  install                            Install skills, references, gates and .specs/ memory
+    [--preset <name>]                Seed .specs/config.yaml from a built-in preset
+    [--force-config]                 Replace existing config.yaml when using --preset
+  init-config [--preset <name>]      Create .specs/config.yaml (default preset: default)
+    [--force]                        Replace existing config.yaml
+  preset list                        List built-in config presets
+  preset show <name>                 Print a preset YAML file
+  project-init                       Map an existing repo into .specs/ project memory (brownfield)
+    [--preset <name>]                Config preset (auto-detected when omitted)
+    [--domains a,b,c]                Explicit domain slugs (overrides auto-detect)
+    [--no-domains]                   Skip .specs/domains/ scaffolding
+    [--no-project]                   Skip PROJECT.md generation
+    [--force]                        Overwrite generated project/domain/config files
+    [--dry-run]                      Print scan results without writing files
+  feature-init "<description>"       Allocate NNN-slug feature, STATE, local branch (Tier 0)
+    [--no-branch]                    Skip git checkout -b
+    [--no-spec]                      Skip spec.md stub
+  archive-feature [feature]          Fold verified feature into ROADMAP + domain spec; reset STATE
+    [--domain <slug>]                Domain folder under .specs/domains/ (default: feature slug)
+    [--skip-verify]                  Skip validate-state (tests / recovery only)
+    [--no-roadmap]                   Skip ROADMAP update
+    [--no-domain]                    Skip domain spec merge
+    [--no-state]                     Skip STATE reset
+  phase-context <phase>              Print .specs/config.yaml context + rules for a phase
+  doctor [path]                      Audit guardrails readiness (score + next actions)
+    [--json]                         Machine-readable output
+    [--no-suggest]                   Hide per-check remediation hints
+  validate-spec [spec.md|feature]    Closure gate for a feature spec
+  analyze-artifacts [feature]        Cross-artifact consistency before task approval
+  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-state [feature]           Completion gate before declaring a feature done
+  check-commit --message "<msg>"     Conventional Commits gate
+  lessons <add|list|penalize|prune|status>  Lessons engine
+  --help                             Show this message
+  --version                          Print the package version
+`;
+
+const [, , command, ...args] = process.argv;
+
+if (command === "--version" || command === "-v" || command === "version") {
+  console.log(PACKAGE_VERSION);
+  process.exit(0);
+} else if (!command || command === "--help" || command === "-h" || command === "help") {
+  const out = command ? console.log : console.error;
+  out(USAGE);
+  process.exit(command ? 0 : 1);
+} else if (command === "install") {
+  try {
+    const installOptions = {};
+    for (let i = 0; i < args.length; i++) {
+      const arg = args[i];
+      if (arg === "--preset") {
+        installOptions.preset = args[++i];
+        if (!installOptions.preset) {
+          throw new Error("--preset requires a name. Run preset list.");
+        }
+      } else if (arg === "--force-config") {
+        installOptions.forceConfig = true;
+      } else {
+        throw new Error(`Unknown install flag: ${arg}`);
+      }
+    }
+
+    await install(installOptions);
+  } catch (err) {
+    console.error(`❌ ${err.message}`);
+    process.exit(1);
+  }
+} else if (command === "init-config") {
+  try {
+    let preset = "default";
+    let force = false;
+
+    for (let i = 0; i < args.length; i++) {
+      const arg = args[i];
+      if (arg === "--preset") {
+        preset = args[++i];
+        if (!preset) {
+          throw new Error("--preset requires a name. Run preset list.");
+        }
+      } else if (arg === "--force") {
+        force = true;
+      } else {
+        throw new Error(`Unknown init-config flag: ${arg}`);
+      }
+    }
+
+    const result = await initProjectConfig({ preset, force });
+    if (result.skipped) {
+      console.log(`ℹ️  ${result.path} already exists — kept your file (use --force to replace)`);
+    } else if (result.updated) {
+      console.log(`✅ ${result.path} replaced from preset: ${result.preset}`);
+    } else {
+      console.log(`✅ ${result.path} created from preset: ${result.preset}`);
+    }
+  } catch (err) {
+    console.error(`❌ ${err.message}`);
+    process.exit(1);
+  }
+} else if (command === "preset") {
+  try {
+    const sub = args[0];
+    if (sub === "list") {
+      const presets = await listPresets();
+      console.log("Built-in presets:");
+      for (const name of presets) {
+        console.log(`  ${name}`);
+      }
+    } else if (sub === "show") {
+      const name = args[1];
+      if (!name) {
+        throw new Error("Preset name required. Example: preset show node-ts");
+      }
+      process.stdout.write(await loadPresetText(name));
+    } else {
+      throw new Error("Usage: preset list | preset show <name>");
+    }
+  } catch (err) {
+    console.error(`❌ ${err.message}`);
+    process.exit(1);
+  }
+} else if (command === "project-init") {
+  try {
+    const initOptions = {
+      skipDomains: false,
+      skipProject: false,
+      force: false,
+      dryRun: false,
+    };
+
+    for (let i = 0; i < args.length; i++) {
+      const arg = args[i];
+      if (arg === "--preset") {
+        initOptions.preset = args[++i];
+        if (!initOptions.preset) {
+          throw new Error("--preset requires a name. Run preset list.");
+        }
+      } else if (arg === "--domains") {
+        const raw = args[++i];
+        if (!raw) {
+          throw new Error("--domains requires a comma-separated list.");
+        }
+        initOptions.domains = raw.split(",").map((item) => item.trim()).filter(Boolean);
+      } else if (arg === "--no-domains") {
+        initOptions.skipDomains = true;
+      } else if (arg === "--no-project") {
+        initOptions.skipProject = true;
+      } else if (arg === "--force") {
+        initOptions.force = true;
+      } else if (arg === "--dry-run") {
+        initOptions.dryRun = true;
+      } else {
+        throw new Error(`Unknown project-init flag: ${arg}`);
+      }
+    }
+
+    const result = await projectInit(initOptions);
+
+    if (result.dryRun) {
+      console.log(`🔍 Brownfield scan: ${result.repoName}`);
+      console.log(`   Stack: ${result.stack.stack}`);
+      console.log(`   Preset: ${result.preset}`);
+      if (result.domains.length) {
+        console.log(`   Domains: ${result.domains.map((d) => d.domain).join(", ")}`);
+      } else {
+        console.log("   Domains: (none detected — use --domains or add code layout)");
+      }
+      console.log("   Dry run — no files written.");
+      process.exit(0);
+    }
+
+    console.log(`✅ Brownfield project memory initialized for ${result.repoName}`);
+    console.log(`   Stack: ${result.stack.stack}`);
+    console.log(`   Preset: ${result.preset}`);
+    for (const line of result.planned) {
+      console.log(`   ${line}`);
+    }
+    console.log("   Tier 0 — review PROJECT.md and domain stubs, then run feature-init.");
+  } catch (err) {
+    console.error(`❌ ${err.message}`);
+    process.exit(1);
+  }
+} else if (command === "feature-init") {
+  try {
+    const descriptionParts = [];
+    const initOptions = { skipBranch: false, skipSpec: false };
+
+    for (const arg of args) {
+      if (arg === "--no-branch") {
+        initOptions.skipBranch = true;
+      } else if (arg === "--no-spec") {
+        initOptions.skipSpec = true;
+      } else {
+        descriptionParts.push(arg);
+      }
+    }
+
+    const description = descriptionParts.join(" ").trim();
+    const result = await featureInit(description, initOptions);
+
+    console.log(`✅ Feature ${result.featureId}`);
+    console.log(`   Directory: ${result.featureDir}`);
+    console.log(`   Branch: ${result.branchName}`);
+    console.log(`   Git: ${result.branchMessage}`);
+    console.log("   Tier 0 complete — draft spec.md, then run validate-spec.");
+  } catch (err) {
+    console.error(`❌ ${err.message}`);
+    process.exit(1);
+  }
+} else if (command === "archive-feature") {
+  try {
+    const archiveOptions = {
+      skipVerify: false,
+      skipRoadmap: false,
+      skipDomainMerge: false,
+      skipState: false,
+    };
+    const positional = [];
+
+    for (let i = 0; i < args.length; i++) {
+      const arg = args[i];
+      if (arg === "--skip-verify") {
+        archiveOptions.skipVerify = true;
+      } else if (arg === "--no-roadmap") {
+        archiveOptions.skipRoadmap = true;
+      } else if (arg === "--no-domain") {
+        archiveOptions.skipDomainMerge = true;
+      } else if (arg === "--no-state") {
+        archiveOptions.skipState = true;
+      } else if (arg === "--domain") {
+        archiveOptions.domain = args[++i];
+        if (!archiveOptions.domain) {
+          throw new Error("--domain requires a slug argument.");
+        }
+      } else {
+        positional.push(arg);
+      }
+    }
+
+    const result = await archiveFeature(positional[0], archiveOptions);
+
+    console.log(`✅ Archived ${result.featureId}`);
+    if (result.roadmapPath) {
+      console.log(`   ROADMAP: ${result.roadmapPath}${result.roadmapUpdated ? " (updated)" : ""}`);
+    }
+    if (result.domainPath) {
+      console.log(`   Domain: ${result.domainPath}`);
+      if (result.mergeSummary.length) {
+        console.log(`   Merge: ${result.mergeSummary.join(", ")}`);
+      }
+    }
+    if (result.stateReset) {
+      console.log("   STATE: reset for next feature");
+    }
+    console.log("   Tier 0 — commit archive updates locally; push needs owner go-ahead.");
+  } catch (err) {
+    console.error(`❌ ${err.message}`);
+    process.exit(1);
+  }
+} else if (command === "phase-context") {
+  try {
+    const phase = args[0];
+    if (!phase) {
+      throw new Error("Phase is required. Example: phase-context specify");
+    }
+    const output = await phaseContext(phase);
+    process.stdout.write(output);
+  } catch (err) {
+    console.error(`❌ ${err.message}`);
+    process.exit(1);
+  }
+} else if (command === "doctor") {
+  try {
+    const doctorOptions = { json: false, suggest: true };
+    const positional = [];
+
+    for (const arg of args) {
+      if (arg === "--json") {
+        doctorOptions.json = true;
+      } else if (arg === "--no-suggest") {
+        doctorOptions.suggest = false;
+      } else {
+        positional.push(arg);
+      }
+    }
+
+    const target = positional[0] ? path.resolve(positional[0]) : process.cwd();
+    await doctor(target, doctorOptions);
+  } 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) {
+    console.error(`❌ ${err.message}`);
+    process.exit(2);
+  }
+} else if (GATE_COMMANDS.includes(command)) {
+  try {
+    const code = await runGate(command, args);
+    process.exit(code);
+  } catch (err) {
+    console.error(`❌ ${err.message}`);
+    process.exit(2);
+  }
+} else {
+  console.error(USAGE);
+  process.exit(1);
+}