entropy-machines 0.1.1

package/lib/preflight-tree.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+/**
+ * Refuse to run a suite from a tree that cannot resolve its own dependencies.
+ *
+ *
+ * THE FAILURE THIS EXISTS FOR. A git worktree has no `node_modules`. Node then
+ * walks UP from the worktree looking for one — and on 2026-08-17 a dispatched
+ * agent's `npm run e2e` resolved `playwright` out of a SIBLING agent's worktree
+ * and ran with that worktree as cwd. It tested someone else's code and reported
+ * the result as its own. Green, confident, wrong. The agent caught it only by
+ * watching the output; nothing in the tooling would have told it, or the
+ * session landing its work.
+ *
+ * That is worse than the already-known symptom (an empty ENOENT from a missing
+ * .bin/tsc), because a spurious red gets investigated and a spurious green does
+ * not. A worktree isolates the filesystem; it does not isolate node resolution.
+ *
+ * THE CHECK. Every package a suite spawns must be present under THIS tree's own
+ * node_modules. A symlink to the main checkout satisfies that and is the fix we
+ * recommend — what must never happen is no entry at all, because that is the
+ * only case where resolution leaves the tree.
+ *
+ * Silent and fast on the happy path: one `git rev-parse` and four `stat`s.
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+// Anything a suite spawns or imports from the tree root. Keep this list to
+// things whose absence produces a WRONG ANSWER rather than a clean crash.
+const NEEDED = ['playwright', 'vitest', 'typescript', 'esbuild'];
+
+function git(...args) {
+  return execFileSync('git', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+}
+
+let root;
+try {
+  root = git('rev-parse', '--show-toplevel');
+} catch {
+  process.exit(0); // not a git checkout — nothing to be confused about
+}
+
+const nodeModules = join(root, 'node_modules');
+const missing = existsSync(nodeModules)
+  ? NEEDED.filter((p) => !existsSync(join(nodeModules, p)))
+  : NEEDED;
+
+if (missing.length === 0) process.exit(0);
+
+// Where a worktree should point. --git-common-dir is the MAIN checkout's .git
+// even when called from a worktree, so its parent is the tree that has the
+// real node_modules.
+let mainTree = null;
+try {
+  const commonDir = git('rev-parse', '--path-format=absolute', '--git-common-dir');
+  const candidate = dirname(commonDir);
+  if (candidate !== root && existsSync(join(candidate, 'node_modules'))) mainTree = candidate;
+} catch {
+  /* older git without --path-format; the message still works without it */
+}
+
+const lines = [
+  '',
+  'preflight: this tree cannot resolve its own dependencies — refusing to run.',
+  '',
+  `  tree:    ${root}`,
+  `  missing: ${missing.join(', ')}${existsSync(nodeModules) ? ' (node_modules exists but is incomplete)' : ' (no node_modules at all)'}`,
+  '',
+  '  Node would search UPWARD from here and can land in another worktree, which',
+  '  means testing someone else\'s code and reporting it as yours. That has',
+  '  happened once already.',
+  '',
+];
+lines.push(
+  mainTree
+    ? `  Fix:  ln -s ${JSON.stringify(join(mainTree, 'node_modules'))} ${JSON.stringify(nodeModules)}`
+    : '  Fix:  symlink or install node_modules in this tree (npm ci).'
+);
+lines.push('');
+console.error(lines.join('\n'));
+process.exit(1);

package/lib/roots.sh

@@ -0,0 +1,212 @@
+# roots.sh — resolve the ONE root every entry point needs. SOURCE it, do not
+# run it.
+#
+#   . "$(dirname "$0")/../lib/roots.sh"
+#   ENTROPY_MACHINES_HOME=$(entropy_machines_home "$0")
+#   entropy_machines_require_root <tool-name>          # sets+exports ENTROPY_MACHINES_ROOT,
+#                                             # refusing a nested clone first
+#
+# THERE IS ONE ROOT: THE GIT REPOSITORY.
+#
+# The harness is VENDORED AS PLAIN TRACKED FILES inside the project it works
+# on and committed alongside the project's code — exactly as a `scripts/`
+# directory is. There is no nested `.git`, so `git` from anywhere inside the
+# project always answers with the project. config.json, .entropy-machines/, the
+# harness's own bin/ and lib/ are all inside one repository.
+#
+#   ENTROPY_MACHINES_ROOT   the repository's MAIN checkout. .entropy-machines/
+#                  lives here. This is THE root.
+#   ENTROPY_MACHINES_HOME   the directory the harness's own files sit in (bin/, lib/,
+#                  hooks/, doctrine/, config.json). NOT a root and not a repo —
+#                  just a path, derived from the calling script's own $0, so a
+#                  script can find its sibling lib/ files whether the harness is
+#                  vendored at the repo root or in a subdirectory. It is always
+#                  inside ENTROPY_MACHINES_ROOT, or equal to it when the harness
+#                  is its own project.
+#
+# WHAT USED TO BE HERE AND WHY IT IS GONE. This file used to resolve TWO
+# roots, because the install layout was a NESTED GIT CLONE (`cd my-project &&
+# git clone <harness> entropy-machines`). A nested repo shadows its parent for
+# every git query, so "which repo am I in" had two answers depending on cwd.
+# That one fact produced all of: a second root, drift detection
+# (`entropy_harness_drift`), drift refusals in bin/init, gitignoring the
+# harness directory, and a worktree-resolution stanza to tell the two apart.
+# The vendored layout deletes the premise, so all of it is deleted. If you
+# find yourself re-adding a "which repo is this really" check, the layout has
+# regressed, not the code.
+#
+# THE NESTED CLONE IS REFUSED, NOT RESOLVED. Deleting the two-root machinery
+# removed the harness's ability to COPE with a nested clone; it did not stop
+# anyone creating one (`cd my-project && git clone <harness> tools/` is the
+# instinct, and is what the README said to do until recently). A nested repo
+# shadows its parent for every git query, so every command run from inside it
+# resolves to the HARNESS as the project: the tracker writes .entropy-machines/ into
+# the harness, dispatch and handoff operate on the wrong repo, and nothing
+# says a word. Three agents in a sibling project were lost to exactly that on
+# 2026-08-17. entropy_machines_refuse_nested_clone() says so and exits. It is a
+# REFUSAL, not a resolution scheme — if it ever grows a way to keep working
+# in that layout, the expensive mistake has been re-made.
+#
+# ENTROPY_MACHINES_ROOT USES --git-common-dir, NOT --show-toplevel. THIS IS
+# LOAD-BEARING. From inside a LINKED WORKTREE --show-toplevel prints the
+# WORKTREE's own path. Tracker state lives under .entropy-machines/, which is
+# gitignored and therefore absent from every worktree — resolving it that way
+# hands a dispatched worker an EMPTY tracker instead of the project's, which
+# reads as "no issues" rather than as an error. --git-common-dir names the
+# main checkout's .git from anywhere, including from inside a worktree, which
+# is the question actually being asked. A previous bug here sent state to the
+# wrong place; do not "simplify" this to --show-toplevel.
+
+# entropy_machines_home <path-to-calling-script>   — echoes the harness directory.
+entropy_machines_home() {
+  CDPATH= cd -- "$(dirname -- "$1")/.." 2>/dev/null && pwd -P
+}
+
+# entropy_machines_git_root [dir]  — echoes the main checkout of the git repository
+# containing <dir> (default: the current directory), or nothing (exit 1).
+#
+# GIT ONLY: no config.json walk-up. entropy_machines_root() adds that fallback; the
+# nested-clone check must not have it, because it asks specifically "WHICH GIT
+# REPOSITORY owns this directory" and a walk-up would answer a different
+# question with a path that looks like an answer.
+entropy_machines_git_root() {
+  _egr_dir=${1:-}
+  if [ -n "$_egr_dir" ]; then
+    _egr_common=$(CDPATH= cd -- "$_egr_dir" 2>/dev/null && git rev-parse --git-common-dir 2>/dev/null) || _egr_common=""
+  else
+    # No argument: run git in the AMBIENT cwd rather than cd-ing to "$PWD",
+    # so entropy_machines_root() below keeps the exact behaviour it had before this
+    # helper was extracted out of it.
+    _egr_dir=$PWD
+    _egr_common=$(git rev-parse --git-common-dir 2>/dev/null) || _egr_common=""
+  fi
+  if [ -n "$_egr_common" ]; then
+    # --git-common-dir may print a path relative to the directory git ran in.
+    case "$_egr_common" in
+      /*) ;;
+      *) _egr_common="$_egr_dir/$_egr_common" ;;
+    esac
+    if _egr_top=$(CDPATH= cd -- "$_egr_common/.." 2>/dev/null && pwd -P); then
+      printf '%s\n' "$_egr_top"
+      unset _egr_dir _egr_common _egr_top
+      return 0
+    fi
+  fi
+  unset _egr_dir _egr_common
+  return 1
+}
+
+# entropy_machines_root   — echoes the repository's main checkout, or nothing (exit 1).
+#
+# No environment override. Nothing in this harness needs one any more: every
+# caller either runs with a cwd inside the project (git answers), or is a git
+# hook (git guarantees the cwd) or a scheduled unit that cd's into the harness
+# directory first — which is inside the project. The old ENTROPY_PROJECT
+# override existed to paper over the nested clone, and papering is exactly
+# what made the wrong answer survivable.
+entropy_machines_root() {
+  if _er_top=$(entropy_machines_git_root); then
+    printf '%s\n' "$_er_top"
+    unset _er_top
+    return 0
+  fi
+
+  # No git. Walk up for config.json so the harness still works in a plain
+  # directory — the config loader's own tests do exactly this.
+  _er_d=$PWD
+  while [ -n "$_er_d" ] && [ "$_er_d" != "/" ]; do
+    if [ -f "$_er_d/config.json" ]; then
+      printf '%s\n' "$_er_d"
+      unset _er_d
+      return 0
+    fi
+    _er_d=$(dirname -- "$_er_d")
+  done
+
+  unset _er_d
+  return 1
+}
+
+# entropy_machines_refuse_nested_clone <tool-name>  — exits 2 if the harness is a
+# NESTED GIT REPOSITORY inside the project. A REFUSAL, not a resolution: it
+# never tries to make that layout work (see the header).
+#
+# The harness is vendored — plain files committed into the project — so
+# $ENTROPY_MACHINES_HOME/.git normally does not exist at all and this returns
+# immediately. When it DOES exist there is exactly one innocent explanation:
+# the harness IS the project, either developed standalone or vendored at the
+# repo root. That still holds from inside a linked worktree, where the .git
+# is a FILE pointing at the main checkout.
+#
+# So: nested iff a DIFFERENT repository encloses the harness's parent
+# directory than the one that owns the harness directory itself. Deliberately
+# phrased without ENTROPY_MACHINES_ROOT, which is resolved from the CWD and is
+# therefore the shadowed, wrong answer in the very case being detected.
+entropy_machines_refuse_nested_clone() {
+  _rnc_tool=${1:-entropy-machines}
+  _rnc_home=${ENTROPY_MACHINES_HOME:-}
+  if [ -z "$_rnc_home" ] || [ ! -e "$_rnc_home/.git" ]; then
+    unset _rnc_tool _rnc_home
+    return 0
+  fi
+
+  _rnc_owner=$(entropy_machines_git_root "$_rnc_home") || _rnc_owner=""
+  _rnc_outer=$(entropy_machines_git_root "$_rnc_home/..") || _rnc_outer=""
+
+  if [ -z "$_rnc_outer" ] || [ "$_rnc_outer" = "$_rnc_owner" ]; then
+    unset _rnc_tool _rnc_home _rnc_owner _rnc_outer
+    return 0
+  fi
+
+  echo "$_rnc_tool: REFUSED — the harness is a nested git repository." >&2
+  echo "  $_rnc_home has its own .git, and it sits inside another" >&2
+  echo "  repository ($_rnc_outer)." >&2
+  echo "" >&2
+  echo "  A nested repo shadows its parent for every git query, so every" >&2
+  echo "  command run from inside it resolves to the HARNESS as the project:" >&2
+  echo "  the tracker writes .entropy-machines/ into the harness, and dispatch and" >&2
+  echo "  handoff operate on the wrong repository. Nothing has been written." >&2
+  echo "" >&2
+  echo "  This harness is VENDORED, not cloned — plain files committed into" >&2
+  echo "  the project alongside its code, exactly as a scripts/ directory is." >&2
+  echo "  Fix it either way:" >&2
+  echo "    rm -rf $_rnc_home/.git" >&2
+  echo "    git -C $_rnc_outer add $_rnc_home && git -C $_rnc_outer commit" >&2
+  echo "  or re-vendor: delete $_rnc_home and copy the harness's files in" >&2
+  echo "  (no .git), then commit them into $_rnc_outer." >&2
+  unset _rnc_tool _rnc_home _rnc_owner _rnc_outer
+  exit 2
+}
+
+# entropy_machines_require_root <tool-name>  — sets and exports ENTROPY_MACHINES_ROOT, or exits 2
+# with a message that names the directory actually looked in.
+#
+# config.json is still the project's contract with the harness, and its
+# absence is still a refusal: every other entry point would otherwise have to
+# guess at paths, suite commands and protected paths it has not been told.
+# bin/init is the one command that runs without it, because it is the thing
+# that writes it.
+entropy_machines_require_root() {
+  _err_tool=${1:-entropy-machines}
+  # Before anything is resolved: in a nested clone every answer below is the
+  # harness's, not the project's, and they all look plausible.
+  entropy_machines_refuse_nested_clone "$_err_tool"
+  if ! ENTROPY_MACHINES_ROOT=$(entropy_machines_root); then
+    echo "$_err_tool: REFUSED — not inside a git repository, and no config.json" >&2
+    echo "  found by walking up from $PWD." >&2
+    echo "  cd into the project you are running the factory on." >&2
+    unset _err_tool
+    exit 2
+  fi
+  if [ ! -f "${ENTROPY_MACHINES_HOME:-$ENTROPY_MACHINES_ROOT}/config.json" ]; then
+    echo "$_err_tool: REFUSED — no config.json at ${ENTROPY_MACHINES_HOME:-$ENTROPY_MACHINES_ROOT}." >&2
+    echo "  That is this project's contract with the harness: every path," >&2
+    echo "  command and suite the harness would otherwise hardcode lives in" >&2
+    echo "  it. See ${ENTROPY_MACHINES_HOME:-<harness>}/docs/CONFIG.md." >&2
+    echo "  To create a starter one:  ${ENTROPY_MACHINES_HOME:-<harness>}/bin/init" >&2
+    unset _err_tool
+    exit 2
+  fi
+  export ENTROPY_MACHINES_ROOT
+  unset _err_tool
+}

package/lib/themes/daylight.css

@@ -0,0 +1,84 @@
+/* daylight — the long-reading theme. LIGHT FIRST.
+   The bare :root is the light palette and [data-theme=dark] is the override,
+   which is the mirror image of high-contrast.css. Both directions of the
+   toggle therefore work under either theme: whichever state a theme does not
+   name falls through to its own bare :root.
+
+   EVERY TOKEN HAS A VALUE IN THE BARE :root. A token defined only under
+   [data-theme=dark] renders unstyled in the default state — that is the
+   classic bug in a theme file and the reason the test compares the two files'
+   token NAME sets rather than eyeballing them.
+
+   WHAT IT IS, AND WHY IT IS NOT A RECOLOURED hc-light. hc-light maximises
+   legibility: pure white ground, saturated 4.5:1-and-up ink on every element,
+   a border hue loud enough to be a signal on its own. daylight is for reading
+   a long report end to end, so it trades some of that for comfort:
+
+     * The ground is warm paper (#FAF8F4), not #fff, and the ink is a
+       blue-leaning near-black (#23262E), not #292929 grey — a slight hue bias
+       in both directions rather than a pure neutral, which is what stops a
+       full page of prose reading as printer output.
+     * The rules are quiet. --line sits at 3.25:1 on the ground: a real
+       boundary you can see, not a stripe that competes with the text. The
+       structural CSS still separates with borders and never with tints, so
+       quieting the line is the whole difference between the two looks.
+     * The type scale is bigger and further apart — 13/16/20/28 against
+       high-contrast's 12/14/16/20. Body sits at the browser default rather
+       than below it, and the title is more than twice the small step, so a
+       heading reads as a heading in a page of running text.
+     * --accent (#2A5DB0 light / #7FB2F0 dark) is one blue that works on both
+       grounds, so a link does not change character with the toggle.
+     * --focus is amber (#B45309 / #F0A868) — the one hue no other token
+       occupies in either state, because focus has to be unmistakable, and the
+       structural CSS draws it as a border and never as a fill.
+
+   SEMANTICS DO NOT RELY ON HUE. ok is a teal-green, warn an amber, bad a red;
+   under deuteranopia or protanopia the teal stays visibly cool while the other
+   two collapse together, so the three are also separated by LIGHTNESS — in the
+   light state ok/warn/bad differ by 1.40:1, 1.47:1 and 2.05:1 in luminance,
+   and in the dark state by 1.85:1, 1.29:1 and 1.43:1. Every one of them clears
+   4.5:1 against its own ground. The templates pair each of these colours with
+   a word ("open", "ok"); keep that true — the colour is the second signal, not
+   the only one.
+
+   Body text on ground: 14.26:1 light, 14.13:1 dark. Muted text (--dim):
+   6.29:1 light, 7.43:1 dark.
+
+   A THEME FILE IS TOKENS ONLY — no layout, no component rules, no @font-face,
+   no remote URL. Selected by docs.theme in config.json; bin/serve inlines it
+   between a doc's entropy-machines-theme:begin and entropy-machines-theme:end markers and never
+   links to it. See docs/CONFIG.md. */
+:root{
+  --bg:#FAF8F4;              /* warm paper, not #fff */
+  --panel:#FFFFFF;           /* one step up from the ground, for insets */
+  --ink:#23262E;             /* blue-leaning near-black — 14.26:1 on --bg */
+  --dim:#5A5C63;             /* 6.29:1 — a real value, never opacity */
+  --line:#8E8A7E;            /* 3.25:1 — visible, quiet */
+  --focus:#B45309;           /* amber; no other token uses this hue */
+  --accent:#2A5DB0;          /* one link blue for both grounds */
+  --ok:#0B6E5A;              /* teal-green: stays cool for a red-green reader */
+  --warn:#A06E12;
+  --bad:#8C1D18;             /* darkest of the three here, so it shouts */
+  --alt:#6D4AA8;
+  --fs-sm:13px; --fs-base:16px; --fs-head:20px; --fs-title:28px;
+  --mono:ui-monospace,SFMono-Regular,Menlo,monospace;
+  --positive:var(--ok); --good:var(--ok); --muted:var(--dim); --border:var(--line);
+  --caution:var(--warn); --warn-deep:var(--warn); --code-bg:var(--panel);
+}
+/* The dark state. Ink-on-slate rather than white-on-black: the same trade as
+   the light state, one stop softer than high contrast at both ends. The type
+   scale does not change with the state, so it is not restated. The aliases are
+   var() references and re-resolve here on their own. */
+:root[data-theme=dark]{
+  --bg:#14161A;              /* slate, not #000 */
+  --panel:#1B1E24;
+  --ink:#E6E3DC;             /* warm off-white — 14.13:1 on --bg */
+  --dim:#A8A69F;             /* 7.43:1 */
+  --line:#626973;            /* 3.27:1 */
+  --focus:#F0A868;
+  --accent:#7FB2F0;
+  --ok:#34A98D;
+  --warn:#F2C87B;
+  --bad:#FF8C82;             /* lightest of the three here, so it shouts */
+  --alt:#C79BEE;
+}

package/lib/themes/high-contrast.css

@@ -0,0 +1,36 @@
+/* high-contrast — the house style, and the default.
+   VS Code High Contrast: hc-black as the bare :root, hc-light on the toggle.
+   Lifted verbatim from what lib/REPORT-TEMPLATE.html has always shipped; the
+   values are established house style, not up for improvement here.
+
+   A THEME FILE IS TOKENS ONLY. No layout, no component rules, no @font-face
+   and no remote URL of any kind — the structural CSS stays in the templates
+   so both themes get every structural fix for free, and bin/doclint refuses
+   any doc that references something off this machine.
+
+   Selected by docs.theme in config.json (see docs/CONFIG.md). bin/serve
+   INLINES this file between a doc's entropy-machines-theme:begin and entropy-machines-theme:end
+   markers, and into its own dashboard. It is never linked to as a stylesheet:
+   a doc is a standalone local file that must still look right when it is
+   opened straight off disk or moved somewhere else. */
+:root{
+  --bg:#000; --panel:#000;
+  --ink:#fff; --dim:rgba(255,255,255,.7);
+  --line:#6FC3DF;            /* contrastBorder */
+  --focus:#F38518;           /* focusBorder / activeContrastBorder */
+  --accent:#21A6FF;          /* textLink.foreground */
+  --ok:#23D18B; --warn:#F5F543; --bad:#F48771; --alt:#D670D6;
+  --fs-sm:12px; --fs-base:14px; --fs-head:16px; --fs-title:20px;
+  --mono:ui-monospace,SFMono-Regular,Menlo,monospace;
+  --positive:var(--ok); --good:var(--ok); --muted:var(--dim); --border:var(--line);
+  --caution:var(--warn); --warn-deep:var(--warn); --code-bg:var(--panel);
+}
+/* The toggle stamps data-theme on the root element. hc-black is the bare
+   :root, so only the light state needs restating; [data-theme=dark] matches
+   nothing here and correctly falls through to the default. */
+:root[data-theme=light]{
+  --bg:#fff; --panel:#fff;
+  --ink:#292929; --dim:rgba(41,41,41,.75);
+  --line:#0F4A85; --focus:#006BBD; --accent:#0F4A85;
+  --ok:#0A5C21; --warn:#7A4A00; --bad:#A81C0B; --alt:#6B21A8;
+}