From 41c6187c4f67df498bbb1fc1c35a5e53e602dc1a Mon Sep 17 00:00:00 2001 From: Michael Dieringer <65093775+MichaelDieringer@users.noreply.github.com> Date: Wed, 1 Jul 2026 23:08:50 +0200 Subject: [PATCH] Setup v7: BCQuality knowledge-mirror er maskin-lokal, ikke repo-lokal - curabis-standard.agent.md v6 -> v7: mirror deployes til ~/.claude/bcquality-knowledge/ (delt af alle repoer paa maskinen) i stedet for .github/.agents/bcquality-knowledge/ i hvert repo - CLAUDE.md-templaten peger paa maskin-mirroren via %USERPROFILE% (aldrig literal udviklersti) og faar self-heal-instruktion - Mode B: v6-aera-oprydning (fjern committet repo-mirror, gitignore stien, foreslaa CLAUDE.md-migrering) + genkend hardcodede udviklerstier og raa-URL-lister som foraeldede CLAUDE.md-former - sync-bcquality-knowledge.ps1: fast destination $env:USERPROFILE \.claude\bcquality-knowledge i stedet for $PSScriptRoot-relativ (det var dobbelttydigheden der skabte repo-mirrors) - Ny regel: bcquality-knowledge-must-mirror-to-machine-not-repo - Setup-artefakter skal fetches som raa bytes (Invoke-WebRequest -OutFile) - aldrig via strengindhold, som dobbelt-encoder UTF-8 Begrundelse: udviklere skifter repo mange gange dagligt; N repo- mirrors er permanent ude af sync, een maskin-mirror kraever een sync pr. upstream-aendring. CI/cloud-agenter henter selv reglerne via .github/bcquality.config.yaml. Co-Authored-By: Claude Fable 5 --- ...owledge-must-mirror-to-machine-not-repo.md | 68 +++++++++++ custom/setup/curabis-standard.agent.md | 111 ++++++++++++------ custom/setup/sync-bcquality-knowledge.ps1 | 13 +- 3 files changed, 153 insertions(+), 39 deletions(-) create mode 100644 custom/knowledge/architecture/bcquality-knowledge-must-mirror-to-machine-not-repo.md diff --git a/custom/knowledge/architecture/bcquality-knowledge-must-mirror-to-machine-not-repo.md b/custom/knowledge/architecture/bcquality-knowledge-must-mirror-to-machine-not-repo.md new file mode 100644 index 0000000..e9d36a2 --- /dev/null +++ b/custom/knowledge/architecture/bcquality-knowledge-must-mirror-to-machine-not-repo.md @@ -0,0 +1,68 @@ +--- +bc-version: [all] +domain: architecture +keywords: [bcquality, knowledge-mirror, machine-local, repo-hygiene, sync, curabis-standard, claude-md] +technologies: [al] +countries: [w1] +application-area: [all] +--- + +## Description + +The three-layer BCQuality knowledge mirror (custom/community/microsoft + +INDEX.md) can technically live in two places: inside each project repository +(`.github/.agents/bcquality-knowledge/`, setup v6) or once per developer +machine (`~/.claude/bcquality-knowledge/`, setup v7+). CURABIS developers +switch between many repositories every day. With per-repo mirrors, every repo +carries its own copy that goes stale on its own schedule — N repos are +permanently out of sync with each other and with upstream, every re-sync +pollutes the project's git history with hundreds of files of upstream rule +churn, and a review can be judged by whichever rule vintage that particular +repo happens to carry. + +## Rule + +The BCQuality knowledge mirror is machine-local, never repo-local. It lives at +`~/.claude/bcquality-knowledge/` on each developer's machine, populated by +`~/.claude/sync-bcquality-knowledge.ps1`, and is shared by every CURABIS repo +on that machine. One sync per machine per upstream change covers all repos. + +Project CLAUDE.md files point at the machine mirror using +`~/.claude/...` / `%USERPROFILE%` — never a literal `C:\Users\\...` +path — and include the self-heal instruction (if the mirror or sync script is +missing, fetch the script as raw bytes from BCQuality and run it) so a fresh +clone works on a fresh machine. + +CI and cloud agents have no developer machine: they fetch the rules themselves +via `.github/bcquality.config.yaml` (repo + ref + enabled-layers) — not from a +committed mirror. + +## What NOT to do + +- Do not commit `.github/.agents/bcquality-knowledge/` (or any knowledge + mirror) into a project repository +- Do not point a project CLAUDE.md at one developer's literal profile path + (`C:\Users\mid\...`) — that breaks every other developer on the project +- Do not deploy `sync-bcquality-knowledge.ps1` into `.github/.agents/` — its + destination follows the script's own location, which is what created + repo-local mirrors in the first place +- Do not assume "the repo builds, so the rules are current" — mirror freshness + is a machine concern, gated by the machine's BCQuality version marker + +## Signal to watch for + +At session start or during Mode B, any of these means the project predates +setup v7 and needs the Mode B v6-era cleanup (remove the repo mirror, +gitignore the path, repoint CLAUDE.md at the machine mirror): + +- `.github/.agents/bcquality-knowledge/` exists in the repository +- CLAUDE.md contains a literal developer profile path (`C:\Users\\.claude\...`) +- CLAUDE.md points its BCQuality section at `.github/.agents/bcquality-knowledge/` + +## Message to developer + +When a repo-local mirror or hardcoded mirror path is found, tell the developer +before continuing: this repo uses an obsolete BCQuality mirror model +(repo-local mirror and/or hardcoded developer path in CLAUDE.md); the standard +is the machine-local mirror in `~/.claude/bcquality-knowledge/`; offer to run +"Opdater CURABIS Standard fra BCQuality" to migrate now. diff --git a/custom/setup/curabis-standard.agent.md b/custom/setup/curabis-standard.agent.md index 341f839..80ff85f 100644 --- a/custom/setup/curabis-standard.agent.md +++ b/custom/setup/curabis-standard.agent.md @@ -1,17 +1,18 @@ --- kind: action-skill id: curabis-standard-setup -version: 6 +version: 7 title: CURABIS Standard — Project Setup description: > Configures a new or existing repository to the CURABIS Standard development environment. Writes CLAUDE.md, BCQuality agents, .mcp.json and cspell.json - from authoritative templates in BCQuality. Deploys bc-mcp-bridge.js to the - developer's machine. Syncs a local three-layer BCQuality knowledge mirror - (custom/community/microsoft + INDEX.md) into the repo. Also handles updates - to an already-configured project. + from authoritative templates in BCQuality. Deploys bc-mcp-bridge.js and the + three-layer BCQuality knowledge mirror (custom/community/microsoft + INDEX.md) + to the developer's machine (~/.claude/) — the mirror is machine-local and is + never committed to a project repository. Also handles updates to an + already-configured project, including cleanup of v6-era repo-local mirrors. inputs: [repo-root] -outputs: [CLAUDE.md, .mcp.json, .github/.agents/*, .github/.agents/bcquality-knowledge/, cspell.json, projectmemory/, docs/] +outputs: [CLAUDE.md, .mcp.json, .github/.agents/*, ~/.claude/bcquality-knowledge/, cspell.json, projectmemory/, docs/] domain: setup keywords: [setup, bootstrap, update, mcp, bcquality, standard, new-project] --- @@ -147,20 +148,27 @@ This file is read automatically by Claude Code at the start of every session. At the start of every session, before doing anything else: 1. Read `.github/.agents/bcquality.agent.md` -2. Read knowledge files vendored locally under `.github/.agents/bcquality-knowledge/`: +2. Read BCQuality knowledge files from the machine-local mirror at + `~/.claude/bcquality-knowledge/` (Windows: `%USERPROFILE%\.claude\bcquality-knowledge\`): - **`custom/`** — always read in full (CURABIS-specific rules, always active) - **`community/`** and **`microsoft/`** — do NOT read in full (~200 files is too much to preload every session). Instead read `INDEX.md` first and open only the files whose domain/keywords match the task at hand. -These files are a local copy of the Curabis BCQuality knowledge base, spanning -all three layers (custom/community/microsoft). They are read from disk each -session — no network fetch required. Refresh them from upstream periodically -(e.g. monthly, or whenever a session flags the mirror as stale) by running: +The mirror covers all three BCQuality layers and lives on the developer's +machine, shared by every CURABIS repo on it. It is deliberately NOT committed +to this repository (BCQuality rule +`bcquality-knowledge-must-mirror-to-machine-not-repo`) — one sync per machine +covers every repo, and the repo history stays free of upstream rule churn. - powershell -File .github/.agents/sync-bcquality-knowledge.ps1 +If `~/.claude/bcquality-knowledge/` is missing or empty, self-heal before continuing: -Then review the diff and commit any changes. + powershell -ExecutionPolicy Bypass -File "$env:USERPROFILE\.claude\sync-bcquality-knowledge.ps1" + +If the sync script itself is missing, first download it AS RAW BYTES (do not +decode/re-encode — use `Invoke-WebRequest -OutFile`) from +`https://raw.githubusercontent.com/Curabis/BCQuality/main/custom/setup/sync-bcquality-knowledge.ps1` +to `~/.claude/sync-bcquality-knowledge.ps1`, then run it. These rules are always active. @@ -360,20 +368,32 @@ Fetch and write verbatim: Create `.github/.agents/` if it does not exist. -#### 4c-2. bcquality-knowledge/ (local mirror of all three BCQuality layers) +#### 4c-2. bcquality-knowledge — machine-local mirror (NEVER in the repo) -1. Fetch `{BASE}/sync-bcquality-knowledge.ps1` → write to - `.github/.agents/sync-bcquality-knowledge.ps1` -2. Run it once: `powershell -ExecutionPolicy Bypass -File .github/.agents/sync-bcquality-knowledge.ps1` - This populates `.github/.agents/bcquality-knowledge/{custom,community,microsoft}/` +The knowledge mirror lives on the developer's machine and is shared by every +CURABIS repo on that machine: `~/.claude/bcquality-knowledge/`. It must never +be committed to a project repository (BCQuality rule +`bcquality-knowledge-must-mirror-to-machine-not-repo`). Rationale: developers +switch between many repos daily — N per-repo mirrors are permanently out of +sync with each other, while one machine mirror needs exactly one sync per +upstream change. + +1. Fetch `{BASE}/sync-bcquality-knowledge.ps1` → write AS RAW BYTES + (`Invoke-WebRequest -OutFile`, never via string content — re-encoding + corrupts UTF-8) to `~/.claude/sync-bcquality-knowledge.ps1` +2. Run it once: + `powershell -ExecutionPolicy Bypass -File "$env:USERPROFILE\.claude\sync-bcquality-knowledge.ps1"` + This populates `~/.claude/bcquality-knowledge/{custom,community,microsoft}/` plus an `INDEX.md` (domain + keywords per file, for relevance-based lookup — `custom/` is always read in full, `community/` and `microsoft/` are scanned via the index rather than preloaded, since together they run into the hundreds of files). -3. Confirm: "bcquality-knowledge/ synkroniseret — [antal] filer på tværs af 3 lag." +3. Add `.github/.agents/bcquality-knowledge/` to the repo's `.gitignore`, so no + future session can accidentally commit a repo-local mirror. +4. Confirm: "bcquality-knowledge synkroniseret til din maskine — [antal] filer, 3 lag." This mirror is what Step 4a's generated CLAUDE.md instructs Claude to read at session start. Without this step, the CLAUDE.md reference in 4a points at a -folder that doesn't exist yet. +folder that doesn't exist yet on a fresh machine. #### 4d. cspell.json @@ -470,8 +490,9 @@ Never touches `CLAUDE.md`, `projectmemory/`, `docs/`, or `~/.bc-mcp.config.json` | `.github/.agents/weber.agent.md` | Fetch fresh from BCQuality, overwrite (add if missing) | | `.github/.agents/algo-settings.agent.md` | Fetch fresh from BCQuality, overwrite (add if missing) | | `.github/.agents/smiley.agent.md` | Fetch fresh from BCQuality, overwrite (add if missing) | -| `.github/.agents/sync-bcquality-knowledge.ps1` | Fetch fresh from BCQuality, overwrite (add if missing) | -| `.github/.agents/bcquality-knowledge/` | Re-run the sync script (see below), commit the diff | +| `~/.claude/sync-bcquality-knowledge.ps1` | Fetch fresh from BCQuality (raw bytes), overwrite (add if missing) | +| `~/.claude/bcquality-knowledge/` | Re-run the sync script (see below) — machine-local, nothing to commit | +| `.github/.agents/bcquality-knowledge/` + `.github/.agents/sync-bcquality-knowledge.ps1` | v6-era repo-local mirror: propose removal (see below) | | `cspell.json` — words from template | Merge new words, keep project words | | `.mcp.json` — `al` entry | Add if `find-altool.ps1` now exists and entry is missing | | `.mcp.json` — `businesscentral` path | Validate and correct if wrong (see below) | @@ -479,26 +500,48 @@ Never touches `CLAUDE.md`, `projectmemory/`, `docs/`, or `~/.bc-mcp.config.json` | `HEARTBEAT.md` | Create from template if missing (substitute tokens), never overwrite | | `docs/specs/`, `docs/decisions/`, `docs/cleanup/` | Create if missing, never overwrite content | -### bcquality-knowledge/ re-sync (Mode B) +### bcquality-knowledge — machine re-sync (Mode B) -After overwriting `.github/.agents/sync-bcquality-knowledge.ps1`, always re-run it: +After overwriting `~/.claude/sync-bcquality-knowledge.ps1`, always re-run it: ``` -powershell -ExecutionPolicy Bypass -File .github/.agents/sync-bcquality-knowledge.ps1 +powershell -ExecutionPolicy Bypass -File "$env:USERPROFILE\.claude\sync-bcquality-knowledge.ps1" ``` -This refreshes `.github/.agents/bcquality-knowledge/{custom,community,microsoft}/` +This refreshes `~/.claude/bcquality-knowledge/{custom,community,microsoft}/` and regenerates `INDEX.md` from the live BCQuality tree. Run this every time Mode B runs, not just when the script itself changed — the mirror goes stale independently -of the script (new upstream knowledge files land on their own schedule). Stage the -resulting diff for the update commit in "After update — report and commit" below. +of the script (new upstream knowledge files land on their own schedule). The mirror +is machine-local: there is no repo diff to stage. -If `.github/.agents/sync-bcquality-knowledge.ps1` does not exist yet (project set up -before this mechanism existed): fetch it, run it, and also check whether the -project's CLAUDE.md still has the old flat `architecture/*.md, testing/*.md, mcp/*.md` -BCQuality-reading instruction from before the three-layer mirror existed. If so, propose -replacing it with the current template from Step 4a and ask for confirmation before -editing CLAUDE.md (same confirmation gate as the agent-synligheds-check below). +### v6-era repo-local mirror — cleanup (Mode B) + +Projects configured under setup v6 have the mirror committed INSIDE the repo. +Detect and clean up: + +1. If `.github/.agents/bcquality-knowledge/` exists in the repo (tracked or not), + propose removing it — ask for confirmation first: + + ``` + ⚠️ Dette repo indeholder en v6-æra repo-lokal BCQuality-mirror + (.github/.agents/bcquality-knowledge/, ~[antal] filer). Standarden er nu + maskin-lokal mirror (~/.claude/bcquality-knowledge/). Må jeg fjerne + repo-mirroren og gitignore stien? (ja/nej) + ``` + + On yes: `git rm -r --cached .github/.agents/bcquality-knowledge/` (if tracked), + delete the folder, delete `.github/.agents/sync-bcquality-knowledge.ps1` (its + `$PSScriptRoot`-relative destination is what created the repo mirror), and add + `.github/.agents/bcquality-knowledge/` to `.gitignore`. + +2. Check the project's CLAUDE.md `## BCQuality` section for obsolete forms: + - a flat list of `raw.githubusercontent.com/...` knowledge URLs (pre-mirror era) + - a reference to `.github/.agents/bcquality-knowledge/` (v6 repo-mirror era) + - a literal per-developer path such as `C:\Users\\.claude\...` — must be + `~/.claude/...` / `%USERPROFILE%`, never one developer's username + If any match, propose replacing the section with the current template from + Step 4a and ask for confirmation before editing CLAUDE.md (same confirmation + gate as the agent-synligheds-check below). ### .mcp.json — hardcoded developer-path validation (Mode B) diff --git a/custom/setup/sync-bcquality-knowledge.ps1 b/custom/setup/sync-bcquality-knowledge.ps1 index 9ad031b..375bc28 100644 --- a/custom/setup/sync-bcquality-knowledge.ps1 +++ b/custom/setup/sync-bcquality-knowledge.ps1 @@ -1,4 +1,4 @@ -# Refresh the local mirror of the Curabis BCQuality knowledge base. +# Refresh the MACHINE-LOCAL mirror of the Curabis BCQuality knowledge base. # # Mirrors three layers from https://github.com/Curabis/BCQuality: # custom/ - Curabis org-specific rules (ALWAYS read in full each session) @@ -11,14 +11,17 @@ # keywords from each file's frontmatter) so an agent can scan and pull only the # files relevant to a task instead of loading all ~100 every session. # -# Run periodically, then review the diff and commit: -# pwsh .github/.agents/sync-bcquality-knowledge.ps1 +# The mirror is per developer machine (~/.claude/bcquality-knowledge/), shared +# by every CURABIS repo on it. It is NEVER committed to a project repository - +# see BCQuality rule bcquality-knowledge-must-mirror-to-machine-not-repo. +# One sync per machine covers every repo. Run periodically: +# powershell -ExecutionPolicy Bypass -File "$env:USERPROFILE\.claude\sync-bcquality-knowledge.ps1" $ErrorActionPreference = 'Stop' $repo = 'Curabis/BCQuality' $branch = 'main' -$dest = Join-Path $PSScriptRoot 'bcquality-knowledge' +$dest = Join-Path $env:USERPROFILE '.claude\bcquality-knowledge' $staging = "$dest.tmp" $rawBase = "https://raw.githubusercontent.com/$repo/$branch" $treeUrl = "https://api.github.com/repos/$repo/git/trees/$branch" + '?recursive=1' @@ -121,5 +124,5 @@ Rename-Item -Path $staging -NewName (Split-Path $dest -Leaf) Write-Host '' Write-Host "Done. $($files.Count) files across $($layerMap.Count) layers." -Write-Host "Review changes with: git diff $dest" +Write-Host "Machine-local mirror updated: $dest" exit $rc