@litfamily/litopencode 1.0.0

package/tools/run-rules-glob-differential.mjs

@@ -0,0 +1,232 @@
+#!/usr/bin/env node
+// Differential harness: LitOpenCode's hand-rolled glob matcher vs real picomatch.
+//
+// The engine ships dependency-free, so divergence from the dialect rule authors expect is a real
+// risk. A written divergence list is a claim; this is a measurement. Every pattern in the corpus is
+// compiled through both matchers against every path, and disagreements are reported.
+//
+// picomatch is a repo-local DEV-TIME import only. It is never imported by src/. A standalone
+// checkout receives it through this package's devDependencies, so the comparison does not depend
+// on a sibling repository or an environment-specific fallback.
+//
+//   node tools/run-rules-glob-differential.mjs            report divergences
+//   node tools/run-rules-glob-differential.mjs --check    exit 1 if an UNPINNED divergence appears
+//
+// Pinned divergences are deliberate, documented subset choices. An unpinned one is a defect.
+
+import { createRequire } from "node:module";
+import path from "node:path";
+import process from "node:process";
+import { pathToFileURL } from "node:url";
+
+const require = createRequire(import.meta.url);
+const repoRoot = path.resolve(import.meta.dirname, "..");
+
+function loadPicomatch() {
+  const source = require.resolve("picomatch");
+  const version = require("picomatch/package.json").version;
+  return { picomatch: require("picomatch"), source, version };
+}
+
+// Patterns a .cursor/rules or .github/instructions author actually writes, plus the edge cases
+// where a hand-rolled translation is most likely to drift.
+const patterns = [
+  "*.ts", "*.md", "src/*.ts", "src/**", "src/**/*.ts", "**/*.ts", "**/test/**",
+  "src/**/test/*.ts", "a?.md", "a??.md", "src/[abc].ts", "src/[!abc].ts", "src/[a-z].ts",
+  "{a,b}.md", "src/{a,b}/*.ts", "src/{a,{b,c}}/*.ts", "docs/**/*.{md,mdx}",
+  "src/index.ts", "src/", "/src/*.ts", "./src/*.ts", "**", "*", "**/*",
+  "src/**/", "a*.md", "*.config.*", ".github/**/*.yml", "packages/*/src/**/*.ts"
+];
+
+const paths = [
+  "a.ts", "a.md", "ab.md", "abc.md", "src/a.ts", "src/b.ts", "src/index.ts",
+  "src/nested/a.ts", "src/deep/nested/a.ts", "src", "src/a", "src/test/a.ts",
+  "src/a/test/b.ts", "test/a.ts", "docs/a.md", "docs/nested/a.mdx", "a.md.bak",
+  "src/A.ts", "src/1.ts", "b.md", "c.md", "src/a/x.ts", "src/b/x.ts", "src/c/x.ts",
+  ".github/workflows/ci.yml", "packages/one/src/deep/a.ts", "a.config.js", "src/.hidden.ts"
+];
+
+// Divergences that are deliberate subset choices, keyed `pattern :: path`. Each carries the reason
+// it is accepted rather than fixed.
+// Measured with picomatch({ dot: true }).
+//
+// `bash: true` was tried first and rejected on evidence: it compiles `*` to `.*?` instead of `[^/]*?`,
+// so `*.ts` starts matching `src/a.ts` and every nested path. Rule authors scoping `*.ts` mean files
+// at that level, not the whole tree, so bash mode is the wrong baseline for path scoping. `dot: true`
+// is kept because rule files legitimately scope dotfiles such as `.github/**`.
+const picomatchOptions = { dot: true };
+
+const divergenceReasons = new Map([
+  [
+    "[!seq] negation",
+    "picomatch 4.0.5 does NOT read `[!abc]` as negation under any option set tried, including " +
+      "{bash:true,dot:true}: it compiles to `(?:\\[!abc\\]|[!abc])`, a literal-or-class, so `src/a.ts` MATCHES " +
+      "`src/[!abc].ts`. This engine reads `!` as negation, matching gitignore, minimatch, and what a rule " +
+      "author writing `.cursor/rules` means. Deliberate dialect choice; flip translateCharacterClass to " +
+      "drop the `!` branch if picomatch parity is ever wanted instead."
+  ],
+  [
+    "trailing-slash subtree",
+    "`src/` is normalized to the `src` subtree, matching gitignore and how rule files scope directories. " +
+      "picomatch treats the trailing slash literally and matches nothing."
+  ],
+  [
+    "leading-slash anchor",
+    "`/src/*.ts` is normalized to a repository-root anchor, matching gitignore. picomatch treats the " +
+      "leading slash as a literal path segment and matches nothing."
+  ]
+]);
+
+const trailingSlashPaths = [
+  "src/a.ts", "src/b.ts", "src/index.ts", "src/nested/a.ts", "src/deep/nested/a.ts",
+  "src", "src/a", "src/test/a.ts", "src/a/test/b.ts", "src/A.ts", "src/1.ts",
+  "src/a/x.ts", "src/b/x.ts", "src/c/x.ts", "src/.hidden.ts"
+];
+
+const pinnedDivergenceTuples = [
+  { pattern: "src/[!abc].ts", path: "src/a.ts", mine: false, theirs: true },
+  { pattern: "src/[!abc].ts", path: "src/b.ts", mine: false, theirs: true },
+  { pattern: "src/[!abc].ts", path: "src/A.ts", mine: true, theirs: false },
+  { pattern: "src/[!abc].ts", path: "src/1.ts", mine: true, theirs: false },
+  ...["src/", "src/**/"].flatMap((pattern) =>
+    trailingSlashPaths.map((candidatePath) => ({ pattern, path: candidatePath, mine: true, theirs: false }))
+  ),
+  ...["src/a.ts", "src/b.ts", "src/index.ts", "src/A.ts", "src/1.ts", "src/.hidden.ts"].map((candidatePath) => ({
+    pattern: "/src/*.ts",
+    path: candidatePath,
+    mine: true,
+    theirs: false
+  }))
+];
+
+function divergencePairKey(entry) {
+  return `${entry.pattern}\u0000${entry.path}`;
+}
+
+function evaluateDivergencePins(actual, pins = pinnedDivergenceTuples) {
+  const expectedByPair = new Map(pins.map((entry) => [divergencePairKey(entry), entry]));
+  const seenPairs = new Set();
+  const unpinned = [];
+  const directionMismatches = [];
+  for (const entry of actual) {
+    const pair = divergencePairKey(entry);
+    const expected = expectedByPair.get(pair);
+    if (expected === undefined) {
+      unpinned.push(entry);
+      continue;
+    }
+    seenPairs.add(pair);
+    if (entry.mine !== expected.mine || entry.theirs !== expected.theirs) {
+      directionMismatches.push({ actual: entry, expected });
+    }
+  }
+  const stalePins = pins.filter((entry) => !seenPairs.has(divergencePairKey(entry)));
+  return { unpinned, stalePins, directionMismatches };
+}
+
+// Divergences are keyed by class rather than by pair, because one dialect decision produces many
+// pairs and pinning each pair would hide a later regression inside an accepted list.
+function divergenceClass(pattern) {
+  if (/\[!/u.test(pattern)) return "[!seq] negation";
+  if (pattern.trim().endsWith("/")) return "trailing-slash subtree";
+  if (pattern.trim().startsWith("/")) return "leading-slash anchor";
+  return undefined;
+}
+
+function main() {
+  const loaded = loadPicomatch();
+  return import(pathToFileURL(path.join(repoRoot, "dist", "rules", "glob.js")).href).then((engine) => {
+    const { picomatch, source, version } = loaded;
+    const divergences = [];
+    let comparisons = 0;
+
+    for (const pattern of patterns) {
+      let isMatch;
+      try {
+        isMatch = picomatch(pattern, picomatchOptions);
+      } catch (error) {
+        console.error(`picomatch could not compile ${pattern}: ${error.message}`);
+        continue;
+      }
+      for (const candidatePath of paths) {
+        comparisons += 1;
+        const mine = engine.matchGlob(pattern, candidatePath);
+        const theirs = isMatch(candidatePath);
+        if (mine !== theirs) {
+          divergences.push({
+            pattern,
+            path: candidatePath,
+            mine,
+            theirs,
+            cls: divergenceClass(pattern),
+            key: `${pattern} :: ${candidatePath}`
+          });
+        }
+      }
+    }
+
+    console.log(`rules-glob differential: picomatch ${version}`);
+    console.log(`  source:  ${source}`);
+    console.log(`  options: ${JSON.stringify(picomatchOptions)}`);
+    console.log(`  ${patterns.length} patterns x ${paths.length} paths = ${comparisons} comparisons`);
+    console.log(`  divergences: ${divergences.length}`);
+    console.log("");
+
+    const { unpinned, stalePins, directionMismatches } = evaluateDivergencePins(divergences);
+    const seenClasses = new Set(divergences.map((entry) => entry.cls).filter((cls) => cls !== undefined));
+
+    for (const cls of seenClasses) {
+      const members = divergences.filter((entry) => entry.cls === cls);
+      console.log(`  PINNED CLASS  ${cls}  (${members.length} pair(s))`);
+      console.log(`    reason: ${divergenceReasons.get(cls)}`);
+      for (const entry of members.slice(0, 4)) {
+        console.log(`      ${entry.key}  litopencode=${entry.mine} picomatch=${entry.theirs}`);
+      }
+      if (members.length > 4) console.log(`      ... and ${members.length - 4} more in the same class`);
+      console.log("");
+    }
+    for (const entry of unpinned) {
+      console.log(`  UNPINNED  ${entry.key}  litopencode=${entry.mine} picomatch=${entry.theirs}`);
+    }
+    for (const entry of stalePins) {
+      console.log(`  STALE PIN  ${entry.pattern} :: ${entry.path}  litopencode=${entry.mine} picomatch=${entry.theirs}`);
+    }
+    for (const mismatch of directionMismatches) {
+      console.log(
+        `  DIRECTION MISMATCH  ${mismatch.actual.pattern} :: ${mismatch.actual.path}  ` +
+        `expected litopencode=${mismatch.expected.mine} picomatch=${mismatch.expected.theirs}, ` +
+        `observed litopencode=${mismatch.actual.mine} picomatch=${mismatch.actual.theirs}`
+      );
+    }
+
+    console.log("");
+    if (unpinned.length === 0 && stalePins.length === 0 && directionMismatches.length === 0) {
+      console.log(`rules-glob differential OK: ${divergences.length} exact pinned divergence(s), 0 unpinned, 0 stale, 0 direction mismatches.`);
+      process.exit(0);
+    }
+    console.error(
+      `rules-glob differential FAILED: ${unpinned.length} unpinned, ${stalePins.length} stale, ` +
+      `${directionMismatches.length} direction mismatch(es).`
+    );
+    process.exit(1);
+  });
+}
+
+if (process.argv.includes("--self-test")) {
+  const pins = [
+    { pattern: "a", path: "one", mine: true, theirs: false },
+    { pattern: "c", path: "three", mine: false, theirs: true }
+  ];
+  const actual = [
+    { pattern: "a", path: "one", mine: false, theirs: true },
+    { pattern: "b", path: "two", mine: true, theirs: false }
+  ];
+  const result = evaluateDivergencePins(actual, pins);
+  if (result.unpinned.length !== 1 || result.stalePins.length !== 1 || result.directionMismatches.length !== 1) {
+    console.error("pin self-test FAILED");
+    process.exit(1);
+  }
+  console.log("pin self-test OK: unpinned=1 stale=1 direction-mismatch=1");
+} else {
+  await main();
+}

package/tools/run-typecheck.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import { spawnSync } from "node:child_process";
+import process from "node:process";
+
+const tscBin = "node_modules/typescript/bin/tsc";
+const sourceEntry = "src/index.ts";
+
+if (!fs.existsSync(tscBin)) {
+  console.log("typecheck skipped: TypeScript dev dependency is not installed in this packed artifact.");
+  process.exit(0);
+}
+
+if (!fs.existsSync(sourceEntry)) {
+  console.log("typecheck skipped: TypeScript source files are not present in this packed artifact.");
+  process.exit(0);
+}
+
+const result = spawnSync(process.execPath, [tscBin, "--noEmit"], {
+  cwd: process.cwd(),
+  encoding: "utf8",
+  stdio: "inherit"
+});
+
+process.exit(result.status ?? 1);

package/tools/run-uiux-visual-qa-scenarios.mjs

@@ -0,0 +1,234 @@
+#!/usr/bin/env node
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const scenarioIds = Object.freeze([
+  "public-service-form-ko",
+  "fintech-dashboard",
+  "healthcare-mobile",
+  "saas-landing-responsive",
+  "brownfield-design-system",
+  "reference-fidelity",
+  "cjk-terminal-dashboard",
+  "missing-capture-auth-review"
+]);
+function sha256(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+export async function hashInstalledCapabilityTree(root) {
+  const hash = createHash("sha256");
+  async function visit(relative) {
+    const absolute = path.join(root, relative);
+    const stat = await fs.lstat(absolute);
+    if (stat.isSymbolicLink()) throw new Error(`capability tree contains symlink: ${relative}`);
+    if (stat.isDirectory()) {
+      const entries = (await fs.readdir(absolute)).sort();
+      for (const entry of entries) await visit(path.join(relative, entry));
+      return;
+    }
+    if (!stat.isFile()) throw new Error(`capability tree contains non-file: ${relative}`);
+    hash.update(relative.split(path.sep).join("/")).update("\0").update(await fs.readFile(absolute)).update("\0");
+  }
+  await visit("skills/frontend-ui-ux");
+  await visit("skills/visual-qa");
+  return hash.digest("hex");
+}
+
+export async function assertCapabilityTreeUnchanged(root, expectedHash) {
+  const actualHash = await hashInstalledCapabilityTree(root);
+  if (actualHash !== expectedHash) throw new Error("installed capability tree mutated during benchmark");
+  return actualHash;
+}
+
+function parseArgs(argv) {
+  const options = {};
+  const seen = new Set();
+  for (let index = 0; index < argv.length; index += 1) {
+    const flag = argv[index];
+    if (seen.has(flag)) throw new Error(`duplicate singleton option: ${flag}`);
+    seen.add(flag);
+    if (flag === "--json") options.json = true;
+    else if (["--installed-root", "--fixtures", "--scenario"].includes(flag)) {
+      if (argv[index + 1] === undefined) throw new Error(`${flag} requires a value`);
+      options[flag.slice(2).replaceAll("-", "_")] = argv[++index];
+    } else throw new Error(`unknown option: ${flag}`);
+  }
+  if (!options.installed_root || !options.fixtures || options.scenario !== "all" || !options.json) {
+    throw new Error("required: --installed-root ROOT --fixtures ROOT --scenario all --json");
+  }
+  return options;
+}
+
+async function boundedRegular(filePath, root, maxBytes = 1024 * 1024) {
+  const absolute = path.resolve(root, filePath);
+  const relative = path.relative(root, absolute);
+  if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+    throw new Error(`path escapes root: ${filePath}`);
+  }
+  const stat = await fs.lstat(absolute);
+  if (stat.isSymbolicLink() || !stat.isFile()) throw new Error(`not a regular non-symlink file: ${filePath}`);
+  if (stat.size > maxBytes) throw new Error(`file exceeds ${maxBytes} bytes: ${filePath}`);
+  return { absolute, bytes: await fs.readFile(absolute) };
+}
+
+function inspectInput(detector, input, visualQa) {
+  if (detector === "tui") {
+    const inspected = visualQa.inspectTui(input.text, { ambiguousWidth: input.ambiguous_width });
+    return {
+      findings: inspected.findings,
+      blockedCodes: [],
+      verdict: inspected.findings.length === 0 ? "PASS" : "REVISE",
+      publicValidator: "inspectTui",
+      inspected
+    };
+  }
+  if (detector === "capabilities") {
+    const inspected = visualQa.evaluateCapabilityBlocks(input);
+    return {
+      findings: [],
+      blockedCodes: inspected.codes,
+      verdict: inspected.verdict,
+      publicValidator: "evaluateCapabilityBlocks",
+      inspected
+    };
+  }
+  const inspected = visualQa.inspectUiArtifact(input);
+  return {
+    findings: inspected.findings,
+    blockedCodes: [],
+    verdict: inspected.verdict,
+    publicValidator: "inspectUiArtifact",
+    inspected
+  };
+}
+
+function scenarioAssertions(scenario, inspected) {
+  const input = scenario.input;
+  if (scenario.detector === "healthcare-safety") {
+    return { source_mutated: input.source_before_hash !== input.source_after_hash };
+  }
+  if (scenario.detector === "brownfield-system") return { source_pointer: input.source_pointer };
+  if (scenario.detector === "reference-fidelity") {
+    return {
+      similarity_overrode_dimension_mismatch:
+        input.similarity >= 0.95 &&
+        JSON.stringify(input.expected_dimensions) === JSON.stringify(input.actual_dimensions)
+    };
+  }
+  if (scenario.detector === "tui") {
+    return {
+      osc_inert: inspected.controlSequencesInert && !inspected.sanitized.includes("example.invalid"),
+      zwj_width: inspected.rows.flatMap((row) => row.graphemes)
+        .find((item) => item.text === input.zwj_grapheme)?.width
+    };
+  }
+  return {};
+}
+
+export async function runScenarios(options) {
+  const installedRoot = await fs.realpath(path.resolve(options.installed_root));
+  const fixturesRoot = await fs.realpath(path.resolve(options.fixtures));
+  const fixture = await boundedRegular("scenarios.json", fixturesRoot);
+  const strictJsonUrl = pathToFileURL(
+    path.join(installedRoot, "skills/frontend-ui-ux/scripts/strict-json.mjs")
+  ).href;
+  const visualQaUrl = pathToFileURL(path.join(installedRoot, "skills/visual-qa/scripts/visual-qa.mjs")).href;
+  const [{ parseStrictJson }, visualQa] = await Promise.all([import(strictJsonUrl), import(visualQaUrl)]);
+  const treeHashBefore = await hashInstalledCapabilityTree(installedRoot);
+  const contract = parseStrictJson(new TextDecoder("utf-8", { fatal: true }).decode(fixture.bytes));
+  if (
+    contract.schema_version !== "litfamily.uiux-visual-qa-scenarios/v1" ||
+    !Array.isArray(contract.scenarios) ||
+    JSON.stringify(contract.scenarios.map((item) => item.id)) !== JSON.stringify(scenarioIds)
+  ) throw new Error("scenario fixture contract mismatch");
+  const results = [];
+  for (const scenario of contract.scenarios) {
+    const validationRuns = [
+      inspectInput(scenario.detector, scenario.input, visualQa),
+      inspectInput(scenario.detector, scenario.control_input, visualQa)
+    ];
+    const [seeded, control] = validationRuns;
+    const reviewRounds = validationRuns.filter(
+      (run) => run.publicValidator === "validateReviewReceipt"
+    ).length;
+    const findingCodes = seeded.findings.map((finding) => finding.code);
+    const controlCodes = [
+      ...control.findings.map((finding) => finding.code),
+      ...control.blockedCodes
+    ];
+    const controlPassed =
+      controlCodes.length === 0 && ["PASS", "READY"].includes(control.verdict);
+    const detected =
+      JSON.stringify(findingCodes) === JSON.stringify(scenario.expected_finding_codes) &&
+      JSON.stringify(seeded.blockedCodes) === JSON.stringify(scenario.expected_blocked_codes) &&
+      controlPassed;
+    const seededIssueExpected =
+      scenario.expected_finding_codes.length > 0 || scenario.expected_blocked_codes.length > 0;
+    results.push({
+      assertions: scenarioAssertions(scenario, seeded.inspected),
+      blocked_codes: seeded.blockedCodes,
+      control_codes: controlCodes,
+      control_passed: controlPassed,
+      detected,
+      detector: scenario.detector,
+      finding_codes: findingCodes,
+      false_pass: seededIssueExpected && ["PASS", "READY"].includes(seeded.verdict),
+      id: scenario.id,
+      public_validator: seeded.publicValidator,
+      review_rounds: reviewRounds,
+      severity: seeded.blockedCodes.length > 0
+        ? "blocking"
+        : seeded.findings.some((finding) => finding.severity === "critical") ? "critical" : "high",
+      validation_runs: validationRuns.length,
+      verdict: seeded.verdict
+    });
+  }
+  await assertCapabilityTreeUnchanged(installedRoot, treeHashBefore);
+  return {
+    capability_tree_mutated: false,
+    detection_failure_count: results.filter((item) => !item.detected).length,
+    false_pass_count: results.filter((item) => item.false_pass).length,
+    fixture_sha256: sha256(fixture.bytes),
+    installed_capability_tree_sha256: treeHashBefore,
+    max_review_rounds: Math.max(...results.map((item) => item.review_rounds)),
+    max_validation_runs: Math.max(...results.map((item) => item.validation_runs)),
+    results,
+    scenario_count: results.length,
+    schema_version: "litfamily.uiux-visual-qa-driver-result/v1",
+    seeded_critical_high_detected: results.filter(
+      (item) => item.detected && item.finding_codes.length > 0 &&
+        ["critical", "high"].includes(item.severity)
+    ).length,
+    seeded_findings_detected: results.filter(
+      (item) => item.detected && item.finding_codes.length > 0
+    ).length,
+    seeded_blocked_outcomes_detected: results.filter(
+      (item) => item.detected && item.blocked_codes.length > 0
+    ).length
+  };
+}
+
+async function main() {
+  const output = await runScenarios(parseArgs(process.argv.slice(2)));
+  process.stdout.write(JSON.stringify(output) + "\n");
+}
+
+async function isDirectExecution(argvPath = process.argv[1]) {
+  if (!argvPath) return false;
+  try {
+    return await fs.realpath(argvPath) === await fs.realpath(fileURLToPath(import.meta.url));
+  } catch {
+    return pathToFileURL(path.resolve(argvPath)).href === import.meta.url;
+  }
+}
+
+if (await isDirectExecution()) {
+  main().catch((error) => {
+    process.stderr.write(`SCENARIO_DRIVER_FAIL: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 2;
+  });
+}

package/tools/run-wikify-surface-probe.mjs

@@ -0,0 +1,170 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+const root = await fs.mkdtemp(path.join(os.tmpdir(), "litopencode-wikify-surface-"));
+const isolatedEnvironment = {
+  HOME: path.join(root, "home"),
+  XDG_CONFIG_HOME: path.join(root, "xdg", "config"),
+  XDG_CACHE_HOME: path.join(root, "xdg", "cache"),
+  XDG_DATA_HOME: path.join(root, "xdg", "data"),
+  LITOPENCODE_NO_AUTO_UPDATE: "1",
+  NO_UPDATE_NOTIFIER: "1",
+  LITOPENCODE_NO_UPDATE_CHECK: "1"
+};
+
+async function snapshotDirectoryState(directory) {
+  const entries = [];
+  async function visit(current, relativePath) {
+    let stat;
+    try {
+      stat = await fs.lstat(current);
+    } catch (error) {
+      if (error instanceof Error && "code" in error && error.code === "ENOENT") return;
+      throw error;
+    }
+    const entryPath = relativePath === "" ? "." : relativePath;
+    if (stat.isSymbolicLink()) {
+      entries.push({ path: entryPath, kind: "symlink", target: await fs.readlink(current) });
+      return;
+    }
+    if (stat.isDirectory()) {
+      entries.push({ path: entryPath, kind: "directory" });
+      for (const child of (await fs.readdir(current)).sort()) {
+        await visit(path.join(current, child), relativePath === "" ? child : path.join(relativePath, child));
+      }
+      return;
+    }
+    if (stat.isFile()) {
+      entries.push({
+        path: entryPath,
+        kind: "file",
+        sha256: createHash("sha256").update(await fs.readFile(current)).digest("hex")
+      });
+      return;
+    }
+    entries.push({ path: entryPath, kind: "special" });
+  }
+  await visit(directory, "");
+  return entries;
+}
+
+async function snapshotProfileState() {
+  const roots = {
+    home: isolatedEnvironment.HOME,
+    xdgConfig: isolatedEnvironment.XDG_CONFIG_HOME,
+    xdgCache: isolatedEnvironment.XDG_CACHE_HOME,
+    xdgData: isolatedEnvironment.XDG_DATA_HOME
+  };
+  const state = {};
+  for (const [name, directory] of Object.entries(roots)) state[name] = await snapshotDirectoryState(directory);
+  return state;
+}
+
+const previousEnvironment = Object.fromEntries(
+  Object.keys(isolatedEnvironment).map((key) => [key, process.env[key]])
+);
+for (const [key, value] of Object.entries(isolatedEnvironment)) process.env[key] = value;
+const profileStateBefore = await snapshotProfileState();
+let receipt;
+try {
+  const { default: plugin } = await import("../dist/index.js");
+  const hooks = await plugin({ directory: root, worktree: root });
+  const config = {};
+  await hooks.config(config);
+  const context = {
+    sessionID: "surface-session",
+    messageID: "surface-message",
+    agent: "lit-loop",
+    directory: root,
+    worktree: root,
+    abort: new AbortController().signal,
+    metadata() {},
+    async ask() {}
+  };
+  const captured = await hooks.tool.wikify.execute({
+    action: "capture",
+    kind: "decision",
+    text: "Use claims.jsonl as the only project knowledge authority.",
+    evidenceRef: "README.md:165",
+    source: "surface-probe"
+  }, context);
+  const afterOutput = {
+    title: "Structured tool receipt",
+    output: "Raw tool output remains inert.",
+    metadata: {
+      litopencodeKnowledgeCapture: {
+        kind: "fact",
+        text: "An automatic tool receipt starts in review-needed state.",
+        evidenceRef: "README.md:204",
+        source: "surface-probe"
+      }
+    }
+  };
+  await hooks["tool.execute.after"](
+    { tool: "evidence-recorder", sessionID: "surface-session", callID: "surface-call", args: {} },
+    afterOutput
+  );
+  const automaticReceipt = afterOutput.metadata?.litopencodeKnowledgeReceipt;
+  if (
+    automaticReceipt?.status !== "captured" ||
+    !/^kn_[a-f0-9]{24}$/u.test(automaticReceipt.id) ||
+    automaticReceipt.state !== "review-needed"
+  ) {
+    throw new Error("the tool.execute.after hook did not emit a captured review-needed receipt");
+  }
+  const saved = await hooks.tool.wikify.execute({ action: "save", id: captured.metadata.id }, context);
+  if (saved.metadata.state !== "accepted") throw new Error("the tool did not accept the captured record");
+
+  const chatOutput = {
+    message: { id: "surface-chat-message", agent: "lit-loop" },
+    parts: [{ id: "surface-chat-part", type: "text", text: "Which knowledge file is authoritative?" }]
+  };
+  await hooks["chat.message"](
+    { sessionID: "surface-session", messageID: "surface-chat-message", agent: "lit-loop" },
+    chatOutput
+  );
+  const commandOutput = { parts: [] };
+  await hooks["command.execute.before"](
+    { command: "/wikify-query", arguments: "project knowledge authority", sessionID: "surface-session" },
+    commandOutput
+  );
+
+  const claimsPath = path.join(root, ".litopencode", "knowledge", "claims.jsonl");
+  const claims = await fs.readFile(claimsPath, "utf8");
+  await hooks.dispose();
+  const profileStateAfter = await snapshotProfileState();
+  receipt = {
+    status: "PASS",
+    surfaces: {
+      config: config.agent?.["lit-loop"] !== undefined,
+      tool: typeof hooks.tool.wikify.execute === "function",
+      toolExecuteAfter: automaticReceipt.status === "captured" && automaticReceipt.state === "review-needed",
+      chatMessage: chatOutput.parts.some((part) => part.metadata?.litopencodeKnowledge !== undefined),
+      commandExecuteBefore: commandOutput.parts.some((part) => part.metadata?.litopencodeKnowledge !== undefined)
+    },
+    artifact: {
+      path: claimsPath,
+      lineCount: claims.trim().split("\n").length,
+      sha256: createHash("sha256").update(claims).digest("hex")
+    },
+    automaticReceipt: {
+      id: automaticReceipt.id,
+      state: automaticReceipt.state
+    },
+    profileState: {
+      before: profileStateBefore,
+      after: profileStateAfter
+    },
+    liveProfileMutated: JSON.stringify(profileStateBefore) !== JSON.stringify(profileStateAfter)
+  };
+} finally {
+  for (const [key, value] of Object.entries(previousEnvironment)) {
+    if (value === undefined) delete process.env[key];
+    else process.env[key] = value;
+  }
+  await fs.rm(root, { recursive: true, force: true });
+}
+
+process.stdout.write(`${JSON.stringify({ ...receipt, cleanup: { root, removed: true } }, null, 2)}\n`);