@profoundry-us/highball 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Profoundry
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/ONBOARDING.md

@@ -0,0 +1,136 @@
+# Highball onboarding — instructions for this repo's AI agent
+
+You are setting up Highball in this repository. Highball gives you (the
+agent) guardrails while you work — a checks runner your Claude Code hooks
+fire on every edit and turn end, whose exit code 2 blocks you until the
+repo's rules pass — and gives your human a hosted dashboard recording
+every run. You are configuring the tool that will check your own future
+work: set it up so the rules reflect what this repo already trusts, not
+what you wish it did.
+
+Work through the steps in order. Steps marked **human** need your human's
+input or action — ask, don't guess, and never handle credential values
+yourself.
+
+## 0. Preconditions
+
+`npx highball --help` must work (Node >= 18, package installed as a dev
+dependency). If it doesn't, ask your human whether to install from the npm
+registry (`npm install --save-dev @profoundry-us/highball`) or from a
+local tarball path they provide. In a repo with no `package.json`, create
+a minimal private one first (`{ "name": "<repo>", "private": true }`) and
+gitignore `node_modules/` if it isn't already.
+
+## 1. Survey the repo before writing anything
+
+Answer these by reading, not assuming:
+
+- **What languages and toolchains live here**, and which commands does the
+  repo *already trust* — look at `package.json` scripts, a `justfile` or
+  `Makefile`, CI workflows, README instructions. Wire what exists; invent
+  no new tooling in the first pass.
+- **Host or container?** If the toolchain runs in Docker (compose files, a
+  devcontainer), find the dev service's name, then verify the repo mount
+  and working directory by running `pwd` and `ls` through
+  `docker compose exec -T <service>`. Rules will run there; you need to
+  know what paths they see.
+- **What's fast?** Time candidate commands. Only sub-~2s commands belong
+  on the per-edit path; test suites belong at turn end; anything needing a
+  live server or long setup should not gate turns at all (leave it to the
+  repo's existing workflow, or declare it `todo`).
+
+## 2. Scaffold
+
+Run `npx highball init`. It never overwrites: an existing
+`.highball/checks.yml` is kept, and if `.claude/settings.json` already
+exists it prints the hook snippet for you to merge by hand — merge it
+without disturbing existing hooks. Otherwise it creates both files.
+
+## 3. Write `.highball/checks.yml`
+
+Fill the scaffold using what the survey found. A containerized repo looks
+like this:
+
+```yaml
+version: 1
+project: my-mud            # ask your human if their org has slug conventions
+
+reporting:
+  url: https://highball.example.com   # human provides; committed, not secret
+
+# Toolchain in Docker: declare the wrapper once. -T is mandatory (hook
+# shells have no TTY); --workdir should be the container's repo mount.
+exec:
+  via: docker compose exec -T --workdir /app mud
+
+checks:
+  - id: python-syntax
+    name: Game code compiles
+    run: python -m compileall -q game
+    fast: true                        # sub-2s → runs on every edit
+
+  - id: js-syntax
+    name: Web viewer JS parses
+    run: node --check web/app.js
+    exec: host                        # host tool → opts out of the container
+    fast: true
+
+  - id: unit-tests
+    name: Unit tests (offline)
+    run: just test-unit               # orchestrates its own docker exec
+    exec: host                        # → must run on the host
+
+  - id: coverage-ratchet
+    name: Coverage never decreases
+    todo: true                        # declared aspiration; tracked, never run
+```
+
+Decision rules:
+
+- `exec.via` wraps every rule by default; a rule opts out with
+  `exec: host` when it invokes a host tool **or** is self-orchestrating
+  (a `just`/`make` target that runs `docker compose` itself must not be
+  double-wrapped).
+- Start minimal: one or two fast syntax/lint rules plus the repo's unit
+  test command at turn end. You can grow the ruleset later; a wrong rule
+  that blocks every turn erodes trust immediately.
+- The runner exports `HIGHBALL_CHANGED_FILES` (newline-separated,
+  repo-relative) to every rule — scripts that want changed-only behavior
+  can read it instead of shelling out to git.
+
+## 4. Credentials — **human**
+
+You must never see, type, or store a token value. Ask your human to:
+
+1. Create this project (and a token for it) in their Highball app.
+2. Run `npx highball login` themselves — interactively, or piping the
+   token via `--token-stdin` to keep it out of shell history.
+
+This stores the token in `~/.highball/credentials.json` (machine-local,
+0600, keyed host → project). CI uses `HIGHBALL_URL`/`HIGHBALL_TOKEN` env
+vars instead. The repo tree never contains a secret.
+
+## 5. Verify — all four proofs, not just the happy path
+
+1. **Fast path:** `npx highball run --fast` exits 0, every rule passed.
+2. **Full path:** `npx highball run` exits 0 (or fails honestly on real
+   pre-existing issues — surface those to your human rather than papering
+   over them).
+3. **The guardrail:** prove exit 2 works. Create an obviously-temporary
+   failing file (e.g. a syntax error in a `tmp_highball_plant.*` file),
+   run the fast path, confirm `FAILED` plus exit code 2 plus the failure
+   text on stderr — then delete the plant and confirm green again.
+4. **The witness:** every run above should print
+   `reported to <host> (run <id>)`. If you see
+   `highball reporting skipped: …` instead, diagnose in order: is
+   `reporting.url` set? did the human run `login` for this exact URL and
+   project slug? is the Highball app reachable from this machine?
+
+## 6. Report back — **human**
+
+Tell your human, concretely: which rules you wired and why each is
+fast/turn-end/todo; what you deliberately did NOT gate (slow suites,
+live-server tests); that hooks now block your turns on failures and how
+to remove them (`.claude/settings.json`) if they ever need to; and where
+credentials live. Follow this repo's own norms about committing the new
+files — do not commit without being asked.

package/README.md

@@ -0,0 +1,89 @@
+# @profoundry-us/highball
+
+The Highball runner: executes a repo's `.highball/checks.yml` rules, blocks AI
+coding agents on failure (exit 2, the Claude Code hook contract), and reports
+every run to a Highball dashboard — think "local CI for AI agents": the checks
+run and enforce on your machine while the dashboard records what happened.
+Enforcement stays local; Highball is the witness and system of record — the
+runner never uploads code, only pass/fail plus log tails. Reporting is always
+best-effort: no token or no reachable dashboard means checks still run and
+block, they just aren't recorded.
+
+## Install
+
+Published releases: `npm install --save-dev @profoundry-us/highball`.
+
+From a local tarball (pre-release):
+
+```bash
+npm pack                                   # in this repo → profoundry-us-highball-<v>.tgz
+npm install --save-dev ../highball-runner/profoundry-us-highball-<v>.tgz
+```
+
+## Setup: let the repo's own agent do it
+
+Highball is installed *by the AI agent that will be checked by it*. After
+installing the package, tell the repo's Claude Code agent:
+
+> Run `npx highball onboard` and follow the instructions.
+
+[ONBOARDING.md](ONBOARDING.md) (which that command prints) walks the agent
+through surveying the repo's real toolchain, scaffolding, writing rules that
+reflect what the repo already trusts, handing the credentials step to the
+human, and verifying all four proofs — including that exit 2 actually blocks.
+
+The pieces, for reference or manual setup:
+
+```bash
+npx highball init    # scaffolds .highball/checks.yml + Claude Code hooks
+npx highball login   # stores this machine's project token (once per machine)
+```
+
+`init` never overwrites an existing `checks.yml` and never edits an existing
+`.claude/settings.json` (it prints the hook snippet to merge by hand).
+`login` writes `~/.highball/credentials.json` (host → project → token, 0600);
+pipe the token via `--token-stdin` to keep it out of shell history. CI uses
+`HIGHBALL_URL` / `HIGHBALL_TOKEN` env vars instead.
+
+## checks.yml
+
+```yaml
+version: 1
+project: my-app
+
+reporting:
+  url: https://highball.example.com   # per-team, not a secret — committed
+
+# Containerized toolchain? Declare the wrapper once and every rule runs
+# through it; rules opt out with `exec: host`. Rule definitions stay
+# environment-agnostic on purpose — the *where* is per-checkout config.
+exec:
+  via: docker compose exec -T app
+
+checks:
+  - id: unit-tests
+    name: Unit tests
+    run: bundle exec rspec spec        # runs through exec.via
+
+  - id: js-syntax
+    name: Playback JS parses
+    run: node --check web/app.js
+    exec: host                         # host-side tool, opts out
+    fast: true                         # cheap → runs on every agent edit
+
+  - id: coverage-ratchet
+    name: Coverage never decreases
+    todo: true                         # declared, tracked, not yet built
+```
+
+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.
+
+## Roadmap
+
+AI-judged rules (`rubric:` — headless Claude applying a markdown rubric to
+changed files) land here as a first-class rule type in a future release.
+Built-in generic rules (spec pairing, focused-spec detection, diff budgets)
+likewise, along with per-framework starter packs (`highball-rails`,
+`highball-python`, `highball-go`) carrying recommended check scripts.

package/bin/highball.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+// The `highball` CLI: a thin dispatcher so each subcommand stays an
+// importable, testable module. `run` owns the process exit code — exit 2
+// is the contract Claude Code hooks read as "block the agent and feed
+// the failure output back".
+import { run } from "../lib/run.js";
+import { init } from "../lib/init.js";
+import { login } from "../lib/login.js";
+import { onboard } from "../lib/onboard.js";
+
+const [command, ...args] = process.argv.slice(2);
+
+const USAGE = `highball — hosted checks for local AI development
+
+Usage:
+  highball run [--fast]     Run this repo's .highball/checks.yml rules.
+                            Exits 2 on failure (blocks Claude Code hooks).
+                            --fast runs only rules marked fast: true.
+  highball init             Scaffold .highball/checks.yml and Claude Code
+                            hooks in the current repo.
+  highball login            Store a project token in
+                            ~/.highball/credentials.json. Reads the token
+                            from stdin with --token-stdin (recommended).
+  highball onboard          Print the setup guide written for this repo's
+                            AI agent — tell your agent to run this and
+                            follow it.
+`;
+
+switch (command) {
+  case "run":
+    process.exit(await run(args));
+    break;
+  case "init":
+    process.exit(await init(args));
+    break;
+  case "login":
+    process.exit(await login(args));
+    break;
+  case "onboard":
+    process.exit(await onboard(args));
+    break;
+  default:
+    console.log(USAGE);
+    process.exit(command === undefined || command === "--help" ? 0 : 1);
+}

package/lib/config.js

@@ -0,0 +1,51 @@
+// Config resolution, kept pure where possible so tests can exercise the
+// decision logic without a filesystem.
+import { readFileSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import YAML from "yaml";
+
+export const CONFIG_PATH = ".highball/checks.yml";
+export const CREDENTIALS_PATH = join(homedir(), ".highball", "credentials.json");
+
+// Loads .highball/checks.yml from the given repo root. Throws with a
+// friendly message — `highball run` outside a configured repo should read
+// as "set me up", not as a stack trace.
+export function loadConfig(root = process.cwd()) {
+  const path = join(root, CONFIG_PATH);
+  if (!existsSync(path)) {
+    throw new Error(`${CONFIG_PATH} not found — run \`highball init\` first.`);
+  }
+  const config = YAML.parse(readFileSync(path, "utf8"));
+  if (!config?.project) throw new Error(`${CONFIG_PATH} is missing \`project:\`.`);
+  if (!Array.isArray(config.checks)) {
+    throw new Error(`${CONFIG_PATH} is missing its \`checks:\` list.`);
+  }
+  return config;
+}
+
+// The reporting URL is per-team committed config; the token never lives
+// in the repo tree: env var (CI) wins, else the machine-local credentials
+// file keyed host → project (the .npmrc / gh-hosts pattern, written by
+// `highball login`).
+export function resolveReporting(config, env = process.env, credentials = readCredentials()) {
+  const url = env.HIGHBALL_URL || config.reporting?.url || null;
+  const token =
+    env.HIGHBALL_TOKEN || (url && credentials?.[url]?.[config.project]) || null;
+  return { url, token };
+}
+
+export function readCredentials(path = CREDENTIALS_PATH) {
+  if (!existsSync(path)) return {};
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+
+// The execution-context decision (ADR 202608): rule definitions stay
+// environment-agnostic; the checkout declares `exec.via` once and every
+// rule runs through it unless it opts out with `exec: host`. No declared
+// context means everything runs on the host unchanged.
+export function commandFor(rule, config) {
+  const via = config.exec?.via;
+  if (!via || rule.exec === "host") return rule.run;
+  return `${via} ${rule.run}`;
+}

package/lib/init.js

@@ -0,0 +1,90 @@
+// `highball init` — scaffolds the .highball/ install unit and the Claude
+// Code hooks. Deliberately conservative: it never overwrites an existing
+// checks.yml, and it never edits an existing .claude/settings.json (hook
+// merging is a human decision — it prints the snippet instead).
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+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,
+# never a failure.
+version: 1
+project: ${project}
+
+# Where runs get reported. The URL is per-team and not a secret, so it
+# lives here in committed config; the token never enters the repo — run
+# \`highball login\` once per machine (or set HIGHBALL_TOKEN in CI).
+# reporting:
+#   url: https://your-highball-host
+
+# If this repo's toolchain lives in a container, declare the wrapper once
+# and every rule runs through it; rules that belong on the host opt out
+# with \`exec: host\`. Omit entirely for host-based setups.
+# exec:
+#   via: docker compose exec -T app
+
+checks:
+  # - id: unit-tests
+  #   name: Unit tests
+  #   run: npm test
+
+  # - id: lint
+  #   name: Lint & formatting
+  #   run: npx eslint .
+  #   fast: true
+`;
+
+const HOOKS_JSON = {
+  hooks: {
+    PostToolUse: [
+      {
+        matcher: "Write|Edit",
+        hooks: [{ type: "command", command: "npx highball run --fast" }]
+      }
+    ],
+    Stop: [
+      {
+        hooks: [{ type: "command", command: "npx highball run", timeout: 900 }]
+      }
+    ]
+  }
+};
+
+export async function init() {
+  const root = process.cwd();
+  const project = basename(root);
+
+  mkdirSync(join(root, ".highball"), { recursive: true });
+
+  const checksPath = join(root, ".highball", "checks.yml");
+  if (existsSync(checksPath)) {
+    console.log(`kept existing ${relative(checksPath, root)}`);
+  } else {
+    writeFileSync(checksPath, CHECKS_TEMPLATE(project));
+    console.log(`created .highball/checks.yml (project: ${project}) — add your rules`);
+  }
+
+  const settingsPath = join(root, ".claude", "settings.json");
+  if (existsSync(settingsPath)) {
+    console.log(
+      "\n.claude/settings.json already exists — merge these hooks yourself:\n" +
+        JSON.stringify(HOOKS_JSON, null, 2)
+    );
+  } else {
+    mkdirSync(join(root, ".claude"), { recursive: true });
+    writeFileSync(settingsPath, JSON.stringify(HOOKS_JSON, null, 2) + "\n");
+    console.log("created .claude/settings.json (fast checks on edit, full suite at turn end)");
+  }
+
+  console.log(
+    "\nnext: fill in .highball/checks.yml, uncomment reporting.url, and run" +
+      "\n  highball login   # stores this machine's project token"
+  );
+  return 0;
+}
+
+function relative(path, root) {
+  return path.startsWith(root) ? path.slice(root.length + 1) : path;
+}

package/lib/login.js

@@ -0,0 +1,68 @@
+// `highball login` — stores a project token in the machine-local
+// credentials file (~/.highball/credentials.json, host → project →
+// token). The token is read from stdin with --token-stdin (recommended:
+// no shell history, no process listing) or prompted interactively.
+// Tokens never touch the repo tree and are never echoed back.
+import { chmodSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { CREDENTIALS_PATH, loadConfig, readCredentials } from "./config.js";
+
+export async function login(args) {
+  const options = parse(args);
+
+  // The local checks.yml, when present, already knows the url + project —
+  // don't make the user repeat what the repo declares.
+  let config = null;
+  try {
+    config = loadConfig();
+  } catch {
+    // Not in a configured repo; url/project must come from flags/prompts.
+  }
+
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const url =
+      options.url ||
+      config?.reporting?.url ||
+      (await rl.question("Highball URL (e.g. https://highball.example.com): "));
+    const project =
+      options.project || config?.project || (await rl.question("Project slug: "));
+    const token = options.tokenStdin
+      ? (await readAllStdin()).trim()
+      : (await rl.question("Project token (input is visible — prefer --token-stdin): ")).trim();
+
+    if (!url || !project || !token) {
+      console.error("highball: url, project, and token are all required.");
+      return 1;
+    }
+
+    const credentials = readCredentials();
+    (credentials[url] ??= {})[project] = token;
+
+    mkdirSync(dirname(CREDENTIALS_PATH), { recursive: true, mode: 0o700 });
+    writeFileSync(CREDENTIALS_PATH, JSON.stringify(credentials, null, 2) + "\n");
+    chmodSync(CREDENTIALS_PATH, 0o600);
+
+    console.log(`stored token for ${project} @ ${url} in ${CREDENTIALS_PATH}`);
+    return 0;
+  } finally {
+    rl.close();
+  }
+}
+
+function parse(args) {
+  const options = { tokenStdin: false };
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--url") options.url = args[++i];
+    else if (args[i] === "--project") options.project = args[++i];
+    else if (args[i] === "--token-stdin") options.tokenStdin = true;
+  }
+  return options;
+}
+
+async function readAllStdin() {
+  let text = "";
+  for await (const chunk of process.stdin) text += chunk;
+  return text;
+}

package/lib/onboard.js

@@ -0,0 +1,12 @@
+// `highball onboard` — prints the agent-facing setup guide. The whole
+// point of shipping it as a command: any repo's AI agent can be told
+// "run `npx highball onboard` and follow it", and the instructions
+// arrive versioned with the runner they describe.
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+export async function onboard() {
+  const path = fileURLToPath(new URL("../ONBOARDING.md", import.meta.url));
+  process.stdout.write(readFileSync(path, "utf8"));
+  return 0;
+}

package/lib/report.js

@@ -0,0 +1,71 @@
+// The witness half: best-effort reporting to the Highball app — open
+// run, per-check results, finalize. Payloads mirror the Ruby
+// proto-runner exactly so the ingestion API sees one dialect. Failures
+// here warn and return; they NEVER fail the checks.
+import { execSync } from "node:child_process";
+import { hostname } from "node:os";
+
+export async function report({ url, token, rules, results, hook, fastOnly, startedAt }) {
+  try {
+    const base = new URL(url);
+    const request = async (method, path, body) => {
+      const response = await fetch(new URL(path, base), {
+        method,
+        headers: {
+          Authorization: `Bearer ${token}`,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(15_000)
+      });
+      if (response.status >= 300) {
+        throw new Error(`${path} -> ${response.status}: ${await response.text()}`);
+      }
+      return response.json();
+    };
+
+    const opened = await request("POST", "/api/v1/runs", {
+      agent: hook.session_id ? "claude-code" : "manual",
+      session_key:
+        hook.session_id || process.env.HIGHBALL_SESSION_KEY || `manual-${hostname()}`,
+      trigger: fastOnly ? "edit" : "stop",
+      branch: git("git branch --show-current"),
+      commit_sha: git("git rev-parse HEAD"),
+      rules_snapshot: rules,
+      started_at: startedAt.toISOString()
+    });
+    const runId = opened.run_id;
+
+    for (const result of results) {
+      await request("POST", `/api/v1/runs/${runId}/results`, {
+        check_key: result.rule.id,
+        name: result.rule.name,
+        status: result.todo ? "todo" : result.passed ? "passed" : "failed",
+        duration_ms: result.durationMs,
+        // Full logs stay local; the tail is enough to read a failure on
+        // the dashboard without shipping megabytes per keystroke.
+        log_tail: result.passed ? null : result.output.slice(-4000),
+        summary: result.todo
+          ? "planned — not implemented yet"
+          : result.passed
+            ? null
+            : result.output.split("\n")[0]?.trim().slice(0, 120)
+      });
+    }
+
+    await request("PATCH", `/api/v1/runs/${runId}`, {
+      status: results.every((result) => result.passed) ? "passed" : "failed"
+    });
+    console.log(`reported to ${base.host} (run ${runId})`);
+  } catch (error) {
+    console.error(`highball reporting skipped: ${error.message}`);
+  }
+}
+
+function git(command) {
+  try {
+    return execSync(`${command} 2>/dev/null`, { encoding: "utf8" }).trim();
+  } catch {
+    return "";
+  }
+}

package/lib/run.js

@@ -0,0 +1,121 @@
+// `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.
+import { execSync, spawnSync } from "node:child_process";
+import { loadConfig, resolveReporting, commandFor } from "./config.js";
+import { report } from "./report.js";
+
+export async function run(args) {
+  // When an AI-judged rule spawns a judge session inside this repo, the
+  // judge inherits the repo's hooks — and its Stop hook would re-enter
+  // this runner and spawn another judge, forever. The env var breaks the
+  // loop.
+  if (process.env.HIGHBALL_JUDGE) return 0;
+
+  const fastOnly = args.includes("--fast");
+  let config;
+  try {
+    config = loadConfig();
+  } catch (error) {
+    console.error(`highball: ${error.message}`);
+    return 1;
+  }
+
+  const rules = fastOnly ? config.checks.filter((rule) => rule.fast) : config.checks;
+  const hook = await readHookPayload();
+  const changed = changedFiles();
+
+  // Captured before the loop and reported as the run's started_at: the
+  // run is opened AFTER checks finish (one reporting burst, no mid-run
+  // network stalls), so without this the server would clock the run at
+  // the length of the reporting window instead of the checks themselves.
+  const startedAt = new Date();
+  const results = [];
+
+  for (const rule of rules) {
+    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
+    // fail a run — an aspiration shouldn't block anyone.
+    if (rule.todo) {
+      console.log("todo (not implemented yet)");
+      results.push({ rule, passed: true, todo: true, durationMs: null, output: "" });
+      continue;
+    }
+
+    const command = commandFor(rule, config);
+    const t0 = process.hrtime.bigint();
+    // The runner owns git (ADR 202608): check scripts get the changed
+    // list handed to them and stay pure analyzers — no git, no network
+    // required in their execution context (which may be a container).
+    const child = spawnSync(`${command} 2>&1`, {
+      shell: true,
+      encoding: "utf8",
+      env: { ...process.env, HIGHBALL_CHANGED_FILES: changed },
+      maxBuffer: 32 * 1024 * 1024
+    });
+    const durationMs = Math.round(Number(process.hrtime.bigint() - t0) / 1e6);
+    const output = child.stdout ?? "";
+    const passed = child.status === 0;
+
+    console.log(`${passed ? "passed" : "FAILED"} (${(durationMs / 1000).toFixed(1)}s)`);
+    results.push({ rule, passed, todo: false, durationMs, output });
+  }
+
+  const failures = results.filter((result) => !result.passed);
+
+  const { url, token } = resolveReporting(config);
+  if (url && token) {
+    await report({ url, token, project: config.project, rules, results, hook, fastOnly, startedAt });
+  }
+
+  if (failures.length === 0) return 0;
+
+  for (const failure of failures) {
+    console.error(
+      `\n### ${failure.rule.name} (${failure.rule.id}) failed. ` +
+        `Fix before finishing:\n${failure.output}`
+    );
+  }
+  return 2;
+}
+
+// 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
+// read.
+async function readHookPayload() {
+  if (process.stdin.isTTY) return {};
+  try {
+    let text = "";
+    for await (const chunk of process.stdin) text += chunk;
+    return JSON.parse(text);
+  } catch {
+    return {};
+  }
+}
+
+// Changed = branch work in progress: tracked edits vs HEAD plus
+// untracked files. Handed to check scripts via HIGHBALL_CHANGED_FILES
+// (newline-separated, repo-relative). Skipped past 100KB — env vars
+// share the OS arg-space budget, and a monster refactor shouldn't make
+// every rule invocation fail; scripts fall back to their own git.
+function changedFiles() {
+  try {
+    const tracked = execSync("git diff --name-only HEAD", { encoding: "utf8" });
+    const untracked = execSync("git ls-files --others --exclude-standard", {
+      encoding: "utf8"
+    });
+    const list = `${tracked}\n${untracked}`
+      .split("\n")
+      .map((line) => line.trim())
+      .filter(Boolean)
+      .join("\n");
+    return list.length > 100_000 ? "" : list;
+  } catch {
+    return "";
+  }
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@profoundry-us/highball",
+  "version": "0.1.0",
+  "description": "Highball runner — local CI for AI coding agents: runs a repo's .highball/checks.yml rules, blocks the agent on failure, and reports runs to a Highball dashboard.",
+  "keywords": [
+    "ai",
+    "claude-code",
+    "hooks",
+    "checks",
+    "ci",
+    "code-quality"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/profoundry-us/highball-runner.git"
+  },
+  "homepage": "https://github.com/profoundry-us/highball-runner#readme",
+  "bugs": {
+    "url": "https://github.com/profoundry-us/highball-runner/issues"
+  },
+  "type": "module",
+  "bin": {
+    "highball": "bin/highball.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md",
+    "ONBOARDING.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "dependencies": {
+    "yaml": "^2.5.0"
+  },
+  "license": "MIT"
+}