Require the instruction set before any authoring - #485
Merged
Conversation
The Blog standup carried four mechanical config files and none of the authorities, then authored its tooling and imported its content under no rules. AGENTS.md, GOVERNANCE.md, CODESTYLE.md, WORKFLOW.md, AUDIT.md, README.md, HISTORY.md, copilot-instructions.md, markdownlint-cli2.jsonc, cspell.json and version.json were all absent from the live tree, and the result is 237 comment-shape findings across its 28 authored files. Step 2 permitted that by treating the baseline as one undifferentiated list. It is two kinds of file. Most are deliverables, but the instruction set is the rules for producing every other file, so carrying it late means everything authored beforehand was authored against unknown rules, and the cost is rework rather than a warning. Step 1A now stops the procedure until the instruction set is carried and read. The rationale is stated as the same shape as step 0: signing must be live before the first commit, governance must be loaded before the first authored file, and in both cases the window closes quietly while the repair is expensive out of proportion to the prevention. The step also requires markdownlint-cli2.jsonc and cspell.json as the mechanical half, since a repo that carries the prose authorities without the linter configs has guidance and no gate. Their absence is why the comment style drifted unchecked in Blog rather than failing a run. One caution is aimed at a contributing cause rather than the agent. The hub's own .editorconfig, .gitattributes and .gitignore carry 44 comment-wrap and comment-case findings, so a repo that copies them and reads them for house style learns the shape the rules forbid. Blog's copies carry 37 of the same, inherited rather than introduced. The step now says to read the rule text as the authority and never to infer style from a carried file's formatting. Cleaning those files is a separate hub backlog item. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the repo-standup procedure (STANDUP.md) to require carrying and reading the governance/instruction set before authoring any new repo content, closing an onboarding gap where repos could be created and substantially authored under no rules and without prose/tooling gates.
Changes:
- Adds a new step 1A that blocks further scaffolding until the instruction set is present and read.
- Explicitly requires
.markdownlint-cli2.jsoncandcspell.jsonto be carried early as the mechanical enforcement half of prose guidance. - Adds the missing reference link target for
AGENTS.md.
ptr727
added a commit
that referenced
this pull request
Aug 1, 2026
Forward promotion of five commits. `main` carries no content beyond the merge-base (`8771e62`, #478), so this is a clean forward merge with no conflicts. **This one has a consumer waiting.** The Blog standup (#456) is mid-correction and has been told to carry its instruction set from `main`, because `main` is the audit ground truth. Every fix for the failure it just hit is currently on `develop` only: `main`'s `STANDUP.md` still begins at "1. Classify and Catalog", with no step 0 and no step 1A, and `main` does not yet require `OPERATIONS.md`. Until this promotes, a repo following the corrected instructions re-runs the uncorrected procedure. ## What promotes - **#480 - Name where repo-specific content goes.** `STANDUP.md` step 2 named no destination for content that is not a carried file. The three destinations existed only in `spec/section-model.md`, which nothing on the scaffolding path pointed at. - **#481 - Verify commit identity before the first commit, and require `OPERATIONS.md`.** Step 0 verifies identity and signing before `git init`, framed **verify, never set**, because the host carries the identity globally and a repo-local override shadows it silently. `OPERATIONS.md` becomes required for an `operational` repo, presence-checked like `README.md`. - **#482 - State what a host must provide.** The tooling contract, naming no installer so it stays true on every platform, plus a route to the write-safety kit which the host-setup document never referenced. - **#484 - Prefix the PowerShell invocation, and name the interpreter per platform.** Both corrections came from real Windows and WSL2 testing in #483 and disproved something #482 asserted. - **#485 - Require the instruction set before any authoring.** Step 1A, the direct fix for the Blog failure. ## Verification on the merged `develop` The full 180-case `scripts/` suite, `scripts/repo_gate.py`, `spec/validate.py` and `spec/audit.py --selftest` all pass. The blocking prose run (charset, dupword, spelling) is clean tree-wide, markdownlint reports 0 issues over 39 files, and editorconfig-checker is clean. ## Release A human merge never auto-publishes, so this fires no release, as designed. The latest release stays `2.0.108`. ## Re-vendor debt #481 changed `GOVERNANCE.md` "Git and Commit Rules", a `verbatim` section, so this promotion re-vendors it across the fleet. That was accepted deliberately when the change was made. The debt is pre-existing and still untracked, and `spec/audit.py --branch <ref>` checks a repo's convergence before it promotes. ## Known backlog, not in this promotion The hub's own `.editorconfig`, `.gitattributes` and `.gitignore` carry 44 comment-shape findings, which downstream repos inherit by copying them and reading them for house style. #485 works around it by telling agents to trust the rule text over a carried file's formatting. Cleaning those three files is owed and deliberately separate. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
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.
The Blog standup (#456) produced a repo with no instruction set at all, then authored under no rules. This closes the gap that allowed it.
What actually happened
Checked against the live tree at
/home/pieter/Blog:.editorconfig,.editorconfig-checker.json,.gitattributes,.gitignoreAGENTS.md,GOVERNANCE.md,CODESTYLE.md,WORKFLOW.md,AUDIT.md,README.md,HISTORY.md,.github/copilot-instructions.md,.markdownlint-cli2.jsonc,cspell.json,version.jsonFour mechanical config files landed, every authority was skipped, and roughly 1,300 files were then authored or imported. Running
prose_lint.pyagainst its authored tree gives 237 findings (comment-wrap, comment-case, dupword) across 28 files, topped bydeploy/make-release.shat 74 andchecks/build-redirects.pyat 59.Why step 2 permitted it
Step 2 says to copy every applicable
spec/files.jsonentry and treats the baseline as one undifferentiated list. It is two kinds of file:An agent reading step 2 as a copy list reasonably carries what git and the editor need immediately and gets on with building the repo. Nothing marked the difference.
This is the same shape as step 0 (#481): signing must be live before the first commit, not retrofitted. Governance must be loaded before the first authored file, for the same reason — the window closes quietly and the repair is expensive out of proportion to the prevention. Blog is now facing rework of every tooling file it wrote.
The change
Step 1A stops the procedure until the instruction set is carried and read, before any repo content is authored. It also requires
.markdownlint-cli2.jsoncandcspell.jsonas the mechanical half, since a repo carrying the prose authorities without the linter configs has guidance and no gate. Their absence in Blog is exactly why the comment style drifted unchecked rather than failing a run.The step says to read the rules, not merely place the files, since comment shape, one sentence per line, US spelling and the character rules all govern the code about to be written.
A contributing cause that is ours, not the agent's
The hub's own
.editorconfig,.gitattributesand.gitignorecarry 44 comment-wrap and comment-case findings. Blog's adapted copies carry 37 of the same, inherited rather than introduced. A repo that copies those files and reads them for house style learns the shape the rules forbid:So step 1A now says to treat the rule text as the authority and never to infer style from a carried file's formatting. Cleaning those three files is a separate hub backlog item, deliberately not bundled here.
Not in this change
The
content/question is settled the other way and is worth recording so nobody "fixes" it: I checked for British spellings across Blog's authored tree and found zero, and acrosscontent/only two instances of "amongst" in 113 files. That corpus is a sixteen-year imported archive including third-party comments, deliberately out of scope per the provenance table in #456. A spelling sweep there would corrupt provenance rather than improve style, and the correction posted to #456 says so explicitly.Verification
STANDUP.mdreports zero on all prose rules, markdownlint and editorconfig-checker are clean, and the diff is additive (16 insertions, 0 deletions) with line endings intact.