@tech-leads-club/harness-toolkit 0.10.5 → 0.11.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>24 rails</b> you choose.
+  <b>8 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
@@ -90,11 +90,11 @@ Three tiers, and which tier a check is in decides whether you can turn it off.
 
 | Tier | Count | Configurable | Runs |
 |------|-------|--------------|------|
-| [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 |
+| [Floor](#tier-1--the-floor-no-configuration-reaches-it) | 8 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) | 24 capabilities | Each one, individually | Where the table says |
+| [Rails](#tier-3--the-rails-you-choose) | 25 capabilities | Each one, individually | Where the table says |
 
-Nothing else runs. If a message on your screen is not from one of the thirty-four rows below, it is not the
+Nothing else runs. If a message on your screen is not from one of the thirty-six rows below, it is not the
 harness.
 
 ### Tier 1 — the floor, no configuration reaches it
@@ -113,6 +113,7 @@ prints `rule=<name>`, and the name is the first column here.
 | `machine-control` | `shutdown`, `reboot`, `halt`, `poweroff` | — |
 | `unprovable-execution` | a program fetched over the network and handed to a shell — piped, process-substituted, or inside a shell's `-c`/`eval` substitution. The gate cannot read what would run | a fetch with no shell downstream, and a shell fed a local file the gate can read |
 | `policy-surface-write` | every route an agent has to harness policy and state — a shell redirect, an interpreter, a heredoc program, or a write tool — in the project and under the runtime home, plus the mutating `tlc harness` subcommands from inside a session | reading them with a proven reader (`cat`, `head`, `grep`, `jq`, `ls`, `stat`, `test`), and `tlc harness handoff` for the handoff state |
+| `wiring-tamper` | a shell redirect, in-place edit, or delete into a registered provider's wiring target — the document its own editor reads to register the harness's hooks — and a direct `Edit`/`Write`/`MultiEdit` tool call against the same path — overwriting it silences every hook the harness has for that host | reading the same path with a proven reader or a read tool |
 
 <!-- /generated -->
 
@@ -167,6 +168,7 @@ trade-off when you ran the init wizard. `configPath` is the key in `.tlc/harness
 | **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 |
+| **Secret redaction (tool/shell output)**<br>`secrets.redactOutput` · **on** | Scans a tool's or shell command's output for a secret-shaped signature or high-entropy span and masks it. | `tool.after` | `context` | the masked placeholder itself, in the tool output — `[REDACTED:<kind>:<hash>]` |
 
 <!-- /generated -->
 

package/bin/tlc-cli.ts

@@ -30,6 +30,7 @@ import {
 } from "../src/platform/paths.ts";
 import { type Row, render, type Screen, type Section } from "../src/platform/screen.ts";
 import { createStyle, PLAIN, type Style } from "../src/platform/style.ts";
+import { scaffold } from "../tools/new-provider.ts";
 
 export class UsageError extends Error {}
 
@@ -195,9 +196,10 @@ export function setPaused(root: string, on: boolean): string {
 }
 
 /**
- * why: the operator's escape hatch for a stuck gate — `blockers` and `previous_gaps` are project-wide,
- * so a grind-cap or stagnation signal from one session can block every later subagent until either a
- * clean stop clears it or this runs. Denied from inside a session by `policy-surface-write`.
+ * why: the operator's escape hatch for a stuck gate — `blockers`/`previous_gaps` are per session
+ * ([/decisions/ad-122.md](/decisions/ad-122.md)), and a subagent inheriting its parent's session key inherits
+ * a stuck signal the same way, until either a clean stop clears it or this runs across every session on
+ * record. Denied from inside a session by `policy-surface-write`.
  */
 export async function resetStuckState(root: string): Promise<string> {
   const cleared = await coreFacade.handoff.clearStuckSignals(root);
@@ -244,22 +246,23 @@ export function setMode(root: string, raw: string): string {
 
 export type HandoffReport = {
   root: string;
-  providers: Record<string, ReturnType<typeof coreFacade.handoff.readHandoff>>;
+  providers: Record<string, ReturnType<typeof coreFacade.handoff.readLatestSlice>>;
 };
 
 /**
  * The sanctioned way to read handoff state.
  *
- * why: the bootstrap used to tell the agent to read `.tlc/harness/state/handoff.json`, a path the floor guards. So
- * the instruction and the permission disagreed, and the obvious command — `test -f … && head -c 2000 …` — was
- * refused with advice about writing policy. An instruction is not an affordance; the route the harness asks for has
- * to be one it grants ([/decisions/ad-047.md](/decisions/ad-047.md)).
+ * why: the route the floor grants instead of the raw file path it guards ([/decisions/ad-047.md](/decisions/ad-047.md)).
+ * One row per provider, the most recent session, not liveness-gated — a diagnostic summary, not a turn's own
+ * decision ([/decisions/ad-122.md](/decisions/ad-122.md)).
  */
 export function handoffJson(root: string): HandoffReport {
-  const file = coreFacade.handoff.readHandoffFile(root);
+  const providerNames = new Set(
+    coreFacade.handoff.listHandoffSessionFiles(root).map((file) => file.owner.provider),
+  );
   const providers: HandoffReport["providers"] = {};
-  for (const provider of Object.keys(file.by_provider)) {
-    providers[provider] = coreFacade.handoff.readHandoff(root, provider);
+  for (const provider of providerNames) {
+    providers[provider] = coreFacade.handoff.readLatestSlice(root, provider);
   }
   return { root, providers };
 }
@@ -859,6 +862,43 @@ export function setGateCommand(root: string, field: GateField, argv: string[], i
   return `grind.${field}Command = ${JSON.stringify(argv)}`;
 }
 
+const REGISTRY_TYPE_IMPORT = 'import type { ProviderPort } from "./provider.port.ts";\n';
+const REGISTRY_ARRAY = /export const providers: ProviderPort\[\] = \[([^\]]*)\];/;
+
+// invariant: an append, never a reorder — the new entry always lands last in `providers`, so every existing provider's detection-order position is unchanged.
+export function appendProviderToRegistry(text: string, name: string): string {
+  if (!text.includes(REGISTRY_TYPE_IMPORT)) {
+    throw new Error("provider.registry.ts: could not find the ProviderPort type-import anchor line");
+  }
+  const withImport = text.replace(
+    REGISTRY_TYPE_IMPORT,
+    `import { ${name}Provider } from "./${name}/index.ts";\n${REGISTRY_TYPE_IMPORT}`,
+  );
+
+  const match = REGISTRY_ARRAY.exec(withImport);
+  if (!match) {
+    throw new Error("provider.registry.ts: could not find the providers array literal");
+  }
+  const existing = (match[1] ?? "").trim();
+  const appended = existing.length > 0 ? `${existing}, ${name}Provider` : `${name}Provider`;
+  return withImport.replace(REGISTRY_ARRAY, `export const providers: ProviderPort[] = [${appended}];`);
+}
+
+/**
+ * The full `tlc harness new-provider` flow: T5's scaffold, then a real import appended to
+ * provider.registry.ts — in that order, so a refused scaffold never touches the registry.
+ */
+export function runNewProvider(name: string, root: string): { ok: true } | { ok: false; reason: string } {
+  const scaffolded = scaffold(name, root);
+  if (!scaffolded.ok) {
+    return scaffolded;
+  }
+  const registryPath = join(root, "src", "providers", "provider.registry.ts");
+  const current = readFileSync(registryPath, "utf8");
+  writeFileSync(registryPath, appendProviderToRegistry(current, name), "utf8");
+  return { ok: true };
+}
+
 export function helpScreen(): Screen {
   return {
     title: "tlc harness",
@@ -1165,6 +1205,7 @@ export type Action =
   | { kind: "prices-lookup"; modelId: string; provider: string }
   | { kind: "entry"; entry: string; args: string[] }
   | { kind: "install"; args: string[] }
+  | { kind: "new-provider"; name: string }
   | { kind: "unknown"; cmd: string };
 
 export function route(args: string[]): Action {
@@ -1293,6 +1334,13 @@ export function route(args: string[]): Action {
       return { kind: "entry", entry: "init-project", args: args.slice(1) };
     case "install":
       return { kind: "install", args: args.slice(1) };
+    case "new-provider": {
+      const name = args[1];
+      if (!name) {
+        throw new UsageError("usage: tlc harness new-provider <name>");
+      }
+      return { kind: "new-provider", name };
+    }
     // why: the exit has to be as easy to find as the entrance. An operator who cannot get the harness off their
     // machine without hand-editing settings.json will not try it on a second one
     // ([/decisions/ad-066.md](/decisions/ad-066.md)).
@@ -1330,7 +1378,8 @@ export const TEST_ENV_IMPORT = ["--import", "./tools/test-env.mjs"];
  * 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;
+// why: raised from 76 to 80 — knip cannot trace render-provider-docs.ts's dynamic import() of each provider's inbound module, so EVENT_KIND_BY_HOOK (both adapters) and Claude's PRE_TOOL_USE_FAN_OUT/POST_TOOL_USE_FAN_OUT report as unused though the drift gate depends on them.
+export const KNIP_EXPORTS_CEILING = 80;
 
 export function buildTestSteps(): TestStep[] {
   return [
@@ -1376,6 +1425,7 @@ export function buildTestSteps(): TestStep[] {
     // for an unrelated reason ([/decisions/ad-081.md](/decisions/ad-081.md)).
     { label: "check-manifest", bin: "node", args: ["tools/dev/check-manifest.ts"] },
     { label: "capabilities in sync", bin: "node", args: ["tools/dev/render-capabilities.ts", "--check"] },
+    { label: "provider docs in sync", bin: "node", args: ["tools/dev/render-provider-docs.ts", "--check"] },
     { label: "changelog in sync", bin: "node", args: ["tools/dev/render-changelog.ts", "--check"] },
     // why: the OKF bundle's log is a reserved file that cannot be retired, and hand-maintaining it drifted to 19
     // of 66 records before anyone noticed ([/decisions/ad-067.md](/decisions/ad-067.md)).
@@ -1813,6 +1863,17 @@ async function main(argv: string[]): Promise<void> {
     case "install":
       runInstall(action.args, root);
       break;
+    case "new-provider": {
+      const result = runNewProvider(action.name, process.cwd());
+      if (!result.ok) {
+        console.error(`new-provider: refusing — ${result.reason}`);
+        process.exit(1);
+      }
+      console.log(
+        `new-provider: scaffolded src/providers/${action.name}/, docs/providers/${action.name}.md, and appended ${action.name}Provider to provider.registry.ts`,
+      );
+      break;
+    }
     case "entry":
       runEntry(action.entry, json ? [...action.args, JSON_FLAG] : action.args, root);
       break;

package/capabilities/catalog.json

@@ -1,5 +1,5 @@
 {
-  "catalogVersion": 14,
+  "catalogVersion": 15,
   "capabilities": [
     {
       "id": "grind",
@@ -430,6 +430,23 @@
       "verdict": "deny",
       "inspect": "tlc harness doctor \u2014 each active rule, its tier, and any proof kind never observed here",
       "asks": []
+    },
+    {
+      "id": "secretRedaction",
+      "configPath": "secrets.redactOutput",
+      "title": "Secret redaction (tool/shell output)",
+      "summary": "Scans a tool's or shell command's output for a secret-shaped signature or high-entropy span and masks it.",
+      "benefit": "Masks an AWS access key, GitHub/Slack/Stripe token, PEM private-key block, JWT, or an unlabelled high-entropy string with a deterministic placeholder \u2014 the same value always yields the same placeholder within a session \u2014 instead of blocking the command that produced it.",
+      "tradeOff": "A synchronous regex plus Shannon-entropy pass on every tool/shell output; a high-diversity non-secret string can be masked as a false positive, and an unlabelled low-entropy secret can be missed. On a host with no rewrite mechanism for the firing event, the mask degrades to a context warning instead \u2014 the model is told a secret was masked but the raw value already reached it.",
+      "defaultOn": true,
+      "sinceCatalogVersion": 15,
+      "fires": [
+        "tool.after"
+      ],
+      "verdict": "context",
+      "inspect": "the masked placeholder itself, in the tool output \u2014 `[REDACTED:<kind>:<hash>]`",
+      "asks": [],
+      "recommend": "on"
     }
   ]
 }