Release: the ring file, the rules that cut and move next and roll it back, a commit's one Release, and a Run's own (#197, PR 1)

Merged
DO
23d ago
+2054-82

Record 0071. Part of "Release: cut an immutable tag, move next, and roll back in one action" (#197), PR 1: code and data only. It replaces combsmith/software-factory#337, whose history held a test value gitleaks reads as a key (an invented placeholder, never a real id); this branch carries #337's final tree in one clean commit, plus ruling 8. The PR table is #197's comment. Nothing here writes a tag, mints a credential or dispatches a workflow.

What it holds

  • release/rings.json (rings/1, a data file): next (factory/v0-next) serves combsmith/software-factory for review-change; stable (factory/v0-stable) serves nothing; promotion from next to stable needs at least one Run, every Effect read back and an eval for each changed Intent (FR-47, FR-50, L-47). Schema schemas/rings.schema.json; example and four counter-examples.
  • release/cut.py, pure (rulings 4, 4″, 5′): plan(step, refs, facts, channels) gives the writes or one code. Only a Channel rings.json declares is moved, and only to a commit one Release names alone; every commit and ref is a full sha, or the step is refused. A cut refuses not_newer, not_on_main, not_verified, already_released, another_major and, read before anything is written so a closed gate burns no version, eval_gate_closed, which also refuses a pass judged for another Release. A move goes only to an existing Release of the Channel's major, through the same gate. A rollback passes no gate and only moves back (not_earlier), by default to the greatest Release below. No step writes a Release tag (release_is_immutable) or stable (promotion_not_built).
  • release/current.py (ruling 7): resolve(commit, refs) is the one Release tag on the commit; a Channel never counts, and two Releases are none, matching the interim git tag --points-at semantics.
  • release/move.py: python3 -m release.move plan STEP REFS FACTS, which prints the plan and writes nothing.
  • adapters/tags.py: one read of git/matching-refs/tags/factory through the transport; {name: commit}, or None for an annotated tag, a name twice, another page, or any answer not a list of refs. It reads nothing at any tag (0006).
  • tools/check_release.py, run by verify: no repo and family on two Channels, both Channels of one major, and the rules import nothing but each other. check_examples refuses a rings counter-example through it, as it does a trial's through check_trials.
  • .claude/skills/cut-a-release/SKILL.md (10′), pointed to from the root AGENTS.md; release/AGENTS.md.
  • examples/invalid/task.a-channel-for-a-release.json (L-45).
  • config/apps.json: the release App's five needs (write:release_tag, write:move_channel, write:deployment, read:release.refs, read:release.runs), each waits_on its registration, as write:write_view waits on the view App's; the schema and the apps counter-examples carry them.
  • release/fixtures/refs.read.json: one read of refs/tags/factory/ through the Maintainer's gh login on 2026-10-26, redacted (no factory/ tag exists yet); adapters/tags.py replays it, and check_release holds every Release fixture to check_trials' credential scan and header list.
  • Ruling 8: harness/read.py, the run job's reader, names the Run's own Release, the one Release tag on the commit its own job checked out (steps.commit(), read before any key), from the factory/ tags read with its own token. A Run whose own Release is not its pass record's builds no Task and leaves outcome/1 superseded, release_moved, which harness/outcome.py keeps over apply's run_failed; one whose own Release cannot be named stops release_unresolved and never takes the pass record's. read:release.refs is the reader's, under the contents: read it already holds. apply's own release_differs stays, for the apply job disagreeing after the reader agreed.
  • Wired into #339's run-jobs.yml: the run job uploads the reader's outcome as reader-outcome when the reader's step failed; apply downloads it by id (and the Result only when there is one) for harness.outcome's workflow form. harness/steps.release, #339's interim name for a step's Release, now applies release/current.py's rules, one implementation, keeping release_untagged and release_twice. RUN_JOBS_FILE holds the new file word for word.
  • The tags read follows each page GitHub links (CodeRabbit), of this list alone, of this repo by its name or the id GitHub gives for it, and to a bound, failing closed on anything else.
  • Rows re-pointed: 0006 (three), 0010 (one), L-45, L-46 (both halves now), L-47.
  • Protected files, for the Maintainer's eye: config/hooks.json (release/ added as a verify lens input; tests/test_tools.py::TheList requires every top-level package there) and config/apps.json (the five needs above, no grant).

The gate is read before the tag is created, not after as 4′ words it, so a closed gate burns no version; the record should say so.

Not here

  • .github/workflows/release.yml (4′): PR 2, reviewed on its own. The App's entry with 4′'s grants: after the Maintainer registers it and P-39 reads it again (PR 3 or its own). Here, only its needs, each waiting on that registration.
  • release/rings.json as a protected path in config/hooks.json: the Maintainer's edit (ruling 6).
  • For PR 2: a forward move input on release.yml (9′ step 5 needs one; 4′ names only cut and rollback); a check that factory/v0.0.1 is lightweight, since adapters/tags.py refuses an annotated tag and a Release tag can never be deleted; and whether GitHub paginates matching-refs (the port fails closed on a next link), which no fixture records yet.

Gates

  • make verify (SIM_SEEDS=40, alone): 1215 tests OK (14 expected failures), every check ok, on 565e8b1 (1223 tests); CI on the merge with main
  • Mutants: 58 new (50, then 8 for ruling 8), each killed by its named test in a whole-tree copy with MUTATING=1 (50 now). The capped filtered run hit the machine-load timeout (its baseline suite takes over 600 s here, and it caps a run at 40), so CI's 8 shards stand as the mutant gate
  • Fresh Claude review with a security pass: no blocker; two majors (an undeclared Channel of another major; ruling 8 not here) and minors, fixed in the second commit but for ruling 8 and the PR 2 items above
  • Argon (AGY): one blocker (a move or rollback onto a commit two Releases name) and majors (the rules could import the CLI; a falsy to; non-sha commits; mutants missing), each fixed in the second commit
  • SonarCloud: the plan read paths from argv (S8707); it now reads standard input (on #337), thread answered there
  • Ruling 8's delta (c8cbf2b..e66f52c on the old branch), as this PR's fix round: Claude review with a security pass, no blocker, one major (the moved outcome never reached the Run's recorded outcome, fixed by the last step keeping it, with an end-to-end test) and minors (an outcome for a Run id the record does not hold, fixed); Argon: no findings
  • The wiring's delta (6141456..9731942): Claude review with a security pass, no blocker, no major, no CodeQL alert expected; its minors fixed in 9731942. AGY: not run (quota); an Argon read of this PR's merged diff is owed when quota returns, as for a PR merged early
  • gitleaks, locally, on this branch's history with main's config: no leaks
  • Muse: not run (Maintainer, 2026-10-20: Kernel/hook only)

🤖 Generated with Claude Code