From 766b822a2c2511a740be56414b48208b997d447e Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Fri, 28 Aug 2026 20:31:04 -0700 Subject: [PATCH 1/3] Add CLAUDE.md bridge so Claude Code actually loads AGENTS.md Claude Code reads CLAUDE.md, not AGENTS.md, at all - confirmed against current official docs. This repo (and every fleet repo carrying AGENTS.md as its provider-agnostic instruction file, precisely so Codex, opencode, and Claude Code read the same rules with no per-provider duplication) never actually reached Claude Code sessions automatically: AGENTS.md only surfaced when an agent chose to read it mid-task, which is the reliability gap behind agents repeatedly skipping the local-strict-review Skill unless explicitly reminded. Adds a root CLAUDE.md using Claude Code's official @AGENTS.md import syntax (confirmed: works anywhere in the file, not just as the first line), a new spec/files.json baseline entry (verbatim, whole, appliesTo *, same shape as .markdownlint-cli2.jsonc), and updates to STANDUP.md's carry list, RESYNC.md's apply-order step 1 and guard- probe scope, and GOVERNANCE.md's own Repository Layout bullet list. --- CLAUDE.md | 10 ++++++++++ GOVERNANCE.md | 1 + RESYNC.md | 2 +- STANDUP.md | 4 +++- spec/files.json | 1 + 5 files changed, 16 insertions(+), 2 deletions(-) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..54f11b12 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,10 @@ +# Claude Code Entry Point + +@AGENTS.md + +Claude Code reads `CLAUDE.md`, not `AGENTS.md`, so a repo carrying only `AGENTS.md` never +reaches a Claude Code session on its own, the import line above is what makes it load. Every +rule lives in `AGENTS.md` and `GOVERNANCE.md`, which are provider-agnostic by design so Codex +and opencode read the same rules with no separate copy. Do not add content here beyond the +import line, a Claude-specific addition would be exactly the per-provider duplication those two +files exist to avoid. diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 9982cfef..cc652655 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -300,6 +300,7 @@ Every repo's GitHub repository details (the About panel) follow a fixed conventi ## Repository Layout - [`AGENTS.md`](./AGENTS.md): the agent entry point, carrying context and delegation rules plus the map to the sections below. +- [`CLAUDE.md`](./CLAUDE.md): imports `AGENTS.md`, since Claude Code reads `CLAUDE.md` and never `AGENTS.md` on its own. Carries no rule of its own. - [`GOVERNANCE.md`](./GOVERNANCE.md), [`CODESTYLE.md`](./CODESTYLE.md), [`WORKFLOW.md`](./WORKFLOW.md), [`AUDIT.md`](./AUDIT.md): the governance and audit docs. This file is the cross-cutting-rules authority. - [`spec/`](./spec/): the machine-readable ground truth, covering project-type requirements, the file/section baseline, secrets, the host tool contract and its floors, and the preferred README structure. - [`registry/repos.json`](./registry/repos.json): the fleet registry, holding every project, its type(s), and its status. diff --git a/RESYNC.md b/RESYNC.md index cb1fc438..5fd91fa5 100644 --- a/RESYNC.md +++ b/RESYNC.md @@ -71,7 +71,7 @@ python3 spec/fidelity_honesty.py --report # regenerate reports/divergences The order is load-bearing. Each step below either changes the rules the later steps are judged against, or removes something a later step would otherwise refresh. -1. **The instruction set first.** `AGENTS.md` and `GOVERNANCE.md` verbatim sections, then `CODESTYLE.md` and `WORKFLOW.md`. `AGENTS.md`'s skill-dependency pointer paragraph, naming `scripts/skills_install.py` and where the fleet's Skills live, carries as one more verbatim unit in this same step, not a separate pass. These are the rules for producing every other file, so carrying them last means everything touched beforehand was judged against the previous revision. This is the same closing-window shape as [`STANDUP.md`][standup] section 1A, and the cost of getting it wrong is rework proportional to how much was changed first. **Run the `carried-instruction-file-guard` skill's distinctive-phrase probe before any verbatim re-vendor in this step, every time, without exception.** A diff that looks routine is exactly the shape the AGENTS.md-overwrite incident took, so the probe is not weighed against how routine the request sounds, it runs regardless. `resync-a-repo` packages this whole step, and the rest of this section, as a Skill for a hub-context session driving the resync. +1. **The instruction set first.** `CLAUDE.md`, then `AGENTS.md` and `GOVERNANCE.md` verbatim sections, then `CODESTYLE.md` and `WORKFLOW.md`. `CLAUDE.md` is the single `@AGENTS.md`-import file that gets `AGENTS.md` into a Claude Code session's context at all, so a repo carrying `AGENTS.md` without it is still a partial carry for that provider even though `spec/files.json` lists them as separate entries. `AGENTS.md`'s skill-dependency pointer paragraph, naming `scripts/skills_install.py` and where the fleet's Skills live, carries as one more verbatim unit in this same step, not a separate pass. These are the rules for producing every other file, so carrying them last means everything touched beforehand was judged against the previous revision. This is the same closing-window shape as [`STANDUP.md`][standup] section 1A, and the cost of getting it wrong is rework proportional to how much was changed first. **Run the `carried-instruction-file-guard` skill's distinctive-phrase probe before any verbatim re-vendor of `AGENTS.md`, `GOVERNANCE.md`, `CODESTYLE.md`, or `WORKFLOW.md` in this step, every time, without exception.** A diff that looks routine is exactly the shape the AGENTS.md-overwrite incident took, so the probe is not weighed against how routine the request sounds, it runs regardless. `CLAUDE.md` carries no mixed or repo-specific content by design, so it takes the guard's own "safe to overwrite" exemption instead, the same footing as `.markdownlint-cli2.jsonc`. `resync-a-repo` packages this whole step, and the rest of this section, as a Skill for a hub-context session driving the resync. 2. **Deletions second, before any re-vendor.** A `hub-only:` finding names a file the hub hosts rather than carries, and its remedy removes the file. Doing it after the re-vendors means refreshing a copy that is about to be deleted, which is wasted work that also reads as a deliberate update in the diff. See section 4, which is the whole of what deletion means here. 3. **Verbatim re-vendors.** Copy the current hub canonical down, whole file or the one named `## heading` region. A finding classified **stale** matches a past hub revision and needs no judgment. One classified **modified** matches no revision, so the repository changed fixed content and the change is read before it is overwritten, since it may be an improvement the hub should adopt instead. Run `python3 scripts/carry.py check --target /path/to/worktree` for manifest-owned trees. Read each modified-file diff and every extra path before running the same command with `apply`. The tree declaration supplies the prune authority, so the carried-instruction-file guard does not apply to this fully owned content. diff --git a/STANDUP.md b/STANDUP.md index 47bf1559..c62c7a74 100644 --- a/STANDUP.md +++ b/STANDUP.md @@ -127,7 +127,8 @@ This is the same shape as step 0. Signing has to be live before the first commit 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. +- [`CLAUDE.md`][claude-md], [`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. +- **`CLAUDE.md` is not optional decoration.** Claude Code reads `CLAUDE.md`, not `AGENTS.md`, so a repo carrying `AGENTS.md` alone never gets it into a Claude Code session's context at all, only into whatever an agent chooses to read on its own initiative mid-task, which is exactly the reliability gap that motivated carrying this file. It is a fixed, `verbatim`, whole-file carry with no repo-specific content: a single `@AGENTS.md` import line plus a short paragraph explaining why, never a place to add Claude-only rules (that duplication is what `AGENTS.md`/`GOVERNANCE.md` being provider-agnostic exists to avoid, so Codex and opencode keep reading the same rules with no separate copy). - **`.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. @@ -240,6 +241,7 @@ The same [`AUDIT.md`][audit] run is the on-demand audit for any known repo, and [agents]: ./AGENTS.md [audit]: ./AUDIT.md +[claude-md]: ./CLAUDE.md [codestyle]: ./CODESTYLE.md [content-import]: ./docs/content-import.md [divergences]: ./spec/divergences.json diff --git a/spec/files.json b/spec/files.json index 7703dc8c..891677b1 100644 --- a/spec/files.json +++ b/spec/files.json @@ -5,6 +5,7 @@ { "source": ".github/skills", "target": ".github/skills", "fidelity": "verbatim-tree", "appliesTo": "*", "include": ["**/*"], "prune": true } ], "baseline": [ + { "path": "CLAUDE.md", "fidelity": "verbatim", "whole": true, "appliesTo": "*" }, { "path": "AGENTS.md", "fidelity": "intent", "sections": [{ "name": "Fleet Bootstrap", "fidelity": "verbatim" }, { "name": "Context and Delegation Discipline", "fidelity": "verbatim" }, { "name": "Where the Rules Live", "fidelity": "verbatim" }], "intentRef": "AGENTS.md", "appliesTo": "*" }, { "path": "GOVERNANCE.md", "fidelity": "intent", "sections": [{ "name": "Foundational Principles", "fidelity": "verbatim" }, { "name": "Durable Knowledge and Self-Improvement", "fidelity": "verbatim" }, { "name": "Repository Boundaries and Write Safety", "fidelity": "verbatim" }, { "name": "Representative Data in Agent-Authored Text", "fidelity": "verbatim" }, { "name": "Git and Commit Rules", "fidelity": "verbatim" }, { "name": "Branching Model", "fidelity": "verbatim" }, { "name": "Release Model", "fidelity": "verbatim" }, { "name": "Operational Repositories", "fidelity": "verbatim" }, { "name": "Hub-Hosted Tooling", "fidelity": "verbatim" }, { "name": "Pull Request Title and Commit Message Conventions", "fidelity": "verbatim" }, { "name": "Documentation Style Conventions", "fidelity": "verbatim" }, { "name": "Verification Discipline", "fidelity": "verbatim" }, { "name": "PR Review Etiquette", "fidelity": "verbatim" }, { "name": "Communicating with the User", "fidelity": "verbatim" }, { "name": "Workflow YAML Conventions", "fidelity": "verbatim" }, { "name": "Supported Development Platforms", "fidelity": "verbatim" }, { "name": "Devcontainer", "fidelity": "intent" }, { "name": "Editor and Tasks", "fidelity": "verbatim" }, { "name": "Repository Details", "fidelity": "verbatim" }, { "name": "Repository Layout", "fidelity": "intent" }], "intentRef": "GOVERNANCE.md", "appliesTo": "*" }, From 42a23013162bcdf45a922904a8ec8a713c38ba80 Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Fri, 28 Aug 2026 20:52:08 -0700 Subject: [PATCH 2/3] Fix review findings: stop restating policy, close a resync-skill gap CodeRabbit and Qodo caught real problems on the first round: - CLAUDE.md's paragraph both understated the rule map (omitted CODESTYLE.md/WORKFLOW.md) and restated AGENTS.md's own provider-agnostic/no-duplication policy, a cross-cutting-rule duplication AGENTS.md's own opening line forbids. Trimmed to the mechanical loading fact plus a pointer, matching GOVERNANCE.md's own 'carries no rule of its own' description of this file exactly. - STANDUP.md's new bullet restated the same policy; trimmed to operational facts, pointing at CLAUDE.md itself. Also fixed a present-tense slip Copilot caught ('motivated' -> 'motivates'). - RESYNC.md overstated what carried-instruction-file-guard actually says (it never names CLAUDE.md or defines an exemption for it); reworded to state CLAUDE.md is simply outside that guard's scope. - resync-a-repo/SKILL.md's own executable apply-order never mentioned CLAUDE.md at all, so a Skill-driven resync would silently skip it. Added it to step 1, regenerated the two mirrored copies. Local-strict-review caught two more before push: step 3's wording still made CLAUDE.md's re-vendor depend on a probe step 1 explicitly exempts it from (fixed), and a line-wrap artifact from an earlier edit (fixed). --- .agents/skills/resync-a-repo/SKILL.md | 30 +++++++++++-------- .claude-plugin/fleet-skills/.source-digest | 2 +- .../skills/resync-a-repo/SKILL.md | 30 +++++++++++-------- .github/skills/resync-a-repo/SKILL.md | 30 +++++++++++-------- CLAUDE.md | 9 ++---- RESYNC.md | 2 +- STANDUP.md | 2 +- 7 files changed, 60 insertions(+), 45 deletions(-) diff --git a/.agents/skills/resync-a-repo/SKILL.md b/.agents/skills/resync-a-repo/SKILL.md index 50930639..d3462533 100644 --- a/.agents/skills/resync-a-repo/SKILL.md +++ b/.agents/skills/resync-a-repo/SKILL.md @@ -49,21 +49,27 @@ Preserve the evidence RESYNC.md section 2 requires, and do not leave the finding ## Apply, in this order -1. **The instruction set first.** `AGENTS.md` and `GOVERNANCE.md` verbatim sections, then - `CODESTYLE.md` and `WORKFLOW.md`, including the `AGENTS.md` skill-dependency pointer paragraph - (naming `scripts/skills_install.py` and where the fleet's Skills live) as one more verbatim - unit carried in this same step, not a separate pass. **Before any verbatim re-vendor in this - step, run the `carried-instruction-file-guard` skill's distinctive-phrase probe against the - target file, every time, without exception.** This is not advisory language to weigh against - how routine the diff looks, a diff that looks routine is exactly the shape the - AGENTS.md-overwrite incident took. Do not proceed to the re-vendor until the probe has run and - any local addition it finds has a destination, per that skill's own procedure. +1. **The instruction set first.** `CLAUDE.md`, then `AGENTS.md` and `GOVERNANCE.md` verbatim + sections, then `CODESTYLE.md` and `WORKFLOW.md`, including the `AGENTS.md` skill-dependency + pointer paragraph (naming `scripts/skills_install.py` and where the fleet's Skills live) as + one more verbatim unit carried in this same step, not a separate pass. `CLAUDE.md` is the + single `@AGENTS.md`-import file that gets `AGENTS.md` into a Claude Code session's context at + all, a separate baseline entry from `AGENTS.md` itself, so carrying one without the other + still leaves that provider unconfigured. **Before any verbatim re-vendor of `AGENTS.md`, + `GOVERNANCE.md`, `CODESTYLE.md`, or `WORKFLOW.md` in this step, run the + `carried-instruction-file-guard` skill's distinctive-phrase probe against the target file, + every time, without exception.** This is not advisory language to weigh against how routine + the diff looks, a diff that looks routine is exactly the shape the AGENTS.md-overwrite + incident took. Do not proceed to the re-vendor until the probe has run and any local addition + it finds has a destination, per that skill's own procedure. `CLAUDE.md` is outside that + guard's scope: it carries no mixed or repo-specific content by design, so its re-vendor is an + ordinary verbatim-fidelity copy, no probe needed. 2. **Deletions second, before any re-vendor.** Only a `retire` disposition in `spec/divergences.json` authorizes removing a file, and the removal is swept tree-wide, per RESYNC.md section 4, before the deletion counts as done. -3. **Verbatim re-vendors** for everything the probe in step 1 cleared. A finding classified - modified rather than stale gets its diff read before being overwritten, since it may be an - improvement the hub should adopt instead of a mistake to erase. +3. **Verbatim re-vendors** for `CLAUDE.md` and everything else the probe in step 1 cleared. A + finding classified modified rather than stale gets its diff read before being overwritten, + since it may be an improvement the hub should adopt instead of a mistake to erase. 4. **Interface workflows.** Honor the named contract, required jobs, the ruleset-bound check name, the artifact-name handoff, rather than copying bytes. 5. **Settings, rulesets, and secrets.** Run diff --git a/.claude-plugin/fleet-skills/.source-digest b/.claude-plugin/fleet-skills/.source-digest index f470fe62..172323e0 100644 --- a/.claude-plugin/fleet-skills/.source-digest +++ b/.claude-plugin/fleet-skills/.source-digest @@ -1 +1 @@ -4dbdf71167625f52 +8cedd0e8eeeff215 diff --git a/.claude-plugin/fleet-skills/skills/resync-a-repo/SKILL.md b/.claude-plugin/fleet-skills/skills/resync-a-repo/SKILL.md index 50930639..d3462533 100644 --- a/.claude-plugin/fleet-skills/skills/resync-a-repo/SKILL.md +++ b/.claude-plugin/fleet-skills/skills/resync-a-repo/SKILL.md @@ -49,21 +49,27 @@ Preserve the evidence RESYNC.md section 2 requires, and do not leave the finding ## Apply, in this order -1. **The instruction set first.** `AGENTS.md` and `GOVERNANCE.md` verbatim sections, then - `CODESTYLE.md` and `WORKFLOW.md`, including the `AGENTS.md` skill-dependency pointer paragraph - (naming `scripts/skills_install.py` and where the fleet's Skills live) as one more verbatim - unit carried in this same step, not a separate pass. **Before any verbatim re-vendor in this - step, run the `carried-instruction-file-guard` skill's distinctive-phrase probe against the - target file, every time, without exception.** This is not advisory language to weigh against - how routine the diff looks, a diff that looks routine is exactly the shape the - AGENTS.md-overwrite incident took. Do not proceed to the re-vendor until the probe has run and - any local addition it finds has a destination, per that skill's own procedure. +1. **The instruction set first.** `CLAUDE.md`, then `AGENTS.md` and `GOVERNANCE.md` verbatim + sections, then `CODESTYLE.md` and `WORKFLOW.md`, including the `AGENTS.md` skill-dependency + pointer paragraph (naming `scripts/skills_install.py` and where the fleet's Skills live) as + one more verbatim unit carried in this same step, not a separate pass. `CLAUDE.md` is the + single `@AGENTS.md`-import file that gets `AGENTS.md` into a Claude Code session's context at + all, a separate baseline entry from `AGENTS.md` itself, so carrying one without the other + still leaves that provider unconfigured. **Before any verbatim re-vendor of `AGENTS.md`, + `GOVERNANCE.md`, `CODESTYLE.md`, or `WORKFLOW.md` in this step, run the + `carried-instruction-file-guard` skill's distinctive-phrase probe against the target file, + every time, without exception.** This is not advisory language to weigh against how routine + the diff looks, a diff that looks routine is exactly the shape the AGENTS.md-overwrite + incident took. Do not proceed to the re-vendor until the probe has run and any local addition + it finds has a destination, per that skill's own procedure. `CLAUDE.md` is outside that + guard's scope: it carries no mixed or repo-specific content by design, so its re-vendor is an + ordinary verbatim-fidelity copy, no probe needed. 2. **Deletions second, before any re-vendor.** Only a `retire` disposition in `spec/divergences.json` authorizes removing a file, and the removal is swept tree-wide, per RESYNC.md section 4, before the deletion counts as done. -3. **Verbatim re-vendors** for everything the probe in step 1 cleared. A finding classified - modified rather than stale gets its diff read before being overwritten, since it may be an - improvement the hub should adopt instead of a mistake to erase. +3. **Verbatim re-vendors** for `CLAUDE.md` and everything else the probe in step 1 cleared. A + finding classified modified rather than stale gets its diff read before being overwritten, + since it may be an improvement the hub should adopt instead of a mistake to erase. 4. **Interface workflows.** Honor the named contract, required jobs, the ruleset-bound check name, the artifact-name handoff, rather than copying bytes. 5. **Settings, rulesets, and secrets.** Run diff --git a/.github/skills/resync-a-repo/SKILL.md b/.github/skills/resync-a-repo/SKILL.md index 50930639..d3462533 100644 --- a/.github/skills/resync-a-repo/SKILL.md +++ b/.github/skills/resync-a-repo/SKILL.md @@ -49,21 +49,27 @@ Preserve the evidence RESYNC.md section 2 requires, and do not leave the finding ## Apply, in this order -1. **The instruction set first.** `AGENTS.md` and `GOVERNANCE.md` verbatim sections, then - `CODESTYLE.md` and `WORKFLOW.md`, including the `AGENTS.md` skill-dependency pointer paragraph - (naming `scripts/skills_install.py` and where the fleet's Skills live) as one more verbatim - unit carried in this same step, not a separate pass. **Before any verbatim re-vendor in this - step, run the `carried-instruction-file-guard` skill's distinctive-phrase probe against the - target file, every time, without exception.** This is not advisory language to weigh against - how routine the diff looks, a diff that looks routine is exactly the shape the - AGENTS.md-overwrite incident took. Do not proceed to the re-vendor until the probe has run and - any local addition it finds has a destination, per that skill's own procedure. +1. **The instruction set first.** `CLAUDE.md`, then `AGENTS.md` and `GOVERNANCE.md` verbatim + sections, then `CODESTYLE.md` and `WORKFLOW.md`, including the `AGENTS.md` skill-dependency + pointer paragraph (naming `scripts/skills_install.py` and where the fleet's Skills live) as + one more verbatim unit carried in this same step, not a separate pass. `CLAUDE.md` is the + single `@AGENTS.md`-import file that gets `AGENTS.md` into a Claude Code session's context at + all, a separate baseline entry from `AGENTS.md` itself, so carrying one without the other + still leaves that provider unconfigured. **Before any verbatim re-vendor of `AGENTS.md`, + `GOVERNANCE.md`, `CODESTYLE.md`, or `WORKFLOW.md` in this step, run the + `carried-instruction-file-guard` skill's distinctive-phrase probe against the target file, + every time, without exception.** This is not advisory language to weigh against how routine + the diff looks, a diff that looks routine is exactly the shape the AGENTS.md-overwrite + incident took. Do not proceed to the re-vendor until the probe has run and any local addition + it finds has a destination, per that skill's own procedure. `CLAUDE.md` is outside that + guard's scope: it carries no mixed or repo-specific content by design, so its re-vendor is an + ordinary verbatim-fidelity copy, no probe needed. 2. **Deletions second, before any re-vendor.** Only a `retire` disposition in `spec/divergences.json` authorizes removing a file, and the removal is swept tree-wide, per RESYNC.md section 4, before the deletion counts as done. -3. **Verbatim re-vendors** for everything the probe in step 1 cleared. A finding classified - modified rather than stale gets its diff read before being overwritten, since it may be an - improvement the hub should adopt instead of a mistake to erase. +3. **Verbatim re-vendors** for `CLAUDE.md` and everything else the probe in step 1 cleared. A + finding classified modified rather than stale gets its diff read before being overwritten, + since it may be an improvement the hub should adopt instead of a mistake to erase. 4. **Interface workflows.** Honor the named contract, required jobs, the ruleset-bound check name, the artifact-name handoff, rather than copying bytes. 5. **Settings, rulesets, and secrets.** Run diff --git a/CLAUDE.md b/CLAUDE.md index 54f11b12..2c0757bd 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,9 +2,6 @@ @AGENTS.md -Claude Code reads `CLAUDE.md`, not `AGENTS.md`, so a repo carrying only `AGENTS.md` never -reaches a Claude Code session on its own, the import line above is what makes it load. Every -rule lives in `AGENTS.md` and `GOVERNANCE.md`, which are provider-agnostic by design so Codex -and opencode read the same rules with no separate copy. Do not add content here beyond the -import line, a Claude-specific addition would be exactly the per-provider duplication those two -files exist to avoid. +Claude Code reads `CLAUDE.md`, not `AGENTS.md`, so the import line above is what gets this +repository's rules into a Claude Code session at all. See `AGENTS.md` for what is authoritative +and why. This file carries no rule of its own, and adds none beyond the import line. diff --git a/RESYNC.md b/RESYNC.md index 5fd91fa5..d1924c4d 100644 --- a/RESYNC.md +++ b/RESYNC.md @@ -71,7 +71,7 @@ python3 spec/fidelity_honesty.py --report # regenerate reports/divergences The order is load-bearing. Each step below either changes the rules the later steps are judged against, or removes something a later step would otherwise refresh. -1. **The instruction set first.** `CLAUDE.md`, then `AGENTS.md` and `GOVERNANCE.md` verbatim sections, then `CODESTYLE.md` and `WORKFLOW.md`. `CLAUDE.md` is the single `@AGENTS.md`-import file that gets `AGENTS.md` into a Claude Code session's context at all, so a repo carrying `AGENTS.md` without it is still a partial carry for that provider even though `spec/files.json` lists them as separate entries. `AGENTS.md`'s skill-dependency pointer paragraph, naming `scripts/skills_install.py` and where the fleet's Skills live, carries as one more verbatim unit in this same step, not a separate pass. These are the rules for producing every other file, so carrying them last means everything touched beforehand was judged against the previous revision. This is the same closing-window shape as [`STANDUP.md`][standup] section 1A, and the cost of getting it wrong is rework proportional to how much was changed first. **Run the `carried-instruction-file-guard` skill's distinctive-phrase probe before any verbatim re-vendor of `AGENTS.md`, `GOVERNANCE.md`, `CODESTYLE.md`, or `WORKFLOW.md` in this step, every time, without exception.** A diff that looks routine is exactly the shape the AGENTS.md-overwrite incident took, so the probe is not weighed against how routine the request sounds, it runs regardless. `CLAUDE.md` carries no mixed or repo-specific content by design, so it takes the guard's own "safe to overwrite" exemption instead, the same footing as `.markdownlint-cli2.jsonc`. `resync-a-repo` packages this whole step, and the rest of this section, as a Skill for a hub-context session driving the resync. +1. **The instruction set first.** `CLAUDE.md`, then `AGENTS.md` and `GOVERNANCE.md` verbatim sections, then `CODESTYLE.md` and `WORKFLOW.md`. `CLAUDE.md` is the single `@AGENTS.md`-import file that gets `AGENTS.md` into a Claude Code session's context at all, so a repo carrying `AGENTS.md` without it is still a partial carry for that provider even though `spec/files.json` lists them as separate entries. `AGENTS.md`'s skill-dependency pointer paragraph, naming `scripts/skills_install.py` and where the fleet's Skills live, carries as one more verbatim unit in this same step, not a separate pass. These are the rules for producing every other file, so carrying them last means everything touched beforehand was judged against the previous revision. This is the same closing-window shape as [`STANDUP.md`][standup] section 1A, and the cost of getting it wrong is rework proportional to how much was changed first. **Run the `carried-instruction-file-guard` skill's distinctive-phrase probe before any verbatim re-vendor of `AGENTS.md`, `GOVERNANCE.md`, `CODESTYLE.md`, or `WORKFLOW.md` in this step, every time, without exception.** A diff that looks routine is exactly the shape the AGENTS.md-overwrite incident took, so the probe is not weighed against how routine the request sounds, it runs regardless. `CLAUDE.md` is outside that guard's scope entirely, the same as any file the guard was never written to cover: it carries no mixed or repo-specific content by design, so its own re-vendor is an ordinary verbatim-fidelity copy, no probe needed. `resync-a-repo` packages this whole step, and the rest of this section, as a Skill for a hub-context session driving the resync. 2. **Deletions second, before any re-vendor.** A `hub-only:` finding names a file the hub hosts rather than carries, and its remedy removes the file. Doing it after the re-vendors means refreshing a copy that is about to be deleted, which is wasted work that also reads as a deliberate update in the diff. See section 4, which is the whole of what deletion means here. 3. **Verbatim re-vendors.** Copy the current hub canonical down, whole file or the one named `## heading` region. A finding classified **stale** matches a past hub revision and needs no judgment. One classified **modified** matches no revision, so the repository changed fixed content and the change is read before it is overwritten, since it may be an improvement the hub should adopt instead. Run `python3 scripts/carry.py check --target /path/to/worktree` for manifest-owned trees. Read each modified-file diff and every extra path before running the same command with `apply`. The tree declaration supplies the prune authority, so the carried-instruction-file guard does not apply to this fully owned content. diff --git a/STANDUP.md b/STANDUP.md index c62c7a74..6b7b08d2 100644 --- a/STANDUP.md +++ b/STANDUP.md @@ -128,7 +128,7 @@ This is the same shape as step 0. Signing has to be live before the first commit Carry these before writing any repo content of your own: - [`CLAUDE.md`][claude-md], [`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. -- **`CLAUDE.md` is not optional decoration.** Claude Code reads `CLAUDE.md`, not `AGENTS.md`, so a repo carrying `AGENTS.md` alone never gets it into a Claude Code session's context at all, only into whatever an agent chooses to read on its own initiative mid-task, which is exactly the reliability gap that motivated carrying this file. It is a fixed, `verbatim`, whole-file carry with no repo-specific content: a single `@AGENTS.md` import line plus a short paragraph explaining why, never a place to add Claude-only rules (that duplication is what `AGENTS.md`/`GOVERNANCE.md` being provider-agnostic exists to avoid, so Codex and opencode keep reading the same rules with no separate copy). +- **`CLAUDE.md` is not optional decoration.** Claude Code reads `CLAUDE.md`, not `AGENTS.md`, so a repo carrying `AGENTS.md` alone never gets it into a Claude Code session's context at all, only into whatever an agent chooses to read on its own initiative mid-task, which is exactly the reliability gap that motivates carrying this file. It is a fixed, `verbatim`, whole-file carry with no repo-specific content, see `CLAUDE.md` itself for what belongs in it and what does not. - **`.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. From 99235861d785a4c77a4d8efd61aff00e2f763c7c Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Fri, 28 Aug 2026 21:09:49 -0700 Subject: [PATCH 3/3] Close a probe scope hole, add CLAUDE.md to standup-a-repo, fix a comma splice CodeRabbit caught a real scope hole an earlier fix introduced: gating the carried-instruction-file-guard probe on 'any verbatim re-vendor' of the four instruction files silently excludes CODESTYLE.md and WORKFLOW.md, which are intent-fidelity and never re-vendored verbatim, so they'd never trigger the probe at all. Reworded both RESYNC.md and resync-a-repo/SKILL.md to gate on touching the file, not on the update being verbatim. Also: standup-a-repo/SKILL.md's own executable instruction-set step never mentioned CLAUDE.md, the standup equivalent of the resync-skill gap fixed earlier in this PR - added it, regenerated mirrors. Fixed a comma splice in STANDUP.md's CLAUDE.md bullet. --- .agents/skills/resync-a-repo/SKILL.md | 8 ++++---- .agents/skills/standup-a-repo/SKILL.md | 11 +++++++---- .claude-plugin/fleet-skills/.source-digest | 2 +- .../fleet-skills/skills/resync-a-repo/SKILL.md | 8 ++++---- .../fleet-skills/skills/standup-a-repo/SKILL.md | 11 +++++++---- .github/skills/resync-a-repo/SKILL.md | 8 ++++---- .github/skills/standup-a-repo/SKILL.md | 11 +++++++---- RESYNC.md | 2 +- STANDUP.md | 2 +- 9 files changed, 36 insertions(+), 27 deletions(-) diff --git a/.agents/skills/resync-a-repo/SKILL.md b/.agents/skills/resync-a-repo/SKILL.md index d3462533..e5573fd3 100644 --- a/.agents/skills/resync-a-repo/SKILL.md +++ b/.agents/skills/resync-a-repo/SKILL.md @@ -55,10 +55,10 @@ Preserve the evidence RESYNC.md section 2 requires, and do not leave the finding one more verbatim unit carried in this same step, not a separate pass. `CLAUDE.md` is the single `@AGENTS.md`-import file that gets `AGENTS.md` into a Claude Code session's context at all, a separate baseline entry from `AGENTS.md` itself, so carrying one without the other - still leaves that provider unconfigured. **Before any verbatim re-vendor of `AGENTS.md`, - `GOVERNANCE.md`, `CODESTYLE.md`, or `WORKFLOW.md` in this step, run the - `carried-instruction-file-guard` skill's distinctive-phrase probe against the target file, - every time, without exception.** This is not advisory language to weigh against how routine + still leaves that provider unconfigured. **Before touching `AGENTS.md`, `GOVERNANCE.md`, + `CODESTYLE.md`, or `WORKFLOW.md` in this step, run the `carried-instruction-file-guard` + skill's distinctive-phrase probe against the target file, every time, without exception, + regardless of whether the update is a verbatim re-vendor or an intent-fidelity edit.** This is not advisory language to weigh against how routine the diff looks, a diff that looks routine is exactly the shape the AGENTS.md-overwrite incident took. Do not proceed to the re-vendor until the probe has run and any local addition it finds has a destination, per that skill's own procedure. `CLAUDE.md` is outside that diff --git a/.agents/skills/standup-a-repo/SKILL.md b/.agents/skills/standup-a-repo/SKILL.md index f9d2b4f5..363d6bb3 100644 --- a/.agents/skills/standup-a-repo/SKILL.md +++ b/.agents/skills/standup-a-repo/SKILL.md @@ -51,10 +51,13 @@ maintainer can supply what section 0A lists. section 2, then write or repair its `registry/repos.json` entry and confirm it with `spec/validate.py`. -4. **The instruction set, before authoring anything.** STANDUP.md section 1A: carry `AGENTS.md`, - `GOVERNANCE.md`, `CODESTYLE.md`, `WORKFLOW.md` and `AUDIT.md`, adapted rather than cloned for - the ones that describe a repo, plus `.markdownlint-cli2.jsonc` and `cspell.json`. Read - `CODESTYLE.md` and the `GOVERNANCE.md` documentation-style rules before writing any repo +4. **The instruction set, before authoring anything.** STANDUP.md section 1A: carry `CLAUDE.md`, + `AGENTS.md`, `GOVERNANCE.md`, `CODESTYLE.md`, `WORKFLOW.md` and `AUDIT.md`, adapted rather + than cloned for the ones that describe a repo, plus `.markdownlint-cli2.jsonc` and + `cspell.json`. `CLAUDE.md` is the fixed, verbatim `@AGENTS.md`-import file that gets + `AGENTS.md` into a Claude Code session's context at all, a separate baseline entry from + `AGENTS.md` itself, so carrying one without the other still leaves that provider unconfigured. + Read `CODESTYLE.md` and the `GOVERNANCE.md` documentation-style rules before writing any repo content of your own, the same window-closes shape as signing in step 1. 5. **Capture the source, if one exists.** STANDUP.md section 1B, only when the repo's content diff --git a/.claude-plugin/fleet-skills/.source-digest b/.claude-plugin/fleet-skills/.source-digest index 627ee5c1..7591ad72 100644 --- a/.claude-plugin/fleet-skills/.source-digest +++ b/.claude-plugin/fleet-skills/.source-digest @@ -1 +1 @@ -f33693f0118de8c8 +79146733e388bff5 diff --git a/.claude-plugin/fleet-skills/skills/resync-a-repo/SKILL.md b/.claude-plugin/fleet-skills/skills/resync-a-repo/SKILL.md index d3462533..e5573fd3 100644 --- a/.claude-plugin/fleet-skills/skills/resync-a-repo/SKILL.md +++ b/.claude-plugin/fleet-skills/skills/resync-a-repo/SKILL.md @@ -55,10 +55,10 @@ Preserve the evidence RESYNC.md section 2 requires, and do not leave the finding one more verbatim unit carried in this same step, not a separate pass. `CLAUDE.md` is the single `@AGENTS.md`-import file that gets `AGENTS.md` into a Claude Code session's context at all, a separate baseline entry from `AGENTS.md` itself, so carrying one without the other - still leaves that provider unconfigured. **Before any verbatim re-vendor of `AGENTS.md`, - `GOVERNANCE.md`, `CODESTYLE.md`, or `WORKFLOW.md` in this step, run the - `carried-instruction-file-guard` skill's distinctive-phrase probe against the target file, - every time, without exception.** This is not advisory language to weigh against how routine + still leaves that provider unconfigured. **Before touching `AGENTS.md`, `GOVERNANCE.md`, + `CODESTYLE.md`, or `WORKFLOW.md` in this step, run the `carried-instruction-file-guard` + skill's distinctive-phrase probe against the target file, every time, without exception, + regardless of whether the update is a verbatim re-vendor or an intent-fidelity edit.** This is not advisory language to weigh against how routine the diff looks, a diff that looks routine is exactly the shape the AGENTS.md-overwrite incident took. Do not proceed to the re-vendor until the probe has run and any local addition it finds has a destination, per that skill's own procedure. `CLAUDE.md` is outside that diff --git a/.claude-plugin/fleet-skills/skills/standup-a-repo/SKILL.md b/.claude-plugin/fleet-skills/skills/standup-a-repo/SKILL.md index f9d2b4f5..363d6bb3 100644 --- a/.claude-plugin/fleet-skills/skills/standup-a-repo/SKILL.md +++ b/.claude-plugin/fleet-skills/skills/standup-a-repo/SKILL.md @@ -51,10 +51,13 @@ maintainer can supply what section 0A lists. section 2, then write or repair its `registry/repos.json` entry and confirm it with `spec/validate.py`. -4. **The instruction set, before authoring anything.** STANDUP.md section 1A: carry `AGENTS.md`, - `GOVERNANCE.md`, `CODESTYLE.md`, `WORKFLOW.md` and `AUDIT.md`, adapted rather than cloned for - the ones that describe a repo, plus `.markdownlint-cli2.jsonc` and `cspell.json`. Read - `CODESTYLE.md` and the `GOVERNANCE.md` documentation-style rules before writing any repo +4. **The instruction set, before authoring anything.** STANDUP.md section 1A: carry `CLAUDE.md`, + `AGENTS.md`, `GOVERNANCE.md`, `CODESTYLE.md`, `WORKFLOW.md` and `AUDIT.md`, adapted rather + than cloned for the ones that describe a repo, plus `.markdownlint-cli2.jsonc` and + `cspell.json`. `CLAUDE.md` is the fixed, verbatim `@AGENTS.md`-import file that gets + `AGENTS.md` into a Claude Code session's context at all, a separate baseline entry from + `AGENTS.md` itself, so carrying one without the other still leaves that provider unconfigured. + Read `CODESTYLE.md` and the `GOVERNANCE.md` documentation-style rules before writing any repo content of your own, the same window-closes shape as signing in step 1. 5. **Capture the source, if one exists.** STANDUP.md section 1B, only when the repo's content diff --git a/.github/skills/resync-a-repo/SKILL.md b/.github/skills/resync-a-repo/SKILL.md index d3462533..e5573fd3 100644 --- a/.github/skills/resync-a-repo/SKILL.md +++ b/.github/skills/resync-a-repo/SKILL.md @@ -55,10 +55,10 @@ Preserve the evidence RESYNC.md section 2 requires, and do not leave the finding one more verbatim unit carried in this same step, not a separate pass. `CLAUDE.md` is the single `@AGENTS.md`-import file that gets `AGENTS.md` into a Claude Code session's context at all, a separate baseline entry from `AGENTS.md` itself, so carrying one without the other - still leaves that provider unconfigured. **Before any verbatim re-vendor of `AGENTS.md`, - `GOVERNANCE.md`, `CODESTYLE.md`, or `WORKFLOW.md` in this step, run the - `carried-instruction-file-guard` skill's distinctive-phrase probe against the target file, - every time, without exception.** This is not advisory language to weigh against how routine + still leaves that provider unconfigured. **Before touching `AGENTS.md`, `GOVERNANCE.md`, + `CODESTYLE.md`, or `WORKFLOW.md` in this step, run the `carried-instruction-file-guard` + skill's distinctive-phrase probe against the target file, every time, without exception, + regardless of whether the update is a verbatim re-vendor or an intent-fidelity edit.** This is not advisory language to weigh against how routine the diff looks, a diff that looks routine is exactly the shape the AGENTS.md-overwrite incident took. Do not proceed to the re-vendor until the probe has run and any local addition it finds has a destination, per that skill's own procedure. `CLAUDE.md` is outside that diff --git a/.github/skills/standup-a-repo/SKILL.md b/.github/skills/standup-a-repo/SKILL.md index f9d2b4f5..363d6bb3 100644 --- a/.github/skills/standup-a-repo/SKILL.md +++ b/.github/skills/standup-a-repo/SKILL.md @@ -51,10 +51,13 @@ maintainer can supply what section 0A lists. section 2, then write or repair its `registry/repos.json` entry and confirm it with `spec/validate.py`. -4. **The instruction set, before authoring anything.** STANDUP.md section 1A: carry `AGENTS.md`, - `GOVERNANCE.md`, `CODESTYLE.md`, `WORKFLOW.md` and `AUDIT.md`, adapted rather than cloned for - the ones that describe a repo, plus `.markdownlint-cli2.jsonc` and `cspell.json`. Read - `CODESTYLE.md` and the `GOVERNANCE.md` documentation-style rules before writing any repo +4. **The instruction set, before authoring anything.** STANDUP.md section 1A: carry `CLAUDE.md`, + `AGENTS.md`, `GOVERNANCE.md`, `CODESTYLE.md`, `WORKFLOW.md` and `AUDIT.md`, adapted rather + than cloned for the ones that describe a repo, plus `.markdownlint-cli2.jsonc` and + `cspell.json`. `CLAUDE.md` is the fixed, verbatim `@AGENTS.md`-import file that gets + `AGENTS.md` into a Claude Code session's context at all, a separate baseline entry from + `AGENTS.md` itself, so carrying one without the other still leaves that provider unconfigured. + Read `CODESTYLE.md` and the `GOVERNANCE.md` documentation-style rules before writing any repo content of your own, the same window-closes shape as signing in step 1. 5. **Capture the source, if one exists.** STANDUP.md section 1B, only when the repo's content diff --git a/RESYNC.md b/RESYNC.md index d1924c4d..2fb374be 100644 --- a/RESYNC.md +++ b/RESYNC.md @@ -71,7 +71,7 @@ python3 spec/fidelity_honesty.py --report # regenerate reports/divergences The order is load-bearing. Each step below either changes the rules the later steps are judged against, or removes something a later step would otherwise refresh. -1. **The instruction set first.** `CLAUDE.md`, then `AGENTS.md` and `GOVERNANCE.md` verbatim sections, then `CODESTYLE.md` and `WORKFLOW.md`. `CLAUDE.md` is the single `@AGENTS.md`-import file that gets `AGENTS.md` into a Claude Code session's context at all, so a repo carrying `AGENTS.md` without it is still a partial carry for that provider even though `spec/files.json` lists them as separate entries. `AGENTS.md`'s skill-dependency pointer paragraph, naming `scripts/skills_install.py` and where the fleet's Skills live, carries as one more verbatim unit in this same step, not a separate pass. These are the rules for producing every other file, so carrying them last means everything touched beforehand was judged against the previous revision. This is the same closing-window shape as [`STANDUP.md`][standup] section 1A, and the cost of getting it wrong is rework proportional to how much was changed first. **Run the `carried-instruction-file-guard` skill's distinctive-phrase probe before any verbatim re-vendor of `AGENTS.md`, `GOVERNANCE.md`, `CODESTYLE.md`, or `WORKFLOW.md` in this step, every time, without exception.** A diff that looks routine is exactly the shape the AGENTS.md-overwrite incident took, so the probe is not weighed against how routine the request sounds, it runs regardless. `CLAUDE.md` is outside that guard's scope entirely, the same as any file the guard was never written to cover: it carries no mixed or repo-specific content by design, so its own re-vendor is an ordinary verbatim-fidelity copy, no probe needed. `resync-a-repo` packages this whole step, and the rest of this section, as a Skill for a hub-context session driving the resync. +1. **The instruction set first.** `CLAUDE.md`, then `AGENTS.md` and `GOVERNANCE.md` verbatim sections, then `CODESTYLE.md` and `WORKFLOW.md`. `CLAUDE.md` is the single `@AGENTS.md`-import file that gets `AGENTS.md` into a Claude Code session's context at all, so a repo carrying `AGENTS.md` without it is still a partial carry for that provider even though `spec/files.json` lists them as separate entries. `AGENTS.md`'s skill-dependency pointer paragraph, naming `scripts/skills_install.py` and where the fleet's Skills live, carries as one more verbatim unit in this same step, not a separate pass. These are the rules for producing every other file, so carrying them last means everything touched beforehand was judged against the previous revision. This is the same closing-window shape as [`STANDUP.md`][standup] section 1A, and the cost of getting it wrong is rework proportional to how much was changed first. **Run the `carried-instruction-file-guard` skill's distinctive-phrase probe before touching `AGENTS.md`, `GOVERNANCE.md`, `CODESTYLE.md`, or `WORKFLOW.md` in this step, every time, without exception, regardless of whether the update is a verbatim re-vendor or an intent-fidelity edit.** A diff that looks routine is exactly the shape the AGENTS.md-overwrite incident took, so the probe is not weighed against how routine the request sounds, it runs regardless. `CLAUDE.md` is outside that guard's scope entirely, the same as any file the guard was never written to cover: it carries no mixed or repo-specific content by design, so its own re-vendor is an ordinary verbatim-fidelity copy, no probe needed. `resync-a-repo` packages this whole step, and the rest of this section, as a Skill for a hub-context session driving the resync. 2. **Deletions second, before any re-vendor.** A `hub-only:` finding names a file the hub hosts rather than carries, and its remedy removes the file. Doing it after the re-vendors means refreshing a copy that is about to be deleted, which is wasted work that also reads as a deliberate update in the diff. See section 4, which is the whole of what deletion means here. 3. **Verbatim re-vendors.** Copy the current hub canonical down, whole file or the one named `## heading` region. A finding classified **stale** matches a past hub revision and needs no judgment. One classified **modified** matches no revision, so the repository changed fixed content and the change is read before it is overwritten, since it may be an improvement the hub should adopt instead. Run `python3 scripts/carry.py check --target /path/to/worktree` for manifest-owned trees. Read each modified-file diff and every extra path before running the same command with `apply`. The tree declaration supplies the prune authority, so the carried-instruction-file guard does not apply to this fully owned content. diff --git a/STANDUP.md b/STANDUP.md index 6b7b08d2..4617bd78 100644 --- a/STANDUP.md +++ b/STANDUP.md @@ -128,7 +128,7 @@ This is the same shape as step 0. Signing has to be live before the first commit Carry these before writing any repo content of your own: - [`CLAUDE.md`][claude-md], [`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. -- **`CLAUDE.md` is not optional decoration.** Claude Code reads `CLAUDE.md`, not `AGENTS.md`, so a repo carrying `AGENTS.md` alone never gets it into a Claude Code session's context at all, only into whatever an agent chooses to read on its own initiative mid-task, which is exactly the reliability gap that motivates carrying this file. It is a fixed, `verbatim`, whole-file carry with no repo-specific content, see `CLAUDE.md` itself for what belongs in it and what does not. +- **`CLAUDE.md` is not optional decoration.** Claude Code reads `CLAUDE.md`, not `AGENTS.md`, so a repo carrying `AGENTS.md` alone never gets it into a Claude Code session's context at all, only into whatever an agent chooses to read on its own initiative mid-task, which is exactly the reliability gap that motivates carrying this file. It is a fixed, `verbatim`, whole-file carry with no repo-specific content. See `CLAUDE.md` itself for what belongs in it and what does not. - **`.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.