@xera-ai/core 0.11.6 → 0.12.0

package/dist/bin/internal.js

@@ -10544,21 +10544,270 @@ async function execCmd(argv) {
   }
 }
 
+// src/bin-internal/explore-finalize.ts
+import { appendFileSync as appendFileSync3, existsSync as existsSync19, readFileSync as readFileSync16, writeFileSync as writeFileSync10 } from "fs";
+import { join as join18 } from "path";
+import { z as z7 } from "zod";
+var CATEGORY_ENUM = z7.enum([
+  "negative",
+  "boundary",
+  "state-combination",
+  "race",
+  "error-recovery",
+  "a11y",
+  "security-smell",
+  "non-functional"
+]);
+var ProposalsSchema = z7.object({
+  proposals: z7.array(z7.object({
+    id: z7.string().min(1),
+    ticketId: z7.string().min(1),
+    category: CATEGORY_ENUM,
+    severity: z7.enum(["low", "medium", "high"]),
+    title: z7.string().min(1),
+    rationale: z7.string().min(1),
+    gherkin: z7.string().min(1)
+  }))
+});
+function parseArgs4(argv) {
+  let ticket;
+  let accept;
+  for (let i = 0;i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--accept") {
+      const v = argv[++i];
+      if (v !== undefined)
+        accept = v;
+    } else if (a === "--help-stub") {} else if (a && !a.startsWith("--") && ticket === undefined) {
+      ticket = a;
+    } else {
+      return { error: `unknown flag: ${a}` };
+    }
+  }
+  if (!ticket)
+    return { error: "ticket key is required as a positional argument" };
+  if (!accept)
+    return { error: '--accept is required (comma-separated IDs, "all", or "high-only")' };
+  return { ticket, accept };
+}
+function selectProposals(all, accept) {
+  const trimmed = accept.trim();
+  if (trimmed === "all")
+    return all;
+  if (trimmed === "high-only")
+    return all.filter((p) => p.severity === "high");
+  const ids = new Set(trimmed.split(",").map((s) => s.trim()).filter(Boolean));
+  if (ids.size === 0)
+    return { error: "no IDs supplied" };
+  const picked = all.filter((p) => ids.has(p.id));
+  const found = new Set(picked.map((p) => p.id));
+  const missing = [...ids].filter((id) => !found.has(id));
+  if (missing.length > 0)
+    return { error: `unknown proposal IDs: ${missing.join(", ")}` };
+  return picked;
+}
+function ensureFeatureHeader(ticketDir, ticket) {
+  const explorePath = join18(ticketDir, "explore.feature");
+  if (existsSync19(explorePath))
+    return explorePath;
+  const testFeaturePath = join18(ticketDir, "test.feature");
+  let header;
+  if (existsSync19(testFeaturePath)) {
+    const testContent = readFileSync16(testFeaturePath, "utf8");
+    const firstFeatureMatch = testContent.match(/^Feature:.*$/m);
+    header = firstFeatureMatch ? `${firstFeatureMatch[0]} (adversarial)
+  Adversarial scenarios beyond the acceptance criteria.
+  Generated by /xera-explore \u2014 review before merging into test.feature.
+
+` : `Feature: ${ticket} adversarial
+
+`;
+  } else {
+    header = `Feature: ${ticket} adversarial
+  Adversarial scenarios beyond the acceptance criteria.
+  Generated by /xera-explore \u2014 review before merging into test.feature.
+
+`;
+  }
+  writeFileSync10(explorePath, header);
+  return explorePath;
+}
+function formatScenario(p) {
+  const tags = `@adversarial @adversarial-${p.category} @severity-${p.severity}`;
+  const rationaleComment = `  # ${p.rationale}`;
+  const indented = p.gherkin.split(`
+`).map((line) => line.startsWith("Scenario:") ? `  ${line}` : line ? `  ${line}` : line).join(`
+`);
+  return `
+  ${tags}
+${rationaleComment}
+${indented}
+`;
+}
+async function exploreFinalizeCmd(argv) {
+  const parsed = parseArgs4(argv);
+  if ("error" in parsed) {
+    console.error(`[explore-finalize] ${parsed.error}`);
+    return 1;
+  }
+  const cwd = process.cwd();
+  const ticketDir = join18(cwd, ".xera", parsed.ticket);
+  const proposalsPath = join18(ticketDir, "adversarial-proposals.json");
+  if (!existsSync19(proposalsPath)) {
+    console.error(`[explore-finalize] adversarial-proposals.json not found for ${parsed.ticket} \u2014 run /xera-explore Step 4 first`);
+    return 2;
+  }
+  let proposals;
+  try {
+    const raw = JSON.parse(readFileSync16(proposalsPath, "utf8"));
+    proposals = ProposalsSchema.parse(raw);
+  } catch (e) {
+    console.error(`[explore-finalize] invalid proposals JSON: ${e.message}`);
+    return 1;
+  }
+  const picked = selectProposals(proposals.proposals, parsed.accept);
+  if ("error" in picked) {
+    console.error(`[explore-finalize] ${picked.error}`);
+    return 1;
+  }
+  if (picked.length === 0) {
+    console.error("[explore-finalize] no proposals matched the --accept filter");
+    return 1;
+  }
+  const explorePath = ensureFeatureHeader(ticketDir, parsed.ticket);
+  for (const p of picked) {
+    appendFileSync3(explorePath, formatScenario(p));
+  }
+  console.log(`[explore-finalize] appended ${picked.length} scenario(s) to ${explorePath} (${picked.map((p) => p.id).join(", ")})`);
+  return 0;
+}
+
+// src/bin-internal/explore-prepare.ts
+import { existsSync as existsSync20, readFileSync as readFileSync17, writeFileSync as writeFileSync11 } from "fs";
+import { join as join19 } from "path";
+var VALID_CATEGORIES = [
+  "negative",
+  "boundary",
+  "state-combination",
+  "race",
+  "error-recovery",
+  "a11y",
+  "security-smell",
+  "non-functional"
+];
+function parseArgs5(argv) {
+  let ticket;
+  let categoriesRaw = "";
+  let userHint = "";
+  for (let i = 0;i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--categories") {
+      const v = argv[++i];
+      if (v !== undefined)
+        categoriesRaw = v;
+    } else if (a === "--user-hint") {
+      const v = argv[++i];
+      if (v !== undefined)
+        userHint = v;
+    } else if (a === "--help-stub") {} else if (a && !a.startsWith("--") && ticket === undefined) {
+      ticket = a;
+    } else {
+      return { error: `unknown flag: ${a}` };
+    }
+  }
+  if (!ticket)
+    return { error: "ticket key is required as a positional argument" };
+  const categoriesInclude = [];
+  for (const slug of categoriesRaw.split(",").map((s) => s.trim()).filter(Boolean)) {
+    if (!VALID_CATEGORIES.includes(slug)) {
+      return { error: `invalid category: ${slug}` };
+    }
+    categoriesInclude.push(slug);
+  }
+  return { ticket, categoriesInclude, userHint };
+}
+function parseStoryMd(content) {
+  const fmMatch = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!fmMatch)
+    return { summary: "", ac: [], body: content };
+  const [, fm, body] = fmMatch;
+  const summaryMatch = fm.match(/^summary:\s*(.+)$/m);
+  const summary = summaryMatch?.[1]?.trim() ?? "";
+  const ac = [];
+  const acBlock = fm.match(/^ac:\s*\n((?:\s*-\s.+\n?)+)/m);
+  if (acBlock) {
+    for (const line of acBlock[1].split(`
+`)) {
+      const m = line.match(/^\s*-\s*(.+)$/);
+      if (m)
+        ac.push(m[1].trim());
+    }
+  }
+  return { summary, ac, body: body.trim() };
+}
+async function explorePrepareCmd(argv) {
+  const parsed = parseArgs5(argv);
+  if ("error" in parsed) {
+    console.error(`[explore-prepare] ${parsed.error}`);
+    return 1;
+  }
+  const cwd = process.cwd();
+  const configPath = join19(cwd, "xera.config.ts");
+  if (!existsSync20(configPath)) {
+    console.error("[explore-prepare] xera.config.ts not found \u2014 run inside a xera project");
+    return 2;
+  }
+  const ticketDir = join19(cwd, ".xera", parsed.ticket);
+  const storyPath = join19(ticketDir, "story.md");
+  if (!existsSync20(storyPath)) {
+    console.error(`[explore-prepare] no story for ${parsed.ticket} \u2014 run /xera-fetch ${parsed.ticket} first`);
+    return 2;
+  }
+  const story = readFileSync17(storyPath, "utf8");
+  const { summary, ac, body } = parseStoryMd(story);
+  let adapter = "web";
+  const metaPath = join19(ticketDir, "meta.json");
+  if (existsSync20(metaPath)) {
+    try {
+      const meta = JSON.parse(readFileSync17(metaPath, "utf8"));
+      if (meta.adapter === "http")
+        adapter = "http";
+    } catch {}
+  }
+  const input = {
+    ticket: { id: parsed.ticket, summary, story: body, ac },
+    adapter,
+    categoriesInclude: parsed.categoriesInclude
+  };
+  const featurePath = join19(ticketDir, "test.feature");
+  if (existsSync20(featurePath))
+    input.existingFeature = readFileSync17(featurePath, "utf8");
+  const specPath = join19(ticketDir, "spec.ts");
+  if (existsSync20(specPath))
+    input.existingSpec = readFileSync17(specPath, "utf8");
+  if (parsed.userHint)
+    input.userHint = parsed.userHint;
+  const outPath = join19(ticketDir, "adversarial-input.json");
+  writeFileSync11(outPath, JSON.stringify(input, null, 2));
+  console.log(`[explore-prepare] wrote ${outPath}`);
+  return 0;
+}
+
 // src/bin-internal/fetch.ts
-import { mkdirSync as mkdirSync12, writeFileSync as writeFileSync11 } from "fs";
+import { mkdirSync as mkdirSync12, writeFileSync as writeFileSync13 } from "fs";
 import { dirname as dirname5 } from "path";
 
 // src/artifact/hash.ts
 import { createHash as createHash4 } from "crypto";
-import { existsSync as existsSync19, readFileSync as readFileSync16 } from "fs";
+import { existsSync as existsSync21, readFileSync as readFileSync18 } from "fs";
 function hashString(s) {
   return `sha256:${createHash4("sha256").update(s).digest("hex")}`;
 }
 function hashFile(path) {
-  return hashString(readFileSync16(path, "utf8"));
+  return hashString(readFileSync18(path, "utf8"));
 }
 function hashFileIfExists(path) {
-  if (!existsSync19(path))
+  if (!existsSync21(path))
     return null;
   return hashFile(path);
 }
@@ -10567,33 +10816,33 @@ function hashFileIfExists(path) {
 init_paths2();
 
 // src/jira/mcp-backend.ts
-import { existsSync as existsSync20, mkdirSync as mkdirSync11, readFileSync as readFileSync17, writeFileSync as writeFileSync10 } from "fs";
+import { existsSync as existsSync22, mkdirSync as mkdirSync11, readFileSync as readFileSync19, writeFileSync as writeFileSync12 } from "fs";
 import { tmpdir } from "os";
-import { join as join18 } from "path";
+import { join as join20 } from "path";
 var MCP_ENV = "XERA_MCP_JIRA";
 async function createMcpBackend(_baseUrl) {
   if (process.env[MCP_ENV] !== "1")
     return null;
-  const tmpDir = join18(tmpdir(), "xera-mcp");
+  const tmpDir = join20(tmpdir(), "xera-mcp");
   mkdirSync11(tmpDir, { recursive: true });
   return {
     backend: "mcp",
     async fetchTicket(key, _fields) {
-      const cachePath = join18(tmpDir, `${key}.json`);
-      if (!existsSync20(cachePath)) {
+      const cachePath = join20(tmpDir, `${key}.json`);
+      if (!existsSync22(cachePath)) {
         throw new Error(`MCP-mode fetch requires the skill to first call mcp__atlassian__getJiraIssue and write ${cachePath}. ` + `If you are running this directly, unset ${MCP_ENV} to use REST.`);
       }
-      const parsed = JSON.parse(readFileSync17(cachePath, "utf8"));
+      const parsed = JSON.parse(readFileSync19(cachePath, "utf8"));
       return parsed;
     },
     async postComment(key, body) {
-      const outPath = join18(tmpDir, `${key}.comment.json`);
-      writeFileSync10(outPath, JSON.stringify({ key, body }));
+      const outPath = join20(tmpDir, `${key}.comment.json`);
+      writeFileSync12(outPath, JSON.stringify({ key, body }));
       return { id: "mcp-pending" };
     },
     async transitionStatus(key, statusName) {
-      const outPath = join18(tmpDir, `${key}.transition.json`);
-      writeFileSync10(outPath, JSON.stringify({ key, statusName }));
+      const outPath = join20(tmpDir, `${key}.transition.json`);
+      writeFileSync12(outPath, JSON.stringify({ key, statusName }));
     },
     async listFields(_sampleKey) {
       throw new Error("listFields is REST-only; init flow uses REST for field discovery.");
@@ -10747,7 +10996,7 @@ async function fetchCmd(argv, opts = {}) {
   const acLines = parseAcLines(t.acceptanceCriteria);
   const full = renderStory(t.key, t.summary, storyHash, acLines, body);
   mkdirSync12(dirname5(paths.storyPath), { recursive: true });
-  writeFileSync11(paths.storyPath, full);
+  writeFileSync13(paths.storyPath, full);
   const existing = readMeta(paths.metaPath);
   writeMeta(paths.metaPath, {
     ticket,
@@ -10808,20 +11057,20 @@ function renderStory(key, summary, storyHash, acLines, body) {
 }
 
 // src/bin-internal/fill-gap-finalize.ts
-import { existsSync as existsSync21, mkdirSync as mkdirSync13, readFileSync as readFileSync18, writeFileSync as writeFileSync12 } from "fs";
-import { join as join19 } from "path";
-import { z as z7 } from "zod";
-var ProposalsSchema = z7.object({
-  proposals: z7.array(z7.object({
-    id: z7.string().min(1),
-    ticketId: z7.string().min(1),
-    title: z7.string().min(1),
-    rationale: z7.string().min(1),
-    gherkin: z7.string().min(1),
-    satisfiesAcs: z7.array(z7.number().int().nonnegative())
+import { existsSync as existsSync23, mkdirSync as mkdirSync13, readFileSync as readFileSync20, writeFileSync as writeFileSync14 } from "fs";
+import { join as join21 } from "path";
+import { z as z8 } from "zod";
+var ProposalsSchema2 = z8.object({
+  proposals: z8.array(z8.object({
+    id: z8.string().min(1),
+    ticketId: z8.string().min(1),
+    title: z8.string().min(1),
+    rationale: z8.string().min(1),
+    gherkin: z8.string().min(1),
+    satisfiesAcs: z8.array(z8.number().int().nonnegative())
   }))
 });
-function parseArgs4(argv) {
+function parseArgs6(argv) {
   let accept;
   let ticket;
   let source;
@@ -10871,21 +11120,21 @@ function formatDraft(ticketId, proposal) {
 }
 async function fillGapFinalizeCmd(argv) {
   if (argv.includes("--help-stub")) {}
-  const parsed = parseArgs4(argv);
+  const parsed = parseArgs6(argv);
   if ("error" in parsed) {
     console.error(`[fill-gap-finalize] ${parsed.error}`);
     return 1;
   }
   const cwd = process.cwd();
-  const sourcePath = parsed.source ?? join19(cwd, ".xera/coverage/proposals.json");
-  if (!existsSync21(sourcePath)) {
+  const sourcePath = parsed.source ?? join21(cwd, ".xera/coverage/proposals.json");
+  if (!existsSync23(sourcePath)) {
     console.error(`[fill-gap-finalize] source not found: ${sourcePath}`);
     return 2;
   }
   let proposals;
   try {
-    const raw = JSON.parse(readFileSync18(sourcePath, "utf8"));
-    proposals = ProposalsSchema.parse(raw);
+    const raw = JSON.parse(readFileSync20(sourcePath, "utf8"));
+    proposals = ProposalsSchema2.parse(raw);
   } catch (e) {
     console.error(`[fill-gap-finalize] invalid proposals: ${e.message}`);
     return 2;
@@ -10895,22 +11144,22 @@ async function fillGapFinalizeCmd(argv) {
     console.error(`[fill-gap-finalize] proposal id "${parsed.accept}" not in source`);
     return 2;
   }
-  const ticketDir = join19(cwd, ".xera", parsed.ticket);
+  const ticketDir = join21(cwd, ".xera", parsed.ticket);
   mkdirSync13(ticketDir, { recursive: true });
-  const draftPath = join19(ticketDir, "feature.draft.md");
-  if (existsSync21(draftPath) && !parsed.force) {
+  const draftPath = join21(ticketDir, "feature.draft.md");
+  if (existsSync23(draftPath) && !parsed.force) {
     console.error(`[fill-gap-finalize] ${draftPath} exists; pass --force to overwrite`);
     return 3;
   }
-  writeFileSync12(draftPath, formatDraft(parsed.ticket, proposal));
+  writeFileSync14(draftPath, formatDraft(parsed.ticket, proposal));
   return 0;
 }
 
 // src/bin-internal/fill-gap-prepare.ts
 init_store();
-import { mkdirSync as mkdirSync14, writeFileSync as writeFileSync13 } from "fs";
-import { join as join20 } from "path";
-function parseArgs5(argv) {
+import { mkdirSync as mkdirSync14, writeFileSync as writeFileSync15 } from "fs";
+import { join as join22 } from "path";
+function parseArgs7(argv) {
   const args = {};
   for (let i = 0;i < argv.length; i++) {
     const a = argv[i];
@@ -10976,7 +11225,7 @@ function buildTicketContext(snap, ticketId) {
   };
 }
 async function fillGapPrepareCmd(argv) {
-  const parsed = parseArgs5(argv);
+  const parsed = parseArgs7(argv);
   if ("error" in parsed) {
     console.error(`[fill-gap-prepare] ${parsed.error}`);
     return 1;
@@ -11000,9 +11249,9 @@ async function fillGapPrepareCmd(argv) {
       return 2;
     }
   }
-  const outDir = parsed.outputDir ?? join20(cwd, ".xera/coverage", scope);
+  const outDir = parsed.outputDir ?? join22(cwd, ".xera/coverage", scope);
   mkdirSync14(outDir, { recursive: true });
-  writeFileSync13(join20(outDir, "context.json"), JSON.stringify(context, null, 2));
+  writeFileSync15(join22(outDir, "context.json"), JSON.stringify(context, null, 2));
   return 0;
 }
 
@@ -11012,18 +11261,18 @@ init_graph_backfill();
 // src/graph/enrich.ts
 init_store();
 init_ulid();
-import { existsSync as existsSync22, readFileSync as readFileSync19, unlinkSync as unlinkSync2 } from "fs";
-import { join as join21 } from "path";
-import { z as z8 } from "zod";
+import { existsSync as existsSync24, readFileSync as readFileSync21, unlinkSync as unlinkSync2 } from "fs";
+import { join as join23 } from "path";
+import { z as z9 } from "zod";
 var MAX_SIMILAR_EDGES = 10;
 var MIN_CONFIDENCE = 0.7;
-var SimilarEntrySchema = z8.object({
-  ticketId: z8.string().regex(/^[A-Z][A-Z0-9]*-\d+$/),
-  confidence: z8.number(),
-  reason: z8.string()
+var SimilarEntrySchema = z9.object({
+  ticketId: z9.string().regex(/^[A-Z][A-Z0-9]*-\d+$/),
+  confidence: z9.number(),
+  reason: z9.string()
 });
-var EnrichmentInputSchema = z8.object({
-  similar: z8.array(SimilarEntrySchema)
+var EnrichmentInputSchema = z9.object({
+  similar: z9.array(SimilarEntrySchema)
 });
 var nowIso3 = () => new Date().toISOString();
 var mk2 = (actor, type, payload) => ({
@@ -11042,11 +11291,11 @@ async function enrichTicket(repoRoot, ticketId, opts) {
   if (snapshot.tickets[ticketId].enrichedAt && !opts.force) {
     return { ticketId, similarCount: 0, enrichedAt: snapshot.tickets[ticketId].enrichedAt };
   }
-  const inputPath = join21(repoRoot, ".xera", ticketId, "enrichment-input.json");
-  if (!existsSync22(inputPath)) {
+  const inputPath = join23(repoRoot, ".xera", ticketId, "enrichment-input.json");
+  if (!existsSync24(inputPath)) {
     throw new Error(`enrichment-input.json not found at ${inputPath}`);
   }
-  const raw = JSON.parse(readFileSync19(inputPath, "utf8"));
+  const raw = JSON.parse(readFileSync21(inputPath, "utf8"));
   const parsed = EnrichmentInputSchema.safeParse(raw);
   if (!parsed.success) {
     throw new Error(`invalid enrichment-input.json: ${parsed.error.message}`);
@@ -11151,12 +11400,12 @@ async function graphQueryCmd(argv) {
 init_graph_record();
 
 // src/bin-internal/graph-render.ts
-import { existsSync as existsSync23, mkdirSync as mkdirSync15, readFileSync as readFileSync21, renameSync as renameSync2, writeFileSync as writeFileSync14 } from "fs";
-import { dirname as dirname7, join as join23 } from "path";
+import { existsSync as existsSync25, mkdirSync as mkdirSync15, readFileSync as readFileSync23, renameSync as renameSync2, writeFileSync as writeFileSync16 } from "fs";
+import { dirname as dirname7, join as join25 } from "path";
 
 // src/graph/render.ts
-import { readFileSync as readFileSync20 } from "fs";
-import { dirname as dirname6, join as join22 } from "path";
+import { readFileSync as readFileSync22 } from "fs";
+import { dirname as dirname6, join as join24 } from "path";
 import { fileURLToPath } from "url";
 var COLORS = {
   ticket: "#3B82F6",
@@ -11375,9 +11624,9 @@ function transformForVisNetwork(snap, opts) {
 }
 var __filename2 = fileURLToPath(import.meta.url);
 var __dirname2 = dirname6(__filename2);
-var TEMPLATES_DIR = join22(__dirname2, "templates");
+var TEMPLATES_DIR = join24(__dirname2, "templates");
 function loadTemplate(name) {
-  return readFileSync20(join22(TEMPLATES_DIR, name), "utf8");
+  return readFileSync22(join24(TEMPLATES_DIR, name), "utf8");
 }
 function statsToHuman(s) {
   return `${s.tickets} tickets \xB7 ${s.scenarios} scenarios \xB7 ${s.poms} POMs \xB7 ${s.edges} edges`;
@@ -11429,7 +11678,7 @@ async function graphRenderCmd(argv) {
       includeCoverage = true;
   }
   const repoRoot = process.cwd();
-  const finalPath = outPath ?? join23(repoRoot, ".xera/graph.html");
+  const finalPath = outPath ?? join25(repoRoot, ".xera/graph.html");
   const events = loadAllEvents(repoRoot);
   const snap = deriveSnapshot(events);
   const totalNodeCount = Object.keys(snap.tickets).length + Object.keys(snap.scenarios).length + Object.keys(snap.poms).length + Object.keys(snap.areas).length;
@@ -11437,7 +11686,7 @@ async function graphRenderCmd(argv) {
   if (performanceMode === "text-fallback") {
     const txtPath = finalPath.replace(/\.html$/, ".txt");
     mkdirSync15(dirname7(txtPath), { recursive: true });
-    writeFileSync14(txtPath, `Graph too large for HTML viewer (${totalNodeCount} nodes). Use 'xera:graph-query --format text' instead.
+    writeFileSync16(txtPath, `Graph too large for HTML viewer (${totalNodeCount} nodes). Use 'xera:graph-query --format text' instead.
 `);
     console.log(`[graph-render] graph too large (${totalNodeCount} nodes); wrote ${txtPath}`);
     return 0;
@@ -11449,9 +11698,9 @@ async function graphRenderCmd(argv) {
     opts.since = since;
   let coverage;
   if (includeCoverage) {
-    const reportPath = join23(repoRoot, ".xera/coverage/report.json");
-    if (existsSync23(reportPath)) {
-      const report = JSON.parse(readFileSync21(reportPath, "utf8"));
+    const reportPath = join25(repoRoot, ".xera/coverage/report.json");
+    if (existsSync25(reportPath)) {
+      const report = JSON.parse(readFileSync23(reportPath, "utf8"));
       const snapshots = events.filter((e) => e.type === "coverage.snapshot").map((e) => e.payload);
       coverage = { report, snapshots };
     } else {
@@ -11469,7 +11718,7 @@ async function graphRenderCmd(argv) {
   const html = renderHtml(renderInput);
   mkdirSync15(dirname7(finalPath), { recursive: true });
   const tmpPath = `${finalPath}.tmp`;
-  writeFileSync14(tmpPath, html);
+  writeFileSync16(tmpPath, html);
   renameSync2(tmpPath, finalPath);
   console.log(`[graph-render] wrote ${finalPath} (${data.stats.tickets} tickets \xB7 ${data.stats.scenarios} scenarios \xB7 ${html.length} bytes)`);
   return 0;
@@ -11500,8 +11749,8 @@ async function graphSnapshotCmd(argv) {
 }
 
 // src/bin-internal/heal-prepare.ts
-import { existsSync as existsSync24, readdirSync as readdirSync6, readFileSync as readFileSync22, writeFileSync as writeFileSync15 } from "fs";
-import { join as join24 } from "path";
+import { existsSync as existsSync26, readdirSync as readdirSync6, readFileSync as readFileSync24, writeFileSync as writeFileSync17 } from "fs";
+import { join as join26 } from "path";
 import { scrubFreeText } from "@xera-ai/web";
 
 // ../../node_modules/fflate/esm/index.mjs
@@ -11848,15 +12097,15 @@ function strFromU8(dat, latin1) {
 var slzh = function(d, b) {
   return b + 30 + b2(d, b + 26) + b2(d, b + 28);
 };
-var zh = function(d, b, z9) {
+var zh = function(d, b, z10) {
   var fnl = b2(d, b + 28), efl = b2(d, b + 30), fn = strFromU8(d.subarray(b + 46, b + 46 + fnl), !(b2(d, b + 8) & 2048)), es = b + 46 + fnl;
-  var _a2 = z64hs(d, es, efl, z9, b4(d, b + 20), b4(d, b + 24), b4(d, b + 42)), sc = _a2[0], su = _a2[1], off = _a2[2];
+  var _a2 = z64hs(d, es, efl, z10, b4(d, b + 20), b4(d, b + 24), b4(d, b + 42)), sc = _a2[0], su = _a2[1], off = _a2[2];
   return [b2(d, b + 10), sc, su, fn, es + efl + b2(d, b + 32), off];
 };
-var z64hs = function(d, b, l, z9, sc, su, off) {
+var z64hs = function(d, b, l, z10, sc, su, off) {
   var nsc = sc == 4294967295, nsu = su == 4294967295, noff = off == 4294967295, e = b + l;
   var nf = nsc + nsu + noff;
-  if (z9 && nf) {
+  if (z10 && nf) {
     for (;b + 4 < e; b += 4 + b2(d, b + 2)) {
       if (b2(d, b) == 1) {
         return [
@@ -11867,7 +12116,7 @@ var z64hs = function(d, b, l, z9, sc, su, off) {
         ];
       }
     }
-    if (z9 < 2)
+    if (z10 < 2)
       err(13);
   }
   return [sc, su, off, 0];
@@ -11883,18 +12132,18 @@ function unzipSync(data, opts) {
   if (!c)
     return {};
   var o = b4(data, e + 16);
-  var z9 = b4(data, e - 20) == 117853008;
-  if (z9) {
+  var z10 = b4(data, e - 20) == 117853008;
+  if (z10) {
     var ze = b4(data, e - 12);
-    z9 = b4(data, ze) == 101075792;
-    if (z9) {
+    z10 = b4(data, ze) == 101075792;
+    if (z10) {
       c = b4(data, ze + 32);
       o = b4(data, ze + 48);
     }
   }
   var fltr = opts && opts.filter;
   for (var i2 = 0;i2 < c; ++i2) {
-    var _a2 = zh(data, o, z9), c_2 = _a2[0], sc = _a2[1], su = _a2[2], fn = _a2[3], no = _a2[4], off = _a2[5], b = slzh(data, off);
+    var _a2 = zh(data, o, z10), c_2 = _a2[0], sc = _a2[1], su = _a2[2], fn = _a2[3], no = _a2[4], off = _a2[5], b = slzh(data, off);
     o = no;
     if (!fltr || fltr({
       name: fn,
@@ -11930,9 +12179,9 @@ function classifyKind(raw) {
   return "other";
 }
 function extractDomSnapshot(tracePath) {
-  if (!existsSync24(tracePath))
+  if (!existsSync26(tracePath))
     return "";
-  const buf = readFileSync22(tracePath);
+  const buf = readFileSync24(tracePath);
   const entries = unzipSync(buf);
   const traceKey = Object.keys(entries).find((name) => name.endsWith(".trace"));
   let chosenKey = null;
@@ -11980,16 +12229,16 @@ function extractDomSnapshot(tracePath) {
   return scrubFreeText(html);
 }
 function findPomLine(ticketDir, rawLocator) {
-  const pomDir = join24(ticketDir, "page-objects");
+  const pomDir = join26(ticketDir, "page-objects");
   const candidates = [];
-  if (existsSync24(pomDir)) {
+  if (existsSync26(pomDir)) {
     for (const name of readdirSync6(pomDir)) {
       if (name.endsWith(".ts"))
-        candidates.push(join24(pomDir, name));
+        candidates.push(join26(pomDir, name));
     }
   }
   for (const file of candidates) {
-    const text = readFileSync22(file, "utf8");
+    const text = readFileSync24(file, "utf8");
     const lines = text.split(`
 `);
     for (let i2 = 0;i2 < lines.length; i2++) {
@@ -12027,13 +12276,13 @@ function findGherkinStep(featureText, rawLocator) {
 }
 function healPrepare(repoRoot, ticket, runId, scenarioName) {
   const paths = resolveArtifactPaths(repoRoot, ticket);
-  const classifierPath = join24(paths.ticketDir, "classifier-input.json");
-  const classifier = JSON.parse(readFileSync22(classifierPath, "utf8"));
+  const classifierPath = join26(paths.ticketDir, "classifier-input.json");
+  const classifier = JSON.parse(readFileSync24(classifierPath, "utf8"));
   const cls = classifier.scenarios.find((s) => s.name === scenarioName);
   if (!cls)
     throw new Error(`scenario not found in classifier-input: "${scenarioName}"`);
-  const runDir = join24(paths.runsDir, runId);
-  const normalized = JSON.parse(readFileSync22(join24(runDir, "normalized.json"), "utf8"));
+  const runDir = join26(paths.runsDir, runId);
+  const normalized = JSON.parse(readFileSync24(join26(runDir, "normalized.json"), "utf8"));
   const normSc = normalized.scenarios.find((s) => s.name === scenarioName);
   if (!normSc?.failure)
     throw new Error(`no failure recorded for scenario "${scenarioName}"`);
@@ -12044,9 +12293,9 @@ function healPrepare(repoRoot, ticket, runId, scenarioName) {
   const raw = m[1].trim();
   const kind = classifyKind(raw);
   const pomLoc = findPomLine(paths.ticketDir, raw);
-  const featureText = readFileSync22(paths.featurePath, "utf8");
+  const featureText = readFileSync24(paths.featurePath, "utf8");
   const gherkinStep = findGherkinStep(featureText, raw);
-  const domSnapshotAtFailure = extractDomSnapshot(join24(runDir, "trace.zip"));
+  const domSnapshotAtFailure = extractDomSnapshot(join26(runDir, "trace.zip"));
   return {
     ticket,
     runId,
@@ -12066,8 +12315,8 @@ async function healPrepareCmd(argv) {
   try {
     const result = healPrepare(process.cwd(), ticket, runId, scenarioName);
     const paths = resolveArtifactPaths(process.cwd(), ticket);
-    const outPath = join24(paths.runsDir, runId, "heal-input.json");
-    writeFileSync15(outPath, JSON.stringify(result, null, 2));
+    const outPath = join26(paths.runsDir, runId, "heal-input.json");
+    writeFileSync17(outPath, JSON.stringify(result, null, 2));
     console.log(`[xera:heal-prepare] wrote ${outPath}`);
     return 0;
   } catch (err2) {
@@ -12077,8 +12326,8 @@ async function healPrepareCmd(argv) {
 }
 
 // src/bin-internal/impact-prepare.ts
-import { mkdirSync as mkdirSync16, writeFileSync as writeFileSync16 } from "fs";
-import { join as join25 } from "path";
+import { mkdirSync as mkdirSync16, writeFileSync as writeFileSync18 } from "fs";
+import { join as join27 } from "path";
 
 // src/graph/impact.ts
 var PRIORITY_WEIGHT = { p0: 3, p1: 2, p2: 1 };
@@ -12328,11 +12577,11 @@ async function impactPrepareCmd(argv) {
     scenarios,
     generatedAt: new Date().toISOString()
   };
-  const impactDir = join25(repoRoot, ".xera/impact");
+  const impactDir = join27(repoRoot, ".xera/impact");
   mkdirSync16(impactDir, { recursive: true });
-  writeFileSync16(join25(impactDir, `${ticket}.json`), JSON.stringify(report, null, 2));
+  writeFileSync18(join27(impactDir, `${ticket}.json`), JSON.stringify(report, null, 2));
   if (!quiet) {
-    writeFileSync16(join25(impactDir, `${ticket}.md`), renderImpactMarkdown(report));
+    writeFileSync18(join27(impactDir, `${ticket}.md`), renderImpactMarkdown(report));
   }
   return 0;
 }
@@ -12358,8 +12607,8 @@ async function lintCmd(argv) {
 }
 
 // src/bin-internal/normalize.ts
-import { existsSync as existsSync25, readdirSync as readdirSync7 } from "fs";
-import { join as join26 } from "path";
+import { existsSync as existsSync27, readdirSync as readdirSync7 } from "fs";
+import { join as join28 } from "path";
 init_paths2();
 async function normalizeCmd(argv) {
   const ticket = argv[0];
@@ -12374,8 +12623,8 @@ async function normalizeCmd(argv) {
     console.error("[xera:normalize] no run found");
     return 1;
   }
-  const runDir = join26(paths.runsDir, runId);
-  if (!existsSync25(runDir)) {
+  const runDir = join28(paths.runsDir, runId);
+  if (!existsSync27(runDir)) {
     console.error(`[xera:normalize] runs/${runId} missing`);
     return 1;
   }
@@ -12395,14 +12644,14 @@ async function normalizeCmd(argv) {
 
 // src/bin-internal/post.ts
 init_paths2();
-import { existsSync as existsSync27, readFileSync as readFileSync24 } from "fs";
-import { join as join27 } from "path";
+import { existsSync as existsSync29, readFileSync as readFileSync26 } from "fs";
+import { join as join29 } from "path";
 
 // src/artifact/status.ts
-import { existsSync as existsSync26, mkdirSync as mkdirSync17, readFileSync as readFileSync23, writeFileSync as writeFileSync17 } from "fs";
+import { existsSync as existsSync28, mkdirSync as mkdirSync17, readFileSync as readFileSync25, writeFileSync as writeFileSync19 } from "fs";
 import { dirname as dirname8 } from "path";
-import { z as z9 } from "zod";
-var ClassificationEnum = z9.enum([
+import { z as z10 } from "zod";
+var ClassificationEnum = z10.enum([
   "PASS",
   "REAL_BUG",
   "SELECTOR_DRIFT",
@@ -12413,37 +12662,37 @@ var ClassificationEnum = z9.enum([
   "RATE_LIMITED",
   "AUTH_EXPIRED"
 ]);
-var ResultEnum = z9.enum(["PASS", "FAIL"]);
-var ConfidenceEnum = z9.enum(["low", "medium", "high"]);
-var HistoryEntrySchema = z9.object({
-  ts: z9.string(),
+var ResultEnum = z10.enum(["PASS", "FAIL"]);
+var ConfidenceEnum = z10.enum(["low", "medium", "high"]);
+var HistoryEntrySchema = z10.object({
+  ts: z10.string(),
   result: ResultEnum,
   class: ClassificationEnum
 });
-var StatusJsonSchema = z9.object({
-  ticket: z9.string(),
-  lastRun: z9.string(),
+var StatusJsonSchema = z10.object({
+  ticket: z10.string(),
+  lastRun: z10.string(),
   result: ResultEnum,
   classification: ClassificationEnum,
   confidence: ConfidenceEnum,
-  scenarios: z9.object({
-    total: z9.number().int().nonnegative(),
-    passed: z9.number().int().nonnegative(),
-    failed: z9.number().int().nonnegative(),
-    skipped: z9.number().int().nonnegative()
+  scenarios: z10.object({
+    total: z10.number().int().nonnegative(),
+    passed: z10.number().int().nonnegative(),
+    failed: z10.number().int().nonnegative(),
+    skipped: z10.number().int().nonnegative()
   }),
-  history: z9.array(HistoryEntrySchema).default([]),
-  last_jira_comment_id: z9.string().optional()
+  history: z10.array(HistoryEntrySchema).default([]),
+  last_jira_comment_id: z10.string().optional()
 });
 var HISTORY_CAP = 20;
 function readStatus(path) {
-  if (!existsSync26(path))
+  if (!existsSync28(path))
     return null;
-  return StatusJsonSchema.parse(JSON.parse(readFileSync23(path, "utf8")));
+  return StatusJsonSchema.parse(JSON.parse(readFileSync25(path, "utf8")));
 }
 function writeStatus(path, status) {
   mkdirSync17(dirname8(path), { recursive: true });
-  writeFileSync17(path, JSON.stringify(status, null, 2));
+  writeFileSync19(path, JSON.stringify(status, null, 2));
 }
 function appendHistory(path, entry) {
   const s = readStatus(path);
@@ -12469,12 +12718,12 @@ async function postCmd(argv) {
     return 0;
   }
   const paths = resolveArtifactPaths(cwd, ticket);
-  const draftPath = join27(paths.ticketDir, "jira-comment.draft.md");
-  if (!existsSync27(draftPath)) {
+  const draftPath = join29(paths.ticketDir, "jira-comment.draft.md");
+  if (!existsSync29(draftPath)) {
     console.error(`[xera:post] no draft at ${draftPath}; run \`xera-internal report\` first.`);
     return 1;
   }
-  const body = readFileSync24(draftPath, "utf8");
+  const body = readFileSync26(draftPath, "utf8");
   const client = await createJiraClient({
     baseUrl: config.jira.baseUrl,
     preferMcp: true,
@@ -12502,8 +12751,8 @@ async function promoteCmd(argv) {
 }
 
 // src/bin-internal/report.ts
-import { existsSync as existsSync29, readFileSync as readFileSync25, writeFileSync as writeFileSync18 } from "fs";
-import { join as join28 } from "path";
+import { existsSync as existsSync31, readFileSync as readFileSync27, writeFileSync as writeFileSync20 } from "fs";
+import { join as join30 } from "path";
 init_paths2();
 
 // src/classifier/aggregate.ts
@@ -12770,11 +13019,11 @@ xera v${input.xeraVersion} \u2022 prompts v${input.promptsVersion}`;
 }
 
 // src/reporter/status-writer.ts
-import { existsSync as existsSync28 } from "fs";
+import { existsSync as existsSync30 } from "fs";
 function writeStatusFromClassification(path, input) {
   const result = input.classification.overall === "PASS" ? "PASS" : "FAIL";
   const entry = { ts: input.runTs, result, class: input.classification.overall };
-  if (!existsSync28(path)) {
+  if (!existsSync30(path)) {
     writeStatus(path, {
       ticket: input.ticket,
       lastRun: input.runTs,
@@ -12808,22 +13057,22 @@ async function reportCmd(argv) {
   }
   const cwd = process.cwd();
   const paths = resolveArtifactPaths(cwd, ticket);
-  const input = JSON.parse(readFileSync25(inputArg.slice("--input=".length), "utf8"));
+  const input = JSON.parse(readFileSync27(inputArg.slice("--input=".length), "utf8"));
   let httpRuleOverride = null;
   const meta = readMeta(paths.metaPath);
   if (meta?.adapter === "http") {
     const config = await loadConfig(cwd);
     if (config.http) {
-      const normalizedPath = join28(paths.ticketDir, "runs", input.runId, "normalized.json");
-      if (existsSync29(normalizedPath)) {
-        const norm = JSON.parse(readFileSync25(normalizedPath, "utf8"));
+      const normalizedPath = join30(paths.ticketDir, "runs", input.runId, "normalized.json");
+      if (existsSync31(normalizedPath)) {
+        const norm = JSON.parse(readFileSync27(normalizedPath, "utf8"));
         const calls = norm.http?.calls ?? [];
         const rate = classifyRateLimited({ calls });
         if (rate)
           httpRuleOverride = rate;
         if (!httpRuleOverride) {
           const authFiles = {};
-          const httpAuthDir = join28(cwd, ".xera", ".auth", "http");
+          const httpAuthDir = join30(cwd, ".xera", ".auth", "http");
           for (const role of Object.keys(config.http.auth.roles)) {
             const entry = readAuthState(httpAuthDir, role);
             if (entry) {
@@ -12868,8 +13117,8 @@ async function reportCmd(argv) {
     confidence: "high"
   } : s) : input.scenarios;
   const aggregated = aggregateScenarios(scenariosForAggregation);
-  const decisionsPath = join28(paths.ticketDir, "runs", input.runId, "outdated-decisions.json");
-  const decisions = existsSync29(decisionsPath) ? JSON.parse(readFileSync25(decisionsPath, "utf8")) : {};
+  const decisionsPath = join30(paths.ticketDir, "runs", input.runId, "outdated-decisions.json");
+  const decisions = existsSync31(decisionsPath) ? JSON.parse(readFileSync27(decisionsPath, "utf8")) : {};
   const graph = deriveSnapshot(loadAllEvents(process.cwd()));
   const normalizeScenarioName = (name) => name.trim().toLowerCase().replace(/\s+/g, " ");
   const scenarioIdByName = {};
@@ -12917,8 +13166,8 @@ async function reportCmd(argv) {
     xeraVersion: XERA_VERSION,
     promptsVersion: PROMPTS_VERSION
   });
-  const draftPath = join28(paths.ticketDir, "jira-comment.draft.md");
-  writeFileSync18(draftPath, md);
+  const draftPath = join30(paths.ticketDir, "jira-comment.draft.md");
+  writeFileSync20(draftPath, md);
   console.log(`[xera:report] wrote status.json and ${draftPath}`);
   return 0;
 }
@@ -12989,7 +13238,7 @@ async function unlockCmd(argv) {
 
 // src/bin-internal/validate-feature.ts
 init_paths2();
-import { existsSync as existsSync30, readFileSync as readFileSync26 } from "fs";
+import { existsSync as existsSync32, readFileSync as readFileSync28 } from "fs";
 import { validateGherkin as validateGherkin2 } from "@xera-ai/web";
 async function validateFeatureCmd(argv) {
   const ticket = argv[0];
@@ -12998,11 +13247,11 @@ async function validateFeatureCmd(argv) {
     return 1;
   }
   const paths = resolveArtifactPaths(process.cwd(), ticket);
-  if (!existsSync30(paths.featurePath)) {
+  if (!existsSync32(paths.featurePath)) {
     console.error(`[xera:validate-feature] missing ${paths.featurePath}`);
     return 1;
   }
-  const r = validateGherkin2(readFileSync26(paths.featurePath, "utf8"));
+  const r = validateGherkin2(readFileSync28(paths.featurePath, "utf8"));
   if (r.ok) {
     console.log("[xera:validate-feature] ok");
     return 0;
@@ -13024,6 +13273,8 @@ var COMMANDS = {
   "eval-prepare": evalPrepareCmd,
   "eval-report": evalReportCmd,
   exec: execCmd,
+  "explore-finalize": exploreFinalizeCmd,
+  "explore-prepare": explorePrepareCmd,
   "fill-gap-finalize": fillGapFinalizeCmd,
   "fill-gap-prepare": fillGapPrepareCmd,
   fetch: fetchCmd,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xera-ai/core",
-  "version": "0.11.6",
+  "version": "0.12.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -31,8 +31,8 @@
   },
   "dependencies": {
     "zod": "4.4.3",
-    "@xera-ai/web": "^0.11.6",
-    "@xera-ai/http": "^0.11.6",
+    "@xera-ai/web": "^0.12.0",
+    "@xera-ai/http": "^0.12.0",
     "@playwright/test": "1.60.0",
     "dotenv": "^16.0.0",
     "fflate": "0.8.3",

package/src/bin-internal/explore-finalize.ts

@@ -0,0 +1,152 @@
+import { appendFileSync, existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+
+const CATEGORY_ENUM = z.enum([
+  'negative',
+  'boundary',
+  'state-combination',
+  'race',
+  'error-recovery',
+  'a11y',
+  'security-smell',
+  'non-functional',
+]);
+
+const ProposalsSchema = z.object({
+  proposals: z.array(
+    z.object({
+      id: z.string().min(1),
+      ticketId: z.string().min(1),
+      category: CATEGORY_ENUM,
+      severity: z.enum(['low', 'medium', 'high']),
+      title: z.string().min(1),
+      rationale: z.string().min(1),
+      gherkin: z.string().min(1),
+    }),
+  ),
+});
+
+type Proposals = z.infer<typeof ProposalsSchema>;
+type Proposal = Proposals['proposals'][number];
+
+interface ParsedArgs {
+  ticket: string;
+  accept: string;
+}
+
+function parseArgs(argv: string[]): ParsedArgs | { error: string } {
+  let ticket: string | undefined;
+  let accept: string | undefined;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--accept') {
+      const v = argv[++i];
+      if (v !== undefined) accept = v;
+    } else if (a === '--help-stub') {
+      /* no-op */
+    } else if (a && !a.startsWith('--') && ticket === undefined) {
+      ticket = a;
+    } else {
+      return { error: `unknown flag: ${a}` };
+    }
+  }
+  if (!ticket) return { error: 'ticket key is required as a positional argument' };
+  if (!accept)
+    return { error: '--accept is required (comma-separated IDs, "all", or "high-only")' };
+  return { ticket, accept };
+}
+
+function selectProposals(all: Proposal[], accept: string): Proposal[] | { error: string } {
+  const trimmed = accept.trim();
+  if (trimmed === 'all') return all;
+  if (trimmed === 'high-only') return all.filter((p) => p.severity === 'high');
+  const ids = new Set(
+    trimmed
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean),
+  );
+  if (ids.size === 0) return { error: 'no IDs supplied' };
+  const picked = all.filter((p) => ids.has(p.id));
+  const found = new Set(picked.map((p) => p.id));
+  const missing = [...ids].filter((id) => !found.has(id));
+  if (missing.length > 0) return { error: `unknown proposal IDs: ${missing.join(', ')}` };
+  return picked;
+}
+
+function ensureFeatureHeader(ticketDir: string, ticket: string): string {
+  const explorePath = join(ticketDir, 'explore.feature');
+  if (existsSync(explorePath)) return explorePath;
+
+  // Synthesize a Feature header. Prefer copying from test.feature if present.
+  const testFeaturePath = join(ticketDir, 'test.feature');
+  let header: string;
+  if (existsSync(testFeaturePath)) {
+    const testContent = readFileSync(testFeaturePath, 'utf8');
+    const firstFeatureMatch = testContent.match(/^Feature:.*$/m);
+    header = firstFeatureMatch
+      ? `${firstFeatureMatch[0]} (adversarial)\n  Adversarial scenarios beyond the acceptance criteria.\n  Generated by /xera-explore — review before merging into test.feature.\n\n`
+      : `Feature: ${ticket} adversarial\n\n`;
+  } else {
+    header = `Feature: ${ticket} adversarial\n  Adversarial scenarios beyond the acceptance criteria.\n  Generated by /xera-explore — review before merging into test.feature.\n\n`;
+  }
+  writeFileSync(explorePath, header);
+  return explorePath;
+}
+
+function formatScenario(p: Proposal): string {
+  const tags = `@adversarial @adversarial-${p.category} @severity-${p.severity}`;
+  const rationaleComment = `  # ${p.rationale}`;
+  const indented = p.gherkin
+    .split('\n')
+    .map((line) => (line.startsWith('Scenario:') ? `  ${line}` : line ? `  ${line}` : line))
+    .join('\n');
+  return `\n  ${tags}\n${rationaleComment}\n${indented}\n`;
+}
+
+export async function exploreFinalizeCmd(argv: string[]): Promise<number> {
+  const parsed = parseArgs(argv);
+  if ('error' in parsed) {
+    console.error(`[explore-finalize] ${parsed.error}`);
+    return 1;
+  }
+
+  const cwd = process.cwd();
+  const ticketDir = join(cwd, '.xera', parsed.ticket);
+  const proposalsPath = join(ticketDir, 'adversarial-proposals.json');
+  if (!existsSync(proposalsPath)) {
+    console.error(
+      `[explore-finalize] adversarial-proposals.json not found for ${parsed.ticket} — run /xera-explore Step 4 first`,
+    );
+    return 2;
+  }
+
+  let proposals: Proposals;
+  try {
+    const raw = JSON.parse(readFileSync(proposalsPath, 'utf8'));
+    proposals = ProposalsSchema.parse(raw);
+  } catch (e) {
+    console.error(`[explore-finalize] invalid proposals JSON: ${(e as Error).message}`);
+    return 1;
+  }
+
+  const picked = selectProposals(proposals.proposals, parsed.accept);
+  if ('error' in picked) {
+    console.error(`[explore-finalize] ${picked.error}`);
+    return 1;
+  }
+  if (picked.length === 0) {
+    console.error('[explore-finalize] no proposals matched the --accept filter');
+    return 1;
+  }
+
+  const explorePath = ensureFeatureHeader(ticketDir, parsed.ticket);
+  for (const p of picked) {
+    appendFileSync(explorePath, formatScenario(p));
+  }
+  console.log(
+    `[explore-finalize] appended ${picked.length} scenario(s) to ${explorePath} (${picked.map((p) => p.id).join(', ')})`,
+  );
+  return 0;
+}

package/src/bin-internal/explore-prepare.ts

@@ -0,0 +1,142 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const VALID_CATEGORIES = [
+  'negative',
+  'boundary',
+  'state-combination',
+  'race',
+  'error-recovery',
+  'a11y',
+  'security-smell',
+  'non-functional',
+] as const;
+
+type Category = (typeof VALID_CATEGORIES)[number];
+
+interface ParsedArgs {
+  ticket: string;
+  categoriesInclude: Category[];
+  userHint: string;
+}
+
+function parseArgs(argv: string[]): ParsedArgs | { error: string } {
+  let ticket: string | undefined;
+  let categoriesRaw = '';
+  let userHint = '';
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--categories') {
+      const v = argv[++i];
+      if (v !== undefined) categoriesRaw = v;
+    } else if (a === '--user-hint') {
+      const v = argv[++i];
+      if (v !== undefined) userHint = v;
+    } else if (a === '--help-stub') {
+      /* no-op */
+    } else if (a && !a.startsWith('--') && ticket === undefined) {
+      ticket = a;
+    } else {
+      return { error: `unknown flag: ${a}` };
+    }
+  }
+  if (!ticket) return { error: 'ticket key is required as a positional argument' };
+
+  const categoriesInclude: Category[] = [];
+  for (const slug of categoriesRaw
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean)) {
+    if (!(VALID_CATEGORIES as readonly string[]).includes(slug)) {
+      return { error: `invalid category: ${slug}` };
+    }
+    categoriesInclude.push(slug as Category);
+  }
+
+  return { ticket, categoriesInclude, userHint };
+}
+
+interface AdversarialInput {
+  ticket: { id: string; summary: string; story: string; ac: string[] };
+  existingFeature?: string;
+  existingSpec?: string;
+  adapter: 'web' | 'http';
+  categoriesInclude: Category[];
+  userHint?: string;
+}
+
+function parseStoryMd(content: string): { summary: string; ac: string[]; body: string } {
+  // story.md format: optional frontmatter with `summary:` and `ac:` (yaml-ish list),
+  // followed by the body. We do a minimal parse — full YAML is overkill here.
+  const fmMatch = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!fmMatch) return { summary: '', ac: [], body: content };
+  const [, fm, body] = fmMatch;
+  const summaryMatch = fm!.match(/^summary:\s*(.+)$/m);
+  const summary = summaryMatch?.[1]?.trim() ?? '';
+  const ac: string[] = [];
+  const acBlock = fm!.match(/^ac:\s*\n((?:\s*-\s.+\n?)+)/m);
+  if (acBlock) {
+    for (const line of acBlock[1]!.split('\n')) {
+      const m = line.match(/^\s*-\s*(.+)$/);
+      if (m) ac.push(m[1]!.trim());
+    }
+  }
+  return { summary, ac, body: body!.trim() };
+}
+
+export async function explorePrepareCmd(argv: string[]): Promise<number> {
+  const parsed = parseArgs(argv);
+  if ('error' in parsed) {
+    console.error(`[explore-prepare] ${parsed.error}`);
+    return 1;
+  }
+
+  const cwd = process.cwd();
+  const configPath = join(cwd, 'xera.config.ts');
+  if (!existsSync(configPath)) {
+    console.error('[explore-prepare] xera.config.ts not found — run inside a xera project');
+    return 2;
+  }
+
+  const ticketDir = join(cwd, '.xera', parsed.ticket);
+  const storyPath = join(ticketDir, 'story.md');
+  if (!existsSync(storyPath)) {
+    console.error(
+      `[explore-prepare] no story for ${parsed.ticket} — run /xera-fetch ${parsed.ticket} first`,
+    );
+    return 2;
+  }
+
+  const story = readFileSync(storyPath, 'utf8');
+  const { summary, ac, body } = parseStoryMd(story);
+
+  let adapter: 'web' | 'http' = 'web';
+  const metaPath = join(ticketDir, 'meta.json');
+  if (existsSync(metaPath)) {
+    try {
+      const meta = JSON.parse(readFileSync(metaPath, 'utf8')) as { adapter?: string };
+      if (meta.adapter === 'http') adapter = 'http';
+    } catch {
+      /* leave default web */
+    }
+  }
+
+  const input: AdversarialInput = {
+    ticket: { id: parsed.ticket, summary, story: body, ac },
+    adapter,
+    categoriesInclude: parsed.categoriesInclude,
+  };
+
+  const featurePath = join(ticketDir, 'test.feature');
+  if (existsSync(featurePath)) input.existingFeature = readFileSync(featurePath, 'utf8');
+
+  const specPath = join(ticketDir, 'spec.ts');
+  if (existsSync(specPath)) input.existingSpec = readFileSync(specPath, 'utf8');
+
+  if (parsed.userHint) input.userHint = parsed.userHint;
+
+  const outPath = join(ticketDir, 'adversarial-input.json');
+  writeFileSync(outPath, JSON.stringify(input, null, 2));
+  console.log(`[explore-prepare] wrote ${outPath}`);
+  return 0;
+}

package/src/bin-internal/index.ts

@@ -8,6 +8,8 @@ import { evalDeterministicCmd } from './eval-deterministic';
 import { evalPrepareCmd } from './eval-prepare';
 import { evalReportCmd } from './eval-report';
 import { execCmd } from './exec';
+import { exploreFinalizeCmd } from './explore-finalize';
+import { explorePrepareCmd } from './explore-prepare';
 import { fetchCmd } from './fetch';
 import { fillGapFinalizeCmd } from './fill-gap-finalize';
 import { fillGapPrepareCmd } from './fill-gap-prepare';
@@ -41,6 +43,8 @@ const COMMANDS: Record<string, (argv: string[]) => Promise<number>> = {
   'eval-prepare': evalPrepareCmd,
   'eval-report': evalReportCmd,
   exec: execCmd,
+  'explore-finalize': exploreFinalizeCmd,
+  'explore-prepare': explorePrepareCmd,
   'fill-gap-finalize': fillGapFinalizeCmd,
   'fill-gap-prepare': fillGapPrepareCmd,
   fetch: fetchCmd,