chore(memory): BDR-064 + LRN-122 + LRN-123 — ship-feature claude-global-md-rename
This commit is contained in:
Bastien Chanot
@@ -83,6 +83,8 @@ rules:
|
||||
| BDR-060 | 2026-07-08 | job9: CC orchestration floor = v2.1.172 (nested dispatch), supersedes implicit v2.1.83 whole-system floor | accepted |
|
||||
| BDR-061 | 2026-07-08 | job9: seo/geo analyzers → fix-bundle→L1 by doctrine (validator-analyzer pattern), not by version constraint | accepted |
|
||||
| BDR-062 | 2026-07-08 | supersede BDR-031's 275 CLAUDE.md target — 305 assumed reality (extraction done at job1; more compression costs clarity > tokens); guard threshold realigned 280→320 | accepted |
|
||||
| BDR-063 | 2026-07-10 | GSC multi-account: OAuth2 installed-app flow + label-keyed token store, explicit (account,property) args, no global state | accepted |
|
||||
| BDR-064 | 2026-07-14 | global memory split: repo file → CLAUDE.global.md (deployed name unchanged), CLAUDE.md freed for project scope; consumer/maintainer wording rule | accepted |
|
||||
|
||||
---
|
||||
|
||||
@@ -950,3 +952,14 @@ rules:
|
||||
- **Why**: user needs real field data (the one edge marketplace `claude-seo` had that personal skills lacked); multi-account without cross-site leakage; secrets never in code (all from `~/.claude/.env`).
|
||||
- **Alternatives rejected**: (a) service-account — GSC needs per-property owner grant + no interactive consent, wrong for a personal multi-client tool. (b) API-key-only — GSC has no key auth (CrUX does → `CRUX_API_KEY`). (c) single "current account" global + switch verb — a race the moment two audits run; explicit args dissolve it by construction.
|
||||
- **Reference**: `lib/seo-data/` (tokenstore.py, connect.py, google_seo.py, fetch.sh), `lib/seo-data/README.md`; fronted by [[LRN-119]] (fail-open contract).
|
||||
|
||||
---
|
||||
|
||||
## BDR-064 — Global memory split: repo global file → CLAUDE.global.md, CLAUDE.md freed for project scope
|
||||
|
||||
- **Date**: 2026-07-14
|
||||
- **Status**: accepted (shipped feature/claude-global-md-rename, merge pending human GO)
|
||||
- **Decision**: repo-root global memory `git mv` → `CLAUDE.global.md`; deployed name unchanged (`~/.claude/CLAUDE.md` symlink via link.sh). `CLAUDE.md` name freed → real project-scope memory for claude-config (Health Stack + rules/ doctrine — ex-"This repo only" section + ex-rules/README body; rules/README = 3-line pointer, keeps `paths:` frontmatter). Wording rule (user-arbitrated): consumer-facing hook strings say "global CLAUDE.md" (deployed name — foreign sessions resolve via symlink, repo filename means nothing there); maintainer comments say `CLAUDE.global.md`. Guards follow: session-start 320-guard path, doctor EXACT readlink-target check (new), GUARDED_CONFIGS 4 entries (keeps "CLAUDE.md" — graphify rewrite target = project file now), doc-commit exclusions, CHANGELOG BREAKING(layout) line ("run bash link.sh once after pull").
|
||||
- **Why**: "This repo only" section + rules/README doctrine loaded in EVERY project (~40+280 tok waste + foreign-project glob over-match); repo had no project-scope memory slot — filename occupied by global content.
|
||||
- **Alternatives rejected**: `CLAUDE.prod.md` name ("prod" implies deploy env that doesn't exist); project `.claude/rules/repo.md` (works, less idiomatic than project CLAUDE.md, no natural home for future repo-specific content). NOT a revival of BDR-021's rejected 2-file split — that was global content in 2 SYNCED files; here scopes disjoint, zero sync.
|
||||
- **Reference**: feature/claude-global-md-rename (9496538 rename R98%, e9a38a0 guards), spec `docs/superpowers/specs/2026-07-12-claude-global-md-rename-design.md`. Linked [[BDR-021]], [[BDR-031]], [[BDR-062]], [[LRN-122]], [[LRN-123]].
|
||||
|
||||
@@ -377,3 +377,6 @@ rules:
|
||||
- Docs synced (`/doc`, `4a15c73` on `chore/doc-sync-gsc-crux`): README (seo-connect, make-test glob, /seo row) + USAGE (/seo FULL real-data) + CHANGELOG Added entry. Pending: merge `chore/doc-sync-gsc-crux`→develop (human GO), then delete transient spec+plan `docs/superpowers/…gsc-crux…`.
|
||||
- Post-ship housekeeping merged to develop: `chore/doc-sync-gsc-crux` (`8a1fac0`, docs+memory+transient-cleanup), then `bugfix/seo-connect-env-source` (`61a98d3`) — `make seo-connect` never sourced `~/.claude/.env` so OAuth creds never reached connect.py; found by real `make seo-connect` run (403 discover_properties after consent = Search Console API not enabled + the env bug). Live OAuth validated end-to-end by user (consent OK, app published to Production for non-expiring refresh token).
|
||||
- `/feat` feature/seo-account-mgmt (unmerged, human GO pending): account-management verbs — tokenstore remove/clear, fetch.sh forget, connect.sh wrapper (sources env, runs from any project), `/seo connect|accounts|forget` routing, Makefile delegates to wrapper. Commits `8bf7459` (feat) + `887341d` (doc USAGE). Security loop hit its cap: 3 GATE-2 BLOCKs on the label guard (injection → parser differential → per-line-grep newline), closed categorically by a whole-string POSIX `case` guard [[LRN-121]]; final fresh scan PASS (~50 vectors, 0 bypass). 85/85 engine + `make test` green throughout. forget = local delete, NOT Google revocation (surfaces myaccount.google.com/permissions).
|
||||
|
||||
## 2026-07-14
|
||||
- `/ship-feature` feature/claude-global-md-rename (unmerged, human GO pending): global memory → CLAUDE.global.md + project-scope CLAUDE.md, 8 commits (a4ee7e1 docs → e9a38a0 guards). Full pipeline: analyzer + contract (17 criteria), brainstorm/spec/plan gates, SDD 5 tasks (all task reviews Approved), verifier CONFORME 17/17 (after user-arbitrated criterion-9 consumer-wording + FILE-SCOPE [gated] enrichment), security PASS (semgrep 43 rules, 0), final review "Yes" after 2 Important fixes (guard-test drift → 7/7; doctor exact-target check). Decided [[BDR-064]]; learned [[LRN-122]] (2-commit rename split), [[LRN-123]] (exact symlink target). `make test` green throughout. settings.json plugin toggles = session-scoped, NOT committed — restore (gstack/ui-ux-pro-max/frontend-design/emil-design-eng/darwin-skill/magic ON) after merge.
|
||||
|
||||
@@ -1214,3 +1214,21 @@ rules:
|
||||
- **why it matters**: three distinct bypasses of the SAME guard = the approach was wrong, not each patch. `grep`'s line-orientation + locale-sensitive ranges, plus argv-prescan-vs-real-parser grammar drift, are the three classic ways an allowlist "passes" a string it shouldn't. Whole-string `case` in C locale closes all three at once. These were defense-in-depth (downstream used `"$2"`/`"$@"`/JSON-key, never `sh -c`/`eval` → not exploitable in the real exec chain) — but the backstop still took a categorical rewrite, and 3 security-gate BLOCKs to get there.
|
||||
- **future application**: validate shell input WHOLE-STRING (`case` or bash `[[ =~ ]]`), never `grep -q` (per-line). Set `LC_ALL=C` for byte-wise ranges. A guard that pre-scans argv must be STRICTER than the downstream parser (reject `=`-joined/abbrev) or validate post-parse against the value the parser settled on. When a fix is bypassed twice → STOP patching, replace the mechanism (re-plan, not whack-a-mole).
|
||||
- **cousin**: [[LRN-119]] (fail-open engine this hardens), [[BDR-063]] (token store whose labels these guard), [[LRN-045]] (renaming-command leak-guard regexes — same charset-guard family).
|
||||
|
||||
---
|
||||
|
||||
## LRN-122 — git mv + recreate source path in same commit = rename detection dead
|
||||
|
||||
- **pattern**: rename file + create NEW file at old path in ONE commit → git never pairs the rename (source path never vanishes — index sees modify(old)+add(new)). `git log --follow` chain lost; deterministic, persists forever. Fix: TWO commits — pure rename first (paired at R~98%), recreation second. Found live: Task-2 implementer hit the plan's own "2 hunks" STOP gate, diagnosed root cause, escalated instead of patching around it.
|
||||
- **why**: contract criterion (history preserved) outranks plan packaging ("atomic commit"). Commit-level atomicity ≠ deploy-level atomicity — deployed symlink already fixed by running link.sh, independent of commit split.
|
||||
- **future application**: ANY rename-and-replace-in-place (config forks, template splits, versioned API files). Old path must be re-occupied → split commits; verify `git diff -M --stat parent` shows the `=>` rename line before proceeding.
|
||||
- **cousin**: [[BDR-064]] (the split this served), [[LRN-120]] (review-base hygiene — same git-range-semantics family).
|
||||
|
||||
---
|
||||
|
||||
## LRN-123 — "resolves inside repo" symlink check green-lights stale link once old path re-occupied
|
||||
|
||||
- **pattern**: doctor's check_symlink asserted only `readlink -f` lands inside `$REPO` — safe while ONE candidate file existed. Rename freed old path for a NEW file → stale post-pull link (`~/.claude/CLAUDE.md` → `$REPO/CLAUDE.md`) resolves to project file (inside repo) → check PASS, global doctrine silently absent every session. Fix: assert EXACT readlink target (`$REPO/CLAUDE.global.md`), warn + remedy cmd (`run: bash link.sh`). Caught by final whole-branch review (fresh most-capable model), not by any earlier gate.
|
||||
- **why**: containment predicates (inside-dir, prefix-match) silently weaken the moment layout gains a second valid-looking target; exactness costs nothing.
|
||||
- **future application**: symlink/path health checks → assert exact expected target whenever the old target path can be re-occupied; test all three states (correct / stale / missing).
|
||||
- **cousin**: [[BDR-064]], [[LRN-104]] (hook message = test contract — same guard-must-follow-the-change family).
|
||||
|
||||
@@ -0,0 +1,45 @@
|
||||
# CONTRACT — claude-global-md-rename
|
||||
- date: 2026-07-12 | flow: ship-feature | branch: (feature branch off develop, created at STEP 4)
|
||||
- status: active
|
||||
|
||||
## REQUEST (verbatim — IMMUTABLE)
|
||||
> pour les soucis 1 et 2, ne serais-ce pas plus judicieux de mettre notre claude.md de ce repo, qui es tle global, le renommer en CLAUDE.prod.md ou quelqeu chose comme ca, avec tout ce qui concerne le userscope, le link.sh fait un lien symbolique de ce fichier avec ce nom vers ~/.claude/CLAUDE.md car on peut avoir un nom differnt du lien, et ca permet d'avoir le claude.md du projet dasn le quel on met ces deux partie qui sont pas destine au userscope. qu'en pense tu ?
|
||||
|
||||
> oui, utilise /ship-feature pour faire les modification vers un CLAUDE.global.md et toute les dependance et iunstallateur et update etc
|
||||
|
||||
(Name arbitrated in conversation: `CLAUDE.global.md`, not `CLAUDE.prod.md`.)
|
||||
|
||||
## CLARIFICATIONS
|
||||
none — request complete (design questions resolved at STEP 1 brainstorm, gated at STEP 3)
|
||||
|
||||
## ACCEPTANCE CRITERIA
|
||||
1. `CLAUDE.global.md` exists at repo root, renamed via `git mv` (history preserved: `git log --follow CLAUDE.global.md` shows pre-rename commits), containing the former global content MINUS the `# This repo only (claude-config)` section, PLUS a short scope header stating it is the user-scope global memory deployed as `~/.claude/CLAUDE.md`.
|
||||
2. A new project-level `CLAUDE.md` exists at repo root containing: a short scope header (project-only, not user-scope), the former "This repo only" content (Health Stack / shellcheck), and the rules/ maintenance doctrine migrated from `rules/README.md` (what belongs in rules/, lazy-load semantics, machine-owned context7/BDR-053 note).
|
||||
3. `link.sh` links `<repo>/CLAUDE.global.md` → `~/.claude/CLAUDE.md`; after running it, `readlink ~/.claude/CLAUDE.md` resolves to `<repo>/CLAUDE.global.md` (stale link replaced, no dangling symlink).
|
||||
4. `hooks/session-start.sh` line-count guard (BDR-062) reads `CLAUDE.global.md` (new path), threshold 320 unchanged, and does not silently fail-open on the old path.
|
||||
5. `doctor.sh` passes: `~/.claude/CLAUDE.md` symlink check green; size/token reporting reads `CLAUDE.global.md`.
|
||||
6. `install-plugins.sh` GUARDED_CONFIGS protects `CLAUDE.global.md` (installer drift guard follows the renamed file).
|
||||
7. `lib/doc-commit.sh` exclusion list covers `CLAUDE.global.md` as read-only/never-target (BDR-022 unchanged in spirit).
|
||||
8. `rules/README.md` slimmed to a minimal pointer (keeps `paths:` frontmatter; doctrine lives in the project CLAUDE.md).
|
||||
9. No stale script reference remains: `grep -rn 'CLAUDE\.md' *.sh hooks/*.sh lib/*.sh` shows no reference meaning the repo-root GLOBAL file under its old name (references to `~/.claude/CLAUDE.md` symlink name and to per-project CLAUDE.md concept are expected and unchanged). [gated 2026-07-14 clarification, user-arbitrated] CONSUMER-facing hook strings (messages injected into sessions, which run in any project) reference the global by its DEPLOYED name — "global CLAUDE.md" — because consumers resolve it via ~/.claude/CLAUDE.md; only MAINTAINER-facing comments use the repo filename CLAUDE.global.md. Both are conformant, not stale.
|
||||
10. `README.md` / `USAGE.md` / `MIGRATION.md` layout descriptions updated where they mean the repo-root global file.
|
||||
11. `shellcheck` passes on every modified `.sh` file (repo Health Stack).
|
||||
12. [gated 2026-07-13] New project CLAUDE.md is MINIMAL — scope header + Health Stack + rules/ maintenance doctrine (incl. context7/BDR-053 note and the foreign-project glob caveat); no empty template sections.
|
||||
13. [gated 2026-07-13] rules/README.md keeps `paths: ["rules/**"]` frontmatter; body reduced to a pointer referencing the project CLAUDE.md.
|
||||
14. [gated 2026-07-13] Global file nets 305 → 301 lines; scope header = 2-line HTML comment above the title; `git diff -M --cached -- CLAUDE.global.md` shows exactly two hunks (header insertion, tail-section deletion).
|
||||
15. [gated 2026-07-13] `GUARDED_CONFIGS` has 4 entries: keeps `"CLAUDE.md"` (graphify's rewrite target = project file) AND adds `"CLAUDE.global.md"`; mktemp error message lists all four.
|
||||
16. [gated 2026-07-13] USAGE.md / MIGRATION.md / update-all.sh verified as having zero references to the repo-root global file — deliberately not edited.
|
||||
17. [gated 2026-07-13] Spec + plan docs are the feature branch's first commit; the session-scoped plugin toggles in settings.json are NEVER staged in any commit of this branch.
|
||||
|
||||
## FILE SCOPE
|
||||
- CLAUDE.md → CLAUDE.global.md (git mv + content split)
|
||||
- CLAUDE.md (new project-level file)
|
||||
- link.sh
|
||||
- hooks/session-start.sh
|
||||
- doctor.sh
|
||||
- install-plugins.sh
|
||||
- lib/doc-commit.sh
|
||||
- rules/README.md
|
||||
- README.md, USAGE.md, MIGRATION.md (doc references)
|
||||
- [gated 2026-07-14] hooks/config-protection.sh, hooks/design-toolchain-reminder.sh (required by criterion 9's sweep — global-file references in comments/messages)
|
||||
- [gated 2026-07-14] docs/superpowers/specs/2026-07-12-claude-global-md-rename-design.md, docs/superpowers/plans/2026-07-13-claude-global-md-rename.md (required by criterion 17 — branch's first commit)
|
||||
Reference in New Issue
Block a user