feat(standards): cut-successor writer automates payload version cuts (#227 E3#1/#2) - #241
Merged
Merged
Conversation
`project-standards standards cut-successor <standard-id> <version>` performs the mechanical half of a payload cut, which until now was a hand-run procedure with four declaration sites that had to move in one order: the copied `payload.toml`, the family index, the catalog major, and the two generated artifacts. The writer copies the predecessor tree, stamps the version and the per-file digests, computes the aggregate through the repository's own `validate_payload_integrity`, appends the `[[versions]]` entry, inserts the catalog entry immediately after the family's last one, and then reruns `sync-payload-projection` and `render-catalog` through the same entry points an author would type — so a cut can never generate a projection or catalog those commands would not. The successor inherits the predecessor's catalog role and only a `default` predecessor is demoted, which keeps reference-only and internal families from acquiring a default as a side effect. Inherited version references are reported, never rewritten: a permalink or a migration `from` endpoint is correct history. The one exception is a migration's `to` endpoint, which the payload contract requires to name its containing version — a copy that kept the predecessor there produces a manifest that does not load — so it is re-pointed and reported as an applied edit. Refs #227, #236
chrisdpurcell
marked this pull request as ready for review
September 1, 2026 20:36
This was referenced Sep 1, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
project-standards standards cut-successor <family> <new> [--from <pred>] [--scaffold-test] [--dry-run]: copies the predecessor payload tree, stamps the version, recomputes every per-resource digest and the aggregate throughpackage_contract/integrity.py, appends the[[versions]]entry, inserts the catalog[[packages]]entry as the family default and flips the predecessor toretained, re-points migrationtoendpoints onto the successor (the payload contract requires it), reports every remaining predecessor-version occurrence for human review, then runs the existing projection sync and catalog render.--scaffold-testemits the mechanical half of the version contract test with a marked TODO block. Refuses an existing successor directory.Governing work
Supporting: #227
Acceptance coverage
tests/package_contract/test_cut_successor.py: end-to-end cut ofpython-codingon a temp copy with the five validators green afterwards and the scaffolded test passing; migration-endpoint test onpython-toolingproving predecessor bytes are untouched.Verification
New tests (2 passed, 28 s),
tests/test_usage_doc_inventory.py(65 passed), ruff format/check, basedpyright, five standards validators, prettier + markdownlint on docs — all exit 0.check-release --baseline v5.28.0reports only the by-designPC-RELEASE-LEVEL.