@agjs/tsforge 0.1.19 → 0.2.1

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/feedback/meta-rule-docs.ts

@@ -11,6 +11,30 @@ export const META_RULE_DOCS: Record<string, string> = {
   "no-overlapping-libs":
     "Remove duplicate or conflicting library versions from the dependency tree; only one canonical version per library is allowed.",
 
+  "fastify-security-plugins":
+    "Add @fastify/helmet, @fastify/cors, and @fastify/rate-limit when using fastify in production.",
+
+  "lockfile-required":
+    "Commit the lockfile for your package manager (package-lock.json, yarn.lock, pnpm-lock.yaml, or bun.lockb) and keep it in sync with package.json.",
+
+  "single-package-manager":
+    "Remove extra lockfiles — use one package manager and delete lockfiles from other tools.",
+
+  "package-manager-field-required":
+    'Add a "packageManager" field to package.json (e.g. "bun@1.3.14") so installs are reproducible across environments.',
+
+  "no-git-or-tarball-dependencies":
+    "Replace git+, git:, or HTTP tarball dependency URLs with registry versions from npm.",
+
+  "dependency-overrides-require-comment":
+    "Add a comment next to overrides/resolutions in package.json explaining why each override is needed.",
+
+  "production-must-not-use-drizzle-push":
+    "Replace `drizzle-kit push` in scripts and CI with checked-in SQL migrations and `drizzle-kit migrate`.",
+
+  "migrations-must-be-checked-in":
+    "Add a drizzle/ or migrations/ folder with generated SQL migration files when using Drizzle ORM.",
+
   // Source text
   "no-eslint-disable-comments":
     "Remove `// eslint-disable` comments — they hide warnings. Fix the underlying violation or refactor the code.",
@@ -25,6 +49,18 @@ export const META_RULE_DOCS: Record<string, string> = {
   "tsconfig-strict":
     "Enable all strict mode flags in tsconfig.json (strict: true or all strict flags individually).",
 
+  "tsconfig-recommended-flags":
+    "Enable useUnknownInCatchVariables, erasableSyntaxOnly, exactOptionalPropertyTypes, verbatimModuleSyntax, and noPropertyAccessFromIndexSignature in tsconfig.json compilerOptions.",
+
+  "next-proxy-over-middleware":
+    "Migrate middleware.ts to proxy.ts for Next.js 16 early request interception.",
+
+  "next-instrumentation-present":
+    "Add instrumentation.ts with registerOTel for OpenTelemetry tracing in Next.js apps.",
+
+  "next-image-remote-patterns-no-wildcards":
+    "Remove `**` hostname wildcards from next.config remotePatterns — allowlist specific image hostnames.",
+
   // Testing
   "test-sibling-required":
     "Add a test file for each source file; follow naming conventions (foo.ts → foo.test.ts or foo.spec.ts).",
@@ -38,4 +74,16 @@ export const META_RULE_DOCS: Record<string, string> = {
 
   "workflow-timeout-required":
     "Add a timeout-minutes setting to each GitHub Actions job to prevent hanging workflows.",
+
+  "workflow-permissions-explicit":
+    "Add a top-level permissions: block or job-level permissions to every GitHub Actions workflow.",
+
+  "workflow-permissions-least-privilege":
+    "Avoid workflow-level contents: write or id-token: write — scope write permissions to the job that needs them.",
+
+  "no-pull-request-target-untrusted-checkout":
+    "Do not combine pull_request_target with checkout of the PR head ref — use pull_request or checkout the base ref.",
+
+  "no-github-context-in-shell":
+    "Pass github.event values through env: instead of interpolating them directly in run: shell scripts.",
 };

package/src/loop/feedback/rule-docs.ts

@@ -154,6 +154,156 @@ const RULE_DOCS: Record<string, IRuleDoc> = {
     bad: "<button onClick={() => doThing(id)} />",
     good: "const onClickRow = useCallback(() => doThing(id), [id]); <button onClick={onClickRow} />",
   },
+  "tsforge/no-throw-literal": {
+    what: "Throw `Error` instances, not string or number literals.",
+    bad: "throw 'Unauthorized';",
+    good: "throw new Error('Unauthorized');",
+  },
+  "tsforge/no-react-fc": {
+    what: "Do not use React.FC — type props on the function parameter.",
+    bad: "const Button: React.FC<IButtonProps> = ({ onClick }) => <button onClick={onClick} />;",
+    good: "function Button({ onClick }: IButtonProps) { return <button onClick={onClick} />; }",
+  },
+  "tsforge/no-component-invocation": {
+    what: "Render components as JSX, not function calls.",
+    bad: "<div>{Header()}</div>",
+    good: "<div><Header /></div>",
+  },
+  "tsforge/no-nested-component": {
+    what: "Declare components at module scope, not inside another component.",
+    bad: "function App() { function Inner() { return <span />; } return <Inner />; }",
+    good: "function Inner() { return <span />; } function App() { return <Inner />; }",
+  },
+  "tsforge/dangerous-html-requires-sanitize": {
+    what: "Sanitize HTML before dangerouslySetInnerHTML — import DOMPurify.",
+    bad: "<div dangerouslySetInnerHTML={{ __html: rawHtml }} />",
+    good: "import DOMPurify from 'isomorphic-dompurify'; <div dangerouslySetInnerHTML={{ __html: DOMPurify.sanitize(rawHtml) }} />",
+  },
+  "tsforge/no-child-process-exec": {
+    what: "Do not use child_process.exec/execSync — shell execution enables command injection.",
+    bad: "import { exec } from 'child_process'; exec(`rm -rf ${dir}`);",
+    good: "import { execFile } from 'child_process'; execFile('rm', ['-rf', dir], callback);",
+  },
+  "tsforge/no-spawn-with-shell": {
+    what: "Do not pass `{ shell: true }` to spawn/spawnSync.",
+    bad: "spawn('sh', ['-c', cmd], { shell: true });",
+    good: "spawn('node', ['script.js', arg]);",
+  },
+  "tsforge/no-dynamic-regexp": {
+    what: "Do not build RegExp from runtime input — ReDoS risk.",
+    bad: "const re = new RegExp(userPattern);",
+    good: "const re = /^fixed-pattern$/;",
+  },
+  "tsforge/no-inner-html-assignment": {
+    what: "Do not assign to innerHTML — XSS risk in vanilla DOM code.",
+    bad: "el.innerHTML = userHtml;",
+    good: "el.textContent = userText;",
+  },
+  "tsforge/catch-must-handle": {
+    what: "Catch blocks must log, rethrow, or return a typed error — not silently mask failure.",
+    bad: "catch (e) { return null; }",
+    good: "catch (e) { logger.error(e); throw e; }",
+  },
+  "tsforge/no-react-in-services": {
+    what: "Service/data modules must not import React — keep business logic decoupled from UI.",
+    bad: "import { useMemo } from 'react'; // in src/services/users.ts",
+    good: "Move React hooks to components; keep services as plain TypeScript.",
+  },
+  "tsforge/no-anonymous-useEffect": {
+    what: "Pass a named function to useEffect for debuggable stack traces.",
+    bad: "useEffect(() => { sync(); }, [id]);",
+    good: "useEffect(function syncOnIdChange() { sync(); }, [id]);",
+  },
+  "tsforge/no-derived-state-in-effect": {
+    what: "Do not set local state inside useEffect when the value can be derived during render.",
+    bad: "useEffect(() => { setFullName(first + ' ' + last); }, [first, last]);",
+    good: "const fullName = `${first} ${last}`;",
+  },
+  "tsforge/no-internal-api-fetch": {
+    what: "Server Components must not fetch the app's own /api routes.",
+    bad: "await fetch('/api/users');",
+    good: "import { listUsers } from '@/services/users'; const users = await listUsers();",
+  },
+  "tsforge/await-dynamic-request-apis": {
+    what: "Await Next.js dynamic request APIs in Server Components.",
+    bad: "const jar = cookies();",
+    good: "const jar = await cookies();",
+  },
+  "tsforge/error-boundary-require-use-client": {
+    what: "error.tsx and global-error.tsx must be Client Components.",
+    bad: "export default function Error() { return <div />; }",
+    good: "'use client'; export default function Error() { return <div />; }",
+  },
+  "tsforge/no-html-img-element": {
+    what: "Prefer next/image over raw img elements.",
+    bad: "<img src='/hero.jpg' alt='hero' />",
+    good: "import Image from 'next/image'; <Image src='/hero.jpg' alt='hero' width={800} height={400} />",
+  },
+  "tsforge/no-sensitive-next-public-env": {
+    what: "NEXT_PUBLIC_* vars are exposed in the client bundle — never use for secrets.",
+    bad: "process.env.NEXT_PUBLIC_STRIPE_SECRET",
+    good: "process.env.STRIPE_SECRET_KEY // server-only, no NEXT_PUBLIC prefix",
+  },
+  "tsforge/prefer-lazy-use-state-init": {
+    what: "Use lazy useState when parsing localStorage on mount.",
+    bad: "useState(JSON.parse(localStorage.getItem('cfg') ?? '{}'))",
+    good: "useState(() => JSON.parse(localStorage.getItem('cfg') ?? '{}'))",
+  },
+  "tsforge/no-auth-token-in-storage": {
+    what: "Never store auth tokens in localStorage/sessionStorage.",
+    bad: "localStorage.setItem('auth_token', token);",
+    good: "Set an httpOnly session cookie on the server instead.",
+  },
+  "tsforge/fetch-must-check-ok": {
+    what: "Check response.ok before calling .json() on fetch results.",
+    bad: "const data = await fetch(url).then(r => r.json());",
+    good: "const res = await fetch(url); if (!res.ok) { throw new Error('fetch failed'); } const data = await res.json();",
+  },
+  "tsforge/json-parse-must-validate": {
+    what: "Parse external JSON through a schema library, not bare JSON.parse.",
+    bad: "const body = JSON.parse(raw);",
+    good: "const body = UserSchema.parse(JSON.parse(raw));",
+  },
+  "tsforge/no-unsafe-boundary-cast": {
+    what: "Do not cast untrusted parsed input with `as` — validate at the boundary.",
+    bad: "const user = (await req.json()) as IUser;",
+    good: "const user = UserSchema.parse(await req.json());",
+  },
+  "tsforge/no-user-controlled-redirect": {
+    what: "Redirect URLs must be string literals or allowlisted helpers — not user input.",
+    bad: "redirect(searchParams.get('next')!);",
+    good: "redirect('/dashboard');",
+  },
+  "tsforge/no-user-controlled-fetch-url": {
+    what: "fetch/axios URLs must be literals or pass through an allowlisted URL builder.",
+    bad: "await fetch(userSuppliedUrl);",
+    good: "await fetch('https://api.example.com/v1/status');",
+  },
+  "tsforge/no-prototype-polluting-merge": {
+    what: "Do not merge request body/query/params into objects wholesale.",
+    bad: "Object.assign(config, req.body);",
+    good: "const name = UserSchema.parse(req.body).name; config.name = name;",
+  },
+  "tsforge/server-only-modules-import-server-only": {
+    what: "Server-only modules importing DB/env must include `import 'server-only'`.",
+    bad: "import { db } from '@/lib/db'; // in lib/admin.ts",
+    good: "import 'server-only'; import { db } from '@/lib/db';",
+  },
+  "tsforge/server-action-requires-authz-and-validation": {
+    what: "Server actions must validate input and call authz before mutations.",
+    bad: "'use server'; export async function deleteUser(id: string) { await db.delete(users).where(eq(users.id, id)); }",
+    good: "'use server'; export async function deleteUser(raw: unknown) { const user = await requireUser(); const { id } = IdSchema.parse(raw); await authorize(user, id); ... }",
+  },
+  "tsforge/require-route-schema": {
+    what: "Fastify routes need a schema object with input validation.",
+    bad: "fastify.post('/users', async () => ({ ok: true }));",
+    good: "fastify.post('/users', { schema: { body: UserSchema } }, async () => ({ ok: true }));",
+  },
+  "tsforge/require-plugin-name": {
+    what: "fastify-plugin wrappers need a name option.",
+    bad: "export default fp(dbPlugin);",
+    good: "export default fp(dbPlugin, { name: 'db-connector', fastify: '5.x' });",
+  },
 };
 
 /**