entropy-machines 0.1.1

package/docs/SERVE.md

@@ -0,0 +1,74 @@
+# bin/serve — the factory lights
+
+    bin/serve [port]        # default 8787, 127.0.0.1 only
+
+A local web server, not a CLI. The owner's surface is a browser tab: dialogue
+docs with response boxes answered in place, plus a dashboard.
+
+| Route | What |
+|---|---|
+| `GET /` | Dashboard — ready issues, in-flight claims, per-doc answered counts, recent events. |
+| `GET /<doc>.html` | A doc from `docs.dir`, save patch and theme injected at serve time. |
+| `GET /__docversion?file=…` | `{"reviews": "<hash>"}`, polled by the live-reload watcher. |
+| `POST /__save?file=…` | Body `{"<data-resp>": "<answer>"}`, merged atomically. |
+
+Everything else 404s — no listing, nothing outside `docs.dir`.
+
+## The rule
+
+**No report, plan or PRD is ever published to an external site, and none may
+depend on one** — a doc pulling a font or stylesheet from someone else's server
+breaks offline and tells that server it was opened. And every section the owner
+is asked about has a box to answer in.
+
+**`bin/doclint` enforces exactly those two things.** Run it before handing over
+a URL. Exit 1 names file, line and problem for an off-machine origin in an
+`href`, `src`, CSS `url()` or script literal (prose mentioning a URL passes, as
+do `data:` URIs and relative paths), or for an `<h2>` with no answer box, two
+boxes sharing a key, or a missing `#saveBtn` / `#responses-data`.
+`data-informational` on an `<h2>` skips that section — no whole-file exemption.
+Exit 2 is a refusal, not a pass: it could not read its input. **The look is not
+checked** — `lib/REPORT-TEMPLATE.html` is a default, not a conformance target.
+
+## Docs and themes
+
+`docs.dir` (default `entropy-machines-docs/`) is created if absent; docs sit directly in
+it, since the save-path check refuses any `file` containing `/`. Reports start
+from `lib/REPORT-TEMPLATE.html`, PRDs from `lib/doc-template.html`, whose header
+comment authoritatively describes the response-box machinery. `docs.theme` picks
+a stylesheet from `lib/themes/` (`high-contrast`, `daylight`), inlined on each
+`GET` between the `entropy-machines-theme` markers; an unknown name is refused by name.
+
+## Saving
+
+A save endpoint taking a path is a whole-disk write primitive, so `file` is
+validated on both routes: no `/`, no `..`, ends `.html`, already in `docs.dir`.
+Refusals return plain 4xx JSON. A valid save merges into `#responses-data` and
+the matching `<textarea>`s via temp-file-plus-`os.replace`.
+
+**The save patch is injected on every `GET`, never written into the file** —
+otherwise an older doc falls back to `showSaveFilePicker`, writing to
+`~/Downloads` and leaving the reviewed file untouched. It runs in the click
+capture phase with `stopImmediatePropagation`, so it wins whatever else is bound.
+
+## Hot reload
+
+The doc polls `__docversion` every 5s: a clean tab reloads itself, a dirty one
+shows a bar instead. Typed text is never clobbered.
+
+`reviews` is **not** a whole-file hash — your own 💾 rewrites `#responses-data`
+and the answered `<textarea>`s, which would read back as an incoming reply. It
+is a SHA-256 with exactly those two regions blanked. **Consequence:**
+overwriting an existing answer is indistinguishable from the reader typing and
+triggers no reload; land a reply as new content outside the answer regions.
+
+## Dashboard, port, root
+
+`GET /` uses only state already tracked: `tracker ready`; `tracker notes` through
+`lib/notes.py claims --hours 24`, the same derivation `bin/dispatch` uses for its
+denylist; each doc's own counts; the notes tail. An unreachable tracker says so
+rather than rendering empty — unreadable and empty are different facts.
+
+A busy port refuses with the next port to try, not a traceback. One root,
+resolved via `--git-common-dir` so it is the MAIN checkout even from a linked
+worktree; no environment override, so `cd` to serve another project.

package/docs/TRACKER-ADAPTER.md

@@ -0,0 +1,66 @@
+# The tracker adapter
+
+The harness needs **six** operations from an issue tracker. That is the whole
+dependency. Anything richer belongs to your tracker, not to us.
+
+A backend is any executable that implements this CLI. `tracker.backend` in
+`config.json` selects one.
+
+| Command | Contract |
+|---|---|
+| `show <id>` | Print one issue as JSON on stdout. Exit 3 if no such issue. |
+| `notes [--issue <id>]` | Print the note log as JSONL, one record per line, oldest first. With `--issue`, only that issue's records. |
+| `remember --issue <id> <text>` | Append one note record. Must be atomic under concurrent writers. |
+| `claim <id>` | Mark in-progress and record the claimant. Exit 4 if already claimed by someone else. |
+| `ready` | Print claimable issues as JSONL — no open blockers, not held, not gated. |
+| `set <id> <key>=<value>` | Set a field. Exit 2 on an unknown key. |
+
+## The note record
+
+The original harness wrote notes as free text with em-dash delimiters and
+re-parsed that format in four independent places. Any format change needed
+four synchronised edits, so the format could never change.
+
+Notes are JSONL here. One record per line, one parser, `lib/notes`:
+
+```json
+{"ts":"2026-08-27T19:04:11Z","verb":"DISPATCH","issue":"i-foo","actor":"orchestrator",
+ "fields":{"scope":["src/a.ts","tests/a.test.ts"],"brief":"one-line task"}}
+```
+
+- `verb` is the record type: `DISPATCH`, `HANDOFF`, `INTERROGATION`, or a
+  backend-defined string. Consumers MUST ignore verbs they do not know.
+- `fields` is free-form per verb. `scope` is an ARRAY — the original parsed
+  comma-vs-space-delimited strings differently in different call sites.
+- Records are append-only. Nothing rewrites or deletes one.
+
+## What we deliberately do not require
+
+Milestones, priorities, assignees, sprints, epics, time tracking. If your
+tracker has them, good; the harness will not read them.
+
+## Two states a general tracker usually lacks
+
+A `command` backend that cannot express these will degrade: `ready` will
+over-report, and the orchestrator has to catch it by eye.
+
+- **held** — decided not to do now, WITH a reason. Distinct from closed: a
+  held issue is a decision, not a completion, and `ready` must not return it.
+- **gated** — blocked on an open question outside the issue graph (a design
+  decision, an owner ruling). Distinct from blocked-by, which points at
+  another issue. `ready` must not return a gated issue, and must fail closed
+  when the gate handle is unknown.
+
+**Neither is a `status` value.** `status` holds only `notstarted`, `progress`
+or `done`. Held-ness is the presence of a `heldWhy` field; gated-ness is the
+presence of a `gate` field. This is deliberate. Modelling them as statuses
+makes the reason optional — a bare `status: held` is expressible, and a held
+issue whose reason nobody recorded is indistinguishable from one somebody
+forgot. Carrying the reason in the field that defines the state makes the
+reasonless version unrepresentable.
+
+It also keeps the two orthogonal to progress: an issue can be half-implemented
+AND held, which a single status enum forces you to lose.
+
+The built-in `file` backend enforces this — `set <id> status=held` is refused
+with a message naming the right field.

package/doctrine/HANDOFF-PROMPT.md

@@ -0,0 +1,63 @@
+# Reshare prompt
+
+Paste the block below into a fresh session to hand this work off. It is
+self-contained — it assumes the reader knows nothing about the repo or this
+conversation.
+
+Use it if you want the doctrine extended or revised by an agent that is not
+carrying a sprint's worth of context.
+
+---
+
+```
+Read `doctrine/README.md`, `doctrine/ROLES.md` and `doctrine/WORKFLOW.md` in
+this repo, plus `agents/verifier.md` and `agents/isolated-worker.md`. They
+document how work moves through this project: issues → worked → verified →
+folded → sprint report → issues.
+
+Four roles: the owner (decides, ticks, says when held work may merge), workers
+(one scoped issue each, in isolated git worktrees, commit nothing), a verifier
+(ONE sweep across all finished work for a sprint, on a clean tree, before
+anything is folded), and orchestrators (fold, land, report, file issues, talk to
+the owner — the only committers).
+
+The design intent, in the owner's words: verification is a quick check across
+the workstreams for a sprint — not one verifier per worker — to confirm nothing
+is glaringly wrong and the work is in an acceptable, testable, healthy state.
+The orchestrator's job is the higher order: rather than polluting its context
+with nitty-gritty verification, it inherits healthier work to fold in, which
+frees orchestrators to work more fully with the owner instead of getting buried.
+
+YOUR TASK: <state it here>
+
+Things to know before you change any of it:
+
+- Every rule in those files exists because something went wrong once, and most
+  say so. Do not shorten a rule into a slogan — the incident IS the argument.
+  If you remove one, say what now prevents the incident.
+- The repo convention is that a new working rule names what enforces it (a
+  wrapper, a gate, a refusal, a CI job) or states plainly that nothing does.
+- Depth belongs to the orchestrator, breadth to the verifier. The verifier
+  checks a test EXISTS and plausibly bites; proving a test is pinned to
+  behaviour — by mutating one half of a fix and watching the right subset go
+  red — stays with the orchestrator, on risky changes only. Do not collapse
+  those two into one role.
+- A project can keep its own local, gitignored docs directory outside this
+  one; whether it is reachable from inside an agent's worktree depends on
+  whether it is listed in `config.json`'s `worktree.linkPaths` AND whether
+  this clone's git hooks were installed (`hooks/post-checkout` is what
+  symlinks it in). Don't assume either way — paste what an agent needs into
+  its brief regardless: proximity, not reachability, is what gets a rule
+  followed (96% vs 7%, measured on an earlier version of this workflow).
+- Agent definitions are picked up at SESSION START only in Claude Code, which
+  is what this doctrine's reference implementation targets — `subagent_type`
+  needs a restart to see a new one. A different agent runner may behave
+  differently; check it before assuming this restart requirement carries
+  over.
+
+Open question the owner raised and I could not resolve: they described the
+roles as "4 — workers, verifiers, orchestrators", which names three. I
+documented the fourth as the OWNER, since the owner holds decisions no agent may
+take (the sprint-close tick has no code path, and held work merges only on their
+say-so). If a different fourth role was meant, ask.
+```

package/doctrine/README.md

@@ -0,0 +1,62 @@
+# The factory
+
+How work moves through this repo: the cycle, the roles, and the rules that
+exist because something went wrong once.
+
+This directory is the home for workflow documentation. A project can keep its
+own local, gitignored docs directory for product and design material
+alongside it; this directory is committed, because it governs how anyone —
+human or agent — is supposed to operate here.
+
+- **[WORKFLOW.md](WORKFLOW.md)** — the cycle, stage by stage, with what must be
+  true to leave each stage.
+- **[ROLES.md](ROLES.md)** — who does what, and what each role must never do.
+
+---
+
+## The cycle
+
+```
+   ┌──────────────────────────────────────────────────────────┐
+   │                                                          │
+   ▼                                                          │
+ISSUES ──▶ WORKED ──▶ VERIFIED ──▶ FOLDED ──▶ SPRINT REPORT ──┘
+(tracker)  (workers)  (verifier)  (orchestr.)  (orchestrator +
+                                                 owner ticks)
+```
+
+Issues get worked. Finished work is verified as a sprint, on a clean tree,
+before anything is folded. The orchestrator folds it in and lands it. The sprint
+ends in a report the owner ticks. Rulings from that report — plus whatever
+arrives from other workstreams — become the next issues, and round it goes.
+
+## The one-paragraph version
+
+**Workers** implement one scoped issue each, in isolated git worktrees, and
+commit nothing. **A verifier** sweeps all of their finished output together,
+once, on a clean tree, and reports whether it is healthy. **An orchestrator**
+folds the verified work into `main`, re-proving anything risky by its own
+mutation, and is the only committer. The orchestrator then writes the sprint
+report, the owner ticks it, and the rulings in it become issues.
+
+## Why it is shaped like this
+
+**Verification is a sprint-level sweep, not a per-agent gate.** One verifier
+across the whole sprint is cheaper than one per worker, and it is the only
+vantage point that can see two changes interacting. It also keeps the
+orchestrator's attention on the owner rather than on nitty-gritty re-running.
+
+**The orchestrator still owns depth.** The verifier checks that a test exists
+and plausibly bites. Proving a test is pinned to *behaviour* — by mutating one
+half of a fix at a time and watching the right subset go red — stays with the
+orchestrator, on the risky changes only. A subagent's proof can be vacuous in a
+way that re-running it cannot reveal; only an independent mutation shows what a
+test is actually pinned to.
+
+**Work is landed at the behest of the owner** If they're working wtith you directly likely they'll indicate what to do, to be mindful of other agents, when pulling work in. You should also be intentional about surfacing risks of collission and surfacing what you can in advance of merging work.
+
+**The clean tree is the source of truth.** The orchestrator's checkout is
+usually dirty with other sessions' work. A worker's worktree branches from
+committed HEAD, so it is clean. When a worker reports a failure the
+orchestrator cannot reproduce, **the worker is right** — see the incident in
+[WORKFLOW.md](WORKFLOW.md#the-clean-tree-is-the-truth).

package/doctrine/ROLES.md

@@ -0,0 +1,27 @@
+# Roles
+
+Four roles: three agents and the owner. Every prohibition is here because
+something went wrong once.
+
+| Role | Does | Never |
+|---|---|---|
+| **Owner** | Rules on open questions in served docs, ticks the sprint closed, says when held work merges. | Delegates the ready tick — there is no code path to it. |
+| **Worker**<br>`agents/isolated-worker.md` | One scoped issue in its own worktree: the change, its tests, its `changelog.d/` fragment, and a `HANDOFF.md` — `changed` / `found` / `assumed` / `next`. | Commits, pushes, merges, runs the full build, edits outside its scope, or touches another worktree. |
+| **Verifier**<br>`agents/verifier.md` | One sweep per sprint (not per worker) on a clean tree: applies every finished patch together, builds, regenerates, runs the suites, checks each change has a test that bites. Verdict with real numbers. | Fixes, lands, commits, reviews design, edits a worker's worktree, or repeats a number it did not re-run. |
+| **Orchestrator**<br>the session talking to the owner | Dispatches, folds, lands, reports, files rulings as issues. The **only committer**. | Lands held work without the owner, relays a subagent's verification as its own, or lets its cwd leave the repo root. |
+
+**Worker, hard-won:** write `HANDOFF.md` early — a dead worker otherwise
+leaves only a diff. Check `git rev-parse --git-common-dir` first — not
+`--show-toplevel`, which prints the worktree's own path and cannot confirm
+which repo you branched from. Symlink
+`worktree.linkPaths` before running anything. Report what you did **not** run.
+
+| Job | Agent |
+|---|---|
+| Implement a scoped issue | `isolated-worker` |
+| Sprint verification sweep | `verifier` |
+| Read-only investigation | `Explore` — no worktree cost |
+| Fold, land, report, file | the orchestrator itself |
+
+Written against Claude Code: `agents/*.md` are picked up **at session start
+only**. Check your runner's equivalent.

package/doctrine/WORKFLOW.md

@@ -0,0 +1,87 @@
+# The workflow
+
+```
+ISSUES ──▶ WORKED ──▶ VERIFIED ──▶ FOLDED ──▶ SPRINT REPORT ──▶ ISSUES
+```
+
+## 1. Issues
+The tracker is the state of the world, not the docs (`../docs/TRACKER-ADAPTER.md`).
+**Leave when:** issues are chosen, non-overlapping in file scope, none gated on an
+open decision. Held means decided, not forgotten. Two issues on one file serialize.
+
+## 2. Worked
+One worker per issue, each in its own worktree. `dispatch <id> --files "…" --brief
+"…"` **before** spawning anything — it refuses a non-root cwd, refuses uncommitted
+edits inside the worker's scope, claims the issue, records the brief.
+**Everything the worker needs goes in the brief:** over 225 subagent runs a rule
+pasted into the brief was followed 96% of the time, the same rule left in the
+project instructions file 7%. Prompt position, not access.
+**Leave when:** every worker has finished or stopped *with* a `HANDOFF.md`. A
+stopped worker is fine; one with no handoff is a loss.
+
+## 3. Verified
+One verifier for the sprint. It gets every finished patch as a file and sweeps them
+together. **Leave when:** `healthy` or `healthy with caveats` and the caveats are
+understood. `not ready` goes back to stage 2.
+
+## 4. Folded
+The orchestrator, and only the orchestrator, merges. Per change: apply to `main`;
+run `generate` and confirm **nothing moves**; for the risky ones **mutate one half
+of the fix at a time** and check the failure set is the one that half owns —
+replaying a worker's own revert only proves the test noticed *that* revert. Then
+`handoff <id> --from <worktree> --verified "<what YOU ran>"` and commit.
+**Leave when:** committed on `main` with a fragment, the issue `done`, suites green
+**on the final tree** — not on each patch. Nothing is folded while work is HELD.
+Because folding is serial, the verifier blessed a combination, not each merge: **a
+conflict resolution is the orchestrator's own code and needs its own proof.**
+
+## 5. Sprint report
+Names the issues delivered and the issues opened, and gives the owner somewhere to
+respond section by section. **A local HTML file in the project's docs directory** —
+served by `bin/serve`, answered in the browser, saved back to disk; never published
+to an external site, never loading from one. `bin/doclint` gates that plus
+answerability. **Leave when:** the owner ticks the sprint closed — no code path.
+
+## 6. Back to issues
+Rulings become tracker issues. `remember --issue <id> "…"` puts a finding where the
+next session reads it. A ruling living only in chat is lost; only in a doc, nearly.
+
+## Standing rules
+
+### The clean tree is the truth
+A worker's worktree branches from committed HEAD; the orchestrator's checkout is
+dirty. **When a worker reports a failure the orchestrator cannot reproduce, the
+worker is right.** Dismissing that once hid a fixture set broken at HEAD.
+
+- **A new rule names what enforces it** — wrapper, gate, refusal or CI job, or say
+  plainly that nothing does.
+- **Work is held until the owner says merge.**
+- **Never run the full build in a worker or verifier** — release commands rewrite
+  committed bookkeeping. Use `config.json`'s `suites`.
+- **Symlink `worktree.linkPaths` in every worktree.** Unlinked, a runtime walks up
+  and resolves a *sibling worktree* — you test someone else's code and report it as
+  your own. Green, confident, wrong.
+
+### Isolation is the runner's, and it can silently not happen
+`isolation: worktree` branches the repo the **calling session's cwd** is in, not the
+one the harness is vendored in. Orchestrate project A from a shell sitting in
+project B and every worker gets a worktree of B, without the files it was sent for.
+On 2026-08-30 the fallback from that put every agent in one shared checkout: they
+could see each other's uncommitted edits, and one `git add -A` swept a live lane's
+work into an unrelated commit.
+
+**The worker's check, before it writes anything:** `git rev-parse --git-common-dir`
+must contain the project's directory name; a bare relative `.git` means no worktree
+at all. Not `--show-toplevel` — that prints the *worktree's* path, which never
+equals the main repo's. `dispatch` pastes this into every brief.
+
+**Orchestrating without isolation:** confirm cwd is the project root before every
+dispatch, give concurrent agents strictly disjoint file scopes, and **never `git add
+-A` while a lane is live** — stage explicit paths, every time.
+
+**What enforces it: nothing.** `bin/dispatch` refuses a cwd that is not
+`ENTROPY_MACHINES_ROOT`, which catches a session already drifted *when the brief is written*.
+The runner creates the worktree later, from whatever the cwd is then, so a `cd` in
+between is invisible to every gate — and no shell script can reach inside the
+runner's isolation to check what it actually did. The worker's own check is all
+that is downstream of it.

package/hooks/commit-msg

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# Repo commit-msg hook — VERSION-CONTROLLED, like its pre-commit sibling.
+#
+# It exists separately from pre-commit because handoff-guard keys on the issue
+# id in the commit message, and pre-commit runs before a message exists.
+#
+# ONE ROOT. lib/handoff-guard.sh is a harness file living one directory up from
+# this one, inside the same repository as the commit being made. The shim
+# exports ENTROPY_MACHINES_HOME (it lives in .git/hooks and cannot find lib/
+# relatively); the fallback below only matters when this file is run directly.
+# $1, the message file path git passes in, is already project-relative or
+# absolute as git gives it — nothing here needs to touch it.
+#
+# Keep it fast. $1 is the path to the message file.
+
+set -euo pipefail
+
+. "$(dirname "$0")/../lib/roots.sh"
+
+: "${ENTROPY_MACHINES_HOME:=$(entropy_machines_home "$0")}"
+export ENTROPY_MACHINES_HOME
+entropy_machines_require_root commit-msg
+
+exec "$ENTROPY_MACHINES_HOME/lib/handoff-guard.sh" --message "$1"