docs(plans): record the step MRs and correct the plan's stale claims

Fills the MR column for the three merged steps of the repository-column-writers plan: step 1 is !2358 (merged), step 2 is !2399 (merged) and step 3 is !2362 (merged). All three are merged. Steps 4 and 5 keep empty cells, which mean "not yet recorded" rather than "not started".

The table has a single writer by design, per guardrail 4 in AGENTS.md: parallel step MRs editing their own rows collide wherever the rows are adjacent lines of the same file, and this plan keeps consecutive steps in flight together.

Plan corrections carried here

That same single-writer rule makes this branch the only open MR that can make the plan-text edits the merged steps deferred, since !2441 (merged)'s declared scope is the Q1 ruling. Two review findings asked for them, and both are addressed. A second round asked for four more, listed under Second review round below.

Step 3 shipped a different cap than the plan described

!2362 (merged) gave the repository timestamp write its own repositoryStampMaxInFlight rather than running it behind counterEmitMaxInFlight, so it does not widen what that cap draws on. docs/dev/storage-accounting.md:1541 at 577ecde53 says so outright: "the repository timestamp write does not widen that set: it draws on repositoryStampMaxInFlight instead".

Four passages still said the reverse, and all four now describe what shipped: Step 3's storage-accounting.md entry, Step 5's entry, the Dependencies bullet's Step 3 half together with its parent sentence, and the operator sentence. The Step 5 half of the Dependencies bullet is left as it stands, because Step 5 books Redis increments and still does not widen the Postgres draw, so narrowing it would drop a claim that is still correct.

The edits !2358 (merged) and !2362 (merged) deferred

Carried here rather than filed as a work item, so they reach a git message instead of surviving only in two merged MR descriptions.

  • Step 1's Files: named six spec files; !2358 (merged) changed nine. Entries added for docs/specs/S14-maven-remote.md, docs/specs/monolith/S05-repository-detail.md and AGENTS.md, with a note that the S10 and S16 edits reached six and nine passages against the one and two those entries name.
  • Step 1's Acceptance read "no sentence claims a remote read path books one" as an absolute, while the step's own Files: entry deliberately keeps S16's gated rows. Narrowed to name that exception, citing S16 :980 and :1377, then narrowed again in the second round below, because Maven remote books one as well.
  • Step 2's Files: entry ordered the S17 :93 no-op-stub clause rewritten. !2358 (merged) rewrote that row whole, so the entry now records that half as done and the two steps no longer share a document line.
  • TestNewCounterSink_RejectsAHalfBuiltPair is TestNewCounterSink_RejectsAHalfBuiltSink at internal/format/oci/emit_test.go:1797 on main. Fixed at both sites, along with the constructor's collaborator count, which Step 3 took to three.
  • "guardrail 19" is guardrail 17 on main. Fixed at both sites.
  • Step 5's entry quoted "Five sites emit" and put Steps 3 and 5 together at eight. main:1561 reads "Seven sites emit", so the target is nine.
  • Step 5's five membership read travels inside line numbers are :1470, :1500, :1506, :1540 and :1775 on main. The count of five holds; only the numbers moved.

Every figure above was re-derived at 577ecde53.

Not carried. The eleven-caps paragraph pins :1465, :1486 and :1487 and quotes a row reading "Eleven hand-rolled in-flight caps" as current on main. That text is gone on main today rather than only moved, and "Ten of the eleven" with it. Restating that argument needs its own derivation, so it is left for the census work rather than folded in here as a number swap.

Second review round

Four more findings on the same plan text, each a place where a merged step's entry was corrected and a sentence around it was not.

  • Three sentences still handed Step 5 the membership read travels inside clause as an edit it owns, while Step 5's own entry at :1463-1469 records that none of the five passages takes an edit from this plan. All three now say the site count instead: Step 3's storage-accounting.md entry, the Step 5 entry's lead at :1433, and the closing sentence at :1472. :1463-1469 is left as it stands.
  • Step 1's Acceptance absolute is narrowed to container or npm. Maven remote is the third remote read path and it does book one, in two sentences !2358 (merged) itself wrote: S14-maven-remote.md:579-580 and S17-rest-management-api.md:93. The qualifier makes the paragraph agree with the sentence above it and the grep -rn sentence below it. Neither spec is touched; both are correct.
  • Step 2's Shared seams field still ordered a rebase over S17-rest-management-api.md:93 after the Files: entry three lines above had recorded !2358 (merged) as taking the row whole. Rewritten as a record: nothing at :93 is left for Step 2 and no rebase order applies.
  • Step 1's monolith/S05-repository-detail.md entry closed on a sentence reading as though nothing still routes the column to S18. Three passages do, and !2358 (merged) left them: :270's blocked-on column and the "#757 carries ... into S18" sentences at :905 and :1851. None carries the string downloads_count, which is why the step's grep did not reach them, so they are recorded as a docs(specs) follow-up. The same entry called a ## References bullet "the Requirements pointer"; it is the S22 bullet at :81-84, and the requirements-shaped table is the :270 row.

Every figure in this section was re-derived at 577ecde53.

AGENTS.md gains one convention section

The four findings above are one failure shape, so they land as one section, A Merged Step Turns Its Plan Entry Into a Record, with a rule per finding: narrow every pointer to a corrected entry, check a step's Acceptance absolute against the step's own other edits, turn a coordination field into a past-tense record once the coordination is over, grep what a passage routes to rather than only the name it routes, and name a passage by the heading it sits under.

Each rule ships as its own commit, paired with the plan commit it came from, so either half can be reverted alone. The section sits between An Accepted Log Volume Says Whether the Records Are Sampled and A Steady-State Claim Names the Transient It Excludes, which is a region main has not moved since this branch's base, so the addition merges without a conflict.

Overlap with !2441 (merged), and how to resolve it

!2441 (merged) is open against the same plan file. It rules the plan's open sub-decision and, among other passages, clears the Blocked cells of rows 4 and 5 and rewrites the prose that explains that column. git merge-tree reports a content conflict between the two branches, while each merges cleanly into main, so the conflict belongs to whichever lands second.

The corrections above add no new conflict region: re-derived at bec5aee07, the two branches still conflict in exactly one place, the Status table. !2441 (merged) touches only the plan file, so this branch's AGENTS.md commits add none.

There is nothing to choose when resolving it. In that table this MR changes rows 1, 2 and 3 only; rows 4 and 5 appear as context lines, not as changes, and the conflict is purely that the two hunks sit within three lines of each other. So the resolution is keep-both:

  • rows 1 to 3 keep this MR's MR references,
  • rows 4 and 5 keep !2441 (merged)'s empty Blocked cells, and the legend below the table keeps !2441 (merged)'s wording.

Do not take this MR's rows 4 and 5 wholesale. On this branch they still read Q1 and via Step 4, because the branch predates !2441 (merged), and restoring them would put a block back into a plan whose Research Findings, dependency graph, Step 4 bullet, Dependencies, Open Questions and Status legend all say the sub-decision is ruled. Nothing in CI reports that.

Docs-only and behaviour-preserving, so no issue link is required.

Edited by Dzmitry (Dima) Meshcharakou

Merge request reports

Loading
Loading