@xera-ai/core 0.11.6 → 0.12.1

package/dist/bin/internal.js

@@ -8559,6 +8559,7 @@ var init_graph_backfill = __esm(() => {
 
 // bin/internal.ts
 var import_dotenv = __toESM(require_main(), 1);
+import { existsSync as existsSync33 } from "fs";
 
 // src/bin-internal/ac-coverage-backfill-finalize.ts
 init_store();
@@ -8797,7 +8798,7 @@ var CoverageSchema = z3.object({
   criticalAreas: z3.array(z3.string().regex(/^[a-z0-9-]+$/)).default([]),
   autoSnapshotOnCoverage: z3.boolean().default(true)
 }).prefault({});
-var XeraConfigSchema = z3.object({
+var XeraConfigSchema = z3.strictObject({
   jira: JiraSchema,
   web: WebSchema.optional(),
   http: HttpSchema.optional(),
@@ -8852,6 +8853,46 @@ async function authSetupCmd(argv) {
   }
   const mod = await import(pathToFileURL2(authSetupScript).href);
   let exitCode = 0;
+  const shapeRequestsWeb = opts.shape === "all" || opts.shape === "web";
+  const shapeRequestsHttp = opts.shape === "all" || opts.shape === "http";
+  const explicit = opts.shape !== "all";
+  if (shapeRequestsWeb && config.web && typeof mod.web !== "function") {
+    console.error(`[xera:auth-setup] web adapter is configured in xera.config.ts but shared/auth-setup.ts is missing the \`web\` export.
+` + `                  Add: \`export const web = defineAuthSetup(async (page, role, creds) => { ... })\` \u2014 see docs/CONFIGURATION.md`);
+    exitCode = 1;
+  }
+  if (shapeRequestsHttp && config.http && typeof mod.http !== "function") {
+    console.error(`[xera:auth-setup] http adapter is configured in xera.config.ts but shared/auth-setup.ts is missing the \`http\` export.
+` + `                  Add: \`export const http = defineHttpAuthSetup(async (request, role, creds) => { ... })\` \u2014 see docs/CONFIGURATION.md`);
+    exitCode = 1;
+  }
+  if (explicit && opts.shape === "web" && !config.web) {
+    console.error(`[xera:auth-setup] --shape web requested, but xera.config.ts has no \`web\` block. Add a web: {...} block or use --shape http/all.`);
+    exitCode = 1;
+  }
+  if (explicit && opts.shape === "http" && !config.http) {
+    console.error(`[xera:auth-setup] --shape http requested, but xera.config.ts has no \`http\` block. Add an http: {...} block or use --shape web/all.`);
+    exitCode = 1;
+  }
+  if (!config.web && !config.http) {
+    console.error(`[xera:auth-setup] no \`web\` or \`http\` block found in xera.config.ts \u2014 nothing to authenticate.`);
+    exitCode = 1;
+  }
+  if (opts.role !== undefined) {
+    const webRoles = shapeRequestsWeb && config.web ? Object.keys(config.web.auth.roles) : [];
+    const httpRoles = shapeRequestsHttp && config.http ? Object.keys(config.http.auth.roles) : [];
+    const allRoles = Array.from(new Set([...webRoles, ...httpRoles]));
+    if (allRoles.length > 0 && !allRoles.includes(opts.role)) {
+      const detail = [];
+      if (webRoles.length > 0)
+        detail.push(`web roles: ${webRoles.join(", ")}`);
+      if (httpRoles.length > 0)
+        detail.push(`http roles: ${httpRoles.join(", ")}`);
+      console.error(`[xera:auth-setup] unknown role '${opts.role}' \u2014 configured roles: ${allRoles.join(", ")}
+                  (${detail.join("; ")})`);
+      return 1;
+    }
+  }
   if ((opts.shape === "all" || opts.shape === "web") && config.web && typeof mod.web === "function") {
     const webConfig = config.web;
     const envName = process.env.XERA_ENV ?? webConfig.defaultEnv;
@@ -10544,21 +10585,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 +10857,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 +11037,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 +11098,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 +11161,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 +11185,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 +11266,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 +11290,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 +11302,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 +11332,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 +11441,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 +11665,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 +11719,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 +11727,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 +11739,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 +11759,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 +11790,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 +12138,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 +12157,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 +12173,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 +12220,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 +12270,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 +12317,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 +12334,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 +12356,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 +12367,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 +12618,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 +12648,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 +12664,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 +12685,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 +12703,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 +12759,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 +12792,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 +13060,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 +13098,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 +13158,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 +13207,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 +13279,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 +13288,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 +13314,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,
@@ -13062,7 +13354,11 @@ Commands: ${Object.keys(COMMANDS).join(", ")}`);
 }
 
 // bin/internal.ts
-import_dotenv.config({ path: ".env.local" });
+if (existsSync33(".env.local")) {
+  console.error(`
+warning: .env.local detected but ignored. xera uses .env only \u2014 ` + `merge values from .env.local into .env and delete .env.local to silence this warning.
+`);
+}
 import_dotenv.config();
 var code = await run(process.argv.slice(2));
 process.exit(code);