From 6ca2c3b6172e5aa284ca34370248db53df50671f Mon Sep 17 00:00:00 2001 From: bchanot Date: Thu, 29 Oct 2026 11:30:31 +0100 Subject: [PATCH 01/21] docs(spec): phase 1 native context diet (design) --- .../specs/2026-10-29-context-diet-design.md | 119 ++++++++++++++++++ 1 file changed, 119 insertions(+) create mode 100644 docs/superpowers/specs/2026-10-29-context-diet-design.md diff --git a/docs/superpowers/specs/2026-10-29-context-diet-design.md b/docs/superpowers/specs/2026-10-29-context-diet-design.md new file mode 100644 index 0000000..ea8633e --- /dev/null +++ b/docs/superpowers/specs/2026-10-29-context-diet-design.md @@ -0,0 +1,119 @@ +# Phase 1 — native context diet (design) + +Contract: `.claude/tasks/contracts/2026-10-28-context-diet-1944.md` (the +acceptance criteria live there). Queue: BDR-125, TODO bullet "Phase 1, +native context diet: no mod". Approved in chat 2026-10-29 (A = 200 chars, +B = extend the census). + +## Goal + +Cut the always-on context loaded by every session, without a mod: each +section moves to the native carrier that fires when it is needed (path rule, +hook, lib Read by our skills, setting). Nothing is lost: every moved text is +reachable where it serves. Estimate: −2 to −2.5k tokens per session +(baseline 2026-10-28: 30.5k total, Memory files 9.6k, System prompt 4.4k, +Custom agents 2.6k). + +## Carriers + +| Source (develop 017a28b) | Carrier | Always-on residue | +|---|---|---| +| auto-memory system section | `"autoMemoryEnabled": false` (settings.json) | none | +| CLAUDE.global.md § Design work — full toolchain (tiered by scope) | appended verbatim to `rules/web-building.md` (same UI globs) | Skill-routing line points to it; design hook one-liner says Read it | +| CLAUDE.global.md § graphify usage body | `hooks/session-start.sh`, free lines after the box, only when `/graphify-out/graph.json` exists | `## graphify` + the 200-file threshold rule | +| CLAUDE.global.md § Public websites — never SPA + `rules/default-language.md` | `lib/architecture-defaults.md` (verbatim, H1 of the language rule demoted to H2) | one line under `# Architecture decisions` naming Rust default, never SPA, `/api/v1`, the lib path | +| CLAUDE.global.md § Web APIs — always versioned | `rules/rest-api.md` § Versioning (full text, replaces "Not repeated here"); the lib carries a one-line summary + pointer | named in the architecture line | +| `rules/secure-by-default.md` §4 Supabase, §6 Cloud functions bodies | `rules/supabase.md` (`**/supabase/**`, `**/*supabase*.*`), `rules/cloud-functions.md` (`**/functions/**`, `**/serverless.*`, `**/firebase.json`), bullets verbatim | the two headings stay, one line each (critical rule + pointer) | +| `agents/*.md` `description:` (23 tracked) | trimmed at the source to ≤ 200 chars | n/a | + +`rules/default-language.md` is deleted. The always-on rule set becomes +exactly `writing-style.md` + `secure-by-default.md`. + +## Exact visible strings + +- CLAUDE.global.md, under `# Architecture decisions` (replaces the intro and + the two sections): + `New project, scaffolding, stack brainstorm or whole-project rewrite: Rust + by default, a public site is never a SPA (Astro; Next.js when SSR is + needed), every web API versioned `/api/v1/` from day one. Read + `~/.claude/lib/architecture-defaults.md` before proposing a stack.` +- CLAUDE.global.md Skill routing: `Design / UI (build, system, audit, + polish) → Read ~/.claude/rules/web-building.md § Design work first`. +- Design hook stdout: `Design work detected → Read + ~/.claude/rules/web-building.md § "Design work — full toolchain" first. + Trivial (≤2 files, cosmetic) → /hotfix.` (one line). +- secure-by-default.md §4: `- RLS on every table, never a service_role or + secret key client-side. Full domain: rules/supabase.md (loads on Supabase + files).` §6: `- Max instances and a timeout on every function, never a + self-trigger. Full domain: rules/cloud-functions.md (loads on function + files).` + +## Readers of the lib + +init-project (interviewer row, STEP 3 brainstorm input, STEP 5 scaffolder +brief), agents/interviewer.md, agents/scaffolder.md, ship-feature STEP 1 +(when the feature picks a language, framework or API shape), onboard STEP 6 +(audit briefs), audit-delta conformity axis. agents/seo-analyzer.md cites the +lib for "public sites are never SPAs". /refactor is not edited (no +whole-project mode; the always-on line covers it). + +## Hook fixes (user scope additions, pass A) + +- design-toolchain-reminder.sh skips ``. +- Its suite runs every call under a temp HOME (1,770 logged fires were suite + prompts); the exact one-liner is asserted. + +## Auto memories + +One decision entry into robin_petier's registry (LAN dev server: never start +unprompted, detached form on ask, a server found running = user-started → ask +before killing), via `memory.sh -C`, on a `chore/*` branch of that repo, text +shown to the user first. The other four are dropped (already in registries, +or contrary to doctrine). The user removes the auto-memory dirs by hand. +`lib/doctor-automem.sh` + suite: doctor warns while any +`~/.claude/projects/*/memory/` holds a file. + +## Proofs + +- New suite `lib/tests/user-rules.test.sh`: every `rules/*.md` frontmatter + parses (one-line JSON `paths:` or none); the always-on set is exactly + writing-style + secure-by-default; flip controls (two-line `paths:`, an + extra always-on file). +- Census extension (`lib/tests/doctrine-citers.test.sh`): citations of + `rules/.md § Label` and `lib/.md § Label` resolve against that file's + headings; flip-tested. +- New suite for the session-start graphify branch (graph present / absent). +- `lib/tests/doctor-automem.test.sh` (empty → silent, one file → warn, count). +- Controller proof (journaled, not in make test): `project-rules.sh -C + matches ` per new glob in a real project; one headless + session per moved path rule whose prompt names the Read tool, logged + `path_glob_match` (faunosteo supabase, game supabase/functions, a UI file); + `/context` after vs baseline. + +## Cleanup and citers + +lib/project-rules.sh:22-23 comment (engine matching is gitignore-style: +trailing `/**` dropped, any depth, hidden dirs included; evidence +InstructionsLoaded `globs: ["rules"]` on `.claude/rules/*.md`); +.claude/rules/rules-maintenance.md (always-on exception list, the +"always-on doctrine stays in CLAUDE.global.md" sentence, matching note); +lib/design-gate.md:48 (stale "+motion / +static" citation); +lib/project-archetypes/rest-api-node.md:58; CLAUDE.global.md Higgsfield line; +hooks/session-start.sh BDR-031 comment; TODO.md phase 1 checked + follow-ups. +CLAUDE.global.md ends ≤ 320 lines. + +## Out of scope + +/refactor edits; the four vendored `impeccable-*` agents; the per-repo memory +v2 upgrade pass; settings.json `model`/`theme` lines written by the user's +`/model` (left uncommitted, user decides). + +## Risks + +- `autoMemoryEnabled: false` may also affect the analyzer's `memory: + project`: checked during the proof, not promised. +- Engine glob semantics differ from compgen: the static suite proves parsing + only; loading is proved by the logged sessions. +- `**/functions/**` also fires in non-cloud `functions/` dirs (≈80 tokens of + noise there), accepted. From d2bd20995ee5b18808060b5748144d1cc19a1ab5 Mon Sep 17 00:00:00 2001 From: bchanot Date: Thu, 29 Oct 2026 11:40:10 +0100 Subject: [PATCH 02/21] docs(plan): phase 1 native context diet --- .../plans/2026-10-29-context-diet.md | 1075 +++++++++++++++++ 1 file changed, 1075 insertions(+) create mode 100644 docs/superpowers/plans/2026-10-29-context-diet.md diff --git a/docs/superpowers/plans/2026-10-29-context-diet.md b/docs/superpowers/plans/2026-10-29-context-diet.md new file mode 100644 index 0000000..cb331cd --- /dev/null +++ b/docs/superpowers/plans/2026-10-29-context-diet.md @@ -0,0 +1,1075 @@ +# Phase 1 native context diet — Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Move four always-on doctrine blocks, two secure-by-default domain bodies and the long agent descriptions to native carriers that load only when needed, and switch off auto memory, without losing any rule. + +**Architecture:** No mod. Each text moves to the carrier whose trigger matches it: a `paths:` rule (loads on Read of a matching file), the SessionStart hook (prints only when a graph exists), a lib file our skills Read, a setting. CLAUDE.global.md keeps one always-on line where plain chat still needs the rule. + +**Tech Stack:** bash 5.3 (shellcheck-clean, GNU + BSD portable, no `grep -P`), markdown doctrine, jq, python3 (`-I`) with PyYAML for one oracle. + +**Spec:** `docs/superpowers/specs/2026-10-29-context-diet-design.md`. Contract (acceptance criteria, judged by the verifier): `.claude/tasks/contracts/2026-10-28-context-diet-1944.md`. Oracles: `.claude/tasks/contracts/c1-*.sh` (already written, do not edit them). + +## Global Constraints + +- Branch `feature/context-diet` (exists). Never commit on develop/main. Never `--no-verify`. Never `git add -A` / `git add .`: add the exact paths listed in the task. +- Moved text is moved VERBATIM (byte-identical lines) unless the task shows the new text. The oracles compare against develop commit `017a28b`. +- Hook stdout strings name deployed paths (`~/.claude/...`); maintainer comments name `CLAUDE.global.md` (BDR-064). +- Foreign-style repo: match the neighbouring code (inline shell, `check()` test idiom, `PASS=%s FAIL=%s` footer, comments only for the why). Doctrine lines ≤ 80 chars; do not add a line over 80 chars to CLAUDE.global.md (3 exist today). +- Tests run only through `make test suite=` or the full `make test`. shellcheck: `shellcheck *.sh hooks/*.sh lib/*.sh` (+ any new `lib/tests/*.sh` you create). +- Bash pitfalls: no `head` reading a producer under pipefail (SIGPIPE rc 141); a sourced lib never changes the caller's shell options. +- `settings.json` has two hunks the USER wrote (`"model"` and `"theme"`, from `/model`): never stage or revert them (Task 7 gives the exact recipe). +- No destructive commands, no file outside this repo (the robin_petier write is a controller step, not yours). + +## Review Focus + +1. A real user prompt that starts with `<` (pasted content: `…`) must still fire the design hook; only `` and `/dev/null || echo 0)" +LINE='Design work detected → Read ~/.claude/rules/web-building.md § "Design work — full toolchain" first. Trivial (≤2 files, cosmetic) → /hotfix.' +pass=0; fail=0 +``` + +Replace the `fire()` definition (2 lines) with + +```bash +fire() { if printf '{"prompt":"%s"}' "$1" | HOME="$T" bash "$H" | grep -q 'full toolchain'; then + echo fire; else echo quiet; fi; } +``` + +After the line `check D11-bare-ux ...` add + +```bash +check D12-agent-msg "$(fire ' [Subagent hand-back] add css header fonts')" quiet +``` + +After the line `check F10-bare-ui ...` add + +```bash +check F11-pasted "$(fire ' add a button')" fire + +# --- The one-liner is a contract (LRN-104): exact text --- +check O1-exact-line "$(printf '{"prompt":"add a button"}' | HOME="$T" bash "$H")" "$LINE" +``` + +Replace the last line `printf 'PASS=%s FAIL=%s\n' "$pass" "$fail"; [ "$fail" -eq 0 ]` with + +```bash +check G1-real-log-untouched "$(wc -l < "$REAL_LOG" 2>/dev/null || echo 0)" "$real_before" + +printf 'PASS=%s FAIL=%s\n' "$pass" "$fail"; [ "$fail" -eq 0 ] +``` + +(The L1 block keeps its own `tmp` dir unchanged.) + +- [ ] **Step 2: Run it, expect FAIL** + +Run: `make test suite=lib/tests/design-toolchain-reminder.test.sh` +Expected: FAIL lines for `D12-agent-msg` (got fire) and `O1-exact-line` (old text); the others pass. + +- [ ] **Step 3: Update the hook** + +In `hooks/design-toolchain-reminder.sh`, replace the header lines + +```bash +# UserPromptSubmit hook. When the prompt carries a UI/design signal, inject a +# reminder to mobilize the full design toolchain (tiered by scope, per CLAUDE.global.md +# "Design work — full toolchain"). A UserPromptSubmit hook's stdout is appended +# to the model's context, so the cat block below becomes additional guidance. +``` + +with + +```bash +# UserPromptSubmit hook. When the prompt carries a UI/design signal, point the +# model at the design toolchain section (tiered by scope). Since BDR-125 +# phase 1 it lives in rules/web-building.md § "Design work — full toolchain", +# not in CLAUDE.global.md: it loads by itself on a UI file Read, and a +# chat-only design request needs this pointer. A UserPromptSubmit hook's +# stdout is appended to the model's context. +``` + +Replace + +```bash +# Harness-generated turns (subagent/task notifications) are not user +# requests — never fire on them (CLAUDE.global.md trigger = a design/UI *request*). +case "$prompt" in + ''*) exit 0 ;; +esac +``` + +with + +```bash +# Harness-generated turns (task notifications, sub-agent hand-backs: 857 of +# 2,779 logged fires on 2026-10-28) are not user requests — never fire on +# them (the Design work trigger = a design/UI *request*). +case "$prompt" in + ''*|'/dev/null); } +usage() { banner "$1" | grep -c 'graphify query'; } + +git init -q "$WORK/repo"; git -C "$WORK/repo" config core.hooksPath /dev/null +mkdir -p "$WORK/repo/app/sub" "$WORK/plain" +check T1-no-graph-silent "$(usage "$WORK/repo")" 0 +check T1b-banner-control "$(banner "$WORK/repo" | grep -c 'Claude Code config')" 1 +mkdir -p "$WORK/repo/graphify-out"; echo '{}' > "$WORK/repo/graphify-out/graph.json" +check T2-graph-prints "$(usage "$WORK/repo")" 1 +check T3-from-subdir "$(usage "$WORK/repo/app/sub")" 1 +check T4-update-rule "$(banner "$WORK/repo" | grep -c 'graphify update \.')" 1 +check T5-not-a-repo "$(usage "$WORK/plain")" 0 +check T5b-not-a-repo-banner "$(banner "$WORK/plain" | grep -c 'Claude Code config')" 1 + +printf 'PASS=%s FAIL=%s\n' "$pass" "$fail"; [ "$fail" -eq 0 ] +``` + +- [ ] **Step 2: Run it, expect FAIL** + +Run: `make test suite=lib/tests/session-start-graphify.test.sh` +Expected: FAIL on T2, T3, T4 (got 0); T1, T1b, T5, T5b pass. + +- [ ] **Step 3: Add the block to session-start.sh** + +In `hooks/session-start.sh`, between the line `[ -n "$EFFORT_WARN" ] && printf '%s\n' "$EFFORT_WARN"` and the final `echo ""`, insert: + +```bash +# graphify usage (BDR-125 phase 1): the rules left CLAUDE.global.md, which +# keeps only the 200-file threshold; they print where a graph exists. +_gx_root=$(git rev-parse --show-toplevel 2>/dev/null) +if [ -n "$_gx_root" ] && [ -f "$_gx_root/graphify-out/graph.json" ]; then + cat <<'EOF' +graphify (graphify-out/graph.json present): +- Codebase-wide question → `graphify query`; relationships → `path A B`; + concept → `explain`. Scoped subgraph beats raw grep. +- Known file / small task → read directly, no graphify. +- `wiki/index.md` → broad-nav entry; `GRAPH_REPORT.md` → whole-architecture. +- After editing code → `graphify update .` (AST-only, free). +EOF +fi +unset _gx_root +``` + +Replace the comment + +```bash +# CLAUDE.global.md line-count guard (anti-regression). BDR-062 supersedes +# BDR-031's 275 target: 305 is the assumed reality (extraction done at +# job1; further compression costs clarity > token gain) — warn past 320. +``` + +with + +```bash +# CLAUDE.global.md line-count guard (anti-regression, BDR-062): warn past +# 320. BDR-125 phase 1 moved Design work, the graphify usage and the +# architecture defaults to their carriers (333 → ~285 lines). +``` + +- [ ] **Step 4: Trim the CLAUDE.global.md section** + +Replace the whole `## graphify` section (heading through `- After editing code → \`graphify update .\` (AST-only, free).`) with: + +``` +## graphify + +Threshold: graphify from 200 tracked code files, never below (banner line +`graphify? N code files ≥ 200, no graph` informs, the user decides; never +build or `graphify claude install` without that go). With a graph +(`graphify-out/graph.json`), the session banner prints the usage rules. +``` + +- [ ] **Step 5: Run, expect PASS** + +Run: `make test suite=lib/tests/session-start-graphify.test.sh`, `make test suite=lib/tests/graphify-gate.test.sh`, `make test suite=lib/tests/memory.test.sh`, `make test suite=lib/tests/push-guard.test.sh` (the last two grep the banner). +Expected: four `all suites green`. `shellcheck hooks/session-start.sh lib/tests/session-start-graphify.test.sh` clean. + +- [ ] **Step 6: Commit** + +```bash +git add CLAUDE.global.md hooks/session-start.sh lib/tests/session-start-graphify.test.sh +git commit -m "feat(graphify): usage rules print from session-start only where a graph exists" +``` + +--- + +### Task 3: Architecture defaults move to lib/architecture-defaults.md; Web APIs to rules/rest-api.md + +**Files:** +- Create: `lib/architecture-defaults.md` +- Delete: `rules/default-language.md` (`git rm`) +- Modify: `CLAUDE.global.md` (`# Architecture decisions` H1: intro + `## Public websites — never SPA` + `## Web APIs — always versioned`, ~142-167) +- Modify: `rules/rest-api.md` (`## Versioning`) +- Modify: `lib/project-archetypes/rest-api-node.md:58` +- Modify (readers): `skills/init-project/SKILL.md` (STEP 3, STEP 5), `agents/interviewer.md:26`, `agents/scaffolder.md` (INPUTS REQUIRED, PHASE 1), `skills/ship-feature/SKILL.md` (STEP 1), `skills/onboard/SKILL.md` (STEP 6), `skills/audit-delta/SKILL.md:276`, `agents/seo-analyzer.md:542-543` + +**Interfaces:** +- Produces: `lib/architecture-defaults.md` headings `## Public websites — never SPA`, `## Default language — Rust`, `## Web APIs — always versioned`; `rules/rest-api.md` heading `## Versioning` with the full rule (Task 6 resolves citations to both). + +- [ ] **Step 1: Run the oracles, expect FAIL** + +Run: `bash .claude/tasks/contracts/c1-arch-moved.sh; bash .claude/tasks/contracts/c1-readers.sh` +Expected: `no lib/architecture-defaults.md`, `no lib in skills/init-project/SKILL.md`. + +- [ ] **Step 2: Create the lib** + +Create `lib/architecture-defaults.md` with exactly this structure: + +``` +# Architecture defaults — read before proposing a stack + +Read at project creation, scaffolding, a stack brainstorm or a whole-project +rewrite: /init-project (interviewer, STEP 3 design, scaffolder), +/ship-feature STEP 1, /onboard audits, /audit-delta conformity. The +always-on line under `~/.claude/CLAUDE.md` § "Architecture decisions" names +the three defaults; the detail lives here (BDR-125 phase 1). + + + + + +## Web APIs — always versioned +Every endpoint `/api/v1/...` from day one; breaking change → `v2`, the old +version keeps working. Full rule: `~/.claude/rules/rest-api.md` § Versioning +(loads on API files). +``` + +One blank line between sections; the `<…>` lines are instructions, not text to write. + +- [ ] **Step 3: Replace the H1 block in CLAUDE.global.md** + +Replace everything from the line `# Architecture decisions` down to (not including) `## Version control — gitflow (universal)` with: + +``` +# Architecture decisions +New project, scaffolding, stack brainstorm or whole-project rewrite: Rust +by default, a public site is never a SPA (Astro; Next.js when SSR is +needed), every web API versioned `/api/v1/` from day one. Read +`~/.claude/lib/architecture-defaults.md` before proposing a stack. + +``` + +- [ ] **Step 4: Web APIs into rules/rest-api.md, delete default-language.md** + +In `rules/rest-api.md` replace + +``` +## Versioning +CLAUDE.md § Web APIs — always versioned. Not repeated here. +``` + +with (body byte-identical to the former CLAUDE.global.md § Web APIs body): + +``` +## Versioning +Every endpoint versioned from day one: `/api/v1/...`, no bare `/api/`; the +router mirrors it (`api/v1/routes/`). Breaking change → `v2`, the old +version keeps working and clients migrate at their pace; non-breaking +additions → current version. Each version is a self-contained contract, +never bent to match a newer one. +``` + +In `lib/project-archetypes/rest-api-node.md` replace + +``` +- Pas de versioning API (/api/v1/) — flag CLAUDE.md : "Web APIs — always versioned" +``` + +with + +``` +- Pas de versioning API (/api/v1/) — flag `rules/rest-api.md` § Versioning +``` + +Run: `git rm -q rules/default-language.md` + +- [ ] **Step 5: Wire the readers** + +`agents/interviewer.md` row "Language not stated": replace `(\`rules/default-language.md\`)` with `(\`~/.claude/lib/architecture-defaults.md\` § Default language)`. + +`skills/init-project/SKILL.md` STEP 3: after the line `Invoke \`brainstorming\` (vendored superpowers skill) with BRIEF + ANALYSIS REPORT.` insert: + +``` +Read `~/.claude/lib/architecture-defaults.md` first and pass it as binding +context: its defaults (Rust, never a SPA for a public site, `/api/v1/`) hold +unless the BRIEF names otherwise. +``` + +`skills/init-project/SKILL.md` STEP 5: replace + +``` ++ DESIGN (verbatim) + paths `~/.claude/templates/project-CLAUDE.md` + +`~/.claude/CLAUDE.md`. A STOP (missing input) comes back as its report — +``` + +with + +``` ++ DESIGN (verbatim) + paths `~/.claude/templates/project-CLAUDE.md` + +`~/.claude/CLAUDE.md` + `~/.claude/lib/architecture-defaults.md`. A STOP +(missing input) comes back as its report — +``` + +`agents/scaffolder.md`: after `4. \`~/.claude/CLAUDE.md\`` add `5. \`~/.claude/lib/architecture-defaults.md\``; replace `Read \`~/.claude/templates/project-CLAUDE.md\` and \`~/.claude/CLAUDE.md\`.` with `Read \`~/.claude/templates/project-CLAUDE.md\`, \`~/.claude/CLAUDE.md\` and \`~/.claude/lib/architecture-defaults.md\`.` + +`skills/ship-feature/SKILL.md` STEP 1: after the line ` BLK already closed."` insert: + +``` +When the feature picks a language, a framework or an API shape, Read +`~/.claude/lib/architecture-defaults.md` first and add its defaults to the +in-force constraints. +``` + +`skills/onboard/SKILL.md` STEP 6: after the line `Lire le bloc \`audit_stack:\` du fichier \`~/.claude/lib/project-archetypes/.md\`.` insert one blank line and: + +``` +Les audits jugent l'architecture contre `~/.claude/lib/architecture-defaults.md` +(site public jamais SPA, API `/api/v1/`, Rust par défaut pour une réécriture) : +passer ce chemin dans chaque brief d'audit. +``` + +`skills/audit-delta/SKILL.md`: replace + +``` +- **conformity** — read project `CLAUDE.md` (+ `~/.claude/CLAUDE.md`) + FIRST, then check changed code against those norms. This repo's: +``` + +with + +``` +- **conformity** — read project `CLAUDE.md` (+ `~/.claude/CLAUDE.md` and + `~/.claude/lib/architecture-defaults.md`) FIRST, then check changed code + against those norms. This repo's: +``` + +`agents/seo-analyzer.md`: replace + +``` +HTML). Global score excludes it. Fix: SSR/SSG (CLAUDE.md: public sites are +never SPAs).` +``` + +with + +``` +HTML). Global score excludes it. Fix: SSR/SSG +(lib/architecture-defaults.md: public sites are never SPAs).` +``` + +- [ ] **Step 6: Run, expect PASS** + +Run: `bash .claude/tasks/contracts/c1-arch-moved.sh` → `ARCH-MOVED`; `bash .claude/tasks/contracts/c1-readers.sh` → `READERS-OK`; `make test suite=lib/tests/doctrine-citers.test.sh` → `all suites green`. + +- [ ] **Step 7: Commit** + +```bash +git add lib/architecture-defaults.md CLAUDE.global.md rules/rest-api.md \ + lib/project-archetypes/rest-api-node.md agents/interviewer.md agents/scaffolder.md \ + agents/seo-analyzer.md skills/init-project/SKILL.md skills/ship-feature/SKILL.md \ + skills/onboard/SKILL.md skills/audit-delta/SKILL.md +git commit -m "feat(doctrine): architecture defaults move to lib/architecture-defaults.md, Web APIs to rules/rest-api.md" +``` + +(`git rm` already staged the deletion of `rules/default-language.md`.) + +--- + +### Task 4: Supabase and cloud-functions bodies become path rules + +**Files:** +- Create: `rules/supabase.md`, `rules/cloud-functions.md` +- Modify: `rules/secure-by-default.md` (§4 and §6 bodies only) +- Modify: `skills/guardrails/SKILL.md:10`, `agents/interviewer.md:27` + +- [ ] **Step 1: Run the oracle, expect FAIL** + +Run: `bash .claude/tasks/contracts/c1-supabase-functions.sh` → `no rules/supabase.md`. + +- [ ] **Step 2: Create the two rules** + +`rules/supabase.md`: + +``` +--- +paths: ["**/supabase/**", "**/*supabase*.*"] +--- + +# Supabase — secure by default, domain 4 + +Path-scoped body of `rules/secure-by-default.md` domain 4 (BDR-125 phase 1); +the always-on line there keeps RLS and the client-side key ban. + + +``` + +`rules/cloud-functions.md`: + +``` +--- +paths: ["**/functions/**", "**/serverless.*", "**/firebase.json"] +--- + +# Cloud functions — secure by default, domain 6 + +Path-scoped body of `rules/secure-by-default.md` domain 6 (BDR-125 phase 1); +the always-on line there keeps the instance cap and the self-trigger ban. + + +``` + +No line of the intro paragraph may start with `- ` (the oracle takes everything from the first `- ` line as the bullets). + +- [ ] **Step 3: Shrink the two sections of secure-by-default.md** + +Replace the body under `## 4. Supabase` (7 lines) with: + +``` +- RLS on every table, never a service_role or secret key client-side. Full + domain: rules/supabase.md (loads on Supabase files). +``` + +Replace the body under `## 6. Cloud functions` (4 lines) with: + +``` +- Max instances and a timeout on every function, never a self-trigger. Full + domain: rules/cloud-functions.md (loads on function files). +``` + +Every other line of the file stays byte-identical (the oracle checks it). + +- [ ] **Step 4: Patch the two citers** + +`skills/guardrails/SKILL.md`: replace + +``` +Checks a project against `rules/secure-by-default.md`, then fixes what the +user accepts and proves each fix. A scanner reads the tree as data and finds +``` + +with + +``` +Checks a project against `rules/secure-by-default.md` (domains 4 and 6 in +full: `rules/supabase.md`, `rules/cloud-functions.md`), then fixes what the +user accepts and proves each fix. A scanner reads the tree as data and finds +``` + +`agents/interviewer.md` row "Project has an API…": replace `Apply \`rules/secure-by-default.md\`:` with `Apply \`rules/secure-by-default.md\` (Supabase and cloud-function detail: \`rules/supabase.md\`, \`rules/cloud-functions.md\`):`. + +- [ ] **Step 5: Run, expect PASS** + +Run: `bash .claude/tasks/contracts/c1-supabase-functions.sh` → `SB-CF-MOVED`; `make test suite=lib/tests/guardrails-scan.test.sh` → `all suites green`. + +- [ ] **Step 6: Commit** + +```bash +git add rules/supabase.md rules/cloud-functions.md rules/secure-by-default.md \ + skills/guardrails/SKILL.md agents/interviewer.md +git commit -m "feat(rules): Supabase and cloud-functions bodies become path rules, one always-on line each" +``` + +--- + +### Task 5: user-rules suite locks the always-on set; matching facts documented + +**Files:** +- Create: `lib/tests/user-rules.test.sh` +- Modify: `lib/project-rules.sh` (header comment lines 21-23 only) +- Modify: `.claude/rules/rules-maintenance.md` (second paragraph) + +**Interfaces:** +- Consumes: `_rules_frontmatter ` (rc 1 = no frontmatter) and `_rules_globs ` (rc 0 globs, 1 no `paths:`, 2 malformed) from `lib/project-rules.sh` (sourced; it runs nothing when sourced). + +- [ ] **Step 1: Write the test** + +Create `lib/tests/user-rules.test.sh`: + +```bash +#!/usr/bin/env bash +# lib/tests/user-rules.test.sh — user-scope rules (rules/*.md, deployed as +# ~/.claude/rules): every frontmatter parses (one-line JSON `paths:` or no +# frontmatter at all) and the always-on set is exactly the two rules chat +# needs (BDR-125 phase 1 moved default-language to lib/architecture-defaults.md +# and the Supabase / cloud-functions bodies to path rules). Globs are not +# matched here: user rules span every stack; the load is proved by an +# InstructionsLoaded session (contract context-diet, criterion 15). +set -u +ROOT="$(cd "$(dirname "$0")/../.." && pwd)" +# shellcheck source=../project-rules.sh disable=SC1091 +source "$ROOT/lib/project-rules.sh" +pass=0; fail=0 +check() { if [ "$2" = "$3" ]; then pass=$((pass+1)); else fail=$((fail+1)); + printf 'FAIL %s: got[%s] want[%s]\n' "$1" "$2" "$3"; fi; } + +# rule_kind → path | always | bad +rule_kind() { + local fm + fm=$(_rules_frontmatter "$1") || { echo always; return; } + _rules_globs "$fm" >/dev/null + case $? in 0) echo path ;; 1) echo always ;; *) echo bad ;; esac +} +# always_on → the always-on rule file names, space-joined +always_on() { + local f out="" + for f in "$1"/*.md; do + [ "$(rule_kind "$f")" = always ] && out="$out ${f##*/}" + done + printf '%s\n' "${out# }" +} + +# ── flip controls: the checker bites (LRN-096) ── +FIX="$(mktemp -d)"; trap 'rm -rf "$FIX"' EXIT +printf -- '---\npaths: ["**/*.css"]\n---\n\n# A\n' > "$FIX/a.md" +printf '# B, always-on\n' > "$FIX/b.md" +printf -- '---\npaths:\n - "**/*.css"\n---\n\n# C\n' > "$FIX/c.md" +check F1-path-rule "$(rule_kind "$FIX/a.md")" path +check F2-no-frontmatter-always "$(rule_kind "$FIX/b.md")" always +check F3-multiline-paths-bad "$(rule_kind "$FIX/c.md")" bad +check F4-extra-always-on-seen "$(always_on "$FIX")" "b.md" + +# ── the real rules ── +bad="" +for f in "$ROOT"/rules/*.md; do + [ "$(rule_kind "$f")" = bad ] && bad="$bad ${f##*/}" +done +check R1-every-frontmatter-parses "${bad# }" "" +check R2-always-on-set "$(always_on "$ROOT/rules")" "secure-by-default.md writing-style.md" +check R3-moved-rules-path "$(rule_kind "$ROOT/rules/supabase.md")/$(rule_kind "$ROOT/rules/cloud-functions.md")" path/path + +printf 'PASS=%s FAIL=%s\n' "$pass" "$fail"; [ "$fail" -eq 0 ] +``` + +- [ ] **Step 2: Run, expect PASS (Tasks 3-4 already landed)** + +Run: `make test suite=lib/tests/user-rules.test.sh` → `all suites green`. The lock's bite is F4 (fixture). Never create a file under `rules/` to flip-test: it is the live `~/.claude/rules` of every session on this machine. + +- [ ] **Step 3: Correct the project-rules.sh comment (comment only)** + +In `lib/project-rules.sh` replace + +```bash +# dotglob makes `*` match dotfiles, which the engine's matcher skips: a +# glob that only hits hidden paths passes here but never loads), +``` + +with + +```bash +# dotglob makes `*` match dotfiles; the engine reaches hidden dirs too. Its +# matcher looks gitignore-style (InstructionsLoaded log, 2026-10-26: +# `paths: ["rules/**"]` logged as `globs: ["rules"]` and loaded on a Read +# of `.claude/rules/*.md`): a trailing `/**` dropped, a pattern without an +# inner `/` matching at any depth. A glob can thus load where this check +# does not look; the load proof is the logged session, not this check), +``` + +- [ ] **Step 4: Update rules-maintenance.md** + +In `.claude/rules/rules-maintenance.md` replace the paragraph that starts `A rule WITH \`paths:\` YAML frontmatter` and ends `keep rule bodies tiny.` with: + +``` +A rule WITH `paths:` YAML frontmatter (glob list) loads lazily — only when +Claude Reads a file matching a glob (never on the Write of a new file; +sub-agents too); a rule WITHOUT it loads at session start, same cost as the +global memory. Doctrine leaves CLAUDE.global.md only for a carrier that fires +when it is needed (BDR-125 phase 1): a path rule (Design work → +web-building.md; Supabase, cloud functions → supabase.md, cloud-functions.md), +a hook (graphify usage → session-start.sh) or a lib our skills Read +(lib/architecture-defaults.md), with one always-on line wherever plain chat +still needs the rule. Exception: a standalone user-authored rule set that +would bust the 320-line density budget may live here WITHOUT `paths:` +(always-on load) — writing-style.md (BDR-085), secure-by-default.md +(BDR-120); `lib/tests/user-rules.test.sh` locks that set. `paths:` globs +match against the CURRENT project's tree, gitignore-style (a pattern without +an inner `/` matches at any depth, hidden dirs included) — a broad glob (e.g. +`rules/**`) can fire in foreign projects; keep rule bodies tiny. +``` + +- [ ] **Step 5: Run, expect PASS** + +Run: `make test suite=lib/tests/project-rules.test.sh` and `make test suite=lib/tests/user-rules.test.sh` → `all suites green`; `bash lib/project-rules.sh check` → `project-rules: 4 rule(s) ok`; `shellcheck lib/project-rules.sh lib/tests/user-rules.test.sh` clean. + +- [ ] **Step 6: Commit** + +```bash +git add lib/tests/user-rules.test.sh lib/project-rules.sh .claude/rules/rules-maintenance.md +git commit -m "test(rules): user-rules suite locks the always-on set; engine matching documented" +``` + +--- + +### Task 6: doctrine-citers census resolves rules/ and lib/ § citations + +**Files:** +- Modify: `lib/tests/doctrine-citers.test.sh` + +**Interfaces:** +- Consumes: `_citers_resolve ` (existing, rc 0 when a heading starts with `` then end/space/`:`/`(`/`—`, or a bold label `**` exists). +- Produces: `_citers_extract_files …` → `file:line:target:name`; `citers_check_files …` → `DANGLING:` lines, rc = count (≤ 99). + +- [ ] **Step 1: Add the extractor, the checker and the flip tests** + +In `lib/tests/doctrine-citers.test.sh`, after the `citers_check()` function (before `# ── flip-test`), insert: + +```bash +# _citers_extract_files … → "file:line:target:name" per citation of a +# heading in another doctrine file: `rules/.md § Label` or +# `lib/.md § Label`, backticks around the path and quotes around the +# label allowed. An unquoted label ends at the first character that is not a +# letter, space or hyphen: quote a label that prose follows. A citation of +# `.claude/rules/.md § X` would be read as `rules/.md` (none exist; +# ERE has no lookbehind and the portability census bans grep -P). +_citers_extract_files() { + /usr/bin/grep -nHoE '(rules|lib)/[a-z0-9-]+\.md`? § ?"?[A-Z][A-Za-z][A-Za-z -]{1,40}' "$@" 2>/dev/null \ + | sed -E 's/^([^:]+:[0-9]+):(.*\.md)`? § ?"?(.*)$/\1:\2:\3/; s/[[:space:]]+$//' +} + +# citers_check_files … → DANGLING lines; rc = their count (capped 99) +citers_check_files() { + local root="$1" line file lno target name n=0; shift + while IFS= read -r line; do + [ -n "$line" ] || continue + file="${line%%:*}"; lno="$(printf '%s' "$line" | cut -d: -f2)" + target="$(printf '%s' "$line" | cut -d: -f3)"; name="${line#*:*:*:}" + if [ ! -f "$root/$target" ] || ! _citers_resolve "$root/$target" "$name"; then + echo "DANGLING: $file:$lno → $target § \"$name\""; n=$((n+1)) + fi + done < <(_citers_extract_files "$@") + return $(( n > 99 ? 99 : n )) +} +``` + +After the line `check T2c-label-named ...` insert: + +```bash +mkdir -p "$FIX/rules" "$FIX/lib" +printf '## Versioning\nx\n' > "$FIX/rules/api.md" +printf '## WRITE (before the commit)\n' > "$FIX/lib/cc.md" +# shellcheck disable=SC2016 # literal backticks in the fixture +printf 'ok: see `rules/api.md` § Versioning, and lib/cc.md § WRITE (x)\n' > "$FIX/fgood.md" +printf 'quoted: rules/api.md § "Versioning" first\n' >> "$FIX/fgood.md" +printf 'bad: rules/api.md § "Version", rules/none.md § Alpha, lib/cc.md § Read\n' > "$FIX/fbad.md" +citers_check_files "$FIX" "$FIX/fgood.md" >/dev/null; check T4-file-citations-resolve "$?" 0 +out=$(citers_check_files "$FIX" "$FIX/fbad.md"); rc=$? +check T5-file-dangling-caught "$rc" 3 +check T5b-missing-file-named "$(printf '%s\n' "$out" | grep -c 'rules/none.md')" 1 +check T5c-prefix-not-a-heading "$(printf '%s\n' "$out" | grep -c '"Version"')" 1 +``` + +After the line `check T3-repo-citations-resolve "$rc" 0` insert: + +```bash +out=$(cd "$ROOT" && citers_check_files "$ROOT" "${FILES[@]}" CLAUDE.global.md); rc=$? +[ -n "$out" ] && printf '%s\n' "$out" +check T6-repo-file-citations-resolve "$rc" 0 +# T7: the real citers bite — the same two files against a copy of +# rules/rest-api.md whose heading is renamed (never edit the live rules/) +mkdir -p "$FIX/copy/rules" +cp "$ROOT/rules/rest-api.md" "$FIX/copy/rules/rest-api.md" +(cd "$ROOT" && citers_check_files "$FIX/copy" lib/architecture-defaults.md \ + lib/project-archetypes/rest-api-node.md) >/dev/null +check T7a-real-citers-control "$?" 0 +sed 's/^## Versioning$/## Version policy/' "$ROOT/rules/rest-api.md" > "$FIX/copy/rules/rest-api.md" +(cd "$ROOT" && citers_check_files "$FIX/copy" lib/architecture-defaults.md \ + lib/project-archetypes/rest-api-node.md) >/dev/null +check T7b-real-rename-bites "$?" 2 +``` + +Also update the file header comment: after the line `# skill's own sections and are out of scope.` add: + +```bash +# Since BDR-125 phase 1 doctrine also lives in rules/ and lib/: a +# `rules/.md § Label` / `lib/.md § Label` citation resolves against +# that file (T4-T6). +``` + +- [ ] **Step 2: Run, expect PASS** + +Run: `make test suite=lib/tests/doctrine-citers.test.sh` → `all suites green`. If T6 prints a DANGLING line, the citation text is wrong (fix the citing file's wording, never the checker), report it. + +- [ ] **Step 3: Commit** + +```bash +git add lib/tests/doctrine-citers.test.sh +git commit -m "test(census): resolve rules/ and lib/ § citations against their file" +``` + +--- + +### Task 7: auto memory off; doctor warns on leftover auto-memory files + +**Files:** +- Modify: `settings.json` (ONE line; the user's hunks stay unstaged) +- Create: `lib/doctor-automem.sh`, `lib/tests/doctor-automem.test.sh` +- Modify: `doctor.sh` (source line near 28; new section 5d after 5c "Scratchpad") + +**Interfaces:** +- Produces: `automem_leftover_dirs ` → prints the number of `/*/memory` dirs holding ≥ 1 file; always rc 0. + +- [ ] **Step 1: Write the failing test** + +Create `lib/tests/doctor-automem.test.sh`: + +```bash +#!/usr/bin/env bash +# lib/tests/doctor-automem.test.sh — lib/doctor-automem.sh's +# automem_leftover_dirs(): absent dir, empty memory dirs, a file, a nested +# file, an empty subdir only, rc 0 under errexit (doctor.sh runs under +# `set -euo pipefail`) — BDR-125 phase 1. +set -u +ROOT="$(cd "$(dirname "$0")/../.." && pwd)" +LIB="$ROOT/lib/doctor-automem.sh" +# shellcheck source=../doctor-automem.sh disable=SC1091 +source "$LIB" +pass=0; fail=0 +check() { if [ "$2" = "$3" ]; then pass=$((pass+1)); else fail=$((fail+1)); + printf 'FAIL %s: got[%s] want[%s]\n' "$1" "$2" "$3"; fi; } +W="$(mktemp -d)"; trap 'rm -rf "$W"' EXIT + +check T1-absent-dir "$(automem_leftover_dirs "$W/nope")" 0 +mkdir -p "$W/p/-home-a/memory" "$W/p/-home-b/memory" +check T2-empty-dirs "$(automem_leftover_dirs "$W/p")" 0 +echo x > "$W/p/-home-a/memory/MEMORY.md" +check T3-one-file "$(automem_leftover_dirs "$W/p")" 1 +mkdir -p "$W/p/-home-b/memory/sub"; echo y > "$W/p/-home-b/memory/sub/note.md" +check T4-nested-file-counts "$(automem_leftover_dirs "$W/p")" 2 +mkdir -p "$W/p/-home-c/memory/empty-sub" +check T5-empty-subdir-silent "$(automem_leftover_dirs "$W/p")" 2 +check T6-rc0-under-errexit "$(bash -c 'set -euo pipefail; source "$1"; automem_leftover_dirs "$2" >/dev/null; echo "rc$?"' _ "$LIB" "$W/nope")" rc0 + +printf 'PASS=%s FAIL=%s\n' "$pass" "$fail"; [ "$fail" -eq 0 ] +``` + +- [ ] **Step 2: Run, expect FAIL** + +Run: `make test suite=lib/tests/doctor-automem.test.sh` → red (`lib/doctor-automem.sh` missing). + +- [ ] **Step 3: Write the lib** + +Create `lib/doctor-automem.sh`: + +```bash +#!/usr/bin/env bash +# ============================================================ +# lib/doctor-automem.sh — doctor.sh's auto-memory leftover check +# +# settings.json sets "autoMemoryEnabled": false (BDR-125 phase 1): Claude +# Code no longer reads ~/.claude/projects//memory/, so a file left +# there is knowledge nobody loads. `automem_leftover_dirs ` +# prints how many /memory dirs hold at least one file and ALWAYS +# exits 0 (doctor.sh runs under `set -euo pipefail`; an absent dir is 0). +# +# No `set -euo pipefail` here: a sourced lib must not change the caller's +# shell options. +# ============================================================ + +# automem_leftover_dirs — see file header. +automem_leftover_dirs() { + local d n=0 + for d in "$1"/*/memory; do + [ -d "$d" ] || continue + if [ -n "$(find "$d" -type f -print -quit 2>/dev/null)" ]; then + n=$((n + 1)) + fi + done + echo "$n" +} +``` + +- [ ] **Step 4: Wire doctor.sh** + +After the two lines + +```bash +# shellcheck source=lib/doctor-skills.sh disable=SC1091 +source "$REPO/lib/doctor-skills.sh" +``` + +add + +```bash +# shellcheck source=lib/doctor-automem.sh disable=SC1091 +source "$REPO/lib/doctor-automem.sh" +``` + +After the Scratchpad section's closing `unset _sp _sp_fs _sp_opts` + `echo ""`, insert: + +```bash +# ──────────────────────────────────────────────────────────── +# 5d. Auto memory (BDR-125 phase 1): "autoMemoryEnabled": false, so a file +# left under ~/.claude/projects//memory/ is never loaded again. +# ──────────────────────────────────────────────────────────── +echo "── Auto memory ──" +if jq -e '.autoMemoryEnabled == false' "$REPO/settings.json" >/dev/null 2>&1; then + pass "settings.json: autoMemoryEnabled false" +else + warn "settings.json: autoMemoryEnabled is not false — the auto-memory section loads every session (BDR-125 phase 1)" +fi +_am=$(automem_leftover_dirs "$HOME/.claude/projects") +if [ "$_am" -gt 0 ]; then + warn "auto memory: $_am project dir(s) still hold files under ~/.claude/projects/*/memory/ (never loaded) — migrate them to the project registries, then remove them by hand" +else + pass "auto memory: no leftover file under ~/.claude/projects/*/memory/" +fi +unset _am +echo "" +``` + +- [ ] **Step 5: Run, expect PASS** + +Run: `make test suite=lib/tests/doctor-automem.test.sh` → `all suites green`; `shellcheck doctor.sh lib/doctor-automem.sh lib/tests/doctor-automem.test.sh` clean. + +- [ ] **Step 6: settings.json, one line, staged alone** + +The working tree holds the user's own uncommitted hunks (`"model"`, `"theme"`): leave them. Stage only the new key, built from HEAD's version: + +```bash +tmp=$(mktemp) +git show HEAD:settings.json \ + | sed 's/^ "effortLevel": "high",$/&\n "autoMemoryEnabled": false,/' > "$tmp" +jq -e '.autoMemoryEnabled == false' "$tmp" >/dev/null || { echo "bad edit"; rm -f "$tmp"; exit 1; } +blob=$(git hash-object -w "$tmp"); rm -f "$tmp" +git update-index --cacheinfo "100644,$blob,settings.json" +sed -i.bak 's/^ "effortLevel": "high",$/&\n "autoMemoryEnabled": false,/' settings.json && rm settings.json.bak +git diff --cached settings.json +``` + +Expected: the cached diff is exactly one added line `+ "autoMemoryEnabled": false,`; `git diff settings.json` still shows the user's `model`/`theme` hunks and nothing about autoMemoryEnabled; `jq -e '.autoMemoryEnabled == false' settings.json` → true. + +- [ ] **Step 7: Commit** + +```bash +git add lib/doctor-automem.sh lib/tests/doctor-automem.test.sh doctor.sh +git commit -m "feat(memory): autoMemoryEnabled false; doctor warns on leftover auto-memory files" +git show --stat HEAD | cat +git diff --stat settings.json | cat +``` + +Expected: the commit lists settings.json with `1 +`; the user's hunks remain unstaged. + +--- + +### Task 8: agent descriptions trimmed at the source (≤ 200 chars) + +**Files:** +- Modify (the `description:` line only): `agents/{validator-analyzer,doc-syncer,handover-doc-writer,client-handover-writer,plan-challenger,security-auditor,onboarder,verifier,bugfixer,seo-analyzer,code-cleaner,plugin-advisor,geo-analyzer}.md` + +- [ ] **Step 1: Run the oracle, expect FAIL** + +Run: `bash .claude/tasks/contracts/c1-agent-desc.sh` → lists the 13 files over 200 chars. + +- [ ] **Step 2: Replace each `description:` line with exactly the line below (nothing else in the file changes)** + +``` +agents/validator-analyzer.md: +description: Web standards audit agent, dispatched from /web-validate. W3C HTML/CSS validity and WCAG 2.1 (axe-core, pa11y, WAVE); scored .claude/audits/VALIDATE.md with fix diffs and user actions. +agents/doc-syncer.md: +description: 'Two-mode public-doc sync agent. MODE: audit (opus, read-only: drift, drafts, PATCH PLAN); MODE: patch (sonnet: applies the approved plan, emits PATCHED_FILES). Never touches .claude/.' +agents/handover-doc-writer.md: +description: 'Two-mode client deliverable writer, dispatched twice by client-handover. MODE: synthesize (opus: memory + git, 6-chapter draft); MODE: render (sonnet: annexes, gates, MD + HTML/PDF).' +agents/client-handover-writer.md: +description: Final ship-and-handover orchestrator called by /client-handover. Audit/fix/gate pipeline (SEO+GEO+HARDEN to ≥17/20, live VALIDATE), then the client deliverable via handover-doc-writer. +agents/plan-challenger.md: +description: Fresh plan challenger. Reads a PLAN file and attacks it through ONE lens (correctness | robustness | simplicity), then renders findings + a verdict. Report-only, blind to the other lenses. +agents/security-auditor.md: +description: 'SAST security gate: pinned semgrep rulesets + the CLAUDE.md security checklist on a diff or scope. VERDICT: PASS | BLOCK(n), blocks HIGH/CRITICAL only. Never fixes code. Fresh dispatch.' +agents/onboarder.md: +description: Generate claude-config files (CLAUDE.md, settings.json, .claudeignore, .gitignore safety, .claude/{tasks,memory,audits}/) for an existing project. No interview, no audit. Called by /onboard. +agents/verifier.md: +description: Fresh independent verifier. Reads a CONTRACT file from disk and renders CONFORME / ECARTS / ERROR on the implemented diff. Report-only, never fixes; dispatched with no iteration history. +agents/bugfixer.md: +description: Bug-fix EXECUTOR dispatched by /bugfix (or /guardrails, /a11y) with a closed DIAGNOSIS + FIX PLAN + contract. Applies the fix and a regression test, runs the suite. No investigation, no commit. +agents/seo-analyzer.md: +description: 'Classical SEO audit agent (Google, Bing), dispatched from /seo: Core Web Vitals, on-page, technical, local SEO, legal (FR). Emits a fix bundle + scored report. AI/GEO → geo-analyzer.' +agents/code-cleaner.md: +description: Cleanup EXECUTOR (PHASE 2) dispatched by /code-clean with an APPROVED scope. Deletes approved dead code, hands style items to the refactorer, re-audits. Zero behavior change, no commit. +agents/plugin-advisor.md: +description: Plugin-fit REASONER dispatched by lib/plugin-gate.md with a PROBE REPORT from plugin-probe. Classifies signals, scores complexity, recommends enable/disable. Report-only. +agents/geo-analyzer.md: +description: GEO audit agent for AI search engines, dispatched by /geo and /seo. AI crawlers, llms.txt, entity signals, Schema.org; emits a fix bundle and a scored report. Classical SEO → seo-analyzer. +``` + +(Lengths 170-193, all parse as YAML; measured 2026-10-29.) + +- [ ] **Step 3: Run, expect PASS, then the full suite** + +Run: `bash .claude/tasks/contracts/c1-agent-desc.sh` → `AGENT-DESC-OK (23 agents)`; then `make test` → last line `all suites green`; then `shellcheck *.sh hooks/*.sh lib/*.sh` clean. + +- [ ] **Step 4: Commit** + +```bash +git add agents/validator-analyzer.md agents/doc-syncer.md agents/handover-doc-writer.md \ + agents/client-handover-writer.md agents/plan-challenger.md agents/security-auditor.md \ + agents/onboarder.md agents/verifier.md agents/bugfixer.md agents/seo-analyzer.md \ + agents/code-cleaner.md agents/plugin-advisor.md agents/geo-analyzer.md +git commit -m "chore(agents): descriptions trimmed to ≤ 200 chars at the source" +``` + +--- + +## Controller steps (main loop, not dispatched) + +- **C1 — robin_petier entry** (after the STEP 3 gate approves its text): `cd ~/Documents/robin_petier && bash ~/.claude/lib/gitflow.sh start chore memory-lan-server`, then `bash ~/.claude/lib/memory.sh -C ~/Documents/robin_petier add decision --title "" --body-file `, memory commit per `lib/capitalize-commit.md`, no merge (user go). +- **C2 — proofs** (after Task 8): `bash lib/project-rules.sh -C matches ''` per new glob (faunosteo, game; `**/serverless.*` named if nowhere); one headless `claude -p` per moved path rule naming the Read tool (faunosteo supabase file, game `supabase/functions/*`, a UI file) → `path_glob_match` lines from `~/.claude/logs/instructions-loaded.jsonl`; `claude -p "/context"` vs baseline; analyzer `memory: project` check after an analyzer dispatch. All journaled. +- **C3 — oracles**: `GATES_TIMEOUT=900 bash ~/.claude/lib/gates.sh run .claude/tasks/contracts/2026-10-28-context-diet-1944.md`. From 242d5bcdba302971c1764e876f17dbf552c6c155 Mon Sep 17 00:00:00 2001 From: bchanot Date: Thu, 29 Oct 2026 12:04:57 +0100 Subject: [PATCH 03/21] docs(plan): phase 1 plan r2 after the 3-lens challenge --- .../plans/2026-10-29-context-diet.md | 208 +++++++++--------- .../specs/2026-10-29-context-diet-design.md | 13 +- 2 files changed, 114 insertions(+), 107 deletions(-) diff --git a/docs/superpowers/plans/2026-10-29-context-diet.md b/docs/superpowers/plans/2026-10-29-context-diet.md index cb331cd..1ed7c96 100644 --- a/docs/superpowers/plans/2026-10-29-context-diet.md +++ b/docs/superpowers/plans/2026-10-29-context-diet.md @@ -12,6 +12,7 @@ ## Global Constraints +- Execute IN PLACE in `/home/bchanot/Documents/claude` on `feature/context-diet`, no worktree: `~/.claude/{CLAUDE.md,rules,lib,hooks,settings.json}` are symlinks into this checkout and Task 7 relies on the user's uncommitted hunks in THIS working tree. - Branch `feature/context-diet` (exists). Never commit on develop/main. Never `--no-verify`. Never `git add -A` / `git add .`: add the exact paths listed in the task. - Moved text is moved VERBATIM (byte-identical lines) unless the task shows the new text. The oracles compare against develop commit `017a28b`. - Hook stdout strings name deployed paths (`~/.claude/...`); maintainer comments name `CLAUDE.global.md` (BDR-064). @@ -59,22 +60,16 @@ with ```bash H="$(cd "$(dirname "$0")/../.." && pwd)/hooks/design-toolchain-reminder.sh" -# Every hook call runs under a throwaway HOME: the fire log is -# ~/.claude/logs/design-toolchain-fires.log and the suite must never write the +# Every hook call runs under a throwaway HOME (the fire log is +# $HOME/.claude/logs/design-toolchain-fires.log): the suite never writes the # real one (1,770 of 2,779 logged fires were this suite's prompts, 2026-10-28). T="$(mktemp -d)"; trap 'rm -rf "$T"' EXIT -REAL_LOG="$HOME/.claude/logs/design-toolchain-fires.log" -real_before="$(wc -l < "$REAL_LOG" 2>/dev/null || echo 0)" +export HOME="$T" LINE='Design work detected → Read ~/.claude/rules/web-building.md § "Design work — full toolchain" first. Trivial (≤2 files, cosmetic) → /hotfix.' pass=0; fail=0 ``` -Replace the `fire()` definition (2 lines) with - -```bash -fire() { if printf '{"prompt":"%s"}' "$1" | HOME="$T" bash "$H" | grep -q 'full toolchain'; then - echo fire; else echo quiet; fi; } -``` +(`fire()` stays as it is: the exported HOME covers it. The L1 block keeps its own `tmp` HOME.) After the line `check D11-bare-ux ...` add @@ -88,19 +83,11 @@ After the line `check F10-bare-ui ...` add check F11-pasted "$(fire ' add a button')" fire # --- The one-liner is a contract (LRN-104): exact text --- -check O1-exact-line "$(printf '{"prompt":"add a button"}' | HOME="$T" bash "$H")" "$LINE" +check O1-exact-line "$(printf '{"prompt":"add a button"}' | bash "$H")" "$LINE" +# the fires above landed in the throwaway HOME, positively (not a global count) +check G1-fires-in-temp-home "$([ -s "$T/.claude/logs/design-toolchain-fires.log" ] && echo yes)" yes ``` -Replace the last line `printf 'PASS=%s FAIL=%s\n' "$pass" "$fail"; [ "$fail" -eq 0 ]` with - -```bash -check G1-real-log-untouched "$(wc -l < "$REAL_LOG" 2>/dev/null || echo 0)" "$real_before" - -printf 'PASS=%s FAIL=%s\n' "$pass" "$fail"; [ "$fail" -eq 0 ] -``` - -(The L1 block keeps its own `tmp` dir unchanged.) - - [ ] **Step 2: Run it, expect FAIL** Run: `make test suite=lib/tests/design-toolchain-reminder.test.sh` @@ -163,9 +150,9 @@ Design work detected → Read ~/.claude/rules/web-building.md § "Design work - [ ] **Step 4: Move the section** -Cut the whole section from `CLAUDE.global.md`: from the line `## Design work — full toolchain (tiered by scope)` through the line `ui-explore / ui-review are \`max\`-profile only.` (23 lines), plus the one blank line that follows it, so `## graphify` follows the Skill-routing block's last line `office-hours…) are gone: use the fallback above, else say so.` and one blank line. +Cut the whole section from `CLAUDE.global.md`: from the line `## Design work — full toolchain (tiered by scope)` through the line `ui-explore / ui-review are \`max\`-profile only.` (22 lines, CLAUDE.global.md:300-321), plus the one blank line that follows it (322), so `## graphify` follows the Skill-routing block's last line `office-hours…) are gone: use the fallback above, else say so.` and one blank line. Never touch the `## graphify` heading. -Append to `rules/web-building.md`: one blank line, then those 23 lines byte-identical (the file must END with `ui-explore / ui-review are \`max\`-profile only.` + newline). Do not touch its frontmatter. +Append to `rules/web-building.md`: one blank line, then those 22 lines byte-identical (the file must END with `ui-explore / ui-review are \`max\`-profile only.` + newline). Do not touch its frontmatter. - [ ] **Step 5: Retarget the two CLAUDE.global.md pointers** @@ -245,57 +232,49 @@ git commit -m "feat(design): Design work moves to rules/web-building.md, hook po **Files:** - Modify: `CLAUDE.global.md` (`## graphify` section, now the last section) -- Modify: `hooks/session-start.sh` (line-count guard comment ~257-259; new block before the final `echo ""`) -- Create: `lib/tests/session-start-graphify.test.sh` +- Modify: `hooks/session-start.sh` (quick health-check list line ~10; line-count guard comment ~257-259; new block before the final `echo ""`) +- Modify: `lib/tests/graphify-gate.test.sh` (new S-checks before its final `echo "PASS=…"`) **Interfaces:** - Produces: when `$(git rev-parse --show-toplevel)/graphify-out/graph.json` exists, session-start stdout carries, after the box, the block shown in Step 3 (first line `graphify (graphify-out/graph.json present):`). -- [ ] **Step 1: Write the failing test** +- [ ] **Step 1: Write the failing checks** -Create `lib/tests/session-start-graphify.test.sh`: +In `lib/tests/graphify-gate.test.sh`, insert before the final `echo "PASS=$pass FAIL=$fail"` (reuse its `mkrepo`, `check`, `$WORK/plain`; one banner run per fixture state): ```bash -#!/usr/bin/env bash -# lib/tests/session-start-graphify.test.sh — the graphify usage rules print -# from hooks/session-start.sh only when the repo root holds -# graphify-out/graph.json (BDR-125 phase 1: the body left CLAUDE.global.md). -set -u -ROOT="$(cd "$(dirname "$0")/../.." && pwd)" -WORK="$(mktemp -d)"; trap 'rm -rf "$WORK"' EXIT -pass=0; fail=0 -check() { if [ "$2" = "$3" ]; then pass=$((pass+1)); else fail=$((fail+1)); - printf 'FAIL %s: got[%s] want[%s]\n' "$1" "$2" "$3"; fi; } -banner() { (cd "$1" && SESSION_START_OFFLINE=1 bash "$ROOT/hooks/session-start.sh" \ - /dev/null); } -usage() { banner "$1" | grep -c 'graphify query'; } - -git init -q "$WORK/repo"; git -C "$WORK/repo" config core.hooksPath /dev/null -mkdir -p "$WORK/repo/app/sub" "$WORK/plain" -check T1-no-graph-silent "$(usage "$WORK/repo")" 0 -check T1b-banner-control "$(banner "$WORK/repo" | grep -c 'Claude Code config')" 1 -mkdir -p "$WORK/repo/graphify-out"; echo '{}' > "$WORK/repo/graphify-out/graph.json" -check T2-graph-prints "$(usage "$WORK/repo")" 1 -check T3-from-subdir "$(usage "$WORK/repo/app/sub")" 1 -check T4-update-rule "$(banner "$WORK/repo" | grep -c 'graphify update \.')" 1 -check T5-not-a-repo "$(usage "$WORK/plain")" 0 -check T5b-not-a-repo-banner "$(banner "$WORK/plain" | grep -c 'Claude Code config')" 1 - -printf 'PASS=%s FAIL=%s\n' "$pass" "$fail"; [ "$fail" -eq 0 ] +# ── session-start prints the usage rules only where a graph exists +# (BDR-125 phase 1: the body left CLAUDE.global.md) ── +SS="$(cd "$(dirname "$0")/../.." && pwd)/hooks/session-start.sh" +banner() { (cd "$1" && SESSION_START_OFFLINE=1 bash "$SS" /dev/null); } +d=$(mkrepo ss 1) +out=$(banner "$d") +check S1-banner-control "$(grep -c 'Claude Code config' <<<"$out")" 1 +check S1b-no-graph-silent "$(grep -c 'graphify query' <<<"$out")" 0 +mkdir -p "$d/graphify-out" "$d/app/sub"; echo '{}' > "$d/graphify-out/graph.json" +out=$(banner "$d") +check S2-graph-prints "$(grep -c 'graphify query' <<<"$out")" 1 +check S2b-update-rule "$(grep -c 'graphify update \.' <<<"$out")" 1 +check S3-from-subdir "$(banner "$d/app/sub" | grep -c 'graphify query')" 1 +out=$(banner "$WORK/plain") +check S4-not-a-repo "$(grep -c 'graphify query' <<<"$out")/$(grep -c 'Claude Code config' <<<"$out")" 0/1 ``` - [ ] **Step 2: Run it, expect FAIL** -Run: `make test suite=lib/tests/session-start-graphify.test.sh` -Expected: FAIL on T2, T3, T4 (got 0); T1, T1b, T5, T5b pass. +Run: `make test suite=lib/tests/graphify-gate.test.sh` +Expected: FAIL on S2, S2b, S3 (got 0); T1-T9, S1, S1b, S4 pass. -- [ ] **Step 3: Add the block to session-start.sh** +- [ ] **Step 3: Edit session-start.sh** -In `hooks/session-start.sh`, between the line `[ -n "$EFFORT_WARN" ] && printf '%s\n' "$EFFORT_WARN"` and the final `echo ""`, insert: +Replace `for f in CLAUDE.md settings.json agents skills; do` (quick health check, ~line 10) with `for f in CLAUDE.md settings.json agents skills rules; do` (Design work and the Supabase / cloud-functions bodies now live only under `~/.claude/rules`). + +Between the line `[ -n "$EFFORT_WARN" ] && printf '%s\n' "$EFFORT_WARN"` and the final `echo ""`, insert: ```bash # graphify usage (BDR-125 phase 1): the rules left CLAUDE.global.md, which -# keeps only the 200-file threshold; they print where a graph exists. +# keeps the 200-file threshold and a one-line reminder; they print where a +# graph exists. _gx_root=$(git rev-parse --show-toplevel 2>/dev/null) if [ -n "$_gx_root" ] && [ -f "$_gx_root/graphify-out/graph.json" ]; then cat <<'EOF' @@ -328,7 +307,7 @@ with - [ ] **Step 4: Trim the CLAUDE.global.md section** -Replace the whole `## graphify` section (heading through `- After editing code → \`graphify update .\` (AST-only, free).`) with: +Replace the whole `## graphify` section (heading through `- After editing code → \`graphify update .\` (AST-only, free).`) with the lines below. The reminder clause stays always-on because dispatched sub-agents load CLAUDE.md, never the main session's SessionStart output: ``` ## graphify @@ -336,18 +315,19 @@ Replace the whole `## graphify` section (heading through `- After editing code Threshold: graphify from 200 tracked code files, never below (banner line `graphify? N code files ≥ 200, no graph` informs, the user decides; never build or `graphify claude install` without that go). With a graph -(`graphify-out/graph.json`), the session banner prints the usage rules. +(`graphify-out/graph.json`): `graphify query` before raw grep, +`graphify update .` after code edits; the session banner prints the rest. ``` - [ ] **Step 5: Run, expect PASS** -Run: `make test suite=lib/tests/session-start-graphify.test.sh`, `make test suite=lib/tests/graphify-gate.test.sh`, `make test suite=lib/tests/memory.test.sh`, `make test suite=lib/tests/push-guard.test.sh` (the last two grep the banner). -Expected: four `all suites green`. `shellcheck hooks/session-start.sh lib/tests/session-start-graphify.test.sh` clean. +Run: `make test suite=lib/tests/graphify-gate.test.sh`, `make test suite=lib/tests/memory.test.sh`, `make test suite=lib/tests/push-guard.test.sh` (the last two grep the banner). +Expected: three `all suites green`. `shellcheck hooks/session-start.sh lib/tests/graphify-gate.test.sh` clean. - [ ] **Step 6: Commit** ```bash -git add CLAUDE.global.md hooks/session-start.sh lib/tests/session-start-graphify.test.sh +git add CLAUDE.global.md hooks/session-start.sh lib/tests/graphify-gate.test.sh git commit -m "feat(graphify): usage rules print from session-start only where a graph exists" ``` @@ -359,7 +339,8 @@ git commit -m "feat(graphify): usage rules print from session-start only where a - Create: `lib/architecture-defaults.md` - Delete: `rules/default-language.md` (`git rm`) - Modify: `CLAUDE.global.md` (`# Architecture decisions` H1: intro + `## Public websites — never SPA` + `## Web APIs — always versioned`, ~142-167) -- Modify: `rules/rest-api.md` (`## Versioning`) +- Modify: `rules/rest-api.md` (`## Versioning`; the `/api/tasks` example in `## Naming`) +- Modify: `.claude/rules/rules-maintenance.md` (second paragraph) - Modify: `lib/project-archetypes/rest-api-node.md:58` - Modify (readers): `skills/init-project/SKILL.md` (STEP 3, STEP 5), `agents/interviewer.md:26`, `agents/scaffolder.md` (INPUTS REQUIRED, PHASE 1), `skills/ship-feature/SKILL.md` (STEP 1), `skills/onboard/SKILL.md` (STEP 6), `skills/audit-delta/SKILL.md:276`, `agents/seo-analyzer.md:542-543` @@ -379,10 +360,8 @@ Create `lib/architecture-defaults.md` with exactly this structure: # Architecture defaults — read before proposing a stack Read at project creation, scaffolding, a stack brainstorm or a whole-project -rewrite: /init-project (interviewer, STEP 3 design, scaffolder), -/ship-feature STEP 1, /onboard audits, /audit-delta conformity. The -always-on line under `~/.claude/CLAUDE.md` § "Architecture decisions" names -the three defaults; the detail lives here (BDR-125 phase 1). +rewrite (BDR-125 phase 1). The three defaults are named always-on in +`~/.claude/CLAUDE.md` § "Architecture decisions"; the detail lives here. @@ -429,6 +408,26 @@ additions → current version. Each version is a self-contained contract, never bent to match a newer one. ``` +In the same file, `## Naming` now contradicts it: replace `Plural nouns for endpoints (\`/api/tasks\`), no verbs.` with `Plural nouns for endpoints (\`/api/v1/tasks\`), no verbs.` + +In `.claude/rules/rules-maintenance.md` (it names `default-language.md` as an always-on exception, which `c1-readers.sh` reads as a stale citer), replace the paragraph that starts `A rule WITH \`paths:\` YAML frontmatter` and ends `keep rule bodies tiny.` with (it names `lib/tests/user-rules.test.sh`, which Task 5 of this branch creates): + +``` +A rule WITH `paths:` YAML frontmatter (glob list) loads lazily — only when +Claude Reads a file matching a glob (never on the Write of a new file; +sub-agents too); a rule WITHOUT it loads at session start, same cost as the +global memory. Doctrine leaves CLAUDE.global.md only for a carrier that fires +when it is needed (BDR-125 phase 1: a path rule, a hook, a lib our skills +Read), with one always-on line wherever plain chat still needs the rule. +Exception: a standalone user-authored rule set that would bust the 320-line +density budget may live here WITHOUT `paths:` (always-on load) — +writing-style.md (BDR-085), secure-by-default.md (BDR-120); +`lib/tests/user-rules.test.sh` locks that set. `paths:` globs match against +the CURRENT project's tree, gitignore-style (a pattern without an inner `/` +matches at any depth, hidden dirs included) — a broad glob (e.g. `rules/**`) +can fire in foreign projects; keep rule bodies tiny. +``` + In `lib/project-archetypes/rest-api-node.md` replace ``` @@ -525,6 +524,7 @@ Run: `bash .claude/tasks/contracts/c1-arch-moved.sh` → `ARCH-MOVED`; `bash .cl ```bash git add lib/architecture-defaults.md CLAUDE.global.md rules/rest-api.md \ + .claude/rules/rules-maintenance.md \ lib/project-archetypes/rest-api-node.md agents/interviewer.md agents/scaffolder.md \ agents/seo-analyzer.md skills/init-project/SKILL.md skills/ship-feature/SKILL.md \ skills/onboard/SKILL.md skills/audit-delta/SKILL.md @@ -631,12 +631,11 @@ git commit -m "feat(rules): Supabase and cloud-functions bodies become path rule --- -### Task 5: user-rules suite locks the always-on set; matching facts documented +### Task 5: user-rules suite locks the always-on set; engine matching documented **Files:** - Create: `lib/tests/user-rules.test.sh` - Modify: `lib/project-rules.sh` (header comment lines 21-23 only) -- Modify: `.claude/rules/rules-maintenance.md` (second paragraph) **Interfaces:** - Consumes: `_rules_frontmatter ` (rc 1 = no frontmatter) and `_rules_globs ` (rc 0 globs, 1 no `paths:`, 2 malformed) from `lib/project-rules.sh` (sourced; it runs nothing when sourced). @@ -724,36 +723,14 @@ with # does not look; the load proof is the logged session, not this check), ``` -- [ ] **Step 4: Update rules-maintenance.md** - -In `.claude/rules/rules-maintenance.md` replace the paragraph that starts `A rule WITH \`paths:\` YAML frontmatter` and ends `keep rule bodies tiny.` with: - -``` -A rule WITH `paths:` YAML frontmatter (glob list) loads lazily — only when -Claude Reads a file matching a glob (never on the Write of a new file; -sub-agents too); a rule WITHOUT it loads at session start, same cost as the -global memory. Doctrine leaves CLAUDE.global.md only for a carrier that fires -when it is needed (BDR-125 phase 1): a path rule (Design work → -web-building.md; Supabase, cloud functions → supabase.md, cloud-functions.md), -a hook (graphify usage → session-start.sh) or a lib our skills Read -(lib/architecture-defaults.md), with one always-on line wherever plain chat -still needs the rule. Exception: a standalone user-authored rule set that -would bust the 320-line density budget may live here WITHOUT `paths:` -(always-on load) — writing-style.md (BDR-085), secure-by-default.md -(BDR-120); `lib/tests/user-rules.test.sh` locks that set. `paths:` globs -match against the CURRENT project's tree, gitignore-style (a pattern without -an inner `/` matches at any depth, hidden dirs included) — a broad glob (e.g. -`rules/**`) can fire in foreign projects; keep rule bodies tiny. -``` - -- [ ] **Step 5: Run, expect PASS** +- [ ] **Step 4: Run, expect PASS** Run: `make test suite=lib/tests/project-rules.test.sh` and `make test suite=lib/tests/user-rules.test.sh` → `all suites green`; `bash lib/project-rules.sh check` → `project-rules: 4 rule(s) ok`; `shellcheck lib/project-rules.sh lib/tests/user-rules.test.sh` clean. -- [ ] **Step 6: Commit** +- [ ] **Step 5: Commit** ```bash -git add lib/tests/user-rules.test.sh lib/project-rules.sh .claude/rules/rules-maintenance.md +git add lib/tests/user-rules.test.sh lib/project-rules.sh git commit -m "test(rules): user-rules suite locks the always-on set; engine matching documented" ``` @@ -776,13 +753,16 @@ In `lib/tests/doctrine-citers.test.sh`, after the `citers_check()` function (bef # _citers_extract_files … → "file:line:target:name" per citation of a # heading in another doctrine file: `rules/.md § Label` or # `lib/.md § Label`, backticks around the path and quotes around the -# label allowed. An unquoted label ends at the first character that is not a -# letter, space or hyphen: quote a label that prose follows. A citation of +# label allowed. A quoted label runs to its closing quote (`—` included); an +# unquoted one ends at the first character that is not a letter, space or +# hyphen: quote a label that prose follows. A citation of # `.claude/rules/.md § X` would be read as `rules/.md` (none exist; # ERE has no lookbehind and the portability census bans grep -P). _citers_extract_files() { - /usr/bin/grep -nHoE '(rules|lib)/[a-z0-9-]+\.md`? § ?"?[A-Z][A-Za-z][A-Za-z -]{1,40}' "$@" 2>/dev/null \ - | sed -E 's/^([^:]+:[0-9]+):(.*\.md)`? § ?"?(.*)$/\1:\2:\3/; s/[[:space:]]+$//' + /usr/bin/grep -nHoE '(rules|lib)/[a-z0-9-]+\.md`? § ?"[^"]{2,60}"' "$@" 2>/dev/null \ + | sed -E 's/^([^:]+:[0-9]+):(.*\.md)`? § ?"([^"]+)"$/\1:\2:\3/' + /usr/bin/grep -nHoE '(rules|lib)/[a-z0-9-]+\.md`? § ?[A-Z][A-Za-z][A-Za-z -]{1,40}' "$@" 2>/dev/null \ + | sed -E 's/^([^:]+:[0-9]+):(.*\.md)`? § ?(.*)$/\1:\2:\3/; s/[[:space:]]+$//' } # citers_check_files … → DANGLING lines; rc = their count (capped 99) @@ -809,10 +789,14 @@ printf '## WRITE (before the commit)\n' > "$FIX/lib/cc.md" # shellcheck disable=SC2016 # literal backticks in the fixture printf 'ok: see `rules/api.md` § Versioning, and lib/cc.md § WRITE (x)\n' > "$FIX/fgood.md" printf 'quoted: rules/api.md § "Versioning" first\n' >> "$FIX/fgood.md" +printf '## Design work — full toolchain (tiered)\n' > "$FIX/rules/web.md" +printf 'dash: rules/web.md § "Design work — full toolchain" first\n' >> "$FIX/fgood.md" printf 'bad: rules/api.md § "Version", rules/none.md § Alpha, lib/cc.md § Read\n' > "$FIX/fbad.md" +printf 'dash: rules/web.md § "Design work — full kit" first\n' >> "$FIX/fbad.md" citers_check_files "$FIX" "$FIX/fgood.md" >/dev/null; check T4-file-citations-resolve "$?" 0 out=$(citers_check_files "$FIX" "$FIX/fbad.md"); rc=$? -check T5-file-dangling-caught "$rc" 3 +check T5-file-dangling-caught "$rc" 4 +check T5d-quoted-label-whole "$(printf '%s\n' "$out" | grep -c 'full kit')" 1 check T5b-missing-file-named "$(printf '%s\n' "$out" | grep -c 'rules/none.md')" 1 check T5c-prefix-not-a-heading "$(printf '%s\n' "$out" | grep -c '"Version"')" 1 ``` @@ -834,6 +818,9 @@ sed 's/^## Versioning$/## Version policy/' "$ROOT/rules/rest-api.md" > "$FIX/cop (cd "$ROOT" && citers_check_files "$FIX/copy" lib/architecture-defaults.md \ lib/project-archetypes/rest-api-node.md) >/dev/null check T7b-real-rename-bites "$?" 2 +# the hook's pointer is checked whole, not as its "Design work" prefix +check T7c-hook-label-whole "$(cd "$ROOT" && _citers_extract_files hooks/design-toolchain-reminder.sh \ + | grep -c ':rules/web-building.md:Design work — full toolchain$')" 2 ``` Also update the file header comment: after the line `# skill's own sections and are out of scope.` add: @@ -862,7 +849,9 @@ git commit -m "test(census): resolve rules/ and lib/ § citations against their **Files:** - Modify: `settings.json` (ONE line; the user's hunks stay unstaged) - Create: `lib/doctor-automem.sh`, `lib/tests/doctor-automem.test.sh` -- Modify: `doctor.sh` (source line near 28; new section 5d after 5c "Scratchpad") +- Modify: `doctor.sh` (source line near 28; `check_symlink "rules"` + `_EXPECTED_LINKS=8`; new section 5d after 5c "Scratchpad") + +**Precondition:** the controller confirms C1 (the robin_petier entry) is committed before Step 6: Step 6 switches auto memory off for every session on the machine. **Interfaces:** - Produces: `automem_leftover_dirs ` → prints the number of `/*/memory` dirs holding ≥ 1 file; always rc 0. @@ -897,6 +886,9 @@ check T4-nested-file-counts "$(automem_leftover_dirs "$W/p")" 2 mkdir -p "$W/p/-home-c/memory/empty-sub" check T5-empty-subdir-silent "$(automem_leftover_dirs "$W/p")" 2 check T6-rc0-under-errexit "$(bash -c 'set -euo pipefail; source "$1"; automem_leftover_dirs "$2" >/dev/null; echo "rc$?"' _ "$LIB" "$W/nope")" rc0 +# doctor.sh calls it on "$HOME/.claude/projects": the same call under a temp HOME +mkdir -p "$W/h/.claude/projects/-home-x/memory"; echo z > "$W/h/.claude/projects/-home-x/memory/a.md" +check T7-via-temp-home "$(HOME="$W/h" bash -c 'source "$1"; automem_leftover_dirs "$HOME/.claude/projects"' _ "$LIB")" 1 printf 'PASS=%s FAIL=%s\n' "$pass" "$fail"; [ "$fail" -eq 0 ] ``` @@ -939,6 +931,8 @@ automem_leftover_dirs() { - [ ] **Step 4: Wire doctor.sh** +Replace `_EXPECTED_LINKS=7` with `_EXPECTED_LINKS=8`, and after `check_symlink "lib"` add `check_symlink "rules"` (Design work and the Supabase / cloud-functions bodies now live only under `~/.claude/rules`). + After the two lines ```bash @@ -982,7 +976,7 @@ Run: `make test suite=lib/tests/doctor-automem.test.sh` → `all suites green`; - [ ] **Step 6: settings.json, one line, staged alone** -The working tree holds the user's own uncommitted hunks (`"model"`, `"theme"`): leave them. Stage only the new key, built from HEAD's version: +The working tree holds the user's own uncommitted hunks (three today: `"model"` changed at @@359, `"theme"` + `"switchModelsOnFlag"` added at @@489, the trailing `"switchModelsOnFlag"` removed at @@542): leave them. Stage only the new key, built from HEAD's version: ```bash tmp=$(mktemp) @@ -992,10 +986,11 @@ jq -e '.autoMemoryEnabled == false' "$tmp" >/dev/null || { echo "bad edit"; rm - blob=$(git hash-object -w "$tmp"); rm -f "$tmp" git update-index --cacheinfo "100644,$blob,settings.json" sed -i.bak 's/^ "effortLevel": "high",$/&\n "autoMemoryEnabled": false,/' settings.json && rm settings.json.bak +jq -e '.autoMemoryEnabled == false' settings.json >/dev/null || { echo "worktree edit missed"; exit 1; } git diff --cached settings.json ``` -Expected: the cached diff is exactly one added line `+ "autoMemoryEnabled": false,`; `git diff settings.json` still shows the user's `model`/`theme` hunks and nothing about autoMemoryEnabled; `jq -e '.autoMemoryEnabled == false' settings.json` → true. +Expected: the cached diff is exactly one added line `+ "autoMemoryEnabled": false,`; `git diff settings.json` still shows the user's three hunks and nothing about autoMemoryEnabled; `jq -e '.autoMemoryEnabled == false' settings.json` → true. - [ ] **Step 7: Commit** @@ -1070,6 +1065,9 @@ git commit -m "chore(agents): descriptions trimmed to ≤ 200 chars at the sourc ## Controller steps (main loop, not dispatched) -- **C1 — robin_petier entry** (after the STEP 3 gate approves its text): `cd ~/Documents/robin_petier && bash ~/.claude/lib/gitflow.sh start chore memory-lan-server`, then `bash ~/.claude/lib/memory.sh -C ~/Documents/robin_petier add decision --title "" --body-file `, memory commit per `lib/capitalize-commit.md`, no merge (user go). -- **C2 — proofs** (after Task 8): `bash lib/project-rules.sh -C matches ''` per new glob (faunosteo, game; `**/serverless.*` named if nowhere); one headless `claude -p` per moved path rule naming the Read tool (faunosteo supabase file, game `supabase/functions/*`, a UI file) → `path_glob_match` lines from `~/.claude/logs/instructions-loaded.jsonl`; `claude -p "/context"` vs baseline; analyzer `memory: project` check after an analyzer dispatch. All journaled. +- **C0 — track the oracles** (before Task 1): commit the contract and `.claude/tasks/contracts/c1-*.sh` on this branch (`chore(contract)`), so every task and reviewer reads them from HEAD. +- **C1 — robin_petier entry** (after the STEP 3 gate approves its text, BEFORE Task 7 Step 6): `cd ~/Documents/robin_petier && bash ~/.claude/lib/gitflow.sh start chore memory-lan-server`, then `bash ~/.claude/lib/memory.sh -C ~/Documents/robin_petier add decision --title "" --status accepted --body-file `, memory commit per `lib/capitalize-commit.md`, no merge (user go). robin_petier CLAUDE.md:192/:201 cite "Web APIs — always versioned" / "Public websites — never SPA" as global rules: both headings live on in `lib/architecture-defaults.md`, no patch; journal it. +- **C2 — proofs** (after Task 8): `bash lib/project-rules.sh -C matches ''` per new glob (faunosteo, game; `**/serverless.*` named if nowhere); one headless `claude -p` per moved path rule naming the Read tool (faunosteo supabase file, game `supabase/functions/*`, a UI file) → `path_glob_match` lines from `~/.claude/logs/instructions-loaded.jsonl`; `claude -p "/context"` vs baseline; analyzer `memory: project` check after an analyzer dispatch. All journaled. If the analyzer memory turns out disabled by `autoMemoryEnabled: false`: STOP and ask the user (revert the line, or keep it and record a BDR). - **C3 — oracles**: `GATES_TIMEOUT=900 bash ~/.claude/lib/gates.sh run .claude/tasks/contracts/2026-10-28-context-diet-1944.md`. +- **C4 — TODO.md** (STEP 7 memory commit): phase 1 checked with its proof numbers, follow-ups added (the user removes the auto-memory dirs; any deferred item from the gate). +- **C5 — finish precondition**: `gitflow finish` checks out develop, which git refuses while the user's settings.json hunks are uncommitted (this branch changes settings.json). Before finish the user decides: commit their hunks (own `chore(settings)` commit) or `git stash push -- settings.json` around the finish and `git stash pop` after. Never `git checkout -- settings.json` / restore it (it is the live ~/.claude/settings.json and loses the edits). diff --git a/docs/superpowers/specs/2026-10-29-context-diet-design.md b/docs/superpowers/specs/2026-10-29-context-diet-design.md index ea8633e..f6d5bf6 100644 --- a/docs/superpowers/specs/2026-10-29-context-diet-design.md +++ b/docs/superpowers/specs/2026-10-29-context-diet-design.md @@ -22,7 +22,7 @@ Custom agents 2.6k). | CLAUDE.global.md § Design work — full toolchain (tiered by scope) | appended verbatim to `rules/web-building.md` (same UI globs) | Skill-routing line points to it; design hook one-liner says Read it | | CLAUDE.global.md § graphify usage body | `hooks/session-start.sh`, free lines after the box, only when `/graphify-out/graph.json` exists | `## graphify` + the 200-file threshold rule | | CLAUDE.global.md § Public websites — never SPA + `rules/default-language.md` | `lib/architecture-defaults.md` (verbatim, H1 of the language rule demoted to H2) | one line under `# Architecture decisions` naming Rust default, never SPA, `/api/v1`, the lib path | -| CLAUDE.global.md § Web APIs — always versioned | `rules/rest-api.md` § Versioning (full text, replaces "Not repeated here"); the lib carries a one-line summary + pointer | named in the architecture line | +| CLAUDE.global.md § Web APIs — always versioned | `rules/rest-api.md` § Versioning (full text, replaces "Not repeated here"; the § Naming example becomes `/api/v1/tasks`); the lib carries a one-line summary + pointer | named in the architecture line | | `rules/secure-by-default.md` §4 Supabase, §6 Cloud functions bodies | `rules/supabase.md` (`**/supabase/**`, `**/*supabase*.*`), `rules/cloud-functions.md` (`**/functions/**`, `**/serverless.*`, `**/firebase.json`), bullets verbatim | the two headings stay, one line each (critical rule + pointer) | | `agents/*.md` `description:` (23 tracked) | trimmed at the source to ≤ 200 chars | n/a | @@ -38,7 +38,13 @@ exactly `writing-style.md` + `secure-by-default.md`. needed), every web API versioned `/api/v1/` from day one. Read `~/.claude/lib/architecture-defaults.md` before proposing a stack.` - CLAUDE.global.md Skill routing: `Design / UI (build, system, audit, - polish) → Read ~/.claude/rules/web-building.md § Design work first`. + polish) → Read `~/.claude/rules/web-building.md` § "Design work" first` + (the quotes end the label for the extended census; plan challenge + 2026-10-29). +- CLAUDE.global.md § graphify keeps, after the threshold: `With a graph + (graphify-out/graph.json): graphify query before raw grep, graphify + update . after code edits; the session banner prints the rest.` + (sub-agents load CLAUDE.md, never the SessionStart output). - Design hook stdout: `Design work detected → Read ~/.claude/rules/web-building.md § "Design work — full toolchain" first. Trivial (≤2 files, cosmetic) → /hotfix.` (one line). @@ -117,3 +123,6 @@ v2 upgrade pass; settings.json `model`/`theme` lines written by the user's only; loading is proved by the logged sessions. - `**/functions/**` also fires in non-cloud `functions/` dirs (≈80 tokens of noise there), accepted. +- `gitflow finish` refuses while the user's settings.json hunks are + uncommitted (this branch changes settings.json): the user commits or + stashes them first; never a checkout of the live file. From 0441e5647dc18a6daa4cd09c7128ccac89201c0a Mon Sep 17 00:00:00 2001 From: bchanot Date: Thu, 29 Oct 2026 12:25:37 +0100 Subject: [PATCH 04/21] docs(plan): r3, confirmation-challenge minors --- docs/superpowers/plans/2026-10-29-context-diet.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/superpowers/plans/2026-10-29-context-diet.md b/docs/superpowers/plans/2026-10-29-context-diet.md index 1ed7c96..35ca9f7 100644 --- a/docs/superpowers/plans/2026-10-29-context-diet.md +++ b/docs/superpowers/plans/2026-10-29-context-diet.md @@ -686,6 +686,9 @@ check F1-path-rule "$(rule_kind "$FIX/a.md")" path check F2-no-frontmatter-always "$(rule_kind "$FIX/b.md")" always check F3-multiline-paths-bad "$(rule_kind "$FIX/c.md")" bad check F4-extra-always-on-seen "$(always_on "$FIX")" "b.md" +# the R2 lock itself bites on a dir whose always-on set differs +cp "$FIX/b.md" "$FIX/writing-style.md"; cp "$FIX/b.md" "$FIX/secure-by-default.md" +check F5-lock-bites "$([ "$(always_on "$FIX")" = "secure-by-default.md writing-style.md" ] && echo match || echo mismatch)" mismatch # ── the real rules ── bad="" @@ -851,7 +854,7 @@ git commit -m "test(census): resolve rules/ and lib/ § citations against their - Create: `lib/doctor-automem.sh`, `lib/tests/doctor-automem.test.sh` - Modify: `doctor.sh` (source line near 28; `check_symlink "rules"` + `_EXPECTED_LINKS=8`; new section 5d after 5c "Scratchpad") -**Precondition:** the controller confirms C1 (the robin_petier entry) is committed before Step 6: Step 6 switches auto memory off for every session on the machine. +**Precondition (controller):** Task 7 is dispatched only once C1 (the robin_petier entry) is committed: Step 6 switches auto memory off for every session on the machine. **Interfaces:** - Produces: `automem_leftover_dirs ` → prints the number of `/*/memory` dirs holding ≥ 1 file; always rc 0. @@ -931,7 +934,7 @@ automem_leftover_dirs() { - [ ] **Step 4: Wire doctor.sh** -Replace `_EXPECTED_LINKS=7` with `_EXPECTED_LINKS=8`, and after `check_symlink "lib"` add `check_symlink "rules"` (Design work and the Supabase / cloud-functions bodies now live only under `~/.claude/rules`). +Replace `_EXPECTED_LINKS=7` with `_EXPECTED_LINKS=8`, replace the comment line `# Expected: CLAUDE.md, settings.json, agents, skills, templates, hooks/session-start.sh` with `# Expected: CLAUDE.md, settings.json, agents, skills, templates, lib, rules, hooks/session-start.sh`, and after `check_symlink "lib"` add `check_symlink "rules"` (Design work and the Supabase / cloud-functions bodies now live only under `~/.claude/rules`). After the two lines From 4bbd6e278eb42126073f0c5b9ca92f32f877a7ca Mon Sep 17 00:00:00 2001 From: bchanot Date: Thu, 29 Oct 2026 12:54:56 +0100 Subject: [PATCH 05/21] chore(contract): phase 1 contract, oracles, gate amendments --- .../contracts/2026-10-28-context-diet-1944.md | 73 +++++++++++++++++++ .claude/tasks/contracts/c1-agent-desc.sh | 27 +++++++ .claude/tasks/contracts/c1-arch-moved.sh | 24 ++++++ .claude/tasks/contracts/c1-design-moved.sh | 17 +++++ .claude/tasks/contracts/c1-readers.sh | 14 ++++ .../tasks/contracts/c1-supabase-functions.sh | 29 ++++++++ .../plans/2026-10-29-context-diet.md | 8 +- 7 files changed, 188 insertions(+), 4 deletions(-) create mode 100644 .claude/tasks/contracts/2026-10-28-context-diet-1944.md create mode 100644 .claude/tasks/contracts/c1-agent-desc.sh create mode 100644 .claude/tasks/contracts/c1-arch-moved.sh create mode 100644 .claude/tasks/contracts/c1-design-moved.sh create mode 100644 .claude/tasks/contracts/c1-readers.sh create mode 100644 .claude/tasks/contracts/c1-supabase-functions.sh diff --git a/.claude/tasks/contracts/2026-10-28-context-diet-1944.md b/.claude/tasks/contracts/2026-10-28-context-diet-1944.md new file mode 100644 index 0000000..e834bd9 --- /dev/null +++ b/.claude/tasks/contracts/2026-10-28-context-diet-1944.md @@ -0,0 +1,73 @@ +# CONTRACT — context-diet (phase 1) +- date: 2026-10-28 | flow: ship-feature | branch: feature/context-diet (off develop 017a28b) +- status: active + +## REQUEST (verbatim — IMMUTABLE) +continue avec la phase suivante + +(user, 2026-10-28, after the phase 4a merge 017a28b. Queue order in `.claude/tasks/TODO.md` (BDR-125): 0 → 4a → 1 → 5 → 2 → 3 → 4b-4d, so "la phase suivante" = the TODO bullet "**Phase 1, native context diet: no mod**", its spec read verbatim from that bullet plus the "Shared rules for every phase" block above it.) + +## CLARIFICATIONS +Q: Architecture defaults (Rust default, public site never SPA, API /api/v1) leave always-on context for lib/architecture-defaults.md; BDR-118/BDR-120 rejected such moves because brainstorm happens in plain chat. What stays always-on? / A: one always-on line in CLAUDE.global.md naming the three defaults and pointing to the lib; rules/default-language.md moves into the lib (file deleted); /refactor not edited (it has no whole-project mode, the line covers it). [gated 2026-10-28, pass A] +Q: Which of the 5 auto memories migrate before `autoMemoryEnabled: false`? / A: one entry into robin_petier's registry (LAN dev server: never restart unprompted, ask before killing one found running) via memory.sh on a chore/* branch, text reviewed by the user before the write; the other 4 dropped (onecmd = robin_petier BLK-017, restore = BLK-016/LRN-066/067, faunosteo docker = its resolved BLK, jeux-deploy `:branch` refspec contradicts the gitflow delete doctrine and its project is gone). The user removes the ~/.claude/projects/*/memory dirs by hand afterwards; doctor warns while one is non-empty. [gated 2026-10-28, pass A] +Q: Supabase and cloud-functions bodies to path rules: names and globs? / A: rules/supabase.md on `**/supabase/**`, `**/*supabase*.*`; rules/cloud-functions.md on `**/functions/**`, `**/serverless.*`, `**/firebase.json`; one always-on line stays under each heading of rules/secure-by-default.md (Supabase: RLS everywhere + no service_role key client-side; cloud functions: instance cap + no self-trigger). No `**/*.sql` nor `**/migrations/**`. [gated 2026-10-28, pass A] +Q: Neighbouring defects in scope? / A: all three in: (a) design-toolchain test F1-F10 run with a temp HOME (1,770 of 2,779 logged fires are suite prompts); (b) lib/project-rules.sh:22-23 comment corrected (engine matching is gitignore-style, observed in the InstructionsLoaded log) and the static proof accounts for it; (c) the design hook stops firing on harness-generated `/dev/null && echo AUTOMEM-OFF + EXPECT: AUTOMEM-OFF + EVIDENCE: pending +2. robin_petier's registry holds exactly one new entry for the LAN dev server rule, written by `lib/memory.sh -C ~/Documents/robin_petier add`, on a `chore/*` branch of that repo, with the text the user approved; no other project's `.claude/memory/` changes. +3. doctor warns when any `~/.claude/projects/*/memory/` dir holds a file, names how many dirs, and stays silent when all are empty (flip-tested in a suite with a temp HOME). + [gated 2026-10-29] amended: doctor prints a warn line naming the count when a dir holds a file, a pass line otherwise; the proof is the function-level suite (lib/tests/doctor-automem.test.sh) including a call through a temp HOME; doctor also checks the `~/.claude/rules` symlink and that settings.json `autoMemoryEnabled` is false. +4. CLAUDE.global.md has no `## Design work` heading; rules/web-building.md ends with the section `## Design work — full toolchain (tiered by scope)`, body identical to the CLAUDE.global.md section at develop 017a28b (internal pointers excepted, listed in the plan); web-building.md `paths:` unchanged. + CHECK: bash .claude/tasks/contracts/c1-design-moved.sh + EXPECT: DESIGN-MOVED + EVIDENCE: pending +5. hooks/design-toolchain-reminder.sh prints a one-liner that names `~/.claude/rules/web-building.md` and the heading fragment `full toolchain`, and no longer says "already in context"; its suite asserts the exact new line. +6. The design hook stays quiet on a prompt starting with `/dev/null 2>&1 || exit 1; b=$(wc -l < "$L"); [ "$a" = "$b" ] && echo LOG-UNTOUCHED + EXPECT: LOG-UNTOUCHED + EVIDENCE: pending +8. [gated 2026-10-29] amended: `## graphify` keeps the threshold rule plus ONE reminder clause (`graphify query` before raw grep, `graphify update .` after code edits; sub-agents never see the banner); the full usage body moves as below. Original: CLAUDE.global.md `## graphify` keeps only the threshold rule; the usage body (query/path/explain, wiki/GRAPH_REPORT, `graphify update .`) is printed by hooks/session-start.sh only when the repo root holds `graphify-out/graph.json`; a suite proves present-with-graph and absent-without (flip). +9. lib/architecture-defaults.md exists and holds the "Public websites — never SPA" text and the "Default language — Rust" text (wording identical to their sources at 017a28b, pointers excepted) plus the Web APIs rule or a pointer to rules/rest-api.md § Versioning; CLAUDE.global.md has no `## Public websites` and no `## Web APIs` heading and holds one always-on line naming Rust default, never SPA, `/api/v1` and the lib path; rules/default-language.md no longer exists. + CHECK: bash .claude/tasks/contracts/c1-arch-moved.sh + EXPECT: ARCH-MOVED + EVIDENCE: pending +10. Readers name the lib: skills/init-project/SKILL.md, skills/ship-feature/SKILL.md (STEP 1), skills/onboard/SKILL.md, agents/interviewer.md, agents/scaffolder.md, skills/audit-delta/SKILL.md; no tracked file under skills/ agents/ lib/ hooks/ rules/ templates/ nor CLAUDE.global.md cites `default-language.md`. + CHECK: bash .claude/tasks/contracts/c1-readers.sh + EXPECT: READERS-OK + EVIDENCE: pending +11. rules/rest-api.md `## Versioning` carries the full versioning rule (text of CLAUDE.global.md § Web APIs at 017a28b), no "Not repeated here"; lib/project-archetypes/rest-api-node.md cites rules/rest-api.md instead of CLAUDE.md "Web APIs — always versioned". +12. rules/supabase.md and rules/cloud-functions.md exist with the clarified one-line JSON `paths:` and the bullets of secure-by-default.md §4 / §6 at 017a28b, wording identical; secure-by-default.md keeps the `## 4. Supabase` and `## 6. Cloud functions` headings with one line each naming the critical rule and the path rule. + CHECK: bash .claude/tasks/contracts/c1-supabase-functions.sh + EXPECT: SB-CF-MOVED + EVIDENCE: pending +13. A make-test suite parses every rules/*.md frontmatter (one-line JSON `paths:` or none) and locks the always-on set to exactly writing-style.md + secure-by-default.md; positive control: a multi-line `paths:` fixture and an extra always-on fixture both fail it. +14. lib/project-rules.sh header comment states the observed engine matching (trailing `/**` dropped, a pattern matches at any depth, hidden dirs included, evidence: InstructionsLoaded `globs: ["rules"]` on `.claude/rules/*.md`) instead of "the engine's matcher skips" dotfiles; code behaviour unchanged. +15. Load proof (controller, journaled): one fresh headless session per moved path rule, each prompt naming the Read tool on a real file, logs `path_glob_match` for rules/supabase.md (faunosteo), rules/cloud-functions.md (game, supabase/functions), rules/web-building.md (a UI file); and `bash lib/project-rules.sh -C matches ''` per new glob in the project that holds it (a glob that matches nowhere is named in the journal). +16. Every tracked agents/*.md `description:` (the 4 vendored impeccable-* excepted) is ≤ the length settled at the plan gate; agent names, files and `model:` lines unchanged. + CHECK: bash .claude/tasks/contracts/c1-agent-desc.sh + EXPECT: AGENT-DESC-OK + EVIDENCE: pending +17. Citers patched in the same branch: CLAUDE.global.md Skill routing (Design / UI line, Higgsfield line), lib/design-gate.md, agents/seo-analyzer.md, .claude/rules/rules-maintenance.md (always-on exception list and the "always-on doctrine stays in CLAUDE.global.md" sentence), hooks/session-start.sh comments citing BDR-031 / the moved sections; doctrine-citers census green. +18. CLAUDE.global.md is ≤ 320 lines (the session banner density warning goes away). + CHECK: n=$(wc -l < CLAUDE.global.md); [ "$n" -le 320 ] && echo GLOBAL-UNDER-320 + EXPECT: GLOBAL-UNDER-320 + EVIDENCE: pending +19. `/context` after (controller, `claude -p "/context"` at repo root, journaled with the baseline 2026-10-28: total 30.5k, Memory files 9.6k with user CLAUDE.md 7.4k / default-language 409 / secure-by-default 1.2k, Custom agents 2.6k, System prompt 4.4k): Memory files and Custom agents both lower, rules/default-language.md absent from the Memory files table. +20. make test all green and shellcheck clean. + CHECK: make test 2>&1 | tail -1 + EXPECT: all suites green + EVIDENCE: pending +21. shellcheck clean on the health stack. + CHECK: shellcheck *.sh hooks/*.sh lib/*.sh && echo SHELLCHECK-CLEAN + EXPECT: SHELLCHECK-CLEAN + EVIDENCE: pending + +## FILE SCOPE +CLAUDE.global.md, settings.json, rules/web-building.md, rules/rest-api.md, rules/secure-by-default.md, rules/default-language.md (deleted), rules/supabase.md (new), rules/cloud-functions.md (new), lib/architecture-defaults.md (new), hooks/design-toolchain-reminder.sh, lib/tests/design-toolchain-reminder.test.sh, hooks/session-start.sh, lib/graphify-gate.sh (only if the graph-present branch needs it), a session-start graphify suite (new), doctor.sh + one lib/doctor-*.sh + its suite (new), lib/tests/ user-rules suite (new) + fixtures, lib/tests/graphify-gate.test.sh (the session-start graphify checks live there) [gated 2026-10-29], lib/tests/effort-routing.test.sh (one lock retargeted) [gated 2026-10-29], lib/tests/doctrine-citers.test.sh (census extension) [gated 2026-10-29], skills/guardrails/SKILL.md (citer) [gated 2026-10-29], .claude/tasks/contracts/2026-10-28-context-diet-1944.md + c1-*.sh [gated 2026-10-29], .claude/tasks/TODO.md [gated 2026-10-29], lib/project-rules.sh (comment only), agents/*.md (23 tracked, `description:` only), skills/init-project/SKILL.md, skills/ship-feature/SKILL.md, skills/onboard/SKILL.md, skills/audit-delta/SKILL.md, agents/interviewer.md, agents/scaffolder.md, agents/seo-analyzer.md, lib/design-gate.md, lib/project-archetypes/rest-api-node.md, .claude/rules/rules-maintenance.md, .claude/tasks/contracts/c1-*.sh (oracles), robin_petier `.claude/memory/` (one entry, its own chore/* branch), docs at STEP 8. diff --git a/.claude/tasks/contracts/c1-agent-desc.sh b/.claude/tasks/contracts/c1-agent-desc.sh new file mode 100644 index 0000000..2231334 --- /dev/null +++ b/.claude/tasks/contracts/c1-agent-desc.sh @@ -0,0 +1,27 @@ +#!/usr/bin/env bash +# GATE 0 oracle, contract context-diet c16: every tracked agent description +# ≤ 200 chars as written; file list and every other frontmatter key unchanged. +set -u +python3 -I - <<'PY' +import subprocess, sys, yaml +def ls(rev=None): + cmd = ['git', 'ls-tree', '-r', '--name-only', rev, 'agents'] if rev else ['git', 'ls-files', 'agents'] + out = subprocess.run(cmd, capture_output=True, text=True, check=True).stdout.split() + return sorted(f for f in out if f.endswith('.md') and not f.startswith('agents/resources/')) +def fm(text): + if not text.startswith('---\n'): return None, None + head = text.split('\n---\n', 1)[0][4:] + raw = next((l for l in head.splitlines() if l.startswith('description:')), '') + return yaml.safe_load(head), raw[len('description: '):] +now, old = ls(), ls('017a28b') +if now != old: print('agent file list changed'); sys.exit(1) +bad = [] +for f in now: + meta, raw = fm(open(f, encoding='utf-8').read()) + prev, _ = fm(subprocess.run(['git', 'show', '017a28b:' + f], capture_output=True, text=True).stdout) + if not isinstance(meta.get('description'), str) or len(raw) > 200: bad.append(f'{f}: {len(raw)} chars') + if {k: v for k, v in meta.items() if k != 'description'} != {k: v for k, v in prev.items() if k != 'description'}: + bad.append(f'{f}: other keys changed') +if bad: print('\n'.join(bad)); sys.exit(1) +print(f'AGENT-DESC-OK ({len(now)} agents)') +PY diff --git a/.claude/tasks/contracts/c1-arch-moved.sh b/.claude/tasks/contracts/c1-arch-moved.sh new file mode 100644 index 0000000..e4deadc --- /dev/null +++ b/.claude/tasks/contracts/c1-arch-moved.sh @@ -0,0 +1,24 @@ +#!/usr/bin/env bash +# GATE 0 oracle, contract context-diet c9: architecture defaults in the lib, +# verbatim; one always-on line in CLAUDE.global.md; default-language.md gone. +set -u +fail() { echo "$1"; exit 1; } +L=lib/architecture-defaults.md +body() { awk -v h="$1" 'index($0, h) == 1 { f = 1; print; next } f && /^#/ { exit } f'; } +[ -f "$L" ] || fail "no $L" +[ -e rules/default-language.md ] && fail "rules/default-language.md still exists" +grep -q '^## Public websites' CLAUDE.global.md && fail "Public websites in CLAUDE.global.md" +grep -q '^## Web APIs' CLAUDE.global.md && fail "Web APIs in CLAUDE.global.md" +a=$(git show 017a28b:CLAUDE.global.md | body '## Public websites — never SPA') +b=$(body '## Public websites — never SPA' < "$L") +[ -n "$a" ] && [ "$a" = "$b" ] || fail "SPA section differs" +a=$(git show 017a28b:rules/default-language.md | sed '1s/^# /## /') +b=$(body '## Default language — Rust' < "$L") +[ -n "$a" ] && [ "$a" = "$b" ] || fail "language section differs" +grep -q 'rules/rest-api.md' "$L" || fail "no rest-api.md pointer in the lib" +line=$(awk '/^# Architecture decisions/ { f = 1; next } f && /^#/ { exit } f' CLAUDE.global.md \ + | tr '\n' ' ') +for w in 'Rust by default' 'never a SPA' '/api/v1/' '~/.claude/lib/architecture-defaults.md'; do + case "$line" in *"$w"*) ;; *) fail "architecture line lacks: $w" ;; esac +done +echo ARCH-MOVED diff --git a/.claude/tasks/contracts/c1-design-moved.sh b/.claude/tasks/contracts/c1-design-moved.sh new file mode 100644 index 0000000..75de76b --- /dev/null +++ b/.claude/tasks/contracts/c1-design-moved.sh @@ -0,0 +1,17 @@ +#!/usr/bin/env bash +# GATE 0 oracle, contract context-diet c4: Design work moved verbatim to +# rules/web-building.md (last section), gone from CLAUDE.global.md, paths kept. +set -u +fail() { echo "$1"; exit 1; } +sec() { awk '/^## Design work — full toolchain/ { f = 1; print; next } + f && /^#/ { exit } f'; } +old=$(git show 017a28b:CLAUDE.global.md | sec) +[ -n "$old" ] || fail "no source section at 017a28b" +grep -q '^## Design work' CLAUDE.global.md && fail "still in CLAUDE.global.md" +new=$(sec < rules/web-building.md) +[ "$old" = "$new" ] || { diff <(printf '%s\n' "$old") <(printf '%s\n' "$new"); fail "body differs"; } +tail_=$(awk '/^## Design work — full toolchain/ { f = 1 } f' rules/web-building.md) +[ "$tail_" = "$new" ] || fail "not the last section" +[ "$(git show 017a28b:rules/web-building.md | sed -n 2p)" = "$(sed -n 2p rules/web-building.md)" ] \ + || fail "paths changed" +echo DESIGN-MOVED diff --git a/.claude/tasks/contracts/c1-readers.sh b/.claude/tasks/contracts/c1-readers.sh new file mode 100644 index 0000000..6fbf297 --- /dev/null +++ b/.claude/tasks/contracts/c1-readers.sh @@ -0,0 +1,14 @@ +#!/usr/bin/env bash +# GATE 0 oracle, contract context-diet c10: the readers name the lib; no +# tracked doctrine file still cites rules/default-language.md. +set -u +for f in skills/init-project/SKILL.md skills/ship-feature/SKILL.md \ + skills/onboard/SKILL.md agents/interviewer.md agents/scaffolder.md \ + skills/audit-delta/SKILL.md agents/seo-analyzer.md; do + grep -q 'lib/architecture-defaults.md' "$f" || { echo "no lib in $f"; exit 1; } +done +if git grep -n 'default-language\.md' -- skills agents lib hooks rules templates \ + .claude/rules CLAUDE.global.md ':!lib/tests'; then + echo "stale default-language.md citer"; exit 1 +fi +echo READERS-OK diff --git a/.claude/tasks/contracts/c1-supabase-functions.sh b/.claude/tasks/contracts/c1-supabase-functions.sh new file mode 100644 index 0000000..8a5f5d4 --- /dev/null +++ b/.claude/tasks/contracts/c1-supabase-functions.sh @@ -0,0 +1,29 @@ +#!/usr/bin/env bash +# GATE 0 oracle, contract context-diet c12: Supabase / cloud-functions bodies +# moved verbatim to path rules; secure-by-default keeps one bullet each and +# every other section byte-identical to 017a28b. +set -u +fail() { echo "$1"; exit 1; } +S=rules/secure-by-default.md +sect() { awk -v h="$1" '$0 == h { f = 1; next } f && /^## / { exit } f && NF'; } +bullets() { awk '/^- / { f = 1 } f && NF' "$1"; } +for r in supabase cloud-functions; do [ -f "rules/$r.md" ] || fail "no rules/$r.md"; done +[ "$(sed -n 2p rules/supabase.md)" = 'paths: ["**/supabase/**", "**/*supabase*.*"]' ] \ + || fail "supabase.md paths" +[ "$(sed -n 2p rules/cloud-functions.md)" = 'paths: ["**/functions/**", "**/serverless.*", "**/firebase.json"]' ] \ + || fail "cloud-functions.md paths" +[ "$(git show "017a28b:$S" | sect '## 4. Supabase')" = "$(bullets rules/supabase.md)" ] \ + || fail "supabase bullets differ" +[ "$(git show "017a28b:$S" | sect '## 6. Cloud functions')" = "$(bullets rules/cloud-functions.md)" ] \ + || fail "cloud-functions bullets differ" +one() { # one … → the section holds one bullet carrying every word + local t; t=$(sect "$1" < "$S"); shift + [ "$(printf '%s\n' "$t" | grep -c '^- ')" = 1 ] || return 1 + t=$(printf '%s' "$t" | tr '\n' ' ') + for w in "$@"; do case "$t" in *"$w"*) ;; *) return 1 ;; esac; done +} +one '## 4. Supabase' RLS service_role rules/supabase.md || fail "§4 line" +one '## 6. Cloud functions' 'Max instances' self-trigger rules/cloud-functions.md || fail "§6 line" +strip() { awk '/^## / { skip = ($0 == "## 4. Supabase" || $0 == "## 6. Cloud functions"); print; next } !skip'; } +[ "$(git show "017a28b:$S" | strip)" = "$(strip < "$S")" ] || fail "other sections changed" +echo SB-CF-MOVED diff --git a/docs/superpowers/plans/2026-10-29-context-diet.md b/docs/superpowers/plans/2026-10-29-context-diet.md index 35ca9f7..7aae6a6 100644 --- a/docs/superpowers/plans/2026-10-29-context-diet.md +++ b/docs/superpowers/plans/2026-10-29-context-diet.md @@ -19,7 +19,7 @@ - Foreign-style repo: match the neighbouring code (inline shell, `check()` test idiom, `PASS=%s FAIL=%s` footer, comments only for the why). Doctrine lines ≤ 80 chars; do not add a line over 80 chars to CLAUDE.global.md (3 exist today). - Tests run only through `make test suite=` or the full `make test`. shellcheck: `shellcheck *.sh hooks/*.sh lib/*.sh` (+ any new `lib/tests/*.sh` you create). - Bash pitfalls: no `head` reading a producer under pipefail (SIGPIPE rc 141); a sourced lib never changes the caller's shell options. -- `settings.json` has two hunks the USER wrote (`"model"` and `"theme"`, from `/model`): never stage or revert them (Task 7 gives the exact recipe). +- `settings.json` carries one uncommitted UI line (`"theme": "dark"`): never stage or revert it (Task 7 gives the exact recipe). - No destructive commands, no file outside this repo (the robin_petier write is a controller step, not yours). ## Review Focus @@ -979,7 +979,7 @@ Run: `make test suite=lib/tests/doctor-automem.test.sh` → `all suites green`; - [ ] **Step 6: settings.json, one line, staged alone** -The working tree holds the user's own uncommitted hunks (three today: `"model"` changed at @@359, `"theme"` + `"switchModelsOnFlag"` added at @@489, the trailing `"switchModelsOnFlag"` removed at @@542): leave them. Stage only the new key, built from HEAD's version: +The working tree holds one uncommitted line written by the Claude Code UI, `"theme": "dark",` right after `"effortLevel": "high",` (gate 2026-10-29: UI writes are stashed, never committed): leave it. Stage only the new key, built from HEAD's version: ```bash tmp=$(mktemp) @@ -993,7 +993,7 @@ jq -e '.autoMemoryEnabled == false' settings.json >/dev/null || { echo "worktree git diff --cached settings.json ``` -Expected: the cached diff is exactly one added line `+ "autoMemoryEnabled": false,`; `git diff settings.json` still shows the user's three hunks and nothing about autoMemoryEnabled; `jq -e '.autoMemoryEnabled == false' settings.json` → true. +Expected: the cached diff is exactly one added line `+ "autoMemoryEnabled": false,`; `git diff settings.json` still shows only the `"theme"` line and nothing about autoMemoryEnabled; `jq -e '.autoMemoryEnabled == false' settings.json` → true. - [ ] **Step 7: Commit** @@ -1004,7 +1004,7 @@ git show --stat HEAD | cat git diff --stat settings.json | cat ``` -Expected: the commit lists settings.json with `1 +`; the user's hunks remain unstaged. +Expected: the commit lists settings.json with `1 +`; the `"theme"` line remains unstaged. --- From 45977899ffb101bab3dc2cb3ee043e84f78d9f33 Mon Sep 17 00:00:00 2001 From: bchanot Date: Thu, 29 Oct 2026 12:55:37 +0100 Subject: [PATCH 06/21] docs(plan): C5 per gate (stash UI settings around finish) --- docs/superpowers/plans/2026-10-29-context-diet.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/superpowers/plans/2026-10-29-context-diet.md b/docs/superpowers/plans/2026-10-29-context-diet.md index 7aae6a6..5df74df 100644 --- a/docs/superpowers/plans/2026-10-29-context-diet.md +++ b/docs/superpowers/plans/2026-10-29-context-diet.md @@ -1073,4 +1073,4 @@ git commit -m "chore(agents): descriptions trimmed to ≤ 200 chars at the sourc - **C2 — proofs** (after Task 8): `bash lib/project-rules.sh -C matches ''` per new glob (faunosteo, game; `**/serverless.*` named if nowhere); one headless `claude -p` per moved path rule naming the Read tool (faunosteo supabase file, game `supabase/functions/*`, a UI file) → `path_glob_match` lines from `~/.claude/logs/instructions-loaded.jsonl`; `claude -p "/context"` vs baseline; analyzer `memory: project` check after an analyzer dispatch. All journaled. If the analyzer memory turns out disabled by `autoMemoryEnabled: false`: STOP and ask the user (revert the line, or keep it and record a BDR). - **C3 — oracles**: `GATES_TIMEOUT=900 bash ~/.claude/lib/gates.sh run .claude/tasks/contracts/2026-10-28-context-diet-1944.md`. - **C4 — TODO.md** (STEP 7 memory commit): phase 1 checked with its proof numbers, follow-ups added (the user removes the auto-memory dirs; any deferred item from the gate). -- **C5 — finish precondition**: `gitflow finish` checks out develop, which git refuses while the user's settings.json hunks are uncommitted (this branch changes settings.json). Before finish the user decides: commit their hunks (own `chore(settings)` commit) or `git stash push -- settings.json` around the finish and `git stash pop` after. Never `git checkout -- settings.json` / restore it (it is the live ~/.claude/settings.json and loses the edits). +- **C5 — finish precondition** (gate 2026-10-29): `gitflow finish` checks out develop, which git refuses while settings.json carries the uncommitted UI line (`"theme"`). Wrap the finish: `git stash push -m "ui settings" -- settings.json`, finish, `git stash pop`. Never `git checkout -- settings.json` / restore it (it is the live ~/.claude/settings.json). Tracked default stays `"model": "opus"`, `"switchModelsOnFlag": true`. From 4bbb3c58d4275600b3b3e9c23174f728373359d9 Mon Sep 17 00:00:00 2001 From: bchanot Date: Thu, 29 Oct 2026 12:56:58 +0100 Subject: [PATCH 07/21] feat(design): Design work moves to rules/web-building.md, hook points there and skips sub-agent hand-backs --- CLAUDE.global.md | 29 +++------------------ hooks/design-toolchain-reminder.sh | 19 ++++++++------ lib/design-gate.md | 5 ++-- lib/tests/design-toolchain-reminder.test.sh | 13 +++++++++ lib/tests/effort-routing.test.sh | 2 +- rules/web-building.md | 23 ++++++++++++++++ 6 files changed, 55 insertions(+), 36 deletions(-) diff --git a/CLAUDE.global.md b/CLAUDE.global.md index b181f52..813843a 100644 --- a/CLAUDE.global.md +++ b/CLAUDE.global.md @@ -277,7 +277,8 @@ cryptic names. - Docs post-ship → document-release (doc if gstack off); stale-doc audit → doc - Grouped all-axes sweep ("tir groupé", fix + loop until clean) → tour - Open-work inventory / "queue empty?" / stale TODO vs git → reconcile -- Design / UI (build, system, audit, polish) → "Design work" below +- Design / UI (build, system, audit, polish) → Read + `~/.claude/rules/web-building.md` § "Design work" first - Architecture review → plan-eng-review - Before /clear or /compact → capitalize; end-of-session ritual → close - superpowers skills are vendored, called by bare name; an upstream @@ -293,33 +294,11 @@ cryptic names. enable higgsfield`, then Read the skill under `~/.claude/skills/`; `higgsfield generate cost` before a paid run. Landing page "with Higgsfield", named ask → `enable higgsfield-websites`: an aid inside - Design work and the site rules, never `website create|deploy|publish`. + the Design work rules (`rules/web-building.md`), never + `website create|deploy|publish`. gstack OFF → its skills (investigate, qa, review, health, retro, office-hours…) are gone: use the fallback above, else say so. -## Design work — full toolchain (tiered by scope) -Trigger = UI work: editing a component/style file (.tsx/.vue/.svelte/.css…) -or a design/UI request, not the word "design" alone. Single source for -design routing; the design-toolchain hook reinforces it. -- Trivial (≤2 files, one cosmetic value) → /hotfix, no toolchain. -- Build UI (component, page, redesign) → impeccable (build path: init, - shape, new-work, craft floor, fresh finish reviewer) + ui-ux-pro-max + - 21st-ui-build (catalog + generation) + emil-design-eng (polish) + - design-motion-principles (motion) + design-html (static) + site-motion. - Floor: `impeccable detect ` (61 rules, exit 2). frontend-design - only for a one-off visual with no project context, not beside impeccable. -- Design system / brand → design-consultation first, then the build tools. -- Review / audit → design-review + emil-design-eng + design-motion-principles - + /impeccable audit|critique + `impeccable detect` floor. -- The vendored stack members route to `reflect` (high) through their - model-router rows (`mods/model-router`); the last rowed skill loaded - wins and an unrowed member (plugin, gstack) changes nothing. -Scope doubt → ask or default to Build, never silently skip. Gate: light -skills run `~/.claude/lib/design-gate.md`, orchestrators plugin-check. 21st = -CLI (`npm i -g @21st-dev/cli`, `21st login`), no MCP, no key; search free, -`21st get`/`generate` metered → generation, not micro-tweaks. 21st-ai / -ui-explore / ui-review are `max`-profile only. - ## graphify Threshold: graphify from 200 tracked code files, never below (banner line diff --git a/hooks/design-toolchain-reminder.sh b/hooks/design-toolchain-reminder.sh index 0c23fbd..165b822 100755 --- a/hooks/design-toolchain-reminder.sh +++ b/hooks/design-toolchain-reminder.sh @@ -1,10 +1,12 @@ #!/usr/bin/env bash # design-toolchain-reminder.sh # -# UserPromptSubmit hook. When the prompt carries a UI/design signal, inject a -# reminder to mobilize the full design toolchain (tiered by scope, per CLAUDE.global.md -# "Design work — full toolchain"). A UserPromptSubmit hook's stdout is appended -# to the model's context, so the cat block below becomes additional guidance. +# UserPromptSubmit hook. When the prompt carries a UI/design signal, point the +# model at the design toolchain section (tiered by scope). Since BDR-125 +# phase 1 it lives in rules/web-building.md § "Design work — full toolchain", +# not in CLAUDE.global.md: it loads by itself on a UI file Read, and a +# chat-only design request needs this pointer. A UserPromptSubmit hook's +# stdout is appended to the model's context. # # This is a soft nudge: the tiered rule itself says trivial work uses NO # toolchain, so a false positive (e.g. "API design") costs only a reminder the @@ -25,10 +27,11 @@ prompt="$(printf '%s' "$input" \ 2>/dev/null || true)" [ -z "$prompt" ] && prompt="$input" -# Harness-generated turns (subagent/task notifications) are not user -# requests — never fire on them (CLAUDE.global.md trigger = a design/UI *request*). +# Harness-generated turns (task notifications, sub-agent hand-backs: 857 of +# 2,779 logged fires on 2026-10-28) are not user requests — never fire on +# them (the Design work trigger = a design/UI *request*). case "$prompt" in - ''*) exit 0 ;; + ''*|'> "$logf" 2>/dev/null || true cat <<'EOF' -Design work detected → apply global CLAUDE.md section "Design work — full toolchain" (already in context). Trivial (≤2 files, cosmetic) → /hotfix. +Design work detected → Read ~/.claude/rules/web-building.md § "Design work — full toolchain" first. Trivial (≤2 files, cosmetic) → /hotfix. EOF fi diff --git a/lib/design-gate.md b/lib/design-gate.md index c515db2..40d3b0a 100644 --- a/lib/design-gate.md +++ b/lib/design-gate.md @@ -45,8 +45,9 @@ design-review, design-consultation, the `21st` CLI and `21st-ui-build` — the canary for the whole 21st skill pack). The profile also bundles browser/plan/shotgun tooling and graphify for convenience; those never trip the gate. Motion (`design-motion-principles`) and static-HTML (`design-html`) are -already in the core set — checked regardless; their CLAUDE.md "+motion / -+static" notes say which tool you'll lean on, not a separate activation step. +already in the core set — checked regardless; the Design work section +(`rules/web-building.md`) names them as the motion and static tools, not a +separate activation step. `site-motion` (personal skill, site-level scroll/page choreography) rides the same Build chain but isn't on the GATE-BLOCK list: it ships with the repo, nothing to install or verify. diff --git a/lib/tests/design-toolchain-reminder.test.sh b/lib/tests/design-toolchain-reminder.test.sh index 53977cb..69df979 100644 --- a/lib/tests/design-toolchain-reminder.test.sh +++ b/lib/tests/design-toolchain-reminder.test.sh @@ -2,6 +2,12 @@ # lib/tests/design-toolchain-reminder.test.sh set -u H="$(cd "$(dirname "$0")/../.." && pwd)/hooks/design-toolchain-reminder.sh" +# Every hook call runs under a throwaway HOME (the fire log is +# $HOME/.claude/logs/design-toolchain-fires.log): the suite never writes the +# real one (1,770 of 2,779 logged fires were this suite's prompts, 2026-10-28). +T="$(mktemp -d)"; trap 'rm -rf "$T"' EXIT +export HOME="$T" +LINE='Design work detected → Read ~/.claude/rules/web-building.md § "Design work — full toolchain" first. Trivial (≤2 files, cosmetic) → /hotfix.' pass=0; fail=0 check() { if [ "$2" = "$3" ]; then pass=$((pass+1)); else fail=$((fail+1)); printf 'FAIL %s: got[%s] want[%s]\n' "$1" "$2" "$3"; fi; } @@ -23,6 +29,7 @@ check D8-dash-file "$(fire 'ecc_dashboard.py')" quiet check D9-tasknotif "$(fire ' x add css header fonts')" quiet check D10-notif-file "$(fire ' design-motion-principles keyframe done')" quiet check D11-bare-ux "$(fire 'changement ux vu de tes trouvailles')" quiet +check D12-agent-msg "$(fire ' [Subagent hand-back] add css header fonts')" quiet # --- Real UI signals must still FIRE --- check F1-button "$(fire 'add a button')" fire @@ -35,6 +42,12 @@ check F7-admin-dash "$(fire 'admin dashboard screen')" fire check F8-animation "$(fire 'add an animation')" fire check F9-designsys "$(fire 'our design system')" fire check F10-bare-ui "$(fire 'revois l'\''ui du panneau admin')" fire +check F11-pasted "$(fire ' add a button')" fire + +# --- The one-liner is a contract (LRN-104): exact text --- +check O1-exact-line "$(printf '{"prompt":"add a button"}' | bash "$H")" "$LINE" +# the fires above landed in the throwaway HOME, positively (not a global count) +check G1-fires-in-temp-home "$([ -s "$T/.claude/logs/design-toolchain-fires.log" ] && echo yes)" yes # --- Fire is logged (time + token + excerpt) --- tmp="$(mktemp -d)" diff --git a/lib/tests/effort-routing.test.sh b/lib/tests/effort-routing.test.sh index 4743217..902865f 100755 --- a/lib/tests/effort-routing.test.sh +++ b/lib/tests/effort-routing.test.sh @@ -210,7 +210,7 @@ has "agents/client-handover-writer.md" 'ROUTING: follow $HOME/.claude/lib/effort # ── (f) doctrine includes ──────────────────────────────────────────────── has "lib/model-gate.md" 'mcp__model-router__route' has "lib/effort-shift.md" 'ToolSearch' -has "CLAUDE.global.md" 'route to `reflect` (high) through their' +has "rules/web-building.md" 'route to `reflect` (high) through their' # ── (g) session default and hooks (unchanged locks) ────────────────────── has "settings.json" '"effortLevel": "high"' diff --git a/rules/web-building.md b/rules/web-building.md index 809a0b4..76cfcdc 100644 --- a/rules/web-building.md +++ b/rules/web-building.md @@ -43,3 +43,26 @@ compressed images. Report the missing items to the user instead of inventing them. Internal tools and dashboards: only the relevant items apply. Deep audits stay with /seo, /harden, /web-validate. + +## Design work — full toolchain (tiered by scope) +Trigger = UI work: editing a component/style file (.tsx/.vue/.svelte/.css…) +or a design/UI request, not the word "design" alone. Single source for +design routing; the design-toolchain hook reinforces it. +- Trivial (≤2 files, one cosmetic value) → /hotfix, no toolchain. +- Build UI (component, page, redesign) → impeccable (build path: init, + shape, new-work, craft floor, fresh finish reviewer) + ui-ux-pro-max + + 21st-ui-build (catalog + generation) + emil-design-eng (polish) + + design-motion-principles (motion) + design-html (static) + site-motion. + Floor: `impeccable detect ` (61 rules, exit 2). frontend-design + only for a one-off visual with no project context, not beside impeccable. +- Design system / brand → design-consultation first, then the build tools. +- Review / audit → design-review + emil-design-eng + design-motion-principles + + /impeccable audit|critique + `impeccable detect` floor. +- The vendored stack members route to `reflect` (high) through their + model-router rows (`mods/model-router`); the last rowed skill loaded + wins and an unrowed member (plugin, gstack) changes nothing. +Scope doubt → ask or default to Build, never silently skip. Gate: light +skills run `~/.claude/lib/design-gate.md`, orchestrators plugin-check. 21st = +CLI (`npm i -g @21st-dev/cli`, `21st login`), no MCP, no key; search free, +`21st get`/`generate` metered → generation, not micro-tweaks. 21st-ai / +ui-explore / ui-review are `max`-profile only. From de6e51ce7ae606009a3e6f42c5f4197c5f995c70 Mon Sep 17 00:00:00 2001 From: bchanot Date: Thu, 29 Oct 2026 12:58:53 +0100 Subject: [PATCH 08/21] feat(graphify): usage rules print from session-start only where a graph exists --- CLAUDE.global.md | 10 +++------- hooks/session-start.sh | 23 +++++++++++++++++++---- lib/tests/graphify-gate.test.sh | 16 ++++++++++++++++ 3 files changed, 38 insertions(+), 11 deletions(-) diff --git a/CLAUDE.global.md b/CLAUDE.global.md index 813843a..fabc896 100644 --- a/CLAUDE.global.md +++ b/CLAUDE.global.md @@ -303,10 +303,6 @@ office-hours…) are gone: use the fallback above, else say so. Threshold: graphify from 200 tracked code files, never below (banner line `graphify? N code files ≥ 200, no graph` informs, the user decides; never -build or `graphify claude install` without that go). ALL rules below apply -only if `graphify-out/graph.json` exists — else read files directly. -- Codebase-wide question → `graphify query`; relationships → `path A B`; - concept → `explain`. Scoped subgraph beats raw grep. -- Known file / small task → read directly, no graphify. -- `wiki/index.md` → broad-nav entry; `GRAPH_REPORT.md` → whole-architecture. -- After editing code → `graphify update .` (AST-only, free). +build or `graphify claude install` without that go). With a graph +(`graphify-out/graph.json`): `graphify query` before raw grep, +`graphify update .` after code edits; the session banner prints the rest. diff --git a/hooks/session-start.sh b/hooks/session-start.sh index 6a2a340..b81d262 100644 --- a/hooks/session-start.sh +++ b/hooks/session-start.sh @@ -7,7 +7,7 @@ # ── Quick health check (filesystem only, no subprocesses) ── BROKEN=() -for f in CLAUDE.md settings.json agents skills; do +for f in CLAUDE.md settings.json agents skills rules; do [ ! -e "$HOME/.claude/$f" ] && BROKEN+=("$f") done @@ -254,9 +254,9 @@ if [ -n "$GRAPHIFY_HINT" ]; then printf "│ 🕸️ %-44s│\n" "${GRAPHIFY_HINT:0:44}" printf "│ %-40s│\n" "→ /graphify (AST, seconds) — you decide" fi -# CLAUDE.global.md line-count guard (anti-regression). BDR-062 supersedes -# BDR-031's 275 target: 305 is the assumed reality (extraction done at -# job1; further compression costs clarity > token gain) — warn past 320. +# CLAUDE.global.md line-count guard (anti-regression, BDR-062): warn past +# 320. BDR-125 phase 1 moved Design work, the graphify usage and the +# architecture defaults to their carriers (333 → ~285 lines). if [ -n "$REPO_DIR" ] && [ -f "$REPO_DIR/CLAUDE.global.md" ]; then _claude_lines=$(wc -l < "$REPO_DIR/CLAUDE.global.md") if [ "$_claude_lines" -gt 320 ]; then @@ -293,5 +293,20 @@ echo "│ 💡 /plugin-check before starting a new project │" echo "│ 🩺 make doctor full diagnostic │" echo "└───────────────────────────────────────────────────┘" [ -n "$EFFORT_WARN" ] && printf '%s\n' "$EFFORT_WARN" +# graphify usage (BDR-125 phase 1): the rules left CLAUDE.global.md, which +# keeps the 200-file threshold and a one-line reminder; they print where a +# graph exists. +_gx_root=$(git rev-parse --show-toplevel 2>/dev/null) +if [ -n "$_gx_root" ] && [ -f "$_gx_root/graphify-out/graph.json" ]; then + cat <<'EOF' +graphify (graphify-out/graph.json present): +- Codebase-wide question → `graphify query`; relationships → `path A B`; + concept → `explain`. Scoped subgraph beats raw grep. +- Known file / small task → read directly, no graphify. +- `wiki/index.md` → broad-nav entry; `GRAPH_REPORT.md` → whole-architecture. +- After editing code → `graphify update .` (AST-only, free). +EOF +fi +unset _gx_root echo "" unset TOKEN_WARN diff --git a/lib/tests/graphify-gate.test.sh b/lib/tests/graphify-gate.test.sh index 221d2fb..90bb50e 100644 --- a/lib/tests/graphify-gate.test.sh +++ b/lib/tests/graphify-gate.test.sh @@ -56,5 +56,21 @@ for i in $(seq 1 300); do echo "# $i" > "$d/doc$i.md"; done git -C "$d" add -A; git -C "$d" commit -q -m docs check T9-non-code-not-counted "$(gate "$d")" silent +# ── session-start prints the usage rules only where a graph exists +# (BDR-125 phase 1: the body left CLAUDE.global.md) ── +SS="$(cd "$(dirname "$0")/../.." && pwd)/hooks/session-start.sh" +banner() { (cd "$1" && SESSION_START_OFFLINE=1 bash "$SS" /dev/null); } +d=$(mkrepo ss 1) +out=$(banner "$d") +check S1-banner-control "$(grep -c 'Claude Code config' <<<"$out")" 1 +check S1b-no-graph-silent "$(grep -c 'graphify query' <<<"$out")" 0 +mkdir -p "$d/graphify-out" "$d/app/sub"; echo '{}' > "$d/graphify-out/graph.json" +out=$(banner "$d") +check S2-graph-prints "$(grep -c 'graphify query' <<<"$out")" 1 +check S2b-update-rule "$(grep -c 'graphify update \.' <<<"$out")" 1 +check S3-from-subdir "$(banner "$d/app/sub" | grep -c 'graphify query')" 1 +out=$(banner "$WORK/plain") +check S4-not-a-repo "$(grep -c 'graphify query' <<<"$out")/$(grep -c 'Claude Code config' <<<"$out")" 0/1 + echo "PASS=$pass FAIL=$fail" [ "$fail" -eq 0 ] From 2fe5291a13203893ff02106add00a26255ebb954 Mon Sep 17 00:00:00 2001 From: bchanot Date: Thu, 29 Oct 2026 13:00:58 +0100 Subject: [PATCH 09/21] feat(doctrine): architecture defaults move to lib/architecture-defaults.md, Web APIs to rules/rest-api.md --- .claude/rules/rules-maintenance.md | 21 ++++++----- CLAUDE.global.md | 28 ++------------ agents/interviewer.md | 2 +- agents/scaffolder.md | 3 +- agents/seo-analyzer.md | 4 +- lib/architecture-defaults.md | 49 +++++++++++++++++++++++++ lib/project-archetypes/rest-api-node.md | 2 +- rules/default-language.md | 23 ------------ rules/rest-api.md | 8 +++- skills/audit-delta/SKILL.md | 5 ++- skills/init-project/SKILL.md | 6 ++- skills/onboard/SKILL.md | 4 ++ skills/ship-feature/SKILL.md | 3 ++ 13 files changed, 92 insertions(+), 66 deletions(-) create mode 100644 lib/architecture-defaults.md delete mode 100644 rules/default-language.md diff --git a/.claude/rules/rules-maintenance.md b/.claude/rules/rules-maintenance.md index 9089601..8935a23 100644 --- a/.claude/rules/rules-maintenance.md +++ b/.claude/rules/rules-maintenance.md @@ -9,15 +9,18 @@ Modular instruction files loaded by Claude Code alongside the global memory. projects). One rule = one file = one concern. A rule WITH `paths:` YAML frontmatter (glob list) loads lazily — only when -Claude reads a file matching a glob; a rule WITHOUT it loads at session -start, same cost as the global memory. Extract from CLAUDE.global.md only -what can be path-scoped (the token win) or what is generated; always-on -doctrine stays in CLAUDE.global.md. Exception: a standalone user-authored -rule set that would bust the 320-line density budget may live here WITHOUT -`paths:` (always-on load) — writing-style.md (BDR-085), default-language.md -(BDR-118), secure-by-default.md (BDR-120). `paths:` globs match against the -CURRENT project's tree — a broad glob (e.g. `rules/**`) can fire in foreign -projects; keep rule bodies tiny. +Claude Reads a file matching a glob (never on the Write of a new file; +sub-agents too); a rule WITHOUT it loads at session start, same cost as the +global memory. Doctrine leaves CLAUDE.global.md only for a carrier that fires +when it is needed (BDR-125 phase 1: a path rule, a hook, a lib our skills +Read), with one always-on line wherever plain chat still needs the rule. +Exception: a standalone user-authored rule set that would bust the 320-line +density budget may live here WITHOUT `paths:` (always-on load) — +writing-style.md (BDR-085), secure-by-default.md (BDR-120); +`lib/tests/user-rules.test.sh` locks that set. `paths:` globs match against +the CURRENT project's tree, gitignore-style (a pattern without an inner `/` +matches at any depth, hidden dirs included) — a broad glob (e.g. `rules/**`) +can fire in foreign projects; keep rule bodies tiny. Docs: https://code.claude.com/docs/en/memory.md#path-specific-rules Machine-owned: `rules/context7.md` is DELETED BY DESIGN (BDR-053, diff --git a/CLAUDE.global.md b/CLAUDE.global.md index fabc896..ae7f491 100644 --- a/CLAUDE.global.md +++ b/CLAUDE.global.md @@ -140,30 +140,10 @@ their CAPITALIZE step. Session close (`/close` = `/capitalize --ritual`): what was decided → decisions, learned → learnings, blocked → blockers. # Architecture decisions -Override default framework/tooling choices at project creation, scaffolding, -brainstorming. - -## Public websites — never SPA -A public site meant to be indexed (landing, portfolio, blog, e-commerce, -docs) is never a pure SPA (CRA, Vite React, Vue SPA): the empty HTML shell -hides content from search and AI engines, SEO and GEO destroyed. -- **Astro** by default for informational sites: static HTML at build, zero - JS by default, React/Vue/Svelte islands for interactive parts. -- **Next.js** when dynamic SSR is needed (personalized content, server-side - auth, API routes, hybrid app). -- **React SPA** only for what needs no indexing: admin panels, dashboards, - auth-gated apps, internal tools. Mixed project: Astro/Next for public, - React island (`client:only`) for admin. -- At brainstorming (`/init-project`, `/ship-feature` STEP 1), public site - and no framework named → propose Astro, explain why not SPA. Never - silently pick React CRA. - -## Web APIs — always versioned -Every endpoint versioned from day one: `/api/v1/...`, no bare `/api/`; the -router mirrors it (`api/v1/routes/`). Breaking change → `v2`, the old -version keeps working and clients migrate at their pace; non-breaking -additions → current version. Each version is a self-contained contract, -never bent to match a newer one. +New project, scaffolding, stack brainstorm or whole-project rewrite: Rust +by default, a public site is never a SPA (Astro; Next.js when SSR is +needed), every web API versioned `/api/v1/` from day one. Read +`~/.claude/lib/architecture-defaults.md` before proposing a stack. ## Version control — gitflow (universal) Every git action follows gitflow, inside a skill or for an ad-hoc commit. diff --git a/agents/interviewer.md b/agents/interviewer.md index 6cafcfd..e08acc6 100644 --- a/agents/interviewer.md +++ b/agents/interviewer.md @@ -23,7 +23,7 @@ Gather context. Produce complete PROJECT BRIEF as single source of truth. | Answer vague/ambiguous | One targeted follow-up on that item only | Gap: record it in OPEN DECISIONS with the safest reading, marked `(assumed)` — never invent a confident value. Visible / public-name / scope item: one more targeted question instead, never `(assumed)` | | "I don't know / you decide" | Propose ONE concrete default + why, ask yes/no | Take the default, mark `(assumed)`, list in OPEN DECISIONS | | Contradictory answers (e.g. embedded runtime + managed cloud DB) | Name the contradiction, ask which side wins | Put BOTH options in OPEN DECISIONS; do not silently pick one | -| Language not stated (new project / from scratch / whole-project rewrite) | Propose Rust + why (`rules/default-language.md`); name the contraindication if another language fits better (browser frontend, mandated platform, missing ecosystem) | Rust, marked `(assumed)`, listed in OPEN DECISIONS | +| Language not stated (new project / from scratch / whole-project rewrite) | Propose Rust + why (`~/.claude/lib/architecture-defaults.md` § Default language); name the contraindication if another language fits better (browser frontend, mandated platform, missing ecosystem) | Rust, marked `(assumed)`, listed in OPEN DECISIONS | | Project has an API, a database, messaging, cloud functions or a UI | Apply `rules/secure-by-default.md`: note under QUALITY which of the six guardrail domains apply, and whether the accessibility baseline (`rules/a11y.md`) applies, and list each dashboard-only item (spend cap, WAF, budget alert) in OPEN DECISIONS as manual | A domain applies and nothing is planned: list it in OPEN DECISIONS, never drop it silently | | Partial answer to the block | Re-ask ONLY the missing items in the follow-up round | Missing fields → `none stated` + OPEN DECISIONS entry | | Feature list balloons (>10) | Keep the 10 the user ranks first as V1 | Overflow goes to OUT OF SCOPE with a `(deferred by budget)` tag | diff --git a/agents/scaffolder.md b/agents/scaffolder.md index 9d24a93..adfb05f 100644 --- a/agents/scaffolder.md +++ b/agents/scaffolder.md @@ -16,6 +16,7 @@ Deliver a buildable skeleton: structure + config + empty entry points. No featur 2. Approved DESIGN (from brainstorming) 3. `~/.claude/templates/project-CLAUDE.md` 4. `~/.claude/CLAUDE.md` +5. `~/.claude/lib/architecture-defaults.md` If any missing → STOP. @@ -31,7 +32,7 @@ Store: `DOCKER_RELEVANT = true/false`. If true → Docker is additional, project ## PHASE 1 — GENERATE CLAUDE.md -Read `~/.claude/templates/project-CLAUDE.md` and `~/.claude/CLAUDE.md`. +Read `~/.claude/templates/project-CLAUDE.md`, `~/.claude/CLAUDE.md` and `~/.claude/lib/architecture-defaults.md`. Fill every section from BRIEF + DESIGN. No placeholders. Irrelevant sections → `N/A — `. Required: overview, stack+version, build/test/lint/docker commands (exact), folder tree, architecture, conventions, exceptions, deps, workflow. Write to `CLAUDE.md` at project root. diff --git a/agents/seo-analyzer.md b/agents/seo-analyzer.md index 7613567..f6a3b91 100644 --- a/agents/seo-analyzer.md +++ b/agents/seo-analyzer.md @@ -539,8 +539,8 @@ it is. **§0 line, mandatory when not server-rendered:** `Rendering: client-rendered — On-page NOT scored (content absent from served -HTML). Global score excludes it. Fix: SSR/SSG (CLAUDE.md: public sites are -never SPAs).` +HTML). Global score excludes it. Fix: SSR/SSG +(lib/architecture-defaults.md: public sites are never SPAs).` This is the honest half of the R1/R2 call: we do not render JS (no Playwright, no Chromium), so we do not pretend to see what JS paints. Refusing is the diff --git a/lib/architecture-defaults.md b/lib/architecture-defaults.md new file mode 100644 index 0000000..5866d39 --- /dev/null +++ b/lib/architecture-defaults.md @@ -0,0 +1,49 @@ +# Architecture defaults — read before proposing a stack + +Read at project creation, scaffolding, a stack brainstorm or a whole-project +rewrite (BDR-125 phase 1). The three defaults are named always-on in +`~/.claude/CLAUDE.md` § "Architecture decisions"; the detail lives here. + +## Public websites — never SPA +A public site meant to be indexed (landing, portfolio, blog, e-commerce, +docs) is never a pure SPA (CRA, Vite React, Vue SPA): the empty HTML shell +hides content from search and AI engines, SEO and GEO destroyed. +- **Astro** by default for informational sites: static HTML at build, zero + JS by default, React/Vue/Svelte islands for interactive parts. +- **Next.js** when dynamic SSR is needed (personalized content, server-side + auth, API routes, hybrid app). +- **React SPA** only for what needs no indexing: admin panels, dashboards, + auth-gated apps, internal tools. Mixed project: Astro/Next for public, + React island (`client:only`) for admin. +- At brainstorming (`/init-project`, `/ship-feature` STEP 1), public site + and no framework named → propose Astro, explain why not SPA. Never + silently pick React CRA. + +## Default language — Rust + +Scope: a new project, a project from scratch, or a whole-project +refactor or rewrite the user asks for. Not a module refactor or a feature +inside an existing codebase: that keeps the codebase's language. + +Rust is the default. Two candidates equal on features, security, +performance, reliability and ease of use or maintenance → Rust wins. +Where Rust can do the job, Rust does it. + +Another language needs a demonstrated gain on one of those axes, stated +at the choice: a browser frontend (TypeScript, Astro per the web rules), +a platform that mandates its language (Swift, Kotlin), an ecosystem Rust +lacks (ML research → Python), a throwaway script where Rust's build +cycle costs more than it returns. "Rust is slower to write" alone is not +a gain. + +At brainstorming (`/init-project`, `/ship-feature` STEP 1, `/refactor` +of a whole project): language not named → propose Rust, name the +contraindication if you pick something else. Never silently default to +Python, Node or Go. Mixed project: Rust for everything server-side, +CLI, systems and tooling; the exception stays scoped to the part that +earned it. + +## Web APIs — always versioned +Every endpoint `/api/v1/...` from day one; breaking change → `v2`, the old +version keeps working. Full rule: `~/.claude/rules/rest-api.md` § Versioning +(loads on API files). diff --git a/lib/project-archetypes/rest-api-node.md b/lib/project-archetypes/rest-api-node.md index 239e484..2c5f71b 100644 --- a/lib/project-archetypes/rest-api-node.md +++ b/lib/project-archetypes/rest-api-node.md @@ -55,7 +55,7 @@ API backend Node.js pure (Express / Fastify / Koa / Hapi / NestJS), sans fronten - **UI/UX** : N/A ## Typical pain points -- Pas de versioning API (/api/v1/) — flag CLAUDE.md : "Web APIs — always versioned" +- Pas de versioning API (/api/v1/) — flag `rules/rest-api.md` § Versioning - Validation input absente (pas de Zod/Joi/class-validator) - SQL injections (string concat dans queries brutes) - Auth faible (pas de hash password, ou MD5/SHA1) diff --git a/rules/default-language.md b/rules/default-language.md deleted file mode 100644 index 9eb15fe..0000000 --- a/rules/default-language.md +++ /dev/null @@ -1,23 +0,0 @@ -# Default language — Rust - -Scope: a new project, a project from scratch, or a whole-project -refactor or rewrite the user asks for. Not a module refactor or a feature -inside an existing codebase: that keeps the codebase's language. - -Rust is the default. Two candidates equal on features, security, -performance, reliability and ease of use or maintenance → Rust wins. -Where Rust can do the job, Rust does it. - -Another language needs a demonstrated gain on one of those axes, stated -at the choice: a browser frontend (TypeScript, Astro per the web rules), -a platform that mandates its language (Swift, Kotlin), an ecosystem Rust -lacks (ML research → Python), a throwaway script where Rust's build -cycle costs more than it returns. "Rust is slower to write" alone is not -a gain. - -At brainstorming (`/init-project`, `/ship-feature` STEP 1, `/refactor` -of a whole project): language not named → propose Rust, name the -contraindication if you pick something else. Never silently default to -Python, Node or Go. Mixed project: Rust for everything server-side, -CLI, systems and tooling; the exception stays scoped to the part that -earned it. diff --git a/rules/rest-api.md b/rules/rest-api.md index e971f83..e4e7a0f 100644 --- a/rules/rest-api.md +++ b/rules/rest-api.md @@ -31,7 +31,7 @@ wait, or 202 + status URL. Retention outlives the longest retry path, dead-letter replay included. ## Naming -Plural nouns for endpoints (`/api/tasks`), no verbs. camelCase query +Plural nouns for endpoints (`/api/v1/tasks`), no verbs. camelCase query params and response fields. UPPER_SNAKE enum values. Boolean fields prefixed is/has/can. @@ -40,4 +40,8 @@ Every observable behavior — undocumented quirks, error text, timing — becomes a de facto contract once someone depends on it. ## Versioning -CLAUDE.md § Web APIs — always versioned. Not repeated here. +Every endpoint versioned from day one: `/api/v1/...`, no bare `/api/`; the +router mirrors it (`api/v1/routes/`). Breaking change → `v2`, the old +version keeps working and clients migrate at their pace; non-breaking +additions → current version. Each version is a self-contained contract, +never bent to match a newer one. diff --git a/skills/audit-delta/SKILL.md b/skills/audit-delta/SKILL.md index c0a6c3a..c2a2ee0 100644 --- a/skills/audit-delta/SKILL.md +++ b/skills/audit-delta/SKILL.md @@ -273,8 +273,9 @@ Then offer to capitalize (per CLAUDE.md): recurring finding patterns → errors, resource leaks (missing trap/close/finally). Improvements only when concrete and local: simplification, dedup against an existing helper, obvious perf. -- **conformity** — read project `CLAUDE.md` (+ `~/.claude/CLAUDE.md`) - FIRST, then check changed code against those norms. This repo's: +- **conformity** — read project `CLAUDE.md` (+ `~/.claude/CLAUDE.md` and + `~/.claude/lib/architecture-defaults.md`) FIRST, then check changed code + against those norms. This repo's: ≤25 logic lines/function, ≤80 chars/line, ≤5 params, ≤5 locals, no global state, intent-not-mechanics comments, explicit naming, versioned APIs (`/api/v1/`), no-SPA-for-public-sites, security defaults. Foreign diff --git a/skills/init-project/SKILL.md b/skills/init-project/SKILL.md index 1fba43b..ec51f8a 100644 --- a/skills/init-project/SKILL.md +++ b/skills/init-project/SKILL.md @@ -71,6 +71,9 @@ Load `$HOME/.claude/agents/analyzer.md`. Analyze BRIEF: existing code, stack con ## STEP 3 — DESIGN Invoke `brainstorming` (vendored superpowers skill) with BRIEF + ANALYSIS REPORT. +Read `~/.claude/lib/architecture-defaults.md` first and pass it as binding +context: its defaults (Rust, never a SPA for a public site, `/api/v1/`) hold +unless the BRIEF names otherwise. Produce DESIGN: stack+versions, full folder tree, module responsibilities, data flow, interfaces (signatures only), config+tooling, test strategy, resolved decisions, prereqs list. Then run pass B of `$HOME/.claude/lib/contract-interview.md` against the DESIGN (minus what the BRIEF and the brainstorm settled): one batch before STEP 4; @@ -102,7 +105,8 @@ BDR-077 : le design est CLOS au gate #1, le scaffold est de l'exécution, plus jamais inline sur le modèle de session). Pass IN THE PROMPT (LRN-126 — every field the scaffolder consumes crosses the dispatch): BRIEF (verbatim) + DESIGN (verbatim) + paths `~/.claude/templates/project-CLAUDE.md` + -`~/.claude/CLAUDE.md`. A STOP (missing input) comes back as its report — +`~/.claude/CLAUDE.md` + `~/.claude/lib/architecture-defaults.md`. A STOP +(missing input) comes back as its report — resolve here, re-dispatch. The ~30s liveness pings are THIS loop's job while waiting. Creates: CLAUDE.md, `.claude/settings.json`, `.claudeignore`, `.gitignore`, `.env.example`, empty entry points. NO README, NO features. diff --git a/skills/onboard/SKILL.md b/skills/onboard/SKILL.md index f8cc5d3..de4d4a4 100644 --- a/skills/onboard/SKILL.md +++ b/skills/onboard/SKILL.md @@ -371,6 +371,10 @@ Attendre la fin. Vérifier que `.onboard-audit/analyze.md` existe et est non vid Lire le bloc `audit_stack:` du fichier `~/.claude/lib/project-archetypes/.md`. +Les audits jugent l'architecture contre `~/.claude/lib/architecture-defaults.md` +(site public jamais SPA, API `/api/v1/`, Rust par défaut pour une réécriture) : +passer ce chemin dans chaque brief d'audit. + **Mapping audit_stack entry → action :** | Entry | Action | Livraison | diff --git a/skills/ship-feature/SKILL.md b/skills/ship-feature/SKILL.md index 1cf342c..850bee4 100644 --- a/skills/ship-feature/SKILL.md +++ b/skills/ship-feature/SKILL.md @@ -110,6 +110,9 @@ not the raw request alone: Existing code that bears: . Brainstorm WITHIN these — don't re-explore a direction an in-force BDR rejects or a BLK already closed." +When the feature picks a language, a framework or an API shape, Read +`~/.claude/lib/architecture-defaults.md` first and add its defaults to the +in-force constraints. Inject ONLY what constrains: the NON-BINDING count does NOT enter the brainstorm input (the injection inherits the OUTPUT filter — detail what binds, drop what doesn't). Consumption = INPUT INJECTION (we can't modify the external skill; we control its input). From 664d1ea8395502cebb0b41cce58819465856c058 Mon Sep 17 00:00:00 2001 From: bchanot Date: Thu, 29 Oct 2026 13:03:31 +0100 Subject: [PATCH 10/21] feat(rules): Supabase and cloud-functions bodies become path rules, one always-on line each --- agents/interviewer.md | 2 +- rules/cloud-functions.md | 13 +++++++++++++ rules/secure-by-default.md | 15 ++++----------- rules/supabase.md | 16 ++++++++++++++++ skills/guardrails/SKILL.md | 3 ++- 5 files changed, 36 insertions(+), 13 deletions(-) create mode 100644 rules/cloud-functions.md create mode 100644 rules/supabase.md diff --git a/agents/interviewer.md b/agents/interviewer.md index e08acc6..95c83e2 100644 --- a/agents/interviewer.md +++ b/agents/interviewer.md @@ -24,7 +24,7 @@ Gather context. Produce complete PROJECT BRIEF as single source of truth. | "I don't know / you decide" | Propose ONE concrete default + why, ask yes/no | Take the default, mark `(assumed)`, list in OPEN DECISIONS | | Contradictory answers (e.g. embedded runtime + managed cloud DB) | Name the contradiction, ask which side wins | Put BOTH options in OPEN DECISIONS; do not silently pick one | | Language not stated (new project / from scratch / whole-project rewrite) | Propose Rust + why (`~/.claude/lib/architecture-defaults.md` § Default language); name the contraindication if another language fits better (browser frontend, mandated platform, missing ecosystem) | Rust, marked `(assumed)`, listed in OPEN DECISIONS | -| Project has an API, a database, messaging, cloud functions or a UI | Apply `rules/secure-by-default.md`: note under QUALITY which of the six guardrail domains apply, and whether the accessibility baseline (`rules/a11y.md`) applies, and list each dashboard-only item (spend cap, WAF, budget alert) in OPEN DECISIONS as manual | A domain applies and nothing is planned: list it in OPEN DECISIONS, never drop it silently | +| Project has an API, a database, messaging, cloud functions or a UI | Apply `rules/secure-by-default.md` (Supabase and cloud-function detail: `rules/supabase.md`, `rules/cloud-functions.md`): note under QUALITY which of the six guardrail domains apply, and whether the accessibility baseline (`rules/a11y.md`) applies, and list each dashboard-only item (spend cap, WAF, budget alert) in OPEN DECISIONS as manual | A domain applies and nothing is planned: list it in OPEN DECISIONS, never drop it silently | | Partial answer to the block | Re-ask ONLY the missing items in the follow-up round | Missing fields → `none stated` + OPEN DECISIONS entry | | Feature list balloons (>10) | Keep the 10 the user ranks first as V1 | Overflow goes to OUT OF SCOPE with a `(deferred by budget)` tag | diff --git a/rules/cloud-functions.md b/rules/cloud-functions.md new file mode 100644 index 0000000..91a32c3 --- /dev/null +++ b/rules/cloud-functions.md @@ -0,0 +1,13 @@ +--- +paths: ["**/functions/**", "**/serverless.*", "**/firebase.json"] +--- + +# Cloud functions — secure by default, domain 6 + +Path-scoped body of `rules/secure-by-default.md` domain 6 (BDR-125 phase 1); +the always-on line there keeps the instance cap and the self-trigger ban. + +- No function re-triggers itself: never write to the resource that fires it, + never invoke itself. If unavoidable, guard with an idempotency flag. +- Max instances (or reserved concurrency) and a timeout on every function. +- Budget alert wired to an automatic stop beyond the budget. diff --git a/rules/secure-by-default.md b/rules/secure-by-default.md index 1a97ccc..d31753b 100644 --- a/rules/secure-by-default.md +++ b/rules/secure-by-default.md @@ -39,13 +39,8 @@ never claimed done: write it as a manual step in the project's deploy notes. comments carry no token, hash, key or secret. ## 4. Supabase -- RLS enabled on every table, in the migration that creates it. -- Policies limited to the owner: `(select auth.uid())` per operation, role - `authenticated`. No `using (true)` on writes, no anon write. -- No `service_role` or secret key client-side: not in a bundle, not in a - `NEXT_PUBLIC_`, `VITE_` or `PUBLIC_` variable. -- Views `security_invoker`. `security definer` functions pin `search_path` - and revoke execute from anon. Buckets private by default. +- RLS on every table, never a service_role or secret key client-side. Full + domain: rules/supabase.md (loads on Supabase files). ## 5. SMS and email - Prior consent recorded per contact: who, when, channel, source, wording. @@ -54,7 +49,5 @@ never claimed done: write it as a manual step in the project's deploy notes. SMS says STOP, and a STOP reply is processed and stored automatically. ## 6. Cloud functions -- No function re-triggers itself: never write to the resource that fires it, - never invoke itself. If unavoidable, guard with an idempotency flag. -- Max instances (or reserved concurrency) and a timeout on every function. -- Budget alert wired to an automatic stop beyond the budget. +- Max instances and a timeout on every function, never a self-trigger. Full + domain: rules/cloud-functions.md (loads on function files). diff --git a/rules/supabase.md b/rules/supabase.md new file mode 100644 index 0000000..9552f11 --- /dev/null +++ b/rules/supabase.md @@ -0,0 +1,16 @@ +--- +paths: ["**/supabase/**", "**/*supabase*.*"] +--- + +# Supabase — secure by default, domain 4 + +Path-scoped body of `rules/secure-by-default.md` domain 4 (BDR-125 phase 1); +the always-on line there keeps RLS and the client-side key ban. + +- RLS enabled on every table, in the migration that creates it. +- Policies limited to the owner: `(select auth.uid())` per operation, role + `authenticated`. No `using (true)` on writes, no anon write. +- No `service_role` or secret key client-side: not in a bundle, not in a + `NEXT_PUBLIC_`, `VITE_` or `PUBLIC_` variable. +- Views `security_invoker`. `security definer` functions pin `search_path` + and revoke execute from anon. Buckets private by default. diff --git a/skills/guardrails/SKILL.md b/skills/guardrails/SKILL.md index bce5357..3b98a8a 100644 --- a/skills/guardrails/SKILL.md +++ b/skills/guardrails/SKILL.md @@ -7,7 +7,8 @@ argument-hint: '[project path] [--domain api,hosting,supabase,messaging,function # /guardrails -Checks a project against `rules/secure-by-default.md`, then fixes what the +Checks a project against `rules/secure-by-default.md` (domains 4 and 6 in +full: `rules/supabase.md`, `rules/cloud-functions.md`), then fixes what the user accepts and proves each fix. A scanner reads the tree as data and finds what text can prove. This skill judges the hits, covers what text cannot prove, lists what only a dashboard can set and, on request, probes a running From 6a642956d8eb5bca16f7c80ad5deef37ed2b2c15 Mon Sep 17 00:00:00 2001 From: bchanot Date: Thu, 29 Oct 2026 13:05:17 +0100 Subject: [PATCH 11/21] test(rules): user-rules suite locks the always-on set; engine matching documented --- lib/project-rules.sh | 8 ++++-- lib/tests/user-rules.test.sh | 55 ++++++++++++++++++++++++++++++++++++ 2 files changed, 61 insertions(+), 2 deletions(-) create mode 100755 lib/tests/user-rules.test.sh diff --git a/lib/project-rules.sh b/lib/project-rules.sh index 47c0c80..1bf4f6d 100644 --- a/lib/project-rules.sh +++ b/lib/project-rules.sh @@ -19,8 +19,12 @@ # no brace expansion: one glob per extension; a symlinked dir matches # when the glob names it, globstar never descends into a symlink met # under `**`; -# dotglob makes `*` match dotfiles, which the engine's matcher skips: a -# glob that only hits hidden paths passes here but never loads), +# dotglob makes `*` match dotfiles; the engine reaches hidden dirs too. Its +# matcher looks gitignore-style (InstructionsLoaded log, 2026-10-26: +# `paths: ["rules/**"]` logged as `globs: ["rules"]` and loaded on a Read +# of `.claude/rules/*.md`): a trailing `/**` dropped, a pattern without an +# inner `/` matching at any depth. A glob can thus load where this check +# does not look; the load proof is the logged session, not this check), # dependency dirs excluded (unless the glob names one: `vendor/**` is a # valid rule): the engine matches the path the model reads, # tracked or not; a typo matches nothing either way. A frontmatter line diff --git a/lib/tests/user-rules.test.sh b/lib/tests/user-rules.test.sh new file mode 100755 index 0000000..b777d9a --- /dev/null +++ b/lib/tests/user-rules.test.sh @@ -0,0 +1,55 @@ +#!/usr/bin/env bash +# lib/tests/user-rules.test.sh — user-scope rules (rules/*.md, deployed as +# ~/.claude/rules): every frontmatter parses (one-line JSON `paths:` or no +# frontmatter at all) and the always-on set is exactly the two rules chat +# needs (BDR-125 phase 1 moved default-language to lib/architecture-defaults.md +# and the Supabase / cloud-functions bodies to path rules). Globs are not +# matched here: user rules span every stack; the load is proved by an +# InstructionsLoaded session (contract context-diet, criterion 15). +set -u +ROOT="$(cd "$(dirname "$0")/../.." && pwd)" +# shellcheck source=../project-rules.sh disable=SC1091 +source "$ROOT/lib/project-rules.sh" +pass=0; fail=0 +check() { if [ "$2" = "$3" ]; then pass=$((pass+1)); else fail=$((fail+1)); + printf 'FAIL %s: got[%s] want[%s]\n' "$1" "$2" "$3"; fi; } + +# rule_kind → path | always | bad +rule_kind() { + local fm + fm=$(_rules_frontmatter "$1") || { echo always; return; } + _rules_globs "$fm" >/dev/null + case $? in 0) echo path ;; 1) echo always ;; *) echo bad ;; esac +} +# always_on → the always-on rule file names, space-joined +always_on() { + local f out="" + for f in "$1"/*.md; do + [ "$(rule_kind "$f")" = always ] && out="$out ${f##*/}" + done + printf '%s\n' "${out# }" +} + +# ── flip controls: the checker bites (LRN-096) ── +FIX="$(mktemp -d)"; trap 'rm -rf "$FIX"' EXIT +printf -- '---\npaths: ["**/*.css"]\n---\n\n# A\n' > "$FIX/a.md" +printf '# B, always-on\n' > "$FIX/b.md" +printf -- '---\npaths:\n - "**/*.css"\n---\n\n# C\n' > "$FIX/c.md" +check F1-path-rule "$(rule_kind "$FIX/a.md")" path +check F2-no-frontmatter-always "$(rule_kind "$FIX/b.md")" always +check F3-multiline-paths-bad "$(rule_kind "$FIX/c.md")" bad +check F4-extra-always-on-seen "$(always_on "$FIX")" "b.md" +# the R2 lock itself bites on a dir whose always-on set differs +cp "$FIX/b.md" "$FIX/writing-style.md"; cp "$FIX/b.md" "$FIX/secure-by-default.md" +check F5-lock-bites "$([ "$(always_on "$FIX")" = "secure-by-default.md writing-style.md" ] && echo match || echo mismatch)" mismatch + +# ── the real rules ── +bad="" +for f in "$ROOT"/rules/*.md; do + [ "$(rule_kind "$f")" = bad ] && bad="$bad ${f##*/}" +done +check R1-every-frontmatter-parses "${bad# }" "" +check R2-always-on-set "$(always_on "$ROOT/rules")" "secure-by-default.md writing-style.md" +check R3-moved-rules-path "$(rule_kind "$ROOT/rules/supabase.md")/$(rule_kind "$ROOT/rules/cloud-functions.md")" path/path + +printf 'PASS=%s FAIL=%s\n' "$pass" "$fail"; [ "$fail" -eq 0 ] From 363fa90f8f5a49da1e1075244870f0019a712d04 Mon Sep 17 00:00:00 2001 From: bchanot Date: Thu, 29 Oct 2026 13:08:36 +0100 Subject: [PATCH 12/21] =?UTF-8?q?test(census):=20resolve=20rules/=20and=20?= =?UTF-8?q?lib/=20=C2=A7=20citations=20against=20their=20file?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- lib/tests/doctrine-citers.test.sh | 65 +++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) diff --git a/lib/tests/doctrine-citers.test.sh b/lib/tests/doctrine-citers.test.sh index 7281874..7ed785b 100644 --- a/lib/tests/doctrine-citers.test.sh +++ b/lib/tests/doctrine-citers.test.sh @@ -8,6 +8,9 @@ # Only citations that NAME the doctrine count: `CLAUDE.md "Section"` and # `CLAUDE.md … § Label`. Bare `section "…"` / `§ X` inside a skill refer to the # skill's own sections and are out of scope. +# Since BDR-125 phase 1 doctrine also lives in rules/ and lib/: a +# `rules/.md § Label` / `lib/.md § Label` citation resolves against +# that file (T4-T6). set -u ROOT="$(cd "$(dirname "$0")/../.." && pwd)" pass=0; fail=0 @@ -50,6 +53,35 @@ citers_check() { return $(( n > 99 ? 99 : n )) } +# _citers_extract_files … → "file:line:target:name" per citation of a +# heading in another doctrine file: `rules/.md § Label` or +# `lib/.md § Label`, backticks around the path and quotes around the +# label allowed. A quoted label runs to its closing quote (`—` included); an +# unquoted one ends at the first character that is not a letter, space or +# hyphen: quote a label that prose follows. A citation of +# `.claude/rules/.md § X` would be read as `rules/.md` (none exist; +# ERE has no lookbehind and the portability census bans grep -P). +_citers_extract_files() { + /usr/bin/grep -nHoE '(rules|lib)/[a-z0-9-]+\.md`? § ?"[^"]{2,60}"' "$@" 2>/dev/null \ + | sed -E 's/^([^:]+:[0-9]+):(.*\.md)`? § ?"([^"]+)"$/\1:\2:\3/' + /usr/bin/grep -nHoE '(rules|lib)/[a-z0-9-]+\.md`? § ?[A-Z][A-Za-z][A-Za-z -]{1,40}' "$@" 2>/dev/null \ + | sed -E 's/^([^:]+:[0-9]+):(.*\.md)`? § ?(.*)$/\1:\2:\3/; s/[[:space:]]+$//' +} + +# citers_check_files … → DANGLING lines; rc = their count (capped 99) +citers_check_files() { + local root="$1" line file lno target name n=0; shift + while IFS= read -r line; do + [ -n "$line" ] || continue + file="${line%%:*}"; lno="$(printf '%s' "$line" | cut -d: -f2)" + target="$(printf '%s' "$line" | cut -d: -f3)"; name="${line#*:*:*:}" + if [ ! -f "$root/$target" ] || ! _citers_resolve "$root/$target" "$name"; then + echo "DANGLING: $file:$lno → $target § \"$name\""; n=$((n+1)) + fi + done < <(_citers_extract_files "$@") + return $(( n > 99 ? 99 : n )) +} + # ── flip-test: a synthetic dangling citation must be caught ────────────────── FIX="$(mktemp -d)"; trap 'rm -rf "$FIX"' EXIT # shellcheck disable=SC2016 # literal backticks in the fixture heading @@ -65,6 +97,22 @@ out=$(citers_check "$FIX/doctrine.md" "$FIX/bad.md"); rc=$? check T2-dangling-section-and-label-caught "$rc" 2 check T2b-names-the-culprit "$(printf '%s\n' "$out" | grep -c 'bad.md:1')" 2 check T2c-label-named "$(printf '%s\n' "$out" | grep -c '"Language"')" 1 +mkdir -p "$FIX/rules" "$FIX/lib" +printf '## Versioning\nx\n' > "$FIX/rules/api.md" +printf '## WRITE (before the commit)\n' > "$FIX/lib/cc.md" +# shellcheck disable=SC2016 # literal backticks in the fixture +printf 'ok: see `rules/api.md` § Versioning, and lib/cc.md § WRITE (x)\n' > "$FIX/fgood.md" +printf 'quoted: rules/api.md § "Versioning" first\n' >> "$FIX/fgood.md" +printf '## Design work — full toolchain (tiered)\n' > "$FIX/rules/web.md" +printf 'dash: rules/web.md § "Design work — full toolchain" first\n' >> "$FIX/fgood.md" +printf 'bad: rules/api.md § "Version", rules/none.md § Alpha, lib/cc.md § Read\n' > "$FIX/fbad.md" +printf 'dash: rules/web.md § "Design work — full kit" first\n' >> "$FIX/fbad.md" +citers_check_files "$FIX" "$FIX/fgood.md" >/dev/null; check T4-file-citations-resolve "$?" 0 +out=$(citers_check_files "$FIX" "$FIX/fbad.md"); rc=$? +check T5-file-dangling-caught "$rc" 4 +check T5d-quoted-label-whole "$(printf '%s\n' "$out" | grep -c 'full kit')" 1 +check T5b-missing-file-named "$(printf '%s\n' "$out" | grep -c 'rules/none.md')" 1 +check T5c-prefix-not-a-heading "$(printf '%s\n' "$out" | grep -c '"Version"')" 1 # ── real census: the repo's own citers against CLAUDE.global.md ────────────── mapfile -t FILES < <(cd "$ROOT" && find skills agents lib rules hooks -type f \( -name '*.md' -o -name '*.sh' \) \ @@ -73,6 +121,23 @@ mapfile -t FILES < <(cd "$ROOT" && find skills agents lib rules hooks -type f \( out=$(cd "$ROOT" && citers_check CLAUDE.global.md "${FILES[@]}"); rc=$? [ -n "$out" ] && printf '%s\n' "$out" check T3-repo-citations-resolve "$rc" 0 +out=$(cd "$ROOT" && citers_check_files "$ROOT" "${FILES[@]}" CLAUDE.global.md); rc=$? +[ -n "$out" ] && printf '%s\n' "$out" +check T6-repo-file-citations-resolve "$rc" 0 +# T7: the real citers bite — the same two files against a copy of +# rules/rest-api.md whose heading is renamed (never edit the live rules/) +mkdir -p "$FIX/copy/rules" +cp "$ROOT/rules/rest-api.md" "$FIX/copy/rules/rest-api.md" +(cd "$ROOT" && citers_check_files "$FIX/copy" lib/architecture-defaults.md \ + lib/project-archetypes/rest-api-node.md) >/dev/null +check T7a-real-citers-control "$?" 0 +sed 's/^## Versioning$/## Version policy/' "$ROOT/rules/rest-api.md" > "$FIX/copy/rules/rest-api.md" +(cd "$ROOT" && citers_check_files "$FIX/copy" lib/architecture-defaults.md \ + lib/project-archetypes/rest-api-node.md) >/dev/null +check T7b-real-rename-bites "$?" 2 +# the hook's pointer is checked whole, not as its "Design work" prefix +check T7c-hook-label-whole "$(cd "$ROOT" && _citers_extract_files hooks/design-toolchain-reminder.sh \ + | grep -c ':rules/web-building.md:Design work — full toolchain$')" 2 echo "PASS=$pass FAIL=$fail" [ "$fail" -eq 0 ] From c4f3f0b17b1d2e7ca6b486921006ce54520e1587 Mon Sep 17 00:00:00 2001 From: bchanot Date: Thu, 29 Oct 2026 13:10:44 +0100 Subject: [PATCH 13/21] feat(memory): autoMemoryEnabled false; doctor warns on leftover auto-memory files --- doctor.sh | 26 ++++++++++++++++++++++++-- lib/doctor-automem.sh | 25 +++++++++++++++++++++++++ lib/tests/doctor-automem.test.sh | 30 ++++++++++++++++++++++++++++++ settings.json | 1 + 4 files changed, 80 insertions(+), 2 deletions(-) create mode 100755 lib/doctor-automem.sh create mode 100755 lib/tests/doctor-automem.test.sh diff --git a/doctor.sh b/doctor.sh index bd1c44b..12cc1da 100644 --- a/doctor.sh +++ b/doctor.sh @@ -26,6 +26,8 @@ source "$REPO/lib/gstack-playwright.sh" source "$REPO/lib/doctor-vendored.sh" # shellcheck source=lib/doctor-skills.sh disable=SC1091 source "$REPO/lib/doctor-skills.sh" +# shellcheck source=lib/doctor-automem.sh disable=SC1091 +source "$REPO/lib/doctor-automem.sh" # shellcheck source=lib/higgsfield-skills.sh disable=SC1091 source "$REPO/lib/higgsfield-skills.sh" @@ -37,8 +39,8 @@ echo "" # 1. Core symlinks # ──────────────────────────────────────────────────────────── echo "── Symlinks ──" -# Expected: CLAUDE.md, settings.json, agents, skills, templates, hooks/session-start.sh -_EXPECTED_LINKS=7 +# Expected: CLAUDE.md, settings.json, agents, skills, templates, lib, rules, hooks/session-start.sh +_EXPECTED_LINKS=8 _LINK_PASS=0 check_symlink() { @@ -87,6 +89,7 @@ check_symlink "agents" check_symlink "skills" check_symlink "templates" check_symlink "lib" +check_symlink "rules" check_symlink "hooks/session-start.sh" info "Symlinks: ${_LINK_PASS}/${_EXPECTED_LINKS} OK" unset _EXPECTED_LINKS _LINK_PASS @@ -472,6 +475,25 @@ fi unset _sp _sp_fs _sp_opts echo "" +# ──────────────────────────────────────────────────────────── +# 5d. Auto memory (BDR-125 phase 1): "autoMemoryEnabled": false, so a file +# left under ~/.claude/projects//memory/ is never loaded again. +# ──────────────────────────────────────────────────────────── +echo "── Auto memory ──" +if jq -e '.autoMemoryEnabled == false' "$REPO/settings.json" >/dev/null 2>&1; then + pass "settings.json: autoMemoryEnabled false" +else + warn "settings.json: autoMemoryEnabled is not false — the auto-memory section loads every session (BDR-125 phase 1)" +fi +_am=$(automem_leftover_dirs "$HOME/.claude/projects") +if [ "$_am" -gt 0 ]; then + warn "auto memory: $_am project dir(s) still hold files under ~/.claude/projects/*/memory/ (never loaded) — migrate them to the project registries, then remove them by hand" +else + pass "auto memory: no leftover file under ~/.claude/projects/*/memory/" +fi +unset _am +echo "" + # ──────────────────────────────────────────────────────────── # 6. Token budget estimate # ──────────────────────────────────────────────────────────── diff --git a/lib/doctor-automem.sh b/lib/doctor-automem.sh new file mode 100755 index 0000000..b515c53 --- /dev/null +++ b/lib/doctor-automem.sh @@ -0,0 +1,25 @@ +#!/usr/bin/env bash +# ============================================================ +# lib/doctor-automem.sh — doctor.sh's auto-memory leftover check +# +# settings.json sets "autoMemoryEnabled": false (BDR-125 phase 1): Claude +# Code no longer reads ~/.claude/projects//memory/, so a file left +# there is knowledge nobody loads. `automem_leftover_dirs ` +# prints how many /memory dirs hold at least one file and ALWAYS +# exits 0 (doctor.sh runs under `set -euo pipefail`; an absent dir is 0). +# +# No `set -euo pipefail` here: a sourced lib must not change the caller's +# shell options. +# ============================================================ + +# automem_leftover_dirs — see file header. +automem_leftover_dirs() { + local d n=0 + for d in "$1"/*/memory; do + [ -d "$d" ] || continue + if [ -n "$(find "$d" -type f -print -quit 2>/dev/null)" ]; then + n=$((n + 1)) + fi + done + echo "$n" +} diff --git a/lib/tests/doctor-automem.test.sh b/lib/tests/doctor-automem.test.sh new file mode 100755 index 0000000..73f8281 --- /dev/null +++ b/lib/tests/doctor-automem.test.sh @@ -0,0 +1,30 @@ +#!/usr/bin/env bash +# lib/tests/doctor-automem.test.sh — lib/doctor-automem.sh's +# automem_leftover_dirs(): absent dir, empty memory dirs, a file, a nested +# file, an empty subdir only, rc 0 under errexit (doctor.sh runs under +# `set -euo pipefail`) — BDR-125 phase 1. +set -u +ROOT="$(cd "$(dirname "$0")/../.." && pwd)" +LIB="$ROOT/lib/doctor-automem.sh" +# shellcheck source=../doctor-automem.sh disable=SC1091 +source "$LIB" +pass=0; fail=0 +check() { if [ "$2" = "$3" ]; then pass=$((pass+1)); else fail=$((fail+1)); + printf 'FAIL %s: got[%s] want[%s]\n' "$1" "$2" "$3"; fi; } +W="$(mktemp -d)"; trap 'rm -rf "$W"' EXIT + +check T1-absent-dir "$(automem_leftover_dirs "$W/nope")" 0 +mkdir -p "$W/p/-home-a/memory" "$W/p/-home-b/memory" +check T2-empty-dirs "$(automem_leftover_dirs "$W/p")" 0 +echo x > "$W/p/-home-a/memory/MEMORY.md" +check T3-one-file "$(automem_leftover_dirs "$W/p")" 1 +mkdir -p "$W/p/-home-b/memory/sub"; echo y > "$W/p/-home-b/memory/sub/note.md" +check T4-nested-file-counts "$(automem_leftover_dirs "$W/p")" 2 +mkdir -p "$W/p/-home-c/memory/empty-sub" +check T5-empty-subdir-silent "$(automem_leftover_dirs "$W/p")" 2 +check T6-rc0-under-errexit "$(bash -c 'set -euo pipefail; source "$1"; automem_leftover_dirs "$2" >/dev/null; echo "rc$?"' _ "$LIB" "$W/nope")" rc0 +# doctor.sh calls it on "$HOME/.claude/projects": the same call under a temp HOME +mkdir -p "$W/h/.claude/projects/-home-x/memory"; echo z > "$W/h/.claude/projects/-home-x/memory/a.md" +check T7-via-temp-home "$(HOME="$W/h" bash -c 'source "$1"; automem_leftover_dirs "$HOME/.claude/projects"' _ "$LIB")" 1 + +printf 'PASS=%s FAIL=%s\n' "$pass" "$fail"; [ "$fail" -eq 0 ] diff --git a/settings.json b/settings.json index d8e9806..2ef0acd 100644 --- a/settings.json +++ b/settings.json @@ -489,6 +489,7 @@ }, "feedbackDrafts": "off", "effortLevel": "high", + "autoMemoryEnabled": false, "remoteControlAtStartup": true, "inputNeededNotifEnabled": true, "skipAutoPermissionPrompt": true, From 22cfcd910b671aecc8d6f3550a3f85edd656ac42 Mon Sep 17 00:00:00 2001 From: bchanot Date: Thu, 29 Oct 2026 13:13:20 +0100 Subject: [PATCH 14/21] =?UTF-8?q?chore(agents):=20descriptions=20trimmed?= =?UTF-8?q?=20to=20=E2=89=A4=20200=20chars=20at=20the=20source?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- agents/bugfixer.md | 2 +- agents/client-handover-writer.md | 2 +- agents/code-cleaner.md | 2 +- agents/doc-syncer.md | 2 +- agents/geo-analyzer.md | 2 +- agents/handover-doc-writer.md | 2 +- agents/onboarder.md | 2 +- agents/plan-challenger.md | 2 +- agents/plugin-advisor.md | 2 +- agents/security-auditor.md | 2 +- agents/seo-analyzer.md | 2 +- agents/validator-analyzer.md | 2 +- agents/verifier.md | 2 +- 13 files changed, 13 insertions(+), 13 deletions(-) diff --git a/agents/bugfixer.md b/agents/bugfixer.md index 412725c..904ac5a 100644 --- a/agents/bugfixer.md +++ b/agents/bugfixer.md @@ -1,6 +1,6 @@ --- name: bugfixer -description: Bug-fix EXECUTOR — dispatched by /bugfix (or /guardrails and /a11y for accepted fixes) with a closed DIAGNOSIS + FIX PLAN + contract. Applies the fix and a regression test, runs the suite, reports. No investigation, no questions, no commit. +description: Bug-fix EXECUTOR dispatched by /bugfix (or /guardrails, /a11y) with a closed DIAGNOSIS + FIX PLAN + contract. Applies the fix and a regression test, runs the suite. No investigation, no commit. tools: Read, Edit, Write, Bash, Grep, Glob model: sonnet effort: medium diff --git a/agents/client-handover-writer.md b/agents/client-handover-writer.md index 80948b3..7d7df18 100644 --- a/agents/client-handover-writer.md +++ b/agents/client-handover-writer.md @@ -1,6 +1,6 @@ --- name: client-handover-writer -description: Final ship-and-handover orchestrator — called by /client-handover. Runs the audit/fix/gate pipeline (SEO+GEO+HARDEN to ≥17/20, live VALIDATE) inline on the big session model with fable-pinned skill-runner children, then delegates the client deliverable to the two-mode handover-doc-writer (synthesize opus / render sonnet — BDR-077). +description: Final ship-and-handover orchestrator called by /client-handover. Audit/fix/gate pipeline (SEO+GEO+HARDEN to ≥17/20, live VALIDATE), then the client deliverable via handover-doc-writer. tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch, AskUserQuestion, Agent --- diff --git a/agents/code-cleaner.md b/agents/code-cleaner.md index 6c32af2..daec552 100644 --- a/agents/code-cleaner.md +++ b/agents/code-cleaner.md @@ -1,6 +1,6 @@ --- name: code-cleaner -description: Cleanup EXECUTOR (PHASE 2) — dispatched by /code-clean with an APPROVED scope. Deletes approved dead code, hands style/structural items to the refactorer, re-audits. Zero behavior change. No audit, no questions, no commit. +description: Cleanup EXECUTOR (PHASE 2) dispatched by /code-clean with an APPROVED scope. Deletes approved dead code, hands style items to the refactorer, re-audits. Zero behavior change, no commit. tools: Read, Edit, Write, Bash, Grep, Glob model: sonnet effort: medium diff --git a/agents/doc-syncer.md b/agents/doc-syncer.md index 7fbaaaf..fab4357 100644 --- a/agents/doc-syncer.md +++ b/agents/doc-syncer.md @@ -1,6 +1,6 @@ --- name: doc-syncer -description: 'Two-mode public-doc sync agent — MODE: audit (dispatched model="opus" — drift detection, semantic analysis, drafts, PATCH PLAN, read-only) and MODE: patch (sonnet pin — applies the APPROVED plan, oracle-checked, emits CHANGE SUMMARY + PATCHED_FILES). The validation gate lives in the DISPATCHER (BDR-077). Convention-aware (Diátaxis, Keep a Changelog); never touches .claude/.' +description: 'Two-mode public-doc sync agent. MODE: audit (opus, read-only: drift, drafts, PATCH PLAN); MODE: patch (sonnet: applies the approved plan, emits PATCHED_FILES). Never touches .claude/.' tools: Read, Write, Edit, Bash, Grep, Glob model: sonnet effort: high diff --git a/agents/geo-analyzer.md b/agents/geo-analyzer.md index 77d845b..c4d84f0 100644 --- a/agents/geo-analyzer.md +++ b/agents/geo-analyzer.md @@ -1,6 +1,6 @@ --- name: geo-analyzer -description: GEO audit agent for AI search engines — dispatched by /geo and /seo. Audits AI crawlers, llms.txt, entity signals, Schema.org; emits a fix bundle (dispatcher applies), scored report. Classical SEO → seo-analyzer agent. +description: GEO audit agent for AI search engines, dispatched by /geo and /seo. AI crawlers, llms.txt, entity signals, Schema.org; emits a fix bundle and a scored report. Classical SEO → seo-analyzer. tools: Read, Edit, Write, Bash, Grep, Glob, WebFetch, WebSearch model: opus effort: xhigh diff --git a/agents/handover-doc-writer.md b/agents/handover-doc-writer.md index b2b0e79..2c981d0 100644 --- a/agents/handover-doc-writer.md +++ b/agents/handover-doc-writer.md @@ -1,6 +1,6 @@ --- name: handover-doc-writer -description: 'Two-mode deliverable writer — MODE: synthesize (dispatched model="opus" — memory+git clustering, 6-chapter synthesis into a run-scoped draft) and MODE: render (sonnet pin — annexes, precheck, deterministic gates, MD + branded HTML/PDF from the draft). Dispatched twice by client-handover with the resolved PACKAGE. No audits, no questions, no dispatch.' +description: 'Two-mode client deliverable writer, dispatched twice by client-handover. MODE: synthesize (opus: memory + git, 6-chapter draft); MODE: render (sonnet: annexes, gates, MD + HTML/PDF).' tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch model: sonnet effort: high diff --git a/agents/onboarder.md b/agents/onboarder.md index 10e0405..3ed09c6 100644 --- a/agents/onboarder.md +++ b/agents/onboarder.md @@ -1,6 +1,6 @@ --- name: onboarder -description: Generate claude-config files (CLAUDE.md, settings.json, .claudeignore, .gitignore safety, .claude/tasks/ + .claude/memory/ + .claude/audits/) for an existing project. Pure config generator — no interview, no audit. Called by /onboard orchestrator. +description: Generate claude-config files (CLAUDE.md, settings.json, .claudeignore, .gitignore safety, .claude/{tasks,memory,audits}/) for an existing project. No interview, no audit. Called by /onboard. tools: Read, Write, Edit, Bash, Glob, Grep model: sonnet effort: medium diff --git a/agents/plan-challenger.md b/agents/plan-challenger.md index a969cad..5a481be 100644 --- a/agents/plan-challenger.md +++ b/agents/plan-challenger.md @@ -1,6 +1,6 @@ --- name: plan-challenger -description: Fresh independent plan challenger — reads a PLAN file from disk and adversarially attacks it through ONE assigned lens (correctness | robustness | simplicity), then renders structured findings + a verdict. Report-only, never fixes, never implements. Dispatched fresh; blind to the other lenses. +description: Fresh plan challenger. Reads a PLAN file and attacks it through ONE lens (correctness | robustness | simplicity), then renders findings + a verdict. Report-only, blind to the other lenses. tools: Read, Grep, Glob, Bash model: opus effort: xhigh diff --git a/agents/plugin-advisor.md b/agents/plugin-advisor.md index 4ec48f9..4e1aa2e 100644 --- a/agents/plugin-advisor.md +++ b/agents/plugin-advisor.md @@ -1,6 +1,6 @@ --- name: plugin-advisor -description: Plugin-fit REASONER — dispatched by lib/plugin-gate.md with a PROBE REPORT (from plugin-probe). Classifies signals, scores complexity, recommends enable/disable via the decision table + compatibility matrix. Report-only. +description: Plugin-fit REASONER dispatched by lib/plugin-gate.md with a PROBE REPORT from plugin-probe. Classifies signals, scores complexity, recommends enable/disable. Report-only. tools: Read, Glob, Grep model: opus effort: xhigh diff --git a/agents/security-auditor.md b/agents/security-auditor.md index ef9080d..965a094 100644 --- a/agents/security-auditor.md +++ b/agents/security-auditor.md @@ -1,6 +1,6 @@ --- name: security-auditor -description: 'SAST security gate — runs the pinned semgrep rulesets + the CLAUDE.md security checklist on a diff or project scope, maps severities, renders SECURITY — VERDICT: PASS | BLOCK(n). Blocks HIGH/CRITICAL only, reports the rest. Never fixes code. Fresh dispatch, no iteration history.' +description: 'SAST security gate: pinned semgrep rulesets + the CLAUDE.md security checklist on a diff or scope. VERDICT: PASS | BLOCK(n), blocks HIGH/CRITICAL only. Never fixes code. Fresh dispatch.' tools: Read, Grep, Glob, Bash, Write model: opus effort: xhigh diff --git a/agents/seo-analyzer.md b/agents/seo-analyzer.md index f6a3b91..0281e93 100644 --- a/agents/seo-analyzer.md +++ b/agents/seo-analyzer.md @@ -1,6 +1,6 @@ --- name: seo-analyzer -description: 'Classical SEO audit agent (Google, Bing) — dispatched from /seo. Live audit: Core Web Vitals, on-page, technical, local SEO, legal (FR). Emits a fix bundle (dispatcher applies) + scored report. AI/GEO → geo-analyzer agent.' +description: 'Classical SEO audit agent (Google, Bing), dispatched from /seo: Core Web Vitals, on-page, technical, local SEO, legal (FR). Emits a fix bundle + scored report. AI/GEO → geo-analyzer.' tools: Read, Edit, Write, Bash, Grep, Glob, WebFetch, WebSearch model: opus effort: xhigh diff --git a/agents/validator-analyzer.md b/agents/validator-analyzer.md index 3156755..d1fa128 100644 --- a/agents/validator-analyzer.md +++ b/agents/validator-analyzer.md @@ -1,6 +1,6 @@ --- name: validator-analyzer -description: Web standards audit agent — W3C HTML validity (validator.nu), W3C CSS validity (jigsaw.w3.org), WCAG 2.1 accessibility (axe-core, pa11y, WAVE). Dispatched from /web-validate. Produces scored .claude/audits/VALIDATE.md report with concrete diffs for auto-fixable issues and user actions for judgment-required fixes. Complementary to /harden (security), /seo (indexability), /geo (AI extraction). +description: Web standards audit agent, dispatched from /web-validate. W3C HTML/CSS validity and WCAG 2.1 (axe-core, pa11y, WAVE); scored .claude/audits/VALIDATE.md with fix diffs and user actions. tools: Read, Edit, Write, Bash, Grep, Glob, WebFetch model: sonnet effort: low diff --git a/agents/verifier.md b/agents/verifier.md index 6a1205f..7223721 100644 --- a/agents/verifier.md +++ b/agents/verifier.md @@ -1,6 +1,6 @@ --- name: verifier -description: Fresh independent verifier — reads a CONTRACT file from disk and renders a structured verdict (CONFORME / ECARTS / ERROR) on the implemented diff. Report-only, never fixes. Dispatched fresh at every iteration; receives no iteration history. +description: Fresh independent verifier. Reads a CONTRACT file from disk and renders CONFORME / ECARTS / ERROR on the implemented diff. Report-only, never fixes; dispatched with no iteration history. tools: Read, Grep, Glob, Bash model: opus effort: xhigh From ce7d426fc7c2dfc2e5255873e3c3fd89ddd05901 Mon Sep 17 00:00:00 2001 From: bchanot Date: Thu, 29 Oct 2026 13:27:41 +0100 Subject: [PATCH 15/21] chore(contract): analyzer memory ruling (gated) --- .claude/tasks/contracts/2026-10-28-context-diet-1944.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.claude/tasks/contracts/2026-10-28-context-diet-1944.md b/.claude/tasks/contracts/2026-10-28-context-diet-1944.md index e834bd9..41f7eb3 100644 --- a/.claude/tasks/contracts/2026-10-28-context-diet-1944.md +++ b/.claude/tasks/contracts/2026-10-28-context-diet-1944.md @@ -15,6 +15,8 @@ Q: Neighbouring defects in scope? / A: all three in: (a) design-toolchain test F Q: STEP 3 gate (plan r3, 0441e56)? / A: plan approved; robin_petier entry text approved as shown (robin_petier = finished project, serves as the test case of the auto-memory → registry migration; faunosteo and game (orbistep) are the critical ones: the proof states explicitly that nothing of theirs is lost); settings.json: never commit a `/model` write, the tracked default stays `"model": "opus"`, `"switchModelsOnFlag": true` stays; UI-written changes (`"theme"`) are stashed, never committed, re-pushed only for a major change; Skill-routing lines → skill descriptions (TODO phase 3 bullet) DEFERRED to a TODO line; contract amendments below accepted. [gated 2026-10-29] +Q: `autoMemoryEnabled: false` also drops the analyzer's `memory: project` section (proved 2026-10-29 with a control run `--settings '{"autoMemoryEnabled": true}'`: YES vs NO); the 4 `.claude/agent-memory/analyzer/` dirs are empty. Keep false? / A: keep false + record a BDR; removing the dead `memory: project` field from agents/analyzer.md = TODO line. [gated 2026-10-29] + ## ACCEPTANCE CRITERIA 1. settings.json carries `"autoMemoryEnabled": false`. CHECK: jq -e '.autoMemoryEnabled == false' settings.json >/dev/null && echo AUTOMEM-OFF From 1c14e31db99efa12fa97b148c12978c325a3f459 Mon Sep 17 00:00:00 2001 From: bchanot Date: Thu, 29 Oct 2026 13:30:14 +0100 Subject: [PATCH 16/21] chore(contract): phase 1 controller proofs + GATE 0 evidence --- .../contracts/2026-10-28-context-diet-1944.md | 27 ++++++++++++------- 1 file changed, 17 insertions(+), 10 deletions(-) diff --git a/.claude/tasks/contracts/2026-10-28-context-diet-1944.md b/.claude/tasks/contracts/2026-10-28-context-diet-1944.md index 41f7eb3..afa7cc7 100644 --- a/.claude/tasks/contracts/2026-10-28-context-diet-1944.md +++ b/.claude/tasks/contracts/2026-10-28-context-diet-1944.md @@ -21,55 +21,62 @@ Q: `autoMemoryEnabled: false` also drops the analyzer's `memory: project` sectio 1. settings.json carries `"autoMemoryEnabled": false`. CHECK: jq -e '.autoMemoryEnabled == false' settings.json >/dev/null && echo AUTOMEM-OFF EXPECT: AUTOMEM-OFF - EVIDENCE: pending + EVIDENCE: MET exit=0 marker-found :: AUTOMEM-OFF 2. robin_petier's registry holds exactly one new entry for the LAN dev server rule, written by `lib/memory.sh -C ~/Documents/robin_petier add`, on a `chore/*` branch of that repo, with the text the user approved; no other project's `.claude/memory/` changes. 3. doctor warns when any `~/.claude/projects/*/memory/` dir holds a file, names how many dirs, and stays silent when all are empty (flip-tested in a suite with a temp HOME). [gated 2026-10-29] amended: doctor prints a warn line naming the count when a dir holds a file, a pass line otherwise; the proof is the function-level suite (lib/tests/doctor-automem.test.sh) including a call through a temp HOME; doctor also checks the `~/.claude/rules` symlink and that settings.json `autoMemoryEnabled` is false. 4. CLAUDE.global.md has no `## Design work` heading; rules/web-building.md ends with the section `## Design work — full toolchain (tiered by scope)`, body identical to the CLAUDE.global.md section at develop 017a28b (internal pointers excepted, listed in the plan); web-building.md `paths:` unchanged. CHECK: bash .claude/tasks/contracts/c1-design-moved.sh EXPECT: DESIGN-MOVED - EVIDENCE: pending + EVIDENCE: MET exit=0 marker-found :: DESIGN-MOVED 5. hooks/design-toolchain-reminder.sh prints a one-liner that names `~/.claude/rules/web-building.md` and the heading fragment `full toolchain`, and no longer says "already in context"; its suite asserts the exact new line. 6. The design hook stays quiet on a prompt starting with `/dev/null 2>&1 || exit 1; b=$(wc -l < "$L"); [ "$a" = "$b" ] && echo LOG-UNTOUCHED EXPECT: LOG-UNTOUCHED - EVIDENCE: pending + EVIDENCE: MET exit=0 marker-found :: LOG-UNTOUCHED 8. [gated 2026-10-29] amended: `## graphify` keeps the threshold rule plus ONE reminder clause (`graphify query` before raw grep, `graphify update .` after code edits; sub-agents never see the banner); the full usage body moves as below. Original: CLAUDE.global.md `## graphify` keeps only the threshold rule; the usage body (query/path/explain, wiki/GRAPH_REPORT, `graphify update .`) is printed by hooks/session-start.sh only when the repo root holds `graphify-out/graph.json`; a suite proves present-with-graph and absent-without (flip). 9. lib/architecture-defaults.md exists and holds the "Public websites — never SPA" text and the "Default language — Rust" text (wording identical to their sources at 017a28b, pointers excepted) plus the Web APIs rule or a pointer to rules/rest-api.md § Versioning; CLAUDE.global.md has no `## Public websites` and no `## Web APIs` heading and holds one always-on line naming Rust default, never SPA, `/api/v1` and the lib path; rules/default-language.md no longer exists. CHECK: bash .claude/tasks/contracts/c1-arch-moved.sh EXPECT: ARCH-MOVED - EVIDENCE: pending + EVIDENCE: MET exit=0 marker-found :: ARCH-MOVED 10. Readers name the lib: skills/init-project/SKILL.md, skills/ship-feature/SKILL.md (STEP 1), skills/onboard/SKILL.md, agents/interviewer.md, agents/scaffolder.md, skills/audit-delta/SKILL.md; no tracked file under skills/ agents/ lib/ hooks/ rules/ templates/ nor CLAUDE.global.md cites `default-language.md`. CHECK: bash .claude/tasks/contracts/c1-readers.sh EXPECT: READERS-OK - EVIDENCE: pending + EVIDENCE: MET exit=0 marker-found :: READERS-OK 11. rules/rest-api.md `## Versioning` carries the full versioning rule (text of CLAUDE.global.md § Web APIs at 017a28b), no "Not repeated here"; lib/project-archetypes/rest-api-node.md cites rules/rest-api.md instead of CLAUDE.md "Web APIs — always versioned". 12. rules/supabase.md and rules/cloud-functions.md exist with the clarified one-line JSON `paths:` and the bullets of secure-by-default.md §4 / §6 at 017a28b, wording identical; secure-by-default.md keeps the `## 4. Supabase` and `## 6. Cloud functions` headings with one line each naming the critical rule and the path rule. CHECK: bash .claude/tasks/contracts/c1-supabase-functions.sh EXPECT: SB-CF-MOVED - EVIDENCE: pending + EVIDENCE: MET exit=0 marker-found :: SB-CF-MOVED 13. A make-test suite parses every rules/*.md frontmatter (one-line JSON `paths:` or none) and locks the always-on set to exactly writing-style.md + secure-by-default.md; positive control: a multi-line `paths:` fixture and an extra always-on fixture both fail it. 14. lib/project-rules.sh header comment states the observed engine matching (trailing `/**` dropped, a pattern matches at any depth, hidden dirs included, evidence: InstructionsLoaded `globs: ["rules"]` on `.claude/rules/*.md`) instead of "the engine's matcher skips" dotfiles; code behaviour unchanged. 15. Load proof (controller, journaled): one fresh headless session per moved path rule, each prompt naming the Read tool on a real file, logs `path_glob_match` for rules/supabase.md (faunosteo), rules/cloud-functions.md (game, supabase/functions), rules/web-building.md (a UI file); and `bash lib/project-rules.sh -C matches ''` per new glob in the project that holds it (a glob that matches nowhere is named in the journal). 16. Every tracked agents/*.md `description:` (the 4 vendored impeccable-* excepted) is ≤ the length settled at the plan gate; agent names, files and `model:` lines unchanged. CHECK: bash .claude/tasks/contracts/c1-agent-desc.sh EXPECT: AGENT-DESC-OK - EVIDENCE: pending + EVIDENCE: MET exit=0 marker-found :: AGENT-DESC-OK (23 agents) 17. Citers patched in the same branch: CLAUDE.global.md Skill routing (Design / UI line, Higgsfield line), lib/design-gate.md, agents/seo-analyzer.md, .claude/rules/rules-maintenance.md (always-on exception list and the "always-on doctrine stays in CLAUDE.global.md" sentence), hooks/session-start.sh comments citing BDR-031 / the moved sections; doctrine-citers census green. 18. CLAUDE.global.md is ≤ 320 lines (the session banner density warning goes away). CHECK: n=$(wc -l < CLAUDE.global.md); [ "$n" -le 320 ] && echo GLOBAL-UNDER-320 EXPECT: GLOBAL-UNDER-320 - EVIDENCE: pending + EVIDENCE: MET exit=0 marker-found :: GLOBAL-UNDER-320 19. `/context` after (controller, `claude -p "/context"` at repo root, journaled with the baseline 2026-10-28: total 30.5k, Memory files 9.6k with user CLAUDE.md 7.4k / default-language 409 / secure-by-default 1.2k, Custom agents 2.6k, System prompt 4.4k): Memory files and Custom agents both lower, rules/default-language.md absent from the Memory files table. 20. make test all green and shellcheck clean. CHECK: make test 2>&1 | tail -1 EXPECT: all suites green - EVIDENCE: pending + EVIDENCE: MET exit=0 marker-found :: all suites green 21. shellcheck clean on the health stack. CHECK: shellcheck *.sh hooks/*.sh lib/*.sh && echo SHELLCHECK-CLEAN EXPECT: SHELLCHECK-CLEAN - EVIDENCE: pending + EVIDENCE: MET exit=0 marker-found :: SHELLCHECK-CLEAN ## FILE SCOPE CLAUDE.global.md, settings.json, rules/web-building.md, rules/rest-api.md, rules/secure-by-default.md, rules/default-language.md (deleted), rules/supabase.md (new), rules/cloud-functions.md (new), lib/architecture-defaults.md (new), hooks/design-toolchain-reminder.sh, lib/tests/design-toolchain-reminder.test.sh, hooks/session-start.sh, lib/graphify-gate.sh (only if the graph-present branch needs it), a session-start graphify suite (new), doctor.sh + one lib/doctor-*.sh + its suite (new), lib/tests/ user-rules suite (new) + fixtures, lib/tests/graphify-gate.test.sh (the session-start graphify checks live there) [gated 2026-10-29], lib/tests/effort-routing.test.sh (one lock retargeted) [gated 2026-10-29], lib/tests/doctrine-citers.test.sh (census extension) [gated 2026-10-29], skills/guardrails/SKILL.md (citer) [gated 2026-10-29], .claude/tasks/contracts/2026-10-28-context-diet-1944.md + c1-*.sh [gated 2026-10-29], .claude/tasks/TODO.md [gated 2026-10-29], lib/project-rules.sh (comment only), agents/*.md (23 tracked, `description:` only), skills/init-project/SKILL.md, skills/ship-feature/SKILL.md, skills/onboard/SKILL.md, skills/audit-delta/SKILL.md, agents/interviewer.md, agents/scaffolder.md, agents/seo-analyzer.md, lib/design-gate.md, lib/project-archetypes/rest-api-node.md, .claude/rules/rules-maintenance.md, .claude/tasks/contracts/c1-*.sh (oracles), robin_petier `.claude/memory/` (one entry, its own chore/* branch), docs at STEP 8. + +## PROOF — controller, 2026-10-29 +- c2 (robin_petier): `chore/memory-lan-server` started by `gitflow.sh start`, `memory.sh -C ~/Documents/robin_petier add decision --status accepted` → BDR-075 (v1 registry, stderr note), memory commit d16cd6e via memory-commit.sh rc 0, pushed; `git -C ~/Documents/{faunosteo,game} status --short` empty. Critical projects: faunosteo's only auto memory (dev-host-no-docker-access) already lives in its blockers.md (docker.sock BLK, resolved 2026-10-08); game's auto-memory dir is empty; jeux-deploy's (remote-git-ops) dropped by the pass-A answer (contradicts the gitflow delete doctrine). Nothing of faunosteo/game is lost. +- c15 static: `project-rules.sh -C matches`: faunosteo `**/supabase/**` → packages/supabase, `**/*supabase*.*` → apps/app/src/lib/supabase.ts; game `**/supabase/**` → supabase, `**/*supabase*.*` → apps/web/src/progress/supabase.ts, `**/functions/**` → supabase/functions; robin_petier and zenquality: all five globs match nothing (no Supabase text loads there); `**/serverless.*` and `**/firebase.json` match nowhere in the four projects. +- c15 load (`~/.claude/logs/instructions-loaded.jsonl`, headless `claude -p` naming the Read tool): 2026-10-29T12:14:26Z faunosteo `supabase.md` User path_glob_match on packages/supabase/package.json (globs logged `**/supabase,**/*supabase*.*`), `web-building.md` User on apps/app/e2e/harness/dialog.tsx; 12:14:36Z game `cloud-functions.md` + `supabase.md` User on supabase/functions/_shared/core.mjs (globs `**/functions,…`). Both repos clean after. +- c19 `/context` after (repo root, headless): total 30.5k → 26.2k; Memory files 9.6k → 8.0k (user CLAUDE.md 7.4k → 6.3k, secure-by-default 1.2k → 985, default-language row gone); System prompt 4.4k → 3.7k (auto-memory section); Custom agents 2.6k → 2.1k. MCP server instructions 2.4k → 945 is NOT this branch (claude.ai connector set changed between the runs): own gain ≈ −2.8k. +- analyzer `memory: project`: dropped by `autoMemoryEnabled: false` (control `--settings '{"autoMemoryEnabled": true}'` → section present); dirs empty; user kept false [gated 2026-10-29]. From 789a2b202787db86e2a53905c1c21dd8bf41cb28 Mon Sep 17 00:00:00 2001 From: bchanot Date: Thu, 29 Oct 2026 13:51:53 +0100 Subject: [PATCH 17/21] =?UTF-8?q?fix(doctrine):=20final-review=20wave=20?= =?UTF-8?q?=E2=80=94=20Supabase/functions=20pointers=20say=20Read=20before?= =?UTF-8?q?=20a=20new=20file,=20graphify/API/ship-feature=20wording?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CLAUDE.global.md | 5 +++-- hooks/session-start.sh | 2 +- lib/architecture-defaults.md | 6 +++--- rules/secure-by-default.md | 10 ++++++---- skills/ship-feature/SKILL.md | 5 +++-- 5 files changed, 16 insertions(+), 12 deletions(-) diff --git a/CLAUDE.global.md b/CLAUDE.global.md index ae7f491..492ae5e 100644 --- a/CLAUDE.global.md +++ b/CLAUDE.global.md @@ -284,5 +284,6 @@ office-hours…) are gone: use the fallback above, else say so. Threshold: graphify from 200 tracked code files, never below (banner line `graphify? N code files ≥ 200, no graph` informs, the user decides; never build or `graphify claude install` without that go). With a graph -(`graphify-out/graph.json`): `graphify query` before raw grep, -`graphify update .` after code edits; the session banner prints the rest. +(`graphify-out/graph.json`): `graphify query` before raw grep on +codebase-wide questions, `graphify update .` after code edits; the session +banner prints the rest. diff --git a/hooks/session-start.sh b/hooks/session-start.sh index b81d262..9cbcdac 100644 --- a/hooks/session-start.sh +++ b/hooks/session-start.sh @@ -256,7 +256,7 @@ if [ -n "$GRAPHIFY_HINT" ]; then fi # CLAUDE.global.md line-count guard (anti-regression, BDR-062): warn past # 320. BDR-125 phase 1 moved Design work, the graphify usage and the -# architecture defaults to their carriers (333 → ~285 lines). +# architecture defaults to their carriers. if [ -n "$REPO_DIR" ] && [ -f "$REPO_DIR/CLAUDE.global.md" ]; then _claude_lines=$(wc -l < "$REPO_DIR/CLAUDE.global.md") if [ "$_claude_lines" -gt 320 ]; then diff --git a/lib/architecture-defaults.md b/lib/architecture-defaults.md index 5866d39..39c712c 100644 --- a/lib/architecture-defaults.md +++ b/lib/architecture-defaults.md @@ -44,6 +44,6 @@ CLI, systems and tooling; the exception stays scoped to the part that earned it. ## Web APIs — always versioned -Every endpoint `/api/v1/...` from day one; breaking change → `v2`, the old -version keeps working. Full rule: `~/.claude/rules/rest-api.md` § Versioning -(loads on API files). +Every endpoint `/api/v1/...` from day one, the router mirrors it +(`api/v1/routes/`); breaking change → `v2`, the old version keeps working. +Full rule: `~/.claude/rules/rest-api.md` § Versioning (loads on API files). diff --git a/rules/secure-by-default.md b/rules/secure-by-default.md index d31753b..1392443 100644 --- a/rules/secure-by-default.md +++ b/rules/secure-by-default.md @@ -39,8 +39,9 @@ never claimed done: write it as a manual step in the project's deploy notes. comments carry no token, hash, key or secret. ## 4. Supabase -- RLS on every table, never a service_role or secret key client-side. Full - domain: rules/supabase.md (loads on Supabase files). +- RLS on every table, never a service_role or secret key client-side. + Full domain: ~/.claude/rules/supabase.md; Read it before writing a + migration, policy or client (a new file's Write loads no path rule). ## 5. SMS and email - Prior consent recorded per contact: who, when, channel, source, wording. @@ -49,5 +50,6 @@ never claimed done: write it as a manual step in the project's deploy notes. SMS says STOP, and a STOP reply is processed and stored automatically. ## 6. Cloud functions -- Max instances and a timeout on every function, never a self-trigger. Full - domain: rules/cloud-functions.md (loads on function files). +- Max instances and a timeout on every function, never a self-trigger. + Full domain: ~/.claude/rules/cloud-functions.md; Read it before + writing a function (a new file's Write loads no path rule). diff --git a/skills/ship-feature/SKILL.md b/skills/ship-feature/SKILL.md index 850bee4..f0cef63 100644 --- a/skills/ship-feature/SKILL.md +++ b/skills/ship-feature/SKILL.md @@ -111,8 +111,9 @@ not the raw request alone: Brainstorm WITHIN these — don't re-explore a direction an in-force BDR rejects or a BLK already closed." When the feature picks a language, a framework or an API shape, Read -`~/.claude/lib/architecture-defaults.md` first and add its defaults to the -in-force constraints. +`~/.claude/lib/architecture-defaults.md` first and add to the in-force +constraints the defaults whose Scope applies (an existing codebase keeps its +language). Inject ONLY what constrains: the NON-BINDING count does NOT enter the brainstorm input (the injection inherits the OUTPUT filter — detail what binds, drop what doesn't). Consumption = INPUT INJECTION (we can't modify the external skill; we control its input). From a29b6d5871b12cfe04ecb027c7480f9fc621865d Mon Sep 17 00:00:00 2001 From: bchanot Date: Thu, 29 Oct 2026 14:20:39 +0100 Subject: [PATCH 18/21] chore(contract): GATE 1 human micro-gate answers --- .claude/tasks/contracts/2026-10-28-context-diet-1944.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.claude/tasks/contracts/2026-10-28-context-diet-1944.md b/.claude/tasks/contracts/2026-10-28-context-diet-1944.md index afa7cc7..cfdaa53 100644 --- a/.claude/tasks/contracts/2026-10-28-context-diet-1944.md +++ b/.claude/tasks/contracts/2026-10-28-context-diet-1944.md @@ -17,6 +17,8 @@ Q: STEP 3 gate (plan r3, 0441e56)? / A: plan approved; robin_petier entry text a Q: `autoMemoryEnabled: false` also drops the analyzer's `memory: project` section (proved 2026-10-29 with a control run `--settings '{"autoMemoryEnabled": true}'`: YES vs NO); the 4 `.claude/agent-memory/analyzer/` dirs are empty. Keep false? / A: keep false + record a BDR; removing the dead `memory: project` field from agents/analyzer.md = TODO line. [gated 2026-10-29] +Q: GATE 1 ECARTS(5), human-only points: (1) robin_petier BDR-075 = the text approved at the STEP 3 gate? (2) docs/superpowers/specs/2026-10-29-context-diet-design.md and docs/superpowers/plans/2026-10-29-context-diet.md in FILE SCOPE? (3) authorize two `# shellcheck disable=SC2016 # literal backticks in the fixture` (lib/tests/doctrine-citers.test.sh fixture printf, same waiver as the file's existing line; and the plan doc that quotes it)? / A: yes to all three: BDR-075 is the approved text (byte-identical to the gate text); the two transient pipeline docs join FILE SCOPE (purged by gitflow finish, BDR-065); both SC2016 waivers authorized. [gated 2026-10-29] + ## ACCEPTANCE CRITERIA 1. settings.json carries `"autoMemoryEnabled": false`. CHECK: jq -e '.autoMemoryEnabled == false' settings.json >/dev/null && echo AUTOMEM-OFF @@ -72,7 +74,7 @@ Q: `autoMemoryEnabled: false` also drops the analyzer's `memory: project` sectio EVIDENCE: MET exit=0 marker-found :: SHELLCHECK-CLEAN ## FILE SCOPE -CLAUDE.global.md, settings.json, rules/web-building.md, rules/rest-api.md, rules/secure-by-default.md, rules/default-language.md (deleted), rules/supabase.md (new), rules/cloud-functions.md (new), lib/architecture-defaults.md (new), hooks/design-toolchain-reminder.sh, lib/tests/design-toolchain-reminder.test.sh, hooks/session-start.sh, lib/graphify-gate.sh (only if the graph-present branch needs it), a session-start graphify suite (new), doctor.sh + one lib/doctor-*.sh + its suite (new), lib/tests/ user-rules suite (new) + fixtures, lib/tests/graphify-gate.test.sh (the session-start graphify checks live there) [gated 2026-10-29], lib/tests/effort-routing.test.sh (one lock retargeted) [gated 2026-10-29], lib/tests/doctrine-citers.test.sh (census extension) [gated 2026-10-29], skills/guardrails/SKILL.md (citer) [gated 2026-10-29], .claude/tasks/contracts/2026-10-28-context-diet-1944.md + c1-*.sh [gated 2026-10-29], .claude/tasks/TODO.md [gated 2026-10-29], lib/project-rules.sh (comment only), agents/*.md (23 tracked, `description:` only), skills/init-project/SKILL.md, skills/ship-feature/SKILL.md, skills/onboard/SKILL.md, skills/audit-delta/SKILL.md, agents/interviewer.md, agents/scaffolder.md, agents/seo-analyzer.md, lib/design-gate.md, lib/project-archetypes/rest-api-node.md, .claude/rules/rules-maintenance.md, .claude/tasks/contracts/c1-*.sh (oracles), robin_petier `.claude/memory/` (one entry, its own chore/* branch), docs at STEP 8. +CLAUDE.global.md, settings.json, rules/web-building.md, rules/rest-api.md, rules/secure-by-default.md, rules/default-language.md (deleted), rules/supabase.md (new), rules/cloud-functions.md (new), lib/architecture-defaults.md (new), hooks/design-toolchain-reminder.sh, lib/tests/design-toolchain-reminder.test.sh, hooks/session-start.sh, lib/graphify-gate.sh (only if the graph-present branch needs it), a session-start graphify suite (new), doctor.sh + one lib/doctor-*.sh + its suite (new), lib/tests/ user-rules suite (new) + fixtures, lib/tests/graphify-gate.test.sh (the session-start graphify checks live there) [gated 2026-10-29], lib/tests/effort-routing.test.sh (one lock retargeted) [gated 2026-10-29], lib/tests/doctrine-citers.test.sh (census extension) [gated 2026-10-29], skills/guardrails/SKILL.md (citer) [gated 2026-10-29], .claude/tasks/contracts/2026-10-28-context-diet-1944.md + c1-*.sh [gated 2026-10-29], .claude/tasks/TODO.md [gated 2026-10-29], docs/superpowers/specs/2026-10-29-context-diet-design.md + docs/superpowers/plans/2026-10-29-context-diet.md (transient, purged at finish) [gated 2026-10-29], lib/project-rules.sh (comment only), agents/*.md (23 tracked, `description:` only), skills/init-project/SKILL.md, skills/ship-feature/SKILL.md, skills/onboard/SKILL.md, skills/audit-delta/SKILL.md, agents/interviewer.md, agents/scaffolder.md, agents/seo-analyzer.md, lib/design-gate.md, lib/project-archetypes/rest-api-node.md, .claude/rules/rules-maintenance.md, .claude/tasks/contracts/c1-*.sh (oracles), robin_petier `.claude/memory/` (one entry, its own chore/* branch), docs at STEP 8. ## PROOF — controller, 2026-10-29 - c2 (robin_petier): `chore/memory-lan-server` started by `gitflow.sh start`, `memory.sh -C ~/Documents/robin_petier add decision --status accepted` → BDR-075 (v1 registry, stderr note), memory commit d16cd6e via memory-commit.sh rc 0, pushed; `git -C ~/Documents/{faunosteo,game} status --short` empty. Critical projects: faunosteo's only auto memory (dev-host-no-docker-access) already lives in its blockers.md (docker.sock BLK, resolved 2026-10-08); game's auto-memory dir is empty; jeux-deploy's (remote-git-ops) dropped by the pass-A answer (contradicts the gitflow delete doctrine). Nothing of faunosteo/game is lost. From 6a5208f545b01b310bcb22c700e1d0eaf0db0a94 Mon Sep 17 00:00:00 2001 From: bchanot Date: Thu, 29 Oct 2026 14:40:35 +0100 Subject: [PATCH 19/21] =?UTF-8?q?chore(memory):=20BDR-130=20+=20BDR-131=20?= =?UTF-8?q?+=20LRN-238..241=20+=20EVAL-053=20=E2=80=94=20ship-feature=20co?= =?UTF-8?q?ntext-diet,=20TODO=20phase=201=20checked=20+=20follow-ups?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .claude/memory/decisions.md | 17 +++++++++++++++++ .claude/memory/evals.md | 6 ++++++ .claude/memory/journal.md | 3 +++ .claude/memory/learnings.md | 16 ++++++++++++++++ .claude/tasks/TODO.md | 11 ++++++++++- 5 files changed, 52 insertions(+), 1 deletion(-) diff --git a/.claude/memory/decisions.md b/.claude/memory/decisions.md index b38e7c9..69213fd 100644 --- a/.claude/memory/decisions.md +++ b/.claude/memory/decisions.md @@ -1155,6 +1155,7 @@ Branch feature/user-writing-web-rules, UNMERGED (human gate). - **Alternatives rejected**: path-scope Design work / Web sections into `rules/` (BDR-031 principle; the design hook needs the section in context regardless of file type); caveman doctrine (BDR-031: instructions-to-follow must stay prose); raise the 320 guard again (BDR-062 already moved it once; a guard that follows the file is not a guard). - **Status**: accepted, on chore/claude-global-density, UNMERGED (human gate). make test unchanged (2 pre-existing T16a), banner density warning gone, doctor 0 errors. - **Reference**: `CLAUDE.global.md`, `hooks/session-start.sh` (320 guard), `hooks/design-toolchain-reminder.sh` (heading match). Links [[BDR-031]], [[BDR-062]], [[BDR-085]]. +- **Status (2026-10-29)**: accepted, amended by BDR-130 (2026-10-29): Design work path-scoped in rules/web-building.md, hook = Read pointer ## BDR-099 — C2 coherence: 30 doctrine/skill tensions resolved, doctrine wins, BDR-068 kept as the written exception - **Date**: 2026-09-24 @@ -1337,6 +1338,7 @@ Branch feature/user-writing-web-rules, UNMERGED (human gate). - **Hooks**: interviewer FAILURE MODES row (language not stated → propose Rust), init-project founding-BDR table, project CLAUDE.md exception list. - **Alternatives rejected**: section in CLAUDE.global.md (busts 320 budget); `paths:`-scoped rule (brainstorm is chat, never fires). - **Refs**: commit ee76723, branch chore/rust-default. Links [[BDR-085]]. +- **Status (2026-10-29)**: accepted, amended by BDR-130 (2026-10-29): Rust default moved to lib/architecture-defaults.md, chat covered by the always-on line ## BDR-119 — impeccable = Build path for all UI, frontend-design out of the gate [accepted] (2026-10-16) - **Decision**: Build UI routes to impeccable (init, shape, new-work, craft floor, `impeccable detect`, fresh finish reviewer). `design.profile` GATE-BLOCK: impeccable in, frontend-design out. frontend-design stays installed + profile-listed: light path for a one-off visual w/o project context, never beside impeccable on same task. @@ -1351,6 +1353,7 @@ Branch feature/user-writing-web-rules, UNMERGED (human gate). - **Why**: user ask. Dashboard-only items (spend cap, WAF, budget stop) stay MANUAL, never claimed done. Scanner proves absence of protection, never presence of security; clean scan = "no static finding". Calibrated on 8 real projects, each FP class fixed + locked by benign test. - **Alternatives rejected**: Rust scanner (interpreted skill script, no build step, default-language contraindication, same rank as explain-diff checker); section in CLAUDE.global.md (budget); `paths:`-scoped rule (never fires in chat/brainstorm); semgrep rules only (blind to migrations, policies, consent flow). - **Refs**: branch feature/secure-by-default, suite `lib/tests/guardrails-scan.test.sh` (89 checks). Links [[BDR-085]] [[BDR-118]]. +- **Status (2026-10-29)**: accepted, amended by BDR-130 (2026-10-29): Supabase/cloud-functions bodies → path rules, one always-on line each ## BDR-121 — Guardrails fix loop reuses the bugfix circuit, scanner = oracle [accepted] (2026-10-18) - **Decision**: after report, proposals (route plan) -> prose approval gate -> bugfixer + verify-secure gates -> re-pass. Each accepted fix = contract criterion, CHECK = `scan.py --assert-absent RULE:path` (marker GUARDRAILS-CLEAR, positive control: fails before fix). Re-pass = `--baseline` vs pre-fix scan (GUARDRAILS-NO-NEW). 2 rounds max, residuals open. `--report-only` keeps audit alone. @@ -1397,6 +1400,7 @@ Branch feature/user-writing-web-rules, UNMERGED (human gate). - **Amendment 6 (2026-10-25, shell deny probe)**: bench `.claude/tasks/plans/2026-10-25-bash-deny-probe/`. Native Bash deny matcher sees through compound ops, subshell, `env`/`command`/`timeout`/`nohup`/`xargs`, quoted command word, simple assignments: no per-rule shell duplication. Misses `sh -c`, bare shell + heredoc, `$(…)` command, absolute path, interpreters, quoted literal arg. Under `defaultMode: auto` classifier approved every miss. rtk-rewrite hook runs before permission eval, deny evaluated on rewritten cmd: `git push origin :feature` → `rtk git push …` bypasses `git push * :**` (ac23cc6) and ask `git push *`; `cat */*.pem` likewise. Redirects into Edit-denied path denied. `ask` beats `allow`. User: stay auto, fixes go in phase 2 (rtk rc=3 passthrough + rtk read twins, targeted ask/deny rules, limits written down, routing guard covers Bash writes). Interim risk accepted with the phase order. - **Amendment 7 (2026-10-25, Fable re-challenge of the whole queue)**: 4 lenses + native-features guide (CLI 2.1.308), synthesis `.claude/tasks/plans/2026-10-25-context-mod-queue-challenge.md` § RE-CHALLENGE. BLOCKER closed: hard_deny names off switches only, never mod paths/sources (classifier would refuse mod maintenance). Merge gate = native `ask` rules (`Bash(bash */gitflow.sh finish*)`, `Bash(gitflow_finish*)`, `Bash(git merge *)`), bench r3 G1-G7 all denied, `start` free; `$.ui.ask` mod dropped; BDR-068 /close auto-finish costs one click (user accepted). Routing guard hosted in model-router: `runMain` wrong signal (BEST tier only, never ends), mod state plugin-private; free when `turnMain.source ∈ {skill, model}` or `/route` sticky; Edit/Write/NotebookEdit only, Bash write forms deferred (no measured evasion). Interpreters (`python3 -c` 211, `node -e` 450 calls / 14 days) → soft_deny prose, not static ask; `Bash(/*)` dropped (kills rtk abs twins). Commit-msg hook deferred (4/78 overrun, hooks miss 6/7 repos on core.hooksPath). 4a shrunk: memory.sh add/status/journal/check/index + flock, own-header `[tag]` first then last status line wins (reconcile.sh:60-67 dropped own header = BLK-032..034 false-open), Index blocks removed via /prune-memory, no Meta backfill, no English validator (1/1,290), per-file v2 marker. Phase 1: design section appended to rules/web-building.md (hook one-liner, 2,131 fires), one lib/architecture-defaults.md, Supabase/functions keep always-on line (path rules fail open at scaffold), agent description diet at source, origin line already shipped. Phase 5: lib/profiles/.json source of truth (no generator), detection via /plugin-check (no fingerprint), cleanup += toggle-external.sh + old-layout writers, migrate auto memories before autoMemoryEnabled:false, enable scope = --settings copy else settings.local, never user scope mid-skill. Phase 3 CONDITIONAL on the measured residual after 0/4a/1/5/2: listing filter, contexts field, hint classifier, agent rewrite, higgsfield deltas dropped. 4c = intent rerank + error 4-gram only, digest in session-start.sh on compact/clear; 4b redacts at capture, bounded ring; 4d deferred. Proof budget: static glob check + InstructionsLoaded log for path rules, model canaries for hook/mod levers only. - **Amendment 8 (2026-10-25, model per project and per conversation)**: user ask (one Claude Code conversation per project, often concurrent: Fable on one, opus on another). Measured headless (scratchpad modeltest): project `.claude/settings.local.json` `"model"` wins over user settings, `--settings '{"model":…}'` wins over both; same scopes as packs. `/model` writes the TRACKED user settings.json (fable landed there 2026-10-25): never the per-project route. Applied: tracked default `opus`, this repo local `claude-fable-5-1[1m]`. Phase 5 profile = `enabledPlugins` + `model`; doctor warns when tracked `model` ≠ `opus`. Residuals accepted by the user: interpreters (`python3 -c`, `node -e`) rest on prose + classifier (491/661 calls from sub-agents, an ask rule would fail executors); Bash write forms out of the routing guard until a measured evasion. +- **Status (2026-10-29)**: accepted, phase 1 shipped 2026-10-29 (BDR-130): next phase 5 ## BDR-126 — model-router `/model ` scope dialog: project / conversation / everywhere [accepted] (2026-10-25) @@ -1426,3 +1430,16 @@ Branch feature/user-writing-web-rules, UNMERGED (human gate). - **Why**: Index drifted (16 rows missing), status in 3 places, BLK-032..034 false-open (prose words), no single writer (ad hoc Edit/python on 357k files). Phase 4a of [[BDR-125]]. - **Alternatives rejected**: `flock(1)` (absent on macOS, [[BDR-110]]); `mkdir` lock (uutils 0.10 not atomic, [[LRN-236]]); generated Index kept (drift by construction, [[LRN-055]]); upgrade via /prune-memory curation (no oracle); strict parser on v1 (regressed 4 of 13 repos: title-suffix, `date: · status:`, `**Statut** :`). - **Refs**: contract `.claude/tasks/contracts/2026-10-27-memory-v2-write-2030.md`, plan + spec `docs/superpowers/{plans,specs}/2026-10-27-memory-v2-write*`, commits a423594..aab9e4d, upgrade 9698473. [[LRN-237]], [[EVAL-052]]. + +## BDR-130 — Phase 1 context diet: native carriers per section, one always-on line where chat needs it [accepted] (2026-10-29) +- **Context**: BDR-125 phase 1, feature/context-diet (4bbb3c5..789a2b2), contract `.claude/tasks/contracts/2026-10-28-context-diet-1944.md`. +- **Decision**: each always-on section → native carrier matching its trigger, no mod. Design work → `rules/web-building.md` (hook one-liner says Read it); graphify usage → `hooks/session-start.sh` block only when `graphify-out/graph.json` exists (threshold + one reminder clause stay, sub-agents never see the banner); never SPA + Rust default → `lib/architecture-defaults.md` Read by init-project/interviewer/scaffolder/ship-feature STEP 1/onboard/audit-delta, one always-on line under `# Architecture decisions`; Web APIs → `rules/rest-api.md` § Versioning; Supabase/cloud-functions bodies → `rules/supabase.md` / `rules/cloud-functions.md`, one always-on line each saying Read before writing a new file; `"autoMemoryEnabled": false`; 13 agent descriptions ≤ 200 chars. +- **Measured**: `/context` 30.5k → 26.2k; own gain ≈ −2.8k (Memory files 9.6k → 8.0k, System prompt 4.4k → 3.7k, Custom agents 2.6k → 2.1k); MCP instr 2.4k → 0.9k external. +- **Accepted costs**: analyzer `memory: project` dropped with auto memory (dirs empty, user pick); `**/functions/**` fires in non-cloud dirs; Supabase owner-policy detail not always-on. +- **Amends**: BDR-118, BDR-120 (moved out of always-on; chat covered by always-on line), BDR-098 (Design work path-scoped, hook = pointer). +- **Deferred**: Skill-routing lines → skill descriptions (TODO phase 3 bullet). + +## BDR-131 — settings.json is a base file: /model never committed, UI writes stashed [accepted] (2026-10-29) +- **Decision**: tracked `settings.json` = base file. `/model` writes never committed (model per project lives in `.claude/settings.local.json`); tracked default `"model": "opus"`, `"switchModelsOnFlag": true` stays. UI-written keys (`"theme"`) stay uncommitted, stashed around `gitflow finish` (`git stash push -- settings.json`, finish, pop); re-pushed only for a major change. +- **Why**: user 2026-10-29: "il ne faut jamais suivre le model… le model par defaut est opus… push un fichier de base, ensuite toute modifs auto on les stash". Never `git checkout`/`restore` the live file (symlink of ~/.claude/settings.json). +- **Rejected**: commit `/model` + theme as is (doctor warns tracked ≠ opus). diff --git a/.claude/memory/evals.md b/.claude/memory/evals.md index a376fa6..5cc726a 100644 --- a/.claude/memory/evals.md +++ b/.claude/memory/evals.md @@ -413,3 +413,9 @@ Dogfood: 3 blind lenses attacked the v1 plan for the plan-challenge feature itse - **Method**: 2 plan-challenge rounds (3 lenses each, reference lib run before the plan), 8 task reviews, 4 fix rounds on Task 8, verifier ×2, security gate, controller proof on 14 repo copies, opus xhigh final review + scoped re-review. - **Anomalies**: each layer caught what earlier green layers missed. Challenge: two classifiers, BLK-019/020 false-open, uutils mkdir lock. Task reviews: G4 guard dodged by string split (rejected), `###` verdict flip ×4 shapes. Verifier: 3 EVAL Index actions lost. Controller proof: template path after `-C` (relative call only). Opus final, after all gates green: lock spin on unwritable `.git` (no rc), bare-prefix `status BLK` writing BLK-001, bullet-list Index facts dropped (trucks_at_work), 59+106 duplicate Date lines (`**Date** :` spacing). One implementer tried `--no-verify` in a temp repo (denied). - **Action**: keep the full stack for libs that rewrite user data; add a real-data copy proof with the user's own invocation before the final review. [[BDR-129]], [[LRN-237]]. + +## EVAL-053 — ship-feature phase 1 context diet: challenge, final review and gates (2026-10-29) +- **Checked**: ship-feature phase 1 run quality (8 tasks, sonnet executors + reviewers, one haiku transcription). +- **Method**: 3-lens plan challenge + confirmation pass, per-task reviews, final opus/xhigh whole-branch review, GATE 0 oracles (10 runnable, c1-*.sh positive-controlled before work), fresh verifier, security gate. +- **Anomalies**: challenge found 4 MAJOR (c1-readers red mid-Task 3, worktree vs in place, finish blocked by user settings hunks, contract out of sync with r2); final review found the new-file Write gap (I1) everybody missed; verifier 1st run died on Fable credits (429), retry pinned opus; 2nd run ECARTS(5) all human micro-gate items (approved text not on disk, transient docs out of scope, 2 SC2016 waivers); every per-task review clean first pass. +- **Action**: keep oracles + positive control before dispatch; brief reviewers on new-file Write semantics for path rules; record gate texts on disk (contract) so the verifier can match them. diff --git a/.claude/memory/journal.md b/.claude/memory/journal.md index f134d5e..c0fbe0a 100644 --- a/.claude/memory/journal.md +++ b/.claude/memory/journal.md @@ -668,3 +668,6 @@ rules: ## 2026-10-28 - Phase 4a memory v2 shipped on feature/memory-v2-write: lib/memory.sh single writer, registries v2 (9698473), shared parser fixes BLK-032..034, upgrade migrates 12/14 repos on copies (game, trucks_at_work refused). 2 challenge rounds + 8 task reviews + 4 Task 8 fix rounds + verifier x2 + opus final (lock spin, bare-prefix status, bullet Index). BDR-129, LRN-236, LRN-237, EVAL-052. Merge on user go. + +## 2026-10-29 +- Phase 1 context diet (feature/context-diet): 8 tasks SDD + final opus review (I1 Write gap fixed 789a2b2), GATE 0 MET, verifier CONFORME 21/21 after 2 micro-gates, security PASS. /context 30.5k → 26.2k (own −2.8k). Load proof: faunosteo supabase.md + web-building.md, game cloud-functions.md + supabase.md path_glob_match. robin_petier BDR-075 (auto memory migrated, chore/memory-lan-server). BDR-130/131, LRN-238..241, EVAL-053. Faunosteo/game: nothing lost. diff --git a/.claude/memory/learnings.md b/.claude/memory/learnings.md index acc804e..c6084ec 100644 --- a/.claude/memory/learnings.md +++ b/.claude/memory/learnings.md @@ -1833,3 +1833,19 @@ Rule: when editing a doctrine file under structure locks, grep the test's lock s ## LRN-237 — A migration oracle sharing the transform reader proves nothing: own range per reader, assert on the entry, prove with the user invocation (2026-10-28) - **Context**: memory v2 `upgrade` verdict oracle, 2026-10-28. Oracle compared each blocker's open/closed verdict, legacy reader before vs strict reader after. Four review rounds each found a range leak the oracle shared: `###` entry invisible to v1 reader counted closed → `resolved` written on an open blocker; `## BLK-003` range swallowed a following `### BLK-001`; a `### ` heading quoted in a fence ended the range; status lines inside a fence read. Tests stayed green because they checked the reconcile enumerator, blind to `###`. Separately: template path derived after `-C` cd → upgrade rc 2 only when the lib is called by relative path; implementers always used absolute paths. - **Apply**: an oracle sharing the transform's reader proves nothing: give each reader its own entry range (end at next heading of any level, fence-aware, skip fenced status). Assert on the entry itself, not via an enumerator. Prove a CLI on real data copies with the invocation users type (relative path + `-C`). Resolve a lib's own dir at source time (`cd -P` before any `cd`). [[BDR-129]], [[LRN-096]]. + +## LRN-238 — Path rules match gitignore-style and load on Read only: pointers say Read before writing (2026-10-29) +- **Pattern**: engine path-rule match = gitignore-style. InstructionsLoaded logs globs normalized (`**/supabase/**` → `**/supabase`, `rules/**` → `rules`), match at any depth, hidden dirs included. Load on Read only, never Write of new file. +- **Application**: an always-on pointer to a path rule must say "Read it before writing a new ", not "loads on X files". Plan, spec and user approval all missed it; final opus review caught it (I1, fixed 789a2b2). Static compgen check proves parsing only; load proof = logged headless session naming the Read tool. + +## LRN-239 — Live Claude Code rewrites settings.json from memory on its next settings write (2026-10-29) +- **Pattern**: running Claude Code re-serializes its in-memory settings into user `settings.json` on any later settings write: a `/model` "Everywhere" value + key order came back after a manual restore (seen 2026-10-29, twice). +- **Application**: after `/model` in a live session, restore the tracked file, then re-check before any commit or finish; stash UI writes (BDR-131). Restart ends it. + +## LRN-240 — autoMemoryEnabled false also drops sub-agent memory: project (2026-10-29) +- **Pattern**: `"autoMemoryEnabled": false` also removes a sub-agent's `memory: project` section. Proof 2026-10-29: analyzer asked for its agent-memory section → NO; same probe with `claude -p --settings '{"autoMemoryEnabled": true}'` → YES "# Persistent Agent Memory". +- **Application**: before toggling auto memory, check `memory:` frontmatter users and `.claude/agent-memory/*` contents (here 4 dirs, all empty: no loss). Dead field `memory: project` in agents/analyzer.md → TODO. + +## LRN-241 — Classify a usage log by source before trusting its counts (2026-10-29) +- **Pattern**: design-toolchain fire log 2026-10-28: 2,779 fires = 1,770 suite prompts (tests ran with the real HOME) + 857 `/x.md § Y`, templates/ and .claude/rules/ outside doctrine-citers. + - [ ] Measure the design hook's "Read … first" re-Read cost (instructions-loaded log) before adding "once per session". + - [ ] Probe: path rules seen injected after a Bash `sed -n` read (final review M8): confirm Read-only semantics before a later phase relies on it. + - [ ] Minor: relative `rules/supabase.md` paths in interviewer.md / guardrails SKILL.md beside absolute ones; agent description losses ("dispatcher applies", "no dispatch", gate-in-dispatcher; security-auditor names no dispatcher). + - [ ] robin_petier `chore/memory-lan-server` (BDR-075): merge on user go (approved 2026-10-29). - Facts 2026-10-24 (scratchpad pathtest, memtest): a `paths:` rule loads on Read of a matching file, NOT on Write of a new file; `"autoMemoryEnabled": false` removes the auto-memory system section; classic SessionStart / UserPromptSubmit hooks inject additionalContext; instruction files reload on compaction natively. `hooks/design-toolchain-reminder.sh` fired 2,131 times (16 to 210 per day); `brainstorming` is vendored and gitignored (.gitignore:78), an edit there does not persist. - Section → carrier: - auto-memory system section → `"autoMemoryEnabled": false` in settings.json. Before: migrate existing auto memories in faunosteo, jeux-deploy, robin_petier into their registries (user review), doctor warns when an auto-memory dir is non-empty. From cdcf28f3dcea441c297219e819487e0ca34527ad Mon Sep 17 00:00:00 2001 From: bchanot Date: Thu, 29 Oct 2026 14:42:27 +0100 Subject: [PATCH 20/21] =?UTF-8?q?docs:=20CHANGELOG,=20MIGRATION,=20README,?= =?UTF-8?q?=20ARCHITECTURE=20name=20phase=201=20context=20diet=20(carriers?= =?UTF-8?q?,=20auto=20memory=20off,=20doctor=20check)=20=E2=80=94=20ship-f?= =?UTF-8?q?eature=20context-diet?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ARCHITECTURE.md | 4 ++-- CHANGELOG.md | 6 +++++- MIGRATION.md | 4 ++++ README.md | 2 +- 4 files changed, 12 insertions(+), 4 deletions(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index b2ad7e5..6a05c3f 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -30,7 +30,7 @@ claude-config/ ├── mods/ # Claude Code mods (function-hooks plugins), loaded through the skills/ symlink ├── skills-external/ # Vendored skill packs: gstack submodule, design skills, superpowers, agent-skills, MengTo scroll skills, 21st and Higgsfield packs (machine-owned copies gitignored) ├── templates/ # Per-project templates (CLAUDE.md, settings, memory registries, path-rule skeletons, deploy runbook, gitignore) -└── lib/ # Shared libs: gitflow, memory registry writer, profiles, vendoring, route doctrine, gates, archetypes, project-rule oracle, tests +└── lib/ # Shared libs: gitflow, memory registry writer, profiles, vendoring, route doctrine, gates, archetypes, architecture defaults, project-rule oracle, tests ``` ## Architecture principles @@ -39,4 +39,4 @@ claude-config/ - `agents/` = execution units called by skills (never invoked directly by user) - `mods/` = Claude Code mods (function-hooks plugins); each loads through the tracked symlink `skills/` as `@skills-dir`, live at the next session; `mods/model-router/routing.json` (tracked) holds the phase table (tier, effort and the `about` line the first-use dialog shows), every skill and agent row and the first-use decisions - `templates/` = symlinked to `~/.claude/templates/` — copy into projects via `/onboard` or manually -- **Graphify** builds a knowledge graph of any codebase (`/graphify query`), producing a navigable wiki in `graphify-out/wiki/`. This map helps Claude understand project structure, find relevant code faster, and reason across files. Essential for large-scope tasks (multi-file features, complex bugs, architectural changes). Small tasks should skip it and read files directly. Proposed only from 200 tracked code files: the session-start banner informs, the user decides; nothing builds a graph without that go. +- **Graphify** builds a knowledge graph of any codebase (`/graphify query`), producing a navigable wiki in `graphify-out/wiki/`. This map helps Claude understand project structure, find relevant code faster, and reason across files. Essential for large-scope tasks (multi-file features, complex bugs, architectural changes). Small tasks should skip it and read files directly. Proposed only from 200 tracked code files: the session-start banner informs, the user decides; nothing builds a graph without that go. Where `graphify-out/graph.json` exists, the session-start hook prints the graphify usage rules. diff --git a/CHANGELOG.md b/CHANGELOG.md index 6dd2c41..a020a19 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,7 +7,7 @@ Format follows [Keep a Changelog](https://keepachangelog.com/) and this project ## [Unreleased] ### Added -- **Secure-by-default guardrails**: `rules/secure-by-default.md` (always on) makes six domains baseline on every project, plus systematic API and access hygiene (auth on every route, CORS, secrets, passwords hashed with argon2id or bcrypt, never compared in clear, logged or hardcoded): hosting (rate limit, CDN and firewall, hard spend cap), Supabase (RLS on every table, owner-scoped policies, no service role key client-side), SMS and email (recorded consent, unsubscribe, STOP), cloud functions (no self-trigger, instance cap, budget stop), injection (bound values in raw escapes, `format()` for dynamic SQL, allowlisted filters, no shell into a DB tool), exposure (no data in the console, no production source map, no debug flag, no secret in hydrated state, data attributes, hidden fields or shipped comments). `/guardrails` audits them: a stdlib Python scanner (`skills/guardrails/scripts/scan.py`, FAIL / WARN / MANUAL, exit 1 on FAIL) then judgment, report in `.claude/audits/GUARDRAILS.md`. The security-auditor gate runs the scanner's `api` and `supabase` domains and blocks on FAIL. Items only a provider dashboard can set stay MANUAL, never claimed done. An optional read-only live probe (`skills/guardrails/scripts/probe.py`, `--live`) confirms a finding from outside on a target the user owns and names: anon-read, cross-user, no-auth route, CORS reflection and a capped rate-limit burst, verdicts OPEN / CLOSED / SKIPPED / ERROR. An `exposure` block in the plan adds three read-only probes, meant for a production build or a staging URL: a served or inline source map for the page's scripts, a stack trace in a 404 or a user-named error route, sensitive keys in a JSON response (identifier-shaped names printed, never values); a target the probe could not observe is SKIPPED or ERROR, never CLOSED, and every plan path must start with `/`. It sends GET, HEAD and OPTIONS only (one opt-in POST burst, capped at 25), requires `--authorized`, takes secrets from the environment never the command line, never follows a redirect to another host, and stops at a request budget. After the report, `/guardrails` proposes fixes (plan phase, so Fable when the router can switch), applies only the ones the user accepts through the `bugfixer` executor and the `lib/verify-secure-loop.md` gates, then re-scans: each accepted fix is a contract criterion whose oracle is the scanner (`--assert-absent RULE:path`, marker `GUARDRAILS-CLEAR`), and a full pass against the pre-fix baseline (`--baseline`, marker `GUARDRAILS-NO-NEW`) catches regressions; a live probe replays on the user's go; two rounds at most, residuals reported open; `--report-only` keeps the audit alone. Suites: `lib/tests/guardrails-scan.test.sh` (clean fixture plus one mutant per rule, check modes, `gates.sh` integration) and `lib/tests/guardrails-probe.test.sh` (probe logic against a localhost fixture server). +- **Secure-by-default guardrails**: `rules/secure-by-default.md` (always on) makes six domains baseline on every project (the Supabase and cloud-function detail lives in the path rules `rules/supabase.md` and `rules/cloud-functions.md`), plus systematic API and access hygiene (auth on every route, CORS, secrets, passwords hashed with argon2id or bcrypt, never compared in clear, logged or hardcoded): hosting (rate limit, CDN and firewall, hard spend cap), Supabase (RLS on every table, owner-scoped policies, no service role key client-side), SMS and email (recorded consent, unsubscribe, STOP), cloud functions (no self-trigger, instance cap, budget stop), injection (bound values in raw escapes, `format()` for dynamic SQL, allowlisted filters, no shell into a DB tool), exposure (no data in the console, no production source map, no debug flag, no secret in hydrated state, data attributes, hidden fields or shipped comments). `/guardrails` audits them: a stdlib Python scanner (`skills/guardrails/scripts/scan.py`, FAIL / WARN / MANUAL, exit 1 on FAIL) then judgment, report in `.claude/audits/GUARDRAILS.md`. The security-auditor gate runs the scanner's `api` and `supabase` domains and blocks on FAIL. Items only a provider dashboard can set stay MANUAL, never claimed done. An optional read-only live probe (`skills/guardrails/scripts/probe.py`, `--live`) confirms a finding from outside on a target the user owns and names: anon-read, cross-user, no-auth route, CORS reflection and a capped rate-limit burst, verdicts OPEN / CLOSED / SKIPPED / ERROR. An `exposure` block in the plan adds three read-only probes, meant for a production build or a staging URL: a served or inline source map for the page's scripts, a stack trace in a 404 or a user-named error route, sensitive keys in a JSON response (identifier-shaped names printed, never values); a target the probe could not observe is SKIPPED or ERROR, never CLOSED, and every plan path must start with `/`. It sends GET, HEAD and OPTIONS only (one opt-in POST burst, capped at 25), requires `--authorized`, takes secrets from the environment never the command line, never follows a redirect to another host, and stops at a request budget. After the report, `/guardrails` proposes fixes (plan phase, so Fable when the router can switch), applies only the ones the user accepts through the `bugfixer` executor and the `lib/verify-secure-loop.md` gates, then re-scans: each accepted fix is a contract criterion whose oracle is the scanner (`--assert-absent RULE:path`, marker `GUARDRAILS-CLEAR`), and a full pass against the pre-fix baseline (`--baseline`, marker `GUARDRAILS-NO-NEW`) catches regressions; a live probe replays on the user's go; two rounds at most, residuals reported open; `--report-only` keeps the audit alone. Suites: `lib/tests/guardrails-scan.test.sh` (clean fixture plus one mutant per rule, check modes, `gates.sh` integration) and `lib/tests/guardrails-probe.test.sh` (probe logic against a localhost fixture server). - **/a11y skill**: accessibility leaves `/guardrails` and becomes its own skill. Same A11Y-* rules (img alt, field label, click without keyboard, focus outline removed, positive tabindex) on the shared scan engine (`skills/guardrails/scripts/scanner.py`, a `Catalogue` per CLI; `skills/a11y/scripts/scan.py`, markers `A11Y-CLEAR` / `A11Y-NO-NEW`), a Tab-only walk of the main flow on `--live` through `/browse` (marked not done otherwise), report `.claude/audits/A11Y.md`, fixes proposed with the alt and label wording as the user's choice, applied through the bugfix circuit (`bugfixer`, verify-secure gates, `bugfix/a11y-`), re-pass against a baseline. The keyboard, alt and label doctrine moves from `rules/secure-by-default.md` to the lazy `rules/a11y.md` (loads on UI files only; `rules/web-building.md` points at it). `/guardrails` scans `injection` (INJ-*) and `exposure` (EXP-*) instead, with per-language SQL patterns, shared `code_files` / `hits` / `dedupe_lines` / `client_reachable` helpers and a walker that lists files over 1 MB by path; `--domain a11y` is a usage error there. `/web-validate` keeps full WCAG conformance. Suite `lib/tests/a11y-scan.test.sh`; routing row `reflect`; profiles audit, dev, web, web-full, full, max. - **model-router mod**: `mods/model-router/`, a Claude Code mod (function-hooks plugin), routes every repo skill and agent from phase rows (`plan`, `reflect`, `orchestrate`, `escalate`, `judge`, `audit`, `implement`, `write`, `verify`, `explore`, `apply`, `mechanical`; built-ins Explore on sonnet/medium, Plan on opus/xhigh). A typed skill routes the main loop to its row, and a best-tier row holds across turns in a run slot until `/route clear`, `/route off`, a user `/model` or a typed skill on a non-best row. Agents get their row's model at spawn (within the tier, upward only) and its effort on every step; explicit Agent params win. Orchestrators declare their phases through the `mcp__model-router__route` tool. `ultrathink` in a prompt sets the turn's minimum effort and `/route effort=max` holds until `/route clear`; the built-in `/effort` is not a lever inside a run. `/route show` names the run slot (`main: run `), and a `null` row in the override drops a default row. The model gets a `route` tool and the user a `/route` command (`show|clear|off|on|reload|pending|ask on|off|forget ||model= effort=|switch on|off|verbose on|off`). Optional per-machine config `~/.claude/model-router.json`, where `"enabled": false` turns it off on that machine. The spinner suffix and the status line show the route in force. It loads in every session through the tracked symlink `skills/model-router` (`model-router@skills-dir`). `make doctor` gains a Mods section; suite `make test suite=lib/tests/mods.test.sh`. Known limits: a main-loop switch (a `/model` hand pick excepted) runs only while the cold read it costs (the context minus what the target model's prompt cache holds) fits `upgradeMaxTokens` (200000) or `downgradeMaxTokens` (120000), and a downgrade also needs `mainModelSwitch` (on by default, off on any non-boolean value); the hooks send full model ids, so the `models` table has to follow new versions. - **model-router first-use confirmation**: `mods/model-router/routing.json` (tracked) is the single source of the phase table and of every skill and agent row, and keeps the decisions: `confirmed`, `changed` (`from`/`to`), `projects` exceptions keyed by the origin remote reduced to `host/path` (credentials and local paths never stored), and `ask`. The first use of a rowed typed skill, a rowed agent spawn or a main-loop phase declared through the `route` tool opens a dialog with context: the skill's description (first sentence of its `SKILL.md` frontmatter) or the agent's, the phase with its `about` line (a new field on each of the 12 phases) and the model id and effort the next step really runs on. A row offers Later, Keep or Change; a main-loop phase Later or Keep. Change asks the model (fable, opus, sonnet, haiku with their tier), then the effort among those the phases of that model use (skipped when there is only one), then Everywhere or This project only; the pair maps to an existing phase (rows stay phase names, the same phase counts as Keep, a pair no phase offers is added by hand as a new phase). A skill-row change toasts the model and effort it now runs on, with the `/route switch on` hint when the main loop holds back a downgrade; a free-text answer counts as Later. One dialog at a time, never in headless (`-p`) runs or inside a sub-agent. Only a dialog answer, `/route ask on|off` or `/route forget` (which takes decisions back; a changed row returns to its shipped phase, the frontmatter floors stay yours to realign) writes the file (serialized, 64 KiB cap, never created when absent); each write asks you to commit it from the config repo. `/route pending` lists unconfirmed rows and phases. Layers: routing.json < `~/.claude/model-router.json` (its `ask` wins); a project's `.claude/model-router.json` is never read. Tests: `mods/model-router/hooks/register.test.ts`. @@ -20,6 +20,7 @@ Format follows [Keep a Changelog](https://keepachangelog.com/) and this project - **Project path rules (CLAUDE.md split)**: `lib/project-rules.sh` (`check`, `matches`, `sections`, `extract`, `emit`, optional `-C `) is the glob oracle for `.claude/rules/.md` rules, one-line `paths:` frontmatter, loaded on Read of a matching file; suite `lib/tests/project-rules.test.sh`. `/onboard split` classifies an existing project CLAUDE.md section by section behind a gate and moves the path-bound ones into rules on a `chore/claude-md-split` branch. `extract` also moves a `###` subsection (heading passed as `'### '`; a bare heading stays `##`), which ends at the next heading of level 3 or less outside a fence, and `sections --depth 3` lists each `##` section's subsections with their sizes, so `/onboard split` can move a path-bound subsection out of an always-on parent (one `### <title>` row; a row's parent is never itself a move row). `extract` refuses an absolute `<out>`, one with a `..` part, or one that already exists (a dangling symlink included), with rc 2 and the reason on stderr, and leaves the source CLAUDE.md untouched when the rule directory or file cannot be written. `/onboard` and `/init-project` emit `docker`, `testing` and `ci` rules from `templates/project-rules/` when their globs match. This repo's CLAUDE.md now keeps its header, Health Stack and a pointer; four sections load as path rules. - **InstructionsLoaded logger**: `hooks/instructions-loaded.sh`, wired in `settings.json`, appends one JSON line per instruction file loaded to `~/.claude/logs/instructions-loaded.jsonl` (rotated above 5 MB), the proof that a path rule loaded. - **Memory registries v2, single writer**: `lib/memory.sh` is the one writer and reader of the `.claude/memory/` registries (every verb takes an optional leading `-C <dir>`): `add <kind> --title … --body-file … [--status …] [--supersedes <ID>]` appends an entry with the next ID from the headings and prints only the new ID; `status <ID> <text>` appends a dated `**Status (<date>)**:` line; `journal <line>` appends under today's `## YYYY-MM-DD`; `index [<kind>]` prints ID, date, title and status from headings and bodies; `check [--staged]` verifies heading shape, unique IDs, no Index and no open fence (a v1 file is named, never failed); `upgrade` migrates v1 to v2 (Index-only dates and statuses become body lines, `format: 2` added, `## Index` removed, every v1 heading dialect becomes `## ID — title (date)`), after an oracle on IDs, check and blocker verdicts, else rc 2 with the file untouched (a duplicate ID or a non-table Index is refused). Writes run under a lock in the git common dir, on a verified backup restored on failure or signal. `templates/memory/` ships v2 templates; the session banner adds `registry v1: N file(s) (memory.sh check)` while a project registry is v1. Suite `lib/tests/memory.test.sh`. +- **Architecture defaults carrier**: `lib/architecture-defaults.md`, read before proposing a stack (new project, scaffolding, stack brainstorm, whole-project rewrite): public sites never SPA, Rust by default, web APIs versioned. Path rules `rules/supabase.md` and `rules/cloud-functions.md` hold the full Supabase and cloud-function domains. Suites `lib/tests/user-rules.test.sh` and `lib/tests/doctor-automem.test.sh`. ### Changed - Registries are written only through `lib/memory.sh`, never by Edit (`CLAUDE.global.md`, Memory registries); every CAPITALIZE step (`/feat`, `/bugfix`, `/hotfix`, `/ship-feature`, `/capitalize`, `/init-project`, `/onboard`, `commit-changer`) writes through `lib/capitalize-commit.md` § WRITE. @@ -41,8 +42,11 @@ Format follows [Keep a Changelog](https://keepachangelog.com/) and this project - `/tour`: each summary row says `on origin` or `local only` with the `! git -C "<project>" push -u origin <branch>` to run. The tour never pushes or retries. - model-router keyword prompt rules (`plan|design|architecture…`, `why|review|audit…`), the `ultrathink` floor and the derived `orchestrate` route of a main Agent dispatch set the turn's effort only, never a model: they no longer lift main above the session model, and a held best-tier run keeps its model. Fable on main comes only from a skill row, the `route` tool, a typed `/route` or a `/model` hand pick (BDR-123). Tests: `mods/model-router/hooks/register.test.ts`. - `.gitignore` and `templates/gitignore/standard.gitignore` un-ignore `.claude/rules/` (`!.claude/rules/` after `.claude/*`); `lib/gitflow-test.sh` asserts the socle line. +- Context diet (BDR-125 phase 1): `CLAUDE.global.md` keeps one always-on line for the architecture defaults and points to `lib/architecture-defaults.md`. Design work moves to `rules/web-building.md` § "Design work — full toolchain", and `hooks/design-toolchain-reminder.sh` now tells the model to Read it and no longer fires on `<agent-message` hand-backs. API versioning moves to `rules/rest-api.md`. Graphify usage prints from `hooks/session-start.sh` only where `graphify-out/graph.json` exists. `rules/secure-by-default.md` keeps one line each for Supabase and cloud functions, telling to Read the path rule before writing a new file. Agent descriptions are 200 characters or fewer. Own gain about 2.8k tokens of always-on context (measured `/context` 30.5k to 26.2k). +- `settings.json` sets `"autoMemoryEnabled": false`. `make doctor` gains an Auto memory section (the setting, plus leftover files under `~/.claude/projects/*/memory/`) and checks the `~/.claude/rules` symlink (8 links). The session-start health check includes `rules`. ### Removed +- `rules/default-language.md`: its content is `lib/architecture-defaults.md` § Default language. - The five `effort-low` … `effort-max` skills, `lib/effort-pins.txt`, `lib/effort-pins.sh` and `lib/model-check.sh`, with their tests and the effort-pin re-apply steps of `install-plugins.sh` and `update-all.sh`. The model-router rows replace them. A typed `/effort-<level>` no longer exists: use `ultrathink` or `/route effort=max`. Breaking: the next release is 3.0.0. ### Fixed diff --git a/MIGRATION.md b/MIGRATION.md index fe285b2..6128784 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -203,3 +203,7 @@ make doctor A v2 registry is the same `.claude/memory/<name>.md` file, versioned and pushed with the code, with `format: 2` in its frontmatter and no `## Index`. The session banner line `registry v1: N file(s) (memory.sh check)` flags a project still on v1. v1 stays readable and writable (lenient), and the `check --staged` chokepoint skips it. To migrate, run `bash ~/.claude/lib/memory.sh -C <project> upgrade` on a clean `.claude/memory`, then commit through `/commit-change` when headings were rewritten (memory-commit refuses heading rewrites by design). `upgrade` refuses a registry with duplicate IDs or a non-table Index and leaves the file untouched: a human renumbers or converts first. + +## Auto memory off (2026-10-29) + +`settings.json` now sets `"autoMemoryEnabled": false`, so Claude Code no longer loads `~/.claude/projects/<slug>/memory/`. Anything left there is knowledge no session reads. `make doctor` (section "Auto memory") counts the project dirs that still hold files. For each one, move what is worth keeping into that project's registries with `bash ~/.claude/lib/memory.sh -C <project> add <kind> --title … --body-file …`, then delete the leftover dir by hand. diff --git a/README.md b/README.md index 1f7a9bc..3daf38a 100644 --- a/README.md +++ b/README.md @@ -491,7 +491,7 @@ make profile-reset # go to the default profile (full) make new-skill name=myskill # scaffold agent + skill files ``` -`doctor.sh` checks: symlinks, GStack submodule, vendored skills (curl-pinned externals in `plugins.lock.json` + `link.sh`'s `EXTERNAL_SKILLS`, per the active profile), Playwright browser cache, prerequisites (git, Node, Cargo, Python, Claude Code), plugins, permissions, token budget, config consistency, git hooks (global core.hooksPath + generated githooks/), mods (loading link and `@skills-dir` state), scratchpad (TMPDIR quota), Higgsfield CLI and session, seo-data layer. +`doctor.sh` checks: symlinks, GStack submodule, vendored skills (curl-pinned externals in `plugins.lock.json` + `link.sh`'s `EXTERNAL_SKILLS`, per the active profile), Playwright browser cache, prerequisites (git, Node, Cargo, Python, Claude Code), plugins, permissions, token budget, config consistency, git hooks (global core.hooksPath + generated githooks/), mods (loading link and `@skills-dir` state), scratchpad (TMPDIR quota), Higgsfield CLI and session, seo-data layer, auto memory (`autoMemoryEnabled` false in `settings.json`, leftover files under `~/.claude/projects/*/memory/`). --- From d1d1127f310254f530feba70616894232de0f7c6 Mon Sep 17 00:00:00 2001 From: bchanot <chanot.bastien@gmail.com> Date: Thu, 29 Oct 2026 14:42:42 +0100 Subject: [PATCH 21/21] chore: purge transient planning artifacts (BDR-065) --- .../plans/2026-10-29-context-diet.md | 1076 ----------------- .../specs/2026-10-29-context-diet-design.md | 128 -- 2 files changed, 1204 deletions(-) delete mode 100644 docs/superpowers/plans/2026-10-29-context-diet.md delete mode 100644 docs/superpowers/specs/2026-10-29-context-diet-design.md diff --git a/docs/superpowers/plans/2026-10-29-context-diet.md b/docs/superpowers/plans/2026-10-29-context-diet.md deleted file mode 100644 index 5df74df..0000000 --- a/docs/superpowers/plans/2026-10-29-context-diet.md +++ /dev/null @@ -1,1076 +0,0 @@ -# Phase 1 native context diet — Implementation Plan - -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. - -**Goal:** Move four always-on doctrine blocks, two secure-by-default domain bodies and the long agent descriptions to native carriers that load only when needed, and switch off auto memory, without losing any rule. - -**Architecture:** No mod. Each text moves to the carrier whose trigger matches it: a `paths:` rule (loads on Read of a matching file), the SessionStart hook (prints only when a graph exists), a lib file our skills Read, a setting. CLAUDE.global.md keeps one always-on line where plain chat still needs the rule. - -**Tech Stack:** bash 5.3 (shellcheck-clean, GNU + BSD portable, no `grep -P`), markdown doctrine, jq, python3 (`-I`) with PyYAML for one oracle. - -**Spec:** `docs/superpowers/specs/2026-10-29-context-diet-design.md`. Contract (acceptance criteria, judged by the verifier): `.claude/tasks/contracts/2026-10-28-context-diet-1944.md`. Oracles: `.claude/tasks/contracts/c1-*.sh` (already written, do not edit them). - -## Global Constraints - -- Execute IN PLACE in `/home/bchanot/Documents/claude` on `feature/context-diet`, no worktree: `~/.claude/{CLAUDE.md,rules,lib,hooks,settings.json}` are symlinks into this checkout and Task 7 relies on the user's uncommitted hunks in THIS working tree. -- Branch `feature/context-diet` (exists). Never commit on develop/main. Never `--no-verify`. Never `git add -A` / `git add .`: add the exact paths listed in the task. -- Moved text is moved VERBATIM (byte-identical lines) unless the task shows the new text. The oracles compare against develop commit `017a28b`. -- Hook stdout strings name deployed paths (`~/.claude/...`); maintainer comments name `CLAUDE.global.md` (BDR-064). -- Foreign-style repo: match the neighbouring code (inline shell, `check()` test idiom, `PASS=%s FAIL=%s` footer, comments only for the why). Doctrine lines ≤ 80 chars; do not add a line over 80 chars to CLAUDE.global.md (3 exist today). -- Tests run only through `make test suite=<path>` or the full `make test`. shellcheck: `shellcheck *.sh hooks/*.sh lib/*.sh` (+ any new `lib/tests/*.sh` you create). -- Bash pitfalls: no `head` reading a producer under pipefail (SIGPIPE rc 141); a sourced lib never changes the caller's shell options. -- `settings.json` carries one uncommitted UI line (`"theme": "dark"`): never stage or revert it (Task 7 gives the exact recipe). -- No destructive commands, no file outside this repo (the robin_petier write is a controller step, not yours). - -## Review Focus - -1. A real user prompt that starts with `<` (pasted content: `<pasted_content>…`) must still fire the design hook; only `<task-notification>` and `<agent-message` turns are skipped. Pinned: Task 1 F11. -2. session-start run from a subdirectory of a repo whose root holds `graphify-out/graph.json` prints the usage block; run outside any git repo it prints none and does not error. Pinned: Task 2 T3, T5. -3. A `§` citation whose label is a prefix of a heading (`§ "Version"` vs `## Versioning`) or whose target file does not exist must be reported DANGLING, never skipped. Pinned: Task 6 T5. -4. doctor runs under `set -euo pipefail`: an absent `~/.claude/projects`, or memory dirs holding only empty subdirs, must yield 0 and rc 0. Pinned: Task 7 T1, T5, T6. -5. The settings.json commit must carry only the `autoMemoryEnabled` line, the user's `/model` hunks stay unstaged in the working tree. Pinned: Task 7 Step 6. - ---- - -### Task 1: Design work moves to rules/web-building.md; the hook points there - -**Files:** -- Modify: `CLAUDE.global.md` (Skill routing line ~280, Higgsfield line ~295-296, delete the `## Design work — full toolchain (tiered by scope)` section ~300-322) -- Modify: `rules/web-building.md` (append the section at the end) -- Modify: `hooks/design-toolchain-reminder.sh` (header comment, skip case, output line) -- Modify: `lib/tests/design-toolchain-reminder.test.sh` -- Modify: `lib/tests/effort-routing.test.sh:213` -- Modify: `lib/design-gate.md:47-49` - -**Interfaces:** -- Produces: the heading `## Design work — full toolchain (tiered by scope)` as the LAST section of `rules/web-building.md` (Task 6's census resolves citations to it); the hook output line below (exact). - -- [ ] **Step 1: Update the hook test first (it must fail on the current hook)** - -In `lib/tests/design-toolchain-reminder.test.sh`: - -Replace the two lines - -```bash -H="$(cd "$(dirname "$0")/../.." && pwd)/hooks/design-toolchain-reminder.sh" -pass=0; fail=0 -``` - -with - -```bash -H="$(cd "$(dirname "$0")/../.." && pwd)/hooks/design-toolchain-reminder.sh" -# Every hook call runs under a throwaway HOME (the fire log is -# $HOME/.claude/logs/design-toolchain-fires.log): the suite never writes the -# real one (1,770 of 2,779 logged fires were this suite's prompts, 2026-10-28). -T="$(mktemp -d)"; trap 'rm -rf "$T"' EXIT -export HOME="$T" -LINE='Design work detected → Read ~/.claude/rules/web-building.md § "Design work — full toolchain" first. Trivial (≤2 files, cosmetic) → /hotfix.' -pass=0; fail=0 -``` - -(`fire()` stays as it is: the exported HOME covers it. The L1 block keeps its own `tmp` HOME.) - -After the line `check D11-bare-ux ...` add - -```bash -check D12-agent-msg "$(fire '<agent-message from=a1> [Subagent hand-back] add css header fonts')" quiet -``` - -After the line `check F10-bare-ui ...` add - -```bash -check F11-pasted "$(fire '<pasted_content> add a button')" fire - -# --- The one-liner is a contract (LRN-104): exact text --- -check O1-exact-line "$(printf '{"prompt":"add a button"}' | bash "$H")" "$LINE" -# the fires above landed in the throwaway HOME, positively (not a global count) -check G1-fires-in-temp-home "$([ -s "$T/.claude/logs/design-toolchain-fires.log" ] && echo yes)" yes -``` - -- [ ] **Step 2: Run it, expect FAIL** - -Run: `make test suite=lib/tests/design-toolchain-reminder.test.sh` -Expected: FAIL lines for `D12-agent-msg` (got fire) and `O1-exact-line` (old text); the others pass. - -- [ ] **Step 3: Update the hook** - -In `hooks/design-toolchain-reminder.sh`, replace the header lines - -```bash -# UserPromptSubmit hook. When the prompt carries a UI/design signal, inject a -# reminder to mobilize the full design toolchain (tiered by scope, per CLAUDE.global.md -# "Design work — full toolchain"). A UserPromptSubmit hook's stdout is appended -# to the model's context, so the cat block below becomes additional guidance. -``` - -with - -```bash -# UserPromptSubmit hook. When the prompt carries a UI/design signal, point the -# model at the design toolchain section (tiered by scope). Since BDR-125 -# phase 1 it lives in rules/web-building.md § "Design work — full toolchain", -# not in CLAUDE.global.md: it loads by itself on a UI file Read, and a -# chat-only design request needs this pointer. A UserPromptSubmit hook's -# stdout is appended to the model's context. -``` - -Replace - -```bash -# Harness-generated turns (subagent/task notifications) are not user -# requests — never fire on them (CLAUDE.global.md trigger = a design/UI *request*). -case "$prompt" in - '<task-notification>'*) exit 0 ;; -esac -``` - -with - -```bash -# Harness-generated turns (task notifications, sub-agent hand-backs: 857 of -# 2,779 logged fires on 2026-10-28) are not user requests — never fire on -# them (the Design work trigger = a design/UI *request*). -case "$prompt" in - '<task-notification>'*|'<agent-message'*) exit 0 ;; -esac -``` - -Replace the heredoc body line - -``` -Design work detected → apply global CLAUDE.md section "Design work — full toolchain" (already in context). Trivial (≤2 files, cosmetic) → /hotfix. -``` - -with - -``` -Design work detected → Read ~/.claude/rules/web-building.md § "Design work — full toolchain" first. Trivial (≤2 files, cosmetic) → /hotfix. -``` - -- [ ] **Step 4: Move the section** - -Cut the whole section from `CLAUDE.global.md`: from the line `## Design work — full toolchain (tiered by scope)` through the line `ui-explore / ui-review are \`max\`-profile only.` (22 lines, CLAUDE.global.md:300-321), plus the one blank line that follows it (322), so `## graphify` follows the Skill-routing block's last line `office-hours…) are gone: use the fallback above, else say so.` and one blank line. Never touch the `## graphify` heading. - -Append to `rules/web-building.md`: one blank line, then those 22 lines byte-identical (the file must END with `ui-explore / ui-review are \`max\`-profile only.` + newline). Do not touch its frontmatter. - -- [ ] **Step 5: Retarget the two CLAUDE.global.md pointers** - -Replace - -``` -- Design / UI (build, system, audit, polish) → "Design work" below -``` - -with - -``` -- Design / UI (build, system, audit, polish) → Read - `~/.claude/rules/web-building.md` § "Design work" first -``` - -Replace - -``` - Higgsfield", named ask → `enable higgsfield-websites`: an aid inside - Design work and the site rules, never `website create|deploy|publish`. -``` - -with - -``` - Higgsfield", named ask → `enable higgsfield-websites`: an aid inside - the Design work rules (`rules/web-building.md`), never - `website create|deploy|publish`. -``` - -- [ ] **Step 6: Patch the two other citers** - -`lib/tests/effort-routing.test.sh:213`: replace - -```bash -has "CLAUDE.global.md" 'route to `reflect` (high) through their' -``` - -with - -```bash -has "rules/web-building.md" 'route to `reflect` (high) through their' -``` - -`lib/design-gate.md`: replace - -``` -already in the core set — checked regardless; their CLAUDE.md "+motion / -+static" notes say which tool you'll lean on, not a separate activation step. -``` - -with - -``` -already in the core set — checked regardless; the Design work section -(`rules/web-building.md`) names them as the motion and static tools, not a -separate activation step. -``` - -- [ ] **Step 7: Run the suites, expect PASS** - -Run each: `make test suite=lib/tests/design-toolchain-reminder.test.sh`, `make test suite=lib/tests/effort-routing.test.sh`, `make test suite=lib/tests/doctrine-citers.test.sh`, then `bash .claude/tasks/contracts/c1-design-moved.sh`. -Expected: three `all suites green`; the oracle prints `DESIGN-MOVED`. `shellcheck hooks/design-toolchain-reminder.sh lib/tests/design-toolchain-reminder.test.sh` clean. - -- [ ] **Step 8: Commit** - -```bash -git add CLAUDE.global.md rules/web-building.md hooks/design-toolchain-reminder.sh \ - lib/tests/design-toolchain-reminder.test.sh lib/tests/effort-routing.test.sh lib/design-gate.md -git commit -m "feat(design): Design work moves to rules/web-building.md, hook points there and skips sub-agent hand-backs" -``` - ---- - -### Task 2: graphify usage printed by session-start only where a graph exists - -**Files:** -- Modify: `CLAUDE.global.md` (`## graphify` section, now the last section) -- Modify: `hooks/session-start.sh` (quick health-check list line ~10; line-count guard comment ~257-259; new block before the final `echo ""`) -- Modify: `lib/tests/graphify-gate.test.sh` (new S-checks before its final `echo "PASS=…"`) - -**Interfaces:** -- Produces: when `$(git rev-parse --show-toplevel)/graphify-out/graph.json` exists, session-start stdout carries, after the box, the block shown in Step 3 (first line `graphify (graphify-out/graph.json present):`). - -- [ ] **Step 1: Write the failing checks** - -In `lib/tests/graphify-gate.test.sh`, insert before the final `echo "PASS=$pass FAIL=$fail"` (reuse its `mkrepo`, `check`, `$WORK/plain`; one banner run per fixture state): - -```bash -# ── session-start prints the usage rules only where a graph exists -# (BDR-125 phase 1: the body left CLAUDE.global.md) ── -SS="$(cd "$(dirname "$0")/../.." && pwd)/hooks/session-start.sh" -banner() { (cd "$1" && SESSION_START_OFFLINE=1 bash "$SS" </dev/null 2>/dev/null); } -d=$(mkrepo ss 1) -out=$(banner "$d") -check S1-banner-control "$(grep -c 'Claude Code config' <<<"$out")" 1 -check S1b-no-graph-silent "$(grep -c 'graphify query' <<<"$out")" 0 -mkdir -p "$d/graphify-out" "$d/app/sub"; echo '{}' > "$d/graphify-out/graph.json" -out=$(banner "$d") -check S2-graph-prints "$(grep -c 'graphify query' <<<"$out")" 1 -check S2b-update-rule "$(grep -c 'graphify update \.' <<<"$out")" 1 -check S3-from-subdir "$(banner "$d/app/sub" | grep -c 'graphify query')" 1 -out=$(banner "$WORK/plain") -check S4-not-a-repo "$(grep -c 'graphify query' <<<"$out")/$(grep -c 'Claude Code config' <<<"$out")" 0/1 -``` - -- [ ] **Step 2: Run it, expect FAIL** - -Run: `make test suite=lib/tests/graphify-gate.test.sh` -Expected: FAIL on S2, S2b, S3 (got 0); T1-T9, S1, S1b, S4 pass. - -- [ ] **Step 3: Edit session-start.sh** - -Replace `for f in CLAUDE.md settings.json agents skills; do` (quick health check, ~line 10) with `for f in CLAUDE.md settings.json agents skills rules; do` (Design work and the Supabase / cloud-functions bodies now live only under `~/.claude/rules`). - -Between the line `[ -n "$EFFORT_WARN" ] && printf '%s\n' "$EFFORT_WARN"` and the final `echo ""`, insert: - -```bash -# graphify usage (BDR-125 phase 1): the rules left CLAUDE.global.md, which -# keeps the 200-file threshold and a one-line reminder; they print where a -# graph exists. -_gx_root=$(git rev-parse --show-toplevel 2>/dev/null) -if [ -n "$_gx_root" ] && [ -f "$_gx_root/graphify-out/graph.json" ]; then - cat <<'EOF' -graphify (graphify-out/graph.json present): -- Codebase-wide question → `graphify query`; relationships → `path A B`; - concept → `explain`. Scoped subgraph beats raw grep. -- Known file / small task → read directly, no graphify. -- `wiki/index.md` → broad-nav entry; `GRAPH_REPORT.md` → whole-architecture. -- After editing code → `graphify update .` (AST-only, free). -EOF -fi -unset _gx_root -``` - -Replace the comment - -```bash -# CLAUDE.global.md line-count guard (anti-regression). BDR-062 supersedes -# BDR-031's 275 target: 305 is the assumed reality (extraction done at -# job1; further compression costs clarity > token gain) — warn past 320. -``` - -with - -```bash -# CLAUDE.global.md line-count guard (anti-regression, BDR-062): warn past -# 320. BDR-125 phase 1 moved Design work, the graphify usage and the -# architecture defaults to their carriers (333 → ~285 lines). -``` - -- [ ] **Step 4: Trim the CLAUDE.global.md section** - -Replace the whole `## graphify` section (heading through `- After editing code → \`graphify update .\` (AST-only, free).`) with the lines below. The reminder clause stays always-on because dispatched sub-agents load CLAUDE.md, never the main session's SessionStart output: - -``` -## graphify - -Threshold: graphify from 200 tracked code files, never below (banner line -`graphify? N code files ≥ 200, no graph` informs, the user decides; never -build or `graphify claude install` without that go). With a graph -(`graphify-out/graph.json`): `graphify query` before raw grep, -`graphify update .` after code edits; the session banner prints the rest. -``` - -- [ ] **Step 5: Run, expect PASS** - -Run: `make test suite=lib/tests/graphify-gate.test.sh`, `make test suite=lib/tests/memory.test.sh`, `make test suite=lib/tests/push-guard.test.sh` (the last two grep the banner). -Expected: three `all suites green`. `shellcheck hooks/session-start.sh lib/tests/graphify-gate.test.sh` clean. - -- [ ] **Step 6: Commit** - -```bash -git add CLAUDE.global.md hooks/session-start.sh lib/tests/graphify-gate.test.sh -git commit -m "feat(graphify): usage rules print from session-start only where a graph exists" -``` - ---- - -### Task 3: Architecture defaults move to lib/architecture-defaults.md; Web APIs to rules/rest-api.md - -**Files:** -- Create: `lib/architecture-defaults.md` -- Delete: `rules/default-language.md` (`git rm`) -- Modify: `CLAUDE.global.md` (`# Architecture decisions` H1: intro + `## Public websites — never SPA` + `## Web APIs — always versioned`, ~142-167) -- Modify: `rules/rest-api.md` (`## Versioning`; the `/api/tasks` example in `## Naming`) -- Modify: `.claude/rules/rules-maintenance.md` (second paragraph) -- Modify: `lib/project-archetypes/rest-api-node.md:58` -- Modify (readers): `skills/init-project/SKILL.md` (STEP 3, STEP 5), `agents/interviewer.md:26`, `agents/scaffolder.md` (INPUTS REQUIRED, PHASE 1), `skills/ship-feature/SKILL.md` (STEP 1), `skills/onboard/SKILL.md` (STEP 6), `skills/audit-delta/SKILL.md:276`, `agents/seo-analyzer.md:542-543` - -**Interfaces:** -- Produces: `lib/architecture-defaults.md` headings `## Public websites — never SPA`, `## Default language — Rust`, `## Web APIs — always versioned`; `rules/rest-api.md` heading `## Versioning` with the full rule (Task 6 resolves citations to both). - -- [ ] **Step 1: Run the oracles, expect FAIL** - -Run: `bash .claude/tasks/contracts/c1-arch-moved.sh; bash .claude/tasks/contracts/c1-readers.sh` -Expected: `no lib/architecture-defaults.md`, `no lib in skills/init-project/SKILL.md`. - -- [ ] **Step 2: Create the lib** - -Create `lib/architecture-defaults.md` with exactly this structure: - -``` -# Architecture defaults — read before proposing a stack - -Read at project creation, scaffolding, a stack brainstorm or a whole-project -rewrite (BDR-125 phase 1). The three defaults are named always-on in -`~/.claude/CLAUDE.md` § "Architecture decisions"; the detail lives here. - -<the `## Public websites — never SPA` section of CLAUDE.global.md, byte-identical: heading + its 13 body lines, up to and including ` silently pick React CRA.`> - -<the whole content of rules/default-language.md, byte-identical, except its first line `# Default language — Rust` becomes `## Default language — Rust`> - -## Web APIs — always versioned -Every endpoint `/api/v1/...` from day one; breaking change → `v2`, the old -version keeps working. Full rule: `~/.claude/rules/rest-api.md` § Versioning -(loads on API files). -``` - -One blank line between sections; the `<…>` lines are instructions, not text to write. - -- [ ] **Step 3: Replace the H1 block in CLAUDE.global.md** - -Replace everything from the line `# Architecture decisions` down to (not including) `## Version control — gitflow (universal)` with: - -``` -# Architecture decisions -New project, scaffolding, stack brainstorm or whole-project rewrite: Rust -by default, a public site is never a SPA (Astro; Next.js when SSR is -needed), every web API versioned `/api/v1/` from day one. Read -`~/.claude/lib/architecture-defaults.md` before proposing a stack. - -``` - -- [ ] **Step 4: Web APIs into rules/rest-api.md, delete default-language.md** - -In `rules/rest-api.md` replace - -``` -## Versioning -CLAUDE.md § Web APIs — always versioned. Not repeated here. -``` - -with (body byte-identical to the former CLAUDE.global.md § Web APIs body): - -``` -## Versioning -Every endpoint versioned from day one: `/api/v1/...`, no bare `/api/`; the -router mirrors it (`api/v1/routes/`). Breaking change → `v2`, the old -version keeps working and clients migrate at their pace; non-breaking -additions → current version. Each version is a self-contained contract, -never bent to match a newer one. -``` - -In the same file, `## Naming` now contradicts it: replace `Plural nouns for endpoints (\`/api/tasks\`), no verbs.` with `Plural nouns for endpoints (\`/api/v1/tasks\`), no verbs.` - -In `.claude/rules/rules-maintenance.md` (it names `default-language.md` as an always-on exception, which `c1-readers.sh` reads as a stale citer), replace the paragraph that starts `A rule WITH \`paths:\` YAML frontmatter` and ends `keep rule bodies tiny.` with (it names `lib/tests/user-rules.test.sh`, which Task 5 of this branch creates): - -``` -A rule WITH `paths:` YAML frontmatter (glob list) loads lazily — only when -Claude Reads a file matching a glob (never on the Write of a new file; -sub-agents too); a rule WITHOUT it loads at session start, same cost as the -global memory. Doctrine leaves CLAUDE.global.md only for a carrier that fires -when it is needed (BDR-125 phase 1: a path rule, a hook, a lib our skills -Read), with one always-on line wherever plain chat still needs the rule. -Exception: a standalone user-authored rule set that would bust the 320-line -density budget may live here WITHOUT `paths:` (always-on load) — -writing-style.md (BDR-085), secure-by-default.md (BDR-120); -`lib/tests/user-rules.test.sh` locks that set. `paths:` globs match against -the CURRENT project's tree, gitignore-style (a pattern without an inner `/` -matches at any depth, hidden dirs included) — a broad glob (e.g. `rules/**`) -can fire in foreign projects; keep rule bodies tiny. -``` - -In `lib/project-archetypes/rest-api-node.md` replace - -``` -- Pas de versioning API (/api/v1/) — flag CLAUDE.md : "Web APIs — always versioned" -``` - -with - -``` -- Pas de versioning API (/api/v1/) — flag `rules/rest-api.md` § Versioning -``` - -Run: `git rm -q rules/default-language.md` - -- [ ] **Step 5: Wire the readers** - -`agents/interviewer.md` row "Language not stated": replace `(\`rules/default-language.md\`)` with `(\`~/.claude/lib/architecture-defaults.md\` § Default language)`. - -`skills/init-project/SKILL.md` STEP 3: after the line `Invoke \`brainstorming\` (vendored superpowers skill) with BRIEF + ANALYSIS REPORT.` insert: - -``` -Read `~/.claude/lib/architecture-defaults.md` first and pass it as binding -context: its defaults (Rust, never a SPA for a public site, `/api/v1/`) hold -unless the BRIEF names otherwise. -``` - -`skills/init-project/SKILL.md` STEP 5: replace - -``` -+ DESIGN (verbatim) + paths `~/.claude/templates/project-CLAUDE.md` + -`~/.claude/CLAUDE.md`. A STOP (missing input) comes back as its report — -``` - -with - -``` -+ DESIGN (verbatim) + paths `~/.claude/templates/project-CLAUDE.md` + -`~/.claude/CLAUDE.md` + `~/.claude/lib/architecture-defaults.md`. A STOP -(missing input) comes back as its report — -``` - -`agents/scaffolder.md`: after `4. \`~/.claude/CLAUDE.md\`` add `5. \`~/.claude/lib/architecture-defaults.md\``; replace `Read \`~/.claude/templates/project-CLAUDE.md\` and \`~/.claude/CLAUDE.md\`.` with `Read \`~/.claude/templates/project-CLAUDE.md\`, \`~/.claude/CLAUDE.md\` and \`~/.claude/lib/architecture-defaults.md\`.` - -`skills/ship-feature/SKILL.md` STEP 1: after the line ` BLK already closed."` insert: - -``` -When the feature picks a language, a framework or an API shape, Read -`~/.claude/lib/architecture-defaults.md` first and add its defaults to the -in-force constraints. -``` - -`skills/onboard/SKILL.md` STEP 6: after the line `Lire le bloc \`audit_stack:\` du fichier \`~/.claude/lib/project-archetypes/<archetype>.md\`.` insert one blank line and: - -``` -Les audits jugent l'architecture contre `~/.claude/lib/architecture-defaults.md` -(site public jamais SPA, API `/api/v1/`, Rust par défaut pour une réécriture) : -passer ce chemin dans chaque brief d'audit. -``` - -`skills/audit-delta/SKILL.md`: replace - -``` -- **conformity** — read project `CLAUDE.md` (+ `~/.claude/CLAUDE.md`) - FIRST, then check changed code against those norms. This repo's: -``` - -with - -``` -- **conformity** — read project `CLAUDE.md` (+ `~/.claude/CLAUDE.md` and - `~/.claude/lib/architecture-defaults.md`) FIRST, then check changed code - against those norms. This repo's: -``` - -`agents/seo-analyzer.md`: replace - -``` -HTML). Global score excludes it. Fix: SSR/SSG (CLAUDE.md: public sites are -never SPAs).` -``` - -with - -``` -HTML). Global score excludes it. Fix: SSR/SSG -(lib/architecture-defaults.md: public sites are never SPAs).` -``` - -- [ ] **Step 6: Run, expect PASS** - -Run: `bash .claude/tasks/contracts/c1-arch-moved.sh` → `ARCH-MOVED`; `bash .claude/tasks/contracts/c1-readers.sh` → `READERS-OK`; `make test suite=lib/tests/doctrine-citers.test.sh` → `all suites green`. - -- [ ] **Step 7: Commit** - -```bash -git add lib/architecture-defaults.md CLAUDE.global.md rules/rest-api.md \ - .claude/rules/rules-maintenance.md \ - lib/project-archetypes/rest-api-node.md agents/interviewer.md agents/scaffolder.md \ - agents/seo-analyzer.md skills/init-project/SKILL.md skills/ship-feature/SKILL.md \ - skills/onboard/SKILL.md skills/audit-delta/SKILL.md -git commit -m "feat(doctrine): architecture defaults move to lib/architecture-defaults.md, Web APIs to rules/rest-api.md" -``` - -(`git rm` already staged the deletion of `rules/default-language.md`.) - ---- - -### Task 4: Supabase and cloud-functions bodies become path rules - -**Files:** -- Create: `rules/supabase.md`, `rules/cloud-functions.md` -- Modify: `rules/secure-by-default.md` (§4 and §6 bodies only) -- Modify: `skills/guardrails/SKILL.md:10`, `agents/interviewer.md:27` - -- [ ] **Step 1: Run the oracle, expect FAIL** - -Run: `bash .claude/tasks/contracts/c1-supabase-functions.sh` → `no rules/supabase.md`. - -- [ ] **Step 2: Create the two rules** - -`rules/supabase.md`: - -``` ---- -paths: ["**/supabase/**", "**/*supabase*.*"] ---- - -# Supabase — secure by default, domain 4 - -Path-scoped body of `rules/secure-by-default.md` domain 4 (BDR-125 phase 1); -the always-on line there keeps RLS and the client-side key ban. - -<the 7 body lines under `## 4. Supabase` of rules/secure-by-default.md, byte-identical, from `- RLS enabled on every table, in the migration that creates it.` to ` and revoke execute from anon. Buckets private by default.`> -``` - -`rules/cloud-functions.md`: - -``` ---- -paths: ["**/functions/**", "**/serverless.*", "**/firebase.json"] ---- - -# Cloud functions — secure by default, domain 6 - -Path-scoped body of `rules/secure-by-default.md` domain 6 (BDR-125 phase 1); -the always-on line there keeps the instance cap and the self-trigger ban. - -<the 4 body lines under `## 6. Cloud functions`, byte-identical, from `- No function re-triggers itself: never write to the resource that fires it,` to `- Budget alert wired to an automatic stop beyond the budget.`> -``` - -No line of the intro paragraph may start with `- ` (the oracle takes everything from the first `- ` line as the bullets). - -- [ ] **Step 3: Shrink the two sections of secure-by-default.md** - -Replace the body under `## 4. Supabase` (7 lines) with: - -``` -- RLS on every table, never a service_role or secret key client-side. Full - domain: rules/supabase.md (loads on Supabase files). -``` - -Replace the body under `## 6. Cloud functions` (4 lines) with: - -``` -- Max instances and a timeout on every function, never a self-trigger. Full - domain: rules/cloud-functions.md (loads on function files). -``` - -Every other line of the file stays byte-identical (the oracle checks it). - -- [ ] **Step 4: Patch the two citers** - -`skills/guardrails/SKILL.md`: replace - -``` -Checks a project against `rules/secure-by-default.md`, then fixes what the -user accepts and proves each fix. A scanner reads the tree as data and finds -``` - -with - -``` -Checks a project against `rules/secure-by-default.md` (domains 4 and 6 in -full: `rules/supabase.md`, `rules/cloud-functions.md`), then fixes what the -user accepts and proves each fix. A scanner reads the tree as data and finds -``` - -`agents/interviewer.md` row "Project has an API…": replace `Apply \`rules/secure-by-default.md\`:` with `Apply \`rules/secure-by-default.md\` (Supabase and cloud-function detail: \`rules/supabase.md\`, \`rules/cloud-functions.md\`):`. - -- [ ] **Step 5: Run, expect PASS** - -Run: `bash .claude/tasks/contracts/c1-supabase-functions.sh` → `SB-CF-MOVED`; `make test suite=lib/tests/guardrails-scan.test.sh` → `all suites green`. - -- [ ] **Step 6: Commit** - -```bash -git add rules/supabase.md rules/cloud-functions.md rules/secure-by-default.md \ - skills/guardrails/SKILL.md agents/interviewer.md -git commit -m "feat(rules): Supabase and cloud-functions bodies become path rules, one always-on line each" -``` - ---- - -### Task 5: user-rules suite locks the always-on set; engine matching documented - -**Files:** -- Create: `lib/tests/user-rules.test.sh` -- Modify: `lib/project-rules.sh` (header comment lines 21-23 only) - -**Interfaces:** -- Consumes: `_rules_frontmatter <file>` (rc 1 = no frontmatter) and `_rules_globs <frontmatter>` (rc 0 globs, 1 no `paths:`, 2 malformed) from `lib/project-rules.sh` (sourced; it runs nothing when sourced). - -- [ ] **Step 1: Write the test** - -Create `lib/tests/user-rules.test.sh`: - -```bash -#!/usr/bin/env bash -# lib/tests/user-rules.test.sh — user-scope rules (rules/*.md, deployed as -# ~/.claude/rules): every frontmatter parses (one-line JSON `paths:` or no -# frontmatter at all) and the always-on set is exactly the two rules chat -# needs (BDR-125 phase 1 moved default-language to lib/architecture-defaults.md -# and the Supabase / cloud-functions bodies to path rules). Globs are not -# matched here: user rules span every stack; the load is proved by an -# InstructionsLoaded session (contract context-diet, criterion 15). -set -u -ROOT="$(cd "$(dirname "$0")/../.." && pwd)" -# shellcheck source=../project-rules.sh disable=SC1091 -source "$ROOT/lib/project-rules.sh" -pass=0; fail=0 -check() { if [ "$2" = "$3" ]; then pass=$((pass+1)); else fail=$((fail+1)); - printf 'FAIL %s: got[%s] want[%s]\n' "$1" "$2" "$3"; fi; } - -# rule_kind <file> → path | always | bad -rule_kind() { - local fm - fm=$(_rules_frontmatter "$1") || { echo always; return; } - _rules_globs "$fm" >/dev/null - case $? in 0) echo path ;; 1) echo always ;; *) echo bad ;; esac -} -# always_on <dir> → the always-on rule file names, space-joined -always_on() { - local f out="" - for f in "$1"/*.md; do - [ "$(rule_kind "$f")" = always ] && out="$out ${f##*/}" - done - printf '%s\n' "${out# }" -} - -# ── flip controls: the checker bites (LRN-096) ── -FIX="$(mktemp -d)"; trap 'rm -rf "$FIX"' EXIT -printf -- '---\npaths: ["**/*.css"]\n---\n\n# A\n' > "$FIX/a.md" -printf '# B, always-on\n' > "$FIX/b.md" -printf -- '---\npaths:\n - "**/*.css"\n---\n\n# C\n' > "$FIX/c.md" -check F1-path-rule "$(rule_kind "$FIX/a.md")" path -check F2-no-frontmatter-always "$(rule_kind "$FIX/b.md")" always -check F3-multiline-paths-bad "$(rule_kind "$FIX/c.md")" bad -check F4-extra-always-on-seen "$(always_on "$FIX")" "b.md" -# the R2 lock itself bites on a dir whose always-on set differs -cp "$FIX/b.md" "$FIX/writing-style.md"; cp "$FIX/b.md" "$FIX/secure-by-default.md" -check F5-lock-bites "$([ "$(always_on "$FIX")" = "secure-by-default.md writing-style.md" ] && echo match || echo mismatch)" mismatch - -# ── the real rules ── -bad="" -for f in "$ROOT"/rules/*.md; do - [ "$(rule_kind "$f")" = bad ] && bad="$bad ${f##*/}" -done -check R1-every-frontmatter-parses "${bad# }" "" -check R2-always-on-set "$(always_on "$ROOT/rules")" "secure-by-default.md writing-style.md" -check R3-moved-rules-path "$(rule_kind "$ROOT/rules/supabase.md")/$(rule_kind "$ROOT/rules/cloud-functions.md")" path/path - -printf 'PASS=%s FAIL=%s\n' "$pass" "$fail"; [ "$fail" -eq 0 ] -``` - -- [ ] **Step 2: Run, expect PASS (Tasks 3-4 already landed)** - -Run: `make test suite=lib/tests/user-rules.test.sh` → `all suites green`. The lock's bite is F4 (fixture). Never create a file under `rules/` to flip-test: it is the live `~/.claude/rules` of every session on this machine. - -- [ ] **Step 3: Correct the project-rules.sh comment (comment only)** - -In `lib/project-rules.sh` replace - -```bash -# dotglob makes `*` match dotfiles, which the engine's matcher skips: a -# glob that only hits hidden paths passes here but never loads), -``` - -with - -```bash -# dotglob makes `*` match dotfiles; the engine reaches hidden dirs too. Its -# matcher looks gitignore-style (InstructionsLoaded log, 2026-10-26: -# `paths: ["rules/**"]` logged as `globs: ["rules"]` and loaded on a Read -# of `.claude/rules/*.md`): a trailing `/**` dropped, a pattern without an -# inner `/` matching at any depth. A glob can thus load where this check -# does not look; the load proof is the logged session, not this check), -``` - -- [ ] **Step 4: Run, expect PASS** - -Run: `make test suite=lib/tests/project-rules.test.sh` and `make test suite=lib/tests/user-rules.test.sh` → `all suites green`; `bash lib/project-rules.sh check` → `project-rules: 4 rule(s) ok`; `shellcheck lib/project-rules.sh lib/tests/user-rules.test.sh` clean. - -- [ ] **Step 5: Commit** - -```bash -git add lib/tests/user-rules.test.sh lib/project-rules.sh -git commit -m "test(rules): user-rules suite locks the always-on set; engine matching documented" -``` - ---- - -### Task 6: doctrine-citers census resolves rules/ and lib/ § citations - -**Files:** -- Modify: `lib/tests/doctrine-citers.test.sh` - -**Interfaces:** -- Consumes: `_citers_resolve <doctrine-file> <name>` (existing, rc 0 when a heading starts with `<name>` then end/space/`:`/`(`/`—`, or a bold label `**<name>` exists). -- Produces: `_citers_extract_files <file>…` → `file:line:target:name`; `citers_check_files <root> <file>…` → `DANGLING:` lines, rc = count (≤ 99). - -- [ ] **Step 1: Add the extractor, the checker and the flip tests** - -In `lib/tests/doctrine-citers.test.sh`, after the `citers_check()` function (before `# ── flip-test`), insert: - -```bash -# _citers_extract_files <file>… → "file:line:target:name" per citation of a -# heading in another doctrine file: `rules/<f>.md § Label` or -# `lib/<f>.md § Label`, backticks around the path and quotes around the -# label allowed. A quoted label runs to its closing quote (`—` included); an -# unquoted one ends at the first character that is not a letter, space or -# hyphen: quote a label that prose follows. A citation of -# `.claude/rules/<f>.md § X` would be read as `rules/<f>.md` (none exist; -# ERE has no lookbehind and the portability census bans grep -P). -_citers_extract_files() { - /usr/bin/grep -nHoE '(rules|lib)/[a-z0-9-]+\.md`? § ?"[^"]{2,60}"' "$@" 2>/dev/null \ - | sed -E 's/^([^:]+:[0-9]+):(.*\.md)`? § ?"([^"]+)"$/\1:\2:\3/' - /usr/bin/grep -nHoE '(rules|lib)/[a-z0-9-]+\.md`? § ?[A-Z][A-Za-z][A-Za-z -]{1,40}' "$@" 2>/dev/null \ - | sed -E 's/^([^:]+:[0-9]+):(.*\.md)`? § ?(.*)$/\1:\2:\3/; s/[[:space:]]+$//' -} - -# citers_check_files <root> <file>… → DANGLING lines; rc = their count (capped 99) -citers_check_files() { - local root="$1" line file lno target name n=0; shift - while IFS= read -r line; do - [ -n "$line" ] || continue - file="${line%%:*}"; lno="$(printf '%s' "$line" | cut -d: -f2)" - target="$(printf '%s' "$line" | cut -d: -f3)"; name="${line#*:*:*:}" - if [ ! -f "$root/$target" ] || ! _citers_resolve "$root/$target" "$name"; then - echo "DANGLING: $file:$lno → $target § \"$name\""; n=$((n+1)) - fi - done < <(_citers_extract_files "$@") - return $(( n > 99 ? 99 : n )) -} -``` - -After the line `check T2c-label-named ...` insert: - -```bash -mkdir -p "$FIX/rules" "$FIX/lib" -printf '## Versioning\nx\n' > "$FIX/rules/api.md" -printf '## WRITE (before the commit)\n' > "$FIX/lib/cc.md" -# shellcheck disable=SC2016 # literal backticks in the fixture -printf 'ok: see `rules/api.md` § Versioning, and lib/cc.md § WRITE (x)\n' > "$FIX/fgood.md" -printf 'quoted: rules/api.md § "Versioning" first\n' >> "$FIX/fgood.md" -printf '## Design work — full toolchain (tiered)\n' > "$FIX/rules/web.md" -printf 'dash: rules/web.md § "Design work — full toolchain" first\n' >> "$FIX/fgood.md" -printf 'bad: rules/api.md § "Version", rules/none.md § Alpha, lib/cc.md § Read\n' > "$FIX/fbad.md" -printf 'dash: rules/web.md § "Design work — full kit" first\n' >> "$FIX/fbad.md" -citers_check_files "$FIX" "$FIX/fgood.md" >/dev/null; check T4-file-citations-resolve "$?" 0 -out=$(citers_check_files "$FIX" "$FIX/fbad.md"); rc=$? -check T5-file-dangling-caught "$rc" 4 -check T5d-quoted-label-whole "$(printf '%s\n' "$out" | grep -c 'full kit')" 1 -check T5b-missing-file-named "$(printf '%s\n' "$out" | grep -c 'rules/none.md')" 1 -check T5c-prefix-not-a-heading "$(printf '%s\n' "$out" | grep -c '"Version"')" 1 -``` - -After the line `check T3-repo-citations-resolve "$rc" 0` insert: - -```bash -out=$(cd "$ROOT" && citers_check_files "$ROOT" "${FILES[@]}" CLAUDE.global.md); rc=$? -[ -n "$out" ] && printf '%s\n' "$out" -check T6-repo-file-citations-resolve "$rc" 0 -# T7: the real citers bite — the same two files against a copy of -# rules/rest-api.md whose heading is renamed (never edit the live rules/) -mkdir -p "$FIX/copy/rules" -cp "$ROOT/rules/rest-api.md" "$FIX/copy/rules/rest-api.md" -(cd "$ROOT" && citers_check_files "$FIX/copy" lib/architecture-defaults.md \ - lib/project-archetypes/rest-api-node.md) >/dev/null -check T7a-real-citers-control "$?" 0 -sed 's/^## Versioning$/## Version policy/' "$ROOT/rules/rest-api.md" > "$FIX/copy/rules/rest-api.md" -(cd "$ROOT" && citers_check_files "$FIX/copy" lib/architecture-defaults.md \ - lib/project-archetypes/rest-api-node.md) >/dev/null -check T7b-real-rename-bites "$?" 2 -# the hook's pointer is checked whole, not as its "Design work" prefix -check T7c-hook-label-whole "$(cd "$ROOT" && _citers_extract_files hooks/design-toolchain-reminder.sh \ - | grep -c ':rules/web-building.md:Design work — full toolchain$')" 2 -``` - -Also update the file header comment: after the line `# skill's own sections and are out of scope.` add: - -```bash -# Since BDR-125 phase 1 doctrine also lives in rules/ and lib/: a -# `rules/<f>.md § Label` / `lib/<f>.md § Label` citation resolves against -# that file (T4-T6). -``` - -- [ ] **Step 2: Run, expect PASS** - -Run: `make test suite=lib/tests/doctrine-citers.test.sh` → `all suites green`. If T6 prints a DANGLING line, the citation text is wrong (fix the citing file's wording, never the checker), report it. - -- [ ] **Step 3: Commit** - -```bash -git add lib/tests/doctrine-citers.test.sh -git commit -m "test(census): resolve rules/ and lib/ § citations against their file" -``` - ---- - -### Task 7: auto memory off; doctor warns on leftover auto-memory files - -**Files:** -- Modify: `settings.json` (ONE line; the user's hunks stay unstaged) -- Create: `lib/doctor-automem.sh`, `lib/tests/doctor-automem.test.sh` -- Modify: `doctor.sh` (source line near 28; `check_symlink "rules"` + `_EXPECTED_LINKS=8`; new section 5d after 5c "Scratchpad") - -**Precondition (controller):** Task 7 is dispatched only once C1 (the robin_petier entry) is committed: Step 6 switches auto memory off for every session on the machine. - -**Interfaces:** -- Produces: `automem_leftover_dirs <projects_dir>` → prints the number of `<projects_dir>/*/memory` dirs holding ≥ 1 file; always rc 0. - -- [ ] **Step 1: Write the failing test** - -Create `lib/tests/doctor-automem.test.sh`: - -```bash -#!/usr/bin/env bash -# lib/tests/doctor-automem.test.sh — lib/doctor-automem.sh's -# automem_leftover_dirs(): absent dir, empty memory dirs, a file, a nested -# file, an empty subdir only, rc 0 under errexit (doctor.sh runs under -# `set -euo pipefail`) — BDR-125 phase 1. -set -u -ROOT="$(cd "$(dirname "$0")/../.." && pwd)" -LIB="$ROOT/lib/doctor-automem.sh" -# shellcheck source=../doctor-automem.sh disable=SC1091 -source "$LIB" -pass=0; fail=0 -check() { if [ "$2" = "$3" ]; then pass=$((pass+1)); else fail=$((fail+1)); - printf 'FAIL %s: got[%s] want[%s]\n' "$1" "$2" "$3"; fi; } -W="$(mktemp -d)"; trap 'rm -rf "$W"' EXIT - -check T1-absent-dir "$(automem_leftover_dirs "$W/nope")" 0 -mkdir -p "$W/p/-home-a/memory" "$W/p/-home-b/memory" -check T2-empty-dirs "$(automem_leftover_dirs "$W/p")" 0 -echo x > "$W/p/-home-a/memory/MEMORY.md" -check T3-one-file "$(automem_leftover_dirs "$W/p")" 1 -mkdir -p "$W/p/-home-b/memory/sub"; echo y > "$W/p/-home-b/memory/sub/note.md" -check T4-nested-file-counts "$(automem_leftover_dirs "$W/p")" 2 -mkdir -p "$W/p/-home-c/memory/empty-sub" -check T5-empty-subdir-silent "$(automem_leftover_dirs "$W/p")" 2 -check T6-rc0-under-errexit "$(bash -c 'set -euo pipefail; source "$1"; automem_leftover_dirs "$2" >/dev/null; echo "rc$?"' _ "$LIB" "$W/nope")" rc0 -# doctor.sh calls it on "$HOME/.claude/projects": the same call under a temp HOME -mkdir -p "$W/h/.claude/projects/-home-x/memory"; echo z > "$W/h/.claude/projects/-home-x/memory/a.md" -check T7-via-temp-home "$(HOME="$W/h" bash -c 'source "$1"; automem_leftover_dirs "$HOME/.claude/projects"' _ "$LIB")" 1 - -printf 'PASS=%s FAIL=%s\n' "$pass" "$fail"; [ "$fail" -eq 0 ] -``` - -- [ ] **Step 2: Run, expect FAIL** - -Run: `make test suite=lib/tests/doctor-automem.test.sh` → red (`lib/doctor-automem.sh` missing). - -- [ ] **Step 3: Write the lib** - -Create `lib/doctor-automem.sh`: - -```bash -#!/usr/bin/env bash -# ============================================================ -# lib/doctor-automem.sh — doctor.sh's auto-memory leftover check -# -# settings.json sets "autoMemoryEnabled": false (BDR-125 phase 1): Claude -# Code no longer reads ~/.claude/projects/<slug>/memory/, so a file left -# there is knowledge nobody loads. `automem_leftover_dirs <projects_dir>` -# prints how many <slug>/memory dirs hold at least one file and ALWAYS -# exits 0 (doctor.sh runs under `set -euo pipefail`; an absent dir is 0). -# -# No `set -euo pipefail` here: a sourced lib must not change the caller's -# shell options. -# ============================================================ - -# automem_leftover_dirs <projects_dir> — see file header. -automem_leftover_dirs() { - local d n=0 - for d in "$1"/*/memory; do - [ -d "$d" ] || continue - if [ -n "$(find "$d" -type f -print -quit 2>/dev/null)" ]; then - n=$((n + 1)) - fi - done - echo "$n" -} -``` - -- [ ] **Step 4: Wire doctor.sh** - -Replace `_EXPECTED_LINKS=7` with `_EXPECTED_LINKS=8`, replace the comment line `# Expected: CLAUDE.md, settings.json, agents, skills, templates, hooks/session-start.sh` with `# Expected: CLAUDE.md, settings.json, agents, skills, templates, lib, rules, hooks/session-start.sh`, and after `check_symlink "lib"` add `check_symlink "rules"` (Design work and the Supabase / cloud-functions bodies now live only under `~/.claude/rules`). - -After the two lines - -```bash -# shellcheck source=lib/doctor-skills.sh disable=SC1091 -source "$REPO/lib/doctor-skills.sh" -``` - -add - -```bash -# shellcheck source=lib/doctor-automem.sh disable=SC1091 -source "$REPO/lib/doctor-automem.sh" -``` - -After the Scratchpad section's closing `unset _sp _sp_fs _sp_opts` + `echo ""`, insert: - -```bash -# ──────────────────────────────────────────────────────────── -# 5d. Auto memory (BDR-125 phase 1): "autoMemoryEnabled": false, so a file -# left under ~/.claude/projects/<slug>/memory/ is never loaded again. -# ──────────────────────────────────────────────────────────── -echo "── Auto memory ──" -if jq -e '.autoMemoryEnabled == false' "$REPO/settings.json" >/dev/null 2>&1; then - pass "settings.json: autoMemoryEnabled false" -else - warn "settings.json: autoMemoryEnabled is not false — the auto-memory section loads every session (BDR-125 phase 1)" -fi -_am=$(automem_leftover_dirs "$HOME/.claude/projects") -if [ "$_am" -gt 0 ]; then - warn "auto memory: $_am project dir(s) still hold files under ~/.claude/projects/*/memory/ (never loaded) — migrate them to the project registries, then remove them by hand" -else - pass "auto memory: no leftover file under ~/.claude/projects/*/memory/" -fi -unset _am -echo "" -``` - -- [ ] **Step 5: Run, expect PASS** - -Run: `make test suite=lib/tests/doctor-automem.test.sh` → `all suites green`; `shellcheck doctor.sh lib/doctor-automem.sh lib/tests/doctor-automem.test.sh` clean. - -- [ ] **Step 6: settings.json, one line, staged alone** - -The working tree holds one uncommitted line written by the Claude Code UI, `"theme": "dark",` right after `"effortLevel": "high",` (gate 2026-10-29: UI writes are stashed, never committed): leave it. Stage only the new key, built from HEAD's version: - -```bash -tmp=$(mktemp) -git show HEAD:settings.json \ - | sed 's/^ "effortLevel": "high",$/&\n "autoMemoryEnabled": false,/' > "$tmp" -jq -e '.autoMemoryEnabled == false' "$tmp" >/dev/null || { echo "bad edit"; rm -f "$tmp"; exit 1; } -blob=$(git hash-object -w "$tmp"); rm -f "$tmp" -git update-index --cacheinfo "100644,$blob,settings.json" -sed -i.bak 's/^ "effortLevel": "high",$/&\n "autoMemoryEnabled": false,/' settings.json && rm settings.json.bak -jq -e '.autoMemoryEnabled == false' settings.json >/dev/null || { echo "worktree edit missed"; exit 1; } -git diff --cached settings.json -``` - -Expected: the cached diff is exactly one added line `+ "autoMemoryEnabled": false,`; `git diff settings.json` still shows only the `"theme"` line and nothing about autoMemoryEnabled; `jq -e '.autoMemoryEnabled == false' settings.json` → true. - -- [ ] **Step 7: Commit** - -```bash -git add lib/doctor-automem.sh lib/tests/doctor-automem.test.sh doctor.sh -git commit -m "feat(memory): autoMemoryEnabled false; doctor warns on leftover auto-memory files" -git show --stat HEAD | cat -git diff --stat settings.json | cat -``` - -Expected: the commit lists settings.json with `1 +`; the `"theme"` line remains unstaged. - ---- - -### Task 8: agent descriptions trimmed at the source (≤ 200 chars) - -**Files:** -- Modify (the `description:` line only): `agents/{validator-analyzer,doc-syncer,handover-doc-writer,client-handover-writer,plan-challenger,security-auditor,onboarder,verifier,bugfixer,seo-analyzer,code-cleaner,plugin-advisor,geo-analyzer}.md` - -- [ ] **Step 1: Run the oracle, expect FAIL** - -Run: `bash .claude/tasks/contracts/c1-agent-desc.sh` → lists the 13 files over 200 chars. - -- [ ] **Step 2: Replace each `description:` line with exactly the line below (nothing else in the file changes)** - -``` -agents/validator-analyzer.md: -description: Web standards audit agent, dispatched from /web-validate. W3C HTML/CSS validity and WCAG 2.1 (axe-core, pa11y, WAVE); scored .claude/audits/VALIDATE.md with fix diffs and user actions. -agents/doc-syncer.md: -description: 'Two-mode public-doc sync agent. MODE: audit (opus, read-only: drift, drafts, PATCH PLAN); MODE: patch (sonnet: applies the approved plan, emits PATCHED_FILES). Never touches .claude/.' -agents/handover-doc-writer.md: -description: 'Two-mode client deliverable writer, dispatched twice by client-handover. MODE: synthesize (opus: memory + git, 6-chapter draft); MODE: render (sonnet: annexes, gates, MD + HTML/PDF).' -agents/client-handover-writer.md: -description: Final ship-and-handover orchestrator called by /client-handover. Audit/fix/gate pipeline (SEO+GEO+HARDEN to ≥17/20, live VALIDATE), then the client deliverable via handover-doc-writer. -agents/plan-challenger.md: -description: Fresh plan challenger. Reads a PLAN file and attacks it through ONE lens (correctness | robustness | simplicity), then renders findings + a verdict. Report-only, blind to the other lenses. -agents/security-auditor.md: -description: 'SAST security gate: pinned semgrep rulesets + the CLAUDE.md security checklist on a diff or scope. VERDICT: PASS | BLOCK(n), blocks HIGH/CRITICAL only. Never fixes code. Fresh dispatch.' -agents/onboarder.md: -description: Generate claude-config files (CLAUDE.md, settings.json, .claudeignore, .gitignore safety, .claude/{tasks,memory,audits}/) for an existing project. No interview, no audit. Called by /onboard. -agents/verifier.md: -description: Fresh independent verifier. Reads a CONTRACT file from disk and renders CONFORME / ECARTS / ERROR on the implemented diff. Report-only, never fixes; dispatched with no iteration history. -agents/bugfixer.md: -description: Bug-fix EXECUTOR dispatched by /bugfix (or /guardrails, /a11y) with a closed DIAGNOSIS + FIX PLAN + contract. Applies the fix and a regression test, runs the suite. No investigation, no commit. -agents/seo-analyzer.md: -description: 'Classical SEO audit agent (Google, Bing), dispatched from /seo: Core Web Vitals, on-page, technical, local SEO, legal (FR). Emits a fix bundle + scored report. AI/GEO → geo-analyzer.' -agents/code-cleaner.md: -description: Cleanup EXECUTOR (PHASE 2) dispatched by /code-clean with an APPROVED scope. Deletes approved dead code, hands style items to the refactorer, re-audits. Zero behavior change, no commit. -agents/plugin-advisor.md: -description: Plugin-fit REASONER dispatched by lib/plugin-gate.md with a PROBE REPORT from plugin-probe. Classifies signals, scores complexity, recommends enable/disable. Report-only. -agents/geo-analyzer.md: -description: GEO audit agent for AI search engines, dispatched by /geo and /seo. AI crawlers, llms.txt, entity signals, Schema.org; emits a fix bundle and a scored report. Classical SEO → seo-analyzer. -``` - -(Lengths 170-193, all parse as YAML; measured 2026-10-29.) - -- [ ] **Step 3: Run, expect PASS, then the full suite** - -Run: `bash .claude/tasks/contracts/c1-agent-desc.sh` → `AGENT-DESC-OK (23 agents)`; then `make test` → last line `all suites green`; then `shellcheck *.sh hooks/*.sh lib/*.sh` clean. - -- [ ] **Step 4: Commit** - -```bash -git add agents/validator-analyzer.md agents/doc-syncer.md agents/handover-doc-writer.md \ - agents/client-handover-writer.md agents/plan-challenger.md agents/security-auditor.md \ - agents/onboarder.md agents/verifier.md agents/bugfixer.md agents/seo-analyzer.md \ - agents/code-cleaner.md agents/plugin-advisor.md agents/geo-analyzer.md -git commit -m "chore(agents): descriptions trimmed to ≤ 200 chars at the source" -``` - ---- - -## Controller steps (main loop, not dispatched) - -- **C0 — track the oracles** (before Task 1): commit the contract and `.claude/tasks/contracts/c1-*.sh` on this branch (`chore(contract)`), so every task and reviewer reads them from HEAD. -- **C1 — robin_petier entry** (after the STEP 3 gate approves its text, BEFORE Task 7 Step 6): `cd ~/Documents/robin_petier && bash ~/.claude/lib/gitflow.sh start chore memory-lan-server`, then `bash ~/.claude/lib/memory.sh -C ~/Documents/robin_petier add decision --title "<approved>" --status accepted --body-file <abs path>`, memory commit per `lib/capitalize-commit.md`, no merge (user go). robin_petier CLAUDE.md:192/:201 cite "Web APIs — always versioned" / "Public websites — never SPA" as global rules: both headings live on in `lib/architecture-defaults.md`, no patch; journal it. -- **C2 — proofs** (after Task 8): `bash lib/project-rules.sh -C <project> matches '<glob>'` per new glob (faunosteo, game; `**/serverless.*` named if nowhere); one headless `claude -p` per moved path rule naming the Read tool (faunosteo supabase file, game `supabase/functions/*`, a UI file) → `path_glob_match` lines from `~/.claude/logs/instructions-loaded.jsonl`; `claude -p "/context"` vs baseline; analyzer `memory: project` check after an analyzer dispatch. All journaled. If the analyzer memory turns out disabled by `autoMemoryEnabled: false`: STOP and ask the user (revert the line, or keep it and record a BDR). -- **C3 — oracles**: `GATES_TIMEOUT=900 bash ~/.claude/lib/gates.sh run .claude/tasks/contracts/2026-10-28-context-diet-1944.md`. -- **C4 — TODO.md** (STEP 7 memory commit): phase 1 checked with its proof numbers, follow-ups added (the user removes the auto-memory dirs; any deferred item from the gate). -- **C5 — finish precondition** (gate 2026-10-29): `gitflow finish` checks out develop, which git refuses while settings.json carries the uncommitted UI line (`"theme"`). Wrap the finish: `git stash push -m "ui settings" -- settings.json`, finish, `git stash pop`. Never `git checkout -- settings.json` / restore it (it is the live ~/.claude/settings.json). Tracked default stays `"model": "opus"`, `"switchModelsOnFlag": true`. diff --git a/docs/superpowers/specs/2026-10-29-context-diet-design.md b/docs/superpowers/specs/2026-10-29-context-diet-design.md deleted file mode 100644 index f6d5bf6..0000000 --- a/docs/superpowers/specs/2026-10-29-context-diet-design.md +++ /dev/null @@ -1,128 +0,0 @@ -# Phase 1 — native context diet (design) - -Contract: `.claude/tasks/contracts/2026-10-28-context-diet-1944.md` (the -acceptance criteria live there). Queue: BDR-125, TODO bullet "Phase 1, -native context diet: no mod". Approved in chat 2026-10-29 (A = 200 chars, -B = extend the census). - -## Goal - -Cut the always-on context loaded by every session, without a mod: each -section moves to the native carrier that fires when it is needed (path rule, -hook, lib Read by our skills, setting). Nothing is lost: every moved text is -reachable where it serves. Estimate: −2 to −2.5k tokens per session -(baseline 2026-10-28: 30.5k total, Memory files 9.6k, System prompt 4.4k, -Custom agents 2.6k). - -## Carriers - -| Source (develop 017a28b) | Carrier | Always-on residue | -|---|---|---| -| auto-memory system section | `"autoMemoryEnabled": false` (settings.json) | none | -| CLAUDE.global.md § Design work — full toolchain (tiered by scope) | appended verbatim to `rules/web-building.md` (same UI globs) | Skill-routing line points to it; design hook one-liner says Read it | -| CLAUDE.global.md § graphify usage body | `hooks/session-start.sh`, free lines after the box, only when `<repo root>/graphify-out/graph.json` exists | `## graphify` + the 200-file threshold rule | -| CLAUDE.global.md § Public websites — never SPA + `rules/default-language.md` | `lib/architecture-defaults.md` (verbatim, H1 of the language rule demoted to H2) | one line under `# Architecture decisions` naming Rust default, never SPA, `/api/v1`, the lib path | -| CLAUDE.global.md § Web APIs — always versioned | `rules/rest-api.md` § Versioning (full text, replaces "Not repeated here"; the § Naming example becomes `/api/v1/tasks`); the lib carries a one-line summary + pointer | named in the architecture line | -| `rules/secure-by-default.md` §4 Supabase, §6 Cloud functions bodies | `rules/supabase.md` (`**/supabase/**`, `**/*supabase*.*`), `rules/cloud-functions.md` (`**/functions/**`, `**/serverless.*`, `**/firebase.json`), bullets verbatim | the two headings stay, one line each (critical rule + pointer) | -| `agents/*.md` `description:` (23 tracked) | trimmed at the source to ≤ 200 chars | n/a | - -`rules/default-language.md` is deleted. The always-on rule set becomes -exactly `writing-style.md` + `secure-by-default.md`. - -## Exact visible strings - -- CLAUDE.global.md, under `# Architecture decisions` (replaces the intro and - the two sections): - `New project, scaffolding, stack brainstorm or whole-project rewrite: Rust - by default, a public site is never a SPA (Astro; Next.js when SSR is - needed), every web API versioned `/api/v1/` from day one. Read - `~/.claude/lib/architecture-defaults.md` before proposing a stack.` -- CLAUDE.global.md Skill routing: `Design / UI (build, system, audit, - polish) → Read `~/.claude/rules/web-building.md` § "Design work" first` - (the quotes end the label for the extended census; plan challenge - 2026-10-29). -- CLAUDE.global.md § graphify keeps, after the threshold: `With a graph - (graphify-out/graph.json): graphify query before raw grep, graphify - update . after code edits; the session banner prints the rest.` - (sub-agents load CLAUDE.md, never the SessionStart output). -- Design hook stdout: `Design work detected → Read - ~/.claude/rules/web-building.md § "Design work — full toolchain" first. - Trivial (≤2 files, cosmetic) → /hotfix.` (one line). -- secure-by-default.md §4: `- RLS on every table, never a service_role or - secret key client-side. Full domain: rules/supabase.md (loads on Supabase - files).` §6: `- Max instances and a timeout on every function, never a - self-trigger. Full domain: rules/cloud-functions.md (loads on function - files).` - -## Readers of the lib - -init-project (interviewer row, STEP 3 brainstorm input, STEP 5 scaffolder -brief), agents/interviewer.md, agents/scaffolder.md, ship-feature STEP 1 -(when the feature picks a language, framework or API shape), onboard STEP 6 -(audit briefs), audit-delta conformity axis. agents/seo-analyzer.md cites the -lib for "public sites are never SPAs". /refactor is not edited (no -whole-project mode; the always-on line covers it). - -## Hook fixes (user scope additions, pass A) - -- design-toolchain-reminder.sh skips `<agent-message` turns (857 of 2,779 - logged fires) like it skips `<task-notification>`. -- Its suite runs every call under a temp HOME (1,770 logged fires were suite - prompts); the exact one-liner is asserted. - -## Auto memories - -One decision entry into robin_petier's registry (LAN dev server: never start -unprompted, detached form on ask, a server found running = user-started → ask -before killing), via `memory.sh -C`, on a `chore/*` branch of that repo, text -shown to the user first. The other four are dropped (already in registries, -or contrary to doctrine). The user removes the auto-memory dirs by hand. -`lib/doctor-automem.sh` + suite: doctor warns while any -`~/.claude/projects/*/memory/` holds a file. - -## Proofs - -- New suite `lib/tests/user-rules.test.sh`: every `rules/*.md` frontmatter - parses (one-line JSON `paths:` or none); the always-on set is exactly - writing-style + secure-by-default; flip controls (two-line `paths:`, an - extra always-on file). -- Census extension (`lib/tests/doctrine-citers.test.sh`): citations of - `rules/<f>.md § Label` and `lib/<f>.md § Label` resolve against that file's - headings; flip-tested. -- New suite for the session-start graphify branch (graph present / absent). -- `lib/tests/doctor-automem.test.sh` (empty → silent, one file → warn, count). -- Controller proof (journaled, not in make test): `project-rules.sh -C - <project> matches <glob>` per new glob in a real project; one headless - session per moved path rule whose prompt names the Read tool, logged - `path_glob_match` (faunosteo supabase, game supabase/functions, a UI file); - `/context` after vs baseline. - -## Cleanup and citers - -lib/project-rules.sh:22-23 comment (engine matching is gitignore-style: -trailing `/**` dropped, any depth, hidden dirs included; evidence -InstructionsLoaded `globs: ["rules"]` on `.claude/rules/*.md`); -.claude/rules/rules-maintenance.md (always-on exception list, the -"always-on doctrine stays in CLAUDE.global.md" sentence, matching note); -lib/design-gate.md:48 (stale "+motion / +static" citation); -lib/project-archetypes/rest-api-node.md:58; CLAUDE.global.md Higgsfield line; -hooks/session-start.sh BDR-031 comment; TODO.md phase 1 checked + follow-ups. -CLAUDE.global.md ends ≤ 320 lines. - -## Out of scope - -/refactor edits; the four vendored `impeccable-*` agents; the per-repo memory -v2 upgrade pass; settings.json `model`/`theme` lines written by the user's -`/model` (left uncommitted, user decides). - -## Risks - -- `autoMemoryEnabled: false` may also affect the analyzer's `memory: - project`: checked during the proof, not promised. -- Engine glob semantics differ from compgen: the static suite proves parsing - only; loading is proved by the logged sessions. -- `**/functions/**` also fires in non-cloud `functions/` dirs (≈80 tokens of - noise there), accepted. -- `gitflow finish` refuses while the user's settings.json hunks are - uncommitted (this branch changes settings.json): the user commits or - stashes them first; never a checkout of the live file.