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

package/README.md

@@ -39,7 +39,7 @@
 <p align="center">
   Hooks fire on the editor's own events. The harness answers each one with a decision — <b>allow</b>, <b>ask</b>,
   <b>deny</b>, or text injected into the turn — and writes a record of what it decided and why.
-  <b>7 floor rules</b> no configuration can reach, <b>3 always-on checks</b>, and <b>23 rails</b> you choose.
+  <b>7 floor rules</b> no configuration can reach, <b>3 always-on checks</b>, and <b>24 rails</b> you choose.
 </p>
 
 - **[Everything it validates](#everything-it-validates)** — the whole list, one row per check
@@ -91,9 +91,9 @@ Three tiers, and which tier a check is in decides whether you can turn it off.
 |------|-------|--------------|------|
 | [Floor](#tier-1--the-floor-no-configuration-reaches-it) | 7 rules | Never | Before any policy is loaded, on every tool call, shell command and read |
 | [Always on](#tier-2--always-on-no-switch) | 3 checks | Never | After the floor, on every acting event |
-| [Rails](#tier-3--the-rails-you-choose) | 23 capabilities | Each one, individually | Where the table says |
+| [Rails](#tier-3--the-rails-you-choose) | 24 capabilities | Each one, individually | Where the table says |
 
-Nothing else runs. If a message on your screen is not from one of the thirty-three rows below, it is not the
+Nothing else runs. If a message on your screen is not from one of the thirty-four rows below, it is not the
 harness.
 
 ### Tier 1 — the floor, no configuration reaches it
@@ -135,7 +135,7 @@ otherwise switch off.
 
 ### Tier 3 — the rails you choose
 
-All 23 are off unless the **default** column says `on`, and each was presented with its benefit and its
+All 24 are off unless the **default** column says `on`, and each was presented with its benefit and its
 trade-off when you ran the init wizard. `configPath` is the key in `.tlc/harness/config.json`.
 
 <!-- generated:validates -->
@@ -165,6 +165,7 @@ trade-off when you ran the init wizard. `configPath` is the key in `.tlc/harness
 | **Untrusted-content framing and enforcement**<br>`untrustedContent.enabled` · off | Frames outside content as data, and in enforce mode asks before a command that appears verbatim in it. | `tool.after` | `context` | tlc harness obs report — one framing injection per turn, with the characters it cost |
 | **Plan gate (declared scope vs diff)**<br>`planGate.enabled` · off | Checks the files the turn changed against the scope it declared, and against any stated deviation. | `response.after`<br>`stop` | `block-stop` | tlc harness handoff — plan_paths, plan_at and plan_deviations |
 | **Observation mode (measure a rail with its rule off)**<br>`observe.enabled` · off | Runs a rail's checker while that rail is not enforcing, and records the reading without acting on it. | `stop`<br>`session.end` | `record` | tlc harness obs report — the observation readings, held apart from the refusal counters so those stay honest |
+| **Operator rules (your trigger, your proof)**<br>`rules.enabled` · off | Reads the rules you declare in markdown and enforces them: on this trigger, this must have happened. | `tool.before`<br>`stop` | `deny` | tlc harness doctor — each active rule, its tier, and any proof kind never observed here |
 
 <!-- /generated -->
 
@@ -275,15 +276,50 @@ each provider it finds, because a provider only reads its own.
 
 1. Materialises the runtime at `~/.tlc/harness` from the installed package
 2. Creates `config.json` from `config.example.json` when missing
-3. Adds `tlc` to `~/.local/bin`
-4. Links the init skill into each detected provider's `skills/harness-init`
-5. Wires user-level hooks for every provider it detects installed, in that provider's resolved config
+3. Links the init skill into each detected provider's `skills/harness-init`
+4. Wires user-level hooks for every provider it detects installed, in that provider's resolved config
    directory
 
+The `tlc` command itself comes from npm, not from this step: `npm i -g` generates the shim for the platform it
+runs on, and `npm link` does the same from a clone. If `tlc` is not found after installing, the shim is in the
+`bin` directory of the Node version npm installed under — which is not on `PATH` when a version manager later
+switches versions. A link solves it for good:
+
+```bash
+ln -s ~/.tlc/harness/bin/tlc ~/.local/bin/tlc
+```
+
 Update with `tlc harness update`, which bumps the package and re-materialises the runtime.
 
 Overrides: `TLC_HOME`, `TLC_REPO_URL`, `TLC_BIN_DIR`.
 
+### Running a development copy
+
+The runtime that answers a hook is whichever one `TLC_HOME` names, and it wins over the location of the launcher
+that was invoked. So a checkout can be exercised without touching the machine's install:
+
+```bash
+# one command against the checkout
+TLC_HOME=/path/to/clone tlc harness doctor
+
+# a whole editor session on the checkout — everything else on the machine stays on the installed copy
+export TLC_HOME=/path/to/clone
+cursor .
+```
+
+Two things worth knowing before doing that:
+
+- **A checkout serves its hooks from source.** With Bun present the launcher runs `src/` directly, so a file saved
+  half-edited is live on the next hook — in that session only. Nothing needs building first, and nothing protects
+  you from a syntax error either.
+- **Do not install a clone with `--link` as the machine's runtime** unless you accept that your working tree *is*
+  what every session on the machine runs. That is the contributor route, and it is why `doctor` reports it
+  distinctly (`runtime ownership — link to a working clone`).
+
+Neither of those applies to the ordinary route: `tlc harness test` runs the whole gate hermetically, and the
+entrypoints can be driven with real hook payloads from a scratch directory, so most work needs no live session at
+all.
+
 Provider config directories are resolved, not assumed: `CLAUDE_CONFIG_DIR` and `CURSOR_CONFIG_DIR` are
 honoured when set, so a relocated config is wired correctly. `tlc harness doctor` prints the resolved
 target for each provider.
@@ -415,7 +451,7 @@ See `tlc harness help architecture` or [`docs/architecture.md`](docs/architectur
 | `tlc harness lessons list` | Lessons across the three tiers, with staleness and effectiveness |
 | `tlc harness lessons add "…" [--ref path:symbol] [--global] [--pin]` | Write a lesson; `--ref` retires it when that stops resolving, `--pin` puts it ahead of ranking |
 | `tlc harness policy` / `policy accept <path>` | List a mid-session policy change; accept exactly those paths |
-| `tlc harness init --minimal` | Project stub |
+| `tlc harness init --minimal` | A project config that decides nothing; an existing one is kept |
 
 ## Connect a project
 

package/bin/tlc-cli.ts

@@ -12,9 +12,11 @@ import {
 import { delimiter, join } from "node:path";
 import { coreFacade } from "../src/core/index.ts";
 import { emitJson, JSON_FLAG, takeJsonFlag, unknownFlags } from "../src/platform/cli-output.ts";
-import { linkDir, seedConfig } from "../src/platform/links.ts";
+import { linkDir, linkFile, seedConfig } from "../src/platform/links.ts";
 import {
   flagsDir,
+  isOnPath,
+  launcherBinDir,
   projectConfigPath,
   projectStateDir,
   providerConfigDirs,
@@ -977,6 +979,41 @@ export function npmRootFailureMessage(home: string): string {
  *
  * invariant: one function, no platform branch, and the launcher on PATH is npm's business.
  */
+/**
+ * The `tlc` command on `PATH`.
+ *
+ * hazard: install never created this. `uninstall` removed it, `doctor` failed without it, and the README claimed
+ * install added it — three halves of a thing that did not exist. The command came from npm's own shim instead,
+ * which lives in the `bin` directory of whichever Node version npm ran under and leaves `PATH` the moment a
+ * version manager switches. Measured on an operator's machine: a successful install followed immediately by
+ * `tlc: command not found` ([/decisions/ad-101.md](/decisions/ad-101.md)).
+ *
+ * invariant: never fatal. A link is a convenience — npm's shim is still there — so a refusal is reported and the
+ * install continues.
+ *
+ * why the `PATH` check is separate from the link: a link nobody can reach is worse than none, because `doctor`
+ * then reports it healthy while the command still does not exist.
+ */
+export function launcherLines(dest: string): string[] {
+  const dir = launcherBinDir();
+  const source = join(dest, "bin", "tlc");
+  // hazard: `symlinkSync` happily creates a link to a path that is not there, and `existsSync` on a dangling link
+  // is false — so a broken launcher would report as linked and `doctor` would say no `tlc` on PATH with a healthy
+  // install beside it. Found by the test for this function ([/decisions/ad-101.md](/decisions/ad-101.md)).
+  if (!existsSync(source)) {
+    return [`tlc not linked — ${source} is missing from the runtime`];
+  }
+  const outcome = linkFile(source, join(dir, "tlc"));
+  if (outcome.kind === "refused") {
+    return [`tlc not linked — ${outcome.reason}`];
+  }
+  const lines = [`tlc → ${outcome.target}`];
+  if (!isOnPath(dir)) {
+    lines.push(`${dir} is not on PATH — add it, or use the shim npm installed`);
+  }
+  return lines;
+}
+
 export function wireRuntime(dest: string, home: string): { lines: string[]; missingSkill: boolean } {
   const lines: string[] = [];
   const seeded = seedConfig(dest);
@@ -999,6 +1036,8 @@ export function wireRuntime(dest: string, home: string): { lines: string[]; miss
     );
   }
 
+  lines.push(...launcherLines(dest));
+
   const hooks = spawnSync(process.execPath, [join(dest, "bin", "write-user-hooks.mjs")], {
     stdio: "inherit",
     env: { ...process.env, TLC_HOME: home },

package/bin/tlc-exec.d.mts

@@ -58,3 +58,4 @@ export type RuntimeDecision =
 export function decideRuntime(input: RuntimeDecisionInput): RuntimeDecision;
 
 export function main(argv?: string[]): void;
+export const HOOK_ENTRIES: Set<string>;

package/bin/tlc-exec.mjs

@@ -153,6 +153,44 @@ export function resolveEntrySource(harnessHome, entry) {
   return null;
 }
 
+/**
+ * The entries that answer a host hook, as opposed to the ones an operator runs.
+ *
+ * why the distinction: a hook that cannot run must not stand between the agent and its tools, and a command that
+ * cannot run must fail loudly or the operator and CI lose the signal. Same launcher, opposite duties
+ * ([/decisions/ad-101.md](/decisions/ad-101.md)).
+ *
+ * invariant: this list is checked against `src/entrypoints/` by the gate, so an entrypoint added later cannot be
+ * left out of it — a hook missing from here fails closed, which is the direction that blocks a working machine.
+ */
+export const HOOK_ENTRIES = new Set([
+  "compact-before",
+  "prompt-submit",
+  "response-after",
+  "session-end",
+  "session-start",
+  "stop",
+  "subagent-start",
+  "subagent-stop",
+  "tool-after",
+  "tool-before",
+  "tool-failure",
+]);
+
+/**
+ * No opinion, in the shape both hosts read as "carry on".
+ *
+ * why `{}` rather than nothing: measured against both providers' own renderers, an abstain is `{}` on stdout for
+ * Cursor and empty for Claude, and `{}` satisfies both — Claude parses it as a verdict with no decision. A broken
+ * runtime used to emit nothing at all with exit 1, which Claude treats as a non-blocking error and Cursor's
+ * contract does not describe. A harness that cannot run was protecting nothing, so it must not be the thing that
+ * stops the turn ([/decisions/ad-101.md](/decisions/ad-101.md)).
+ */
+function carryOn() {
+  process.stdout.write("{}");
+  process.exit(0);
+}
+
 export function decideRuntime({ harnessHome, entry, bunPath, nodeMajor, distExists, srcPath }) {
   const distPath = join(harnessHome, "dist", `${entry}.mjs`);
   if (bunPath && srcPath && distExists) {
@@ -196,7 +234,7 @@ export function decideRuntime({ harnessHome, entry, bunPath, nodeMajor, distExis
   };
 }
 
-function run(harnessHome, command, commandArgs, origin = harnessHome) {
+function run(harnessHome, command, commandArgs, origin = harnessHome, entry = "") {
   const result = spawnSync(command, commandArgs, {
     stdio: "inherit",
     // why: `TLC_ORIGIN` is where this copy physically lives, which is not `TLC_HOME` once an npm-installed shim
@@ -216,6 +254,9 @@ function run(harnessHome, command, commandArgs, origin = harnessHome) {
   });
   if (result.error) {
     console.error(`tlc: failed to start ${command}: ${result.error.message}`);
+    if (HOOK_ENTRIES.has(entry)) {
+      carryOn();
+    }
     process.exit(127);
   }
   process.exit(result.status ?? 1);
@@ -240,10 +281,14 @@ export function main(argv = process.argv) {
 
   const decision = decideRuntime({ harnessHome, entry, bunPath, nodeMajor, distExists, srcPath });
   if (decision.kind === "error") {
+    // invariant: the diagnosis still reaches stderr either way. Failing open is not failing silently.
     console.error(decision.message);
+    if (HOOK_ENTRIES.has(entry)) {
+      carryOn();
+    }
     process.exit(decision.status);
   }
-  run(harnessHome, decision.command, [...decision.args, ...args], join(binDir, ".."));
+  run(harnessHome, decision.command, [...decision.args, ...args], join(binDir, ".."), entry);
 }
 
 if (import.meta.main) {

package/capabilities/catalog.json

@@ -1,5 +1,5 @@
 {
-  "catalogVersion": 13,
+  "catalogVersion": 14,
   "capabilities": [
     {
       "id": "grind",
@@ -7,14 +7,14 @@
       "title": "Grind (lint/test on stop)",
       "summary": "Runs your lint and test commands against the files the turn changed, and sends the agent back until they pass.",
       "benefit": "Re-checks lint/test after each completed turn and follow-ups until gates pass.",
-      "tradeOff": "Uses turns; flaky commands thrash the agent. The gate's cost is paid once per attempt, up to maxLoops — a four-minute suite with maxLoops 5 can spend twenty minutes on tests alone. tlc harness obs report shows the runs and the total.",
+      "tradeOff": "Uses turns; flaky commands thrash the agent. The gate's cost is paid once per attempt, up to maxLoops \u2014 a four-minute suite with maxLoops 5 can spend twenty minutes on tests alone. tlc harness obs report shows the runs and the total.",
       "defaultOn": false,
       "sinceCatalogVersion": 1,
       "fires": [
         "stop"
       ],
       "verdict": "follow-up",
-      "inspect": "tlc harness obs report — runs, wall-clock and total; the last verdict is in the project state directory as last-gate.json",
+      "inspect": "tlc harness obs report \u2014 runs, wall-clock and total; the last verdict is in the project state directory as last-gate.json",
       "asks": [
         "lintCommand",
         "testCommand",
@@ -56,7 +56,7 @@
         "stop"
       ],
       "verdict": "block-stop",
-      "inspect": "the ship ledger in the project state directory — the challenge row names the empty diff",
+      "inspect": "the ship ledger in the project state directory \u2014 the challenge row names the empty diff",
       "asks": [
         "requires shipGate enabled"
       ]
@@ -67,14 +67,14 @@
       "title": "Comment gate (agent-added comments)",
       "summary": "Checks the comment lines this turn added against the commit the turn started from: by reason, by resolvability, or none.",
       "benefit": "Blocks the stop when this turn added comment lines, so narration never lands. Diff-scoped: comments you already committed are never flagged.",
-      "tradeOff": "Three modes. declared lets the agent keep a comment by writing why:/hazard:/invariant:; resolvable adds the question the marker cannot answer — can a reader who was not in the session check this? — and catches change narration, dead plan or decision citations, and comments arguing with a reviewer; strict accepts none and asks you to write it instead. Each is stricter and interrupts more.",
+      "tradeOff": "Three modes. declared lets the agent keep a comment by writing why:/hazard:/invariant:; resolvable adds the question the marker cannot answer \u2014 can a reader who was not in the session check this? \u2014 and catches change narration, dead plan or decision citations, and comments arguing with a reviewer; strict accepts none and asks you to write it instead. Each is stricter and interrupts more.",
       "defaultOn": false,
       "sinceCatalogVersion": 1,
       "fires": [
         "stop"
       ],
       "verdict": "block-stop",
-      "inspect": "tlc harness obs report — the comments gate appears among the gate outcomes",
+      "inspect": "tlc harness obs report \u2014 the comments gate appears among the gate outcomes",
       "asks": [
         "mode: declared | resolvable | strict"
       ]
@@ -85,14 +85,14 @@
       "title": "Duplication gate (agent-added copies)",
       "summary": "Checks whether the runs of code this turn added already exist somewhere else in the project.",
       "benefit": "Blocks the stop when the turn wrote six or more lines the project already has, naming both sites. Diff-scoped: what was already duplicated is not counted.",
-      "tradeOff": "Reads every tracked file on stop, bounded at 2000 files and 8 MB, and says when a bound was reached. Comments, dependency declarations and pure data — object literals, type bodies, export lists — are excluded, so it reports duplicated logic and misses duplicated shape.",
+      "tradeOff": "Reads every tracked file on stop, bounded at 2000 files and 8 MB, and says when a bound was reached. Comments, dependency declarations and pure data \u2014 object literals, type bodies, export lists \u2014 are excluded, so it reports duplicated logic and misses duplicated shape.",
       "defaultOn": false,
       "sinceCatalogVersion": 11,
       "fires": [
         "stop"
       ],
       "verdict": "block-stop",
-      "inspect": "tlc harness obs report — the duplication gate appears among the gate outcomes",
+      "inspect": "tlc harness obs report \u2014 the duplication gate appears among the gate outcomes",
       "asks": [
         "minRun: lines a run must reach before two copies count (default 6)"
       ]
@@ -103,14 +103,14 @@
       "title": "Supply-chain gate (dependencies this turn added)",
       "summary": "Checks what this turn added to the dependency graph: a manifest that moved without its lock, or an unpinned version.",
       "benefit": "Blocks the stop when a dependency added this turn is not recorded in a lockfile, or is specified as latest/*/no version. A dependency added in a turn runs on every later turn, in CI, and on every machine that installs the project.",
-      "tradeOff": "Recognises a manifest by filename from one table, so an ecosystem the table does not carry is not covered. For a JSON manifest the declared dependency sections decide, so it reads the manifest as it stands — without that, a rename or a scripts entry reads as a dependency. It does not check advisories, licences or typosquats: those need the network on every stop.",
+      "tradeOff": "Recognises a manifest by filename from one table, so an ecosystem the table does not carry is not covered. For a JSON manifest the declared dependency sections decide, so it reads the manifest as it stands \u2014 without that, a rename or a scripts entry reads as a dependency. It does not check advisories, licences or typosquats: those need the network on every stop.",
       "defaultOn": false,
       "sinceCatalogVersion": 12,
       "fires": [
         "stop"
       ],
       "verdict": "block-stop",
-      "inspect": "tlc harness obs report — the supply-chain gate appears among the gate outcomes",
+      "inspect": "tlc harness obs report \u2014 the supply-chain gate appears among the gate outcomes",
       "asks": []
     },
     {
@@ -119,7 +119,7 @@
       "title": "Subagent allowlist",
       "summary": "Checks a subagent's model against the list you wrote, and against the blocked *-fast shapes.",
       "benefit": "Restricts Task/subagent models to a list you write, and blocks *-fast shapes by default.",
-      "tradeOff": "The harness ships no model list, so switching this on without filling allowedModels enforces nothing and doctor reports it as a fault. You maintain the list as providers add models — including a value for `inherit` if you want subagents to take the parent's model.",
+      "tradeOff": "The harness ships no model list, so switching this on without filling allowedModels enforces nothing and doctor reports it as a fault. You maintain the list as providers add models \u2014 including a value for `inherit` if you want subagents to take the parent's model.",
       "defaultOn": false,
       "sinceCatalogVersion": 1,
       "fires": [
@@ -127,7 +127,7 @@
         "subagent.start"
       ],
       "verdict": "deny",
-      "inspect": "tlc harness obs report — refusals attributed by rule; the denial text names subagents.allowedModels and lists what is permitted",
+      "inspect": "tlc harness obs report \u2014 refusals attributed by rule; the denial text names subagents.allowedModels and lists what is permitted",
       "asks": [
         "allowedModels",
         "requireModel",
@@ -148,7 +148,7 @@
         "subagent.start"
       ],
       "verdict": "deny",
-      "inspect": "tlc harness obs report — refusals by rule; tlc harness status shows the sticky parent model it read",
+      "inspect": "tlc harness obs report \u2014 refusals by rule; tlc harness status shows the sticky parent model it read",
       "recommend": "on"
     },
     {
@@ -164,7 +164,7 @@
         "shell.before"
       ],
       "verdict": "deny",
-      "inspect": "tlc harness obs report — interruptions attributed to the shell-stall rule",
+      "inspect": "tlc harness obs report \u2014 interruptions attributed to the shell-stall rule",
       "asks": [
         "stallRepeatThreshold (default 3)"
       ]
@@ -174,7 +174,7 @@
       "configPath": "shell.catastrophicAsk",
       "title": "Catastrophic shell ask",
       "summary": "Checks a shell command for destruction that reaches outside the workspace.",
-      "benefit": "Asks before destructive shell commands (rm -rf, drop db, force push, …).",
+      "benefit": "Asks before destructive shell commands (rm -rf, drop db, force push, \u2026).",
       "tradeOff": "Extra prompts on risky commands.",
       "defaultOn": true,
       "sinceCatalogVersion": 1,
@@ -182,7 +182,7 @@
         "shell.before"
       ],
       "verdict": "ask",
-      "inspect": "tlc harness obs report — interruptions attributed to the shell-catastrophic rule",
+      "inspect": "tlc harness obs report \u2014 interruptions attributed to the shell-catastrophic rule",
       "recommend": "on"
     },
     {
@@ -191,7 +191,7 @@
       "title": "Lessons",
       "summary": "Records what a repeated gate failure taught, ranks it, and injects it into the next session and retry.",
       "benefit": "Records compact lessons on gate stagnation and reinjects them ranked under a char budget. A lesson can name the path or symbol that makes it true and is withheld once that stops resolving, can carry an end date, and is graded helped or neutral by the next run of the gate it was injected for. Three tiers: shipped core, a global tier read by every product on this machine, and this project's own. How the lessons reach the model is decided by the provider rather than configured: where a host does not deliver context returned from its session-start hook, a durable rules file is written instead.",
-      "tradeOff": "Uses context tokens; not a second brain / chat memory. The grading is correlational, not causal — a gate passing after a lesson was injected does not prove the lesson caused it. Nothing is promoted between products automatically, so carrying a lesson to another product is an operator command. On a host that needs the durable view, a file is written into the repo (`.cursor/rules/harness-lessons.mdc`) and asked to be included on every request; `syncRulesFile: never` declines it.",
+      "tradeOff": "Uses context tokens; not a second brain / chat memory. The grading is correlational, not causal \u2014 a gate passing after a lesson was injected does not prove the lesson caused it. Nothing is promoted between products automatically, so carrying a lesson to another product is an operator command. On a host that needs the durable view, a file is written into the repo (`.cursor/rules/harness-lessons.mdc`) and asked to be included on every request; `syncRulesFile: never` declines it.",
       "defaultOn": false,
       "sinceCatalogVersion": 1,
       "fires": [
@@ -200,7 +200,7 @@
         "session.end"
       ],
       "verdict": "context",
-      "inspect": "tlc harness lessons list — every tier with staleness and effectiveness; obs report shows the characters each injection cost",
+      "inspect": "tlc harness lessons list \u2014 every tier with staleness and effectiveness; obs report shows the characters each injection cost",
       "asks": [
         "maxInjectSession",
         "maxCharsSession",
@@ -227,7 +227,7 @@
         "stop"
       ],
       "verdict": "follow-up",
-      "inspect": "tlc harness handoff — the follow-up fires only with unfinished work recorded there",
+      "inspect": "tlc harness handoff \u2014 the follow-up fires only with unfinished work recorded there",
       "asks": [
         "budgetContinueAfterLoops"
       ]
@@ -245,7 +245,7 @@
         "stop"
       ],
       "verdict": "follow-up",
-      "inspect": "tlc harness handoff — the gaps it injects are the ones stored as previous_gaps"
+      "inspect": "tlc harness handoff \u2014 the gaps it injects are the ones stored as previous_gaps"
     },
     {
       "id": "failureClassification",
@@ -260,7 +260,7 @@
         "stop"
       ],
       "verdict": "record",
-      "inspect": "tlc harness handoff — last_failure_category"
+      "inspect": "tlc harness handoff \u2014 last_failure_category"
     },
     {
       "id": "progressiveHandoff",
@@ -268,14 +268,14 @@
       "title": "Progressive handoff",
       "summary": "Reads the gaps the previous session ended with back out at the next session's start.",
       "benefit": "Carries the gaps the previous session ended with into the next session's bootstrap, as history rather than as a task list.",
-      "tradeOff": "Spends session-start context on a verdict that may already be stale — only the next run of the gate says whether it still holds. Capped at five, and the rest are counted rather than dropped in silence.",
+      "tradeOff": "Spends session-start context on a verdict that may already be stale \u2014 only the next run of the gate says whether it still holds. Capped at five, and the rest are counted rather than dropped in silence.",
       "defaultOn": true,
       "sinceCatalogVersion": 1,
       "fires": [
         "session.start"
       ],
       "verdict": "context",
-      "inspect": "tlc harness handoff — the gaps it reads back out are previous_gaps"
+      "inspect": "tlc harness handoff \u2014 the gaps it reads back out are previous_gaps"
     },
     {
       "id": "progressiveContext",
@@ -290,7 +290,7 @@
         "stop"
       ],
       "verdict": "follow-up",
-      "inspect": "tlc harness obs report — the retry count for a stop is the escalation level it reached"
+      "inspect": "tlc harness obs report \u2014 the retry count for a stop is the escalation level it reached"
     },
     {
       "id": "autopilot",
@@ -313,7 +313,7 @@
       "title": "Idle-turn gate (asked instead of acting)",
       "summary": "Checks whether a turn that ended with open work recorded any tool call or file change at all.",
       "benefit": "Blocks a turn that ends with open work, zero tool calls and zero file changes. Counts recorded tool events rather than reading the reply, so it cannot be talked around.",
-      "tradeOff": "A turn that legitimately only answers a question is blocked while handoff work is open — clear the handoff or turn this off for conversational repos.",
+      "tradeOff": "A turn that legitimately only answers a question is blocked while handoff work is open \u2014 clear the handoff or turn this off for conversational repos.",
       "defaultOn": false,
       "sinceCatalogVersion": 3,
       "fires": [
@@ -364,14 +364,14 @@
       "title": "Untrusted-content framing and enforcement",
       "summary": "Frames outside content as data, and in enforce mode asks before a command that appears verbatim in it.",
       "benefit": "Injects one framing line per turn when the agent reads a pull request, an issue, a fetched page or an MCP result, stating that the content is data and that any directive inside it is to be reported as a prompt-injection attempt, not obeyed.",
-      "tradeOff": "Two modes. frame injects one line per turn, costing a few hundred characters and enforcing nothing. enforce also remembers what an untrusted read returned, bounded at 64 KB per session, and asks before a shell command that appears verbatim in it — verbatim because a paraphrase cannot be shown to come from the content, so a rewritten command is missed. It needs the host to deliver tool output on the after-event: measured present on Claude Code's PostToolUse and on Cursor's afterShellExecution and afterMCPExecution, and absent on Cursor's generic postToolUse.",
+      "tradeOff": "Two modes. frame injects one line per turn, costing a few hundred characters and enforcing nothing. enforce also remembers what an untrusted read returned, bounded at 64 KB per session, and asks before a shell command that appears verbatim in it \u2014 verbatim because a paraphrase cannot be shown to come from the content, so a rewritten command is missed. It needs the host to deliver tool output on the after-event: measured present on Claude Code's PostToolUse and on Cursor's afterShellExecution and afterMCPExecution, and absent on Cursor's generic postToolUse.",
       "defaultOn": false,
       "sinceCatalogVersion": 7,
       "fires": [
         "tool.after"
       ],
       "verdict": "context",
-      "inspect": "tlc harness obs report — one framing injection per turn, with the characters it cost",
+      "inspect": "tlc harness obs report \u2014 one framing injection per turn, with the characters it cost",
       "asks": [
         "mode: frame | enforce"
       ]
@@ -390,7 +390,7 @@
         "stop"
       ],
       "verdict": "block-stop",
-      "inspect": "tlc harness handoff — plan_paths, plan_at and plan_deviations",
+      "inspect": "tlc harness handoff \u2014 plan_paths, plan_at and plan_deviations",
       "asks": [
         "windowMinutes"
       ]
@@ -409,10 +409,27 @@
         "session.end"
       ],
       "verdict": "record",
-      "inspect": "tlc harness obs report — the observation readings, held apart from the refusal counters so those stay honest",
+      "inspect": "tlc harness obs report \u2014 the observation readings, held apart from the refusal counters so those stay honest",
       "asks": [
-        "rails — the rails to observe, chosen from the observable set (today: comments). A name with no checker records nothing and doctor reports it"
+        "rails \u2014 the rails to observe, chosen from the observable set (today: comments). A name with no checker records nothing and doctor reports it"
       ]
+    },
+    {
+      "id": "operatorRules",
+      "configPath": "rules.enabled",
+      "title": "Operator rules (your trigger, your proof)",
+      "summary": "Reads the rules you declare in markdown and enforces them: on this trigger, this must have happened.",
+      "benefit": "Turns a standing instruction into a gate. A rule names when it applies, what the harness must have observed, and what to do when it has not \u2014 so 'no pull request without a review' stops depending on the model remembering it.",
+      "tradeOff": "The proof must 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 good, and a pattern trigger is policy rather than containment \u2014 a script written to disk and run later, or a pull request opened in a browser, escape it.",
+      "defaultOn": false,
+      "sinceCatalogVersion": 14,
+      "fires": [
+        "tool.before",
+        "stop"
+      ],
+      "verdict": "deny",
+      "inspect": "tlc harness doctor \u2014 each active rule, its tier, and any proof kind never observed here",
+      "asks": []
     }
   ]
 }