@tech-leads-club/harness-toolkit 0.3.5 → 0.4.0

package/src/core/rules/rules.proof.ts

@@ -0,0 +1,130 @@
+/**
+ * Whether the proof a rule demands exists.
+ *
+ * invariant: a proof is satisfied only by something the harness itself observed. Never by the agent asserting it,
+ * and never by a model's verdict — the same change gets different verdicts across runs, so a probabilistic
+ * reviewer cannot be an enforcement mechanism ([/decisions/ad-100.md](/decisions/ad-100.md)).
+ *
+ * invariant: pure. The store hands over the observations; this decides what they mean.
+ */
+import { matchesPhrase } from "./rules.trigger.ts";
+import type { Rule, RuleProof } from "./rules.types.ts";
+
+/**
+ * One thing the harness saw.
+ *
+ * why `sha`: freshness is part of the proof. A review of the code as it was two commits ago reviewed something
+ * else, so an observation carries the HEAD it was made against and `since HEAD` compares them.
+ */
+export type Observation = {
+  kind: RuleProof["kind"];
+  /** The subagent type, the command as words, the gate name, or the path. */
+  value: string;
+  /** HEAD when it was observed. `null` when the project is not a git checkout. */
+  sha: string | null;
+  sessionKey: string;
+  at: string;
+};
+
+export type ProofContext = { sha: string | null; sessionKey: string };
+
+/**
+ * why a suffix and a directory instead of a glob engine: nothing else in this repository needs globs, and an
+ * engine written for one caller is generality nobody asked for. Three shapes, each stated: an exact path,
+ * `*.<ext>`, and a `dir/` prefix. A rule that needs more than that is a decision with a reason, not a silent
+ * extension of this function.
+ */
+function pathMatches(pattern: string, path: string): boolean {
+  if (pattern === path) {
+    return true;
+  }
+  if (pattern.startsWith("*")) {
+    return path.endsWith(pattern.slice(1));
+  }
+  if (pattern.endsWith("/")) {
+    return path.startsWith(pattern);
+  }
+  return false;
+}
+
+function valueMatches(proof: RuleProof, observation: Observation): boolean {
+  if (proof.kind !== observation.kind) {
+    return false;
+  }
+  switch (proof.kind) {
+    case "command":
+      // why the same phrase rule as the trigger: the operator wrote words in an order, in both places.
+      return matchesPhrase(observation.value.split(/\s+/), proof.value);
+    case "file":
+      return pathMatches(proof.value, observation.value);
+    default:
+      return observation.value === proof.value;
+  }
+}
+
+/**
+ * invariant: `since HEAD` needs a sha on both sides. When the project is not a git checkout there is no HEAD to
+ * compare, so a `since HEAD` proof cannot be satisfied — and saying so is the honest answer, rather than treating
+ * "no sha" as "any sha".
+ */
+function windowMatches(proof: RuleProof, observation: Observation, context: ProofContext): boolean {
+  if (proof.since === "session") {
+    return observation.sessionKey === context.sessionKey;
+  }
+  return context.sha !== null && observation.sha === context.sha;
+}
+
+export function proofSatisfied(
+  proof: RuleProof,
+  observations: readonly Observation[],
+  context: ProofContext,
+): boolean {
+  return observations.some(
+    (observation) => valueMatches(proof, observation) && windowMatches(proof, observation, context),
+  );
+}
+
+/** invariant: every proof must hold. The list is a conjunction, which is why there is no boolean algebra. */
+export function missingProofs(
+  rule: Rule,
+  observations: readonly Observation[],
+  context: ProofContext,
+): RuleProof[] {
+  return rule.require.filter((proof) => !proofSatisfied(proof, observations, context));
+}
+
+export function proofLabel(proof: RuleProof): string {
+  return `${proof.kind}(${proof.value}) since ${proof.since === "head" ? "HEAD" : "session"}`;
+}
+
+/**
+ * Whether recording this kind could ever matter here.
+ *
+ * why: the observing rails fire on every tool call, and a fact nothing reads is a write and a process spawn for
+ * nothing. An operator whose only rule wants `subagent(the-jury)` pays no git on any command
+ * ([/decisions/ad-100.md](/decisions/ad-100.md)).
+ */
+export function kindIsRequired(rules: readonly Rule[], kind: RuleProof["kind"]): boolean {
+  return rules.some((rule) => rule.require.some((proof) => proof.kind === kind));
+}
+
+/**
+ * What `doctor` needs to tell an operator that a rule can never be satisfied here.
+ *
+ * why this rather than a capability flag: both hosts report subagent types today, so a flag for it would be a flag
+ * that is never false — the shape of a rail that reads as protection and measures nothing
+ * ([/decisions/ad-034.md](/decisions/ad-034.md)). What is worth saying is factual: this rule wants a kind of
+ * observation that has never been recorded in this project.
+ */
+export function unobservedKinds(
+  rules: readonly Rule[],
+  observations: readonly Observation[],
+): Array<{ rule: string; kinds: RuleProof["kind"][] }> {
+  const seen = new Set(observations.map((observation) => observation.kind));
+  return rules
+    .map((rule) => ({
+      rule: rule.name,
+      kinds: [...new Set(rule.require.map((proof) => proof.kind))].filter((kind) => !seen.has(kind)),
+    }))
+    .filter((entry) => entry.kinds.length > 0);
+}

package/src/core/rules/rules.service.ts

@@ -0,0 +1,141 @@
+/**
+ * The composition the entrypoints call: read the rules, see what fired, decide.
+ *
+ * why here and not in the entrypoint: the entrypoints are adapters. Which rules apply, what proves them and what
+ * the verdict is are all decisions, and decisions live in core ([/decisions/ad-016.md](/decisions/ad-016.md)).
+ *
+ * invariant: with the capability off, or with no rule files, this reads two directory entries and returns nothing.
+ * That is what makes the feature inert until an operator declares something (AC1).
+ */
+import type { Decision } from "../../contracts/decision.ts";
+import type { OperatorMode } from "../policy/policy.types.ts";
+import { actionDecision, evaluateRules, type RuleOutcome, stopDecision, strictest } from "./rules.decide.ts";
+import {
+  gateObservation,
+  type ObservableEvent,
+  type ObserveContext,
+  observationFrom,
+  observedFact,
+} from "./rules.observe.ts";
+import { buildRuleSet } from "./rules.parse.ts";
+import { kindIsRequired } from "./rules.proof.ts";
+import { readObservations, readRuleSources, recordObservation } from "./rules.store.ts";
+import { firingRules, type TriggerContext } from "./rules.trigger.ts";
+import type { RuleError, RuleSet } from "./rules.types.ts";
+
+export type RulesConfig = { enabled: boolean };
+
+export function loadRules(root: string, config: RulesConfig): RuleSet {
+  if (!config.enabled) {
+    return { rules: [], disabled: [], errors: [] };
+  }
+  return buildRuleSet(readRuleSources(root));
+}
+
+/**
+ * Whether this event is worth a sha.
+ *
+ * hazard: nothing called `observe` at all in the first cut of this feature. The store was never written, so no
+ * proof could exist, so every rule that parsed denied for ever — and `require:` is mandatory, so that was every
+ * rule. The end-to-end run that appeared to show the loop working was a script calling `observe` by hand, which
+ * supplied the missing half and hid it ([/decisions/ad-100.md](/decisions/ad-100.md)).
+ *
+ * why the question is asked before the answer is fetched: the observing rails fire on every tool call and the sha
+ * is a process spawn. An operator whose only rule wants `subagent(the-jury)` pays two directory reads per command
+ * and no git at all.
+ */
+export function wantsObservation(root: string, config: RulesConfig, event: ObservableEvent): boolean {
+  const fact = observedFact(event);
+  return fact !== null && kindIsRequired(loadRules(root, config).rules, fact.kind);
+}
+
+/** invariant: with the capability off nothing is written, so a machine that never opted in carries no new file. */
+export function observe(
+  root: string,
+  config: RulesConfig,
+  event: ObservableEvent,
+  context: ObserveContext,
+): void {
+  if (!config.enabled) {
+    return;
+  }
+  const observation = observationFrom(event, context);
+  if (observation !== null) {
+    recordObservation(root, observation);
+  }
+}
+
+/**
+ * A gate is the one proof the harness decides rather than witnesses, so it is recorded where it is decided.
+ *
+ * invariant: only a gate that passed. Recording a failure as an observation would make "the gate ran" satisfy a
+ * rule that asked for "the gate passed".
+ */
+export function wantsGateObservation(root: string, config: RulesConfig): boolean {
+  return kindIsRequired(loadRules(root, config).rules, "gate");
+}
+
+export function observeGate(root: string, config: RulesConfig, gate: string, context: ObserveContext): void {
+  if (!config.enabled) {
+    return;
+  }
+  recordObservation(root, gateObservation(gate, context));
+}
+
+export type RulesVerdict = {
+  decision: Decision;
+  /** Everything that fired, so a `follow-up` or a `warn` can be reported even when the action is allowed. */
+  outcomes: RuleOutcome[];
+  errors: RuleError[];
+};
+
+const NOTHING: RulesVerdict = { decision: { kind: "abstain" }, outcomes: [], errors: [] };
+
+/**
+ * The action-time answer. `deny` and `ask` block here; `follow-up` and `warn` are answers to the end of a turn and
+ * to the record, so they abstain and are returned for the caller to report.
+ */
+export function decideAction(
+  root: string,
+  config: RulesConfig,
+  trigger: TriggerContext,
+  context: RuleContext,
+): RulesVerdict {
+  return decide(root, config, trigger, context, actionDecision);
+}
+
+/**
+ * The end-of-turn answer, and the only caller that can see an `on: stop` rule.
+ *
+ * why a second entry rather than a flag: the trigger is fixed and the mapping differs, so a boolean would make one
+ * function answer two questions ([/decisions/ad-100.md](/decisions/ad-100.md)).
+ */
+export function decideStop(root: string, config: RulesConfig, context: RuleContext): RulesVerdict {
+  return decide(root, config, { event: "stop" }, context, stopDecision);
+}
+
+export type RuleContext = { sha: string | null; sessionKey: string; mode: OperatorMode };
+
+function decide(
+  root: string,
+  config: RulesConfig,
+  trigger: TriggerContext,
+  context: RuleContext,
+  map: (outcome: RuleOutcome) => Decision,
+): RulesVerdict {
+  const set = loadRules(root, config);
+  if (set.rules.length === 0 && set.errors.length === 0) {
+    return NOTHING;
+  }
+  const firing = firingRules(set.rules, trigger);
+  if (firing.length === 0) {
+    return { ...NOTHING, errors: set.errors };
+  }
+  const outcomes = evaluateRules(firing, readObservations(root), context);
+  const worst = strictest(outcomes);
+  return {
+    decision: worst === null ? { kind: "abstain" } : map(worst),
+    outcomes,
+    errors: set.errors,
+  };
+}

package/src/core/rules/rules.store.ts

@@ -0,0 +1,77 @@
+/**
+ * Where the harness records what it observed, and where it reads the rules from.
+ *
+ * invariant: the agent cannot write here. This lives under the project state directory, which the floor's
+ * `policy-surface-write` refuses to an agent through a shell redirect, an interpreter or a write tool — and the
+ * mutating `tlc harness` subcommands are refused from inside a session. So the only writer is the harness
+ * observing a host event, which is what makes a proof unforgeable rather than conventional
+ * ([/decisions/ad-100.md](/decisions/ad-100.md), [/decisions/ad-022.md](/decisions/ad-022.md)).
+ *
+ * why append-only jsonl and not a merged document: two sessions observe at the same time, and an append is the one
+ * write that needs no lock. The reader takes the tail, because a proof is about now.
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { appendRecord, readTail } from "../../platform/fs-jsonl.ts";
+import { machineHome, projectStateDir } from "../../platform/paths.ts";
+import type { RuleSource } from "./rules.parse.ts";
+import type { Observation } from "./rules.proof.ts";
+import type { RuleTier } from "./rules.types.ts";
+
+/**
+ * why a bound: an observation older than this window cannot satisfy `since HEAD` anyway, and a file that grows
+ * without limit is a file nobody prunes. The tail is generous enough that a long session keeps its own proofs.
+ */
+const OBSERVATION_TAIL = 500;
+
+export function observationsPath(root: string): string {
+  return join(projectStateDir(root), "rule-observations.jsonl");
+}
+
+/** The project's rules, versioned with it. */
+export function projectRulesDir(root: string): string {
+  return join(projectStateDir(root), "..", "rules");
+}
+
+/** This machine's rules, every repository — the tier that follows the operator across products. */
+export function globalRulesDir(): string {
+  return join(machineHome(), "rules");
+}
+
+function readDir(dir: string, tier: RuleTier): RuleSource[] {
+  if (!existsSync(dir)) {
+    return [];
+  }
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".md"))
+    .map((entry) => {
+      const path = join(dir, entry.name);
+      return { name: basename(entry.name, ".md"), tier, text: readFileSync(path, "utf8") };
+    });
+}
+
+/**
+ * invariant: both tiers are read, global first, so `buildRuleSet` can let the project win by name. Absent
+ * directories are absent rules, not an error — no rules means no behaviour change
+ * ([/decisions/ad-040.md](/decisions/ad-040.md)).
+ */
+export function readRuleSources(root: string): RuleSource[] {
+  return [...readDir(globalRulesDir(), "global"), ...readDir(projectRulesDir(root), "project")];
+}
+
+export function recordObservation(root: string, observation: Observation): void {
+  try {
+    appendRecord(observationsPath(root), observation);
+  } catch {
+    // why swallowed: an unwritable state directory must not fail the turn that was being observed. The proof will
+    // be missing, which the gate reports as missing rather than as an error nobody can act on.
+  }
+}
+
+export function readObservations(root: string): Observation[] {
+  try {
+    return readTail<Observation>(observationsPath(root), OBSERVATION_TAIL);
+  } catch {
+    return [];
+  }
+}

package/src/core/rules/rules.trigger.ts

@@ -0,0 +1,101 @@
+/**
+ * Whether a rule's trigger fires on this event.
+ *
+ * invariant: pure, and it never reads a host payload. It takes the published event shape, so a rule written once
+ * fires the same way on every provider ([/decisions/ad-004.md](/decisions/ad-004.md)).
+ *
+ * hazard: a shell trigger cannot be a substring test against the whole command. `x && gh pr create` is a pull
+ * request being opened, and a heredoc body containing the words `gh pr create` is a document. `tokenizeShell`
+ * separates both and is the only splitter in this repository — a second regex here would be the duplication that
+ * makes one of them wrong later ([/decisions/ad-100.md](/decisions/ad-100.md)).
+ */
+import { tokenizeShell } from "../floor/floor.tokenize.ts";
+import type { Rule, RuleTrigger } from "./rules.types.ts";
+
+/**
+ * What the harness reads to decide whether a trigger fires. A subset of the event, named so the vocabulary is
+ * visible: adding a trigger that needs a new field has to widen this deliberately.
+ */
+export type TriggerContext = {
+  event: string;
+  toolName?: string;
+  command?: string;
+};
+
+/**
+ * why a set per trigger rather than one pattern the operator writes: `pr-open` has to mean the same thing in
+ * every repository, or a rule copied between them silently stops firing. An operator who wants their own shape
+ * writes `command(<pattern>)`.
+ */
+const SHELL_SHAPES: Record<"pr-open" | "commit" | "push", readonly string[][]> = {
+  "pr-open": [
+    ["gh", "pr", "create"],
+    ["gh", "pr", "ready"],
+  ],
+  commit: [["git", "commit"]],
+  push: [["git", "push"]],
+};
+
+/**
+ * invariant: `tokenizeShell` already declines to emit segments from a heredoc body, so a body is never mistaken
+ * for a command and a command after one is still seen. Measured both ways on
+ * `cat <<EOF > runbook.md\ngh pr create --fill\nEOF` and on the same with a real command after the terminator:
+ * identical output.
+ *
+ * hazard: the first version of this called `splitHeredocs` first as well. It changed nothing — the mutation that
+ * removed it survived, which is what exposed it as dead rather than as untested
+ * ([/decisions/ad-100.md](/decisions/ad-100.md)).
+ */
+function subCommands(command: string): string[][] {
+  return tokenizeShell(command)
+    .map((segment) => segment.words.map((word) => word.text))
+    .filter((words) => words.length > 0);
+}
+
+/** why prefix rather than equality: `gh pr create --fill --base main` is the same act as `gh pr create`. */
+function startsWithShape(words: readonly string[], shape: readonly string[]): boolean {
+  return shape.every((token, index) => words[index] === token);
+}
+
+/**
+ * why a phrase and not a word: an operator writes `command(gh pr review)`, meaning those words in that order.
+ * Matching the raw string against the whole command would let a heredoc or an unrelated argument satisfy it.
+ */
+export function matchesPhrase(words: readonly string[], pattern: string): boolean {
+  const phrase = pattern.trim().split(/\s+/);
+  if (phrase.length === 0) {
+    return false;
+  }
+  return words.some((_, start) => phrase.every((token, index) => words[start + index] === token));
+}
+
+export function triggerMatches(trigger: RuleTrigger, context: TriggerContext): boolean {
+  switch (trigger.kind) {
+    case "stop":
+      return context.event === "stop";
+    case "tool":
+      return context.toolName === trigger.name;
+    case "pr-open":
+    case "commit":
+    case "push": {
+      if (context.command === undefined) {
+        return false;
+      }
+      const shapes = SHELL_SHAPES[trigger.kind];
+      return subCommands(context.command).some((words) =>
+        shapes.some((shape) => startsWithShape(words, shape)),
+      );
+    }
+    default: {
+      if (context.command === undefined) {
+        return false;
+      }
+      return subCommands(context.command).some((words) => matchesPhrase(words, trigger.pattern));
+    }
+  }
+}
+
+/** invariant: a disabled rule never fires. It exists to switch a global off and to record why. */
+export function firingRules(rules: readonly Rule[], context: TriggerContext): Rule[] {
+  return rules.filter((rule) => rule.enabled && triggerMatches(rule.on, context));
+}

package/src/core/rules/rules.types.ts

@@ -0,0 +1,64 @@
+/**
+ * What an operator rule is.
+ *
+ * why two closed vocabularies: a gate may only rest on something the harness observed, and a trigger may only be
+ * something it can recognise. An open expression language would let an operator declare a rule the harness cannot
+ * evaluate, and the honest answer to that is a parse error rather than a rule that never fires
+ * ([/decisions/ad-100.md](/decisions/ad-100.md)).
+ */
+
+/** Where the rule came from. `project` replaces a `global` of the same name, and both apply otherwise. */
+export type RuleTier = "global" | "project";
+
+/**
+ * What happens when the proof is missing.
+ *
+ * invariant: `deny`, `follow-up` and `warn` are verification and are identical at every posture. `ask` is an
+ * interruption, which is the one thing posture governs ([/decisions/ad-025.md](/decisions/ad-025.md)).
+ */
+export type RuleVerdict = "deny" | "ask" | "follow-up" | "warn";
+
+export const RULE_VERDICTS: ReadonlySet<string> = new Set<RuleVerdict>(["deny", "ask", "follow-up", "warn"]);
+
+/** When the rule is evaluated. */
+export type RuleTrigger =
+  | { kind: "pr-open" }
+  | { kind: "commit" }
+  | { kind: "push" }
+  | { kind: "stop" }
+  | { kind: "tool"; name: string }
+  | { kind: "command"; pattern: string };
+
+/**
+ * What counts as proof, and how fresh it must be.
+ *
+ * why `head` by default: a review of the code as it was two commits ago is not a review of what the pull request
+ * carries.
+ */
+export type ProofWindow = "head" | "session";
+
+export type RuleProof =
+  | { kind: "subagent"; value: string; since: ProofWindow }
+  | { kind: "command"; value: string; since: ProofWindow }
+  | { kind: "gate"; value: string; since: ProofWindow }
+  | { kind: "file"; value: string; since: ProofWindow };
+
+export const PROOF_KINDS: ReadonlySet<string> = new Set(["subagent", "command", "gate", "file"]);
+
+export type Rule = {
+  /** The file name without its extension. This is the id the tiers dedupe on. */
+  name: string;
+  tier: RuleTier;
+  enabled: boolean;
+  on: RuleTrigger;
+  /** invariant: every proof must hold. There is no boolean algebra here on purpose. */
+  require: RuleProof[];
+  otherwise: RuleVerdict;
+  /** The operator's own text, injected verbatim when the rule fires. */
+  body: string;
+};
+
+/** A rule that could not be read. Named, so `doctor` can report it instead of the harness ignoring it silently. */
+export type RuleError = { name: string; tier: RuleTier; error: string };
+
+export type RuleSet = { rules: Rule[]; errors: RuleError[]; disabled: Rule[] };

package/src/entrypoints/run.ts

@@ -1,5 +1,6 @@
 import { join } from "node:path";
 import type { Decision, HarnessEvent, ProviderCapabilities, Rendered } from "../contracts/index.ts";
+import { isWriteTool } from "../contracts/tool-names.ts";
 import { coreFacade, type Policy } from "../core/index.ts";
 import { appendRecord } from "../platform/fs-jsonl.ts";
 import { projectStateDir } from "../platform/paths.ts";
@@ -36,6 +37,25 @@ export type RunOutcome = {
 // (lessons.maxCharsSession) — reusing that here truncated the operator posture and handoff.
 export const CONTEXT_BUDGET_CHARS = 6000;
 
+/**
+ * Whether this event may claim its file against other sessions.
+ *
+ * invariant: a claim exists so that two writers do not lose each other's work. A reader loses nothing, so a read
+ * carries no claim however many files it opens ([/decisions/ad-099.md](/decisions/ad-099.md)).
+ *
+ * why `edit.after` with no tool name still claims: the write already happened, and the host does not always name
+ * the tool on that event. An event that reports a completed edit is a writer by definition.
+ */
+export function claimsFile(event: HarnessEvent): boolean {
+  if (event.filePath === undefined) {
+    return false;
+  }
+  if (event.event === "edit.after") {
+    return true;
+  }
+  return isWriteTool(event.toolName);
+}
+
 function errorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
@@ -144,10 +164,20 @@ export async function runHandler(handler: Handler, io: RunIo = {}): Promise<RunO
         effectiveBlockedPatterns(policy.subagents.blockedPatterns, provider),
       );
     }
+    /**
+     * hazard: this passed `event.filePath` for every event, and `read.before` carries one. So reading a file
+     * claimed it for ten minutes, and the next session to write it was refused — under a rule called
+     * `edit-collision`, with a message saying the file had been edited. Measured on a real machine: a review agent
+     * that only read blocked the operator's own writes to two files, while their `git status` showed a single
+     * modification, theirs ([/decisions/ad-099.md](/decisions/ad-099.md)).
+     *
+     * invariant: the heartbeat is unconditional — a reading session is still a live session, and staleness is what
+     * expires a claim. Only the *claim* is write-only, because only a writer can lose somebody's work.
+     */
     coreFacade.presence.heartbeat(event.projectDir, {
       provider: event.provider,
       session: sessionIdFromKey(event),
-      file: event.filePath,
+      ...(claimsFile(event) ? { file: event.filePath } : {}),
       now,
     });
     const context: HandlerContext = { policy, capabilities, provider, now };

package/src/entrypoints/shim.ts

@@ -79,6 +79,14 @@ if (existsSync(execBin)) {
 } else if (existsSync(srcHandler)) {
   run(process.env.BUN_BIN || "bun", ["run", srcHandler]);
 } else {
+  /**
+   * hazard: this exited 127 with nothing on stdout. The project shim answers a host hook, so a shim that cannot
+   * find its handler was standing between the agent and its tools with no verdict at all — the same defect the
+   * launcher had one layer down ([/decisions/ad-101.md](/decisions/ad-101.md)).
+   *
+   * invariant: the diagnosis still reaches stderr. Failing open is not failing silently.
+   */
   console.error(`tlc shim: handler not found: ${handler}`);
-  process.exit(127);
+  process.stdout.write("{}");
+  process.exit(0);
 }