fix: move the improvement log out of the tree behind an accessor

.gitignore

@@ -59,8 +59,18 @@ venv/
 # instance's failure history, spend calibration and availability stay local.
 # Sanitized public twins of the load-bearing docs are committed under their
 # canonical names; these are the full versions.
+#
+# IMPROVEMENT_BACKLOG.md IS NO LONGER LISTED, ON PURPOSE. Ignoring it made it
+# invisible: a gitignored file does not exist in a git worktree, and agents work
+# in worktrees, so CLAUDE.md's two mandatory rules about it were unfollowable by
+# the workers they bind. The log now lives OUTSIDE the tree at
+# $ORCH_LOCAL_RUNTIME, reached via improvement_log.py, and the tracked
+# IMPROVEMENT_BACKLOG.md here is a short POINTER to it. Keeping it ignored as
+# well would let the 481 KB evidence file reappear at that path silently, which
+# is the failure this whole change undoes; tracked, it announces itself in
+# `git status` instead. test_improvement_log.py fails if the pointer grows into
+# a log.
 LOCAL_POLICY.md
-IMPROVEMENT_BACKLOG.md
 CAPABILITY_USEFULNESS.md
 *.local.md
 

.verify-floor.json

@@ -1,8 +1,8 @@
 {
- "collected": 387,
- "passed": 387,
+ "collected": 391,
+ "passed": 391,
  "skipped_max": 26,
  "selftest_skipped_max": 7,
  "gate_skipped_max": 2,
- "note": "Recorded by verify.py --update-floor, except the *_max ceilings, which are edited BY HAND and never re-measured. `collected` catches tests that stopped being collected; `passed` is compared against passed+skipped, so a check may move between passing and consciously-skipped but the two together may never shrink. The *_max ceilings bound the skipped side: 24/7/2 is exactly what a machine with none of this instance's local prerequisites skips (a GitHub runner: no agent CLIs, no ~/.codex/skills, no /Applications/ChatGPT.app, no populated capability ledger), measured 2026-08-21. On the owner's machine all prerequisites exist and nothing skips at all. Raising a ceiling is a deliberate act: it means agreeing that one more thing is allowed to go unchecked, so say which and why in the commit. LOWERED 26 -> 24 on 2026-08-22, reverting the raise made earlier the same day. The two kill-switch exemption tests no longer need to skip on a bare runner: their declarations moved out of the running instance's ledger and into capabilities.KNOWN_DECLARATIONS, so they assert code-derived truth and run everywhere. Moving a test back below the ceiling is the preferred way to lower it -- fix what made it machine-dependent, rather than agreeing to check less. FLOOR 345 -> 353 on 2026-08-22: 345 was measured on a branch cut before #13 (research panels/rounds/domain studies) merged, so the recorded floor sat 8 tests BELOW what main actually collects. A floor below reality is the permissive direction -- those 8 could have silently stopped being collected and still cleared the check, which is exactly the hole this file exists to close. Measure the floor on the merge result, not on the branch. Raised again on 2026-08-22 by the producer-identity-scope branch, which adds tests on top of the 353 recorded by #15; re-measured after rebasing rather than assumed. NOTE: `verify.py --update-floor` REPLACES this note with a generic one, so it must be restored by hand after every use \u2014 the ceiling rationale is the only record of which prerequisite justifies each skip. FLOOR 365 -> 366 on 2026-08-22 (heartbeat-ordering work, PR #18): exactly one new test, test_capabilities.test_no_tick_producer_runs_above_the_heartbeat_export. No ceiling moved and nothing new is skipped -- it reads source files rather than a populated ledger, so it runs on any machine. The branch recorded 354 because it was cut before #16 merged; re-measured on the MERGE RESULT per the rule above, which is exactly the mistake that put the floor 8 below reality last time. FLOOR 366 -> 368 on 2026-08-23: main collected 368 while this file recorded 366, drift left by #34 (evidence-acquisition landed, +1) and #37 (tick capability evidence, +1) whose authors each measured against a branch cut before the other merged. A floor BELOW reality is the permissive direction this file exists to close -- those two could have silently stopped being collected and still cleared the check. Measured on the merge result per the rule above: 368 passed, 0 failed, 0 skipped, 83/83 selftests, 43/43 can-fire, 5/5 gates. CEILING 24 -> 26 and FLOOR 368 -> 387 on 2026-08-23 (profiles/provenance branch, PR #42). This file CONFLICTED with #50, which raised the floor 366 -> 368 on main while this branch raised it to 387; resolved as the UNION rather than by taking a side -- #50's rationale is retained above and the count was RE-MEASURED on the new merge result instead of keeping either number. 368 (main) + 19 (this branch's net new tests) = 387; #50 corrected recorded drift rather than adding coverage, which is why 387 is unchanged from the pre-conflict measurement. Measured in a runner sandbox reproducing CI exactly (361 passed, 26 skipped, 387 collected) AND on the owner's machine (387 passed, 0 skipped, 5/5 gates). The two new skips are drift detectors against a REAL installed agent runtime, so neither can be moved below the ceiling -- the preferred way to lower one: (1) agy advertised-models cache absent, since comparing declared model ids against the catalogue agy actually advertises needs that catalogue, and a fixture would exercise the comparison while detecting no real drift; (2) vibe config absent (~/.vibe/config.toml), since active_model cannot be read to check for drift when there is no config to read. Both name their missing prerequisite, so a green run still states what it did not check. A third candidate skip was REFUSED: dispatcher's per-run agy-log assertion failed on a bare runner because adapters.advertised_models shells out to `agy models` when its disk cache is cold, and that probe landed inside a monkeypatched subprocess.run and overwrote the captured command. That is a stub leak, so it was fixed by ISOLATING the double rather than by skipping -- which makes CI run MORE."
+ "note": "Recorded by verify.py --update-floor, except the *_max ceilings, which are edited BY HAND and never re-measured. `collected` catches tests that stopped being collected; `passed` is compared against passed+skipped, so a check may move between passing and consciously-skipped but the two together may never shrink. The *_max ceilings bound the skipped side: 24/7/2 is exactly what a machine with none of this instance's local prerequisites skips (a GitHub runner: no agent CLIs, no ~/.codex/skills, no /Applications/ChatGPT.app, no populated capability ledger), measured 2026-08-21. On the owner's machine all prerequisites exist and nothing skips at all. Raising a ceiling is a deliberate act: it means agreeing that one more thing is allowed to go unchecked, so say which and why in the commit. LOWERED 26 -> 24 on 2026-08-22, reverting the raise made earlier the same day. The two kill-switch exemption tests no longer need to skip on a bare runner: their declarations moved out of the running instance's ledger and into capabilities.KNOWN_DECLARATIONS, so they assert code-derived truth and run everywhere. Moving a test back below the ceiling is the preferred way to lower it -- fix what made it machine-dependent, rather than agreeing to check less. FLOOR 345 -> 353 on 2026-08-22: 345 was measured on a branch cut before #13 (research panels/rounds/domain studies) merged, so the recorded floor sat 8 tests BELOW what main actually collects. A floor below reality is the permissive direction -- those 8 could have silently stopped being collected and still cleared the check, which is exactly the hole this file exists to close. Measure the floor on the merge result, not on the branch. Raised again on 2026-08-22 by the producer-identity-scope branch, which adds tests on top of the 353 recorded by #15; re-measured after rebasing rather than assumed. NOTE: `verify.py --update-floor` REPLACES this note with a generic one, so it must be restored by hand after every use \u2014 the ceiling rationale is the only record of which prerequisite justifies each skip. FLOOR 365 -> 366 on 2026-08-22 (heartbeat-ordering work, PR #18): exactly one new test, test_capabilities.test_no_tick_producer_runs_above_the_heartbeat_export. No ceiling moved and nothing new is skipped -- it reads source files rather than a populated ledger, so it runs on any machine. The branch recorded 354 because it was cut before #16 merged; re-measured on the MERGE RESULT per the rule above, which is exactly the mistake that put the floor 8 below reality last time. FLOOR 366 -> 368 on 2026-08-23: main collected 368 while this file recorded 366, drift left by #34 (evidence-acquisition landed, +1) and #37 (tick capability evidence, +1) whose authors each measured against a branch cut before the other merged. A floor BELOW reality is the permissive direction this file exists to close -- those two could have silently stopped being collected and still cleared the check. Measured on the merge result per the rule above: 368 passed, 0 failed, 0 skipped, 83/83 selftests, 43/43 can-fire, 5/5 gates. CEILING 24 -> 26 and FLOOR 368 -> 387 on 2026-08-23 (profiles/provenance branch, PR #42). This file CONFLICTED with #50, which raised the floor 366 -> 368 on main while this branch raised it to 387; resolved as the UNION rather than by taking a side -- #50's rationale is retained above and the count was RE-MEASURED on the new merge result instead of keeping either number. 368 (main) + 19 (this branch's net new tests) = 387; #50 corrected recorded drift rather than adding coverage, which is why 387 is unchanged from the pre-conflict measurement. Measured in a runner sandbox reproducing CI exactly (361 passed, 26 skipped, 387 collected) AND on the owner's machine (387 passed, 0 skipped, 5/5 gates). The two new skips are drift detectors against a REAL installed agent runtime, so neither can be moved below the ceiling -- the preferred way to lower one: (1) agy advertised-models cache absent, since comparing declared model ids against the catalogue agy actually advertises needs that catalogue, and a fixture would exercise the comparison while detecting no real drift; (2) vibe config absent (~/.vibe/config.toml), since active_model cannot be read to check for drift when there is no config to read. Both name their missing prerequisite, so a green run still states what it did not check. A third candidate skip was REFUSED: dispatcher's per-run agy-log assertion failed on a bare runner because adapters.advertised_models shells out to `agy models` when its disk cache is cold, and that probe landed inside a monkeypatched subprocess.run and overwrote the captured command. That is a stub leak, so it was fixed by ISOLATING the double rather than by skipping -- which makes CI run MORE. FLOOR 387 -> 391 on 2026-08-23 (improvement-log accessor, PR #59): exactly four new tests, all in test_improvement_log.py -- three read tracked files in the tree (the pointer's size and content, and that CLAUDE.md 0 step 3 and 5 name the accessor rather than a bare path) and one runs the accessor as a subprocess against a path that cannot exist. None reads a populated ledger, an agent CLI or ~/.codex, so all four RUN on a bare runner and NO ceiling moved: nothing new is skipped. Measured on the MERGE RESULT after rebasing onto origin/main af6654d, which collected 387 -- not on the branch base, per the rule above."
 }

ADDING_CAPABILITIES.md

@@ -24,7 +24,8 @@ in a table nothing wrote for it.
 
 The dated evidence for all nine failure modes is deliberately **not** committed — it names this
 instance's repositories, PRs, spend and working constraints. It lives in
-`ADDING_CAPABILITIES.local.md` alongside `IMPROVEMENT_BACKLOG.md` (see `LOCAL_POLICY.md`).
+`ADDING_CAPABILITIES.local.md` (see `LOCAL_POLICY.md`), and the item-by-item status history lives in
+the machine-local improvement log, reached with `python3 improvement_log.py search <term>`.
 
 The governing lesson survives the split, and it is the reason this file has a test file rather than
 only prose: **a rule that lives only in a document does not survive the next session.** `CLAUDE.md`

CLAUDE.md

@@ -2,11 +2,19 @@
 
 > **Local vs public.** This repository is the TOOL: generic capabilities, gates and tests. This
 > instance's EVIDENCE is not committed — the failure history, spend calibration and attention-budget
-> figures live in `LOCAL_POLICY.md`, `IMPROVEMENT_BACKLOG.md`, `CAPABILITY_USEFULNESS.md`,
-> `*.local.md` and `Code/Audits/Orchestrator/`, all gitignored. Where a rule below cites a figure,
-> read it from `LOCAL_POLICY.md`. Runtime state (Brain, ledger, stamps, worktrees) lives outside the
-> tree at `$ORCH_STATE_DIR`, default `~/.codex/orchestrator`, so a second instance needs a different
-> `ORCH_STATE_DIR` and no code change.
+> figures live in `LOCAL_POLICY.md`, `CAPABILITY_USEFULNESS.md`, `*.local.md` and
+> `Code/Audits/Orchestrator/`, all gitignored. Where a rule below cites a figure, read it from
+> `LOCAL_POLICY.md`. Runtime state and durable evidence live OUTSIDE the tree, behind two variables:
+> `$ORCH_LOCAL_RUNTIME` (the Brain, the capability ledger, and the **improvement log** — reached with
+> `improvement_log.py`, never by path) and `$ORCH_STATE_DIR` (the audit cache, cadence stamps,
+> monitors, worktrees). Both default to `~/.codex/orchestrator`, so a second instance needs different
+> values and no code change.
+>
+> **Gitignored is not the same as machine-local, and confusing the two hid a rule from its own
+> workers.** A gitignored file does not exist in a git WORKTREE, and agents work in worktrees — so
+> the improvement log, which §0 and §5 both require, was unreachable by every worker those rules
+> bind. Evidence that agents must READ belongs outside the tree behind an accessor, not gitignored
+> inside it. When you add such a thing, leave a tracked pointer naming the accessor.
 
 Read `README.md` first for what this project is and its important functionality. This file is the
 rules for anyone (human or agent) *changing* it.
@@ -143,7 +151,12 @@ back. Adding a "new" feature that already exists is the easy mistake here.
 2. Read the historical dormancy inventory:
    `Code/Audits/Orchestrator/2026-07-08-dormancy-rescan.md`, then generate current activation truth
    with `python3 capabilities.py inventory`. Feature maturity is not activation evidence.
-3. Check `IMPROVEMENT_BACKLOG.md` — items carry status notes; many "ideas" are already DONE.
+3. Search the improvement log — `python3 improvement_log.py search <term>`. Items carry status
+   notes and many "ideas" are already DONE. The log is machine-local evidence living outside the
+   tree, so **use the accessor, never a path**: it resolves `$ORCH_LOCAL_RUNTIME` for you, prints
+   each hit under the item that owns it, and — when the log is not on this machine — names what is
+   missing and exits 2 instead of looking like "no matches". `IMPROVEMENT_BACKLOG.md` in the tree is
+   a pointer, not the log.
 4. If the capability EXISTS: the task is to **wire/activate/extend or un-gate it** (and say so),
    not rebuild it. If it exists but is deliberately gated, treat flipping the gate as the change and
    justify it. Only build new if the concept genuinely isn't present.
@@ -223,11 +236,16 @@ Do not create a second event log, model registry, or capability inventory.
   `capability_activation_audit.entrypoint_presence` / `absent_entrypoint_note`, which name the
   sibling checkout the code was found in — but read the message rather than the missing-parts list.
 - **The split is TOOL vs EVIDENCE.** Generic capabilities, gates and tests are committed. This
-  instance's evidence is not: `IMPROVEMENT_BACKLOG.md`, `CAPABILITY_USEFULNESS.md`,
-  `LOCAL_POLICY.md`, `*.local.md`, `experiments/`, `ux_reviews/`, `data/`, `Audits/`. When adding a
+  instance's evidence is not: `CAPABILITY_USEFULNESS.md`, `LOCAL_POLICY.md`, `*.local.md`,
+  `experiments/`, `ux_reviews/`, `data/`, `Audits/` — gitignored in the tree — plus the ledger, the
+  Brain and the **improvement log**, which live outside it under `$ORCH_LOCAL_RUNTIME`. When adding a
   personal figure — spend, availability, a habit — it goes in `LOCAL_POLICY.md`; the code refers to
   it. The boundary is file location, not recall. Published VENDOR list prices are fine and are kept
   deliberately: they are public and they are the model-tier rationale.
+  **Evidence an agent is REQUIRED to read must go outside the tree behind an accessor, not
+  gitignored inside it** — a gitignored path is absent from every worktree, which is how §0 step 3
+  became unfollowable. `improvement_log.py` is the pattern: a tracked pointer of the same name, an
+  accessor that resolves the path, and a named absence when the file is not on this machine.
 - A live fleet tick runs hourly and writes only to worktrees/state, never to this canonical tree —
   but if another interactive/headless session is editing here too, coordinate (the fleet-checkout
   hazard is real; see the user's memory). Look before overwriting a file you didn't create.
@@ -282,5 +300,9 @@ and update the gated-features list in README.md + the dormancy inventory.
 
 When you activate a dormant feature, un-gate a flag, or add a subsystem: update its lifecycle
 record, regenerate the capability inventory, update README.md's functionality section if the
-topology changed, and append a status note to the relevant IMPROVEMENT_BACKLOG.md item. Do not
-duplicate lifecycle verdicts in prose; stale parallel inventories are how features get forgotten.
+topology changed, and record a status note on the relevant improvement-log item with
+`python3 improvement_log.py append <item-ref> "<note>"`. Use the accessor rather than editing a
+file: the log is machine-local (outside the tree), the accessor finds the item and places the dated
+note inside it, and it REFUSES on an ambiguous or unknown ref rather than guessing — a note filed
+against the wrong item corrupts the record it exists to improve. Do not duplicate lifecycle verdicts
+in prose; stale parallel inventories are how features get forgotten.

IMPROVEMENT_BACKLOG.md

@@ -0,0 +1,27 @@
+# Improvement backlog — POINTER. The log itself is machine-local.
+
+**Do not append to this file.** It is a tracked pointer, a few lines long, and `test_improvement_log.py`
+fails if it grows into a log. The real improvement log — the numbered items and their status notes —
+is this instance's EVIDENCE, not the tool, so it lives outside the tree with the ledger and the Brain
+(`$ORCH_LOCAL_RUNTIME/IMPROVEMENT_BACKLOG.md`, default `~/.codex/orchestrator/`). Reach it through the
+accessor, which resolves the path for you:
+
+```bash
+python3 improvement_log.py search <term>        # CLAUDE.md §0 step 3 — is this already DONE?
+python3 improvement_log.py append <item-ref> "<note>"   # CLAUDE.md §5 — record a status note
+python3 improvement_log.py path                 # where it resolved to, and whether it is here
+```
+
+`search` prints each hit under the item heading that owns it, plus the number of lines and sections it
+read, so "no matching items" is a statement about a file that was actually read. When the log is not on
+this machine at all — a fresh clone, a CI runner, a second instance — every command says what is
+missing and where it would be, and exits 2 rather than returning empty.
+
+## Why this pointer exists
+
+The rules above are mandatory and, until this file, unfollowable by the workers they bind. The log was
+gitignored, and **a gitignored file does not exist in a git worktree** — agents work in worktrees, so
+the project's own countermeasure against its #1 defect (building something that already exists) was
+invisible to every worker required to consult it. Nothing in a worktree even hinted the log existed.
+Moving it to machine-local state is what `CLAUDE.md` §1 already prescribes for runtime state and
+instance evidence; this pointer is what makes it findable from anywhere.