From 41e7aa1060f800c72316c65e2eee7fb299589a9a Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Tue, 25 Aug 2026 07:58:53 -0700 Subject: [PATCH 1/2] Fix Three Spec and Doc Drift Findings from HomeAutomation-Config Audit Reword the .editorconfig comment above the .NET-only block so it states the whole-file carry model instead of contradicting it (a non-.NET repo keeps the section unused rather than dropping it), matching CODESTYLE.md 'General'. Declare 'When in Doubt' in spec/files.json's sections array for .github/copilot-instructions.md, since the hub's own canonical file carries that heading and its absence from the manifest flagged it as phantom drift on every repo that carries the file verbatim. Add accepted gap entries in spec/divergences.json for .github/actionlint.yaml and .github/actions/validate/action.yml, both HomeAutomation-Config's own content at paths the hub also hosts (a path collision, not a carry), matching the existing accepted entries for LICENSE, TODO.md, .husky/pre-commit, and scripts/README.md. --- .editorconfig | 2 +- spec/divergences.json | 2 ++ spec/files.json | 2 +- 3 files changed, 4 insertions(+), 2 deletions(-) diff --git a/.editorconfig b/.editorconfig index fdf69a34..67cd1d57 100644 --- a/.editorconfig +++ b/.editorconfig @@ -41,7 +41,7 @@ indent_size = 2 end_of_line = crlf # .NET-only below, covering C# and ReSharper style. -# Everything above is the line-ending governance every derived repo carries, and a non-.NET repo may drop from here down. +# Everything above is the line-ending governance every derived repo carries, and a non-.NET repo carries this section unused, per CODESTYLE.md's whole-file model. # C# files [*.cs] diff --git a/spec/divergences.json b/spec/divergences.json index f7156905..0baecd52 100644 --- a/spec/divergences.json +++ b/spec/divergences.json @@ -18,6 +18,8 @@ { "path": "TODO.md", "disposition": "accepted", "reason": "A repo's own running backlog, which STANDUP.md section 2 names as one of the four declared destinations for repo-specific content. It is advisory and required by no selector, so the manifest deliberately does not declare it and a repo's copy is its own content rather than a carry.", "tracking": null }, { "path": ".husky/pre-commit", "disposition": "accepted", "reason": "A path collision rather than a carry. Each repo's hook runs that repo's own language formatters, and the hub's runs the doc gates, so the seven downstream copies share the path and none of the content: LanguageTags and Utilities run language formatting and style with no Docker, PlexCleaner runs CSharpier and dotnet format, and the hub runs prose_lint.py and repo_gate.py. Verified by reading the downstream copies on 2026-08-10.", "tracking": null }, { "path": "scripts/README.md", "disposition": "accepted", "reason": "A path collision rather than a carry. KiCadLibrary's copy documents its own KiCad tooling (common.py, verify_library.py, build_library.py) beside the scripts it describes, and shares nothing with the hub's fleet-gate documentation. Verified by reading it on 2026-08-10. scripts/ is a generic path, so a repo with its own tooling directory matches this check without carrying anything of the hub's.", "tracking": null }, + { "path": ".github/actionlint.yaml", "disposition": "accepted", "reason": "A path collision rather than a carry. HomeAutomation-Config's own copy declares self-hosted-runner labels (homelab, ubuntu-24.04) for its self-hosted CI runner, entirely different content from the hub's own file at this path, which configures $/ self-reference ignore rules for the hub's own workflows. Verified by reading both copies on 2026-08-25.", "tracking": null }, + { "path": ".github/actions/validate/action.yml", "disposition": "accepted", "reason": "A path collision rather than a carry. HomeAutomation-Config's own copy overrides the interface-workflow validate hook, per RESYNC.md 'Apply, in This Order' item 4, 'Interface workflows': 'Honor the named contract... rather than copying bytes. The body is the repository's own.' It runs its CloudInit/ nested Python project through uv/ruff/pyright/pytest. The hub's own file at this same path is a different override, its own registry/spec self-test suite. A repo declaring its own .github/actions/validate/action.yml is the documented, intended override mechanism, not drift to reconcile. Verified by reading both copies on 2026-08-25.", "tracking": null }, { "path": "pyproject.toml", "disposition": "investigate", "reason": "The hub gained a config-only Scripts-profile pyproject.toml in #388. Decide whether to track it (intent, appliesTo python) after confirming the python repos carry an equivalent.", "tracking": null }, { "path": ".github/workflows/get-version-task.yml", "disposition": "retire", "reason": "The task is hub-hosted rather than carried, per GOVERNANCE.md \"Hub-Hosted Tooling\", so it is no manifest entry and a downstream copy is retired rather than re-vendored. Every copy is the hub's own NBGV logic with nothing per-repo in it beyond the action pins Dependabot already owns. The carriers, read from the fleet on 2026-08-15, are ESPHome-NonRoot, NxWitness, PhotoCleaner, PlexCleaner, VSCode-Server-DotNetCore, KiCadLibrary, aiopurpleair, and homeassistant-purpleair. Delete the copy and reach the hub task by pin as each repo is next visited, per docs/reusable-workflows.md \"Adopting the Pure Functions\".", "tracking": null }, { "path": ".github/workflows/publish-plan-task.yml", "disposition": "retire", "reason": "The task is hub-hosted rather than carried, per GOVERNANCE.md \"Hub-Hosted Tooling\", so it is no manifest entry and a downstream copy is retired rather than re-vendored. The carriers, read from the fleet on 2026-08-15, are ESPHome-NonRoot, NxWitness, and Utilities, and all three carry a strict subset of the canonical, missing the -E in set -Eeuo pipefail and the ::warning:: branch for an unrecognized actor pushing to main (WORKFLOW.md D8.4). Delete the copy and reach the hub task by pin as each repo is next visited, per docs/reusable-workflows.md \"Adopting the Pure Functions\".", "tracking": null }, diff --git a/spec/files.json b/spec/files.json index 3f21366c..9a822d80 100644 --- a/spec/files.json +++ b/spec/files.json @@ -13,7 +13,7 @@ { "path": "README.md", "appliesTo": "*" }, { "path": "HISTORY.md", "appliesTo": "*" }, { "path": "OPERATIONS.md", "appliesTo": "*" }, - { "path": ".github/copilot-instructions.md", "fidelity": "intent", "whole": true, "sections": ["Commit Messages and Pull Request Titles", "Reviewing Carried Fleet Content", "GitHub Copilot Review Runbook"], "placeholders": ["", "", ""], "appliesTo": "*" }, + { "path": ".github/copilot-instructions.md", "fidelity": "intent", "whole": true, "sections": ["Commit Messages and Pull Request Titles", "Reviewing Carried Fleet Content", "GitHub Copilot Review Runbook", "When in Doubt"], "placeholders": ["", "", ""], "appliesTo": "*" }, { "path": ".editorconfig", "fidelity": "intent", "whole": true, "intentRef": "GOVERNANCE.md#line-endings", "appliesTo": "*" }, { "path": ".editorconfig-checker.json", "fidelity": "intent", "whole": true, "intentRef": "GOVERNANCE.md#line-endings", "appliesTo": "*" }, { "path": ".gitattributes", "fidelity": "intent", "whole": true, "intentRef": "GOVERNANCE.md#line-endings", "appliesTo": "*" }, From b626b2597306f5ca78fb1a109a953cdcea03af0c Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Tue, 25 Aug 2026 08:05:21 -0700 Subject: [PATCH 2/2] Update Keeper Skill's Section Count to Four The copilot-instructions-keeper skill still described three named sections in spec/files.json for .github/copilot-instructions.md, both in its overview and its update checklist, after this PR added a fourth ('When in Doubt'). Regenerated both distribution trees with scripts/build_dist.py. --- .../skills/copilot-instructions-keeper/SKILL.md | 14 +++++++------- .claude-plugin/fleet-skills/.source-digest | 2 +- .../skills/copilot-instructions-keeper/SKILL.md | 14 +++++++------- .../skills/copilot-instructions-keeper/SKILL.md | 14 +++++++------- 4 files changed, 22 insertions(+), 22 deletions(-) diff --git a/.agents/skills/copilot-instructions-keeper/SKILL.md b/.agents/skills/copilot-instructions-keeper/SKILL.md index 88f3c38c..9ee43bcc 100644 --- a/.agents/skills/copilot-instructions-keeper/SKILL.md +++ b/.agents/skills/copilot-instructions-keeper/SKILL.md @@ -23,13 +23,13 @@ description: >- intact in every repo that carries it. This skill maintains that carried copy, it does not replace the bootstrap. -`spec/files.json` declares it `intent` fidelity, `whole: true`, covering three named sections +`spec/files.json` declares it `intent` fidelity, `whole: true`, covering four named sections (`Commit Messages and Pull Request Titles`, `Reviewing Carried Fleet Content`, `GitHub Copilot -Review Runbook`), with ``, ``, and `` placeholders filled per repo. **The fleet -audit checks an `intent` file for file presence and each named section's heading, never for -content drift inside a section.** A section that is present but has fallen out of date against -the hub, the exact gap this skill exists to catch, produces no finding anywhere in the mechanical -audit. Noticing that has to happen in a live session like this one. +Review Runbook`, `When in Doubt`), with ``, ``, and `` placeholders filled per +repo. **The fleet audit checks an `intent` file for file presence and each named section's +heading, never for content drift inside a section.** A section that is present but has fallen out +of date against the hub, the exact gap this skill exists to catch, produces no finding anywhere in +the mechanical audit. Noticing that has to happen in a live session like this one. ## The one thing this file has that others don't: repo-local ledger entries @@ -51,7 +51,7 @@ repo's copy is wrong in both directions: 1. Read the current "Disproved Claims" section in that repo's copy, if it has one, and preserve every entry that names a file or behavior that repo actually carries. -2. Update everything else, the runbook mechanics, the three named sections, the rule text, to +2. Update everything else, the runbook mechanics, the four named sections, the rule text, to match the hub canonical. 3. Never carry the hub's own repo-specific "Disproved Claims" entries downstream. They name `ProjectTemplate`'s own files and revisions, not the target repo's. diff --git a/.claude-plugin/fleet-skills/.source-digest b/.claude-plugin/fleet-skills/.source-digest index db22d6f2..97ea0b63 100644 --- a/.claude-plugin/fleet-skills/.source-digest +++ b/.claude-plugin/fleet-skills/.source-digest @@ -1 +1 @@ -86607328dc15eded +b945e66c274cb82a diff --git a/.claude-plugin/fleet-skills/skills/copilot-instructions-keeper/SKILL.md b/.claude-plugin/fleet-skills/skills/copilot-instructions-keeper/SKILL.md index 88f3c38c..9ee43bcc 100644 --- a/.claude-plugin/fleet-skills/skills/copilot-instructions-keeper/SKILL.md +++ b/.claude-plugin/fleet-skills/skills/copilot-instructions-keeper/SKILL.md @@ -23,13 +23,13 @@ description: >- intact in every repo that carries it. This skill maintains that carried copy, it does not replace the bootstrap. -`spec/files.json` declares it `intent` fidelity, `whole: true`, covering three named sections +`spec/files.json` declares it `intent` fidelity, `whole: true`, covering four named sections (`Commit Messages and Pull Request Titles`, `Reviewing Carried Fleet Content`, `GitHub Copilot -Review Runbook`), with ``, ``, and `` placeholders filled per repo. **The fleet -audit checks an `intent` file for file presence and each named section's heading, never for -content drift inside a section.** A section that is present but has fallen out of date against -the hub, the exact gap this skill exists to catch, produces no finding anywhere in the mechanical -audit. Noticing that has to happen in a live session like this one. +Review Runbook`, `When in Doubt`), with ``, ``, and `` placeholders filled per +repo. **The fleet audit checks an `intent` file for file presence and each named section's +heading, never for content drift inside a section.** A section that is present but has fallen out +of date against the hub, the exact gap this skill exists to catch, produces no finding anywhere in +the mechanical audit. Noticing that has to happen in a live session like this one. ## The one thing this file has that others don't: repo-local ledger entries @@ -51,7 +51,7 @@ repo's copy is wrong in both directions: 1. Read the current "Disproved Claims" section in that repo's copy, if it has one, and preserve every entry that names a file or behavior that repo actually carries. -2. Update everything else, the runbook mechanics, the three named sections, the rule text, to +2. Update everything else, the runbook mechanics, the four named sections, the rule text, to match the hub canonical. 3. Never carry the hub's own repo-specific "Disproved Claims" entries downstream. They name `ProjectTemplate`'s own files and revisions, not the target repo's. diff --git a/.github/skills/copilot-instructions-keeper/SKILL.md b/.github/skills/copilot-instructions-keeper/SKILL.md index 88f3c38c..9ee43bcc 100644 --- a/.github/skills/copilot-instructions-keeper/SKILL.md +++ b/.github/skills/copilot-instructions-keeper/SKILL.md @@ -23,13 +23,13 @@ description: >- intact in every repo that carries it. This skill maintains that carried copy, it does not replace the bootstrap. -`spec/files.json` declares it `intent` fidelity, `whole: true`, covering three named sections +`spec/files.json` declares it `intent` fidelity, `whole: true`, covering four named sections (`Commit Messages and Pull Request Titles`, `Reviewing Carried Fleet Content`, `GitHub Copilot -Review Runbook`), with ``, ``, and `` placeholders filled per repo. **The fleet -audit checks an `intent` file for file presence and each named section's heading, never for -content drift inside a section.** A section that is present but has fallen out of date against -the hub, the exact gap this skill exists to catch, produces no finding anywhere in the mechanical -audit. Noticing that has to happen in a live session like this one. +Review Runbook`, `When in Doubt`), with ``, ``, and `` placeholders filled per +repo. **The fleet audit checks an `intent` file for file presence and each named section's +heading, never for content drift inside a section.** A section that is present but has fallen out +of date against the hub, the exact gap this skill exists to catch, produces no finding anywhere in +the mechanical audit. Noticing that has to happen in a live session like this one. ## The one thing this file has that others don't: repo-local ledger entries @@ -51,7 +51,7 @@ repo's copy is wrong in both directions: 1. Read the current "Disproved Claims" section in that repo's copy, if it has one, and preserve every entry that names a file or behavior that repo actually carries. -2. Update everything else, the runbook mechanics, the three named sections, the rule text, to +2. Update everything else, the runbook mechanics, the four named sections, the rule text, to match the hub canonical. 3. Never carry the hub's own repo-specific "Disproved Claims" entries downstream. They name `ProjectTemplate`'s own files and revisions, not the target repo's.