Skip to content

NOW.md is still a surface every PR must write: the doc-checkpoint gate marches them into it #374

Description

@localai-bot

Follow-up to #364, which removed .agents/NOW.md's byte budget but left the file itself a surface every PR writes. That is the defect the same change wrote into AGENTS.md as an invariant — "if N concurrent PRs all edit file F, then F is a lock" — so NOW.md is now a documented violation of the rule it shipped alongside.

Why everyone edits it

It is not habit. It is mechanical:

# scripts/check-doc-checkpoint.py
REQUIRED = {
    "lifecycle": (STATUS, BENCHMARKS, NOW),
    ...

Any lifecycle move must touch .agents/NOW.md, so the gate marches every row-advancing PR into one shared file. NOW.md conflicted in 5 of the 16 conflicting open PRs measured at d928e2c3. Removing the byte budget removed the forced eviction; it did not remove the forced write.

What NOW.md actually contains

Almost all of it is a projection of records that already have a per-row home:

NOW.md content Already lives in
row state, owner the matrix row
who is working on it .agents/claims/CLAIM-*.md (added by #364) and open PRs
the row's "next command or step" nowhere per-row — this is the gap
cross-row priorities, current gate genuinely authored, operator cadence

Proposal

Relocate the obligation rather than delete it. The live position must stay current; what is wrong is where that is paid.

  1. Each row's next step becomes a ## Now line in the row's own spec — a file only that row's author touches. .agents/specs/ took zero conflicts across the whole Shared record surfaces are a lock: 16/29 open PRs conflict, 13 of them in bookkeeping only #364 sample; it is the shape that demonstrably works here.
  2. scripts/now.py renders the digest on demand from the matrices, .agents/claims/*.md, each spec's ## Now line, and open PRs (degrading to REMOTE_UNVERIFIED offline, as claim-view.py already does).
  3. check-doc-checkpoint.py drops NOW from the lifecycle triple and instead requires the moved row's spec to carry a current ## Now. Same obligation, per-row surface, no lock.
  4. .agents/NOW.md keeps only what is genuinely authored at operator cadence — current gate, next actions, the invariants that bite. Its live-claims table is deleted and generated instead, and check-now-current.py gains a rule that the file may not carry a per-row claims table again, so it cannot regrow into the log it replaced.

Net effect: a row-advancing PR writes its own spec and its own claim file, and touches no shared surface at all.

Also in scope

AGENTS.md's new §Records paragraph ends with a dated measurement (16 of 29 ... at d928e2c3 ... third instance after policy.csv 0f3e44ee). That is a log entry in the one file the project says history does not go — "There is no state log", and the reason for a change belongs in its commit, where git log --grep is the record. It is also the accumulating-justification pattern #364 removed from STATUS_RATCHET. Compress to the rule; the evidence is already in the spec and the commit.

Risk

This changes the cold-start ritual every agent depends on (AGENTS.md step 3), so it takes its own row, spec and fresh review. scripts/now.py must be fast and work offline, or it becomes a worse NOW.md than the one it replaces.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions