@profoundry-us/highball 0.5.0 → 0.6.1

package/ONBOARDING.md

@@ -151,11 +151,18 @@ Decision rules:
 Highball enforces with no account and no network. Reporting is a separate,
 optional decision, and it is your human's to make — ask, do not assume.
 
-If they want it, they add a `reporting.posthog` block to `checks.yml` with
-their PostHog host and project key. That key is write-only by design (it is
-the same one that ships in client-side web bundles), so it is committed
-config, not a secret — there is no login step and no credentials file. If
-they would rather not send anything anywhere, skip the block: the local
+If they want it, there are two ways, and the choice is theirs:
+
+- **Committed:** a `reporting.posthog` block in `checks.yml` with their
+  PostHog host and project key. That key is write-only by design (it is the
+  same one that ships in client-side web bundles), so it is committed
+  config, not a secret — there is no login step and no credentials file.
+- **Per machine:** `HIGHBALL_POSTHOG_KEY` in the environment, with no block
+  in `checks.yml` at all. The `env` block of `~/.claude/settings.json`
+  reaches every repo's hooks. Your human sets this themselves; never ask
+  for the key value or write it anywhere.
+
+If they would rather not send anything anywhere, skip both: the local
 journal (`highball runs`) already records every run in more detail than
 PostHog receives.
 

package/README.md

@@ -1,5 +1,7 @@
 # @profoundry-us/highball
 
+**Website:** [highball.profoundry.us](https://highball.profoundry.us)
+
 The Highball runner: executes a repo's `.highball/checks.yml` rules and blocks
 AI coding agents on failure (exit 2, the Claude Code hook contract) — "local
 CI for AI agents". Enforcement is entirely local and needs no account, no
@@ -103,6 +105,72 @@ The runner computes the branch's changed-file list once (it owns git) and
 hands it to every rule via `HIGHBALL_CHANGED_FILES` — check scripts stay pure
 analyzers and need no git in their execution context.
 
+## Turning it off
+
+Three switches, differing in who they affect and — the part that usually
+decides it — when they take effect:
+
+```bash
+touch .highball/disabled       # this checkout, gitignored, next run
+```
+
+```yaml
+enabled: false                 # in checks.yml — committed, everyone, next run
+```
+
+```bash
+export HIGHBALL_DISABLED=1     # your whole machine, next session restart
+```
+
+Any of them makes `highball run` exit 0 immediately, with no rule executed, no
+journal entry, and nothing reported. Hooks and rules stay exactly where they
+are, so switching back on is a one-line revert.
+
+| | takes effect | scope | committed |
+| --- | --- | --- | --- |
+| `.highball/disabled` | next run | this checkout | no — `init` gitignores it |
+| `enabled: false` | next run | one repo, everyone who clones it | yes |
+| `HIGHBALL_DISABLED` | next Claude Code restart, for hooks | every repo, your machine | no |
+
+**Reach for the marker file first.** `touch .highball/disabled` while an agent
+session is running and the very next hook run skips; delete it and the run
+after that is armed again. Both directions are live because the file is
+checked on every run and every hook invocation is a new process — there is no
+state anywhere and nothing to restart. `init` writes a `.highball/.gitignore`
+alongside it, so a switch-off in your checkout can't ride along in a commit.
+
+Anything you write into the marker comes back as the reason on every run,
+which is what the person who finds the checks off next week actually needs:
+
+```console
+$ echo "bisecting a flaky spec" > .highball/disabled
+$ npx @profoundry-us/highball run --fast
+highball: disabled by .highball/disabled (bisecting a flaky spec) — no checks run
+```
+
+`enabled: false` is the committed counterpart, for a repo genuinely stepping
+away from its checks. It lands in a diff, which is what you want when the
+decision belongs to the team rather than to your afternoon.
+
+`HIGHBALL_DISABLED` is an ordinary environment variable, so a hook sees
+whatever value the Claude Code process had when it started — Claude Code
+writes settings `env` entries into its environment at launch, and a shell
+`export` after that never reaches an already-running session. That makes it
+the right switch for a machine-wide default you rarely change, and the wrong
+one for a mid-session toggle. Like the marker, it is read *before*
+`checks.yml`, so both still work when the config is itself what's broken.
+
+`HIGHBALL_DISABLED=0`, `false`, `no`, `off` and empty all mean **not**
+disabled. Anything else disables. Plain truthiness would make `=0` stop every
+check in the repo, which is exactly the "is the guardrail live right now?"
+doubt this switch exists to remove.
+
+None of the three is silent. Each prints a line on every run, because a guardrail
+that has quietly stopped guarding is worse than no guardrail — the next
+person reads green and believes it. For the same reason `enabled:` accepts
+only a real boolean: `enabled: "false"` and `enabled: no` are strings, and
+rather than leaving checks quietly on, they fail loudly.
+
 ## AI-judged rules
 
 A rule with `rubric:` instead of `run:` is judged by headless Claude rather
@@ -140,9 +208,24 @@ Rubrics live with the opinions they express: a framework pack such as
 `reporting.posthog` sends runs to PostHog — the runner's only telemetry path.
 A team that already runs PostHog needs no server for this, and a team that
 doesn't can skip the block entirely and use the local journal. The project key
-is write-only by design, so it is committed config: no login step, no
-credentials file. `HIGHBALL_POSTHOG_KEY` / `HIGHBALL_POSTHOG_HOST` (or
-`POSTHOG_API_KEY` / `POSTHOG_HOST`) override it for CI.
+is write-only by design — it is the same key PostHog has you ship in browser
+bundles, and all it can do is capture events — so committing it is safe:
+no login step, no credentials file.
+
+If you would still rather keep it out of the repo, set the environment
+instead. `HIGHBALL_POSTHOG_KEY` (or `POSTHOG_API_KEY`) on its own turns
+reporting on with no `reporting:` block at all, and `HIGHBALL_POSTHOG_HOST`
+(or `POSTHOG_HOST`) points it at an EU or self-hosted instance; either wins
+over committed config, which is also how CI redirects a run. One place that
+reaches every repo's hooks is the `env` block of your user-level Claude Code
+settings, `~/.claude/settings.json`:
+
+```json
+{ "env": { "HIGHBALL_POSTHOG_KEY": "phc_your_key" } }
+```
+
+The trade-off is that reporting is then per machine rather than per repo: a
+teammate cloning the repo reports nothing until they set the key too.
 
 The whole run leaves in ONE request to `/batch/`. PostHog events are
 immutable, which suits a runner that already defers reporting to after the

package/bin/highball.js

@@ -20,7 +20,11 @@ Usage:
                             --if-changed skips when the working tree is
                             unchanged since the last run (for hooks that
                             also match Bash).
-  highball init            Scaffold .highball/checks.yml and Claude Code
+                            Switched off by .highball/disabled (this
+                            checkout, gitignored), \`enabled: false\` in
+                            checks.yml (committed, whole team), or
+                            HIGHBALL_DISABLED=1 (your machine).
+  highball init             Scaffold .highball/checks.yml and Claude Code
                             hooks in the current repo.
   highball onboard          Print the setup guide written for this repo's
                             AI agent — tell your agent to run this and

package/lib/config.js

@@ -16,6 +16,17 @@ export function loadConfig(root = process.cwd()) {
   }
   const config = YAML.parse(readFileSync(path, "utf8"));
   if (!config?.project) throw new Error(`${CONFIG_PATH} is missing \`project:\`.`);
+  // A kill switch that silently fails to kill is the worst of both worlds,
+  // so only a real boolean counts and anything else is an error rather than
+  // a shrug. `enabled: no` parses as the string "no" under YAML 1.2 and
+  // `enabled: "false"` as a string; both are truthy, so a typo would leave
+  // the repo running checks its author believed were off.
+  if (config.enabled !== undefined && typeof config.enabled !== "boolean") {
+    throw new Error(
+      `${CONFIG_PATH}: \`enabled:\` must be true or false, not ` +
+        `\`${config.enabled}\` (${typeof config.enabled}).`
+    );
+  }
   if (!Array.isArray(config.checks)) {
     throw new Error(`${CONFIG_PATH} is missing its \`checks:\` list.`);
   }
@@ -41,6 +52,48 @@ export function loadConfig(root = process.cwd()) {
   return config;
 }
 
+// The per-machine off switch, read fresh on every `highball run` — there is
+// no state anywhere, so unsetting the variable re-arms the checks with
+// nothing to clean up.
+//
+// Falsey spellings mean "don't disable" rather than "disable". Plain
+// truthiness would make `HIGHBALL_DISABLED=0` stop every check in the repo,
+// which is precisely the doubt about whether the guardrail is live that this
+// switch exists to remove. Anything else — 1, true, yes, on, or a bare
+// value — disables.
+const NOT_DISABLED = new Set([ "", "0", "false", "no", "off" ]);
+
+export function disabledByEnv(env = process.env) {
+  const value = env.HIGHBALL_DISABLED;
+  if (value === undefined) return false;
+  return !NOT_DISABLED.has(String(value).trim().toLowerCase());
+}
+
+// The per-checkout off switch: an untracked marker file beside checks.yml.
+//
+// It exists because the other two each miss the common case. `enabled: false`
+// is committed, so switching your own checkout off can ship to everyone;
+// HIGHBALL_DISABLED is an environment variable, so a hook only sees a change
+// after the agent session restarts. This one is per repo, per checkout, and
+// re-read on every run like checks.yml — `touch` and `rm`, effective on the
+// next run, and `.highball/.gitignore` keeps it out of commits.
+export const DISABLED_MARKER = ".highball/disabled";
+
+// Presence is the whole signal; any text inside is the reason, echoed back on
+// every run so "why are the checks off in here?" has an answer that outlives
+// whoever switched them off.
+export function disabledByMarker(root = process.cwd()) {
+  const path = join(root, DISABLED_MARKER);
+  if (!existsSync(path)) return null;
+  try {
+    return { reason: readFileSync(path, "utf8").split("\n")[0].trim() };
+  } catch {
+    // An unreadable marker still counts: it was put there on purpose, and
+    // guessing "probably fine, run the checks" is the wrong way to be wrong.
+    return { reason: "" };
+  }
+}
+
 // PostHog is the runner's telemetry sink. There is no secret to resolve: a
 // PostHog project key is write-only by design, so it lives in committed
 // config right next to the host — no login step, no credentials file. Env

package/lib/init.js

@@ -8,13 +8,21 @@ import { basename, join } from "node:path";
 const CHECKS_TEMPLATE = (project) => `# ${project}'s Highball rules — the file \`highball run\` reads and
 # reports from. \`fast: true\` marks rules cheap enough to run on every
 # agent edit; the rest join at turn end. \`todo: true\` declares a rule
-# you're committed to but haven't built — tracked on the dashboard,
+# you're committed to but haven't built — tracked in run history,
 # never a failure.
 version: 1
 project: ${project}
 
+# Set \`enabled: false\` to switch this repo's checks off for everyone,
+# without deleting rules or hooks. To switch them off only in YOUR
+# checkout, leave this alone and \`touch .highball/disabled\` instead —
+# it is gitignored, and takes effect on the next run.
+
 # Optional telemetry. The PostHog project key is write-only by design, so
 # it is committed config — there is no login step and no credentials file.
+# To keep it out of the repo instead, set HIGHBALL_POSTHOG_KEY in the
+# environment (e.g. the env block of ~/.claude/settings.json) and leave
+# this block out entirely.
 # reporting:
 #   posthog:
 #     host: https://us.i.posthog.com
@@ -77,6 +85,18 @@ export async function init() {
     console.log(`created .highball/checks.yml (project: ${project}) — add your rules`);
   }
 
+  // Ignore the `disabled` marker from inside .highball/ rather than by
+  // editing the repo's root .gitignore, which init doesn't own. It is
+  // committed, so every clone inherits the protection and nobody has to
+  // remember the setup step that keeps a local switch-off local.
+  const ignorePath = join(root, ".highball", ".gitignore");
+  if (existsSync(ignorePath)) {
+    console.log("kept existing .highball/.gitignore");
+  } else {
+    writeFileSync(ignorePath, "# A local, uncommitted `highball run` off switch.\ndisabled\n");
+    console.log("created .highball/.gitignore (keeps the `disabled` marker out of commits)");
+  }
+
   const settingsPath = join(root, ".claude", "settings.json");
   if (existsSync(settingsPath)) {
     console.log(

package/lib/journal.js

@@ -1,9 +1,9 @@
 // The local run journal: every run appends one JSONL line to
 // ~/.highball/runs/<project>.jsonl, whether or not remote reporting is
-// configured. This is what makes the runner useful with no dashboard at
-// all — `highball runs` reads it — and it lives outside the repo tree
-// (like credentials) so there's no gitignore to manage and no state to
-// leak into commits.
+// configured. This is what makes the runner useful with no telemetry at
+// all — `highball runs` and the MCP widget read it — and it lives outside
+// the repo tree so there's no gitignore to manage and no state to leak
+// into commits.
 import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";

package/lib/mcp.js

@@ -266,7 +266,7 @@ export async function mcp() {
     description:
       "Execute a repo's Highball checks (fast rules or the full suite). " +
       "Blocks until done; the run lands in the journal and, when reporting " +
-      "is configured, on the dashboard.",
+      "is configured, in PostHog.",
     inputSchema: {
       dir: z.string().optional()
         .describe("Repo root containing .highball/checks.yml; defaults to cwd"),

package/lib/run.js

@@ -1,11 +1,14 @@
 // `highball run [--fast]` — the enforcement half. Runs each rule, prints
 // progress, exits 2 with failures on stderr (the Claude Code hook
 // contract: a Stop hook reading exit 2 blocks the agent and feeds the
-// output back). Reporting is the witness half and is best-effort: a dead
-// dashboard must never block the agent.
+// output back). Reporting is the witness half and is best-effort: an
+// unreachable PostHog must never block the agent.
 import { execSync, spawnSync } from "node:child_process";
 import { readFileSync } from "node:fs";
-import { loadConfig, resolvePosthog, commandFor } from "./config.js";
+import {
+  CONFIG_PATH, DISABLED_MARKER, disabledByEnv, disabledByMarker,
+  loadConfig, resolvePosthog, commandFor
+} from "./config.js";
 import { appendRun } from "./journal.js";
 import { readStamp, treeFingerprint, writeStamp } from "./stamp.js";
 import { git } from "./git.js";
@@ -26,6 +29,25 @@ export async function run(args) {
   // loop.
   if (process.env.HIGHBALL_JUDGE) return 0;
 
+  // Off switch #1, deliberately ahead of the config load: HIGHBALL_DISABLED
+  // is the one to reach for mid-task, so it has to work even when
+  // checks.yml is itself the thing in the way. Per machine, nothing to
+  // commit, nothing to accidentally push at a teammate.
+  if (disabledByEnv()) {
+    console.log("highball: disabled by HIGHBALL_DISABLED — no checks run");
+    return 0;
+  }
+
+  // Off switch #2, also ahead of the config load and for the same reason:
+  // the marker is a bare file next to checks.yml, so it still works when
+  // checks.yml is itself what's in the way.
+  const marker = disabledByMarker();
+  if (marker) {
+    const why = marker.reason ? ` (${marker.reason})` : "";
+    console.log(`highball: disabled by ${DISABLED_MARKER}${why} — no checks run`);
+    return 0;
+  }
+
   const fastOnly = args.includes("--fast");
   let config;
   try {
@@ -35,6 +57,17 @@ export async function run(args) {
     return 1;
   }
 
+  // Off switch #2, the committed counterpart: this repo isn't using
+  // Highball right now, for everyone who clones it. Neither switch is ever
+  // silent — a guardrail that has stopped guarding should say so on every
+  // single run, or the next person reads green and believes it.
+  if (config.enabled === false) {
+    console.log(
+      `highball: disabled by \`enabled: false\` in ${CONFIG_PATH} — no checks run`
+    );
+    return 0;
+  }
+
   // --if-changed: a fast hook that also matches Bash fires after every
   // command, and most commands are reads. Skip outright when the working
   // tree is exactly where the last run left it. The fingerprint is taken
@@ -42,7 +75,7 @@ export async function run(args) {
   // mid-run makes the next call run again rather than trust a stale pass.
   const fingerprint = treeFingerprint();
   if (args.includes("--if-changed") && fingerprint &&
-      fingerprint === readStamp(config.project)) {
+      fingerprint === readStamp(config.project, process.cwd())) {
     console.log("highball: no changes since the last run — skipped");
     return 0;
   }
@@ -67,7 +100,7 @@ export async function run(args) {
     process.stdout.write(`→ ${rule.name} ... `);
 
     // Placeholder rules are tracked, not run: they report as "todo" so
-    // the dashboard shows the full intended ruleset, and they can never
+    // the widget and PostHog show the full intended ruleset, and they can never
     // fail a run — an aspiration shouldn't block anyone.
     if (rule.todo) {
       console.log("todo (not implemented yet)");
@@ -109,7 +142,7 @@ export async function run(args) {
 
   // Stamped pass or fail: after a failure the agent's next reads must not
   // re-run and re-block; its next edit moves the tree and runs again.
-  if (fingerprint) writeStamp(config.project, fingerprint);
+  if (fingerprint) writeStamp(config.project, process.cwd(), fingerprint);
 
   const failures = results.filter((result) => !result.passed);
   const durationMs = Date.now() - startedAt.getTime();
@@ -125,7 +158,7 @@ export async function run(args) {
   }
 
   // The local journal is unconditional — `highball runs` works with no
-  // dashboard configured at all. Journal failures never fail the checks,
+  // reporting configured at all. Journal failures never fail the checks,
   // same policy as reporting.
   try {
     appendRun(config.project, {
@@ -157,7 +190,7 @@ export async function run(args) {
         command:
           result.rule.run ??
           (result.rule.rubric ? `judge ${result.rule.rubric}` : null),
-        // Unlike the dashboard (failure tails only), the journal keeps
+        // Unlike PostHog (one-line summaries only), the journal keeps
         // every rule's output GitHub-Actions-style — it's the user's own
         // disk, and `highball runs <n> --logs` is the payoff.
         output_tail: result.output ? result.output.slice(-10_000) : null
@@ -180,7 +213,7 @@ export async function run(args) {
 
 // Claude Code hooks pass a JSON payload on stdin (session_id and
 // friends); that id groups this run with the rest of the agent's session
-// on the dashboard. A TTY means a human at a terminal — don't block on
+// in the journal and in PostHog. A TTY means a human at a terminal — don't block on
 // read.
 //
 // The deadline matters: a non-TTY stdin that nobody writes to and nobody

package/lib/runs.js

@@ -1,4 +1,4 @@
-// `highball runs [n] [--logs]` — the no-dashboard view of run history,
+// `highball runs [n] [--logs]` — the terminal view of run history,
 // read from the local journal. Bare: a table of recent runs, newest
 // first. With a number: that run's detail — failure output by default,
 // every rule's captured output with --logs.

package/lib/stamp.js

@@ -6,7 +6,7 @@
 // The fingerprint makes those free: HEAD plus every dirty path with its
 // size and mtime, hashed. A further edit to an already-dirty file moves
 // its mtime, so the stamp tracks edits rather than just the set of dirty
-// paths. Stamps live per project outside the repo, like the journal.
+// paths. Stamps live outside the repo, like the journal.
 import { createHash } from "node:crypto";
 import { execSync } from "node:child_process";
 import { mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
@@ -17,6 +17,14 @@ export function stampDir() {
   return join(homedir(), ".highball", "stamps");
 }
 
+// One stamp per CHECKOUT, not per project: git worktrees and parallel
+// clones share a project name but not a working tree, and a run in one
+// must never let the other skip a run it needs.
+export function stampPath(project, cwd, dir = stampDir()) {
+  const checkout = createHash("sha256").update(cwd).digest("hex").slice(0, 12);
+  return join(dir, `${project}-${checkout}`);
+}
+
 // null outside a git repo: with no way to tell whether anything changed,
 // --if-changed must never skip.
 export function treeFingerprint(cwd = process.cwd()) {
@@ -45,9 +53,9 @@ export function treeFingerprint(cwd = process.cwd()) {
   return hash.digest("hex");
 }
 
-export function readStamp(project, dir = stampDir()) {
+export function readStamp(project, cwd, dir = stampDir()) {
   try {
-    return readFileSync(join(dir, project), "utf8").trim();
+    return readFileSync(stampPath(project, cwd, dir), "utf8").trim();
   } catch {
     return null;
   }
@@ -55,10 +63,10 @@ export function readStamp(project, dir = stampDir()) {
 
 // Best-effort, like the journal: a stamp that fails to write costs one
 // extra fast run, never a failed one.
-export function writeStamp(project, fingerprint, dir = stampDir()) {
+export function writeStamp(project, cwd, fingerprint, dir = stampDir()) {
   try {
     mkdirSync(dir, { recursive: true, mode: 0o700 });
-    writeFileSync(join(dir, project), `${fingerprint}\n`);
+    writeFileSync(stampPath(project, cwd, dir), `${fingerprint}\n`);
   } catch {
     // ignore
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@profoundry-us/highball",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Highball runner — local CI for AI coding agents: runs a repo's .highball/checks.yml rules, blocks the agent on failure, and optionally reports runs to PostHog.",
   "keywords": [
     "ai",
@@ -14,7 +14,7 @@
     "type": "git",
     "url": "git+https://github.com/profoundry-us/highball.git"
   },
-  "homepage": "https://github.com/profoundry-us/highball#readme",
+  "homepage": "https://highball.profoundry.us",
   "bugs": {
     "url": "https://github.com/profoundry-us/highball/issues"
   },