@luizsantiago/spec-guardrails 3.1.11 → 3.2.0

package/README.md

@@ -11,7 +11,7 @@
 | **Solution** | One kit, two deliberate modes: **Process** (Node only) for a flexible spec-driven workflow; **Brakes** (Node + Python) for the **full product** — structural gates that exit non-zero when paperwork or evidence is missing. You approve specs/tasks in both. |
 | **Result** | Traceable `.specs/` memory, fewer fake finishes, cheaper turns (~70% less skill text on planning). Choose Process for light ceremony; add Python when you want the [Guarantees matrix](#guarantees-matrix) enforced automatically. |
 
-npm: [`@luizsantiago/spec-guardrails`](https://www.npmjs.com/package/@luizsantiago/spec-guardrails) **3.1.x**
+npm: [`@luizsantiago/spec-guardrails`](https://www.npmjs.com/package/@luizsantiago/spec-guardrails) **3.2.x**
 
 ---
 
@@ -41,11 +41,16 @@ npx @luizsantiago/spec-guardrails install
 
 Re-run `install` anytime to refresh skills; your `.specs/` decisions and `STATE.md` are kept.
 
-### Optional Atlas companions (Lego)
+### Governance focus (3.2+)
 
-Spec Guardrails is a **complete product alone**. Optional **Atlas** packages add domain specialization (Path Domains, catalogs). The first is [**Tech Atlas**](https://github.com/luizssantiago92/tech-atlas) (`@luizsantiago/tech-atlas`) — tech engineering context routing.
+Spec Guardrails is a **single product**: governance, evidence, verification, and controlled execution for agentic software development — not a bundle of companion packages.
 
-When paired, install Guardrails first, then the Atlas. Re-running Guardrails `install` **preserves** companion assets: Atlas skills/catalog, `.specs/atlas/`, mirrored `validate_layer_routing.py`, and `.specs/desks/` if present. Contract: [Companion: Tech Atlas](docs/guide/Companion-tech-atlas.md).
+| Capability | What it does |
+| --- | --- |
+| **Artifact gates** | Structural quality for spec, tasks, and cross-artifact consistency — with **blocking / warning / info** severity |
+| **Parallel waves** | `loop-plan` computes safe parallel groups; `workspace-prepare` isolates tasks in git worktrees |
+| **Execution policy** | Budgets, path scope, and escalation rules in `.specs/config.yaml` — consult via `execution-policy` |
+| **Independent verify** | Fresh-context verification with evidence-or-zero (`validate-state`) |
 
 | Need | Command |
 | --- | --- |
@@ -196,6 +201,7 @@ Full reference: **[Gates](docs/guide/gates.md)** · [Guarantees matrix](docs/gui
 | [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) | Shipped adapters (Cursor, Claude, Copilot, Codex) — core works with any agent |
+| [Restart PRD seed](docs/guide/Restart-prd-seed.md) | Clean-project PRD template for a single-package restart |
 | [FAQ](docs/guide/FAQ.md) | Common questions |
 | [Changelog](docs/CHANGELOG.md) | Full version history |
 
@@ -211,7 +217,8 @@ npx @luizsantiago/spec-guardrails install
 
 | Version | What you gain |
 | --- | --- |
-| **3.1.x** | Copilot/Codex/AGENTS.md adapters; doctor Process + Brakes scores; unified execution contracts; `validate-traceability` / `validate-quick`; `classify-change` / `feature-status` |
+| **3.2.x** | Single-package focus; artifact gate severity labels; git worktree isolation CLI; execution policy (budget/scope/escalation) |
+| **3.1.x** | Copilot/Codex/AGENTS.md adapters; doctor Process + Brakes scores; `validate-traceability` / `validate-quick`; `classify-change` / `feature-status` |
 | **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

@@ -8,10 +8,22 @@ 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 {
+  checkPathScope,
+  formatPolicyStatus,
+  loadExecutionPolicy,
+  loadPolicyState,
+  savePolicyState,
+} from "./lib/execution-policy.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 {
+  cleanupWorkspaces,
+  formatWorkspaceResults,
+  prepareWorkspaces,
+} from "./lib/workspace-isolation.js";
 import {
   initProjectConfig,
   listPresets,
@@ -50,10 +62,21 @@ Commands:
     [--json]                         Machine-readable output
   phase-context <phase>              Print .specs/config.yaml context + rules for a phase
   doctor [path]                      Audit guardrails readiness (score + next actions)
-                                      When Atlas companions are installed, also probes their
-                                      gates, rules, and PROJECT.md registry via INDEX.json
     [--json]                         Machine-readable output
     [--no-suggest]                   Hide per-check remediation hints
+  workspace-prepare <feature>        Create isolated git worktrees for parallel tasks
+    --tasks T1,T2                    Task ids to isolate (required)
+    [--base-ref HEAD]                Base ref for new worktrees
+    [--json]                         Machine-readable output
+  workspace-cleanup <feature>        Remove isolated worktrees for a feature
+    [--tasks T1,T2]                  Limit cleanup to specific tasks
+    [--force]                        Force-remove dirty worktrees
+    [--json]                         Machine-readable output
+  execution-policy status            Show configured budgets, scope, and runtime counters
+    [--json]                         Machine-readable output
+  execution-policy check-path <path> Check whether a relative path is allowed by scope policy
+    [--json]                         Machine-readable output
+  execution-policy record-retry <task>  Increment retry counter for a task id
   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
@@ -323,6 +346,144 @@ if (command === "--version" || command === "-v" || command === "version") {
     console.error(`❌ ${err.message}`);
     process.exit(1);
   }
+} else if (command === "workspace-prepare") {
+  try {
+    let json = false;
+    let baseRef = "HEAD";
+    let tasksRaw = "";
+    const positional = [];
+
+    for (let i = 0; i < args.length; i++) {
+      const arg = args[i];
+      if (arg === "--json") {
+        json = true;
+      } else if (arg === "--base-ref") {
+        baseRef = args[++i];
+        if (!baseRef) {
+          throw new Error("--base-ref requires a git ref");
+        }
+      } else if (arg === "--tasks") {
+        tasksRaw = args[++i] ?? "";
+        if (!tasksRaw) {
+          throw new Error("--tasks requires a comma-separated list (e.g. T1,T2)");
+        }
+      } else {
+        positional.push(arg);
+      }
+    }
+
+    const featureId = positional[0];
+    if (!featureId) {
+      throw new Error("Usage: workspace-prepare <feature> --tasks T1,T2");
+    }
+
+    const taskIds = tasksRaw.split(",").map((item) => item.trim()).filter(Boolean);
+    const results = await prepareWorkspaces(process.cwd(), { featureId, taskIds, baseRef });
+    process.stdout.write(formatWorkspaceResults(results, { json }));
+
+    if (results.some((item) => item.status === "failed")) {
+      process.exit(1);
+    }
+  } catch (err) {
+    console.error(`❌ ${err.message}`);
+    process.exit(1);
+  }
+} else if (command === "workspace-cleanup") {
+  try {
+    let json = false;
+    let force = false;
+    let tasksRaw = "";
+    const positional = [];
+
+    for (let i = 0; i < args.length; i++) {
+      const arg = args[i];
+      if (arg === "--json") {
+        json = true;
+      } else if (arg === "--force") {
+        force = true;
+      } else if (arg === "--tasks") {
+        tasksRaw = args[++i] ?? "";
+      } else {
+        positional.push(arg);
+      }
+    }
+
+    const featureId = positional[0];
+    if (!featureId) {
+      throw new Error("Usage: workspace-cleanup <feature> [--tasks T1,T2] [--force]");
+    }
+
+    const taskIds = tasksRaw
+      ? tasksRaw.split(",").map((item) => item.trim()).filter(Boolean)
+      : undefined;
+    const results = await cleanupWorkspaces(process.cwd(), { featureId, taskIds, force });
+    process.stdout.write(formatWorkspaceResults(results, { json }));
+
+    if (results.some((item) => item.status === "failed")) {
+      process.exit(1);
+    }
+  } catch (err) {
+    console.error(`❌ ${err.message}`);
+    process.exit(1);
+  }
+} else if (command === "execution-policy") {
+  try {
+    const sub = args[0];
+    let json = false;
+    const rest = [];
+
+    for (let i = 1; i < args.length; i++) {
+      if (args[i] === "--json") {
+        json = true;
+      } else {
+        rest.push(args[i]);
+      }
+    }
+
+    const cwd = process.cwd();
+    const policy = await loadExecutionPolicy(cwd);
+    const state = await loadPolicyState(cwd);
+
+    if (sub === "status") {
+      process.stdout.write(formatPolicyStatus(policy, state, { json }));
+    } else if (sub === "check-path") {
+      const relativePath = rest[0];
+      if (!relativePath) {
+        throw new Error("Usage: execution-policy check-path <relative-path>");
+      }
+      const result = checkPathScope(relativePath, policy);
+      if (json) {
+        console.log(JSON.stringify({ path: relativePath, ...result }, null, 2));
+      } else {
+        console.log(
+          `${relativePath}: ${result.allowed ? "allowed" : "blocked"} (${result.reason})`,
+        );
+      }
+      if (!result.allowed) {
+        process.exit(1);
+      }
+    } else if (sub === "record-retry") {
+      const taskId = rest[0];
+      if (!taskId) {
+        throw new Error("Usage: execution-policy record-retry <task-id>");
+      }
+      state.retries[taskId] = (state.retries[taskId] ?? 0) + 1;
+      state.iterations += 1;
+      await savePolicyState(cwd, state);
+      if (json) {
+        console.log(JSON.stringify({ taskId, retries: state.retries[taskId], state }, null, 2));
+      } else {
+        console.log(`Recorded retry for ${taskId}: ${state.retries[taskId]}`);
+      }
+    } else {
+      throw new Error(
+        "Usage: execution-policy status | check-path <path> | record-retry <task>",
+      );
+    }
+  } catch (err) {
+    console.error(`❌ ${err.message}`);
+    process.exit(1);
+  }
 } else if (command === "classify-change") {
   try {
     let json = false;

package/lib/archive.js

@@ -9,6 +9,7 @@ import {
 import { ensureDir, readFileSafe, writeFileSafe } from "./fs-utils.js";
 import { runGate } from "./gates.js";
 import { assertSafeDomainSlug } from "./slug-utils.js";
+import { isPassVerdict } from "./validation-verdict.js";
 import {
   featureDir,
   readFeatureArtifact,
@@ -23,15 +24,6 @@ Track milestones and archived features.
 
 `;
 
-/**
- * @param {string} text
- * @returns {boolean}
- */
-function validationPassed(text) {
-  const visible = text.replace(/<!--[\s\S]*?-->/g, "");
-  return /\b(?:PASS|PASSED)\b/.test(visible);
-}
-
 /**
  * @param {string} cwd
  * @param {string} featureId
@@ -150,7 +142,7 @@ export async function archiveFeature(featureArg, options = {}) {
       },
     );
 
-    if (!validationPassed(validationText)) {
+    if (!isPassVerdict(validationText)) {
       throw new Error(
         `validation.md for ${featureId} does not contain PASS/PASSED. Run validate-state first.`,
       );

package/lib/assets.js

@@ -55,8 +55,9 @@ export function resolveInstallSource(repoUrl) {
 /**
  * @param {string} remotePath
  * @param {string} destPath
+ * @param {{ boundary?: string }} [options]
  */
-export async function copyPackagedAsset(remotePath, destPath) {
+export async function copyPackagedAsset(remotePath, destPath, options = {}) {
   const source = packagedAssetPath(remotePath);
 
   try {
@@ -71,7 +72,7 @@ export async function copyPackagedAsset(remotePath, destPath) {
     throw err;
   }
 
-  await assertSafeWriteTarget(destPath);
+  await assertSafeWriteTarget(destPath, options);
 
   try {
     await fs.copyFile(source, destPath);
@@ -91,7 +92,7 @@ export async function copyPackagedAsset(remotePath, destPath) {
  * repo with no override (kept for the remote path; the default install no
  * longer uses it).
  *
- * @param {{ remotePath: string, destPath: string, repoUrl?: string, state: { warned: boolean }, log: (msg: string) => void }} params
+ * @param {{ remotePath: string, destPath: string, repoUrl?: string, state: { warned: boolean }, log: (msg: string) => void, boundary?: string }} params
  */
 export async function downloadRemoteAsset({
   remotePath,
@@ -99,9 +100,10 @@ export async function downloadRemoteAsset({
   repoUrl,
   state,
   log,
+  boundary,
 }) {
   try {
-    await downloadToFile(resolveAssetUrl(remotePath, repoUrl), destPath);
+    await downloadToFile(resolveAssetUrl(remotePath, repoUrl), destPath, { boundary });
     return;
   } catch (err) {
     const missingPinnedAsset =
@@ -123,15 +125,16 @@ export async function downloadRemoteAsset({
   await downloadToFile(
     resolveAssetUrl(remotePath, FALLBACK_REPO_URL),
     destPath,
+    { boundary },
   );
 }
 
 /**
- * @param {{ remotePath: string, destPath: string, source: ReturnType<typeof resolveInstallSource>, state: { warned: boolean }, log: (msg: string) => void }} params
+ * @param {{ remotePath: string, destPath: string, source: ReturnType<typeof resolveInstallSource>, state: { warned: boolean }, log: (msg: string) => void, boundary?: string }} params
  */
-export async function installAsset({ remotePath, destPath, source, state, log }) {
+export async function installAsset({ remotePath, destPath, source, state, log, boundary }) {
   if (source.mode === "package") {
-    await copyPackagedAsset(remotePath, destPath);
+    await copyPackagedAsset(remotePath, destPath, { boundary });
     return;
   }
 
@@ -141,5 +144,6 @@ export async function installAsset({ remotePath, destPath, source, state, log })
     repoUrl: source.repoUrl,
     state,
     log,
+    boundary,
   });
 }

package/lib/doctor.js

@@ -8,11 +8,6 @@ import {
   NPX,
   SKILL_DIRS,
 } from "./constants.js";
-import { listInstalledCompanions } from "./companions.js";
-import {
-  runCompanionDoctorChecks,
-  summarizeCompanionChecks,
-} from "./companion-doctor.js";
 import { resolvePython, resolveScriptsDir } from "./gates.js";
 import { readFileSafe } from "./fs-utils.js";
 import { listFeatureIds, readActiveFeatureFromState } from "./specs-utils.js";
@@ -203,21 +198,6 @@ export async function runDoctorChecks(cwd) {
     suggest: NPX("project-init"),
   });
 
-  const companionReport = await runCompanionDoctorChecks(cwd);
-  if (companionReport.checks.length > 0) {
-    checks.push(...companionReport.checks);
-  } else {
-    checks.push({
-      id: "atlas-companions",
-      label: "Atlas companions registry (.specs/companions/INDEX.json)",
-      weight: 5,
-      pass: false,
-      optional: true,
-      suggest:
-        "Optional: npx @luizsantiago/tech-atlas install (or another Atlas package)",
-    });
-  }
-
   const activeFeature = await readActiveFeature(cwd);
   let activeFeatureOk = true;
   let activeFeatureSuggest;
@@ -399,45 +379,16 @@ export async function doctor(cwd, options = {}) {
   const executeHint = await resolveExecuteHint(cwd, activeFeature);
   const pythonCheck = checks.find((check) => check.id === "python");
   const pythonMissing = pythonCheck ? !pythonCheck.pass : false;
-  const companions = await listInstalledCompanions(cwd);
-  const companionChecks = checks.filter((check) => check.id.startsWith("atlas-"));
-  const companionSummary = summarizeCompanionChecks(companionChecks);
-  const stackPaired = companions.length > 0 && companionChecks.some((c) => !c.optional);
 
   if (options.json) {
     console.log(
       JSON.stringify(
-        {
-          score,
-          modes,
-          checks,
-          suggestions,
-          executeHint,
-          pythonMissing,
-          stack: {
-            paired: stackPaired,
-            companions: companions.map((c) => ({
-              id: c.id,
-              npm: c.npm,
-              version: c.version,
-              displayName: c.displayName,
-            })),
-            atlasReady: companionSummary.ready,
-          },
-        },
+        { score, modes, checks, suggestions, executeHint, pythonMissing },
         null,
         2,
       ),
     );
-    return {
-      score,
-      modes,
-      checks,
-      suggestions,
-      executeHint,
-      pythonMissing,
-      stack: { paired: stackPaired, companions, atlasReady: companionSummary.ready },
-    };
+    return { score, modes, checks, suggestions, executeHint, pythonMissing };
   }
 
   if (pythonMissing) {
@@ -456,13 +407,6 @@ export async function doctor(cwd, options = {}) {
   console.log(`  Brakes:  ${modes.brakes.score}/100${brakesHint}\n`);
   console.log(`Guardrails Ready: ${score}/100\n`);
 
-  if (companions.length > 0) {
-    const stackLabel = stackPaired ? "paired Lego stack" : "solo + Atlas companions";
-    console.log(
-      `Atlas stack: ${stackLabel} — ${companions.length} companion(s), ${companionSummary.passed}/${companionSummary.total} checks passed\n`,
-    );
-  }
-
   for (const check of checks) {
     const mark = check.pass ? "✓" : "✗";
     const optional = check.optional ? " (optional)" : "";
@@ -483,13 +427,5 @@ export async function doctor(cwd, options = {}) {
     console.log(`\nExecute hint:\n  → ${executeHint}`);
   }
 
-  return {
-    score,
-    modes,
-    checks,
-    suggestions,
-    executeHint,
-    pythonMissing,
-    stack: { paired: stackPaired, companions, atlasReady: companionSummary.ready },
-  };
+  return { score, modes, checks, suggestions, executeHint, pythonMissing };
 }

package/lib/download.js

@@ -98,8 +98,8 @@ async function fetchWithSafeRedirects(startUrl) {
   );
 }
 
-export async function downloadToFile(url, destPath) {
-  await assertSafeWriteTarget(destPath);
+export async function downloadToFile(url, destPath, options = {}) {
+  await assertSafeWriteTarget(destPath, options);
 
   const response = await fetchWithSafeRedirects(url);