@agjs/tsforge 0.2.7 → 0.2.9

package/package.json

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

package/src/cli.ts

@@ -28,6 +28,7 @@ import {
 } from "./render";
 import type { ITask } from "./spec";
 import type { Reporter, ILoopEvent } from "./loop";
+import { loadLedger, activeRules, forgetMemory } from "./loop/memory";
 import {
   buildGate,
   buildWebGate,
@@ -675,6 +676,7 @@ const HELP = [
   "  /sessions        list saved sessions (resume one with: tsforge --resume <id>)",
   "  /cost            rough conversation size (messages + ~tokens)",
   "  /metrics         token totals + generation rate (tok/s) this session",
+  "  /memory          show learned failure→fix lessons (/memory forget to clear)",
   "  /exit, /quit     leave the session",
   "",
   "Anything else is sent to the agent. It works with its tools; when it stops,",
@@ -1247,6 +1249,40 @@ async function repl(args: ICliArgs): Promise<number> {
         await printSessions(args.dir);
         break;
 
+      case "memory": {
+        if (arg.trim() === "forget") {
+          await forgetMemory(args.dir);
+          process.stdout.write("  memory cleared for this repo\n");
+          break;
+        }
+
+        const ledger = await loadLedger(args.dir);
+
+        if (ledger.entries.length === 0) {
+          process.stdout.write("  no learned lessons yet\n");
+          break;
+        }
+
+        const activeNames = new Set(
+          activeRules(ledger, Date.now()).map((r) => r.name)
+        );
+
+        process.stdout.write(
+          `  ${String(ledger.entries.length)} lesson(s), ${String(activeNames.size)} active (● fires · ○ still accruing):\n`
+        );
+
+        for (const entry of ledger.entries.slice(0, 20)) {
+          const mark = activeNames.has(entry.name) ? "●" : "○";
+
+          process.stdout.write(
+            `    ${mark} ${entry.rule} · ${String(entry.hits)} hit(s)\n`
+          );
+        }
+
+        process.stdout.write("  /memory forget to clear\n");
+        break;
+      }
+
       case "cost": {
         const chars = session.messages.reduce(
           (sum, m) => sum + m.content.length,

package/src/loop/memory/consolidate.ts

@@ -0,0 +1,256 @@
+import { join } from "node:path";
+import { rm } from "node:fs/promises";
+
+import { isRecord, isArray } from "../../lib/guards";
+import type { ITtsrRule } from "../ttsr";
+
+import {
+  EMPTY_LEDGER,
+  MIN_HITS_TO_ACTIVATE,
+  DECAY_MS,
+  type ICandidateLesson,
+  type ILedgerEntry,
+  type IMemoryLedger,
+} from "./memory.types";
+
+const MEMORY_DIR = ".tsforge";
+const LEDGER_FILE = "memory.json";
+const LEARNED_RULES_FILE = "learned-rules.json";
+const MAX_GUIDANCE = 300;
+
+/** Escape a string for use as a literal regex source. */
+function escapeRegex(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** djb2 hash → base36, for a short stable id from a snippet. */
+function shortHash(text: string): string {
+  let hash = 5381;
+
+  for (let i = 0; i < text.length; i += 1) {
+    hash = (hash * 33) ^ text.charCodeAt(i);
+  }
+
+  return (hash >>> 0).toString(36);
+}
+
+/** The single most informative line of a snippet — the condition matches THIS,
+ *  not the whole (possibly multi-line) replaced block, so it stays a tight,
+ *  meaningful trigger. */
+function salientLine(before: string): string {
+  const lines = before
+    .split("\n")
+    .map((l) => l.trim())
+    .filter((l) => l.length > 0);
+
+  return lines.reduce(
+    (best, line) => (line.length > best.length ? line : best),
+    ""
+  );
+}
+
+/** A conservative literal-regex condition source matching the mistake's salient line. */
+export function conditionFor(before: string): string {
+  return escapeRegex(salientLine(before));
+}
+
+/** A deterministic, collision-resistant rule name from the gate rule + the snippet. */
+export function ruleName(rule: string, before: string): string {
+  const slug = rule.replace(/[^a-zA-Z0-9]+/g, "-").toLowerCase();
+
+  return `learned-${slug}-${shortHash(salientLine(before))}`;
+}
+
+/** TTSR file globs for the fixed file's family (by extension). */
+function fileGlobsFor(file: string): string[] {
+  if (file.endsWith(".tsx")) {
+    return ["**/*.tsx"];
+  }
+
+  if (file.endsWith(".ts")) {
+    return ["**/*.ts"];
+  }
+
+  return ["**/*"];
+}
+
+/** The corrective nudge shown when the learned pattern recurs (capped). */
+function guidanceFor(rule: string, after: string): string {
+  const fix = salientLine(after);
+  const base = `This pattern previously failed the gate (${rule}) in this repo. Use the known-good fix instead`;
+  const withFix = fix.length > 0 ? `${base}, e.g.: ${fix}` : `${base}.`;
+
+  return withFix.length > MAX_GUIDANCE
+    ? `${withFix.slice(0, MAX_GUIDANCE - 1)}…`
+    : withFix;
+}
+
+function candidateToEntry(
+  candidate: ICandidateLesson,
+  sessionId: string,
+  now: number
+): ILedgerEntry {
+  return {
+    name: ruleName(candidate.rule, candidate.before),
+    rule: candidate.rule,
+    condition: conditionFor(candidate.before),
+    guidance: guidanceFor(candidate.rule, candidate.after),
+    fileGlobs: fileGlobsFor(candidate.file),
+    hits: 1,
+    source: sessionId,
+    lastSeen: now,
+  };
+}
+
+/**
+ * Merge a run's candidates into the ledger. `hits` counts DISTINCT SESSIONS, so
+ * multiple candidates with the same name from one run bump it by exactly one;
+ * a lesson from a NEW session bumps an existing entry. Returns a new ledger.
+ */
+export function mergeCandidates(
+  ledger: IMemoryLedger,
+  candidates: readonly ICandidateLesson[],
+  sessionId: string,
+  now: number
+): IMemoryLedger {
+  const byName = new Map<string, ILedgerEntry>(
+    ledger.entries.map((e) => [e.name, e])
+  );
+  // Dedupe this session's candidates by name first (one fix seen twice in a run
+  // is still one occurrence).
+  const seenThisSession = new Set<string>();
+
+  for (const candidate of candidates) {
+    const name = ruleName(candidate.rule, candidate.before);
+
+    if (seenThisSession.has(name)) {
+      continue;
+    }
+
+    seenThisSession.add(name);
+
+    const existing = byName.get(name);
+
+    if (existing === undefined) {
+      byName.set(name, candidateToEntry(candidate, sessionId, now));
+      continue;
+    }
+
+    // A new session re-producing the lesson bumps hits; the same session never does.
+    const bump = existing.source === sessionId ? 0 : 1;
+
+    byName.set(name, {
+      ...existing,
+      hits: existing.hits + bump,
+      source: sessionId,
+      lastSeen: now,
+    });
+  }
+
+  return { version: 1, entries: [...byName.values()] };
+}
+
+/** Project the ledger to ACTIVE learned TTSR rules: recurring (hits ≥ threshold)
+ *  and not decayed (seen within DECAY_MS). Accumulation ≠ injection. */
+export function activeRules(ledger: IMemoryLedger, now: number): ITtsrRule[] {
+  return ledger.entries
+    .filter(
+      (e) => e.hits >= MIN_HITS_TO_ACTIVATE && now - e.lastSeen < DECAY_MS
+    )
+    .map((e) => ({
+      name: e.name,
+      condition: [e.condition],
+      scope: "tool-args" as const,
+      // No fileGlobs: the condition is already a specific code snippet, and the
+      // TTSR file-glob matcher does not match `**/*.ts`-style patterns — setting
+      // one would silently prevent the rule from ever firing.
+      guidance: e.guidance,
+      repeatMode: "cooldown" as const,
+      repeatGap: 3,
+    }));
+}
+
+/** Parse a stored ledger, tolerating any malformation (→ empty), like the rest
+ *  of tsforge's disk readers. */
+function parseLedger(content: string): IMemoryLedger {
+  let parsed: unknown;
+
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    return EMPTY_LEDGER;
+  }
+
+  if (!isRecord(parsed) || !isArray(parsed.entries)) {
+    return EMPTY_LEDGER;
+  }
+
+  const entries = parsed.entries.filter(
+    (e): e is ILedgerEntry =>
+      isRecord(e) &&
+      typeof e.name === "string" &&
+      typeof e.rule === "string" &&
+      typeof e.condition === "string" &&
+      typeof e.guidance === "string" &&
+      isArray(e.fileGlobs) &&
+      typeof e.hits === "number" &&
+      typeof e.source === "string" &&
+      typeof e.lastSeen === "number"
+  );
+
+  return { version: 1, entries };
+}
+
+/** Forget all learned memory for a project: delete the ledger and the active
+ *  learned-rules file (`tsforge memory forget`). Best-effort. */
+export async function forgetMemory(cwd: string): Promise<void> {
+  for (const name of [LEDGER_FILE, LEARNED_RULES_FILE]) {
+    await rm(join(cwd, MEMORY_DIR, name), { force: true });
+  }
+}
+
+/** Load the project ledger from `<cwd>/.tsforge/memory.json`. */
+export async function loadLedger(cwd: string): Promise<IMemoryLedger> {
+  const file = Bun.file(join(cwd, MEMORY_DIR, LEDGER_FILE));
+
+  if (!(await file.exists())) {
+    return EMPTY_LEDGER;
+  }
+
+  return parseLedger(await file.text());
+}
+
+/**
+ * The full Phase-1 consolidation step: load the ledger, merge this run's
+ * candidates, persist the ledger, and (re)write the active learned-rules file
+ * the TTSR loader reads. Returns the count of active rules written.
+ */
+export async function consolidate(
+  cwd: string,
+  candidates: readonly ICandidateLesson[],
+  sessionId: string,
+  now: number = Date.now()
+): Promise<number> {
+  if (candidates.length === 0) {
+    return 0;
+  }
+
+  const merged = mergeCandidates(
+    await loadLedger(cwd),
+    candidates,
+    sessionId,
+    now
+  );
+  const active = activeRules(merged, now);
+
+  await Bun.write(
+    join(cwd, MEMORY_DIR, LEDGER_FILE),
+    `${JSON.stringify(merged, null, 2)}\n`
+  );
+  await Bun.write(
+    join(cwd, MEMORY_DIR, LEARNED_RULES_FILE),
+    `${JSON.stringify(active, null, 2)}\n`
+  );
+
+  return active.length;
+}

package/src/loop/memory/index.ts

@@ -0,0 +1,18 @@
+export { mineLessons } from "./mine";
+export {
+  consolidate,
+  loadLedger,
+  forgetMemory,
+  mergeCandidates,
+  activeRules,
+  conditionFor,
+  ruleName,
+} from "./consolidate";
+export {
+  EMPTY_LEDGER,
+  MIN_HITS_TO_ACTIVATE,
+  DECAY_MS,
+  type ICandidateLesson,
+  type ILedgerEntry,
+  type IMemoryLedger,
+} from "./memory.types";

package/src/loop/memory/memory.types.ts

@@ -0,0 +1,65 @@
+/**
+ * tsforge MEMORY — the reflect → distill → consolidate → recall loop.
+ *
+ * Phase 1 (this module set) is the failure→fix channel: mine a run's event
+ * stream for mistakes the model MADE then FIXED, accumulate them in a local
+ * ledger with recurrence counts, and project the recurring ones into the
+ * `.tsforge/learned-rules.json` TTSR file the harness already loads. Memory
+ * accumulates aggressively; recall stays cheap (a learned rule is a dormant
+ * trigger — zero prompt cost until the exact mistake recurs).
+ */
+
+/** A mistake-then-fix pair mined from one run: the gate rule that was failing,
+ *  the file it was fixed in, and the edit that cleared it. */
+export interface ICandidateLesson {
+  /** The gate rule/code that disappeared after the edit (e.g. "no-explicit-any",
+   *  "TS18048"). */
+  readonly rule: string;
+  /** The file whose edit cleared the failure. */
+  readonly file: string;
+  /** The offending snippet (the edit's replaced text). */
+  readonly before: string;
+  /** The fix (the edit's replacement text). */
+  readonly after: string;
+}
+
+/** One accumulated lesson in the project ledger. Carries provenance so it can
+ *  decay: a lesson the model stops re-committing eventually retires. */
+export interface ILedgerEntry {
+  /** Stable, deterministic rule name (derived from rule + a hash of `before`). */
+  readonly name: string;
+  /** The gate rule/code this lesson guards against. */
+  readonly rule: string;
+  /** The TTSR condition (a conservative literal regex source matching `before`). */
+  readonly condition: string;
+  /** The corrective guidance injected when the pattern recurs (≤300 chars). */
+  readonly guidance: string;
+  /** Glob(s) the rule applies to (the fixed file's directory family). */
+  readonly fileGlobs: readonly string[];
+  /** How many distinct sessions have produced this lesson. */
+  readonly hits: number;
+  /** The most recent session id that produced it. */
+  readonly source: string;
+  /** ms timestamp of the most recent occurrence (for decay). */
+  readonly lastSeen: number;
+}
+
+/** The on-disk project ledger (`.tsforge/memory.json`): every candidate ever
+ *  seen, with counts. The subset with `hits >= MIN_HITS_TO_ACTIVATE` is
+ *  projected into the active `.tsforge/learned-rules.json`. */
+export interface IMemoryLedger {
+  readonly version: 1;
+  readonly entries: readonly ILedgerEntry[];
+}
+
+/** Empty ledger for a repo with no memory yet. */
+export const EMPTY_LEDGER: IMemoryLedger = { version: 1, entries: [] };
+
+/** A lesson must be seen in at least this many sessions before it becomes an
+ *  active learned rule — so a single fluke fix never starts steering future
+ *  runs (accumulation ≠ injection). */
+export const MIN_HITS_TO_ACTIVATE = 2;
+
+/** A learned rule unseen for longer than this is retired from the active set
+ *  (kept in the ledger but no longer projected), so stale lessons don't silt up. */
+export const DECAY_MS = 1000 * 60 * 60 * 24 * 45; // 45 days

package/src/loop/memory/mine.ts

@@ -0,0 +1,85 @@
+import type { ILoopEvent } from "../loop.types";
+
+import type { ICandidateLesson } from "./memory.types";
+
+/** Cap edits attributed to a single fix window — keeps a noisy burst of edits
+ *  from cross-producing a flood of weak candidates (the hits gate filters the
+ *  rest anyway). */
+const MAX_EDITS_PER_WINDOW = 3;
+
+interface IEditWindow {
+  file: string;
+  before: string;
+  after: string;
+}
+
+/**
+ * Mine a run's event stream for failure→fix lessons: a gate rule/code that was
+ * FAILING and then DISAPPEARED after one or more edits. Each such (rule, edit)
+ * pair is a candidate — the edit's replaced text (`before`) is the mistake, its
+ * replacement (`after`) is the fix.
+ *
+ * Deterministic, no model call. Only `edit` events teach (they carry the
+ * before→after diff); `create` is net-new so there is no mistake-pattern to
+ * learn. Attribution is coarse (the validated event lists rule codes, not their
+ * files), so one fix window can yield a few candidates; the cross-session hits
+ * gate in consolidation is what promotes only the recurring, real ones.
+ */
+export function mineLessons(events: readonly ILoopEvent[]): ICandidateLesson[] {
+  const candidates: ICandidateLesson[] = [];
+  let prevFailing: Set<string> | null = null;
+  let edits: IEditWindow[] = [];
+
+  for (const event of events) {
+    // The pre-run RED gate is a `red` event (not `validated`), so seed the
+    // baseline failing set from it — otherwise a one-turn red→green fix, whose
+    // only `validated` event is the GREEN one, would mine nothing.
+    if (event.kind === "red") {
+      prevFailing = new Set(event.rules ?? []);
+
+      continue;
+    }
+
+    if (
+      event.kind === "edit" &&
+      event.file !== undefined &&
+      event.oldString !== undefined &&
+      event.newString !== undefined &&
+      event.oldString.trim().length > 0
+    ) {
+      edits.push({
+        file: event.file,
+        before: event.oldString,
+        after: event.newString,
+      });
+
+      continue;
+    }
+
+    if (event.kind !== "validated") {
+      continue;
+    }
+
+    const failing = new Set(event.rules ?? []);
+
+    if (prevFailing !== null && edits.length > 0) {
+      const fixed = [...prevFailing].filter((rule) => !failing.has(rule));
+
+      for (const rule of fixed) {
+        for (const edit of edits.slice(-MAX_EDITS_PER_WINDOW)) {
+          candidates.push({
+            rule,
+            file: edit.file,
+            before: edit.before,
+            after: edit.after,
+          });
+        }
+      }
+    }
+
+    prevFailing = failing;
+    edits = [];
+  }
+
+  return candidates;
+}

package/src/loop/run.ts

@@ -1,16 +1,25 @@
-import { join } from "node:path";
 import type { ITask } from "../spec";
 import type { IChatMessage, IModelResponse, IProvider } from "../inference";
 import { validate, type ErrorParser } from "../validate";
 import { parseEslintJson } from "../validate";
 import { readFiles } from "../lib/fs";
 import { RUN_STATUS, STUCK_REASON, LOOP_LIMITS } from "./loop.constants";
-import type { IRunResult, IRunOptions, Reporter } from "./loop.types";
+import type {
+  IRunResult,
+  IRunOptions,
+  Reporter,
+  ILoopEvent,
+} from "./loop.types";
+import { mineLessons, consolidate as consolidateMemory } from "./memory";
 import { flags } from "../config";
 import { SYSTEM, seedPrompt } from "./prompt";
 import { detectStack } from "../stack-detection";
-import { TtsrManager, parseProjectRules, type ITtsrRule } from "./ttsr";
-import { DEFAULT_TTSR_RULES } from "./ttsr-defaults";
+import type { TtsrManager } from "./ttsr";
+import {
+  initTtsrManager,
+  loadProjectTtsrRules,
+  applyTtsrInterrupt,
+} from "./ttsr-init";
 import {
   type ILoopCtx,
   type ILoopState,
@@ -66,57 +75,14 @@ function handleDegeneration(
   };
 }
 
-/** Read and parse `<cwd>/.tsforge/rules.json` if present. Missing or invalid
- *  files yield no rules (parseProjectRules tolerates malformed JSON). */
-export async function loadProjectTtsrRules(cwd: string): Promise<ITtsrRule[]> {
-  const file = Bun.file(join(cwd, ".tsforge", "rules.json"));
-
-  if (!(await file.exists())) {
-    return [];
-  }
+// TTSR init + project/learned-rule loading live in the shared ttsr-init module
+// (the interactive session uses the same loaders). Re-exported here so existing
+// importers (and tests) keep their path.
+export { initTtsrManager, loadProjectTtsrRules };
 
-  return parseProjectRules(await file.text());
-}
-
-/** Build and configure a TTSR manager if enabled. Returns null if disabled.
- *  Built-in defaults register first, then optional project rules from
- *  `<cwd>/.tsforge/rules.json`; `addRule` ignores duplicate names, so a
- *  built-in safety rule always wins over a same-named project rule. */
-export async function initTtsrManager(
-  cwd: string,
-  report: Reporter,
-  taskId: string
-): Promise<TtsrManager | null> {
-  if (!flags.ttsr()) {
-    return null;
-  }
-
-  const manager = new TtsrManager();
-
-  for (const rule of DEFAULT_TTSR_RULES) {
-    manager.addRule(rule);
-  }
-
-  let added = 0;
-
-  for (const rule of await loadProjectTtsrRules(cwd)) {
-    if (manager.addRule(rule)) {
-      added += 1;
-    }
-  }
-
-  if (added > 0) {
-    report({
-      kind: "ttsr",
-      task: taskId,
-      message: `loaded ${added} custom TTSR rule(s) from .tsforge/rules.json`,
-    });
-  }
-
-  return manager;
-}
-
-/** Handle a TTSR interrupt: report, inject corrective message, and optionally disable. */
+/** Handle a TTSR interrupt in the headless loop: apply the shared interrupt
+ *  (count, report, inject corrective guidance, disable at the cap) then emit
+ *  timing for the interrupted turn. */
 function handleTtsrInterrupt(
   ttsrFired: { ruleName: string; guidance: string },
   state: ILoopState,
@@ -128,32 +94,41 @@ function handleTtsrInterrupt(
   taskStart: number,
   ttsrManager: TtsrManager | null
 ): void {
-  state.ttsrInterrupts += 1;
-
-  report({
-    kind: "ttsr",
-    task: taskId,
-    message: `⚠ TTSR interrupted: ${ttsrFired.ruleName}`,
-  });
-
-  // Hard cap: after 3 interrupts, disable TTSR to prevent loops
-  if (state.ttsrInterrupts >= 3) {
-    report({
-      kind: "tool",
-      task: taskId,
-      message: `TTSR disabled after ${state.ttsrInterrupts} interrupts (hit cap)`,
-    });
+  applyTtsrInterrupt(ttsrFired, state, messages, report, taskId, ttsrManager);
+  emitTiming(report, taskId, turn, turnStart, taskStart);
+}
 
-    ttsrManager?.disable();
+/**
+ * MEMORY post-run hook: mine this run's events for failure→fix lessons and
+ * consolidate them into `.tsforge/`. Gated on the TTSR flag (learned rules are
+ * recalled via TTSR, so there's nothing to learn for if it's off). Best-effort:
+ * a memory failure never affects the run's result. `runId` is unique per run so
+ * the same task re-run counts as a distinct session for the recurrence gate.
+ */
+async function consolidateLessons(
+  cwd: string,
+  events: readonly ILoopEvent[],
+  runId: string,
+  report: Reporter
+): Promise<void> {
+  if (!flags.ttsr()) {
+    return;
   }
 
-  // Append corrective message and retry without counting as a normal cycle
-  messages.push({
-    role: "user",
-    content: `⚠ generation interrupted: ${ttsrFired.guidance} Rewrite the affected part without that pattern.`,
-  });
+  try {
+    const candidates = mineLessons(events);
+    const active = await consolidateMemory(cwd, candidates, runId);
 
-  emitTiming(report, taskId, turn, turnStart, taskStart);
+    if (active > 0) {
+      report({
+        kind: "ttsr",
+        task: runId,
+        message: `memory: ${String(active)} learned rule(s) active in .tsforge/learned-rules.json`,
+      });
+    }
+  } catch {
+    // Memory is supplementary — never let it break a run.
+  }
 }
 
 /** Assemble per-call completion options, leaving optional knobs unset when absent. */
@@ -242,7 +217,25 @@ export async function runTask(
   const effectiveParse = effectiveParserFor(parse);
   const temperature = opts.temperature ?? 0;
   const maxTurns = opts.maxTurns ?? LOOP_LIMITS.maxTurns;
-  const report: Reporter = opts.onEvent ?? (() => undefined);
+  // Buffer every event so the post-run memory hook can mine the run for
+  // failure→fix lessons, while still forwarding live to the real reporter.
+  const base: Reporter = opts.onEvent ?? (() => undefined);
+  const events: ILoopEvent[] = [];
+
+  const report: Reporter = (event) => {
+    events.push(event);
+    base(event);
+  };
+
+  // Unique per run, so re-running the same task counts as a distinct session for
+  // the lesson-recurrence gate.
+  const runId = `${task.id}-${Date.now().toString(36)}`;
+
+  const finish = async (result: IRunResult): Promise<IRunResult> => {
+    await consolidateLessons(cwd, events, runId, report);
+
+    return result;
+  };
 
   report({
     kind: "start",
@@ -275,6 +268,9 @@ export async function runTask(
     kind: "red",
     task: task.id,
     errors: red.errors.length,
+    // Carry the failing rule codes so the memory miner can seed the baseline
+    // failure set — a one-turn red→green fix has no prior `validated` event.
+    rules: red.errors.flatMap((e) => (e.rule === undefined ? [] : [e.rule])),
     message: `task ${task.id}: RED (${red.errors.length} error(s))`,
   });
 
@@ -403,7 +399,7 @@ export async function runTask(
     });
 
     if (looped !== null) {
-      return looped;
+      return finish(looped);
     }
 
     const touchedEditable =
@@ -419,11 +415,11 @@ export async function runTask(
       emitTiming(report, task.id, turn, turnStart, taskStart);
 
       if (settled !== null) {
-        return {
+        return finish({
           ...settled,
           edits: state.edits,
           regressions: state.regressions,
-        };
+        });
       }
 
       // Stopped with no tool call while still red → nudge it to act, not narrate.
@@ -444,7 +440,7 @@ export async function runTask(
     message: `task ${task.id}: stuck (hit ${maxTurns}-turn cap)`,
   });
 
-  return {
+  return finish({
     task: task.id,
     redConfirmed: true,
     status: RUN_STATUS.stuck,
@@ -452,5 +448,5 @@ export async function runTask(
     reason: STUCK_REASON.cap,
     edits: state.edits,
     regressions: state.regressions,
-  };
+  });
 }

package/src/loop/session.ts

@@ -28,7 +28,10 @@ import {
 import { connectMcpServers } from "../mcp";
 import { loadAndRegisterPlugins } from "../config/external-plugins";
 import { LOOP_LIMITS, RUN_STATUS } from "./loop.constants";
-import type { Reporter } from "./loop.types";
+import type { Reporter, ILoopEvent } from "./loop.types";
+import type { TtsrManager } from "./ttsr";
+import { initTtsrManager, applyTtsrInterrupt } from "./ttsr-init";
+import { mineLessons, consolidate as consolidateMemory } from "./memory";
 import { CHAT_SYSTEM, COMPACT_SYSTEM } from "./prompt";
 import {
   buildTsService,
@@ -396,6 +399,12 @@ export class Session {
   private readonly forceTools: boolean;
   /** Mid-session turn-cap override (setMaxTurns) — a web scaffold raises it. */
   private maxTurnsOverride?: number;
+  /** TTSR manager (built-in + project + memory-learned rules). Null when TTSR is
+   *  disabled. Built in `create` (needs async rule loading). */
+  private ttsrManager: TtsrManager | null = null;
+  /** Events of the CURRENT send (reset each drive), buffered off ctx.report so the
+   *  post-send memory hook can mine the run for failure→fix lessons. */
+  private readonly sendEvents: ILoopEvent[] = [];
 
   private constructor(cfg: ISessionConfig, ctx: ILoopCtx) {
     this.provider = cfg.provider;
@@ -443,6 +452,15 @@ export class Session {
     }
 
     this.ctx = ctx;
+    // Buffer events off ctx.report (where edit/create/validated flow) so the
+    // post-send memory hook can mine them; still forward to the original reporter.
+    const rawCtxReport = ctx.report;
+
+    this.ctx.report = (event) => {
+      this.sendEvents.push(event);
+      rawCtxReport(event);
+    };
+
     this.state = {
       prevGateErrors: [],
       gateNoProgress: 0,
@@ -523,7 +541,14 @@ export class Session {
       },
     };
 
-    return new Session(cfg, ctx);
+    const session = new Session(cfg, ctx);
+
+    // Build the TTSR manager (built-in + project + memory-learned rules) so the
+    // interactive loop gets the SAME mid-stream guidance the headless loop does —
+    // including the failure→fix lessons learned in this repo.
+    session.ttsrManager = await initTtsrManager(cfg.cwd, report, SESSION_ID);
+
+    return session;
   }
 
   /** The current gate command (empty when none). */
@@ -1024,6 +1049,9 @@ export class Session {
       mcpSchemas.length > 0 ? [...baseTools, ...mcpSchemas] : baseTools;
     const callStart = performance.now();
     let firstTokenAt = 0;
+
+    this.ttsrManager?.resetBuffer();
+
     const res = await this.provider.complete(ctx.messages, {
       tools: offeredTools,
       temperature: this.cfg.temperature ?? 0,
@@ -1032,6 +1060,7 @@ export class Session {
       ...(this.cfg.thinkingTokenBudget === undefined
         ? {}
         : { thinkingTokenBudget: this.cfg.thinkingTokenBudget }),
+      ...this.ttsrCallOption(),
       ...(signal === undefined ? {} : { signal }),
       onToken: (token, channel) => {
         // Stamp the first token so tokens/sec measures generation rate (excluding
@@ -1073,6 +1102,10 @@ export class Session {
 
     ctx.messages.push(assistantMessage(res));
 
+    // Every model call advances TTSR cooldown accounting (including interrupted
+    // ones, so repeatGap rules count correctly after a retry).
+    this.ttsrManager?.incrementTurnCount();
+
     if (res.salvaged !== undefined && res.salvaged > 0) {
       report({
         kind: "tool",
@@ -1370,10 +1403,103 @@ export class Session {
     }
   }
 
+  /** Drive one send to a terminal result, then mine the send's events for
+   *  failure→fix lessons (best-effort, never affects the result). The buffer is
+   *  reset per send so each maps to one "run". */
   private async drive(
     maxTurns: number,
     sendStart: number,
     opts: ISendOptions
+  ): Promise<ISendResult> {
+    this.sendEvents.length = 0;
+
+    try {
+      return await this.driveInner(maxTurns, sendStart, opts);
+    } finally {
+      await this.consolidateLessons();
+    }
+  }
+
+  /** Mine the current send's events into the project's learned-rules memory.
+   *  Gated on the TTSR flag (learned rules are recalled via TTSR). */
+  private async consolidateLessons(): Promise<void> {
+    if (!flags.ttsr()) {
+      return;
+    }
+
+    try {
+      const candidates = mineLessons(this.sendEvents);
+      const runId = `${SESSION_ID}-${Date.now().toString(36)}`;
+      const active = await consolidateMemory(this.ctx.cwd, candidates, runId);
+
+      if (active > 0) {
+        this.report({
+          kind: "ttsr",
+          task: SESSION_ID,
+          message: `memory: ${String(active)} learned rule(s) active in .tsforge/learned-rules.json`,
+        });
+      }
+    } catch {
+      // Memory is supplementary — never let it break a send.
+    }
+  }
+
+  /** The `ttsrManager` completion option, or nothing when TTSR is off. */
+  private ttsrCallOption():
+    | { ttsrManager: TtsrManager }
+    | Record<string, never> {
+    return this.ttsrManager === null ? {} : { ttsrManager: this.ttsrManager };
+  }
+
+  /** Apply a mid-stream TTSR fire (inject guidance, retry). Returns true when it
+   *  fired (the caller should `continue`). */
+  private handleTtsrFired(
+    res: IModelResponse,
+    turn: number,
+    turnStart: number,
+    sendStart: number
+  ): boolean {
+    if (res.ttsrFired === undefined) {
+      return false;
+    }
+
+    applyTtsrInterrupt(
+      res.ttsrFired,
+      this.state,
+      this.ctx.messages,
+      this.report,
+      SESSION_ID,
+      this.ttsrManager
+    );
+    emitTiming(this.report, SESSION_ID, turn, turnStart, sendStart);
+
+    return true;
+  }
+
+  /** Handle a degenerate stream: a bounded recovery or a terminal stop. Returns a
+   *  stop result, "retry" to continue with a forced tool, or null if not degenerate. */
+  private degenerationStop(
+    res: IModelResponse,
+    degenerations: number,
+    turn: number,
+    turnStart: number,
+    sendStart: number
+  ): ISendResult | "retry" | null {
+    if (res.degenerated !== true) {
+      return null;
+    }
+
+    const stop = this.degenerationRecovery(degenerations, turn);
+
+    emitTiming(this.report, SESSION_ID, turn, turnStart, sendStart);
+
+    return stop ?? "retry";
+  }
+
+  private async driveInner(
+    maxTurns: number,
+    sendStart: number,
+    opts: ISendOptions
   ): Promise<ISendResult> {
     const { ctx, report } = this;
     // The gate confirms CHANGES, not answers: it fires only once the model has
@@ -1439,24 +1565,34 @@ export class Session {
 
       forceTool = false;
 
-      // The stream caught a degenerate repetition loop. Try a BOUNDED recovery
-      // (force a concrete tool call next turn — can't loop in prose) before
-      // giving up; see degenerationRecovery.
-      if (res.degenerated === true) {
-        const stop = this.degenerationRecovery(degenerations, turn);
-
-        emitTiming(report, SESSION_ID, turn, turnStart, sendStart);
+      // A learned/built-in TTSR rule fired mid-stream — inject its corrective
+      // guidance and retry (checked before degeneration so the fix lands first).
+      // This is how memory's failure→fix lessons reach an interactive session.
+      if (this.handleTtsrFired(res, turn, turnStart, sendStart)) {
+        continue;
+      }
 
-        if (stop !== null) {
-          return stop;
-        }
+      // The stream caught a degenerate repetition loop. Bounded recovery (force a
+      // concrete tool call next turn) before giving up; see degenerationRecovery.
+      const deg = this.degenerationStop(
+        res,
+        degenerations,
+        turn,
+        turnStart,
+        sendStart
+      );
 
+      if (deg === "retry") {
         degenerations += 1;
         forceTool = true;
 
         continue;
       }
 
+      if (deg !== null) {
+        return deg;
+      }
+
       // FORCED-TOOLS: a lone yield_status call becomes a normal stop.
       this.resolveYieldCalls(res);
 

package/src/loop/ttsr-init.ts

@@ -0,0 +1,111 @@
+import { join } from "node:path";
+
+import type { Reporter } from "./loop.types";
+import type { ILoopState } from "./turn";
+import type { IChatMessage } from "../inference";
+import { flags } from "../config";
+import { TtsrManager, parseProjectRules, type ITtsrRule } from "./ttsr";
+import { DEFAULT_TTSR_RULES } from "./ttsr-defaults";
+
+const TTSR_INTERRUPT_CAP = 3;
+
+/**
+ * Load a project's TTSR rules: hand-authored `.tsforge/rules.json` AND the
+ * memory-learned `.tsforge/learned-rules.json` (the failure→fix lessons the
+ * harness wrote itself). Both are tolerated-if-missing. Learned rules are named
+ * `learned-*`, so they never collide with hand or built-in rules on dedup.
+ */
+export async function loadProjectTtsrRules(cwd: string): Promise<ITtsrRule[]> {
+  const files = [
+    join(cwd, ".tsforge", "rules.json"),
+    join(cwd, ".tsforge", "learned-rules.json"),
+  ];
+  const rules: ITtsrRule[] = [];
+
+  for (const path of files) {
+    const file = Bun.file(path);
+
+    if (await file.exists()) {
+      rules.push(...parseProjectRules(await file.text()));
+    }
+  }
+
+  return rules;
+}
+
+/**
+ * Build the TTSR manager for a run: built-in defaults + project + learned rules.
+ * Shared by the headless loop (run.ts) and the interactive session (session.ts).
+ * Returns null when TTSR is disabled by flag.
+ */
+export async function initTtsrManager(
+  cwd: string,
+  report: Reporter,
+  taskId: string
+): Promise<TtsrManager | null> {
+  if (!flags.ttsr()) {
+    return null;
+  }
+
+  const manager = new TtsrManager();
+
+  for (const rule of DEFAULT_TTSR_RULES) {
+    manager.addRule(rule);
+  }
+
+  let added = 0;
+
+  for (const rule of await loadProjectTtsrRules(cwd)) {
+    if (manager.addRule(rule)) {
+      added += 1;
+    }
+  }
+
+  if (added > 0) {
+    report({
+      kind: "ttsr",
+      task: taskId,
+      message: `loaded ${added} project/learned TTSR rule(s) from .tsforge/`,
+    });
+  }
+
+  return manager;
+}
+
+/**
+ * Apply a TTSR interrupt: count it, report it, inject the corrective guidance as
+ * a user message, and disable the manager once the per-run cap is hit (so a
+ * stubborn pattern can't loop forever). Shared by both loops; the caller decides
+ * what to do next (retry the turn). Timing emission stays with the caller.
+ */
+export function applyTtsrInterrupt(
+  ttsrFired: { ruleName: string; guidance: string },
+  state: ILoopState,
+  messages: IChatMessage[],
+  report: Reporter,
+  taskId: string,
+  ttsrManager: TtsrManager | null
+): void {
+  state.ttsrInterrupts += 1;
+
+  report({
+    kind: "ttsr",
+    task: taskId,
+    message: `⚠ TTSR interrupted: ${ttsrFired.ruleName}`,
+  });
+
+  if (state.ttsrInterrupts >= TTSR_INTERRUPT_CAP) {
+    report({
+      kind: "tool",
+      task: taskId,
+      message: `TTSR disabled after ${state.ttsrInterrupts} interrupts (hit cap)`,
+    });
+
+    ttsrManager?.disable();
+  }
+
+  messages.push({
+    role: "user",
+    content: `⚠ generation interrupted: ${ttsrFired.guidance} Rewrite the affected part without that pattern.`,
+  });
+}