@luizsantiago/spec-guardrails 3.2.0 → 3.2.1

package/index.js

@@ -9,10 +9,12 @@ 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,
+  recordAgentRun,
+  recordTaskRetry,
+  resolvePathCheck,
   savePolicyState,
 } from "./lib/execution-policy.js";
 import { featureInit } from "./lib/feature.js";
@@ -21,7 +23,9 @@ import { GATE_COMMANDS, AUX_COMMANDS, runGate, runGuardrailsScript } from "./lib
 import { install } from "./lib/install.js";
 import {
   cleanupWorkspaces,
+  formatWorkspaceList,
   formatWorkspaceResults,
+  listWorkspaces,
   prepareWorkspaces,
 } from "./lib/workspace-isolation.js";
 import {
@@ -70,13 +74,20 @@ Commands:
     [--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
+    [--force]                        Force-remove dirty worktrees (recovery after worker FAIL)
+    [--json]                         Machine-readable output
+  workspace-list <feature>           List isolated worktrees for a feature
     [--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
+  execution-policy record-retry <task>  Increment retry counter for a task id (blocks at limit)
+  execution-policy record-run        Increment agent-run counter (blocks at budget)
+  memory-index rebuild               Rebuild SQLite memory index from .specs/ artifacts
+  memory-query --from <id>           Bounded context package from the knowledge graph
+    [--depth N]                      Traversal depth (default 2)
+    [--json]                         Machine-readable output
   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
@@ -86,7 +97,7 @@ Commands:
   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
+  lessons <add|list|penalize|prune|promote|graduate|status>  Lessons engine
   --help                             Show this message
   --version                          Print the package version
 `;
@@ -426,6 +437,30 @@ if (command === "--version" || command === "-v" || command === "version") {
     console.error(`❌ ${err.message}`);
     process.exit(1);
   }
+} else if (command === "workspace-list") {
+  try {
+    let json = false;
+    const positional = [];
+
+    for (const arg of args) {
+      if (arg === "--json") {
+        json = true;
+      } else {
+        positional.push(arg);
+      }
+    }
+
+    const featureId = positional[0];
+    if (!featureId) {
+      throw new Error("Usage: workspace-list <feature> [--json]");
+    }
+
+    const workspaces = await listWorkspaces(process.cwd(), featureId);
+    process.stdout.write(formatWorkspaceList(workspaces, { json, featureId }));
+  } catch (err) {
+    console.error(`❌ ${err.message}`);
+    process.exit(1);
+  }
 } else if (command === "execution-policy") {
   try {
     const sub = args[0];
@@ -451,33 +486,57 @@ if (command === "--version" || command === "-v" || command === "version") {
       if (!relativePath) {
         throw new Error("Usage: execution-policy check-path <relative-path>");
       }
-      const result = checkPathScope(relativePath, policy);
+      const result = resolvePathCheck(relativePath, policy);
       if (json) {
         console.log(JSON.stringify({ path: relativePath, ...result }, null, 2));
       } else {
-        console.log(
-          `${relativePath}: ${result.allowed ? "allowed" : "blocked"} (${result.reason})`,
-        );
+        const label = result.allowed
+          ? "allowed"
+          : result.severity === "warning"
+            ? "blocked (warn)"
+            : "blocked";
+        console.log(`${relativePath}: ${label} (${result.reason})`);
       }
-      if (!result.allowed) {
-        process.exit(1);
+      if (result.exitCode !== 0) {
+        process.exit(result.exitCode);
       }
     } 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);
+      const recorded = recordTaskRetry(state, taskId, policy);
+      if (!recorded.ok) {
+        console.error(`❌ ${recorded.message}`);
+        process.exit(1);
+      }
+      await savePolicyState(cwd, recorded.state);
       if (json) {
-        console.log(JSON.stringify({ taskId, retries: state.retries[taskId], state }, null, 2));
+        console.log(
+          JSON.stringify({ taskId, retries: recorded.retries, state: recorded.state }, null, 2),
+        );
       } else {
-        console.log(`Recorded retry for ${taskId}: ${state.retries[taskId]}`);
+        console.log(`Recorded retry for ${taskId}: ${recorded.retries}`);
+      }
+    } else if (sub === "record-run") {
+      const recorded = recordAgentRun(state, policy);
+      if (!recorded.ok) {
+        console.error(`❌ ${recorded.message}`);
+        process.exit(1);
+      }
+      await savePolicyState(cwd, recorded.state);
+      if (json) {
+        console.log(
+          JSON.stringify({ agent_runs: recorded.state.agent_runs, state: recorded.state }, null, 2),
+        );
+      } else {
+        console.log(
+          `Recorded agent run: ${recorded.state.agent_runs}/${policy.budget.max_agent_runs}`,
+        );
       }
     } else {
       throw new Error(
-        "Usage: execution-policy status | check-path <path> | record-retry <task>",
+        "Usage: execution-policy status | check-path <path> | record-retry <task> | record-run",
       );
     }
   } catch (err) {
@@ -536,7 +595,8 @@ if (command === "--version" || command === "-v" || command === "version") {
     console.error(`❌ ${err.message}`);
     process.exit(1);
   }
-} else if (AUX_COMMANDS.includes(command)) {  try {
+} else if (AUX_COMMANDS.includes(command)) {
+  try {
     const code = await runGuardrailsScript(command, args);
     process.exit(code);
   } catch (err) {

package/lib/adapter-registry.js

@@ -0,0 +1,128 @@
+import { injectAgentsMd } from "./agents-md.js";
+import { injectCodexAgents } from "./codex-agents.js";
+import { injectCopilotInstructions } from "./copilot-instructions.js";
+import { injectClaudeMd } from "./claude-md.js";
+import { injectCursorRules } from "./cursorrules.js";
+
+/**
+ * @typedef {{
+ *   id: string,
+ *   label: string,
+ *   skillsDir: string | null,
+ *   entryFiles: string[],
+ *   capabilities: {
+ *     supports_hooks: boolean,
+ *     supports_commands: boolean,
+ *     supports_rules: boolean,
+ *     supports_skills: boolean,
+ *   },
+ *   install: (cwd: string) => Promise<void>,
+ * }} PlatformAdapter
+ */
+
+/** @type {PlatformAdapter[]} */
+export const ADAPTER_REGISTRY = [
+  {
+    id: "cursor",
+    label: "Cursor",
+    skillsDir: ".cursor/skills",
+    entryFiles: [".cursorrules", ".cursor/rules/engineering-baseline.mdc"],
+    capabilities: {
+      supports_hooks: true,
+      supports_commands: true,
+      supports_rules: true,
+      supports_skills: true,
+    },
+    install: injectCursorRules,
+  },
+  {
+    id: "claude",
+    label: "Claude Code",
+    skillsDir: ".claude/skills",
+    entryFiles: [".claude/CLAUDE.md"],
+    capabilities: {
+      supports_hooks: false,
+      supports_commands: true,
+      supports_rules: false,
+      supports_skills: true,
+    },
+    install: injectClaudeMd,
+  },
+  {
+    id: "copilot",
+    label: "GitHub Copilot",
+    skillsDir: ".github/skills",
+    entryFiles: [".github/copilot-instructions.md"],
+    capabilities: {
+      supports_hooks: false,
+      supports_commands: false,
+      supports_rules: false,
+      supports_skills: true,
+    },
+    install: injectCopilotInstructions,
+  },
+  {
+    id: "codex",
+    label: "OpenAI Codex",
+    skillsDir: ".codex/skills",
+    entryFiles: [".codex/AGENTS.md"],
+    capabilities: {
+      supports_hooks: false,
+      supports_commands: false,
+      supports_rules: false,
+      supports_skills: true,
+    },
+    install: injectCodexAgents,
+  },
+  {
+    id: "agents-md",
+    label: "AGENTS.md (open standard)",
+    skillsDir: null,
+    entryFiles: ["AGENTS.md"],
+    capabilities: {
+      supports_hooks: false,
+      supports_commands: false,
+      supports_rules: false,
+      supports_skills: false,
+    },
+    install: injectAgentsMd,
+  },
+];
+
+/**
+ * @param {string} id
+ * @returns {PlatformAdapter | undefined}
+ */
+export function getAdapter(id) {
+  return ADAPTER_REGISTRY.find((adapter) => adapter.id === id);
+}
+
+/** @returns {PlatformAdapter[]} */
+export function listAdapters() {
+  return [...ADAPTER_REGISTRY];
+}
+
+/**
+ * @param {keyof PlatformAdapter["capabilities"]} capability
+ * @returns {PlatformAdapter[]}
+ */
+export function getAdaptersWithCapability(capability) {
+  return ADAPTER_REGISTRY.filter((adapter) => adapter.capabilities[capability]);
+}
+
+/**
+ * @param {string} cwd
+ * @param {PlatformAdapter} [adapter]
+ */
+export async function installAdapter(cwd, adapter) {
+  await adapter.install(cwd);
+}
+
+/**
+ * Install all registered platform adapters.
+ *
+ * @param {string} cwd
+ */
+export async function installAllAdapters(cwd) {
+  await Promise.all(ADAPTER_REGISTRY.map((adapter) => installAdapter(cwd, adapter)));
+}

package/lib/adapters.js

@@ -1,17 +1,11 @@
-import { injectAgentsMd } from "./agents-md.js";
-import { injectCodexAgents } from "./codex-agents.js";
-import { injectCopilotInstructions } from "./copilot-instructions.js";
+import { installAllAdapters } from "./adapter-registry.js";
 
 /**
  * Install shipped platform adapter entry files (Copilot, Codex, AGENTS.md).
- * Cursor and Claude adapters are injected separately in install.js.
+ * Cursor and Claude adapters are injected via the same registry during install.
  *
  * @param {string} cwd
  */
 export async function installPlatformAdapters(cwd) {
-  return Promise.all([
-    injectCopilotInstructions(cwd),
-    injectAgentsMd(cwd),
-    injectCodexAgents(cwd),
-  ]);
+  return installAllAdapters(cwd);
 }

package/lib/constants.js

@@ -108,6 +108,8 @@ export const SCRIPT_ASSETS = [
   { file: "check_commit.py", remotePath: "scripts/check_commit.py" },
   { file: "lessons.py", remotePath: "scripts/lessons.py" },
   { file: "loop_plan.py", remotePath: "scripts/loop_plan.py" },
+  { file: "memory_index.py", remotePath: "scripts/memory_index.py" },
+  { file: "memory_query.py", remotePath: "scripts/memory_query.py" },
 ];
 
 /** @type {{ file: string, remotePath: string }[]} */

package/lib/execution-policy.js

@@ -235,13 +235,32 @@ export function checkBudget(state, policy) {
   return { ok: issues.length === 0, issues };
 }
 
+/**
+ * @param {string} relativePath
+ * @param {ExecutionPolicy} policy
+ * @returns {{ allowed: boolean, exitCode: number, severity: "blocking" | "warning" | "info", reason: string }}
+ */
+export function resolvePathCheck(relativePath, policy) {
+  const result = checkPathScope(relativePath, policy);
+  if (result.allowed) {
+    return { ...result, exitCode: 0 };
+  }
+
+  const mode = policy.escalation.on_policy_violation ?? "block";
+  if (mode === "warn") {
+    return { ...result, severity: "warning", exitCode: 0 };
+  }
+
+  return { ...result, exitCode: 1 };
+}
+
 /**
  * @param {string} taskId
  * @param {ExecutionPolicyState} state
  * @param {ExecutionPolicy} policy
  * @returns {{ ok: boolean, severity?: "blocking", message?: string, retries: number }}
  */
-export function checkTaskRetries(taskId, state, policy) {
+export function previewTaskRetry(taskId, state, policy) {
   const retries = state.retries[taskId] ?? 0;
   if (retries >= policy.budget.max_retries_per_task) {
     return {
@@ -254,6 +273,70 @@ export function checkTaskRetries(taskId, state, policy) {
   return { ok: true, retries };
 }
 
+/**
+ * @param {string} taskId
+ * @param {ExecutionPolicyState} state
+ * @param {ExecutionPolicy} policy
+ * @returns {{ ok: boolean, severity?: "blocking", message?: string, retries: number }}
+ */
+export function checkTaskRetries(taskId, state, policy) {
+  const preview = previewTaskRetry(taskId, state, policy);
+  return preview.ok
+    ? { ok: true, retries: preview.retries }
+    : {
+        ok: false,
+        severity: preview.severity,
+        message: preview.message,
+        retries: preview.retries,
+      };
+}
+
+/**
+ * @param {ExecutionPolicyState} state
+ * @param {ExecutionPolicy} policy
+ * @returns {{ ok: boolean, message?: string }}
+ */
+export function previewAgentRun(state, policy) {
+  if (state.agent_runs >= policy.budget.max_agent_runs) {
+    return { ok: false, message: "max_agent_runs budget exhausted" };
+  }
+  return { ok: true };
+}
+
+/**
+ * @param {ExecutionPolicyState} state
+ * @param {string} taskId
+ * @param {ExecutionPolicy} policy
+ * @returns {{ ok: boolean, state: ExecutionPolicyState, retries: number, message?: string }}
+ */
+export function recordTaskRetry(state, taskId, policy) {
+  const preview = previewTaskRetry(taskId, state, policy);
+  if (!preview.ok) {
+    return { ok: false, state, retries: preview.retries, message: preview.message };
+  }
+
+  const next = structuredClone(state);
+  next.retries[taskId] = (next.retries[taskId] ?? 0) + 1;
+  next.iterations += 1;
+  return { ok: true, state: next, retries: next.retries[taskId] };
+}
+
+/**
+ * @param {ExecutionPolicyState} state
+ * @param {ExecutionPolicy} policy
+ * @returns {{ ok: boolean, state: ExecutionPolicyState, message?: string }}
+ */
+export function recordAgentRun(state, policy) {
+  const preview = previewAgentRun(state, policy);
+  if (!preview.ok) {
+    return { ok: false, state, message: preview.message };
+  }
+
+  const next = structuredClone(state);
+  next.agent_runs += 1;
+  return { ok: true, state: next };
+}
+
 /**
  * @param {ExecutionPolicy} policy
  * @param {ExecutionPolicyState} state

package/lib/gates.js

@@ -41,6 +41,8 @@ const GATE_SCRIPTS = {
 
 const AUX_SCRIPTS = {
   "loop-plan": "loop_plan.py",
+  "memory-index": "memory_index.py",
+  "memory-query": "memory_query.py",
 };
 
 const GUARDRAILS_SCRIPTS = { ...GATE_SCRIPTS, ...AUX_SCRIPTS };

package/lib/install.js

@@ -13,8 +13,6 @@ import {
   resolveAssetOverride,
 } from "./constants.js";
 import { installPlatformAdapters } from "./adapters.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";
 import { initGuardrailsMemory } from "./memory.js";
@@ -117,8 +115,6 @@ export async function install(options = {}) {
   }
 
   log("🔗 Installing platform adapters...");
-  await injectCursorRules(cwd);
-  await injectClaudeMd(cwd);
   await installPlatformAdapters(cwd);
   log("✅ Adapters → .cursorrules, CLAUDE.md, copilot-instructions.md, AGENTS.md, .codex/AGENTS.md");
 

package/lib/memory-index.js

@@ -0,0 +1,59 @@
+import path from "node:path";
+
+import { GUARDRAILS_SCRIPTS_DIR } from "./constants.js";
+import { runGuardrailsScript } from "./gates.js";
+
+export const MEMORY_DB_PATH = ".specs/memory/memory.db";
+
+/**
+ * Rebuild the SQLite memory index from `.specs/` markdown artifacts.
+ *
+ * @param {{ cwd?: string }} [options]
+ * @returns {Promise<number>} exit code
+ */
+export async function rebuildMemoryIndex(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  return runGuardrailsScript("memory-index", ["rebuild"], { cwd });
+}
+
+/**
+ * Query the knowledge graph for a bounded context package.
+ *
+ * @param {{ from: string, depth?: number, json?: boolean, cwd?: string }} options
+ * @returns {Promise<number>} exit code
+ */
+export async function queryMemory(options) {
+  const cwd = options.cwd ?? process.cwd();
+  const args = ["--from", options.from];
+  if (options.depth !== undefined) {
+    args.push("--depth", String(options.depth));
+  }
+  if (options.json) {
+    args.push("--json");
+  }
+  return runGuardrailsScript("memory-query", args, { cwd });
+}
+
+/**
+ * @param {string} [cwd]
+ * @returns {string}
+ */
+export function memoryDbPath(cwd = process.cwd()) {
+  return path.join(cwd, MEMORY_DB_PATH);
+}
+
+/**
+ * @returns {string}
+ */
+export function memoryDbRelativePath() {
+  return MEMORY_DB_PATH;
+}
+
+/**
+ * Relative scripts directory for memory tooling diagnostics.
+ *
+ * @returns {string}
+ */
+export function memoryScriptsDir() {
+  return GUARDRAILS_SCRIPTS_DIR;
+}

package/lib/workspace-isolation.js

@@ -137,6 +137,39 @@ export async function cleanupWorkspaces(cwd, { featureId, taskIds, force = false
   return results;
 }
 
+/**
+ * @param {string} cwd
+ * @param {string} featureId
+ * @returns {Promise<Array<{ taskId: string, path: string }>>}
+ */
+export async function listWorkspaces(cwd, featureId) {
+  const paths = await listWorkspacePaths(cwd, featureId);
+  return paths.map((wtPath) => ({
+    taskId: path.basename(wtPath),
+    path: wtPath,
+  }));
+}
+
+/**
+ * @param {Awaited<ReturnType<typeof listWorkspaces>>} workspaces
+ * @param {{ json?: boolean, featureId?: string }} [options]
+ */
+export function formatWorkspaceList(workspaces, options = {}) {
+  if (options.json) {
+    return JSON.stringify({ feature: options.featureId, workspaces }, null, 2);
+  }
+
+  const lines = ["Workspace list:"];
+  if (!workspaces.length) {
+    lines.push("  (none)");
+  } else {
+    for (const item of workspaces) {
+      lines.push(`  ${item.taskId}: ${item.path}`);
+    }
+  }
+  return `${lines.join("\n")}\n`;
+}
+
 /**
  * @param {ReturnType<typeof prepareWorkspaces> extends Promise<infer T> ? T : never} results
  * @param {{ json?: boolean }} [options]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luizsantiago/spec-guardrails",
-  "version": "3.2.0",
+  "version": "3.2.1",
   "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/test_specs_utils.test.js test/test_validation_verdict.test.js test/test_execution_policy.test.js test/test_workspace_isolation.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/test_validation_verdict.test.js test/test_execution_policy.test.js test/test_workspace_isolation.test.js test/test_adapter_registry.test.js",
     "test:gates": "node test/run-gate-tests.mjs",
     "prepublishOnly": "npm test"
   },

package/rules/engineering-baseline.mdc

@@ -47,8 +47,10 @@ Gates live in `.specs/guardrails/scripts/` (Python 3). **The agent runs them** a
 | `feature-init "…"` | Optional — or ask the agent to `/specify` |
 | `project-init` | Optional — brownfield repo with existing code |
 | `doctor` | Install looks broken |
+| `workspace-list <feature>` | Inspect parallel worktrees before cleanup |
+| `execution-policy status` | Check budgets and scope before expanding Execute |
 
-Everything else (`validate-spec`, `validate-tasks`, `check-commit`, …) is normally run **by the agent**, not memorized from this file. Full list: `npx @luizsantiago/spec-guardrails --help` or `.specs/GETTING_STARTED.md`.
+Everything else (`validate-spec`, `validate-tasks`, `check-commit`, `workspace-prepare`, `execution-policy check-path`, …) is normally run **by the agent**, not memorized from this file. Full list: `npx @luizsantiago/spec-guardrails --help` or `.specs/GETTING_STARTED.md`.
 
 Non-zero gate exit = STOP. Without Python, the agent performs the same checks manually.
 

package/scripts/analyze_artifacts.py

@@ -46,6 +46,15 @@ STATE_FEATURE = re.compile(
     r"^\s*-\s*Feature:\s*(.+)$",
     re.IGNORECASE | re.MULTILINE,
 )
+TASK_HEADING = re.compile(
+    r"^#{2,6}\s*(?P<id>T\d{1,6})\s*[:\-–]?\s*(?P<title>.*)$",
+    re.MULTILINE | re.IGNORECASE,
+)
+VERIFY_HINT = re.compile(
+    r"\b(test strategy|verification|validate\.md|/verify|acceptance test)\b",
+    re.IGNORECASE,
+)
+MEDIUM_TASK_FLOOR = 5
 
 
 def git_branch(root: Path) -> str | None:
@@ -121,6 +130,20 @@ def build_report(feature_dir: Path, root: Path) -> Report:
     else:
         report.warn("tasks.md missing or empty — task coverage checks skipped")
 
+    task_count = len(TASK_HEADING.findall(tasks_text or ""))
+    medium_plus = task_count >= MEDIUM_TASK_FLOOR
+
+    if medium_plus and design_text is None:
+        report.warn(
+            f"{task_count} tasks — design.md recommended for Medium+ features"
+        )
+
+    plan_text = "\n".join(filter(None, [spec_text, design_text]))
+    if medium_plus and plan_text and not VERIFY_HINT.search(plan_text):
+        report.warn(
+            "no verification or test strategy mention in spec/design — add verify plan before Execute"
+        )
+
     if design_text is not None and tasks_text:
         visible_design = visible_markdown(design_text).strip()
         if len(visible_design.splitlines()) < 5: