@tech-leads-club/harness-toolkit 0.4.1 → 0.4.3

package/README.md

@@ -65,6 +65,7 @@ To give one project its own rules, open it and say **"setup harness"** to the ag
    - [Tier 1 — the floor](#tier-1--the-floor-no-configuration-reaches-it)
    - [Tier 2 — always on, no switch](#tier-2--always-on-no-switch)
    - [Tier 3 — the rails you choose](#tier-3--the-rails-you-choose)
+   - [One rail takes a rule you write](#one-rail-takes-a-rule-you-write)
 3. [How to see any of it](#how-to-see-any-of-it)
 4. [How to explain a decision](#how-to-explain-a-decision)
 5. [Providers](#providers)
@@ -180,6 +181,46 @@ Each rail's full benefit and trade-off — the long form, as the init wizard rea
 the agent surfaces and what earns an interruption. It switches no gate on and weakens no verification —
 the evidence bar is identical at all three ([`docs/decisions/ad-025.md`](docs/decisions/ad-025.md)).
 
+### One rail takes a rule you write
+
+Every other capability is a switch. **Operator rules** is a switch plus a file, because the trigger and the
+proof are yours: *on this trigger, this must have happened, otherwise do that.* No pull request without a
+review, for instance:
+
+```markdown
+---
+on: pr-open
+require:
+  - subagent(the-jury) since HEAD
+otherwise: deny
+---
+
+Convene the jury on this branch. Checklist: docs/review-checklist.md
+```
+
+Save it as one markdown file per rule in `.tlc/harness/rules/` for this repository, or in the runtime home's
+`rules/` for every repository on this machine, and set `rules.enabled: true`. 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
+— so the agent cannot write one: that store is under the project state directory, which the floor refuses it.
+
+`tlc harness doctor` lists every rule it loaded, and says so when the switch is on and no file was found.
+The full grammar — six triggers, four proof kinds, four verdicts and how each lands at the stop — is
+`tlc harness help rules`.
+
+**Why not the editor's own rules?** Because a rule file there is context, not a gate: activation is a mode
+you pick, always-apply defaults to off, and one of the modes leaves it to the model to decide whether to load
+the rule at all. This is not a replacement for that file — it is the layer underneath it. The editor's rule
+says what the agent should do; this one says what must be provably true before it may.
+
+The fair comparison is with the editors' **hooks**, which are deterministic too. Three things separate them
+from this, taken from their own reference rather than from opinion: there is no prerequisite mechanism and no
+state store, so "X requires Y to have happened" is custom logic you write per event; the state you would keep
+lives in an ordinary repository path the agent can write, while a proof here lives where the floor refuses it;
+and one host's stop hook cannot refuse completion at all, so the same requirement has to mean something
+different on each — which is what the capability table and the degrade step already do. A hook is a program
+per host per repository, fail-open unless it opts out. A rule is five lines of frontmatter, two tiers, both
+hosts ([`docs/decisions/ad-100.md`](docs/decisions/ad-100.md)).
+
 ## How to see any of it
 
 Every row above names a command in its last column. These are those commands.
@@ -276,21 +317,18 @@ 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. 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
+3. Links `tlc` into `~/.local/bin`, and says so if that directory is not on `PATH`
+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
    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.
 
+Every release is published from CI with a short-lived OIDC credential — no token is stored in the repository — and
+carries a provenance attestation you can check on npmjs.com. What gates it is the test suite on four platforms plus
+an install of the packed tarball into a clean container, driven as a real command
+([`docs/decisions/ad-102.md`](docs/decisions/ad-102.md)).
+
 Overrides: `TLC_HOME`, `TLC_REPO_URL`, `TLC_BIN_DIR`.
 
 ### Running a development copy

package/bin/tlc-cli.ts

@@ -16,6 +16,7 @@ import { linkDir, linkFile, seedConfig } from "../src/platform/links.ts";
 import {
   EXECUTABLE_EXTENSIONS,
   executableOnPath,
+  findProjectRoot,
   flagsDir,
   isOnPath,
   launcherBinDir,
@@ -35,8 +36,17 @@ export class UsageError extends Error {}
 // single door into core and the two cannot drift apart.
 type Posture = ReturnType<typeof coreFacade.policy.resolveProjectPosture>;
 
+/**
+ * invariant: an explicit `TLC_PROJECT_DIR` still wins — the hooks set it from the host's own payload, which knows
+ * the workspace better than a directory walk can. Everything else discovers the project the way `git` does
+ * ([/decisions/ad-101.md](/decisions/ad-101.md)).
+ */
 export function resolveProjectRoot(): string {
-  return process.env.TLC_PROJECT_DIR ?? process.cwd();
+  const declared = process.env.TLC_PROJECT_DIR;
+  if (declared) {
+    return declared;
+  }
+  return findProjectRoot(process.cwd()) ?? process.cwd();
 }
 
 export function modeFilePath(root: string): string {
@@ -390,9 +400,18 @@ export function acceptPolicy(root: string, paths: string[], interactive: boolean
   const notHere = requested.filter((path) => !blocked.includes(path));
   const outcome = coreFacade.policy.acceptPolicySources(root, requested);
   if (outcome.kind === "not-a-source") {
+    /**
+     * hazard: this listed the sources and never said which project it had resolved. Run from a home directory,
+     * `projectConfigPath(root)` *is* the machine config path — so the list showed the same file twice, none of the
+     * repository's own paths, and no hint that the root was wrong. An operator read it as a defect in the product
+     * and lost the afternoon to it ([/decisions/ad-101.md](/decisions/ad-101.md)).
+     *
+     * invariant: the success path already names the project. The failure path is the one that needed it.
+     */
     throw new UsageError(
       [
         `not a policy source: ${outcome.paths.join(", ")}`,
+        `project: ${root} — pass TLC_PROJECT_DIR or run this from the repository whose session is blocked`,
         "The sources the loader reads are:",
         ...outcome.sources.map((source) => `  ${source}`),
       ].join("\n"),
@@ -1277,6 +1296,15 @@ export type TestStep = { label: string; bin: string; args: string[] };
 // against the real repository — green from a shell, red from inside a hook.
 export const TEST_ENV_IMPORT = ["--import", "./tools/test-env.mjs"];
 
+/**
+ * The number of unused exports this repository carries today.
+ *
+ * why a number in code and not a snapshot file: it is a debt, and a debt that has to be edited down in a reviewed
+ * commit is one somebody looks at. Lowering it is the point; raising it needs an argument in the diff
+ * ([/decisions/ad-102.md](/decisions/ad-102.md)).
+ */
+export const KNIP_EXPORTS_CEILING = 76;
+
 export function buildTestSteps(): TestStep[] {
   return [
     // why: `--error-on-warnings`. A warn-level rule does not change biome's exit code, so three fixable warnings
@@ -1288,6 +1316,22 @@ export function buildTestSteps(): TestStep[] {
     { label: "tsc --noEmit", bin: "npx", args: ["tsc", "--noEmit"] },
     { label: "src suite", bin: "node", args: [...TEST_ENV_IMPORT, "--test", "src/**/__test__/*.test.ts"] },
     { label: "tools suite", bin: "node", args: [...TEST_ENV_IMPORT, "--test", "tools/__test__/*.test.ts"] },
+    /**
+     * why two knip steps and not one: `files` and `dependencies` are already at zero, so they block. `exports` has a
+     * backlog of legitimately-exported-for-tests symbols, and a step that reports without failing is a signal that
+     * never fires — so it blocks on *growth* instead, which is the published way to adopt this without a sweep
+     * ([/decisions/ad-102.md](/decisions/ad-102.md)).
+     *
+     * hazard: `observe` was exported, wired into the facade and called by nothing, so no proof could ever exist and
+     * every operator rule denied for ever. 113 tests passed. This is the check that sees that class
+     * ([/decisions/ad-100.md](/decisions/ad-100.md)).
+     */
+    { label: "knip: dead files and dependencies", bin: "npx", args: ["knip", "--files", "--dependencies"] },
+    {
+      label: "knip: unused exports do not grow",
+      bin: "npx",
+      args: ["knip", "--exports", "--max-issues", String(KNIP_EXPORTS_CEILING)],
+    },
     { label: "check-boundaries", bin: "node", args: ["tools/dev/check-boundaries.ts"] },
     // why: `--error-on-warnings` above cannot see a rule that was suppressed rather than fixed, and biome accepts
     // any text after the colon. This is what makes the reason a reason ([/decisions/ad-051.md](/decisions/ad-051.md)).