[OmarAlJarrah]

Summary

This resolves the skills: issues filed up to #1257 in one change, and #1230, a docs: issue on the same title budget the shipping rules state. Later ones, from #1262 on, stay open for a change of their own. Most of it is rule text. Four parts change behaviour: sweep.py, skills_lint.py, and two new tests.

#1152, #1155, #1185, #1198 and #1206 mention a skill but are about code, so they stay open. #1251 was closed as not planned, because the lint needs a checkout by design, so this PR leaves the lint's exit outside one as it was.

sweep.py. Two problems came from the same code, so they are fixed together.

• A full disk ended a run in a traceback with no results. Compile output now stays in memory while it is compared, and only a spec that differs writes its outputs under OUTDIR/runs/<n>/. If those writes fail, the sweep carries on and says how many were not kept, because nothing it compares is on disk.
• An IRVersion bump listed every spec that compiled. The version a document opens with is now set aside before comparing: the summary prints it once, a spec that differs in nothing else is stamp in results.tsv, and the listed specs are the ones that moved. A sweep with only stamp changes exits 0.

The direction in the issue was to delete each pair once it agreed. Holding output in memory goes further, because a compile writing to a full disk fails on its own write, which reads as a difference between the builds rather than a crash. On a full disk the old script recorded morphic: write ir document: write /dev/stdout: no space left on device beside documents cut short, before it stopped.

A run now also clears OUTDIR/runs, since rewriting only the specs that differ would leave an earlier run's pairs under numbers that can name another spec. An OUTDIR that cannot be made exits 2 with a message rather than a traceback, and a results.tsv that fails partway is removed rather than left to read as a sweep of fewer specs. An empty irVersion counts as a version, so it still shows as a difference.

skills_lint.py. The lint named a test as missing until its file was staged, so a rule naming a new test drew exit 1 from a run the curating skill asks for after every edit. It read test declarations from the tracked list and paths from the list that holds untracked files too. Both now read the one list, so an ignored or deleted file still declares nothing.

Review and merge against a stacked base. The review setup built the tree it reviews by merging main alone, so a stacked PR could pass on a tree that does not compile once it meets its base. The setup now reads baseRefName and merges that branch first. The same gap is closed at each other site: the gate pass, the new-commits pass, recheck-against-final-tree, the push checklist's conflict line, and a new merge-the-base-first rule. That rule is separate because adding this to merge-main-first took it past the word cap.

New or widened rules

• trial-merge-open-prs now covers a change to what every file of a kind must hold, such as a golden, and runs that kind's tests on each merged tree. The review's process pass points at it. trial-merge-happened is new beside it: a trial merged from FETCH_HEAD in a new worktree fails, and its tests then pass on the branch alone.
• trial-merge-lints-the-skills is new: a word cap is shared across open PRs, and this PR and feat(ir)!: settle doc references, promotion records and names #1219 merged with no conflict at 512 words against 500. This PR's additions to that skill are now short enough that the two come to 487 on today's main.
• widened-field-values is new: when a lowering writes a value a field never held, read what the documents assume of the old values, and bump for the change of meaning, which no test sees. fix!: lower file bodies, enums, unions and streams as declared #1191's own 0.23.0 entry lists such a widening. The changing-the-IR description, its "What changes with it" list and the OpenAPI skill's traps all reach it, since nothing would otherwise have sent a reader there. widened-field-consumers is its second half, as a grep of the field and its old values finds nothing where a reader leaned on the old value unsaid.
• cost-claims-per-arm is new: a cost through a function that switches on kind is measured per arm and quoted as a range. The issue allowed measuring only the arm that reads hardest. The rule asks for every arm, naming any left out, because the same reference opens by saying that reading the code does not find a cost.
• limitation-searched-on-what-it-names is new: each limitation a body states is searched on the tool or behaviour it names, since a search on the construct can miss the issue tracking it. limitation-stated-where-it-lives and tracker-on-what-a-rule-settles both point at it.
• new-id-namespace is new: a new entry in a compiler's Namespaces rewrites every golden document, where a version bump rewrites none, and needs a spec that mints it, since the compiler's tests hold the list to its corpus. The issue did not name that second part; a plant showed it.
• rebuild-lost-plants is new, in mutation.md: a plant set nobody kept is rebuilt from the conditions the change adds rather than carried over, and run once before merge even after a comments-only merge. The review's code pass points at it.
• verdict-outlives-unchanged-files is new, beside it: a plant at hand keeps its verdict across a merge that left its file and the test that killed it alone, so merge-main-first no longer reads as every plant after every merge. The issue's comment proposed the file alone, and said why that falls short: a merge can remove the test.
• overlay-reaches-the-compiler-alone is new: go test -overlay plants without writing the tree, as that comment proposed, but it reaches only the compiler. A //nolint line and a new TypeKind each pass through an overlay and fail on disk, because internal/archtest and internal/decls read the sources at run time, so the rule says to re-plant such a survivor.
• equivalent-means-every-input is new: a survivor is recorded as equivalent only with the reason no input can observe it, after compiling inputs across the construct's domain, since a green suite answers for the inputs it holds.
• classify-named-strings is new, beside classify-ir-fields: a named string type needs an identityClasses entry. It is a rule of its own because classify-ir-fields is about fields.
• mention-is-no-use is new: a TypeID position that names a type without using it stays out of ir.TypeEdges and of each reader that takes the class as a use. The issue asked for it to stay out of every reflective reader, which would be wrong for one resolving references, since a mention can dangle.
• body-lands-at-merge is new: a commit body could stand on main when pushed, and a later commit making it stale is no finding, since a pushed branch is never rewritten and merges set their own body. A merge keeping the default paste edits a stale body out. commit-and-pr-message-form no longer claims the default squash decides what lands.
• finish-checks-before-the-golden is new, split from tests-fail-fast-and-legibly: no assertion follows a golden write, and one that may start a parallel subtest runs inside a serial t.Run, since a guard ahead of the write sees neither failing. Its Probe plants a regression that changes the golden, as one that leaves the document alone keeps the golden with or without a guard.
• deep-generated-shapes adds many $refs to one wide component, and reads output bytes beside instructions. The issue asked for the shape and the bytes; this also grows both dimensions together, since doubling either alone reads as linear. bound-the-product names references as a dimension.
• build-guards-see-later-writes is new: a check on how a value is built also matches a later write that resets it, the forbidden value in each argument of an append, and a literal with an elided type. source-scanners-match-every-form gains every import of a path and a range clause's assignment, and its Probe a plant nested in another.
• test-only-fix-reverts-by-hand is new: the revert that keeps test files is empty for a fix in test code, which read as a pass.
• no-network-through-a-logging-proxy is new, with a row in the claim table. It states what the proxy cannot see, since a request to a loopback address and a client whose Transport sets no Proxy both leave the log empty.
• plant-in-an-unpacked-copy and review-without-origin are new, for a repository that must stay unwritten or has no origin. The issue said git init for status and diff; the copy also takes a commit, since git init alone leaves them nothing to compare.
• moved-prose is new, beside moved-comments: it covers text that moved word for word and went stale when its neighbour did not move, a citation that outlived its passage, and a rewrapped line that opens with block markup.

Found while making this change, so no issue tracks them

• count-on-one-thread is new: an instruction count over a compile is taken under GOMAXPROCS=1 GOGC=off. Following instructions-not-wall-clock as written, the same two builds read +2.73% and then -2.08%; pinned, they read +2.06% with each side's range under 1%.
• trial-merge-happened is new, as above: a loop here reported three green trial merges that had never happened.
• pr-claims-match-evidence now holds a match count to the matches read, and a body edit to a push that has landed. A body here ran ahead of a commit the lint had refused, and a count of matching diagnostics turned out to hold ordinary spec text.
• closing-keywords says to read the field seconds after a save. It listed one of this PR's issues straight after opening.

Corrected rules

• rules-the-tree-still-breaks now names rules 6.15 and 6.24, and no longer implies its list is complete. test: most test doubles carry no stub, spy, fake or mock prefix #1279 tracks 6.24, as no issue did.
• redundant-guard asks whether removing a guard changes any outcome. A guard whose removal changes none is deleted, where the old text told a review to pin something no test could fail on. CLAUDE.md's sentence on guards stays as it is: it already gives this answer, and the rule now agrees with it.
• better-than-main no longer sends every output change to a Breaking section, which morphic-shipping-prs ties to a ! in the title.
• mutation-survivor-scope no longer asks for a whole-module run for a helper in a _test.go file, where its directory and ./internal/archtest settle it. This departs from the issue twice. Its own directory is not enough, since archtest reads test files as text. And export_test.go symbols are not an exception: another package importing the package does not compile that file.
• The verifying skill's habit lets a review's gate pass take CI's run for go test ./... too, as it already does for make gate. Pass 1 says a head behind a moved main gets no such exception.
• one-mutant-per-verdict says a plant removing a call removes it, as one discarding its error still runs it, and mutation-survivor-scope says an arm's removal alone does not make it equivalent.
• CLAUDE.md counts the appended number at the number the PR will get. It fixed the width at three digits, so a title its command passed at 72 landed at 73.
• CLAUDE.md and the shipping skill said a PR lands under its title. A branch with one commit of its own lands under that commit's subject, as CONTRIBUTING.md already said and test(ir/irverify): make the sort test reach its Path tiebreak #1232 shows, so every commit subject now counts the number, and the push checklist measures each as it would land.
• The IR skill's hand lists line says which list each kind of field meets. It said which test, and the reference names no test per table.

A departure to weigh. #1246 left two ways to settle assert.Equal against rule 6.16, which takes cmp for slices and maps and bars reflect.DeepEqual, which assert.Equal calls. assert-equal-on-plain-values records a departure for a value holding no unexported field, and CLAUDE.md says the same; a value holding one keeps cmp.Diff. The rule's reason is unexported fields. On a plain value the two agree on nil against empty, on order and on a NaN in separate values, and cmp parts from assert.Equal in two probed cases: it calls an Equal method, so the departure leaves out a value declaring one, which no type here does, and it refuses a NaN in a slice compared with itself. The tree compares a literal slice or map with assert.Equal about twice as often as it calls cmp.Diff. The alternative is a row in rules-the-tree-still-breaks and an issue to convert the calls.

New checks. TestAppendTypeIDs_ReadsWhatTheTypeGraphReads fills every kind and holds appendTypeIDs, which reads every TypeID under an operation by reflection, to ir.TypeEdges. A position that only mentions a type would otherwise become a GraphQL reachability root, and the check on field arguments would go silent on that type, with nothing saying so: the tests that fail on a new position ask for it to be classified, which says nothing about this reader. The test keeps no list, so it passes on #1219's DocRef position with no edit.

TestDocuments_OpenNoLineWithAPlus refuses a line opening with + outside a fence, across the repository's documents and .claude/skills, which a walk of the root leaves out. No document writes a list that way, so such a line is a sum a reflow left at the start of a line, and GitHub renders the rest of the paragraph as a list.

Limitations

• TestAppendTypeIDs_ReadsWhatTheTypeGraphReads reaches a type definition's fields. A position only an operation holds is no field of a kind, so nothing holds the reader to it: such a field added to ir.Operation leaves go test ./pass green, which mention-is-no-use states.
• TestDocuments_OpenNoLineWithAPlus holds the plus marker alone. Every other marker has real lists to tell it from, so moved-prose leaves those to a Probe that prints candidates to read.
• The push checklist's conflict line reports conflicts, not failures, as trial-merge-open-prs says. A base that merges cleanly but breaks the build is caught by merge-the-base-first and the review setup, not by the checklist.
• sweep.py holds each spec's output in memory for as long as it is compared, so -j bounds what it holds.

A tracker search on each of these (appendTypeIDs, TypeEdges, reflective reader, list marker, markdown block markup, merge-tree, push checklist, sweep memory, sweep.py) returned only issues this PR closes or ones on other subjects, so no issue tracks them.

Closes #1184
Closes #1186
Closes #1189
Closes #1193
Closes #1196
Closes #1197
Closes #1203
Closes #1204
Closes #1205
Closes #1208
Closes #1209
Closes #1213
Closes #1216
Closes #1223
Closes #1224
Closes #1225
Closes #1230
Closes #1236
Closes #1237
Closes #1242
Closes #1243
Closes #1246
Closes #1252
Closes #1253
Closes #1254
Closes #1255
Closes #1256
Closes #1257

Test plan

Sweep behaviour, on real builds of cmd/morphic at this head's sweep.py:

• Version bump: fix!: lower file bodies, enums, unions and streams as declared #1191's head 2c2404be against 20017d99, over testdata and a corpus of real specs, 2,170 specs in all. The old script lists 2,075 and this one 174, with 1,901 marked stamp. An independent comparison of the old script's kept outputs, as JSON with irVersion removed, agrees with every one of the 2,170 verdicts.
• No bump, real differences: test: witness common formats and pin what the suite left unheld #1192's head 46125b1b against bd874baa, over testdata alone, 215 specs. results.tsv is byte-identical to the old script's, each of the 212 kept pairs matches its bytes, and the printed rows match. The one printed change is the header, which no longer names an outputs directory.
• Full disk, on a 130 MB RAM disk over the same bump. The old script ends partway, at run 550 and at run 761 in two attempts, with a traceback and no results.tsv. This one finishes all 2,170 specs and reports the pairs it could not keep, 112 and 113 in those attempts, and none of its verdicts differ from a run with room.
• python3.14 -m unittest discover passes for both script directories, eight concurrent runs of the sweep's suite included, and 36 runs of its command-line tests, twelve at a time on a loaded machine. 32 mutants of sweep.py are each killed by a test, and a comment-only control survives.

Evidence the rules cite, replayed rather than quoted:

• 0611ef9b passes go vet ./internal/archtest alone and fails once merged with d707412d. On a local remote holding that stack, with main at 20017d99, the old setup stops on four conflicts with the head alone, where the failure cannot show. The new one merges the base first, which is the merge that fails, and then stops on the conflicts with main, leaving that tree to review.
• 21854da9 and ba2f961c merge with no conflict, and TestConformance fails on the merge.
• At 46125b1b, replacing the getter with a field read panics TestAllOf_BoolBranchContributesNoRequiredNames, and deleting the neighbouring bs == nil guard panics the same test at unmergedBranchKeys.
• Per-format cost at e67594b2 against 20017d99, instructions retired under GOMAXPROCS=1 GOGC=off, three alternating runs a side on 65,000-member specs I generated: double adds about 34%, int64 about 2% and uuid under 1%, with each side's range far narrower than the gap on double. That is the spread the rule describes; the figures in its Why are the ones its citation pins.

The rest:

• Deleting the DocRef guard from appendTypeIDs on a trial merge with feat(ir)!: settle doc references, promotion records and names #1219 fails TestAppendTypeIDs_ReadsWhatTheTypeGraphReads, which passes there unedited. Adding a struct holding a TypeID to ir.Docs, as mention-is-no-use's Probe says, fails it until the reader skips the struct. Three mutants of the test redden it, its guard against comparing nothing among them.
• An untracked test file named in a rule draws a finding at the previous head and none here. Eleven mutants of load_tree each redden test_skills_lint.py, and a comment-only control survives.
• With KindPrimitive changed in (*Primitive).MarshalJSONTo at 707849c8, TestConformance/scalar-format under -update fails and still rewrites its golden, from an assertion after the write. test: witness common formats and pin what the suite left unheld #1192 moved that assertion ahead of the guard, so the same plant at this head fails and leaves the golden alone. A guard in a test holding a parallel subtest reads Failed false, and true once the subtest sits inside a serial t.Run.
• openapi: a component lowers once per reference, so output grows as references times its size #1240's generator, from 100 references and 100 entries: output grows 2.00 times with references alone, 1.95 with entries alone, and 3.89 with both. From 200 of each it is 2.00, 1.97 and 3.94.
• The proxy logs a curl -x request and a planted http.Get, and logs nothing for a loopback address or a client with its own Transport, which still dials out.
• An unpacked copy with a commit shows one file in status and one change in diff HEAD after a plant, and both fetches of review-without-origin work in a new git init with no remote.
• The revert in fix-must-move-a-golden prints 0 bytes against test(compilers/openapi): keep the external order oracle offline #1235's test-only fix at 7d31114f.
• Deleting t.Helper() from a helper in pass/validate_payloads_test.go passes go test ./pass and fails TestTestHelpers_StartWithHelper, and a test in another package naming pass.AppendTypeIDs does not compile.
• A new named string type in ir fails TestIdentityClasses_AreAllClassified, and so does an entry for a type no longer declared.
• printf '%s (#%s)' "<title>" "$N" | wc -c measures the 65-character title from docs: the title budget assumes three-digit PR numbers, which are now four #1230 at 73 with its real number, where the old command read 72.
• Adding unresolved to the auth entry of ids.Namespaces changes all 129 golden documents at this head by one hunk each, against the 128 skills: morphic-changing-the-ir does not say a new ID namespace rewrites every golden #1213 measured, and the uniq -c line in new-id-namespace's Probe prints only that entry's lines. TestNamespaces_DeclaredAreExactlyWhatTheCorpusUses fails on the plant.
• Removing namesMedia's check on mime.ParseMediaType's error at 2c2404be fails no test across 40 packages, while a control mutant of the same function fails TestDecodeOptions_Refusals.
• The three searches in the limitation rule's source issue return what it says: content entry and several content entries miss cli: --explain doesn't list the Unmodeled entries kept at a coordinate #693, and explain Unmodeled finds it.
• TestDocuments_OpenNoLineWithAPlus fails on docs/emitters/emit/printing.md as it stood at 612b11bd, and on a + line planted in a skill and in docs/architecture.md. Four mutants of the check each redden TestPlusLines_ReportsAMarkerOutsideAFence.
• The moved-prose awk Probe, run as the rule prints it, flags a planted reflow of each marker (===, ---, >, - , 1. , # ) and leaves a real list alone. It prints four candidates over docs/ at this head.
• The review setup and the push checklist, run as their SKILL.md blocks print them, work on this PR. The checklist now prints eleven of this branch's earlier subjects, past the cap once the number is counted. They are pushed and stay as they are: a branch of several commits lands under its title, which is 66 characters with its number.
• Across the 354 merged PRs at deda5731, 240 of the 241 with several commits of their own landed under their titles. Each of the four with one commit whose subject differs from the title landed under that subject: refactor(compilers/openapi): lift the core's leaf methods out #197, refactor(compilers/openapi): free component and response lowering #216, and fix(engine)!: keep compiler diagnostics and exit on spec problems #335 and test(ir/irverify): make the sort test reach its Path tiebreak #1232, which have a merge of main beside the commit.
• The forms source-scanners-match-every-form gains, replayed on test: give every covered child its own coverage directory #1233's child-command rule: a row for a named import beside a blank one fails at 15a7e663, and one for cmd.Env as a range value at c6b9992c. Stopping the walk at a match in each Env branch, or at any selector, passes at e3bd3168 and fails at d2042a66, which added the nested rows.
• Deleting the no-kind guard in elect at fix(compilers/openapi)!: lower allOf by what its conjuncts say #1269's 68ac67d1: {format: int32} then {type: integer} lowers through t/prim/any, and the swapped order through t/prim/integer. With the guard the two agree.
• A mutant of appendTypeIDs through go test -overlay fails its test and leaves the tree clean. A //nolint line and a new TypeKind through an overlay pass TestSuppressions_NoDirectiveStandsInTheSource and TestTypeDef_HandWrittenKindListsAreComplete, and fail them on disk.
• git grep -n -E 'Content\.File|File' e1aa55c0 -- docs/emitters/refine docs/emitters/plan/operations.md prints nothing, the case widened-field-consumers covers.
• skills_lint.py and go test ./internal/archtest pass on this head.
• Trial merges of 41b7143b, this head before its last merge of main, with fix!: lower file bodies, enums, unions and streams as declared #1191 (b8f1b7f3), test(archtest): widen what two style checks see #1199 (e5d2ed23), fix(compilers/openapi): keep a keyword at every schema outcome #1217 (57591e6a), feat(ir)!: settle doc references, promotion records and names #1219 (d643a686), fix!: keep a security requirement naming no scheme #1226 (1c9e1ace), feat(compilers/openapi): read each document's schema identifiers #1227 (a7affa3f), feat(ir)!: type the secrecy and stability a document states #1229 (346c6b67), test: give every covered child its own coverage directory #1233 (d2042a66), test(compilers/openapi): keep the external order oracle offline #1235 (7a69f281), fix(compilers/openapi)!: lower allOf by what its conjuncts say #1269 (32417e90), fix(compilers/openapi): report allOf conjuncts sharing no value #1277 (e80229c1) and fix(compilers/openapi): treat a restated union branch as bare #1278 (afb4a4f0), each confirmed to hold the PR's head. skills_lint.py, go test ./pass -run TestAppendTypeIDs and go test ./internal/archtest -run TestDocuments pass on all twelve. fix!: lower file bodies, enums, unions and streams as declared #1191 then landed at that head, with no file in common with this PR. fix(compilers/openapi): keep a keyword at every schema outcome #1217, feat(ir)!: settle doc references, promotion records and names #1219, fix!: keep a security requirement naming no scheme #1226, feat(compilers/openapi): read each document's schema identifiers #1227, feat(ir)!: type the secrecy and stability a document states #1229 and fix(compilers/openapi)!: lower allOf by what its conjuncts say #1269 conflict with main alone since, in the same files with this head as without it. test(ir/irverify): refuse an integerFields entry for no field #1238 landed while this was under review. It rewrote the hand lists sentence in morphic-changing-the-ir/SKILL.md, whose stale-entry clause it made false, so the merge of main keeps its shorter sentence with this PR's correction to it.
• Both gate jobs pass on 5a1b146b, which holds main.