@tech-leads-club/harness-toolkit 0.2.1

package/src/core/observe/observe.service.ts

@@ -0,0 +1,76 @@
+import type { ObserveConfig } from "../policy/policy.types.ts";
+
+/**
+ * Observation mode answers the one question a firing rate cannot: **was the rule ever needed?**
+ *
+ * A rail that never fires while its prose is injected is either working or unnecessary, and the count alone cannot
+ * separate those. Running the checker with the prose *absent* separates them: if the property holds anyway, the
+ * model was already doing it and the rule is paying for injected context and delivering nothing.
+ *
+ * why: this is possible here and nowhere else, because in this harness the checker and the instruction are
+ * different things. In a prose-based system the rule *is* the mechanism, so there is nothing to hold apart. The
+ * alternative — running a task N times with and without the rule — needs task repetition, and real work does not
+ * repeat ([/decisions/ad-027.md](/decisions/ad-027.md)).
+ *
+ * invariant: observation never returns a Decision and never reaches the turn. A measurement that can change what
+ * it measures is not a measurement.
+ */
+/**
+ * hazard: `observe.rails` accepted any string, and a name with no checker behind it did nothing and said nothing —
+ * the exact defect this project keeps removing, a config value nothing reads. Forward-compatible inertness is fine;
+ * silent inertness is not. This list is the one source of what can actually be observed, read by the classifier,
+ * by `doctor`, and by the capability catalog's own prompt ([/decisions/ad-029.md](/decisions/ad-029.md)).
+ *
+ * invariant: a name enters this list in the same change that adds its `shouldObserve` call site. A name here with
+ * no call site would advertise an observation that never happens, which is the same lie pointed the other way.
+ */
+export const OBSERVABLE_RAILS: readonly string[] = ["comments"];
+
+export function isObservableRail(rail: string): boolean {
+  return OBSERVABLE_RAILS.includes(rail);
+}
+
+/** why: names the rails that were asked for and cannot be delivered, so a surface can report them by name. */
+export function unobservableRails(rails: readonly string[]): string[] {
+  return rails.filter((rail) => !isObservableRail(rail));
+}
+
+export type ObserveVerdict = {
+  rail: string;
+  /** How many times the checker found the property violated. Zero is the interesting case. */
+  violations: number;
+  /**
+   * Whether the rail's prose was in the injected context for this turn. This is the field that makes a record
+   * interpretable: the same zero means "the rule worked" when true and "the rule was unnecessary" when false.
+   */
+  proseInjected: boolean;
+};
+
+/**
+ * invariant: enforcement wins. When a rail is enforcing, its own path already records the outcome, and observing
+ * it as well would double-count — the operator would read twice the interruptions they lived through.
+ */
+export function shouldObserve(config: ObserveConfig, rail: string, enforcing: boolean): boolean {
+  // hazard: this answered yes for a rail with no checker behind it. Nothing called it for such a rail, so nothing
+  // broke — but the function's contract said "observe this" about something unobservable, which is exactly the gap
+  // a future call site would fall into.
+  return config.enabled && !enforcing && isObservableRail(rail) && config.rails.includes(rail);
+}
+
+export function observeAttrs(verdict: ObserveVerdict): Record<string, unknown> {
+  return {
+    rail: verdict.rail,
+    violations: verdict.violations,
+    prose_injected: verdict.proseInjected,
+    // why: the reading, stated rather than left to be inferred from two fields. An operator scanning a log should
+    // not have to reconstruct the logic that makes the number mean something.
+    reading:
+      verdict.violations === 0
+        ? verdict.proseInjected
+          ? "held-with-prose"
+          : "held-without-prose"
+        : verdict.proseInjected
+          ? "violated-with-prose"
+          : "violated-without-prose",
+  };
+}

package/src/core/plan/plan.detect.ts

@@ -0,0 +1,47 @@
+import type { PlanDeclaration, PlanDeviation } from "./plan.types.ts";
+
+const PLAN_LINE = /(?:^|\n)\s*HARNESS_PLAN:\s*(.+?)\s*(?=\n|$)/;
+const DEVIATION_LINE = /(?:^|\n)\s*HARNESS_PLAN_DEVIATION:\s*(.+?)\s*(?=\n|$)/g;
+const REASON_SEPARATOR = /\s+(?:—|--|-)\s+/;
+
+function splitPaths(body: string): string[] {
+  return body
+    .split(/[,\s]+/)
+    .map((path) => path.trim())
+    .filter((path) => path.length > 0);
+}
+
+// why: an empty declaration is malformed, not "nothing is planned". Treating it as an empty plan would make
+// every subsequent file unplanned and block the turn on a typo.
+export function detectPlan(text: string): PlanDeclaration | null {
+  const match = PLAN_LINE.exec(text);
+  const body = match?.[1]?.trim();
+  if (!body) {
+    return null;
+  }
+  const paths = splitPaths(body);
+  if (paths.length === 0) {
+    return null;
+  }
+  return { paths, snippet: `HARNESS_PLAN: ${body}`.slice(0, 280) };
+}
+
+export function detectDeviations(text: string): PlanDeviation[] {
+  const found: PlanDeviation[] = [];
+  for (const match of text.matchAll(DEVIATION_LINE)) {
+    const body = match[1]?.trim();
+    if (!body) {
+      continue;
+    }
+    const [rawPath, ...rest] = body.split(REASON_SEPARATOR);
+    const path = rawPath?.trim();
+    const reason = rest.join(" ").trim();
+    // why: a path with no stated reason is not a justification. Accepting it would turn the gate into a
+    // formality the agent can satisfy by naming the file it already touched.
+    if (!path || reason.length === 0) {
+      continue;
+    }
+    found.push({ path, reason });
+  }
+  return found;
+}

package/src/core/plan/plan.service.ts

@@ -0,0 +1,81 @@
+import type { Decision } from "../../contracts/decision.ts";
+import { pathExcluded } from "../ship/ship.service.ts";
+import type { PlanDeviation, PlanVerdict } from "./plan.types.ts";
+
+export function planActive(declaredAt: string | undefined, windowMinutes: number, now = Date.now()): boolean {
+  if (!declaredAt) {
+    return false;
+  }
+  const at = Date.parse(declaredAt);
+  if (Number.isNaN(at)) {
+    return false;
+  }
+  return now - at < windowMinutes * 60 * 1000;
+}
+
+// why: the matcher is the one shipGate.runtimePathExcludes already accepts, so the operator learns a single
+// pattern syntax rather than one per gate.
+export function unplannedPaths(args: {
+  changedFiles: readonly string[];
+  planned: readonly string[];
+  deviations: readonly PlanDeviation[];
+}): string[] {
+  const justified = args.deviations.map((deviation) => deviation.path);
+  return args.changedFiles.filter((file) => {
+    if (pathExcluded(file, [...args.planned])) {
+      return false;
+    }
+    return !pathExcluded(file, justified);
+  });
+}
+
+export function evaluatePlanGate(args: {
+  enabled: boolean;
+  declaredAt: string | undefined;
+  windowMinutes: number;
+  planned: readonly string[];
+  deviations: readonly PlanDeviation[];
+  changedFiles: readonly string[];
+  now?: number;
+}): Decision {
+  const verdict = planVerdict(args);
+  if (!verdict.active || verdict.unplanned.length === 0) {
+    return { kind: "abstain" };
+  }
+  const listed = verdict.unplanned.slice(0, 10).join(", ");
+  const more = verdict.unplanned.length > 10 ? ` (+${verdict.unplanned.length - 10} more)` : "";
+  return {
+    kind: "continue",
+    text: [
+      `BLOCKED: ${verdict.unplanned.length} changed file(s) are outside the declared plan: ${listed}${more}`,
+      `TRIED: compared the working tree against HARNESS_PLAN (${args.planned.join(", ")}).`,
+      "NEED: either revert what the plan did not call for, or justify each path with a reason —",
+      "HARNESS_PLAN_DEVIATION: <path> — <why this file had to change>",
+    ].join("\n"),
+  };
+}
+
+export function planVerdict(args: {
+  enabled: boolean;
+  declaredAt: string | undefined;
+  windowMinutes: number;
+  planned: readonly string[];
+  deviations: readonly PlanDeviation[];
+  changedFiles: readonly string[];
+  now?: number;
+}): PlanVerdict {
+  if (!args.enabled || args.planned.length === 0) {
+    return { active: false, unplanned: [] };
+  }
+  if (!planActive(args.declaredAt, args.windowMinutes, args.now ?? Date.now())) {
+    return { active: false, unplanned: [] };
+  }
+  return {
+    active: true,
+    unplanned: unplannedPaths({
+      changedFiles: args.changedFiles,
+      planned: args.planned,
+      deviations: args.deviations,
+    }),
+  };
+}

package/src/core/plan/plan.types.ts

@@ -0,0 +1,25 @@
+export type PlanDeclaration = {
+  paths: string[];
+  snippet: string;
+};
+
+export type PlanDeviation = {
+  path: string;
+  reason: string;
+};
+
+export type PlanState = {
+  paths: string[];
+  declaredAt: string;
+  deviations: PlanDeviation[];
+};
+
+export type PlanPolicyConfig = {
+  enabled: boolean;
+  windowMinutes: number;
+};
+
+export type PlanVerdict = {
+  active: boolean;
+  unplanned: string[];
+};

package/src/core/policy/policy.defaults.ts

@@ -0,0 +1,103 @@
+import { MIN_RUN } from "../duplication/duplication.service.ts";
+import { DEFAULT_OBS } from "../observability/observability.types.ts";
+import type { Policy } from "./policy.types.ts";
+
+export const DEFAULT_LESSONS_POLICY: Policy["intelligence"]["lessons"] = {
+  enabled: false,
+  maxInjectSession: 5,
+  maxInjectRetry: 8,
+  maxCharsSession: 900,
+  maxCharsRetry: 1400,
+  promoteHitCount: 2,
+  decayLambda: 0.02,
+  projectBoost: 1.5,
+  syncRulesFile: "auto",
+  gardenOnSessionEnd: true,
+};
+
+export const DEFAULTS: Policy = {
+  version: 1,
+  mode: "solo",
+  codePaths: ["src", "apps", "libs", "packages"],
+  grind: {
+    enabled: false,
+    maxLoops: 5,
+    lintCommand: null,
+    testCommand: null,
+    appendFiles: "auto",
+  },
+  shipGate: {
+    enabled: false,
+    runtimePathPrefixes: ["src", "apps", "libs", "packages", "deploy", "scripts"],
+    runtimePathExcludes: [".tlc/", "**/node_modules/", "**/.git/"],
+    evidenceDir: null,
+    evidenceMaxAgeHours: 48,
+    emptyDiffAntiShip: false,
+    claimWindowMinutes: 10,
+  },
+  subagents: {
+    enforceAllowlist: false,
+    requireModel: false,
+    allowedModels: [],
+    blockedPatterns: ["-fast(?:$|[^a-z0-9])", "/fast(?:$|[^a-z0-9])"],
+    minEffort: null,
+    blockParentFast: false,
+    blockMode: "deny",
+    readOnlyTypes: ["explore"],
+  },
+  docs: {
+    command: null,
+    severity: "warn",
+  },
+  observe: {
+    enabled: false,
+    rails: [],
+  },
+  comments: {
+    enabled: false,
+    onViolation: "followup",
+    mode: "declared",
+  },
+  supplyChain: {
+    enabled: false,
+  },
+  duplication: {
+    enabled: false,
+    minRun: MIN_RUN,
+  },
+  obs: {
+    globalSpool: false,
+    includePayloads: DEFAULT_OBS.includePayloads,
+    maxAttrChars: DEFAULT_OBS.maxAttrChars,
+    sessionCostAlertUsd: DEFAULT_OBS.sessionCostAlertUsd,
+    retentionDays: DEFAULT_OBS.retentionDays,
+  },
+  untrustedContent: {
+    mode: "frame",
+    enabled: false,
+    extraTools: [],
+    extraCommandPatterns: [],
+  },
+  planGate: {
+    enabled: false,
+    windowMinutes: 120,
+  },
+  shell: {
+    catastrophicAsk: true,
+    stallDetection: false,
+    stallRepeatThreshold: 3,
+  },
+  intelligence: {
+    gapFeedback: true,
+    failureClassification: true,
+    progressiveHandoff: true,
+    progressiveContext: true,
+    autopilot: true,
+    idleTurnGate: false,
+    budgetContinue: false,
+    budgetContinueAfterLoops: 3,
+    lessons: { ...DEFAULT_LESSONS_POLICY },
+  },
+  mcpPrime: [],
+  bootstrapExtra: [],
+};

package/src/core/policy/policy.guard.ts

@@ -0,0 +1,34 @@
+import type { Decision } from "../../contracts/decision.ts";
+import { isPolicySurface } from "../floor/floor.paths.ts";
+
+export { isPolicySurface };
+
+const WRITE_TOOLS = new Set(["Edit", "Write", "Delete", "MultiEdit", "NotebookEdit"]);
+
+export function guardPolicySurface(args: {
+  projectDir: string;
+  toolName: string | undefined;
+  filePath: string | undefined;
+}): Decision {
+  if (!args.toolName || !WRITE_TOOLS.has(args.toolName) || !args.filePath) {
+    return { kind: "allow" };
+  }
+  if (!isPolicySurface(args.projectDir, args.filePath)) {
+    return { kind: "allow" };
+  }
+  // hazard: this used to answer "change policy through the CLI instead", naming the very subcommands the floor
+  // refuses from inside a session. Measured: the agent read it as a route, ran `tlc harness mode`, and was denied
+  // again — a suggestion that costs a turn and teaches nothing. The CLI is the operator's route, not the reader's.
+  return {
+    kind: "deny",
+    reason: [
+      "Harness policy and state are not agent-writable — a gate an agent can switch off is not a gate.",
+      "The harness CLI does not help you here either: the same floor rule refuses the mutating subcommands from inside a session.",
+      "Tell the operator which value you would change and why, and let them run it from their own terminal.",
+    ].join(" "),
+    userNote: `Blocked an agent write to ${args.filePath}.`,
+    // why: the shell route to the same paths denies with `rule=policy-surface-write` and this one carried no rule
+    // at all, so the tool half of one guard was unattributable in the report that counts refusals by rule.
+    rule: "policy-surface-write",
+  };
+}

package/src/core/policy/policy.integrity.ts

@@ -0,0 +1,238 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { Decision } from "../../contracts/decision.ts";
+import {
+  flagsDir,
+  policyBaselineDir,
+  projectConfigPath,
+  projectStateDir,
+  runtimeHome,
+} from "../../platform/paths.ts";
+import { sanitizeSegment } from "../../platform/sanitize.ts";
+
+export type PolicySource = { path: string; hash: string };
+
+const ABSENT = "absent";
+const SCHEMA = "harness.policy-baseline.v1";
+
+// why: every file `loadPolicy` consults. A mutation that changed the effective policy without touching one
+// of these would be a change the loader cannot see either.
+const MODE_FILE = "harness-mode";
+// why: every file the loader consults. The posture flags carry the posture names, so renaming a posture
+// renames its flag — a stale file from the old spelling decides nothing and is not hashed.
+const FLAG_FILES = ["grind-on", "skip-verify", "focus", "paired"];
+
+function hashOf(path: string): string {
+  if (!existsSync(path)) {
+    return ABSENT;
+  }
+  try {
+    return createHash("sha256").update(readFileSync(path)).digest("hex");
+  } catch {
+    // hazard: an unreadable source must not read as unchanged, or a policy made unreadable mid-session
+    // would pass silently. It gets its own marker instead.
+    return "unreadable";
+  }
+}
+
+export function policySourceFingerprint(root: string): PolicySource[] {
+  const paths = [
+    projectConfigPath(root),
+    join(runtimeHome(), "config.json"),
+    join(projectStateDir(root), MODE_FILE),
+    ...FLAG_FILES.map((flag) => join(flagsDir(root), flag)),
+  ];
+  return paths.map((path) => ({ path, hash: hashOf(path) }));
+}
+
+function baselinePath(root: string, sessionKey: string): string {
+  return join(policyBaselineDir(root), `${sanitizeSegment(sessionKey)}.json`);
+}
+
+export function recordPolicyBaseline(root: string, sessionKey: string): void {
+  try {
+    mkdirSync(policyBaselineDir(root), { recursive: true });
+    writeFileSync(
+      baselinePath(root, sessionKey),
+      `${JSON.stringify({ schema: SCHEMA, sources: policySourceFingerprint(root) }, null, 2)}\n`,
+      "utf8",
+    );
+  } catch {}
+}
+
+function readBaseline(root: string, sessionKey: string): PolicySource[] | null {
+  const path = baselinePath(root, sessionKey);
+  if (!existsSync(path)) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as { sources?: PolicySource[] };
+    return Array.isArray(parsed.sources) ? parsed.sources : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * hazard: this compared every current source against the baseline, so a path the baseline had never heard of
+ * counted as divergence. That is not a policy change — it means the harness's own list of policy sources grew
+ * or was renamed, which happens on upgrade. Renaming a posture flag made this fire against its own author, and
+ * it would have accused every operator with a live session of tampering the moment they updated the harness.
+ *
+ * invariant: only paths present in both are compared, and a hash that moved still fires. An out-of-band flag
+ * write is caught because the baseline records absent sources too, so that source goes from `absent` to a hash
+ * on a path the baseline already knows — detection is untouched.
+ */
+function divergedIn(baseline: PolicySource[], current: PolicySource[]): string[] {
+  const recorded = new Map(baseline.map((source) => [source.path, source.hash]));
+  return current
+    .filter((source) => {
+      const was = recorded.get(source.path);
+      return was !== undefined && was !== source.hash;
+    })
+    .map((source) => source.path);
+}
+
+/**
+ * why: every diverged path, not the first. Reporting one at a time makes an operator repair, get blocked again, and
+ * repair again — and accepting requires the full list anyway
+ * ([/decisions/ad-030.md](/decisions/ad-030.md)).
+ */
+export function divergedPaths(root: string, sessionKey: string): string[] {
+  const baseline = readBaseline(root, sessionKey);
+  return baseline === null ? [] : divergedIn(baseline, policySourceFingerprint(root));
+}
+
+/** why: the union across live sessions, so a listing shows what the operator has to deal with, not one session's view. */
+export function allDivergedPaths(root: string): string[] {
+  const dir = policyBaselineDir(root);
+  if (!existsSync(dir)) {
+    return [];
+  }
+  const found = new Set<string>();
+  const current = policySourceFingerprint(root);
+  for (const entry of readdirSync(dir)) {
+    if (!entry.endsWith(".json")) {
+      continue;
+    }
+    const baseline = readBaseline(root, entry.replace(/\.json$/, ""));
+    if (baseline) {
+      for (const path of divergedIn(baseline, current)) {
+        found.add(path);
+      }
+    }
+  }
+  return [...found].sort();
+}
+
+export type AcceptOutcome =
+  | { kind: "accepted"; paths: string[] }
+  | { kind: "not-a-source"; paths: string[]; sources: string[] }
+  | { kind: "nothing-to-accept" };
+
+/**
+ * invariant: per source. `refreshPolicyBaselines` rewrites the whole fingerprint, so using it here would silently
+ * accept every *other* change alongside the one named — which is the hole this closes. Each named path gets its
+ * current hash written into every live session's baseline; every other entry is left exactly as it was, so a second
+ * divergence still fires.
+ *
+ * invariant: no blanket permission is expressible. The accepted hash is the hash at this moment, so a later change
+ * to the same file diverges again. There is deliberately no way to stop watching a source.
+ *
+ * hazard: this is the one function in the codebase whose job is to clear a tampering signal. It reads no policy and
+ * makes no judgement — the four locks that keep it out of an agent's reach live at the CLI and in the floor, where
+ * they can be tested independently ([/decisions/ad-030.md](/decisions/ad-030.md)).
+ */
+export function acceptPolicySources(root: string, paths: string[]): AcceptOutcome {
+  const current = policySourceFingerprint(root);
+  const known = new Map(current.map((source) => [source.path, source.hash]));
+  const unknown = paths.filter((path) => !known.has(path));
+  if (unknown.length > 0) {
+    return { kind: "not-a-source", paths: unknown, sources: current.map((source) => source.path) };
+  }
+
+  const dir = policyBaselineDir(root);
+  if (!existsSync(dir) || paths.length === 0) {
+    return { kind: "nothing-to-accept" };
+  }
+
+  for (const entry of readdirSync(dir)) {
+    if (!entry.endsWith(".json")) {
+      continue;
+    }
+    const sessionKey = entry.replace(/\.json$/, "");
+    const baseline = readBaseline(root, sessionKey);
+    if (!baseline) {
+      continue;
+    }
+    const updated = baseline.map((source) =>
+      paths.includes(source.path) ? { path: source.path, hash: known.get(source.path) as string } : source,
+    );
+    try {
+      writeFileSync(
+        join(dir, entry),
+        `${JSON.stringify({ schema: SCHEMA, sources: updated }, null, 2)}\n`,
+        "utf8",
+      );
+    } catch {}
+  }
+  return { kind: "accepted", paths };
+}
+
+// invariant: this is the layer that covers what shell parsing cannot — `bash script.sh`, a compiled binary,
+// a path built at runtime. It reads the policy's *bytes*, never its values, so nothing inside the policy can
+// switch off the check that watches it.
+export function checkPolicyBaseline(root: string, sessionKey: string): Decision {
+  const baseline = readBaseline(root, sessionKey);
+  // why: a missing baseline is the first hook of a session, not evidence of tampering. Recording and
+  // allowing is the only safe reading — blocking here would break every fresh session.
+  if (!baseline) {
+    recordPolicyBaseline(root, sessionKey);
+    return { kind: "allow" };
+  }
+
+  const diverged = divergedIn(baseline, policySourceFingerprint(root));
+  if (diverged.length === 0) {
+    return { kind: "allow" };
+  }
+
+  /**
+   * hazard: the reason used to end "the harness commands re-record the baseline when they write" — and the floor
+   * refuses every one of those commands from inside a session. A blocked agent read it as a route, tried one, and
+   * stayed blocked. `reason` reaches the agent and `userNote` reaches the operator; the fix is to stop putting the
+   * operator's instructions in the agent's half ([/decisions/ad-030.md](/decisions/ad-030.md)).
+   */
+  return {
+    kind: "deny",
+    reason: [
+      `HARNESS: ${diverged.join(", ")} changed during this session, and no harness command changed it.`,
+      "The gates are now running a policy the operator did not set, so what they check cannot be trusted.",
+      "Report this to the operator and name the paths above. Only they can clear it, from their own terminal — the harness commands that would are refused from inside a session, so there is nothing for you to run here.",
+    ].join("\n"),
+    userNote: [
+      `Harness policy changed out of band during this session: ${diverged.join(", ")}.`,
+      `If that was you, accept it with: tlc harness policy accept ${diverged.join(" ")}`,
+    ].join(" "),
+    rule: "policy-baseline-divergence",
+  };
+}
+
+// why: the CLI is the sanctioned mutator, so after it writes, every live session's baseline is refreshed.
+// It cannot know which sessions are live, which is exactly why it refreshes all of them — and it makes
+// "a harness command did this" and "the baseline matches" the same fact, with no second log to drift.
+export function refreshPolicyBaselines(root: string): void {
+  const dir = policyBaselineDir(root);
+  if (!existsSync(dir)) {
+    return;
+  }
+  const sources = policySourceFingerprint(root);
+  for (const entry of readdirSync(dir)) {
+    if (!entry.endsWith(".json")) {
+      continue;
+    }
+    try {
+      writeFileSync(join(dir, entry), `${JSON.stringify({ schema: SCHEMA, sources }, null, 2)}\n`, "utf8");
+    } catch {}
+  }
+}