@tech-leads-club/harness-toolkit 0.2.1

package/src/core/supply-chain/supply-chain.catalog.ts

@@ -0,0 +1,51 @@
+/**
+ * A dependency manifest, its lockfile, and how a version is written in it.
+ *
+ * why: one table, the way the comment gate keeps one table of comment delimiters. A manifest is recognised by
+ * filename and nothing else, so adding an ecosystem is a row rather than a parser
+ * ([/decisions/ad-075.md](/decisions/ad-075.md)).
+ *
+ * invariant: a filename absent from here produces no findings and is reported as unknown. Guessing that a file
+ * called `deps.txt` pins versions the way `requirements.txt` does is how a checker starts refusing honest work.
+ */
+export type ManifestEntry = {
+  manifest: string;
+  /** Null when the ecosystem has no separate lockfile, so `unlocked` cannot apply. */
+  lockfile: string | null;
+  /**
+   * How a dependency line reads. `json-object` is `"name": "spec"`; `requirement` is `name==spec` or `name>=spec`
+   * on its own line; `toml-table` is `name = "spec"`; `directive` is `require name spec`.
+   */
+  shape: "json-object" | "requirement" | "toml-table" | "directive";
+};
+
+/**
+ * hazard: PHP is absent, and not for a technical reason. Its manifest filename contains a word this project's
+ * boundary check forbids anywhere under `src/core` because it is also a provider's agent name
+ * ([/decisions/ad-004.md](/decisions/ad-004.md)). The architecture rule is worth more than one row, so the row
+ * goes and the reason is stated rather than a suppression invented
+ * ([/decisions/ad-075.md](/decisions/ad-075.md)).
+ */
+export const MANIFESTS: readonly ManifestEntry[] = [
+  { manifest: "package.json", lockfile: "package-lock.json", shape: "json-object" },
+  { manifest: "requirements.txt", lockfile: null, shape: "requirement" },
+  { manifest: "pyproject.toml", lockfile: "poetry.lock", shape: "toml-table" },
+  { manifest: "Cargo.toml", lockfile: "Cargo.lock", shape: "toml-table" },
+  { manifest: "go.mod", lockfile: "go.sum", shape: "directive" },
+  { manifest: "Gemfile", lockfile: "Gemfile.lock", shape: "directive" },
+];
+
+export function manifestFor(relativePath: string): ManifestEntry | null {
+  const name = relativePath.split(/[\\/]/).pop() ?? relativePath;
+  return MANIFESTS.find((entry) => entry.manifest === name) ?? null;
+}
+
+/** why: the alternative lockfiles an ecosystem accepts. A project using pnpm has locked just as firmly as one using npm. */
+export const ALTERNATE_LOCKFILES: Readonly<Record<string, readonly string[]>> = {
+  "package.json": ["package-lock.json", "pnpm-lock.yaml", "yarn.lock", "npm-shrinkwrap.json", "bun.lockb"],
+  "pyproject.toml": ["poetry.lock", "pdm.lock", "uv.lock"],
+};
+
+export function lockfilesFor(entry: ManifestEntry): readonly string[] {
+  return ALTERNATE_LOCKFILES[entry.manifest] ?? (entry.lockfile === null ? [] : [entry.lockfile]);
+}

package/src/core/supply-chain/supply-chain.service.ts

@@ -0,0 +1,217 @@
+import type { AddedLine } from "../../platform/git.ts";
+import { lockfilesFor, type ManifestEntry, manifestFor } from "./supply-chain.catalog.ts";
+
+/** why: the stop asks this before reading any diff, so a turn that touched no manifest costs nothing. */
+export function isManifest(relativePath: string): boolean {
+  return manifestFor(relativePath) !== null;
+}
+
+/**
+ * What a turn did to the dependency graph.
+ *
+ * why: a dependency added in a turn is code that runs on every later turn, in CI, and on every machine that
+ * installs the project — and it arrives with none of the review the turn's own diff gets. Two mechanical failures
+ * are worth a finding; a new dependency as such is not, because a rail that fires on ordinary work is a rail the
+ * operator switches off ([/decisions/ad-075.md](/decisions/ad-075.md)).
+ */
+export type SupplyFinding = {
+  kind: "unlocked" | "unpinned";
+  file: string;
+  line: number;
+  detail: string;
+};
+
+/** invariant: a specifier that names no version. A range is pinned enough — the lockfile decides the bytes. */
+const UNPINNED_SPECS = new Set(["latest", "*", "x", "X", "", "main", "master", "HEAD"]);
+
+/**
+ * why: shape-driven rather than parsed. Reading `"name": "spec"` out of an added line needs no JSON parser and
+ * survives a diff that shows one line of a larger object — which is the only form a diff ever shows.
+ */
+export function dependencyOf(
+  text: string,
+  shape: ManifestEntry["shape"],
+): { name: string; spec: string } | null {
+  const line = text.trim().replace(/,$/, "");
+  switch (shape) {
+    case "json-object": {
+      const match = /^"([^"]+)"\s*:\s*"([^"]*)"$/.exec(line);
+      return match ? { name: match[1] as string, spec: match[2] as string } : null;
+    }
+    case "toml-table": {
+      const match = /^([A-Za-z0-9._-]+)\s*=\s*"([^"]*)"$/.exec(line);
+      return match ? { name: match[1] as string, spec: match[2] as string } : null;
+    }
+    case "requirement": {
+      if (line === "" || line.startsWith("#") || line.startsWith("-")) {
+        return null;
+      }
+      const match = /^([A-Za-z0-9._-]+)\s*(?:\[[^\]]*\])?\s*(?:[=<>~!]=?\s*(.+))?$/.exec(line);
+      return match ? { name: match[1] as string, spec: (match[2] ?? "").trim() } : null;
+    }
+    default: {
+      // `require github.com/x/y v1.2.3`, `gem "rails", "7.0"`
+      const match = /^(?:require|gem)\s+["']?([^"'\s]+)["']?(?:\s*,?\s*["']?([^"'\s]+)["']?)?$/.exec(line);
+      return match ? { name: match[1] as string, spec: (match[2] ?? "").trim() } : null;
+    }
+  }
+}
+
+export function isUnpinned(spec: string): boolean {
+  const trimmed = spec.trim();
+  if (UNPINNED_SPECS.has(trimmed)) {
+    return true;
+  }
+  // invariant: a range is pinned enough, because the lockfile decides the bytes. `^1.2.3` and `~2.0` pass; a bare
+  // `>=1` does not, because nothing bounds it above.
+  return /^>=?\s*[\d.]+$/.test(trimmed);
+}
+
+export type SupplyInput = {
+  /** Every path the turn changed, so a lockfile that moved is visible without reading it. */
+  changedFiles: readonly string[];
+  /** The lines the turn added, in the manifests among those paths. */
+  added: readonly AddedLine[];
+  /**
+   * The manifest as it stands, or null when it cannot be read.
+   *
+   * hazard: a diff shows one line, so the line alone cannot say which object it sits in. Calibrated against this
+   * repository's history, the textual shape read `"name": "harness-toolkit"` from a rename commit as a dependency
+   * — and would read every `scripts` entry the same way. The declared names are the only way to tell a dependency
+   * from metadata ([/decisions/ad-075.md](/decisions/ad-075.md)).
+   */
+  readManifest?: (relativePath: string) => string | null;
+};
+
+const DEPENDENCY_SECTIONS = [
+  "dependencies",
+  "devDependencies",
+  "peerDependencies",
+  "optionalDependencies",
+  "require",
+  "require-dev",
+] as const;
+
+/**
+ * why: parsed, not pattern-matched. A JSON manifest is JSON, and the question "is this key a dependency" has an
+ * exact answer that a regex over one diff line cannot reach.
+ */
+export function declaredDependencies(manifestText: string | null): Set<string> | null {
+  if (manifestText === null) {
+    return null;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(manifestText);
+  } catch {
+    return null;
+  }
+  if (parsed === null || typeof parsed !== "object") {
+    return null;
+  }
+  const names = new Set<string>();
+  const record = parsed as Record<string, unknown>;
+  for (const section of DEPENDENCY_SECTIONS) {
+    const block = record[section];
+    if (block !== null && typeof block === "object" && !Array.isArray(block)) {
+      for (const name of Object.keys(block)) {
+        names.add(name);
+      }
+    }
+  }
+  return names;
+}
+
+export type SupplyOutcome = { findings: SupplyFinding[]; unknownManifests: string[] };
+
+export function inspectSupplyChain(input: SupplyInput): SupplyOutcome {
+  const findings: SupplyFinding[] = [];
+  const changed = new Set(input.changedFiles.map((path) => path.split(/[\\/]/).pop() ?? path));
+  const manifestsTouched = new Map<string, ManifestEntry>();
+
+  for (const path of input.changedFiles) {
+    const entry = manifestFor(path);
+    if (entry !== null) {
+      manifestsTouched.set(path, entry);
+    }
+  }
+
+  for (const [path, entry] of manifestsTouched) {
+    const addedHere = input.added.filter((line) => line.file === path);
+    // invariant: for a JSON manifest the declared names decide. An unreadable manifest yields no findings rather
+    // than guessing, which is the conservative direction — a missed dependency is quieter than a refused rename.
+    const declared =
+      entry.shape === "json-object" ? declaredDependencies(input.readManifest?.(path) ?? null) : null;
+    const dependencies = addedHere
+      .map((line) => ({ line, dependency: dependencyOf(line.text, entry.shape) }))
+      .filter((row): row is { line: AddedLine; dependency: { name: string; spec: string } } => {
+        if (row.dependency === null) {
+          return false;
+        }
+        if (entry.shape !== "json-object") {
+          return true;
+        }
+        return declared?.has(row.dependency.name) === true;
+      });
+
+    // invariant: no added dependency means nothing to answer for. A manifest whose version bumped, or whose
+    // scripts changed, has not touched the dependency graph.
+    if (dependencies.length === 0) {
+      continue;
+    }
+
+    const locks = lockfilesFor(entry);
+    if (locks.length > 0 && !locks.some((lock) => changed.has(lock))) {
+      const head = dependencies[0] as { line: AddedLine };
+      findings.push({
+        kind: "unlocked",
+        file: path,
+        line: head.line.line,
+        detail: `${path} gained a dependency and none of ${locks.join(", ")} moved, so what installs is decided at install time`,
+      });
+    }
+
+    for (const { line, dependency } of dependencies) {
+      if (isUnpinned(dependency.spec)) {
+        findings.push({
+          kind: "unpinned",
+          file: path,
+          line: line.line,
+          detail: `${dependency.name} is specified as \`${dependency.spec || "(no version)"}\`, so tomorrow's bytes are not today's`,
+        });
+      }
+    }
+  }
+
+  const unknownManifests = input.changedFiles
+    .filter((path) => {
+      const name = path.split(/[\\/]/).pop() ?? path;
+      return /^(?:.*\.)?(?:lock|manifest)$/.test(name) && manifestFor(path) === null;
+    })
+    .sort();
+
+  return { findings, unknownManifests };
+}
+
+export function supplyChainMessage(findings: readonly SupplyFinding[]): string {
+  const unlocked = findings.filter((finding) => finding.kind === "unlocked");
+  const unpinned = findings.filter((finding) => finding.kind === "unpinned");
+  return [
+    `BLOCKED: this turn changed the dependency graph in ${findings.length} way(s) that outlive it.`,
+    "TRIED: compared the manifest lines this turn added against the commit it started from, and checked",
+    "whether the paired lockfile moved with them.",
+    ...(unlocked.length > 0
+      ? [
+          "NEED: run the ecosystem's install so the lockfile records what resolves, and commit it with the manifest.",
+        ]
+      : []),
+    ...(unpinned.length > 0
+      ? ["NEED: name a version. `latest` and `*` mean the bytes that arrive tomorrow were never reviewed."]
+      : []),
+    "If a floating specifier is deliberate, say which and why in one line and continue.",
+    "",
+    ...findings
+      .slice(0, 10)
+      .map((finding) => `${finding.file}:${finding.line}  [${finding.kind}]  ${finding.detail}`),
+  ].join("\n");
+}

package/src/core/turn/turn.activity.ts

@@ -0,0 +1,94 @@
+import { readSignalEvents } from "../observability/observability.store.ts";
+import type { ObsEvent } from "../observability/observability.types.ts";
+
+/**
+ * hazard: this set was right and the file it was read from was not. A tool call that succeeds resolves to the
+ * **debug** plane, so `obs.jsonl` — the signal plane — holds none of them. Measured on this repository's own
+ * state: `obs.jsonl` carried 0 `tool.end` and 0 `shell.end`, while `debug.jsonl` carried 322, 1909, and 981
+ * `file.edit`. So the counter read zero for every turn whose work went well, and the rail's central claim — that
+ * it counts what the harness recorded and therefore cannot be talked around — was inverted: nothing could
+ * satisfy it ([/decisions/ad-059.md](/decisions/ad-059.md)).
+ */
+export const TOOL_KINDS = new Set([
+  "tool.start",
+  "tool.end",
+  "tool.fail",
+  "shell.start",
+  "shell.end",
+  "mcp.start",
+  "mcp.end",
+  "file.edit",
+  "file.read",
+]);
+const TURN_START = "prompt.submit";
+
+// why: the signal plane holds the turn boundary and the debug plane holds the work. Neither alone answers
+// "did this turn do anything".
+export const ACTIVITY_PLANES = ["obs.jsonl", "debug.jsonl"] as const;
+
+export type TurnActivity = {
+  toolCalls: number;
+  sawTurnStart: boolean;
+};
+
+function forSession(event: ObsEvent, sessionKey: string): boolean {
+  return event.session_id === sessionKey;
+}
+
+/**
+ * invariant: the window boundary is a timestamp, not a position. `prompt.submit` only ever lands on the signal
+ * plane while the events counted inside the window come from both, and two files cannot share an index.
+ */
+export function activitySince(events: readonly ObsEvent[], sessionKey: string): TurnActivity {
+  const mine = events.filter((event) => forSession(event, sessionKey));
+  let startTs: string | null = null;
+  for (const event of mine) {
+    if (event.kind === TURN_START && (startTs === null || event.ts > startTs)) {
+      startTs = event.ts;
+    }
+  }
+  const boundary = startTs;
+  // hazard: `>` dropped any event sharing the boundary's millisecond, and `toISOString` has exactly that
+  // resolution — two records written back to back land on the same stamp. It surfaced as a test that passed
+  // twice and failed on the third run of the same suite, which is the shape of a race rather than a bug in the
+  // rule. `>=` includes the boundary instant; `prompt.submit` is not a counted kind, so including it costs
+  // nothing.
+  const window = boundary === null ? mine : mine.filter((event) => event.ts >= boundary);
+  return {
+    toolCalls: window.filter((event) => TOOL_KINDS.has(event.kind)).length,
+    sawTurnStart: boundary !== null,
+  };
+}
+
+export function readTurnActivity(root: string, sessionKey: string, limit = 500): TurnActivity {
+  return activitySince(
+    ACTIVITY_PLANES.flatMap((plane) => readSignalEvents(root, plane, limit)),
+    sessionKey,
+  );
+}
+
+export type IdleTurnInput = {
+  activity: TurnActivity;
+  changedFiles: number;
+  hasOpenWork: boolean;
+};
+
+export function endedWithoutActing(input: IdleTurnInput): boolean {
+  if (!input.hasOpenWork) {
+    return false;
+  }
+  if (!input.activity.sawTurnStart) {
+    return false;
+  }
+  return input.activity.toolCalls === 0 && input.changedFiles === 0;
+}
+
+export function idleTurnMessage(): string {
+  return [
+    "BLOCKED: this turn ended with open work, no tool call, and no file change.",
+    "TRIED: counted tool events since the last prompt in this session — nothing ran.",
+    "NEED: attempt the work. If a decision is genuinely blocking, state the assumption you are",
+    "proceeding under in one line and continue; escalate only for an irreversible action, a real",
+    "dead-end after searching, or ambiguity that would make the result useless if guessed wrong.",
+  ].join("\n");
+}

package/src/core/turn/turn.autopilot.ts

@@ -0,0 +1,131 @@
+import type { FailureCategory } from "../gate/gate.types.ts";
+import type { OperatorMode } from "../policy/policy.types.ts";
+import { suggestionFor } from "./turn.failure-signals.ts";
+
+export type AutopilotPlan = {
+  next_action: string;
+  steps: string[];
+};
+
+// hazard: this line used to read `Focus files: <changed files>` under a category whose plan says "fix each
+// item explicitly". The changed files come from the diff, so under a failure they had nothing to do with, the
+// plan pointed an agent at innocent code — measured naming a file no test imports while the gate output named
+// the three real ones. Only evidence may read as an instruction; the diff has to say what it is.
+function fileLine(failing: string[] | undefined, changed: string[] | undefined): string | null {
+  if (failing && failing.length > 0) {
+    return `Failing files (named by the gate output): ${failing.slice(0, 8).join(", ")}.`;
+  }
+  if (changed && changed.length > 0) {
+    return `Files the gate ran (from the diff, not necessarily the cause): ${changed.slice(0, 8).join(", ")}.`;
+  }
+  return null;
+}
+
+/**
+ * invariant: these render only from the default branch below, which is reached after a gate has already failed —
+ * late in the work by construction. That makes this the one place where the deadline for a question is a fact
+ * rather than a guess, so every posture states the same settle-and-state form and none invites a question about
+ * ambiguity. Asking at this point is measurably worse than deciding
+ * ([/decisions/ad-026.md](/decisions/ad-026.md)).
+ *
+ * `paired` keeps its check-in, because that one is about an action it is *about to take*, not about ambiguity
+ * it should have raised earlier.
+ */
+const POSTURE_STEP: Record<OperatorMode, string> = {
+  paired:
+    "Fix the reported issue with tool-backed evidence, showing your reasoning, and check in before any sizable non-destructive move. The work is already under way, so settle any remaining ambiguity yourself and state the assumption.",
+  solo: "Fix the reported issue with tool-backed evidence; do not invent success. The work is already under way, so settle remaining ambiguity by taking the most reasonable reading and stating the assumption; escalate only an irreversible action or a real dead-end.",
+  focus:
+    "Keep going until the gates pass. Settle ambiguity yourself and state the assumption; escalate only for an irreversible action or a real dead-end, with BLOCKED / TRIED / NEED.",
+};
+
+export function resolveAutopilot(args: {
+  category: FailureCategory;
+  gate: string;
+  mode: OperatorMode;
+  loopCount: number;
+  maxLoops: number;
+  /** Files the gate output itself named — evidence of where the failure is. */
+  failingFiles?: string[];
+  /** Files the gate ran against, from the diff. Context, never a culprit. */
+  changedFiles?: string[];
+}): AutopilotPlan {
+  const filesHint = fileLine(args.failingFiles, args.changedFiles);
+  const base = suggestionFor(args.category, args.gate);
+
+  switch (args.category) {
+    case "verification":
+      return {
+        next_action: base,
+        steps: [
+          `Do not claim done. Gate ${args.gate} is still failing (loop ${args.loopCount + 1}/${args.maxLoops}).`,
+          "Read the PREVIOUS_GAPS list and fix each item explicitly.",
+          "Do not add suppressions, delete tests, or weaken the gate.",
+          filesHint ?? "Re-run only against the changed files the gate used.",
+          "After edits, continue — the stop hook will re-check.",
+        ].filter(Boolean) as string[],
+      };
+    case "stagnation":
+      return {
+        next_action: base,
+        steps: [
+          "STOP repeating the same edit/command pattern.",
+          "Diagnose root cause with a different tool or smaller repro.",
+          "If still blocked after one new approach, emit BLOCKED / TRIED / NEED to the owner.",
+        ],
+      };
+    case "ship-evidence":
+      return {
+        next_action: base,
+        steps: [
+          "Do not claim shipped/done yet.",
+          args.gate === "empty-diff"
+            ? "Either implement the missing work (produce a real diff) or explain why zero changes is correct."
+            : "Produce production evidence and cite 90-verdict.txt before claiming done.",
+          "Then continue — ship gate will re-check on the next stop.",
+        ],
+      };
+    case "budget":
+      return {
+        next_action: base,
+        steps: [
+          "Do not summarize or wrap up.",
+          "Prefer tool calls that advance unfinished handoff work.",
+          "Address PREVIOUS_GAPS if present before anything else.",
+        ],
+      };
+    case "policy":
+      return {
+        next_action: base,
+        steps: [
+          "Change approach to comply with policy (model allowlist, shell stall, explore read-only).",
+          "Do not retry the denied action with the same arguments.",
+        ],
+      };
+    case "config":
+      return {
+        next_action: base,
+        steps: ["Run harness doctor.", "Fix .tlc/harness/config.json commands/paths.", "Retry the task."],
+      };
+    default:
+      return {
+        next_action: base,
+        steps: [
+          // why: the step states the active posture's interruption threshold, which is what posture governs.
+          // It says nothing about gates — those do not vary by posture.
+          POSTURE_STEP[args.mode],
+          filesHint,
+        ].filter(Boolean) as string[],
+      };
+  }
+}
+
+export function formatAutopilotBlock(plan: AutopilotPlan): string {
+  const lines = plan.steps.map((step, i) => `${i + 1}. ${step}`);
+  return [
+    "AUTOPILOT (runtime-decided — execute in order; do not invent a different plan):",
+    ...lines,
+    "",
+    `NEXT_ACTION: ${plan.next_action}`,
+  ].join("\n");
+}

package/src/core/turn/turn.failure-signals.ts

@@ -0,0 +1,193 @@
+import type { FailureCategory, GateGap } from "../gate/gate.types.ts";
+
+export function classifyGateFailure(gate: string): FailureCategory {
+  if (gate === "lint" || gate === "test" || gate === "comments") {
+    return "verification";
+  }
+  if (gate === "ship" || gate === "empty-diff") {
+    return "ship-evidence";
+  }
+  if (gate === "stagnation") {
+    return "stagnation";
+  }
+  if (gate === "budget") {
+    return "budget";
+  }
+  if (gate === "policy" || gate === "shell-stall") {
+    return "policy";
+  }
+  return "agent-quality";
+}
+
+export function suggestionFor(category: FailureCategory, gate: string): string {
+  switch (category) {
+    case "verification":
+      return `Fix the ${gate} findings without suppressions or deleted tests; re-run until the gate passes.`;
+    case "stagnation":
+      return "Change approach — do not repeat the same failing edit. Inspect root cause or escalate with BLOCKED/TRIED/NEED.";
+    case "ship-evidence":
+      return "Produce real evidence (or make a real diff) before claiming done/shipped.";
+    case "policy":
+      return "Respect harness policy (models, shell, explore read-only). Adjust config only if the owner asked.";
+    case "budget":
+      return "Keep working on the task — do not summarize or end the turn early.";
+    case "config":
+      return "Check .tlc/harness/config.json commands/paths; run harness doctor.";
+    default:
+      return "Fix the reported issue and continue; do not invent success.";
+  }
+}
+
+export function buildGaps(args: {
+  gate: string;
+  output: string;
+  category: FailureCategory;
+  max?: number;
+}): GateGap[] {
+  const max = args.max ?? 8;
+  const lines = args.output
+    .split("\n")
+    .map((l) => l.trim())
+    .filter((l) => l.length > 0 && !l.startsWith(">"));
+  const picked = lines.slice(-max);
+  if (picked.length === 0) {
+    return [
+      {
+        id: `${args.gate}-0`,
+        gate: args.gate,
+        category: args.category,
+        summary: `${args.gate} failed`,
+      },
+    ];
+  }
+  return picked.map((line, index) => ({
+    id: `${args.gate}-${index}`,
+    gate: args.gate,
+    category: args.category,
+    summary: line.slice(0, 200),
+    detail: line.length > 200 ? line.slice(0, 500) : undefined,
+  }));
+}
+
+export function formatGapFeedback(gaps: GateGap[], suggestion: string): string {
+  const body = gaps.map((g, i) => `${i + 1}. [${g.gate}/${g.category}] ${g.summary}`).join("\n");
+  return ["PREVIOUS_GAPS (fix these explicitly — do not ignore):", body, "", `NEXT: ${suggestion}`].join(
+    "\n",
+  );
+}
+
+export const CARRIED_GAP_LIMIT = 5;
+
+/**
+ * why: `intelligence.progressiveHandoff` promised to carry gaps into the next session bootstrap, and nothing read
+ * the flag. `stop` wrote `previous_gaps` onto the handoff and `session.start` read `blockers` and `next_action`
+ * back out but never the gaps, so a resumed session started blind to the gate that was failing when the previous
+ * one ended — the one thing the handoff existed to carry.
+ *
+ * invariant: past tense, and named as the state the previous session ended in rather than as a list to fix now.
+ * The gate may already pass; only the next run of it says so, and the same list phrased as an order would send
+ * the turn to edit code on the strength of a stale verdict ([/decisions/ad-028.md](/decisions/ad-028.md)).
+ */
+export function formatCarriedGaps(gaps: readonly GateGap[], limit = CARRIED_GAP_LIMIT): string {
+  if (gaps.length === 0) {
+    return "";
+  }
+  const shown = gaps.slice(0, limit);
+  const lines = [
+    "Gaps open when the previous session ended (history, not a task list — run the gate to see what still holds):",
+    ...shown.map((gap, index) => `${index + 1}. [${gap.gate}/${gap.category}] ${gap.summary}`),
+  ];
+  const dropped = gaps.length - shown.length;
+  if (dropped > 0) {
+    lines.push(`(${dropped} more not shown — \`tlc harness handoff\` lists all of them.)`);
+  }
+  return lines.join("\n");
+}
+
+export function mergeGaps(prior: GateGap[] | undefined, current: GateGap[], max = 12): GateGap[] {
+  const seen = new Set<string>();
+  const out: GateGap[] = [];
+  for (const gap of [...(prior ?? []), ...current]) {
+    const key = `${gap.gate}|${gap.summary}`;
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    out.push(gap);
+    if (out.length >= max) {
+      break;
+    }
+  }
+  return out;
+}
+
+/**
+ * why: the note appears from the second attempt, never the first. A project-scoping variable is set on every hook
+ * invocation under some providers, so mentioning it on every failure would be an alarm that fires on a healthy
+ * run — which is what [/decisions/ad-034.md](/decisions/ad-034.md) removed from the update digest. By the second
+ * attempt the cheap explanations are spent, and "perhaps it is not your code" has earned its space: this cost four
+ * stop loops of editing code that was not broken ([/decisions/ad-060.md](/decisions/ad-060.md)).
+ *
+ * invariant: it states the fact and the command that settles it. It never claims the variable caused the failure,
+ * because nothing here can know that.
+ */
+export function formatScopedEnvNote(scopedEnv: readonly string[], command: readonly string[]): string {
+  if (scopedEnv.length === 0) {
+    return "";
+  }
+  return [
+    `NOTE: this gate ran with ${scopedEnv.join(", ")} set by the hook.`,
+    "  A suite that builds fixtures in temporary directories reads the real project under those, so a failure",
+    "  here can be the environment rather than the code. Confirm outside the hook before editing:",
+    `    ${command.join(" ")}`,
+    "  If it passes there, the gate command is the thing to change — and only the operator can change it.",
+  ].join("\n");
+}
+
+export function formatProgressiveContext(args: {
+  loopCount: number;
+  maxLoops: number;
+  gate: string;
+  category: FailureCategory;
+  gaps: GateGap[];
+  gateOutput: string;
+  suggestion: string;
+  scopedEnv?: readonly string[];
+  command?: readonly string[];
+}): string {
+  const attempt = args.loopCount + 1;
+  const level = args.loopCount <= 0 ? 1 : args.loopCount === 1 ? 2 : 3;
+  const parts: string[] = [
+    `PROGRESSIVE_CONTEXT level=${level} attempt=${attempt}/${args.maxLoops} gate=${args.gate} category=${args.category}`,
+  ];
+
+  if (level >= 2) {
+    parts.push(
+      "PRIOR ATTEMPT FAILED — do not repeat the same fix. The gaps below include earlier failures; address all of them.",
+    );
+  }
+  if (level >= 3) {
+    parts.push(
+      "ESCALATION: two+ stop loops without clearance. Change strategy (different files, smaller patch, or BLOCKED/TRIED/NEED). Do not re-apply the last failing edit.",
+    );
+  }
+  if (level >= 2) {
+    const note = formatScopedEnvNote(args.scopedEnv ?? [], args.command ?? []);
+    if (note) {
+      parts.push("", note);
+    }
+  }
+
+  const gapLimit = level === 1 ? 6 : level === 2 ? 10 : 12;
+  const outputLines = level === 1 ? 40 : level === 2 ? 80 : 120;
+  const trimmedGaps = args.gaps.slice(0, gapLimit);
+  parts.push("", formatGapFeedback(trimmedGaps, args.suggestion));
+
+  const rawLines = args.gateOutput.split("\n");
+  const outputSlice = rawLines.slice(-outputLines).join("\n").trim();
+  if (outputSlice) {
+    parts.push("", `GATE_OUTPUT (truncated for level ${level}):`, outputSlice);
+  }
+
+  return parts.join("\n");
+}