Promotion: develop → main (ADR rulesets join the derived-artifact chain) - #555
Merged
Conversation
The loose end left by GT-703. `generate-adr-rulesets.mjs` writes one conformance
ruleset per ADR, so editing an ADR's PROSE drifts a generated artifact — a one-word
correction to ADR-0126 ("Sixteen" -> "Seventeen") turned `Validate documentation` red
on a PR that touched no ruleset at all. It had its own step and its own `--check`, but
it was not a chain link, so nothing replayed it in order and `--fix` could not repair
it.
THE EDGE WAS ALREADY KNOWN, IN PROSE ONLY. The native evaluability snapshot's comment
says `documentation-only` moved 129 -> 136 "purely because seven generated ADR rulesets
appeared". That is a dependency, written down and never declared, so the ordering claim
could not be checked. The link now sits before the snapshot and those rulesets are in
the snapshot's `consumes`, which turns the sentence into an assertion — verified by
swapping the two links and watching `validateChainShape` refuse: "native evaluability
snapshot consumes …adr-0001….rules.json, which a LATER link writes."
ARTIFACTS RESOLVED FROM DISK, NOT LISTED. 135 files today and one more per future ADR.
A hand-written list would rot on the next ADR and rot SILENTLY: a `writes` entry that
stops existing fails loudly, but one that was never added is simply not checked.
AND THE VACUITY THAT CREATES: a resolved-from-disk list can come back empty. An ABSENT
directory is legitimate (a synthetic `--root` has none, and the missing producer is what
fails there); an EXISTING but empty one is not, and now fails with its own message
rather than handing the chain a link that verifies nothing and reports success.
Verified: chain 9 links / 146 artifacts, current and at a fixed point. Reproduced the
original failure — ADR prose edited, check mode names "ADR conformance rulesets is
STALE (link 3 of 9)", one `--fix` repairs it. Tests 12/12 after re-pinning the declared
count 8 -> 9 and stubbing the new producer in the synthetic roots (they broke first, and
the breakage was the fixture describing a chain that had moved). Meta-guards: 82
classified, 58 observed refusing the empty fixture.
feat(ci): fold the ADR conformance rulesets into the derived-artifact chain
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
📊 Bilingual Coverage ImpactPR Changes
Repository Coverage
✅ Good: All EN changes have ES counterparts. Generated by GitHub Actions |
#556) The README opened with a menu, an architecture diagram, and a link to a quickstart whose Step 1 invoked a script that does not exist. The working quickstart sat at line 227 of 389, behind a twenty-row Q and A accordion. Measured readership over the preceding fortnight: two unique visitors to the landing page. WHAT A STRANGER NOW SEES FIRST: a one-line positioning claim, one badge row, and an installable three-command block at line 16. Then "What just happened", which quotes a real run of the published 1.3.0 in a container with nothing but Node -- 133 checked / 26 skipped / 0 errored, 37 blocking, exit 2 -- and says what the numbers are for: NINE of those 37 blocking issues are rules that were SKIPPED. Not rules that failed; rules the engine could not decide, reported as failures because an undecided blocking rule is not a passing one. Backed by a named invariant test rather than by adjectives. TWO SECTIONS THAT DID NOT EXIST. "Use it as a PR gate", with the copyable uses: block -- the README mentioned the GitHub Action NOWHERE while action.yml has been Marketplace-shaped at the repository root for weeks. "Why not ArchUnit, Conftest or dependency-cruiser?", which opens by telling the reader to use them and carries a column for where the neighbour is equal or better. It also states what is NOT built: no command in the installed CLI reaches an LLM, so the "LLM proposes, verifier disposes" half is labelled a documented direction. That paragraph exists because it is the first thing a skeptic greps for. NUMBERS, AND TWO OF MINE WERE WRONG. The README claimed "137 ADRs, 163 rulesets, 45 schemas" and "47 tools, 9 resources". My own first count said 103 core ADRs and 382 rules. An independent measurement replicating the PRODUCTION LOADER corrected both: the normalizer reads rules ?? principles, so four principle-shaped packs contribute 30 rules a naive count misses, and the corpus is 412. ADRs are 142 once README/adr-matrix/authoring-standard are excluded. Now: 142 ADRs, 181 ruleset files carrying 412 rules, 50 schemas, 52 tools, 12 resources. It also caught a contradiction I had introduced: 412 is the corpus the Core carries, 159 is what one satellite's run selected. The README now says which is which, because a report that blurred two denominators is the exact defect this project exists to stop. QUICKSTART REWRITTEN. It made booting a Core API a mandatory Step 1 via ./.harness/scripts/run-core-local.sh -- a file that does not exist -- and promised a server on :30080 that no service in the compose file defines. It is now the three commands that work, plus what the numbers mean and the exit-code taxonomy: 1 and 3 are not weaker forms of 2, they mean nothing was evaluated. The server material moved to a new "Self-hosting the Core API" guide that opens by saying you do not need it, and that records the dead instruction rather than quietly deleting it. The Q and A accordion moves below Quick Start, the hero diagram below the fold, and the dead "Onboarding by role" row is a link again. Not in this change: the asciinema demo. Everything it would record is now real and reproducible; the recording itself is still to do.
Contributor
Author
|
Note before merge: |
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.
Promotion: develop → main
A transport, not a work item. The change was reviewed and merged on
develop; nothing here changes a verdict, and this body declares no gap ids — per #538, a promotion's diff does not claim what merely travels inside it.What travels
Why it matters
generate-adr-rulesets.mjswrites one conformance ruleset per ADR, so editing an ADR's prose drifts a generated artifact. That is how a one-word correction to ADR-0126 turnedValidate documentationred on a pull request that touched no ruleset at all. It had its own--checkbut was not a chain link, so nothing replayed it in order and--fixcould not repair it.The dependency was already written down one link below — "documentation-only moved 129 → 136 purely because seven generated ADR rulesets appeared" — but only in prose. It is now declared, and therefore machine-checked: swapping the two links makes
validateChainShaperefuse.State at the tip
42(82 classified) and43(58 observed refusing)08-validate-tracking,01-validate-docs,04-check-bilingual-parity(17/17),66-validate-bilingual-syncall passmaincarries no commits thatdeveloplacks.Evolith Core Quality Gates
develop.Linked ADRs / Issues
No gap ids declared — no board row moves in this diff.
Conventional Commits
🤖 Generated with Claude Code