feat(docs): gate BReg tutorials with a runner that reads the page as its spec - #1572
Merged
Merged
Conversation
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
jeremi
enabled auto-merge
September 26, 2026 05:51
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: f0d9304513
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
A Node runner reads the tutorial as the specification: sh fences run in one shell in document order, test-skip names why a fence is left alone, and test-expect output blocks are checked against what the fence above printed. It runs beside check-breg-tutorial.sh until the two agree. Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
A diff block titled with its file and marked test-edit is the change the page asks for; the runner applies it at whatever indentation the file has and refuses an edit that matches nowhere or more than once. test-exit covers a refusal the page demonstrates, and pages given together replay in one directory, so extend-a-registry-with-a-module continues from first-breg as a reader does. Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
…t they quote Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
…age runner Each page under start/ or tutorials/ that runs breg or bregctl now declares tutorial_test: the toolset, the page a reader finishes first, or why it is not replayed. run-tutorial.mjs --gate breg replays first-breg and the module tutorial as one journey and replaces check-breg-tutorial.sh in CI. Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
…gain Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
…report init prints The page showed a trimmed finding list the command no longer prints; the replay caught it. The selection change is now the edit a reader makes. Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
…ts page does A page that begins from a Registry Stack checkout sets tutorial_test.checkout, and the runner starts it at the root of a copy of the tracked and unignored files instead of an empty directory. Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
The request excerpt now quotes the example file in the order it is written, and the page shows the part of the explain report it describes. Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
…stopped a journey A misspelt toolset, unreadable frontmatter, or a broken annotation on a skipped page now fails the gate by name. An interrupt reaches the running command and shows its output, a fence that exits its shell stops the journey on any page, a page bash cannot parse is blamed instead of the fence before it, and cleanup survives directories the journey locked. Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
…ncher The routing comments and tests named a quickstart launcher and a deleted script; the gate runs the page runner, which starts bregctl dev. Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
…al inputs Every products/breg path already selects the BReg packages the replay builds, and no replayed binary links registry-evidence, so the comment saying it did is gone. Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
A page running breg commands under another toolset, or skipping every one of them, is now refused, and the journey script no longer sets shell variables a page's fences could read or overwrite. Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
jeremi
force-pushed
the
feat/tutorial-runner-pilot
branch
from
September 26, 2026 06:10
f0d9304 to
6dfc284
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 6dfc28433a
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
A toolset that cannot be prepared fails every journey the same way, so the gate now exits 2 at once instead of rebuilding it for each journey and reporting an ordinary replay failure. Signed-off-by: Jeremi Joslin <jeremi@joslin.fr>
This was referenced Sep 26, 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
This replaces the bash BReg tutorial gate (
check-breg-tutorial.sh) with a Node runner in which the tutorial page is the specification. The runner replays a page'sshfences in document order, in one shell, from an empty reader directory. Each check sits on the page, as a fence annotation:test-expect: the whole output of the preceding fence, with<name>placeholders.test-excerpt/test-excerpt="<path>": a run of lines, or a JSON subset, found in that output or in a file.test-edit: adiffblock applied to the file it names, exactly as the reader sees it.test-exit="N": a documented refusal.test-skip="reason": a fence the replay cannot run.Coverage comes from each page's frontmatter (
tutorial_test: {toolset, after?, skip?, checkout?}). Every page understart/ortutorials/whose fences runbreg/bregctlmust either be replayed or say why it is skipped.node docs/site/scripts/run-tutorial.mjs --gate bregreplays every journey, and--dry-runprints the plan.The pages give the reader file contents and edits, not scripts that write files, so they still read as written for people.
What this PR replays
first-breg->extend-a-registry-with-a-module, as one journeyderive-a-registry-from-publicschema. Replaying it found staleinitoutput and a false claim that paths were omitted; both are fixed.review-registry-changes, which starts in a copy of the checkout (checkout: true). Its old skip reason was stale.Also in this PR
QuickstartMetaprerequisites link to the pages that cover them.breg-tutorialjob runs the runner's own tests and then the gate.check-breg-tutorial.shand its test are removed, and the CI routing and gates inventory are updated.Verification
npm testindocs/site: 661 pass.test_ci_changes.py: 119 pass.check-gates-inventory.pypasses.breg/bregctl:gate PASS: 3 journeys replayed, 5 pages skipped. Everybregctl devsession was stopped, and no tokens appeared in the log.Known limits
test-exitchecks only the fence's final status.Follow-ups
The Casework, Evidence, Relay, and Discovery tutorial gates move to this runner in one PR per product.