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

package/docs/concepts.md

@@ -336,6 +336,45 @@ 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:
+
+| proof | what it names | how it matches |
+|---|---|---|
+| `subagent(<type>)` | the *declared type* of a spawn that finished, not the name the spawning agent gave it | exact string |
+| `command(<pattern>)` | a shell command that ran and did not fail | the pattern's words, in order, as a contiguous run inside the command — `command(gh pr create)` matches `gh pr create --fill`, not `gh api pulls`|
+| `gate(<name>)` | one of this harness's own gates *passing* — never just running | exact string; the only names a gate ever reports are `lint`, `test`, `docs` |
+| `file(<pattern>)` | a file edited by a write tool | exact path, **or** `*<suffix>` (a leading `*`, matched against the path's end), **or** `<dir>/` (a trailing `/`, matched as a prefix) — three shapes, not a glob engine |
+
+One example per kind (shown separately — `require:` is a conjunction; listing more than one demands
+all of them):
+
+```
+require:
+  - subagent(<type>) since HEAD      # a spawn declaring exactly <type> finished
+  - command(<pattern>) since session # a shell command containing <pattern>, in order, ran this session
+  - gate(<name>) since HEAD          # this harness's own <name> gate passed at the current HEAD
+  - file(<pattern>) since HEAD       # a file matching <pattern> was edited since HEAD
+```
+
+**A `subagent(<type>)` proof needs the host to let the agent declare an arbitrary type when it spawns
+one.** Some hosts only offer a closed set of built-in spawn types and cannot declare a custom name at
+all — a rule naming one there never has a producer and denies forever, not because the work never ran
+but because the host has no way to say which custom kind ran (Cursor's `Task` tool is one example: its
+type field is a fixed enum, not a free string, so a custom skill name can never appear there no matter
+what the skill itself is called). A rule meant to hold on every host the operator actually uses should
+prove itself with something every host can produce identically: `command(<the work's own command>)` —
+the exact command the work already runs to do its job — is the portable choice, because running a
+command is not a closed set the way declaring a spawn's type can be. `subagent(<type>)` is the right
+proof only when every host the rule has to survive on can actually declare that type.
+
 The four verdicts land differently at the two moments a rule can fire:
 
 | verdict | on an action | at the stop |
@@ -356,6 +395,12 @@ A pattern trigger is policy rather than containment. A script written to disk an
 built at runtime, `gh api` instead of `gh pr create`, or a pull request opened in a browser all escape it — the
 rule covers the agent's shell path ([/decisions/ad-100.md](/decisions/ad-100.md)).
 
+`pr-open` does not fire on opening a **draft** pull request — only on a non-draft create and on converting a
+draft to ready. This matters when a `require:` proof itself depends on the pull request already existing (a
+review step that reads the diff through the PR, for instance): open the draft first, satisfy the proof against
+it, then convert it to ready, which is still gated the same way
+([/decisions/ad-118.md](/decisions/ad-118.md)).
+
 ## plan gate
 
 `planGate.enabled` (off by default), with `planGate.windowMinutes` (default 120). The turn declares the paths

package/docs/log.md

@@ -19,6 +19,8 @@ newest first. For what landed in which npm release, see `CHANGELOG.md` at the re
 - **AD-115** — A comment violation refuses commit, push and gh pr create, not only the stop ([/decisions/ad-115.md](/decisions/ad-115.md))
 - **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.1",
+  "version": "0.10.3",
   "type": "module",
   "description": "Multi-provider agent steering: gates, follow-up, handoff, policy",
   "keywords": [

package/skills/harness-init/SKILL.md

@@ -164,22 +164,32 @@ The vocabulary is closed, so read it out rather than inventing terms:
 
 ```
 on:         pr-open | commit | push | stop | tool(<name>) | command(<pattern>)
-require:    subagent(<type>) | command(<pattern>) | gate(<name>) | file(<glob>)
+require:    subagent(<type>) | command(<pattern>) | gate(<name>) | file(<pattern>)
             each since HEAD (default) or since session
 otherwise:  deny | ask | follow-up | warn
 ```
 
 A rule is one file in `<repo>/.tlc/harness/rules/<name>.md` for the team, or in the runtime home's `rules/` for
 every repository on this machine. The frontmatter is enforced; the body is their own text, injected verbatim when
-the rule fires. Full grammar and the verdict matrix: `tlc harness help rules`.
+the rule fires. Full grammar, exact matching semantics per proof kind, and the verdict matrix:
+`tlc harness help rules`.
 
-Two things to say out loud, because both surprise people later:
+Four things to say out loud, because all four surprise people later:
 
 - **The proof has to be something the harness observed** — a subagent that ran, a command that completed, a gate
   that passed, a file that changed. It cannot judge whether the review was any good, and the agent cannot create
   a proof: that store is under the project state directory, which the floor refuses it.
 - **`since HEAD` means a new commit makes an old proof stale**, and a project with no git checkout cannot satisfy
   `since HEAD` at all.
+- **`subagent(<type>)` only holds on a host that lets the agent declare an arbitrary custom type.** A host with a
+  closed set of built-in spawn types (Cursor's `Task` tool, for one) can never produce a match for a custom name,
+  no matter what the actual work is called — the rule denies forever, not because nothing ran but because the
+  host cannot say which kind ran. If the rule has to hold on more than one host, ask what command the work itself
+  runs to do its job and require that instead: `command(<pattern>)` is producible identically everywhere.
+- **`on: pr-open` does not fire on opening a draft pull request** — only on a non-draft create and on
+  converting a draft to ready. If the requirement itself needs the pull request to already exist (a proof that
+  reads the diff through the PR, for one), have them open the draft, satisfy the proof against it, then convert
+  it to ready — still gated the same way.
 
 If they accept the capability but have no requirement in mind, write `rules.enabled: false` and say why — a switch
 with no file is the shape that looks like protection and is not.

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})`;
 }
 
 /**

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

@@ -27,13 +27,24 @@ export type TriggerContext = {
  * 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[][]> = {
+type ShellShape = {
+  readonly prefix: readonly string[];
+  /**
+   * why this exists only on `gh pr create`: a draft is not yet open for review, so a rule gating `pr-open`
+   * has no work to demand proof of. It is also the only way a proof that itself depends on the pull request
+   * existing — `gh pr view`, for one — can ever run: open the draft, produce the proof against it, then
+   * `gh pr ready`, which keeps its own gate ([/decisions/ad-118.md](/decisions/ad-118.md)).
+   */
+  readonly excludeIfAny?: readonly string[];
+};
+
+const SHELL_SHAPES: Record<"pr-open" | "commit" | "push", readonly ShellShape[]> = {
   "pr-open": [
-    ["gh", "pr", "create"],
-    ["gh", "pr", "ready"],
+    { prefix: ["gh", "pr", "create"], excludeIfAny: ["--draft", "-d"] },
+    { prefix: ["gh", "pr", "ready"] },
   ],
-  commit: [["git", "commit"]],
-  push: [["git", "push"]],
+  commit: [{ prefix: ["git", "commit"] }],
+  push: [{ prefix: ["git", "push"] }],
 };
 
 /**
@@ -53,8 +64,15 @@ function subCommands(command: string): string[][] {
 }
 
 /** 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);
+function startsWithShape(words: readonly string[], prefix: readonly string[]): boolean {
+  return prefix.every((token, index) => words[index] === token);
+}
+
+function matchesShape(words: readonly string[], shape: ShellShape): boolean {
+  if (!startsWithShape(words, shape.prefix)) {
+    return false;
+  }
+  return !shape.excludeIfAny?.some((flag) => words.includes(flag));
 }
 
 /**
@@ -82,9 +100,7 @@ export function triggerMatches(trigger: RuleTrigger, context: TriggerContext): b
         return false;
       }
       const shapes = SHELL_SHAPES[trigger.kind];
-      return subCommands(context.command).some((words) =>
-        shapes.some((shape) => startsWithShape(words, shape)),
-      );
+      return subCommands(context.command).some((words) => shapes.some((shape) => matchesShape(words, shape)));
     }
     default: {
       if (context.command === undefined) {