@luizsantiago/spec-guardrails 3.3.0 → 3.5.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.3.x**
+npm: [`@luizsantiago/spec-guardrails`](https://www.npmjs.com/package/@luizsantiago/spec-guardrails) **3.5.x**
 
 ---
 
@@ -217,6 +217,8 @@ npx @luizsantiago/spec-guardrails install
 
 | Version | What you gain |
 | --- | --- |
+| **3.5.x** | Solution exploration (`solution-explore`) — compare candidates from approved spec |
+| **3.4.x** | Contextual guards (`context-guard`); FTS memory search (`memory-search`) |
 | **3.3.x** | Intent/effect policy — `check-path --op read|write|delete` and `effects` config block |
 | **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` |

package/index.js

@@ -5,6 +5,13 @@ 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 {
+  checkBeforeComplete,
+  checkBeforeEdit,
+  evaluateExecuteContext,
+  formatCheckBeforeEdit,
+  formatContextGuardStatus,
+} from "./lib/context-guard.js";
 import { PACKAGE_VERSION, CLI_NAME } from "./lib/constants.js";
 import { phaseContext } from "./lib/config.js";
 import { doctor } from "./lib/doctor.js";
@@ -28,6 +35,16 @@ import {
   listWorkspaces,
   prepareWorkspaces,
 } from "./lib/workspace-isolation.js";
+import {
+  formatExplorationInit,
+  formatExplorationStatus,
+  formatExplorationValidation,
+  getExplorationStatus,
+  initExploration,
+  normalizeCandidateId,
+  recordExplorationDecision,
+  validateExplorationArtifact,
+} from "./lib/solution-exploration.js";
 import {
   initProjectConfig,
   listPresets,
@@ -89,6 +106,34 @@ Commands:
   memory-query --from <id>           Bounded context package from the knowledge graph
     [--depth N]                      Traversal depth (default 2)
     [--json]                         Machine-readable output
+  memory-search <query>              Full-text search over the memory index (FTS5)
+    [--limit N]                      Max results (default 10)
+    [--json]                         Machine-readable output
+  context-guard status               Execute readiness from STATE + tasks.md
+    [--json]                         Machine-readable output
+  context-guard check-edit <path>    Contextual guard before editing a file
+    [--op read|write|delete]         Intended operation (default: inferred)
+    [--no-strict-files]              Skip task Files allowlist check
+    [--json]                         Machine-readable output
+  context-guard check-complete       Contextual guard before claiming feature done
+    [feature]                        Feature id (default: active in STATE)
+    [--json]                         Machine-readable output
+  solution-explore init <feature>    Start solution exploration from approved spec
+    --candidates A,B[,C]             Candidate ids (required, at least two)
+    [--labels "a,b,c"]               Optional labels aligned to candidate ids
+    [--base-ref HEAD]                Base ref for candidate worktrees
+    [--force]                        Replace existing exploration.md
+    [--json]                         Machine-readable output
+  solution-explore status [feature]  Show exploration candidates and decision state
+    [--json]                         Machine-readable output
+  solution-explore validate [feature]  Gate: comparison matrix complete before select
+    [--json]                         Machine-readable output
+  solution-explore select <feature>  Record exploration decision
+    --candidate A                    Selected candidate id (required)
+    [--merge B]                      Optional secondary candidate to merge from
+    --rationale "…"                  Why this candidate won (required)
+    [--cleanup]                      Remove non-selected candidate worktrees
+    [--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
@@ -565,6 +610,218 @@ if (command === "--version" || command === "-v" || command === "version") {
     console.error(`❌ ${err.message}`);
     process.exit(1);
   }
+} else if (command === "context-guard") {
+  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();
+
+    if (sub === "status") {
+      const context = await evaluateExecuteContext(cwd);
+      process.stdout.write(formatContextGuardStatus(context, { json }));
+      if (!context.ok && context.severity === "blocking") {
+        process.exit(1);
+      }
+    } else if (sub === "check-edit") {
+      let operation;
+      let strictFiles = true;
+      const positional = [];
+
+      for (let i = 0; i < rest.length; i++) {
+        const arg = rest[i];
+        if (arg === "--no-strict-files") {
+          strictFiles = false;
+        } else if (arg === "--op") {
+          operation = rest[++i];
+          if (!operation) {
+            throw new Error("--op requires read, write, or delete");
+          }
+        } else {
+          positional.push(arg);
+        }
+      }
+
+      const relativePath = positional[0];
+      if (!relativePath) {
+        throw new Error(
+          "Usage: context-guard check-edit <relative-path> [--op read|write|delete] [--no-strict-files]",
+        );
+      }
+
+      const result = await checkBeforeEdit(cwd, relativePath, { operation, strictFiles });
+      process.stdout.write(formatCheckBeforeEdit(result, relativePath, { json }));
+      if (result.exitCode !== 0) {
+        process.exit(result.exitCode);
+      }
+    } else if (sub === "check-complete") {
+      const featureId = rest[0];
+      const result = await checkBeforeComplete(cwd, featureId);
+      if (json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        const label = result.allowed ? "ready" : "blocked";
+        console.log(`Feature ${result.featureId}: ${label}`);
+        for (const message of result.messages) {
+          console.log(`  ${message}`);
+        }
+      }
+      if (result.exitCode !== 0) {
+        process.exit(result.exitCode);
+      }
+    } else {
+      throw new Error(
+        "Usage: context-guard status | check-edit <path> | check-complete [feature]",
+      );
+    }
+  } catch (err) {
+    console.error(`❌ ${err.message}`);
+    process.exit(1);
+  }
+} else if (command === "solution-explore") {
+  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();
+
+    if (sub === "init") {
+      let candidatesRaw = "";
+      let labelsRaw = "";
+      let baseRef = "HEAD";
+      let force = false;
+      const positional = [];
+
+      for (let i = 0; i < rest.length; i++) {
+        const arg = rest[i];
+        if (arg === "--candidates") {
+          candidatesRaw = rest[++i] ?? "";
+        } else if (arg === "--labels") {
+          labelsRaw = rest[++i] ?? "";
+        } else if (arg === "--base-ref") {
+          baseRef = rest[++i];
+          if (!baseRef) {
+            throw new Error("--base-ref requires a git ref");
+          }
+        } else if (arg === "--force") {
+          force = true;
+        } else {
+          positional.push(arg);
+        }
+      }
+
+      const featureId = positional[0];
+      if (!featureId || !candidatesRaw) {
+        throw new Error(
+          "Usage: solution-explore init <feature> --candidates A,B [--labels \"a,b\"] [--base-ref HEAD] [--force]",
+        );
+      }
+
+      const ids = candidatesRaw.split(",").map((item) => item.trim()).filter(Boolean);
+      const labels = labelsRaw
+        ? labelsRaw.split(",").map((item) => item.trim())
+        : [];
+      const candidateSpecs = ids.map((id, index) => ({
+        id: normalizeCandidateId(id),
+        label: labels[index] || undefined,
+      }));
+
+      const result = await initExploration(cwd, featureId, candidateSpecs, { baseRef, force });
+      process.stdout.write(formatExplorationInit(result, { json }));
+
+      if (result.workspaces.some((item) => item.status === "failed")) {
+        process.exit(1);
+      }
+    } else if (sub === "status") {
+      const featureId = rest[0];
+      const status = await getExplorationStatus(cwd, featureId);
+      process.stdout.write(formatExplorationStatus(status, { json }));
+    } else if (sub === "validate") {
+      const featureId = rest[0];
+      if (!featureId) {
+        throw new Error("Usage: solution-explore validate <feature>");
+      }
+      const result = await validateExplorationArtifact(cwd, featureId);
+      process.stdout.write(formatExplorationValidation(result, { json }));
+      if (!result.ok) {
+        process.exit(1);
+      }
+    } else if (sub === "select") {
+      let selected = "";
+      let mergedFrom = "";
+      let rationale = "";
+      let cleanup = false;
+      const positional = [];
+
+      for (let i = 0; i < rest.length; i++) {
+        const arg = rest[i];
+        if (arg === "--candidate") {
+          selected = rest[++i] ?? "";
+        } else if (arg === "--merge") {
+          mergedFrom = rest[++i] ?? "";
+        } else if (arg === "--rationale") {
+          rationale = rest[++i] ?? "";
+        } else if (arg === "--cleanup") {
+          cleanup = true;
+        } else {
+          positional.push(arg);
+        }
+      }
+
+      const featureId = positional[0];
+      if (!featureId || !selected || !rationale) {
+        throw new Error(
+          'Usage: solution-explore select <feature> --candidate A --rationale "…" [--merge B] [--cleanup]',
+        );
+      }
+
+      const result = await recordExplorationDecision(cwd, featureId, {
+        selected,
+        mergedFrom: mergedFrom || null,
+        rationale,
+        cleanup,
+      });
+
+      if (json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(`Recorded decision for ${result.featureId}: ${result.selected}`);
+        if (result.mergedFrom) {
+          console.log(`  Merged from: ${result.mergedFrom}`);
+        }
+        if (result.cleanup?.length) {
+          for (const item of result.cleanup) {
+            console.log(`  Cleanup ${path.basename(item.path)}: ${item.status}`);
+          }
+        }
+      }
+    } else {
+      throw new Error(
+        "Usage: solution-explore init | status | validate | select",
+      );
+    }
+  } catch (err) {
+    console.error(`❌ ${err.message}`);
+    process.exit(1);
+  }
 } else if (command === "classify-change") {
   try {
     let json = false;

package/lib/constants.js

@@ -77,6 +77,7 @@ export const SKILL_ASSETS = [
 /** @type {{ file: string, remotePath: string }[]} */
 export const REFERENCE_ASSETS = [
   { file: "explore.md", remotePath: "skills/references/explore.md" },
+  { file: "solution-exploration.md", remotePath: "skills/references/solution-exploration.md" },
   { file: "project-init.md", remotePath: "skills/references/project-init.md" },
   { file: "constitution.md", remotePath: "skills/references/constitution.md" },
   { file: "specify.md", remotePath: "skills/references/specify.md" },
@@ -110,6 +111,7 @@ export const SCRIPT_ASSETS = [
   { 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" },
+  { file: "memory_search.py", remotePath: "scripts/memory_search.py" },
 ];
 
 /** @type {{ file: string, remotePath: string }[]} */

package/lib/context-guard.js

@@ -0,0 +1,340 @@
+import path from "node:path";
+
+import { loadExecutionPolicy, resolvePathCheck } from "./execution-policy.js";
+import { readFileSafe } from "./fs-utils.js";
+import { featureDir, readActiveFeatureFromState, resolveFeatureId } from "./specs-utils.js";
+import { findVerdict } from "./validation-verdict.js";
+
+const TASK_FILES = /^\s*[-*]?\s*\*{0,2}Files\*{0,2}\s*:\s*(.+)$/gim;
+
+/**
+ * @param {string} cwd
+ * @returns {Promise<{ featureId: string | null, phase: string | null }>}
+ */
+export async function readStateContext(cwd) {
+  const statePath = path.join(cwd, ".specs/STATE.md");
+  let content = "";
+
+  try {
+    content = await readFileSafe(statePath);
+  } catch {
+    return { featureId: null, phase: null };
+  }
+
+  const featureId = await readActiveFeatureFromState(cwd);
+  const phaseMatch = content.match(/^-\s*Phase:\s*(.+)$/m);
+  const phase = phaseMatch ? phaseMatch[1].trim() : null;
+
+  return { featureId, phase: phase && !/^—|-$/i.test(phase) ? phase : null };
+}
+
+/**
+ * @param {string} tasksText
+ * @returns {number}
+ */
+export function countOpenTasks(tasksText) {
+  return [...tasksText.matchAll(/^\s*[-*]\s*\[ \]\s+/gm)].length;
+}
+
+/**
+ * @param {string} tasksText
+ * @returns {Set<string>}
+ */
+export function collectTaskFilePaths(tasksText) {
+  /** @type {Set<string>} */
+  const files = new Set();
+
+  for (const match of tasksText.matchAll(TASK_FILES)) {
+    const raw = match[1].trim();
+    if (!raw || /^—|-$|none|n\/a$/i.test(raw)) {
+      continue;
+    }
+    for (const part of raw.split(/[,;]/)) {
+      const cleaned = part.trim().replace(/^`|`$/g, "");
+      if (cleaned) {
+        files.add(cleaned.replace(/\\/g, "/"));
+      }
+    }
+  }
+
+  return files;
+}
+
+/**
+ * @param {string} relativePath
+ * @param {Set<string>} approvedFiles
+ * @returns {boolean}
+ */
+export function pathInApprovedTaskFiles(relativePath, approvedFiles) {
+  if (!approvedFiles.size) {
+    return true;
+  }
+
+  const normalized = relativePath.replace(/\\/g, "/").replace(/^\.\//, "");
+  for (const approved of approvedFiles) {
+    const pattern = approved.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*/g, ".*").replace(/\*/g, "[^/]*");
+    if (new RegExp(`^${pattern}$`).test(normalized)) {
+      return true;
+    }
+    if (normalized === approved || normalized.endsWith(`/${approved}`)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * @param {string} cwd
+ * @param {{ featureId?: string }} [options]
+ * @returns {Promise<{
+ *   ok: boolean,
+ *   severity: "blocking" | "warning" | "info",
+ *   featureId: string | null,
+ *   phase: string | null,
+ *   openTasks: number,
+ *   messages: string[],
+ * }>}
+ */
+export async function evaluateExecuteContext(cwd, options = {}) {
+  const messages = [];
+  const state = await readStateContext(cwd);
+  let featureId = options.featureId ?? state.featureId;
+
+  if (!featureId) {
+    return {
+      ok: false,
+      severity: "blocking",
+      featureId: null,
+      phase: state.phase,
+      openTasks: 0,
+      messages: ["no active feature in .specs/STATE.md — run feature-init or /specify first"],
+    };
+  }
+
+  const tasksPath = path.join(featureDir(featureId, cwd), "tasks.md");
+  let tasksText = "";
+
+  try {
+    tasksText = await readFileSafe(tasksPath);
+  } catch {
+    return {
+      ok: false,
+      severity: "blocking",
+      featureId,
+      phase: state.phase,
+      openTasks: 0,
+      messages: [`tasks.md missing for active feature ${featureId}`],
+    };
+  }
+
+  const openTasks = countOpenTasks(tasksText);
+  if (openTasks === 0) {
+    messages.push("no open tasks in tasks.md — Execute may be complete; run /verify instead");
+  } else {
+    messages.push(`${openTasks} open task(s) in tasks.md`);
+  }
+
+  const severity = openTasks === 0 ? "warning" : "info";
+  return {
+    ok: openTasks > 0,
+    severity,
+    featureId,
+    phase: state.phase,
+    openTasks,
+    messages,
+  };
+}
+
+/**
+ * @param {string} cwd
+ * @param {string} relativePath
+ * @param {{ operation?: string, featureId?: string, strictFiles?: boolean }} [options]
+ */
+export async function checkBeforeEdit(cwd, relativePath, options = {}) {
+  const execute = await evaluateExecuteContext(cwd, { featureId: options.featureId });
+  const policy = await loadExecutionPolicy(cwd);
+  const pathCheck = resolvePathCheck(relativePath, policy, {
+    operation: options.operation,
+  });
+
+  /** @type {string[]} */
+  const messages = [...execute.messages];
+
+  if (!execute.ok && execute.severity === "blocking") {
+    return {
+      allowed: false,
+      exitCode: 1,
+      severity: "blocking",
+      operation: pathCheck.operation,
+      featureId: execute.featureId,
+      messages,
+    };
+  }
+
+  if (!pathCheck.allowed) {
+    messages.push(pathCheck.reason);
+    return {
+      allowed: false,
+      exitCode: pathCheck.exitCode,
+      severity: pathCheck.severity,
+      operation: pathCheck.operation,
+      featureId: execute.featureId,
+      messages,
+    };
+  }
+
+  if (options.strictFiles !== false && execute.featureId) {
+    const tasksText = await readFileSafe(
+      path.join(featureDir(execute.featureId, cwd), "tasks.md"),
+    );
+    const approved = collectTaskFilePaths(tasksText);
+    if (approved.size && !pathInApprovedTaskFiles(relativePath, approved)) {
+      messages.push("path is not listed in any task Files field — escalate or update tasks.md");
+      const mode = policy.escalation.on_scope_expansion ?? "human";
+      if (mode === "human") {
+        return {
+          allowed: false,
+          exitCode: 1,
+          severity: "blocking",
+          operation: pathCheck.operation,
+          featureId: execute.featureId,
+          messages,
+        };
+      }
+    }
+  }
+
+  if (pathCheck.severity === "warning") {
+    messages.push(pathCheck.reason);
+  }
+
+  if (!execute.ok && execute.severity === "warning") {
+    messages.push(...execute.messages);
+  }
+
+  return {
+    allowed: true,
+    exitCode: 0,
+    severity: pathCheck.severity === "warning" || execute.severity === "warning" ? "warning" : "info",
+    operation: pathCheck.operation,
+    featureId: execute.featureId,
+    messages,
+  };
+}
+
+/**
+ * @param {string} cwd
+ * @param {string} [featureRaw]
+ */
+export async function checkBeforeComplete(cwd, featureRaw) {
+  const featureId = featureRaw ? await resolveFeatureId(featureRaw, cwd) : await resolveFeatureId(undefined, cwd);
+  const dir = featureDir(featureId, cwd);
+  /** @type {string[]} */
+  const messages = [];
+
+  let tasksText = "";
+  try {
+    tasksText = await readFileSafe(path.join(dir, "tasks.md"));
+  } catch {
+    return {
+      allowed: false,
+      exitCode: 1,
+      severity: "blocking",
+      featureId,
+      messages: ["tasks.md missing — cannot claim completion"],
+    };
+  }
+
+  const openTasks = countOpenTasks(tasksText);
+  if (openTasks > 0) {
+    messages.push(`${openTasks} task(s) still open in tasks.md`);
+    return {
+      allowed: false,
+      exitCode: 1,
+      severity: "blocking",
+      featureId,
+      messages,
+    };
+  }
+
+  const validationPath = path.join(dir, "validation.md");
+  let validationText = "";
+  try {
+    validationText = await readFileSafe(validationPath);
+  } catch {
+    messages.push("validation.md missing — run independent /verify first");
+    return {
+      allowed: false,
+      exitCode: 1,
+      severity: "blocking",
+      featureId,
+      messages,
+    };
+  }
+
+  const verdict = findVerdict(validationText);
+  if (!verdict || !["PASS", "PASSED"].includes(verdict)) {
+    messages.push(verdict ? `validation verdict is ${verdict}, not PASS` : "validation.md has no PASS/FAIL verdict");
+    return {
+      allowed: false,
+      exitCode: 1,
+      severity: "blocking",
+      featureId,
+      messages,
+    };
+  }
+
+  messages.push("tasks complete and validation PASS recorded");
+  return {
+    allowed: true,
+    exitCode: 0,
+    severity: "info",
+    featureId,
+    messages,
+  };
+}
+
+/**
+ * @param {Awaited<ReturnType<typeof evaluateExecuteContext>>} context
+ * @param {{ json?: boolean }} [options]
+ */
+export function formatContextGuardStatus(context, options = {}) {
+  if (options.json) {
+    return JSON.stringify(context, null, 2);
+  }
+
+  const lines = ["Context guard status:"];
+  lines.push(`  feature: ${context.featureId ?? "(none)"}`);
+  lines.push(`  phase: ${context.phase ?? "(unknown)"}`);
+  lines.push(`  open_tasks: ${context.openTasks}`);
+  lines.push(`  execute_ready: ${context.ok ? "yes" : "no"}`);
+  for (const message of context.messages) {
+    lines.push(`  note: ${message}`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+/**
+ * @param {Awaited<ReturnType<typeof checkBeforeEdit>>} result
+ * @param {string} relativePath
+ * @param {{ json?: boolean }} [options]
+ */
+export function formatCheckBeforeEdit(result, relativePath, options = {}) {
+  if (options.json) {
+    return JSON.stringify({ path: relativePath, ...result }, null, 2);
+  }
+
+  const label = result.allowed
+    ? result.severity === "warning"
+      ? "allowed (warn)"
+      : "allowed"
+    : result.severity === "warning"
+      ? "blocked (warn)"
+      : "blocked";
+
+  const lines = [`${relativePath} [${result.operation}]: ${label}`];
+  for (const message of result.messages) {
+    lines.push(`  ${message}`);
+  }
+  return `${lines.join("\n")}\n`;
+}

package/lib/gates.js

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