Name where repo-specific content goes when standing up a repo - #480
Merged
Conversation
STANDUP.md step 2 said to copy the spec/files.json entries and stopped, so it covered what a repo carries and left no destination for what only that repo knows. The destinations exist in spec/section-model.md, but nothing on the scaffolding path points at them: STANDUP.md never mentioned them, AGENTS.md has no arrow to them, and the one pointer from spec/files.json is framed as a per-section fidelity question rather than as where a runbook lives. By this file's own self-test standard that is a documentation defect: a context-free agent cannot stand up an operational repo from these docs alone if nothing tells it where the deploy runbook goes. Blog is the first operational repo with substantial runbooks and would have hit it, putting repo-specific prose into a carried file and creating drift to reconcile. Step 2 now names the three destinations (CODESTYLE.md, ARCHITECTURE.md, OPERATIONS.md) with the rule that the choice is what the content is, plus the note that OPERATIONS.md takes the inline-link exception. AGENTS.md is deliberately untouched: its "Where the Rules Live" section is verbatim fleet-law, so adding the pointer there would re-vendor across the fleet and is a separate decision. Two corrections ride along. The baseline list named repo-config/develop.json without its operational variant, which is exactly wrong for the repo shape this change serves. And the file's own dash and semicolon backlog is cleared, per the standing rule that existing prose is corrected as each file is next edited; both headings were checked for inbound anchors first and have none. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the hub-only STANDUP.md onboarding/scaffolding procedure to explicitly direct agents to the correct destinations for repo-specific (non-carried) content, reducing drift and preventing repo-local runbooks/architecture notes from being placed into carried fleet-law files.
Changes:
- Adds explicit guidance (and
spec/section-model.mdpointer) for where repo-specific content must live:CODESTYLE.md,ARCHITECTURE.md, orOPERATIONS.md. - Corrects/clarifies baseline ruleset payload guidance for
operationalworkflow model repos and applies minor prose/heading punctuation cleanups.
Uh oh!
There was an error while loading. Please reload this page.
The parenthetical read as "(main.json plus develop.json), or operational/develop.json", which parses as though an operational repo carries no main.json at all. It carries one: repo-config/main.json is appliesTo "*", and only the develop payload varies by workflow model. Stated as its own sentence rather than a clause nested inside the baseline list, since the first fix put a relative clause in the middle of a comma series and made the list itself hard to follow. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.
Suppressed comments (1)
STANDUP.md:13
- Step 2 says to copy
spec/files.jsonentries that apply to the repo’s types, butspec/files.jsonuses broaderappliesToscope selectors (includingrelease/operational, which are workflow-model selectors). As written, this can mislead readers into ignoring non-type selectors even though they’re part of what must be carried.
Copy every [`spec/files.json`][files] entry that applies to the repo's types (the `appliesTo: "*"` baseline plus the per-type additions), **adapted, not cloned**. The prose files (`CODESTYLE.md`, `README.md`, and the like) describe the repo's own toolchain, so adapt them to reality rather than propagating template specifics verbatim (see the "Adapt before propagating" callout in [`CODESTYLE.md`][codestyle], since a verbatim copy that misdescribes the repo is rejected in review). The baseline covers `WORKFLOW.md`, `version.json`, the two rulesets, `.github/dependabot.yml`, `.editorconfig`, `.gitattributes`, the linter configs, and the per-type files (`.vscode/tasks.json` from the language's snippet, `codecov.yml`, `.dockerignore`, `Docker/README.md`). **Every repo carries `repo-config/main.json`**, and only the `develop` payload varies by workflow model: `repo-config/develop.json` for a release repo, `repo-config/operational/develop.json` for an operational one.
Step 2 said to copy every spec/files.json entry "that applies to the repo's types". Types are one of four disjoint selector namespaces. A repo's selector set is its types plus workflowModel, releaseTrigger and consumerModel (spec/scope-model.md), so an agent filtering on type alone drops every entry a non-type selector carries. The concrete casualty is the entry this change exists to surface: repo-config/operational/develop.json is appliesTo ["operational"], a workflow-model selector, so a type-only reading skips the one ruleset an operational repo needs. AUDIT.md section 3 already states the rule correctly; this file did not. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
ptr727
commented
Jul 31, 2026
OwnerAuthor
Round 2 suppressed finding: accepted and fixed in 1ee741a. The finding was right, and it is the third instance of the same root cause this PR exists to address. Step 2 said to copy every Verified against the spec rather than taken on faith. The concrete casualty is the exact entry this PR exists to surface: Step 2 now reads: copy every entry whose Worth recording that this was a suppressed comment with no thread, so a thread-only poll would have reported this PR clean with a real defect standing. That is precisely the gap #477 was built to close, working as intended two PRs later. |
Uh oh!
There was an error while loading. Please reload this page.
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 freeto 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.
STANDUP.mdstep 2 said to copy thespec/files.jsonentries and stopped. That covers what a repo carries and leaves no destination for what only that repo knows.The gap
The destinations do exist, in
spec/section-model.mdunder "Where repo-specific content goes". Nothing on the scaffolding path points at them:STANDUP.mdnever mentioned them. Step 2 is the exact moment an agent decides what goes where.AGENTS.mdhas no arrow to them either (zero hits forOPERATIONSorsection-model).spec/files.jsonnote, is framed as "the per-section fidelity ofAGENTS.mdandGOVERNANCE.md... is defined inspec/section-model.md". Nothing in that phrasing signals "this is where you learn where your runbooks live."By this file's own self-test standard that is a documentation defect, not a nicety: the docs are sufficient only if a context-free agent stands up each shape from them alone, and one cannot stand up an
operationalrepo without being told where the deploy runbook goes. Blog (#456) is the first operational repo with substantial runbooks (deploy, rollback, retention prune, credential rotation) and would have hit it, landing repo-specific prose in a carried file and creating drift to reconcile later.The change
Step 2 now names the three destinations and the rule that the choice is decided by what the content is, not per repo:
CODESTYLE.mdARCHITECTURE.mdOPERATIONS.mdPlus the note that
OPERATIONS.mdtakes the inline-link exception rather than the reference-style default, since it is one of the four agent-instruction filesGOVERNANCE.mdnames.AGENTS.mdis deliberately untouched. Its "Where the Rules Live" section isverbatimfleet-law perspec/section-model.md, so adding the pointer there would re-vendor across the whole fleet. That is a separate decision, not a drive-by.Two corrections riding along
repo-config/develop.jsonwithout its operational variant. Anoperationalrepo carriesrepo-config/operational/develop.json, and the release one applies the wrong ruleset, which is exactly wrong for the repo shape this change serves.STANDUP.mdis hub-only, so this creates no re-vendor debt. Both headings that took a colon (5. VerifyandSelf-Test) were checked for inbound anchors first and have none.Verification
STANDUP.mdreports zero on all eight prose rules and markdownlint is clean over it. The full 180-casescripts/suite,scripts/repo_gate.py,spec/validate.pyandspec/audit.py --selftestpass, and the blocking prose run is clean tree-wide.🤖 Generated with Claude Code