docs: move the ledger beside its pages and tag what each merge changed - #13
Merged
Conversation
There was a problem hiding this comment.
Pull request overview
This PR reorganizes and operationalizes the documentation provenance system by relocating the validation ledger into the rendered reference/ tree, updating cross-references and CI checks accordingly, and adding automated tagging/releases plus a human-readable changelog.
Changes:
- Move the provenance ledger to
reference/validation.mdand update references across docs, templates, and CI scripts. - Add
CHANGELOG.mdto summarize corpus changes perYYYY.MM.PATCHrelease tag. - Add an automated release workflow and a release-notes composer script that pulls pinned baselines from the ledger.
Reviewed changes
Copilot reviewed 13 out of 13 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| skills/atomic-integration/SKILL.md | Updates ledger reference to the new reference/validation.md location. |
| reference/validation.md | Updates ledger frontmatter scope to match its broader “corpus” role and rendered placement. |
| README.md | Points readers to reference/validation.md for provenance/tiers and updates an in-text reference. |
| learning/INSTRUCTIONS.md | Updates tier/ledger references to the new ledger path. |
| CONTRIBUTING.md | Updates contributor guidance to refer to reference/validation.md. |
| CHANGELOG.md | Introduces a release-by-release change record for the corpus. |
| AGENTS.md | Updates ledger reference to the new path in agent routing guidance. |
| .github/workflows/release.yml | Adds an automated tag+GitHub Release workflow keyed off merges to main. |
| .github/scripts/lib/pages.mjs | Adds a reusable section() helper used by CI/release scripts. |
| .github/scripts/compose-release-notes.mjs | New script that composes Release notes from the ledger’s “Pinned baselines” section. |
| .github/scripts/check-validation-consistency.mjs | Updates ledger path handling and reuses the shared section() helper. |
| .github/scripts/check-frontmatter.mjs | Stops treating the old root ledger filename as a “root page” for frontmatter checks. |
| .github/PULL_REQUEST_TEMPLATE.md | Updates template prompt to reference reference/validation.md. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
robrigo
force-pushed
the
docs/ledger-and-releases
branch
from
August 18, 2026 20:17
df20da3 to
e873e8a
Compare
The one page recording how every fact in this corpus was checked sat at the repository root, which is the one place the docs site cannot serve from: the include globs admit the four content trees, a root path resolves to no route, and no cross-reference can target it. The page that proves the corpus was the page a reader could not open. Under reference/ an existing glob admits it, so it renders beside the pages it grades and the sidebar can claim it. It takes no row of its own in the table it carries, because it is the ledger. Its description moves into the band a rendered page is held to, which is the only change the file itself takes. Both checks read it by path, so both move with it.
A reader who acted on a page has no way to learn that the page was wrong. Every fact here carries its source and nothing tracks a fact that moved, so a correction reaches only the reader who happens to open the same page again. The file uses four section names in one order and no others. Corrected leads every release, because a stated fact that turned out wrong is what a returning reader has to see first. Fixed, Changed, and Deprecated stay out: they describe code, and what ships here is claims. Each entry is one sentence naming the page it applies to, so a reader scanning for the page they depend on finds it without reading the release.
A corpus has no API surface to break, so a semantic major and minor carry nothing a reader can act on. What a reader wants is recency and the releases the pages were read against, which is why a tag is YYYY.MM.PATCH and the Release body copies the pinned baselines out of the ledger instead of restating them beside it. The patch number comes from the tags already in the month and the merge commit's own date, so nothing depends on the runner clock or on a date library. A commit that already carries a tag cuts nothing, which makes a re-run harmless, and the trigger is a branch push, so the tag this workflow creates cannot start a second run. Creating the tag and the Release in one call keeps a tag from standing with no Release behind it, which is what the next run reads to find the highest patch. The ledger check already cut a named section out of that file, so the reader moves into the shared library rather than being written twice. Its rewrite also fixes a section at the end of a page, which the regex form could not reach.
robrigo
force-pushed
the
docs/ledger-and-releases
branch
from
August 18, 2026 20:47
e873e8a to
27cff53
Compare
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
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.
Why
The provenance ledger lived at the repository root, where the site's include globs cannot admit it and where its grades were invisible beside the pages they cover, so it moves to
reference/validation.mdwith every reference across the tree updated and the two CI scripts reading the new path.CHANGELOG.mdopens with the record a returning reader needs first: what this series corrected, then what it added, re-verified, and removed, one sentence per entry naming the page. The release workflow tags each merge tomainwith the nextYYYY.MM.PATCH, creates a Release in the same call so no tag can exist without one, and composes the body from the ledger's own pinned-baselines block, so the corpus states what it was read against on every release. The emulator testing guide's install line already names@atomichub/vert; the package is not on the public registry yet, so the page stays excluded from the site until that publish, which is the sibling effort's pin-bump call.Notes for the maintainer
The first tag this workflow cuts is the merge of this pull request itself,
2026.08.0if it lands this month. The changelog heading is written by hand and the tag is computed from the merge date, so a merge that slips a month boundary leaves the heading behind by one; reconciling the two automatically is an open choice. The commits are unsigned; the squash merge carries GitHub's signature.