@tech-leads-club/harness-toolkit 0.2.1

package/src/core/gate/gate.types.ts

@@ -0,0 +1,67 @@
+export const GATE_SCHEMA = "harness.gate.v1" as const;
+
+export type GateFinding = {
+  id?: string;
+  summary: string;
+  detail?: string;
+};
+
+export type LastGateArtifact = {
+  schema: typeof GATE_SCHEMA;
+  gate: string;
+  exitCode: number;
+  passed: boolean;
+  command: string[];
+  files: string[];
+  durationMs: number;
+  ts: string;
+  outputTail: string;
+  findings: GateFinding[];
+  /**
+   * The content hash of the command and files this verdict was produced under. Absent on an artifact written
+   * before the field existed, which is why the first run after an upgrade always executes
+   * ([/decisions/ad-045.md](/decisions/ad-045.md)).
+   */
+  inputsHash?: string;
+  /**
+   * Project-scoping environment variables that were set when this gate ran, by name.
+   *
+   * why: recorded always, as a fact rather than an alarm. A gate failing because the hook's environment points
+   * its fixtures at the real repository is indistinguishable, from the follow-up alone, from a gate failing
+   * because the code is wrong — and it cost four stop loops of editing code that was not broken. Absent on an
+   * artifact written before the field existed ([/decisions/ad-060.md](/decisions/ad-060.md)).
+   */
+  scopedEnv?: string[];
+};
+
+export type AppendFilesMode = "auto" | "always" | "never";
+
+export type FailureCategory =
+  | "agent-quality"
+  | "stagnation"
+  | "verification"
+  | "ship-evidence"
+  | "policy"
+  | "config"
+  | "budget";
+
+export type GateGap = {
+  id: string;
+  gate: string;
+  category: FailureCategory;
+  summary: string;
+  detail?: string;
+};
+
+export type LockBody = {
+  provider: string;
+  session: string;
+  pid: number;
+  acquired_at: string;
+  /**
+   * The machine that wrote the lock. A pid only means something on the host that issued it, so liveness is
+   * consulted only when this matches. A body without it — written by an older build — falls back to the age
+   * rule, which is the honest answer when liveness cannot be established.
+   */
+  host?: string;
+};

package/src/core/handoff/handoff.service.ts

@@ -0,0 +1,43 @@
+import { divergedMessage, shouldInject, verifySeal } from "../integrity/state-seal.ts";
+import { handoffPath, patchHandoff, readHandoffFile } from "./handoff.store.ts";
+import type { ForeignSlice, HandoffProviderSlice, HandoffShared } from "./handoff.types.ts";
+
+export type ResolvedHandoff = HandoffShared & HandoffProviderSlice;
+
+/**
+ * Whether the handoff is safe to read aloud to the model.
+ *
+ * why: separate from `readHandoff`, because reading and injecting are different acts. `tlc harness handoff`
+ * displaying a diverged file is how an operator investigates it; a turn being *told* what it says is the moment
+ * worth withholding ([/decisions/ad-078.md](/decisions/ad-078.md)).
+ */
+export function handoffInjectable(root: string): { ok: boolean; note: string | null } {
+  const target = handoffPath(root);
+  const verdict = verifySeal(target);
+  return shouldInject(verdict)
+    ? { ok: true, note: null }
+    : { ok: false, note: divergedMessage(target, "The handoff") };
+}
+
+export function readHandoff(root: string, provider: string): ResolvedHandoff {
+  const file = readHandoffFile(root);
+  const slice = file.by_provider[provider] ?? { updated_at: file.shared.updated_at };
+  return { ...file.shared, ...slice };
+}
+
+export function readForeignSlices(root: string, provider: string): ForeignSlice[] {
+  const file = readHandoffFile(root);
+  const foreign: ForeignSlice[] = [];
+  for (const [name, slice] of Object.entries(file.by_provider)) {
+    if (name === provider) {
+      continue;
+    }
+    if (slice.next_action === undefined && slice.blockers === undefined) {
+      continue;
+    }
+    foreign.push({ provider: name, next_action: slice.next_action, blockers: slice.blockers });
+  }
+  return foreign;
+}
+
+export { patchHandoff, readHandoffFile };

package/src/core/handoff/handoff.store.ts

@@ -0,0 +1,59 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { updateJsonAtomic } from "../../platform/fs-atomic.ts";
+import { projectStateDir } from "../../platform/paths.ts";
+import { seal } from "../integrity/state-seal.ts";
+import {
+  defaultHandoffFile,
+  type HandoffFile,
+  type HandoffProviderSlice,
+  type HandoffShared,
+  isHandoffFile,
+} from "./handoff.types.ts";
+
+export function handoffPath(root: string): string {
+  return join(projectStateDir(root), "handoff.json");
+}
+
+function handoffLockPath(root: string): string {
+  return `${handoffPath(root)}.lock`;
+}
+
+export function readHandoffFile(root: string): HandoffFile {
+  const path = handoffPath(root);
+  if (!existsSync(path)) {
+    return defaultHandoffFile();
+  }
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (isHandoffFile(parsed)) {
+      return parsed;
+    }
+  } catch {}
+  return defaultHandoffFile();
+}
+
+export type HandoffPatch = {
+  shared?: Partial<HandoffShared>;
+  slice?: Partial<HandoffProviderSlice>;
+};
+
+export function patchHandoff(root: string, provider: string, patch: HandoffPatch): Promise<HandoffFile> {
+  return updateJsonAtomic<HandoffFile>(
+    handoffPath(root),
+    (current) => {
+      const base = current && isHandoffFile(current) ? current : defaultHandoffFile();
+      const now = new Date().toISOString();
+      const ownSlice = base.by_provider[provider] ?? { updated_at: now };
+      return {
+        schema: base.schema,
+        shared: { ...base.shared, ...patch.shared, updated_at: now },
+        by_provider: {
+          ...base.by_provider,
+          [provider]: { ...ownSlice, ...patch.slice, updated_at: now },
+        },
+      };
+    },
+    { lockPath: handoffLockPath(root), afterWrite: seal },
+  );
+}

package/src/core/handoff/handoff.types.ts

@@ -0,0 +1,89 @@
+import type { FailureCategory, GateGap } from "../gate/gate.types.ts";
+import type { PendingLessonCredit } from "../lesson/lesson.types.ts";
+import type { PlanDeviation } from "../plan/plan.types.ts";
+import type { OperatorMode } from "../policy/policy.types.ts";
+
+export type GateResult = "pass" | "fail" | "skipped";
+
+export type HandoffShared = {
+  mode: OperatorMode;
+  project_name?: string;
+  git_branch?: string;
+  git_sha?: string;
+  updated_at: string;
+};
+
+export type HandoffProviderSlice = {
+  updated_at: string;
+  session_key?: string;
+  session_narrative?: string;
+  completed?: string[];
+  in_progress?: string[];
+  pending?: string[];
+  last_ship_claim_at?: string;
+  last_ship_claim_snippet?: string;
+  last_ship_claim_kind?: "structured";
+  last_changed_files?: string[];
+  last_stop_status?: string;
+  last_gate_result?: GateResult;
+  last_fingerprint?: string;
+  fingerprint_hits?: number;
+  last_failure_category?: FailureCategory;
+  // why: the lessons injected for a gate are graded by that gate's next run, which happens in a later process.
+  // The handoff is the only state that survives between the two ([/decisions/ad-039.md](/decisions/ad-039.md)).
+  pending_lesson_credit?: PendingLessonCredit;
+  previous_gaps?: GateGap[];
+  /**
+   * why: the revision this turn started at. Every stop-time gate diffs against it rather than against `HEAD`,
+   * because a turn that commits moves `HEAD` past its own changes and each gate then reads an empty diff
+   * ([/decisions/ad-058.md](/decisions/ad-058.md)).
+   */
+  turn_base_sha?: string;
+  plan_paths?: string[];
+  plan_at?: string;
+  plan_snippet?: string;
+  plan_deviations?: PlanDeviation[];
+  next_action?: string;
+  blockers?: string;
+  machine_state?: Record<string, unknown>;
+};
+
+export const HANDOFF_SCHEMA = "harness.handoff.v2" as const;
+
+export type HandoffFile = {
+  schema: typeof HANDOFF_SCHEMA;
+  shared: HandoffShared;
+  by_provider: Record<string, HandoffProviderSlice>;
+};
+
+export type ForeignSlice = {
+  provider: string;
+  plan_paths?: string[];
+  plan_at?: string;
+  plan_snippet?: string;
+  plan_deviations?: PlanDeviation[];
+  next_action?: string;
+  blockers?: string;
+};
+
+export function defaultHandoffFile(mode: OperatorMode = "solo"): HandoffFile {
+  return {
+    schema: HANDOFF_SCHEMA,
+    shared: { mode, updated_at: new Date().toISOString() },
+    by_provider: {},
+  };
+}
+
+export function isHandoffFile(value: unknown): value is HandoffFile {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const candidate = value as Partial<HandoffFile>;
+  return (
+    candidate.schema === HANDOFF_SCHEMA &&
+    typeof candidate.shared === "object" &&
+    candidate.shared !== null &&
+    typeof candidate.by_provider === "object" &&
+    candidate.by_provider !== null
+  );
+}

package/src/core/index.ts

@@ -0,0 +1,52 @@
+export type {
+  CapabilityCatalog,
+  CatalogCapability,
+  RuntimeSeen,
+} from "./capability/capability.types.ts";
+export type { CommentFinding } from "./comment-policy/comment-policy.types.ts";
+export type { CoreFacade } from "./core.facade.ts";
+export { coreFacade } from "./core.facade.ts";
+export type { FloorInput, FloorRule } from "./floor/floor.service.ts";
+export type { FailureCategory, GateFinding, GateGap, LastGateArtifact, LockBody } from "./gate/gate.types.ts";
+export type {
+  ForeignSlice,
+  GateResult,
+  HandoffFile,
+  HandoffProviderSlice,
+  HandoffShared,
+} from "./handoff/handoff.types.ts";
+export type {
+  HarnessLesson,
+  LessonEffectiveness,
+  LessonLink,
+  LessonLinkStatus,
+  LessonSource,
+  LessonStatus,
+  LessonStoreFile,
+  LessonTier,
+  PendingLessonCredit,
+} from "./lesson/lesson.types.ts";
+export type { ProviderTotals } from "./observability/observability.report.ts";
+export type { SessionRollup } from "./observability/observability.store.ts";
+export type {
+  CostPool,
+  CostSource,
+  ObsEvent,
+  ObservabilityConfig,
+  ObsKind,
+  ObsLevel,
+} from "./observability/observability.types.ts";
+export type {
+  LessonsPolicyConfig,
+  OperatorMode,
+  PartialPolicy,
+  Policy,
+  ProviderScoped,
+} from "./policy/policy.types.ts";
+export type { PresenceRecord } from "./presence/presence.types.ts";
+export type { ShellEffectClass } from "./shell-policy/shell-policy.types.ts";
+export type { ShipClaim, ShipClaimKind, ShipLedgerEvent, ShipLedgerRow } from "./ship/ship.types.ts";
+export type { FingerprintEntry, FingerprintStore } from "./stagnation/stagnation.types.ts";
+export type { ModelParam, ParentModelSnapshot } from "./subagent-policy/subagent-policy.types.ts";
+export type { AutopilotPlan } from "./turn/turn.autopilot.ts";
+export type { BootResult, LoopCheck, LoopState } from "./turn/turn.types.ts";

package/src/core/integrity/state-seal.ts

@@ -0,0 +1,81 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+
+/**
+ * A hash the harness records after every write it makes to a file it later reads aloud to the model.
+ *
+ * why: the policy baseline answers "did this change since the session started", which is the right question for a
+ * file only an operator edits. The handoff changes every turn by design, so the question here is different — did
+ * something *other than the harness* change it. One write path per file makes that answerable
+ * ([/decisions/ad-078.md](/decisions/ad-078.md)).
+ *
+ * invariant: this is defence in depth and not the first line. The floor already refuses an agent write to either
+ * file, because both sit under the project state directory. What this catches is a write the floor did not see —
+ * another process, an MCP server with filesystem access, a route through a tool nothing named.
+ */
+export type SealVerdict = "sealed" | "unsealed" | "diverged" | "absent";
+
+const SCHEMA = "harness.seal.v1";
+
+export function sealPath(target: string): string {
+  return join(dirname(target), ".seal", `${basename(target)}.json`);
+}
+
+function hashOf(target: string): string | null {
+  try {
+    return createHash("sha256").update(readFileSync(target)).digest("hex");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * why: called inside the write lock. A seal recorded after the lock releases races the next writer, and the pair
+ * that loses leaves a seal matching neither content.
+ */
+export function seal(target: string): void {
+  const hash = hashOf(target);
+  if (hash === null) {
+    return;
+  }
+  try {
+    mkdirSync(dirname(sealPath(target)), { recursive: true });
+    writeFileSync(sealPath(target), JSON.stringify({ schema: SCHEMA, hash }));
+  } catch {
+    // invariant: a seal that cannot be written is not an error the turn should carry. The next verify reads
+    // `unsealed` and adopts, which is the same state as a fresh install.
+  }
+}
+
+export function verifySeal(target: string): SealVerdict {
+  if (!existsSync(target)) {
+    return "absent";
+  }
+  let recorded: string | null = null;
+  try {
+    const parsed = JSON.parse(readFileSync(sealPath(target), "utf8")) as { hash?: unknown };
+    recorded = typeof parsed.hash === "string" ? parsed.hash : null;
+  } catch {
+    recorded = null;
+  }
+  if (recorded === null) {
+    // why: adopted, not refused. Every install that predates sealing has no sidecar, and refusing on absence
+    // would break all of them. The cost is stated: deleting the sidecar buys one unverified read.
+    return "unsealed";
+  }
+  return hashOf(target) === recorded ? "sealed" : "diverged";
+}
+
+/** why: one place decides what withholding means, so the two call sites cannot disagree about it. */
+export function shouldInject(verdict: SealVerdict): boolean {
+  return verdict !== "diverged";
+}
+
+export function divergedMessage(target: string, what: string): string {
+  return [
+    `${what} at ${target} changed without a harness write behind it, so it was not injected into this turn.`,
+    "That file is read aloud to the model, so text placed in it reaches every later turn. Read it, and if the",
+    "contents are yours, the next harness write reseals it.",
+  ].join("\n");
+}

package/src/core/lesson/lesson.authored.ts

@@ -0,0 +1,96 @@
+import { createHash } from "node:crypto";
+import type { HarnessLesson, LessonLink, LessonTier } from "./lesson.types.ts";
+
+/**
+ * The lesson store had exactly one producer: gate stagnation. So a lesson learned by *reasoning* — a code review, an
+ * incident, an operator's correction, a pattern noticed across several changes — had no way in, while the mechanism
+ * that would have carried it (ranked injection with recurrence decay) already existed and ran every session
+ * ([/decisions/ad-035.md](/decisions/ad-035.md)).
+ *
+ * invariant: this knows nothing about where a lesson came from in the world. No document layout, no decision-record
+ * convention, no directory. The harness ships the mechanism; a project decides what feeds it. Reading a repository's
+ * documentation to harvest lessons would couple every install to one project's filing habits.
+ *
+ * why: `source: "manual"` was already in `LessonSource` and produced by nothing — the union anticipated this route and
+ * it was never built.
+ */
+export type AuthoredLessonInput = {
+  /** The one thing to do differently. This is what gets injected, so it is written as an instruction. */
+  instruction: string;
+  /** What went wrong, in the author's words. Empty is allowed — an instruction alone is still useful. */
+  avoid?: string;
+  prefer?: string;
+  preRetryCheck?: string;
+  /**
+   * The gate this applies to, when it applies to one. Ranking boosts a lesson whose gate matches the failing gate,
+   * and session-mode injection includes every lesson regardless — so a lesson about no particular gate still arrives.
+   */
+  gate?: string;
+  /** Words that should pull this lesson up when they appear in the failure text. */
+  triggerTokens?: string[];
+  /** What makes this lesson true. When any ref breaks, `garden` stops the lesson being injected. */
+  refs?: LessonLink[];
+  /** ISO bound after which this lesson stops being injected. */
+  validTo?: string;
+  tier?: Exclude<LessonTier, "core">;
+  /** A standing rule: injected before every scored lesson rather than competing with them. */
+  pinned?: boolean;
+  /**
+   * True when the command ran inside an agent session. Recorded rather than refused: an agent that cannot write down
+   * what it learned writes nothing down, which is the state this replaces. Marking it is what keeps it auditable.
+   */
+  inAgentSession?: boolean;
+  now?: string;
+};
+
+/** why: a stable id from the instruction, so writing the same lesson twice updates rather than duplicates. */
+export function authoredLessonId(instruction: string): string {
+  const digest = createHash("sha256").update(instruction.trim().toLowerCase()).digest("hex").slice(0, 12);
+  return `manual:${digest}`;
+}
+
+export const AUTHORED_GATE = "any";
+
+export function buildAuthoredLesson(input: AuthoredLessonInput): HarnessLesson {
+  const now = input.now ?? new Date().toISOString();
+  const instruction = input.instruction.trim();
+  return {
+    id: authoredLessonId(instruction),
+    scope: "gate-execution",
+    // why: `any` rather than a real gate name, so a retry for a specific gate is not falsely boosted by a lesson that
+    // was never about it. Session-mode injection carries it anyway.
+    failedGate: input.gate?.trim() || AUTHORED_GATE,
+    category: input.inAgentSession ? "authored-in-session" : "authored",
+    triggerTokens: (input.triggerTokens ?? []).map((token) => token.trim().toLowerCase()).filter(Boolean),
+    instruction,
+    avoid: input.avoid?.trim() ?? "",
+    prefer: input.prefer?.trim() ?? "",
+    preRetryCheck: input.preRetryCheck?.trim() ?? "",
+    source: "manual",
+    tier: input.tier ?? "project",
+    // why: `active`, not `candidate`. A candidate exists because the automatic producer is guessing from output; an
+    // author is not guessing, and making them wait for a promotion threshold that only recurrence can satisfy would
+    // mean an authored lesson never activates.
+    status: "active",
+    confidence: 0.8,
+    hitCount: 1,
+    // hazard: this was `0.8`, written as if priority were the 0..1 scale `confidence` uses. Every other producer
+    // is 70..100 and `relevanceScore` divides by 200, so an authored lesson contributed 0.004 where a core lesson
+    // contributes 0.45 — ranked below everything, always, and never injected under a real char budget.
+    priority: 80,
+    pinned: input.pinned === true,
+    refs: input.refs ?? [],
+    ...(input.validTo ? { validTo: input.validTo } : {}),
+    // why: an authored lesson has no failing session behind it, so it carries none. Promotion reads distinct
+    // sessions and an authored lesson is already active, so it never consults this.
+    sessionKeys: [],
+    injectedCount: 0,
+    gradeableCount: 0,
+    helpedCount: 0,
+    neutralCount: 0,
+    firstSeenAt: now,
+    lastSeenAt: now,
+    lastAccessedAt: now,
+    updatedAt: now,
+  };
+}

package/src/core/lesson/lesson.credit.ts

@@ -0,0 +1,51 @@
+import type { HarnessLesson, LessonEffectiveness } from "./lesson.types.ts";
+
+export type LessonVerdict = "helped" | "neutral";
+
+export function gradedCount(lesson: HarnessLesson): number {
+  return lesson.helpedCount + lesson.neutralCount;
+}
+
+// invariant: a rate over zero graded injections is null, not zero. Zero reads as "measured and it never helped";
+// null is the only honest value for "nothing has tested this yet".
+export function helpRate(lesson: HarnessLesson): number | null {
+  const graded = gradedCount(lesson);
+  return graded === 0 ? null : lesson.helpedCount / graded;
+}
+
+/**
+ * hazard: this read `injectedCount`, which counts session-start injections. Those are never graded — a lesson
+ * whose gate is `any` is not even eligible on a retry — so a healthy pinned standing rule reported `unproven`
+ * forever and `doctor` warned about it on every run, in every repository
+ * ([/decisions/ad-044.md](/decisions/ad-044.md)).
+ */
+export function lessonEffectiveness(lesson: HarnessLesson): LessonEffectiveness {
+  const rate = helpRate(lesson);
+  if (rate === null) {
+    // why: only an injection a gate could have graded can be unproven. Everything else has had no opportunity.
+    return lesson.gradeableCount === 0 ? "not-injected" : "unproven";
+  }
+  return rate > 0 ? "helped" : "neutral";
+}
+
+export function creditLesson(lesson: HarnessLesson, verdict: LessonVerdict, now: string): HarnessLesson {
+  return {
+    ...lesson,
+    helpedCount: lesson.helpedCount + (verdict === "helped" ? 1 : 0),
+    neutralCount: lesson.neutralCount + (verdict === "neutral" ? 1 : 0),
+    updatedAt: now,
+  };
+}
+
+export function effectivenessLine(lesson: HarnessLesson): string {
+  const reading = lessonEffectiveness(lesson);
+  if (reading === "not-injected") {
+    return lesson.injectedCount === 0
+      ? "not-injected"
+      : `session-only (injected ${lesson.injectedCount}x, never for a gate)`;
+  }
+  if (reading === "unproven") {
+    return `unproven (injected for a gate ${lesson.gradeableCount}x, graded 0x)`;
+  }
+  return `${reading} ${lesson.helpedCount}/${gradedCount(lesson)}`;
+}