ergane-cli 0.6.0__tar.gz

ergane_cli-0.6.0/.agents/skills/away-mode/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: "away-mode"
+description: "Put this session on a self-paced loop that keeps the factory floor moving while the operator is away: land what is verified, attest what is complete, dispatch what is ready, answer what agents ask, and park anything that needs a human. Use when leaving the keyboard, going to bed, or asking the session to babysit the floor. `/away-mode off` ends it."
+compatibility: "Requires the ergane CLI on PATH via scripts/ergane-env.sh, gh authenticated, a checkout of this repository, and the ergane-worker/-temporal/-bridge user units running"
+metadata:
+  author: "operator session, 2026-08-17"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Away mode
+
+The operator has left. Nothing else changes about how this repository works —
+the same gates, the same queue, the same constitution — but one thing changes
+about **you**: there is no longer anyone to catch a bad call before it costs a
+night. So the whole skill reduces to one asymmetry.
+
+> **A parked node costs a wait. A wrong call costs the night.**
+> When the two are close, park.
+
+That is not timidity. It is the measured trade: on 2026-08-16 the factory lost
+three verified nodes, and every one of them was lost in the landing path by an
+automated actor being confident — not by an agent writing bad code.
+
+## Turning it on and off
+
+- `/away-mode` — start the loop.
+- `/away-mode <note>` — start it with an extra standing constraint for tonight
+  (`/away-mode don't touch 032`, `/away-mode back by 7am`). Treat the note as
+  binding and repeat it back in the first tick's log line.
+- `/away-mode off` — stop. Call `ScheduleWakeup({stop: true})`, `TaskStop` every
+  monitor you armed, and write a closing entry to the away log.
+
+On the very first tick, before anything else, say in one short message what you
+are about to do and what you will not do without them. Then work.
+
+## The mechanism
+
+This is a self-paced loop, not a cron job.
+
+1. Run **one tick** (below).
+2. Append a line to the away log.
+3. As the **last action of the turn**, call `ScheduleWakeup` with
+   `prompt: "/away-mode"` (plus tonight's note, verbatim, if there was one) so
+   the next firing re-enters this skill.
+   - `delaySeconds`: **1200–1800** when something is genuinely in flight and a
+     `<task-notification>` will wake you anyway. Shorter only when you are
+     polling something the harness cannot notify you about — a merge queue that
+     moves in minutes, a CI run you timed. Never poll a background task you
+     started; you get woken when it finishes.
+   - `noop: true` when the tick changed nothing. Long quiet stretches are the
+     normal state of a healthy floor and should collapse in the operator's view.
+   - `reason`: what you are waiting on, specifically. "watching #181 through the
+     merge group" beats "checking again".
+4. Stop when the floor is empty **and** everything left needs a human. Say so,
+   `PushNotification` the one-line outcome, and stop. Do not idle-tick against
+   an empty floor for hours; that is noise wearing the costume of diligence.
+
+## One tick
+
+Cheapest first, and **land before you dispatch** — a landed story unblocks the
+next node's merge edge, so landing is what makes dispatch legal.
+
+```bash
+eval "$(scripts/ergane-env.sh)"      # NOT `source` — it emits export lines
+git fetch origin --quiet
+uv run ergane status specs           # roadmap, epics, ready queue, drafts, pace
+```
+
+### 1. Land what is verified
+
+Read the arm state and the queue **together** — neither column means anything
+alone. `/floor-status` carries the full table; the one row that needs action is
+`auto=false` **and not in the queue**, which is a dropped arm and is fixed with a
+bare `gh pr merge <n>`. Every other combination is the queue working.
+
+Then verify the landing **on the branch**, by content:
+
+```bash
+git fetch origin --quiet && git log origin/ergane-buildout -1 --format='%h %s'
+uv run ergane spec landed specs/<dir> --default-branch ergane-buildout
+```
+
+**A pull request's `merged` flag can be true while the branch never moved.**
+That is not a hypothesis — PR #176 reported merged on 2026-08-16, the file it
+added 404'd on the branch, and the story had to be recovered by cherry-pick. A
+merged flag is a claim. The branch head is the fact.
+
+`--default-branch ergane-buildout` is not optional; `ergane spec landed` scans
+`main`, and the factory does not land there.
+
+### 2. Attest what is complete
+
+When every story of a spec is on `ergane-buildout` by ancestry *and* content,
+flip its frontmatter to `state: landed` with the convention already in the tree
+(`specs/043-runtime-root-integrity/spec.md` is the model): the date, then each
+story's landing SHA and PR number. Validate, branch, PR, arm.
+
+Attestation is not bookkeeping — `ergane status` reads it to decide readiness,
+so an unattested finished epic silently blocks whatever depended on it.
+
+### 3. Answer what the agents ask
+
+```bash
+uv run ergane build answer <epic>        # pending questions, or answer one
+uv run ergane escalations list           # what is waiting on a human
+```
+
+Questions from agents are yours to answer; that is the whole point of the
+operator channel, and an unanswered question dead-waits its window and then
+pages the operator anyway.
+
+**Escalations are not.** Never press an escalation button on the operator's
+behalf. Silence is a decision they are entitled to make, and expiry is part of
+the contract. Log the escalation, `PushNotification` it if it is time-critical,
+and leave it.
+
+### 4. Dispatch what is ready
+
+Only from `ergane status`'s **dispatchable** list. Re-derive the delta *at
+dispatch time*, never reuse a remainder file from an earlier tick — the baseline
+moved when you landed something, and a stale remainder re-runs landed stories.
+
+```bash
+uv run ergane spec derive specs/<dir> --target-repo "$PWD" --delta \
+  -o specs/<dir>/workgraph-remainder.json
+uv run ergane build start specs/<dir>/workgraph-remainder.json
+```
+
+If dispatch fails on a forge blip — a 503, a timeout, a read-after-write miss —
+**retry on a bounded loop rather than concluding anything.** GitHub's transient
+failures are minutes long; a dispatch that failed four times in a row succeeded
+80 seconds later once the retry loop was doing the timing instead of a human.
+
+If Ollama returns **429**, stop dispatching and back off a full hour. Do not
+retry into a rate limit; you will only extend it.
+
+### 5. Watch what is in flight
+
+```bash
+uv run ergane build status <epic-id>
+git -C "$wt" log --oneline origin/ergane-buildout..HEAD | wc -l
+```
+
+A node that has produced no commit in well over the measured build range
+(24–84 minutes, median ~55, on 2026-08-16) is a stall, not slowness.
+
+**Do not trust the newest attempt directory to be the live attempt.** Read
+`ATTEMPT_ARCHIVE` from the running bwrap process instead. A stale `attempt-4`
+log from a killed morning run once produced a confident, entirely false report
+that an agent had done work and never committed it.
+
+### 6. File what you learned
+
+Anything that broke and is not already in the ledger:
+
+```bash
+uv run ergane findings report --key <category>/<slug> --category <cat> \
+  --severity warning --summary "..." --notes "<reproduction, not narration>"
+```
+
+A finding with a reproduction in it is worth a spec later. A finding that
+describes a feeling is worth nothing. Findings *rising* during a hard night is
+the healthy signal — a flat ledger through heavy running means you stopped
+looking.
+
+### 7. Log the tick
+
+```bash
+printf '%s  %s\n' "$(TZ=America/Chicago date +'%Y-%m-%d %-I:%M %p CT')" "<what changed, or 'quiet'>" \
+  >> ~/ergane-ops/away-log.md
+```
+
+One line. The operator reads this file to reconstruct the night in one scroll;
+it is the only durable record that this loop ran at all.
+
+## Park list — never, while away
+
+Each of these is here because doing it unattended cost something real.
+
+| Do not | Because |
+| --- | --- |
+| Delete anything — remote refs, worktrees, store rows, branches | On 2026-08-14 an agent's `rm -rf .factory` destroyed three stores and both node worktrees; recovery took a restic snapshot and half a day |
+| Terminate a workflow beyond a failed node's own retry ladder | A kill skips the sweep, and the survivors outlive it |
+| Force-push anywhere outside a node's own branch | |
+| Touch live systemd units, or dispatch a story that provisions the host | 042/US3 installs a Temporal unit on the machine this factory runs on |
+| Modify factory code while an attempt is in flight | The worker imports it live |
+| Restart the worker mid-attempt — and never with `nohup` | `systemctl --user restart ergane-worker.service`, between attempts, only |
+| Flip a spec's state the operator deliberately held | The hold note names its release condition; if the condition needs a human, so does the flip |
+| Widen a story's scope to make it pass | |
+| Press an escalation button | Expiry is part of the contract |
+| Retain to cross-session memory | Unattended runs are read-only against memory: recall yes, retain no |
+
+When you hit one of these, do everything else in the tick, then write the parked
+item into the log **and** send it as a `PushNotification` if it is blocking. The
+operator wakes up to a decision queue, not a mystery.
+
+## Judgement rules that do not fit a table
+
+- **A green suite is evidence, not proof.** A fully green run has shipped a
+  command that could not start. If a fix matters, prove it by control or
+  mutation — break the thing on purpose and watch the test go red.
+- **The merge-group build is the gate.** A pull request's own green check tests
+  the branch, not the speculative merge, and those are different trees.
+- **Report what you ran, not what you were told.** An agent's report is a claim.
+  So is a judge verdict. So is a merged flag.
+- **Correct yourself in one line and move on.** You will be wrong about
+  something at 3 AM. Say what is true now; do not write an incident report about
+  your own reasoning.
+- **If a lesson would change how an implementer writes code, it belongs in that
+  spec's plan as a named trap** — not in your head, and not in a memory file.
+  Nothing dispatches a memory. The only path from what you learned to what an
+  agent obeys runs through refinement.
+
+## The morning message
+
+When the operator returns, or when you stop, lead with what they have to decide,
+not with what you did. Parked items first, then losses with their causes, then
+landings. Timestamp it in Central. If the honest summary is "quiet, four stories
+landed, nothing needs you" — say exactly that and stop there.

ergane_cli-0.6.0/.agents/skills/build-metrics/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: "build-metrics"
+description: "Measure what the factory has actually produced: lines of code by language and module, commit-size distribution with outliers trimmed, and the story rework rate with its trend over time. Use when asked how big the codebase is, how large a typical change is, how often stories need a second attempt, or whether the factory is getting better."
+compatibility: "Requires a checkout of this repository, python3, git, and a stable local cloc executable. Reads .ergane/*.db read-only; honors ERGANE_ROOT (with FACTORY_ROOT as the legacy alias); does not need the worker or Temporal running."
+metadata:
+  author: "operator session"
+user-invocable: true
+disable-model-invocation: false
+---
+
+# Build metrics
+
+Three families of measurement, each with a script under `scripts/`. Run only
+what was asked for — the rework analysis is the expensive-to-interpret one and
+nobody wants a LOC table when they asked about attempt counts.
+
+| Question | Script |
+| --- | --- |
+| How big is this, by language and by module? | `scripts/loc.py` |
+| How large is a typical commit? Does anything ever get deleted? | `scripts/commit_sizes.py` |
+| How often does a story need reworking, and is that improving? | `scripts/rework.py` |
+
+All three take an optional repo path and default to the current directory:
+
+```bash
+python3 .agents/skills/build-metrics/scripts/rework.py
+```
+
+`ergane` is **not on PATH** — anything shelling out to the CLI needs
+`uv run ergane`, after `eval "$(scripts/ergane-env.sh)"`. The scripts here
+deliberately avoid the CLI and read git and the SQLite stores directly, so they
+work with the worker down.
+
+## The traps, which are most of the value
+
+Every one of these produced a wrong number first.
+
+### Outliers can carry the churn
+
+Raw commit-size means are summaries of the tail as well as the typical change.
+**Report both and say which you mean.** The script's Tukey fences and trimmed
+rows are the comparison; do not quote an unqualified mean as "typical."
+
+### Machine-generated recordings can dominate LOC
+
+Machine-generated fixtures are measured by `scripts/loc.py` as their own rows.
+Keep that row visible in the answer; do not fold it into an authored-code total.
+
+### The insertion:deletion ratio measures youth, not discipline
+
+Repo-wide insertion:deletion measures youth, not discipline. The
+growth-adjusted buckets by commits touching a file are the comparison. **Quote
+the most-revisited bucket.** `scripts/commit_sizes.py` prints it.
+
+### Rework has two honest definitions
+
+- **Verification rework** — the story's first attempt was verified `FAIL`.
+- **Dispatch rework** — the story was dispatched more than once, for any reason.
+
+The second definition includes stories whose first attempt died before
+verification could judge it: `agent_error`, `timeout`, `killed`, `question`.
+Those absolutely are rework — the story was built twice — and the verification
+store cannot see them because nothing was ever verified. **Lead with the
+dispatch number.** Give the verification number as the narrower "the gates
+rejected it" figure.
+
+### Two dispatches can share every old key field
+
+Group verification attempts by the recorded dispatch before collapsing to a
+story. Dispatch identity comes only from recorded evidence that carries it; an
+old `(epic, node, attempt, persona)` key and a timestamp window do not make a
+second dispatch.
+
+### Unknown is not zero
+
+Missing tokens, dollars, runner, route, model, or landing data stay unknown.
+Keep measured subtotals beside the rows that make them partial, legacy, or
+unknown, and preserve accounting provenance even when one field happens to be
+complete. Optional cache and request counters can remain unknown even when token
+totals are complete.
+
+### Empty input is valid
+
+An empty ledger produces an empty report, not an exception. Percentages and
+coverage have explicit no-denominator paths.
+
+### `usage_records` has ~2 rows per attempt, not 1
+
+One row per persona: `implementer`, `judge`, and `debugger` when the ladder
+climbs. Always count `distinct attempt` per `(epic_id, node_id)`. Dividing row
+counts by story counts overstates rework by roughly 2×.
+
+### The stores do not cover everything that landed
+
+`scripts/rework.py` re-runs this cross-check every time and prints the coverage
+percentage or names the absence as unknown. **Say the coverage out loud in the
+report.** Report the estimate and refuse to call it a census.
+
+### Daily buckets are noise at this volume
+
+Small periods have small denominators — one story can make a day look like
+100% rework. Use **weekly** buckets and a **rolling 20-story window** ordered
+chronologically, which is what the script emits. A rolling window over stories
+rather than days is the one that shows a learning curve if there is one,
+because it holds the denominator fixed.
+
+### Read the stores read-only, always
+
+The helpers resolve `.ergane/` first and honor the legacy `.factory/` name. Use
+`--runtime-root` for a temporary store. This is the live store in normal use. A
+skill that reports on the factory must not be a skill that writes to it.
+
+### LOC has no network bootstrap
+
+`scripts/loc.py` uses a stable local `cloc` executable or reports the
+capability unavailable. It does not fetch executable code from a remote branch.
+Its scratch output lives in a run-unique temporary directory.
+
+## What to conclude, not just what to print
+
+**Pair the rework trend with the findings ledger.** Rework rate is the outcome
+metric for the whole detect-and-promote loop; `ergane findings list` is the
+input side. Report the current rework trend beside the current findings trend.
+That pairing is the report's actual finding; the tables are supporting evidence.
+
+**Separate growth-phase artifacts from structural ones.** Additive commit
+ratio and a findings backlog that outruns resolution can be artifacts of a
+young repository. What does not correct itself is anything that compounds with
+dispatch volume: test-code authorship, gate count as Goodhart surface, and
+unknown quantities silently collapsed to zero. If asked to editorialise, sort
+the criticisms by that axis rather than by severity.
+
+**A flat trend is a finding, not a null result.** Name the period and the
+denominator, then say plainly when there is no improvement.
+
+## Baseline
+
+`reference/baseline-2026-08-19.md` holds the full numbers as measured on
+2026-08-19. It is a historical snapshot, not the default report. Re-measure
+rather than quoting it — but do report which way a number moved, and by how
+much.

ergane_cli-0.6.0/.agents/skills/build-metrics/reference/baseline-2026-08-19.md

@@ -0,0 +1,118 @@
+# Baseline — 2026-08-19
+
+Measured on `ergane-buildout` at `8206721`. Re-measure rather than quoting
+these; they are here so a later run can say which way a number moved.
+
+## Size
+
+842 git-tracked files, **200,990 lines of code**. Net of the ten machine-recorded
+Temporal replay histories under `tests/fixtures/replay-032/` (59,630 lines),
+authored total is **141,360**.
+
+| Language | Files | Code | Blank | Comment |
+| --- | ---: | ---: | ---: | ---: |
+| Python | 269 | 80,025 | 25,661 | 36,598 |
+| JSON | 95 | 64,108 | 0 | 0 |
+| Markdown | 387 | 54,386 | 12,623 | 135 |
+| Bourne Shell | 18 | 1,387 | 211 | 359 |
+| YAML | 59 | 534 | 46 | 265 |
+| Text / SQL / TOML / JS | 14 | 550 | 92 | 151 |
+
+| Module | Files | Code | % |
+| --- | ---: | ---: | ---: |
+| `tests/` | 267 | 117,045 | 58.2% |
+| `specs/` | 311 | 48,428 | 24.1% |
+| `factory/` (production) | 104 | 25,121 | 12.5% |
+| `.agents/skills/` | 107 | 3,192 | 1.6% |
+| `.claude/skills/` | 12 | 2,220 | 1.1% |
+| `docs/` | 6 | 2,154 | 1.1% |
+| `.specify/` | 19 | 1,603 | 0.8% |
+| repo root | 9 | 955 | 0.5% |
+| `scripts/` + `ralph/` | 4 | 166 | 0.1% |
+| `.github/` | 3 | 106 | 0.1% |
+
+Largest production packages: `workgraph` 5,415 · `cli` 5,350 · `verify` 3,429 ·
+`activities` 1,868 · `mergequeue` 1,602 · `controlplane` 1,474.
+
+Ratios: test:production Python **2.19 : 1** · comment density in `factory/`
+**54%** · prose:code **0.68 : 1**.
+
+## Commit size
+
+404 non-merge commits, 3 merge commits.
+
+| Cut | n | Mean | Median | SD | Median files |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| Raw | 404 | 928 | 284 | 5,147 | 3 |
+| **Tukey 1.5×IQR** | 380 | **359** | 254 | 374 | 3 |
+| 5% trimmed both tails | 364 | 393 | 284 | 396 | 3 |
+| 10% trimmed both tails | 324 | 354 | 284 | 318 | 3 |
+
+24 commits dropped, all high-side; the lower fence was −847.
+
+| Group (trimmed) | n | Mean | Median | Median files | ins:del |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| Factory node landings | 143 | 690 | 594 | 5 | 23:1 |
+| Operator commits | 235 | 172 | 67 | 2 | 10:1 |
+
+The three commits that eat the raw mean: `aebcb288` (60,186), `e915296e`
+(59,751, the initial 350-file import), `a10bea88` (59,640, the replay capture).
+
+Churn by path class: specs 32.6% · tests 29.5% · fixtures 16.9% ·
+production 16.5% · docs 3.1% · other 1.5%.
+
+Delete ratio by revisit count (Python under `factory/` + `tests/`):
+
+| Touches | Files | Ins | Del | ins:del |
+| --- | ---: | ---: | ---: | ---: |
+| 1 (never revisited) | 116 | 31,292 | 0 | ∞ |
+| 2–3 | 77 | 36,426 | 717 | 50.8:1 |
+| 4–6 | 40 | 21,606 | 775 | 27.9:1 |
+| 7–12 | 31 | 30,921 | 1,560 | 19.8:1 |
+| **13+** | 16 | 27,252 | 2,281 | **11.9:1** |
+
+## Rework
+
+Store window 2026-08-06 → 2026-08-20. All verification rows were form `PHASE`.
+
+- **Dispatch rework: 43 / 117 = 36.8%** — the headline.
+- **Verification rework: 27 / 116 = 23.3%** — the narrower "gates said no" figure.
+- Mean attempts per story **1.69**.
+
+| Landed on | Stories | % |
+| --- | ---: | ---: |
+| attempt 1 | 89 | 76.7% |
+| attempt 2 | 14 | 12.1% |
+| attempt 3 | 8 | 6.9% |
+| never passed | 5 | 4.3% |
+
+Terminations across 363 usage rows: `completed` 341 (93.9%), `agent_error` 16,
+`timeout` 3, `question` 2, `killed` 1. Personas: implementer 183, judge 164,
+debugger 16.
+
+### Trend — flat
+
+| Week of | Stories | Verification rework | Dispatch rework |
+| --- | ---: | ---: | ---: |
+| 2026-08-03 | 32 | 15.6% | 34.4% |
+| 2026-08-10 | 42 | 26.2% | 40.5% |
+| 2026-08-17 | 42/43 | 26.2% | 34.9% |
+
+Rolling 20-story window oscillated between 5% and 45% with no direction. Three
+weeks and 116 stories in, first-attempt success is not improving.
+
+### Coverage at the time
+
+Ledger held 117 stories; git showed 148 distinct story landings; **79%
+coverage**. The 45 landed-but-unmeasured stories clustered on
+`033-ergane-install`, `034-ergane-init`, `040-manifest-rename`,
+`041-escalation-workflow` — lost when an agent ran `rm -rf .factory` on
+2026-08-14 and the restic restore came from that day's 03:06Z snapshot. 14
+ledger stories had never landed (`032`, `061`, `070`, `071`, and older killed
+work).
+
+## Ledger state, for pairing with the trend
+
+242 findings: 204 open, 34 resolved, 2 promoted, 2 regressed. `agent-worktree-boundary`
+appeared under 37 distinct per-story keys — one auto-generated detector firing
+per story, not 37 independent observations.

ergane_cli-0.6.0/.agents/skills/build-metrics/reference/current-baseline.md

@@ -0,0 +1 @@
+baseline-2026-08-19.md

ergane_cli-0.6.0/.agents/skills/build-metrics/scripts/commit_sizes.py

@@ -0,0 +1,166 @@
+#!/usr/bin/env python3
+"""Commit-size distribution, outlier-trimmed, plus the growth-adjusted delete ratio.
+
+Two things this exists to stop you from reporting:
+
+  1. The raw mean. Three commits carry ~48% of this repo's churn, so the raw
+     mean describes those three commits and nothing else. Trimmed is the number.
+  2. The repo-wide insertion:deletion ratio. It measures how young the tree is,
+     not whether anyone deletes code - you cannot delete from a file nobody
+     revisited. The by-revisit-count table is the honest version.
+
+usage: commit_sizes.py [repo_path]
+"""
+import collections
+import datetime
+import os
+import re
+import statistics
+import subprocess
+import sys
+
+SEP = "\x01C\x01"
+NODE = re.compile(r"^\d{3}-[a-z0-9-]+/us\d+")
+
+
+def commits():
+    out = subprocess.run(
+        [
+            "git", "log", "--no-merges", "--numstat",
+            "--format=" + SEP + "%H%x02%ad%x02%s", "--date=short",
+        ],
+        capture_output=True, text=True,
+    ).stdout
+    got, cur = [], None
+    for line in out.splitlines():
+        if line.startswith(SEP):
+            if cur:
+                got.append(cur)
+            h, ad, subj = line[len(SEP):].split("\x02")
+            cur = {"h": h[:8], "day": ad, "subj": subj, "ins": 0, "del": 0, "files": 0, "paths": []}
+            continue
+        p = line.split("\t")
+        if cur is None or len(p) != 3 or p[0] == "-":
+            continue  # blank line or binary file
+        cur["ins"] += int(p[0])
+        cur["del"] += int(p[1])
+        cur["files"] += 1
+        cur["paths"].append((p[2], int(p[0]), int(p[1])))
+    if cur:
+        got.append(cur)
+    for c in got:
+        c["churn"] = c["ins"] + c["del"]
+    return got
+
+
+def klass(path):
+    if path.startswith("factory/"):
+        return "production"
+    if path.startswith("tests/fixtures/"):
+        return "fixtures"
+    if path.startswith("tests/"):
+        return "tests"
+    if path.startswith("specs/"):
+        return "specs"
+    if path.startswith("docs/") or path.endswith(".md"):
+        return "docs"
+    return "other"
+
+
+def stats(label, cs):
+    if not cs:
+        return
+    ch = sorted(c["churn"] for c in cs)
+    f = [c["files"] for c in cs]
+    i, d = sum(c["ins"] for c in cs), sum(c["del"] for c in cs)
+    print(
+        f"  {label:<34}n={len(ch):>4}  mean {statistics.mean(ch):>6.0f}  "
+        f"median {statistics.median(ch):>5.0f}  sd {statistics.pstdev(ch):>6.0f}  "
+        f"files med {statistics.median(f):>3.0f}  {i / max(d, 1):>5.1f}:1"
+    )
+
+
+def main(repo):
+    os.chdir(repo)
+    C = commits()
+    ch = sorted(c["churn"] for c in C)
+    n = len(ch)
+    qs = statistics.quantiles(ch, n=4, method="inclusive")
+    q1, q3 = qs[0], qs[2]
+    iqr = q3 - q1
+    lo, hi = q1 - 1.5 * iqr, q3 + 1.5 * iqr
+
+    print(f"non-merge commits: {n}   min {ch[0]}  Q1 {q1:.0f}  median {statistics.median(ch):.0f}"
+          f"  Q3 {q3:.0f}  max {ch[-1]}")
+    print(f"Tukey fences [{lo:.0f}, {hi:.0f}]  -- note the lower fence is normally negative here,")
+    print("so nothing trims from the low end and 'outliers on either side' does not apply.")
+
+    print("\n=== COMMIT SIZE (churn = insertions + deletions) ===")
+    stats("raw (all)", C)
+    inf = [c for c in C if lo <= c["churn"] <= hi]
+    stats("Tukey 1.5*IQR  <- report this", inf)
+    for pct in (5, 10):
+        k = int(n * pct / 100)
+        stats(f"{pct}% trimmed both tails", sorted(C, key=lambda c: c["churn"])[k : n - k])
+    print(f"  dropped by Tukey: {sum(1 for c in C if c['churn'] > hi)} high, "
+          f"{sum(1 for c in C if c['churn'] < lo)} low")
+
+    print("\n=== FACTORY NODE LANDINGS vs OPERATOR COMMITS (trimmed per-group) ===")
+    for label, sub in (
+        ("node landings", [c for c in C if NODE.match(c["subj"])]),
+        ("operator", [c for c in C if not NODE.match(c["subj"])]),
+    ):
+        s = sorted(c["churn"] for c in sub)
+        sq = statistics.quantiles(s, n=4, method="inclusive")
+        f_lo, f_hi = sq[0] - 1.5 * (sq[2] - sq[0]), sq[2] + 1.5 * (sq[2] - sq[0])
+        stats(label + " (trimmed)", [c for c in sub if f_lo <= c["churn"] <= f_hi])
+
+    print("\n=== LARGEST COMMITS (the ones that eat the raw mean) ===")
+    for c in sorted(C, key=lambda c: -c["churn"])[:8]:
+        print(f"  {c['day']}  {c['h']}  {c['churn']:>7} churn  {c['files']:>4}f  {c['subj'][:58]}")
+
+    print("\n=== CHURN BY PATH CLASS ===")
+    tot = collections.Counter()
+    for c in C:
+        for p, a, d in c["paths"]:
+            tot[klass(p)] += a + d
+    s = sum(tot.values())
+    for k, v in tot.most_common():
+        print(f"  {k:<12}{v:>10,}  {100 * v / s:>5.1f}%")
+
+    print("\n=== DELETE RATIO BY REVISIT COUNT (the growth-adjusted version) ===")
+    print("Repo-wide ins:del measures youth. This measures discipline. Quote the last row.")
+    live = set(subprocess.run(["git", "ls-files"], capture_output=True, text=True).stdout.split())
+    touch, ins, dele = collections.Counter(), collections.Counter(), collections.Counter()
+    for c in C:
+        for p, a, d in c["paths"]:
+            if "=>" in p:
+                continue  # rename entry; path is unparseable
+            touch[p] += 1
+            ins[p] += a
+            dele[p] += d
+
+    def bucket(t):
+        return ("1 (never revisited)" if t == 1 else "2-3" if t <= 3
+                else "4-6" if t <= 6 else "7-12" if t <= 12 else "13+")
+
+    b = collections.defaultdict(lambda: [0, 0, 0])
+    for p, t in touch.items():
+        if p not in live or not p.endswith(".py"):
+            continue
+        if not (p.startswith("factory/") or p.startswith("tests/")):
+            continue
+        k = bucket(t)
+        b[k][0] += 1
+        b[k][1] += ins[p]
+        b[k][2] += dele[p]
+    print(f"  {'touches':<22}{'files':>7}{'ins':>10}{'del':>9}{'ins:del':>10}")
+    for k in ["1 (never revisited)", "2-3", "4-6", "7-12", "13+"]:
+        if k not in b:
+            continue
+        f, i, d = b[k]
+        print(f"  {k:<22}{f:>7}{i:>10,}{d:>9,}{i / max(d, 1):>9.1f}:1")
+
+
+if __name__ == "__main__":
+    main(sys.argv[1] if len(sys.argv) > 1 else ".")