@agjs/tsforge 0.2.0 → 0.2.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agjs/tsforge",
   "type": "module",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "license": "MIT",
   "description": "TypeScript coding harness with a deterministic gate, stack-aware guardrails, and stream-level correction.",
   "repository": {
@@ -19,7 +19,8 @@
     "src",
     "scripts",
     "strict.eslint.config.mjs",
-    "strict.web.eslint.config.mjs"
+    "strict.web.eslint.config.mjs",
+    "strict.type-aware.eslint.config.mjs"
   ],
   "engines": {
     "bun": ">=1.3.14"

package/scripts/browser-check.ts

@@ -5,27 +5,59 @@
 //
 //   bun browser-check.ts <htmlFile>                 # render-only (no errors)
 //   bun browser-check.ts <htmlFile> --smoke         # render + generic behaviour smoke
+//   bun browser-check.ts <htmlFile> --a11y          # + axe accessibility (serious/critical fail)
+//   bun browser-check.ts <htmlFile> --screenshots[=dir]  # + per-route PNGs (artifact)
+//   bun browser-check.ts <htmlFile> --perf          # + a basic DOM-size/mount-time budget
 //   bun browser-check.ts <htmlFile> <checks.json>   # render + interaction checks
 //   bun browser-check.ts <htmlFile> <selector> [text]
 import { readdir } from "node:fs/promises";
 import { dirname, join } from "node:path";
-import { renderCheck, parseChecks, type IRenderOptions } from "../src/browser";
+import {
+  renderCheck,
+  parseChecks,
+  type IRenderOptions,
+  type IPerfBudget,
+} from "../src/browser";
 import { crawlableRoutePaths } from "../src/web-routes";
 
 const rawArgs = process.argv.slice(2);
 const smoke = rawArgs.includes("--smoke");
 const crawl = rawArgs.includes("--crawl");
-const [file, arg2, arg3] = rawArgs.filter(
-  (a) => a !== "--smoke" && a !== "--crawl"
-);
+const a11y = rawArgs.includes("--a11y");
+const perf = rawArgs.includes("--perf");
+const screenshotsArg = rawArgs.find((a) => a.startsWith("--screenshots"));
+// Positionals are anything that isn't a recognized `--flag`.
+const [file, arg2, arg3] = rawArgs.filter((a) => !a.startsWith("--"));
 
 if (file === undefined) {
   process.stderr.write(
-    "usage: browser-check.ts <htmlFile> [--smoke] [--crawl] [checks.json | selector [text]]\n"
+    "usage: browser-check.ts <htmlFile> [--smoke] [--crawl] [--a11y] " +
+      "[--screenshots[=dir]] [--perf] [checks.json | selector [text]]\n"
   );
   process.exit(2);
 }
 
+/** A conservative default budget — a tripwire for runaway render trees / slow
+ *  mounts, not a tuned Lighthouse target. */
+const DEFAULT_PERF_BUDGET: IPerfBudget = {
+  maxDomNodes: 5000,
+  maxMountMs: 6000,
+};
+
+/** The screenshot dir: `--screenshots=<dir>`, else a `screenshots/` folder next
+ *  to the HTML file. undefined when `--screenshots` wasn't passed. */
+function screenshotDir(): string | undefined {
+  if (screenshotsArg === undefined) {
+    return undefined;
+  }
+
+  const eq = screenshotsArg.indexOf("=");
+
+  return eq === -1
+    ? join(dirname(file ?? "."), "screenshots")
+    : screenshotsArg.slice(eq + 1);
+}
+
 /** With --crawl, enumerate the app's static routes from `<buildDir>/src/routes/`
  *  (the build dir is the parent of dist/) so every page — not just the home —
  *  is render-checked. Dynamic ($param) routes are skipped. */
@@ -66,10 +98,14 @@ async function checksFor(): Promise<Partial<IRenderOptions>> {
   };
 }
 
+const shots = screenshotDir();
 const result = await renderCheck({
   file,
   smoke,
+  a11y,
   routes: await routesFor(),
+  ...(perf ? { perfBudget: DEFAULT_PERF_BUDGET } : {}),
+  ...(shots !== undefined ? { screenshotDir: shots } : {}),
   ...(await checksFor()),
 });
 

package/scripts/cli-metrics.ts

@@ -10,6 +10,7 @@ import { readdir } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { isRecord } from "../src/lib/guards";
+import { classifyRun, parseEventLog } from "../src/eval";
 
 function num(value: unknown): number {
   return typeof value === "number" ? value : 0;
@@ -168,6 +169,9 @@ async function main(): Promise<void> {
   const text = await Bun.file(path).text();
   const lines = text.split("\n").filter((l) => l.trim().length > 0);
   const m = analyze(lines);
+  // Single source of truth for WHY a run failed — the same classifier the eval
+  // sweep and the reusable analyzeEvents() use, fed the typed event stream.
+  const failure = classifyRun(parseEventLog(text));
   const pct =
     m.contextWindow > 0
       ? Math.round((m.peakContext / m.contextWindow) * 100)
@@ -182,6 +186,12 @@ async function main(): Promise<void> {
     ["model", m.model],
     ["context window", String(m.contextWindow)],
     ["final status", m.finalStatus],
+    [
+      "failure class",
+      failure.detail === undefined
+        ? failure.failureClass
+        : `${failure.failureClass} (${failure.detail})`,
+    ],
     ["turns (repair iterations)", String(m.turns)],
     ["model calls", String(m.modelCalls)],
     ["tokens out (→ solution)", String(m.tokensOut)],

package/scripts/sweep.ts

@@ -12,7 +12,13 @@ import { modelAgent } from "../src/agent";
 import { OpenAICompatibleProvider } from "../src/inference";
 import { resolveActiveModel, resolveApiKey } from "../src/models-config";
 import { providerConfig } from "../src/cli";
-import { summarize, type IRunRecord } from "../src/eval";
+import {
+  summarize,
+  classifyRun,
+  renderSweepReportMarkdown,
+  buildSweepReport,
+  type IRunRecord,
+} from "../src/eval";
 import { renderEvent } from "../src/render";
 import type { ILoopEvent } from "../src/loop";
 
@@ -268,8 +274,12 @@ async function runOne(
     // Every run gets a full transcript at <runDir>/run.log; stream to the
     // terminal too when TSFORGE_STREAM=1.
     const log = Bun.file(join(runDir, "run.log")).writer();
+    // Keep the structured events so a failed run can be classified (WHY it
+    // failed), not just counted — fed to classifyRun below.
+    const runEvents: ILoopEvent[] = [];
 
     const onEvent = (e: ILoopEvent): void => {
+      runEvents.push(e);
       void log.write(renderEvent(e, { color: false }));
       // Flush per event — otherwise Bun's FileSink buffers and `tail -f` shows
       // nothing until the run ends. The log must be live.
@@ -359,6 +369,9 @@ async function runOne(
     );
 
     const vLabel = variantLabel(variantEnv);
+    const failureClass = passed
+      ? undefined
+      : classifyRun(runEvents).failureClass;
 
     records.push({
       label: `${vLabel} temp=${temp}`,
@@ -366,9 +379,10 @@ async function runOne(
       cycles,
       ms,
       quality,
+      ...(failureClass === undefined ? {} : { failureClass }),
     });
     process.stdout.write(
-      `  ${seed} ${vLabel} temp=${temp} #${i + 1}: ${passed ? "done" : "blocked"} (${cycles} cyc, ${edits} edits, ${regressions} regress, ${ms}ms${quality === undefined ? "" : `, Q${quality}/5`}) → ${runId}\n`
+      `  ${seed} ${vLabel} temp=${temp} #${i + 1}: ${passed ? "done" : `blocked[${failureClass ?? "unknown"}]`} (${cycles} cyc, ${edits} edits, ${regressions} regress, ${ms}ms${quality === undefined ? "" : `, Q${quality}/5`}) → ${runId}\n`
     );
   } finally {
     restore();
@@ -380,11 +394,22 @@ const summaries = summarize(records);
 process.stdout.write(`\n=== sweep: ${seed} (${repeats} runs/variant) ===\n`);
 
 for (const s of summaries) {
+  const failures = Object.entries(s.failureClasses)
+    .sort(([, a], [, b]) => b - a)
+    .map(([cls, n]) => `${cls}×${String(n)}`)
+    .join(", ");
+
   process.stdout.write(
-    `${s.label.padEnd(10)}  pass ${Math.round(s.passRate * 100)}% (${s.passed}/${s.runs})  Q ${s.avgQuality.toFixed(1)}/5  avg ${s.avgCycles.toFixed(1)} cyc  ${Math.round(s.avgMs)}ms\n`
+    `${s.label.padEnd(10)}  pass ${Math.round(s.passRate * 100)}% (${s.passed}/${s.runs})  Q ${s.avgQuality.toFixed(1)}/5  avg ${s.avgCycles.toFixed(1)} cyc  ${Math.round(s.avgMs)}ms${failures.length > 0 ? `  [${failures}]` : ""}\n`
   );
 }
 
+// The statistical report (Wilson CI + z-test vs baseline) now also tabulates a
+// per-variant failure-class breakdown — WHY runs failed, not just how often.
+process.stdout.write(
+  `\n${renderSweepReportMarkdown(buildSweepReport(records))}\n`
+);
+
 const outPath = join(evalsRoot, "runs", `sweep-${seed}-${stamp()}.json`);
 
 await Bun.write(

package/src/browser/index.ts

@@ -1,8 +1,11 @@
 export {
   renderCheck,
+  summarizeAxeViolations,
+  checkPerfBudget,
   type IRenderOptions,
   type IRenderExpect,
   type IRenderResult,
   type IStep,
+  type IPerfBudget,
 } from "./oracle";
 export { parseChecks } from "./checks";

package/src/browser/oracle.ts

@@ -1,4 +1,5 @@
 import { resolve, dirname, basename, join } from "node:path";
+import { isRecord } from "../lib/guards";
 // `playwright` is an OPTIONAL peer: bundling it (+ a browser binary) into every
 // install is too heavy, so the import is dynamic and the render-check skips when
 // it's absent. The type-only import is erased at runtime, so it can't crash a
@@ -14,6 +15,20 @@ async function loadChromium(): Promise<typeof Chromium | null> {
   }
 }
 
+/** Run axe against a page and return its raw result; null when @axe-core/
+ *  playwright isn't installed (a11y is an optional enhancement, like the browser
+ *  itself). Kept untyped at the boundary — extractAxeViolations narrows it. */
+async function runAxe(page: Page): Promise<unknown> {
+  try {
+    const mod = await import("@axe-core/playwright");
+    const builder = new mod.AxeBuilder({ page });
+
+    return await builder.analyze();
+  } catch {
+    return null;
+  }
+}
+
 /**
  * The browser oracle — renders a built web page in headless chromium and reports
  * whether it actually WORKS, beyond what tsc/eslint can see: it fails on uncaught
@@ -55,22 +70,121 @@ export interface IRenderOptions {
    *  single-page smoke misses them. Served with SPA fallback so the client
    *  router handles the path. Empty/undefined → no crawl (unchanged behavior). */
   routes?: string[];
+  /** Run axe accessibility checks on the page (and each crawled route). Serious
+   *  and critical violations become gate errors; minor/moderate are skipped.
+   *  Skipped gracefully when @axe-core/playwright isn't installed. */
+  a11y?: boolean;
+  /** Directory to write a screenshot per page/route into (desktop + mobile
+   *  viewports). An artifact for human/visual review — never a pass/fail signal. */
+  screenshotDir?: string;
+  /** A perf budget (DOM node count + mount time) checked on the initial page. */
+  perfBudget?: IPerfBudget;
   /** Navigation timeout (default 15s). */
   timeoutMs?: number;
 }
 
+/** Screenshot viewports — a desktop and a mobile pass per page. */
+const VIEWPORTS = [
+  { name: "desktop", width: 1280, height: 800 },
+  { name: "mobile", width: 390, height: 844 },
+] as const;
+
 export interface IRenderResult {
   ok: boolean;
   /** Human-readable failures (console errors, page errors, missing content). */
   errors: string[];
   /** True when the check was skipped because playwright isn't installed. */
   skipped?: boolean;
+  /** Paths of screenshots captured (when `screenshotDir` was set). */
+  screenshots?: string[];
+}
+
+/** A simple performance budget: fail the render when the built app blows past
+ *  these. Intentionally minimal (no full Lighthouse) — a tripwire, not a profiler. */
+export interface IPerfBudget {
+  /** Max total DOM nodes after load (a proxy for over-heavy render trees). */
+  maxDomNodes?: number;
+  /** Max time from navigation start to DOMContentLoaded, in ms. */
+  maxMountMs?: number;
+}
+
+/** axe impact levels that FAIL the a11y check — minor/moderate are reported by
+ *  axe but don't gate (too noisy to block a build on). */
+const AXE_FAIL_IMPACTS = new Set(["serious", "critical"]);
+
+/** The subset of an axe violation the oracle reports on. */
+interface IAxeViolation {
+  id: string;
+  impact: string | undefined;
+  nodeCount: number;
+}
+
+/** Extract the reportable violations from axe's (untyped, dynamically-imported)
+ *  result — narrowed with guards, no casts. */
+function extractAxeViolations(result: unknown): IAxeViolation[] {
+  if (!isRecord(result) || !Array.isArray(result.violations)) {
+    return [];
+  }
+
+  const out: IAxeViolation[] = [];
+
+  for (const v of result.violations) {
+    if (!isRecord(v) || typeof v.id !== "string") {
+      continue;
+    }
+
+    out.push({
+      id: v.id,
+      impact: typeof v.impact === "string" ? v.impact : undefined,
+      nodeCount: Array.isArray(v.nodes) ? v.nodes.length : 0,
+    });
+  }
+
+  return out;
+}
+
+/** Turn axe violations into gate errors — only serious/critical fail. Pure. */
+export function summarizeAxeViolations(
+  violations: readonly IAxeViolation[],
+  where: string
+): string[] {
+  return violations
+    .filter((v) => v.impact !== undefined && AXE_FAIL_IMPACTS.has(v.impact))
+    .map(
+      (v) =>
+        `a11y ${v.impact ?? "?"} at ${where}: ${v.id} (${String(v.nodeCount)} node(s))`
+    );
+}
+
+/** Evaluate a perf budget against measured values → gate errors. Pure. */
+export function checkPerfBudget(
+  domNodes: number,
+  mountMs: number,
+  budget: IPerfBudget,
+  where: string
+): string[] {
+  const errors: string[] = [];
+
+  if (budget.maxDomNodes !== undefined && domNodes > budget.maxDomNodes) {
+    errors.push(
+      `perf at ${where}: ${String(domNodes)} DOM nodes > budget ${String(budget.maxDomNodes)}`
+    );
+  }
+
+  if (budget.maxMountMs !== undefined && mountMs > budget.maxMountMs) {
+    errors.push(
+      `perf at ${where}: mount ${String(Math.round(mountMs))}ms > budget ${String(budget.maxMountMs)}ms`
+    );
+  }
+
+  return errors;
 }
 
 export async function renderCheck(
   opts: IRenderOptions
 ): Promise<IRenderResult> {
   const errors: string[] = [];
+  const screenshots: string[] = [];
   const chromium = await loadChromium();
 
   // No playwright → skip the render check rather than fail the gate. The build
@@ -87,7 +201,10 @@ export async function renderCheck(
   const browser = await chromium.launch({ args: ["--no-sandbox"] });
 
   try {
-    const page = await browser.newPage();
+    // Page via an explicit context (not browser.newPage()) — axe-core/playwright
+    // requires a context-owned page; browser.close() tears the context down too.
+    const context = await browser.newContext();
+    const page = await context.newPage();
     const timeout = opts.timeoutMs ?? 15_000;
 
     page.on("console", (message) => {
@@ -113,30 +230,39 @@ export async function renderCheck(
           waitUntil: "load",
           timeout,
         });
-        await runChecks(page, opts, errors);
+        await runChecks(page, opts, errors, screenshots);
 
         if (opts.routes !== undefined && opts.routes.length > 0) {
-          await crawlRoutes(page, base, opts.routes, errors, timeout);
+          await crawlRoutes(page, base, opts.routes, errors, timeout, {
+            opts,
+            screenshots,
+          });
         }
       } finally {
         await server.stop(true);
       }
     } else {
       await page.setContent(opts.html ?? "", { waitUntil: "load", timeout });
-      await runChecks(page, opts, errors);
+      await runChecks(page, opts, errors, screenshots);
     }
 
-    return { ok: errors.length === 0, errors };
+    return {
+      ok: errors.length === 0,
+      errors,
+      ...(screenshots.length > 0 ? { screenshots } : {}),
+    };
   } finally {
     await browser.close();
   }
 }
 
-/** The expectation + step + smoke checks that run against the loaded page. */
+/** The expectation + step + smoke checks that run against the loaded page, then
+ *  the optional quality oracles (a11y, perf budget, screenshots). */
 async function runChecks(
   page: Page,
   opts: IRenderOptions,
-  errors: string[]
+  errors: string[],
+  screenshots: string[]
 ): Promise<void> {
   await checkExpectations(page, opts.expect, errors);
 
@@ -147,6 +273,76 @@ async function runChecks(
   if (opts.smoke === true) {
     await runSmoke(page, errors);
   }
+
+  await runQualityOracles(page, opts, "index", errors, screenshots);
+}
+
+/** The opt-in quality layer: accessibility (axe), a perf budget, and screenshots.
+ *  Each is independent and skips cleanly when not requested / dep absent. */
+async function runQualityOracles(
+  page: Page,
+  opts: IRenderOptions,
+  where: string,
+  errors: string[],
+  screenshots: string[]
+): Promise<void> {
+  if (opts.a11y === true) {
+    const violations = extractAxeViolations(await runAxe(page));
+
+    errors.push(...summarizeAxeViolations(violations, where));
+  }
+
+  if (opts.perfBudget !== undefined) {
+    const { domNodes, mountMs } = await measurePage(page);
+
+    errors.push(...checkPerfBudget(domNodes, mountMs, opts.perfBudget, where));
+  }
+
+  if (opts.screenshotDir !== undefined) {
+    await capturePage(page, opts.screenshotDir, where, screenshots);
+  }
+}
+
+/** Measure DOM size + mount time for the perf budget. */
+async function measurePage(
+  page: Page
+): Promise<{ domNodes: number; mountMs: number }> {
+  return page.evaluate(() => {
+    const nav = performance.getEntriesByType("navigation")[0];
+    const mountMs =
+      nav instanceof PerformanceNavigationTiming
+        ? nav.domContentLoadedEventEnd - nav.startTime
+        : 0;
+
+    return { domNodes: document.querySelectorAll("*").length, mountMs };
+  });
+}
+
+/** Filesystem-safe label for a route (e.g. "/a/b" → "a-b", "/" → "index"). */
+function routeLabel(route: string): string {
+  const cleaned = route.replace(/^\/+|\/+$/g, "").replace(/\//g, "-");
+
+  return cleaned.length === 0 ? "index" : cleaned;
+}
+
+/** Capture a desktop + mobile screenshot of the current page into `dir`. */
+async function capturePage(
+  page: Page,
+  dir: string,
+  label: string,
+  screenshots: string[]
+): Promise<void> {
+  for (const vp of VIEWPORTS) {
+    const path = join(dir, `${label}-${vp.name}.png`);
+
+    try {
+      await page.setViewportSize({ width: vp.width, height: vp.height });
+      await page.screenshot({ path, fullPage: true });
+      screenshots.push(path);
+    } catch {
+      // A screenshot is a best-effort artifact, never a gate failure.
+    }
+  }
 }
 
 /** Serve a directory on an ephemeral localhost port. SPA FALLBACK: an
@@ -187,7 +383,8 @@ async function crawlRoutes(
   base: string,
   routes: readonly string[],
   errors: string[],
-  timeout: number
+  timeout: number,
+  quality: { opts: IRenderOptions; screenshots: string[] }
 ): Promise<void> {
   for (const route of routes) {
     try {
@@ -207,7 +404,17 @@ async function crawlRoutes(
 
       if (blank) {
         errors.push(`route ${route} rendered blank`);
+        continue;
       }
+
+      // a11y + screenshots per route (perf budget stays an initial-page check).
+      await runQualityOracles(
+        page,
+        { ...quality.opts, perfBudget: undefined },
+        routeLabel(route),
+        errors,
+        quality.screenshots
+      );
     } catch (error) {
       errors.push(
         `route ${route} failed to load: ${error instanceof Error ? error.message : String(error)}`

package/src/cli.ts

@@ -102,11 +102,15 @@ export interface ICliArgs {
   /** Plan mode: a from-scratch build pauses after the design phase to show its
    *  plan for review/edit before implementing (`--plan`; also toggled by /plan). */
   plan: boolean;
+  /** Keep the auto-gate at the strict TS floor only — do NOT append the
+   *  project's discovered tests (`--strict-floor-only`). By default the auto-gate
+   *  also runs the project's tests, so "green" means floor + tests pass. */
+  strictFloorOnly: boolean;
 }
 
 const BOOL_FLAGS: Record<
   string,
-  "continue" | "noGate" | "web" | "log" | "plan"
+  "continue" | "noGate" | "web" | "log" | "plan" | "strictFloorOnly"
 > = {
   "--continue": "continue",
   "-c": "continue",
@@ -114,6 +118,7 @@ const BOOL_FLAGS: Record<
   "--web": "web",
   "--log": "log",
   "--plan": "plan",
+  "--strict-floor-only": "strictFloorOnly",
 };
 
 const VALUE_FLAGS = new Set([
@@ -140,6 +145,7 @@ export function parseArgs(argv: readonly string[]): ICliArgs {
     web: false,
     log: false,
     plan: false,
+    strictFloorOnly: false,
   };
 
   for (let i = 0; i < argv.length; i += 1) {
@@ -812,7 +818,13 @@ async function baseGate(
     args.dir,
     activePacks,
     Object.keys(ruleOverrides).length > 0 ? ruleOverrides : undefined,
-    { enableTypeAware: profile === "strict" }
+    {
+      enableTypeAware: profile === "strict",
+      // "Green" should mean the strict floor AND the project's own tests pass —
+      // not just that it type-checks and lints. discoverTestCommand appends them
+      // only when the project actually has tests; --strict-floor-only opts out.
+      includeTests: !args.strictFloorOnly,
+    }
   );
 
   return { accept: auto.command, gateLabel: auto.label };

package/src/detect-gate.ts

@@ -2,6 +2,7 @@ import { join, dirname } from "node:path";
 import { existsSync } from "node:fs";
 import { ESLint } from "eslint";
 import { WEB_TEMPLATES, type WebFramework } from "./web-templates";
+import { isRecord } from "./lib/guards";
 
 /**
  * Build the gate that confirms "done" — and makes tsforge a TypeScript-SPECIALIZED
@@ -106,10 +107,16 @@ const STRICT_TSCONFIG = `{
 /** Strict overlay for a project that ALREADY has a tsconfig: extend it (so the
  *  project's paths/jsx/module/lib still resolve — a bare strict config would
  *  mis-compile a real app) but FORCE every strictness flag on top, so a loosely-
- *  configured repo still gets tsforge's strict-TS floor. Written as a sibling
- *  `tsforge.tsconfig.json` and gated with `tsc -p`. */
-const STRICT_TSCONFIG_OVERRIDE = `{
-  "extends": "./tsconfig.json",
+ *  configured repo still gets tsforge's strict-TS floor.
+ *
+ *  PERSISTENCE POLICY: written under `.tsforge/` (tsforge's cache namespace), NOT
+ *  as a sibling in the project root — so the gate never litters the user's repo
+ *  with a `tsforge.tsconfig.json`. `extends` points one level up to the project's
+ *  own config, and `include`/`exclude` are re-stated relative to the subdir
+ *  because `extends` does not inherit them (they default to the config's own
+ *  directory otherwise — which under `.tsforge/` would compile nothing). */
+const STRICT_TSCONFIG_OVERLAY = `{
+  "extends": "../tsconfig.json",
   "compilerOptions": {
     "strict": true,
     "noUncheckedIndexedAccess": true,
@@ -119,10 +126,16 @@ const STRICT_TSCONFIG_OVERRIDE = `{
     "erasableSyntaxOnly": true,
     "skipLibCheck": true,
     "noEmit": true
-  }
+  },
+  "include": ["../**/*.ts", "../**/*.tsx"],
+  "exclude": ["../node_modules", "../dist", "../build", "../scratch", "../.tsforge"]
 }
 `;
 
+/** The gate overlay's home: tsforge's cache dir + the overlay filename. */
+const GATE_TSCONFIG_DIR = ".tsforge";
+const GATE_TSCONFIG_FILE = "tsconfig.gate.json";
+
 // The web-stack scaffolds (Vite + React full-kit, or Vite vanilla) live in the
 // registry; this module just lays them down and builds their gate. shadcn/TanStack
 // boilerplate is held to a web-tailored strict config (no `I`-prefix — React names
@@ -373,7 +386,12 @@ export function buildWebGate(framework: WebFramework): IGate {
   // HARNESS-authored and app-agnostic: we deliberately do NOT run a model-authored
   // checks.json — the 27b writes over-strict interaction assertions (exact
   // placeholders/fill flows) it then can't satisfy and spirals on (iter3/4).
-  const render = `bun "${BROWSER_CHECK}" dist/index.html --smoke --crawl`;
+  // OPT-IN quality oracles (default OFF so existing web runs are unchanged):
+  // TSFORGE_A11Y=1 adds axe (serious/critical fail), TSFORGE_SCREENSHOTS=1 writes
+  // per-route PNGs. A "frontend"/"strict" profile can set these.
+  const a11y = process.env.TSFORGE_A11Y === "1" ? " --a11y" : "";
+  const shots = process.env.TSFORGE_SCREENSHOTS === "1" ? " --screenshots" : "";
+  const render = `bun "${BROWSER_CHECK}" dist/index.html --smoke --crawl${a11y}${shots}`;
   // Prettier enforces formatting (the fix step runs `prettier --write` first, so
   // this passes without the model ever hand-formatting). Respects .prettierignore
   // (vendored ui/ + lib/ skipped). Runs after lint so a parse error fails there.
@@ -468,7 +486,7 @@ export async function buildGate(
   cwd: string,
   packs?: readonly string[],
   ruleOverrides?: Readonly<Record<string, "error" | "warn" | "off">>,
-  options?: { enableTypeAware?: boolean }
+  options?: { enableTypeAware?: boolean; includeTests?: boolean }
 ): Promise<IGate> {
   const parts: string[] = [];
   const labels: string[] = [];
@@ -494,29 +512,95 @@ export async function buildGate(
     }
   }
 
+  // Tests run LAST (after the cheap static floor) so a type/lint error fails
+  // fast without paying for a test run. Only appended when the project actually
+  // has tests to run — a strict-floor-only run, or a project with none, skips it.
+  if (options?.includeTests === true) {
+    const test = await discoverTestCommand(cwd);
+
+    if (test !== null) {
+      parts.push(test);
+      labels.push("tests");
+    }
+  }
+
   return { command: parts.join(" && "), label: labels.join(" + ") };
 }
 
+/** The npm-init placeholder test script — running it always fails, so it must
+ *  NOT count as "the project has tests". */
+const PLACEHOLDER_TEST = /no test specified/i;
+
+/**
+ * The project's test command for the gate, or null when there's nothing to run.
+ * Prefers an explicit, real package.json `test` script (run via `bun run test`);
+ * else falls back to `bun test` when the project has test files; else null — so
+ * a greenfield app with no tests yet stays at the strict floor instead of
+ * failing a gate that runs a placeholder/absent test command.
+ */
+export async function discoverTestCommand(cwd: string): Promise<string | null> {
+  const pkgFile = Bun.file(join(cwd, "package.json"));
+
+  if (await pkgFile.exists()) {
+    try {
+      const pkg: unknown = await pkgFile.json();
+      const scripts = isRecord(pkg) ? pkg.scripts : undefined;
+      const script = isRecord(scripts) ? scripts.test : undefined;
+
+      if (
+        typeof script === "string" &&
+        script.trim().length > 0 &&
+        !PLACEHOLDER_TEST.test(script)
+      ) {
+        return "bun run test";
+      }
+    } catch {
+      // Malformed package.json — fall through to file detection.
+    }
+  }
+
+  return (await hasTestFiles(cwd)) ? "bun test" : null;
+}
+
+/** True when the project has at least one *.test.* / *.spec.* file (outside
+ *  node_modules) — the signal that a bare `bun test` has something to run. */
+async function hasTestFiles(cwd: string): Promise<boolean> {
+  const glob = new Bun.Glob("**/*.{test,spec}.{ts,tsx,js,jsx}");
+
+  for await (const path of glob.scan({ cwd, onlyFiles: true })) {
+    if (!path.includes("node_modules")) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
 /**
  * The type-aware floor — ALWAYS tsforge-strict (user policy: a repo's own config
- * is never trusted to be strict enough). With a project tsconfig, extend it but
- * force the strict flags; greenfield, bring the full strict one. null when not a
- * TS project. (The strict override / bundled config win over whatever the repo set.)
+ * is never trusted to be strict enough). With a project tsconfig, extend it under
+ * `.tsforge/` but force the strict flags; greenfield, bring the full strict one.
+ * null when not a TS project. (The strict overlay / bundled config win over
+ * whatever the repo set.)
  */
 async function tscPart(cwd: string): Promise<string | null> {
   const hasTsconfig = await Bun.file(join(cwd, "tsconfig.json")).exists();
 
   if (hasTsconfig) {
+    // EPHEMERAL gate artifact: lives in .tsforge/ (Bun.write makes the dir), so
+    // we never drop a tsforge.tsconfig.json in the user's project root.
     await Bun.write(
-      join(cwd, "tsforge.tsconfig.json"),
-      STRICT_TSCONFIG_OVERRIDE
+      join(cwd, GATE_TSCONFIG_DIR, GATE_TSCONFIG_FILE),
+      STRICT_TSCONFIG_OVERLAY
     );
+    await ignoreGateArtifact(cwd);
 
-    return `"${TSC_BIN}" --noEmit -p tsforge.tsconfig.json`;
+    return `"${TSC_BIN}" --noEmit -p ${GATE_TSCONFIG_DIR}/${GATE_TSCONFIG_FILE}`;
   }
 
   // Greenfield: bring a strict tsconfig so tsc can gate — but only when this is
   // actually a TS project (has a package.json), so we never litter a random dir.
+  // Unlike the overlay, a greenfield tsconfig.json is a DURABLE project file.
   if (await Bun.file(join(cwd, "package.json")).exists()) {
     await Bun.write(join(cwd, "tsconfig.json"), STRICT_TSCONFIG);
 
@@ -526,6 +610,20 @@ async function tscPart(cwd: string): Promise<string | null> {
   return null;
 }
 
+/** Keep the ephemeral gate overlay out of git WITHOUT touching the user's root
+ *  .gitignore: drop a scoped `.tsforge/.gitignore` ignoring just the overlay.
+ *  Created only when absent, so a user-authored `.tsforge/.gitignore` (e.g. one
+ *  that intentionally tracks rules.json) is never clobbered. */
+async function ignoreGateArtifact(cwd: string): Promise<void> {
+  const ignore = join(cwd, GATE_TSCONFIG_DIR, ".gitignore");
+
+  if (await Bun.file(ignore).exists()) {
+    return;
+  }
+
+  await Bun.write(ignore, `${GATE_TSCONFIG_FILE}\n`);
+}
+
 /** The syntactic idiom layer — ALWAYS tsforge's bundled strict eslint config
  *  (user policy). We deliberately do NOT defer to the project's own `lint`
  *  script: that's exactly how a weak repo would dodge the strict-TS floor. The

package/src/eval/eval.types.ts

@@ -1,3 +1,5 @@
+import type { FailureClass } from "./failure-class";
+
 export interface IJudgeInput {
   goal: string;
   criteria: string;
@@ -21,6 +23,9 @@ export interface IRunRecord {
   ms: number;
   /** LLM-judge quality score (1–5), when available. */
   quality?: number;
+  /** Structured reason a failed run failed (from classifyRun); omitted/`none`
+   *  for a passing run. The substrate for turning failures into interventions. */
+  failureClass?: FailureClass;
 }
 
 /** Aggregated metrics for a variant across its runs. */
@@ -33,4 +38,8 @@ export interface IVariantSummary {
   avgMs: number;
   /** Average quality across runs that were scored (0 if none). */
   avgQuality: number;
+  /** Count of failed runs by failure class (e.g. {"type-error": 2}); empty when
+   *  no run carried a class. Lets a sweep show WHY a variant failed, not just how
+   *  often. */
+  failureClasses: Record<string, number>;
 }

package/src/eval/failure-class.ts

@@ -0,0 +1,263 @@
+import type { ILoopEvent } from "../loop/loop.types";
+import type { ErrorSet } from "../validate/validate.types";
+
+/**
+ * Why a run failed — a structured reason, so every failed run maps to a possible
+ * harness intervention (the self-improving north-star). Derived purely from the
+ * event stream (+ an optional final gate error set), so the same classifier
+ * serves the live loop, the eval sweep, and the offline log analyzer.
+ */
+export const FAILURE_CLASS = {
+  /** The run reached a green gate — no failure. */
+  none: "none",
+  /** Model emitted tool calls the parser couldn't read (repair L3 / salvage). */
+  toolMalformed: "tool-malformed",
+  /** Edits kept missing their target (missing-file / not-found / ambiguous). */
+  editReject: "edit-reject",
+  /** Hit the turn cap or the gate stalled with no decisive error class. */
+  noProgress: "no-progress",
+  /** Final gate red dominated by tsc type errors. */
+  typeError: "type-error",
+  /** Final gate red dominated by ESLint rule violations. */
+  lintRule: "lint-rule",
+  /** Imported a module that doesn't exist (TS2307 / "Cannot find module"). */
+  hallucinatedImport: "hallucinated-import",
+  /** Output degenerated into a repetition loop (StreamGuard fired). */
+  degeneration: "degeneration",
+  /** A per-call/timeout backstop tripped. */
+  timeout: "timeout",
+  /** A route rendered as an empty/phantom page. */
+  routePhantom: "route-phantom",
+  /** The built app failed to render / threw in the browser oracle. */
+  browserFail: "browser-fail",
+  /** The bundler/build step (vite) failed. */
+  buildFail: "build-fail",
+  /** Failed, but no signal was decisive. */
+  unknown: "unknown",
+} as const;
+
+export type FailureClass = (typeof FAILURE_CLASS)[keyof typeof FAILURE_CLASS];
+
+/** Per-signal tallies behind a classification — kept for debugging/telemetry. */
+export interface IFailureSignals {
+  repairs: number;
+  salvages: number;
+  editRejects: number;
+  degenerated: boolean;
+  tsErrors: number;
+  lintErrors: number;
+  missingModule: number;
+  browser: number;
+  build: number;
+}
+
+export interface IFailureSummary {
+  failureClass: FailureClass;
+  /** The dominant rule/code for type-error|lint-rule (e.g. "TS18048", "no-as"). */
+  detail?: string;
+  signals: IFailureSignals;
+}
+
+const TS_CODE = /^TS\d+$/;
+const MISSING_MODULE = /cannot find module/i;
+const DEGENERATE = /degenerat/i;
+const TOOL_MALFORMED = /salvage|recovered|malformed|re-ask/i;
+const REJECTED = /reject/i;
+const BROWSER = /blank|did not render|did not mount|page error|uncaught/i;
+const ROUTE = /route|phantom|stub/i;
+const BUILD = /vite|esbuild|build failed|bundl/i;
+
+/** The most frequently occurring string, or undefined for an empty list. */
+function mostCommon(values: readonly string[]): string | undefined {
+  const counts = new Map<string, number>();
+  let best: string | undefined;
+  let bestN = 0;
+
+  for (const value of values) {
+    const n = (counts.get(value) ?? 0) + 1;
+
+    counts.set(value, n);
+
+    if (n > bestN) {
+      bestN = n;
+      best = value;
+    }
+  }
+
+  return best;
+}
+
+/** The final red gate's rules: prefer the explicit error set, else the rules
+ *  carried on the last failing `validated` event. */
+function finalRules(
+  events: readonly ILoopEvent[],
+  finalErrors?: ErrorSet
+): string[] {
+  if (finalErrors !== undefined) {
+    return finalErrors.flatMap((e) => (e.rule === undefined ? [] : [e.rule]));
+  }
+
+  let last: readonly string[] = [];
+
+  for (const event of events) {
+    if (event.kind === "validated" && event.passed === false && event.rules) {
+      last = event.rules;
+    }
+  }
+
+  return [...last];
+}
+
+/** Concatenated message/output text across the run — for keyword signals that
+ *  aren't structured into a dedicated field (missing module, browser, build). */
+function runText(
+  events: readonly ILoopEvent[],
+  finalErrors?: ErrorSet
+): string {
+  const parts: string[] = [];
+
+  for (const event of events) {
+    parts.push(event.message);
+
+    if (event.output !== undefined) {
+      parts.push(event.output);
+    }
+  }
+
+  for (const e of finalErrors ?? []) {
+    parts.push(e.message);
+  }
+
+  return parts.join("\n");
+}
+
+function gatherSignals(
+  events: readonly ILoopEvent[],
+  finalErrors?: ErrorSet
+): IFailureSignals {
+  const rules = finalRules(events, finalErrors);
+  const text = runText(events, finalErrors);
+  const missingModule =
+    rules.filter((r) => r === "TS2307").length +
+    (MISSING_MODULE.test(text) ? 1 : 0);
+
+  return {
+    repairs: events.filter((e) => e.kind === "repair").length,
+    salvages: events.filter(
+      (e) => e.kind === "tool" && TOOL_MALFORMED.test(e.message)
+    ).length,
+    editRejects: events.filter(
+      (e) => e.kind === "edit" && REJECTED.test(e.message)
+    ).length,
+    degenerated: events.some((e) => DEGENERATE.test(e.message)),
+    tsErrors: rules.filter((r) => TS_CODE.test(r) && r !== "TS2307").length,
+    lintErrors: rules.filter((r) => !TS_CODE.test(r)).length,
+    missingModule,
+    browser: BROWSER.test(text) ? 1 : 0,
+    build: BUILD.test(text) ? 1 : 0,
+  };
+}
+
+function finalStatusOf(
+  events: readonly ILoopEvent[]
+): "done" | "stuck" | "none" {
+  let status: "done" | "stuck" | "none" = "none";
+
+  for (const event of events) {
+    if (event.kind === "done") {
+      status = "done";
+    } else if (event.kind === "stuck") {
+      status = "stuck";
+    }
+  }
+
+  return status;
+}
+
+/** Pick the dominant gate-error class (type vs lint), with its commonest code. */
+function classifyGateErrors(
+  events: readonly ILoopEvent[],
+  finalErrors: ErrorSet | undefined,
+  signals: IFailureSignals
+): IFailureSummary | undefined {
+  const rules = finalRules(events, finalErrors);
+
+  if (signals.tsErrors > 0 && signals.tsErrors >= signals.lintErrors) {
+    return {
+      failureClass: FAILURE_CLASS.typeError,
+      detail: mostCommon(rules.filter((r) => TS_CODE.test(r))),
+      signals,
+    };
+  }
+
+  if (signals.lintErrors > 0) {
+    return {
+      failureClass: FAILURE_CLASS.lintRule,
+      detail: mostCommon(rules.filter((r) => !TS_CODE.test(r))),
+      signals,
+    };
+  }
+
+  return undefined;
+}
+
+/** Behavioral fallback when no gate-error class dominates. */
+function classifyBehavior(signals: IFailureSignals): FailureClass {
+  if (signals.degenerated) {
+    return FAILURE_CLASS.degeneration;
+  }
+
+  if (signals.salvages > 0 || signals.repairs > 0) {
+    return FAILURE_CLASS.toolMalformed;
+  }
+
+  if (signals.editRejects > 0) {
+    return FAILURE_CLASS.editReject;
+  }
+
+  return FAILURE_CLASS.noProgress;
+}
+
+/**
+ * Classify a run from its event stream. Pass the final gate `ErrorSet` when the
+ * caller has it (authoritative); otherwise the classifier falls back to the
+ * `rules` carried on the last failing `validated` event and keyword signals.
+ * A run that reached a green gate classifies as `none`.
+ */
+export function classifyRun(
+  events: readonly ILoopEvent[],
+  finalErrors?: ErrorSet
+): IFailureSummary {
+  const signals = gatherSignals(events, finalErrors);
+
+  if (finalStatusOf(events) === "done") {
+    return { failureClass: FAILURE_CLASS.none, signals };
+  }
+
+  if (signals.missingModule > 0) {
+    return { failureClass: FAILURE_CLASS.hallucinatedImport, signals };
+  }
+
+  if (signals.browser > 0) {
+    const text = runText(events, finalErrors);
+
+    return {
+      failureClass: ROUTE.test(text)
+        ? FAILURE_CLASS.routePhantom
+        : FAILURE_CLASS.browserFail,
+      signals,
+    };
+  }
+
+  if (signals.build > 0 && signals.tsErrors === 0 && signals.lintErrors === 0) {
+    return { failureClass: FAILURE_CLASS.buildFail, signals };
+  }
+
+  const gate = classifyGateErrors(events, finalErrors, signals);
+
+  if (gate !== undefined) {
+    return gate;
+  }
+
+  return { failureClass: classifyBehavior(signals), signals };
+}

package/src/eval/index.ts

@@ -2,6 +2,14 @@ export * from "./eval.types";
 export { judge } from "./judge";
 export { summarize } from "./score";
 export { analyzeEvents, type IRunMetrics } from "./metrics";
+export {
+  classifyRun,
+  FAILURE_CLASS,
+  type FailureClass,
+  type IFailureSummary,
+  type IFailureSignals,
+} from "./failure-class";
+export { parseEventLog } from "./parse-log";
 export {
   buildSweepReport,
   renderSweepReportMarkdown,

package/src/eval/metrics.ts

@@ -1,4 +1,5 @@
 import type { ILoopEvent } from "../loop/loop.types";
+import { classifyRun, type FailureClass } from "./failure-class";
 
 /** Behavioral metrics distilled from a run's event stream — the signals the
  *  local-model literature says predict outcomes (tokens-to-solution, repair
@@ -6,6 +7,10 @@ import type { ILoopEvent } from "../loop/loop.types";
  *  the cli-metrics script. */
 export interface IRunMetrics {
   finalStatus: "done" | "stuck" | "none";
+  /** Structured reason the run failed (`none` when it reached green). The single
+   *  source of truth for failure classification — the cli-metrics analyzer and
+   *  the eval sweep both read this rather than re-deriving it. */
+  failureClass: FailureClass;
   /** Model turns (one per `cycle` event). */
   turns: number;
   /** Model calls (one per `usage` event). */
@@ -29,6 +34,7 @@ export interface IRunMetrics {
 function emptyMetrics(): IRunMetrics {
   return {
     finalStatus: "none",
+    failureClass: "none",
     turns: 0,
     modelCalls: 0,
     tokensOut: 0,
@@ -82,6 +88,7 @@ export function analyzeEvents(events: readonly ILoopEvent[]): IRunMetrics {
 
   m.filesCreated = created.size;
   m.avgTokensPerSecond = tpsCount > 0 ? Math.round(tpsSum / tpsCount) : 0;
+  m.failureClass = classifyRun(events).failureClass;
 
   return m;
 }

package/src/eval/parse-log.ts

@@ -0,0 +1,105 @@
+import type { ILoopEvent } from "../loop/loop.types";
+import { isRecord } from "../lib/guards";
+
+/** The known event kinds, as a runtime set, so a JSONL line can be validated
+ *  into a typed ILoopEvent without an `as` cast. Keep in sync with ILoopEvent. */
+const KNOWN_KINDS = new Set<string>([
+  "start",
+  "red",
+  "cycle",
+  "token",
+  "message",
+  "fix",
+  "edit",
+  "create",
+  "validated",
+  "done",
+  "stuck",
+  "run",
+  "tool",
+  "repair",
+  "timing",
+  "usage",
+  "ttsr",
+]);
+
+function isKind(value: string): value is ILoopEvent["kind"] {
+  return KNOWN_KINDS.has(value);
+}
+
+function optionalString(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+function stringArray(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+
+  return value.filter((v): v is string => typeof v === "string");
+}
+
+/** Coerce one parsed JSONL record into an ILoopEvent, or null when it isn't one.
+ *  Reads only the fields the failure classifier + metrics consume — enough to
+ *  reconstruct a typed event stream from a `--log` file. */
+function coerceEvent(record: unknown): ILoopEvent | null {
+  if (!isRecord(record)) {
+    return null;
+  }
+
+  const kind = record.kind;
+
+  if (typeof kind !== "string" || !isKind(kind)) {
+    return null;
+  }
+
+  const event: ILoopEvent = {
+    kind,
+    task: optionalString(record.task) ?? "",
+    message: optionalString(record.message) ?? "",
+  };
+  const output = optionalString(record.output);
+  const rules = stringArray(record.rules);
+
+  if (output !== undefined) {
+    event.output = output;
+  }
+
+  if (typeof record.passed === "boolean") {
+    event.passed = record.passed;
+  }
+
+  if (rules !== undefined) {
+    event.rules = rules;
+  }
+
+  return event;
+}
+
+/** Parse a `--log` JSONL transcript (one serialized event per line) into a typed
+ *  event stream. Malformed lines and non-event records are skipped. */
+export function parseEventLog(jsonl: string): ILoopEvent[] {
+  const events: ILoopEvent[] = [];
+
+  for (const line of jsonl.split("\n")) {
+    if (line.trim().length === 0) {
+      continue;
+    }
+
+    let parsed: unknown;
+
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      continue;
+    }
+
+    const event = coerceEvent(parsed);
+
+    if (event !== null) {
+      events.push(event);
+    }
+  }
+
+  return events;
+}

package/src/eval/report.ts

@@ -164,5 +164,24 @@ export function renderSweepReportMarkdown(report: ISweepReport): string {
     ...rows,
     "",
     "`*` = significant at p < 0.05 (two-proportion z-test vs baseline).",
+    ...failureSection(report),
   ].join("\n");
 }
+
+/** Format a variant's failure-class tally, e.g. "type-error×2, no-progress×1". */
+function formatFailureClasses(classes: Record<string, number>): string {
+  return Object.entries(classes)
+    .sort(([, a], [, b]) => b - a)
+    .map(([cls, n]) => `${cls}×${String(n)}`)
+    .join(", ");
+}
+
+/** A "why failures happened" section — per-variant failure-class breakdown.
+ *  Empty (no lines) when every run passed, so a clean sweep stays terse. */
+function failureSection(report: ISweepReport): string[] {
+  const lines = report.variants
+    .filter((v) => Object.keys(v.failureClasses).length > 0)
+    .map((v) => `- **${v.label}**: ${formatFailureClasses(v.failureClasses)}`);
+
+  return lines.length === 0 ? [] : ["", "### Failure breakdown", ...lines];
+}

package/src/eval/score.ts

@@ -20,6 +20,15 @@ export function summarize(records: IRunRecord[]): IVariantSummary[] {
     const sum = (select: (r: IRunRecord) => number): number =>
       list.reduce((acc, r) => acc + select(r), 0);
     const scored = list.filter((r) => r.quality !== undefined);
+    const failureClasses: Record<string, number> = {};
+
+    for (const r of list) {
+      const fc = r.failureClass;
+
+      if (!r.passed && fc !== undefined && fc !== "none") {
+        failureClasses[fc] = (failureClasses[fc] ?? 0) + 1;
+      }
+    }
 
     summaries.push({
       label,
@@ -32,6 +41,7 @@ export function summarize(records: IRunRecord[]): IVariantSummary[] {
         scored.length > 0
           ? scored.reduce((acc, r) => acc + (r.quality ?? 0), 0) / scored.length
           : 0,
+      failureClasses,
     });
   }
 

package/src/loop/loop.types.ts

@@ -32,6 +32,10 @@ export interface ILoopEvent {
   /** For `timing` events: how long the turn took, in milliseconds. */
   ms?: number;
   errors?: number;
+  /** For `validated` events: the failing gate rules/codes (e.g. "TS18048",
+   *  "no-restricted-syntax") — the structured substrate the failure classifier
+   *  reads to tell a type error from a lint rule, not just a count. */
+  rules?: readonly string[];
   passed?: boolean;
   file?: string;
   /** For `create` events: the new file's content (rendered as a code block). */

package/src/loop/turn.ts

@@ -784,6 +784,9 @@ export async function settleGate(
     cycle: turn,
     passed: gatePassed,
     errors: gateErrors.length,
+    // Structured rule/code list (not just a count) so the failure classifier can
+    // tell a type error from a lint rule without re-parsing the gate output.
+    rules: gateErrors.flatMap((e) => (e.rule === undefined ? [] : [e.rule])),
     message: gatePassed
       ? `task ${task.id} · turn ${turn}: GREEN`
       : `task ${task.id} · turn ${turn}: red (${String(gateErrors.length)} error(s))${gateDetail}`,

package/strict.type-aware.eslint.config.mjs

@@ -0,0 +1,33 @@
+// Optional type-aware ESLint overlay — enabled only when the target has a
+// compiling tsconfig (see detect-gate.ts). Adds async correctness rules that
+// require parserOptions.project; kept separate from strict.eslint.config.mjs
+// so the syntactic gate still runs on any .ts file without type info.
+import tseslint from "typescript-eslint";
+
+export default tseslint.config(
+  { ignores: ["**/node_modules/**", "**/dist/**", "**/build/**"] },
+  {
+    files: ["**/*.ts", "**/*.tsx"],
+    languageOptions: {
+      parser: tseslint.parser,
+      parserOptions: {
+        projectService: true,
+        tsconfigRootDir: process.cwd(),
+      },
+    },
+    plugins: {
+      "@typescript-eslint": tseslint.plugin,
+    },
+    rules: {
+      "@typescript-eslint/no-floating-promises": "error",
+      "@typescript-eslint/no-misused-promises": [
+        "error",
+        {
+          checksVoidReturn: {
+            attributes: false,
+          },
+        },
+      ],
+    },
+  }
+);