@tyroneross/build-loop 0.35.0 → 0.36.0

package/plugin-artifacts/codex/references/backlog-system.md

@@ -0,0 +1,285 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Backlog System — host-agnostic, multi-repo deferred-work tracker
+
+A backlog is the durable list of wanted-but-not-now work for a repo: deferred
+debt, blocked infra, known fixes, pending decisions. This system makes that list
+**host-neutral** (any coding agent — Claude, Codex, or other — reads and writes
+it the same way), **filesystem-first** (grep + frontmatter, no DB/vector/graph),
+and **aggregatable** across all of one user's repos via their personal memory.
+
+## Why it is shaped this way
+
+Five research-grounded principles drive the design (from the memory-architecture
+guide; Letta filesystem-memory benchmark; "don't over-engineer"):
+
+1. **Canonical truth vs derived index.** The items in `items/` are the truth.
+   `INDEX.md` is a *generated, rebuildable* view — never hand-edited.
+2. **Metadata-rich items.** Each item carries provenance, evidence,
+   supersession links, and a TTL (`review_by`) so it can be audited and aged.
+3. **Filesystem-first retrieval.** Reading = `cat BACKLOG.md` → `INDEX.md`, then
+   `grep` over `items/*.md` frontmatter. No index server, no embeddings.
+4. **Lifecycle ops.** Formation (`new`) → consolidation (`sync` archives
+   done/dropped, flags stale) → retrieval (`list`, grep) → forgetting
+   (archive, never delete).
+5. **Governance Level 3.** Every write is logged, timestamped, attributable —
+   git history + `created`/`updated` stamps + archive-not-delete provide it.
+
+## Two scopes (do not conflate)
+
+| Scope | Path | Lifetime | Shared? |
+|---|---|---|---|
+| **Per-repo backlog** | `<repo>/.build-loop/backlog/` | Travels with the repo; committed | Team-shareable (in the repo) |
+| **Personal memory mirror** | `build-loop-memory/projects/<slug>/backlog/` | Per-user, aggregated across ALL the user's repos | Private to the user |
+
+The sync is **one-way**: per-repo backlog → personal memory. The per-repo store
+is the source of truth; the memory mirror is a cross-repo read view for the user
+who downloaded build-loop.
+
+## Structure
+
+```
+<repo>/
+├── BACKLOG.md                      # repo-root pointer → .build-loop/backlog/INDEX.md
+└── .build-loop/backlog/
+    ├── README.md                   # what this dir is + how to use it
+    ├── .gitattributes              # INDEX.md merge=ours (resolve by regeneration)
+    ├── INDEX.md                    # DERIVED — regenerated by `sync`; do not edit
+    ├── items/<ID>.md               # CANONICAL truth — one file per item
+    └── archive/<ID>.md             # done/dropped items (never deleted)
+```
+
+`<ID>` = `<PROJSLUG>-<AREA>-<token>` — e.g. `ATOM-SEARCH-mt3k9p7q`. The prefix is
+derived from the repo basename; the **token** is a coordination-free,
+collision-resistant suffix: 8 Crockford-base32 digits of millisecond time
+(so `ls items/` still roughly sorts by creation) followed by 5 digits of
+`os.urandom` entropy (so the ID is unique across agents, machines, branches, and
+clones with **no shared counter**). Lowercase throughout.
+
+**Why not the old sequential `-NNN`?** A per-area zero-padded counter is a
+single-writer assumption. Two agents in independent worktrees/clones (Claude on
+branch A, Codex on branch B) each read their OWN highest-NNN and both minted the
+SAME `...-001/002/003` for DIFFERENT items — on `git merge` the identical
+filenames/IDs collided or silently lost an item. The token removes the shared
+counter entirely. The readability trade-off (IDs gain a ~13-char token suffix
+instead of `-001`) is paid back by `INDEX.md`, which is the human-ordered
+navigation view; the items themselves are addressed by token.
+
+**Legacy `-NNN` items still read.** Items minted before this change (and any
+hand-authored `-NNN`) remain valid: the ID-shape regex accepts BOTH a token
+suffix and a legacy `\d{3,}` suffix, and no parser assumes a numeric tail.
+Existing IDs are never rewritten — only NEW items get tokens.
+
+## Item schema (frontmatter on every `items/<ID>.md`)
+
+```yaml
+id: ATOM-SEARCH-001
+title: <one line>
+status: open            # open | in-progress | blocked | deferred | done | dropped
+priority: P2            # P0..P3
+type: debt              # feature | fix | debt | infra | decision | cleanup | research
+area: search            # free-ish tag; the grep + filter routing key
+entities: [pg_trgm, keyword-leg]
+gated: db-migration     # none | prod-deploy | db-migration | infra | product-decision
+provenance: { source: followup, ref: <path/commit/PR#/chat-date> }
+evidence: [<commit/PR/retro/followup paths>]
+supersedes: null
+superseded_by: null
+created: 2026-06-16
+updated: 2026-06-16
+review_by: 2026-07-16   # TTL — surfaced by `sync` when passed
+owner: unassigned
+```
+
+Body sections: `## Context`, `## Acceptance`, `## Notes`.
+
+Dates are caller-stamped (`--today YYYY-MM-DD` or the `BACKLOG_TODAY` env var,
+falling back to the system clock) so the tool runs in harnesses where the clock
+is not callable.
+
+## Lifecycle / sync contract
+
+`scripts/backlog.py sync --repo <path>` does three things, in order:
+
+1. **Consolidate.** Move every `status: done` / `status: dropped` item from
+   `items/` to `archive/`. Never deletes. Flags items whose `review_by` has
+   passed as stale. Warns about `.build-loop/{followup,issues,proposals}` files
+   not yet referenced by any item's `evidence`/`provenance.ref` (scattered work
+   not yet triaged into the backlog).
+2. **Regenerate INDEX.** Rebuild `INDEX.md` deterministically from the remaining
+   items' frontmatter — grouped status → area → priority, with a compact table,
+   a summary (active count, open P0/P1, stale count, gated count), and a stale
+   call-out. For a FIXED item set re-rendering is **byte-identical** (no
+   wall-clock in the body), so `sync` is safe to re-run and diff-clean. The INDEX
+   write is atomic (temp file + `os.replace`), so a concurrent `sync` by two
+   agents never leaves a torn file for a reader. **Duplicate-ID guard
+   (defense in depth):** if two items ever share an `id` (a bad merge, a
+   hand-edit), `sync` surfaces them LOUDLY in a `## ⚠ Duplicate IDs` section
+   (id, count, all titles, all paths) instead of silently rendering one — so a
+   collision that did happen is visible.
+3. **Mirror to personal memory.** Copy active item files (+ a mirror INDEX) into
+   `build-loop-memory/projects/<slug>/backlog/`. Each mirror file is written
+   atomically (temp file + `os.replace`), so a parallel session never observes a
+   half-written file; last-writer-wins (the per-repo backlog is the truth).
+   Best-effort: if the memory root is absent or unwritable, sync still succeeds
+   and reports `mirror.skipped`.
+
+### INDEX.md merge handling
+
+`INDEX.md` is fully derived, so two agents that both regenerate it WILL conflict
+on `git merge`. The scaffold (via `adopt` AND any backlog materialisation by
+`new`/`sync`) drops a `.build-loop/backlog/.gitattributes` with:
+
+```gitattributes
+INDEX.md merge=ours
+```
+
+so git resolves the conflict by keeping one side instead of inserting conflict
+markers. **On an `INDEX.md` conflict, run `backlog.py sync` — `items/` is the
+truth and the INDEX regenerates deterministically.** Item files in `items/`
+don't conflict once IDs are unique (token suffix → separate paths), so both
+branches' new items survive a merge.
+
+## How ANY agent uses it (host-neutral)
+
+**Read** (no tools required — just the filesystem):
+1. `cat <repo>/BACKLOG.md` → follow the pointer to `INDEX.md`.
+2. `cat <repo>/.build-loop/backlog/INDEX.md` for the grouped view.
+3. `grep -l 'area: search' <repo>/.build-loop/backlog/items/*.md` to find items
+   by any frontmatter field; read the matching item bodies.
+
+**Write** (via the pure-stdlib CLI — works under bare `python3`, no host SDK):
+```bash
+# create
+python3 scripts/backlog.py new --repo <path> --area search --type debt \
+    --title "pg_trgm for keyword leg" --priority P1 --gated db-migration \
+    --provenance-source followup --provenance-ref .build-loop/followup/x.md \
+    --today 2026-06-16
+# edit the item body / frontmatter by hand in items/<ID>.md
+# then regenerate + mirror
+python3 scripts/backlog.py sync --repo <path> --today 2026-06-16
+# read
+python3 scripts/backlog.py list --repo <path> --status open
+```
+
+The CLI emits structured JSON (machine-readable) on `new`/`sync`; `list` prints
+a text table (or JSON with `--json`). The host LLM reasons over the structured
+data + the convention — it never calls a vendor API.
+
+## Relationship to existing build-loop surfaces
+
+- `.build-loop/issues/` — current-run bugs (short-lived). A persistent issue is
+  triaged INTO the backlog (`new`), then the issue file is referenced as
+  `evidence`/`provenance.ref` so `sync` stops warning about it.
+- `.build-loop/followup/` — iterate-cap overflow. Same triage path.
+- `templates/backlog-item.md` + `build-loop-memory/projects/<slug>/backlog.md`
+  (the legacy single-table durable backlog) remain valid for build-loop's own
+  self-work tracking; this per-item system is the general, multi-repo surface
+  and writes its mirror to the `backlog/` *subdir* (no clobber of `backlog.md`).
+
+## Phase 1 Assess integration
+
+`scripts/context_bootstrap.py` surfaces a compact backlog line at Phase 1 Assess
+when `.build-loop/backlog/INDEX.md` exists: open P0/P1 count, past-`review_by`
+stale count, and gated count. Cheap (reads the generated INDEX summary only) and
+non-fatal when the file is absent.
+
+It also surfaces a one-time **discoverability nudge** (`backlog_discoverability`)
+when there's something to act on:
+
+- **Adoptable** — the repo has scattered work in `.build-loop/{followup,issues}`
+  but no `INDEX.md` yet → *"Backlog available — run `backlog.py adopt
+  --dry-run --repo .`"*.
+- **Won't travel** — `.build-loop/backlog/` exists but is gitignored → *"Backlog
+  won't travel — run `adopt --apply` to fix `.gitignore`"*.
+
+Both are silent when there's nothing to surface, and neither ever raises.
+
+## Download & upgrade safety
+
+This is the contract that makes the backlog safe to **download** with a fresh
+build-loop and **upgrade** in place over an existing one. The guiding rule:
+*every adoption/upgrade step is additive and reversible; nothing the user
+already had is moved, deleted, or rewritten in a lossy way.*
+
+**1. Additive / never-destructive.** Adoption never touches the existing work
+surfaces. `.build-loop/followup/`, `.build-loop/issues/`, `.build-loop/proposals/`,
+and the personal `build-loop-memory` store are read-only inputs to `adopt` — an
+imported item *links* to its source (`provenance.ref` + `evidence[]` +
+`imported_from`); the source file stays exactly where it was as the inbox /
+provenance record. `sync` likewise only ever archives (`done`/`dropped` →
+`archive/`) and regenerates the derived `INDEX.md`; it never deletes a live item.
+
+**2. Lazy / opt-in scaffolding.** A repo gets backlog dirs and pointer files
+*only* when the user runs `adopt` (or `new`). A downloaded build-loop does not
+litter every repo with an empty `backlog/` on first run — the structure
+materialises on demand. `adopt --dry-run` (the default) reports exactly what it
+*would* create without writing anything, so the user previews before opting in.
+
+**3. The `.gitignore` dependency — and how `adopt` fixes it.** `.build-loop/` is
+gitignored by default (confirmed in both `build-loop` and `sample-app`). That is
+correct for transient run state — but it means the backlog would **not commit
+and therefore would not travel** with the repo (no team-sharing, lost on a fresh
+clone). `adopt` detects this by inspecting `.gitignore` (pure text, no git call)
+and, on `--apply`, appends un-ignore rules so the durable backlog escapes the
+broad ignore:
+
+```gitignore
+# build-loop backlog (added by `backlog.py adopt` — keep so the backlog travels)
+!.build-loop/backlog/
+!.build-loop/backlog/**
+!BACKLOG.md
+```
+
+It reports this loudly (`gitignore.was_ignored: true`, `added: [...]`) and is
+idempotent — re-running never appends the block twice. If `.build-loop/` is not
+ignored, `adopt` leaves `.gitignore` untouched.
+
+**4. Idempotent, dry-run-first migration.** `adopt` defaults to a read-only
+dry-run; `--apply` executes. Re-running `--apply` is a no-op: each imported item
+records `imported_from: <source path>`, and a re-run reads that field across
+`items/` **and** `archive/` and skips any source already imported. No duplicate
+items, no churned `.gitignore`. Verified contract: `adopt --apply` twice → the
+second run's diff (items + `.gitignore`) is empty.
+
+**5. Schema-version tolerance (forward/back compatible).** Every item carries
+`schema_version` (current = `1`). The reader (`read_item`) is deliberately
+tolerant: it **defaults missing known fields** and **preserves unknown fields**.
+An item written by an *older* build-loop (no `schema_version`) reads back with
+defaults filled in; an item written by a *newer* build-loop (carrying fields
+this version doesn't know) reads back without error and with those fields intact.
+So a backlog written by one build-loop version always reads on another — neither
+a downgrade nor an upgrade corrupts or rejects it. Bump `SCHEMA_VERSION` only for
+a contract change a reader must actively know about; the tolerant reader absorbs
+purely-additive field changes without a bump.
+
+**6. `build-loop-memory` is the per-user cross-repo long-term store.** The
+per-repo backlog travels *with the repo* (committed, team-shareable). `sync`
+additionally mirrors active items one-way into
+`build-loop-memory/projects/<slug>/backlog/` — the user's private, cross-repo
+aggregate view. The mirror writes to the `backlog/` **subdir**, so it never
+collides with the legacy single-table `backlog.md`, with `lessons/`, or with
+`decisions/` in that project's memory lane. The mirror is additive: its only
+delete path is pruning orphaned item mirrors (ID-shaped stems whose source item
+was removed), and it never touches a hand-dropped note. If the memory root is
+absent or unwritable, `sync` still succeeds and reports `mirror.skipped`.
+
+**Concurrency note (multi-agent) — two distinct collision classes.**
+
+1. **Distributed (cross-worktree/clone/machine).** Independent checkouts share no
+   filesystem and no counter, so IDs must be collision-free *with zero
+   coordination*. The token suffix (time-ordered + `os.urandom`) provides exactly
+   that: two agents in separate worktrees minting in the same area produce
+   DISJOINT ID sets, so a `git merge` of their `items/` trees lands every item
+   with nothing clobbered. This is the bug the token scheme fixes — the retired
+   sequential counter collided here.
+2. **Same-filesystem concurrent processes.** N `new`/`adopt` processes on ONE
+   filesystem still race on the create. That is handled (kept from the prior fix)
+   by the `O_EXCL` atomic create: exactly one process can create a given path;
+   the rest re-mint a fresh token and retry, bounded. So 8 parallel `new` calls
+   in one area yield 8 distinct files, zero loss.
+
+Together these make the backlog safe as a shared multi-agent work surface across
+both separate checkouts AND concurrent processes — not just a single-writer file.
+The INDEX and memory-mirror writes are atomic (temp + `os.replace`) so a reader
+never sees a torn derived file.

package/plugin-artifacts/codex/references/capability-routing.md

@@ -25,6 +25,55 @@ Phase 1 runs `node ${CLAUDE_PLUGIN_ROOT}/skills/build-loop/detect-plugins.mjs` a
 | Modular systems pack | Phases 1-4 | Read `references/modular-systems-pack.md`; partition files/tasks MECE; prefer modular scalable boundaries unless an exception is documented |
 | Codex subagent adapter | Phase 3 (Execute, Codex only) | Read `references/codex-subagents.md`; use `templates/codex-worker-prompt.md` for authorized Codex workers |
 
+### Spec/Plan author router (intent-driven, ordered)
+
+This router selects the single skill that AUTHORS the plan/spec/task graph for this run. It is a recommendation that DRIVES Phase 2 — recorded into `state.json.intent.spec_router`, consumed by Phase 2 Plan, never a hard block.
+
+**Scope — author selection only.** `prd-bridge` is NOT in this router. It is mandatory in Phase 1 step 10 and only *consumes* an existing PRD (`docs/prd-*.md` → `state.json.prd`); it never authors. PRD-context is orthogonal to author selection — keep them separate.
+
+**Governing rule**: select on intent + goal + context, not on a trigger-word match. A skill's word-overlap activation is not enough to call it (this is why `prd-builder` over-fired during build-loop runs). The router is the intent-side selection; it pairs with the activation-side guard (prd-builder's negative-trigger scope, which excludes in-flight changes and active build-loop runs).
+
+Signals (all set during Phase 1 Assess):
+
+- `run_active` — is a build-loop run active? (`true` for any `/build-loop:run` or build-orchestrator dispatch.)
+- `plan_status` — `no-plan` | `plan-valid`, from the Phase 2 plan-exists gate (`.build-loop/plan.md` absent/empty + last `plan-verify` result).
+- `intent_kind` — `PRD-author` | `build-plan` | `task-graph` | `none`, the LLM's read of what this run needs authored.
+- `code_exists` — does the repo have substantive existing code? (Assess maps architecture: new/empty repo → false, existing repo → true.)
+- `goal_scope` — `new-app` | `existing-app-change` | `in-build-task-breakdown`.
+
+The rows are ORDERED — first match wins, so exactly one author is selected and no case matches two. The final default row makes the table exhaustive: every `(run_active, plan_status, intent_kind)` combination matches exactly one row, so nothing falls through.
+
+| # | Match condition (first true wins) | route_type / action | Author selected | Why |
+|---|---|---|---|---|
+| 1 | `intent_kind == none` — nothing to author (Q&A, status, trivial, read-only, or advisory-context-only) | `noop` (call nothing) | — (`skill: null`) | no plan/spec/task graph needed |
+| 2 | `run_active == false` AND greenfield PRD authoring is explicitly intended (new app with no code, OR `/start-prd` requested for a project) | `call` (or `recommend` outside an interactive session) | `prd-builder` | greenfield authoring + interactive intake; honors prd-builder's negative trigger — never fires inside an active run |
+| 3 | `run_active == true` AND `plan_status == no-plan` | `call` | `build-loop:spec-writing` | author the in-build, non-interactive, gated plan for the orchestrator |
+| 4 | `run_active == true` AND `plan_status == plan-valid` | `call` | `build-loop:writing-plans` (external) | turn the accepted plan into the task / dependency graph |
+| 5 (default) | else (no earlier row matched) — the canonical case is `run_active == false` AND `intent_kind` is `build-plan` or `task-graph`: a direct, out-of-run invocation of plan authoring on an existing repo | `recommend` | `build-loop:spec-writing` | recommend, not auto-call: there is no active run to drive, so surface the author for the lead to run if it chooses |
+
+The order is the contract: row 1 short-circuits before any author runs; row 2 is the only PRD author and is fenced off from active runs; rows 3 and 4 are mutually exclusive on `plan_status`; row 5 is the exhaustive `else` default that catches every remaining combination — its canonical case is an out-of-run `build-plan`/`task-graph` intent, but as the final row it also absorbs any residual (e.g. an out-of-run non-greenfield `PRD-author`) so no signal combination ever falls through. The table extends to any future author skill — add a row at the right precedence above the default, key it on the same signals, and the system still selects exactly one and records why.
+
+`build-loop:writing-plans` (row 4) is the **external** `writing-plans` skill from the superpowers plugin — it is not vendored in this repo (`skills/writing-plans/SKILL.md` does not exist here). When it is absent, fall back to the inline "write a structured plan directly" path in the §"Core loop skills/assets" table above.
+
+> Future refinement (do not over-build now): for monorepos, a `target_code_exists` signal (does the *target sub-path* already have code, vs the repo as a whole) would refine row 2's greenfield test. Out of scope until a monorepo case demands it.
+
+**Phase 1 record (the consumable contract)**. Phase 1 writes the matched decision into `state.json.intent.spec_router` so a Codex lead (no `Skill()` auto-activation) can consume it deterministically:
+
+```json
+{
+  "route_type": "author",
+  "action": "call" | "recommend" | "noop",
+  "skill": "build-loop:spec-writing" | "build-loop:writing-plans" | "prd-builder" | null,
+  "fallback": "<fallbacks.md section or inline guidance> | null",
+  "matched_row": 1 | 2 | 3 | 4 | 5,
+  "signals": { "run_active": true, "plan_status": "no-plan", "intent_kind": "build-plan", "code_exists": true, "goal_scope": "existing-app-change" }
+}
+```
+
+`action: "noop"` → `skill: null`, Phase 2 authors nothing from the router (terminal). `action: "recommend"` → `skill` carries the recommended author name (so the lead knows what to run if it chooses); Phase 2 surfaces the recommendation in the report and does NOT auto-call. `action: "call"` → `skill` is non-null and Phase 2 calls it. The three actions are distinct: `call` auto-invokes, `recommend` surfaces-only, `noop` skips.
+
+**Phase 2 read (the load-bearing wire)**. Phase 2 Plan READS `state.json.intent.spec_router` and acts on `action`/`skill` — it does NOT independently re-decide which author to call. See `references/phase-2-plan.md` step 0.
+
 ### Phase quick reference
 
 | # | Phase | Purpose | Sub-steps / key actions |

package/plugin-artifacts/codex/references/coordination-rules.md

@@ -51,6 +51,8 @@ post(
 
 **Channel scope (worktree- and clone-independent):** resolve the channel through `scripts/rally_point/discovery_bridge.resolve(workdir)`. Native `agent-rally-point` discovery returns the canonical shared channel (currently `~/.agent-rally-point/apps/<repo-id>/`). The embedded build-loop fallback also defaults to `~/.agent-rally-point/apps/<slug>/`, where `slug` comes from `git rev-parse --git-common-dir` via `scripts/rally_point/channel_paths.app_slug(cwd)`. The main checkout, every worktree, and every clone of the same canonical repo share ONE channel. Different canonical repos get different channel directories (cross-repo isolation).
 
+**Rally's REAL CLI surface (the only commands build-loop shells out to).** Rally exposes `enter`, `say <kind>`, `whoami`, `room`, `next`, `recent`, `stop <session|name|tool>`, `sessions [--reap]`, `migrate-legacy`, `mission`, `version`, and `check`. It has NO `setup`, NO `post`, NO `start`, and NO `replay` — those were anticipated but never shipped, and a discovery tier that gated on them was dead code (removed). A write goes out as `rally say <kind> --json …` (build-loop's `post()` helper translates to this); identity/channel info comes from `rally whoami --json` (`repo_root`/`repo_id`/`worktree`/`build_id`/`cwd`), NOT a `setup` probe. The surface-acceptance check (`discovery_bridge._rally_binary_supports_required_surface`) is pinned to a real rally binary's `--help` by `scripts/test_discovery_bridge.py::RequiredSurfacePinnedToRealRallyTests`, so it can never silently drift back to a phantom surface. When adding a rally call, read the binary's real `--help` first; do not assume a command exists.
+
 **Anti-pattern (silent no-op):**
 
 ```python
@@ -77,6 +79,27 @@ Threats this model does NOT cover (out of scope by design): a hostile process ru
 
 ---
 
+## Evidence boundary (Rally is not a verifier)
+
+Rally records are peer-authored coordination metadata. They can tell an agent
+what another agent claimed, handed off, reviewed, blocked, or released, and they
+can point to artifacts worth inspecting. They do not prove the artifact, code,
+package, tag, release, or remote state is correct.
+
+Before making a factual claim about repo or release state, check the authoritative
+surface directly:
+
+- Code and docs: working tree, `git diff`, file contents, and tests.
+- Package/version surface: manifests, package tests, dry-run pack/publish output,
+  and release-surface verifier scripts.
+- Remote release state: GitHub/npm/GitHub Packages API or public pages, not a
+  Rally `release` or `artifact` record.
+
+A Rally `artifact`, `release`, `resolve`, `review_artifact`, or `next` record is
+a routing signal. It may identify what to inspect; it is never the inspection.
+
+---
+
 ## Cheap detection at step boundaries
 
 **Poll `coordination_status.py` BEFORE any step-boundary decision.** Costs ~100 tokens; prevents stale-state recommendations that cost full plan rewrites (~5K tokens).
@@ -150,9 +173,255 @@ any of the above. Memory citation:
 
 **Orphaned-lane absorption:** when a lane assigned to an idle peer is **local and reversible** (commits, doc/agent edits, dead-code or dead-key trims, version bumps, test updates), the live agent **absorbs it** — does the work itself, then records in the report `absorbed <peer>'s idle lane: <what> [<evidence>]`. Do **not** block a release, a finish, or "done" on an idle peer's local lane — that is the same manufactured wait as a turn-length stop (see `skills/build-loop/SKILL.md` §"Keep going until done"). Only surface/hold a lane that is genuinely **peer-exclusive**: needs the other vendor's model (true cross-vendor review), the peer's environment/credentials, or an irreversible action only that peer is authorized to take. Coordination is cooperative, not a dependency that can deadlock the live agent.
 
+## Recency decay & size-scaled lead/ownership auto-reclaim
+
+A single coordination policy governs message aging and stale-claim reclaim,
+mirrored from the canonical Rust implementation (agent-rally-point). Tunables
+live under `coordinationPolicy` in `.build-loop/config.json` (defaults shown):
+
+```json
+{
+  "coordinationPolicy": {
+    "half_life_hours": 48,
+    "archive_floor_weight": 0.05,
+    "reclaim_small_minutes": 30,
+    "reclaim_large_minutes": 120
+  }
+}
+```
+
+- **Recency decay (listing order + archive).** Every coordination change gets a
+  weight `0.5 ** (age_hours / half_life_hours)` (default half-life 48h). The
+  status / recent-changes listing orders fresh-first by weight and EXCLUDES any
+  change whose weight has fallen below the archive floor (default `0.05`, ≈14d).
+  Archived changes are losslessly retrievable with `--include-archived`
+  (`coordination_status.py --include-archived`), which also folds back any
+  physically-rotated `changes.jsonl.<date>` logs. Decay applies only to the
+  historical change stream — never to the live direct-message inbox or to active
+  state. Fails OPEN: a change with a malformed `ts` is treated as fresh.
+- **Size-scaled lead/ownership auto-reclaim.** A lead lease (`rally/lead.json`)
+  whose `lease_until` has passed is auto-reclaimable by the next `claim_lead`.
+  The lease WINDOW scales with the claimed work size: a small (single-file /
+  effort XS·S) claim expires after `reclaim_small_minutes` (default 30m); a
+  large (multi-file / coarse / effort M·L·XL) claim after `reclaim_large_minutes`
+  (default 2h). Pass `work_size`/`effort`/`owns` to `claim_lead`; with NO size
+  signal the lease window stays the historical `renew_every_minutes` cadence
+  (backward-compatible). An auto-reclaim posts a durable `lead-reclaim` record
+  naming who reclaimed, the prior owner, and the reason (`stale-by-timeout`).
+- **Preserved invariants.** Reclaim stays race-safe (the `rally/lead.lock`
+  fcntl lock is untouched) and FAIL-CLOSED: a present incumbent lease whose
+  `lease_until` is unparseable is NEVER auto-reclaimed (we refuse rather than
+  reclaim on a timestamp we cannot trust). An empty seat is still freely
+  claimable.
+- **Policy is Rust-only; the Python math is an in-process helper.** Reclaim and
+  reap DECISIONS are made by the Rust binary (facade in `reaper.py` /
+  `leadership.py`, fail-loud below full capability). `decay.py` survives only as
+  pure in-process math the lead-lease window sizing needs (`recency_weight`,
+  `reclaim_timeout_seconds`, `classify_work_size`); it is NOT a behavioral mirror
+  of `decay.rs` and is no longer double-pinned against a cross-repo golden
+  fixture. The status/recent-changes LISTING still applies the decay weight in
+  Python over build-loop's own change-log so an old on-PATH binary cannot
+  un-decay the listing (pinned by `scripts/test_coordination_decay_invariant.py`);
+  that is a presentation concern, distinct from the now-Rust-only reclaim/reap
+  actuation.
+
+This complements (does not replace) the >10-minute idle absorption rule above:
+idle-absorption handles local reversible lanes a quiet peer left open; the lease
+timeout governs the formal lead/ownership role handover.
+
+## In-room stale-state reaper (actuator) — RUST-ONLY via a fail-loud facade
+
+The sections above define WHEN records become stale. Physically removing them
+(reaping) is **Rust-only**. There is no Python reaper sweep — the prior Python
+parity mirror (presence/claim-index/lead deletion, double-pinned against golden
+fixtures) was RETIRED in the Rust-rally facade migration. A Python process
+deleting coordination records the Rust binary owns is the exact shadow
+implementation that is worse than no coordination.
+
+**Canonical actuator (Rust):** the `rally` binary's reaper (`rally sessions
+--reap`, or `rally doctor --reap-stale` on newer builds). Dry-run by default;
+`--reap`/`--apply` physically removes over-TTL presence, claims, and leads.
+
+**Facade (`scripts/rally_point/reaper.py`).** `reap_channel(channel, workdir,
+apply=…)` resolves coordination capability via `discovery_bridge` and then:
+- **full capability** (a real binary owns the channel — `repo-local-rally-cli`
+  / `fetched-binary` / env-override / path-binary / python-import) → shells
+  `rally sessions --reap` and surfaces the result (`capability_level: full`,
+  `deferred_to_rust: false`).
+- **below full** (degraded-breadcrumb or unavailable) → REFUSES. It reaps
+  nothing and returns a capability-marked report (`deferred_to_rust: true`,
+  `coordination_unavailable: <reason>`). A degraded session must never reap a
+  peer it cannot prove is dead.
+
+CLI: `python3 scripts/rally_point/reaper.py --workdir <path> [--apply] [--json]`.
+
+**Capability field on every coordination envelope.** Every facade return and
+`DiscoveryEnvelope` carries `capability_level` (`full` / `degraded-breadcrumb` /
+`unavailable`) + a `coordination_unavailable` reason. The single source of truth
+is `scripts/rally_point/capability.py`; `FULL_ONLY_OPERATIONS`
+(claim/release/reclaim/lead/reap/liveness/before_write/checkpoint) are permitted
+only at full capability.
+
+**Degraded breadcrumb path (the ONLY thing a sub-full session may write).** When
+no binary is available but the host is supported, a session may write
+capability-marked presence/handoff *breadcrumb* facts so a later full-capability
+peer (or a human) sees it existed. It must NOT — and structurally cannot — claim
+ownership, reclaim, infer liveness, reap, or imply before-write protection.
+
+**Unsupported-host = loud no-coordination.** A host with no fetchable pinned-
+binary asset (Intel macOS, musl/Alpine, exotic arch) resolves to
+`capability_level: unavailable` (`coordination_unavailable: unsupported_host`).
+The facade is a loud no-op there — NEVER a policy mirror.
+
+**Remaining Python guards** (the destructive paths that survive as in-process
+guards, all FAIL-CLOSED): `presence.reap_stale` physically unlinks only at full
+capability; `leadership` reclaim (taking a peer's lease) is full-only, while
+seeding an EMPTY lead seat and self-relinquishing one's OWN seat stay breadcrumb-
+class. The in-process `decay.py` / `liveness.py` are now pure window/weight math
+helpers (lead-lease sizing, adaptive presence window), not behavioral mirrors.
+
+**Codex parity.** A codex session emits the same presence record claude does, via
+the `.codex/hooks.json` `SessionStart` hook that calls `session_probe.py --tool
+codex`, so it ages and decays identically — now enforced by the single Rust
+reaper both tools share, not by a cross-language golden fixture.
+
+**Session-end self-release (primary).** Both tool hooks release the agent's Rally
+file-claims at turn completion (`Stop` event) so peers immediately see the agent's
+absence and the claims do not leak past Stop. The two hosts reach this differently
+because their session models differ:
+
+- **Codex** emits `rally stop codex` (`.codex/hooks.json` Stop). `codex` resolves to
+  Codex's managed `rally-*` tmux session, so that one call both self-kills the
+  session (it can never become a detached orphan) AND releases the session's claims.
+- **Claude Code** is normally NOT a `rally run`-managed session, so `rally stop
+  claude_code` fails (`unknown managed session`). The Claude Stop hook therefore
+  releases claims via the portable primitive instead: `scripts/stop_closeout.py`
+  (`release_my_claims`, called from `hooks/closeout.sh stop`) enumerates this tool's
+  open claims with `rally room --tool claude_code --json` and releases each by event
+  id with `rally say release --tool claude_code --ref <event-id>`. It fires on EVERY
+  Stop (a stopped session is no longer editing), is advisory + fail-open (`command -v
+  rally` guarded; swallows all errors; exit 0 always), and is capped per Stop so a
+  backlog can't make the hook run long. History: before this, the Claude hook
+  released only the run IDENTITY, never the file claims, so `claude_code` auto-claims
+  accreted unbounded (112→127 observed). Added 2026-06-29.
+
+**Reaper = backstop, not primary (NON-DEFAULT).** The reaper that expires abandoned
+claims/presence (`rally sessions --reap`, faced by `scripts/rally_point/reaper.py`)
+is Rust-only and dry-run/manual by default — it is NOT turned on. Self-release above
+is the primary mechanism. The reaper exists ONLY to catch the dead: sessions that
+crash (SIGKILL / 529 / network drop) before their Stop hook fires, so self-release
+never ran. Do not enable it as a default-on sweep; run it deliberately as the
+explicit backstop for crash-orphaned claims.
+
+## Adaptive multi-signal liveness (squad-projection decay + tmux orphan reaper)
+
+Fixed staleness cutoffs are replaced by liveness that ADAPTS to each session's
+planned heartbeat cadence and weighs four signals. The liveness DECISION (reap /
+self-exit) is Rust-only via the facade; `scripts/rally_point/liveness.py` retains
+only the in-process window/verdict MATH the presence squad-projection uses,
+verified by its own inline unit tests (`test_liveness.py`). The cross-repo golden
+fixture `liveness_vectors.json` and its `_provenance.json` drift entry were
+RETIRED in the Rust-rally migration — there is no longer a byte-identical parity
+contract to maintain across the two codebases.
+
+**Adaptive cadence.** A session declares its beat via `planned_heartbeat_secs`
+(presence record) or `renew_every_minutes` (lead.json); undeclared → the default
+cadence. Staleness is RELATIVE: `window = planned_interval * MISS_MULTIPLIER + GRACE`.
+Defaults `DEFAULT_CADENCE_SECS=300`, `MISS_MULTIPLIER=6`, `GRACE_SECS=60` →
+a 5-min cadence is stale at ~31 min (≈6 missed beats); a 5-hour cadence not until
+~30 h. Tunable via `.rally/config.json` `coordination{}` (Rust) /
+`.build-loop/config.json` `coordinationPolicy{}` (Python):
+`default_cadence_secs`, `miss_multiplier`, `grace_secs` (+ `RALLY_*` env in Rust).
+Legacy `heartbeat_minutes` is honored as a cadence source for backward compat.
+
+**Four signals — LIVE if ANY is fresh within the adaptive window:**
+(a) heartbeat/presence `last_seen`; (b) inject/ack (a `receipt`/`wake`/`handoff`
+naming the session); (c) forward code progress (the session's worktree branch HEAD
+MOVED since the last poll — Rust compares the two newest presence facts' shas, the
+Python reaper compares a cached `branch_head_sha`); (d) declared active work (a
+live claim or authored mission/handoff).
+
+**Two fail-directions, each on the safe side:**
+- **Squad VISIBILITY projection** (Rust `snapshot_from_facts_with_policy`) is
+  FAIL-OPEN. A squad whose four signals are ALL provably stale is DROPPED from the
+  default `rally room` view; `--include-archived` restores it (mirrors the message
+  archive model). A `Live` OR `Unknown` (any absent/unparseable signal) verdict
+  KEEPS the squad visible — hiding a still-alive peer could cause the very
+  write-collision this system prevents.
+- **Reaper REMOVAL** (presence-file unlink, claim/lead) stays FAIL-CLOSED — never
+  remove on a signal it cannot trust.
+
+**tmux orphan reaper.** `rally sessions --reap` also detects DETACHED `rally-*`
+tmux sessions whose last activity is past the adaptive window and which are not
+tracked as managed sessions, kills them, and tombstones the reap (closing the gap
+where `--reap` saw 0 of the real detached orphans). Attached sessions (a human is
+looking) are never killed.
+
+## Zombie-tmux prevention — three layers over ONE liveness model
+
+Root cause of accreted zombie tmux sessions: rally `exec`s the agent, so a session
+auto-closes when its agent EXITS, but agents that never exit (a disabled autonomy
+poller, idle detached panes) leave the session forever — tmux has no native
+idle/lifetime timeout. The fix is three layers, all reusing the single
+`liveness::is_live` 4-signal model and the adaptive window above. NONE adds a
+fixed/brute-force idle clock; lifetime follows real liveness/ownership.
+
+**Layer 1 — completion-scoped self-exit (prevent at source).** `rally
+self-exit-check --tool <self>` is a stateless re-check: a task-scoped session that
+holds NO active claims AND for which `rally next` is non-actionable for a SUSTAINED
+streak self-kills its own `rally-*` tmux session, so `exec` auto-closes it. The
+streak (default 2 consecutive empty re-checks, `liveness::DEFAULT_SELF_EXIT_STREAK`)
+is persisted in the session's OWN tmux env (`RALLY_SELFEXIT_STREAK`, dies with the
+session — no new filesystem surface) so a brief lull between claims never exits
+mid-task. **Opt-out:** `--persistent` short-circuits to "never self-exit" for a
+deliberately-long-lived session. The existing `rally stop` self-kill remains the
+explicit-completion path; Layer 1 adds the implicit "work done" path. Decision is
+the shared `liveness::completion_self_exit_eligible(work_resolved,
+next_empty_streak, required_streak, persistent_optout)`.
+
+**Layer 2 — event-driven liveness-lease safety net.** `rally enter` (a new agent
+joining) opportunistically sweeps detached `rally-*` orphan tmux sessions via the
+SAME reaper Layer-3 logic, in addition to `rally sessions --reap`. Best-effort and
+fail-open: it runs AFTER presence (so the entering agent's own session is in the
+guard set), never blocks the enter path, and never raises. A live / parent-alive
+session is never reaped. No daemon/cron (those would themselves need worktree
+isolation). Both the enter sweep and `sessions --reap` call ONE shared actuator
+(`sweep_orphan_tmux`).
+
+**Layer 3 — parent-lifecycle binding.** At launch (`tmux_start_command`) the new
+session's env is stamped with `RALLY_PARENT_PID=<launcher pid>` in the SAME atomic
+`tmux new-session -e` call. The reaper reads it back (`show-environment`), probes
+`kill -0 <pid>` (no new crate dependency — the repo keeps a zero-extra-dep
+contract), and feeds the result to the shared `liveness::reapable(liveness,
+parent_alive)`. This targets the exact failure mode here (autonomy poller died →
+its child sessions orphaned).
+
+**The single reaper-eligibility authority** is `liveness::reapable` (mirrored
+Rust↔Python, asserted by the byte-identical `liveness_vectors.json` `reapable_cases`):
+
+| liveness | parent_alive | reapable | rationale |
+|----------|--------------|----------|-----------|
+| Live     | any          | NO       | any of 4 signals fresh → independently live |
+| Unknown  | any          | NO       | fail-closed: untrustworthy signals |
+| Stale    | alive        | NO       | stale by signals but a live parent may re-drive it (conservative) |
+| Stale    | dead         | YES      | the Layer-3 orphan target |
+| Stale    | none (no info)| YES     | window criterion ALONE — fail-safe degradation |
+
+**Fail-safe directions (binding):**
+- A session making code progress / heartbeating on cadence / recently injected /
+  holding a live plan is NEVER reaped — that's `Live` → not reapable, regardless of
+  parent state.
+- The control NEVER reaps on the parent criterion ALONE: parent-dead reaps only a
+  session that is ALSO `Stale` by the 4-signal liveness.
+- Missing/unparseable parent info (`parent_alive = None`) degrades to the
+  liveness-window criterion alone (`Stale → reap`), preserving the pre-Layer-3
+  orphan-window behavior exactly — never reaped *because* the parent is unknown.
+- `kill -0` failing for any reason other than "no such process" (e.g. EPERM) reads
+  ALIVE (a live-but-unsignalable process is never treated as dead).
+
 ## Idle-agent self-selection (rally facilitates, the agent decides)
 
-**Rally is a facilitator, not an orchestrator.** It exposes room state (`rally room` / `rally next`), file-level deconfliction (`rally check before-write --path P`), and claims/handoffs. It does **not** assign or pick work. A waiting agent runs this decision tree itself and chooses — the agent's LLM reasons over rally's surfaced state. This keeps coordination decentralized: no single point that hands out tasks (which would be a failure site and a bottleneck).
+**Rally is a facilitator, not an orchestrator or verifier.** It exposes room state (`rally room` / `rally next`), file-level deconfliction (`rally check before-write --path P`), and claims/handoffs. It does **not** assign work, pick work, or verify code/release truth. A waiting agent runs this decision tree itself and chooses — the agent's LLM reasons over Rally's surfaced coordination records. This keeps coordination decentralized: no single point that hands out tasks (which would be a failure site and a bottleneck).
 
 When an agent is idle and `rally next` returns no actionable item, walk the tree top-down, stop at the first match:
 
@@ -162,7 +431,7 @@ When an agent is idle and `rally next` returns no actionable item, walk the tree
 4. **All coding candidates are claimed or conflicted** → do read-only research or assessment that helps and has zero file conflict (simplification scans of untouched areas, duplication/test-gap audits, docs the room needs).
 5. **Nothing fits, or the only work left is risky/deferred/peer-exclusive** → stay idle and say so; do not start risky/deferred work, do not touch another session's claimed paths.
 
-The tree is the guideline; rally supplies the facts (claims, collisions, pending items) each branch needs. Two same-tool agents running it independently land on different work because claim-first + `check before-write` makes the first claimant win and the second re-select — no central referee required.
+The tree is the guideline; Rally supplies coordination records (claims, collisions, pending items) each branch needs. Two same-tool agents running it independently land on different work because claim-first + `check before-write` makes the first claimant win and the second re-select — no central referee required.
 
 ## Coordination reliability (verify the room before trusting it)