@tech-leads-club/harness-toolkit 0.2.1

package/src/core/floor/floor.catalog.ts

@@ -0,0 +1,54 @@
+import type { FloorRule } from "./floor.service.ts";
+
+export type FloorRuleDoc = {
+  /** What the rule refuses, in the terms an operator reading a denial would use. */
+  denies: string;
+  /** The one case that reads like it should be denied and is not, where there is one worth stating. */
+  allows?: string;
+};
+
+/**
+ * why: the README described the floor as "five rules" above a table of six, and `docs/architecture.md` listed
+ * eight — two of which are not floor rules at all. The floor is the part no configuration can reach, so a
+ * hand-copied count of it is the worst place in the product for a number to drift.
+ *
+ * invariant: keyed by `FloorRule`, so adding a member to that union without describing it here fails the
+ * typecheck rather than shipping an undocumented rule.
+ */
+export const FLOOR_RULES: Record<FloorRule, FloorRuleDoc> = {
+  "outside-project-destruction": {
+    denies:
+      "a destructive command whose target resolves outside the repository and outside the OS temp directory",
+    allows: "the same command inside the repository, or inside the temp directory",
+  },
+  "unprovable-destruction": {
+    denies:
+      "a destructive verb whose target is a variable, a command substitution, or otherwise built at runtime — the harness cannot see what it would delete",
+    allows: "a literal path it can resolve and check",
+  },
+  "secret-access": {
+    denies:
+      "a read that would copy a credential into the transcript — `.env`, `~/.ssh`, `~/.aws`, `*.pem` and similar through a shell reader or the editor's own read tool, and the instance metadata service through any verb that speaks to the network",
+    allows: "searching local files for the literal address, because `grep` and its kin make no request",
+  },
+  "history-rewrite": {
+    denies: "`git push --force`",
+    allows: "`--force-with-lease`, which refuses on its own when the remote moved",
+  },
+  "machine-control": {
+    denies: "`shutdown`, `reboot`, `halt`, `poweroff`",
+  },
+  "unprovable-execution": {
+    denies:
+      "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",
+    allows: "a fetch with no shell downstream, and a shell fed a local file the gate can read",
+  },
+  "policy-surface-write": {
+    denies:
+      "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",
+    allows:
+      "reading them with a proven reader (`cat`, `head`, `grep`, `jq`, `ls`, `stat`, `test`), and `tlc harness handoff` for the handoff state",
+  },
+};
+
+export const FLOOR_RULE_IDS = Object.keys(FLOOR_RULES) as FloorRule[];

package/src/core/floor/floor.paths.ts

@@ -0,0 +1,90 @@
+import { homedir, tmpdir } from "node:os";
+import { basename, isAbsolute, relative, resolve, sep } from "node:path";
+import {
+  flagsDir,
+  projectConfigPath,
+  projectStateDir,
+  runtimeHome,
+  runtimeStateDir,
+} from "../../platform/paths.ts";
+import { normalizeSeparators } from "../../platform/sanitize.ts";
+
+export function expandHome(text: string, home = homedir()): string {
+  if (text === "~") {
+    return home;
+  }
+  return text.startsWith(`~${sep}`) || text.startsWith("~/") ? resolve(home, text.slice(2)) : text;
+}
+
+export function resolveTarget(projectDir: string, word: string, home = homedir()): string {
+  const expanded = expandHome(word, home);
+  return isAbsolute(expanded) ? resolve(expanded) : resolve(projectDir, expanded);
+}
+
+export function isInside(parent: string, child: string): boolean {
+  const rel = relative(resolve(parent), resolve(child));
+  return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+
+// why: scratch space is where an agent is supposed to make a mess, so destruction there is not a floor
+// concern even though it sits outside the project.
+export function isScratch(target: string, tmp = tmpdir()): boolean {
+  return isInside(tmp, target);
+}
+
+// hazard: the runtime config is merged by `loadPolicy` under the project one, so a field the project does
+// not set is decided there — for every repository on the machine. Guarding only the project paths left
+// `echo '{}' > ~/.tlc/harness/config.json` allowed, which is the same defect one directory up.
+export function isRuntimePolicySurface(filePath: string): boolean {
+  const target = resolve(filePath);
+  return target === resolve(runtimeHome(), "config.json") || isInside(runtimeStateDir(), target);
+}
+
+// invariant: the policy surface is defined here, next to the floor's other path predicates, because the
+// floor decides before any policy is read. Defining it inside the policy module would point the dependency
+// backwards — against the order the two actually run in.
+export function isPolicySurface(projectDir: string, filePath: string): boolean {
+  if (isRuntimePolicySurface(filePath)) {
+    return true;
+  }
+  const target = normalizeSeparators(relative(projectDir, filePath) || filePath);
+  const config = normalizeSeparators(relative(projectDir, projectConfigPath(projectDir)));
+  const flags = normalizeSeparators(relative(projectDir, flagsDir(projectDir)));
+  const state = normalizeSeparators(relative(projectDir, projectStateDir(projectDir)));
+  return target === config || target.startsWith(`${flags}/`) || target.startsWith(`${state}/`);
+}
+
+const SECRET_HOME_DIRS = [".ssh", ".aws", ".kube", ".gnupg", ".docker", ".config/gh", ".config/gcloud"];
+const SECRET_BASENAMES = new Set([
+  ".git-credentials",
+  ".netrc",
+  ".npmrc",
+  ".pgpass",
+  "credentials",
+  "id_dsa",
+  "id_ecdsa",
+  "id_ed25519",
+  "id_rsa",
+]);
+const SECRET_SUFFIXES = [".pem", ".p12", ".pfx"];
+// invariant: these are templates checked into repos on purpose — treating them as secrets would
+// block ordinary work and teach the operator to distrust the floor.
+const ENV_TEMPLATE_SUFFIXES = [".example", ".sample", ".template", ".dist"];
+
+function isEnvFile(name: string): boolean {
+  if (name !== ".env" && !name.startsWith(".env.")) {
+    return false;
+  }
+  return !ENV_TEMPLATE_SUFFIXES.some((suffix) => name.endsWith(suffix));
+}
+
+export function isSecretPath(target: string, home = homedir()): boolean {
+  const name = basename(target);
+  if (isEnvFile(name) || SECRET_BASENAMES.has(name)) {
+    return true;
+  }
+  if (SECRET_SUFFIXES.some((suffix) => name.endsWith(suffix))) {
+    return true;
+  }
+  return SECRET_HOME_DIRS.some((dir) => isInside(resolve(home, dir), target));
+}

package/src/core/floor/floor.policy-surface.ts

@@ -0,0 +1,311 @@
+import { relative, resolve } from "node:path";
+import { projectConfigPath, projectStateDir } from "../../platform/paths.ts";
+import { normalizeSeparators } from "../../platform/sanitize.ts";
+import { isInside, isPolicySurface, resolveTarget } from "./floor.paths.ts";
+import {
+  type HeredocChunk,
+  heredocChunks,
+  type ShellSegment,
+  type ShellWord,
+  tokenizeShell,
+} from "./floor.tokenize.ts";
+import { firstOperand, verbOf } from "./floor.verb.ts";
+
+/**
+ * `remedy` is the way out for *this* denial.
+ *
+ * hazard: every policy-surface refusal used to end with the same sentence — set a gate command, make policy changes
+ * from your own terminal. That is advice about *writing* policy, handed to an agent that was trying to *read* the
+ * handoff the harness had just told it to read. A refusal a model cannot plan around is the opaque-refusal failure
+ * the 2026 tool-use literature names, and it is what confused a colleague's agent
+ * ([/decisions/ad-047.md](/decisions/ad-047.md)).
+ */
+export type PolicySurfaceVerdict =
+  | { kind: "allow" }
+  | { kind: "deny"; detail: string; note: string; remedy?: string };
+
+const ALLOW: PolicySurfaceVerdict = { kind: "allow" };
+
+// invariant: this is an allowlist on purpose. The set of ways a shell can write a file is unbounded —
+// `python3 -c`, `perl -pi`, `ex`, any interpreter — so enumerating writers guarantees a hole. Enumerating
+// the readers instead means an unknown verb lands on the deny side without anyone having to predict it.
+// hazard: `awk` and `sort` look like readers and are not — `awk '{print > f}'` and `sort -o f` both write a
+// file the head verb never reveals. They are left out deliberately.
+const PROVEN_READERS = new Set([
+  "cat",
+  "cmp",
+  "diff",
+  "echo",
+  "file",
+  "grep",
+  "head",
+  "jq",
+  "less",
+  "ls",
+  "md5sum",
+  "more",
+  "od",
+  "printf",
+  "rg",
+  "sha256sum",
+  "stat",
+  "strings",
+  "tail",
+  // why: `test` and `[` evaluate a predicate and produce an exit code. They have no way to write a file at all —
+  // no output flag, no redirection of their own — so they are strictly safer than `echo`, which is already here.
+  // Their absence was an incomplete allowlist rather than a decision: the harness tells an agent to read the
+  // handoff, and `test -f handoff.json && head -c 2000 handoff.json` — the obvious way to do it — was denied
+  // ([/decisions/ad-047.md](/decisions/ad-047.md)).
+  "test",
+  "[",
+  "wc",
+  "xxd",
+]);
+
+// hazard: `git checkout -- <path>`, `git restore` and `git apply` overwrite the working tree, so `git` as a
+// whole cannot be a reader. Only the subcommands that provably do not write are allowed.
+const GIT_READERS = new Set(["show", "diff", "log", "status", "ls-files", "cat-file", "blame"]);
+
+// hazard: a heredoc is only a program when the verb it feeds executes what it reads. `git commit -F -` and
+// `cat <<EOF` take a heredoc that *documents* this path — commit messages and docs in this repository name
+// it constantly — so judging a body by "not a proven reader" denied writing about the rule at all.
+const EXECUTES_STDIN = new Set([
+  "ash",
+  "awk",
+  "bash",
+  "bun",
+  "dash",
+  "deno",
+  "ed",
+  "ex",
+  "fish",
+  "gawk",
+  "ksh",
+  "lua",
+  "node",
+  "perl",
+  "php",
+  "python",
+  "python2",
+  "python3",
+  "ruby",
+  "sed",
+  "sh",
+  "tclsh",
+  "zsh",
+]);
+
+const HARNESS_BINS = new Set(["tlc", "tlc.cmd"]);
+// why: `policy` is here for the sharpest reason of any of them — `tlc harness policy accept` exists to clear a
+// tampering signal, so an agent that could reach it would make the whole integrity rail decorative. It is refused
+// by a floor rule with no config switch, exactly like the rest ([/decisions/ad-030.md](/decisions/ad-030.md)).
+const MUTATING_SUBCOMMANDS = new Set(["pause", "resume", "grind", "mode", "init", "gate", "policy"]);
+
+function deny(detail: string, note: string, remedy?: string): PolicySurfaceVerdict {
+  return { kind: "deny", detail, note, ...(remedy ? { remedy } : {}) };
+}
+
+/**
+ * The route that does work, named in the refusal itself.
+ *
+ * why: reading harness state is ordinary work the bootstrap asks for by name, so a refusal on that path has to say
+ * how to do it rather than what not to do. The command exists so nothing has to reach into the protected path at
+ * all — an instruction that points at a path the floor guards is three layers disagreeing.
+ */
+export const READ_REMEDY =
+  "Reading is allowed: run `tlc harness handoff` for handoff state, `tlc harness policy` for the resolved policy, or use a proven reader (cat, head, jq, grep, ls, stat, test) on the path.";
+
+// why: the harness directory prefix is derived from the path module rather than written as a literal, so a
+// change to the on-disk layout cannot leave this rule matching a path that no longer exists. The relative
+// form is what appears in commands, and an absolute path contains it too.
+function harnessPrefix(projectDir: string): string {
+  const state = normalizeSeparators(relative(projectDir, projectStateDir(projectDir)));
+  return state.slice(0, state.lastIndexOf("/"));
+}
+
+// hazard: the incident's command hid the path inside `python3 -c "...open('.tlc/harness/config.json','w')"`,
+// which tokenizes as one word that resolves to nothing. Reasoning about the nested quoting is the
+// weak-parser trap the floor refuses elsewhere, so the text is only asked whether the surface is named at
+// all — and that question is only asked of verbs that were not proven to be readers.
+function namesSurface(projectDir: string, segment: ShellSegment): boolean {
+  const text = normalizeSeparators(segment.words.map((word) => word.text).join(" "));
+  return text.includes(harnessPrefix(projectDir));
+}
+
+// why: the surface and the target overlap when either contains the other. Containment in the second
+// direction is what catches `rm -rf .tlc/harness/state`, which removes the flags without ever naming one.
+// hazard: the project root also contains the surface. Counting it would deny `find .` and `grep -r x .`,
+// so the root is excluded and destruction of the whole project stays the concern of the existing rules.
+function overlapsSurface(projectDir: string, resolved: string): boolean {
+  if (resolved === resolve(projectDir)) {
+    return false;
+  }
+  if (isPolicySurface(projectDir, resolved)) {
+    return true;
+  }
+  return [projectConfigPath(projectDir), projectStateDir(projectDir)].some(
+    (surface) => isInside(surface, resolved) || isInside(resolved, surface),
+  );
+}
+
+function referencesSurface(projectDir: string, word: ShellWord): boolean {
+  if (word.text === "") {
+    return false;
+  }
+  // hazard: an unresolved word carries a `$var` or `$(...)`, so its value is unknowable here. Matching the
+  // literal portion catches `> .tlc/harness/$f`; a fully computed path stays out of reach and is what the
+  // per-session integrity baseline exists to catch.
+  if (word.unresolved) {
+    return normalizeSeparators(word.text).includes(harnessPrefix(projectDir));
+  }
+  return overlapsSurface(projectDir, resolveTarget(projectDir, word.text));
+}
+
+// why: a redirect target is not an argument of the head verb, so argument scanning alone would allow
+// `cat x > config.json` — the head verb there is a proven reader. Both the spaced and the attached forms
+// have to be read, because `>f`, `>>f` and `x>f` all tokenize as a single word.
+function redirectTargets(words: ShellWord[]): ShellWord[] {
+  const targets: ShellWord[] = [];
+  for (let index = 0; index < words.length; index += 1) {
+    const word = words[index];
+    // hazard: a `>` inside a quoted argument is literal text, not a redirect. Scanning quoted words denied
+    // commands that merely carry shell-looking data — a JSON hook payload, a fixture, a doc example.
+    if (!word || word.quotedStart) {
+      continue;
+    }
+    const match = /^(.*?)>{1,2}\|?(.*)$/s.exec(word.text);
+    if (!match) {
+      continue;
+    }
+    const attached = match[2] ?? "";
+    if (attached !== "") {
+      targets.push({ text: attached, unresolved: word.unresolved, quotedStart: false });
+      continue;
+    }
+    const next = words[index + 1];
+    if (next) {
+      targets.push(next);
+      index += 1;
+    }
+  }
+  return targets;
+}
+
+function harnessSubcommand(args: ShellWord[]): string | null {
+  const operands = args.filter((word) => !word.text.startsWith("-") && word.text !== "");
+  if (operands[0]?.text.toLowerCase() !== "harness") {
+    return null;
+  }
+  // why: `route()` defaults a missing subcommand to `status`, so bare `tlc harness` reads state and is
+  // not a mutation.
+  return (operands[1]?.text ?? "status").toLowerCase();
+}
+
+function checkSegment(projectDir: string, segment: ShellSegment): PolicySurfaceVerdict {
+  for (const target of redirectTargets(segment.words)) {
+    if (referencesSurface(projectDir, target)) {
+      return deny(
+        "a redirect in this command writes into the harness policy surface.",
+        "redirect into the policy surface",
+      );
+    }
+  }
+
+  const head = verbOf(segment.words);
+
+  if (head && HARNESS_BINS.has(head.verb)) {
+    const subcommand = harnessSubcommand(head.args);
+    if (subcommand !== null && MUTATING_SUBCOMMANDS.has(subcommand)) {
+      return deny(
+        `\`tlc harness ${subcommand}\` changes harness policy, and policy is the operator's to change.`,
+        `tlc harness ${subcommand}`,
+      );
+    }
+  }
+
+  const references = segment.words.filter((word) => referencesSurface(projectDir, word));
+  if (references.length === 0 && !namesSurface(projectDir, segment)) {
+    return ALLOW;
+  }
+
+  // hazard: an unreliable split means the head verb is not established, so a reader-looking head proves
+  // nothing. Unknown resolves to denied, as it does for the destruction rules.
+  if (segment.opaque) {
+    return deny(
+      "this command names the harness policy surface inside a segment this gate cannot split, so what it does to it cannot be established.",
+      "unprovable policy-surface access",
+    );
+  }
+  if (!head) {
+    return deny(
+      "the harness policy surface is named in a command with no resolvable verb.",
+      "policy-surface access with no verb",
+    );
+  }
+  // why: a proven reader is cleared before any other question, because reading the policy is ordinary work
+  // and the bootstrap asks for it by name. Nothing in this set can write a file on its own.
+  if (PROVEN_READERS.has(head.verb)) {
+    return ALLOW;
+  }
+  if (head.verb === "git") {
+    const subcommand = firstOperand(head.args)?.text.toLowerCase() ?? "";
+    return GIT_READERS.has(subcommand)
+      ? ALLOW
+      : deny(
+          `\`git ${subcommand}\` can write the working tree, so it cannot be proven to only read the harness policy surface.`,
+          `git ${subcommand} on the policy surface`,
+          READ_REMEDY,
+        );
+  }
+  if (references.some((word) => word.unresolved)) {
+    return deny(
+      "this command builds a harness policy path at runtime, so the file it would touch cannot be established.",
+      "unresolvable policy-surface path",
+    );
+  }
+  return deny(
+    `\`${head.verb}\` is not a proven reader, so this command cannot be shown to only read the harness policy surface.`,
+    `${head.verb} on the policy surface`,
+    READ_REMEDY,
+  );
+}
+
+// hazard: `python3 - <<PY` puts the program in the heredoc body, so the path never appears among the words.
+// The body only matters when something executes it: `git commit -F -` and `cat <<EOF` receive heredocs that
+// merely name this path, which is what writing about the rule looks like. A heredoc that *writes* the
+// surface through a redirect or a path argument is caught by the per-segment rules instead.
+function checkHeredocs(projectDir: string, heredocs: HeredocChunk[]): PolicySurfaceVerdict {
+  const prefix = harnessPrefix(projectDir);
+  for (const chunk of heredocs) {
+    if (!normalizeSeparators(chunk.body).includes(prefix)) {
+      continue;
+    }
+    // hazard: the body belongs to the verb immediately before its marker, not to the command. Asking
+    // whether *any* segment runs an interpreter denied `cat >> f <<EOF ... ; node --test`, where the body
+    // goes to cat and node is a separate command.
+    const owner = verbOf(tokenizeShell(chunk.prefix).at(-1)?.words ?? []);
+    if (owner !== null && EXECUTES_STDIN.has(owner.verb)) {
+      return deny(
+        `a heredoc fed to \`${owner.verb}\` names the harness policy surface, so the body is a program rather than a document.`,
+        "heredoc program naming the policy surface",
+      );
+    }
+  }
+  return ALLOW;
+}
+
+// invariant: reads no policy. It answers from paths, head verbs and the command's own text, so the file it
+// protects can never influence the decision that protects it.
+export function checkPolicySurface(
+  projectDir: string,
+  command: string,
+  segments: ShellSegment[],
+): PolicySurfaceVerdict {
+  for (const segment of segments) {
+    const verdict = checkSegment(projectDir, segment);
+    if (verdict.kind === "deny") {
+      return verdict;
+    }
+  }
+  return checkHeredocs(projectDir, heredocChunks(command));
+}