Skip to content

One writer for derived contract files: README contract count, contracts/contracts.nt and the ONT-5 witness (the T21 roadmap.yaml rule) #4781

Closed as not planned

Description

@noahgift

Every PR that adds or renames a contract also regenerates three derived files:

  • the contract count in README.md (make readme-sync),
  • contracts/contracts.nt (the regen step of contracts_gate.sh),
  • the ONT-5 witness contracts/witness/<census hash>.json (pv lint gate 18 fails when it is stale).

Two such PRs conflict on these files even when their contracts have nothing in common. Each merge makes every other open contract PR stale, so each one has to regenerate and re-run. T21 removes the same churn for docs/roadmaps/roadmap.yaml.

Rule, the same one T21 applies to roadmap.yaml:

  1. No PR writes these three files. A PR commits its contract only.
  2. The checks accept a lagging aggregate. CI regenerates the three files in its own clone before any reader, and judges the PR against the regenerated copies (contract validity, census, witness, count). Every existing verdict still blocks.
  3. One writer: a nightly job opens at most one PR, from main, that changes only these files.
  4. The release refuses a commit whose committed files are not the aggregate (publish preflight), so a release never ships a stale count, witness or graph.

Until the writer exists: at most one refresh PR a day for the derived files, and that PR holds nothing else.

Measure: each morning, count the open PRs in conflict with main, and how many of them conflict only on generated files (roadmap.yaml, the README count, contracts.nt, the witness). Target 0 for the second number.

Prior art: T21 (branch build-kaizen/one-writer): scripts/check_roadmap_one_writer.sh, scripts/roadmap_one_writer_ci.sh, scripts/roadmap_writer_nightly.sh, contracts/apr-roadmap-one-writer-v1.yaml.

This changes what a gate accepts. It needs two reviewers who are not the author, plus a quorum sign-off. Any new judge lands as report-only from today's measured value, and blocks only after three green nights.

Owner aprender-a7. Refs #4678.

Activity

  1. added this to the 0.71.0 milestone on Oct 8, 2026
  2. noahgift commented on Oct 14, 2026

    @noahgift
    ContributorAuthor

    Folded into #4741 as a checklist row (TRIAGE-100, 2026-10-14): the open-ticket cap is 100, so this ticket is now tracked on that master and closed as not planned. Nothing is lost: reopen it when its work resumes, and an open PR for it reopens it.

    Agent: aprender-clerk

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    P1High prioritykind:codeWork is a code change (derived rule, #4159)owner:aprender-a7owner sessionsize:MK̂ 3-4 h

    Type

    No type

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions