From a6c0f9bb6851be66db128ce6030113d3433462c7 Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Fri, 31 Jul 2026 18:31:16 -0700 Subject: [PATCH] Require the instruction set before any authoring 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) --- STANDUP.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/STANDUP.md b/STANDUP.md index 9735c3c0..5602d1fa 100644 --- a/STANDUP.md +++ b/STANDUP.md @@ -38,6 +38,21 @@ After the first commit, confirm it took with `git log -1 --format='%G? author=%a Resolve the repo's type(s) with the [`AUDIT.md`][audit] section 2 detection rules, then write or repair its [`registry/repos.json`][repos] entry: `status`, `types[]`, `groundTruthBranch`, `hasDevelop`, `publish[]`, `requiredSecrets[]`, `consumerModel`, `releaseTrigger`, `workflowModel` (omit to take the `release` default), `configLayout`, and `driftNotes` that describe what the repo **actually is**. Run [`spec/validate.py`][validate] to confirm it classifies cleanly. The registry is ground truth about reality, not intent, and a `validate.py`-clean entry is still false if it disagrees with the live repo. +## 1A. Carry the Instruction Set, Before Authoring Anything + +**Stop here until the instruction set is present and read.** The baseline in step 2 is one list, but it holds two kinds of file, and this kind is not a deliverable. `AGENTS.md`, `GOVERNANCE.md`, `CODESTYLE.md` and `WORKFLOW.md` are **the rules for producing every other file in the repo**, so carrying them late means everything authored beforehand was authored against unknown rules. The cost of that is rework rather than a warning, and it scales with how much got written first. + +This is the same shape as step 0. Signing has to be live before the first commit rather than retrofitted, and governance has to 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. + +Carry these before writing any repo content of your own: + +- [`AGENTS.md`][agents], [`GOVERNANCE.md`][governance], [`CODESTYLE.md`][codestyle], [`WORKFLOW.md`][workflow] and [`AUDIT.md`][audit], adapted rather than cloned for the ones that describe a repo. +- **`.markdownlint-cli2.jsonc` and `cspell.json`**, which are the mechanical half. A rule nothing checks drifts silently, so a repo that carries the prose authorities without the linter configs has guidance and no gate. Scope a linter's **file set in the workflow** rather than relaxing either config, since `.markdownlint-cli2.jsonc` is carried `verbatim`. + +Then **read** `CODESTYLE.md` and the `GOVERNANCE.md` documentation-style rules, rather than only placing the files. Comment shape, one sentence per line, US spelling and the character rules all govern the code and config you are about to write, and none of them are recoverable cheaply afterwards. + +**A caution about learning house style from the carried files.** Some carried configuration still holds comment blocks that predate the current rules, so read the rule text as the authority and do not infer style from a file's existing formatting. Where a carried file and the rules disagree, the rules win and the file is a backlog item for the hub. + ## 2. Carry the Baseline Files Copy every [`spec/files.json`][files] entry whose `appliesTo` matches the repo's **selector set**, **adapted, not cloned**. The selector set is the repo's `types` plus its `workflowModel`, `releaseTrigger`, and `consumerModel`, so filtering on type alone silently drops the entries a non-type selector carries ([`spec/scope-model.md`][scope-model] defines the four namespaces and how they resolve). 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. @@ -88,6 +103,7 @@ The same [`AUDIT.md`][audit] run is the on-demand audit for any known repo, and +[agents]: ./AGENTS.md [audit]: ./AUDIT.md [codestyle]: ./CODESTYLE.md [files]: ./spec/files.json