@tech-leads-club/harness-toolkit 0.10.2 → 0.10.3

package/docs/concepts.md

@@ -336,6 +336,13 @@ subcommands are refused from inside a session.
 `since HEAD` compares the sha the observation was made against with the current one, so a review followed by
 another commit is stale. A project with no git checkout cannot satisfy `since HEAD` at all.
 
+A denial says which of two things happened: nothing of that kind and value was ever observed here (a flat
+`missing …`), or it was, just not inside the window (`missing … (ran, but at a different commit)` /
+`(ran, but in a different session)` / `(ran, but this project is not a git checkout, so since HEAD can never
+be satisfied)`). The first of those three is common with more than one branch checked out of the same working
+directory in turn — the proof is real, it is just stamped against whichever commit was checked out when it
+ran, not the one the current command has in mind.
+
 Each proof kind matches differently — picking the wrong one for what you actually want to check is the
 most common way a new rule reads as protection and is not:
 

package/docs/log.md

@@ -20,6 +20,7 @@ newest first. For what landed in which npm release, see `CHANGELOG.md` at the re
 - **AD-116** — push and gh pr create run the stop-time battery before shipping, identically on every provider ([/decisions/ad-116.md](/decisions/ad-116.md))
 - **AD-117** — turn_base_sha resolves sha from the event's own working directory, not the project root ([/decisions/ad-117.md](/decisions/ad-117.md))
 - **AD-118** — pr-open does not fire on a draft, so a proof needing the pull request to exist has a way to run ([/decisions/ad-118.md](/decisions/ad-118.md))
+- **AD-119** — A rule's denial says whether the proof never ran or ran outside the window ([/decisions/ad-119.md](/decisions/ad-119.md))
 
 ## 2026-08-26
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tech-leads-club/harness-toolkit",
-  "version": "0.10.2",
+  "version": "0.10.3",
   "type": "module",
   "description": "Multi-provider agent steering: gates, follow-up, handoff, policy",
   "keywords": [

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

@@ -84,17 +84,43 @@ export function proofSatisfied(
   );
 }
 
+/**
+ * why this exists at all: "missing" reads the same whether the thing never ran or it ran and the window rejected
+ * it, and only one of those is a config-side fact worth stating rather than a guess. The fact is cheap and always
+ * true — an observation of this kind and value exists — so it is stated whenever it holds
+ * ([/decisions/ad-060.md](/decisions/ad-060.md)'s own distinction between a fact and a diagnosis).
+ */
+function staleReason(proof: RuleProof, context: ProofContext): string {
+  if (proof.since === "session") {
+    return "ran, but in a different session";
+  }
+  return context.sha === null
+    ? "ran, but this project is not a git checkout, so since HEAD can never be satisfied"
+    : "ran, but at a different commit";
+}
+
+export type MissingProof = { proof: RuleProof; reason: string | null };
+
 /** 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));
+): MissingProof[] {
+  return rule.require
+    .filter((proof) => !proofSatisfied(proof, observations, context))
+    .map((proof) => ({
+      proof,
+      reason: observations.some((observation) => valueMatches(proof, observation))
+        ? staleReason(proof, context)
+        : null,
+    }));
 }
 
-export function proofLabel(proof: RuleProof): string {
-  return `${proof.kind}(${proof.value}) since ${proof.since === "head" ? "HEAD" : "session"}`;
+export function proofLabel(missing: MissingProof): string {
+  const { proof, reason } = missing;
+  const base = `${proof.kind}(${proof.value}) since ${proof.since === "head" ? "HEAD" : "session"}`;
+  return reason === null ? base : `${base} (${reason})`;
 }
 
 /**