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

package/src/core/policy/policy.loader.ts

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { flagsDir, projectConfigPath, runtimeHome } from "../../platform/paths.ts";
+import { flagsDir, machineConfigPath, projectConfigPath } from "../../platform/paths.ts";
 import { lessonsSyncMode, resolveSyncMode, type SyncModeResolution } from "../lesson/lesson.sync.ts";
 import { DEFAULTS } from "./policy.defaults.ts";
 import { type PostureResolution, resolvePosture } from "./policy.posture.ts";
@@ -55,7 +55,7 @@ type ConfigPair = { fromUser: PartialPolicy; fromProject: PartialPolicy };
 
 function readConfigPair(root: string): ConfigPair {
   return {
-    fromUser: readJsonFile<PartialPolicy>(join(runtimeHome(), "config.json")) ?? {},
+    fromUser: readJsonFile<PartialPolicy>(machineConfigPath()) ?? {},
     fromProject: readJsonFile<PartialPolicy>(projectConfigPath(root)) ?? {},
   };
 }
@@ -89,7 +89,7 @@ export function resolveProjectSyncMode(root: string): SyncModeResolution {
   if (resolution.coercedFrom === undefined) {
     return resolution;
   }
-  const path = fromProject === undefined ? join(runtimeHome(), "config.json") : projectConfigPath(root);
+  const path = fromProject === undefined ? machineConfigPath() : projectConfigPath(root);
   return { ...resolution, coercedIn: path };
 }
 
@@ -112,6 +112,17 @@ export function loadPolicy(root: string): Policy {
   return merged;
 }
 
+/**
+ * The policy as it would be with this project's config absent — `DEFAULTS` merged with the user tier.
+ *
+ * why here: the merge lives in this module, and asking "what would this resolve to without the project file" with
+ * a second copy of the merge is how the two answers drift ([/decisions/ad-100.md](/decisions/ad-100.md)).
+ */
+export function resolvedWithoutProjectTier(): Record<string, unknown> {
+  const fromUser = readJsonFile<PartialPolicy>(machineConfigPath()) ?? {};
+  return deepMerge(DEFAULTS, fromUser) as unknown as Record<string, unknown>;
+}
+
 export function isUnderCodePaths(relativePath: string, codePaths: string[]): boolean {
   const normalized = relativePath.replace(/\\/g, "/");
   return codePaths.some((prefix) => normalized === prefix || normalized.startsWith(`${prefix}/`));

package/src/core/policy/policy.shadow.ts

@@ -0,0 +1,97 @@
+/**
+ * Which keys a project config restates rather than decides.
+ *
+ * why this is worth reporting: the layers are `DEFAULTS < user < project`, so a project key naming the value the
+ * lower tiers already resolve to changes nothing today and shadows them for ever. The moment the operator edits
+ * the machine-wide config, every project that restated the old value keeps it — and nothing said so. `init` writes
+ * the whole default policy when there is no config yet, and the wizard writes every knob it collected, so this is
+ * the common case rather than the odd one ([/decisions/ad-100.md](/decisions/ad-100.md)).
+ *
+ * invariant: pure, and it reports rather than decides. A key that restates a default is not a fault — it is a key
+ * that has stopped tracking the tier below it, which is a thing an operator may want and must be able to see.
+ */
+/** A leaf the project config names, and the value it would have had without naming it. */
+export type ShadowedKey = { path: string; value: unknown };
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * why a JSON comparison rather than a deep walk of its own: the values are config leaves — scalars and small
+ * arrays — and `codePaths: ["src"]` has to compare equal to `codePaths: ["src"]`. A second structural comparator
+ * here would be the copy that disagrees with the merge later.
+ */
+function sameValue(a: unknown, b: unknown): boolean {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+/**
+ * Every leaf in `project` whose value the lower tiers already resolve to.
+ *
+ * `resolved` is the policy as it would be with the project config absent — `DEFAULTS` merged with the user tier.
+ */
+export function shadowedKeys(
+  project: Record<string, unknown>,
+  resolved: Record<string, unknown>,
+  prefix = "",
+): ShadowedKey[] {
+  const found: ShadowedKey[] = [];
+  for (const [key, value] of Object.entries(project)) {
+    // why skipped: `version` is the config's own shape marker rather than a setting, so naming it is required
+    // rather than redundant.
+    if (prefix === "" && key === "version") {
+      continue;
+    }
+    const path = prefix === "" ? key : `${prefix}.${key}`;
+    const below = resolved[key];
+    if (isPlainObject(value) && isPlainObject(below)) {
+      found.push(...shadowedKeys(value, below, path));
+      continue;
+    }
+    if (sameValue(value, below)) {
+      found.push({ path, value });
+    }
+  }
+  return found;
+}
+
+/**
+ * The project config with every restatement removed.
+ *
+ * why this and not just a report: `init` wrote the whole default policy when a project had no config yet, and the
+ * wizard wrote every knob it collected — so a fresh project shadowed the machine tier in dozens of places before
+ * anyone had chosen anything. Reporting it after the fact leaves the operator to undo it by hand; not writing it
+ * is the fix ([/decisions/ad-101.md](/decisions/ad-101.md)).
+ *
+ * invariant: pruning cannot change the effective policy. A leaf is dropped only when the tiers below already
+ * resolve to it, so the merge produces the same value with the key absent.
+ *
+ * why empty objects go too: `{ shipGate: {} }` is a block that decides nothing, and leaving it behind would make
+ * a pruned config read as though it had opinions.
+ */
+export function pruneShadowed(
+  project: Record<string, unknown>,
+  resolved: Record<string, unknown>,
+  prefix = "",
+): Record<string, unknown> {
+  const kept: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(project)) {
+    if (prefix === "" && key === "version") {
+      kept[key] = value;
+      continue;
+    }
+    const below = resolved[key];
+    if (isPlainObject(value) && isPlainObject(below)) {
+      const inner = pruneShadowed(value, below, `${prefix}${key}.`);
+      if (Object.keys(inner).length > 0) {
+        kept[key] = inner;
+      }
+      continue;
+    }
+    if (!sameValue(value, below)) {
+      kept[key] = value;
+    }
+  }
+  return kept;
+}

package/src/core/policy/policy.types.ts

@@ -110,6 +110,13 @@ export type Policy = {
     enabled: boolean;
     windowMinutes: number;
   };
+  /**
+   * Operator rules: the operator declares the trigger and the proof, and the harness enforces it. Off by default,
+   * and with no rule files the whole mechanism is inert ([/decisions/ad-100.md](/decisions/ad-100.md)).
+   */
+  rules: {
+    enabled: boolean;
+  };
   shell: {
     catastrophicAsk: boolean;
     stallDetection: boolean;
@@ -139,6 +146,7 @@ export type PartialPolicy = Partial<Policy> & {
   obs?: Partial<Policy["obs"]>;
   untrustedContent?: Partial<Policy["untrustedContent"]>;
   planGate?: Partial<Policy["planGate"]>;
+  rules?: Partial<Policy["rules"]>;
   shell?: Partial<Policy["shell"]>;
   intelligence?: Partial<Policy["intelligence"]> & {
     lessons?: Partial<LessonsPolicyConfig>;

package/src/core/release/release.decisions.ts

@@ -1,5 +1,8 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
+// invariant: one frontmatter reader, in platform. This file used to carry a private single-field copy
+// ([/decisions/ad-100.md](/decisions/ad-100.md)).
+import { frontmatterField } from "../../platform/frontmatter.ts";
 
 /**
  * why: the substance of a changelog already exists in this repository as thirty decision records, each carrying why,
@@ -22,19 +25,6 @@ export type DecisionSummary = {
   path: string;
 };
 
-function frontmatterField(text: string, field: string): string | undefined {
-  // why: line-scoped, matching how `check-docs-bundle` reads the same files. The values here are single-line
-  // quoted strings by convention, and the bundle check is what enforces that.
-  const match = new RegExp(`^${field}:\\s*"?(.+?)"?\\s*$`, "m").exec(text);
-  const value = match?.[1]?.trim();
-  if (value === undefined || value === "") {
-    return undefined;
-  }
-  // hazard: an escaped quote inside the value survived the outer-quote strip and reached the operator as a literal
-  // `\"` in their terminal. Seen in a real update run ([/decisions/ad-034.md](/decisions/ad-034.md)).
-  return value.replace(/\\(["'\\])/g, "$1");
-}
-
 export function decisionsDir(repoRoot: string): string {
   return join(repoRoot, "docs", "decisions");
 }

package/src/core/rules/rules.decide.ts

@@ -0,0 +1,123 @@
+/**
+ * What the harness answers when a rule fires and its proof is missing.
+ *
+ * invariant: pure, and posture only reaches `ask`. `deny`, `follow-up` and `warn` are verification, and the
+ * evidence bar is identical at all three postures — a posture that switched a check off is the defect the posture
+ * feature exists to remove ([/decisions/ad-025.md](/decisions/ad-025.md) item 4).
+ */
+import type { Decision } from "../../contracts/decision.ts";
+import type { OperatorMode } from "../policy/policy.types.ts";
+import { missingProofs, type Observation, type ProofContext, proofLabel } from "./rules.proof.ts";
+import type { Rule, RuleVerdict } from "./rules.types.ts";
+
+/**
+ * `ask` is an interruption, which is the one thing posture governs. `paired` promises a check-in before a sizable
+ * move, so it asks. `solo` and `focus` name what reaches the operator — a destructive action, a dead end, and for
+ * `solo` a real ambiguity — and a missing proof is none of those, so the harness settles it itself.
+ *
+ * invariant: it hardens rather than softens. Softening would let a posture clear a verification, which is exactly
+ * what posture must never do — and it is the same direction `ask` already degrades in on a host that cannot ask.
+ */
+export function effectiveVerdict(declared: RuleVerdict, mode: OperatorMode): RuleVerdict {
+  return declared === "ask" && mode !== "paired" ? "deny" : declared;
+}
+
+/**
+ * why the body verbatim: the rule's instruction is the operator's, with their project's context and their
+ * attachments. The harness adds the rule's name and what is missing, and changes nothing else.
+ */
+export function ruleMessage(rule: Rule, missing: readonly ReturnType<typeof proofLabel>[]): string {
+  const head = `rule ${rule.name} (${rule.tier}): missing ${missing.join(", ")}`;
+  return rule.body.trim() === "" ? head : `${head}\n\n${rule.body.trim()}`;
+}
+
+export type RuleOutcome = {
+  rule: Rule;
+  verdict: RuleVerdict;
+  missing: string[];
+  message: string;
+};
+
+/**
+ * invariant: a rule whose proof holds produces nothing at all. Silence on the healthy path is what keeps this
+ * from being a wall an operator learns to ignore ([/decisions/ad-034.md](/decisions/ad-034.md)).
+ */
+export function evaluateRules(
+  rules: readonly Rule[],
+  observations: readonly Observation[],
+  context: ProofContext & { mode: OperatorMode },
+): RuleOutcome[] {
+  const outcomes: RuleOutcome[] = [];
+  for (const rule of rules) {
+    const missing = missingProofs(rule, observations, context);
+    if (missing.length === 0) {
+      continue;
+    }
+    const labels = missing.map(proofLabel);
+    outcomes.push({
+      rule,
+      verdict: effectiveVerdict(rule.otherwise, context.mode),
+      missing: labels,
+      message: ruleMessage(rule, labels),
+    });
+  }
+  return outcomes;
+}
+
+const SEVERITY: Record<RuleVerdict, number> = { warn: 0, "follow-up": 1, ask: 2, deny: 3 };
+
+/**
+ * invariant: the strictest outcome decides, which is how every host resolves two hooks answering one event. A
+ * `warn` beside a `deny` must not soften the `deny`.
+ */
+export function strictest(outcomes: readonly RuleOutcome[]): RuleOutcome | null {
+  return outcomes.reduce<RuleOutcome | null>(
+    (best, outcome) => (best === null || SEVERITY[outcome.verdict] > SEVERITY[best.verdict] ? outcome : best),
+    null,
+  );
+}
+
+/**
+ * The decision for an action-time trigger. `follow-up` and `warn` never block an action — they are answers to the
+ * end of a turn, and `stopDecision` is where they are answered.
+ */
+export function actionDecision(outcome: RuleOutcome): Decision {
+  const rule = `rule:${outcome.rule.name}`;
+  if (outcome.verdict === "deny") {
+    return { kind: "deny", reason: outcome.message, rule };
+  }
+  if (outcome.verdict === "ask") {
+    return { kind: "ask", reason: outcome.message, userNote: outcome.message, rule };
+  }
+  return { kind: "abstain" };
+}
+
+/**
+ * The same four verdicts at the other moment. A stop can only be allowed or continued, so the matrix is:
+ *
+ * | verdict     | at an action                  | at the stop                                      |
+ * |-------------|-------------------------------|--------------------------------------------------|
+ * | `deny`      | refuses the action            | refuses the stop                                 |
+ * | `ask`       | asks (`paired`), else refuses | refuses the stop — no host offers an ask here     |
+ * | `follow-up` | allows                        | refuses the stop, framed as the next action       |
+ * | `warn`      | allows                        | advisory text, and the stop is allowed           |
+ *
+ * why `ask` refuses rather than passes: it already hardens to `deny` under `solo` and `focus`, and a verdict that
+ * quietly became "allow" at the one moment its channel is missing would be a bar that vanishes
+ * ([/decisions/ad-100.md](/decisions/ad-100.md)).
+ *
+ * hazard: `follow-up` and `warn` were declared, parsed and evaluated, and then discarded — the caller read only
+ * `.outcomes.length`. `on: stop` was the same: `firingRules` handled it while nothing ever called this with a stop
+ * event. Three members of a closed vocabulary that a rule could name and `doctor` would list as active.
+ */
+export function stopDecision(outcome: RuleOutcome): Decision {
+  switch (outcome.verdict) {
+    case "deny":
+    case "ask":
+      return { kind: "continue", text: `BLOCKED: ${outcome.message}` };
+    case "follow-up":
+      return { kind: "continue", text: `NEED: ${outcome.message}` };
+    case "warn":
+      return { kind: "context", text: `ADVISORY: ${outcome.message}` };
+  }
+}

package/src/core/rules/rules.observe.ts

@@ -0,0 +1,76 @@
+/**
+ * What an event proves, if anything.
+ *
+ * invariant: pure. The caller supplies the sha and the clock; this decides whether the event is worth recording
+ * and as what.
+ *
+ * why `tool.after` and not an exit code: measured on 3,755 real `shell.after` records from this machine, the
+ * payload carries `tool_response: {stdout, stderr, interrupted, …}` and **no exit code**, in any of the three
+ * shapes the two hosts send. But a tool that fails arrives as `tool.failure` — a different event, 64 of them in
+ * the same file, one of which is a `Bash` that exited non-zero. So observing at `tool.after` already means the
+ * command ran and did not fail, and no exit code is needed to say it
+ * ([/decisions/ad-100.md](/decisions/ad-100.md)).
+ *
+ * hazard: 65 of those `shell.after` records carry a non-empty stderr. Treating stderr as failure would discard
+ * proof from every command that warns.
+ */
+import type { Observation } from "./rules.proof.ts";
+
+export type ObservableEvent = {
+  event: string;
+  toolName?: string;
+  command?: string;
+  filePath?: string;
+  /**
+   * hazard: this was `subagentType`, which is the field a *spawn* carries. On `subagent.stop` both hosts put the
+   * type in `spawnSubagentType` — measured by running a real payload of each shape through the providers. So the
+   * producer read `undefined` and recorded nothing, and the unit test passed because its fixture invented the
+   * field name it was asserting about ([/decisions/ad-100.md](/decisions/ad-100.md)).
+   */
+  spawnSubagentType?: string;
+};
+
+export type ObserveContext = { sha: string | null; sessionKey: string; at: string };
+
+/** What the event says happened, with no `when` attached to it yet. */
+export type ObservedFact = { kind: Observation["kind"]; value: string };
+
+/**
+ * invariant: one event, at most one observation. A `tool.after` that carries both a command and a path is a
+ * command — the path is its argument, not a file the turn wrote.
+ *
+ * why this is separate from `observationFrom`: the sha is a process spawn and this answers whether anything is
+ * worth spawning for. One place still decides what an event means
+ * ([/decisions/ad-100.md](/decisions/ad-100.md)).
+ */
+export function observedFact(event: ObservableEvent): ObservedFact | null {
+  if (event.event === "subagent.stop") {
+    // why the type and not the id: a rule says "the jury reviewed", not "agent 7f3a reviewed".
+    return event.spawnSubagentType === undefined
+      ? null
+      : { kind: "subagent", value: event.spawnSubagentType };
+  }
+
+  if (event.event === "tool.after" || event.event === "shell.after") {
+    return event.command === undefined ? null : { kind: "command", value: event.command };
+  }
+
+  if (event.event === "edit.after") {
+    return event.filePath === undefined ? null : { kind: "file", value: event.filePath };
+  }
+
+  return null;
+}
+
+export function observationFrom(event: ObservableEvent, context: ObserveContext): Observation | null {
+  const fact = observedFact(event);
+  return fact === null ? null : { ...fact, sha: context.sha, sessionKey: context.sessionKey, at: context.at };
+}
+
+/**
+ * A gate outcome is not an event the host sends — the harness decides it. So it is recorded where it is decided,
+ * with the gate's own name.
+ */
+export function gateObservation(gate: string, context: ObserveContext): Observation {
+  return { kind: "gate", value: gate, sha: context.sha, sessionKey: context.sessionKey, at: context.at };
+}

package/src/core/rules/rules.parse.ts

@@ -0,0 +1,142 @@
+/**
+ * Reading an operator rule, and merging the two tiers.
+ *
+ * invariant: pure. The caller reads the directories and hands over `{ name, tier, text }`; this decides what they
+ * mean. That is what makes the whole vocabulary testable without a filesystem
+ * ([/decisions/ad-100.md](/decisions/ad-100.md)).
+ */
+import { asList, parseFrontmatterDoc } from "../../platform/frontmatter.ts";
+import {
+  PROOF_KINDS,
+  type ProofWindow,
+  RULE_VERDICTS,
+  type Rule,
+  type RuleError,
+  type RuleProof,
+  type RuleSet,
+  type RuleTier,
+  type RuleTrigger,
+  type RuleVerdict,
+} from "./rules.types.ts";
+
+export type RuleSource = { name: string; tier: RuleTier; text: string };
+
+const BARE_TRIGGERS = new Set(["pr-open", "commit", "push", "stop"]);
+
+/** why: `tool(Write)` and `command(gh pr create)` carry an argument; the other four do not. */
+function parseTrigger(raw: string): RuleTrigger | string {
+  const bare = raw.trim();
+  if (BARE_TRIGGERS.has(bare)) {
+    return { kind: bare } as RuleTrigger;
+  }
+  const call = /^(tool|command)\(([^)]*)\)$/.exec(bare);
+  const verb = call?.[1];
+  const argument = call?.[2]?.trim();
+  if (verb === undefined || argument === undefined || argument === "") {
+    return `unknown trigger "${bare}" — use one of pr-open, commit, push, stop, tool(<name>), command(<pattern>)`;
+  }
+  return verb === "tool" ? { kind: "tool", name: argument } : { kind: "command", pattern: argument };
+}
+
+/**
+ * `subagent(the-jury) since HEAD` → one proof.
+ *
+ * invariant: an unknown kind is an error, never a proof that silently never holds. A rule that cannot be
+ * evaluated has to say so at read time, or it reads as protection and is not.
+ */
+function parseProof(raw: string): RuleProof | string {
+  const [head, ...tail] = raw.trim().split(/\s+since\s+/i);
+  const call = /^([a-z]+)\(([^)]*)\)$/.exec((head ?? "").trim());
+  const kind = call?.[1];
+  const value = call?.[2]?.trim();
+  if (kind === undefined || !PROOF_KINDS.has(kind) || value === undefined || value === "") {
+    return `unknown proof "${raw.trim()}" — use subagent(<type>), command(<pattern>), gate(<name>) or file(<glob>)`;
+  }
+  const windowRaw = (tail[0] ?? "head").trim().toLowerCase();
+  if (windowRaw !== "head" && windowRaw !== "session") {
+    return `unknown window "since ${windowRaw}" in "${raw.trim()}" — use since HEAD or since session`;
+  }
+  return { kind, value, since: windowRaw as ProofWindow } as RuleProof;
+}
+
+export function parseRule(source: RuleSource): { rule: Rule } | { error: RuleError } {
+  const fail = (error: string) => ({ error: { name: source.name, tier: source.tier, error } });
+  const { doc, error } = parseFrontmatterDoc(source.text);
+  if (doc === null) {
+    return fail(error ?? "unreadable");
+  }
+
+  const enabledRaw = doc.fields.enabled;
+  const enabled = enabledRaw === undefined ? true : String(enabledRaw).trim() !== "false";
+
+  const onRaw = doc.fields.on;
+  if (typeof onRaw !== "string" || onRaw.trim() === "") {
+    return fail("no `on:` trigger");
+  }
+  const trigger = parseTrigger(onRaw);
+  if (typeof trigger === "string") {
+    return fail(trigger);
+  }
+
+  const verdictRaw = doc.fields.otherwise;
+  if (typeof verdictRaw !== "string" || !RULE_VERDICTS.has(verdictRaw.trim())) {
+    return fail("`otherwise:` must be one of deny, ask, follow-up, warn");
+  }
+
+  const proofs: RuleProof[] = [];
+  for (const entry of asList(doc.fields.require)) {
+    const proof = parseProof(entry);
+    if (typeof proof === "string") {
+      return fail(proof);
+    }
+    proofs.push(proof);
+  }
+  // why: a disabled rule is allowed to declare nothing — it exists to switch a global off and to say why.
+  if (proofs.length === 0 && enabled) {
+    return fail("no `require:` proof, so nothing could ever satisfy this rule");
+  }
+
+  return {
+    rule: {
+      name: source.name,
+      tier: source.tier,
+      enabled,
+      on: trigger,
+      require: proofs,
+      otherwise: verdictRaw.trim() as RuleVerdict,
+      body: doc.body,
+    },
+  };
+}
+
+/**
+ * Both tiers apply. A project rule of the same name replaces the global one, which is how the lesson tiers
+ * already behave — union, deduplicated by id, nearer tier winning
+ * ([/decisions/ad-040.md](/decisions/ad-040.md)). Writing the same rule once per repository is the friction this
+ * removes.
+ *
+ * invariant: a rule switched off is kept, in `disabled`, so `doctor` can say which global a project turned off
+ * rather than leaving the operator to guess why nothing fired.
+ */
+export function buildRuleSet(sources: readonly RuleSource[]): RuleSet {
+  const byName = new Map<string, Rule>();
+  const errors: RuleError[] = [];
+
+  for (const tier of ["global", "project"] as const) {
+    for (const source of sources.filter((candidate) => candidate.tier === tier)) {
+      const parsed = parseRule(source);
+      if ("error" in parsed) {
+        errors.push(parsed.error);
+        continue;
+      }
+      byName.set(parsed.rule.name, parsed.rule);
+    }
+  }
+
+  const all = [...byName.values()];
+  return {
+    rules: all.filter((rule) => rule.enabled),
+    disabled: all.filter((rule) => !rule.enabled),
+    errors,
+  };
+}

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);
+}