no-human 0.1.1__tar.gz

no_human-0.1.1/.gitignore

@@ -0,0 +1,63 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+# desktop/build is electron-builder's buildResources. Neither icon.icns nor
+# icon.ico is tracked: both are build OUTPUTS, derived at package time from
+# web/public/nh-mark-512.png by packaging/derive-icons.mjs — see that file's
+# header comment for why the binaries stopped being committed.
+!desktop/build/
+desktop/build/*
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Secrets & local state — never commit
+.env
+*.key
+*.pem
+.no_human/
+secrets/
+*.db
+*.db-wal
+*.db-shm
+# ...except the memory-triage runbook's committed test fixture: a tracked
+# INPUT (synthetic, neutral content -- see EXPORT_CLASSIFICATION.txt).
+!testdata/memory_triage_fixture.db
+
+# Test scratch
+/tmp_e2e/
+# pytest's node-id cache stores collected test names verbatim, so it carries
+# whatever the test bodies spell. It was NOT ignored — only `__pycache__/` and
+# `*.py[oc]` were — so a `git add -A` after a test run could have tracked it.
+.pytest_cache/
+
+# IDE-generated (skills, local settings)
+.claude/
+.windsurf/
+
+# web build
+web/node_modules/
+
+# north-star bench: the raw built corpus is verbatim operator conversation
+# content (personal + enterprise) — never committed. Curated specs live one
+# level up and ARE tracked.
+eval/northstar_tasks/generated/
+# Machine-local translation from vendor-neutral spec paths to real checkouts.
+# Holds real repo names by definition — never committed.
+eval/repo_map.yaml
+eval/results/northstar/
+
+# desktop shell
+desktop/node_modules/
+# also match a SYMLINK: a trailing slash only matches a directory, so a
+# symlinked node_modules slipped past and got committed as an absolute path.
+desktop/node_modules
+web/node_modules
+desktop/dist/
+
+# The adoption harness writes its report here on every run.
+e2e/adoption/out/

no_human-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eyal Golan
+
+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.

no_human-0.1.1/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.5
+Name: no-human
+Version: 0.1.1
+Summary: Autonomous AI software-delivery orchestrator driving the Claude Agent SDK on your own Claude credentials
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: aiosqlite>=0.22.1
+Requires-Dist: claude-agent-sdk>=0.2.120
+Requires-Dist: click>=8.4.1
+Requires-Dist: fastapi>=0.138.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: mcp>=1.28.0
+Requires-Dist: psutil>=7.0.0
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: rich>=15.0.0
+Requires-Dist: slack-sdk>=3.43.0
+Requires-Dist: textual>=8.2.7
+Requires-Dist: uvicorn[standard]>=0.49.0
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<img src="docs/assets/nh-mark.png" alt="" width="140" height="140">
+
+# no_human
+
+**From ticket to reviewed pull request.**<br>***Free and open-source, on your machine.***
+
+[![latest release](https://img.shields.io/github/v/release/no-human-ai/no_human?label=release&color=4C9AFF)](https://github.com/no-human-ai/no_human/releases/latest) [![CI](https://img.shields.io/github/actions/workflow/status/no-human-ai/no_human/ci.yml?branch=main&label=CI)](https://github.com/no-human-ai/no_human/actions/workflows/ci.yml) [![python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/) [![license MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+[getnohuman.com](https://getnohuman.com) · [Quickstart](docs/quickstart.md) · [Docs](docs/README.md) · [Watch it work a sprint](https://getnohuman.com/demo)
+
+[![Download for macOS](https://img.shields.io/badge/Download%20for-macOS-4C9AFF?style=for-the-badge)](https://github.com/no-human-ai/no_human/releases/latest) [![Download for Windows](https://img.shields.io/badge/Download%20for-Windows-4C9AFF?style=for-the-badge)](https://github.com/no-human-ai/no_human/releases/latest) [![Download for Linux](https://img.shields.io/badge/Download%20for-Linux-4C9AFF?style=for-the-badge)](https://github.com/no-human-ai/no_human/releases/latest)
+
+<a href="https://getnohuman.com/"><img src="docs/assets/hero-loop-poster.jpg" alt="The no_human board: one task waiting on a question in Needs answer, four tasks working in parallel, one pull request ready for review." width="880"></a>
+
+<sub>▶ <a href="https://getnohuman.com/">Watch the loop</a> — a ticket in, a reviewed pull request out; the whole loop in 57 seconds.</sub>
+
+</div>
+
+The AI coding factory you <ins>**can trust**</ins>:
+
+- **A plan before any code**, from the ticket plus what it finds in your repo.
+- **An adversarial review.** A different model, fresh context, read-only tools,
+  told to refute "done". You get a pass/fail checklist citing file and line —
+  never a numeric self-score.
+- **A tamper guard.** Deleted tests, new skips, an assertion turned into a
+  tautology — blocked before a reviewer token is spent.
+- **Proof the fix fixed the bug.** For a bug fix, the tests offered as evidence
+  must fail at the merge base and pass on the new tree — the reproduction gate
+  enforces that, and you can require it for every change.
+- **Your tests run**, locally and optionally through your CI.
+- **An honest stop.** When it cannot finish, it parks with one specific question
+  instead of inventing a plausible diff.
+
+## Install
+
+Whichever way you install, you need a **Claude credential**: an OAuth token
+from `claude setup-token` (personal subscription or enterprise), so install the
+Claude Code CLI first — `npm install -g @anthropic-ai/claude-code`, or
+`curl -fsSL https://claude.ai/install.sh | bash`. The desktop app also calls
+that CLI for every task. To pay Anthropic directly instead, set
+`llm.auth_mode: "api_key"` and put your `ANTHROPIC_API_KEY` in
+`~/.no_human/.env`.
+
+### Desktop app
+
+[![Download for macOS](https://img.shields.io/badge/Download%20for-macOS-4C9AFF?style=for-the-badge)](https://github.com/no-human-ai/no_human/releases/latest) [![Download for Windows](https://img.shields.io/badge/Download%20for-Windows-4C9AFF?style=for-the-badge)](https://github.com/no-human-ai/no_human/releases/latest) [![Download for Linux](https://img.shields.io/badge/Download%20for-Linux-4C9AFF?style=for-the-badge)](https://github.com/no-human-ai/no_human/releases/latest)
+
+Each release ships a SHA-256 alongside the artifact. Platform notes and the
+first-run walk-through: [docs/quickstart.md](docs/quickstart.md).
+
+### From source
+
+```bash
+git clone https://github.com/no-human-ai/no_human.git && cd no_human
+uv sync                 # installs the `nh` entry point into .venv
+(cd web && npm install && npm run build)   # builds the board (cold first install can take minutes)
+uv run nh init          # token, config, first repo (about 2 minutes)
+uv run nh doctor        # verify the install is real before relying on it
+```
+
+The `web` build is not optional if you want the board: a source checkout ships
+no `web/dist`, so without it `nh start` serves the API only and renders no UI.
+Needs Python 3.12+, [uv](https://github.com/astral-sh/uv), git, and Node with
+npm for the board build.
+
+## Run one task
+
+Run `nh` with no arguments for the shell: your lanes, a live event tail, and an
+intake you describe a task to in plain English. Every command below still works.
+
+```bash
+nh                                   # the shell
+nh start                             # board + worker on 127.0.0.1:8420
+nh task add https://github.com/org/repo/issues/42 --repo ~/git/repo
+nh status                            # needs-you / working / waiting / done
+nh review <id>                       # the reviewer's evidence checklist
+nh diff <id>                         # the diff it wants to ship
+nh approve <id>                      # your approval squash-lands the PR (git.approve_identity)
+nh reject <id> --reason "..."        # send it back with feedback
+```
+
+## Integrations
+
+Point no_human at the tracker you already use and it pulls the tickets to your
+board — a tracker's filter lives in your config, never in a task's own text,
+and a transport error logs and retries on the next tick instead of crashing
+the pool.
+
+| Tracker | How tickets arrive | Filter you configure |
+|---|---|---|
+| **Jira Cloud** | Polled via REST `search/jql` (HTTP Basic `email:token`) | `integrations.jira.jql` |
+| **Linear** | Polled via the GraphQL API | `integrations.linear.team_key` + `state_types` + `label` |
+| **monday.com** | Polled via GraphQL v2 | `integrations.monday.board_id` + `status_column` + `todo_labels` |
+
+With write-back on (`write_back`, off by default), the ticket moves with the
+task — matched by status category, type, or the label you name, never a
+hard-coded transition id — and gets the PR link; a task that needs a human is commented on, never
+transitioned. GitHub and
+GitLab issues import as tasks by URL, and PRs or MRs open on your own host;
+Slack and Teams get a message when a task needs you; Jenkins and CircleCI can
+run your test layers and gate the loop. Setup for each:
+[docs/adapters.md](docs/adapters.md).
+
+**Watch the Jira flow end to end** — tickets synced from a Jira board, scoped,
+implemented, and delivered as a review-passed pull request (click for the full
+video with every step):
+
+[![Jira flow demo](https://getnohuman.com/assets/demo-jira.gif)](https://getnohuman.com/assets/demo-jira.mp4)
+
+<p align="center">▶️&nbsp;&nbsp;<strong><a href="https://getnohuman.com/assets/demo-jira.mp4">Play the full demo</a></strong> — 1:33, from Jira board to review-passed PR</p>
+
+## MCP server — hand it work from the agent you are already in
+
+no_human ships an **MCP (Model Context Protocol) server**: a stdio bridge, built
+on the official Python MCP SDK, that lets Claude Code, Cursor or any MCP client
+file work with your local no_human and check on it.
+
+```bash
+nh mcp-serve        # the MCP server, over stdio
+```
+
+Two tools, and no more:
+
+| Tool | What it does |
+|---|---|
+| `task_add(title, description, repo_path)` | Files a task. no_human then plans it, writes the change, runs your tests, has a second model review it, and opens the pull request. |
+| `task_status(task_id_or_external_id)` | Returns that task's current state — status, attempts, the PR link once there is one. |
+
+It talks to your own no_human at `http://127.0.0.1:8420` and nothing else: no
+auth, because that address is localhost, and no service of ours in between. For
+Claude Code, the same server ships as a plugin — point it at
+[`plugins/no-human/`](plugins/no-human/) and the two tools appear in your
+session.
+
+```jsonc
+// .mcp.json
+{ "mcpServers": { "no_human": { "command": "nh", "args": ["mcp-serve"] } } }
+```
+
+## Docs
+
+| | |
+|---|---|
+| [quickstart.md](docs/quickstart.md) | Zero to first task, per platform |
+| [configuration.md](docs/configuration.md) | Every setting and default |
+| [verification.md](docs/verification.md) | The gates, the bounded loop, the limits |
+| [security.md](docs/security.md) | Auth boundary, the never-merge rule, guards |
+| [blockers.md](docs/blockers.md) | Escalation, wake watcher, `nh reply` |
+| [adapters.md](docs/adapters.md) | Intake, context, VCS and CI backends |
+| [eval.md](docs/eval.md) | Golden set, replay scoring, shadow mode |
+| [CHANGELOG.md](CHANGELOG.md) | What changed, per release |
+
+## Development
+
+```bash
+uv sync
+uv run pytest -q
+uv run nh --help
+```
+
+Issues and pull requests welcome; run `uv run pytest -q` before submitting.
+
+## License
+
+MIT — see [LICENSE](LICENSE). The licence covers the code, not the name:
+[TRADEMARK.md](TRADEMARK.md) is the policy on using "no_human" and the logo.
+Packaging a binary carries obligations the source tree does not, listed in
+[THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md).

no_human-0.1.1/README.md

@@ -0,0 +1,170 @@
+<div align="center">
+
+<img src="docs/assets/nh-mark.png" alt="" width="140" height="140">
+
+# no_human
+
+**From ticket to reviewed pull request.**<br>***Free and open-source, on your machine.***
+
+[![latest release](https://img.shields.io/github/v/release/no-human-ai/no_human?label=release&color=4C9AFF)](https://github.com/no-human-ai/no_human/releases/latest) [![CI](https://img.shields.io/github/actions/workflow/status/no-human-ai/no_human/ci.yml?branch=main&label=CI)](https://github.com/no-human-ai/no_human/actions/workflows/ci.yml) [![python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/) [![license MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+[getnohuman.com](https://getnohuman.com) · [Quickstart](docs/quickstart.md) · [Docs](docs/README.md) · [Watch it work a sprint](https://getnohuman.com/demo)
+
+[![Download for macOS](https://img.shields.io/badge/Download%20for-macOS-4C9AFF?style=for-the-badge)](https://github.com/no-human-ai/no_human/releases/latest) [![Download for Windows](https://img.shields.io/badge/Download%20for-Windows-4C9AFF?style=for-the-badge)](https://github.com/no-human-ai/no_human/releases/latest) [![Download for Linux](https://img.shields.io/badge/Download%20for-Linux-4C9AFF?style=for-the-badge)](https://github.com/no-human-ai/no_human/releases/latest)
+
+<a href="https://getnohuman.com/"><img src="docs/assets/hero-loop-poster.jpg" alt="The no_human board: one task waiting on a question in Needs answer, four tasks working in parallel, one pull request ready for review." width="880"></a>
+
+<sub>▶ <a href="https://getnohuman.com/">Watch the loop</a> — a ticket in, a reviewed pull request out; the whole loop in 57 seconds.</sub>
+
+</div>
+
+The AI coding factory you <ins>**can trust**</ins>:
+
+- **A plan before any code**, from the ticket plus what it finds in your repo.
+- **An adversarial review.** A different model, fresh context, read-only tools,
+  told to refute "done". You get a pass/fail checklist citing file and line —
+  never a numeric self-score.
+- **A tamper guard.** Deleted tests, new skips, an assertion turned into a
+  tautology — blocked before a reviewer token is spent.
+- **Proof the fix fixed the bug.** For a bug fix, the tests offered as evidence
+  must fail at the merge base and pass on the new tree — the reproduction gate
+  enforces that, and you can require it for every change.
+- **Your tests run**, locally and optionally through your CI.
+- **An honest stop.** When it cannot finish, it parks with one specific question
+  instead of inventing a plausible diff.
+
+## Install
+
+Whichever way you install, you need a **Claude credential**: an OAuth token
+from `claude setup-token` (personal subscription or enterprise), so install the
+Claude Code CLI first — `npm install -g @anthropic-ai/claude-code`, or
+`curl -fsSL https://claude.ai/install.sh | bash`. The desktop app also calls
+that CLI for every task. To pay Anthropic directly instead, set
+`llm.auth_mode: "api_key"` and put your `ANTHROPIC_API_KEY` in
+`~/.no_human/.env`.
+
+### Desktop app
+
+[![Download for macOS](https://img.shields.io/badge/Download%20for-macOS-4C9AFF?style=for-the-badge)](https://github.com/no-human-ai/no_human/releases/latest) [![Download for Windows](https://img.shields.io/badge/Download%20for-Windows-4C9AFF?style=for-the-badge)](https://github.com/no-human-ai/no_human/releases/latest) [![Download for Linux](https://img.shields.io/badge/Download%20for-Linux-4C9AFF?style=for-the-badge)](https://github.com/no-human-ai/no_human/releases/latest)
+
+Each release ships a SHA-256 alongside the artifact. Platform notes and the
+first-run walk-through: [docs/quickstart.md](docs/quickstart.md).
+
+### From source
+
+```bash
+git clone https://github.com/no-human-ai/no_human.git && cd no_human
+uv sync                 # installs the `nh` entry point into .venv
+(cd web && npm install && npm run build)   # builds the board (cold first install can take minutes)
+uv run nh init          # token, config, first repo (about 2 minutes)
+uv run nh doctor        # verify the install is real before relying on it
+```
+
+The `web` build is not optional if you want the board: a source checkout ships
+no `web/dist`, so without it `nh start` serves the API only and renders no UI.
+Needs Python 3.12+, [uv](https://github.com/astral-sh/uv), git, and Node with
+npm for the board build.
+
+## Run one task
+
+Run `nh` with no arguments for the shell: your lanes, a live event tail, and an
+intake you describe a task to in plain English. Every command below still works.
+
+```bash
+nh                                   # the shell
+nh start                             # board + worker on 127.0.0.1:8420
+nh task add https://github.com/org/repo/issues/42 --repo ~/git/repo
+nh status                            # needs-you / working / waiting / done
+nh review <id>                       # the reviewer's evidence checklist
+nh diff <id>                         # the diff it wants to ship
+nh approve <id>                      # your approval squash-lands the PR (git.approve_identity)
+nh reject <id> --reason "..."        # send it back with feedback
+```
+
+## Integrations
+
+Point no_human at the tracker you already use and it pulls the tickets to your
+board — a tracker's filter lives in your config, never in a task's own text,
+and a transport error logs and retries on the next tick instead of crashing
+the pool.
+
+| Tracker | How tickets arrive | Filter you configure |
+|---|---|---|
+| **Jira Cloud** | Polled via REST `search/jql` (HTTP Basic `email:token`) | `integrations.jira.jql` |
+| **Linear** | Polled via the GraphQL API | `integrations.linear.team_key` + `state_types` + `label` |
+| **monday.com** | Polled via GraphQL v2 | `integrations.monday.board_id` + `status_column` + `todo_labels` |
+
+With write-back on (`write_back`, off by default), the ticket moves with the
+task — matched by status category, type, or the label you name, never a
+hard-coded transition id — and gets the PR link; a task that needs a human is commented on, never
+transitioned. GitHub and
+GitLab issues import as tasks by URL, and PRs or MRs open on your own host;
+Slack and Teams get a message when a task needs you; Jenkins and CircleCI can
+run your test layers and gate the loop. Setup for each:
+[docs/adapters.md](docs/adapters.md).
+
+**Watch the Jira flow end to end** — tickets synced from a Jira board, scoped,
+implemented, and delivered as a review-passed pull request (click for the full
+video with every step):
+
+[![Jira flow demo](https://getnohuman.com/assets/demo-jira.gif)](https://getnohuman.com/assets/demo-jira.mp4)
+
+<p align="center">▶️&nbsp;&nbsp;<strong><a href="https://getnohuman.com/assets/demo-jira.mp4">Play the full demo</a></strong> — 1:33, from Jira board to review-passed PR</p>
+
+## MCP server — hand it work from the agent you are already in
+
+no_human ships an **MCP (Model Context Protocol) server**: a stdio bridge, built
+on the official Python MCP SDK, that lets Claude Code, Cursor or any MCP client
+file work with your local no_human and check on it.
+
+```bash
+nh mcp-serve        # the MCP server, over stdio
+```
+
+Two tools, and no more:
+
+| Tool | What it does |
+|---|---|
+| `task_add(title, description, repo_path)` | Files a task. no_human then plans it, writes the change, runs your tests, has a second model review it, and opens the pull request. |
+| `task_status(task_id_or_external_id)` | Returns that task's current state — status, attempts, the PR link once there is one. |
+
+It talks to your own no_human at `http://127.0.0.1:8420` and nothing else: no
+auth, because that address is localhost, and no service of ours in between. For
+Claude Code, the same server ships as a plugin — point it at
+[`plugins/no-human/`](plugins/no-human/) and the two tools appear in your
+session.
+
+```jsonc
+// .mcp.json
+{ "mcpServers": { "no_human": { "command": "nh", "args": ["mcp-serve"] } } }
+```
+
+## Docs
+
+| | |
+|---|---|
+| [quickstart.md](docs/quickstart.md) | Zero to first task, per platform |
+| [configuration.md](docs/configuration.md) | Every setting and default |
+| [verification.md](docs/verification.md) | The gates, the bounded loop, the limits |
+| [security.md](docs/security.md) | Auth boundary, the never-merge rule, guards |
+| [blockers.md](docs/blockers.md) | Escalation, wake watcher, `nh reply` |
+| [adapters.md](docs/adapters.md) | Intake, context, VCS and CI backends |
+| [eval.md](docs/eval.md) | Golden set, replay scoring, shadow mode |
+| [CHANGELOG.md](CHANGELOG.md) | What changed, per release |
+
+## Development
+
+```bash
+uv sync
+uv run pytest -q
+uv run nh --help
+```
+
+Issues and pull requests welcome; run `uv run pytest -q` before submitting.
+
+## License
+
+MIT — see [LICENSE](LICENSE). The licence covers the code, not the name:
+[TRADEMARK.md](TRADEMARK.md) is the policy on using "no_human" and the logo.
+Packaging a binary carries obligations the source tree does not, listed in
+[THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md).

no_human-0.1.1/hatch_build.py

@@ -0,0 +1,213 @@
+"""The board is REQUIRED for a distributable build and OPTIONAL for a dev one.
+
+`web/dist` is the built React board. `nh start` — the entrypoint README calls
+primary — serves it, so a wheel or sdist built without it installs a CLI whose
+main command renders nothing. That shipped once, and the fix was to declare the
+board with hatchling's `force-include`, which raises `Forced include not found`
+when the source is absent: a release cut without `npm run build` FAILS instead
+of quietly shipping the broken product.
+
+That guarantee was right; the mechanism was too wide. `force-include` is static
+configuration, so it is evaluated for EVERY build target and version — including
+the editable wheel that `uv sync` and `pip install -e .` build. `web/dist` is a
+gitignored build artifact, so a clean clone of this repo does not have one, and
+the release-time guard fired on the developer's first command instead:
+
+    $ git clone … && cd no_human && uv sync
+    FileNotFoundError: Forced include not found: <repo>/web/dist
+    Call to `hatchling.build.build_editable` failed (exit status: 1)
+
+A clean clone could not be installed, developed, or tested — before collection,
+with a message that reads like a broken repository rather than a missing npm
+build. (The comment this replaces claimed "nothing in CI builds a wheel, so this
+only ever fires on a release build". That was false: `uv sync` reaches the same
+code path through `build_editable`.)
+
+So the declaration moves here, where the build VERSION is visible. Hatchling
+calls `initialize(version, build_data)` with `version == "editable"` for an
+editable install and `"standard"` for everything else, and honours anything a
+hook adds to `build_data["force_include"]` (merged in `BuilderConfig.
+set_build_data`, read by both `build_standard` and `build_editable_detection`).
+That is the whole seam:
+
+  * editable + no board  -> build it automatically when `npm` is on PATH ("cd
+    web && npm install && npm run build"). If npm is absent, the build fails,
+    or it exits 0 without producing `index.html`, fall back to warning and
+    include nothing — the install still succeeds either way.
+  * editable + board     -> include it, exactly as before.
+  * standard + no board  -> FAIL, with a message that names `npm run build` and
+    the directory. The release-time guarantee is unchanged; only its blast
+    radius is.
+  * standard + board     -> include it, exactly as before.
+
+Presence is judged by `index.html`, not by the directory. `npm run build` writes
+INTO an existing directory, so an interrupted or cleaned build leaves the husk
+behind — and the old directory-existence check would have force-included that
+husk into a release wheel, which is the boardless-CLI bug wearing a directory.
+`api/app.py::_resolve_web_dist` already refuses a husk for the same reason.
+
+`migrations/` stays a static `force-include` in `pyproject.toml`: it is TRACKED,
+so it is present in every clone and worktree, and a static declaration is the
+simpler thing that works.
+
+The hatchling import is guarded so this module can be imported as a plain script
+by `tests/test_clean_clone_installable.py`. Hatchling is a BUILD dependency — it
+exists only inside the isolated build environment PEP 517 creates, never in this
+repo's own venv — so an unguarded import would make the decision logic below
+untestable anywhere except inside a real build, which is the slowest and least
+specific place to test it.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from collections.abc import Callable
+from pathlib import Path
+
+try:  # pragma: no cover - the real build environment always has hatchling
+    from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+except ModuleNotFoundError:  # pragma: no cover - importing this file as a module
+    BuildHookInterface = object  # type: ignore[assignment,misc]
+
+# The version string hatchling passes for `pip install -e .` / `uv sync`.
+EDITABLE = "editable"
+
+DEFAULT_SOURCE = "web/dist"
+
+NPM = "npm"
+
+# `npm install` on a cold `node_modules` can take a while; this bounds an
+# editable install rather than hanging it forever.
+NPM_TIMEOUT = 900
+
+
+class BoardNotBuiltError(RuntimeError):
+    """A distributable artifact was built without a board to put in it."""
+
+
+def _build_it() -> str:
+    return "cd web && npm install && npm run build"
+
+
+def _npm_available() -> bool:
+    return shutil.which(NPM) is not None
+
+
+def try_build_board(
+    root: str | Path,
+    source: str,
+    runner: Callable[..., subprocess.CompletedProcess] = subprocess.run,
+) -> bool:
+    """Attempt the editable-install board build named by `_build_it()`.
+
+    Runs `npm install` then `npm run build` in `<root>/<web dir>` (the parent
+    of `source`) and returns whether `<root>/<source>/index.html` exists
+    afterwards. Never raises: an absent `npm`, a missing `web/package.json`
+    (not a real checkout — e.g. a test's bare `tmp_path`), a non-zero exit, a
+    crash, or a timeout all just return `False` so the caller can fall back to
+    `board_missing_warning`. A 0 exit with no `index.html` is also `False` —
+    npm can exit 0 having produced an incomplete build.
+    """
+    web_dir = Path(root) / Path(source).parent
+    if not (web_dir / "package.json").is_file():
+        return False
+    if not _npm_available():
+        return False
+    try:
+        for argv in (["npm", "install"], ["npm", "run", "build"]):
+            result = runner(
+                argv, cwd=web_dir, capture_output=True, text=True,
+                check=False, timeout=NPM_TIMEOUT,
+            )
+            if result.returncode != 0:
+                return False
+    except (OSError, subprocess.SubprocessError):
+        return False
+    return (Path(root) / source / "index.html").is_file()
+
+
+def board_missing_warning(index: Path) -> str:
+    return (
+        f"\nno_human: the web board is not built — {index} is missing.\n"
+        f"  This dev install will work, but `nh start` will serve a notice\n"
+        f"  instead of the board until you run:\n"
+        f"      {_build_it()}\n"
+        f"  (The board is a gitignored build artifact, so a fresh clone never\n"
+        f"  has one. The CLI — `nh task`, `nh status` — is unaffected.)\n"
+    )
+
+
+def board_missing_error(index: Path, target_name: str) -> str:
+    return (
+        f"\nno_human: refusing to build a {target_name} without the web board.\n"
+        f"\n"
+        f"  missing: {index}\n"
+        f"\n"
+        f"  `nh start` is the documented entrypoint and it serves this board, so\n"
+        f"  a {target_name} built without it installs a CLI whose main command\n"
+        f"  renders nothing. That has shipped once already, which is why this is\n"
+        f"  a build failure and not a warning.\n"
+        f"\n"
+        f"  Build the board first:\n"
+        f"      {_build_it()}\n"
+        f"\n"
+        f"  A dev install does NOT need it: `uv sync` and `pip install -e .`\n"
+        f"  warn and continue.\n"
+    )
+
+
+def plan_board_inclusion(
+    root: str | Path,
+    source: str,
+    target: str,
+    version: str,
+    target_name: str = "wheel",
+    *,
+    builder: Callable[[str | Path, str], bool] | None = None,
+) -> tuple[dict[str, str], str | None]:
+    """Decide what a build of `version` does about the board.
+
+    Returns `(force_include_additions, warning_or_None)` and raises
+    `BoardNotBuiltError` when a distributable build has no board to ship. Split
+    out of the hook class so it can be tested without hatchling and without
+    running a build — the branch that matters (editable vs standard) is one
+    string comparison, and it should be provable in milliseconds.
+
+    `builder` is test-injectable and only ever consulted on the editable path
+    (default `try_build_board`); the standard/distributable path never calls
+    it and always fails closed when the board is absent.
+    """
+    index = Path(root) / source / "index.html"
+    if index.is_file():
+        return {source: target}, None
+    if version == EDITABLE:
+        build = builder or try_build_board
+        if build(root, source) and index.is_file():
+            return {source: target}, None
+        return {}, board_missing_warning(index)
+    raise BoardNotBuiltError(board_missing_error(index, target_name))
+
+
+class BoardBuildHook(BuildHookInterface):  # type: ignore[misc,valid-type]
+    """Injects the board's `force-include` entry, or explains its absence."""
+
+    PLUGIN_NAME = "no-human-board"
+
+    def initialize(self, version: str, build_data: dict) -> None:
+        source = self.config.get("source", DEFAULT_SOURCE)
+        target = self.config.get("target")
+        if not isinstance(target, str) or not target:
+            msg = (
+                "hatch_build.py: the hook needs a `target` in "
+                f"[tool.hatch.build.targets.{self.target_name}.hooks.custom] — "
+                "the path the board takes inside the artifact."
+            )
+            raise ValueError(msg)
+
+        additions, warning = plan_board_inclusion(
+            self.root, source, target, version, self.target_name
+        )
+        if warning:
+            self.app.display_warning(warning)
+        build_data["force_include"].update(additions)