50 KiB
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/claudeonfeature/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. Nevergit 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 nameCLAUDE.global.md(BDR-064). - Foreign-style repo: match the neighbouring code (inline shell,
check()test idiom,PASS=%s FAIL=%sfooter, 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 fullmake test. shellcheck:shellcheck *.sh hooks/*.sh lib/*.sh(+ any newlib/tests/*.shyou create). - Bash pitfalls: no
headreading a producer under pipefail (SIGPIPE rc 141); a sourced lib never changes the caller's shell options. settings.jsoncarries 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
- A real user prompt that starts with
<(pasted content:<pasted_content>…) must still fire the design hook; only<task-notification>and<agent-messageturns are skipped. Pinned: Task 1 F11. - session-start run from a subdirectory of a repo whose root holds
graphify-out/graph.jsonprints the usage block; run outside any git repo it prints none and does not error. Pinned: Task 2 T3, T5. - 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. - 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. - The settings.json commit must carry only the
autoMemoryEnabledline, the user's/modelhunks 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 ofrules/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
H="$(cd "$(dirname "$0")/../.." && pwd)/hooks/design-toolchain-reminder.sh"
pass=0; fail=0
with
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
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
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
# 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
# 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
# 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
# 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## graphifyfollows the Skill-routing block's last lineoffice-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
has "CLAUDE.global.md" 'route to `reflect` (high) through their'
with
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
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(## graphifysection, 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 finalecho "") - Modify:
lib/tests/graphify-gate.test.sh(new S-checks before its finalecho "PASS=…")
Interfaces:
-
Produces: when
$(git rev-parse --show-toplevel)/graphify-out/graph.jsonexists, session-start stdout carries, after the box, the block shown in Step 3 (first linegraphify (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):
# ── 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:
# 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
# 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
# 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
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 decisionsH1: intro +## Public websites — never SPA+## Web APIs — always versioned, ~142-167) - Modify:
rules/rest-api.md(## Versioning; the/api/tasksexample 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.mdheadings## Public websites — never SPA,## Default language — Rust,## Web APIs — always versioned;rules/rest-api.mdheading## Versioningwith 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.withPlural 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 frontmatterand endskeep rule bodies tiny.with (it nameslib/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`/.claude/lib/architecture-defaults.md`add5. `; replace Read `/.claude/templates/project-CLAUDE.md` and `/.claude/CLAUDE.md`.withRead `/.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
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`:withApply `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
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 nopaths:, 2 malformed) fromlib/project-rules.sh(sourced; it runs nothing when sourced). -
Step 1: Write the test
Create lib/tests/user-rules.test.sh:
#!/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
# dotglob makes `*` match dotfiles, which the engine's matcher skips: a
# glob that only hits hidden paths passes here but never loads),
with
# 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
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:
# _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:
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:
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:
# 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
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>/*/memorydirs holding ≥ 1 file; always rc 0. -
Step 1: Write the failing test
Create lib/tests/doctor-automem.test.sh:
#!/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:
#!/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
# shellcheck source=lib/doctor-skills.sh disable=SC1091
source "$REPO/lib/doctor-skills.sh"
add
# 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:
# ────────────────────────────────────────────────────────────
# 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:
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
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
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-*.shon 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, thenbash ~/.claude/lib/memory.sh -C ~/Documents/robin_petier add decision --title "<approved>" --status accepted --body-file <abs path>, memory commit perlib/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 inlib/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 headlessclaude -pper moved path rule naming the Read tool (faunosteo supabase file, gamesupabase/functions/*, a UI file) →path_glob_matchlines from~/.claude/logs/instructions-loaded.jsonl;claude -p "/context"vs baseline; analyzermemory: projectcheck after an analyzer dispatch. All journaled. If the analyzer memory turns out disabled byautoMemoryEnabled: 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 finishchecks 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. Nevergit checkout -- settings.json/ restore it (it is the live ~/.claude/settings.json). Tracked default stays"model": "opus","switchModelsOnFlag": true.