@soleur/opencode 0.0.0-stage → 1.0.0

package/lib/c4-from-components.ts

@@ -0,0 +1,554 @@
+// Generate a LikeC4 model from the component docs `/soleur:sync` already writes.
+//
+// WHY A RELATIONSHIP-COUNT GATE EXISTS. The dependency convention this parses is
+// EMERGENT, not specified. Until #7332 the only place it was written down was a
+// prose placeholder in the component template; nothing ever told the producing
+// side to emit a parseable form. Skouer's docs happen to use markdown links,
+// Soleur's own use prose ("None (agents are standalone)") 4 times out of 4. So
+// the failure mode this module is built around is not a crash — it is a corpus
+// that yields elements, exits 0, validates clean, and renders a diagram of
+// DISCONNECTED BOXES reported as a successful result. `assessRender` reports that
+// state as `degraded`: the docs are the defect, not the run.
+//
+// VALIDATION MIRRORS plugins/soleur/scripts/render-c4-model.sh (its DIAG_RE and
+// element-count gates), NOT c4-render.ts — except the #8861 views gate, which
+// all three writers share identically (plain-object `views` count > 0).
+// The two in-repo precedents deliberately disagree on the DIAGNOSTIC gate:
+// `c4-render.ts` refuses to key on likec4 stderr, reasoning that its wording
+// drifts across patch versions — correct for a RUNTIME save path that cannot
+// pin the CLI (its element/view COUNT gates are identical to this module's).
+// This
+// producer pins `likec4@1.50.0` (asserted by a drift guard against both
+// precedents), so the wording is fixed and both gates are safe. That pin is load
+// bearing: if it moves, the diagnostic gate is the thing that breaks.
+//
+// This module is PURE — parsing, edge building, and string generation only. All
+// filesystem writes and the likec4 invocation live in the executable wrapper,
+// plugins/soleur/scripts/generate-c4-from-components.ts, mirroring the
+// heartbeat-live-reconcile.ts -> reconcile-live-heartbeats.ts split.
+
+import { readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Pinned likec4 CLI version. MUST stay equal to `LIKEC4_VERSION` in
+ * plugins/soleur/scripts/render-c4-model.sh and the `likec4@…` pin in
+ * apps/web-platform/server/c4-render.ts — a drift guard asserts all three.
+ */
+export const LIKEC4_VERSION = "1.50.0";
+
+/**
+ * `--before` cutoff for the `npx` resolve. MUST stay equal to `LIKEC4_BEFORE` in
+ * plugins/soleur/scripts/render-c4-model.sh (BUMPING LIKEC4 there) — a drift guard asserts it.
+ */
+export const LIKEC4_BEFORE = "2026-09-28";
+
+/** Provenance stamp. A file without this as its FIRST line is never overwritten. */
+export const GENERATED_HEADER =
+  "// GENERATED by /soleur:sync c4 — hand edits will be overwritten";
+
+/**
+ * Source-fault detector, behaviourally equivalent to `DIAG_RE` in
+ * plugins/soleur/scripts/render-c4-model.sh. likec4@1.50.0 exits 0 on a syntax error —
+ * it drops the bad fragment, prints `Invalid <file>` / `Line N:`, and still emits
+ * a non-empty but INCOMPLETE model, which element-count alone cannot see.
+ *
+ * The anchors are deliberate: likec4 echoes `workspace: /abs/path`, so an
+ * unanchored `Invalid` would false-fail for a checkout directory whose name
+ * happens to contain the marker word.
+ */
+export const DIAG_RE =
+  /^([0-9]{2}:[0-9]{2}:[0-9]{2}(\.[0-9]+)? +[A-Z]+ +[^ ]+ +)?Invalid |Could not resolve|^\s+Line [0-9]+:/m;
+
+/**
+ * The environment likec4 runs under. Under CI it switches to a timestamped, ANSI-coloured
+ * reporter; CI and FORCE_COLOR are dropped and NO_COLOR set so the diagnostics reach
+ * `DIAG_RE` plain. `assessRender` also strips ANSI, so either defence alone holds.
+ */
+export function likec4ChildEnv(base: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = { ...base, NO_COLOR: "1" };
+  delete env.CI;
+  delete env.FORCE_COLOR;
+  return env;
+}
+
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+
+/** Marker sentinel for the C4 producer. */
+export const C4_MARKER = "SOLEUR_KB_SYNC_C4";
+
+/**
+ * Every numeric field the C4 marker emits, in emission order.
+ *
+ * ‼️ ALL of them appear on EVERY branch, even when the value is zero. The first
+ * version emitted a different field set per branch — `generated_*` and `published`
+ * only on the render path, `detail` only on the unavailable path, `docs` sometimes —
+ * so an agent parsing a fixed key set got missing keys with no way to tell
+ * absent-because-zero from absent-because-branch. `MARKER_FIELDS` in kb-coverage.ts
+ * already did this correctly; this is that pattern applied to the sibling producer,
+ * with a drift guard asserting both.
+ */
+export const C4_MARKER_FIELDS = [
+  "elements",
+  "relationships",
+  "generated_components",
+  "generated_relationships",
+  "skipped",
+  "seeded",
+  "published",
+] as const;
+
+export type C4MarkerCounts = Record<(typeof C4_MARKER_FIELDS)[number], number>;
+
+/**
+ * Build the C4 marker. One formatter, so no branch can omit a field.
+ *
+ * `reason` is a BARE TOKEN and `detail` carries prose — a consumer classifies on
+ * `reason=` without string-matching a sentence.
+ */
+export function formatC4Marker(
+  status: RenderVerdict["status"],
+  counts: C4MarkerCounts,
+  reason?: string,
+  detail?: string,
+): string {
+  const head =
+    `${C4_MARKER} status=${status}` +
+    (reason ? ` reason=${reason}` : "") +
+    (detail ? ` detail="${detail.replace(/"/g, "'").replace(/\s+/g, " ").trim()}"` : "");
+  const fields = C4_MARKER_FIELDS.map((f) => `${f}=${counts[f]}`).join(" ");
+  return `${head} ${fields}`;
+}
+
+export type DepSource = "frontmatter" | "links" | "none";
+
+export type ParsedComponent = {
+  /** Sanitized LikeC4 identifier (alphanumeric, camelCase). */
+  id: string;
+  /** Original kebab-case `component:` value — the key dependencies refer to. */
+  name: string;
+  /** Human-readable title for the diagram node. */
+  title: string;
+  /** Resolved dependency names, sorted. */
+  deps: string[];
+  /**
+   * Where `deps` came from. `"frontmatter"` with an empty list means the author
+   * DECLARED no dependencies; `"none"` means they declared nothing at all. The
+   * coverage summary needs that distinction — a corpus of silent docs must not
+   * read as a corpus of genuine leaves.
+   */
+  depSource: DepSource;
+};
+
+export type Edge = { from: string; to: string };
+
+export type RenderVerdict = {
+  status: "ok" | "degraded" | "failed";
+  /**
+   * A BARE TOKEN, never free prose. A consumer classifies on this, and the previous
+   * form emitted a quoted sentence — so a `reason=(\S+)` regex yielded `"0`.
+   * Human-readable context belongs in `detail`.
+   */
+  reason?: string;
+  detail?: string;
+};
+
+// ---------------------------------------------------------------------------
+// frontmatter
+// ---------------------------------------------------------------------------
+
+type Frontmatter = {
+  component?: string;
+  status?: string;
+  /** `undefined` = absent; `[]` = explicitly declared empty. */
+  dependencies?: string[];
+};
+
+function splitFrontmatter(source: string): string | null {
+  if (!source.startsWith("---")) return null;
+  const end = source.indexOf("\n---", 3);
+  if (end === -1) return null;
+  return source.slice(source.indexOf("\n") + 1, end);
+}
+
+function parseFrontmatter(source: string): Frontmatter {
+  const block = splitFrontmatter(source);
+  if (block === null) return {};
+
+  const fm: Frontmatter = {};
+  const lines = block.split("\n");
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const kv = line.match(/^([A-Za-z_][A-Za-z0-9_]*):[ \t]*(.*)$/);
+    if (!kv) continue;
+    const key = kv[1];
+    const inline = kv[2].trim();
+
+    if (key === "component" || key === "status") {
+      fm[key] = inline.replace(/^["']|["']$/g, "");
+      continue;
+    }
+
+    if (key !== "dependencies") continue;
+
+    // Inline form: `dependencies: []` or `dependencies: [a, b]`.
+    if (inline.startsWith("[")) {
+      const inner = inline.slice(1, inline.lastIndexOf("]")).trim();
+      fm.dependencies = inner === "" ? [] : inner.split(",").map((s) => s.trim()).filter(Boolean);
+      continue;
+    }
+
+    // Block form: collect the following `  - item` lines. An empty value with no
+    // following items is still a DECLARATION, so seed with [].
+    const items: string[] = [];
+    for (let j = i + 1; j < lines.length; j++) {
+      const item = lines[j].match(/^[ \t]+-[ \t]+(.*)$/);
+      if (!item) break;
+      const v = item[1].trim().replace(/^["']|["']$/g, "");
+      if (v) items.push(v);
+    }
+    fm.dependencies = items;
+  }
+
+  return fm;
+}
+
+// ---------------------------------------------------------------------------
+// parsing
+// ---------------------------------------------------------------------------
+
+/** Sanitize a kebab-case component name into a LikeC4 identifier. */
+export function toId(name: string): string {
+  const parts = name.split(/[^A-Za-z0-9]+/).filter(Boolean);
+  if (parts.length === 0) return "component";
+  const head = parts[0].toLowerCase();
+  const tail = parts.slice(1).map((p) => p[0].toUpperCase() + p.slice(1).toLowerCase());
+  const id = head + tail.join("");
+  return /^[0-9]/.test(id) ? `c${id}` : id;
+}
+
+function titleFor(name: string): string {
+  return name
+    .split(/[^A-Za-z0-9]+/)
+    .filter(Boolean)
+    .map((p) => p[0].toUpperCase() + p.slice(1))
+    .join(" ");
+}
+
+/**
+ * Parse one component doc. Returns `null` for a `status: deprecated` doc —
+ * sync.md's contract is "Removed components: add `status: deprecated` (do not
+ * delete)", so without this filter the element set accretes deleted components
+ * forever and their declared dependencies create dangling edges.
+ */
+export function parseComponentDoc(source: string, fallbackName: string): ParsedComponent | null {
+  const fm = parseFrontmatter(source);
+  if (fm.status === "deprecated") return null;
+
+  const name = fm.component ?? fallbackName;
+
+  let deps: string[];
+  let depSource: DepSource;
+
+  if (fm.dependencies !== undefined) {
+    deps = fm.dependencies;
+    depSource = "frontmatter";
+  } else {
+    // Fallback for docs written before the frontmatter contract: extract markdown
+    // links from the prose `**Internal**` line. Prose without links yields
+    // nothing — deliberately. Inferring edges from prose would invent
+    // architecture, which is worse than reporting degraded.
+    const internal = source.match(/^[ \t]*[-*][ \t]*\*\*Internal\*\*[ \t]*:(.*)$/m);
+    const links = internal ? [...internal[1].matchAll(/\[([^\]]+)\]\([^)]*\)/g)] : [];
+    if (links.length > 0) {
+      deps = links.map((m) => m[1].trim());
+      depSource = "links";
+    } else {
+      deps = [];
+      depSource = "none";
+    }
+  }
+
+  const unique = [...new Set(deps.filter((d) => d && d !== name))].sort();
+
+  return { id: toId(name), name, title: titleFor(name), deps: unique, depSource };
+}
+
+/** Load and parse every `*.md` in a directory, dropping deprecated docs. Sorted by name. */
+export function loadComponentDir(dir: string): ParsedComponent[] {
+  const files = readdirSync(dir)
+    .filter((f) => f.endsWith(".md") && f !== "README.md")
+    .sort();
+
+  const docs: ParsedComponent[] = [];
+  for (const f of files) {
+    const parsed = parseComponentDoc(readFileSync(join(dir, f), "utf8"), f.replace(/\.md$/, ""));
+    if (parsed) docs.push(parsed);
+  }
+  return docs.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+}
+
+// ---------------------------------------------------------------------------
+// edges
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the edge set, dropping any dependency whose target is not a live element.
+ * An edge to a missing or deprecated component makes likec4 emit
+ * `Could not resolve …`, which the diagnostic gate treats as a hard failure — so
+ * the producer must not emit it in the first place.
+ */
+export function buildEdges(components: ParsedComponent[]): Edge[] {
+  const live = new Set(components.map((c) => c.name));
+  const edges: Edge[] = [];
+
+  for (const c of components) {
+    for (const dep of c.deps) {
+      if (live.has(dep)) edges.push({ from: c.name, to: dep });
+    }
+  }
+
+  return edges.sort((a, b) =>
+    a.from < b.from ? -1 : a.from > b.from ? 1 : a.to < b.to ? -1 : a.to > b.to ? 1 : 0,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// non-destructive write contract
+// ---------------------------------------------------------------------------
+
+/**
+ * True when the producer may write this path. `/soleur:architecture` writes
+ * spec.c4 / model.c4 / views.c4 cwd-relative, and the agent sandbox pins
+ * `cwd = workspacePath` — two writers, one directory. A tester who hand-corrects
+ * a wrong edge must not have it silently reverted by the next sync.
+ *
+ * The header must be the FIRST line, not merely present somewhere in the body
+ * (cq-assert-anchor-not-bare-token): a hand-authored file that happens to quote
+ * the header in a comment is still a hand-authored file.
+ */
+export function canOverwrite(existing: string | null): boolean {
+  if (existing === null) return true;
+  return existing.split("\n", 1)[0].trim() === GENERATED_HEADER;
+}
+
+// ---------------------------------------------------------------------------
+// generation
+// ---------------------------------------------------------------------------
+
+function escapeC4(s: string): string {
+  return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+
+/**
+ * Emit the composing model file. Deterministic by construction: no timestamp, no
+ * run id, sorted inputs — an unchanged component-doc set must produce a
+ * byte-identical file, or every sync emits a diff forever.
+ */
+export function generateC4(components: ParsedComponent[], edges: Edge[]): string {
+  const byName = new Map(components.map((c) => [c.name, c]));
+  const out: string[] = [GENERATED_HEADER, "", "model {", ""];
+
+  for (const c of components) {
+    out.push(`  ${c.id} = component "${escapeC4(c.title)}" {`);
+    out.push(`    description "${escapeC4(`Component: ${c.name}`)}"`);
+    out.push("  }");
+  }
+
+  if (edges.length > 0) {
+    out.push("");
+    for (const e of edges) {
+      const from = byName.get(e.from);
+      const to = byName.get(e.to);
+      if (!from || !to) continue;
+      out.push(`  ${from.id} -> ${to.id} "depends on"`);
+    }
+  }
+
+  out.push("}", "");
+  return out.join("\n");
+}
+
+/**
+ * Minimal `specification` block for the `component` element kind the generated model
+ * uses. Without it every generated element is an unresolved reference and the render
+ * fails.
+ *
+ * ‼️ The wrapper seeds this only when no file NAMED `spec.c4` exists — it does not
+ * scan the directory for an existing `specification` block. That distinction was
+ * previously stated the other way round, and the gap is reachable: a repo using the
+ * valid single-file LikeC4 layout (its `specification` inside `model.c4`) gets a
+ * SECOND `element component` declaration and the whole sync exits 1. Soleur's own
+ * diagrams dir has a discrete `spec.c4`, so dogfooding cannot surface it.
+ *
+ * Left as a filename check deliberately: scanning for a `specification` block means
+ * parsing every `.c4` in the directory, and the failure is loud (exit 1 with the
+ * likec4 diagnostic naming the duplicate) rather than silent. Recorded here so the
+ * next reader sees a known, bounded limitation instead of a false claim.
+ */
+export function generateSpecC4(): string {
+  return [
+    GENERATED_HEADER,
+    "",
+    "specification {",
+    "  element component {",
+    '    notation "Component"',
+    "    style {",
+    "      shape rectangle",
+    "    }",
+    "  }",
+    "}",
+    "",
+  ].join("\n");
+}
+
+/** Minimal view so the model renders in the KB viewer. */
+export function generateViewsC4(): string {
+  return [
+    GENERATED_HEADER,
+    "",
+    "views {",
+    "  view generatedComponents {",
+    '    title "Components (generated from knowledge base)"',
+    "    include *",
+    "  }",
+    "}",
+    "",
+  ].join("\n");
+}
+
+/**
+ * The markdown page carrying the view embed. The KB viewer renders a diagram only
+ * for a markdown page with a `likec4-view` fence — three .c4 files alone are not
+ * enough (api/kb/c4/project/route.ts also returns MODEL_NOT_BUILT without a
+ * committed model.likec4.json).
+ */
+export function generateViewPage(viewId = "generatedComponents"): string {
+  return [
+    "# Components",
+    "",
+    "Generated by `/soleur:sync c4` from the component docs in",
+    "`knowledge-base/project/components/`. Edges come from each doc's",
+    "`dependencies:` frontmatter.",
+    "",
+    "```likec4-view",
+    viewId,
+    "```",
+    "",
+  ].join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Count elements, relationships, and views in a rendered `model.likec4.json`.
+ * `views` feeds `assessRender`'s zero-views gate (#8861).
+ *
+ * ‼️ The relationship key is `relations`, NOT `relationships`. Reading the wrong
+ * key returns `undefined` -> 0, which makes `assessRender` report EVERY corpus as
+ * degraded — a gate that always fires is exactly as useless as one that never
+ * does, and no unit test over `assessRender` (which takes plain numbers) can see
+ * it. `countModelJson` exists so the key mapping itself is pinned by a test
+ * against a real likec4 artifact.
+ *
+ * Non-object shapes yield 0 rather than throwing: likec4 can emit a null/array
+ * field, and a bare `Object.keys` on those would silently produce a wrong count.
+ */
+export function countModelJson(json: string): {
+  elements: number;
+  relationships: number;
+  views: number;
+} {
+  try {
+    const model = JSON.parse(json) as Record<string, unknown>;
+    const size = (v: unknown) =>
+      v && typeof v === "object" && !Array.isArray(v) ? Object.keys(v).length : 0;
+    return {
+      elements: size(model.elements),
+      relationships: size(model.relations),
+      views: size(model.views),
+    };
+  } catch {
+    return { elements: 0, relationships: 0, views: 0 };
+  }
+}
+
+/**
+ * The gates. Order matters: a source fault is a hard failure regardless of
+ * counts, an empty model is a failure, a zero-view model is a LAYOUT failure
+ * (#8861 — a successful layout always emits at least `index`, so this is the
+ * graphviz-fallback/container shape, never the user's source), and only then is
+ * a zero-relationship model classified — as `degraded`, never `failed`. The
+ * docs are the defect there, not the run, and failing the sync over it would
+ * punish the tester for a corpus Soleur itself taught them to write.
+ */
+export function assessRender(input: {
+  diagnostics: string;
+  /** Elements in the RENDERED model (the whole diagrams dir). Validates non-degeneracy. */
+  elementCount: number;
+  /**
+   * Views in the RENDERED model — the #8861 gate, mirroring c4-render.ts's
+   * `counts.views === 0`. Elements-but-no-views means the layout engine failed,
+   * so a zero here is `failed`, and it is checked before the
+   * generatedRelationships degrade so a broken layout is never published as a
+   * "link-free corpus".
+   */
+  viewCount: number;
+  /** Relationships in the RENDERED model. Reported, but NOT the gate — see below. */
+  relationshipCount: number;
+  /**
+   * Relationships THIS PRODUCER contributed, i.e. `buildEdges(docs).length`.
+   *
+   * ‼️ THIS is the gate, and using `relationshipCount` was the defect. `likec4
+   * export json .` renders the WHOLE diagrams directory, so on any repo that already
+   * has a hand-authored `model.c4` the count is dominated by edges the producer did
+   * not create. Measured on this repo: 4 component docs with ZERO `dependencies:`
+   * frontmatter — the producer contributed 0 relationships — and the merged render
+   * reported 135. The zero-relationship gate, which is this module's entire reason
+   * for existing, was therefore unreachable in exactly the two-writer scenario the
+   * design is built around: it could only ever fire on a fresh diagrams dir, where
+   * it is least needed.
+   *
+   * The producer already knows this number without asking likec4 — it built the edge
+   * set. The render's job is validation and artifact production, not counting.
+   */
+  generatedRelationships: number;
+}): RenderVerdict {
+  const diagnostics = input.diagnostics.replace(ANSI_RE, "");
+  if (DIAG_RE.test(diagnostics)) {
+    const line = diagnostics.split("\n").find((l) => DIAG_RE.test(l)) ?? "";
+    return { status: "failed", reason: "source-fault", detail: line.trim() };
+  }
+  if (input.elementCount === 0) {
+    return { status: "failed", reason: "empty-model", detail: "likec4 produced an empty/degenerate model" };
+  }
+  if (input.viewCount === 0) {
+    // A layout failure with no diagnostic the source-fault arm could claim —
+    // the likec4 output tail is the only evidence the agent gets, so carry a
+    // trimmed copy on the wire (the marker collapses whitespace anyway).
+    const tail = diagnostics
+      .split("\n")
+      .filter(Boolean)
+      .slice(-5)
+      .join(" | ")
+      .slice(0, 300);
+    return {
+      status: "failed",
+      reason: "zero-views",
+      detail: `likec4 produced a model with elements but no views — a layout failure, not a source fault${tail ? ` — last output: ${tail}` : ""}`,
+    };
+  }
+  if (input.generatedRelationships === 0) {
+    return {
+      status: "degraded",
+      reason: "no-generated-relationships",
+      detail:
+        "component docs declare no parseable dependencies, so this producer " +
+        "contributed a set of disconnected boxes",
+    };
+  }
+  return { status: "ok" };
+}

package/lib/go-routing.ts

@@ -0,0 +1,81 @@
+/**
+ * /go routing dispatch — maps classified intent labels to registered skills/agents.
+ *
+ * Mirrors the eval-gate routing table in plugins/soleur/commands/go.md.
+ * Golden-path eval (Phase F #6325) asserts Grok slash_command dispatch fidelity.
+ * Anti-bypass contract (#6338): routes resolve via workflow-fidelity.ts.
+ */
+
+import { invokeSkill, spawnAgent, type SkillInvocation, type AgentSpawn } from "./harness";
+import { GO_SKILL_ROUTES, resolveGoSkillRoute } from "./workflow-fidelity";
+
+export { GO_SKILL_ROUTES, resolveGoSkillRoute };
+
+/** Agent routes (spawn_subagent / Task — never improvised workflows). */
+export const GO_AGENT_ROUTES: Record<string, string> = {
+  "clo-attestation": "clo",
+  "legal-threshold": "clo",
+};
+
+export type GoRouteTarget =
+  | { kind: "skill"; skill: string }
+  | { kind: "agent"; agent: string };
+
+/** Resolve a classified routing label to its registered target. */
+export function resolveGoRoute(label: string): GoRouteTarget {
+  if (label in GO_AGENT_ROUTES) {
+    return { kind: "agent", agent: GO_AGENT_ROUTES[label] };
+  }
+  return { kind: "skill", skill: resolveGoSkillRoute(label) };
+}
+
+export type GoDispatch =
+  | { kind: "skill"; invocation: SkillInvocation }
+  | { kind: "agent"; spawn: AgentSpawn };
+
+/**
+ * Dispatch a classified /go route under the active harness.
+ * Pass `env` in tests to pin Grok vs Claude without mutating process.env.
+ */
+export function dispatchGoRoute(
+  label: string,
+  userInput: string,
+  env?: NodeJS.ProcessEnv,
+): GoDispatch {
+  const target = resolveGoRoute(label);
+  const prev = { ...process.env };
+
+  if (env) {
+    for (const key of Object.keys(process.env)) {
+      if (!(key in env)) delete process.env[key];
+    }
+    Object.assign(process.env, env);
+  }
+
+  try {
+    if (target.kind === "agent") {
+      return { kind: "agent", spawn: spawnAgent(target.agent, userInput) };
+    }
+    return { kind: "skill", invocation: invokeSkill(target.skill, userInput) };
+  } finally {
+    for (const key of Object.keys(process.env)) {
+      if (!(key in prev)) delete process.env[key];
+    }
+    Object.assign(process.env, prev);
+  }
+}
+
+/** Pin harness for deterministic golden-path tests. */
+export function grokTestEnv(): NodeJS.ProcessEnv {
+  return { GROK_HOME: "/home/user/.grok" };
+}
+
+export function claudeTestEnv(): NodeJS.ProcessEnv {
+  return { CLAUDECODE: "1" };
+}
+
+/** Expected Grok slash command for a skill route (golden-path assertion). */
+export function expectedGrokSlashCommand(skill: string, args?: string): string {
+  const trimmed = args?.trim();
+  return trimmed ? `/${skill} ${trimmed}` : `/${skill}`;
+}