@agjs/tsforge 0.1.0

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

@@ -0,0 +1,61 @@
+import type { IMetaRuleViolation } from "../../meta-rules";
+import { META_RULE_DOCS } from "./meta-rule-docs";
+
+/** Cap rendered meta-rule violations so error sets can't wall the model. */
+const META_RULE_FEEDBACK_MAX = 10;
+
+/**
+ * Render meta-rule violations as `<file>: <message> (<ruleId>)` with severity tag.
+ * Each violation gets its doc's "how" line appended if available.
+ */
+export function renderMetaViolations(
+  violations: readonly IMetaRuleViolation[]
+): string {
+  const shown = violations.slice(0, META_RULE_FEEDBACK_MAX);
+  const rendered: string[] = [];
+
+  for (const v of shown) {
+    const severity = v.severity === "error" ? "[ERROR]" : "[WARN]";
+    const head = `- ${v.file}: ${v.message} (${v.ruleId}) ${severity}`;
+
+    const doc = META_RULE_DOCS[v.ruleId];
+    const docLine = doc !== undefined ? `\n      💡 ${doc}` : "";
+
+    rendered.push(`${head}${docLine}`);
+  }
+
+  const more =
+    violations.length > META_RULE_FEEDBACK_MAX
+      ? `\n… and ${String(violations.length - META_RULE_FEEDBACK_MAX)} more project structure violations.`
+      : "";
+
+  return rendered.join("\n") + more;
+}
+
+/**
+ * Extract unique meta-rule docs from violations for a help block.
+ * Format: `ruleId: <doc>\n`
+ */
+export function metaRuleHelp(
+  violations: readonly IMetaRuleViolation[]
+): string {
+  const seen = new Set<string>();
+  const blocks: string[] = [];
+
+  for (const v of violations) {
+    if (seen.has(v.ruleId)) {
+      continue;
+    }
+
+    const doc = META_RULE_DOCS[v.ruleId];
+
+    if (doc === undefined) {
+      continue;
+    }
+
+    seen.add(v.ruleId);
+    blocks.push(`${v.ruleId}: ${doc}`);
+  }
+
+  return blocks.length > 0 ? blocks.map((b) => `  ${b}`).join("\n") : "";
+}

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

@@ -0,0 +1,112 @@
+{
+  "@typescript-eslint/no-explicit-any": {
+    "what": "Disallow the `any` type.",
+    "bad": "const age: any = 'seventeen';",
+    "good": "const age: number = 17;"
+  },
+  "@typescript-eslint/no-unsafe-argument": {
+    "what": "Disallow calling a function with a value with type `any`.",
+    "bad": "declare function foo(arg1: string, arg2: number, arg3: string): void;\n\nconst anyTyped = 1 as any;\n\nfoo(...anyTyped);\nfoo(anyTyped, 1, 'a');\n\nconst anyArray: any[] = [];",
+    "good": "declare function foo(arg1: string, arg2: number, arg3: string): void;\n\nfoo('a', 1, 'b');\n\nconst tuple1 = ['a', 1, 'b'] as const;\nfoo(...tuple1);\n\ndeclare function bar(arg1: string, arg2: number, ...rest: string[]): void;"
+  },
+  "@typescript-eslint/no-unsafe-assignment": {
+    "what": "Disallow assigning a value with type `any` to variables and properties.",
+    "bad": "const x = 1 as any,\n  y = 1 as any;\nconst [x] = 1 as any;\nconst [x] = [] as any[];\nconst [x] = [1 as any];\n[x] = [1] as [any];\n\nfunction foo(a = 1 as any) {}",
+    "good": "const x = 1,\n  y = 1;\nconst [x] = [1];\n[x] = [1] as [number];\n\nfunction foo(a = 1) {}\nclass Foo {\n  constructor(private a = 1) {}"
+  },
+  "@typescript-eslint/no-unsafe-call": {
+    "what": "Disallow calling a value with type `any`.",
+    "bad": "declare const anyVar: any;\ndeclare const nestedAny: { prop: any };\n\nanyVar();\nanyVar.a.b();\n\nnestedAny.prop();\nnestedAny.prop['a']();",
+    "good": "declare const typedVar: () => void;\ndeclare const typedNested: { prop: { a: () => void } };\n\ntypedVar();\ntypedNested.prop.a();\n\n(() => {})();\n"
+  },
+  "@typescript-eslint/no-unsafe-member-access": {
+    "what": "Disallow member access on a value with type `any`.",
+    "bad": "declare const anyVar: any;\ndeclare const nestedAny: { prop: any };\n\nanyVar.a;\nanyVar.a.b;\nanyVar['a'];\nanyVar['a']['b'];\n",
+    "good": "declare const properlyTyped: { prop: { a: string } };\n\nproperlyTyped.prop.a;\nproperlyTyped.prop['a'];\n\nconst key = 'a';\nproperlyTyped.prop[key];\n"
+  },
+  "@typescript-eslint/no-unsafe-return": {
+    "what": "Disallow returning a value with type `any` from a function.",
+    "bad": "function foo1() {\n  return 1 as any;\n}\nfunction foo2() {\n  return Object.create(null);\n}\nconst foo3 = () => {\n  return 1 as any;",
+    "good": "function foo1() {\n  return 1;\n}\nfunction foo2() {\n  return Object.create(null) as Record<string, unknown>;\n}\n\nconst foo3 = () => [];"
+  },
+  "@typescript-eslint/no-non-null-assertion": {
+    "what": "Disallow non-null assertions using the `!` postfix operator.",
+    "bad": "interface Example {\n  property?: string;\n}\n\ndeclare const example: Example;\nconst includesBaz = example.property!.includes('baz');",
+    "good": "interface Example {\n  property?: string;\n}\n\ndeclare const example: Example;\nconst includesBaz = example.property?.includes('baz') ?? false;"
+  },
+  "@typescript-eslint/restrict-plus-operands": {
+    "what": "Require both operands of addition to be the same type and be `bigint`, `number`, or `string`.",
+    "bad": "let foo = 1n + 1;\nlet fn = (a: string, b: never) => a + b;",
+    "good": "let foo = 1n + 1n;\nlet fn = (a: string, b: string) => a + b;"
+  },
+  "@typescript-eslint/restrict-template-expressions": {
+    "what": "Enforce template literal expressions to be of `string` type.",
+    "bad": "const arg1 = [1, 2];\nconst msg1 = `arg1 = ${arg1}`;\n\nconst arg2 = { name: 'Foo' };\nconst msg2 = `arg2 = ${arg2 || null}`;",
+    "good": "const arg = 'foo';\nconst msg1 = `arg = ${arg}`;\nconst msg2 = `arg = ${arg || 'default'}`;\n\nconst stringWithKindProp: string & { _kind?: 'MyString' } = 'foo';\nconst msg3 = `stringWithKindProp = ${stringWithKindProp}`;"
+  },
+  "@typescript-eslint/no-floating-promises": {
+    "what": "Require Promise-like statements to be handled appropriately.",
+    "bad": "const promise = new Promise((resolve, reject) => resolve('value'));\npromise;\n\nasync function returnsPromise() {\n  return 'value';\n}\nreturnsPromise().then(() => {});\n",
+    "good": "const promise = new Promise((resolve, reject) => resolve('value'));\nawait promise;\n\nasync function returnsPromise() {\n  return 'value';\n}\n\nvoid returnsPromise();"
+  },
+  "@typescript-eslint/await-thenable": {
+    "what": "Disallow awaiting a value that is not a Thenable.",
+    "bad": "await 'value';\n\nconst createValue = () => 'value';\nawait createValue();",
+    "good": "await Promise.resolve('value');\n\nconst createValue = async () => 'value';\nawait createValue();"
+  },
+  "@typescript-eslint/no-for-in-array": {
+    "what": "Disallow iterating over an array with a for-in loop.",
+    "bad": "declare const array: string[];\n\nfor (const i in array) {\n  console.log(array[i]);\n}\n\nfor (const i in array) {\n  console.log(i, array[i]);",
+    "good": "declare const array: string[];\n\nfor (const value of array) {\n  console.log(value);\n}\n\nfor (let i = 0; i < array.length; i += 1) {\n  console.log(i, array[i]);"
+  },
+  "@typescript-eslint/prefer-nullish-coalescing": {
+    "what": "Enforce using the nullish coalescing operator instead of logical assignments or chaining.",
+    "bad": "declare const a: string | null;\ndeclare const b: string | null;\n\nconst c = a || b;\n\ndeclare let foo: { a: string } | null;\ndeclare function makeFoo(): { a: string };\n",
+    "good": "declare const a: string | null;\ndeclare const b: string | null;\n\nconst c = a ?? b;\n\ndeclare let foo: { a: string } | null;\ndeclare function makeFoo(): { a: string };\n"
+  },
+  "@typescript-eslint/prefer-optional-chain": {
+    "what": "Enforce using concise optional chain expressions instead of chained logical ands, negated logical ors, or empty objects.",
+    "bad": "foo && foo.a && foo.a.b && foo.a.b.c;\nfoo && foo['a'] && foo['a'].b && foo['a'].b.c;\nfoo && foo.a && foo.a.b && foo.a.b.method && foo.a.b.method();\n\n// With empty objects\n(((foo || {}).a || {}).b || {}).c;\n(((foo || {})['a'] || {}).b || {}).c;\n",
+    "good": "foo?.a?.b?.c;\nfoo?.['a']?.b?.c;\nfoo?.a?.b?.method?.();\n\nfoo?.a?.b?.c?.d?.e;\n\n!foo?.bar;\n!foo?.[bar];"
+  },
+  "@typescript-eslint/no-unnecessary-condition": {
+    "what": "Disallow conditionals where the type is always truthy or always falsy.",
+    "bad": "function head<T>(items: T[]) {\n  // items can never be nullable, so this is unnecessary\n  if (items) {\n    return items[0].toUpperCase();\n  }\n}\n\nfunction foo(arg: 'bar' | 'baz') {",
+    "good": "function head<T>(items: T[]) {\n  // Necessary, since items.length might be 0\n  if (items.length) {\n    return items[0].toUpperCase();\n  }\n}\n\nfunction foo(arg: string) {"
+  },
+  "@typescript-eslint/no-unnecessary-type-assertion": {
+    "what": "Disallow type assertions that do not change the type of an expression.",
+    "bad": "const foo = 3;\nconst bar = foo!;",
+    "good": "const foo = <number>3;"
+  },
+  "@typescript-eslint/switch-exhaustiveness-check": {
+    "what": "Require switch-case statements to be exhaustive.",
+    "bad": "type Day =\n  | 'Monday'\n  | 'Tuesday'\n  | 'Wednesday'\n  | 'Thursday'\n  | 'Friday'\n  | 'Saturday'\n  | 'Sunday';",
+    "good": "type Day =\n  | 'Monday'\n  | 'Tuesday'\n  | 'Wednesday'\n  | 'Thursday'\n  | 'Friday'\n  | 'Saturday'\n  | 'Sunday';"
+  },
+  "@typescript-eslint/no-base-to-string": {
+    "what": "Require `.toString()` and `.toLocaleString()` to only be called on objects which provide useful information when stringified.",
+    "bad": "// Passing an object or class instance to string concatenation:\n'' + {};\n\nclass MyClass {}\nconst value = new MyClass();\nvalue + '';\n\n// Interpolation and manual .toString() and `toLocaleString()` calls too:",
+    "good": "// These types all have useful .toString() and `toLocaleString()` methods\n'Text' + true;\n`Value: ${123}`;\n`Arrays too: ${[1, 2, 3]}`;\n(() => {}).toString();\nString(42);\n(() => {}).toLocaleString();\n"
+  },
+  "@typescript-eslint/require-await": {
+    "what": "Disallow async functions which do not return promises and have no `await` expression.",
+    "bad": "async function returnNumber() {\n  return 1;\n}\n\nasync function* asyncGenerator() {\n  yield 1;\n}\n",
+    "good": "function returnNumber() {\n  return 1;\n}\n\nfunction* syncGenerator() {\n  yield 1;\n}\n"
+  },
+  "@typescript-eslint/no-confusing-void-expression": {
+    "what": "Require expressions of type void to appear in statement position.",
+    "bad": "// somebody forgot that `alert` doesn't return anything\nconst response = alert('Are you sure?');\nconsole.log(alert('Are you sure?'));\n\n// it's not obvious whether the chained promise will contain the response (fixable)\npromise.then(value => window.postMessage(value));\n\n// it looks like we are returning the result of `console.error` (fixable)",
+    "good": "// just a regular void function in a statement position\nalert('Hello, world!');\n\n// this function returns a boolean value so it's ok\nconst response = confirm('Are you sure?');\nconsole.log(confirm('Are you sure?'));\n\n// now it's obvious that `postMessage` doesn't return any response"
+  },
+  "@typescript-eslint/no-redundant-type-constituents": {
+    "what": "Disallow members of unions and intersections that do nothing or override type information.",
+    "bad": "type UnionAny = any | 'foo';\ntype UnionUnknown = unknown | 'foo';\ntype UnionNever = never | 'foo';\n\ntype UnionBooleanLiteral = boolean | false;\ntype UnionNumberLiteral = number | 1;\ntype UnionStringLiteral = string | 'foo';\n",
+    "good": "type UnionAny = any;\ntype UnionUnknown = unknown;\ntype UnionNever = never;\n\ntype UnionBooleanLiteral = boolean;\ntype UnionNumberLiteral = number;\ntype UnionStringLiteral = string;\n"
+  },
+  "@typescript-eslint/prefer-reduce-type-parameter": {
+    "what": "Enforce using type parameter when calling `Array#reduce` instead of using a type assertion.",
+    "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  {},"
+  }
+}

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

@@ -0,0 +1,342 @@
+import type { ErrorSet } from "../../validate";
+import generatedJson from "./rule-docs.generated.json";
+
+export interface IRuleDoc {
+  /** One-line statement of what the rule requires. */
+  what: string;
+  /** A minimal example that VIOLATES the rule. */
+  bad: string;
+  /** The corrected version that satisfies it. */
+  good: string;
+}
+
+/**
+ * Auto-fetched docs (eslint/typescript-eslint rules) built offline by
+ * `scripts/build-rule-docs.ts` from the rules' own source. Curated entries
+ * below take precedence; this fills coverage for everything else.
+ */
+const GENERATED: Record<string, IRuleDoc> = generatedJson;
+
+/**
+ * Curated documentation for the rules our gate actually enforces — each with a
+ * before/after, the way a human resolves a lint/type error. Keyed by the exact
+ * `rule` the validators emit: TS diagnostic codes (`TS2532`) and eslint rule
+ * ids (`@typescript-eslint/...`). Surfacing the rule's own bad→good next to the
+ * failure beats making the model re-derive the fix from scratch.
+ */
+const RULE_DOCS: Record<string, IRuleDoc> = {
+  TS2532: {
+    what: "Indexed access is `T | undefined` (noUncheckedIndexedAccess). Bind and guard before use; never `!`.",
+    bad: "total += arr[i];",
+    good: "const x = arr[i]; if (x === undefined) { continue; } total += x;",
+  },
+  TS18048: {
+    what: "Value is possibly `undefined`. Guard it before use.",
+    bad: "return obj.maybe.length;",
+    good: "const v = obj.maybe; if (v === undefined) { return 0; } return v.length;",
+  },
+  TS2322: {
+    what: "Type is not assignable to the target type — fix the value or the annotation, don't widen to `any`.",
+    bad: "const n: number = readLine();",
+    good: "const n: number = Number(readLine());",
+  },
+  TS2307: {
+    what: "Module not found — the package isn't installed. Install it first (greenfield dirs have no node_modules); add its `@types/*` if it ships no types.",
+    bad: "import { render } from 'react-dom';",
+    good: "run: bun add react react-dom @types/react @types/react-dom",
+  },
+  "@typescript-eslint/no-unsafe-return": {
+    what: "Don't return a value typed `any` — narrow it to a real type before returning.",
+    bad: "function f() { return JSON.parse(s); }",
+    good: "const v: unknown = JSON.parse(s); if (typeof v === 'number') { return v; } return 0;",
+  },
+  "@typescript-eslint/no-unsafe-assignment": {
+    what: "Don't assign an `any` to a typed target — type the source.",
+    bad: "const xs = data.map((a, b) => a + b);",
+    good: "const xs: number[] = data.map((a: number, b: number) => a + b);",
+  },
+  "@typescript-eslint/no-unsafe-member-access": {
+    what: "Don't access members off an `any`. Narrow to a known type first.",
+    bad: "return res.body.id;",
+    good: "const body: unknown = res.body; if (isRecord(body)) { return body.id; }",
+  },
+  "@typescript-eslint/restrict-plus-operands": {
+    what: "`+` operands must each be number or string — an `any`/`undefined` is leaking in; type/guard it.",
+    bad: "const sum = a + b; // a or b is any | undefined",
+    good: "const sum: number = (a ?? 0) + (b ?? 0); // with a, b: number",
+  },
+  "@typescript-eslint/no-explicit-any": {
+    what: "No `any`. Use a real type, or `unknown` + a type guard.",
+    bad: "function parse(x: any) {}",
+    good: "function parse(x: unknown) { if (typeof x === 'string') { /* ... */ } }",
+  },
+  "@typescript-eslint/no-non-null-assertion": {
+    what: "No `!`. Guard the value instead.",
+    bad: "const first = arr[0]!;",
+    good: "const first = arr[0]; if (first === undefined) { return; }",
+  },
+  "@typescript-eslint/consistent-type-assertions": {
+    what: "No `as` casts. Use a type guard or `satisfies`.",
+    bad: "const u = json as IUser;",
+    good: "if (isUser(json)) { const u = json; /* narrowed */ }",
+  },
+  "@typescript-eslint/strict-boolean-expressions": {
+    what: "Conditions must be explicit booleans — no truthy strings/numbers/nullables.",
+    bad: "if (name) {}",
+    good: "if (name !== undefined && name.length > 0) {}",
+  },
+  "@typescript-eslint/naming-convention": {
+    what: "Interfaces are PascalCase with an `I` prefix.",
+    bad: "interface User {}",
+    good: "interface IUser {}",
+  },
+  "@typescript-eslint/no-floating-promises": {
+    what: "A promise must be awaited or explicitly voided.",
+    bad: "doAsync();",
+    good: "await doAsync(); // or: void doAsync();",
+  },
+  "prefer-const": {
+    what: "Use `const` for never-reassigned bindings.",
+    bad: "let x = 1;",
+    good: "const x = 1;",
+  },
+  eqeqeq: {
+    what: "Use `===`/`!==`.",
+    bad: "if (a == b) {}",
+    good: "if (a === b) {}",
+  },
+  "prefer-template": {
+    what: "Build strings with template literals, not `+` concatenation.",
+    bad: 'const s = "$" + dollars + "." + cents;',
+    good: "const s = `$${dollars}.${cents}`;",
+  },
+  "@typescript-eslint/no-inferrable-types": {
+    what: "Drop the type annotation when the initializer makes it obvious — let TS infer.",
+    bad: "const negative: boolean = cents < 0;",
+    good: "const negative = cents < 0;",
+  },
+
+  // React / hooks idioms — same failure-keyed mechanism as the eslint/TS rules,
+  // extended to framework rules the React gate enforces. Injected ONLY when the
+  // gate names the rule (never a standing wall of framework advice).
+  "react-hooks/rules-of-hooks": {
+    what: "Hooks run unconditionally at the top of the component — never inside a condition, loop, or after an early return.",
+    bad: "if (open) { const [x, setX] = useState(0); }",
+    good: "const [x, setX] = useState(0); if (open) { /* use x */ }",
+  },
+  "react-hooks/exhaustive-deps": {
+    what: "A hook's dependency array must list every reactive value it reads; add the missing dep (or memoize/move it).",
+    bad: "useEffect(() => { send(query); }, []);",
+    good: "useEffect(() => { send(query); }, [query]);",
+  },
+  "react/jsx-key": {
+    what: "Each element in a list needs a stable, unique `key` — an id, not the array index.",
+    bad: "items.map((it) => <li>{it.text}</li>)",
+    good: "items.map((it) => <li key={it.id}>{it.text}</li>)",
+  },
+  "react/no-array-index-key": {
+    what: "Don't use the array index as `key` — it breaks element identity when the list reorders or filters. Use a stable id.",
+    bad: "items.map((it, i) => <li key={i}>{it.text}</li>)",
+    good: "items.map((it) => <li key={it.id}>{it.text}</li>)",
+  },
+};
+
+/**
+ * Strict-TypeScript idiom traps: valid JavaScript the model habitually writes
+ * that trips the gate in a way the rule MESSAGE alone doesn't explain — the
+ * failure fires at the use-site, not where the bad value was created. Matched
+ * against the editable file's SOURCE (not just the errored line), and gated on
+ * the error set looking like this trap's failure, so the hint is precise and
+ * never fires spuriously on a clean run.
+ *
+ * Seeded from a real, repeated `money` failure: `new Array(n).fill(x)` is typed
+ * `any[]` under strict, so the model fixed it, reintroduced it, and fixed it
+ * again across separate turns.
+ */
+interface IIdiomTrap {
+  /** Pattern in the editable source that signals the trap is present. */
+  inSource: RegExp;
+  /** Tested against each error's `rule + message`; the hint only shows on a match. */
+  relevant: RegExp;
+  /** The targeted fix, shown when both conditions hold. */
+  hint: string;
+}
+
+const IDIOM_TRAPS: readonly IIdiomTrap[] = [
+  {
+    inSource: /new\s+Array\s*\([^)]*\)\s*\.fill\(/,
+    relevant: /unsafe|no-explicit-any|\bany\b/i,
+    hint: "`new Array(n).fill(x)` is typed `any[]` under strict TypeScript, so every element read off it is `any`. Use `Array.from({ length: n }, () => x)` — it's typed `T[]`.",
+  },
+];
+
+/**
+ * Idiom hints for traps whose pattern appears in the given source AND whose
+ * signature matches the current errors. `sources` are the editable files'
+ * contents; `errors` are the gate failures.
+ */
+export function idiomHints(
+  sources: readonly string[],
+  errors: ErrorSet
+): string {
+  const errText = errors.map((e) => `${e.rule ?? ""} ${e.message}`).join("\n");
+  const hints = new Set<string>();
+
+  for (const trap of IDIOM_TRAPS) {
+    if (!trap.relevant.test(errText)) {
+      continue;
+    }
+
+    if (sources.some((s) => trap.inSource.test(s))) {
+      hints.add(trap.hint);
+    }
+  }
+
+  return [...hints].map((h) => `- ${h}`).join("\n");
+}
+
+/**
+ * Pull rule guidance straight from raw command output (tsc text, `eslint
+ * --format json`, plain eslint). This is what lets the docs reach the model
+ * when IT runs the gate via the `run` tool — otherwise it only sees raw errors
+ * and fixes them blind across many rounds.
+ */
+export function ruleHelpFromOutput(output: string): string {
+  const ids = new Set<string>();
+
+  for (const m of output.matchAll(/TS\d+/g)) {
+    ids.add(m[0]);
+  }
+
+  for (const m of output.matchAll(/"ruleId"\s*:\s*"([^"]+)"/g)) {
+    if (m[1] !== undefined) {
+      ids.add(m[1]);
+    }
+  }
+
+  for (const m of output.matchAll(/@typescript-eslint\/[a-z-]+/g)) {
+    ids.add(m[0]);
+  }
+
+  const errors = [...ids].map((rule) => ({ key: rule, rule, message: "" }));
+
+  return ruleHelp(errors);
+}
+
+/** Format the rule docs for whichever rules appear in the current error set. */
+export function ruleHelp(errors: ErrorSet): string {
+  const seen = new Set<string>();
+  const blocks: string[] = [];
+
+  for (const e of errors) {
+    if (e.rule === undefined || seen.has(e.rule)) {
+      continue;
+    }
+
+    // Try curated docs first, then generated, then tsforge pack rules
+    let doc = RULE_DOCS[e.rule] ?? GENERATED[e.rule];
+
+    if (doc === undefined && e.rule.startsWith("tsforge/")) {
+      // For tsforge pack rules, look up in generated docs
+      doc = GENERATED[e.rule];
+    }
+
+    if (doc === undefined) {
+      continue;
+    }
+
+    seen.add(e.rule);
+    blocks.push(`${e.rule}: ${doc.what}\n  ✗ ${doc.bad}\n  ✓ ${doc.good}`);
+  }
+
+  return blocks.join("\n");
+}
+
+/**
+ * Parse a typescript-eslint rule's source `.mdx` into a doc. The format is
+ * regular: a frontmatter `description:` and `<TabItem value="❌ Incorrect">` /
+ * `"✅ Correct"` sections each followed by a fenced ```ts block. Used offline by
+ * the cache builder. Returns null if the expected sections aren't found.
+ */
+export function parseRuleMdx(mdx: string): IRuleDoc | null {
+  const desc = /^description:\s*['"]([\s\S]+?)['"]\s*$/m.exec(mdx);
+  const bad = firstTsBlock(mdx, "❌ Incorrect");
+  const good = firstTsBlock(mdx, "✅ Correct");
+
+  if (bad === null || good === null) {
+    return null;
+  }
+
+  return {
+    what: desc?.[1] ?? "",
+    bad: cap(bad),
+    good: cap(good),
+  };
+}
+
+function firstTsBlock(mdx: string, marker: string): string | null {
+  const at = mdx.indexOf(marker);
+
+  if (at === -1) {
+    return null;
+  }
+
+  const block = /```ts\n([\s\S]*?)```/.exec(mdx.slice(at));
+
+  return block?.[1]?.trimEnd() ?? null;
+}
+
+/** Keep examples prompt-lean — first ~8 lines, capped. */
+function cap(code: string): string {
+  const lines = code.split("\n").slice(0, 8).join("\n");
+
+  return lines.length > 360 ? `${lines.slice(0, 360)}…` : lines;
+}
+
+/**
+ * Targeted fix guidance for a quality-REVIEWER's prose critique — the idiomatic
+ * issues the GATE can't flag (the model is already green). Keyed by what the
+ * judge actually complains about on Q4 runs: over-annotation, gratuitous
+ * undefined guards, locale-less toLocaleString, `+` concatenation, terse names.
+ * Turns a vague "make it more idiomatic" into a concrete bad→good, the same way
+ * ruleHelp does for lint failures — but on the quality channel, not the gate.
+ */
+interface IQualityHint {
+  /** Tested against the judge's notes prose. */
+  match: RegExp;
+  advice: string;
+}
+
+const QUALITY_HINTS: readonly IQualityHint[] = [
+  {
+    match: /verbose|explicit|redundant|annotation/i,
+    advice:
+      "Drop redundant type annotations — let TS infer obvious locals/returns (`const n = total;`, not `const n: number = total;`). Annotate parameters and unclear inference only.",
+  },
+  {
+    match: /unnecessary|undefined check|null check/i,
+    advice:
+      "Remove `=== undefined`/null guards the compiler doesn't require (a value already narrowed, or a non-indexed access). Guard ONLY where `noUncheckedIndexedAccess` actually flags it.",
+  },
+  {
+    match: /locale|toLocaleString/i,
+    advice:
+      'Pass an explicit locale: `n.toLocaleString("en-US")` — bare `toLocaleString()` is environment-dependent.',
+  },
+  {
+    match: /concatenat|string \+| \+ |\bconcat\b/i,
+    advice:
+      "Prefer template literals over `+` string concatenation: `` `${dollars}.${cents}` ``.",
+  },
+  {
+    match: /terse|short name|parameter name|\bnaming\b/i,
+    advice: "Name parameters descriptively (`acc`, `ratio` — not `a`, `r`).",
+  },
+];
+
+/** Concrete fix guidance for a quality reviewer's critique, or "" if none match. */
+export function qualityHints(notes: string): string {
+  return QUALITY_HINTS.filter((h) => h.match.test(notes))
+    .map((h) => `- ${h.advice}`)
+    .join("\n");
+}

package/src/loop/index.ts

@@ -0,0 +1,19 @@
+export * from "./loop.types";
+export * from "./loop.constants";
+export { runTask } from "./run";
+export { runSpec } from "./run-spec";
+export { qualityRepair } from "./quality";
+export {
+  toolsFor,
+  buildTsService,
+  runToolCalls,
+  settleGate,
+  type ILoopCtx,
+  type ILoopState,
+} from "./turn";
+export {
+  Session,
+  PLAN_APPROVED_NOTE,
+  type ISessionConfig,
+  type ISendResult,
+} from "./session";

package/src/loop/loop.constants.ts

@@ -0,0 +1,68 @@
+/** Terminal status of a single task run — compare against these, not bare strings. */
+export const RUN_STATUS = {
+  done: "done",
+  stuck: "stuck",
+  redNotConfirmed: "red-not-confirmed",
+} as const;
+
+/** Why a run gave up (only set when status is `stuck`). */
+export const STUCK_REASON = {
+  stalled: "stalled",
+  cap: "cap",
+} as const;
+
+/** Whole-spec outcome — compare against these, never the bare string. */
+export const SPEC_STATUS = {
+  done: "done",
+  blocked: "blocked",
+} as const;
+
+/**
+ * Loop tuning — kept with the loop domain (not a global bucket). Each value's
+ * rationale lives here so a tuning pass sees the whole budget at a glance.
+ */
+export const LOOP_LIMITS = {
+  /** Max chars of a tool's output fed back to the model (keeps context bounded). */
+  maxToolOutputChars: 4000,
+  /**
+   * Reject an edit replacement spanning more than this many lines — a push
+   * toward surgical changes over lazy whole-file rewrites. 50 admits real
+   * functions, still rejects ~80-line rewrites; the gate re-validates anyway.
+   */
+  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.
+   */
+  gateStuckRepeats: 10,
+  /**
+   * 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. */
+  maxTurns: 40,
+  /** 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
+   *  hit the default 40 cap, before the gate ever ran. */
+  webMaxTurns: 180,
+  /**
+   * How many times a build turn may dump file contents as a chat message (instead
+   * of calling `create`) before the session gives up. Each time we nudge it to use
+   * tools; past this it's clearly not going to act, so stop with a clear message
+   * rather than loop forever narrating code.
+   */
+  maxBuildNudges: 2,
+  /**
+   * Default reasoning-token cap for SCRATCH (create-from-spec) tasks, where the
+   * model over-thinks unbounded (~92s turn-1, occasional 198s spirals) without
+   * converging faster. Measured knee on money: 2048 ≈ 73s/4 turns vs 206s/5.7
+   * uncapped, Q-neutral; 4096 rambles back up to 133s. NOT applied to existing-
+   * code runs — there the cap HURT navigation (react-board hit 12 turns @2048),
+   * since understanding a codebase genuinely needs reasoning. Override per-run
+   * with TSFORGE_THINKING_BUDGET / opts.thinkingTokenBudget. Harder algorithmic
+   * scratch targets may want a higher override.
+   */
+  scratchThinkingBudget: 2048,
+} as const;