backlog-burndown's no-shared-file rule is unsatisfiable: every canonical-content worker writes the shared ledger

[ptr727]

backlog-burndown states its central rule as "Group so that no file is claimed by two live groups at once. This is the rule the skill exists for, and it binds harder than any throughput target."

In this repository that rule is unsatisfiable for any round carrying two canonical-content groups, and the skill never names the file that makes it so.

drive-pr step 2 requires every worker to run local-strict-review, and that skill's carried-content pass records before the commit "because that ledger is tracked". canonical_review.py record writes two tracked files: reports/canonical-review.json and a full regeneration of reports/canonical-review.md. So every worker whose group edits a carried canonical unit necessarily writes both. Carried canonical content is the hub's dominant issue class, and backlog-burndown's own "Choosing the Worker's Model Tier" contemplates such groups in the plural. Two live groups, one file.

The concrete failure is in the .md rather than the .json. write_ledger sorts the ledger per unit precisely "so a concurrent branch touching a different unit merges cleanly", and it does. The burn-down report carries global counts. Two branches each recording one new pass both rewrite the same - covered: N line to the same N+1, which git merges silently as an identical change on both sides, and each deletes a different bullet from the per-file "never" lists, which also merges cleanly. Develop then holds a report whose counts are lower than the ledger's, and .github/actions/validate/action.yml runs canonical_review.py report --check on every pull request, so the next unrelated pull request fails validate with no branch to blame.

The skill's own detection does not reach it. "Predict each group's file set by reading the issues" cannot predict a file no issue names, and "Verify the prediction before dispatching" runs at the round's step 3, before any worker has pushed a pull request whose gh pr diff --name-only would show the ledger.

Possible shapes, all design calls rather than wording ones:

• Name the ledger files as an implicit claim every canonical-content group holds, and cap such groups at one per round. Simple, and it costs most of the parallelism on the repository's dominant issue class.
• Have the orchestrator record every canonical pass itself at the round's cleanup step, so no worker writes the ledger. This crosses the "the orchestrator edits nothing" line, and the digest binding means the orchestrator would be recording a read it did not perform.
• Make report --check tolerant, or make the .md derive its counts at check time rather than storing them, so a stale count is regenerated rather than failed on. This fixes the merge collision at its source and leaves the claim rule honest.

Found by a local-strict-review diff pass on the pull request that added this skill. It is distinct from #1275, which covers --prune, the hardcoded origin/develop three-dot base, the missing branch-to-claim traversal, and the "closing keyword is deliberately absent" falsehood.

[ptr727]

Reframing this after maintainer review, because the original framing put the problem in the wrong place and would have led to the wrong fix.

The state transfer is not the problem. It is already solved. write_ledger in scripts/canonical_review.py writes reports/canonical-review.json sorted, one entry per unit, and its own docstring says why:

Sorted and one entry per unit so a concurrent branch touching a different unit merges cleanly, and so the diff of a recorded pass reads as the pass rather than as a reordering.

Two workers recording passes over different units produce two non-overlapping insertions into a sorted list, which merges correctly. That file needs no claim and no lease.

The problem is a committed derived artifact that is byte-gated. reports/canonical-review.md is not state. cmd_report builds it as render_report(current_units, read_ledger(root), absent), a pure function of the ledger plus the tree, and --check compares the committed bytes against a fresh render. It carries global counts. Two branches each recording one pass both rewrite the same - covered: N line to the same N+1, git merges that silently because the change is textually identical on both sides, and the result is false for both. .github/actions/validate then fails report --check on the next unrelated pull request.

So the question is not "how does a worker claim this file" but "why is a rendering committed and gated at all". Recommended fixes, in order:

1. Stop committing the report. Keep canonical_review.py report as an on-demand command and have CI publish the rendering as a job summary or artifact. The conflict surface goes to zero, nothing has to be claimed, and the burn-down stays readable where people actually read it. report --check then has nothing to check and goes away with it.
2. Make it merge-safe by construction. Keep committing it, but drop the global counts so the file is only per-unit lines sorted the way the ledger is. That is the same property that already makes the .json safe. It costs the at-a-glance coverage summary, which is the reason to prefer option 1.

Option 3, giving backlog-burndown a lease or capping canonical-content groups at one per round, is now clearly the wrong layer. It would spend most of the parallelism on this repository's dominant issue class to work around a report that did not need committing.

The general point, which outlives this issue. A skill should be usable in isolation, tightly coupled internally and loosely integrated with its siblings. Here backlog-burndown's central rule was made unsatisfiable by a file that a script called from a different skill happens to write, and the filename was never the point. The same question is worth asking of every skill that tells a worker to run something with a side effect on tracked files: what state actually has to survive, and does the artifact carrying it merge cleanly when two workers produce it at once. That review is broader than this issue and should be its own piece of work.