@workit-dev/claude-code 0.0.0-stage → 1.0.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "workit",
+  "displayName": "Workit",
+  "version": "1.0.0",
+  "description": "Workflow rails for agentic coding: task context on every session, branch policy on shell commands, and the workit method skills",
+  "author": {
+    "name": "BrainerVirus"
+  },
+  "homepage": "https://github.com/BrainerVirus/workit#readme",
+  "repository": "https://github.com/BrainerVirus/workit",
+  "license": "MIT",
+  "keywords": [
+    "agentic-coding",
+    "branch-policy",
+    "skills",
+    "task-management",
+    "workflow"
+  ]
+}

package/README.md

@@ -1,3 +1,49 @@
-# Temporary Holding Version
+# @workit-dev/claude-code
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![CI](https://github.com/BrainerVirus/workit/actions/workflows/ci.yml/badge.svg)](https://github.com/BrainerVirus/workit/actions/workflows/ci.yml)
+[![license: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/BrainerVirus/workit/blob/main/LICENSE)
+
+[Workit](https://github.com/BrainerVirus/workit) plugin for Claude Code: task context on session start and per turn,
+branch policy on `git` shell commands, the before-write gate on edits and shell
+writes, thirteen method skills (`/workit:<name>`),
+and `verifier`, `reviewer` and `implementer` agents.
+
+## Install
+
+Latest published (the repository root is the marketplace; its entry installs
+this npm package):
+
+```bash
+claude plugin marketplace add BrainerVirus/workit
+claude plugin install workit@workit
+```
+
+Update with `workit upgrade` (native fallback: `claude plugin marketplace update workit && claude plugin update workit@workit`), then restart Claude Code; uninstall with `workit uninstall`.
+
+Local pin to a checkout (hooks and `bin/workit` run the sources with Bun):
+
+```bash
+bun install
+bun packages/workit-claude-code/scripts/build.ts --skills-only
+claude --plugin-dir "$PWD/packages/workit-claude-code"
+# or, for every session:
+export CLAUDE_CODE_PLUGIN_DIRS="$HOME/path/to/workit/packages/workit-claude-code"
+```
+
+`WORKIT_CLAUDE_RUNTIME=source|dist` forces one runtime;
+`WORKIT_SHIM_TRACE=1 workit …` prints which `workit` entry ran.
+
+## Layout
+
+| Path | Purpose |
+| --- | --- |
+| `.claude-plugin/plugin.json` | Manifest (version synced at release) |
+| `hooks/hooks.json` | SessionStart (startup/resume/clear/compact/fork), UserPromptSubmit, PreToolUse (Bash, PowerShell, Edit/Write/MultiEdit/NotebookEdit), SubagentStart |
+| `bin/workit-hook.mjs` | Hook launcher: source with Bun in a checkout, `dist/workit-hook.js` when installed; answers plain shell commands and edits in task-less checkouts with `{}` before loading the runtime; fails open (`{}` + one stderr line) when neither can run |
+| `bin/workit` | `workit` on the Bash tool's PATH (same source/dist switch) |
+| `agents/` | `verifier`, `reviewer` (read-only), `implementer` (works in the lead's `workit fanout worktree create` worktree; no `isolation`) |
+| `skills/` | Generated by `scripts/build.ts` from `packages/workit-core/skills` (not committed) |
+
+Requires Node.js 24+ (installed plugin) or Bun (local pin).
+
+Full guide: [Claude Code](https://github.com/BrainerVirus/workit/blob/main/docs/guides/claude-code.md).

package/agents/implementer.md

@@ -0,0 +1,56 @@
+---
+name: implementer
+description: Implements one scoped workit brief in the git worktree its lead made with `workit fanout worktree create`, and reports what changed and how it was checked. Use to delegate a well-defined slice (goal, scope, acceptance, verify, forbidden, report, worktree) so it can run in parallel with other work.
+---
+
+You are a workit implementer. You work only in the git worktree your brief
+names (its WORKTREE line), which the lead made with
+`workit fanout worktree create <slice>` before spawning you; never in the
+lead's checkout.
+
+Refuse to start without a complete brief. It must state: goal, scope (files
+or areas you may touch), acceptance (observable outcomes), verify (exact
+commands), timebox, forbidden (what you must not touch or do), report (what to
+hand back), standing orders, mode (`new` or `resume`) and the worktree path.
+If a field is missing, report which and stop.
+
+1. In a Workit worktree (the default), run each git and check command against
+   it, one verb per call:
+   `workit git --cwd <worktree> commit …`, `workit check --cwd <worktree> <name>`
+   (verb first, so the host's allow rules match).
+   Never `cd <worktree> && …` chains, `$VAR` paths or compound commands. Edit
+   files by their path under the worktree. Workit's hooks deny an edit or a
+   mutating git command outside it.
+2. The worktree is already on the brief's branch. If it is not: `MODE: new`,
+   `workit git --cwd <worktree> branch <branch> --base <base>`; `MODE: resume`
+   (you replace a stopped worker), `git -C <worktree> switch <branch>` and
+   continue from its head. A hook denies protected or non-compliant names;
+   follow the unblock it prints.
+3. Stay inside the scope. Anything outside it is a follow-up in the report,
+   not a diff. Follow the workit-implement skill (`/workit:implement`).
+4. Decide ambiguities yourself and record them:
+   `workit ledger ruling "<what>" --why "<why>" --cost-if-wrong "<cost>"`.
+   Stop only for an irreversible or security-sensitive action, or a side effect
+   outside your worktree.
+5. Commit in small steps with
+   `workit git --cwd <worktree> commit -m "<conventional message>" -- <paths in scope>`.
+   Add Co-Authored-By in the same commit with
+   `workit git commit --trailer "Co-Authored-By: <name> <email>" -- <paths>`
+   (the brief's RULES give your host's exact line), never by amending.
+6. Run every verify command as `workit check --cwd <worktree> …` and keep the
+   real exit codes.
+7. Never record a verdict on your own work and never pass `--self`: a separate
+   verifier judges it. Never push, open a PR, rebase or merge unless the brief
+   says so.
+
+In a Claude Code host-isolated worktree (`.claude/worktrees/agent-<id>`,
+whose SubagentStart text says "Run git as plain") the rule flips: run git as
+plain commands there, never `workit git …` (Claude Code's isolation refuses a
+git wrapper), and keep workit for `check`, `ledger` and `pr`.
+
+Before your final report, wait for or stop every background command you started
+(the host shows you running while one lives); never report with one still running.
+
+Report: worktree, branch and head SHA, files changed, each verify command with
+its exit code, each acceptance item met or not, rulings recorded, and any
+deviation from the brief.

package/agents/reviewer.md

@@ -0,0 +1,33 @@
+---
+name: reviewer
+description: Fresh-context reviewer for a workit branch or PR - spec fidelity and standards as separate axes, test quality and blast radius - that records findings and a non-author verdict. Use for independent review of a diff, branch or PR.
+tools: Read, Grep, Glob, Bash, Skill
+disallowedTools: Write, Edit, NotebookEdit
+---
+
+You are the workit reviewer. Review the real candidate, never the author's
+description of it. Follow the workit-review skill (`/workit:review`).
+
+1. Pin the candidate: `git rev-parse HEAD`, the base, `git diff <base>...HEAD`;
+   for a PR, `workit pr status --json` for checks and unresolved threads.
+2. Read the intent: brief or acceptance criteria, spec, PR body, and
+   `workit ledger list --type decision`.
+3. Judge two axes separately: spec fidelity (missing, creep, wrong; quote the
+   line) and standards (repo rules first, then smells). Then test quality
+   (`workit test-audit --diff`) and blast radius: one fact plus one proof per
+   touched contract or caller, run with `workit check -- <cmd>`; label anything
+   unproven UNPROVEN.
+4. Each finding: file:line, severity (blocker, major, minor, nit), evidence
+   (hunk, test or command output), concrete fix.
+5. Record the verdict:
+   start from the exact verdict command the SubagentStart hook put in your context (it
+   carries your session and `--token=<token>`; the token is yours alone: never put it in a report); it already names `--kind review`:
+   `workit ledger verdict verified|failed|blocked --kind review --branch <b> --session <id> --token=<token> --how "<what you read and ran>"`
+   (`verified` with `--kind review`: no blocker or major finding left).
+   Record a design choice you had to make as `workit ledger ruling`.
+
+Before your final report, wait for or stop every background command you started
+(the host shows you running while one lives); never report with one still running.
+
+Stay read-only: read and test commands only, never commits, pushes, merges or
+edits. If the ledger refuses you as an author, report that instead of a verdict.

package/agents/verifier.md

@@ -0,0 +1,40 @@
+---
+name: verifier
+description: Independently verifies a workit candidate (branch, commit or PR) on its real surface and records a SHA-keyed verdict in the ledger. Use after an implementer finishes and before shipping, never on work this session authored.
+tools: Read, Grep, Glob, Bash, Skill
+disallowedTools: Write, Edit, NotebookEdit
+---
+
+You are the workit verifier. You did not write the candidate and you never
+change it: you observe, judge and record. Start from the goal and work
+backward: what must be true, what must exist, what must be wired. The author's
+summary is a claim, not evidence; assume the goal is not met until you observe
+it.
+
+1. Pin the candidate in its own checkout (run workit as
+   `workit <verb> --cwd <worktree> …`, verb first; never `cd` first): `git -C <worktree> rev-parse HEAD` and `git -C <worktree> status --short`. A dirty tree
+   or a moving HEAD is itself a finding, and the ledger refuses a verdict on it.
+2. Read the brief: goal, acceptance (Given/When/Then), verify commands.
+3. Run every verify command through the CLI so the result is observed:
+   `workit check <name>` for configured checks, `workit check -- <cmd>` for the
+   rest. Never substitute an easier command. Run every configured check by name
+   (your SubagentStart context lists them) or cite green CI on that head; otherwise, `verified` is refused.
+4. Drive the real surface with the project's `verify-<app>` skill when it
+   exists (`/workit:verify-app` generates one). Tests alone are unit evidence.
+5. Judge each acceptance line as met, not met, or not verifiable, citing what
+   you observed. Label every claim measured, inferred or guess.
+6. Record the verdict, then report it:
+   start from the exact verdict command the SubagentStart hook put in your context (it
+   carries your session and `--token=<token>`; you share the lead's
+   `WORKIT_SESSION_ID`, which authored the work) and pick its `--kind <live|unit>`:
+   `workit ledger verdict verified|tests-verified|type-check-only|failed|blocked --kind <live|unit> --branch <b> --session <id> --token=<token> --how "<what you ran and saw>"`.
+   `verified` means the change was observed working on its real surface
+   (verify-<app>, `--kind live`); `tests-verified` means only tests ran. If the ledger refuses you as an author, report that;
+   never pass `--self` to get around it.
+
+Before your final report, wait for or stop every background command you started
+(the host shows you running while one lives); never report with one still running.
+
+Report: candidate SHA, each check with its exit code, each acceptance line,
+the verdict row you recorded. Do not fix anything you find: a failing check is
+a verdict, not a task.

package/assets/templates/headers.md

@@ -0,0 +1,3 @@
+## Adjunto capturas
+
+## Archivos adjuntos

package/assets/templates/hygiene/.editorconfig

@@ -0,0 +1,8 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 2

package/assets/templates/hygiene/.gitattributes

@@ -0,0 +1,3 @@
+* text=auto
+*.md text
+*.bat text eol=crlf

package/assets/templates/hygiene/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+### Changed
+
+### Fixed

package/assets/templates/hygiene/CONTRIBUTING.md

@@ -0,0 +1,3 @@
+# Contributing
+
+<!-- How to report issues, propose changes, and the review process. -->

package/assets/templates/hygiene/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) <YEAR> <HOLDER>
+
+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/assets/templates/hygiene/README.md

@@ -0,0 +1,3 @@
+# <PROJECT>
+
+<!-- Describe the project: what it does, how to run it, how to contribute. -->

package/assets/templates/issue-update.md

@@ -0,0 +1,5 @@
+# Update
+{{projectSection}}
+{{userNotesSection}}
+{{progressSection}}
+{{gitCommitsSection}}

package/assets/templates/plan-template.md

@@ -0,0 +1,26 @@
+# <Feature> plan
+
+Spec: `docs/<slug>/spec.md` · Goal: <one sentence>
+
+A plan records decisions, not code: per slice the branch, what it touches, its
+acceptance, how it is verified, and what it depends on (workit-shape
+`references/slicing.md`). Independent slices fan out (workit-fanout);
+dependent ones stack (`workit stack plan <bottom> … <top>`).
+
+## Global constraints
+
+- <project-wide requirement, one line each>
+
+---
+
+### S1 <type>/<slug>  (base: main)
+
+Touches: <areas, not line numbers>
+Acceptance:
+- Given <state>, When <action>, Then <observable result>
+Verify: `workit check test`; verify-<app> "<feature>"
+Decisions: <ledger refs or one-line rulings>
+
+| Slice | Branch | Depends on | Status |
+| --- | --- | --- | --- |
+| S1 | <type>/<slug> | — | pending |

package/assets/templates/spec-template.md

@@ -0,0 +1,64 @@
+# Spec: <feature>
+
+**Branch:** `feature/<slug>`
+
+**Change:** ADDED|MODIFIED|REMOVED — <one-sentence intent>. (Small work with
+no durable agreement: `Spec: none (<reason>)`, no file.)
+
+## Context
+
+<!-- Why does this exist? What problem does it solve? 1-3 sentences. -->
+
+## Goals
+
+- <!-- measurable, one per bullet -->
+
+## Non-goals
+
+- <!-- explicitly out of scope -->
+
+## Architecture
+
+<!-- Optional: only when a diagram argues a decision (workit-shape
+     references/diagrams.md); otherwise delete this section. -->
+```mermaid
+flowchart TD
+  A[Start] --> B[Step]
+```
+
+<!-- Optional: a UI choice still open gets an ASCII sketch (workit-shape
+     references/mockups.md). -->
+```text
+┌──────────────┐
+│ Header       │
+└──────────────┘
+```
+
+## Data flow / contracts
+
+<!-- REQUIRED when there is a glossary, scope comparison, or contracts: use markdown tables. -->
+| Term | Meaning |
+| --- | --- |
+| <term> | <meaning> |
+
+## Acceptance criteria
+
+<!-- REQUIRED: enumerable, each verifiable. Numbered CA-01, CA-02, ... -->
+<!-- Requirements use SHALL/MUST (one per bullet, observable, no HOW); each
+     carries at least one GIVEN/WHEN/THEN, including the most-regretted edge. -->
+- CA-01 …
+
+## Review checklist
+
+<!-- Before implementation: intent matches; nothing extra; each requirement
+     testable with an exercising scenario; most-cared case covered;
+     tasks trace to requirements; you would sign if built exactly as written. -->
+- [ ] …
+
+## Decisions
+
+- D-01 …
+
+## Future work
+
+- …

package/assets/templates/workit-contract.md

@@ -0,0 +1,13 @@
+# Workit contract
+
+Workit keeps one accountable lead and one shared task state. Inspect current
+task state before acting; use only the shared operations for task, policy,
+evidence, finding, decision, worker, and state changes. Authority is
+bounded by the requested scope, current revision, caller/session provenance, and
+observed capabilities; delivery is bounded by the workspace autonomy grants
+(`workit grant show`). Never claim host enforcement or evidence that the host
+cannot provide. Preserve unresolved requirements, gaps, and uncertain workers.
+
+Focused methods are loaded only when the resolved policy requires them. A method
+must call the shared operations and must not create a second lifecycle, approval
+chain, or task-state representation.

package/bin/node-resolve.mjs

@@ -0,0 +1,249 @@
+// Finds a Node that can run a Workit hook when the PATH node is below the
+// package's engines floor (a repo pinned to Node 16/18/22 by a version
+// manager). Plain JavaScript with node: builtins only and no syntax newer than
+// Node 16 supports: the host launchers import it (or carry a byte-equal copy,
+// a test holds them equal) and must start on the very Node they are replacing.
+// Side-effect free: importing it runs nothing; no process is spawned here.
+//
+// Order: (1) $WORKIT_NODE; (2) the node `workit setup`/`upgrade` recorded in
+// <state dir>/node.json (workit-paths.mjs); (3) a scan of version-manager installs (fnm, nvm,
+// volta, mise, asdf and the Windows layouts), highest version >= the floor.
+import { spawnSync } from "node:child_process";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { stateDir } from "./workit-paths.mjs";
+
+/** The Node major the hooks need; a test holds it equal to every package's engines.node. */
+export const HOOK_NODE_FLOOR = [24, 0, 0];
+
+/** Set on the re-executed child so a launcher never re-executes twice. */
+export const HOOK_NODE_REEXEC_ENV = "WORKIT_HOOK_REEXEC";
+
+const MAX_ENTRIES_PER_ROOT = 200;
+
+/** @param {unknown} text @returns {number[] | null} */
+export const parseNodeVersion = (text) => {
+  const found = /^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?/.exec(String(text).trim());
+  return found ? [Number(found[1]), Number(found[2] || 0), Number(found[3] || 0)] : null;
+};
+
+/** @param {number[]} a @param {number[]} b negative when a < b */
+export const compareVersions = (a, b) => {
+  for (let i = 0; i < 3; i++) if (a[i] !== b[i]) return a[i] - b[i];
+  return 0;
+};
+
+/** The `>=X[.Y[.Z]]` minimum of an engines.node range, or null. @param {unknown} range */
+export const floorOfRange = (range) => {
+  const min = /^>=\s*(\d+)(?:\.(\d+))?(?:\.(\d+))?/.exec(String(range === undefined ? "" : range));
+  return min ? [Number(min[1]), Number(min[2] || 0), Number(min[3] || 0)] : null;
+};
+
+/** Workit's state dir (workit-paths.mjs, the one resolver). @param {NodeJS.ProcessEnv} env */
+export const hookStateDir = (env) => stateDir(env);
+
+/** @param {string} file */
+const isFile = (file) => {
+  try {
+    return statSync(file).isFile();
+  } catch {
+    return false;
+  }
+};
+
+/** @param {string} file */
+const readJson = (file) => {
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return undefined;
+  }
+};
+
+/**
+ * The version-manager directories that hold one node per child directory:
+ * `{ dir, bin }` where the node is `<dir>/<child>/<bin>`.
+ * @param {NodeJS.ProcessEnv} env @param {string} platform
+ */
+const scanRoots = (env, platform) => {
+  const home = env.HOME || env.USERPROFILE || os.homedir();
+  const win = platform === "win32";
+  const exe = win ? "node.exe" : "node";
+  const bin = win ? exe : path.join("bin", exe);
+  /** @type {Array<{ dir: string, bin: string }>} */
+  const roots = [];
+  const add = (dir, rel) => {
+    if (dir) roots.push({ dir, bin: rel });
+  };
+  // fnm: <dir>/node-versions/<v>/installation/bin/node
+  const fnmDirs = [
+    env.FNM_DIR,
+    win ? path.join(env.APPDATA || path.join(home, "AppData", "Roaming"), "fnm") : "",
+    win ? path.join(env.LOCALAPPDATA || path.join(home, "AppData", "Local"), "fnm") : "",
+    env.XDG_DATA_HOME ? path.join(env.XDG_DATA_HOME, "fnm") : "",
+    path.join(home, ".local", "share", "fnm"),
+    path.join(home, "Library", "Application Support", "fnm"),
+    path.join(home, ".fnm"),
+  ];
+  for (const dir of fnmDirs)
+    if (dir) add(path.join(dir, "node-versions"), path.join("installation", bin));
+  // nvm: <dir>/versions/node/<v>/bin/node; nvm-windows: <NVM_HOME>/<v>/node.exe
+  for (const dir of [env.NVM_DIR, path.join(home, ".nvm")])
+    if (dir) add(path.join(dir, "versions", "node"), bin);
+  if (env.NVM_HOME) add(env.NVM_HOME, exe);
+  // volta: <dir>/tools/image/node/<v>/bin/node
+  const volta = env.VOLTA_HOME || (win ? "" : path.join(home, ".volta"));
+  if (volta) add(path.join(volta, "tools", "image", "node"), bin);
+  if (win)
+    add(
+      path.join(
+        env.LOCALAPPDATA || path.join(home, "AppData", "Local"),
+        "Volta",
+        "tools",
+        "image",
+        "node",
+      ),
+      bin,
+    );
+  // mise and asdf: <dir>/installs/node[js]/<v>/bin/node
+  const mise = env.MISE_DATA_DIR || path.join(home, ".local", "share", "mise");
+  add(path.join(mise, "installs", "node"), bin);
+  const asdf = env.ASDF_DATA_DIR || path.join(home, ".asdf");
+  add(path.join(asdf, "installs", "nodejs"), bin);
+  return roots;
+};
+
+/**
+ * Every installed node a version manager lists, with its version: directory
+ * listings only, at most MAX_ENTRIES_PER_ROOT per root.
+ * @param {NodeJS.ProcessEnv} env @param {string} [platform]
+ * @returns {Array<{ path: string, version: number[], source: string }>}
+ */
+export const scanInstalledNodes = (env, platform = process.platform) => {
+  /** @type {Array<{ path: string, version: number[], source: string }>} */
+  const found = [];
+  for (const root of scanRoots(env, platform)) {
+    let names;
+    try {
+      names = readdirSync(root.dir).slice(0, MAX_ENTRIES_PER_ROOT);
+    } catch {
+      continue;
+    }
+    for (const name of names) {
+      const version = parseNodeVersion(name);
+      if (!version || !/^v?\d/.test(name)) continue;
+      // volta's layout nests nothing; fnm's, nvm's, mise's and asdf's differ only in `bin`.
+      const candidate = path.join(root.dir, name, root.bin);
+      if (isFile(candidate)) found.push({ path: candidate, version, source: root.dir });
+    }
+  }
+  return found;
+};
+
+/**
+ * The node the hooks should run on, or null. `floor` is [major, minor, patch].
+ * @param {{ env: NodeJS.ProcessEnv, floor: number[], platform?: string }} options
+ * @returns {{ path: string, version: string | null, source: "env" | "recorded" | "scan" } | null}
+ */
+export const resolveHookNode = ({ env, floor, platform = process.platform }) => {
+  if (env.WORKIT_NODE && isFile(env.WORKIT_NODE))
+    return { path: env.WORKIT_NODE, version: null, source: "env" };
+  const recorded = readJson(path.join(hookStateDir(env), "node.json"));
+  if (recorded && typeof recorded.path === "string" && isFile(recorded.path)) {
+    const version = parseNodeVersion(recorded.version);
+    if (version && compareVersions(version, floor) >= 0)
+      return { path: recorded.path, version: String(recorded.version), source: "recorded" };
+  }
+  let best = null;
+  for (const entry of scanInstalledNodes(env, platform))
+    if (
+      compareVersions(entry.version, floor) >= 0 &&
+      (!best || compareVersions(entry.version, best.version) > 0)
+    )
+      best = entry;
+  return best ? { path: best.path, version: best.version.join("."), source: "scan" } : null;
+};
+
+/**
+ * The fail-open line for a node below the floor: null when `found` is at or
+ * above `floor`, or unparseable (an unreadable version never blocks).
+ * @param {string} found @param {number[] | null} floor @param {string} range
+ */
+export const floorMessage = (found, floor, range) => {
+  if (!floor) return null;
+  const have = parseNodeVersion(found);
+  if (!have || compareVersions(have, floor) >= 0) return null;
+  return `needs Node ${range}, found ${found}`;
+};
+
+/** What the agent is told once, at SessionStart, when no Node >= the floor resolves. */
+export const nodeFloorNotice = (found, range) =>
+  `Workit hooks are off: the Node on PATH is ${String(found).replace(/^v/, "")}, below the required ${range}, and no Node 24+ was found. ` +
+  "Install Node 24 (fnm install 24, nvm install 24) or run `workit setup` from a Node 24 shell so Workit can record it; " +
+  "`workit doctor` (check hook_node) shows what the hooks run on.";
+
+/**
+ * Where setup and upgrade record the Node they run on. A no-op for a non-node
+ * binary (bun) or a Node below the floor.
+ * @param {{ env: NodeJS.ProcessEnv, execPath: string, version: string, floor: number[] }} options
+ * @returns {string | null} the file written
+ */
+export const nodeRecord = ({ env, execPath, version, floor }) => {
+  const parsed = parseNodeVersion(version);
+  if (!parsed || compareVersions(parsed, floor) < 0) return null;
+  if (!/^node(?:\.exe)?$/i.test(path.basename(execPath))) return null;
+  return path.join(hookStateDir(env), "node.json");
+};
+
+/**
+ * Run `script args…` on `nodePath` with this process's stdin, stdout and
+ * stderr passed through. The child carries the re-exec guard and a real
+ * version (WORKIT_HOOK_NODE_VERSION, a test seam, is dropped).
+ * @returns {number | null} the child's exit code, or null when it could not start
+ */
+export const reexecOnNode = (nodePath, script, args, env) => {
+  const child = Object.assign({}, env, { [HOOK_NODE_REEXEC_ENV]: "1" });
+  delete child.WORKIT_HOOK_NODE_VERSION;
+  const run = spawnSync(nodePath, [script].concat(args), {
+    stdio: "inherit",
+    env: child,
+    windowsHide: true,
+  });
+  if (run.error) return null;
+  return run.status === null ? 1 : run.status;
+};
+
+/**
+ * What a launcher does on a Node below its floor: re-run itself on a resolved
+ * Node (the child's exit code is returned), else fail open: one stderr line,
+ * and `{}` on stdout, except that a start event answers with `notice(text)` so
+ * the agent is told the hooks are off. Resolves to the exit code.
+ * @param {{ host: string, range: string, floor: number[], found: string, script: string,
+ *   argv: string[], env: NodeJS.ProcessEnv, isStart: (event: unknown) => boolean,
+ *   notice: (text: string) => unknown }} options
+ */
+export const handleBelowFloor = async (options) => {
+  if (!options.env[HOOK_NODE_REEXEC_ENV]) {
+    const hit = resolveHookNode({ env: options.env, floor: options.floor });
+    const code = hit ? reexecOnNode(hit.path, options.script, options.argv, options.env) : null;
+    if (code !== null) return code;
+  }
+  process.stderr.write(
+    `[workit] ${options.host} hook unavailable: needs Node ${options.range}, found ${options.found}\n`,
+  );
+  let early = "";
+  for await (const chunk of process.stdin) early += String(chunk);
+  let event;
+  try {
+    event = JSON.parse(early).hook_event_name;
+  } catch {
+    event = undefined;
+  }
+  process.stdout.write(
+    options.isStart(event)
+      ? `${JSON.stringify(options.notice(nodeFloorNotice(options.found, options.range)))}\n`
+      : "{}\n",
+  );
+  return 0;
+};