entropy-machines 0.1.1

package/bin/init

@@ -0,0 +1,232 @@
+#!/bin/sh
+# Bootstrap: write a starter config.json for a project that has none yet.
+#
+# THE CHICKEN-AND-EGG THIS SOLVES — every other entry point in this harness
+# refuses to run without config.json (docs/CONFIG.md rule 2: a missing key
+# is refused by name, never silently defaulted). That is deliberate, but it
+# leaves a brand-new project with no way in: the first thing a new user is
+# meant to do is run the factory once to discover its own config, and that
+# cannot start if the config file it discovers things INTO does not exist.
+# This script writes the minimal file that unblocks everything else, then
+# gets out of the way — completing it honestly is issue q-1's job, not this
+# script's. See docs/CONFIG.md.
+#
+# Usage: bin/init [--force]
+#
+#   (no flags)  refuse if config.json already exists — never silently
+#               overwrite a config someone has tuned.
+#   --force     overwrite an existing config.json.
+set -e
+
+usage() {
+  cat >&2 <<'EOF'
+usage: bin/init [--force]
+EOF
+  exit 2
+}
+
+force=""
+for arg in "$@"; do
+  case "$arg" in
+    --force) force=1 ;;
+    -h|--help) usage ;;
+    *)
+      echo "init: unrecognized argument: $arg" >&2
+      usage
+      ;;
+  esac
+done
+
+. "$(dirname "$0")/../lib/roots.sh"
+ENTROPY_MACHINES_HOME=$(entropy_machines_home "$0")
+
+# THE NESTED-CLONE REFUSAL STILL APPLIES, and has to be called explicitly.
+# entropy_machines_require_root() runs it first, but this script cannot use that (see
+# below), so skipping it silently exempted the ONE command whose whole job is
+# to write files -- and it wrote config.json INTO the harness, which is the
+# exact misrouting the refusal exists to stop. A gate that every entry point
+# honours except the one that creates state is not a gate.
+entropy_machines_refuse_nested_clone init
+
+# Deliberately entropy_machines_root, NOT entropy_machines_require_root: the latter
+# exits unless config.json already exists at the resolved root, and this
+# script is the thing that creates it.
+if ! project=$(entropy_machines_root); then
+  echo "init: 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 want to run the factory on." >&2
+  exit 2
+fi
+
+target="$ENTROPY_MACHINES_HOME/config.json"
+
+if [ -f "$target" ] && [ -z "$force" ]; then
+  echo "init: REFUSED — config.json already exists at $target." >&2
+  echo "  Not overwriting a config someone has tuned. Re-run with --force" >&2
+  echo "  if you mean to replace it." >&2
+  exit 2
+fi
+
+project_name=$(basename -- "$project")
+
+# EVERY REFUSAL COMES BEFORE EVERY WRITE. This check used to sit down at step
+# 5, after config.json and .gitignore had already been written, so a harness
+# missing its PRD left the project half-initialised — configured, but with
+# nothing to do next and an config.json that a re-run would then refuse to
+# overwrite. A gate that fires after the damage is not a gate.
+# The PRD is the HTML dialogue doc, not the markdown quickstart. They are two
+# different artifacts for two different readers: docs/QUICKSTART.md tells an
+# AGENT how to operate this repo, and PRD-001 is the doc the OWNER answers in a
+# browser. init used to copy the quickstart here, which put a document written
+# for agents in front of the human and gave them nothing to answer.
+#
+# It lands in the project's docs directory because that is what bin/serve
+# serves; docs.dir is config, defaulting to entropy-machines-docs/.
+prd_src="$ENTROPY_MACHINES_HOME/lib/PRD-001-orientation.html"
+docs_dir=$(python3 "$ENTROPY_MACHINES_HOME/lib/config.py" get docs.dir 2>/dev/null | tr -d '"')
+if [ -z "$docs_dir" ] || [ "$docs_dir" = "null" ]; then docs_dir="entropy-machines-docs"; fi
+prd_dst="$project/$docs_dir/PRD-001-orientation.html"
+
+if [ ! -f "$prd_src" ]; then
+  echo "init: REFUSED — $prd_src is missing." >&2
+  echo "  That file is the orientation PRD; without it this command would" >&2
+  echo "  write a config and leave you with nothing to do next. Nothing has" >&2
+  echo "  been written." >&2
+  exit 2
+fi
+
+# STEP 3 — write the starter file. Minimal and honest: every value here is
+# either verified (the directory's own name) or a safe, inert default. In
+# particular, suites is an empty array, not a guess like `npm test` — a
+# fabricated suite command that does not exist is worse than an empty list,
+# because post-fold-audit and the verifier would report a broken command as
+# a failing project instead of an unconfigured one. Filling suites in (and
+# everything else this file leaves out — generate, guards, worktree beyond
+# the placeholder below, unattended) is work the orientation PRD asks the
+# owner to decide and then file as issues.
+cat > "$target" <<EOF
+{
+  "project": { "name": "$project_name" },
+  "tracker": { "backend": "file", "file": { "path": ".entropy-machines/issues.json" } },
+  "suites": [],
+  "changelog": { "enabled": false }
+}
+EOF
+
+# STEP 4 — .entropy-machines/ is where the tracker's issues.json lives; it is
+# per-checkout state, not something to commit.
+gitignore="$project/.gitignore"
+
+# Append one entry, creating .gitignore if the project has none. grep -qx so a
+# re-run does not duplicate a line; -F because the entry is a path, and a path
+# is not a regular expression — an unlucky project directory name (`v1.2`, or
+# anything with a bracket) would otherwise either match the wrong line or make
+# grep error out on a malformed pattern and append a duplicate.
+add_ignore() {
+  if [ -f "$gitignore" ]; then
+    if ! grep -qxF -- "$1" "$gitignore"; then
+      # A .gitignore whose last line has no trailing newline would otherwise
+      # weld the entry onto it — `node_modules/.entropy-machines/` — one pattern that
+      # matches nothing, in place of two that match. `$(tail -c 1)` strips a
+      # trailing newline and is therefore empty exactly when there is one.
+      if [ -s "$gitignore" ] && [ -n "$(tail -c 1 "$gitignore")" ]; then
+        printf '\n' >> "$gitignore"
+      fi
+      printf '%s\n' "$1" >> "$gitignore"
+    fi
+  else
+    printf '%s\n' "$1" > "$gitignore"
+  fi
+}
+
+add_ignore ".entropy-machines/"
+# Python leaves these the first time any harness tool runs, INSIDE the files
+# the user just committed. Ignoring .entropy-machines/ but not these meant a fresh init
+# dirtied the tree it had just set up.
+add_ignore "__pycache__/"
+# Per-dispatch briefs, written by bin/dispatch. Local scratch, not history.
+add_ignore ".dispatch-context/"
+# hooks/post-checkout drops this symlink into every worktree it creates. It was
+# invisible until the scope check started working; now every `handoff --lift`
+# would flag or refuse on it.
+add_ignore ".scratch"
+# docs.dir. The docs a project answers ARE the project's own work — a PRD with
+# the owner's answers in it, a report of a sprint that happened here — and the
+# harness cannot know they are fit to publish. They are also machine-written on
+# every serve (TRACKER.html is regenerated by bin/tracker render), so tracking
+# them means a dirty tree after every read. Committing them once put an owner's
+# answered PRD into a public repository. Ignore by default; a project that wants
+# its docs in history removes the line deliberately.
+add_ignore "$docs_dir/"
+
+# STEP 5 — put the orientation PRD in front of the owner.
+#
+# THIS IS THE POINT OF init, AND IT DOES NOT FILE ANY ISSUES. A PRD is the
+# UPSTREAM artifact here: it is what CREATES issues. Seeding a task called
+# "orient the factory" would invert that — it would make the machine hand the
+# owner a job before the owner has decided anything, and it would skip the
+# only step no code path can reach. The PRD's open questions are the owner's
+# to rule on, and the issues fall out of those rulings.
+#
+# lib/PRD-001-orientation.html IS that PRD. It is not a tutorial about a PRD,
+# it is the first one, and it is copied into the project so the owner fills in
+# THEIR answers rather than editing the harness's shipped copy.
+prd_written=""
+if [ -f "$prd_dst" ] && [ -z "$force" ]; then
+  prd_note="init: left existing $prd_dst alone (--force overwrites)."
+else
+  mkdir -p -- "$(dirname -- "$prd_dst")"
+  cp -- "$prd_src" "$prd_dst"
+  prd_written=yes
+  prd_note="init: wrote $prd_dst — open it. It is the first PRD, and the"
+fi
+
+# STEP 6 — prove the tracker actually answers before claiming success.
+# A read, not a write: nothing is filed here. An init that reports success
+# while the tracker is unreachable is the exact failure this harness exists
+# to prevent, and the owner would only discover it at the moment they tried
+# to file their first issue.
+#
+# IT IS THE ONE CHECK THAT CANNOT MOVE UP. Everything above this line is a
+# refusal that fires before any write; this one cannot be, because what it
+# tests is whether the tracker answers for a config that does not exist until
+# step 3 wrote it. So it is NOT phrased as a refusal: the writes above really
+# did happen, and calling it "REFUSED" told the user nothing was written when
+# in fact everything was — and a plain re-run then died on "config.json
+# already exists" with no repair path named.
+if ! (cd "$project" && "$ENTROPY_MACHINES_HOME/bin/tracker" ready >/dev/null 2>&1); then
+  echo "init: WARNING — $target was WRITTEN, but bin/tracker could not read the" >&2
+  echo "  tracker back afterward. This is not a refusal: everything above" >&2
+  echo "  really was written, and the project is half-initialised." >&2
+  echo "  Check $project/.entropy-machines/ and $target by hand." >&2
+  echo "  To re-run once you have fixed it (a plain re-run will refuse," >&2
+  echo "  because config.json now exists):" >&2
+  echo "      $ENTROPY_MACHINES_HOME/bin/init --force" >&2
+  exit 2
+fi
+
+echo "init: wrote $target"
+echo "$prd_note"
+if [ -n "$prd_written" ]; then
+  echo "      questions in it are the ones only you can answer."
+fi
+# PATHS ARE PRINTED AS THE READER MUST TYPE THEM. These lines used to say a
+# bare `bin/serve`, which is only correct when the harness sits at the repo
+# root. Vendored in a subdirectory -- now the default -- that command does not
+# exist, and the closing instruction of the setup command was one a user could
+# not run.
+case "$ENTROPY_MACHINES_HOME" in
+  "$project") cmd_prefix="bin" ;;
+  "$project"/?*) cmd_prefix="${ENTROPY_MACHINES_HOME#"$project"/}/bin" ;;
+  *) cmd_prefix="$ENTROPY_MACHINES_HOME/bin" ;;
+esac
+# RENDER THE TRACKER, so PRD-001's one nav link resolves on day one. The PRD
+# links to TRACKER.html; nothing else creates it, and a first-run user opening
+# the first document the harness hands them would otherwise hit a 404 — which
+# is exactly the bug that made this necessary.
+"$ENTROPY_MACHINES_HOME/bin/tracker" render >/dev/null 2>&1 || \
+  echo "init: warning — could not render TRACKER.html; run \`$cmd_prefix/tracker render\`" >&2
+
+echo "init: tracker is live and empty — \`$cmd_prefix/tracker ready\` answers."
+echo "init: next — run \`$cmd_prefix/serve\` and answer the PRD it opens."
+echo "      Filing the issues it produces is step one."

package/bin/post-fold-audit

@@ -0,0 +1,377 @@
+#!/usr/bin/env python3
+"""Audit the ORCHESTRATOR's folds, after they land.
+
+WHY THIS EXISTS. Every other check in the factory points at the workers. The
+verifier sweeps their finished output before anything is folded; the workers
+prove their own guards. Nothing looks at the code the ORCHESTRATOR writes, and
+it does write some: a conflict resolved by hand at merge time is new code,
+covered by no worker's test and seen by no verifier.
+
+Not hypothetical. A patch adding one feature once stopped applying because a
+guard written for a different feature had landed underneath it in the merge.
+The naive conflict resolution left the new feature UNREACHABLE — its own
+tests caught it, eventually — and the actual fix (narrowing the other guard)
+was invented by hand during the merge. It was mutated and proved, but only
+because the orchestrator chose to. Nothing required it, and nothing would
+have noticed if it hadn't.
+
+TWO JOBS, both mechanical. No model, no judgement.
+
+  1. THE ORCHESTRATOR DELTA. Re-apply each worker's patch to the base it was
+     written against, then diff that tree against what actually landed. What
+     comes out is precisely what the orchestrator wrote at merge time.
+
+  2. HEAD IS GREEN, ON A CLEAN TREE. The orchestrator's checkout carries other
+     sessions' uncommitted work, so a green run there is not a green HEAD --
+     which is how a real regression once survived being repeatedly dismissed
+     as a local artefact before someone finally traced it back to HEAD. This
+     runs the suites (config.json's `suites[]`) in a throwaway worktree at
+     committed HEAD.
+
+Run as a script, not as a fifth agent role: once per sprint, after that
+sprint's folds land and before its report closes it out.
+
+  bin/post-fold-audit --since <ref>
+  bin/post-fold-audit --since <ref> --patch a.patch --base <sha>
+  bin/post-fold-audit --clean-tree-only
+  bin/post-fold-audit --skip <tag>         # skip every suite carrying <tag>
+  bin/post-fold-audit --quick              # shorthand for --skip slow
+
+Writes a stamp naming the commit it verified, under `unattended.stateHome`.
+Whatever closes a sprint on top of this tooling can refuse to do so when that
+stamp is older than the newest commit — a sprint should not close on a tree
+nobody actually checked at HEAD.
+
+Exit 0 clean | 1 findings | 2 misuse.
+"""
+import argparse
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import time
+
+# ONE ROOT -- see lib/roots.sh, which this block mirrors for the shell entry
+# points. ENTROPY_MACHINES_ROOT is the repository's MAIN checkout: config.json,
+# .entropy-machines/ and the git history live there, and the harness is vendored inside
+# it as plain tracked files. ENTROPY_MACHINES_HOME is only the DIRECTORY this harness's
+# own files sit in (bin/, lib/, hooks/, doctrine/) -- the repo root, or a
+# subdirectory of it -- resolved from this file's own path so sibling lib/
+# imports work wherever it is vendored. It is not a root and not a repo.
+ENTROPY_MACHINES_HOME = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+sys.path.insert(0, os.path.join(ENTROPY_MACHINES_HOME, "lib"))
+from config import load_config  # noqa: E402  (path must be set up first)
+
+
+def _refuse_nested_clone():
+    """Mirror of lib/roots.sh's entropy_refuse_nested_clone(). See lib/config.py."""
+    sys.path.insert(0, os.path.join(
+        os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "lib"))
+    import config
+    config.refuse_nested_clone("post-fold-audit")
+
+
+def _entropy_machines_root():
+    """Mirrors lib/roots.sh's entropy_machines_root(): the repository's main checkout,
+    or None. `git rev-parse --git-common-dir` -- NOT --show-toplevel, which
+    prints a linked WORKTREE's own path and would hand this tool a root whose
+    .entropy-machines/ does not exist. Falls back to walking up for config.json when
+    there is no git. No environment override, matching lib/roots.sh: with one
+    root there is nothing for an override to disambiguate.
+    """
+    try:
+        p = subprocess.run(
+            ["git", "rev-parse", "--git-common-dir"],
+            capture_output=True, text=True, timeout=10,
+        )
+    except (OSError, subprocess.SubprocessError):
+        p = None
+    if p is not None and p.returncode == 0 and p.stdout.strip():
+        common = p.stdout.strip()
+        if not os.path.isabs(common):
+            common = os.path.join(os.getcwd(), common)
+        return os.path.realpath(os.path.join(common, os.pardir))
+    d = os.getcwd()
+    while True:
+        if os.path.exists(os.path.join(d, "config.json")):
+            return d
+        parent = os.path.dirname(d)
+        if parent == d:
+            return None
+        d = parent
+
+
+def _require_root():
+    """Mirrors lib/roots.sh's entropy_require_root() -- returns the repo root
+    or exits 2 naming the directory actually looked in, instead of silently
+    operating on ENTROPY_MACHINES_HOME."""
+    _refuse_nested_clone()
+    project = _entropy_machines_root()
+    if not project:
+        print("post-fold-audit: REFUSED -- not inside a git repository, and no "
+              "config.json found by walking up from %s." % os.getcwd(), file=sys.stderr)
+        print("  cd into the project you are running the factory on.", file=sys.stderr)
+        sys.exit(2)
+    if not os.path.exists(os.path.join(ENTROPY_MACHINES_HOME, "config.json")):
+        print("post-fold-audit: REFUSED -- no config.json at %s." % project, file=sys.stderr)
+        print("  That is this project's contract with the harness. See "
+              "%s/docs/CONFIG.md." % ENTROPY_MACHINES_HOME, file=sys.stderr)
+        print("  To create a starter one:  %s/bin/init" % ENTROPY_MACHINES_HOME, file=sys.stderr)
+        sys.exit(2)
+    return project
+
+
+ENTROPY_MACHINES_ROOT = _require_root()
+CONFIG = load_config(cwd=ENTROPY_MACHINES_ROOT)
+STAMP = os.path.join(
+    os.path.expanduser(CONFIG["unattended"]["stateHome"]),
+    "clean-tree-stamp.json")
+
+
+def build_suites(cfg):
+    """`suites[]` from config.json, as (label, cmd, tag, cwd) tuples.
+
+    No suite is assumed. A project with nothing configured gets an empty
+    list here and a loud "no suites configured" print in clean_tree() rather
+    than a silent no-op — an audit that quietly checks zero suites and exits
+    0 is worse than one that refuses to look useful.
+
+    `cwd` is not in docs/CONFIG.md yet: each suite entry may carry its own
+    `"cwd"` (relative to the worktree root, default `"."`), for a project
+    whose toolchain lives in a subdirectory rather than at the repo root.
+    """
+    suites = []
+    for s in cfg.get("suites", []):
+        suites.append((s["name"], s["cmd"], s.get("tag"), s.get("cwd", ".")))
+    return suites
+
+
+def sh(args, cwd, timeout=2400):
+    p = subprocess.run(args, cwd=cwd, capture_output=True, text=True, timeout=timeout)
+    return p.returncode, (p.stdout or "") + (p.stderr or "")
+
+
+def git(args, cwd=ENTROPY_MACHINES_ROOT):
+    return sh(["git"] + args, cwd)
+
+
+def worktree(at, label):
+    """A throwaway worktree at `at`, with worktree.linkPaths symlinked in.
+
+    The symlinks are not a convenience. Without them a runtime walks UP out of
+    the worktree and resolves dependencies from a SIBLING worktree -- you run
+    someone else's code and report the result as your own. That has happened
+    here.
+
+    READ FROM CONFIG, NOT HARDCODED. This used to symlink `node_modules` and
+    nothing else, which silently did nothing for a project that is not
+    JavaScript -- so a Python or Go project got an unlinked worktree and the
+    exact failure above, in the one code path whose job is to catch it.
+    """
+    d = tempfile.mkdtemp(prefix="post-fold-audit-%s-" % label)
+    path = os.path.join(d, "tree")
+    rc, out = git(["worktree", "add", "--detach", path, at])
+    if rc != 0:
+        shutil.rmtree(d, ignore_errors=True)
+        return None, out
+    for rel in (CONFIG.get("worktree") or {}).get("linkPaths") or []:
+        src = os.path.join(ENTROPY_MACHINES_ROOT, rel)
+        if not os.path.isdir(src):
+            continue
+        dst = os.path.join(path, rel)
+        if os.path.exists(dst):
+            # Already present in the tree (it is tracked, not ignored). Nothing
+            # to link, and nothing wrong.
+            continue
+        try:
+            os.makedirs(os.path.dirname(dst), exist_ok=True)
+            os.symlink(src, dst)
+        except OSError as exc:
+            # SAY SO. A swallowed failure here leaves a worktree that resolves
+            # its dependencies from a sibling -- the precise thing this function
+            # exists to prevent -- and the audit would then report someone
+            # else's results as this sprint's, with nothing in the output to
+            # suggest anything went wrong.
+            print("post-fold-audit: WARNING could not link %s into %s (%s).\n"
+                  "  Suites run in this worktree may resolve dependencies from\n"
+                  "  another tree; treat their results as unproven."
+                  % (rel, path, exc), file=sys.stderr)
+    return path, ""
+
+
+def drop(path):
+    if not path:
+        return
+    git(["worktree", "remove", "--force", path])
+    shutil.rmtree(os.path.dirname(path), ignore_errors=True)
+
+
+def orchestrator_delta(patch, base, findings):
+    """What the orchestrator wrote at merge time, and nothing else."""
+    name = os.path.basename(patch)
+    rc, out = sh(["git", "apply", "--numstat", patch], ENTROPY_MACHINES_ROOT)
+    if rc != 0:
+        findings.append("%s: unreadable as a patch -- %s" % (name, out.strip()[:160]))
+        return
+    files = [l.split("\t")[-1] for l in out.splitlines() if "\t" in l]
+    if not files:
+        findings.append("%s: patch touches no files" % name)
+        return
+
+    path, err = worktree(base, "delta")
+    if not path:
+        findings.append("%s: no worktree at %s -- %s" % (name, base, err.strip()[:160]))
+        return
+    try:
+        rc, out = sh(["git", "apply", "--binary", "-3", patch], path)
+        if rc != 0:
+            # Not applying to its OWN base means the base is wrong, which makes
+            # any delta below meaningless. Say so; do not guess.
+            findings.append("%s: does not apply to --base %s; delta NOT computed -- %s"
+                            % (name, base, out.strip()[:160]))
+            return
+        print("\n=== ORCHESTRATOR DELTA - %s (base %s)" % (name, base[:9]))
+        changed = []
+        for f in files:
+            a, b = os.path.join(path, f), os.path.join(ENTROPY_MACHINES_ROOT, f)
+            if not os.path.exists(b):
+                changed.append((f, "deleted after fold"))
+                continue
+            if not os.path.exists(a):
+                continue
+            rc3, d = sh(["git", "diff", "--no-index", "--numstat", a, b], ENTROPY_MACHINES_ROOT)
+            if d.strip():
+                n = d.split("\t")[:2]
+                changed.append((f, "+%s/-%s" % (n[0], n[1]) if len(n) == 2 else "differs"))
+        if not changed:
+            print("  none - what landed is byte-identical to what the worker wrote")
+        else:
+            for f, how in changed:
+                print("  %s  %s" % (f, how))
+            findings.append(
+                "%s: %d file(s) differ from the worker's patch. That is "
+                "orchestrator-written code -- confirm each hunk is covered by a "
+                "test you mutated yourself." % (name, len(changed)))
+    finally:
+        drop(path)
+
+
+def clean_tree(skip_tags, findings):
+    suites = build_suites(CONFIG)
+    if not suites:
+        findings.append("no suites configured -- config.json's suites[] is empty; "
+                        "nothing was run at HEAD")
+        return None, {}
+    rc, head = git(["rev-parse", "HEAD"])
+    head = head.strip()
+    path, err = worktree(head, "cleantree")
+    if not path:
+        findings.append("cannot create clean worktree -- %s" % err.strip()[:160])
+        return None, {}
+    results = {}
+    try:
+        print("\n=== CLEAN TREE AT HEAD %s" % head[:9])
+        for label, cmd, tag, cwd_rel in suites:
+            if tag and tag in skip_tags:
+                results[label] = "skipped (--skip %s)" % tag
+                print("  %-12s skipped (--skip %s)" % (label, tag))
+                continue
+            cwd = os.path.join(path, cwd_rel)
+            t0 = time.time()
+            try:
+                rc, out = sh(cmd, cwd)
+            except subprocess.TimeoutExpired:
+                results[label] = "TIMEOUT"
+                findings.append("clean tree: %s timed out" % label)
+                print("  %-12s TIMEOUT" % label)
+                continue
+            secs = int(time.time() - t0)
+            # The SUMMARY line, not the last line. npm's last line is often a
+            # node_modules path, which reads as a pass whether 1849 tests ran or
+            # zero did -- and a hollow green is the exact thing this script
+            # exists to catch.
+            summary = ""
+            for l in out.splitlines():
+                t = l.strip()
+                if (t.startswith("Tests ") or t.startswith("ok ")
+                        or " passed" in t or t.startswith("--- FAIL")):
+                    summary = t
+            if rc == 0:
+                results[label] = "ok (%ds) %s" % (secs, summary[:60])
+                print("  %-12s ok  %ds   %s" % (label, secs, summary[:78]))
+            else:
+                results[label] = "FAILED (%ds)" % secs
+                findings.append("clean tree: %s FAILED at HEAD -- your own "
+                                "checkout may be masking it" % label)
+                print("  %-12s FAILED  %ds" % (label, secs))
+                for l in out.splitlines():
+                    if l.startswith("FAIL") or "--- FAIL" in l or "error TS" in l:
+                        print("      %s" % l[:118])
+    finally:
+        drop(path)
+    return head, results
+
+
+def write_stamp(head, results, partial):
+    try:
+        os.makedirs(os.path.dirname(STAMP), exist_ok=True)
+        with open(STAMP, "w", encoding="utf-8") as f:
+            json.dump({"commit": head,
+                       "at": time.strftime("%Y-%m-%d %H:%M:%S"),
+                       "partial": bool(partial),
+                       "suites": results}, f, indent=1)
+        print("\nstamp: %s -> %s" % (STAMP, head[:9]))
+    except OSError as e:
+        print("stamp NOT written (%s) - whatever reads this stamp will see the sprint "
+             "as unchecked" % e)
+
+
+def main():
+    ap = argparse.ArgumentParser(add_help=True)
+    ap.add_argument("--since", help="ref the sprint's folds start after")
+    ap.add_argument("--patch", action="append", default=[], metavar="FILE")
+    ap.add_argument("--base", help="commit each --patch was written against")
+    ap.add_argument("--clean-tree-only", action="store_true")
+    ap.add_argument("--skip", action="append", default=[], metavar="TAG",
+                    help="skip every suite carrying this config.json suites[] tag "
+                         "(repeatable); a partial stamp does NOT close a sprint")
+    ap.add_argument("--quick", action="store_true",
+                    help="shorthand for --skip slow")
+    a = ap.parse_args()
+
+    if os.path.realpath(os.getcwd()) != os.path.realpath(ENTROPY_MACHINES_ROOT):
+        print("post-fold-audit: run from %s" % ENTROPY_MACHINES_ROOT, file=sys.stderr)
+        return 2
+    if a.patch and not a.base:
+        print("post-fold-audit: --patch needs --base", file=sys.stderr)
+        return 2
+
+    skip_tags = set(a.skip)
+    if a.quick:
+        skip_tags.add("slow")
+
+    findings = []
+    if not a.clean_tree_only:
+        for p in a.patch:
+            orchestrator_delta(p, a.base, findings)
+        if not a.patch:
+            print("no --patch given: the orchestrator-delta half was SKIPPED, not passed")
+    head, results = clean_tree(skip_tags, findings)
+    if head:
+        write_stamp(head, results, bool(skip_tags))
+
+    print("\n=== FINDINGS")
+    if findings:
+        for f in findings:
+            print("  - %s" % f)
+    else:
+        print("  none")
+    if skip_tags:
+        print("  (--skip %s: this stamp does not close a sprint)" % ",".join(sorted(skip_tags)))
+    return 1 if findings else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())