@luizsantiago/spec-guardrails 3.4.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.4.x**
+npm: [`@luizsantiago/spec-guardrails`](https://www.npmjs.com/package/@luizsantiago/spec-guardrails) **3.5.x**
 
 ---
 
@@ -217,6 +217,7 @@ 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) |

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,
@@ -108,6 +118,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 +687,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" },

package/lib/solution-exploration.js

@@ -0,0 +1,528 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { readFileSafe } from "./fs-utils.js";
+import { featureDir, resolveFeatureId } from "./specs-utils.js";
+import {
+  cleanupWorkspaces,
+  listWorkspaces,
+  prepareWorkspaces,
+  workspacePath,
+  WORKSPACES_ROOT,
+} from "./workspace-isolation.js";
+
+export const EXPLORATION_FILENAME = "exploration.md";
+
+/** @type {readonly string[]} */
+export const COMPARISON_CRITERIA = [
+  "Spec compliance",
+  "Test results",
+  "Complexity",
+  "Maintainability",
+  "Performance",
+  "Risk",
+];
+
+/**
+ * @param {string} candidateId
+ * @returns {string}
+ */
+export function candidateWorkspaceId(candidateId) {
+  return `candidate-${candidateId}`;
+}
+
+/**
+ * @param {string} raw
+ * @returns {string}
+ */
+export function normalizeCandidateId(raw) {
+  const cleaned = raw.trim();
+  if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,15}$/.test(cleaned)) {
+    throw new Error(
+      `Invalid candidate id "${raw}" (use 1–16 alphanumeric characters, hyphen, or underscore)`,
+    );
+  }
+  return cleaned;
+}
+
+/**
+ * @param {string} featureId
+ * @param {Array<{ id: string, label: string }>} candidates
+ * @param {string} cwd
+ * @returns {string}
+ */
+export function buildExplorationMarkdown(featureId, candidates, cwd) {
+  const candidateRows = candidates
+    .map(({ id, label }) => {
+      const workspace = path
+        .join(WORKSPACES_ROOT, featureId, candidateWorkspaceId(id))
+        .replace(/\\/g, "/");
+      return `| ${id} | ${label} | ${workspace} | exploring |`;
+    })
+    .join("\n");
+
+  const headerCols = candidates.map(({ id }) => id).join(" | ");
+  const comparisonRows = COMPARISON_CRITERIA.map(
+    (criterion) => `| ${criterion} | ${candidates.map(() => "").join(" | ")} |`,
+  ).join("\n");
+
+  return `# Solution Exploration: ${featureId}
+
+## Status
+
+exploring
+
+## Candidates
+
+| Id | Label | Workspace | Status |
+| --- | --- | --- | --- |
+${candidateRows}
+
+## Comparison
+
+| Criterion | ${headerCols} |
+| --- | ${candidates.map(() => "---").join(" | ")} |
+${comparisonRows}
+
+## Decision
+
+- **Selected**: (pending)
+- **Merged from**: —
+- **Rationale**: —
+`;
+}
+
+/**
+ * @param {string} line
+ * @returns {string[] | null}
+ */
+function parseTableRow(line) {
+  const trimmed = line.trim();
+  if (!trimmed.startsWith("|") || trimmed.includes("---")) {
+    return null;
+  }
+  const cells = trimmed
+    .slice(1, trimmed.endsWith("|") ? -1 : undefined)
+    .split("|")
+    .map((cell) => cell.trim());
+  return cells.length ? cells : null;
+}
+
+/**
+ * @param {string} content
+ * @param {string} heading
+ * @returns {string[]}
+ */
+function sectionLines(content, heading) {
+  const pattern = new RegExp(`^## ${heading}\\s*$`, "m");
+  const match = pattern.exec(content);
+  if (!match || match.index === undefined) {
+    return [];
+  }
+
+  const rest = content.slice(match.index + match[0].length);
+  const nextHeading = rest.search(/^## /m);
+  const body = nextHeading === -1 ? rest : rest.slice(0, nextHeading);
+  return body.split("\n").map((line) => line.trimEnd());
+}
+
+/**
+ * @param {string} content
+ * @returns {{
+ *   status: string,
+ *   candidates: Array<{ id: string, label: string, workspace: string, status: string }>,
+ *   comparison: Record<string, Record<string, string>>,
+ *   decision: { selected: string | null, mergedFrom: string | null, rationale: string | null },
+ * }}
+ */
+export function parseExplorationMarkdown(content) {
+  const statusLines = sectionLines(content, "Status");
+  const status = statusLines.find((line) => line && !line.startsWith("#"))?.trim() ?? "";
+
+  /** @type {Array<{ id: string, label: string, workspace: string, status: string }>} */
+  const candidates = [];
+  for (const line of sectionLines(content, "Candidates")) {
+    const cells = parseTableRow(line);
+    if (!cells || cells[0] === "Id") {
+      continue;
+    }
+    if (cells.length >= 4) {
+      candidates.push({
+        id: cells[0],
+        label: cells[1],
+        workspace: cells[2],
+        status: cells[3],
+      });
+    }
+  }
+
+  /** @type {Record<string, Record<string, string>>} */
+  const comparison = {};
+  let comparisonHeaders = [];
+
+  for (const line of sectionLines(content, "Comparison")) {
+    const cells = parseTableRow(line);
+    if (!cells) {
+      continue;
+    }
+    if (cells[0] === "Criterion") {
+      comparisonHeaders = cells.slice(1);
+      continue;
+    }
+    const criterion = cells[0];
+    comparison[criterion] = {};
+    for (let i = 0; i < comparisonHeaders.length; i++) {
+      comparison[criterion][comparisonHeaders[i]] = cells[i + 1] ?? "";
+    }
+  }
+
+  const decisionLines = sectionLines(content, "Decision");
+  const decisionText = decisionLines.join("\n");
+  const selectedMatch = decisionText.match(/\*\*Selected\*\*:\s*(.+)/);
+  const mergedMatch = decisionText.match(/\*\*Merged from\*\*:\s*(.+)/);
+  const rationaleMatch = decisionText.match(/\*\*Rationale\*\*:\s*(.+)/);
+
+  const selectedRaw = selectedMatch?.[1]?.trim() ?? "";
+  const mergedRaw = mergedMatch?.[1]?.trim() ?? "";
+  const rationaleRaw = rationaleMatch?.[1]?.trim() ?? "";
+
+  return {
+    status,
+    candidates,
+    comparison,
+    decision: {
+      selected:
+        !selectedRaw || /^\(pending\)|—|-$/i.test(selectedRaw) ? null : selectedRaw,
+      mergedFrom: !mergedRaw || /^—|-$/i.test(mergedRaw) ? null : mergedRaw,
+      rationale: !rationaleRaw || /^—|-$/i.test(rationaleRaw) ? null : rationaleRaw,
+    },
+  };
+}
+
+/**
+ * @param {ReturnType<typeof parseExplorationMarkdown>} parsed
+ * @param {{ requireDecision?: boolean, allowDecided?: boolean }} [options]
+ * @returns {{ ok: boolean, severity: "blocking" | "warning", messages: string[] }}
+ */
+export function validateExploration(parsed, options = {}) {
+  const messages = [];
+
+  if (parsed.candidates.length < 2) {
+    messages.push("At least two candidates are required for solution exploration");
+  }
+
+  const candidateIds = parsed.candidates.map((item) => item.id);
+
+  for (const criterion of COMPARISON_CRITERIA) {
+    const row = parsed.comparison[criterion] ?? {};
+    for (const id of candidateIds) {
+      const value = (row[id] ?? "").trim();
+      if (!value) {
+        messages.push(`Comparison missing ${criterion} for candidate ${id}`);
+      }
+    }
+  }
+
+  if (options.requireDecision) {
+    if (!parsed.decision.selected) {
+      messages.push("Decision must name a selected candidate");
+    }
+    if (!parsed.decision.rationale) {
+      messages.push("Decision must include a rationale");
+    }
+  } else if (!options.allowDecided && parsed.decision.selected) {
+    messages.push("Exploration is already decided — create a new feature to explore again");
+  }
+
+  return {
+    ok: messages.length === 0,
+    severity: "blocking",
+    messages,
+  };
+}
+
+/**
+ * @param {string} cwd
+ * @param {string} featureId
+ * @returns {Promise<string>}
+ */
+async function readExplorationFile(cwd, featureId) {
+  const explorationPath = path.join(featureDir(featureId, cwd), EXPLORATION_FILENAME);
+  return readFileSafe(explorationPath);
+}
+
+/**
+ * @param {string} cwd
+ * @param {string} featureId
+ * @param {Array<{ id: string, label?: string }>} candidateSpecs
+ * @param {{ baseRef?: string, force?: boolean }} [options]
+ */
+export async function initExploration(cwd, featureId, candidateSpecs, options = {}) {
+  const resolvedId = await resolveFeatureId(featureId, cwd);
+  const dir = featureDir(resolvedId, cwd);
+  const specPath = path.join(dir, "spec.md");
+  const explorationPath = path.join(dir, EXPLORATION_FILENAME);
+
+  try {
+    await readFileSafe(specPath);
+  } catch {
+    throw new Error(`Approved spec required before exploration: ${specPath} not found`);
+  }
+
+  if (!options.force) {
+    try {
+      await fs.access(explorationPath);
+      throw new Error(
+        `${EXPLORATION_FILENAME} already exists for ${resolvedId} (use --force to replace)`,
+      );
+    } catch (err) {
+      if (!(err instanceof Error) || !("code" in err) || err.code !== "ENOENT") {
+        throw err;
+      }
+    }
+  }
+
+  if (candidateSpecs.length < 2) {
+    throw new Error("At least two candidates are required (e.g. --candidates A,B)");
+  }
+
+  /** @type {Array<{ id: string, label: string }>} */
+  const candidates = candidateSpecs.map((spec, index) => {
+    const id = normalizeCandidateId(spec.id);
+    const label = spec.label?.trim() || `Candidate ${id}`;
+    return { id, label };
+  });
+
+  const ids = candidates.map((item) => item.id);
+  if (new Set(ids).size !== ids.length) {
+    throw new Error("Candidate ids must be unique");
+  }
+
+  const markdown = buildExplorationMarkdown(resolvedId, candidates, cwd);
+  await fs.mkdir(dir, { recursive: true });
+  await fs.writeFile(explorationPath, markdown, "utf8");
+
+  const workspaceIds = candidates.map(({ id }) => candidateWorkspaceId(id));
+  const workspaces = await prepareWorkspaces(cwd, {
+    featureId: resolvedId,
+    taskIds: workspaceIds,
+    baseRef: options.baseRef ?? "HEAD",
+  });
+
+  return {
+    featureId: resolvedId,
+    explorationPath,
+    candidates,
+    workspaces,
+  };
+}
+
+/**
+ * @param {string} cwd
+ * @param {string} [featureId]
+ */
+export async function getExplorationStatus(cwd, featureId) {
+  const resolvedId = await resolveFeatureId(featureId, cwd);
+  const content = await readExplorationFile(cwd, resolvedId);
+  const parsed = parseExplorationMarkdown(content);
+  const workspaces = await listWorkspaces(cwd, resolvedId);
+  const candidateWorkspaces = workspaces.filter((item) => item.taskId.startsWith("candidate-"));
+
+  return {
+    featureId: resolvedId,
+    ...parsed,
+    workspaces: candidateWorkspaces,
+  };
+}
+
+/**
+ * @param {string} cwd
+ * @param {string} featureId
+ */
+export async function validateExplorationArtifact(cwd, featureId) {
+  const resolvedId = await resolveFeatureId(featureId, cwd);
+  const content = await readExplorationFile(cwd, resolvedId);
+  const parsed = parseExplorationMarkdown(content);
+  const result = validateExploration(parsed, { requireDecision: false });
+
+  return {
+    featureId: resolvedId,
+    ...parsed,
+    ...result,
+  };
+}
+
+/**
+ * @param {string} content
+ * @param {{ selected: string, mergedFrom?: string | null, rationale: string }} decision
+ * @returns {string}
+ */
+export function applyDecisionToMarkdown(content, decision) {
+  let updated = content.replace(
+    /^## Status\s*\n\s*\S+/m,
+    "## Status\n\ndecided",
+  );
+
+  updated = updated.replace(
+    /\*\*Selected\*\*:\s*.+/,
+    `**Selected**: ${decision.selected}`,
+  );
+  updated = updated.replace(
+    /\*\*Merged from\*\*:\s*.+/,
+    `**Merged from**: ${decision.mergedFrom ?? "—"}`,
+  );
+  updated = updated.replace(
+    /\*\*Rationale\*\*:\s*.+/,
+    `**Rationale**: ${decision.rationale}`,
+  );
+
+  return updated;
+}
+
+/**
+ * @param {string} cwd
+ * @param {string} featureId
+ * @param {{ selected: string, mergedFrom?: string | null, rationale: string, cleanup?: boolean }} decision
+ */
+export async function recordExplorationDecision(cwd, featureId, decision) {
+  const resolvedId = await resolveFeatureId(featureId, cwd);
+  const explorationPath = path.join(featureDir(resolvedId, cwd), EXPLORATION_FILENAME);
+  const content = await readExplorationFile(cwd, resolvedId);
+  const parsed = parseExplorationMarkdown(content);
+
+  const selected = normalizeCandidateId(decision.selected);
+  const candidateIds = new Set(parsed.candidates.map((item) => item.id));
+  if (!candidateIds.has(selected)) {
+    throw new Error(`Unknown candidate "${selected}" — expected one of: ${[...candidateIds].join(", ")}`);
+  }
+
+  let mergedFrom = decision.mergedFrom?.trim() || null;
+  if (mergedFrom) {
+    mergedFrom = normalizeCandidateId(mergedFrom);
+    if (!candidateIds.has(mergedFrom)) {
+      throw new Error(`Unknown merge candidate "${mergedFrom}"`);
+    }
+  }
+
+  const rationale = decision.rationale?.trim();
+  if (!rationale) {
+    throw new Error("Decision requires --rationale");
+  }
+
+  const comparisonCheck = validateExploration(parsed, { allowDecided: true });
+  if (!comparisonCheck.ok) {
+    throw new Error(comparisonCheck.messages.join("; "));
+  }
+
+  if (parsed.decision.selected) {
+    throw new Error("Exploration is already decided");
+  }
+
+  const updated = applyDecisionToMarkdown(content, {
+    selected,
+    mergedFrom,
+    rationale,
+  });
+  await fs.writeFile(explorationPath, updated, "utf8");
+
+  /** @type {Awaited<ReturnType<typeof cleanupWorkspaces>> | null} */
+  let cleanup = null;
+  if (decision.cleanup) {
+    const keep = new Set([candidateWorkspaceId(selected)]);
+    if (mergedFrom) {
+      keep.add(candidateWorkspaceId(mergedFrom));
+    }
+    const removeIds = parsed.candidates
+      .map((item) => candidateWorkspaceId(item.id))
+      .filter((workspaceId) => !keep.has(workspaceId));
+    if (removeIds.length) {
+      cleanup = await cleanupWorkspaces(cwd, {
+        featureId: resolvedId,
+        taskIds: removeIds,
+        force: true,
+      });
+    }
+  }
+
+  return {
+    featureId: resolvedId,
+    selected,
+    mergedFrom,
+    rationale,
+    cleanup,
+  };
+}
+
+/**
+ * @param {Awaited<ReturnType<typeof getExplorationStatus>>} status
+ * @param {{ json?: boolean }} [options]
+ */
+export function formatExplorationStatus(status, options = {}) {
+  if (options.json) {
+    return `${JSON.stringify(status, null, 2)}\n`;
+  }
+
+  const lines = [
+    `Solution exploration: ${status.featureId}`,
+    `  Status: ${status.status || "(unset)"}`,
+    "  Candidates:",
+  ];
+
+  if (!status.candidates.length) {
+    lines.push("    (none)");
+  } else {
+    for (const candidate of status.candidates) {
+      lines.push(`    ${candidate.id}: ${candidate.label} (${candidate.status})`);
+    }
+  }
+
+  if (status.decision.selected) {
+    lines.push(`  Decision: ${status.decision.selected}`);
+    if (status.decision.mergedFrom) {
+      lines.push(`  Merged from: ${status.decision.mergedFrom}`);
+    }
+  }
+
+  return `${lines.join("\n")}\n`;
+}
+
+/**
+ * @param {{ ok: boolean, messages: string[], featureId: string }} result
+ * @param {{ json?: boolean }} [options]
+ */
+export function formatExplorationValidation(result, options = {}) {
+  if (options.json) {
+    return `${JSON.stringify(result, null, 2)}\n`;
+  }
+
+  const label = result.ok ? "PASS" : "FAIL";
+  const lines = [`[solution-explore] ${label} - ${result.featureId}`];
+  for (const message of result.messages) {
+    lines.push(`  ${message}`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+/**
+ * @param {Awaited<ReturnType<typeof initExploration>>} result
+ * @param {{ json?: boolean }} [options]
+ */
+export function formatExplorationInit(result, options = {}) {
+  if (options.json) {
+    return `${JSON.stringify(result, null, 2)}\n`;
+  }
+
+  const lines = [
+    `Initialized exploration for ${result.featureId}`,
+    `  Artifact: ${result.explorationPath}`,
+    "  Candidates:",
+  ];
+  for (const candidate of result.candidates) {
+    const workspace = workspacePath(process.cwd(), result.featureId, candidateWorkspaceId(candidate.id));
+    lines.push(`    ${candidate.id}: ${candidate.label} → ${workspace}`);
+  }
+  for (const workspace of result.workspaces) {
+    lines.push(`  Workspace ${workspace.taskId}: ${workspace.status}`);
+  }
+  return `${lines.join("\n")}\n`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luizsantiago/spec-guardrails",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "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/test_adapter_registry.test.js test/test_context_guard.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/test_context_guard.test.js test/test_solution_exploration.test.js",
     "test:gates": "node test/run-gate-tests.mjs",
     "prepublishOnly": "npm test"
   },

package/skills/agent-architecture.md

@@ -50,6 +50,8 @@ Structural gates run **before** owner review, so they cannot drift when the mode
 | After parallel wave merge | `npx @luizsantiago/spec-guardrails workspace-cleanup [feature] --force` |
 | Before editing paths outside task Files | `npx @luizsantiago/spec-guardrails context-guard check-edit <path> [--op write]` |
 | Before claiming feature complete | `npx @luizsantiago/spec-guardrails context-guard check-complete [feature]` |
+| Solution exploration (explicit) | `npx @luizsantiago/spec-guardrails solution-explore init <feature> --candidates A,B` |
+| Before exploration decision | `npx @luizsantiago/spec-guardrails solution-explore validate [feature]` |
 | Retrieve related context | `npx @luizsantiago/spec-guardrails memory-search "<terms>"` |
 | On gate retry (Execute playbook) | `npx @luizsantiago/spec-guardrails execution-policy record-retry Tn` |
 | On each commit | `python3 .specs/guardrails/scripts/check_commit.py --message "<message>"` |
@@ -89,6 +91,7 @@ EXPLORE (optional) → SPECIFY → DISCUSS (conditional) → DESIGN (optional)
 | **Quick** | Alternative | `references/quick-mode.md` | — | `check_commit.py`, `validate_quick.py` |
 | **Context** | Always | `references/context-limits.md` | — | — |
 | **Sub-agents** | When batched | `references/sub-agents.md` | `task-graph-engineering.md` | — |
+| **Solution exploration** | Explicit fork | `references/solution-exploration.md` | — | `solution-explore validate` |
 | **Lessons** | On FAIL | `references/lessons.md` | — | `lessons.py` |
 
 Context is a load rule, not a pipeline phase. Read it when the session is long or the feature has more than a handful of tasks. Sub-agents is the Execute scaling protocol — offer only when the task graph needs more than one batch; see `references/sub-agents.md`. Lessons is a FAIL-path step, not a sequential phase — see `references/lessons.md`.
@@ -144,6 +147,7 @@ When in doubt, start at **Medium** and drop phases only with owner approval.
 | `.specs/features/[feature]/spec.md` | Requirements (use `NNN-slug` from `feature-init`) |
 | `.specs/features/[feature]/context.md` | Owner decisions for gray areas (only when Discuss ran) |
 | `.specs/features/[feature]/design.md` | Architecture (Complex tier) |
+| `.specs/features/[feature]/exploration.md` | Solution exploration candidates + comparison (explicit mode) |
 | `.specs/features/[feature]/tasks.md` | Atomic task breakdown |
 | `.specs/features/[feature]/task-graph.md` | Job DAG and parallel groups (when applicable) |
 | `.specs/features/[feature]/validation.md` | Independent verification report |

package/skills/references/design.md

@@ -81,6 +81,7 @@ Skipping Design is the default for Simple and Medium tiers.
 
 - No implementation code in `design.md` — interfaces and signatures only when they clarify a contract.
 - If the design reveals that the spec is wrong or incomplete, stop and update `spec.md` first; re-run the spec gate.
+- When multiple defensible implementations exist for the same spec, use explicit **solution exploration** (`references/solution-exploration.md`) before Execute — not parallel ad-hoc spikes.
 - Prefer the smallest design that satisfies the spec. Extensibility that no requirement asks for is speculation.
 
 ## Next

package/skills/references/solution-exploration.md

@@ -0,0 +1,86 @@
+# Solution Exploration
+
+Compare multiple candidate implementations from the same **approved spec** before committing to one approach. Explicit mode — not the default Execute path.
+
+## When to Use
+
+- Two or more defensible architectures or libraries for the same requirements
+- High-stakes design fork (auth strategy, persistence, messaging, language/runtime choice)
+- Owner asked to spike and compare before `/loop`
+
+## When NOT to Use
+
+- Ordinary Execute with an approved design and tasks — use `implement.md`
+- Pre-spec ideation — use `explore.md` instead
+- Quick tier (≤3 files) — use `quick-mode.md`
+
+## Prerequisites
+
+- Approved `spec.md` (`validate-spec` PASS)
+- Git repository (worktrees for isolation)
+- Owner approval to explore **multiple** implementations (higher blast radius than single-path Execute)
+
+## Outputs
+
+- `.specs/features/[feature]/exploration.md` — candidates, comparison matrix, decision
+- Isolated workspaces under `.specs/workspaces/[feature]/candidate-<id>/`
+
+## Procedure
+
+1. **Confirm the spec is approved** — run `validate-spec` if uncertain.
+2. **Initialize exploration** (owner OK required):
+   ```bash
+   npx @luizsantiago/spec-guardrails solution-explore init <feature> --candidates A,B,C
+   ```
+   Optional labels: `--labels "Redis,Postgres,Hybrid"`.
+3. **Implement each candidate in its workspace** — one candidate per worktree; no cross-contamination. Production-quality spikes only if the owner expects mergeable code; otherwise time-boxed prototypes with evidence.
+4. **Fill the comparison matrix** in `exploration.md` for every criterion:
+   - Spec compliance
+   - Test results
+   - Complexity
+   - Maintainability
+   - Performance
+   - Risk
+5. **Validate before deciding**:
+   ```bash
+   npx @luizsantiago/spec-guardrails solution-explore validate <feature>
+   ```
+6. **Record the decision** (owner picks):
+   ```bash
+   npx @luizsantiago/spec-guardrails solution-explore select <feature> \
+     --candidate A --rationale "Best spec fit and lowest operational risk"
+   ```
+   Optional merge: `--merge B`. Optional cleanup of losing worktrees: `--cleanup`.
+7. **Promote the winner** — merge chosen work into the main tree, update `design.md` / `tasks.md` if needed, then continue normal Execute on the main branch.
+
+## Rules
+
+- **Explicit opt-in** — never spawn parallel solution paths without owner approval.
+- **Same spec** — all candidates implement the same approved requirements; gaps go back to Specify.
+- **Evidence over opinion** — comparison cells cite tests, benchmarks, or concrete observations.
+- **One decision** — after `select`, exploration is closed; do not restart without a new feature or owner direction.
+- **Independent verify still applies** — `/verify` runs on the merged result, not on exploration chat summaries.
+
+## Gates and CLI
+
+| Step | Command |
+| --- | --- |
+| Init | `solution-explore init <feature> --candidates A,B` |
+| Status | `solution-explore status [feature]` |
+| Before select | `solution-explore validate [feature]` |
+| Decide | `solution-explore select <feature> --candidate A --rationale "…"` |
+
+## Anti-Patterns
+
+| Avoid | Prefer |
+| --- | --- |
+| Exploring without an approved spec | `validate-spec` then `solution-explore init` |
+| Mixing candidates in one worktree | One worktree per candidate id |
+| Skipping the comparison matrix | Fill all criteria before `select` |
+| Default parallel Execute for every feature | Solution exploration only when trade-offs are real |
+
+## Next
+
+- Decision recorded → update `design.md`, resume `tasks.md` / `implement.md`
+- Spec gaps found → `converge.md` or update `spec.md`
+- Back → `agent-architecture.md`