From 51173553907638b64a7c35a39696d7b505f37f60 Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Fri, 28 Aug 2026 19:48:09 -0700 Subject: [PATCH 1/6] Reference AGENTS.md's Unresolved-Rule Line Instead of Copying It (#1074) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fixes #1070. `local-strict-review/SKILL.md`'s subagent-briefing template copied the closing sentence of `AGENTS.md`'s own template ("If a rule you were given does not cover what you find, stop and report it. Do not guess, and do not read a governance file to resolve it.") verbatim into its fenced instantiation, instead of only referencing it. That risks silent drift if `AGENTS.md`'s template wording changes later. Fix: dropped the copied line from the fenced template block, added one prose sentence outside the fence pointing at `AGENTS.md`'s own template line instead. Applied to the canonical source (`.agents/skills/local-strict-review/SKILL.md`) and regenerated the two mirrored copies (`.claude-plugin/fleet-skills/`, `.github/skills/`) via `scripts/build_dist.py`. Ran `local-strict-review` against this branch's own diff before pushing (dogfooding it, per the issue's own subject): it confirmed the fix's core claim (the referenced line is verbatim-present in `AGENTS.md`) and caught one real prose-convention slip — the new sentence was hard-wrapped across two physical lines, the one paragraph in the file breaking its own single-line-per-paragraph convention (`.markdownlint-cli2.jsonc` disables MD013 deliberately for this file's long-paragraph style). Fixed before this push. `scripts/build_dist.py --check`, `scripts/prose_lint.py`, `scripts/repo_gate.py`, and `scripts/host_gate.py` all pass. ## Summary by CodeRabbit * **Documentation** * Updated review guidance to improve briefing formatting and clarify how unresolved rules are communicated. * Standardized instructions across supported review workflows for a more consistent review experience. * Clarified the expected closing statement when applicable rules do not fully resolve a finding. * **Chores** * Refreshed supporting metadata to keep workflow resources synchronized. --- .agents/skills/local-strict-review/SKILL.md | 4 ++-- .claude-plugin/fleet-skills/.source-digest | 2 +- .../fleet-skills/skills/local-strict-review/SKILL.md | 4 ++-- .github/skills/local-strict-review/SKILL.md | 4 ++-- 4 files changed, 7 insertions(+), 7 deletions(-) diff --git a/.agents/skills/local-strict-review/SKILL.md b/.agents/skills/local-strict-review/SKILL.md index 7a2eb75f..ba5dfbe6 100644 --- a/.agents/skills/local-strict-review/SKILL.md +++ b/.agents/skills/local-strict-review/SKILL.md @@ -48,8 +48,8 @@ Rules that bind this task: quote `code-review`'s "Review the Change" section int the Return line below, not a PR comment or a coverage marker. Return: one finding per line, file:line, the concrete failure scenario, no severity theater. Bounds: read-only. No edit, no stage, no commit, no push, no PR-hosted write of any kind. -If a rule you were given does not cover what you find, stop and report it. Do not guess, and do - not read a governance file to resolve it. +Close with the unresolved-rule closing line from `AGENTS.md` "Context and Delegation + Discipline", referenced rather than restated here. ``` **Model tier:** the strongest tier this session can reach, per `AGENTS.md` "Match the model tier to the judgment" and "Never tier down the seat holding the judgment", applied here to the reviewer rather than the author. Run the pass on the same tier that authored the change when only one tier is reachable, a second, adversarially-prompted look still catches what the authoring pass's own "looks ready" judgment did not. diff --git a/.claude-plugin/fleet-skills/.source-digest b/.claude-plugin/fleet-skills/.source-digest index c7e837e4..e1971e55 100644 --- a/.claude-plugin/fleet-skills/.source-digest +++ b/.claude-plugin/fleet-skills/.source-digest @@ -1 +1 @@ -8cab4f8afbf9a439 +126057363d858c0a diff --git a/.claude-plugin/fleet-skills/skills/local-strict-review/SKILL.md b/.claude-plugin/fleet-skills/skills/local-strict-review/SKILL.md index 7a2eb75f..ba5dfbe6 100644 --- a/.claude-plugin/fleet-skills/skills/local-strict-review/SKILL.md +++ b/.claude-plugin/fleet-skills/skills/local-strict-review/SKILL.md @@ -48,8 +48,8 @@ Rules that bind this task: quote `code-review`'s "Review the Change" section int the Return line below, not a PR comment or a coverage marker. Return: one finding per line, file:line, the concrete failure scenario, no severity theater. Bounds: read-only. No edit, no stage, no commit, no push, no PR-hosted write of any kind. -If a rule you were given does not cover what you find, stop and report it. Do not guess, and do - not read a governance file to resolve it. +Close with the unresolved-rule closing line from `AGENTS.md` "Context and Delegation + Discipline", referenced rather than restated here. ``` **Model tier:** the strongest tier this session can reach, per `AGENTS.md` "Match the model tier to the judgment" and "Never tier down the seat holding the judgment", applied here to the reviewer rather than the author. Run the pass on the same tier that authored the change when only one tier is reachable, a second, adversarially-prompted look still catches what the authoring pass's own "looks ready" judgment did not. diff --git a/.github/skills/local-strict-review/SKILL.md b/.github/skills/local-strict-review/SKILL.md index 7a2eb75f..ba5dfbe6 100644 --- a/.github/skills/local-strict-review/SKILL.md +++ b/.github/skills/local-strict-review/SKILL.md @@ -48,8 +48,8 @@ Rules that bind this task: quote `code-review`'s "Review the Change" section int the Return line below, not a PR comment or a coverage marker. Return: one finding per line, file:line, the concrete failure scenario, no severity theater. Bounds: read-only. No edit, no stage, no commit, no push, no PR-hosted write of any kind. -If a rule you were given does not cover what you find, stop and report it. Do not guess, and do - not read a governance file to resolve it. +Close with the unresolved-rule closing line from `AGENTS.md` "Context and Delegation + Discipline", referenced rather than restated here. ``` **Model tier:** the strongest tier this session can reach, per `AGENTS.md` "Match the model tier to the judgment" and "Never tier down the seat holding the judgment", applied here to the reviewer rather than the author. Run the pass on the same tier that authored the change when only one tier is reachable, a second, adversarially-prompted look still catches what the authoring pass's own "looks ready" judgment did not. From bbc9b8f45a9a812aee6dfd7b472523792ef9b10f Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Fri, 28 Aug 2026 20:07:51 -0700 Subject: [PATCH 2/6] Give the Closing-Reference Line Its Own Template Field (#1079) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Follow-up to #1074 (issue #1070), found by the develop -> main promotion PR (#1077)'s own review. Copilot sharpened Qodo's earlier ambiguity finding on the same line: the closing-reference sentence sat inside the fenced subagent-brief template with no field-name prefix, unlike the template's other five fields (Task/Paths/Rules that bind this task/Return/Bounds), so it read as literal content handed to the subagent rather than an instruction to whoever assembles the brief — and the subagent has no access to `AGENTS.md` to resolve it. Fix: gave it its own `Close:` field, phrased the same way line 45 already resolves the identical pattern (inserting canonical content into the prompt at assembly time rather than restating it): `quote X into the prompt`. Ran `local-strict-review` against this branch's diff before pushing; no blocking findings (one purely stylistic comma-splice nit, not a rule violation, left as-is). ## Summary by CodeRabbit * **Documentation** * Updated review guidance to require quoting the exact unresolved-rule closing line, “Context and Delegation Discipline,” rather than referring to it indirectly. * Synchronized the same instruction across all distributed review guidance. * Refreshed associated source metadata to reflect the updated guidance. --- .agents/skills/local-strict-review/SKILL.md | 4 ++-- .claude-plugin/fleet-skills/.source-digest | 2 +- .../fleet-skills/skills/local-strict-review/SKILL.md | 4 ++-- .github/skills/local-strict-review/SKILL.md | 4 ++-- 4 files changed, 7 insertions(+), 7 deletions(-) diff --git a/.agents/skills/local-strict-review/SKILL.md b/.agents/skills/local-strict-review/SKILL.md index ba5dfbe6..27f1238e 100644 --- a/.agents/skills/local-strict-review/SKILL.md +++ b/.agents/skills/local-strict-review/SKILL.md @@ -48,8 +48,8 @@ Rules that bind this task: quote `code-review`'s "Review the Change" section int the Return line below, not a PR comment or a coverage marker. Return: one finding per line, file:line, the concrete failure scenario, no severity theater. Bounds: read-only. No edit, no stage, no commit, no push, no PR-hosted write of any kind. -Close with the unresolved-rule closing line from `AGENTS.md` "Context and Delegation - Discipline", referenced rather than restated here. +Close: quote `AGENTS.md`'s own unresolved-rule closing line ("Context and Delegation + Discipline") into the prompt, do not restate it here. ``` **Model tier:** the strongest tier this session can reach, per `AGENTS.md` "Match the model tier to the judgment" and "Never tier down the seat holding the judgment", applied here to the reviewer rather than the author. Run the pass on the same tier that authored the change when only one tier is reachable, a second, adversarially-prompted look still catches what the authoring pass's own "looks ready" judgment did not. diff --git a/.claude-plugin/fleet-skills/.source-digest b/.claude-plugin/fleet-skills/.source-digest index e1971e55..f470fe62 100644 --- a/.claude-plugin/fleet-skills/.source-digest +++ b/.claude-plugin/fleet-skills/.source-digest @@ -1 +1 @@ -126057363d858c0a +4dbdf71167625f52 diff --git a/.claude-plugin/fleet-skills/skills/local-strict-review/SKILL.md b/.claude-plugin/fleet-skills/skills/local-strict-review/SKILL.md index ba5dfbe6..27f1238e 100644 --- a/.claude-plugin/fleet-skills/skills/local-strict-review/SKILL.md +++ b/.claude-plugin/fleet-skills/skills/local-strict-review/SKILL.md @@ -48,8 +48,8 @@ Rules that bind this task: quote `code-review`'s "Review the Change" section int the Return line below, not a PR comment or a coverage marker. Return: one finding per line, file:line, the concrete failure scenario, no severity theater. Bounds: read-only. No edit, no stage, no commit, no push, no PR-hosted write of any kind. -Close with the unresolved-rule closing line from `AGENTS.md` "Context and Delegation - Discipline", referenced rather than restated here. +Close: quote `AGENTS.md`'s own unresolved-rule closing line ("Context and Delegation + Discipline") into the prompt, do not restate it here. ``` **Model tier:** the strongest tier this session can reach, per `AGENTS.md` "Match the model tier to the judgment" and "Never tier down the seat holding the judgment", applied here to the reviewer rather than the author. Run the pass on the same tier that authored the change when only one tier is reachable, a second, adversarially-prompted look still catches what the authoring pass's own "looks ready" judgment did not. diff --git a/.github/skills/local-strict-review/SKILL.md b/.github/skills/local-strict-review/SKILL.md index ba5dfbe6..27f1238e 100644 --- a/.github/skills/local-strict-review/SKILL.md +++ b/.github/skills/local-strict-review/SKILL.md @@ -48,8 +48,8 @@ Rules that bind this task: quote `code-review`'s "Review the Change" section int the Return line below, not a PR comment or a coverage marker. Return: one finding per line, file:line, the concrete failure scenario, no severity theater. Bounds: read-only. No edit, no stage, no commit, no push, no PR-hosted write of any kind. -Close with the unresolved-rule closing line from `AGENTS.md` "Context and Delegation - Discipline", referenced rather than restated here. +Close: quote `AGENTS.md`'s own unresolved-rule closing line ("Context and Delegation + Discipline") into the prompt, do not restate it here. ``` **Model tier:** the strongest tier this session can reach, per `AGENTS.md` "Match the model tier to the judgment" and "Never tier down the seat holding the judgment", applied here to the reviewer rather than the author. Run the pass on the same tier that authored the change when only one tier is reachable, a second, adversarially-prompted look still catches what the authoring pass's own "looks ready" judgment did not. From c702afb4dab8a667a94e0621ac12b13a2fcdffec Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Fri, 28 Aug 2026 20:55:29 -0700 Subject: [PATCH 3/6] Drop the Close Field, Match AGENTS.md's Own Unlabeled Shape (#1080) Follow-up to #1074/#1079 (issue #1070), found by the develop -> main promotion PR (#1077)'s second review round. Copilot flagged the `Close:` field #1079 introduced as a non-canonical key: `AGENTS.md`'s own template ("Context and Delegation Discipline") has exactly 5 labeled fields (Task/Paths/Rules that bind this task/Return/Bounds) followed by one unlabeled trailing sentence, not a 6th labeled field. `local-strict-review/SKILL.md`'s own "Running It" section says to follow that exact shape. Round 1 fix (commit 2778010): dropped the `Close:` label, went back to an unlabeled trailing line in the same position `AGENTS.md`'s own closing sentence occupies, kept #1079's "quote X into the prompt" phrasing. A fresh Copilot round then flagged that this still read as an imperative instruction addressed to the subagent, who cannot fulfil it (no AGENTS.md access) - the same ambiguity #1079 had already addressed once. Round 2 fix (commit 2faa0e0, current): replaced the imperative sentence with an explicit angle-bracket placeholder, matching `AGENTS.md`'s own template syntax exactly (which uses `<...>` for every field value). This is the second use of that convention in this file, not a new one - `` already appears the same way at line 40. Fails safe if pasted unsubstituted: an obvious unfilled token rather than a misleading instruction. Ran `local-strict-review` against this branch's diff before each push, explicitly asked to hunt for a reason a further round could still be needed. Round 2's review: no confirmed defect, and a specific, honest assessment of why this shape is unlikely to bounce again (matches an established in-file convention, fails safe, closes every prior round's concern simultaneously). --- .agents/skills/local-strict-review/SKILL.md | 4 ++-- .claude-plugin/fleet-skills/.source-digest | 2 +- .../fleet-skills/skills/local-strict-review/SKILL.md | 4 ++-- .github/skills/local-strict-review/SKILL.md | 4 ++-- 4 files changed, 7 insertions(+), 7 deletions(-) diff --git a/.agents/skills/local-strict-review/SKILL.md b/.agents/skills/local-strict-review/SKILL.md index 27f1238e..2349271d 100644 --- a/.agents/skills/local-strict-review/SKILL.md +++ b/.agents/skills/local-strict-review/SKILL.md @@ -48,8 +48,8 @@ Rules that bind this task: quote `code-review`'s "Review the Change" section int the Return line below, not a PR comment or a coverage marker. Return: one finding per line, file:line, the concrete failure scenario, no severity theater. Bounds: read-only. No edit, no stage, no commit, no push, no PR-hosted write of any kind. -Close: quote `AGENTS.md`'s own unresolved-rule closing line ("Context and Delegation - Discipline") into the prompt, do not restate it here. + ``` **Model tier:** the strongest tier this session can reach, per `AGENTS.md` "Match the model tier to the judgment" and "Never tier down the seat holding the judgment", applied here to the reviewer rather than the author. Run the pass on the same tier that authored the change when only one tier is reachable, a second, adversarially-prompted look still catches what the authoring pass's own "looks ready" judgment did not. diff --git a/.claude-plugin/fleet-skills/.source-digest b/.claude-plugin/fleet-skills/.source-digest index f470fe62..39a139f0 100644 --- a/.claude-plugin/fleet-skills/.source-digest +++ b/.claude-plugin/fleet-skills/.source-digest @@ -1 +1 @@ -4dbdf71167625f52 +2044c888625ec970 diff --git a/.claude-plugin/fleet-skills/skills/local-strict-review/SKILL.md b/.claude-plugin/fleet-skills/skills/local-strict-review/SKILL.md index 27f1238e..2349271d 100644 --- a/.claude-plugin/fleet-skills/skills/local-strict-review/SKILL.md +++ b/.claude-plugin/fleet-skills/skills/local-strict-review/SKILL.md @@ -48,8 +48,8 @@ Rules that bind this task: quote `code-review`'s "Review the Change" section int the Return line below, not a PR comment or a coverage marker. Return: one finding per line, file:line, the concrete failure scenario, no severity theater. Bounds: read-only. No edit, no stage, no commit, no push, no PR-hosted write of any kind. -Close: quote `AGENTS.md`'s own unresolved-rule closing line ("Context and Delegation - Discipline") into the prompt, do not restate it here. + ``` **Model tier:** the strongest tier this session can reach, per `AGENTS.md` "Match the model tier to the judgment" and "Never tier down the seat holding the judgment", applied here to the reviewer rather than the author. Run the pass on the same tier that authored the change when only one tier is reachable, a second, adversarially-prompted look still catches what the authoring pass's own "looks ready" judgment did not. diff --git a/.github/skills/local-strict-review/SKILL.md b/.github/skills/local-strict-review/SKILL.md index 27f1238e..2349271d 100644 --- a/.github/skills/local-strict-review/SKILL.md +++ b/.github/skills/local-strict-review/SKILL.md @@ -48,8 +48,8 @@ Rules that bind this task: quote `code-review`'s "Review the Change" section int the Return line below, not a PR comment or a coverage marker. Return: one finding per line, file:line, the concrete failure scenario, no severity theater. Bounds: read-only. No edit, no stage, no commit, no push, no PR-hosted write of any kind. -Close: quote `AGENTS.md`'s own unresolved-rule closing line ("Context and Delegation - Discipline") into the prompt, do not restate it here. + ``` **Model tier:** the strongest tier this session can reach, per `AGENTS.md` "Match the model tier to the judgment" and "Never tier down the seat holding the judgment", applied here to the reviewer rather than the author. Run the pass on the same tier that authored the change when only one tier is reachable, a second, adversarially-prompted look still catches what the authoring pass's own "looks ready" judgment did not. From 5fcd3783f28426545f9a900d520e44e0556fd8d1 Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Fri, 28 Aug 2026 21:14:28 -0700 Subject: [PATCH 4/6] Add CLAUDE.md Bridge So Claude Code Actually Loads AGENTS.md (#1081) Root cause of a recurring complaint: local-strict-review (and other Skills/rules) not firing reliably unless explicitly told to. Confirmed against current official Claude Code docs: Claude Code reads `CLAUDE.md`, not `AGENTS.md`, at all. This repo (and every fleet repo, per the same convention) carries `AGENTS.md` as its provider-agnostic instruction file specifically so Codex, opencode, and Claude Code all read the same rules with no per-provider duplication - but that design silently failed for Claude Code specifically, since `AGENTS.md` never reached a Claude Code session's context automatically. It only surfaced when an agent chose to read it mid-task, which is exactly the unreliable path this fix closes. Fix: a root `CLAUDE.md` using Claude Code's official `@AGENTS.md` import syntax (confirmed: the import works anywhere in the file, not only as the first line - kept after an H1 heading to satisfy MD041). No duplicated content, one import line plus a short paragraph explaining why, matching the fleet's own don't-duplicate-per-provider design. Also: - New `spec/files.json` baseline entry (`fidelity: verbatim`, `whole: true`, `appliesTo: "*"`), same shape as `.markdownlint-cli2.jsonc` (fleet-generic, no governed per-repo divergence), so `resync-a-repo`/`audit-a-repo` propagate it to every fleet repo over time. - `STANDUP.md`'s "carry the instruction set" list and `RESYNC.md`'s "apply, in this order" step 1 both now name `CLAUDE.md` alongside `AGENTS.md`/`GOVERNANCE.md`/`CODESTYLE.md`/`WORKFLOW.md`, with an explicit carve-out from the `carried-instruction-file-guard` skill's probe (that guard is for mixed verbatim+intent content; `CLAUDE.md` carries none by design, same exemption `.markdownlint-cli2.jsonc` already has). - `GOVERNANCE.md`'s own "Repository Layout" bullet list gains the new root file. Scope note: this fixes the hub itself. Every other fleet repo picks this up at its own next `resync-a-repo`/`audit-a-repo` pass via the new baseline entry, per the existing rollout mechanism - not a manual per-repo sweep in this PR. Local-strict-review dogfooded across two rounds on this branch (findings from round 1 - a missing `GOVERNANCE.md` bullet, an over-broad guard-probe sentence that would have swept in the new exempt file - fixed before round 2 confirmed clean). ## Summary by CodeRabbit * **Documentation** * Added a dedicated Claude Code entry point that references centralized repository guidance. * Updated governance and contributor instructions to include the new entry point. * Clarified synchronization procedures for incomplete guidance files and Claude Code configuration. * **Chores** * Updated the standard repository baseline to preserve the new guidance file consistently. * Improved synchronization safeguards and processing for instruction files. --- .agents/skills/resync-a-repo/SKILL.md | 30 +++++++++++-------- .agents/skills/standup-a-repo/SKILL.md | 11 ++++--- .claude-plugin/fleet-skills/.source-digest | 2 +- .../skills/resync-a-repo/SKILL.md | 30 +++++++++++-------- .../skills/standup-a-repo/SKILL.md | 11 ++++--- .github/skills/resync-a-repo/SKILL.md | 30 +++++++++++-------- .github/skills/standup-a-repo/SKILL.md | 11 ++++--- CLAUDE.md | 7 +++++ GOVERNANCE.md | 1 + RESYNC.md | 2 +- STANDUP.md | 4 ++- spec/files.json | 1 + 12 files changed, 89 insertions(+), 51 deletions(-) create mode 100644 CLAUDE.md diff --git a/.agents/skills/resync-a-repo/SKILL.md b/.agents/skills/resync-a-repo/SKILL.md index 50930639..e5573fd3 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 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 + 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/.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 39a139f0..7591ad72 100644 --- a/.claude-plugin/fleet-skills/.source-digest +++ b/.claude-plugin/fleet-skills/.source-digest @@ -1 +1 @@ -2044c888625ec970 +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 50930639..e5573fd3 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 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 + 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/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 50930639..e5573fd3 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 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 + 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/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/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..2c0757bd --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,7 @@ +# Claude Code Entry Point + +@AGENTS.md + +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/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..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.** `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 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 47bf1559..4617bd78 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 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. @@ -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 b283bb68e70427d4af4a731fb88a1b3e2cb144ca Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Fri, 28 Aug 2026 21:39:15 -0700 Subject: [PATCH 5/6] Fix Mid-Sentence Line Wraps Copilot Caught on the Promotion PR (#1084) Fix-up to #1081, found by the develop -> main promotion PR (#1077)'s fresh full-diff review. CLAUDE.md's intro paragraph and resync-a-repo/SKILL.md's step 1 both had a sentence hard-wrapped across physical lines mid-sentence, against this repo's prose convention (paragraphs and sentences stay on one unwrapped physical line, per .markdownlint-cli2.jsonc disabling MD013 for exactly this). Pure re-flow, no wording changed (verified: `git diff -w --word-diff` shows zero word-level differences). Ran local-strict-review before pushing: confirmed no wording changed, both new sentence/line joins read correctly, mirrors byte-identical. One informational note surfaced (not fixed here, correctly out of scope): the same wrap pattern is pervasive fleet-wide and deliberately unenforced (the sentence-split prose_lint rule is opt-in, same rationale as sentence-length) - not a regression this branch introduced. --- .agents/skills/resync-a-repo/SKILL.md | 16 +--------------- .claude-plugin/fleet-skills/.source-digest | 2 +- .../fleet-skills/skills/resync-a-repo/SKILL.md | 16 +--------------- .github/skills/resync-a-repo/SKILL.md | 16 +--------------- CLAUDE.md | 4 +--- 5 files changed, 5 insertions(+), 49 deletions(-) diff --git a/.agents/skills/resync-a-repo/SKILL.md b/.agents/skills/resync-a-repo/SKILL.md index e5573fd3..9ac991f7 100644 --- a/.agents/skills/resync-a-repo/SKILL.md +++ b/.agents/skills/resync-a-repo/SKILL.md @@ -49,21 +49,7 @@ Preserve the evidence RESYNC.md section 2 requires, and do not leave the finding ## Apply, in this order -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 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 - 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. +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 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 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. diff --git a/.claude-plugin/fleet-skills/.source-digest b/.claude-plugin/fleet-skills/.source-digest index 7591ad72..07afc635 100644 --- a/.claude-plugin/fleet-skills/.source-digest +++ b/.claude-plugin/fleet-skills/.source-digest @@ -1 +1 @@ -79146733e388bff5 +69764939de16d10d 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 e5573fd3..9ac991f7 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,7 @@ Preserve the evidence RESYNC.md section 2 requires, and do not leave the finding ## Apply, in this order -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 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 - 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. +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 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 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. diff --git a/.github/skills/resync-a-repo/SKILL.md b/.github/skills/resync-a-repo/SKILL.md index e5573fd3..9ac991f7 100644 --- a/.github/skills/resync-a-repo/SKILL.md +++ b/.github/skills/resync-a-repo/SKILL.md @@ -49,21 +49,7 @@ Preserve the evidence RESYNC.md section 2 requires, and do not leave the finding ## Apply, in this order -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 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 - 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. +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 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 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. diff --git a/CLAUDE.md b/CLAUDE.md index 2c0757bd..a2c84a14 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,6 +2,4 @@ @AGENTS.md -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. +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. From ff9326915b249a17891f207afed1742c75a1ab57 Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Fri, 28 Aug 2026 21:51:31 -0700 Subject: [PATCH 6/6] Join the Unresolved-Rule Placeholder Onto One Physical Line (#1085) Found by a suppressed Qodo finding (low-confidence, 3x across the mirrored copies) on the develop -> main promotion PR (#1077): local-strict-review/SKILL.md's bracket placeholder was split across two physical lines inside the fenced template, which the finding said hurts copy-paste usability and deviates from AGENTS.md's own single-line closing-sentence shape. Joined onto one physical line, no wording changed (verified: git diff -w --word-diff shows zero word-level differences). Ran local-strict-review before pushing: join point reads cleanly, mirrors byte-identical. One stylistic-only observation surfaced and not acted on: the joined line (123 chars) is now wider than the fence's other five fields, which wrap at ~90-94 chars with a hanging indent to simulate a realistic terminal width. Not a rule violation (no gate checks fence-internal line width) and directly trades off against the reviewer's own explicit one-line request, so left as one line. --- .agents/skills/local-strict-review/SKILL.md | 3 +-- .claude-plugin/fleet-skills/.source-digest | 2 +- .../fleet-skills/skills/local-strict-review/SKILL.md | 3 +-- .github/skills/local-strict-review/SKILL.md | 3 +-- 4 files changed, 4 insertions(+), 7 deletions(-) diff --git a/.agents/skills/local-strict-review/SKILL.md b/.agents/skills/local-strict-review/SKILL.md index 2349271d..cad9a06e 100644 --- a/.agents/skills/local-strict-review/SKILL.md +++ b/.agents/skills/local-strict-review/SKILL.md @@ -48,8 +48,7 @@ Rules that bind this task: quote `code-review`'s "Review the Change" section int the Return line below, not a PR comment or a coverage marker. Return: one finding per line, file:line, the concrete failure scenario, no severity theater. Bounds: read-only. No edit, no stage, no commit, no push, no PR-hosted write of any kind. - + ``` **Model tier:** the strongest tier this session can reach, per `AGENTS.md` "Match the model tier to the judgment" and "Never tier down the seat holding the judgment", applied here to the reviewer rather than the author. Run the pass on the same tier that authored the change when only one tier is reachable, a second, adversarially-prompted look still catches what the authoring pass's own "looks ready" judgment did not. diff --git a/.claude-plugin/fleet-skills/.source-digest b/.claude-plugin/fleet-skills/.source-digest index 07afc635..1254e367 100644 --- a/.claude-plugin/fleet-skills/.source-digest +++ b/.claude-plugin/fleet-skills/.source-digest @@ -1 +1 @@ -69764939de16d10d +7c7db19359804689 diff --git a/.claude-plugin/fleet-skills/skills/local-strict-review/SKILL.md b/.claude-plugin/fleet-skills/skills/local-strict-review/SKILL.md index 2349271d..cad9a06e 100644 --- a/.claude-plugin/fleet-skills/skills/local-strict-review/SKILL.md +++ b/.claude-plugin/fleet-skills/skills/local-strict-review/SKILL.md @@ -48,8 +48,7 @@ Rules that bind this task: quote `code-review`'s "Review the Change" section int the Return line below, not a PR comment or a coverage marker. Return: one finding per line, file:line, the concrete failure scenario, no severity theater. Bounds: read-only. No edit, no stage, no commit, no push, no PR-hosted write of any kind. - + ``` **Model tier:** the strongest tier this session can reach, per `AGENTS.md` "Match the model tier to the judgment" and "Never tier down the seat holding the judgment", applied here to the reviewer rather than the author. Run the pass on the same tier that authored the change when only one tier is reachable, a second, adversarially-prompted look still catches what the authoring pass's own "looks ready" judgment did not. diff --git a/.github/skills/local-strict-review/SKILL.md b/.github/skills/local-strict-review/SKILL.md index 2349271d..cad9a06e 100644 --- a/.github/skills/local-strict-review/SKILL.md +++ b/.github/skills/local-strict-review/SKILL.md @@ -48,8 +48,7 @@ Rules that bind this task: quote `code-review`'s "Review the Change" section int the Return line below, not a PR comment or a coverage marker. Return: one finding per line, file:line, the concrete failure scenario, no severity theater. Bounds: read-only. No edit, no stage, no commit, no push, no PR-hosted write of any kind. - + ``` **Model tier:** the strongest tier this session can reach, per `AGENTS.md` "Match the model tier to the judgment" and "Never tier down the seat holding the judgment", applied here to the reviewer rather than the author. Run the pass on the same tier that authored the change when only one tier is reachable, a second, adversarially-prompted look still catches what the authoring pass's own "looks ready" judgment did not.