@tech-leads-club/harness-toolkit 0.2.1

package/src/core/release/release.decisions.ts

@@ -0,0 +1,147 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * why: the substance of a changelog already exists in this repository as thirty decision records, each carrying why,
+ * the trade-offs and what was refused. What was missing is the mapping from "I updated" to "these landed". Reading
+ * the records is that mapping, and it needs no second index to maintain
+ * ([/decisions/ad-031.md](/decisions/ad-031.md)).
+ *
+ * invariant: a `migration` note is what marks a decision as needing operator action. Anything finer would be the
+ * harness guessing whether a given config is affected, and `doctor` already answers that precisely — the note says
+ * what to do, the doctor says whether it applies to you.
+ */
+export type DecisionSummary = {
+  id: string;
+  title: string;
+  /** Present only when the decision requires the operator to change something. */
+  migration?: string;
+  /** why: the OKF bundle's `log.md` groups by ISO date, and the record already carries the date it was taken. */
+  timestamp?: string;
+  /** why: bundle-relative, so a link to an archived record points where the record actually is. */
+  path: string;
+};
+
+function frontmatterField(text: string, field: string): string | undefined {
+  // why: line-scoped, matching how `check-docs-bundle` reads the same files. The values here are single-line
+  // quoted strings by convention, and the bundle check is what enforces that.
+  const match = new RegExp(`^${field}:\\s*"?(.+?)"?\\s*$`, "m").exec(text);
+  const value = match?.[1]?.trim();
+  if (value === undefined || value === "") {
+    return undefined;
+  }
+  // hazard: an escaped quote inside the value survived the outer-quote strip and reached the operator as a literal
+  // `\"` in their terminal. Seen in a real update run ([/decisions/ad-034.md](/decisions/ad-034.md)).
+  return value.replace(/\\(["'\\])/g, "$1");
+}
+
+export function decisionsDir(repoRoot: string): string {
+  return join(repoRoot, "docs", "decisions");
+}
+
+/** why: an absent docs directory is an empty list, not an error. A linked checkout may not carry docs at all. */
+export function readDecision(repoRoot: string, file: string): DecisionSummary | null {
+  const path = join(decisionsDir(repoRoot), file);
+  if (!existsSync(path)) {
+    return null;
+  }
+  let text: string;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch {
+    return null;
+  }
+  const title = frontmatterField(text, "title");
+  if (title === undefined) {
+    return null;
+  }
+  // invariant: the id is the file's own name, so an archived record keeps the id it shipped under.
+  const id = (file.split(/[\\/]/).pop() ?? file).replace(/\.md$/, "").toUpperCase();
+  const migration = frontmatterField(text, "migration");
+  const timestamp = frontmatterField(text, "timestamp");
+  return {
+    id,
+    title,
+    path: `/decisions/${file.split(/[\\/]/).join("/")}`,
+    ...(migration === undefined ? {} : { migration }),
+    ...(timestamp === undefined ? {} : { timestamp }),
+  };
+}
+
+export function readDecisions(repoRoot: string, files: string[]): DecisionSummary[] {
+  return files
+    .filter((file) => /(?:^|[\\/])ad-\d+\.md$/.test(file))
+    .map((file) => readDecision(repoRoot, file))
+    .filter((decision): decision is DecisionSummary => decision !== null)
+    .sort((a, b) => a.id.localeCompare(b.id));
+}
+
+/**
+ * why: an archived record still shipped, so it keeps its row in the changelog and in the dated log. Only the
+ * decisions index distinguishes active from archived, because only the index claims to describe what currently
+ * binds ([/decisions/ad-072.md](/decisions/ad-072.md)).
+ */
+export const ARCHIVED_DIR = "archived";
+
+export function allDecisionFiles(repoRoot: string): string[] {
+  const dir = decisionsDir(repoRoot);
+  const found: string[] = [];
+  for (const sub of ["", ARCHIVED_DIR]) {
+    const full = sub === "" ? dir : join(dir, sub);
+    if (!existsSync(full)) {
+      continue;
+    }
+    try {
+      for (const file of readdirSync(full)) {
+        if (/^ad-\d+\.md$/.test(file)) {
+          found.push(sub === "" ? file : join(sub, file));
+        }
+      }
+    } catch {
+      // why: an unreadable directory is an empty one. A linked checkout may not carry docs at all.
+    }
+  }
+  return found;
+}
+
+export function needsAction(decisions: readonly DecisionSummary[]): DecisionSummary[] {
+  return decisions.filter((decision) => decision.migration !== undefined);
+}
+
+/** why: `AD-031 — Some title` → `AD-031`, so an id can trail a sentence instead of leading it. */
+function idOf(decision: DecisionSummary): string {
+  return decision.id;
+}
+
+/**
+ * hazard: the first version led with each decision's *title*, which describes the author's reasoning rather than the
+ * operator's situation, and printed `NEEDS YOUR ACTION` for every note. In a real update run both notes said "run
+ * `tlc harness doctor`" — which `update` then did automatically, three lines below — and neither applied to that
+ * project. An alarm that fires on every update is one the reader learns to scroll past, and the next one that matters
+ * goes with it ([/decisions/ad-034.md](/decisions/ad-034.md)).
+ *
+ * invariant: the note is the headline and the decision id trails it. The heading appears only when a note exists, and
+ * it says what a note now means: something `doctor` cannot detect for you.
+ */
+export function formatDecisionDigest(decisions: readonly DecisionSummary[]): string {
+  if (decisions.length === 0) {
+    return "";
+  }
+  const action = needsAction(decisions);
+  const lines: string[] = [
+    `Harness updated. ${decisions.length} decision(s) landed; doctor runs below and reports what applies here.`,
+  ];
+  if (action.length > 0) {
+    lines.push("", `Needs a change doctor cannot detect for you (${action.length}):`);
+    for (const decision of action) {
+      lines.push(`  ${decision.migration}  (${idOf(decision)})`);
+    }
+  }
+  const rest = decisions.filter((decision) => decision.migration === undefined);
+  if (rest.length > 0) {
+    lines.push("", `Also landed: ${rest.map(idOf).join(", ")} — docs/decisions/index.md`);
+  } else {
+    lines.push("", "Full reasoning: docs/decisions/index.md");
+  }
+  return lines.join("\n");
+}

package/src/core/release/release.seen.ts

@@ -0,0 +1,38 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { writeJsonAtomic } from "../../platform/fs-atomic.ts";
+import { projectStateDir } from "../../platform/paths.ts";
+
+/**
+ * why: mirrors the capability seen marker rather than inventing a second mechanism. That marker already established
+ * both the shape and the reason — an announcement that repeats becomes noise, and noise is filtered out by the
+ * reader, which is how a real warning gets missed ([/decisions/ad-031.md](/decisions/ad-031.md)).
+ *
+ * invariant: per project, not per machine. Two repositories on one install each hear about a decision once, because
+ * whether a decision matters is a property of the project's config, not of the machine.
+ */
+export type ReleaseSeen = { revision: string; updatedAt?: string };
+
+function seenPath(projectDir: string): string {
+  return join(projectStateDir(projectDir), "release-seen.json");
+}
+
+export function readReleaseSeen(projectDir: string): ReleaseSeen | null {
+  const path = seenPath(projectDir);
+  if (!existsSync(path)) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as ReleaseSeen;
+    return typeof parsed?.revision === "string" && parsed.revision !== "" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function writeReleaseSeen(projectDir: string, revision: string): Promise<void> {
+  await writeJsonAtomic(seenPath(projectDir), {
+    revision,
+    updatedAt: new Date().toISOString(),
+  } satisfies ReleaseSeen);
+}

package/src/core/shell-policy/shell-policy.service.ts

@@ -0,0 +1,215 @@
+import type { Decision } from "../../contracts/decision.ts";
+import { type ShellWord, tokenizeShell } from "../floor/floor.tokenize.ts";
+import type { OperatorMode } from "../policy/policy.types.ts";
+import { trackShellCommand } from "./shell-policy.stall.ts";
+import type { ShellEffectClass } from "./shell-policy.types.ts";
+
+const WRAPPERS = new Set(["command", "doas", "env", "nice", "nohup", "sudo", "time", "xargs"]);
+const MACHINE = new Set(["halt", "poweroff", "reboot", "shutdown"]);
+const NETWORK = new Set(["curl", "ftp", "gh", "nc", "ncat", "rsync", "scp", "sftp", "ssh", "telnet", "wget"]);
+// invariant: a verb belongs in WRITE when it can remove or overwrite a path that already exists. `cp` and `mv`
+// qualify because the destination may exist and the harness cannot know whether it does — conservative wherever
+// the filesystem is unknowable. `tee` qualifies with or without `-a`, because the flagless form truncates and a
+// rule whose failure mode is silent data loss does not get a special case.
+const WRITE = new Set(["cp", "mv", "rm", "rmdir", "tee", "truncate"]);
+// hazard: these lived in the preserving tier for one revision, on the reasoning that they lose no bytes. True and
+// beside the point: they decide who can read or execute a path, `-R` applies that to a whole tree, and the result
+// appears in no diff. Losing content and widening access are separate questions.
+const PRIVILEGE = new Set(["chmod", "chown"]);
+const DEVICE = /^\/dev\/(sd|nvme|vd|hd|disk)/;
+
+// invariant: classification reads head verbs from the shared tokenizer, never patterns in the raw
+// string, so quoted text and heredoc bodies stay data rather than commands.
+function classifySegment(words: ShellWord[]): ShellEffectClass {
+  let index = 0;
+  while (index < words.length) {
+    const word = words[index];
+    if (!word) {
+      break;
+    }
+    if (WRAPPERS.has(word.text) || word.text.startsWith("-") || word.text.includes("=")) {
+      index += 1;
+      continue;
+    }
+    const verb = word.text.split("/").pop() ?? word.text;
+    const args = words.slice(index + 1);
+    const argText = args.map((arg) => arg.text);
+
+    if (MACHINE.has(verb) || verb === "mkfs" || verb.startsWith("mkfs.")) {
+      return "destructive";
+    }
+    if (verb === "dd" && argText.some((arg) => arg.startsWith("of=") && DEVICE.test(arg.slice(3)))) {
+      return "destructive";
+    }
+    if (
+      verb === "diskutil" &&
+      argText.some((arg) => arg.startsWith("erase") || arg.startsWith("partition"))
+    ) {
+      return "destructive";
+    }
+    if (verb === "rm" && argText.some((arg) => arg === "/" || arg === "/*" || arg.startsWith("../../"))) {
+      return "destructive";
+    }
+    if (NETWORK.has(verb)) {
+      return "network";
+    }
+    if ((verb === "git" || verb === "docker") && argText.includes("push")) {
+      return "network";
+    }
+    if (WRITE.has(verb) || (verb === "sed" && argText.includes("-i"))) {
+      return "write";
+    }
+    if (PRIVILEGE.has(verb)) {
+      return "privilege";
+    }
+    // hazard: these two used to collapse into one branch, so an append was indistinguishable from an overwrite.
+    // `>` truncates the target and `>>` does not, which is exactly the line this class exists to draw.
+    if (argText.includes(">")) {
+      return "write";
+    }
+    return argText.includes(">>") ? "write-preserving" : "read";
+  }
+  return "read";
+}
+
+const ORDER: ShellEffectClass[] = [
+  "read",
+  "write-preserving",
+  "write",
+  "privilege",
+  "network",
+  "destructive",
+];
+
+export function classifyShell(command: string): ShellEffectClass {
+  let worst: ShellEffectClass = "read";
+  for (const segment of tokenizeShell(command)) {
+    const found = classifySegment(segment.words);
+    if (ORDER.indexOf(found) > ORDER.indexOf(worst)) {
+      worst = found;
+    }
+  }
+  return worst;
+}
+
+export function isCatastrophic(command: string): boolean {
+  return classifyShell(command) === "destructive";
+}
+
+function stallFollowup(command: string, hits: number): string {
+  return [
+    `BLOCKED: shell stall — the same command was attempted ${hits} times.`,
+    `TRIED: \`${command.slice(0, 160)}\``,
+    "NEED: change approach. Do not repeat this command. Diagnose why it failed, use a different tool/path, or escalate with BLOCKED/TRIED/NEED.",
+  ].join("\n");
+}
+
+export type EvaluateShellCommandArgs = {
+  command: string;
+  sessionKey: string;
+  projectDir: string;
+  /** The active operator posture. Only `paired` lowers the interruption threshold. */
+  mode: OperatorMode;
+  catastrophicAsk: boolean;
+  stallDetection: boolean;
+  stallRepeatThreshold: number;
+};
+
+/**
+ * why: `paired` promises a check-in before a sizable non-destructive move, and `classifyShell` answers what
+ * "sizable" means — a command that can lose something (`write`) or that leaves the machine (`network`).
+ *
+ * hazard: this used to include the whole `write` class, which asked about appending to a file. Repeated approval
+ * of routine actions becomes a keystroke rather than a decision, and a habituated reviewer is the delivery
+ * mechanism for the one action that mattered — approval fatigue is a security defect, not an ergonomics
+ * complaint. Only `write-preserving` left the tier ([/decisions/ad-026.md](/decisions/ad-026.md)).
+ *
+ * hazard: `chmod` and `chown` left it too for one revision, and should not have. They lose no bytes, which was
+ * the criterion, and they still decide who can reach a path — the one change that shows up in no diff. `privilege`
+ * is a member here for that reason.
+ *
+ * invariant: this is a separate rule from `catastrophicAsk`, not an override of it. That switch keeps deciding
+ * `destructive` at every posture; posture decides the tier below it. A posture that switched a capability off
+ * would be the defect the posture feature exists to remove.
+ *
+ * hazard: the threshold is deliberately not applied to tool edits. An `Edit` of one line is a write too, and
+ * asking before every one turns a posture into a permission prompt.
+ */
+const PAIRED_ASK: ReadonlySet<ShellEffectClass> = new Set(["write", "privilege", "network"]);
+
+// why: named here rather than at the call sites so the recorded rate and the rule that produced it cannot drift
+// apart. An operator reading "seven asks" needs to know which switch to reach for.
+export const SHELL_RULES = {
+  catastrophic: "shell-catastrophic",
+  posture: "shell-posture-paired",
+  stall: "shell-stall",
+} as const;
+
+// why: three tiers ask, and each asks a different question. One sentence covering all of them would leave the
+// operator weighing the wrong risk, which fails in the same direction as not asking at all.
+const AT_STAKE: Record<string, string> = {
+  network: "reaches the network, so it leaves this machine and cannot be pulled back",
+  privilege: "changes who can reach a path, and that will not appear in any diff",
+  write: "can overwrite or remove a path that already exists",
+};
+
+function atStake(effect: ShellEffectClass): string {
+  return AT_STAKE[effect] ?? "changes something outside this turn";
+}
+
+function pairedPreCheck(command: string, mode: OperatorMode): Decision | null {
+  if (mode !== "paired") {
+    return null;
+  }
+  const effect = classifyShell(command);
+  if (!PAIRED_ASK.has(effect)) {
+    return null;
+  }
+  // hazard: the reason used to end "leave the posture with `tlc harness mode solo`" — an instruction aimed at the
+  // agent, which the floor refuses from inside a session. `reason` is the agent's half and `userNote` is the
+  // operator's; the way out of a posture belongs in the operator's ([/decisions/ad-030.md](/decisions/ad-030.md)).
+  return {
+    kind: "ask",
+    reason: `Posture paired: this command ${atStake(effect)}, and the operator asked to see these before they run. Wait for their answer — the posture is theirs to change, not yours.`,
+    userNote: `Paired posture: this ${effect} command ${atStake(effect)}. Approve it, or leave the posture with \`tlc harness mode solo\`.`,
+    rule: SHELL_RULES.posture,
+  };
+}
+
+export function evaluateShellCommand(args: EvaluateShellCommandArgs): Decision {
+  const command = args.command;
+  if (!command) {
+    return { kind: "allow" };
+  }
+
+  // why: destructive is decided first and identically at every posture — it is the one stop that never
+  // narrows. The paired rule governs what sits below it.
+  if (args.catastrophicAsk && isCatastrophic(command)) {
+    return {
+      kind: "ask",
+      reason:
+        "The command was flagged as potentially catastrophic. Prefer scoped paths inside the repo or reversible operations.",
+      userNote: "This shell command can destroy data outside the workspace. Approve only if you intend it.",
+      rule: SHELL_RULES.catastrophic,
+    };
+  }
+
+  const preCheck = pairedPreCheck(command, args.mode);
+  if (preCheck) {
+    return preCheck;
+  }
+
+  if (args.stallDetection) {
+    const hits = trackShellCommand(args.projectDir, args.sessionKey, command);
+    if (hits >= args.stallRepeatThreshold) {
+      return {
+        kind: "deny",
+        reason: stallFollowup(command, hits),
+        userNote: `Harness blocked a repeated shell command (${hits}x).`,
+        rule: SHELL_RULES.stall,
+      };
+    }
+  }
+
+  return { kind: "allow" };
+}

package/src/core/shell-policy/shell-policy.stall.ts

@@ -0,0 +1,57 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { projectStateDir } from "../../platform/paths.ts";
+import type { ShellStallEntry, ShellStallStore } from "./shell-policy.types.ts";
+
+function storePath(root: string): string {
+  return join(projectStateDir(root), "shell-stall.json");
+}
+
+function readStore(root: string): ShellStallStore {
+  const path = storePath(root);
+  if (!existsSync(path)) {
+    return {};
+  }
+  try {
+    return JSON.parse(readFileSync(path, "utf8")) as ShellStallStore;
+  } catch {
+    return {};
+  }
+}
+
+function writeStore(root: string, store: ShellStallStore): void {
+  try {
+    mkdirSync(projectStateDir(root), { recursive: true });
+    writeFileSync(storePath(root), `${JSON.stringify(store, null, 2)}\n`, "utf8");
+  } catch {}
+}
+
+function normalizeCommand(command: string): string {
+  return command.trim().replace(/\s+/g, " ").slice(0, 300);
+}
+
+export function trackShellCommand(root: string, sessionKey: string, command: string): number {
+  const normalized = normalizeCommand(command);
+  if (!normalized) {
+    return 0;
+  }
+  const store = readStore(root);
+  const current: ShellStallEntry = store[sessionKey] ?? { hits: 0 };
+  const next: ShellStallEntry =
+    current.lastCommand === normalized
+      ? { lastCommand: normalized, hits: current.hits + 1 }
+      : { lastCommand: normalized, hits: 1 };
+  store[sessionKey] = next;
+  writeStore(root, store);
+  return next.hits;
+}
+
+export function clearShellStall(root: string, sessionKey: string): void {
+  const store = readStore(root);
+  store[sessionKey] = { hits: 0 };
+  writeStore(root, store);
+}
+
+export function shellStallHits(root: string, sessionKey: string): number {
+  return readStore(root)[sessionKey]?.hits ?? 0;
+}

package/src/core/shell-policy/shell-policy.types.ts

@@ -0,0 +1,26 @@
+/**
+ * why: `write-preserving` sits between `read` and `write` because "changes something" and "can lose something"
+ * are different questions, and only the second is worth interrupting an operator for. Repeated approval of the
+ * first becomes reflex, and a habituated reviewer is how the one consequential action gets waved through
+ * ([/decisions/ad-026.md](/decisions/ad-026.md)).
+ *
+ * hazard: `privilege` exists because that split, on its own, was the wrong axis for `chmod` and `chown`. Neither
+ * loses a byte, so both were classified as preserving and stopped being asked about — which let
+ * `chmod -R 777 .` through unremarked. Access is a third question, and the one whose answer never shows up in a
+ * diff. It ranks above `write` for that reason: an overwrite inside a repository is recoverable and visible,
+ * a widened permission is neither.
+ */
+export type ShellEffectClass =
+  | "read"
+  | "write-preserving"
+  | "write"
+  | "privilege"
+  | "network"
+  | "destructive";
+
+export type ShellStallEntry = {
+  lastCommand?: string;
+  hits: number;
+};
+
+export type ShellStallStore = Record<string, ShellStallEntry>;

package/src/core/ship/ship.ledger.ts

@@ -0,0 +1,76 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { appendRecord, readTail } from "../../platform/fs-jsonl.ts";
+import { projectStateDir } from "../../platform/paths.ts";
+import type { ShipLedgerRow } from "./ship.types.ts";
+
+export function shipLedgerPath(root: string): string {
+  return join(projectStateDir(root), "ship-ledger.jsonl");
+}
+
+export function appendShipLedger(root: string, row: Omit<ShipLedgerRow, "ts"> & { ts?: string }): void {
+  const full: ShipLedgerRow = { ...row, ts: row.ts ?? new Date().toISOString() };
+  appendRecord(shipLedgerPath(root), full);
+}
+
+export function readShipLedger(root: string): ShipLedgerRow[] {
+  return readTail<ShipLedgerRow>(shipLedgerPath(root), Number.MAX_SAFE_INTEGER);
+}
+
+/**
+ * hazard: this asked one question — is the verdict fresh? — and freshness is not what makes evidence evidence. A
+ * verdict written ten minutes ago passed while the code it supposedly certified changed five minutes ago. Evidence
+ * that predates the change proves nothing about it, and the gate accepted it silently
+ * ([/decisions/ad-027.md](/decisions/ad-027.md)).
+ *
+ * invariant: ordering is checked first and age second. Age still earns its place — it catches a verdict left over
+ * from last week when nothing changed at all — but only ordering can see the case above.
+ *
+ * why: `notBeforeMs` is a parameter rather than something read here, so the caller supplies the timestamp it
+ * already has. When it is absent the age window decides alone, which is the pre-existing behaviour: a missing
+ * input must not fail closed on a gate that blocks a stop.
+ */
+export function hasRecentEvidence(evidenceDir: string, maxAgeHours: number, notBeforeMs?: number): boolean {
+  if (!existsSync(evidenceDir)) {
+    return false;
+  }
+  const maxAgeMs = maxAgeHours * 60 * 60 * 1000;
+  const now = Date.now();
+  for (const entry of readdirSync(evidenceDir)) {
+    const verdictPath = join(evidenceDir, entry, "90-verdict.txt");
+    if (!existsSync(verdictPath)) {
+      continue;
+    }
+    try {
+      const writtenAt = statSync(verdictPath).mtimeMs;
+      if (notBeforeMs !== undefined && writtenAt < notBeforeMs) {
+        continue;
+      }
+      if (now - writtenAt > maxAgeMs) {
+        continue;
+      }
+      if (/\bPASS\b/i.test(readFileSync(verdictPath, "utf8"))) {
+        return true;
+      }
+    } catch {}
+  }
+  return false;
+}
+
+/**
+ * why: the newest mtime among the files the turn changed. The stop path already has that list, so ordering costs
+ * a stat per changed file and no git call. Returns undefined when there is nothing to compare against, which is
+ * the signal to let the age window decide.
+ */
+export function newestChangeMs(root: string, relativePaths: string[]): number | undefined {
+  let newest: number | undefined;
+  for (const relative of relativePaths) {
+    try {
+      const at = statSync(join(root, relative)).mtimeMs;
+      if (newest === undefined || at > newest) {
+        newest = at;
+      }
+    } catch {}
+  }
+  return newest;
+}