Skip to content

Freeze released work-boards and read them with the current readers (#271) - #312

Merged
memtomem merged 1 commit into
mainfrom
test/frozen-board-271
Nov 15, 2026
Merged

memtomem merged 1 commit into
mainfrom
test/frozen-board-271

Conversation

@memtomem

Copy link
Copy Markdown
Owner

Refs #271. This is the first half of the Board family. It follows the convention of the artifacts, rooms, workflows and sessions families. The issue stays open.

The family is split in two PRs. This one freezes the databases and covers the readers and the human path. The second covers HEAD board run, GC, compaction and renew_claim on a released board, plus the gateway, dashboard and TUI readers. It adds no fixtures.

What

  • Generator. tests/fixtures/persisted/board/freeze.py writes the board databases for v0.1.2, v0.2.0 and v0.3.0 using each release's own CLI: board add, run, update, import-review-candidates, decide, and from v0.2.0 compact.
    • The agent is a fake codex, and each run sets its behaviour.
    • The gate is add(2, 3) == 5 on a one-file repository.
  • Scenarios (per release):
    • lifecycle:
      • gate evidence that passed (route), and gate evidence that failed (pipeline, because route drops a rejected gate report; the route shape is kept too);
      • the agent's done and review blocks, with handoff and outputs;
      • an agent failure;
      • a killed claim that the release's own next run reclaimed and finished;
      • manual evidence, a sign-off, and a refused bare done;
      • a human block, an annotate, and human-required set and cleared;
      • dependencies on a done item, a planned item and a missing item;
      • an imported review candidate;
      • decisions: global, scoped and superseded.
    • running: a run SIGKILLed while its agent works, together with its WAL.
    • crash-blocked: a SIGINT, and an orchestration crash. The crash comes from a .pth hook that is loaded for that run only and raises inside Supervisor.run.
    • compacted (v0.2.0 and v0.3.0): partly compacted. One item's claims and reclaim are only in the rollups. Another item's are split between the rollups and the live audit, so each count needs both sources.
  • No rebinding. The board stores no paths, hostnames or pids. The generator refuses any cell that holds the box path, home or hostname.
  • Generator checks and expected values.
    • Generation fails unless every shape the tests read is present.
    • Each database is copied first. Then the release's own interpreter reads a scratch copy of it, and those reads are the expected values. They cover Board.get, list, transitions, active_decisions, _row_to_decision on every row, and stats. The stats are taken at a fresh clock, at an aged clock, and on both sides of one item's aging cutoff.
  • Readers (each run on a copy):
    • HEAD's first open adds its columns and tables and keeps every released cell. A second open changes nothing, and the files are 0600.
    • Board.get, list (filtered too) and transitions are compared field by field with the release's reads and with the raw cells.
    • board list and board show are checked against the release's reads through the renderers. They are also checked line by line using only the release's values, so a reader and a renderer that drift together still fail.
    • active_decisions; _row_to_decision on every row, retired ones included; board decisions; project_lessons, which is empty because no released decision is a lesson.
    • stats at every recorded clock, and board stats at the fresh and aged clocks.
  • Human path on released rows:
    • update --state done counts stored evidence, and is refused without it.
    • --sign-off, and --clear-human-required on a crash.
    • An annotate keeps a released lease and is not counted as a re-dispatch.
    • decide --supersedes: allowed in the same scope; refused out of scope and for an already-superseded decision.
    • A re-import is skipped. It is refused when the stored provenance differs in task, inputs, or the evidence's kind, ref, author or verdict.
  • docs/architecture/persisted-contracts.md: the Board row now names these, and also what no release wrote:
    • The lesson columns. Their readers stay covered by test_lessons.py.
    • A positive ledger backfill. Every release writes the ledger row inside the claim's transaction. The synthetic tests in test_board.py stay the coverage.
    • Damaged JSON.

No source under src/ changes. No current reader misread a released row. One release difference is pinned rather than reported: v0.1.2 leaves blocked_reason empty on a crash-blocked item, and v0.2.0 onward stores the crash note there.

Verification

  • suite-run is CLEAN, and ruff check . is clean.
  • Fixture hashes are identical before and after a test run.
  • 48 injected regressions. Each is a one-line change to board.py, injected exactly once and restored from a byte copy. Each fails the test. They include:
    • every _row_to_item field, plus list order and list fields;
    • every _load_evidence field;
    • every _row_to_decision field, and the active_decisions superseded, goal and unbound clauses;
    • every _same_review_provenance clause;
    • the done gate counting stored evidence, and the running-annotate lease branch;
    • _add_missing_columns, both whole and for one column;
    • the stats rollup, counter, live-claim and from_state terms, the aging cutoff, and the stats default clock;
    • render_board, render_item and render_board_stats dropping content.
  • Codex review.
    • Design: two rounds before approval. Both were NEEDS-FIX, and every finding was adopted.
    • Implementation, round 1: NEEDS-FIX. CLI checks reused HEAD's renderers on the expected side, there was no evidence-kind collision case, and CLI stats were checked at the fresh clock only.
    • Implementation, round 2: NEEDS-FIX. The renderer reuse was still partly open, so the show, list and decisions checks were rewritten to compare every field line.
    • Implementation, round 3: unprimed, given the diff only. SHIP, with one Minor: Board.list was checked for ids only. That is fixed.

🤖 Generated with Claude Code

)

The first half of the Board family of the persisted-contracts D rows.

tests/fixtures/persisted/board/<release>/ holds the board databases
v0.1.2, v0.2.0 and v0.3.0 wrote with their own CLIs: board add, run (a
fake codex whose behaviour each run sets), update, import-review-
candidates, decide and, from v0.2.0, compact.
- lifecycle: gate evidence passing (route) and failing (pipeline; route
  drops a rejected gate report), the agent's done and review blocks with
  handoff and outputs, an agent failure, a killed claim reclaimed by the
  release's next run, manual evidence, sign-off, a refused bare done, a
  human block, an annotate, human-required set and cleared, dependencies
  on a done, a planned and a missing item, an imported review candidate,
  and decisions global, scoped and superseded;
- running: a run SIGKILLed while its agent works, with its WAL;
- crash-blocked: a SIGINT and an orchestration crash (a .pth hook loaded
  for the run only raises inside Supervisor.run);
- compacted (v0.2.0, v0.3.0): partly compacted, so one item's claims and
  reclaim live only in the rollups and another's are split between the
  rollups and the live audit.
The generator fails unless every shape the tests read is present, and
refuses a cell holding the box path, home or hostname, so nothing is
rebound. After copying each database it has the release's own
interpreter read a scratch copy (Board.get, list, transitions,
active_decisions, _row_to_decision on every row, stats at a fresh and an
aged clock and on both sides of an item's aging cutoff): those reads are
the expected values.

The test works on copies and reads:
- HEAD's first open: the added columns and tables, every released cell
  kept, a second open a no-op, the files 0600;
- Board.get, list (filtered too) and transitions field by field against
  the release's reads and against the raw cells;
- board list and board show, both against the release's reads through
  the renderers and line by line from the release's values alone;
- active_decisions, _row_to_decision (retired rows included), board
  decisions, project_lessons (no released decision is a lesson), stats
  and board stats;
- the human path on released rows: done counting stored evidence or
  refused without it, sign-off, clear-human-required, an annotate keeping
  a released lease, supersede in and out of scope, a re-import skipped,
  and refused when the stored provenance differs in any checked part.

No source under src/ changes; no current reader misread a released row.
48 injected one-line regressions in board.py each fail the test.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@memtomem
memtomem merged commit bc2529a into main Nov 15, 2026
12 checks passed
@memtomem
memtomem deleted the test/frozen-board-271 branch November 15, 2026 00:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant