From b433ff0fb471d7b418f9f508b860e1393538279c Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Fri, 25 Sep 2026 11:32:32 -0700 Subject: [PATCH 1/6] State Who Commits the Audit Report in the Fleet Bootstrap The Fleet Bootstrap told every carrier to "commit the report" without saying the hub authors it, so downstream sessions kept asking for permission to open a hub pull request. Name the hub as the report's author and route downstream findings to hub issues, in the carried section and in the host-wide fleet block, matching AUDIT.md section 8. Co-Authored-By: Claude Opus 5.5 (1M context) --- AGENTS.md | 2 +- host-setup/agent-safety/claude/claude-md-fleet.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 9dc68c01a..fd7fdf271 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -24,7 +24,7 @@ flowchart TD - **No repository yet, or a local tree with no remote.** Follow the hub's `STANDUP.md` from section 0. That file is hub-only and deliberately not carried, because a repository needing it cannot be relied on to hold a current copy. Note that nothing in it creates the GitHub repository, which is an outward-facing write requiring explicit permission, so section 0A is the list handed to the maintainer before anything else starts. - **A repository with no carried instruction set, or a partial one.** Carry the baseline per the hub's `STANDUP.md` sections 1A and 2, which resolve what this repository is owed from its declared types and workflow model. Absent files are not drift to re-vendor, they are a baseline that never arrived, and the two are fixed differently. - **A repository with the instruction set, current or stale.** Follow the hub's `RESYNC.md`, which runs `AUDIT.md` end to end for the findings and then applies each one in an order that matters, since the rules govern what comes after them, a deletion must precede the re-vendor that would otherwise refresh the file, and only some findings are mechanically detectable at all. An audit that reports drift and stops is half the procedure. -- **A repository that believes it is conformant.** Run the audit anyway and commit the report, because conformance asserted without a report is conformance nobody can check. This is the same procedure as the case above and is listed separately only because it is the one most often skipped. +- **A repository that believes it is conformant.** Run the audit anyway, because conformance asserted without a report is conformance nobody can check. The hub commits that report under its own `reports/`, since a report written by the repository it measures is a claim rather than evidence, so a session in the repository being audited never opens a hub pull request to write one and files its findings about the hub as issues instead. This is the same procedure as the case above and is listed separately only because it is the one most often skipped. Three rules bound every path above. **Read the hub's `main` branch as ground truth**, since that is the promoted and gated state, and read `develop` only to detect divergence. **Reach the hub as a checkout of your own and fetch it immediately before reading it**, because a clone is whatever it last fetched rather than the branch it names, and work only in that checkout rather than in one that another task is using, per [`GOVERNANCE.md`](./GOVERNANCE.md) "Repository Boundaries and Write Safety" and "Hub-Hosted Tooling". And **the audit is read-only**: it produces a report and never edits the repository it measures, so a fix is a separate, reviewable change. diff --git a/host-setup/agent-safety/claude/claude-md-fleet.md b/host-setup/agent-safety/claude/claude-md-fleet.md index 4af941609..0dcbd6ae9 100644 --- a/host-setup/agent-safety/claude/claude-md-fleet.md +++ b/host-setup/agent-safety/claude/claude-md-fleet.md @@ -7,6 +7,6 @@ This section enables rather than restricts, so it is bounded by everything above - **Route by what the repository actually holds, not by what it should hold.** The two differ precisely when this matters. No repository yet means the hub's `STANDUP.md` from section 0, and note that nothing in that file creates the GitHub repository, which is an outward-facing write needing explicit permission. A missing or partial instruction set means carrying the baseline per that file's sections 1A and 2, since absent files are a baseline that never arrived rather than drift to re-vendor. An instruction set that is present, current or stale, means the hub's `RESYNC.md`, which runs `AUDIT.md` end to end for the findings and then applies each one in the order that file sets. - **Read the hub's `main` branch as ground truth**, since that is the promoted and gated state, and read `develop` only to detect divergence. The same holds for a repository being audited, for both workflow models. -- **The audit is read-only and produces a report.** It never edits the repository it measures, so a fix is a separate and reviewable change. An audit that reports drift and stops is half the procedure, and a conformance claim carrying no committed report is a claim nobody can check. +- **The audit is read-only and produces a report.** It never edits the repository it measures, so a fix is a separate and reviewable change. An audit that reports drift and stops is half the procedure, and a conformance claim carrying no committed report is a claim nobody can check. The hub commits that report under its own `reports/`, so a session in the repository being audited never opens a hub pull request to write one and files its findings about the hub as issues instead. - **Reach the hub as a checkout of your own, fetched immediately before it is read.** A clone is whatever it last fetched rather than the branch it names, so a stale one answers confidently instead of failing, and a single file lifted out of the tree runs against whatever the caller happens to have. Work only in that checkout rather than in one that another task is using, since a blanket add, a hard reset, or a branch switch in a tree someone else is editing destroys work while every command is individually correct. From 544c7ebec8ddd635c0fb162f2fd6cd06b801621e Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Fri, 25 Sep 2026 11:35:13 -0700 Subject: [PATCH 2/6] Name the Report's Author on the RESYNC Route Too Co-Authored-By: Claude Opus 5.5 (1M context) --- .agents/skills/resync-a-repo/SKILL.md | 4 ++-- .claude-plugin/fleet-skills/.source-digests/resync-a-repo | 2 +- .claude-plugin/fleet-skills/skills/resync-a-repo/SKILL.md | 4 ++-- .github/skills/resync-a-repo/SKILL.md | 4 ++-- AGENTS.md | 2 +- RESYNC.md | 2 +- host-setup/agent-safety/claude/claude-md-fleet.md | 2 +- 7 files changed, 10 insertions(+), 10 deletions(-) diff --git a/.agents/skills/resync-a-repo/SKILL.md b/.agents/skills/resync-a-repo/SKILL.md index 6a4017d76..d837a5483 100644 --- a/.agents/skills/resync-a-repo/SKILL.md +++ b/.agents/skills/resync-a-repo/SKILL.md @@ -92,5 +92,5 @@ One focused pull request per drift class, branched from the target's `develop`, push to a protected branch and never a hand edit outside a pull request. Close the review loop, per the `pr-review-conduct` skill, before asking the maintainer for merge permission. The maintainer merges, the agent drives to green and stops. Re-run the audit after the merge and -commit the report once authorized, per `git-commit-conventions`, done means measured, not -applied. +commit the report under the hub's own `reports/` once authorized, the hub authoring it per +`AUDIT.md` section 8, per `git-commit-conventions`, done means measured, not applied. diff --git a/.claude-plugin/fleet-skills/.source-digests/resync-a-repo b/.claude-plugin/fleet-skills/.source-digests/resync-a-repo index 7baa4816a..ca80d7946 100644 --- a/.claude-plugin/fleet-skills/.source-digests/resync-a-repo +++ b/.claude-plugin/fleet-skills/.source-digests/resync-a-repo @@ -1 +1 @@ -2f7f3442e2a948d6 +4ee2962f953e0d09 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 6a4017d76..d837a5483 100644 --- a/.claude-plugin/fleet-skills/skills/resync-a-repo/SKILL.md +++ b/.claude-plugin/fleet-skills/skills/resync-a-repo/SKILL.md @@ -92,5 +92,5 @@ One focused pull request per drift class, branched from the target's `develop`, push to a protected branch and never a hand edit outside a pull request. Close the review loop, per the `pr-review-conduct` skill, before asking the maintainer for merge permission. The maintainer merges, the agent drives to green and stops. Re-run the audit after the merge and -commit the report once authorized, per `git-commit-conventions`, done means measured, not -applied. +commit the report under the hub's own `reports/` once authorized, the hub authoring it per +`AUDIT.md` section 8, per `git-commit-conventions`, done means measured, not applied. diff --git a/.github/skills/resync-a-repo/SKILL.md b/.github/skills/resync-a-repo/SKILL.md index 6a4017d76..d837a5483 100644 --- a/.github/skills/resync-a-repo/SKILL.md +++ b/.github/skills/resync-a-repo/SKILL.md @@ -92,5 +92,5 @@ One focused pull request per drift class, branched from the target's `develop`, push to a protected branch and never a hand edit outside a pull request. Close the review loop, per the `pr-review-conduct` skill, before asking the maintainer for merge permission. The maintainer merges, the agent drives to green and stops. Re-run the audit after the merge and -commit the report once authorized, per `git-commit-conventions`, done means measured, not -applied. +commit the report under the hub's own `reports/` once authorized, the hub authoring it per +`AUDIT.md` section 8, per `git-commit-conventions`, done means measured, not applied. diff --git a/AGENTS.md b/AGENTS.md index fd7fdf271..42afb3976 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -24,7 +24,7 @@ flowchart TD - **No repository yet, or a local tree with no remote.** Follow the hub's `STANDUP.md` from section 0. That file is hub-only and deliberately not carried, because a repository needing it cannot be relied on to hold a current copy. Note that nothing in it creates the GitHub repository, which is an outward-facing write requiring explicit permission, so section 0A is the list handed to the maintainer before anything else starts. - **A repository with no carried instruction set, or a partial one.** Carry the baseline per the hub's `STANDUP.md` sections 1A and 2, which resolve what this repository is owed from its declared types and workflow model. Absent files are not drift to re-vendor, they are a baseline that never arrived, and the two are fixed differently. - **A repository with the instruction set, current or stale.** Follow the hub's `RESYNC.md`, which runs `AUDIT.md` end to end for the findings and then applies each one in an order that matters, since the rules govern what comes after them, a deletion must precede the re-vendor that would otherwise refresh the file, and only some findings are mechanically detectable at all. An audit that reports drift and stops is half the procedure. -- **A repository that believes it is conformant.** Run the audit anyway, because conformance asserted without a report is conformance nobody can check. The hub commits that report under its own `reports/`, since a report written by the repository it measures is a claim rather than evidence, so a session in the repository being audited never opens a hub pull request to write one and files its findings about the hub as issues instead. This is the same procedure as the case above and is listed separately only because it is the one most often skipped. +- **A repository that believes it is conformant.** Run the audit anyway, because conformance asserted without a report is conformance nobody can check. The hub commits that report under its own `reports/`, since a report written by the repository it measures is a claim rather than evidence, so a session in the repository being audited never opens a hub pull request to write its own report and files its findings about the hub as issues instead. This is the same procedure as the case above and is listed separately only because it is the one most often skipped. Three rules bound every path above. **Read the hub's `main` branch as ground truth**, since that is the promoted and gated state, and read `develop` only to detect divergence. **Reach the hub as a checkout of your own and fetch it immediately before reading it**, because a clone is whatever it last fetched rather than the branch it names, and work only in that checkout rather than in one that another task is using, per [`GOVERNANCE.md`](./GOVERNANCE.md) "Repository Boundaries and Write Safety" and "Hub-Hosted Tooling". And **the audit is read-only**: it produces a report and never edits the repository it measures, so a fix is a separate, reviewable change. diff --git a/RESYNC.md b/RESYNC.md index 8bb4714ef..11c295800 100644 --- a/RESYNC.md +++ b/RESYNC.md @@ -122,7 +122,7 @@ The other half is section 4 of [`AUDIT.md`][audit]: no check belonging to a proj - **The maintainer merges.** The agent drives to green and stops. - **Fix systemic drift in the hub instead.** Where many repositories share a drift, fix the rule or add a check here and let a re-audit re-flag it, rather than hand-patching each repository for a shared cause. -**Done means measured, not applied.** Re-run the audit after the merge and commit the report, because a convergence asserted without a report is a convergence nobody can check. +**Done means measured, not applied.** Re-run the audit after the merge and commit the report, which the hub authors under its own `reports/` per [`AUDIT.md`][audit] section 8, because a convergence asserted without a report is a convergence nobody can check. diff --git a/host-setup/agent-safety/claude/claude-md-fleet.md b/host-setup/agent-safety/claude/claude-md-fleet.md index 0dcbd6ae9..30a9e237b 100644 --- a/host-setup/agent-safety/claude/claude-md-fleet.md +++ b/host-setup/agent-safety/claude/claude-md-fleet.md @@ -7,6 +7,6 @@ This section enables rather than restricts, so it is bounded by everything above - **Route by what the repository actually holds, not by what it should hold.** The two differ precisely when this matters. No repository yet means the hub's `STANDUP.md` from section 0, and note that nothing in that file creates the GitHub repository, which is an outward-facing write needing explicit permission. A missing or partial instruction set means carrying the baseline per that file's sections 1A and 2, since absent files are a baseline that never arrived rather than drift to re-vendor. An instruction set that is present, current or stale, means the hub's `RESYNC.md`, which runs `AUDIT.md` end to end for the findings and then applies each one in the order that file sets. - **Read the hub's `main` branch as ground truth**, since that is the promoted and gated state, and read `develop` only to detect divergence. The same holds for a repository being audited, for both workflow models. -- **The audit is read-only and produces a report.** It never edits the repository it measures, so a fix is a separate and reviewable change. An audit that reports drift and stops is half the procedure, and a conformance claim carrying no committed report is a claim nobody can check. The hub commits that report under its own `reports/`, so a session in the repository being audited never opens a hub pull request to write one and files its findings about the hub as issues instead. +- **The audit is read-only and produces a report.** It never edits the repository it measures, so a fix is a separate and reviewable change. An audit that reports drift and stops is half the procedure, and a conformance claim carrying no committed report is a claim nobody can check. The hub commits that report under its own `reports/`, so a session in the repository being audited never opens a hub pull request to write its own report and files its findings about the hub as issues instead. - **Reach the hub as a checkout of your own, fetched immediately before it is read.** A clone is whatever it last fetched rather than the branch it names, so a stale one answers confidently instead of failing, and a single file lifted out of the tree runs against whatever the caller happens to have. Work only in that checkout rather than in one that another task is using, since a blanket add, a hard reset, or a branch switch in a tree someone else is editing destroys work while every command is individually correct. From 4e86cb9207a565bcf9433263690b9a803aca5826 Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Fri, 25 Sep 2026 11:37:48 -0700 Subject: [PATCH 3/6] Give the Audited Repository's Session Its Next Steps Co-Authored-By: Claude Opus 5.5 (1M context) --- AGENTS.md | 2 +- host-setup/agent-safety/claude/claude-md-fleet.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 42afb3976..a2c864674 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -24,7 +24,7 @@ flowchart TD - **No repository yet, or a local tree with no remote.** Follow the hub's `STANDUP.md` from section 0. That file is hub-only and deliberately not carried, because a repository needing it cannot be relied on to hold a current copy. Note that nothing in it creates the GitHub repository, which is an outward-facing write requiring explicit permission, so section 0A is the list handed to the maintainer before anything else starts. - **A repository with no carried instruction set, or a partial one.** Carry the baseline per the hub's `STANDUP.md` sections 1A and 2, which resolve what this repository is owed from its declared types and workflow model. Absent files are not drift to re-vendor, they are a baseline that never arrived, and the two are fixed differently. - **A repository with the instruction set, current or stale.** Follow the hub's `RESYNC.md`, which runs `AUDIT.md` end to end for the findings and then applies each one in an order that matters, since the rules govern what comes after them, a deletion must precede the re-vendor that would otherwise refresh the file, and only some findings are mechanically detectable at all. An audit that reports drift and stops is half the procedure. -- **A repository that believes it is conformant.** Run the audit anyway, because conformance asserted without a report is conformance nobody can check. The hub commits that report under its own `reports/`, since a report written by the repository it measures is a claim rather than evidence, so a session in the repository being audited never opens a hub pull request to write its own report and files its findings about the hub as issues instead. This is the same procedure as the case above and is listed separately only because it is the one most often skipped. +- **A repository that believes it is conformant.** Run the audit anyway, because conformance asserted without a report is conformance nobody can check. The hub commits that report under its own `reports/`, since a report written by the repository it measures is a claim rather than evidence, so a session in the repository being audited fixes its own drift in its own repository, files its findings about the hub as issues, and leaves the report to a hub-side audit rather than opening a hub pull request to write its own. This is the same procedure as the case above and is listed separately only because it is the one most often skipped. Three rules bound every path above. **Read the hub's `main` branch as ground truth**, since that is the promoted and gated state, and read `develop` only to detect divergence. **Reach the hub as a checkout of your own and fetch it immediately before reading it**, because a clone is whatever it last fetched rather than the branch it names, and work only in that checkout rather than in one that another task is using, per [`GOVERNANCE.md`](./GOVERNANCE.md) "Repository Boundaries and Write Safety" and "Hub-Hosted Tooling". And **the audit is read-only**: it produces a report and never edits the repository it measures, so a fix is a separate, reviewable change. diff --git a/host-setup/agent-safety/claude/claude-md-fleet.md b/host-setup/agent-safety/claude/claude-md-fleet.md index 30a9e237b..d7db5b9a9 100644 --- a/host-setup/agent-safety/claude/claude-md-fleet.md +++ b/host-setup/agent-safety/claude/claude-md-fleet.md @@ -7,6 +7,6 @@ This section enables rather than restricts, so it is bounded by everything above - **Route by what the repository actually holds, not by what it should hold.** The two differ precisely when this matters. No repository yet means the hub's `STANDUP.md` from section 0, and note that nothing in that file creates the GitHub repository, which is an outward-facing write needing explicit permission. A missing or partial instruction set means carrying the baseline per that file's sections 1A and 2, since absent files are a baseline that never arrived rather than drift to re-vendor. An instruction set that is present, current or stale, means the hub's `RESYNC.md`, which runs `AUDIT.md` end to end for the findings and then applies each one in the order that file sets. - **Read the hub's `main` branch as ground truth**, since that is the promoted and gated state, and read `develop` only to detect divergence. The same holds for a repository being audited, for both workflow models. -- **The audit is read-only and produces a report.** It never edits the repository it measures, so a fix is a separate and reviewable change. An audit that reports drift and stops is half the procedure, and a conformance claim carrying no committed report is a claim nobody can check. The hub commits that report under its own `reports/`, so a session in the repository being audited never opens a hub pull request to write its own report and files its findings about the hub as issues instead. +- **The audit is read-only and produces a report.** It never edits the repository it measures, so a fix is a separate and reviewable change. An audit that reports drift and stops is half the procedure, and a conformance claim carrying no committed report is a claim nobody can check. The hub commits that report under its own `reports/`, and a session in the repository being audited fixes its own drift, files its findings about the hub as issues, and leaves the report to a hub-side audit. - **Reach the hub as a checkout of your own, fetched immediately before it is read.** A clone is whatever it last fetched rather than the branch it names, so a stale one answers confidently instead of failing, and a single file lifted out of the tree runs against whatever the caller happens to have. Work only in that checkout rather than in one that another task is using, since a blanket add, a hard reset, or a branch switch in a tree someone else is editing destroys work while every command is individually correct. From cfcc655706d5c766eed4ac182ced4eba1051b28d Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Fri, 25 Sep 2026 11:53:49 -0700 Subject: [PATCH 4/6] Stop check-this-repo Denying a Downstream Resync Co-Authored-By: Claude Opus 5.5 (1M context) --- .agents/skills/check-this-repo/SKILL.md | 2 +- .claude-plugin/fleet-skills/.source-digests/check-this-repo | 2 +- .claude-plugin/fleet-skills/skills/check-this-repo/SKILL.md | 2 +- .github/skills/check-this-repo/SKILL.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.agents/skills/check-this-repo/SKILL.md b/.agents/skills/check-this-repo/SKILL.md index 478f589f7..fad69e717 100644 --- a/.agents/skills/check-this-repo/SKILL.md +++ b/.agents/skills/check-this-repo/SKILL.md @@ -68,7 +68,7 @@ refresh stays out of scope until the fleet has evidence the manual cadence fails - **A carried section that differs from the hub in a way that reads as a genuine local addition** rather than plain staleness, the exact case `carried-instruction-file-guard` exists to protect. Report precisely what differs and stop there. Per AUDIT.md, a downstream repo does not write its - own audit report or resync itself against the hub, it names what it found and points at + own audit report, it names what it found and points at `resync-a-repo`, run from a hub checkout, as the next step. - **Anything the installer alone cannot resolve**, a broken `claude` CLI marketplace registration, a settings or ruleset drift, a workflow interface mismatch. Name it and hand it to diff --git a/.claude-plugin/fleet-skills/.source-digests/check-this-repo b/.claude-plugin/fleet-skills/.source-digests/check-this-repo index 9ec94fec5..127e17d9f 100644 --- a/.claude-plugin/fleet-skills/.source-digests/check-this-repo +++ b/.claude-plugin/fleet-skills/.source-digests/check-this-repo @@ -1 +1 @@ -7a6a5ddfebffe626 +0746a70923b170a4 diff --git a/.claude-plugin/fleet-skills/skills/check-this-repo/SKILL.md b/.claude-plugin/fleet-skills/skills/check-this-repo/SKILL.md index 478f589f7..fad69e717 100644 --- a/.claude-plugin/fleet-skills/skills/check-this-repo/SKILL.md +++ b/.claude-plugin/fleet-skills/skills/check-this-repo/SKILL.md @@ -68,7 +68,7 @@ refresh stays out of scope until the fleet has evidence the manual cadence fails - **A carried section that differs from the hub in a way that reads as a genuine local addition** rather than plain staleness, the exact case `carried-instruction-file-guard` exists to protect. Report precisely what differs and stop there. Per AUDIT.md, a downstream repo does not write its - own audit report or resync itself against the hub, it names what it found and points at + own audit report, it names what it found and points at `resync-a-repo`, run from a hub checkout, as the next step. - **Anything the installer alone cannot resolve**, a broken `claude` CLI marketplace registration, a settings or ruleset drift, a workflow interface mismatch. Name it and hand it to diff --git a/.github/skills/check-this-repo/SKILL.md b/.github/skills/check-this-repo/SKILL.md index 478f589f7..fad69e717 100644 --- a/.github/skills/check-this-repo/SKILL.md +++ b/.github/skills/check-this-repo/SKILL.md @@ -68,7 +68,7 @@ refresh stays out of scope until the fleet has evidence the manual cadence fails - **A carried section that differs from the hub in a way that reads as a genuine local addition** rather than plain staleness, the exact case `carried-instruction-file-guard` exists to protect. Report precisely what differs and stop there. Per AUDIT.md, a downstream repo does not write its - own audit report or resync itself against the hub, it names what it found and points at + own audit report, it names what it found and points at `resync-a-repo`, run from a hub checkout, as the next step. - **Anything the installer alone cannot resolve**, a broken `claude` CLI marketplace registration, a settings or ruleset drift, a workflow interface mismatch. Name it and hand it to From 64d71a4771f914023970362925e00e0fdcd0b064 Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Fri, 25 Sep 2026 12:03:42 -0700 Subject: [PATCH 5/6] Let a Downstream Session Resync Itself and Leave the Report to the Hub Co-Authored-By: Claude Opus 5.5 (1M context) --- .agents/skills/check-this-repo/SKILL.md | 9 ++++----- .../fleet-skills/.source-digests/check-this-repo | 2 +- .../fleet-skills/skills/check-this-repo/SKILL.md | 9 ++++----- .github/skills/check-this-repo/SKILL.md | 9 ++++----- AUDIT.md | 2 +- RESYNC.md | 2 +- 6 files changed, 15 insertions(+), 18 deletions(-) diff --git a/.agents/skills/check-this-repo/SKILL.md b/.agents/skills/check-this-repo/SKILL.md index fad69e717..400dff660 100644 --- a/.agents/skills/check-this-repo/SKILL.md +++ b/.agents/skills/check-this-repo/SKILL.md @@ -50,8 +50,8 @@ repo. needs a review. Nothing else. This skill never re-vendors a carried file, never deletes one, and never applies a -setting or ruleset. Those are `resync-a-repo`'s job, driven from the hub with a named target, -never a downstream repo acting on itself. +setting or ruleset. Converging that drift is a resync, a separate change on its own branch, run +per the hub's `RESYNC.md` by this repo's own session or by `resync-a-repo` from a hub checkout. ## Refresh cadence @@ -67,9 +67,8 @@ refresh stays out of scope until the fleet has evidence the manual cadence fails - **A carried section that differs from the hub in a way that reads as a genuine local addition** rather than plain staleness, the exact case `carried-instruction-file-guard` exists to protect. - Report precisely what differs and stop there. Per AUDIT.md, a downstream repo does not write its - own audit report, it names what it found and points at - `resync-a-repo`, run from a hub checkout, as the next step. + Report precisely what differs and stop there, naming a resync as the next step, where + `carried-instruction-file-guard` decides the merge. - **Anything the installer alone cannot resolve**, a broken `claude` CLI marketplace registration, a settings or ruleset drift, a workflow interface mismatch. Name it and hand it to the maintainer or a hub-driven resync rather than patching around it locally. diff --git a/.claude-plugin/fleet-skills/.source-digests/check-this-repo b/.claude-plugin/fleet-skills/.source-digests/check-this-repo index 127e17d9f..eff0ebcd0 100644 --- a/.claude-plugin/fleet-skills/.source-digests/check-this-repo +++ b/.claude-plugin/fleet-skills/.source-digests/check-this-repo @@ -1 +1 @@ -0746a70923b170a4 +ff8daf3e11ea205d diff --git a/.claude-plugin/fleet-skills/skills/check-this-repo/SKILL.md b/.claude-plugin/fleet-skills/skills/check-this-repo/SKILL.md index fad69e717..400dff660 100644 --- a/.claude-plugin/fleet-skills/skills/check-this-repo/SKILL.md +++ b/.claude-plugin/fleet-skills/skills/check-this-repo/SKILL.md @@ -50,8 +50,8 @@ repo. needs a review. Nothing else. This skill never re-vendors a carried file, never deletes one, and never applies a -setting or ruleset. Those are `resync-a-repo`'s job, driven from the hub with a named target, -never a downstream repo acting on itself. +setting or ruleset. Converging that drift is a resync, a separate change on its own branch, run +per the hub's `RESYNC.md` by this repo's own session or by `resync-a-repo` from a hub checkout. ## Refresh cadence @@ -67,9 +67,8 @@ refresh stays out of scope until the fleet has evidence the manual cadence fails - **A carried section that differs from the hub in a way that reads as a genuine local addition** rather than plain staleness, the exact case `carried-instruction-file-guard` exists to protect. - Report precisely what differs and stop there. Per AUDIT.md, a downstream repo does not write its - own audit report, it names what it found and points at - `resync-a-repo`, run from a hub checkout, as the next step. + Report precisely what differs and stop there, naming a resync as the next step, where + `carried-instruction-file-guard` decides the merge. - **Anything the installer alone cannot resolve**, a broken `claude` CLI marketplace registration, a settings or ruleset drift, a workflow interface mismatch. Name it and hand it to the maintainer or a hub-driven resync rather than patching around it locally. diff --git a/.github/skills/check-this-repo/SKILL.md b/.github/skills/check-this-repo/SKILL.md index fad69e717..400dff660 100644 --- a/.github/skills/check-this-repo/SKILL.md +++ b/.github/skills/check-this-repo/SKILL.md @@ -50,8 +50,8 @@ repo. needs a review. Nothing else. This skill never re-vendors a carried file, never deletes one, and never applies a -setting or ruleset. Those are `resync-a-repo`'s job, driven from the hub with a named target, -never a downstream repo acting on itself. +setting or ruleset. Converging that drift is a resync, a separate change on its own branch, run +per the hub's `RESYNC.md` by this repo's own session or by `resync-a-repo` from a hub checkout. ## Refresh cadence @@ -67,9 +67,8 @@ refresh stays out of scope until the fleet has evidence the manual cadence fails - **A carried section that differs from the hub in a way that reads as a genuine local addition** rather than plain staleness, the exact case `carried-instruction-file-guard` exists to protect. - Report precisely what differs and stop there. Per AUDIT.md, a downstream repo does not write its - own audit report, it names what it found and points at - `resync-a-repo`, run from a hub checkout, as the next step. + Report precisely what differs and stop there, naming a resync as the next step, where + `carried-instruction-file-guard` decides the merge. - **Anything the installer alone cannot resolve**, a broken `claude` CLI marketplace registration, a settings or ruleset drift, a workflow interface mismatch. Name it and hand it to the maintainer or a hub-driven resync rather than patching around it locally. diff --git a/AUDIT.md b/AUDIT.md index 240d3f8a4..6ddf44838 100644 --- a/AUDIT.md +++ b/AUDIT.md @@ -214,7 +214,7 @@ flowchart LR finding -->|"one repo"| s10["10: Converge, branch + fix + PR"] s10 --> review["review loop to green"] review --> merge["maintainer merges"] - merge --> reaudit["re-audit, commit the report"] + merge --> reaudit["re-audit, the hub commits the report"] s9 --> reaudit ``` diff --git a/RESYNC.md b/RESYNC.md index 11c295800..ecc78f83d 100644 --- a/RESYNC.md +++ b/RESYNC.md @@ -122,7 +122,7 @@ The other half is section 4 of [`AUDIT.md`][audit]: no check belonging to a proj - **The maintainer merges.** The agent drives to green and stops. - **Fix systemic drift in the hub instead.** Where many repositories share a drift, fix the rule or add a check here and let a re-audit re-flag it, rather than hand-patching each repository for a shared cause. -**Done means measured, not applied.** Re-run the audit after the merge and commit the report, which the hub authors under its own `reports/` per [`AUDIT.md`][audit] section 8, because a convergence asserted without a report is a convergence nobody can check. +**Done means measured, not applied.** Re-run the audit after the merge, because a convergence asserted without a report is a convergence nobody can check. The hub commits that report under its own `reports/` per [`AUDIT.md`][audit] section 8, so a session resyncing its own repository leaves the report to a hub-side audit. From 5225da00be5609b8ad300ee54325494f445f640b Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Fri, 25 Sep 2026 12:21:04 -0700 Subject: [PATCH 6/6] Finish Aligning check-this-repo, resync-a-repo, and the Host Fleet Block Co-Authored-By: Claude Opus 5.5 (1M context) --- .agents/skills/check-this-repo/SKILL.md | 6 +++--- .agents/skills/resync-a-repo/SKILL.md | 7 ++++--- .../fleet-skills/.source-digests/check-this-repo | 2 +- .claude-plugin/fleet-skills/.source-digests/resync-a-repo | 2 +- .../fleet-skills/skills/check-this-repo/SKILL.md | 6 +++--- .claude-plugin/fleet-skills/skills/resync-a-repo/SKILL.md | 7 ++++--- .github/skills/check-this-repo/SKILL.md | 6 +++--- .github/skills/resync-a-repo/SKILL.md | 7 ++++--- host-setup/agent-safety/claude/claude-md-fleet.md | 2 +- 9 files changed, 24 insertions(+), 21 deletions(-) diff --git a/.agents/skills/check-this-repo/SKILL.md b/.agents/skills/check-this-repo/SKILL.md index 400dff660..f16338bff 100644 --- a/.agents/skills/check-this-repo/SKILL.md +++ b/.agents/skills/check-this-repo/SKILL.md @@ -19,8 +19,8 @@ description: >- ## Why this exists -A downstream repo today only finds out it has drifted when someone runs a hub-driven resync -against it by name. Nothing notices from the inside on its own. This skill is that inside check, +A downstream repo today only finds out it has drifted when someone runs an audit or a resync +against it. Nothing notices from the inside on its own. This skill is that inside check, run with no hub-side operator watching, so a stale Skills install or an out-of-date `AGENTS.md` pointer gets noticed and fixed without waiting for a fleet-wide sweep to reach this particular repo. @@ -71,7 +71,7 @@ refresh stays out of scope until the fleet has evidence the manual cadence fails `carried-instruction-file-guard` decides the merge. - **Anything the installer alone cannot resolve**, a broken `claude` CLI marketplace registration, a settings or ruleset drift, a workflow interface mismatch. Name it and hand it to - the maintainer or a hub-driven resync rather than patching around it locally. + the maintainer or a resync per the hub's `RESYNC.md` rather than patching around it locally. ## Answering "why isn't a fleet rule applying" diff --git a/.agents/skills/resync-a-repo/SKILL.md b/.agents/skills/resync-a-repo/SKILL.md index d837a5483..82588b86a 100644 --- a/.agents/skills/resync-a-repo/SKILL.md +++ b/.agents/skills/resync-a-repo/SKILL.md @@ -91,6 +91,7 @@ rather than leaving it standing. One focused pull request per drift class, branched from the target's `develop`, never a direct push to a protected branch and never a hand edit outside a pull request. Close the review loop, per the `pr-review-conduct` skill, before asking the maintainer for merge permission. The -maintainer merges, the agent drives to green and stops. Re-run the audit after the merge and -commit the report under the hub's own `reports/` once authorized, the hub authoring it per -`AUDIT.md` section 8, per `git-commit-conventions`, done means measured, not applied. +maintainer merges, the agent drives to green and stops. Re-run the audit after the merge and, +from the hub checkout, commit the report under the hub's own `reports/` once authorized, per +`AUDIT.md` section 8 and `git-commit-conventions`. A session resyncing its own repository +leaves the report to a hub-side audit instead. Done means measured, not applied. diff --git a/.claude-plugin/fleet-skills/.source-digests/check-this-repo b/.claude-plugin/fleet-skills/.source-digests/check-this-repo index eff0ebcd0..aa1093ec9 100644 --- a/.claude-plugin/fleet-skills/.source-digests/check-this-repo +++ b/.claude-plugin/fleet-skills/.source-digests/check-this-repo @@ -1 +1 @@ -ff8daf3e11ea205d +f5075baedbd8a74f diff --git a/.claude-plugin/fleet-skills/.source-digests/resync-a-repo b/.claude-plugin/fleet-skills/.source-digests/resync-a-repo index ca80d7946..917b4be56 100644 --- a/.claude-plugin/fleet-skills/.source-digests/resync-a-repo +++ b/.claude-plugin/fleet-skills/.source-digests/resync-a-repo @@ -1 +1 @@ -4ee2962f953e0d09 +179f4010403d2fa1 diff --git a/.claude-plugin/fleet-skills/skills/check-this-repo/SKILL.md b/.claude-plugin/fleet-skills/skills/check-this-repo/SKILL.md index 400dff660..f16338bff 100644 --- a/.claude-plugin/fleet-skills/skills/check-this-repo/SKILL.md +++ b/.claude-plugin/fleet-skills/skills/check-this-repo/SKILL.md @@ -19,8 +19,8 @@ description: >- ## Why this exists -A downstream repo today only finds out it has drifted when someone runs a hub-driven resync -against it by name. Nothing notices from the inside on its own. This skill is that inside check, +A downstream repo today only finds out it has drifted when someone runs an audit or a resync +against it. Nothing notices from the inside on its own. This skill is that inside check, run with no hub-side operator watching, so a stale Skills install or an out-of-date `AGENTS.md` pointer gets noticed and fixed without waiting for a fleet-wide sweep to reach this particular repo. @@ -71,7 +71,7 @@ refresh stays out of scope until the fleet has evidence the manual cadence fails `carried-instruction-file-guard` decides the merge. - **Anything the installer alone cannot resolve**, a broken `claude` CLI marketplace registration, a settings or ruleset drift, a workflow interface mismatch. Name it and hand it to - the maintainer or a hub-driven resync rather than patching around it locally. + the maintainer or a resync per the hub's `RESYNC.md` rather than patching around it locally. ## Answering "why isn't a fleet rule applying" 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 d837a5483..82588b86a 100644 --- a/.claude-plugin/fleet-skills/skills/resync-a-repo/SKILL.md +++ b/.claude-plugin/fleet-skills/skills/resync-a-repo/SKILL.md @@ -91,6 +91,7 @@ rather than leaving it standing. One focused pull request per drift class, branched from the target's `develop`, never a direct push to a protected branch and never a hand edit outside a pull request. Close the review loop, per the `pr-review-conduct` skill, before asking the maintainer for merge permission. The -maintainer merges, the agent drives to green and stops. Re-run the audit after the merge and -commit the report under the hub's own `reports/` once authorized, the hub authoring it per -`AUDIT.md` section 8, per `git-commit-conventions`, done means measured, not applied. +maintainer merges, the agent drives to green and stops. Re-run the audit after the merge and, +from the hub checkout, commit the report under the hub's own `reports/` once authorized, per +`AUDIT.md` section 8 and `git-commit-conventions`. A session resyncing its own repository +leaves the report to a hub-side audit instead. Done means measured, not applied. diff --git a/.github/skills/check-this-repo/SKILL.md b/.github/skills/check-this-repo/SKILL.md index 400dff660..f16338bff 100644 --- a/.github/skills/check-this-repo/SKILL.md +++ b/.github/skills/check-this-repo/SKILL.md @@ -19,8 +19,8 @@ description: >- ## Why this exists -A downstream repo today only finds out it has drifted when someone runs a hub-driven resync -against it by name. Nothing notices from the inside on its own. This skill is that inside check, +A downstream repo today only finds out it has drifted when someone runs an audit or a resync +against it. Nothing notices from the inside on its own. This skill is that inside check, run with no hub-side operator watching, so a stale Skills install or an out-of-date `AGENTS.md` pointer gets noticed and fixed without waiting for a fleet-wide sweep to reach this particular repo. @@ -71,7 +71,7 @@ refresh stays out of scope until the fleet has evidence the manual cadence fails `carried-instruction-file-guard` decides the merge. - **Anything the installer alone cannot resolve**, a broken `claude` CLI marketplace registration, a settings or ruleset drift, a workflow interface mismatch. Name it and hand it to - the maintainer or a hub-driven resync rather than patching around it locally. + the maintainer or a resync per the hub's `RESYNC.md` rather than patching around it locally. ## Answering "why isn't a fleet rule applying" diff --git a/.github/skills/resync-a-repo/SKILL.md b/.github/skills/resync-a-repo/SKILL.md index d837a5483..82588b86a 100644 --- a/.github/skills/resync-a-repo/SKILL.md +++ b/.github/skills/resync-a-repo/SKILL.md @@ -91,6 +91,7 @@ rather than leaving it standing. One focused pull request per drift class, branched from the target's `develop`, never a direct push to a protected branch and never a hand edit outside a pull request. Close the review loop, per the `pr-review-conduct` skill, before asking the maintainer for merge permission. The -maintainer merges, the agent drives to green and stops. Re-run the audit after the merge and -commit the report under the hub's own `reports/` once authorized, the hub authoring it per -`AUDIT.md` section 8, per `git-commit-conventions`, done means measured, not applied. +maintainer merges, the agent drives to green and stops. Re-run the audit after the merge and, +from the hub checkout, commit the report under the hub's own `reports/` once authorized, per +`AUDIT.md` section 8 and `git-commit-conventions`. A session resyncing its own repository +leaves the report to a hub-side audit instead. Done means measured, not applied. diff --git a/host-setup/agent-safety/claude/claude-md-fleet.md b/host-setup/agent-safety/claude/claude-md-fleet.md index d7db5b9a9..f801a1247 100644 --- a/host-setup/agent-safety/claude/claude-md-fleet.md +++ b/host-setup/agent-safety/claude/claude-md-fleet.md @@ -7,6 +7,6 @@ This section enables rather than restricts, so it is bounded by everything above - **Route by what the repository actually holds, not by what it should hold.** The two differ precisely when this matters. No repository yet means the hub's `STANDUP.md` from section 0, and note that nothing in that file creates the GitHub repository, which is an outward-facing write needing explicit permission. A missing or partial instruction set means carrying the baseline per that file's sections 1A and 2, since absent files are a baseline that never arrived rather than drift to re-vendor. An instruction set that is present, current or stale, means the hub's `RESYNC.md`, which runs `AUDIT.md` end to end for the findings and then applies each one in the order that file sets. - **Read the hub's `main` branch as ground truth**, since that is the promoted and gated state, and read `develop` only to detect divergence. The same holds for a repository being audited, for both workflow models. -- **The audit is read-only and produces a report.** It never edits the repository it measures, so a fix is a separate and reviewable change. An audit that reports drift and stops is half the procedure, and a conformance claim carrying no committed report is a claim nobody can check. The hub commits that report under its own `reports/`, and a session in the repository being audited fixes its own drift, files its findings about the hub as issues, and leaves the report to a hub-side audit. +- **The audit is read-only and produces a report.** It never edits the repository it measures, so a fix is a separate and reviewable change. An audit that reports drift and stops is half the procedure, and a conformance claim carrying no committed report is a claim nobody can check. The hub commits that report under its own `reports/`. - **Reach the hub as a checkout of your own, fetched immediately before it is read.** A clone is whatever it last fetched rather than the branch it names, so a stale one answers confidently instead of failing, and a single file lifted out of the tree runs against whatever the caller happens to have. Work only in that checkout rather than in one that another task is using, since a blanket add, a hard reset, or a branch switch in a tree someone else is editing destroys work while every command is individually correct.