@luizsantiago/spec-guardrails 3.4.0 → 3.6.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.4.x**
+npm: [`@luizsantiago/spec-guardrails`](https://www.npmjs.com/package/@luizsantiago/spec-guardrails) **3.6.x**
 
 ---
 
@@ -217,6 +217,8 @@ npx @luizsantiago/spec-guardrails install
 
 | Version | What you gain |
 | --- | --- |
+| **3.6.x** | Hybrid retrieval (`memory-retrieve`); chunk FTS; optional semantic embed |
+| **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) |

package/index.js

@@ -35,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,
@@ -93,12 +103,16 @@ Commands:
   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-index embed [--force]       Optional semantic embeddings (requires config + provider)
   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)
+  memory-search <query>              Full-text search over indexed artifact chunks (FTS5)
     [--limit N]                      Max results (default 10)
     [--json]                         Machine-readable output
+  memory-retrieve "<query>"          Hybrid retrieval (FTS + graph + optional semantic)
+    [--mode fts|hybrid|semantic]     Strategy (default: hybrid)
+    [--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
@@ -108,6 +122,22 @@ Commands:
   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
@@ -661,6 +691,141 @@ if (command === "--version" || command === "-v" || command === "version") {
     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" },
@@ -111,6 +112,9 @@ export const SCRIPT_ASSETS = [
   { 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" },
+  { file: "memory_retrieve.py", remotePath: "scripts/memory_retrieve.py" },
+  { file: "_memory_config.py", remotePath: "scripts/_memory_config.py" },
+  { file: "_memory_embed.py", remotePath: "scripts/_memory_embed.py" },
 ];
 
 /** @type {{ file: string, remotePath: string }[]} */

package/lib/gates.js

@@ -44,6 +44,7 @@ const AUX_SCRIPTS = {
   "memory-index": "memory_index.py",
   "memory-query": "memory_query.py",
   "memory-search": "memory_search.py",
+  "memory-retrieve": "memory_retrieve.py",
 };
 
 const GUARDRAILS_SCRIPTS = { ...GATE_SCRIPTS, ...AUX_SCRIPTS };

package/lib/memory-index.js

@@ -16,6 +16,42 @@ export async function rebuildMemoryIndex(options = {}) {
   return runGuardrailsScript("memory-index", ["rebuild"], { cwd });
 }
 
+/**
+ * Build optional semantic embeddings for indexed chunks.
+ *
+ * @param {{ force?: boolean, json?: boolean, cwd?: string }} [options]
+ * @returns {Promise<number>} exit code
+ */
+export async function embedMemoryIndex(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const args = ["embed"];
+  if (options.force) {
+    args.push("--force");
+  }
+  if (options.json) {
+    args.push("--json");
+  }
+  return runGuardrailsScript("memory-index", args, { cwd });
+}
+
+/**
+ * Hybrid retrieval over indexed artifacts.
+ *
+ * @param {{ query: string, mode?: string, json?: boolean, cwd?: string }} options
+ * @returns {Promise<number>} exit code
+ */
+export async function retrieveMemory(options) {
+  const cwd = options.cwd ?? process.cwd();
+  const args = [options.query];
+  if (options.mode) {
+    args.push("--mode", options.mode);
+  }
+  if (options.json) {
+    args.push("--json");
+  }
+  return runGuardrailsScript("memory-retrieve", args, { cwd });
+}
+
 /**
  * Query the knowledge graph for a bounded context package.
  *