@agjs/tsforge 0.2.5 → 0.2.7

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agjs/tsforge",
   "type": "module",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "license": "MIT",
   "description": "TypeScript coding harness with a deterministic gate, stack-aware guardrails, and stream-level correction.",
   "repository": {

package/src/cli.ts

@@ -2,13 +2,7 @@
 import { join, isAbsolute } from "node:path";
 import { appendFileSync, mkdirSync } from "node:fs";
 import { createInterface } from "node:readline/promises";
-import {
-  runTask,
-  RUN_STATUS,
-  Session,
-  PLAN_APPROVED_NOTE,
-  LOOP_LIMITS,
-} from "./loop";
+import { runTask, RUN_STATUS, Session, PLAN_APPROVED_NOTE } from "./loop";
 import {
   PROVIDER_LIMITS,
   PROVIDER_DEFAULTS,
@@ -997,9 +991,10 @@ async function repl(args: ICliArgs): Promise<number> {
     session.setFix(buildWebFix(framework));
     session.setIncrementalCheck(buildWebTscCheck());
     session.guide(webGuidance(framework));
-    // A from-scratch web build needs the big turn budget — the default cap was
-    // measured to cut a todo app off mid-write, before its gate ever ran.
-    session.setMaxTurns(LOOP_LIMITS.webMaxTurns);
+    // A from-scratch web build legitimately needs many turns. Don't pin a low
+    // ceiling here — the interactive session already rides the high runaway
+    // backstop (interactiveBackstopTurns) and stops on the progress guards, so a
+    // long, converging build is never cut off mid-write.
   };
 
   // The `scaffold_web` tool invokes this when the AGENT decides to build a web app

package/src/detect-gate.ts

@@ -367,7 +367,43 @@ export async function installWebDeps(cwd: string): Promise<boolean> {
  *  TanStack Router's routeTree.gen.ts) exists before tsc; `vite build` is itself
  *  the bundler oracle — it resolves imports, compiles JSX/Tailwind, fails on
  *  anything broken. */
-export function buildWebGate(framework: WebFramework): IGate {
+/** The packs the WEB eslint config must load by default so the React component
+ *  architecture rules (component-folder-structure, component-file-purity,
+ *  no-jsx-computation, …) actually run on a generated app. The web scaffold's
+ *  stack is fixed (React + TanStack), so this set is deterministic; callers may
+ *  pass a detected/overridden set instead. Without this the web gate ran the
+ *  bundled config with ZERO packs and the whole architecture layer was inert. */
+export const WEB_PACKS: readonly string[] = [
+  "typescript-core",
+  "react",
+  "react-component-architecture",
+  "tanstack-query",
+];
+
+/** Build the `KEY=val ` shell prefix that hands packs (+ rule overrides) to a
+ *  bundled eslint config, which reads them from the environment at load time.
+ *  JSON.stringify emits no spaces, so this survives a later whitespace-collapse. */
+function packEnvPrefix(
+  packs?: readonly string[],
+  ruleOverrides?: Readonly<Record<string, "error" | "warn" | "off">>
+): string {
+  const envParts: string[] = [];
+
+  if (packs !== undefined && packs.length > 0) {
+    envParts.push(`TSFORGE_PACKS=${packs.join(",")}`);
+  }
+
+  if (ruleOverrides !== undefined && Object.keys(ruleOverrides).length > 0) {
+    envParts.push(`TSFORGE_RULE_OVERRIDES=${JSON.stringify(ruleOverrides)}`);
+  }
+
+  return envParts.length > 0 ? `${envParts.join(" ")} ` : "";
+}
+
+export function buildWebGate(
+  framework: WebFramework,
+  packs: readonly string[] = WEB_PACKS
+): IGate {
   const template = WEB_TEMPLATES[framework];
   const ignores = template.eslintIgnore
     .map((glob) => `--ignore-pattern "${glob}"`)
@@ -375,7 +411,7 @@ export function buildWebGate(framework: WebFramework): IGate {
   const build = `bun run build`;
   const tsc = `"${TSC_BIN}" --noEmit -p tsconfig.json`;
   const lint =
-    `"${ESLINT_BIN}" --no-config-lookup -c "${STRICT_WEB_CONFIG}" ${ignores} --format json .`.replace(
+    `${packEnvPrefix(packs)}bun "${ESLINT_BIN}" --no-config-lookup -c "${STRICT_WEB_CONFIG}" ${ignores} --format json .`.replace(
       /\s+/g,
       " "
     );
@@ -415,14 +451,17 @@ export function buildWebGate(framework: WebFramework): IGate {
  * ALONE — caught small and isolated, before any component is built — instead of
  * as a 20-error avalanche at the very end (the Linear-clone failure mode).
  */
-export function buildWebTypeGate(framework: WebFramework): IGate {
+export function buildWebTypeGate(
+  framework: WebFramework,
+  packs: readonly string[] = WEB_PACKS
+): IGate {
   const template = WEB_TEMPLATES[framework];
   const ignores = template.eslintIgnore
     .map((glob) => `--ignore-pattern "${glob}"`)
     .join(" ");
   const tsc = `"${TSC_BIN}" --noEmit -p tsconfig.json`;
   const lint =
-    `"${ESLINT_BIN}" --no-config-lookup -c "${STRICT_WEB_CONFIG}" ${ignores} --format json .`.replace(
+    `${packEnvPrefix(packs)}bun "${ESLINT_BIN}" --no-config-lookup -c "${STRICT_WEB_CONFIG}" ${ignores} --format json .`.replace(
       /\s+/g,
       " "
     );
@@ -447,13 +486,16 @@ export function buildWebTscCheck(): string {
  * unfixable rules (`any`/`as`/`!`) still need the model. Best-effort: exits ignored,
  * `;` so prettier runs even when eslint reports remaining (unfixable) errors.
  */
-export function buildWebFix(framework: WebFramework): string {
+export function buildWebFix(
+  framework: WebFramework,
+  packs: readonly string[] = WEB_PACKS
+): string {
   const ignores = WEB_TEMPLATES[framework].eslintIgnore
     .map((glob) => `--ignore-pattern "${glob}"`)
     .join(" ");
 
   const lintFix =
-    `"${ESLINT_BIN}" --no-config-lookup -c "${STRICT_WEB_CONFIG}" ${ignores} --fix .`.replace(
+    `${packEnvPrefix(packs)}bun "${ESLINT_BIN}" --no-config-lookup -c "${STRICT_WEB_CONFIG}" ${ignores} --fix .`.replace(
       /\s+/g,
       " "
     );
@@ -691,24 +733,8 @@ function lintPart(
   packs?: readonly string[],
   ruleOverrides?: Readonly<Record<string, "error" | "warn" | "off">>
 ): IGate {
-  const envParts: string[] = [];
-
-  if (packs !== undefined && packs.length > 0) {
-    envParts.push(`TSFORGE_PACKS=${packs.join(",")}`);
-  }
-
-  if (
-    ruleOverrides !== undefined &&
-    typeof ruleOverrides === "object" &&
-    Object.keys(ruleOverrides).length > 0
-  ) {
-    envParts.push(`TSFORGE_RULE_OVERRIDES=${JSON.stringify(ruleOverrides)}`);
-  }
-
-  const envPrefix = envParts.length > 0 ? `${envParts.join(" ")} ` : "";
-
   return {
-    command: `${envPrefix}bun "${ESLINT_BIN}" --no-config-lookup -c "${STRICT_CONFIG}" --format json .`,
+    command: `${packEnvPrefix(packs, ruleOverrides)}bun "${ESLINT_BIN}" --no-config-lookup -c "${STRICT_CONFIG}" --format json .`,
     label: "strict TypeScript (tsforge)",
   };
 }

package/src/inference/request.ts

@@ -19,7 +19,21 @@ function interpolateEnv(
 }
 
 function style(cfg: IOpenAICompatibleConfig): ReasoningStyle {
-  return cfg.reasoning ?? "qwen";
+  if (cfg.reasoning !== undefined) {
+    return cfg.reasoning;
+  }
+
+  // Auto-detect DeepSeek when not explicitly configured, so its thinking-mode
+  // round-trip works out of the box: DeepSeek requires each prior assistant
+  // turn's `reasoning_content` replayed, and 400s otherwise ("The
+  // reasoning_content in the thinking mode must be passed back to the API").
+  // Without this, a DeepSeek model added with just { baseUrl, model } gets the
+  // `qwen` default, which strips reasoning_content on replay → that 400.
+  if (`${cfg.baseUrl} ${cfg.model}`.toLowerCase().includes("deepseek")) {
+    return "deepseek";
+  }
+
+  return "qwen";
 }
 
 /** Provider-specific reasoning/thinking fields for the request body. */

package/src/loop/loop.constants.ts

@@ -31,17 +31,31 @@ export const LOOP_LIMITS = {
    */
   maxEditLines: 50,
   /**
-   * Give up after the gate shows the EXACT same error set this many edits in a
-   * row (genuine spinning). Generous; the turn cap is the real backstop.
+   * Give up after the gate shows the EXACT same error SET this many edits in a
+   * row (genuine spinning) — the coarse net. The finer `samePersist` guard
+   * (below) usually trips first; this catches a stable-but-shuffling set.
    */
-  gateStuckRepeats: 10,
+  gateStuckRepeats: 6,
+  /**
+   * The PRIMARY no-progress guard: give up when a SINGLE error — same (file,rule)
+   * key — survives this many consecutive gate cycles, i.e. the model keeps failing
+   * at the same thing N attempts running, even while OTHER errors churn around it.
+   * This (not a raw turn count) is how the loop decides it's genuinely stuck.
+   */
+  samePersist: 5,
   /**
    * Above this many chars of combined file content, the seed prompt sends a
    * navigable project MAP instead of full dumps. Below it, full dumps.
    */
   mapThresholdChars: 12000,
-  /** Hard backstop on model turns per task. */
+  /** Hard backstop on model turns per HEADLESS task (eval/cron — no human to
+   *  intervene). Interactive sessions use `interactiveBackstopTurns` instead. */
   maxTurns: 40,
+  /** Interactive runaway safety only — NOT the primary stop. A human is present
+   *  and can interrupt, and the progress guards (`samePersist` / `gateStuckRepeats`)
+   *  pull the agent out the moment it stops converging, so this is set high enough
+   *  that normal long, productive back-and-forth never trips it. */
+  interactiveBackstopTurns: 250,
   /** Turn budget for a from-scratch WEB build (heavy gate, many files): used by
    *  headless web builds AND applied when an interactive session scaffolds via
    *  `scaffold_web` — measured: a todo app was still WRITING components when it

package/src/loop/loop.types.ts

@@ -37,6 +37,8 @@ export interface ILoopEvent {
    *  reads to tell a type error from a lint rule, not just a count. */
   rules?: readonly string[];
   passed?: boolean;
+  /** For `stuck` events: a human-readable blocker diagnosis. */
+  detail?: string;
   file?: string;
   /** For `create` events: the new file's content (rendered as a code block). */
   content?: string;
@@ -82,6 +84,9 @@ export interface IRunResult {
   /** Model turns used. */
   cycles: number;
   reason?: StuckReason;
+  /** When stuck: a human-readable blocker diagnosis (the persistent rule/file +
+   *  last error) so an interactive session can hand back something actionable. */
+  detail?: string;
   /** Edits/creates applied to editable files (measure edit churn). */
   edits?: number;
   /** Times an edit RAISED the gate error count (regressions). */

package/src/loop/rule-docs.generated.json

@@ -109,6 +109,21 @@
     "bad": "[1, 2, 3].reduce((arr, num) => arr.concat(num * 2), [] as number[]);\n\n['a', 'b'].reduce(\n  (accumulator, name) => ({\n    ...accumulator,\n    [name]: true,\n  }),\n  {} as Record<string, boolean>,",
     "good": "[1, 2, 3].reduce<number[]>((arr, num) => arr.concat(num * 2), []);\n\n['a', 'b'].reduce<Record<string, boolean>>(\n  (accumulator, name) => ({\n    ...accumulator,\n    [name]: true,\n  }),\n  {},"
   },
+  "tsforge/id-param-requires-object-authz": {
+    "what": "Warn when a handler reads `params.id` and queries the database without an authorization check in the same function.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/mutating-route-requires-authz": {
+    "what": "POST/PUT/PATCH/DELETE route handlers must call an authorization helper before mutating state.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/server-action-requires-authz": {
+    "what": "Files with `\"use server\"` that perform database mutations must call an authorization helper in the same function.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
   "tsforge/job-name-must-be-constant": {
     "what": "Disallow string-literal job names in `<queue>.add(name, ...)` calls — use a constant identifier so all consumers share one source of truth.",
     "bad": "// Example that violates the rule",
@@ -219,6 +234,16 @@
     "bad": "// Example that violates the rule",
     "good": "// Corrected version"
   },
+  "tsforge/update-delete-account-scoped-must-filter-scope": {
+    "what": "Require Drizzle `.update()` / `.delete()` against account-scoped tables to filter by a scope column in `.where()`.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/update-delete-must-have-where": {
+    "what": "Require every Drizzle `.update()` and `.delete()` call to include a `.where()` clause — unscoped writes affect every row.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
   "tsforge/consistent-status-via-set": {
     "what": "Inside Elysia route handlers, set HTTP status via `set.status = N`, not by returning a `new Response(body, { status: N })`.",
     "bad": "// Example that violates the rule",
@@ -319,11 +344,26 @@
     "bad": "// Example that violates the rule",
     "good": "// Corrected version"
   },
+  "tsforge/auth-cookie-must-set-maxage-or-expires": {
+    "what": "Auth-cookie writes should set `maxAge` or `expires` so session cookies do not live forever by default.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/auth-cookie-must-set-samesite": {
+    "what": "Auth-cookie writes must set `sameSite` (`strict` or `lax`) — missing SameSite allows cross-site cookie delivery.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
   "tsforge/bcrypt-rounds-min": {
     "what": "Disallow `bcrypt.hash` / `bcrypt.hashSync` calls with a numeric-literal rounds value below the configured minimum (default 10).",
     "bad": "// Example that violates the rule",
     "good": "// Corrected version"
   },
+  "tsforge/jwt-must-verify-not-decode": {
+    "what": "Disallow `jwt.decode` / `decodeJwt` — decoding without verification accepts forged tokens. Use `jwt.verify` or `jwtVerify` instead.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
   "tsforge/no-import-build-output": {
     "what": "Disallow importing from build/output directories within the project. Source must import source, not compiled artifacts, to avoid stale-code drift and broken module boundaries.",
     "bad": "// Example that violates the rule",
@@ -354,6 +394,11 @@
     "bad": "// Example that violates the rule",
     "good": "// Corrected version"
   },
+  "tsforge/mutation-should-revalidate-cache": {
+    "what": "After database mutations in server actions or route handlers, call `revalidatePath` or `revalidateTag` so cached pages reflect the change.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
   "tsforge/no-html-img-element": {
     "what": "Prefer next/image over raw <img> elements for optimized responsive images and Core Web Vitals.",
     "bad": "// Example that violates the rule",
@@ -374,6 +419,11 @@
     "bad": "// Example that violates the rule",
     "good": "// Corrected version"
   },
+  "tsforge/no-secret-props-to-client": {
+    "what": "Warn when Server Components pass secret-looking props to JSX — values may cross the client boundary.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
   "tsforge/no-sensitive-next-public-env": {
     "what": "Disallow NEXT_PUBLIC_* env vars whose names suggest secrets — public build-time vars are visible in the client bundle.",
     "bad": "// Example that violates the rule",
@@ -384,6 +434,16 @@
     "bad": "// Example that violates the rule",
     "good": "// Corrected version"
   },
+  "tsforge/server-action-requires-authz-and-validation": {
+    "what": "Server actions (`\"use server\"`) that mutate the database must call authorization helpers and validate input with `.parse()` / `.safeParse()`.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/server-only-modules-import-server-only": {
+    "what": "App-router server modules must import `\"server-only\"` so accidental client bundling fails at build time.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
   "tsforge/pkce-required-for-oidc": {
     "what": "OIDC providers must use PKCE: `buildAuthorizationURL` must call `generateCodeVerifier()` and pass it to `createAuthorizationURL`.",
     "bad": "// Example that violates the rule",
@@ -399,8 +459,13 @@
     "bad": "// Example that violates the rule",
     "good": "// Corrected version"
   },
+  "tsforge/component-file-purity": {
+    "what": "A component .tsx contains only imports and the component itself — types go to <feature>.types.ts, constants to <feature>.constants.ts, helpers to src/lib",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
   "tsforge/component-folder-structure": {
-    "what": "Enforce required sibling files in component folders (hooks, types, stories, test, index)",
+    "what": "A component .tsx must live in src/views/<Feature>/components/ (feature component), src/components/ui/ (shared primitive), or be the view root src/views/<Feature>/index.tsx",
     "bad": "// Example that violates the rule",
     "good": "// Corrected version"
   },
@@ -469,6 +534,31 @@
     "bad": "// Example that violates the rule",
     "good": "// Corrected version"
   },
+  "tsforge/no-prototype-polluting-merge": {
+    "what": "Disallow merging request body/query/params into objects — enables prototype pollution.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/no-user-controlled-fetch-url": {
+    "what": "Disallow fetch/axios requests to non-literal URLs — dynamic URLs enable SSRF.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/no-user-controlled-redirect": {
+    "what": "Disallow redirects to non-literal URLs — user-controlled redirects enable open redirects.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/upload-must-set-limits": {
+    "what": "Multipart upload handlers should declare `limits` or `maxFileSize` to bound request size.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/webhook-must-verify-signature-before-parse": {
+    "what": "Webhook handlers must verify signatures before calling `.json()` on the request body.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
   "tsforge/catch-must-handle": {
     "what": "Catch blocks must log, rethrow, or propagate errors — not silently return empty defaults on failure.",
     "bad": "// Example that violates the rule",
@@ -499,6 +589,16 @@
     "bad": "// Example that violates the rule",
     "good": "// Corrected version"
   },
+  "tsforge/caught-error-log-requires-cause": {
+    "what": "When logging a caught error, include a `cause` field in the structured payload so downstream tools preserve the error chain.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/logger-not-console": {
+    "what": "Service modules should use the structured logger instead of `console.*` — console output is unstructured and hard to search.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
   "tsforge/mask-pii-fields": {
     "what": "Disallow unmasked PII (email, phone, password, token, ...) in structured-logger payloads — the #1 way data leaks quietly.",
     "bad": "// Example that violates the rule",
@@ -519,14 +619,49 @@
     "bad": "// Example that violates the rule",
     "good": "// Corrected version"
   },
+  "tsforge/fake-timers-must-be-restored": {
+    "what": "When a test file calls `useFakeTimers()`, it must also call `useRealTimers()` so later tests are not affected.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/no-conditional-expect": {
+    "what": "Disallow `expect()` inside conditionals — tests must fail when assertions are skipped.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
   "tsforge/no-focused-tests": {
     "what": "Disallow focused tests (`test.only`, `it.only`, `fdescribe`, ...) — the canonical 'I forgot to remove this before committing' leak.",
     "bad": "// Example that violates the rule",
     "good": "// Corrected version"
   },
+  "tsforge/no-real-network-in-unit-tests": {
+    "what": "Unit tests should not perform real network I/O — mock HTTP clients or move the test to an integration suite.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
   "tsforge/test-file-mirrors-source": {
     "what": "Every test file under `tests/` must mirror a source file under `src/`. Catches orphaned tests left behind after refactors and renames.",
     "bad": "// Example that violates the rule",
     "good": "// Corrected version"
+  },
+  "tsforge/exported-functions-require-return-type": {
+    "what": "Exported functions should declare an explicit return type at module boundaries.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/fetch-must-check-ok": {
+    "what": "HTTP fetch responses must check `.ok` or status before calling `.json()`.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/json-parse-must-validate": {
+    "what": "Disallow bare JSON.parse on untrusted input — validate through a schema library.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/no-unsafe-boundary-cast": {
+    "what": "Disallow type assertions immediately after parsing untrusted boundary input.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
   }
 }

package/src/loop/run.ts

@@ -330,6 +330,7 @@ export async function runTask(
   const state: ILoopState = {
     prevGateErrors: red.errors,
     gateNoProgress: 0,
+    errorAge: new Map(),
     lastGateCount: -1,
     edits: 0,
     regressions: 0,

package/src/loop/session.ts

@@ -446,6 +446,7 @@ export class Session {
     this.state = {
       prevGateErrors: [],
       gateNoProgress: 0,
+      errorAge: new Map(),
       lastGateCount: -1,
       edits: 0,
       regressions: 0,
@@ -698,8 +699,13 @@ export class Session {
    */
   async send(text: string, opts: ISendOptions = {}): Promise<ISendResult> {
     const { ctx, report } = this;
+    // Interactive ceiling is a RUNAWAY backstop, not the primary stop — the
+    // progress guards (samePersist / gateNoProgress) pull the agent out the moment
+    // it stops converging. Set high so normal long back-and-forth never trips it.
     const maxTurns =
-      this.maxTurnsOverride ?? this.cfg.maxTurns ?? LOOP_LIMITS.maxTurns;
+      this.maxTurnsOverride ??
+      this.cfg.maxTurns ??
+      LOOP_LIMITS.interactiveBackstopTurns;
     const sendStart = performance.now();
 
     // Thread cancellation to the tool `run` commands and the gate (not just the
@@ -1505,7 +1511,7 @@ export class Session {
       kind: "stuck",
       task: SESSION_ID,
       cycles: maxTurns,
-      message: `stuck (hit ${maxTurns}-turn cap)`,
+      message: `stuck (hit the ${maxTurns}-turn runaway backstop — progress guards never tripped, which is unusual; re-steer or narrow the task)`,
     });
 
     return { status: "stuck", turns: maxTurns };

package/src/loop/turn.ts

@@ -8,6 +8,7 @@ import {
   sameErrorSet,
   type ErrorParser,
   type ErrorSet,
+  type IErrorItem,
 } from "../validate";
 import { isInScope } from "../lib/scope";
 import { fileExists, resolveScopeFiles } from "../lib/fs";
@@ -126,6 +127,9 @@ export interface ILoopCtx {
 export interface ILoopState {
   prevGateErrors: ErrorSet;
   gateNoProgress: number;
+  /** Per-error-key (file:rule) survival count: how many consecutive gate cycles
+   *  each error has persisted. Drives the primary `samePersist` no-progress stop. */
+  errorAge: Map<string, number>;
   lastGateCount: number;
   edits: number;
   regressions: number;
@@ -688,6 +692,46 @@ function autoFixNotice(files: string[]): string {
   );
 }
 
+/**
+ * Advance each error's per-(file:rule) survival count and return the first error
+ * that has now persisted for `samePersist` consecutive gate cycles — the model
+ * keeps failing at the SAME thing — or null. Rebuilds the map from the CURRENT
+ * keys, so a fixed error's age drops out (no stale growth) and an error that
+ * comes back later starts fresh. Catches "stuck on X" even while OTHER errors
+ * churn around it (which the whole-set `gateNoProgress` guard misses).
+ */
+export function trackErrorAges(
+  state: ILoopState,
+  gateErrors: ErrorSet
+): IErrorItem | null {
+  const next = new Map<string, number>();
+  let stuck: IErrorItem | null = null;
+
+  for (const e of gateErrors) {
+    const age = (state.errorAge.get(e.key) ?? 0) + 1;
+
+    next.set(e.key, age);
+
+    if (age >= LOOP_LIMITS.samePersist && stuck === null) {
+      stuck = e;
+    }
+  }
+
+  state.errorAge = next;
+
+  return stuck;
+}
+
+/** The blocker diagnosis surfaced when a single error persists too long — names
+ *  the rule + file + attempt count + the last message, so an interactive session
+ *  hands back something the user can act on. */
+export function persistDetail(e: IErrorItem): string {
+  const where = e.file !== undefined ? ` in ${e.file}` : "";
+  const rule = e.rule ?? "the same error";
+
+  return `stuck on ${rule}${where} after ${String(LOOP_LIMITS.samePersist)} attempts (last: ${e.message.slice(0, 140)})`;
+}
+
 /**
  * The deterministic gate — the only authority on "done". Auto-fix, run the
  * optional fix command, validate, and return a terminal result (done/stuck) or
@@ -817,17 +861,47 @@ export async function settleGate(
     };
   }
 
+  // PRIMARY no-progress stop: the model keeps failing at the SAME (file,rule)
+  // for `samePersist` cycles running — even if other errors churn. Hand back a
+  // concrete blocker rather than spinning to a raw turn cap.
+  const persisted = trackErrorAges(state, gateErrors);
+
+  if (persisted !== null) {
+    const detail = persistDetail(persisted);
+
+    report({
+      kind: "stuck",
+      task: task.id,
+      cycles: turn,
+      detail,
+      message: `task ${task.id}: ${detail}`,
+    });
+
+    return {
+      task: task.id,
+      redConfirmed: true,
+      status: RUN_STATUS.stuck,
+      cycles: turn,
+      reason: STUCK_REASON.stalled,
+      detail,
+    };
+  }
+
+  // Coarser secondary net: the WHOLE error set unchanged this many cycles.
   state.gateNoProgress = sameErrorSet(state.prevGateErrors, gateErrors)
     ? state.gateNoProgress + 1
     : 0;
   state.prevGateErrors = gateErrors;
 
   if (state.gateNoProgress >= LOOP_LIMITS.gateStuckRepeats) {
+    const detail = `gate unchanged ${String(LOOP_LIMITS.gateStuckRepeats)} cycles (${String(gateErrors.length)} error(s) not converging)`;
+
     report({
       kind: "stuck",
       task: task.id,
       cycles: turn,
-      message: `task ${task.id}: stuck (gate unchanged ${LOOP_LIMITS.gateStuckRepeats}x)`,
+      detail,
+      message: `task ${task.id}: stuck — ${detail}`,
     });
 
     return {
@@ -836,6 +910,7 @@ export async function settleGate(
       status: RUN_STATUS.stuck,
       cycles: turn,
       reason: STUCK_REASON.stalled,
+      detail,
     };
   }
 

package/src/rule-packs/react-component-architecture/index.ts

@@ -1,6 +1,7 @@
 import type { TSESLint } from "@typescript-eslint/utils";
 
 import { dangerousHtmlRequiresSanitizeRule } from "./rules/dangerous-html-requires-sanitize";
+import { componentFilePurityRule } from "./rules/component-file-purity";
 import { componentFolderStructureRule } from "./rules/component-folder-structure";
 import { forwardrefDisplayNameRule } from "./rules/forwardref-display-name";
 import { indexMustReexportDefaultRule } from "./rules/index-must-reexport-default";
@@ -17,6 +18,7 @@ import { noStateInComponentBodyRule } from "./rules/no-state-in-component-body";
 import type { IRulePack } from "../rule-packs.types";
 
 const rules: Record<string, TSESLint.RuleModule<string, readonly unknown[]>> = {
+  "component-file-purity": componentFilePurityRule,
   "component-folder-structure": componentFolderStructureRule,
   "dangerous-html-requires-sanitize": dangerousHtmlRequiresSanitizeRule,
   "forwardref-display-name": forwardrefDisplayNameRule,
@@ -39,6 +41,7 @@ export const reactComponentArchitecturePack: IRulePack = {
     "Component structure, composition, and file organization for React",
   rules,
   rulesConfig: {
+    "component-file-purity": "error",
     "component-folder-structure": "error",
     "dangerous-html-requires-sanitize": "error",
     "forwardref-display-name": "error",

package/src/rule-packs/react-component-architecture/rules/component-file-purity.ts

@@ -0,0 +1,105 @@
+import { AST_NODE_TYPES, type TSESTree } from "@typescript-eslint/utils";
+
+import { createRule } from "../../create-rule";
+import {
+  isComponentDeclaration,
+  isInShadcnUi,
+  isRouteFile,
+  isStoryFile,
+  isTestFile,
+  unwrapExport,
+} from "../utils";
+
+export const RULE_NAME = "component-file-purity";
+
+type MessageIds = "inlineType" | "inlineConstant" | "inlineHelper";
+
+/** Map an offending top-level declaration to the message that tells the model
+ *  where it belongs. Returns null for declarations that are allowed to sit
+ *  beside a component (none today — the component itself is filtered earlier). */
+function messageForDeclaration(node: TSESTree.Node): MessageIds | null {
+  switch (node.type) {
+    case AST_NODE_TYPES.TSInterfaceDeclaration:
+    case AST_NODE_TYPES.TSTypeAliasDeclaration:
+    case AST_NODE_TYPES.TSEnumDeclaration:
+      return "inlineType";
+    case AST_NODE_TYPES.VariableDeclaration:
+      return "inlineConstant";
+    case AST_NODE_TYPES.FunctionDeclaration:
+      return "inlineHelper";
+    default:
+      return null;
+  }
+}
+
+export const componentFilePurityRule = createRule<[], MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: "problem",
+    docs: {
+      description:
+        "A component .tsx contains only imports and the component itself — types go to <feature>.types.ts, constants to <feature>.constants.ts, helpers to src/lib",
+    },
+    schema: [],
+    messages: {
+      inlineType:
+        "No inline types in a component file — move this to <feature>.types.ts (or src/shared/shared.types.ts if cross-feature) and import it.",
+      inlineConstant:
+        "No inline constants in a component file — move this to <feature>.constants.ts and import it. A component file holds only imports and the component.",
+      inlineHelper:
+        "No inline helper functions in a component file — move pure helpers (formatters, etc.) to src/lib and import them. A component file holds only imports and the component.",
+    },
+  },
+  defaultOptions: [],
+  create(context) {
+    const filename = context.filename;
+
+    if (!filename.endsWith(".tsx")) {
+      return {};
+    }
+
+    // Primitives (cva variant consts) and route shells (`const Route = …`)
+    // legitimately carry non-component module declarations. Tests/stories too.
+    if (
+      isInShadcnUi(filename) ||
+      isRouteFile(filename) ||
+      isStoryFile(filename) ||
+      isTestFile(filename)
+    ) {
+      return {};
+    }
+
+    return {
+      Program(program) {
+        const unwrapped = program.body.map((s) => ({
+          stmt: s,
+          decl: unwrapExport(s),
+        }));
+
+        // Only enforce purity on files that actually define a component; a .tsx
+        // with no component isn't a "component file" this rule governs.
+        const hasComponent = unwrapped.some((u) =>
+          isComponentDeclaration(u.decl)
+        );
+
+        if (!hasComponent) {
+          return;
+        }
+
+        for (const { decl } of unwrapped) {
+          if (isComponentDeclaration(decl)) {
+            continue;
+          }
+
+          const messageId = messageForDeclaration(decl);
+
+          if (messageId === null) {
+            continue;
+          }
+
+          context.report({ node: decl, messageId });
+        }
+      },
+    };
+  },
+});

package/src/rule-packs/react-component-architecture/rules/component-folder-structure.ts

@@ -1,44 +1,34 @@
-import { existsSync } from "fs";
-import { dirname, join } from "path";
 import type { JSONSchema4 } from "@typescript-eslint/utils/json-schema";
 
 import { createRule } from "../../create-rule";
-import { getComponentName, isComponentFile, isInShadcnUi } from "../utils";
+import {
+  getComponentName,
+  isComponentFile,
+  isInShadcnUi,
+  isRouteFile,
+} from "../utils";
 
 export const RULE_NAME = "component-folder-structure";
 
 export interface ComponentFolderStructureOptions {
-  readonly requiredSiblings?: readonly string[];
+  /** Substrings; a component file whose path matches any is left alone. */
   readonly ignorePaths?: readonly string[];
 }
 
 type RuleOptions = [ComponentFolderStructureOptions];
-type MessageIds = "missingSiblings";
-
-const DEFAULT_SIBLINGS = [
-  "<Name>.hooks.ts",
-  "<Name>.types.ts",
-  "<Name>.stories.tsx",
-  "<Name>.test.ts",
-  "index.ts",
-];
-
-const DEFAULT_IGNORE_PATHS = [
-  "src/components/ui/",
-  "tests/",
-  "e2e/",
-  ".storybook/",
-  "node_modules",
-];
+type MessageIds = "wrongLocation";
+
+const DEFAULT_IGNORE_PATHS = ["tests/", "e2e/", ".storybook/", "node_modules"];
+
+/** A feature component lives at src/views/<Feature>/components/<X>.tsx (nesting
+ *  under components/ is allowed). The view root is src/views/<Feature>/index.tsx
+ *  (lowercase ⇒ not a PascalCase component file, so it never reaches here). */
+const FEATURE_COMPONENT = /(^|\/)src\/views\/[^/]+\/components\//;
 
 const optionSchema: JSONSchema4 = {
   type: "object",
   additionalProperties: false,
   properties: {
-    requiredSiblings: {
-      type: "array",
-      items: { type: "string" },
-    },
     ignorePaths: {
       type: "array",
       items: { type: "string" },
@@ -53,20 +43,15 @@ export const componentFolderStructureRule = createRule<RuleOptions, MessageIds>(
       type: "problem",
       docs: {
         description:
-          "Enforce required sibling files in component folders (hooks, types, stories, test, index)",
+          "A component .tsx must live in src/views/<Feature>/components/ (feature component), src/components/ui/ (shared primitive), or be the view root src/views/<Feature>/index.tsx",
       },
       schema: [optionSchema],
       messages: {
-        missingSiblings:
-          "Component '{{name}}' is missing required siblings: {{missing}}",
+        wrongLocation:
+          "Component '{{name}}' is in the wrong place. Put it in src/views/<Feature>/components/{{name}}.tsx (a feature component), src/components/ui/ (a shared primitive), or make it the view root src/views/<Feature>/index.tsx — do NOT scatter components under {{dir}}.",
       },
     },
-    defaultOptions: [
-      {
-        requiredSiblings: DEFAULT_SIBLINGS,
-        ignorePaths: DEFAULT_IGNORE_PATHS,
-      },
-    ],
+    defaultOptions: [{ ignorePaths: DEFAULT_IGNORE_PATHS }],
     create(context, [options]) {
       const filename = context.filename;
 
@@ -80,42 +65,32 @@ export const componentFolderStructureRule = createRule<RuleOptions, MessageIds>(
         return {};
       }
 
-      if (isInShadcnUi(filename)) {
+      // Allowed homes: shared primitives, generated route shells, feature
+      // components. Anything else is a scattered/mis-placed component.
+      if (
+        isInShadcnUi(filename) ||
+        isRouteFile(filename) ||
+        FEATURE_COMPONENT.test(filename)
+      ) {
         return {};
       }
 
       const componentName = getComponentName(filename);
 
-      if (!componentName) {
+      if (componentName === null) {
         return {};
       }
 
+      const slash = filename.lastIndexOf("/");
+      const dir = slash === -1 ? "." : filename.slice(0, slash);
+
       return {
         "Program:exit"(node) {
-          const dir = dirname(filename);
-          const requiredSiblings = options.requiredSiblings ?? DEFAULT_SIBLINGS;
-
-          const missing: string[] = [];
-
-          for (const sibling of requiredSiblings) {
-            const siblingPath = sibling.replace("<Name>", componentName);
-            const fullPath = join(dir, siblingPath);
-
-            if (!existsSync(fullPath)) {
-              missing.push(siblingPath);
-            }
-          }
-
-          if (missing.length > 0) {
-            context.report({
-              node,
-              messageId: "missingSiblings",
-              data: {
-                name: componentName,
-                missing: missing.join(", "),
-              },
-            });
-          }
+          context.report({
+            node,
+            messageId: "wrongLocation",
+            data: { name: componentName, dir },
+          });
         },
       };
     },

package/src/rule-packs/react-component-architecture/utils.ts

@@ -82,6 +82,68 @@ export function isInShadcnUi(filename: string): boolean {
   return filename.includes("/components/ui/");
 }
 
+/**
+ * Detect if a path is a TanStack route file (generated/hand-wired shells under
+ * src/routes/). These legitimately hold a non-component `const Route =
+ * createFileRoute(...)` and are exempt from the component-purity/location rules.
+ */
+export function isRouteFile(filename: string): boolean {
+  return /(^|\/)src\/routes\//.test(filename);
+}
+
+/** A name is a component name when it is PascalCase (starts with an uppercase). */
+export function isComponentName(name: string): boolean {
+  return /^[A-Z]/.test(name);
+}
+
+/** True when a node is a function expression/arrow (a component's init shape). */
+function isFunctionInit(node: TSESTree.Expression | null | undefined): boolean {
+  return (
+    node?.type === AST_NODE_TYPES.ArrowFunctionExpression ||
+    node?.type === AST_NODE_TYPES.FunctionExpression
+  );
+}
+
+/**
+ * Given a top-level statement (already unwrapped from any `export`), report
+ * whether it DECLARES a React component — a PascalCase `function`, or a
+ * `const PascalCase = (…) => …` whose init is a function. A `const Route =
+ * createFileRoute(...)(...)` is NOT a component (its init is a call), so route
+ * files don't trip this.
+ */
+export function isComponentDeclaration(node: TSESTree.Node): boolean {
+  if (node.type === AST_NODE_TYPES.FunctionDeclaration && node.id !== null) {
+    return isComponentName(node.id.name);
+  }
+
+  if (node.type === AST_NODE_TYPES.VariableDeclaration) {
+    return node.declarations.some(
+      (d) =>
+        d.id.type === AST_NODE_TYPES.Identifier &&
+        isComponentName(d.id.name) &&
+        isFunctionInit(d.init)
+    );
+  }
+
+  return false;
+}
+
+/** Unwrap a top-level statement from its `export`/`export default` wrapper, so
+ *  callers classify the underlying declaration uniformly. */
+export function unwrapExport(
+  statement: TSESTree.ProgramStatement
+): TSESTree.Node {
+  if (
+    (statement.type === AST_NODE_TYPES.ExportNamedDeclaration ||
+      statement.type === AST_NODE_TYPES.ExportDefaultDeclaration) &&
+    statement.declaration !== null
+  ) {
+    return statement.declaration;
+  }
+
+  return statement;
+}
+
 /**
  * Extract component name from filename (e.g., Button.tsx → Button)
  */

package/src/rule-packs/rule-metadata.ts

@@ -18,6 +18,7 @@ const RULE_ENTRIES: Readonly<Record<string, IRuleCatalogEntry>> = {
     falsePositiveRisk: "medium",
   },
   "component-folder-structure": { tier: "architecture", tags: ["react"] },
+  "component-file-purity": { tier: "architecture", tags: ["react"] },
   "no-state-in-component-body": { tier: "architecture", tags: ["react"] },
   "no-inline-jsx-functions": { tier: "architecture", tags: ["react"] },
   "no-anonymous-useEffect": {

package/src/web-components.ts

@@ -365,64 +365,66 @@ export function Separator({
 `,
   table: `import { cn } from "@/lib/utils";
 
-export function Table({
+// A column-driven table: pass your typed rows + a column spec and it renders.
+// This is the table — there is NO per-feature wrapper (no DealsTable/UsersTable).
+// Define columns as a feature constant (e.g. dashboard.constants.ts) and render
+// <Table columns={dealColumns} data={deals} rowKey={(d) => d.id} />.
+export interface IColumn<T> {
+  readonly header: string;
+  readonly cell: (row: T) => React.ReactNode;
+  readonly className?: string;
+}
+
+export function Table<T>({
+  columns,
+  data,
+  rowKey,
   className,
-  ...props
-}: React.TableHTMLAttributes<HTMLTableElement>): React.JSX.Element {
+}: {
+  readonly columns: readonly IColumn<T>[];
+  readonly data: readonly T[];
+  readonly rowKey: (row: T) => string;
+  readonly className?: string;
+}): React.JSX.Element {
   return (
     <div className="relative w-full overflow-auto $DELTA">
-      <table className={cn("w-full caption-bottom text-sm", className)} {...props} />
+      <table className={cn("w-full caption-bottom text-sm", className)}>
+        <thead className="[&_tr]:border-b">
+          <tr className="border-b transition-colors hover:bg-muted/50">
+            {columns.map((col) => (
+              <th
+                key={col.header}
+                className={cn(
+                  "h-10 px-2 text-left align-middle font-medium text-muted-foreground",
+                  col.className
+                )}
+              >
+                {col.header}
+              </th>
+            ))}
+          </tr>
+        </thead>
+        <tbody className="[&_tr:last-child]:border-0">
+          {data.map((row) => (
+            <tr
+              key={rowKey(row)}
+              className="border-b transition-colors hover:bg-muted/50"
+            >
+              {columns.map((col) => (
+                <td
+                  key={col.header}
+                  className={cn("p-2 align-middle", col.className)}
+                >
+                  {col.cell(row)}
+                </td>
+              ))}
+            </tr>
+          ))}
+        </tbody>
+      </table>
     </div>
   );
 }
-
-export function TableHeader({
-  className,
-  ...props
-}: React.HTMLAttributes<HTMLTableSectionElement>): React.JSX.Element {
-  return <thead className={cn("[&_tr]:border-b", className)} {...props} />;
-}
-
-export function TableBody({
-  className,
-  ...props
-}: React.HTMLAttributes<HTMLTableSectionElement>): React.JSX.Element {
-  return <tbody className={cn("[&_tr:last-child]:border-0", className)} {...props} />;
-}
-
-export function TableRow({
-  className,
-  ...props
-}: React.HTMLAttributes<HTMLTableRowElement>): React.JSX.Element {
-  return (
-    <tr
-      className={cn("border-b transition-colors hover:bg-muted/50", className)}
-      {...props}
-    />
-  );
-}
-
-export function TableHead({
-  className,
-  ...props
-}: React.ThHTMLAttributes<HTMLTableCellElement>): React.JSX.Element {
-  return (
-    <th
-      className={cn(
-        "h-10 px-2 text-left align-middle font-medium text-muted-foreground",
-        className
-      )}
-      {...props}
-    />
-  );
-}
-
-export function TableCell({
-  className,
-  ...props
-}: React.TdHTMLAttributes<HTMLTableCellElement>): React.JSX.Element {
-  return <td className={cn("p-2 align-middle", className)} {...props} />;
-}
 `,
   // ─── composition blocks (molecules) ────────────────────────────────────────
   "app-shell": `import { Link, Outlet, useLocation } from "@tanstack/react-router";

package/src/web-templates.ts

@@ -437,20 +437,29 @@ const REACT_GUIDANCE = [
   "TanStack (Router + Query) — ALREADY scaffolded and its dependencies INSTALLED.",
   "Build the app by adding/editing files under src/. Do NOT touch vite.config.ts,",
   "index.html, tsconfig.json, components.json, or the build setup.",
-  "FILE LAYOUT — boringstack, ONE thing per file (judged on this, not just",
-  "compiling). NEVER put more than one component in a file, and NEVER inline types",
-  "or constants in a component file:",
-  "  • Organize by DOMAIN: each feature/area of the app is its own folder under",
-  "    src/, named for the domain it holds. Inside a domain folder <d>/ put:",
-  "      – <d>.types.ts — that domain's interfaces/types (I-prefixed)",
-  "      – <d>.constants.ts — its `as const` registries/config",
-  "      – one component per .tsx file (PascalCase, named for the component)",
-  "      – (NO <d>.hooks.ts query wrapper — the SDK's useCollection IS the data hook;",
-  "        add a hook file ONLY for genuine derived/computed state, never to fetch)",
-  "      – index.ts — a barrel re-exporting the folder's public surface",
-  "  • Types ALWAYS live in a `.types.ts`, constants in a `.constants.ts` — never",
-  "    inline, and never one mega src/types.ts for the whole app. Types shared",
-  "    across domains → src/shared/shared.types.ts.",
+  "FILE LAYOUT — VIEWS. ONE thing per file, and the GATE ENFORCES IT (lint errors,",
+  "not style): a component .tsx holds ONLY imports + the component — NO inline types,",
+  "constants, or helper functions. Every screen/feature is a VIEW:",
+  "  • src/views/<Feature>/ — one folder per feature (PascalCase, e.g. Dashboard). Put:",
+  "      – index.tsx — THE VIEW: the composition root. It imports its pieces from",
+  "        ./components and the shared primitives in @/components/ui and assembles the",
+  "        screen. This is the only component allowed at the feature root.",
+  "      – components/<X>.tsx — the feature's own components, ONE component per file",
+  "        (PascalCase). Create one ONLY when a piece needs local state, is reused in",
+  "        the view, or is big enough to stand alone — otherwise compose primitives",
+  "        directly in index.tsx. Do NOT wrap a single primitive in a feature name",
+  "        (NO `DealsTable` around <Table> — render <Table> with deal columns instead).",
+  "      – <feature>.types.ts — the feature's interfaces/types (I-prefixed).",
+  "      – <feature>.constants.ts — its `as const` registries/label maps/column specs.",
+  "      – (NO <feature>.hooks.ts query wrapper — the SDK's useCollection IS the data",
+  "        hook; add a hook file ONLY for genuine derived/computed state, never to fetch.)",
+  "  • A component .tsx (index.tsx or components/<X>.tsx) = imports + the component,",
+  "    nothing else. A constant (label map, column spec) → <feature>.constants.ts. A type",
+  "    → <feature>.types.ts (shared across features → src/shared/shared.types.ts). A pure",
+  "    helper (formatCurrency, timeAgo) → src/lib/<name>.ts. Putting any of these atop a",
+  "    component is a GATE ERROR (component-file-purity / component-folder-structure).",
+  "  • Shared, reusable UI primitives live in @/components/ui (scaffold_ui) — they are",
+  "    feature-agnostic. Anything feature-specific is a view component, never a primitive.",
   "  • NO RUNTIME VALIDATION / PARSING — there is NO backend, network, or uploaded",
   "    data here; EVERY value originates from your own typed code + seed, so TypeScript",
   "    has already proven its shape. The TYPE SYSTEM is the only validation. NEVER create",
@@ -467,8 +476,9 @@ const REACT_GUIDANCE = [
   "    create/edit pages (e.g. /deals/create). It writes every src/routes/*.tsx stub AND",
   "    the real home at src/routes/index.tsx and regenerates the route tree, so the whole",
   "    app navigates and every <Link to>/navigate target type-checks from that point on.",
-  "    NEVER hand-write or hand-edit route files or createFileRoute paths. THEN fill each",
-  "    route's placeholder component with the real UI, ONE feature at a time.",
+  "    NEVER hand-write or hand-edit route files or createFileRoute paths. A route file is",
+  "    a THIN SHELL: it renders its view (e.g. `import { Dashboard } from",
+  "    '@/views/Dashboard'`), no UI logic of its own. Build the views ONE feature at a time.",
   "      – shadcn/ui primitives stay in @/components/ui (Button exists; add more there",
   "        following cva + cn() + tokens).",
   "  • src/routeTree.gen.ts is AUTO-GENERATED by the Vite build from your route",
@@ -510,15 +520,19 @@ const REACT_GUIDANCE = [
   "    (label+control+error), form-actions, toolbar, empty-state. COMPOSE these:",
   "    layout = app-shell; a list view = page-header + toolbar + table + empty-state;",
   "    a form = field × N + form-actions. NEVER hand-roll a component OR this view",
-  "    chrome — it wastes time and breaks theme coherence. Write only domain wiring.",
+  "    chrome — it wastes time and breaks theme coherence. Write only feature wiring.",
+  "    `table` is COLUMN-DRIVEN: `<Table columns={dealColumns} data={deals} rowKey={(d)",
+  "    => d.id} />`, where `dealColumns: readonly IColumn<IDeal>[]` is a feature CONSTANT",
+  "    (in <feature>.constants.ts). Each column is `{ header, cell: (row) => …, className? }`.",
+  "    Do NOT build a per-feature table component — pass columns to the one <Table>.",
   "  • HARNESS SDK — USE IT, do NOT hand-roll the data layer (this is the biggest",
   "    speed+quality lever). A tested generic toolkit is already in src/lib/:",
-  "      – createCollection(key, SEED) [from @/lib/collection] IS a domain's whole",
-  "        service: typed async CRUD + Result + latency. <d>.service.ts is ONE line:",
-  "        `export const items = createCollection('items', SEED_ITEMS)`.",
+  "      – createCollection(key, SEED) [from @/lib/collection] IS a feature's whole",
+  "        service: typed async CRUD + Result + latency. <feature>.service.ts (in the",
+  "        view folder) is ONE line: `export const items = createCollection('items', SEED_ITEMS)`.",
   "      – useCollection(collection) [from @/lib/use-collection] IS the data hook:",
   "        cached list, isLoading/error, and create/update/remove mutations WITH",
-  "        optimistic updates + rollback. Do NOT write a <d>.hooks.ts query wrapper.",
+  "        optimistic updates + rollback. Do NOT write a <feature>.hooks.ts query wrapper.",
   "      – useForm({ initial, validate, submit }) [from @/lib/use-form] IS form state:",
   "        values, per-field errors, async submit status. Do NOT hand-roll form state.",
   "      – SEED DATA — GENERATE with faker. NEVER hand-write literal arrays, and NEVER",
@@ -554,8 +568,9 @@ const REACT_GUIDANCE = [
   "        `KIND_LABEL[activity.kind]` needs NO cast. NEVER write the map as a bare",
   "        `as const` and then index it `MAP[key as keyof typeof MAP]` — that `as` is",
   "        REJECTED. The map's KEY type, not a cast, is what makes the lookup type-check.",
-  "    So a domain is mostly: <d>.types.ts + a `satisfies`-typed SEED const + one-line",
-  "    createCollection + components that call useCollection/useForm. Far fewer lines,",
+  "    So a feature is mostly: src/views/<Feature>/{<feature>.types.ts + a `satisfies`-typed",
+  "    SEED const + one-line createCollection + index.tsx + components/} calling",
+  "    useCollection/useForm. Far fewer lines,",
   "    fewer bugs. Only write a custom service/hook if the SDK genuinely can't express",
   "    it. A QueryClientProvider is already wired in src/main.tsx.",
   "  • Style with Tailwind classes via className using theme tokens",
@@ -563,7 +578,7 @@ const REACT_GUIDANCE = [
   "  • Need charts? `recharts` is installed — import from 'recharts'. Need drag-and-",
   "    drop? `@dnd-kit/core` + `@dnd-kit/sortable` are installed. Do NOT add other",
   "    deps (only these + the scaffold's are installed; the build can't fetch more).",
-  "Imports use the @/ alias (e.g. @/<domain>/<domain>.types, @/components/ui/button).",
+  "Imports use the @/ alias (e.g. @/views/<Feature>/<feature>.types, @/components/ui/button).",
   "Do NOT write a checks.json or any browser interaction test. The gate already",
   "builds the app with Vite and renders it in a real browser, FAILING on any",
   "runtime/console error — that IS the acceptance. Spend your effort on a working,",

package/strict.web.eslint.config.mjs

@@ -145,6 +145,7 @@ export default tseslint.config(
       "boringstack/one-component-per-file": "error",
       "react/jsx-key": "error",
       "react/no-array-index-key": "error",
+      "react/button-has-type": "error",
       "react-hooks/rules-of-hooks": "error",
       "react-hooks/exhaustive-deps": "warn",
       "prefer-const": "error",
@@ -207,7 +208,6 @@ export default tseslint.config(
             "jsx-a11y/click-events-have-key-events": "warn",
             "jsx-a11y/no-static-element-interactions": "warn",
             "jsx-a11y/label-has-associated-control": "error",
-            "jsx-a11y/button-has-type": "error",
             "jsx-a11y/no-noninteractive-tabindex": "error",
           },
         },