355 KiB
format, type, entry_prefix, schema, rules
| format | type | entry_prefix | schema | rules | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 2 | decisions_registry | BDR |
|
|
Decisions registry (BDR)
BDR-001 — Uniform --help helper via session-start hook (option C)
- Date: 2026-04-22
- Status: accepted
- Decision: every skill expose
--helpvia shared snippet injected by session-start hook, not duplicate helper in each SKILL.md. - Why: 25+ skills — keep same helper synced across every file guarantees drift. Single injection point = single source of truth.
- Alternatives rejected:
- Option A (copy helper into each SKILL.md) — rejected: maintenance entropy.
- Option B (external wrapper
/help <skill>) — rejected: breaks "one command = one skill" experience.
- Reference: commit
3968a29. - Won't-build (2026-06-30): accepted but never built. MEASURED before building — behavioral RED, 6 reps (
/web-validate+/harden, no instruction): 6/6 already render rich help AND stop without dispatching (even/hardendidn't start its audit). The intended behavior is already spontaneous (universal--helpconvention); the ONLY residual value of the global instruction = format CONSISTENCY across 6 divergent shapes — judged not worth ~5 lines in a BDR-031-compressed CLAUDE.md on a solo repo. Not "abandoned" — measured non-rentable. Per-skill option stays rejected (original Decision above). See LRN-080, LRN-075.
BDR-002 — Move tasks/ + introduce memory + audits under .claude/
- Date: 2026-04-23
- Status: accepted
- Decision: migrate
./tasks/to.claude/tasks/, create.claude/memory/(5 registries BDR/LRN/BLK/journal/EVAL) and.claude/audits/for AUDIT_* files. Adapt skills/agents/CLAUDE.md. Integrate CAPITALIZE step into completion skills (ship-feature, feat, bugfix, hotfix, commit-change), add/closeskill for session-end ritual. - Why: group all meta-project state (AI config + tasks + memory + audits) under
.claude/isolate Claude governance from real code. Aligned with official Claude Code memory docs. Without integration in completion skills, registries stay empty (aspirational text). - Alternatives rejected:
- Keep
./tasks/at root — rejected: clutters repo, mixes code signal with governance signal. - Use
.claude/agent-memory/for everything — rejected:agent-memory/has distinct role (already used by other tools). - Ritual as aspirational text only in CLAUDE.md — rejected: zero execution guarantee, registries stay empty.
Stophook to ask 3 questions every turn — rejected: too noisy.
- Keep
BDR-003 — Gitignore wildcard + negations pattern for .claude/
- Date: 2026-04-23
- Status: accepted
- Decision: use
.claude/*(wildcard match of immediate children) + negations!.claude/tasks/,!.claude/memory/, etc., not.claude/(recursive ignore). - Why: when parent ignored via
.claude/, git no descend (performance optimization) and negations on children ignored — documented ingitignore(5). With.claude/*, git matches each child individually, negations active. - Alternatives rejected:
.claude/+!.claude/tasks/(naive) — rejected: negations no effect, everything stays ignored.- Drop
.claude/from gitignore entirely — rejected:.claude/settings.local.jsonand.claude/agent-memory/must stay ignored (per-machine). - Track paths via
.gitattributesor external tool — rejected: over-engineering, git handles natively.
- Reference: commit
499cd07,git check-ignore -vverified on 4 paths (2 tracked, 2 ignored).
BDR-004 — Adopt auto permission mode as default
- Date: 2026-04-27
- Status: accepted
- Decision: set
permissions.defaultModeto"auto"in user-scopesettings.json, dropdisableAutoMode: "disable". Auto mode runs classifier on every action, blocks risky operations (curl|bash, prod deploys, force push, IAM grants, mass deletes, exfiltration to external endpoints), auto-approves local edits, lockfile-declared dep installs, read-only HTTP. - Why: prompt fatigue under
defaultmode big on multi-step autonomous work. Auto mode keeps safety net (classifier review) without per-tool friction. Classifier re-evaluates conversation-stated boundaries ("don't push", "wait for review") on every check, verbal constraints carry weight. - Alternatives rejected:
- Keep
default— too many prompts, breaks flow on long tasks. acceptEdits— eliminates prompts but no classifier, blanket trust on Bash beyond filesystem helpers.bypassPermissions— skips all checks, no prompt-injection guard. Only for isolated containers.dontAsk— full denylist, breaks anything not pre-approved. Suited to CI, not interactive work.
- Keep
- Caveats: requires Claude Code v2.1.83+, plan ≠ Pro (Max/Team/Enterprise/API only), Sonnet 4.6 / Opus 4.6 / Opus 4.7, Anthropic API provider. On entering auto mode, blanket allow rules (
Bash(*),Bash(python*), package-manager run,Agent) dropped, restored on exit. - Reference: commit
1421578.
BDR-005 — motion as default animation library; advisor stays read-only
- Date: 2026-04-27
- Status: accepted
- Decision: when project stack supports it, framework installs
motion(ormotion-vfor Vue 3 / Nuxt) as default animation library. Install automatic in/init-projectSTEP 5e (post-scaffold), opt-in in/onboardSTEP 2.5 (existing projects).plugin-advisoronly detects and reports status — never runsnpm installitself. Detection logic inlib/animation-lib-check.sh(sourced by all three layers). - Why: framer-motion rebranded
motionin November 2024 (single package supporting Reactmotion/react, Svelte, vanilla JS;motion-vparallel package for Vue). Bake new name now to avoid legacy-import sprawl across new projects. Split init-vs-onboard behavior follows trust gradient: at init, user just validated entire scaffold so silent install fine; at onboard, touching existingpackage.jsoninvasive without explicit consent. Plugin-advisor kept read-only to preserve "Never modify files" contract (PHASE 4 already mutates plugin state with confirmation; piling npm installs on top blurs responsibility). - Alternatives rejected:
- Pin
framer-motion(legacy name) — rejected: package in maintenance mode, every new project inherits old import path. - Auto-install during
/onboardwithout asking — rejected: silently adds runtime dep + ~50 KB gzip to project user did not ask to modify. - Make
plugin-advisorinstall missing libs — rejected: violates read-only spec, breaks separation of concerns (advisor advises; orchestrators mutate). - React-only scope — rejected: Vue/Svelte teams should benefit;
motion-vmakes Vue case clean.
- Pin
- Eligibility rules (helper output):
eligible|motion: React, Next.js, Remix, Astro+React, Svelte/SvelteKiteligible|motion-v: Vue 3, Nuxtno|-: backend, CLI, embedded, Flutter, static HTML, React Native (usereact-native-reanimated), Astro without UI integration, nopackage.json
- Reference: helper at
lib/animation-lib-check.sh; integration inskills/init-project/SKILL.mdSTEP 5e,skills/onboard/SKILL.mdSTEP 2.5,agents/plugin-advisor.mdPHASE 1/2/3,lib/design-gate.md.
BDR-006 — Caveman as 4th always-on plugin (output compression)
- Date: 2026-05-03
- Status: accepted
- Decision: install
JuliusBrussee/cavemanin always-on tier alongsidesecurity-guidance,superpowers,rtk. "Full" install = plugin (/caveman+ cavecrew agents + plugin-scoped SessionStart/UserPromptSubmit hooks) + standalone hooks (statusline + stats badge in~/.claude/hooks/) +caveman-shrinkMCP scaffold (NOT auto-registered — proxy needs upstream wrapper).install-plugins.shSTEP 5.5 callsenable_plugin "caveman" "caveman"to write intoenabledPlugins. Hook paths insettings.jsonnormalized to~/.claude/hooks/...post-install so user home dir no leak across machines. - Why: caveman compresses Claude output ~75% via caveman-speak, preserves technical substance. Symmetrical with rtk (input compression hook) — rtk shrinks tool I/O, caveman shrinks model output. Both hooks pay zero passive cost in clean session, amortize across long runs. Always-on justified: plugin auto-deactivates with phrases like "stop caveman" / "normal mode", toggle would be friction without benefit.
- Alternatives rejected:
- Toggle plugin (start OFF) — rejected: misses by-default benefit; user need remember
claude plugin enable caveman@cavemanper session, negates auto-compression value. --minimalinstall (plugin only) — rejected: loses standalone stats badge surfacing token-saving telemetry.--allinstall (adds per-repocaveman-rules.mdetc. into$PWD) — rejected: would litter THIS config repo (cwd at install time) with rule files meant for project repos. Let users opt in per-repo when wanted.- Auto-register
caveman-shrinkMCP — rejected: proxy errors with "missing upstream command" without upstream MCP to wrap, fails health checks. Print snippet instead, let user pick which upstream they want compressed (filesystem, github, …).
- Toggle plugin (start OFF) — rejected: misses by-default benefit; user need remember
- Caveats:
- Caveman
hooks/install.shwrites absolute paths ($HOME/.claude/hooks/caveman-*.js) intosettings.json.settings.jsonsymlinked into repo, absolute path commits username. STEP 5.5 runs Python post-process to rewrite to portable~/.claude/hooks/...form (bash expands~before passing tonode). - Caveman hook files materialize in
hooks/(repo dir, not~/.claude/hooks/) because latter is symlink. Added to.gitignoreto prevent accidental commit of user-scope state.
- Caveman
- Reference: install-plugins.sh STEP 5.5, lib/detect-plugins.sh
detect_caveman*+plugin_enabled, doctor.sh caveman block, commit9b20b84.
BDR-007 — Skill profiles partition gstack by usage (design / dev / qa / audit / minimal)
- Date: 2026-05-04
- Status: accepted
- Decision: ship
lib/profile.sh+lib/profiles/*.profileto give user fine-grained, task-shaped activation of skills. Profile = plain-text file listing skill names + types (gstack,external,personal,plugin,mcp).profile set <name>enables listed skills, disables every gstack-origin skill not in profile, by moving symlinks betweenskills/andskills-disabled/.profile resetre-enables all of gstack. Plugin/MCP entries advisory — script prints manualclaude plugin enable/claude mcp addcommand but never runs it. Surface area: one CLI (bash lib/profile.sh), one slash command (/profile), four Makefile targets, section inagents/plugin-advisor.md. - Why: when user works on focused kind of task (design only, qa only, audit only) full gstack (~38 skills) injects irrelevant skill descriptions into every session. Existing
lib/toggle-external.sh enable|disable gstacktoo coarse — disables whole gstack including infrastructure skills user does want (checkpoint, ship, learn). Profiles give curated middle ground: keep gstack repo installed, hide skills not relevant to this session. - Alternatives rejected:
- Fork SKILL.md files to strip ~70-line gstack preamble — rejected: every gstack upgrade needs re-fork, preamble already degrades gracefully (
|| true) whengstack/bin/unavailable. Hiding skill cheaper than rewriting. - Per-skill toggle via
claude plugin enable/disable— rejected: gstack skills not marketplace plugins, symlinks owned byskills-external/gstack/. CLI no reach them. - Disable via removing symlinks (rm + recreate on enable) — rejected: lossy if user has local edits, re-creation requires running gstack own setup. Move-based toggle preserves symlink intact.
- Auto-toggle plugins (
ui-ux-pro-max) and MCPs as part ofset— rejected: those affect global Claude Code state, may carry API keys (magic). Keep advisory; user runs CLI command knowingly. - Build giant
gstack-profileCLI wrappinggstack/bin/*directly — rejected: scope creep into gstack internals. Repo already has own toggle infra (lib/toggle-external.sh); profile.sh sits alongside as finer tool.
- Fork SKILL.md files to strip ~70-line gstack preamble — rejected: every gstack upgrade needs re-fork, preamble already degrades gracefully (
- Caveats:
- Profiles do NOT change
gstack/bin/infrastructure — preamble in disabled skills still references it, re-enabling restores normal behavior. No telemetry/learnings data touched. cmd_setonly auto-disables skills returned bygstack_skills()(those withSKILL.mdunderskills-external/gstack/*/). Personal skills (real dirs inskills/) never auto-disabled byset— only added back if listed in profile.cmd_currentreturns "full" when nothing disabled, even if profile happens to be 100% covered by current state. Active-profile heuristic requires at least onegstack__*entry inskills-disabled/so we no lie about profile being "set" when nosetever ran.- Personal skills use
external-style move (nogstack__prefix) so name-collision with gstack skills cannot happen during disable.
- Profiles do NOT change
- Reference:
lib/profile.sh,lib/profiles/{design,dev,qa,audit,minimal}.profile,skills/profile/SKILL.md,agents/plugin-advisor.md(DETECT block + TOGGLING EXTERNAL TOOLS section),Makefiletargetsprofile*,lib/toggle-external.shheader pointer.
BDR-008 — Profile system v2: extend to plugins + MCPs + CLIs (web/seo/web-full/backend)
- Date: 2026-05-04
- Status: accepted
- Decision: extend
profile.shto actually toggle Claude plugins (claude plugin enable|disable <name>@<marketplace>) and MCP servers (delegated tolib/toggle-external.shformagicMCP, advisory for others), add CLI status reporting. New profile syntax usesplugin@<marketplace>so script knows where to enable from. New profiles shipped:web(frontend website),seo(SEO/GEO/W3C audit),web-full(web + seo combined),backend(API/system dev — no design, no SEO). Reverted v1 decision (BDR-007 alternative #4 "advisory only for plugins/MCPs"): user explicitly asked for actual toggling soset webactively enablesui-ux-pro-max+magic,set seoactively disablesui-ux-pro-max. Always-on plugins (caveman,security-guidance,superpowers) protected by both allowlist (MANAGED_PLUGINS) and denylist (PROTECTED_PLUGINS). - Why: v1 profiles only managed skills (symlink toggle). User feedback: "active TOUT le splugins necessaire pour tel profile et desactive les autre". Pure-skill toggling left ui-ux-pro-max/magic always loaded regardless of profile, passive token cost no drop as much as expected when switching to non-design profile. Auto-toggling plugins shifts design from "show me right skills" to "set up right session" — closer to what user actually wants.
- Alternatives rejected:
- Keep plugins advisory + add
--apply-pluginsflag — rejected: user has to type flag every time, defeats "switch profile to switch context" workflow. - Disable ALL non-listed plugins (including third-party user-installed ones) — rejected: too aggressive. Profile system has no business touching plugins user installed for own reasons. Solution: explicit
MANAGED_PLUGINSallowlist (currently 3 entries) — script touches only those. - Treat MCPs identically to plugins (auto-toggle any MCP) — rejected: MCPs typically need env vars / API keys / specific commands. Auto-registering with wrong config produces broken MCPs (LRN-006). Compromise: auto-toggle ONLY
magicbecause already have its config inlib/toggle-external.sh. Other MCPs stay advisory. - Track plugin state across
set/resetcycles, restore on reset — rejected: complexity not worth it.resetre-enables gstack skills only. To re-enable managed plugin, user runsapply <profile>or explicitclaude plugin enablecommand. Documented ininfoline printed at end ofreset.
- Keep plugins advisory + add
- Caveats:
MANAGED_PLUGINShardcoded — adding new toggle-managed plugin requires editingprofile.sh. Acceptable for now (3 entries, rarely changes); revisit if grows.claude plugin enablereturns success even for already-enabled plugins, parser greps for "enabled|already" in stdout/stderr. Works on current Claude CLI; brittle if CLI rewords messages. Acceptable risk.currentheuristic now countsinstalled(CLI status) as available. Without that, profiles listing CLIs would never reach 100% match. Tiebreaker: when two profiles tie on %, larger total wins (web-full > web > design when all are 100%).cmd_showwidened TYPE column to 30 chars to fitplugin@ui-ux-pro-max-skillwithout breaking alignment.mcp magictoggle delegates tolib/toggle-external.sh enable magicwhich requiresMAGIC_API_KEYin.env. If key missing, profile.sh prints info line and continues — rest of profile still applies.
- Reference:
lib/profile.sh(MANAGED_PLUGINS/PROTECTED_PLUGINSarrays,skill_statusplugin@/cli/mcp branches,enable_skill/disable_skillplugin@ + mcp branches,cmd_setplugin disable loop,cmd_currentavailable-counting),lib/profiles/{web,seo,web-full,backend}.profile, refinedlib/profiles/{design,dev,qa,audit}.profile(useplugin@<marketplace>syntax +clientries),skills/profile/SKILL.md(updated profile table + mechanism table),agents/plugin-advisor.md(extended profile recommendation table).
BDR-009 — Mandate caveman format on .claude/memory/ registries
- Date: 2026-05-05
- Status: accepted
- Decision: all writes to
.claude/memory/*.md(decisions, learnings, blockers, journal, evals) MUST use caveman style — drop articles (a/an/the), drop filler (just/really/basically/actually/simply), fragments OK, short synonyms (big not extensive, fix not "implement a solution for"). Keep technical terms exact, code blocks unchanged, error messages quoted exact, IDs (BDR-XXX, LRN-XXX, BLK-XXX, EVAL-XXX) and dates unchanged. Pattern:[thing] [action] [reason]. [next step].Rule added toCLAUDE.md"Memory registries" section. Applied retroactively to existing 5 registries via/caveman:compress. Pre-compression backups saved as*.original.md(gitignored). - Why: registries loaded every session start (per CLAUDE.md "Session start" step 1) — every token compressed cuts permanent input cost. Measured ~40% input-token reduction across 5 files (164→97 lines on average per registry). Caveman style preserves all technical substance (code, IDs, error strings, refs) while dropping prose padding that no engineer needs at re-read. Rule mirrors English-only rule that already governs registries — both about read-efficiency, not aesthetics.
- Alternatives rejected:
- Compress only on new entries, leave existing prose untouched — rejected: every session-start still pays 40% prose tax on legacy entries (largest part of file). Mixed-style file harder to scan than uniform compressed file.
- Use lighter compression (drop only fillers, keep articles) — rejected: half-measure. Caveman lite saves ~15%, full saves ~40%. Cost identical (one /caveman:compress run).
- Move registries to JSON/YAML for max density — rejected: registries are narrative (BDR rationale, LRN context). YAML/JSON would lose nuance, force schema rigidity. Caveman keeps prose readable, just compressed.
- Skip rule, rely on writers to compress organically — rejected: untested writers (skills, future agents) revert to verbose prose. Explicit rule + caveman-mode-active hook ensures consistency without per-skill enforcement.
- Caveats:
- Code blocks, error strings, commit refs, IDs, dates, file paths MUST stay byte-exact — caveman applies to prose only.
- User-facing CAPITALIZE prompts may stay verbose / mirror user language; rule applies only to written entry.
*.original.mdbackups gitignored (BDR-009 commit639486a) — recoverable via git history of pre-compression commit.- Existing registries entries compressed in commit
e4a9259; new entries written caveman from start (BDR-009 itself is first such entry).
- Reference:
CLAUDE.md"Format — registries ALWAYS caveman" section, commits520188a(rule added),e4a9259(5 registries compressed),639486a(gitignore backups).
BDR-010 — Gate GEO independently at ≥17/20 in client-handover pipeline
- Date: 2026-05-07
- Status: accepted
- Decision: client-handover gates SEO classique AND GEO (IA) independently — both must reach
≥17/20. Was: combined display only, gate fired on first/20line found (de facto SEO classique alone). Now:ALL_PASS = (SEO_AFTER ≥ 17) AND (GEO_AFTER ≥ 17) AND (HARDEN_AFTER ≥ 17) AND (VALIDATE_AFTER ≥ 17 OR SKIPPED). SEO subagent re-dispatched if either axis below threshold (same agent fixes both). Score table + roadmap + client doc §4 split rows accordingly. - Why: handover deliverable claims "site ready" — bar must hold on classical search (Google/Bing) AND AI search (ChatGPT/Perplexity) given AI traffic growth. Combined gate (e.g. global pondéré ≥17) lets GEO stay weak while combined passes — false confidence shipped to client. Independent gates close gap.
- Alternatives rejected:
- Gate on
Score global pondéré ≥17only — rejected: SEO=20 + GEO=10 → global=18 → passes despite GEO=10. Same false-confidence issue. - Keep GEO informational (Phase A initial design) — rejected: breaks "every gated audit ≥17 or stop" rule. Two-tier system (gated vs informational) confuses client + breaks score-table semantics.
- Lower GEO threshold to ≥15 — rejected by user: weakens signal. Real fix is optimize GEO, not lower bar.
- Split into two parallel subagents (one SEO, one GEO) — rejected: /seo skill runs both inside one envelope-merge dispatcher. Splitting at handover layer duplicates context discovery (STEP 0) + doubles wall-clock.
- Gate on
- Caveats:
- GEO ≥17 hard on existing sites — most lack llms.txt, Speakable/QAPage Schema, entity SEO (sameAs/Wikidata @id), TL;DR/Q→A content shape. Expect more fix-loop iterations on GEO than SEO. Override option C still per-axis with explicit user consent.
SCORE_GEO_AFTER = "UNKNOWN"treated as fail — legacy single-score SEO.md triggers re-dispatch with explicit demand for both labeled lines (Score SEO (classique) : X.X / 20+Score GEO (IA) : X.X / 20).- Backward compat split:
extract_score_labeledSEO usesallow_fallback=yes(legacy single-score parses as SEO classique); GEO usesallow_fallback=no(no silent duplicate of SEO score). - Loop logic axis-aware:
while (SEO < 17 OR GEO < 17) AND iter ≤ MAX. Re-dispatch prompt labels both scores with PASS/FAIL + lists axis-specific fixes (SEO: meta/canonical/sitemap; GEO: llms.txt/Schema AI/entity SEO).
- Reference: commit
5569a80,agents/client-handover-writer.md(STEP 3extract_score_labeled, STEP 4 axis-aware loop + re-dispatch prompt, STEP 8 gate rule + score table + threshold strictness, STEP 12 §4 client doc table),skills/client-handover/SKILL.md.
BDR-011 — Client handover deliverable: 4-chapter structure + ZenQuality branded HTML/PDF
- Date: 2026-05-07
- Status: superseded by BDR-013
- Decision: client handover doc restructured to 4 chapters — §1 Ce qu'il fallait faire (et pourquoi) (briefing+motivation, 100–180 words), §2 Ce qui a été fait (lay summary, ≤300 words hard cap, zero jargon, no internal tool/skill names), §3 Ce qui vous reste à faire (action-only checklist with cadences), §4 Détails techniques (pour les curieux) (scores, key choices, phases, optional glossary — internal labels allowed here only). Plus optional §5 (external platforms, web), §6 (build & deploy). Replaces old 9-section structure. Output now triple:
LIVRAISON.md(editable source) +LIVRAISON.html(always, branded) +LIVRAISON.pdf(when PDF engine on host). HTML/PDF use ZenQuality identity — green palette#1A3A25 / #2D5A3D / #4A7C59 / #87A878, cream BG#F5F0EB, fonts Inter (body) + Playfair Display (headings), cover page with logo + tagline "La sérénité numérique, la qualité en plus", running header (project name) + footer (page N/M,ZenQuality — zenquality.fr). Renderer cascade: MD→HTML via pandoc > python markdown >npx marked; HTML→PDF via weasyprint > wkhtmltopdf > chromium > headless Chrome. STEP 15 enforces gates before render: chapter 2 word count ≤300 (wc -w) AND forbidden-token grep on chapters 1–3 (no/seo,/harden,/validate,/cso,seo-analyzer,SEO.md,SCORE_*, etc.). - Why: client reads top-down, may stop after §2 — old 9 sections diluted the read. Bare markdown unreadable by non-tech client. Branded PDF = professional deliverable matching company identity (ZenQuality), suitable to email/print/sign. Per-section gates prevent regression to skill-name leaks or jargon bloat.
- Alternatives rejected:
- Keep 9-chapter structure + bolt PDF wrapper on top — rejected: doesn't fix dilution + leak risk; client still scans through "Lessons learned (optional)" / "Pour aller plus loin" before useful actions.
- Render PDF only (no HTML intermediate) — rejected: no fallback if engine missing; HTML doubles as browser preview + manual print-to-PDF route. Triple output (
md+html+pdf) covers all cases. - Single PDF engine (e.g. weasyprint only) — rejected: assumes Python installed; cascade gives graceful degradation. Order chosen: weasyprint (best CSS), wkhtmltopdf (mature), chromium (always-bundled on dev hosts).
- Pandoc with custom template only — rejected: pandoc often not installed (was missing on this host); shell cascade with multiple converters more portable.
- Soft 300-word target — rejected: without hard
wc -wgate, drift inevitable. Cap+gate forces rewrite when over.
- Caveats:
- Word-count + leak gates run at STEP 15 after synthesis, not during. Worst case: re-write step needed. Acceptable trade-off vs in-flight enforcement (would require word counter inside agent prompt — fragile).
- ZenQuality logo URL hardcoded as
https://zenquality.fr/logo-horizontal.svg;LOGO_URLenv var allows local file override (bake into PDF for offline robustness if branding changes / SVG breaks). - PDF cascade detects via
command -vonly — assumes engines on$PATH. Custom installs need$PATHadjusted before invocation. - Bash heredoc + stdin-pipe collision bug in v1 (silent empty output) — fixed via env-var pass-through (LRN-012).
- Renderer always outputs HTML + tries PDF; on PDF failure exits 2, prints install hints. STEP 16 reports
PDF: NOT GENERATEDwith hints in final report. - Optional glossary in §4.4 listed terms (HSTS, CSP, WCAG, Schema.org, llms.txt, SEO/GEO) — only renders if ≥4 of these appear in §4 body.
- Reference: commit
e06b52a,agents/client-handover-writer.md(STEP 12 4-chapter doc structure + tone rules, STEP 15 word-count + leak gates, STEP 16 RENDER pipeline, STEP 17 final report),skills/client-handover/scripts/handover-to-pdf.sh(cascade renderer),skills/client-handover/resources/branding/zenquality.css(ZenQuality print stylesheet),skills/client-handover/resources/branding/zenquality-template.html(HTML wrapper with placeholders).
BDR-012 — client-handover cover: white bg + green accents + PNG logo default
- Date: 2026-05-07
- Context: original
.coverCSS used cream--white-cream(#F5F0EB) bg + 8mm green stripe top. Washed out. SVG logologo-horizontal.svgblended into cream bg = low contrast. User feedback: "couleur du fond n'est pas bon", "utiliser une icone non white". Tried green-dark bg first (rejected — too heavy for client-facing doc, hurt readability of long meta block). - Choice:
.coverbg →--white-purewith two subtle radial tints (sage top-right rgba(135,168,120,0.18), green-forest bottom-left rgba(45,90,61,0.06)). Body text →--black-deep. Title--black-deep. Eyebrow/meta labels/footer →--green-forest(medium green). Meta border-left + meta-strong →--green-forest. Removed.cover::before8mm stripe. DefaultLOGO_URL→https://zenquality.fr/assets/logo-horizontal-1024.png. - Alt rejected: (a) cream
#F5F0EBbg — washed-out, original problem. (b) solid green-dark bg — too heavy, hurt long-text readability, felt like marketing brochure not deliverable. (c) generic white + black — no brand signal. - Why: light theme with green accents matches zenquality.fr without overpowering. White bg keeps long client-facing text readable. Green-forest on white = WCAG AA contrast + brand cue. Subtle radial gradients add depth without weight.
- Status: shipped.
- How to apply: ZenQuality client-facing print docs default to white bg + green-forest accents. Body interior keeps cream
--white-creamas accent (code blocks, blockquote bg) — not as page bg. Solid green-dark reserved for marketing covers, not deliverables. - Reference:
skills/client-handover/resources/branding/zenquality.css.coverblock (line 71-86 bg, 119-149 typography);scripts/handover-to-pdf.shline 107 (LOGO_URL default);agents/client-handover-writer.mdline 1218-1222 (doc updated).
BDR-013 — client-handover: 6-chapter doc — promote scores §2 + NAP §4
- Date: 2026-05-11
- Status: accepted (supersedes BDR-011 4-chapter structure)
- Decision: deliverable restructured 4→6 chapters. §1 brief+why (100–180 words). §2 NEW = score table (avant/après) promoted from old §4 technical annex to top of doc. §3 = lay summary ≤300 words zero jargon (formerly §2). §4 NEW = NAP single-source-of-truth table (Nom/Adresse/Téléphone/Email/Catégorie/Description courte/Horaires) promoted from §7 annex. §5 = action checklist by cadence (formerly §3). §6 = tech details for curious (formerly §4, score table removed — now in §2). §7/§8 still optional annexes (external platforms, build+deploy).
- Why: local-business client opens deliverable, scans first 30s — needs immediate visual proof of impact (scores §2) before reading prose. Tested with handover clients: scores up-front converts "what did I pay for?" doubt within 30 seconds. NAP §4 prerequisite chapter before §5 todo list — client's todos reference NAP values constantly ("create Google Business with these values"); if NAP buried in §7 annex, client scrolls deep mid-todo, types inconsistent values across platforms, degrades Google NAP-consistency signal.
- Alternatives rejected:
- Keep 4-chapter + add score sentence inside §2 prose — rejected: lost the visual proof-of-impact moment, table reads stronger than prose.
- Keep NAP in §7 external-platforms annex — rejected: client types 10 different descriptions/addresses while working through §5 todos before reaching §7.
- Compact 3-chapter doc with scores+NAP inline — rejected: too dense, kills lay-summary flow + chapter 3 word-count gate harder to enforce.
- Two-doc deliverable (summary PDF + NAP/todos PDF) — rejected: doubles attachments, client opens only one.
- Caveats:
- Forbidden-token grep gate at STEP 15 now covers §1–§3 (was §1–§3 already, no change). §4 NAP table contains only client input placeholders [À COMPLÉTER] — no tool/skill leak risk.
- Pandoc requires
gfm+gfm_auto_identifiersextension to resolve[§4](#nap)internal links (LRN-014). - §2 score lecture-rapide must stay plain French — numbers OK but no internal labels (
Score SEO classiqueallowed because vulgarized;seo-analyzer/SEO.mdforbidden).
- Reference: commit
b15b275,agents/client-handover-writer.md(chapter list lines 20–60, prose framing §2 + §4 rationale lines 30–55, STEP 12 template),skills/client-handover/scripts/handover-to-pdf.shline 121 (pandoc gfm_auto_identifiers).
BDR-014 — Personal SKILL.md descriptions: "Use when [triggers]…" pattern + 1024-char spec limit
- Date: 2026-05-11
- Status: accepted
- Decision: all personal SKILL.md descriptions must follow
Use when [specific triggering conditions and symptoms]pattern. Workflow summaries forbidden in description (e.g.Ship feature: design → plan → implement → review). Frontmatter total ≤1024 chars per agentskills.io spec. Workflow detail belongs in SKILL.md body, not description. Triggers list compressed and deduped. - Why: superpowers:writing-skills documented (with test evidence) that workflow summaries in description create shortcut risk — Claude reads description, treats it as the skill, and skips reading the body. Test case: description "code review between tasks" caused Claude to do ONE review when skill flowchart had TWO. Removing workflow summary → Claude read flowchart, did 2 reviews. Description's job is to TRIGGER retrieval, not to BE the skill. 1024-char cap is the platform spec limit (agentskills.io/specification); 5 personal skills (client-handover, doc, seo, geo, validate) were 1050–1920 chars — non-compliant.
- Alternatives rejected:
- Free-form descriptions (status quo) — rejected: drift + shortcut risk, 5 skills already spec-violating.
- Hard cap ≤500 chars per writing-skills target — preferred for new skills but hard retrofit on multi-language trigger lists (FR+EN keywords blow past 500). Use 1024 as enforced ceiling, ≤500 as aspirational.
- Per-skill judgment with no rule — rejected: inconsistent, no enforcement gate.
- Move trigger keywords to body — rejected: triggers in description is what Claude uses for routing; body content doesn't help routing.
- Caveats:
- Orchestrators still describe orchestration role explicitly (e.g. client-handover: "Multi-agent orchestrator: dispatches the client-handover-writer agent which spawns parallel /seo + /harden subagents") — that's role identification, not workflow summary.
- Other 10 personal skills (analyze, bugfix, code-clean, commit-change, feat, hotfix, plugin-check, refactor, status, skills-perso) still partially summarize workflow but stay under 1024 chars. Not retrofitted in this pass — flagged for follow-up only if shortcut symptoms observed.
- Reference: commit
1da6a31, 8 SKILL.md files (client-handover, doc, geo, seo, validate, ship-feature, init-project, onboard), superpowers:writing-skills "CSO" section, agentskills.io/specification.
BDR-015 — Exclude broken gstack symlinks from /darwin-skill scope (external ownership)
- Date: 2026-05-12
- Status: accepted
- Decision: 5 dirs in
~/Documents/claude/skills/whoseSKILL.mdsymlinks point to non-existent gstack paths (skills-external/gstack/<name>/SKILL.mdmissing) —benchmark-models,context-restore,context-save,make-pdf,plan-tune— are excluded from/darwin-skillbaseline + optimization. Markedstatus=errorinresults.tsvwith notebroken gstack symlink — out of scope. NOT scored, NOT optimized, NOT deleted. - Why: darwin-skill constraint #1 forbids changing a skill's core function — implies external/gstack-owned skills are out of scope. Symlinks resolve to
skills-external/gstackwhich is third-party submodule. Plus the targets are broken — gstack's actual layout (benchmark/,health/,qa/, etc.) doesn't include these 5 names, suggesting upstream rename or removal. Repairing them is a separate triage task, not darwin's concern. - Alternatives rejected:
- Fix symlinks first then darwin-optimize → out of scope, blocks the optimization queue on gstack archaeology.
- Score them with
FILE_NOT_FOUNDand include in averages → biases stats, mixes signal with infrastructure issue. - Optimize the gstack source files directly → external ownership, never modify.
- Delete the broken symlinks → would obscure that the user once expected these to exist; leave for triage.
- Caveats:
- If/when symlinks are repaired (real gstack target exists), re-run baseline to bring them in scope.
- Bigger picture:
benchmark-modelslooks like a deliberate rename of gstack'sbenchmarkto disambiguate from the gstack-skill called/benchmark. Could be a planned migration that stalled. Worth a one-line ticket separate from darwin.
BDR-016 — doc-syncer: README AUTO+unconditional, DEPLOY.md prod-only + 14-section VPS template
- Date: 2026-05-15
- Status: accepted
- Decision:
agents/doc-syncer.mdSTEP 5/6/8/A4 rewritten. README creation now AUTO + unconditional in both interactive and AUTO modes. Validation gate offers onlyyesoreditfor README — noskip/no. Any project-level "no README" opt-out (e.g.CLAUDE.md"Exceptions: No README at scaffold") gets struck through during same patch. README template expanded: features, Stack, Quick start (dev), Verifying a change, Build & deploy, Documentation, License — all rendered from real manifest/.env.example/scripts data, no placeholders. DEPLOY.md becomes prod-only, expanded into 14-section VPS-deploy structure (topology table, env vars, VPS provisioning, two-layer firewall, Docker tuning, first-time setup, routine deploys, persistence, backups, TLS, observability, hardening, rollback, runbook). Dev quick-start lives ONLY in README "Quick start (dev)" section; mixed dev/prod DEPLOY.md flagged as drift, dev content proposed for move to README during same patch round. - Why: README opt-out makes repo look abandoned to anyone landing on it — universal "always render" beats opt-in. Mixed dev/prod DEPLOY.md was drift source: devs read DEPLOY for local setup, ops read DEPLOY for prod, both edit independently, conflicts pile up. Clean audience split — README = dev + features audience, DEPLOY = ops + SRE audience — gives each doc one owner mental model. 14-section VPS template mirrors real Scaleway/Hetzner/OVH/DO/Vultr deploy shape (reference: Scaleway DEV1-S walkthrough) so the doc maps 1:1 to the runbook ops actually execute.
- Alternatives rejected:
- Keep README gated on HUMAN approval (status quo) — rejected: opt-outs proliferated, repos shipped with no README. Friction wins.
- Single ARCHITECTURE+DEPLOY doc — rejected: mixed-audience doc is the drift source we're fixing. Don't recombine.
- Trim DEPLOY.md to single "Production" section — rejected: real VPS deploys need topology + firewall + Docker tuning + backups + TLS + observability. Single section becomes wall-of-text nobody reads.
- Optional README in AUTO mode (default skip) — rejected: AUTO mode purpose is friction removal. README is most-missed doc; auto-render it.
- Auto-write the README without surfacing draft — rejected: rendered draft still shown at validation gate so user can
editbefore write. "No skip" ≠ "no review".
- Caveats:
- Real-project-data rule still binds — license = "Not specified — set one before public release" (explicit gap, not fabricated SPDX).
- 14-section DEPLOY template drops sections that don't apply (e.g. "Managed DB" if no DB). Template = ceiling not floor.
- If
DEPLOY_COMPLEXITY == TRIVIAL, no DEPLOY.md created — deploy stays in README. Threshold = no Docker + no compose + no fly.toml + no k8s + no scripts/deploy.* → trivial. - Existing DEPLOY.md with
Local development/Dev setupsection → surfaced as drift, content moved to README, section removed from DEPLOY. Not a silent rewrite.
- Reference: commit
7ee9b42,agents/doc-syncer.mdSTEP 5 (README mandatory clause + template lines 223–335), STEP 6 (14-section DEPLOY.md template lines 338–541), STEP 8 (validation gateyes/editfor README,yes/no/editfor HUMAN), STEP A4 (AUTO MODE README-missing → SIGNIFICANT). Linked to doc-syncer-two-doc-split (LRN-019).
BDR-017 — full profile = web-full + plan + dev superset for /init-project MVP
- Date: 2026-05-18
- Status: accepted
- Decision: New
lib/profiles/full.profilecovers brainstorm → design → architecture review → scaffold → implement → ship → audit pipeline in one profile. Superset ofweb-full(design + dev + seo/geo/validate/harden + perf) plus plan-mode reviews (office-hours, plan-ceo/eng/design/devex-review, autoplan), full dev stack (investigate, code-clean, land-and-deploy, setup-deploy, codex), full audit (cso), full QA (qa), docs (doc, document-release), session hygiene (close, prune-memory, status, learn, retro, careful/freeze/unfreeze/guard), andpr-review-toolkitplugin +gsdCLI. Sentinel "full" incmd_currentrenamed to "none" to avoid collision with profile name. - Why:
/init-projectorchestrates 13 steps that touch nearly every skill family — brainstorm, plan, design, scaffold, implement, ship, audit. Existing profiles only cover a slice (web-full = website end-to-end but no plan/dev breadth, dev = code only, audit = audit only). Without a maximal profile, init-project users must either runreset(everything on, noisy) or piece togetherapply web-full && apply dev && apply audit(3 commands). One named profile = one command = right tool for MVP scaffolding sessions. - Alternatives rejected:
- Extend
web-fullto absorb plan + dev — rejected:web-fullis "production website end-to-end"; init-project covers non-website projects too (CLI, library, backend MVP). Different semantic. - Make init-project profile-agnostic (just run with all skills enabled) — rejected: noise.
/profile resetexists for that; named profile gives explicit signal "this session is MVP-scale". - Multiple sub-profiles chained — rejected: 3
applycommands less ergonomic than oneset full; profile-of-profiles not supported by current schema.
- Extend
- Caveats:
fullexcludes a few rarely-used gstack skills (devex-review, pair-agent, gstack-upgrade, skills-perso).set fullwill disable those; user canapply <profile>after to add back.- Sentinel rename "full" → "none" is breaking for any tooling that grepped
cmd_currentoutput for literal "full". No known consumers in this repo.
- Reference: commit message references
lib/profiles/full.profile(new),lib/profile.sh:421sentinel,skills/profile/SKILL.mdtable row. Linked to profile-sentinel-collision (LRN-020). - Status (2026-11-16): superseded by BDR-134: full.profile -> lib/profiles/full.json = manifest defaults, default when no profile (BDR-101 policy); web-full dropped; content per BDR-105 (full includes other profiles, max = everything)
BDR-018 — profile gstack on|off verb keeps active-profile label
- Date: 2026-06-02
- Status: accepted
- Decision: New
cmd_gstack()inlib/profile.sh.gstack on= re-enable all parked gstack (moveskills-disabled/gstack__*back), DON'T touch.active-profile.gstack off= disable gstack skills not in active profile (errors if active=none). Wired intomain()dispatch +usage()+ header block +skills/profile/SKILL.md(argument-hint + examples + output-policy). - Why: User wanted central command for "enable all gstack" + "disable gstack not needed by profile". Both ops existed (
reset,set) butresetclobbers.active-profileto "none" — loses profile context in statusline. New verb does same skill-toggle WITHOUT clearing label, so user layers full gstack on top of current profile (e.g.dev) and statusline still readsdev. - Alternatives rejected:
- 3 new profiles (current+gstack, current+gsd, current+gsd+gstack) — rejected:
gsd= standalone CLI (not profile-toggleable, always-on, 0 passive token), so 2 of 3 meaningless.fullalready = current+gstack+gsd advisory.applyalready additive. - Just document
reset/set— rejected: user wanted clearer centralized verb + label preservation.
- 3 new profiles (current+gstack, current+gsd, current+gsd+gstack) — rejected:
- Impl note: extracted 3 shared helpers (
enable_all_gstack,disable_gstack_not_in,parked_gstack_count);cmd_reset+cmd_setrefactored to reuse (behavior preserved exact, verified by test). See dry-helper-extract-sibling-command (LRN-024). - Reference:
lib/profile.shcmd_gstack + helpers,skills/profile/SKILL.md. Linked to full-profile-superset-init-project (BDR-017), gstack-source-only-skills-unlinked (BLK-007).
BDR-019 — Remove disable-model-invocation repo-wide, align skills with CLAUDE.md routing
- Date: 2026-06-09
- Status: accepted
- Decision: Stripped
disable-model-invocationfrontmatter key from all 19 editableskills/*/SKILL.md. Absent key = default = model invocation ENABLED. 8 weretrue(blocked model + orchestrator routing:status,plugin-check,analyze,onboard,refactor,init-project,pdf-translate,ship-feature); 11 werefalse(already enabled, line was noise). - Why:
trueblocked model AND orchestrator from self-routing to those skills — contradicted CLAUDE.md "Skill routing" intent (e.g. "multi-file feature → ship-feature", "refactor → /refactor"). User hit it live: model detected feature intent, wantedship-feature, couldn't fire. Setting binary (no per-caller granularity) → enabling orchestrator-chaining also enables model auto-fire; accepted as the cost. - Alternatives rejected:
- Keep
trueon 4 heavy orchestrators (init-project,ship-feature,onboard,refactor) — rejected: "destructive" framing wrong.ship-featureonly commits + pushes a feature branch + opens PR (reversible, gated by internal STEPs); no prod deploy (that'sland-and-deploy/canary). Real destructive ops (rm -rf, force-push, prod deploy) guarded by careful/guard hooks INDEPENDENT of this flag — verified live (rm -rfblocked this session). Flag bought ~0 data-safety, only suppressed auto-fire (token/time cost) while breaking routing. - Remove only the 8
trueones — rejected: leaves 11 noisefalselines; uniform removal cleaner.
- Keep
- Durability: all 8 ex-
trueskills are repo-only files (not gstack submodule) → edits not clobbered on gstack upgrade. - Reference: 18
skills/*/SKILL.mdmodified +skills/capitalize/new. Linked to disable-model-invocation-false-not-blocking (LRN-026).
BDR-020 — /audit-delta design: per-axis SHA markers, always-on fix gate, unreachable-first-run = full report-only
- Date: 2026-06-11
- Status: accepted
- Decision: New skill
skills/audit-delta/SKILL.md— recurring multi-axis audit (conformity/errors/deadcode/security) scoped to delta since last run. 3 design choices: (1) state =.claude/audits/audit-delta-state.json, SHA marker PER AXIS (partial runs would desync single marker); (2) approval gate per axis ALWAYS fires — advance pre-auth ("fix what you find") never skips it, findings unknown at request time; user unreachable → audit + report only, no fix, marker still advances; (3) first-run axis + unreachable user → default full codebase report-only, never "from HEAD" (would skip entire existing codebase silently). Axis order fixed security→errors→conformity→deadcode (critical first, session-death safe). Re-verify = same-axis re-audit on modified files + project checks, lint alone insufficient. Built via superpowers:writing-skills TDD (RED 7 gaps / GREEN pass under pressure / REFACTOR 1 hole patched + re-tested). - Alternatives rejected:
- Extend
/code-cleanor/health— rejected: no recurrence state (health re-scans all, tracks scores not scope; code-clean one-shot), no multi-axis checkbox selection, cost not proportional to delta. - 4 separate skills (1 per axis) — rejected: user wants checkbox combo in one run; shared marker protocol + gate + re-verify loop would quadruplicate.
- Single global marker — rejected: run "security only" then "conformity" → conformity range wrong.
- Date-based boundary — rejected: drifts on rebase/timezone/amend (baseline agent failure, see LRN-027).
- Extend
- Reference:
skills/audit-delta/SKILL.md. Linked to periodic-skill-state-file (LRN-027), capitalize-skill (skill TDD precedent, BDR-019 era).
BDR-021 — CLAUDE.md restructure: contradiction purge, project-specific sections labeled, critical sections never compressed
- Date: 2026-06-12
- Status: accepted
- Decision: Full refactor global CLAUDE.md (commit
e7e9dac), Fable 5 audit. 4 contradictions resolved (2 graphify sections merged conditional on graph.json existing; "in doubt skip plan" no longer cancels plan mandate — borderline = single-file small obvious change; deviations minor/justified→after vs significant/shaky→before; append-only reconciled with /prune-memory). 3 dead refs fixed (/caveman-compress, design-gate → ~/.claude/lib/ portable, LESSONS note). Structure: Tooling & skills + "This repo only" top-level sections — Health Stack/routing/graphify no longer nested under Communication mode. Routing +8 skills + explicit gstack-OFF rule. Compression caveman on workflow/memory/routing ONLY: Architecture decisions + Security stay verbatim — ambiguity there costs more than tokens saved. Net -1471 chars despite added content. - Alternatives rejected:
- Compress whole file incl. Security/Architecture — rejected: precision > tokens on non-negotiable rules; misread security default = real damage.
- Split global vs repo-specific into 2 files — rejected: symlink setup (~/.claude/CLAUDE.md → repo) means 1 file everywhere; "This repo only" section header cheaper than 2-file sync.
- Delete graphify section (graph.json absent) — rejected: conditional phrasing keeps rules dormant-but-ready; regenerating graph re-activates without doc edit.
- Durability: heading "Design work — full toolchain (tiered by scope)" preserved verbatim — design-toolchain-reminder.sh quotes it. Norms 25/80/5/5 unchanged — audit-delta conformity axis cites them.
- Reference: CLAUDE.md, commit
e7e9dac. Linked to audit-delta-design (BDR-020), LRN-029 (exception edits need blanket-rule cross-ref — applied here).
BDR-022 — doc-syncer scoped to public docs only; .claude/ + CLAUDE.md read-only context
- Date: 2026-06-18
- Status: accepted
- Decision: Rewrote
agents/doc-syncer.md. Sync targets = PUBLIC docs ONLY: README, INSTALL, CONFIGURE, USAGE, DEPLOY, CONTRIBUTING, CHANGELOG, SECURITY, ARCHITECTURE, LICENSE, docs/**..claude/**+CLAUDE.md= read-only context: agent MAY read them to understand archi/features/constraints, NEVER modifies them, NEVER lists as targets, NEVER copies their content into a public doc. Removed STEP 4 blocks auditing TODO.md / audits/*.md / decisions-learnings-blockers. Added normative CONVENTIONS (Standard-Readme, Diátaxis doc-type split, Keep a Changelog + SemVer, Conventional Commits). README lean — dropped Status + Project layout, forbids roadmap/todo/internal-state, links to Diátaxis docs not duplicate. Added CLEAN mode (cleanarg) → propose removal of out-of-convention sections + copied-.claude/content from existing public docs, HUMAN-gated. Conserved: stack detection, 14-section DEPLOY gate, validation gate, AUTO/HUMAN tagging, never-invent, AUTO MODE (inputauto-mode scope:unchanged → callers unaffected). - Alternatives rejected:
- Keep
.claude/+CLAUDE.mdas sync targets (old behavior) — rejected: leaked internal state (TODO/roadmap/decisions) into public-facing docs; doc-syncer writing under.claude/blurred the read-only registry boundary (registries are/prune-memory-curated, not doc-synced). - Drop only
.claude/, keepCLAUDE.mdwritable (old strike-through README opt-out) — rejected: CLAUDE.md = agent config not public doc, absent from the modifiable-targets list; uniform read-only treatment cleaner. - Inline config table in README — rejected: violates Diátaxis (CONFIGURE.md = single config reference); README must link, not duplicate.
- Keep
- Reference:
agents/doc-syncer.md, commitedff761. Extends doc-syncer-readme-deploy-policy (BDR-016, README-AUTO + DEPLOY 14-section — conserved, not superseded).
BDR-023 — Merge /close into /capitalize — 2 modes + TODO reconcile; /close alias
- Date: 2026-06-19
- Status: accepted (supersedes /close-creation part of BDR-002)
- Decision:
/closemerged into/capitalize. capitalize 2 modes: default (pre-wipe flush) +--ritual(adds 3-question end-of-session reflection; trigger =--ritualflag OR "close"/"ritual" in$ARGUMENTS, OR/close). Both modes dedup (STEP 2) + reconcile.claude/tasks/TODO.md(new STEP 2B). STEP 2B: PASS A done-detection = restraint rule only (flip[ ]→[x]only on clean task↔commit map; partial/umbrella/vague stay unchecked, never guess); PASS B explicit-capture + anti-noise filter (never track commit/deploy/push/release/tag) + orientation-directive→decisions.md (BDR) routing. Ritual answers go thru dedup, footer shows existing ID — unlike legacy /close (wrote fresh). STEP 3 gate gains separate TODO block; journal+handoff report TODO ops. TODO stays plain prose (caveman = registries only)./closekept = thin alias →/capitalize --ritual, zero duplicated logic. - Why: /close + /capitalize overlapped (both flush session memory), /close never deduped → re-logged on re-run. 1 skill 2 modes kills dup + gives /close dedup; TODO reconcile = new capability. Alias file (not merged-triggers-only) because /close resolves by directory name — deleting dir breaks literal
/closecommand. - Alternatives rejected:
- Merged-triggers-only (drop close dir, fold triggers into capitalize desc) — breaks literal
/closecommand (dir-name resolution). - Keep 2 separate skills — duplication persists + /close never dedups.
- Merged-triggers-only (drop close dir, fold triggers into capitalize desc) — breaks literal
- TDD: built via superpowers:writing-skills. RED v1 baseline too easy (passed). RED v2 (pressured fixture: semantic dup + ambiguous umbrella task + parasite-as-task + orientation directive + rushed prompt) failed on anti-noise (folded push/tag into TODO) + invented subtask + no approval stop. GREEN passed. Gate STOP itself UNTESTED (non-interactive harness printed gate then proceeded "all approved") — flagged in skill Red flag + TDD note; verify on first real use.
- Reference:
skills/capitalize/SKILL.md,skills/close/SKILL.md, commits9dc2b83(skill) +be0f047(docs routing) +765e9d7(PASS A trim). Linked to BDR-002 (close created), BDR-019 (capitalize created), LRN-031 (skill-value lesson).
BDR-024 — profile show --plain = claude-free parse contract for the design gate
- Date: 2026-06-19
- Status: accepted
- Decision: added
profile.sh show <name> --plain→ onetype<TAB>nameper line, grouped by type (gstack/external/personal/plugin/mcp/cli order), NO status, ZERO claude calls, derived purely from the.profile. Bareshowkeeps runtime status (human value) + grouped layout;--plain= machine path. Canonical names verbatim (magicstaysmagic; plugin marketplaceplugin@<mp>collapsed to categoryplugin). - Why: upcoming design gate must derive "which profile contains tool X". Needs fast + hook-safe parse. Bare
showcallsclaude plugin list/claude mcp listper plugin/mcp entry → slow + fails in non-terminal/hook context (degrades to "disabled"). - Alternatives rejected:
- Gate re-reads
.profiledirectly — duplicatesread_profileparsing in the gate; two parsers drift. - Gate parses full
showoutput — pays claude calls per plugin/mcp, fragile in hook context.
- Gate re-reads
- Reference:
lib/profile.shcmd_show(+--plainbranch),skills/profile/SKILL.md, commit5776195. Linked to BDR-018 (priorprofile.shcommand addition). - Status (2026-11-16): accepted, amended by BDR-134: show --plain removed; claude-free parse contract = profile.sh current --plain, key=value per line (lib/profile.sh:36)
BDR-025 — Design gate = profile-based; remedy always /profile design; magic required-but-manual; unknown → fail-visible; claude resolved via PATH-repair
- Date: 2026-06-21
- Status: accepted
- Decision:
design-tool-gate.shchecks whether thedesignprofile's design-core tools are active and, if not, points at ONE command —/profile design, never an atomic per-tool toggle. tier = profil: every non-trivial tier (Build / design-system / review) draws from the onedesignprofile (a superset of all tiers) → the gate checks that profile, so ZERO hardcoded tier→tools list. Gate scope = the# GATE-BLOCK:allowlist indesign.profile(only real design tools trip; bundled browser/plan/shotgun/graphify ignored). Structure + types fromprofile.sh show design --plain(BDR-024 contract); per-tool state per channel (skill symlink /claude plugin list/claude mcp list/command -v), mirroringprofile.sh:skill_status(). Three outcomes: blocking/manual → INCOMPLETE exit 10; unknown-only → READY-BUT-UNVERIFIED exit 11 (fail-visible); else READY exit 0. magic = required-but-manual class: TRIPS the gate (NOT advisory), names theMAGIC_API_KEYstep. claude resolved viaensure_claude_on_path()(probe known dirs + nvm globsort -V | tail -1= newest, prepend the bin dir carrying claude AND node) — becausecommand -v claudedepends on PATH carrying the nvm bin, absent in a sanitized subshell/hook; integral to the final gate design, not a detail. - Why: single source of truth = profile system → no CLAUDE.md tier→tools dup (P3/P5 just removed it), no tool→profile map to drift. Credible gate: trips only on real design tools, not bundled infra → not ignored by reflex. magic is the load-bearing design tool, so silence on it would defeat the gate's purpose. Gate runs from hooks/skills where PATH may be sanitized → robust claude resolution is required for it to verify at all.
- Alternatives rejected:
- Hardcoded tier→tools list — reintroduces the CLAUDE.md dup just removed; drifts when a tool is added to a profile.
- magic advisory (mention, don't trip) — fail-OPEN on the very tool the gate exists to catch.
- Strict fail-closed on unknown — false blocks when claude merely slow/unreachable → gate gets ignored. fail-VISIBLE (exit 11) chosen.
- Depend on
command -v claudealone — fails in sanitized-PATH hook → unknown. Proven byPATH=/usr/bin:/bintest (magic-on → READY/0, magic-off → INCOMPLETE/10).
- Reference:
lib/design-tool-gate.sh,lib/design-gate.md,lib/profiles/design.profile(# GATE-BLOCK:), commits3eefb8a/4d19135/f963318. Linked to BDR-024 (the--plainparse contract this consumes), LRN-036 (command -vPATH dependence, the real cause), LRN-037 (proven on the real subject in real context). - Status (2026-11-16): accepted, amended by BDR-134: gate reads profile.sh current --plain (pack-design, pack-gstack-design, ui-ux-pro-max); remedy profile.sh set web or enable , not /profile design; PATH repair now for 21st, not claude; magic gone (BDR-093)
BDR-026 — Secret source-of-truth outside the repo (~/.claude/.env) reached via a repo/.env symlink
- Date: 2026-06-21
- Status: accepted
- Decision: real secret lives in
~/.claude/.env(outside git tree);repo/.env= symlink → it.source "$REPO/.env"follows symlink → ZERO change to any read path (toggle-external.shload_env,install-plugins.shcheck, gate).link.shlink_env()defensive: links only whenrepo/.envabsent or already the right link; a residual REALrepo/.envis left untouched with a migrate hint — never clobbered, so the secret can't be destroyed. Idempotent..gitignorehardened to.env+.env.*+!.env.example. Messages point at~/.claude/.env(canonical edit location). - Why: secret never enters the git tree — not as content (it's a link) nor by accident (gitignored). Even a stray
git add .can't stage the real key. Repo stays usable: symlink visible/editable from repo. Read paths follow the link → no script logic changed. - Alternatives rejected:
- Secret in
repo/.env, gitignored (status quo) — onegit add -for.gitignoreslip leaks it; secret sits in tree. - Scripts read
~/.claude/.envdirectly — symlink redundant, rewrites every read path, loses repo-local visibility.
- Secret in
- Reference:
link.shlink_env(),.gitignore,lib/toggle-external.sh,install-plugins.sh,.env.example, commits131d0bc/f9cc866. Linked to BDR-025 (magic'sMAGIC_API_KEY, consumed by the gate's required-but-manual class). - Update 2026-07-02 (incident — copies of secrets):
claude mcp add --envMATERIALIZES the key into~/.claude.json(mcpServers.magic.env) — 2nd live copy OUTSIDE~/.claude/.envcanonical and outside repo deny rules' reach. Audit query printed it into a session transcript → key rotated (21st.dev). Rule: secrets have COPIES (tool configs, transcripts, caches) — protect/audit the copies, not just the canonical; when inspecting MCP config, filter env fields (jq 'del(.. | .env?)'). Same audit:~/.claude/.envhardened 0664→0600. - Update 2026-07-07 (job7 — backup vector closed):
~/.claude.jsoncopy from 2026-07-02 kept re-leaking into~/.claude/backups/.claude.json.backup.*(native auto-backup, ring-buffer of 5, plaintext) — every backup taken while live file held the value = fresh copy; scrubbing backups alone would recur forever. Closed at the source instead (BDR-057):~/.claude.json'smcpServers.magic.env.API_KEYrewritten to"${MAGIC_API_KEY}"(Claude Code${VAR}expansion, confirmed supported at user scope),lib/toggle-external.shwrites the reference form for futureenable magicruns, var reachesclaudeonly via a scoped~/.bashrcwrapper (never the ambient shell). New backups taken after the fix carry the reference, not the value — confirmed empirically (2 of 5 rotating backups mid-fix still had the old value; scrubbed once, not expected to recur). MAGIC_API_KEY itself still needs rotation (this closes the storage vector, not the already-exposed value).
BDR-027 — Minimal npm-via-nvm bootstrap over centralized prereq lib (reverses the reverted approach)
- Date: 2026-06-23
- Status: accepted (supersedes the reverted
lib/install-prereqs.shcentralization, commit 1ddeed1 removed from history) - Decision: the only real bootstrap blocker =
npmabsent on fresh machine.install.shnow installs current LTS via nvm (v0.39.7→nvm install --lts) ONLY when node/npm missing (install_node_via_nvm). Keep the inline per-tool prereq blocks ininstall-plugins.sh(no sharedensure_*lib). Re-addjqinline (Step 1) +doctor.shfail-level —jqis an active-hook dep that was never installed. - Why: a 1-function fallback fixes the actual blocker. Folding 9 prereqs into a 245-line lib was scope-creep for "npm missing"; user reverted it. Inline blocks stay readable + co-located with their step.
- Alternatives rejected: centralized
lib/install-prereqs.sh(commit 1ddeed1 — over-engineered for the real blocker, reverted); leavenpmas a harderr(the original bug — aborts before the CLI install). - Reference:
install.shinstall_node_via_nvm,install-plugins.shStep 1 jq,doctor.sh, commitsb6cc8b1/2194b11. Linked to BLK-008 (the chromium half of the same fresh-Ubuntu-26.04 session).
BDR-028 — Hand-curated config is install-immutable (auto-revert guard) + de-vendor installer-managed skills
- Date: 2026-06-23
- Status: accepted
- Decision:
install-plugins.shsnapshotsCLAUDE.md+settings.json+.claude/settings.jsonat start, restores them on EXIT (trap) → installer never mutates hand-curated config.frontend-designun-tracked (git rm --cached+ gitignoreskills-external/frontend-design/) — re-synced from the example-skills plugin cache every run, so vendoring = pure churn. npx-skills pollution (/.agents/,/skills-lock.json) gitignored, anchored so ouragents/stays tracked. - Why: a fresh
make installdrifted all 4: graphify clobberedCLAUDE.md(deleted the# This repo onlyheader) + injected aggressive MANDATORY pre-tool hooks;claude plugin installflippedexample-skills→true + addedplugin-dev; frontend-design diffed on every upstream update; darwin-skill polluted repo.agents/at project scope. Guard = these files maintained by hand+commit only; gitignore = generated artifacts never tracked. - Caveat: guard makes the 3 config files install-immutable — anything the installer SHOULD add must be committed by hand. Safe today: committed
settings.jsonalready carries the rtk hook (install skips init).update-all.shneeds no guard (onlyclaude plugin update, no enable flips, no graphify reconfig). - Alternatives rejected:
git checkoutpost-install (nukes legit uncommitted edits, depends on git state); surgical JSON/markdown patching (fragile); accept graphify's generic CLAUDE.md (loses curation). - Reference:
install-plugins.shguard block +restore_curated_configstrap,.gitignore, commits51afe9b/7de8761. Linked to LRN-039.
BDR-029 — Installer auto-fixes gstack browser on OS newer than its pinned Playwright supports
- Date: 2026-06-23
- Status: accepted
- Decision:
install-plugins.shmakes gstack's browser work on too-new distros without manual steps. (1)gstack_bump_playwright_if_unsupported()runs before./setup: if the pinned Playwright's support list lacks the running distro (grepnode_modules/playwright-core/libfor theubuntuXX.04tag),bun add playwright@latestin the submodule, then./setup's frozen-lockfile install picks it up + rebuilds the browse binary. Idempotent (skips when already supported). (2) PersistGSTACK_CHROMIUM_NO_SANDBOX=1to the shell profile, gated onsysctl kernel.apparmor_restrict_unprivileged_userns=1. - Why: fresh
make installon Ubuntu 26.04 must yield a working gstack browser. Submodule pins Playwright 1.58.2; upstream hasn't bumped; can't wait. Local bump in the installer = "just works" + self-heals after agit submodule update(re-applies next run). - Caveats: the installer EDITS the submodule (goes dirty each run on a too-new OS) — invasive, but the user chose it over waiting upstream.
bun add playwright@latestcould pull a Playwright that breaks gstack's build → non-fatal (./setupfail warns, install continues). The local bump is reset bygit submodule update. The.bashrcenv can be wiped if the user restores a hand-managed.bashrc(theirs is managed — the first install's lines were already lost that way). - Alternatives rejected:
PLAYWRIGHT_HOST_PLATFORM_OVERRIDE(fallback build HANGS at extraction — BLK-008); wait for gstack upstream Playwright bump (no ETA); leave browser unavailable (user wanted it); system chromium + executablePath (needs gstack code change). - Reference:
install-plugins.shgstack_bump_playwright_if_unsupported()+ Step 9 sysctl-gated env, commit3b8ffb1. Linked to LRN-040, BLK-008.
BDR-030 — gstack skills activated ON-DEMAND per profile, not pre-installed; OFF by default stays
- Date: 2026-06-23
- Status: accepted
- Decision: gstack stays OFF by default (no per-skill symlink in
skills/, zero context cost) — butprofile.sh set <profile>that LISTS a gstack skill activates it for that profile.enable_skill gstackgained a branch: skill not inskills/and not parked inskills-disabled/but present in theskills-external/gstack/<name>submodule →ln -sit intoskills/.disable_gstack_not_in()parks it again when an unrelated profile is set. The gstack/bin + browse/dist infra those skills need is created independently bylink.sh. - Why: user wanted
make installself-sufficient ANDset full(lists 35 gstack skills) to work without 35missing — try: bash link.shwarnings, WITHOUT abandoning gstack's OFF-by-default context-cost policy (BDR-029 install comment). On-demand-per-profile threads both: gstack invisible until a profile needs it, then auto-on for exactly that profile. Source of truth = the submodule (gstack_skills()already readsskills-external/gstack/*/SKILL.md), so activation needs no gstack./setupskill-registration (which this gstack version writes to the WRONG dir anyway — LRN-042). - Caveats: the symlink form (
skills/<name> -> skills-external/gstack/<name>) differs from what gstack./setupwould create (real dir + symlinked SKILL.md) — fine here because./setupnever populatesskills/in this layout, so no mixed-form collision. Browse RUNTIME still needs the built binary + sandbox env (BDR-029) — on-demand makes the skill DISCOVERABLE, not the browser functional on an unsupported OS. The old "try: bash link.sh" message was wrong (link.sh never creates gstack skills) → replaced with submodule-aware messages. - Alternatives rejected: full gstack integration (make
./setupinstall intoskills/) — user picked option 1, too invasive/version-fragile; leavefullbroken with honest 1-line warning — worse UX; pre-symlink all gstack at install — violates OFF-by-default context policy. - Reference:
lib/profile.shGSTACK_SRC+enable_skillgstack branch. Verified:set full→ 0 missing, 35 on-demand;minimal↔fullcycle re-parks/restores; git clean (gstack symlinks gitignored, LRN-025). Linked to LRN-042, LRN-022, BDR-018 (gstack on/off verb). - Status (2026-11-02): superseded by BDR-134
BDR-031 — global CLAUDE.md lightening = COMPRESSION, not path-scope / externalization
- Date: 2026-06-25
- Status: accepted; SUPERSEDED 2026-10-23 by BDR-125 (conditional load now proven reliable + mod injection)
- Decision: lighten the universal global CLAUDE.md (
~/.claude/CLAUDE.md, loaded every session in every project) by COMPRESSION only — denser prose, drop name-obvious routing lines, trim decorative whitespace. NOT by path-scoping rules under~/.claude/rules/, NOT by externalizing sections to on-demand files. Result: 317 → 275 lines. - Why: user-level path-scoped rules (
paths:frontmatter under~/.claude/rules/) do NOT load in CC 2.1.190 (#21858, BLK-009) — proven by probe. Conditional/scoped loading is therefore an unreliable lever for this user; compression is the only mechanism that actually cuts every-session token cost without depending on the broken feature. - Caveats: future GLOBAL memory must stay tiny — with conditional loading broken, anything global loads in EVERY project unconditionally; fold that constraint into the global-memory design once a backup exists. Caveman pass to ~250 was explicitly DECLINED: marginal ~25-line gain vs real risk (changes the nature of instructions-to-follow; no evidence caveman is followed better than prose; CLAUDE.md is the most-edited file → caveman = painful to re-read/amend). 275 readable > 250 caveman.
- Alternatives rejected: path-scoped
~/.claude/rules/(broken, BLK-009); externalize sections to on-demand-loaded files (same conditional-load dependency); caveman to ~250 (readability + instruction-fidelity risk). - Reference:
~/.claude/CLAUDE.md(symlink →~/Documents/claude/CLAUDE.md), commitsba743cf(compress routing+design+graphify) +990318c(trim separators/blanks). Linked to BLK-009, LRN-043, LRN-044.
BDR-032 — skill /validate → /web-validate (rename user surface, keep internals)
- Date: 2026-06-25
- Status: accepted (shipped
e5e673a) - Decision: rename W3C+WCAG skill
/validate→/web-validate(clearer scoped name, less generic). Renamed the USER-FACING surface ONLY: folder (git mv), frontmattername, H1, command refs, CLAUDE.md routing line, 6lib/profiles/*.profileentries (FUNCTIONAL — profiles activate skills by folder name, a miss = broken activation), cross-refs (harden/seo/depth-matrix/client-handover), agent dispatch refs, README + USAGE tables. Leak-guard regex extended toweb-validate|validate(LRN-045). - Why — 4 deliberate KEEPs:
- agent
validator-analyzername KEPT — internal, lockstep withsubagent_type=+ harness registry; rename = wider blast radius, zero discoverability gain. .validate-cache/+VALIDATE.mdKEPT — names derive from the AUDIT TYPE, family{SEO,GEO,HARDEN,CSO,VALIDATE}.md; renaming makes VALIDATE the odd one out + orphans already-generated reports (MIGRATION.mdcleanup loop hardcodes the name). Same logic kept the dispatch labeldescription="validate — ..."..claude/history KEPT (memory + completed TODO block) — append-only, true at the time. The forward-pointing OPEN TODO item was ANNOTATED additively (désormais /web-validate), not rewritten — append-only protects history, not pointers to future actions.- CHANGELOG old entry KEPT, new "renamed" entry ADDED (Keep-a-Changelog: don't rewrite the past).
- NL trigger keywords ("validate"/"validation") KEPT in the description so "validate my site" still routes here.
- agent
- Alternatives rejected: rename agent + artifacts too (cosmetic symmetry, ~45 extra edits, breaks audit-file family + report back-compat); blind
sed s/validate/web-validate/(breaks third-partyhtml-validate,validator.nu, English-verb prose — discrimination must be at the/validatetoken, proven by.validate-cache/html-validate.jsonstaying intact). - Reference: commit
e5e673a(18 files). Verified complete:/validate= 0 in active code (only.claude/history + CHANGELOG),html-validate= 15 intact, regexclient-handover-writer.md:1462shows both names. Linked to LRN-045, BDR-031 (CLAUDE.md routing), LRN-043 (validate routing line).
BDR-033 — design-gate §4: anim-lib suggestion — suggest-only, non-blocking, stateless 1-line
- Date: 2026-06-25
- Status: accepted
- Decision:
lib/design-gate.mdgains §4. When a non-trivial design task hits a MOTION signal (animation/transition/hover/motion/animate, added to §DETECTION) ANDdetect_anim_eligibility=eligibleANDis_anim_lib_installedfinds none → surface ONE line suggesting the recommendedmotionpkg. Suggest-only (install ONLY on explicit consent, never auto), non-blocking (sole STOP stays §3 exit 10), stateless (ALWAYS the single line, no marker). Calls the helper — no 3rd copy of the lib list. - Why: gate runs mid-build; a 2nd blocking stop on an OPTIONAL dep = friction. Dedup goal is not "prevent re-fire" but "make the surface minimal enough that re-fire is never noise" → deterministic by construction (nothing to remember → no fragile behavioral guard, cf LRN-046/LRN-047). Conditional to stakes: the deduped thing here is a NON-DESTRUCTIVE 1-line cosmetic note → re-fire is annoyance, not risk, so importing marker-grade infra (file + gitignore + permanent state) is not justified. On a DESTRUCTIVE op a deterministic marker IS worth its cost — that is where LRN-046/LRN-047 were forged. Same determinism bar, opposite cost/benefit; pick by stake. Self-heal: condition-3 (
is_anim_lib_installed, 10 libs incl gsap/react-spring/lottie) kills it the instant any anim lib lands → re-fire only ever hits "eligible + pure-CSS + actively declined". - Alternatives rejected:
- File marker
.design-anim-suggested(once-forever) — "session"→"forever-per-project" (1 decline = permanent silence, no cleanup but manual rm); adds write + gitignore mgmt to a non-mutating doctrine;.claude/tracked here → suppression leaks via git. - Blocking yes/skip prompt à la
/onboardSTEP 2.5 — a 2nd STOP mid-build on an optional dep. - Prose "agent remembers not to re-suggest" — fragile behavioral guard, contradicts LRN-046/LRN-047.
- File marker
- Reference: commit
11792cc,lib/design-gate.md§4 + §DETECTION (+motion/+animate). Helperlib/animation-lib-check.shunchanged. Live via symlink (~/.claude/lib/→repo). Builds on BDR-005. See LRN-049.
BDR-034 — Coupled-capitalize invariant v1 — memory commit auto per dev flow (Frame 2)
- Date: 2026-06-26
- Status: accepted
- Decision: Dev flows committing code now auto-commit memory same breath, via include
lib/capitalize-commit.md+ helperlib/memory-commit.sh(surgical: stages+commits.claude/memory+.claude/tasksonly, pathspec, nevergit add -A). 4 inline flows (feat/hotfix/bugfix/commit-change) ref the include at their capitalize step; ship-feature reordered (CAPITALIZE STEP 7 before FINISH STEP 8 — fixes memory committed after push/PR + stranded outside it); init-project gains STEP 10b founding-decisions capitalize. 1 memory commit/flow (F3). Capitalize CONTENT keeps its approval gate — only the COMMIT of approved entries is automated. - Why: Real pain = the 2nd (memory) commit forgotten/manual — ~42% of recent history (17/40 commits) was emergent
chore(memory). Frame chosen = "couplé après-code" not "avant commit": keeps hash-anchoring (>50% entries carryReference: commit) + code/memory concern separation; attacks the forgetting, not the ordering. "Capitalize before commit" rejected — inverts a deliberate property AND can't anchor the code hash (hash exists only post-commit). - Alternatives rejected:
- (a) each orchestrator calls capitalize-before-commit — duplicated across 5+ flows (each has bespoke inline capitalize), breaks hash-anchoring, forgettable on next skill added.
- (b) commit-change as the single gate — not on the path of feat/hotfix/bugfix/ship-feature/init-project (they commit inline or via external superpowers); can't detect "pending capitalize".
- (c) single commit chokepoint — doesn't exist; 3 distinct commit mechanisms, one external/unmodifiable (
superpowers:finishing-a-development-branch). - Frame 3 (single unified commit, drop hash) — sacrifices >50% entries' anchoring for history aesthetics.
- Reference: commits
58cb91d(helper+tests) ·bbef41c(hash/stdout + T6/T7) ·b44791b(include) ·2763678(4 flows) ·e8eff7e(ship-feature reorder) ·df60df6(init-project). Hook (v2, Stop-hook non-blocking BDR-033-style) + doc-sync twin chantier (same PR bug, reorder before FINISH) deferred. See LRN-051, LRN-052, EVAL-007.
BDR-035 — Analyze-before-plan invariant v1 — read-before bookend of coupled-capitalize
- Date: 2026-06-26
- Status: accepted
- Decision: Dev flows now READ related memory before planning (ship-feature also reads related code), mirroring how BDR-034 made them WRITE memory after. Shared include
lib/analyze-before-plan.md(tête-bêche oflib/capitalize-commit.md). Invariant = DISPOSITION, not reading: the plan must NAME each surfaced ID (in-force / already-seen / non-binding) — a verifiable trace in the artifact, not "did it look". Two-pass: grep## <PREFIX>-body headings → select on titles → full-read only the selected bodies. Wiring: ship-feature STEP 0d (analyzer subagent code+memory, fed to brainstorm/plan by INPUT INJECTION + STEP 3 reconciliation gate); bugfix STEP 2.5 (blockers-first); feat STEP 0.6 (decisions-first, MINI-PLAN names in-force or states none); hotfix opt-in blockers-only; init-project + onboard = no-op exceptions. Guarded no-op ([ -d .claude/memory ]). - Why: coupled-capitalize gave every flow a write-after; NO flow read the memory it feeds — bookend half-open. A bugfix wrote BLK at the end but never checked blockers.md for the same root cause already solved. Closes Gap B (memory, universal) + Gap A (code, ship-feature — the lone cold-planner).
- Alternatives rejected:
- Index two-pass —
## Indexdrifted on this mature repo (decisions 11/34, learnings 21/52, blockers 2/9 missing) in scattered blocks → an Index-based selector silently misses a large unpredictable fraction. Body headings drift-immune (100% coverage). See LRN-055. - Extend analyzer only — inline flows (feat/bugfix/hotfix) never call analyzer pre-plan → would close Gap B for none. Needed both: include + analyzer RELATED MEMORY section.
- PASS-2 skip-if-already-in-context — no deterministic oracle for "in context"; reintroduces the behavioral guard. See LRN-054.
- Index two-pass —
- Reference: commit
67c6a81,lib/analyze-before-plan.md,agents/analyzer.md. Bookend of BDR-034. See LRN-053, LRN-054, LRN-055, LRN-056, LRN-057.
BDR-036 — Doc-sync coupled invariant — commit the docs doc-syncer patches (twin of BDR-034, BUILT not reordered)
- Date: 2026-06-27
- Status: accepted
- Decision: doc-sync flows now COMMIT the public docs doc-syncer patches, via new
lib/doc-commit.sh(helper) +lib/doc-commit.md(include) — mirror of memory-commit/capitalize-commit, 4 DELTAS: (Δ1) dynamic scope = patched files as argv, not a fixed pathspec; (Δ2) INVERSE exclusion = fail-closed + loud guard rejecting.claude/**+CLAUDE.md(dedicated exit 4), opposite of memory-commit which TARGETS.claude/; (Δ3) no hash anchoring (docs carry no SHA, LRN-052); (Δ4)docs:msg. doc-syncer emitsPATCHED_FILES(one path/line) → agent splits on newline → each as DISTINCT argv (space-safe, LRN-060). 2 orchestrators reordered DOC SYNC before FINISH (ship-feature STEP 9→8, init-project STEP 12→10c, GSD 13→12); 3 inline flows wired (feat/bugfix/hotfix DOC SYNC). Consumption MECHANICAL (LRN-057 case a, = BDR-034). - Why: doc-syncer PATCHED docs but COMMITTED nothing (grep-proven, zero git commit) → push/PR path = docs stranded outside PR (orchestrators); inline = docs left dirty. Twin of BDR-034 but NOT same fix: memory ALREADY had a commit helper (only mis-timed); doc-sync had NONE → had to BUILD the mechanism, not just reorder. "Reorder alone" (the deferred note's framing) REFUTED in read-phase (LRN-058).
- Honest scope/choices (engraved, not glossed):
- (a) MINOR doc content stays NON-gated yet auto-committed — CONSCIOUS, not memory's always-gated content; the VISIBLE surface (files + AGENT-composed change summary, not a bare count) REPLACES the gate as the review surface. Strengthening the MINOR gate = separate doc-syncer chantier.
- (b) init-project PARTIAL — scaffold + bootstrap-README commit gap (BLK-010, unborn HEAD + worktree) + GSD ROADMAP post-FINISH (BLK-011) deferred = NEW work, not replication.
- (c) scope EXPANDED mid-chantier via the ref-sweep to 3 inline flows — asymmetry vs memory (BDR-034 wired ALL flows) was the decider.
- Alternatives rejected:
- Reorder-only (the deferred note) — refuted: doc-syncer commits nothing, reordering uncommitted docs still misses the merge.
- Static-glob scope (
*.md/docs/) — over-reach onto a user-edited doc /MIGRATION.md; chose touched-files argv (in-thread list already in hand). - Silent-filter the forbidden path — masks an upstream BDR-022 bug; guard must REFUSE-ALL loudly (LRN-060).
- Reference: commits
ae1f218(helper+tests) ·4a54a65(include) ·fb1f359(doc-syncer PATCHED_FILES) ·636b491(ship-feature reorder) ·e81f629(init-project reorder) ·1b01b95(3 inline flows). See BDR-034, LRN-058, LRN-059, LRN-060, BLK-010, BLK-011, EVAL-008.
BDR-037 — v2 capitalize Stop-hook REJECTED → wire /capitalize+/close to the include
- Date: 2026-06-27
- Status: accepted
- Decision: Deferred "v2 hook" (BDR-033-style non-blocking stateless Stop-hook nagging dirty
.claude/memory) REJECTED — no code written. No Claude Code event supports an end-of-session nag:Stopfires PER-TURN (self-defeating — would nag during /capitalize's own write→commit window, LRN-047);SessionEndis debug-log-only (can't nag) + would bypass the content gate (half-written entries). Real gap ≠ forgetting → CÂBLAGE manquant:/capitalize+/closenever calllib/capitalize-commit.md. Redirect: wire the include into/capitalizeSTEP 5B (/close= thin alias, follows free), same one-liner as the 6 dev flows. Content gate (STEP 3) first → commit of approved entries automated (BDR-034 contract). Deterministic, zero-noise, at source. - Why: 3 git proofs — (1) memory already committed by hand 35× as pure
chore(memory)(zero code mixed); (2) orphans self-heal —commit_memorystages whole.claude/memorydir, next flow sweeps up; (3) cost on common path (per-turn noise / non-gated commit), benefit marginal (residual self-healing) → a hook polices a discipline already in evidence. OUBLI not choice: include + helper born 2026-06-26;/capitalizelast edit 2026-06-19 (created 2026-06-09),/close2026-04-23 — skills predate the machinery 7-60d; wiring commits (2763678/e8eff7e/df60df6) touched neither. No control removed: the commit was never gated, just done by hand in the exactchore(memory): <IDs> — <ctx>style the include reproduces. - Alternatives rejected:
- (a) Stop per-turn memory-only wrapper — fires during the very flush it nags about → LRN-047 self-defeat (frequent ignored nag = risk, not annoyance).
- (b) SessionEnd auto-commit (FAIT) — bypasses STEP 3 content gate, embarks half-written entries, can't report actionably.
- (c) abandon with no redirect — leaves the real wiring gap open; fix for an unwired skill = wire it.
- Reference: read-phase analysis (no hook code ever written); wiring commit (capitalize STEP 5B) follows. Completes BDR-034 rollout; applies BDR-033 doctrine to REJECT (not all nudges — the determinism split is LRN-061). See LRN-061, LRN-047, LRN-049, LRN-054.
BDR-038 — deploy skill: per-project learning runbook, two-moment cold-resume
- Date: 2026-06-27
- date: 2026-06-27
- status: accepted
- decision: New
/deployskill = per-project runbook in.claude/deploy/. 5 artifacts:PROCEDURE.md(runbook, in-place edits),INCIDENTS.md(DEP-NNNledger, append-only),STATE.json(deploy oracle, committed),PENDING.json(cold-resume bridge, gitignored),NEXT.sh(instantiated checklist, gitignored, hand-run). Two-moment spine: BEFORE (delta-instantiateNEXT.sh+ hand back) → user deploys OUT-OF-BAND → AFTER (react: MARK success or LEARN from failure). Cold cross-session resume viaPENDING.json(disk = only memory across the gap). Learn = atomic patch+incident (onedeploy-commit.shcall, both files). New helperlib/deploy-commit.sh(allowlist.claude/deploy/). Built via subagent-driven-development (4 tasks). - why: deployment memory that LEARNS (runbook patched in place per failure) beats a frozen runbook; disk-bridge so a resume survives session loss.
- alternatives: tag-oracle (rejected — lightweight-tag date unreliable, rebase-fragile, LRN-063); separate append-only ERRORS log (rejected — git history of
PROCEDURE.md+INCIDENTS.mdsuffices, noresolved-byfield);NEXT.sh-as-bridge (rejected — ephemeral ≠ persistent → separatePENDING.json); reuse doc/memory-commit (rejected — neither can commit.claude/deploy/, LRN-064). - reference:
skills/deploy/SKILL.md,lib/deploy-commit.sh,templates/deploy/; branchfeat/deploy-skill(b210e8d..79741e3, kept un-merged); specdocs/specs/2026-06-27-deploy-skill-design.md, plandocs/plans/2026-06-27-deploy-skill.md. - Status (2026-10-28, upgrade): superseded by BDR-054 (NEXT.sh, hand-back)
BDR-039 — Gitea branch protection = Option-1 owner-pushable, not require-PR
- Date: 2026-06-29
- date: 2026-06-29
- status: accepted
- decision: Protect
main+developon every gitflow-migrated Gitea repo with Option 1 (owner-pushable):enable_push=true+enable_push_whitelist=true+push_whitelist_usernames=[owner]. Blocks force-push, branch deletion, and pushes by non-owners — while letting the owner push their LOCAL gitflow merges directly. NOT require-PR / required-review. - why: gitflow integrates by local directed merges —
gitflow finishrunsgit merge --no-ffon the owner's machine then pushes the merge commit. require-PR would REJECT those pushes: every feature/bugfix/release merge would need a manual PR, and the hotfix fan-out (hotfix → main + develop + each openrelease/*) becomes 3+ manual PRs per hotfix. For a solo-owner Gitea, required reviews add zero review value, only friction. Owner-pushable keeps the protection's real teeth (no force-push, no deletion, no non-owner push) without breaking the local-merge workflow. Protection is a BACKSTOP — the per-repo pre-commit hook + the "finish only on an explicit human signal" rule are the primary controls. - alternatives: require-PR + required reviews (rejected — breaks
gitflow finish's local merges; the 3-way hotfix fan-out becomes manual PRs; no review value for a solo owner, pure friction); no protection (rejected — leaves force-push + branch deletion + accidental non-owner push open; it is the deterministic backstop the advisory rules can't guarantee); protectmainonly (rejected —developis equally a protected base in the model, needs the same force-push/deletion guard). - reference:
lib/gitflow-migrate.sh_protect()(POST/repos/{o}/{r}/branch_protections, owner whitelist); applied to all 6 repos 2026-06-29 (journal). Hook backstop inlib/gitflow.sh(pre-commit); CLAUDE.md "Version control — gitflow (universal)". Pairs with LRN-069 (thegit pushASK gate at the tool-call layer).
BDR-040 — doc-syncer MINOR-shape oracle: deterministic floor under LLM's MINOR call
- Date: 2026-06-29
- date: 2026-06-29
- status: accepted
- Problem: doc-syncer AUTO MODE classifies drift NONE/MINOR/SIGNIFICANT by LLM judgment, no deterministic backstop. SIGNIFICANT mislabeled MINOR → silent auto-patch + auto-commit, skips the SIGNIFICANT gate (RISK-1). Follow-up BDR-036 flagged.
- Decision:
lib/doc-shape.shre-checks SHAPE of each MINOR patch BEFORE the silent auto-commit. Envelope (per path,git diff HEAD): adds ATX heading | added > DOC_SHAPE_MAX_ADDED (def 20) | removed > MAX_REMOVED (def 20) | new/untracked file | non-doc → EXCEEDS. Aggregate: ANY path exceeds → whole set escalates to the EXISTING SIGNIFICANT gate (STEP A4Apply? yes/no/select; no=revert all, select=keep subset). Thresholds env-overridable. - Oracle NOT a blocking gate (B rejected): BDR-036 graved MINOR-non-gated as CONSCIOUS (visible surface replaces gate; blocking gate = friction disproportionate). Oracle does NOT gate genuine MINOR (auto-commit untouched, zero friction) — only re-routes shape-suspect patches. Tightens the DEFINITION of MINOR deterministically (LRN-046 oracle > judge), adds no gate. Option B (human gate on every MINOR) REJECTED — contradicts BDR-036, rejects the premise the reading refuted.
- ENGRAVED LIMIT — do not over-read the guarantee: oracle catches STRUCTURAL/size significance, NOT semantic. A 3-line edit that CHANGES MEANING, no heading, small → still reads MINOR (rc 0) and auto-commits. Deterministic FLOOR under LLM judgment = REDUCTION of RISK-1's gross cases, NOT elimination. LLM owns the semantic call above the floor; the visible surface (BDR-036) stays the content backstop.
- Scope tranché: ① oracle + ② LRN-071 masked-commit fix built. ③ branch-guard (doc-commit refusing main/develop) DEFERRED — duplicates the protected-base predicate a 3rd time (lib + gitflow hook + here); migrated repos have the hook → ③ guards a state that shouldn't exist. Reconsider only for repos outside
gitflow init. - Build: TDD RED→GREEN. run-doc-shape.sh 19/19 (incl. threshold boundary + env-override) + behavioral Scenario D. Wired doc-syncer STEP A4 + doc-commit.md ACKNOWLEDGMENTS coherence. shellcheck clean.
BDR-041 — /reconcile = deterministic declared-vs-real engine + thin gated skill (reconciler, not lister)
- Date: 2026-06-30
- Status: accepted
- Decision:
/reconcileanswers "what work is REALLY open?" by confronting DECLARATIVE sources (TODO[x]/[ ]/[~], registry statuses,## Index) against REAL state (git/fs, registry BODY). Split:lib/reconcile.sh(deterministic engine — body enumeration,reconcile_oracle_*, BLK last-block-wins, lexical deferral sweep, contradiction candidates, purereconcile_verdictkernel) +skills/reconcile/SKILL.md(thin orchestration + A/B/C write-back gate). Founding principle = RECURSIVE COHERENCE: never use a declarative source as oracle (Index/checkbox/status/path-name) — enumerate from BODY## IDheadings, decide done/stale from git/fs. TESTED: run-reconcile.sh T1 reds if engine reads## Index(shim → 51≠72, canary LRN-020 dropped). Registries READ-ONLY (curation = /prune-memory). - Why: RED proved a capable agent reconciles when GUIDED ("use git + justify") but MIRRORS the TODO when not (false positives + missed contradiction), and even guided hits the compound-status trap (BLK-008). Value = determinism + cheapness + gate, NOT teaching (LRN-031, LRN-075). Mechanical 80% → script; judgment 20% → thin skill (writing-skills: automate mechanical, document judgment).
- Alternatives rejected: monolithic teaching/discipline skill (agents reconcile when guided → no teaching value);
grep '[ ]'lister (reproduces the lie); trust Index (drift, LRN-055); blocking write-back gate (friction — A/B/C surface chosen). - Honest limits (graven): deferral detection LEXICAL (marked-only; unmarked "à reprendre quand X" missed); contradictions = CANDIDATES (token overlap), surfaced not asserted; cross-repo "not verifiable here"; cross-ref verdicts ("[~] done because chantier X below complete") surfaced, not auto-resolved.
- Reference:
lib/reconcile.sh,lib/tests/run-reconcile.sh(20/20) +lib/tests/fixtures/(neutral-named, LRN-077),skills/reconcile/SKILL.md, CLAUDE.md "Skill routing". Born of the 2026-06-29 manual inventory (its known-good oracle). Built via superpowers:writing-skills. See LRN-075, LRN-076, EVAL-011.
BDR-042 — /release-candidate = thin orchestrator over gitflow release; the tag lives in the skill
- Date: 2026-06-30
- Status: accepted
- Decision:
/release-candidate <X.Y.Z>cuts a release by ORCHESTRATING the existinglib/gitflow.shmechanic, NOT rewriting it. Flow: preconditions (clean tree, identity, develop ahead of main) →gitflow start release→ prep (version.txt + CHANGELOG, breaking documented) → run-tests gate → HUMAN "WHEN to release" gate →gitflow finish(fan-out main+develop+delete, lib L108-111) →git tag -a vX.Y.Z main→ push gated. Thegit taglives in the SKILL, lib UNTOUCHED — the tag is release-specific (version + message + human call), the lib's fan-out is generic. SchemevX.Y.Z, CONTINUES the version.txt/CHANGELOG lineage (never restart at v1.0.0 — desyncs from a CHANGELOG already at 3.x). - Why: gitflow release was wired (start base=develop L49, finish fan-out main+develop L108-111) but had NO tag step (grep-confirmed: zero
git tagin gitflow.sh). The tag is the only gap; an orchestrator supplies it without touching the tested mechanic. - Consequence (accepted): a release cut by calling
gitflow finishdirectly, bypassing the skill, fans out but is NOT tagged →/release-candidateis the CANONICAL sole release path. Acceptable for a solo repo; revisit (tag in lib) only if direct-lib releases become a need. - Alternatives rejected: tag inside
gitflow_finish(atomic but modifies the tested generic mechanic for a release-specific concern — lib=mechanic/skill=judgment); restart tags at v1.0.0 (desyncs tag↔CHANGELOG lineage). - Reference:
skills/release-candidate/SKILL.md,lib/tests/run-release-candidate.sh(RED no-tag → GREEN 5/5), CLAUDE.md routing. Built via writing-skills TDD. Consumes the gitflow model BDR-039. See LRN-078, LRN-079, EVAL-012.
BDR-043 — BDR-015 trigger cleared: 5 ex-broken gstack symlinks repaired → darwin re-baseline back in scope
- Date: 2026-06-30
- Status: accepted (requalifies BDR-015 — append-only, BDR-015 left intact)
- Decision: the 5 dirs BDR-015 excluded from
/darwin-skill(benchmark-models,context-restore,context-save,make-pdf,plan-tune) are no longer broken. gstack now ships those skills — all GENERATED bygen-skill-docsin themake pluginrun → real submodule targets exist, symlinks resolve. VÉRIF audit 2026-06-30 = 0 broken among 83 symlinks (skills/ 41 + skills-disabled/ 33 + nested 5 + top-level 4). Per BDR-015's own caveat ("if/when symlinks repaired → re-run baseline to bring them in scope"), the 5 RETURN to darwin scope → re-baseline UNBLOCKED. - Why: BDR-015's exclusion was CONDITIONAL on the targets being broken (external-ownership + missing-target). Precondition gone → exclusion no longer applies to these 5.
- Action (NOT done): verify
~/.agents/skills/darwin-skill/results.tsvstill marks these 5status=error("broken gstack symlink — out of scope"); if so, re-run darwin baseline to bring them in. Status = UNBLOCKED, execution PENDING — do NOT read as "re-baselined". - Distinct from BLK-007: BLK-007/
f928a53(2026-06-02) = a DIFFERENT symlink episode (spec+ 5 iOS device-farm skills, source-only after a submodule bump; fixed by linkingspec, skipping iOS). NOT the 5 of BDR-015 — kept separate to avoid a false causal link. - Reference: VÉRIF audit (subagent, filesystem-only, 2026-06-30). BDR-015 caveat. darwin eval log
results.tsv.
BDR-044 — auto-skill-dispatch won't-build: under→over reframe, measured — model already discriminates
- Date: 2026-06-30
- Status: accepted · won't-build
- Decision: do NOT add L2 routing prose to CLAUDE.md for "auto-trigger skills on intent". Chantier retired won't-build — 3rd measured moot of the session (after BDR-001 --help + BDR-043/LRN-082 darwin re-baseline).
- Why — the dependent variable inverted: the initial fear was UNDER-routing (model ignores skills, does the task by hand). Cartography refuted it — routing is a STACK and L1 (superpowers "1% chance → you MUST invoke") already SUR-determines invocation → "does it route?" = "already yes". The real open question became DISCERNMENT (clear→route, ambiguous→ASK, trivial→abstain), and the real hazard inverted to OVER-routing. Measured in REAL fresh main-loop sessions (8 prompts, 3 classes): CLEAR→routes ✓, AMBIGUOUS→asks (refuses to guess, investigates to ask a USEFUL question) ✓, TRIVIAL→abstains ✓. The L1-vs-Workflow-rules textual tension ("1% → MUST invoke" vs "ask one question if needed / pragmatic on trivial") is resolved well in behavior — the model balances. Adding L2 bounding prose = phantom value AND risks DEGRADING an already-good discernment.
- Alternatives rejected:
- Add a routing-reinforcement instruction (original intent) → phantom value: L1 already over-determines routing; more mandate worsens the only real risk (over-routing).
- Add an over-routing bound (clear→route / ambiguous→ask / trivial→abstain) at L2 → measurement shows the model ALREADY does this; codifying it risks perturbing it, zero upside.
- Keyword hook on intent verbs → too noisy — the design-hook mis-fired on "design" in "auto-skill-dispatch" 3× this session; intent verbs (corrige/crée) are everywhere.
- Reference: cartography L0–L4 + discernment-RED (user-run, fresh sessions). Subagent under-routing RED RETIRED as non-discriminating (LRN-083). LRN-080 (measure-first), LRN-049 (bound noise). TODO "auto-skill-dispatch" → won't-build.
BDR-045 — Standalone memory/doc skills branch to chore/* via the aiguillage (hook exemption kept)
- Date: 2026-07-01
- Status: accepted
- Decision: Standalone memory/doc skills (
/capitalize/close/prune-memory/reconcile) run the gitflow aiguillage BEFORE writing: on a protected base theygitflow start chore <name>off develop → commit lands onchore/*, not direct on main/develop. Newchoretype inlib/gitflow.sh(base_for→develop,branch_type,finish→develop like feature/bugfix); hook UNCHANGED (chore/*non-protected; the.claude/**-on-main exemption KEPT — T3 still green).gitflow-aiguillage.mdbroadened (caller→type map); 3 skills wired (capitalizecovers/closevia alias,prune-memory,reconcile); tests +T1 chore predicates +T6b finish chore→develop +T10 coherence chore/m → 64/64. Reused the EXISTING aiguillage include, not a new mechanism. Commite8807a7. - Why: the
.claude/**exemption is scoped to the SIDE-CAR (BDR-034: memory following a code branch). When memory IS the work (standalone reconcile/prune/capitalize) there is no branch to follow → it fell back tomain. A multi-repo raccord committed 5chore(memory)direct onmainand nothing flagged it — the exemption worked as designed, masking the divergence with the "all via branch" rule (LRN-084). The aiguillage closes the SKILL path without taxing the side-car. The hook can NEVER enforce "from develop" (only "not on a protected base") → that half lives ONLY ingitflow_start. - Alternatives rejected:
- (A) remove the
.claude/**exemption — breaks standalone/capitalize+/closeon main/develop (commit in place, no branch of their own —memory-commit.shhas no protected-base guard) AND every side-car commit; over-reaches the leak. - (C) codify exemption + human habit — enforces NOTHING mechanically; goal was automatic.
- (D) narrow the exemption by size/scope in the hook — fuzzy, false positives.
- (A) remove the
- Honest residual: a MANUAL
git commitof.claude/**onmainstill passes — B covers the skill path only. Non-blocking hook WARN on manual.claude/**-on-main = DEFERRED. See BDR-034, BDR-039, LRN-084.
BDR-046 — Claude Code installs via the official native installer, not npm
- Date: 2026-07-01
- Decision: install.sh fresh-machine branch installs Claude Code via
curl -fsSL https://claude.ai/install.sh | bash(official native installer), notnpm install -g @anthropic-ai/claude-code. Skip-if-present guard unchanged. update-all.sh stays channel-aware (native →claude update, legacy npm → npm). - Why: official quickstart (code.claude.com/docs) lists Native (recommended) / Homebrew / WinGet / apt only — npm is NO longer a documented channel. npm collided with the native symlink
~/.local/bin/claude→ EEXIST (BLK-014), and npm bypasses native background auto-update. install-plugins.sh already pointed to code.claude.com (native) — install.sh was the npm outlier; this aligns them. - Alternatives rejected:
- (A) keep npm on fresh install — deprecated channel, re-introduces the EEXIST class on any machine with a prior native install, no auto-update.
- (B)
claude installsubcommand — needs claude already present (chicken-and-egg on fresh machine); curl bootstrap is the documented first-time path. - (C) Homebrew/apt — platform-specific; curl covers macOS/Linux/WSL uniformly and matches the doc's "recommended".
- Honest residual:
curl | bash= pipe-to-remote-bash (accepted: official Anthropic domain, same pattern already used for nvm at install.sh:29). node/npm still installed as prereqs — needed by the plugins step (gsd-pi), not by claude. PATH export added so the auth step finds the freshly-installed binary. See BLK-014, LRN-085. - Status: accepted. Commits
8dc4027+6be627e, branch bugfix/install-claude-idempotent, pending merge. - Update 2026-07-01: MERGED
2393ca5→ develop, pushed — supersedes "pending merge".
BDR-047 — ECC audit → zero import; local config ahead of reference
- Date: 2026-07-01
- Status: accepted
- Decision: audited affaan-m/ECC (legit original, NOT the arabicapp malware clone) read-only for value vs this config. Result: ZERO import. Nothing taken. Clean measure-first outcome — analysis closed.
- Safety (durable, avoids re-audit): ECC = genuine original — 2232 commits,
~1480 by Affaan Mustafa, real contributor long-tail, sequential PRs. No payload:
postinstall = echo, install.sh runs only its 3 reputable deps (@iarna/toml, ajv,
sql.js), ships own supply-chain IOC scanner. Zero injection flags across ALL
categories. NOTE: ECC install.sh auto-runs
npm install→ never run their installer casually; this analysis stayed read-only. - Why zero import (each intuition CHALLENGED, not confirmed):
- RULES (122 files, by-language): ~80% redundant w/ CLAUDE.md, rest dormant
reference. INERT at ECC — nothing reads rules/, their README admits "plugins
cannot distribute rules automatically",
paths:frontmatter aspirational (no auto-routing exists). "take all" refuted. - CONTEXTS (dev/research/review, 3 tiny files): least load-bearing. Delivery via
claude --system-prompt "$(cat)"would OVERWRITE global CLAUDE.md. Harmful as-shipped. "important" refuted. - GUIDELINES: ECC itself demoted to docs/example. Per-project CLAUDE.md (git-tracked) superior.
- INSTRUCTION FILES (AGENTS/RULES/SOUL/WORKING-CONTEXT): redundant or ECC-specific. AGENTS.md "proactive delegation" already mandated here.
- MEMORY/learning: auto hook-capture → confidence-scored instincts. CONFLICTS measure-first (observe-first vs approve-first). Instinct schema parked (gated only).
- eval-harness (the spike): DOCS-ONLY — 271-line SKILL.md, no runner,
/eval define|check|reportexist NOWHERE. Same "belle méthodo / câblage vaporware" pattern as rules. Executable-eval ALREADY covered locally: lib/tests/run-*.sh (code graders) + darwin dim8 (with/without-baseline sub-agent effect testing + git ratchet) + RED-before-GREEN discipline. evals.md = ledger of REAL runs (EVAL-011 ran 20/20, dogfooded) — spike premise "descriptif pas exécuté" was FALSE, corrected.
- RULES (122 files, by-language): ~80% redundant w/ CLAUDE.md, rest dormant
reference. INERT at ECC — nothing reads rules/, their README admits "plugins
cannot distribute rules automatically",
- Lesson: external repo — even prestigious / "d'un boss" — judged on REAL added value to THIS config's axes (typed memory, real harness, gitflow), NOT author reputation. Measuring it revealed local config AHEAD on those axes. Taking a thing "since we analyzed" = sunk-cost. Zero is the honest conclusion. Don't re-propose auditing ECC expecting treasure.
- 2 real gaps FOUND (not rejected — the only concrete fruit of the audit):
- pass@k / reliability-under-repetition — local harness proves PRESENCE (guard fires, often N=1), not RELIABILITY (right output 9/10 under repetition). Blind spot for non-deterministic skill/agent behavior (EVAL-006 flagged "N=6 fleet NOT exhausted").
- re-runnable regression battery indexed on model upgrades — bespoke per-chantier tests, no one-command "re-run behavioral evals for load-bearing skills" when model changes. darwin optimizes on-demand, not a standing gate.
- Both = home-grown ~10-line bash over darwin's test-prompts.json if ever wanted — NOT ECC imports. eval-harness delivers neither (no runner). Separate later decision.
- Alternatives rejected:
- Import eval-harness anyway (sunk-cost "we analyzed it") — rejected: docs-only, capability already covered, adds vocabulary not machinery.
- Import rules by-language + build wiring hook — parked: low ROI (bash/md, not polyglot); hookify-rules would be the mechanism, someday-if-polyglotte.
- Adopt instinct auto-capture — rejected: conflicts measure-first.
- Optional zero-cost nicety (not now): tag evals.md entries w/ grader-type + k
(e.g.
method: code-grader, pass^3) — writing convention, not an import. - Reference: read-only clone (scratchpad), 4 parallel analyzer agents + eval-harness spike, this session. No branch on ECC, no import. See BDR-045 (chore/ aiguillage), BDR-009 (caveman registries).
- Corroboration 2026-07-03 (Opus 4.8 re-audit; repo UNCHANGED — HEAD 81af407
2026-06-29, 2232 commits identical, zero commits since 01/07): 6 parallel analyzer
agents re-verified every BDR-047 fact w/ fresh file:line. rules/ inert (paths: 0
consumers, rules/README.md:333 "cannot distribute rules automatically"); contexts/
overwrite (the-longform-guide.md:68-74
--system-prompt); eval-harness no runner (/eval absent; gan-harness.sh + skill-improvement/evaluate.js exist but hors-scope, deliver NEITHER pass@k nor model-upgrade battery); memory auto-capture conflicts approve-first (continuous-learning-v2 observer-loop.sh:160-164 "Do NOT ask for permission"); distribution = product scaffolding, N/A. ZERO factual divergence. ONE scope gap: BDR-047 never opened hooks/ — ECC's only WIRED subsystem. Fruit: config-protection hook (own idiom, NOT ECC import), shipped feature/config-protection-hook. Lesson holds + refined by LRN-090.
BDR-048 — Deterministic security gate: pinned engine + pinned rulesets (semgrep)
- Date: 2026-07-03
- Decision: semgrep = BLOCKING gate (verify-loops chantier) → engine version PINNED in plugins.lock.json (gsd-pin pattern; update-all.sh honors pin + displays jump cur→pin before
pipx install --force). Rulesets PINNED in-agent:p/security-audit+p/secrets. Never--config auto(registry telemetry + ruleset resolved per-run = non-deterministic gate, LRN-077 class). Never autosemgrep login— Pro rules optional, guide-only (ctx7 pattern). - Rationale: gate blocks HIGH/CRITICAL only (LRN-047); silent engine/rule upgrade = new BLOCKs on unchanged code w/o human decision → gate crying false → ignored. Version jump must be deliberate + visible (bump pin, then
make updateshows the jump). - Alternatives rejected:
latest(pipx house default, graphifyy-style) — fine for comfort tools, wrong for a blocking gate;--config auto— telemetry + non-determinism. - Reference: plugins.lock.json
semgrepentry, install-plugins.sh STEP 7.5, update-all.sh step 6.2 — branch feature/semgrep-installccfecc9. Conditions LRN-047, LRN-085. Coverage caveat of the community rulesets: LRN-092. - Addendum 2026-07-03 (lot 3, measured): rulesets =
p/security-audit+p/secrets+p/owasp-top-ten. owasp-top-ten is REQUIRED not optional — measured on realistic Flask code, the 2-ruleset baseline missed SQL injection + path traversal ENTIRELY (0 findings); owasp's taint rules catch them. Severity map: secrets ERROR→CRITICAL, other ERROR→HIGH (block), WARNING/INFO→reported. Blocking threshold = ERROR (per-RULE, not per-vuln — same class can straddle ERROR/WARNING; blocking WARNING too floods FP). FP measured shell/md only (faunosteo, game: sole added blocking ERROR = Dockerfilemissing-userhygiene, contained by gate-mode diff-scoping). Re-evaluate owasp FP at the first real web/python app project (shell/md repos don't represent where the gate runs). See LRN-094, agents/security-auditor.md branch feature/security-auditor2b297bd. - Status (2026-10-28, upgrade): accepted
BDR-049 — Verifier doctrine: fresh + blind + disk-contract + proof-or-fail
- Date: 2026-07-03
- Decision: conformity verdict comes ONLY from a FRESH verifier subagent per iteration. Input = contract PATH (read from disk — dev restatement structurally unable to interpose) + diff range + optional test cmd. NEVER iteration history: blind, complete verification every time (cost bounded by the main-loop max-3 cap, LRN-083: loops decided in main loop). CONFORME ⇔ all criteria MET + zero out-of-scope. PROOF line mandatory (LRN-048). Mute/unparsable verifier NEVER a PASS: 1 fresh retry, 2nd structural failure = human escalation. Dev-justified out-of-scope enters FILE SCOPE only via a human micro-gate (
[gated]marker) — else the dev justifies everything and scope constrains nothing. Contract on DISK at creation (.claude/tasks/contracts/<date>-<slug>-<HHMM>.md, committed; aborted run → deleted orstatus: aborted, never left dirty). - Rationale: dev self-score is always confident → not a gate. Verifier fed history anchors on prior verdicts → telescopic drift. Context-only contract dies at compaction, the verbatim with it.
- Alternatives rejected: dev self-assessment as gate; cumulative verifier context ("cheaper" but anchored); gitignored run files (lose escalation reference + session-death survival).
- Reference: lib/contract-interview.md + agents/verifier.md + lib/tests/contract-verifier.test.sh (31 locks) — branch feature/contract-verifier
6aed5ee. Behavioral GREEN: planted-gap → ECARTS(2) exact; conform-under-injected-history → CONFORME (blindness held). Twin of BDR-048 (security gate). Conditions LRN-048, LRN-083. - Status (2026-10-28, upgrade): accepted
BDR-050 — Universal verify+secure pipeline, weighted per flow (loops in the main loop)
- Date: 2026-07-03
- Decision: every dev flow = contract (verbatim, on disk) → dev INLINE → fresh verifier (request conformity) → fresh security-auditor (
MODE: gate) → commit. Loops BOUNDED at 3 and decided in the ORCHESTRATOR MAIN LOOP (LRN-083), never in a subagent. Order invariant: on any security re-loop, re-verify the REQUEST before re-scanning security. Per-flow weight: feat/bugfix = both gates, both loop (nominal 2 dispatches); hotfix = NO fresh verifier (its smoke-check verifies the trivial autofill contract), security gate whose FAILURE REVERTS (git restore+ escalate to /bugfix), never loops — the 1-attempt model preserved (nominal 1 dispatch). Shared includelib/verify-secure-loop.mdfor feat/bugfix; hotfix inline variant. - Rationale: the value is the INDEPENDENCE of the gate (fresh subagent vs a rich contract), NOT delegating the dev — so dev stays inline in light flows and weighting lives on loops+questions, never on skipping a gate. hotfix reverts because a 3× loop would reintroduce the weight its identity excludes.
- Alternatives rejected: dispatch the dev too (turns feat into ship-feature-bis); one merged "quality" gate (see LRN-095 — orthogonal gates degrade if fused); hotfix loops like feat (breaks its 1-attempt identity).
- Reference: lib/verify-secure-loop.md + wired feater/bugfixer/hotfixer + lib/tests/loops-light.test.sh (27 locks) — feature/verify-loops
0f0162d. Behavioral GREEN (feat fixture): CONFORME→BLOCK(1) SQLi→fix→re-verify CONFORME→re-scan PASS, order invariant held. Builds on BDR-048 BDR-049. Conditions LRN-083 LRN-095. - Status (2026-10-28, upgrade): accepted
BDR-051 — Contract enrich-at-gate: the contract grows only at a human micro-gate
- Date: 2026-07-04
- Decision: CONTRACT's REQUEST immutable; ACCEPTANCE CRITERIA + FILE SCOPE may GROW — exclusively at a human gate, each added entry tagged
[gated <date>]. Heavy flows (ship-feature STEP 3, init-project GATE #1): approved DESIGN appends design-derived criteria to the contract; the fresh verifier then judges the diff against the ENRICHED contract, never the seed. Same mechanism as the out-of-scope micro-gate (BDR-049) — a dev never enriches; only the human validating a gate does. - Rationale: raw request underspecifies (one-line "add validation" hides the schema-rejection requirement the design surfaces); verifier judging only the seed → every design decision unverified. Gating the growth keeps the contract honest (no silent scope creep) AND complete (design criteria are verified). Only flow where the contract is mutable mid-run — bounded to gate moments.
- Alternatives rejected: freeze contract at creation (design criteria unverified — seed too thin); let dev enrich (BDR-049 failure mode — dev justifies everything, scope constrains nothing); second contract per design (loses single-reference property).
- Reference: ship-feature STEP 0e+3, init-project STEP 1+4, feature/verify-loops
1c69de2. Behavioral GREEN: a[gated 2026-07-04]design criterion (reject unknown config keys) was read + judged NOT-MET by a fresh verifier across 3 rounds (dogfood). Builds on BDR-049 BDR-050. - Status (2026-10-28, upgrade): accepted
BDR-052 — /tour auto mode: branch-as-gate, declared state read-only
- Date: 2026-07-05
- Decision: /tour (grouped sweep clean+security+reconcile+doc, 1..N projects) runs auto, NO mid-run approval gates. Compensations: (1) fixes on
chore/tour-<date>via gitflow lib, skill NEVER finish/merge/push — unmerged branch + per-project append-only.claude/audits/TOUR.md= the human gate, deferred not deleted; (2) reconcile phase REPORT-ONLY even in auto — target TODO + registries read-only, gaps =suggestedrows applied later via /reconcile; (3) convergence loop bounded 3× (LRN-083), residuals reported honestly; (4) security floor = security-auditor (pinned semgrep, LRN-047 BLOCK HIGH/CRITICAL) every iteration + cso posture once (gstack ON); CRITICAL/HIGH contract-changing fix applied but tagged BREAKING in report+summary; (5) dirty tree / no develop / no lib → report-only, never stash, never hand-branch. - Rationale: mid-run gates defeat the skill's point (hands-off grouped sweep, user away). Auto-checking TODO reproduces the exact lie /reconcile catches — RED-proven, baseline did it. Branch+report = same approval semantics as audit-delta's 3c gate, moved after the fact where a headless run can afford it.
- Alternatives rejected: per-phase AskUserQuestion gates (audit-delta model — blocks headless); one consolidated pre-fix gate (still blocks); auto-edit TODO on oracle proof (inference ≠ approval); plain-branch fallback on non-gitflow repos (violates lib-only doctrine → report-only instead).
- Reference: skills/tour/SKILL.md + CLAUDE.md routing (feature/tour-skill
73e6a1c). TDD trail LRN-099 LRN-100 EVAL-014. - Status (2026-10-28, upgrade): accepted
BDR-053 — ctx7 single surface: keep find-docs skill, kill context7.md rule
- Date: 2026-07-06
- Decision: ctx7 gets ONE session surface =
skills/find-docs(lazy body, description-only cost).rules/context7.mddeleted + install-plugins.sh STEP ctx7 purges it unconditionally post-setup (rm -f, generator has no skip-rule flag —--claude/--cli= target/mode only). darwin-skill entry dropped from skills-lock.json same pass (F8: lock stale6bbcda37…vs diskc3220018…, no re-pin verb in npx skills — unpinned rather than hand-edit undocumented hash). - Rationale: rule = ~490 tok/session session-start duplicate of the skill (job1 F10 + job2); skill self-suffices (876-char description carries the triggers, body has full CLI flow). Purge-in-installer beats one-shot rm: survives re-runs + manual
ctx7 setup. - Alternatives rejected: kill skill keep rule (rule always-on, costs every session even non-lib work; skill lazy — wrong direction); hand-trim generated files (fight the generator, LRN-039 class); hand-edit lock hash (algo undocumented).
- Reference: chore/ctx7-single-surface; job1 F10, job2 F8/F13. User decision 2026-07-06.
- Status (2026-10-28, upgrade): accepted
BDR-054 — supersede BDR-038: NEXT.sh file + AskUserQuestion hand-back removed from /deploy
- Date: 2026-07-06
- Status: accepted (supersedes BDR-038 on 2 points: NEXT.sh artifact, hand-back mechanism)
- Decision: /deploy ships WITHOUT NEXT.sh file (checklist display-only, conversation-only) and WITHOUT AskUserQuestion hand-back (plain final-text print, turn ends, no tool call after). BDR-038's original 5-artifact list (PROCEDURE.md, INCIDENTS.md, STATE.json, PENDING.json, NEXT.sh) shrinks to 4 committed/bridge artifacts — NEXT.sh no longer written. Two-moment spine (BEFORE/AFTER), PENDING.json bridge, deploy-commit.sh atomic patch+incident — all unchanged, still current per BDR-038.
- Why: LRN-102 — deliverable text printed before a tool call may never render (harness guarantees only the turn's FINAL text); AskUserQuestion after the checklist swallowed it silently, live run 2026-07-05 (bchanot-cv). NEXT.sh-to-disk also useless in practice (user: throwaway once deployed) — display-only kills a stale-file-drift class for free.
- Alternatives rejected: keep NEXT.sh, fix hand-back only (leaves ephemeral-file-nobody-reads problem); keep AskUserQuestion, cram checklist into its options text (char-limited, brittle); revert to file+question (reproduces the exact LRN-102 bug).
- Reference: commits
31443ba(inline hand-back print),52f6678(checklist display-only, no NEXT.sh);skills/deploy/SKILL.md:74-77,295-297,313-318,440-441; LRN-102; job3 docs-drift audit D6/D7/D9 (.audit/job3-report.md).
BDR-055 — job5: delete pending verbs, close J4-17 MOOT
- Date: 2026-07-07
- Status: accepted
- Decision:
memory_pending()+docs_pending()+pendingdispatcher arms deleted fromlib/memory-commit.sh/lib/doc-commit.sh, plus stale "for the v2 hook" header mentions.commit/commit <message> <file>...= only verb left. J4-17 (job4 backlog: "extend run-deterministic.sh to test pending") closed MOOT — its premise gone with the verb. - Why: headers earmarked both funcs "for the v2 hook" — BDR-037 REJECTED v2 hook, no code ever written. J4-17 queued TEST not DELETE, but deferred to the newer/wrong branch — v2 hook dead means nothing left to test toward. Zero prod/test callers confirmed (job5 audit) before delete.
- Alternatives rejected: keep+test per J4-17 (tests a dead-end, BDR-037 already closed that door); keep unused (dead code, no consumer).
- Reference: commit
da3abf9;.audit/job5-report.mdJ5-13/§3b; supersedes J4-17 (.audit/job4-report.md:35). Same supersession-trace discipline BDR-054 had to backfill for BDR-038/job3 D6-D9 — written here at delete time, not reconstructed later.
BDR-056 — job6: deps policy = latest gated by integration, not KEEP-PINNED by default
- Date: 2026-07-07
- Status: accepted (reverses job6-batch-3 KEEP-PINNED-unless-CVE default)
- Decision: default posture = pull latest, gated per-dep by real integration checks (make test + named smoke), not "keep pinned unless a CVE forces the hand". Sequenced by risk, one upgrade = one commit = one gate, immediate rollback on red. Applied job6: ctx7 0.5.3→0.5.4, gsd-pi 2.64.0→3.0.0, gstack 070722a→11de390 (v1.52.1.0→v1.58.5.0), graphifyy binary 0.9.6→0.9.8 (hook-adoption declined separately, see below).
- Why: job6-batch-3's expected verdict for gstack was KEEP-PINNED sauf CVE; user overrode it — a fail-open security-guard fix (#1911, no formal CVE) counts as the CVE clause in substance, and staying pinned to avoid work means carrying live-vulnerable tooling. Gating on integration tests (not on "did upstream file a CVE") catches the real risk (format/behavior breaks) that pin-forever also fails to prevent — gsd-pi 3.0.0 broke status-reporter's ROADMAP.md parser silently (0/0 instead of an error); the gate caught it before merge, KEEP-PINNED would have avoided the break but also frozen out #1688 (gsd-pi data-loss fix) and the gstack #1911 guards indefinitely.
- Alternatives rejected: KEEP-PINNED unless CVE (job6-batch-3 default) — optimizes for zero-gate-work, pays for it by sitting on fail-open security guards and data-loss bugs with no formal CVE filed; blanket "always latest, no gate" — the gsd-pi break shows why the gate stays mandatory, this is not a license to skip it.
- Caveats: not every dep took the full pull — graphifyy's hook-guard rewrite (a config-protected file) was surfaced with a diff and the user declined to adopt it this round (binary upgraded, hook install skipped); MCP magic version pin was declined by user call. Policy is "latest, gated", not "latest, no exceptions".
- Reference:
.audit/job6-report.md; commitsb4896c9(gsd-pi),2813e55(gstack),00c97bc(docs); LRN-107 (secrets-subagent value-copy ban, same job's incident).
BDR-057 — job7: secrets by reference not by value; redact at capture, not just at rest
- Date: 2026-07-07
- Status: accepted
- Decision: two-part posture from the job7 triage (
.audit/job7/ALL-REDACTED.json, 5+ leak classes across~/.claudeand repos). (1) Wherever the consuming tool supports it, wire secrets BY REFERENCE (${VAR}expansion), not by value — closed the concrete case:lib/toggle-external.sh'sclaude mcp add magic --env API_KEY="$MAGIC_API_KEY"materialized the key as plaintext into~/.claude.json(a 2nd copy outside the~/.claude/.envcanonical); fixed to--env 'API_KEY=${MAGIC_API_KEY}', with the var reachingclaudeonly via a scoped~/.bashrcwrapper function (subshell + exec — never the ambient shell). (2) Redact AT THE CAPTURE POINT, not just after the fact:hooks/rtk-rewrite.shnow appends a redaction pipe to bareprintenv/envdumps before they can reach stdout/the transcript (the GITEA leak's actual vector), instead of relying solely on scrubbing artifacts after the fact. - Why: the job6 incident (LRN-107) and the GITEA leak both trace back to a secret VALUE existing somewhere it didn't strictly need to (a config field, a raw env dump) rather than a reference/redacted form. Fixing storage-at-rest (scrub backups) treats the symptom and must be redone every time a new copy appears (5 rotating
.claude.json.backup.*files, 2 of 5 still had it live mid-job7 despite the canonical fix already applied) — fixing the SOURCE (don't materialize the value; redact before the dump leaves the process) is the only version that doesn't need repeating. - Alternatives rejected: scrub-only (job7's own fallback if reference support were absent) — verified Claude Code DOES support
${VAR}expansion inmcpServersconfig (user + project scope,env/command/args/url/headersfields — code.claude.com/docs/en/mcp.md) → reference form available, preferred; globalexport MAGIC_API_KEYin~/.bashrc— works but exposes the secret to every subprocess of every shell, defeats the redaction hook (user rejected, scoped wrapper kept). - Reference:
lib/toggle-external.sh:191-192,hooks/rtk-rewrite.sh,README.md"Adding an MCP server that needs a secret",.gitleaks.toml,lib/gitflow.sh_gitflow_emit_pre_commit,Makefilescan-secrets; commitsb9300c3/3340c7d/17bdd08/5d5b386. Linked to BDR-026 (canonical vault this closes a leak vector against), LRN-108 (theclaude mcp add --envtrap). - Caveat — contradicts job6's own finding same day: job6 journal (2026-07-07, earlier same day): "
${VAR}env-expansion confirmed unsupported at~/.claude.jsonuser scope after 2 rounds of sourced doc lookup". job7 lookup (claude-code-guide agent, same day): IS supported at user scope, citing code.claude.com/docs/en/mcp.md + a v2.1.161 changelog entry. Not reconciled — could be a version bump between the two lookups, or job6's research being wrong.${MAGIC_API_KEY}rewrite live (claude mcp listrecognizes the reference, reports the var missing → CLI PARSED the${...}syntax); end-to-end confirmation (restart terminal + Claude Code, magic MCP reconnects) still a user residual — see BDR-057's own commit message.
BDR-058 — job8: darwin-skill reinstall full pinned tree, detached HEAD
- Date: 2026-07-07
- Status: accepted
- Decision: darwin-skill non-functional past SKILL.md text —
references/,scripts/,templates/absent, referenced but never fetched. Root cause:~/.agents/.skill-lock.jsonskillPath: "SKILL.md"— installer (skillsCLI, vercel-labs/skills) fetches ONLY that one file, not sibling dirs. Upstream repo HEAD (7c7b7909b630dc3b5cbb91bd4bcb1b10bfb1f894) matches lockfile hash exactly — zero drift, zero tamper, SKILL.md byte-identical old vs new. Fix: cloned upstream at that SHA, copied full tree into~/.agents/skills/darwin-skill/, verified all 5 referenced paths present, HEAD detached (no branch tracking, no silent advance on a straygit pull). Old single-file dir backed up to~/.agents/skills/.job8-backups/darwin-skill.single-file.<ts>first. - Why: user picked reinstall-pinned over remove/keep-broken (job8 audit §4 item 4, 3-way choice). Unverifiable skill can't be trusted; user wants the optimizer kept, not removed.
- Alternatives rejected: remove entry (kills wanted function); keep as-is (fails job8's own audit bar — unverifiable); flat-copy without
.git(matches other 34 dormant skills' convention but drops verifiable pin — kept.gitdetached instead, darwin-skill now 2nd real SHA-pin in the whole trust chain after gstack, job8 report §5). - Reference:
~/.agents/skills/darwin-skill/(detached HEAD7c7b790),~/.agents/.skill-lock.json(untouched, hash still accurate), backup at~/.agents/skills/.job8-backups/. Outside this repo — no commit here covers the file placement itself, this entry is the record. Git-commit whole-.claude/skills-tree scope (job8 C.2,SKILL.md:115/201) NOT restricted — 3rd-party pinned code, patching it breaks the pin; accepted as documented risk, human-checkpoint-gated per job8 report. Linked to LRN-109.
BDR-059 — job8: explicit ask-gate for all 4 magic MCP tools, empty allow stays empty
- Date: 2026-07-07
- Status: accepted
- Decision:
settings.jsonpermissions.asknow explicitly lists all 4mcp__magic__*tools (21st_magic_component_builder,21st_magic_component_refiner,21st_magic_component_inspiration,logo_search).permissions.allowgets ZERO magic entries — no allowlist tightening, the job8 report's "frictionless" diff (allowlist logo_search + inspiration) was explicitly rejected. Confirmation required on every magic call, no exceptions, no auto-exec ever, no wildcard. - Why: job8 §3/§4 found zero real
mcp__magic__*invocations ever (transcript census) and one SUSPECT finding (21st_magic_component_builderunauthenticated callback-injection channel, LRN-110). Prior state relied on undocumented absence-means-ask fallthrough — user wants the gate EXPLICIT so it can't silently regress ifpermissions.allowever gets a careless wildcard or the default-mode semantics change. - Alternatives rejected: leave everything absent (report's own recommended default) — works today but is silent/undocumented, exactly the posture the user wanted to close; allowlist
logo_search+21st_magic_component_inspirationfor frictionless design work (job8 report §3 "frictionless" diff) — explicitly declined, real usage is zero so friction costs nothing. - Reference:
settings.jsonpermissions.ask, commitbb7f25a. Linked to LRN-110 (component_builder risk), LRN-111 (empty-allowlist validity when usage is zero).
BDR-060 — job9: CC orchestration floor = v2.1.172 (nested dispatch), supersedes implicit v2.1.83 whole-system floor
- Date: 2026-07-08
- Status: accepted
- Supersedes: implicit "v2.1.83 = whole-system floor" premise (a misread of BDR-004's
decisions.md:133auto-mode caveat). - Decision: orchestration floor for any NESTED subagent dispatch = Claude Code v2.1.172 (nesting stabilized: "let subagents spawn their own subagents", hard cap 5 levels,
Agentmust be in the subagent'stools:to nest). Live env confirmed v2.1.203 (user, nesting supported, cap 5). BDR-004:133 stays UNCHANGED — itsv2.1.83+is correct for AUTO MODE specifically; the nesting floor is a distinct, higher constraint recorded here (registry is append-only, and BDR-004 is factually right for its scope). - Why: the whole job1-9 audit series operated on the premise "CC flattens to 1 level → a 2-level subagent design is silently broken." That describes the pre-2.1.172 regime. Corrected in job9 via
claude-code-guide(official docscode.claude.com/docs/en/agent-sdk/subagents.md) + user confirmation of live v2.1.203 → depth findings are VERSION-CONTINGENT, not broken. Path b (BDR-061) removes the seo/geo analyzers' dependence on nesting, but client-handover'sgeneral-purpose → /seo → seo-analyzerchain still nests (L1→L2), so the floor stands for the orchestration design. - Alternatives rejected: keep the implicit v2.1.83 floor — predates nesting, mislabels version-contingent flows as "BROKEN"; hard-gate CC version in
doctor.sh— deferred (path b de-risks the analyzers; a doctor warn-gate is an optional follow-up, anddoctor.shis config-guarded → sentinel cost not justified now); raise BDR-004:133 to v2.1.172 — WRONG, that caveat is auto-mode-specific (auto mode works from 2.1.83) and rewriting it would violate append-only + inject a factual error. - Reference:
.audit/job9-report.md§Premise + §6 D-version-floor;decisions.md:133(BDR-004 auto-mode caveat, unchanged). Linked to BDR-061 (path-b), LRN-112 (nesting mechanics).
BDR-061 — job9: seo/geo analyzers emit a fix-bundle applied at L1 by doctrine (validator-analyzer pattern)
- Date: 2026-07-08
- Status: accepted
- Decision:
seo-analyzer+geo-analyzerre-architected to thevalidator-analyzercontract — they AUDIT and EMIT a machine-parseable## FIX BUNDLEterminated by the verbatimREADY TO APPLY — awaiting dispatcher confirmationsentinel; they NEVER edit code and NEVER dispatch a sub-agent (Agentdropped from bothtools:). The DISPATCHER applies at L1 from its own main loop:/seo(new STEP 1.5) +/geo(rewritten to dispatch+apply, mirrors/web-validate) dispatchhotfixer/featerat L1;/hardenkeeps its existing direct-Edit STEP 3 (already end-to-end path-b);/onboardstays audit-only (bundle produced, deferred to backlog STEP 9). AUTO tier applies unconfirmed; GATED tier (seo D/E · geo G5) requires explicit accord; USER ACTIONS → report §11. - Why: by DOCTRINE, not version constraint. Before: analyzer STEP 12/13 dispatched hotfixer/feater; when the analyzer was itself a subagent (
/seo→ analyzer at L1), that dispatch was L2 nesting → silent no-op on CC<2.1.172, and both analyzers forbade direct edits → the reported bug: report produced, ZERO fix applied. The bundle→L1 pattern (a) lands fixes on ANY CC version (single dispatch level), (b) gives fresh-context specialist fixes without depth risk, (c) dissolves the/seoparallel-edit race (fixes now applied serially by the dispatcher, by file ownership)./hardenalready proved the pattern in-repo. Chosen even though BDR-060 confirms live nesting works — version-robust by design beats version-contingent. - Alternatives rejected: only raise the version floor (BDR-060 alone) — leaves the analyzers version-contingent, and the
/seonested-fix design fragile; keep analyzers self-applying but require CC≥2.1.172 — works on current env but not robust and keeps the parallel-edit race; make the dispatcher apply via direct Edit everywhere (like /harden) instead of hotfixer/feater — loses the fresh-context specialist fix; kept direct-Edit only for /harden's tiny scope. - Verification:
make testgreen + 4 real smokes — analyzer emits bundle + edits nothing (md5 unchanged); AUTO fix lands on disk via L1 hotfixer with no confirmation (the exact previously-broken path); GATED withheld pre-approval then applied post-accord; /onboard writes only the report, zero source files. - Reference:
agents/seo-analyzer.mdSTEP 12,agents/geo-analyzer.mdSTEP 13,skills/seo/SKILL.mdSTEP 1.5,skills/geo/SKILL.md,agents/validator-analyzer.md(reference contract),.audit/job9-report.md§6 option (b); commitsa5a7b54/6df42e4/c498b93/70fb3b4. Linked to BDR-060 (nesting floor), LRN-112 (nesting mechanics).
BDR-062 — supersede BDR-031's 275-line CLAUDE.md target: 305 is the assumed reality
- Date: 2026-07-08
- Status: accepted (supersedes the 275-line density TARGET of BDR-031 only; BDR-031's core principle — lightening = compression, not path-scope/externalization — stands unchanged)
- Decision: global CLAUDE.md sits at 305 lines, stays there. job1's density pass took it 319→305 and no later job re-inflated it; the extraction BDR-031 called for is done. Old 275 target (or 280 guard) now costs clarity more than tokens saved.
hooks/session-start.shguard threshold realigned 280→320: still catches genuine regression (bloat past 320), stops firing permanent "density pass requis" warning on assumed-final 305. - Why: the review (
.audit/review-release-1.0.0.mdA6) found the guard had warned every session since job1 without the target ever being met — a self-inflicted permanent warning, not an actionable signal. A gate that never goes green trains you to ignore it. Realign to reality; 15-line margin keeps real regressions visible. - Alternatives rejected: (a) finish the compression 305→≤275 — the remaining lines are load-bearing constraints, not filler; further squeeze loses clarity for a marginal token gain on a solo repo. (b) leave guard at 280, accept permanent warning — permanently-red non-blocking gate is noise. (c) rewrite BDR-031 — registries append-only; supersede target, keep principle.
- Reference:
hooks/session-start.sh:202-211; supersedes the 275 target in BDR-031 (principle kept). Review remediation A6, 2026-07-08.
BDR-063 — GSC multi-account: OAuth2 installed-app flow + label-keyed token store
- Date: 2026-07-10
- Status: accepted (shipped
bb1fbb2, develop) - Decision:
/seoFULL pulls real Search Console + CrUX via alib/seo-data/engine. Auth = OAuth2 installed-app flow (one-time interactive consent,make seo-connect), scopewebmasters.readonlyONLY (least priv). Refresh tokens in per-label store~/.claude/seo-data/tokens.json(0600 file / 0700 dir, atomic tmp→fsync→rename under fcntl lock, tokens redacted from listing, gitleaks-allowlisted).(account, property)explicit args on every call — NO global mutable "current account" → two concurrent site audits never conflict. - Why: user needs real field data (the one edge marketplace
claude-seohad that personal skills lacked); multi-account without cross-site leakage; secrets never in code (all from~/.claude/.env). - Alternatives rejected: (a) service-account — GSC needs per-property owner grant + no interactive consent, wrong for a personal multi-client tool. (b) API-key-only — GSC has no key auth (CrUX does →
CRUX_API_KEY). (c) single "current account" global + switch verb — a race the moment two audits run; explicit args dissolve it by construction. - Reference:
lib/seo-data/(tokenstore.py, connect.py, google_seo.py, fetch.sh),lib/seo-data/README.md; fronted by LRN-119 (fail-open contract).
BDR-064 — Global memory split: repo global file → CLAUDE.global.md, CLAUDE.md freed for project scope
- Date: 2026-07-14
- Status: accepted (shipped feature/claude-global-md-rename, merge pending human GO)
- Decision: repo-root global memory
git mv→CLAUDE.global.md; deployed name unchanged (~/.claude/CLAUDE.mdsymlink via link.sh).CLAUDE.mdname freed → real project-scope memory for claude-config (Health Stack + rules/ doctrine — ex-"This repo only" section + ex-rules/README body; rules/README = 3-line pointer, keepspaths:frontmatter). Wording rule (user-arbitrated): consumer-facing hook strings say "global CLAUDE.md" (deployed name — foreign sessions resolve via symlink, repo filename means nothing there); maintainer comments sayCLAUDE.global.md. Guards follow: session-start 320-guard path, doctor EXACT readlink-target check (new), GUARDED_CONFIGS 4 entries (keeps "CLAUDE.md" — graphify rewrite target = project file now), doc-commit exclusions, CHANGELOG BREAKING(layout) line ("run bash link.sh once after pull"). - Why: "This repo only" section + rules/README doctrine loaded in EVERY project (~40+280 tok waste + foreign-project glob over-match); repo had no project-scope memory slot — filename occupied by global content.
- Alternatives rejected:
CLAUDE.prod.mdname ("prod" implies deploy env that doesn't exist); project.claude/rules/repo.md(works, less idiomatic than project CLAUDE.md, no natural home for future repo-specific content). NOT a revival of BDR-021's rejected 2-file split — that was global content in 2 SYNCED files; here scopes disjoint, zero sync. - Reference: feature/claude-global-md-rename (
9496538rename R98%,e9a38a0guards), specdocs/superpowers/specs/2026-07-12-claude-global-md-rename-design.md. Linked BDR-021, BDR-031, BDR-062, LRN-122, LRN-123.
BDR-065 — Transient planning artifacts: committed during run, deleted post-merge
- Date: 2026-07-14
- Status: accepted
- Decision: superpowers spec/plan docs (
docs/superpowers/{specs,plans}/) = run-time artifacts. Lifecycle: committed as feature branch's first commit (subagent briefs extracted from plan on disk; verifier + final review reference them; survive compaction + foreign worktrees) → DELETED in post-merge cleanup chore. Git history at the feature commits = the archive (git show <sha>:docs/...recovers them). Durable knowledge lives in.claude/memory/registries + contract files, never in spec/plan. Codified in project CLAUDE.md §Transient planning artifacts. - Why: user call 2026-07-14 — registries already capture decisions; a stale plan describes a superseded intermediate state and misleads future readers; accumulation pollutes the repo. Precedent: gsc-crux cleanup (
8a1fac0, 2026-07-10) did the same — this makes it law, not habit. - Alternatives rejected: never-commit (gitignore docs/superpowers) — breaks mid-run: briefs, reviewers, other-machine checkouts need the files; superpowers brainstorming commits the spec by convention. Keep-forever — the drift + pollution complained about.
- Reference: project CLAUDE.md; cleanup commit this chore; precedent
8a1fac0. Linked BDR-064, LRN-124. - Amendment (2026-07-22): DELETE side now AUTOMATED —
lib/gitflow.sh_gitflow_purge_transientatgitflow finish(feature/bugfix, pre-merge, on HEAD) git-rm'sdocs/superpowers/{specs,plans}+ scoped commit → develop TIP clean, feature commits stay reachable (git show <sha>:…archive intact). Best-effort: NEVER aborts finish (nothing-tracked no-op / dirty-path skip / commit-fail index+tree restore). Opt-outGITFLOW_PURGE_TRANSIENT=0. Retires the manual chore that slipped (655e364). Universal via~/.claude/lib→repo symlink (ship-feature STEP 9 + init-project STEP 11 both finish through it). gitignore STILL rejected — unchanged: breaks superpowers'git addof the spec (silently skipped, no travel to SDD worktree)..claude/tasks/{contracts,plans}kept versioned (user call — durable, referenced by decisions.md). Tests: gitflow-test.sh T17 a-d. LRN-138.
BDR-066 — Model routing: reflection inline (session big model), executors pinned sonnet, blocking gate
- Date: 2026-07-15
- Status: accepted (partial supersede of BDR-050: /feat dev no longer inline; bugfix/hotfix dev-inline CONSERVED)
- Decision: reflection (brainstorm, plan, contract, audit judgment, loop decisions) runs on session model (Fable; Opus fallback) — inline or inherit subagents, never pinned down. Execution (code from closed plan, fix-bundle application) runs sonnet-pinned subagents: feater + hotfixer pinned sonnet; SDD implementation+review subagents dispatched
model: "sonnet"(ship-feature/init-project); web-validate fixes via hotfixer L1 (was inline Edit). analyzer haiku pin REMOVED (digest feeds plan = reflection tier). verifier + security-auditor STAY sonnet (job9 confirmed — procedural gates, ≤3×/loop). Blocking gatelib/model-gate.md(self-check + witnesslib/model-check.sh) wired in 12 reflection orchestrators; small → STOP, unknown → fail-visible; census guardlib/tests/model-routing.test.shflip-tested. - Why: big-model quota burned on mechanical execution (Fable exhausted mid-job8); plan closed at dispatch → executor needs obedience not judgment; fresh sonnet gates catch executor drift.
- Alternatives rejected: opus pins on audit agents (session-independent) — rejected: session assumed big + blocking gate as backstop, one tier fewer; advisory gate — rejected by user, blocking; split bugfix/hotfix too — rejected: bugfix investigation interleaved w/ fix, hotfix gain marginal vs dispatch overhead.
- Caveats: client-handover-writer conversion (inline-load → sonnet dispatch, 11 human-gate sites to relocate) DEFERRED to own plan — its opus pin stays inert meanwhile; feater cannot ask → NEED-DECISION report = escalation valve, plan must close decisions; witness reads settings.json — lags
--model-launched sessions (self-check compensates). - Caveat (execution): /feat re-arch broke 5 stale assertions in lib/tests/loops-light.test.sh (locked OLD feater architecture) — repointed to skills/feat/SKILL.md (FSK, mirrors HOT/HSK split) + new dispatch lock + 1-line reflow in feat SKILL for single-line grep lock (LRN-093 class).
- Wave 2 (2026-07-15, user directive): wave-1 exclusion list left execution running on the big session model = the waste this split kills. REVERSES the "split hotfix rejected" alternative above (reason held for bugfix — investigation interleaved w/ fix — but NOT hotfix: LOCATE→apply is linear/separable). Changes: /hotfix split like /feat (LOCATE reflection inline + MODEL GATE, hotfixer sonnet EXECUTOR — rewritten dual-use: also the seo/geo/web-validate L1 applier; revert-not-loop preserved) → hotfix JOINS gated group, census 12→13. /commit-change dispatches sonnet commit-changer (propose→dispatcher gates→apply; grouping ON sonnet so NO model gate; AskUserQuestion dropped from agent). /release-candidate dispatches new sonnet release-executor (2 spans prep/finish; when-to-release + push + version-number decision STAY in dispatcher). /doc → doc-syncer (sonnet) dispatch; /status → status-reporter (kept HAIKU — right tier for read-only collection; win = off big model, not the tier). Gate exclusion list now = commit-change/doc/status/release-candidate. Consumer-staleness swept (LRN-113): feat Rule 1 DOWNGRADE + feat commit-split both repointed off the bare executor agents to the /hotfix + /commit-change skills.
- Wave 3 (2026-07-15/16, user directive): split the last two inline execution-carrying agents like /feat. /bugfix: investigation+diagnosis+contract inline behind the gate; bugfixer = sonnet EXECUTOR (fix + regression test from a closed FIX PLAN; no Agent/AskUserQuestion; BUGFIX-EXEC REPORT). verify+secure loop stays in main loop, executor = its re-dispatched dev (verify-secure-loop.md intro now: BOTH consumers dispatched, no inline branch). FINISHES reversing the "split bugfix rejected" carve-out (hotfix went wave 2, bugfix now) — investigation↔fix coupling accepted, mitigated by structured DIAGNOSIS + verify loop. /code-clean: PHASE-1 audit + validation gate inline (reflection); code-cleaner = sonnet PHASE-2 EXECUTOR (delete approved dead code, inline-load refactorer, re-audit) — refactor NOW on sonnet (inline-load pin was inert on big model). exported-symbol per-item consent stays AT THE GATE. Consumer-staleness swept: hotfix deeper-bug escalation → /bugfix skill (not bare agent); onboard STEP 6 + tour Phase B read-only-audit → general-purpose/analyzer (big model, NEVER the sonnet executor — audit stays big). Both skills STAY gated. Also: Explore built-in kept inheriting session (search feeds reflection = big deserved; custom sonnet override created then reverted — built-in already inherits + no owned prompt). census 36→42, loops-light repointed 35/0.
- Wave 4 (2026-07-16): client-handover doc-gen → sonnet, REDACTION-ONLY (user flipped from whole-writer after the full read). Key finding: nested audits (/seo,/harden,/web-validate — gated wave 1) must run BIG either way → whole-writer = ~7 extra gate-yields + resumable state machine on a CLIENT deliverable for ~0 extra sonnet work. Design: client-handover-writer TRIMMED to ship pipeline (STEP 1-8, all interactive gates native on big, nested audits inherit big) + doc-gen orchestration (resolve questions/NAP/precheck/overwrite/client-name inline → PACKAGE) → dispatches NEW sonnet handover-doc-writer (STEP 9-16: reads memory+git, synthesizes 6-chapter doc, word-count/skill-leak/anchor gates, renders HTML+PDF; GATE-FREE, no AskUserQuestion/Agent). client-handover JOINS gated group (orchestrates audits = reflection); its opus pin dropped (inherits big via inline-load). census 42→46. Branch feature/client-handover-dispatch (off develop, waves 1-3 merged first).
- Reference: spec
docs/superpowers/specs/2026-07-15-model-routing-design.md+ plandocs/superpowers/plans/2026-07-15-model-routing.md(transient, BDR-065 lifecycle), branchesfeature/model-routing(waves 1-3, merged),feature/client-handover-dispatch(wave 4).
BDR-067 — first public release: versioning reset to v1.0.0 (override "never restart at v1.0.0") — 2026-07-16
- Decision: first PUBLIC release cut as v1.0.0, treating internal v1.0.0→v4.0.0 as pre-release history. version.txt 4.0.0→1.0.0; CHANGELOG: new
[1.0.0] — Initial public releaseon top (= former[Unreleased]content), old 1.0-4.0 lineage moved UNCHANGED under a## Pre-release (internal history)banner (provenance). Tag v4.0.0 DELETED (local+origin), v1.0.0 tagged on main. Repo goes public on THIS Gitea (user flips visibility separately — not a git op). - Why: launching publicly at v4 misrepresents (implies missed v1-3 to newcomers); v1-4 were private dev. First public impression should be v1.0.0. User directive.
- Overrides: BDR-055-era release-candidate rule "never restart at v1.0.0 — desyncs tag↔CHANGELOG lineage". That guards ACCIDENTAL mid-lineage restart; a DELIBERATE public-launch reset is the sanctioned exception. CONSEQUENCE for next release: continue from public 1.0.0 (→ 1.0.1 / 1.1.0 / 2.0.0), NEVER back to the old 4.x. The [Unreleased]-BREAKING(CLAUDE.global.md) folds into 1.0.0 harmlessly (first release = breaking vs nothing).
- Safety (git cherry): found a STALE abandoned
release/1.0.0(July-4 prep, 227 commits behind develop, pushed to origin).git cherry develop release/1.0.0+ content checks confirmed all its real changes (rtk PATH fix, drop-AI-attribution settings backstop, find-skills drop, BLK-016/LRN-098/LRN-101/EVAL-015, all features) ALREADY in develop → nothing orphaned → deleted it (local+origin). Cut fresh v1.0.0 from CURRENT develop, not the stale branch. - Method: release-candidate skill gates honored (when-to-release, push) but PREP done manually — backward version (4.0.0→1.0.0) + CHANGELOG restructure exceed the sonnet release-executor's forward-bump assumption (reflection, stays big). LRN candidate: a version RESET is editorial, not mechanical — don't dispatch the forward-only executor for it.
- Status: SHIPPED. origin main=dc4f78b, develop=6c23d6f, tag v1.0.0 sole tag; v4.0.0 + stale release/1.0.0 removed from origin.
BDR-068 — /capitalize + /close auto-persist memory (finish→develop + push); scoped LRN-069 exception — 2026-07-16
- Decision: when /capitalize (or /close = --ritual) writes entries AND the aiguillage branched a
chore/<name>off develop THIS run, new STEP 5C auto-finishes that branch → develop + pushes origin/develop. Default ON.--no-pushholds it on the chore branch (pre-BDR-068 behavior). WORKING branch (memory rides feature/bugfix) or rc-3 commit-fail → 5C skips. push-fail → merge already local, report + manual push (no retry/reset). - Why: memory's value = cross-session persistence; a ritual commit stranded on an unmerged chore branch is INVISIBLE to the next session on develop → the ritual defeats itself (user-identified gap). Memory = append-only/low-risk; the human-gated MERGE (aiguillage) is a CODE safeguard, and LRN-069's push-gate guards surprise CODE/release pushes — neither applies to an end-of-session memory persist.
- Scope: /capitalize + /close ONLY. /prune-memory + /reconcile stay fully human-gated (curation/report may want review before landing). NEVER auto-finish a branch the run did not create.
- Amends: LRN-069 (push needs explicit go) — scoped exception for memory-only ritual persist;
gitflow-aiguillage.md"never gitflow finish" — carved for capitalize/close. - Files: skills/capitalize/SKILL.md (STEP 5C + aiguillage branch-capture + STEP 6 outcomes + Rules + arg-hint
--no-push), lib/gitflow-aiguillage.md (exception note). Tests unaffected (run-deterministic covers memory-commit.sh surgical scope, not the persist step). - Status: implemented on feature/close-auto-persist, UNMERGED (human gate).
- Status (2026-11-16): implemented, merged 1b13bac; amended by BDR-136: 5C auto-finish now prompts once (native ask merge gate), declined -> nothing merged, branch kept
BDR-069 — permissions deny: keep broad .env.* glob, keep .env.example name (option A) — 2026-07-16
- Decision:
Write(path)deny rules inert (Claude Code matchesEdit(path)only) → 5 secret-write bans converted toEdit(). Mirrored 9 secret patterns Read denied but Edit did not → Read/Edit parity 14/14. New read-allowed/write-denied class: lockfiles (*.lock,package-lock.json,pnpm-lock.yaml,go.sum) +node_modules/**. KeptEdit(**/.env.*)BROAD despite matching.env.example(mandated by CLAUDE.global.md:206). No rename. - Why: deny glob = absolute, no exemption mechanism (LRN-130). Only lever = glob shape. Narrowing to
.env*.localfails open on.env.production/.staging— real secrets outside Next.js convention. - Cost accepted: scaffolder/doc-syncer degraded on
.env.example— Edit/Write/Read/Grep/Glob blocked; Bash heredoc still works (Bash(cat *)allowed). Ergonomic tax on /init-project, not a hard block. - Alternatives rejected: (B) narrow glob → weakens
.env.production; blocked by auto-mode classifier as unauthorized self-modification (EVAL-024). (C) rename →env.examplesidesteps glob at zero security cost, but ~30 refs (scaffolder, doc-syncer, init-project, deploy, 3 archetypes, link.sh, install-plugins.sh, toggle-external.sh) + repo's own root.env.example+ seo-data.test.sh + gitignore!.env.example(BDR-030) → refactor, user declined. - Files: settings.json, templates/settings/SETTINGS.md (taught the broken
Write()pattern → fixed at source so /onboard stops propagating it). - Status: implemented on chore/fix-inert-write-deny-rules (
07ca738), UNMERGED (human gate).
BDR-070 — claude-seo (github.com/AgriciDaniel): cherry-pick, never install — 2026-07-17
- Decision: adapt useful scripts into our tree, /seo stays sole entry. Do NOT run install.sh / plugin install.
- Why: their CODE is real (326 tests, render_page.py 428l Playwright, url_safety.py 622l SSRF) — their INSTALLERS destroy our work. install.sh:49
cp -r skills/seo/*overwrites our SKILL.md. uninstall.sh:45 globs~/.claude/agents/seo-*.md→ deletes our seo-analyzer.md (42K) it never installed (verified dry-run). extensions/*/install.sh:42 replaces settings.json with{"env":{...}}on parse error. skills/seo/SKILL.md:119 injects Skool upsell footer into deliverables (leaks to /client-handover client PDFs). hooks.json registers global PostToolUse exit-2 → blocks our dispatcher mid-bundle. - Alternatives rejected: (plugin install) → both
/seocoexist namespaced → non-deterministic dispatch, silently loses our FR-legal axis on an unpredictable fraction of runs. (install nothing) → forgoes render_page/url_safety/unlighthouse we lack. - Verdict on parity: their README lies (dual JSON-LD validator = 2 hyperlinks, zero
.pycalls; "zero-network"/"fully offline" false). Our system is more honest; we keep FR-legal (their whole repo: 2 hits), fix-bundle+ownership, trajectory-17/20, NAP anti-seed. - Files: none installed. Findings drove the whole seo-geo-integrity branch (21 commits).
- Status (2026-10-28, upgrade): accepted
BDR-071 — no viable free backlink source: Off-page axis stays brand-mentions-only — 2026-07-17
- Decision: I1's narrowed Off-page axis (brand mentions from STEP 6 only, backlinks+authority declared §14-unauditable) is the FINAL state, not a placeholder awaiting data.
- Why: measured, not assumed. GSC has no links endpoint (API = Search Analytics/Sitemaps/Sites/URL-Inspection only; links report UI-only). Common Crawl hyperlinkgraph domain-edges = 17.3 GB gzipped (+879MB vertices, +2.3GB ranks), HEAD-measured live. Scanning it per-audit is non-viable + abusive to a nonprofit. The reference impl (claude-seo commoncrawl_graph.py:169) caps download at 500 MiB = 2.9% of edges, sorted by source ID → arbitrary slice reported as a backlink profile, "70/100 health". A random sample dressed as a measurement — the exact failure class the branch removes.
- Consequence: B1/B2/B3 all killed. Weight (10-15%) unchanged — re-deriving for an axis that won't widen churns historical scores for nothing.
- Only free viable source: Bing GetUrlLinks — first-party only (never a competitor), blocked on client's Bing account → raises W2's value (BLK-017), does not unblock it.
- Status (2026-10-28, upgrade): accepted
BDR-072 — SPA: honest refuse, no headless browser (R2 chosen over R1) — 2026-07-17
- Decision: rendercheck verdict
client-rendered→ On-page axis N/A, excluded from weighted global, NEVER scored zero. No Playwright, no Chromium. User-arbitrated. - Why: a zero says "your on-page is bad"; N/A says "we couldn't see it" — only one is true, and /client-handover gates on 17/20. curl on a shell returns "missing" for every meta/H1/JSON-LD → a page of FALSE findings + a bundle that "fixes" tags that already exist. STEP 2 recorded
RENDERING: SPAsince forever and NOTHING acted on it. Verdict from what the server SENT (package.json can't tell React-SPA from Next-SSR). - GEO angle (sharper): AI crawlers (GPTBot/PerplexityBot/ClaudeBot) are WORSE at JS than Googlebot — fetch HTML, largely don't execute. A client-rendered site is near-invisible to the engines the audit serves → §0 alert + SSR/SSG top user action, aligns CLAUDE.global "public sites never SPA".
- Alternatives rejected: R1 Playwright (~300MB Chromium, breaks bash+curl purity) — user chose refusal. Refusing IS the finding.
- Files: lib/seo-data/render_check.py, seo/geo STEP-5 gates (
20d3082). - Status (2026-10-28, upgrade): accepted
BDR-073 — deterministic scoring: split LLM judgement from arithmetic — 2026-07-17
- Decision: LLM emits WHICH findings + severity (irreducible judgement); engine computes the /20. Reuses /harden's scale (-15/-8/-3/-1, clamp, /5 into /20) → one vocabulary across the family.
- Why: /harden had a real scale (SKILL.md:435), /seo had NONE → every axis felt → two runs over identical code diverged, while /client-handover gates on 17/20. H2 sharpened it: once drift reports real change, a self-moving score is visibly noise. Same principle as engine-side cannibalisation grouping — never hand a model 1000 rows to add.
- Makes computable (was prose): "N/A is not a zero" (R2 on-page, I1 off-page) → axis excluded + weights renormalised, verified all-20 with 2 N/A → global 20.0. Prevalence: affected/sampled shift severity ONE step (≥50% escalate, single de-escalate).
- Files: lib/seo-data/score.py (
4818c61). - Status (2026-10-28, upgrade): accepted
BDR-074 — Remove config-protection edit-block guardrail [accepted] (2026-07-17)
Deleted hooks/config-protection.sh + its settings.json PreToolUse registration + lib/tests/config-protection.test.sh. Hook blocked model Edit/Write on quality-gate files (settings.json, gitflow.sh, .githooks, doctor.sh, hooks, lib/tests, lint) via one-shot .claude/.config-edit-ok sentinel. Removed per user req — friction editing own config > guardrail value; user = human operator. Residual: gitflow pre-commit guard + Gitea branch protection still block direct code commits main/develop; only edit-time block gone. Alts rejected: warn-only (exit0+log), targeted relaxation. Supersedes any prior config-protection decision.
BDR-075 — Framework-wide 3-way adversarial plan-challenge phase [accepted] (2026-07-17)
After a plan/reflection elaborated + before execution, 3 fresh blind sub-agents (correctness/robustness/simplicity) attack it; main loop RE-THINKS every aspect a BLOCKER lands (named change or [deferred]) + re-challenges once if plan materially changed. Reusable lib/challenge-plan.md + new agents/plan-challenger.md (read-only, big-model per BDR-066 — audit judgment, NOT sonnet). Fail-safe (never fail open: mute→retry→escalate), severity-driven (any single-lens BLOCKER=must-address, NOT consensus — lenses orthogonal), advisory into existing human gate. KIND tunes lenses: build-plan/proposals/fix-bundle. Wired 11 orchestrators: ship-feature/init-project/feat/bugfix + onboard/audit-delta/code-clean + seo/geo/harden/web-validate. Excluded (no real plan): hotfix/tour/analyze/client-handover/release-candidate/spec. Audit found 0 repo-owned plan-challengers pre-existing (only vendored gstack autoplan, sequential+unwired). See EVAL-026.
BDR-075 amendment (2026-07-18) — hotfix INCLUDED via logic-only guard
Supersedes the "Excluded: hotfix" clause of BDR-075. hotfix now wired (STEP 1.8, Option B): GUARD skips purely cosmetic fixes (CSS/copy/typo), fires the 3-lens challenge ONLY when the fix touches control flow/behaviour (off-by-one, wrong operator, behaviour-changing config, execution-altering import); a BLOCKER → escalate to /bugfix (its STEP 3b runs the full phase). 12 orchestrators wired. Still excluded (no forward plan): tour/analyze/client-handover/release-candidate/spec. Per user (Option B). Branch feature/hotfix-challenge-guard, unmerged.
BDR-076 — Dispatched judgment agents pinned OPUS; session model = orchestration + inline reflection ONLY [accepted] (2026-07-19)
Reverses the BDR-066 rejected alternative "opus pins on audit agents (session-independent)". Context changed: session default now Fable (Mythos tier, /model 2026-07-19) — inherit meant every dispatched audit/challenge burned Fable quota, exactly the waste BDR-066 killed for executors. New rule: Fable does ONLY main-loop orchestration + reflection (brainstorm, plan, contract, synthesis, gates); EVERY dispatched subagent pinned. Pinned model: opus (big tier, session-independent; NEVER sonnet — silent audit downgrade, the thing old §F5 guarded): analyzer, plan-challenger, seo-analyzer, geo-analyzer, validator-analyzer + onboard's 6 general-purpose audit dispatches (model="opus") + tour Phase B. NOT pinned (justified deviation from approved "7 agents"): interviewer + client-handover-writer — inline-load only, never dispatched → frontmatter pin inert + misleading (BDR-066 wave-4 precedent: its inert opus pin was dropped); they ARE the main loop = Fable per the rule. Explore built-in stays inherit (wave-3 decision conserved: no owned prompt, search feeds inline reflection). Local session pin opus-4-8[1m] dropped from .claude/settings.local.json (gitignored) — Fable default from settings.json now applies in this repo too. model-gate.md unchanged (still guards inline reflection, Fable-or-Opus = big). Census: model-routing.test.sh §3 flip + §11 (61 pass), loops-light 35 pass, full make test green. User directives via gate: "Opus partout" + "Supprimer le pin". Branch feature/opus-pin-audit-agents, unmerged.
BDR-077 — Model-tiering v2: 4-tier explicit routing, mode-based splits, no-inherit dispatches [accepted] (2026-07-19)
Supersedes BDR-076 scope + amends BDR-066. Doctrine: session model (Fable) = main-loop reflection/orchestration/planning/logic ONLY; main-loop retention criteria = interactive | conversation-context access | orchestration decision | dispatch overhead > step cost. NOTHING dispatched inherits: typed agents = frontmatter pin, built-ins = model= at every call site (fable for skill-runner reflection children, else complexity tier). Spike+smoke proven: model:"fable" resolves claude-fable-5 (enum-validated, loud fail, no silent fallback); call-site override BEATS a typed pin (sonnet-pinned verifier ran haiku). Fail-safe pin rule: mixed-mode agents keep the HIGH tier as pin, overrides go DOWN — forgotten override over-tiers (cost), never downgrades judgment. Mode-based splits (commit-changer precedent generalized; file splits rejected): doc-syncer audit(opus)/patch(sonnet) — ALSO fixed a latent defect: /doc dispatched an agent whose STEP 8 interactive gate could never fire; gates hoisted to a DISPATCHER PROTOCOL section; handover-doc-writer synthesize(opus)/render(sonnet) via run-scoped .audit/handover-draft-<RUNID>.md + DRAFT COMPLETE sentinel; seo/geo collect(sonnet)/judge(OPUS PIN)/template(sonnet) via .audit/*-signals-<RUNID>.md + COLLECTION COMPLETE + fail-closed judge + dispatcher ERROR contract (mute/ERROR judge NEVER carried into templating; retry once, escalate). File split only for a genuinely new role: plugin-probe (sonnet, facts-only) + plugin-advisor repinned opus reasoner (fail-closed on missing PROBE REPORT) + lib/plugin-gate.md (checkpoint + apply gate, doc-commit ×N include pattern). Inline→dispatch conversions: scaffolder, onboarder, doc-commit steps ×5 flows — their sonnet pins were INERT since creation, now live; CHANGE SUMMARY crosses the doc dispatch into doc-commit (LRN-126 wire). Tier moves: validator-analyzer opus→sonnet (deterministic runner); commit-changer propose=opus/apply=pin; ship-feature/init-project code-review dispatches = opus explicit (WAS an inherit leak); client-handover-writer's 7 skill-runners = model:"fable". Every wave shipped an IN-WAVE planted-input smoke as its merge gate — all PASSED disk-verified. Census §12-18 (125 pass; one vacuous line-wrapped lock self-caught = LRN-093 live). 6 waves, branches feature/model-tiering-w1..w6, merged on user standing signal. Plan: challenged 3 blind lenses + 1 confirmation (1 BLOCKER closed by spike, 8 MAJORs + 8 MINORs closed by named changes, 0 deferred). Refs: .claude/tasks/plans/2026-07-19-model-tiering-v2-{analysis,plan}.md.
- Status (2026-11-17): accepted, amended by BDR-150: skill-runner pins opus (
beebfe2); session opus, Fable is the advisor
BDR-078 — ctx7 coverage: central fast-libs list + once-per-session reminder hook; every code path covered [accepted] (2026-07-20)
Refines BDR-053 (single surface). Audit 2026-07-20: coverage PARTIAL — find-docs fired on user doc-questions only; ship-feature 0c / init-project 5c pre-fetched; /feat //bugfix executors + ad-hoc coding NEVER consulted ctx7; fast-libs list hardcoded 3× (drift risk). 4 closures shipped: (a) find-docs description += BEFORE-writing-code trigger (fast-moving lib, even without doc question, unless fresh cache) + cache-first rule in body (tee fetched docs to .ctx7-cache/); (b) feater+bugfixer briefs += fast-lib docs rule — read fresh .ctx7-cache/<lib>*.md, else npx ctx7@latest fetch max 2 topics, else ctx7 cache miss: <lib> in NOTES + proceed (executors lack Skill tool → Bash path); (c) hooks/ctx7-reminder.sh UserPromptSubmit — ONE fire/session (sentinel on session_id), only when project manifest carries fast-libs; reports cache state; skips turns; always exit 0; (d) lib/fast-libs.sh = SINGLE SOURCE (detect / cache-status verbs, JS package.json anchored full-key match + Python requirements/pyproject, 7-day freshness, LC_ALL=C sort locale-independent) consumed by hook + 3 pipeline skills + 2 briefs. 2nd session surface DELIBERATE, not a BDR-053 reversal: 053 killed a 490-tok ALWAYS-ON rule duplicate; hook costs ~0 quiet, 1 line once when fast-libs present. Alternatives rejected: PreToolUse Edit/Write gate (fires per-edit = noise); description-only fix (probabilistic, executors unreachable). Tests: lib/tests/fast-libs.test.sh 11 checks (anchored/near-miss/py/none, cache fresh/stale/missing, hook fire/sentinel/quiet×2); shellcheck + full make test green. Branch feature/ctx7-coverage, unmerged (human gate).
Amendment (same session): skills/find-docs = machine-owned dist (gitignored, ctx7 regenerates on fresh clone) → durable copy of closure (a) lives in install-plugins.sh STEP ctx7 (idempotent grep-guarded python patch, fixture-verified); live SKILL.md carries the same edit uncommitted by design.
BDR-079 — profile set symmetric on managed externals + MCPs [accepted] (2026-07-20)
Audit (user ask "profile toggles externals both ways?"): ASYMMETRIC. Enable side OK — gstack on-demand from submodule when pack off (shared skills-disabled/gstack__* convention with toggle-external.sh, interoperable), externals restored from parked, magic delegated to toggle-external. Disable side MISSING: cmd_set trimmed only gstack + MANAGED_PLUGINS → set backend left emil/frontend-design/design-motion/impeccable active + magic registered; SKILL.md claimed both-ways toggle (true only at enable). Shipped: (1) MANAGED_EXTERNALS (emil-design-eng, frontend-design, design-motion-principles, impeccable = exact union of profile external usage; darwin-skill excluded — not task-type-driven) + MANAGED_MCPS (magic) allowlists, same doctrine as MANAGED_PLUGINS; (2) cmd_set refactored to 4 trim helpers (disable_{gstack,plugins,externals,mcps}_not_in) — symmetric, nothing outside allowlists ever auto-touched; (3) enable_skill external += from-source fallback (ln -sf skills-external/<name>, mirrors toggle-external) — closes the "missing symlink" warn; (4) stale usage() NOTE ("NOT toggled automatically") + SKILL.md fixed. Hermetic test profile-set-managed.test.sh 16 checks: fixture repo (both *_REPO_OVERRIDE), fake claude shim on PATH logging calls + flat-file MCP registry — gstack on-demand, external from-source, park/restore round-trip, magic add/remove calls, non-managed untouched. shellcheck + make test green. Branch feature/profile-managed-externals, unmerged (human gate).
- Status (2026-11-16): superseded by BDR-134: symlink toggling and MANAGED_EXTERNALS/MANAGED_MCPS trims gone; profile = settings fragment, profile.sh set merges enabledPlugins per project
BDR-080 — bug routing inverted: /bugfix primary, /investigate explicit-only [accepted] (2026-07-21)
Old routing "Bug → investigate (bugfix if gstack off)" + gstack ON by default → every bug took path bypassing own quality pipeline (gitflow aiguillage, contract, fresh verifier + security gates, doc-sync, .claude/memory registries) — /bugfix relegated to near-never fallback. Skill comparison: same core doctrine (root-cause iron law, hypothesis loop, regression test, 3-strike stop, >5-files alert) but incompatible wrappers — investigate monolithic (same context investigates+fixes+verifies, ~1075-line SKILL.md w/ gstack preamble/telemetry/onboarding, capitalizes to ~/.gstack learnings.jsonl framework never reads at session start); bugfix orchestrator (reflection inline, sonnet bugfixer executor, fresh gates — BDR-066, LRN-083). Composition rejected: skills superpose in context, don't compose — invoking investigate inside bugfix = two full workflows, two completion protocols, two memory systems loaded at once. Decision: CLAUDE.global.md routing line inverted — bugfix primary; investigate ONLY on explicit ask for gstack ecosystem (cross-project learnings, /freeze scope lock, long no-commit investigation). Alternatives rejected: keep investigate primary (bypasses framework), embed investigate inside bugfix (context conflict, dual memory). Known drift noted at write time: Index table rows BDR-074..079 missing (pre-existing, /prune-memory scope).
BDR-081 — Config recalibrated for Claude 5 family (Opus 5 dispatch tier) [accepted] (2026-07-30)
Opus 5 (released 2026-07-24) now backs every model: opus pin (BDR-076/077) + any /model opus session. Research (official migration guide + web + registries): Opus 5 OVER-delegates (inverts LRN-030 Opus 4.8 trait that CLAUDE.global.md:43-47 compensated), self-verifies (explicit verify instructions → over-verification, "removing them reduces wasted tokens with no loss in quality"), literal following (conservative-reporting clauses depress recall; MUST/CRITICAL over-triggers), scope expansion = named regression, written deliverables +30-40%. Claude Code injects Opus-5-only anti-delegation prompt sections (heron_brook + subagent_steer_delegation, issue #80988, server-gated, no opt-out) — prose caps would triple-stack. Shipped: delegation block → model-neutral WHEN-guidance + explicit gates carve-out (verifier/security/challenge still dispatch as written); "staff engineer" self-check bar dropped; finish-whole-task clause folded into Deviations (gone-WRONG→STOP still wins); deliverable-length rule; design hook \bux\b dropped (\bui\b KEPT — 0 FP, 1 logged TP, lock-tested); plan-challenger grounded-doubt→[MINOR] in-place reword (grammar byte-identical). Plan challenged by 3 blind Opus 5 plan-challengers: correctness CONCERNS(4) / robustness FATAL(5, BLOCKER: all surfaces symlink-deployed LIVE — gates fire post-deployment) / simplicity CONCERNS(4); every fix adopted as prescribed (scratch-validation before live hook write, minimal diffs, ux-only, MINOR-routing). Alternatives rejected: leave as-is (nudge actively counter-productive); hard spawn caps in prose (harness injects one); confidence axis on challenger grammar (consumer unwired); dropping \bui\b (no evidence). NOT touched: verify-secure-loop + fresh gates (harness architecture BDR-049/050, ≠ model self-check prose); Security/Architecture sections (BDR-021); settings effortLevel xhigh (user pref — Opus 5 carry-over trap → LRN-139); superpowers plugin wording (external upstream). Plan+synthesis: .claude/tasks/plans/2026-07-30-opus5-config-tuning-1238.md. Branch feature/opus5-config-tuning, unmerged (human gate).
BDR-082 — seo/geo analyzers de-prescribed for Opus 5 (C1) [accepted] (2026-08-02)
BDR-081 N5 follow-on, user-directed apparatus (plan+3-lens challenge+census+dogfood). Method: audience×mode-range invariant — dedup ONLY verbatim same-audience (spec rule / bundle-item payload / phase-local caveat) same-mode-range repeats; cross-mode + agent↔dispatcher twins stay (standalone paths need them). Census-FIRST: lib/tests/seo-geo-contract.test.sh 71 locks (verdict grammar, sentinels, ALL STEP headers incl. interiors, item fields, score labels, envelope keys), flip-proven 7 mutations→7 FAILs, committed BEFORE reword. Shipped: self-output verification removed (":970 run twice"→conditional integrity guard; ":1217"→single-shot-scoped), 2 pre-BDR-061 vestigials fixed, caps softened (P0-rule/MANDATORY/ALWAYS→plain content rules), 2 essays compressed, checklist :1309→routing map rows verbatim (challenger caught it = routing table, NOT self-check), true same-range dups only (seo Handoff+landing-page blocks; geo ZERO — all claimed pairs distinct on inspection). FROZEN: guard-first url-guard orderings, :550 denominator-before-sampling (ordering IS the honesty mechanism), R2/NAP/COVERAGE/citation invariants, external-freshness checks (world drift ≠ self-verification). Deltas: seo 1528→1503 l ("P0 rule" 2→0, ALWAYS 1→0, MUST 5→4, NEVER 9→9 = class-B bans kept); geo 1106→1107 (MANDATORY 1→0, MUST 4→3). Plan challenged correctness FATAL / robustness FATAL(3 BLOCKER) / simplicity CONCERNS + confirmation FATAL(9) — every BLOCKER closed by named change (§5bis record). Dogfood before/after on frozen zenquality copy: judge-replay on frozen signals (zero collect variance) + templates + fresh collects + e2e judge + 42/42 assert battery BOTH sets + blind reader "interchangeable; all deltas = presentation variance both directions OR after MORE spec-conformant". Alternatives rejected: keyword dedup (challengers proved audience/range-blind — most annex "twins" were distinct obligations), FULL/aggressive dogfood (billing gate killed nested CLI; left as user option), banner/shape locks (LLM-convention layers wobble — lock strings only). Evidence: .audit/dogfood-baseline/ (18 artifacts + DOGFOOD-VERDICT.md), plan .claude/tasks/plans/2026-07-30-seo-geo-deprescription-1402.md. Branch feature/seo-geo-deprescription, UNMERGED (human gate).
BDR-083 — contract gates: deterministic floor (GATE 0) under the verifier [accepted] (2026-08-24)
User asked what to take from unlazy skill (Leonxlnx/unlazy 2.1.0, MIT). Verdict on its verification ARCHITECTURE: teaches nothing we lack — contract + fresh blind verifier + bounded loops + order invariant already shipped (BDR-049/050/066, LRN-083). Real gap found elsewhere: between executor and GATE 1, NO deterministic floor. GATE 1 = LLM dispatch; verifier's mandatory PROOF: line = a line the verifier WRITES — nothing structurally stops it being produced without executing anything (LRN-048 demands a pass prove it looked; the proof is self-reported prose). Decision: import unlazy's gate ledger INTO the existing contract, never alongside it. Palier 2, user-chosen over doctrine-only / defer.
TAKEN: criterion carries an oracle (indented CHECK: cmd + EXPECT: success-only marker + EVIDENCE: slot); fail-closed = exit 0 AND marker (a nonzero process never passes because its error text carries the token); evidence persisted INTO the contract → the fresh verifier reads fact, not the executor's report; ABANDON: <id> <non-blank reason> = impossible criterion never deleted, blocks CONFORME, routes to human gate (new verdict token ABANDONED(n) — distinct routing from ECARTS ⇒ distinct token, not a sub-line to re-derive); 4 gate-authoring rules (observe the named artifact / success-only marker / positive control before any absence check / recompute supplied numbers, never copy one into EXPECT); 4-pass executor discipline (feater full; bugfixer narrowed to fix+test under "keep the fix minimal", pass 3 = negative control proving the regression test fails without the fix).
REFUSED + why: Stop hook decision:"block" — contradicts "STOP + human escalation", "gone WRONG → STOP re-plan", "merge only on explicit human signal"; a hook FORCING continuation is the inverse of our gates; its 6-block release either traps the session or gives up; each block = an agent continuation = real tokens. Approval store ~/.unlazy/approved (binds ledger+cmd+CWD+shell+timeout+platform+full PATH) — exists to execute ledgers INHERITED from untrusted repos; our contracts are authored by our own orchestrator in our own repo ⇒ biggest chunk of their 28k checker closes zero threat here. .unlazy/<scope>/ tree (PLAN+GATES+gates/+status.log+session+hook-state+locks/) — a 4th bookkeeping tree beside .claude/tasks/{contracts,plans} + memory/ + audits/. tree N Depth-Tree effort arithmetic — disowned by unlazy's OWN research/validation-protocol.md (v1 six-run figures unreproducible), while the repo DESCRIPTION still advertises the retracted claim. Node checker (28k .mjs + 54k .mjs tests) — lib stack is 100% bash, Health Stack = shellcheck *.sh hooks/*.sh lib/*.sh would cover none of it. OWNS: ownership leases — deferred (Palier 3): our parallel dispatches (seo/geo, 3 plan-challengers) are read-only, the write-collision problem does not exist yet.
Shipped: lib/gates.sh (~250 l bash; status never executes and never writes · run ALWAYS re-executes every runnable criterion — trusting written evidence is the failure being closed, so there is no incremental mode to get wrong; rc 0 MET / 2 UNMET|malformed / 3 ABANDONED; parse fails closed on partial oracle, duplicate id, unindented attribute, runnable-without-EVIDENCE, and executes nothing when the ledger is malformed). GATE 0 in lib/verify-secure-loop.md (red floor → executor re-dispatch with the NOT-MET rows, NO verifier spawned; own 3-iteration budget, separate from conformity; malformed ledger fixed in the main loop, never dispatched to a dev). Order invariant now GATE 0→1→2 on every re-loop. lib/contract-interview.md: ORACLES section + template + ABANDONMENT lifecycle + per-flow oracle weight. agents/verifier.md: oracle-consumption rules — a red or unrun oracle is NEVER overridden by reading code; a MET oracle proves the ORACLE, not the English sentence ⇒ vacuous oracle = NOT-MET, the one judgement no command can make; verifier may re-run a CHECK but never edits the contract. lib/tests/gates.test.sh 64 assertions (sentinel-proved non-execution, with its own positive control asserted first).
Alternatives rejected: Palier 1 doctrine-only (CHECK:/EXPECT: become decorative without an executant); port the Node checker (stack break, shellcheck-blind); fold ABANDONED into ECARTS (would send a dev to fix the impossible and eat the 3-iteration budget); status revalidating old evidence (that trust is the failure being closed).
Branch feature/contract-gates, UNMERGED (human gate). make test rc 0, shellcheck clean, e2e verified on a real contract in the documented template.
BDR-084 — /tour multi-project: parallel runners, bounded LRN-083 derogation [accepted] (2026-08-24)
User asked whether agent parallelism on independent tasks is ACTIVE. Measured first (LRN-080): (a) mechanics — nested probe, 1 dispatched orchestrator fanned 3 sub-agents, execution windows all overlap, 9.1s vs ~18s sequential ⇒ nested parallel dispatch WORKS; (b) doctrine — already prescribed at 3 layers (harness "single message" injection; /seo, challenge-plan, /cso, graphify explicit same-message mandates; graphify even anti-sequential wording); remaining serializations all MOTIVATED (audit-delta crash-resilience documented, verify-secure-loop order invariant); (c) behavior — probe orchestrator batched spontaneously without being told "parallel" (N=1), this session fanned 8+7 agents/message during the RED. Conclusion: nothing to add globally — a CLAUDE.md "parallelize" line would duplicate-stack the harness injection (BDR-081 anti-pattern).
ONE real sequential-but-independent candidate: /tour multi-project (independent repos, one by one, no documented reason). User gate: option "tout paralléliser" chosen over report-only-only and no-change, WITH the model invariant "orchestrateur garde le modèle orchestrateur; skills/agents suivent leurs orchestrateurs définis".
Decision: STEP 0 routes (1 project = inline unchanged; ≥2 = STEP 0b fan-out). One general-purpose runner per project, ALL in ONE message, dispatched with NO model override — inherits the session model (model-gate already validated big; a runner carries tour's reflection: fix decisions, convergence). Inside a runner every agent keeps its defined tier (security-auditor sonnet, Phase B opus, doc-syncer sonnet two-mode). Dead/mute runner ⇒ explicit RUNNER FAILED summary row (mute is never a pass). Capitalize offer stays MAIN LOOP ONLY (registries = shared state).
LRN-083 derogation, bounded: per-project fix loop + convergence now run INSIDE the dispatched runner. Bounded because nothing a runner decides touches shared state — independent repos, per-repo chore branches, branches stay UNMERGED for human review exactly as inline (report-as-approval-gate design unchanged). Precedent: client-handover-writer already a dispatched orchestrator running parallel audit loops (BDR-077).
Alternatives rejected: report-only-only parallel (my recommendation — user overrode: full parallel wanted); one sub-orchestrator agent .md file (drift risk vs SKILL.md, the runner reads the skill from disk instead — client-handover→/seo precedent); pinning the runner (would put tour reflection on an executor tier — inverts BDR-076); global CLAUDE.md parallelism line (duplicate of harness injection). Census §12: 6 locks (fan-out present, no-pin, single-message, capitalize main-loop, RUNNER FAILED, no pinned runner), flip-tested. Branch feature/tour-parallel, UNMERGED (human gate).
BDR-085 — user permanent rules: writing-style always-on in rules/, web rules path-scoped [accepted] (2026-08-25)
User supplied 4-block permanent rule text (writing / website / code security / self-check), asked: coverage check, conflict check, integrate. Coverage verdict: security CORE (parameterized queries, input validation, env-var secrets, AuthN/AuthZ split + default deny, no stack traces, fail closed, least privilege) ALREADY in CLAUDE.global.md §Security — NOT duplicated. NEW: entire writing-style block, design anti-default list, public-site done-checklist, web-app specifics (browser-exposed keys, service-key/client split, RLS, server-side auth, IDOR, hashed passwords + cookie flags, field minimization, rate limiting, upload restrictions). Placement: CLAUDE.global.md at 308/320 (session-start density guard) → no room for ~30 always-on lines. Decision: rules/writing-style.md WITHOUT paths: (always-on load, same session cost, outside the 320 budget) + rules/web-building.md + rules/web-security.md WITH paths: (lazy-load = token win, fire only on web/code files). Project CLAUDE.md doctrine line amended with the budget exception. Feeds C2 self-contradiction audit. Conflict carve-outs, stated INSIDE the rules: registries keep caveman format (fragments, em-dashes, bullets); code comments keep code style; structured skill/report templates keep their formats; robuste/transformer banned in buzzword sense only (robustness lens, math transform allowed); no-Inter default rule carries "existing brand identities keep their fonts" (ZenQuality deliverables use Inter+Playfair by brand decision — client-handover BDR). Self-check rule scoped to DELIVERABLES (text, site, feature), not every conversational reply — literal "avant de me rendre quoi que ce soit" would append a compliance note to every chat answer, pure noise. User can re-widen. Alternatives rejected: compress into CLAUDE.global.md (~11 lines to fit → loses the carve-outs, zero headroom left); path-scope writing-style (applies to conversation, not file reads → would never fire in chat-only sessions); one merged web file (two concerns, one-rule-one-file). Branch feature/user-writing-web-rules, UNMERGED (human gate).
BDR-086 — darwin bug-pass scope: verified defects fixed above threshold
- Date: 2026-08-26
- Decision: units < threshold get full weighted-gap optimization loops (per-unit checkpoint). Judge-VERIFIED defects (file:line, confirmed) in above-threshold units get targeted fixes in a grouped pass — same paired 3-judge validation, one batched checkpoint. User-gated at the scorecard.
- Why: leaving a verified destructive path (hotfix
git restore .wiping tolerated user edits, file scored 85) unfixed = score-worship; rubric serves quality, not the inverse. - Alternatives rejected: strict threshold (ships known bugs); optimize-everything (cost, HL-4 diminishing returns).
- Reference: run 2026-08-26, commits 6eceedb..6eac7fb,
.claude/audits/DARWIN-2026-08-26.md. - Status (2026-10-28, upgrade): accepted
BDR-087 — Stop hook = attention signal only, never control flow
- Date: 2026-09-03
- Decision:
hooks/notify-attention.shwired on BOTHNotification(matcher = input-needed set) ANDStop(no matcher). One script, branches on.hook_event_namewhen.message/.notification_typeabsent → Stop yields "Claude has finished responding". Bell + toast now fire every turn end. - Why: Notification types cover input-needed ONLY. Turn-end had no event; nearest was
idle_prompt, ~60s late — useless for Remote-SSH user away from screen. User enumerated turn-end as required case. - Alternatives rejected: second dedicated script (duplicates terminalSequence + jq logic, two files to keep in sync);
idle_promptalone (60s lag); SubagentStop too (noise, subagent completion not user-visible moment). - Guard vs prior refusal: BDR-083 (unlazy review, GATE 0) REFUSED a Stop hook using
decision:"block"(forces continuation, inverts human gates). THIS Stop hook returnsterminalSequence+suppressOutputonly, exit 0, zero control-flow effect. Signal ≠ control. Do not read the refusal as banning Stop outright. - Status: accepted.
- Reference: LRN-146 event-coverage gap, BLK-020 client-side faults, LRN-145 terminalSequence pattern. Verified live: turn-end + AskUserQuestion both ring;
permission_promptunexercisable underdefaultMode: auto.
BDR-088 — gstack Playwright bump shared via lib; update helper never touches submodule tree
- Date: 2026-09-15
- Decision:
gstack_bump_playwright_if_unsupportedmoved out ofinstall-plugins.shintolib/gstack-playwright.sh, sourced by install-plugins + update-all + doctor. update-all's submodule block now callsgstack_submodule_update_with_bump: re-applies bump after successfulsubmodule update --remote; on failure prints git's own message, hintsmake plugin, returns 1. Never touches submodule worktree. - Why: BDR-029 caveat open — bump survived only till next
make plugin, update path never re-checked OS support. Real gap, user-reported. - Alternatives rejected: conflict-RECOVERY branch (discard package.json+bun.lock → retry → backup/restore). Withdrawn at human gate after 4-agent challenge: concentrated 3 BLOCKER + 4 MAJOR. Worst case = bump discarded, re-apply silently no-ops (bun absent / registry down — bump returns 0 on every path),
./setuprebuilds browse against unsupported Playwright → BLK-008 returns. Pre-existing behavior just failed the update and kept bump intact, so the "improvement" could regress a working install. - Deviations carried from "code MOVED not changed":
|| trueon ostag capture (line exited 1 on every non-Ubuntu host → aborted caller under inherited errexit, reproduced);timeouton all 3 bun calls, exit 124 → warn + no bump (TERM'd install leaves node_modules half-written, poisons the support grep). - Status: accepted.
- Reference: commit
2cebecb,lib/gstack-playwright.sh. Links BDR-029, LRN-070, LRN-071, LRN-150, BLK-008.
BDR-089 — No Playwright browser-cache pruner; read-only doctor report instead
- Date: 2026-09-15
- Decision:
doctor.shgains own── Playwright browsers ──section — cache size, per-revision the installs requiring it, counts of unreferenced dirs + broken links. Zero deletion anywhere in the lib. - Why: measured, not assumed.
~/.cache/ms-playwright/.links/registers 3 installs — gstack 1.61.1 → rev 1228, gsd-pi nvm 1.61.0 → 1228, gsd-pi ~/.local 1.63.0 → 1243. Every dir on disk referenced → 0 bytes reclaimable. Playwright's own_deleteStaleBrowsersalready unions across all registered installs on everyinstall. - Alternatives rejected: hand-rolled pruner guarded on "revision resolved by gstack's local playwright" (the originally requested shape) — that guard keeps 1228 and DELETES 1243, breaking gsd-pi. The guard was wrong, not just its implementation.
- Status: accepted.
- Reference: commit
2cebecb. Links LRN-151, BDR-088.
BDR-090 — Destructive shell work → autoMode soft_deny/hard_deny; ask tier abandoned
- Date: 2026-09-15
- Decision: 10 rules leave the static tiers (user's own edit):
rsynckill -9killallpkillout ofdeny;python3 -cpython -cxargssedcpmvout ofask. Cover rebuilt inautoMode— 7soft_deny(write outside cwd,rsync --delete, SIGKILL/kill-by-name, in-place edit spanning >1 file, directory move, inline interpreter orxargsthat deletes or writes outside cwd) + 3hard_deny(secret exfiltration, prod deploy, disarming guardrails). Intent clears a soft block for the CURRENT TURN only — encoded as a rule line, no setting exists for it.classifyAllShellstays false.permissions.deny+10.envreader rules (sed awk cut tr sort uniq diff od xxd strings), 6 of which sat inallow. - Why:
askraises no prompt underdefaultMode: auto(LRN-146, verified live). It gated nothing, so a destructive rule moved deny→ask was a silent loosening dressed as a confirmation.soft_deny= the tier the classifier enforces and user intent clears.hard_deny= the 3 classes no command pattern can express — read-then-send spans turns, a prod target is a name not a verb, widening a deny list is self-disarming. - Alternatives rejected: keep them in
ask— inert, false sense of a gate. Back todeny— blocks legit process cleanup and inter-project copy, and the user works Bash-first under auto mode.classifyAllShell: true— closes the allow-tier blind spot but bills a classifier call on everygit status. Published-history rewrite ashard_deny— user declined;rebasethen an ordinary push stays uncovered, known gap. - Scope fix (same commit):
autoMode.environmentnamed/home/bchanot/Documents/atlast, its FTP deploy target and its customer data, inside the filelink.sh:21symlinks to~/.claude/settings.json. Every project received atlast's facts, and this repo's own Gitea remote contradicted the block's "no remote configured". Global block now machine-generic; atlast facts moved to atlast's gitignored.claude/settings.local.json. - Caveat: the guardrail
hard_denybars REMOVING adeny/soft_deny/hard_denyentry, not adding one. Future loosening goes through/permissionsor the user's own edit — deliberate, confirmed with the user. - Status: accepted.
- Reference:
settings.json,doctor.shcheck_automode,templates/settings/SETTINGS.md. Links LRN-153, LRN-146, BDR-004. - Status (2026-11-16): accepted, amended by BDR-136: ask tier back for merge gate + shell-form asks; ask prompts under auto since CLI 2.1.316 (LRN-256 f), headless sub-agent ask never runs; soft_deny/hard_deny cover kept
BDR-091 — Ask, don't guess: open-choice sweep + mid-run channel supersede "one question upfront"
- Date: 2026-09-16
- Decision:
CLAUDE.global.mdrule → ask on a VISIBLE (placement, wording, order, behavior), PUBLIC NAME (command, flag, endpoint, file) or SCOPE ("X too?") choice the request leaves open, even mid-task; class 4 (internal technical, no observable effect) never.lib/contract-interview.mdSTEP 2 = CLARIFY: pass A (gaps: outcome / scope / constraints) at contract time; pass B (open-choice sweep, 3 classes) ONCE at each flow's PLAN step, no question cap, >5 open → under-specified, list + stop; "you decide" recordedA: delegated — <default>, never re-asked. New MID-RUN CLARIFICATION: executor haltsNEED-DECISION+CLASS:tag; visible / public-name / scope → human verbatim; internal → loop decides, max 2 round-trips. New HOW TO ASK (LRN-102: ≤4 → one AskUserQuestion, context in option descriptions; else plain text ending the turn). Wiring: feat STEP 1, bugfix STEP 3, hotfix LOCATE (pass A stays silent autofill; one re-dispatch on class-tagged BLOCKED = the sole hotfix re-dispatch), ship-feature STEP 2, init-project STEP 3; interviewer: class 1-3 item never(assumed), one extra targeted question. Executors (feater, bugfixer, hotfixer) report the class. Locks: contract-verifier (9), loops-light (hotfix), gates (3). - Why: gap-only trigger structurally blind to taste — "add a share icon" passes outcome / scope / constraints and the icon lands wherever the executor put it; raising the 3-question cap changes nothing. feat:153 / bugfix:165 told the orchestrator "make the decision HERE", twice, before escalating = institutional guessing. Fresh re-dispatch keeps the tree, loses the executor's reasoning → a plan-time batch costs less than the same question mid-run; the mid-run channel stays for leftovers.
- Alternatives rejected: bigger budget (quota was never the limiter); new
lib/clarify.md(extra hop, STEP 2 already the mandatory passage every orchestrator runs); global rule only (skills carried explicit counter-instructions —zero questions ever,make the decision HERE,max 3 questions— the specific beats the general). - Risk watched: chattiness. Brakes = class 4 exclusion + over-5 guard. hotfix identity (speed, silence) = the flow to watch; if pass B fires on most hotfixes the class definitions are too wide, not the flow.
- Status: accepted. Behavioral check OPEN:
/feat "add a share icon to the header"must ask placement before dispatch; the fully specified variant must ask nothing → record inevals.md. - Reference: spec + plan
docs/superpowers/{specs,plans}/2026-09-16-ask-dont-guess*(purged at finish, in history at22ce57f), commits9eb6934..22ce57f, merge56bd035. Supersedes theCLAUDE.global.md:51rule line. Refines BDR-049 (contract), applies LRN-102. Links LRN-157.
BDR-092 — docker + node framed by the classifier (autoMode.allow), ask rules retired
- Date: 2026-09-16
- Decision:
Bash(docker run|exec *),Bash(docker[-| ]compose up*),Bash(node -e *)out ofpermissions.ask. NewautoMode.allow($defaultsfirst): (1) local dev containers —docker exec/run/composeagainst a workstation container whose name lacksprod/production, running a repo SQL file or script inside, output piped; Remote Shell Writes / Production Reads / Sensitive Remote Exec scoped to sensitive-named hosts; a literalDROP/TRUNCATE/DELETEon the command line stays under Mass Delete. (2) project-local node —node <file>,npm run/pnpm/yarnscripts,npx/pnpm execof a lockfile-declared package, effects in cwd. +2soft_deny: docker data destruction (rm -f,volume rm/prune,system prune,compose down -v,--privileged, bind mount outside cwd); undeclared node packages (npx/dlxabsent from lockfile,npm install <name>).modelbump to fable 5.1 committed alongside. - Why: real gate = built-in
Remote Shell Writes/Production Readssoft_deny catchingdocker execintosupabase_db_game; inside the classifierallow= exception tier (hard_deny > soft_deny > allow > explicit intent). StaticBash(node *)allow is suspended under auto (wildcarded interpreter) → prose is the only lever for a conditional node permission;awk/echostatics short-circuit,nodecannot.askinert on 2.1.273 (probe, LRN-155) — retiring it is forward-safe: if the documented prompt behavior lands, those entries would prompt for exactly what should run free. - Alternatives rejected: static
permissions.allowfor docker (short-circuits the classifier, framing impossible); keep theaskentries (inert today, wrong tomorrow); strict on every.sql(blocks the repo's verify scripts). - Trade-off accepted: a repo SQL file runs even when its content is opaque to the classifier — local dev DB only, resettable.
- Guardrail: S6 (loosening = user's own edit) overridden explicitly by the user for this change; diff reviewed on the branch before merge.
- Status: accepted. Verified:
jqvalid;claude auto-mode configshows the 4 entries with$defaultsexpanded;doctor.shautoMode PASS; livedocker exec -i supabase_db_game psql … -f - < verify/0043 … | tail→ROLLBACK, exit 0, no prompt.claude auto-mode critiqueprinted nothing (2.1.273). - Reference:
settings.json,templates/settings/SETTINGS.md(autoMode.allowrow + interpreter note), commit5eccc3f, mergeddadca6. Links BDR-090, LRN-153, LRN-155, LRN-156.
BDR-093 — 21st.dev: magic MCP retired for the 21st CLI + skill pack
- Date: 2026-09-22
- Decision:
@21st-dev/magicMCP out,@21st-dev/cli(bin21st) in — upstream supersedes it (README 1.17.1: "one unified CLI", old magic config now a thin proxy to the same endpoint). Auth =21st login, browser token in~/.config/21st; no API key, no MCP process.install-plugins.shStep 8.7:npm i -g(pin21stin plugins.lock.json) + staged21st skills install --global --agent claude+ TTY-only login offer + pack disabled by default.toggle-external.shmanages21stas a pack (names globbed fromskills-external/21st-*, parked under plain names = interoperable with profile.sh's external path). 5 design skills (21st-ui-build,-ui-explore,-ui-review,-cli-use,-ai) in design/web/web-full/full +MANAGED_EXTERNALS;-registry/-design-syncinstalled, parked.MANAGED_MCPSnow empty (mcp type kept, advisory). Gate:GATE-BLOCK: 21st 21st-ui-build— CLI = required-manual class,magic's old slot. Outward-facing verbs (publish*,submit,edit,delete,remove-from-catalog,profile set|upload) → oneautoMode.soft_denyentry, NOTask(LRN-153). - Why: user ask ("plus besoin de mcp / api, juste en cli"), confirmed at the source, not the marketing page — the 21st.dev web docs still show the MCP
init --clientflow and an API key; the npm package README is what states the supersession. Net wins: one less MCP loaded per session, no API key to protect by reference (BDR-026/BDR-057 vector gone), no unauthenticated local callback server (LRN-110 gone with the tool). - Blocker + shape it forced:
21st skills install --globalwrites<HOME>/.claude/skills/<n>/SKILL.mdand callsassertNoSymlinkComponentson every path segment —~/.claude/skillsIS a symlink torepo/skills, so the documented21st install-skillfails hard ("Refusing to access symbolic link …/.claude/skills", reproduced live). → install undermktemp -das HOME, move each skill intoskills-external/21st-*(gitignored), symlink on demand. Same impeccable/ctx7 machine-owned pattern. - Alternatives rejected: project-scope install (
<cwd>/.claude/skills) — Claude Code would ALSO scan it as project skills in this repo = every 21st skill listed twice; add the pack tolink.sh'sEXTERNAL_SKILLS— that loop force-creates symlinks, resurrecting a default-disabled pack on everymake link; all 7 skills in the design profiles — publishing flows cost 2 descriptions/session for a workflow the user does not run;askentries for the publish verbs — inert under auto (LRN-153, BDR-090/BDR-092 already retired that tier). - Status: accepted. Verified: toggle enable/disable/restore/idempotent round-trip (7 skills),
profile.sh show design, gate INCOMPLETE→names21stwith the two commands, gate PATH repair proven underenv -i PATH=/usr/bin:/binwith an nvm-stub,profile-set-managed.test.sh17/17,make test(2 pre-existing FAILs, gitleaks binary absent on this host), shellcheck clean. OPEN for the user:npm i -g @21st-dev/cli && 21st login— the deny ruleBash(npm install -g *)means the agent cannot run it. - Reference:
install-plugins.shStep 8.7,update-all.sh7.4,lib/toggle-external.sh,lib/profile.sh,lib/profiles/*.profile,lib/design-tool-gate.sh,lib/design-gate.md,CLAUDE.global.md,README.md,settings.json,.gitignore,.gitleaks.toml,.env.example,link.sh. Supersedes the operative parts of BDR-059 (the 4mcp__magic__*ask entries) and the magic instance of BDR-026/BDR-057; BDR-025's required-manual class stands, its magic example does not. Links LRN-158, LRN-110.
BDR-094 — impeccable: global-scope install through the repo symlinks, pin + @latest fallback, output-read failure check
- Date: 2026-09-22
- Decision:
install-plugins.shStep 8d +update-all.shrunnpx -y impeccable@<pin> skills install -y --providers=claude --scope=global --no-hooksstraight through the~/.claude/{skills,agents}symlinks → lands inskills/impeccable+agents/impeccable-*.md(both gitignored, machine-owned). No staging, nomv. Precondition guard: both symlinks must already point into the repo, else "run make link first". Pin failure →@latest+ loud "bump plugins.lock.json" warn. Profile-parked copy stays parked (install to live slot,mvback toskills-disabled/). Success = rc 0 AND installer output free ofDownload failed|Could not check for skill updates(imp_install, mirrored in both scripts, setsIMP_FAIL). Pin 3.2.0 → 4.1.0 (CLI only; skill dist 4.3.1 + engine 0.1.5 own tracks).link.shEXTERNAL_SKILLSdrops impeccable;skills-external/impeccable/gone.lib/design-gate.md§5: suggest/impeccable initonce when frontend project lacksPRODUCT.md. - Why: (1) 3.2.0 skill dist gone upstream → rc 1 →
make pluginprinted "run manually" forever. (2)--scope=project+ stagedmvmoved skill dir only, dropped the 4 subagents the same run wrote. (3) Global scope IS the repo install under the symlink model; staging bought nothing. (4) rc lies once a copy exists. Probe 2026-09-22, sandbox HOME, real installer: 4.1.0 then 3.2.0 → rc 0, "Could not check for skill updates: invalid zip data … Existing skills were left unchanged"; same-pin rerun → rc 0, "Skills are up to date (v4.3.1)"; both leave SKILL.md byte-identical (same mtime, same sha). - Alternatives rejected: before/after skill-version compare (first idea) → cannot separate rotted-pin no-op from up-to-date no-op, identical files + rc 0 both times → false warn on every rerun.
--force→ re-downloads ~15 MB engine + dist on everymake plugin, and the CLI's own update check already refreshes without it. Sharedlib/impeccable.shforimp_install→ deferred: two mirrored 12-line helpers vs new lib + test; revisit at a third caller. Project-scope install inside this repo → Claude Code scans.claude/skillstoo = skill listed twice, shadows the global copy (seen live, TODO T6). - Status: accepted. Verified: harness on extracted Step 8d, sandbox HOME, real installer, 4/4: fresh install (skill 4.3.1, 4 agents); rotted pin over a copy → fallback fires; same pin rerun → no false warn; parked + rotted → fallback, returned to
skills-disabled/.make testgreen minus 2 pre-existing T16a (gitleaks absent), shellcheck clean.update-all.shblock:bash -n+ shellcheck only, same helper, not run end to end. - Reference:
install-plugins.shStep 8d,update-all.sh,plugins.lock.json,.gitignore,link.sh,lib/design-gate.md§5. Links LRN-159, LRN-158 (21st: opposite case, installer refuses symlinks → stage), LRN-077 (pin doctrine), BLK-021.
BDR-095 — Data-loss guardrails: static deny for transfer/destructive tools, push every commit, brief ≠ user authority
- Date: 2026-09-22
- Decision: layer C of the post-incident plan (layers A OS/backup and B sandbox/managed-settings = user's side). (1)
permissions.denystatic: lftp/sftp/ftp/curl -T,rsync --delete,xargs rm, pipe-to-shell,chmod/chown -R, sudo/doas/pkexec, dd/mkfs/shred/wipefs/fdisk/parted, chattr, docker volume drops/system prune/compose down -v/--privileged/docker.sock/-v /:, git push --delete/--mirror/:ref/--force-with-lease, branch -D, filter-branch, reflog expire, stash clear/drop, clean -f, --no-verify, core.hooksPath.askentries for pipe-to-shell + stash drop/clear retired into deny. (2)hard_deny: destructive tool against a local path from a variable/~/../wildcard/outside cwd+tmp, trace or rehearsal included, brief carries no user authority. (3)soft_deny: docker entry reworded (promoted items out), + discarding uncommitted work. (4)environment: incident, push discipline, Claude never deploys. (5)lib/gitflow.sh:startpushes-u origin,_gitflow_merge_intopushes target,install-hookwrites post-commit + post-merge push hooks (--follow-tags, timeout 30,GITFLOW_NO_PUSH=1, warn-never-block). (6)hooks/unpushed-guard.shSessionStart+Stop systemMessage. (7) doctrine section "Destructive tools & data loss" + 4 report-only agents clause. (8)lib/tests/guard-bash.test.sh= spec of the PreToolUse guard, hook not shipped (BLK-022). - Why: 21/09 wipe (LRN-160): prose tiers named neither lftp nor a local trace, the orchestrator's brief authorized it, auto mode inherited by the sub-agent, nothing pushed for 4 days. User: Claude never deploys, only explains; test = dev server on this machine → lftp has zero legitimate use. Static deny resolves before the classifier and inside sub-agents (doc verified 2026-09-22); prose is judgment, static is a rule.
- Alternatives rejected:
asktier → doc says it prompts under auto, LRN-155 probe says inert, unresolved → nothing entrusted to ask. Keep docker volume drops in soft_deny (BDR-092) → "à tout prix" beats in-turn convenience; user runs them by hand. Post-commit hook alone for push →git mergefires post-merge, not post-commit (T18f caught it) → lib pushes the target explicitly AND post-merge hook emitted. Force-push allowance after amend → static deny stays; a rejected push warns and the user decides. Stop-hookdecision: blockon unpushed work → BDR-083 refused control-flow hooks; systemMessage only. - Status: accepted, on feature/destructive-guardrails.
gitflow-test.shT18 7/7 + T19 3/3, unpushed-guard 9/9,make testgreen minus 2 pre-existing T16a, shellcheck clean, doctor 0 errors. NOT DONE:hooks/guard-bash.sh(BLK-022). Existing projects needgitflow install-hookre-run for the push hooks. - Reference:
settings.json,lib/gitflow.sh,.githooks/{post-commit,post-merge},hooks/unpushed-guard.sh,lib/tests/{guard-bash,unpushed-guard}.test.sh,CLAUDE.global.md,templates/settings/SETTINGS.md,agents/{verifier,plan-challenger,analyzer,security-auditor}.md. Extends BDR-090 BDR-092 (ask inert, soft_deny doctrine); links LRN-114 (T19 drift gate), LRN-155, BDR-083. - Amendment 2026-09-22 (user go: "je valide les deux"): no per-project
install-hookstep. (a) GLOBAL:make linkrunsgitflow global-hooks→ generatesgithooks/from the emitters +git config --global core.hooksPath ~/.claude/githooks(symlinked into the repo) → every repo on the machine is protected + auto-pushed, gitflow-initialized or not (faunosteo class). Git precedence: a repo's localcore.hooksPathwins. (b) RECONCILE:hooks/session-start.shcallsgitflow reconcile-hooksonce per session → rewrites a lagging.githooks/(LRN-114 automated), banner line + commit reminder; pre-commit whitelist extended to.githooks/**so that refresh commits on develop. (c) Opt-outs per repo (foreign clone):git config gitflow.protect false,gitflow.autopush false— human-only, static deny ongit config gitflow.*and on theGIT_CONFIG_GLOBAL=/GIT_CONFIG=env bypass. (d) Hermetic tests:make test+ the two suites committing onmainexportGIT_CONFIG_GLOBAL=/dev/null, else the machine's global hooks fire in throwaway repos. (e) doctor: global setting +githooks/== emitted. Tests T18h, T19d, T20, T21. Rejected:init.templateDir(new repos only, ignored once hooksPath is set); dropping the per-repo.githooks/(portability to a machine without claude-config). Status: verified once /tmp was freed — gitflow 127/129 (2 pre-existing T16a), review-guards G5 flagged this repo's own stale.githooks/(the LRN-114 gate doing its job; refreshed via install-hook), shellcheck clean.make link(globalcore.hooksPath) refused to the agent by the classifier twice → user runs it. Doctor gained a "Scratchpad" check (BLK-021 mechanism).
BDR-096 — Branch deletion guard: lib-only delete after verified merge, main/develop undeletable at the ref layer
- Date: 2026-09-24
- Decision: user rule "auto-delete OK only once merged into develop or main; main/develop never". (1)
gitflow_delete= single delete path (finish + CLIdelete <br>): rc 2 unknown, rc 6 protected base, rc 5 not ancestor of develop or main (gitflow_merged_into_base, fail closed when neither base exists), thengit branch -dkept as 2nd layer. (2) 4th generated hookreference-transaction:preparedcall,refs/heads/main|developwith all-zero new value → exit 1, whatever issued it (branch -d/-D, update-ref -d, rename, script, sub-agent);gitflow.protect falseopt-out checked only on a hit.GITFLOW_HOOKSarray = single hook list (write/emit/reconcile, T19d, doctor viagitflow.sh hooks). (3) static denygit branch -d|--delete|-dr|-rd *,-m|-M main|develop*; hard_deny "Branch deletion by hand"; Disarming entry now covers all 4 hooks +gitflow.*config; environment protected-branches line. (4) doctrine CLAUDE.global.md gitflow §, SKILL.mddeleteop + rc 5/6 rows, guard-bash spec T8w flips to deny, SETTINGS.md/README/CHANGELOG. - Why: since BDR-095
startpushes-u origin→git branch -dchecks merge into the UPSTREAM (origin/
, kept in sync by post-commit), not HEAD → its valve is dead; T22a proves it._gitflow_deletesurvived only because finish chained it after a successful merge. Same doctrine as 21/09 (LRN-160): mechanical + static before prose; ref-layer hook holds for nested commands and sub-agents where the Bash deny cannot see. - Alternatives rejected: hook also refusing UNMERGED deletion → files backend rename = delete + create in separate transactions,
branch -dpasses zeros as old oid → merged check impossible/false positives onbranch -m, user-shell friction; lib + deny carry that rule. Remote cleanup after finish (push --delete origin/<br>) → in static deny since BDR-095, not requested; origin/
accumulates, flagged to user.-Din the lib → no,-dstays as defense in depth. Interactive brainstorm → user absent (autonomous run), request unambiguous; trade-off (hook blast radius) stated in the report instead. - Status: accepted, on feature/branch-delete-guard, UNMERGED (human gate). gitflow-test 152/154 (2 pre-existing T16a, gitleaks absent), T22 12/12 + T23 11/11, shellcheck clean incl. emitted hook, doctor 4/4 hooks match. Hook LIVE machine-wide via global
githooks/while the branch is checked out (symlink follows the checkout). - Reference:
lib/gitflow.sh,lib/gitflow-test.shT22/T23,githooks/reference-transaction,.githooks/reference-transaction,settings.json,doctor.sh,skills/gitflow/SKILL.md,CLAUDE.global.md,templates/settings/SETTINGS.md. Extends BDR-095; links LRN-161, LRN-114. - Amendment 2026-09-24 (user go: "nettoie aussi les branches distantes une fois mergées"):
_gitflow_delete_remoteruns after the local delete —ls-remote --exit-codereads the remote tip,gitflow_merged_into_base <tip>re-checks it (unknown or unmerged sha → remote copy KEPT, loud), thenpush origin --delete. Best effort like the pushes: no origin /GITFLOW_NO_PUSH=1/gitflow.autopush false→ skip; unreachable or refused → "NOT removed" + the hand command, rc 0. Explicit protected-base guard inside the helper too. Static deny on handgit push --deleteUNCHANGED: it matches the Bash tool's command string, the lib's sub-process is the sanctioned path (prose says so). Rejected: making a failed remote delete failfinish(merge done, local gone → nothing to roll back; loud is enough); deleting without re-checking the remote tip (a push from another clone would be lost). T24 9/9, suite 161/163 (2 pre-existing T16a). Live: origin/feature/branch-delete-guard + origin/feature/destructive-guardrails removed bygitflow.sh delete(both tips verified merged), bases untouched. On feature/remote-branch-cleanup, UNMERGED (human gate).
BDR-097 — graphify from 200 tracked code files: the banner informs, the user decides
- Date: 2026-09-24
- Decision: deterministic threshold, not AI judgment.
lib/graphify-gate.sh:git ls-filescode extensions (graphify's AST set), vendored trees (vendor|node_modules|third_party|dist|build) excluded, ≥ 200 AND nographify-out/graph.json→ one banner-sized linegraphify? N code files ≥ 200, no graph+→ /graphify (AST, seconds) — you decidein session-start. Nothing built, installed or updated by the hook. Doctrine: CLAUDE.global.md graphify § carries the threshold + "nevergraphify claude installwithout a go"; plugin-advisor thresholds stop pre-enabling graphify at scaffold time.GRAPHIFY_MIN_CODE_FILESoverrides (tests). - Why: user question "when is graphify worth it, can the AI suggest it, even set it up". Measured first (LRN-162): value = localisation (who calls what), not editing (the file is read anyway); code-only build is free (AST), docs cost session tokens; a query costs 2-3k tokens ≈ two file reads. Below ~200 files grep beats the graph. User's own words: "tu informes, je décide" — an AI-estimated trigger is judgment (irreproducible, invisible when silent), a count is a rule. Fits
graphify-out/being a per-project write the user owns. - Alternatives rejected: AI "estimates the project needs graphify" → not reproducible. Auto-build at threshold → writes ~8 MB into the project, user's decision. Interconnection metric (import graph density) → needs the graph itself to compute; file count is the honest proxy. Post-commit
graphify updatein the gitflow hooks → deferred to a pilot (user picked the inform-only compromise); noteupdaterefuses a smaller graph without--force, andgraphify hook installis inert under the globalcore.hooksPath.graphify claude install→ rejected again (PreToolUse nudges on every Read/Glob = the context tax, BDR-028). - Status: accepted, on feature/graphify-threshold-banner, UNMERGED (human gate). Test 11/11, shellcheck clean; live: this repo silent (74 files), robin_petier fires (214).
- Reference:
lib/graphify-gate.sh,lib/tests/graphify-gate.test.sh,hooks/session-start.sh,CLAUDE.global.md§ graphify,agents/plugin-advisor.md, CHANGELOG. Links LRN-162, BDR-028, BDR-021 (conditional graphify rules).
BDR-098 — CLAUDE.global.md density pass 352 → 270: compression only, three name-obvious routing lines dropped
- Date: 2026-09-24
- Decision: user go "fais la passe de densité". BDR-031 principle kept (compression, no path-scoping, no externalization, no caveman); BDR-062's 320 guard kept. Method: prose tightened section by section, blank lines after headings removed, the 6 classic Security subsections folded into one bold-labelled bullet list (
### Destructive tools & data losskept as a heading, referenced from Workflow), Session-start / Planning / After-code numbered lists collapsed, Memory-registries prose rewritten (routing list → one sentence, language + format paragraphs merged, close ritual → one sentence), radical-honesty tenets paired two per bullet, gitflow paragraphs re-flowed. Deliberately dropped: routing linesrelease-candidate,audit-delta,init-project/onboard(name-obvious, the skill descriptions carry them — BDR-031's own criterion), rationale clauses (why English, why caveman),~/.claude/githooksliteral,T22acite, pa11y/HTML-CSS detail in the web-validate line. Every##heading verbatim (Design work — full toolchain (tiered by scope)is matched by the design-toolchain hook). graphify section left byte-identical:feature/graphify-threshold-banner(unmerged) edits it, a clean merge matters more than 2 lines. - Why: 352 lines after BDR-085/091/095/096/097 growth, banner red since 2026-09-22. Words 2694 → 2302 (−15%), doctor passive estimate ~3.9k tokens; loaded every session in every repo. Token-diff audit of the old vocabulary: 174 tokens absent, all rephrasings or the listed drops, no constraint lost.
- 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
- Decision: user go on all four groups. G3 judgment calls: (12) BDR-068 auto-finish of the memory-only
chore/*by /capitalize+/close KEPT, written into CLAUDE.global.md + gitflow SKILL as the one finish without a live signal; (13) memory commit on develop: hook exemption for a commit that follows merged work, aiguillagechore/*for a standalone memory task — both written; (14)chore/*widened to "maintenance without new behaviour" (memory, docs, cleanup, /refactor, /tour fixes), /commit-change asks the type (public name); (15) /tour never applies a contract-breaking fix →open — needs decision (BREAKING); (16) client-handover: children audit and return FIX BUNDLEs, the main loop applies AUTO items and gates the rest at ONE gate (harden whole bundle, seo D/E, geo G5, CSO dependency bumps); (17) /hotfix on develop → typebugfix,hotfix/*= prod incidents only; (18) /seo aggressive + /web-validate --fix → feature branch, /refactor → chore, via the aiguillage; (19) /doc → chore row + STEP 0. G1/G2/G4 = doctrine wins mechanically (see CHANGELOG). Lib:gitflow initsocle viachore/gitflow-adoptmerge (T2c). - Why: TODO C2 (2026-08-25). Three read-only Plan-agent audits (doctrine+rules / skills A-H / skills I-W), 39 raw → 30 unique pairs, heaviest spot-checked by grep. Two classes dominated: today's own partial fixes (graphify 200 rule missing in init-project/onboard; density pass removed a heading 5 skills cited; deploy routing line) and BDR-095 staleness (push everywhere made deploy/release/tour/capitalize push wording false; global hooks broke init on existing repos). LRN-164 applied to myself: a rule change must grep every citer.
- Alternatives rejected: revoke BDR-068 for a strict human gate → 2 months of clean memory auto-persists, memory-only scope,
--no-pushopt-out exists; a new branch type for tour/commit-change code → widen chore instead, fewer types; child-held gates in handover → a dispatched child cannot hold a gate (LRN-165 class); keeppush_deploy_tags/release push gate as no-ops → false statements in doctrine-bearing skills are worse than absence. - Status: accepted, feature/c2-coherence, UNMERGED (human gate). 33 files, make test 168/170 (2 pre-existing T16a), shellcheck clean, doctor 0 errors, CLAUDE.global.md 282 lines.
- Reference:
CLAUDE.global.md,lib/gitflow.sh_gitflow_adopt_socle,lib/gitflow-test.shT2c,lib/gitflow-aiguillage.md,lib/verify-secure-loop.md,lib/design-gate.md, 16 skills, 4 agents, CHANGELOG. Links BDR-068, BDR-095, BDR-097, BDR-098, LRN-164, LRN-165, LRN-169.
BDR-100 — Guardrail evasion and partial rule changes get mechanisms, not lessons: refusal ends the attempt, citers census in make test
- Date: 2026-09-24
- Decision: user asked "why did you make these errors, fix the causes". (1) Evasion:
permissions.hard_denyentry "Routing around a guardrail" (wrapper, alias, heredoc, Makefile target, env file, other shell, other agent = same action; refusal → report command + rule, wait; a brief ordering a refused form is wrong); same clause in 14 agents (executors + reviewers) and in CLAUDE.global.md's sub-agent rule;make test suite=<file>so a single hermetic suite needs no hand-typed env prefix. (2) Partial rule changes:lib/tests/doctrine-citers.test.shinmake test— everyCLAUDE.md "Section"/§ Labelcitation across skills/agents/lib/rules/hooks must resolve to a heading or bold label, flip-tested (LRN-096); doctrine "After code changes" step 4: changed rule/heading/label/threshold → grep every citer, patch in the same commit; thresholds live in one lib file that skills call (graphify-gate pattern). - Why: root causes established on evidence, not guessed. Evasion: MY brief to E2 said "run the suite with
GIT_CONFIG_GLOBAL=/dev/null … exported first" — I ordered the exact form the static deny lists; the executor was refused, then wroterun-rc.shcarrying the prefix one level down and ran it. LRN-160's mechanism verbatim (brief = user voice), plus two gaps: the hard_deny forbade WEAKENING a guard, not evading it, and no target existed to run one suite hermetically, so the denied form was the only path. Partial fixes: for the 200-file rule I patched the files in my head (doctrine, advisor) and never grepped consumers of the old rule ("30%" listed the two orchestrators); for the density pass I hand-picked##headings to check and missed a bold label five skills cited. Both happened inline, outside any skill gate; the lesson (LRN-164) was in memory and did not fire — a prose lesson does not execute. - Alternatives rejected: static deny on
bash <scratch>/*.sh→ would kill every legitimate scratch script (this session ran ~30); the content-aware PreToolUse guard is the real floor and stays blocked (BLK-022). Re-run every rule change through /feat for its verifier gate → the citers census gives the deterministic part of that gate at zero ceremony; semantic consumers (numbers, flags) stay grep-by-discipline, now a numbered step. Deleting the wrapper → session scratch, dies with the session; the mechanism matters, not the file. - Status: accepted, feature/guardrail-evasion-citers, UNMERGED (human gate). doctrine-citers 5/5 (flip + repo, one real dangling fixed), make test 168/170 (2 pre-existing T16a),
make test suite=verified, shellcheck clean, CLAUDE.global.md 287 lines. - Reference:
Makefile,settings.jsonhard_deny,CLAUDE.global.mdWorkflow + After code changes,agents/*.md(14),lib/tests/doctrine-citers.test.sh,lib/project-archetypes/rest-api-node.md. Links LRN-160, LRN-164, LRN-169, EVAL-030, BLK-022, BDR-095, BDR-099.
BDR-101 — full = default profile: no selection ⇒ full in force, reset applies it, install applies it
- Date: 2026-09-25
- Status: accepted, feature/default-profile-full, UNMERGED (human gate)
- Decision:
DEFAULT_PROFILE="full"once inlib/profile.sh;active_profile()resolves cache absent / empty / legacynone→ full.reset=set full(exclusive: enable full's list, park non-listed gstack/managed items).currentlabel-driven: namesactive_profile(), scores THAT profile only,default — not applied yetuntil set/apply/reset wrote cache; cross-profile best-guess scan +none/customsentinels gone. Statusline reads constant (sed, literal fallback), showsfullnot?.make pluginStep 11: no selection →reset, selection →set <sel>(Steps 2/10 rewrite skill state every run); Step 8.7 no longer parks 21st pack (profile governs: full links 5 design skills, 2 publishing stay on demand). User-gated: reset semantics, install applies default, README one history line,.envline deleted. - Why: user ask "profil par défaut = full". LRN-020 kept honest: full made the REAL default (state = label), not a relabelled sentinel. Parked-gstack count was false signal: gstack OFF on real tree (BDR-030), 0 parked ≠ all enabled.
- Alternatives rejected: label-only reset (lies about plugins/externals); additive reset (
gstack on+apply full, state ⊇ full, label ambiguous); keepnonesentinel + statusline?(request unmet); install display-only (fresh machine ≠ full, 21st pack parked); publicprofile.sh defaultverb for installer (reset already IS "go to default"); one shared cache parser (statusline must not spawn profile.sh → 3 copies kept, each commented). - Caveats:
make pluginre-run re-applies selected profile → manual layering (gstack onoverdev) trimmed back. Plugin legs of Step 11 install-immutable (BDR-028 EXIT guard; committed enabledPlugins already match full). LOW security note: cache content not charset-checked before path use (pre-existing inread_profile) → follow-up. - Reference: commits
e196328(residue scrub),0d035fc(profile),1bbdad0(install); contract/plan2026-09-25-default-profile-full-1254;lib/tests/profile-default.test.sh29 checks. Links BDR-017 BDR-018 BDR-079 BDR-093 LRN-170 EVAL-031. - Status (2026-11-16): accepted, merged 1ee6cf6; amended by BDR-134: policy full = default kept, mechanism replaced: no cache, reset or sentinel; no profile = manifest defaults = full
BDR-102 — agent-skills: no plugin, vendor 3 skills + build floor-guard + routing census + rest-api rule
- Date: 2026-09-27
- Status: accepted, feature/agent-skills-borrow, UNMERGED (human gate)
- Decision: addyosmani/agent-skills (99.4k stars, 25 skills) NOT installed as plugin. Borrowed 4 things, user go: (1)
observability-and-instrumentation,deprecation-and-migration,ci-cd-and-automationvendored emil-way at pinned commit 2686b620 (lockagent-skills, install Step 8e tmp+mv, update-all 7.3, link.sh, toggle-external per-name, profiles full/backend/dev); (2)lib/floor-guard.shdiff-scoped bar-weakening detector, verifier STEP 3 mandatory, waiverfloor-guard: allow <reason>; (3)lib/tests/skill-routing-census.test.shTF-IDF description-collision census, WARN 0.50 / FAIL 0.75; (4)rules/rest-api.mdpath-scoped, distilled from api-and-interface-design minus the one-version rule. - Why: 20/25 skills already covered (superpowers, personal skills, gstack, built-ins). Real gaps grep-verified: observability (archetype question only), migration (one strangler line), CI build (ship/cso only detect), bar-weakening guard (security-auditor flags nosemgrep only), collision census (routing section exists because of collisions; darwin scores quality not collisions). Upstream comparison doc: never stack two skill routers.
- Alternatives rejected: plugin install (1.8k tok/session for 20 % novelty,
/spec/review/shipcollide with gstack,/code-simplifyvs/simplify, trunk-based git + one-version API contradict doctrine, second router); vendor api-and-interface-design whole (one-version rule vs § Web APIs → distilled); groupedagent-skillstoggle pack (no shared installer, per-name like emil); web-full profile for the trio (design-class, allowlist wins over "lists bugfix"); Tier 2 prompt ranking (follow-up). - Caveats: vendored prompts = third-party content loaded into sessions, the pin is the review point (security-auditor scanned: benign, no hidden Unicode); floor-guard waiver is self-service, WAIVED informational → security MEDIUM, design decision pending with user (require CLARIFICATIONS ack outside test fixtures?); floor-guard prints raw diff snippets a verifier reads (LOW, framing follow-up); update-all 7.3 failure branch leaves
.tmplike emil (parity, not fixed);make linkafter merge to symlink the trio (user). - Reference: commits
d28c45e(trio),2b25cb4(floor-guard),409db51(census),1a8e6de(rest-api); contracts.claude/tasks/contracts/2026-09-27-{agent-skills-vendor,floor-guard,skill-routing-census,rest-api-rule}-1525.md; gates MET ×4, verifiers CONFORME ×4 (2 re-dispatches), security PASS ×2. Links BDR-100 LRN-172 LRN-173 EVAL-032. Case 1 of the same review: ladder in doctrine, feature/yagni-ladder9315c6c. - Amendment 2026-09-27: waiver policy strict, user go:
WAIVEDoutside a test file = gap unless the contract's CLARIFICATIONS names file + reason (verifier STEP 3, loop doc). Commit6617889. Closes the security MEDIUM caveat above.
BDR-103 — 6-repo review: 5 verdicts, 3 criteria; stars decided nothing
- Date: 2026-09-27
- Status: accepted, chore/six-repo-review-notes, merge on user go 2026-09-27
- Decision (user-approved case by case, order = layer touched per turn → orthogonal):
repo stars verdict one-line why ponytail + chisle 146.7k / 566 no plugin; ordered YAGNI ladder + shortcut:marker into § Code style (feature/yagni-ladder)per-turn + per-subagent injection, prose rules vs writing-style.md, caveman purge precedent, rtk covers the input axis addyosmani/agent-skills 99.4k no plugin; vendor 3 skills, build floor-guard + routing census, distil rest-api rule (BDR-102) 20/25 covered, 1.8k tok/session, /spec /review /ship collide, trunk-based + one-version vs doctrine, second router ibelick/ui-skills 9.2k nothing installed; 14 micro-rule lines in rules/web-building.md CLI/MCP = curl of raw SKILL.md, third router, baseline-ui stack mandates vs Astro-first; registry of 36 third-party skills (mengto motion pack) NOT evaluated reticlehq/reticle 898 parked, 4-step pilot recipe in TODO only real capability gap (store state, verdict with file:line, replayable flows, CI gate); FSL server, PostHog telemetry, per-project build instrumentation, skill auto-runs initOmniRoute 70.6k rejected, no recipe subscription cannot pass a keyed gateway; fail-open guardrails, default JWT secret, Socket.dev block on 3.8.5, JA3/JA4 spoofing + free-tier pools - Criteria that decided every case: (1) coverage verified by grep on local assets (skills, agents, rules, archetypes), never from the README; (2) permanent per-session cost (descriptions, hooks, MCP schemas) against the share of novelty; (3) conflict with doctrine (gitflow, versioned APIs, Astro-first, ask-don't-guess, fail-closed). Stars decided nothing: 566-star chisle beat 146.7k-star ponytail on method; 898-star reticle is the only real capability.
- Alternatives rejected: install-then-prune (sunk cost, BDR-047 ECC lesson); one bulk verdict (user wanted one case per turn, each with a build-vs-install call); building reticle's engine (1 286 server files).
- Caveats: borrowed prompts change upstream with no diff, the pin is the review point; do not re-audit these six expecting more; mengto motion pack from the ui-skills registry is the open follow-up if site-level choreography (GSAP/ScrollTrigger, WebGL hero, masked reveals) proves thin locally.
- Reference: branches feature/yagni-ladder (
9315c6c,de7371d), feature/agent-skills-borrow (d28c45e2b25cb4409db511a8e6de74013836617889d71f3a7), feature/web-building-microrules (a2e654d5a27372), chore/six-repo-review-notes (da35cde197225a). Links BDR-102 LRN-172 LRN-173 EVAL-032 BDR-047 BDR-006.
BDR-104 — MengTo motion pack: vendor 5 scroll skills via a shared helper + build site-motion; 17 skipped
- Date: 2026-09-28
- Status: accepted, feature/mengto-site-motion, UNMERGED (human gate)
- Decision: (1)
lib/vendor-skills.sh= onevendor_pinned_skills <lock-key> [refresh]for every curl-vendored upstream (agent-skills moved onto it; lockskillsas list or dict of file lists; python argv lock read;../charset guard;VENDOR_BASE_URLonly asfile://; tmp+mv; refresh skips never-installed skills, update-all convention). (2) Vendored at a965851: scroll-world-storytelling, build-threejs-scroll-worlds (+5 refs incl. scroll-conductor.js), scroll-scrubbed-visual-sequence, scroll-scrubbed-word-reveal, scroll-progress-timeline; text only, never demo/agents/binaries; design/web/web-full/full profiles. (3)skills/site-motionpersonal: invariants of the other 17 (gates, engine choice, Lenis sync, Astro ClientRouter lifecycle, numbered recipes, pitfalls); routed in CLAUDE.global.md Build UI chain + design-gate (not GATE-BLOCK). - Why: user asked whether the UI profiles carry motion knowledge for lively sites. Census: component polish deep (emil 27 KB, motion cookbook, impeccable animate), site choreography thin as workflows; ui-ux-pro-max CSVs cover terms but as search rows (LRN-174). Two analyzers read 22 skills: 5 clean workflows/recipes absent locally; 17 covered, generic, buggy (reduced-motion
clearProps, gate beforeregisterPlugin, no-JS opacity 0, refresh-ratephi) or Codex/Xcode machinery → distil per LRN-141. Registry sample (11) ≠ catalog (88): always list the tree. - Alternatives rejected: vendor all 22 (bugs + duplicates + 17×~100 tok descriptions); distil only (loses the two deep workflows whose value is their full text); second inline curl loop (duplication; helper instead);
VENDOR_BASE_URLgated by a companion var (file:// prefix check suffices); grouped toggle pack (per-name like emil). - Caveats: vendored prompts change upstream with no diff, pin = review point; GSAP-first content vs BDR-005
motiondefault, site-motion states the allowance; LOW hardening open:re.match$accepts a trailing newline,source/path/shalock fields not charset-checked;make link+bash lib/profile.sh apply fullafter merge (user); sub-agent leftovers/tmp/mengto-verify(user removes). - Reference: commits
2a1ad17(helper + vendoring),ba14b5e(site-motion); contracts.claude/tasks/contracts/2026-09-27-{mengto-vendor,site-motion-skill}-0002.md; gates MET, verifiers CONFORME after 3 re-dispatches (frontmatter shape, refresh convention, security env override + traversal), security PASS ×2,make test36 suites green minus 2 pre-existing T16a. Links BDR-103 BDR-102 LRN-141 LRN-174 EVAL-033. - Amendment 2026-09-28: the two LOW caveats closed on user ask (
415b44e):re.fullmatchguard,commit/source/pathvalidated before URL construction, 4 more hermetic cases (12). Security PASS, verifier CONFORME 9/9. - Amendment 2026-09-28 (doctor):
make doctornow checks every vendored external (6394fa7, feature/doctor-vendored-skills): lock files present, symlink per active profile, parked ≠ failed, hints. Lib sourceable for the hermetic suite (11 cases); doctor mirrorsactive_profile()instead of sourcing profile.sh (its main runs on source). Security: lock shape-validated, allowlists on profile/item names. Closes the gap that emil/frontend-design/motion had since their install.
BDR-105 — skill-catalog prune: 9 gstack removed, full ⊇ every profile, max = everything, two plugins off, Stop review off, 21st sign-in gate
- Date: 2026-09-28
- Status: accepted, feature/skill-catalog-prune, merged to develop 2026-09-28 (user go "merge le tout")
- Decision: (1)
lib/gstack-removed.sh= single denylist (ship, land-and-deploy, setup-deploy, autoplan, context-save, learn, careful, guard, design-shotgun): in no profile,maxincluded;profile.sh gstack onandtoggle-external enable gstackskip them. (2) User rule:full(default) carries everything every other profile carries, one allowlisted exception pr-review-toolkit;max(# SUPERSET-OF: full) = full + parked (make-pdf, diagram, 21st-ai/ui-explore/ui-review) + pr-review-toolkit. 21st trio out of full/web/web-full/design.lib/tests/profile-census.test.shlocks the three invariants live + baseline/mutant fixtures. (3) Live plugin state: brightdata-plugin@syncedfalse, frontend-design@claude-plugins-official uninstalled (byte-dup of the managed skills-external copy). (4) settings.jsonenv.ENABLE_STOP_REVIEW=0: security-guidance keeps regex + commit/push agentic review, loses the Opus call per code-changing turn. (5)lib/gstack-links.shbuilds the whole helper tree under~/.claude/skills/gstack/(83 hardcoded paths), one lib for link.sh, install-plugins.sh, update-all.sh;lib/doctor-skills.shcounts through symlinks with the census parser. (6) Routing: Ship/PR → ship-feature, never gstack ship. (7) Design gate exit 12SIGN-IN REQUIRED: installed-but-signed-out 21st → ask! 21st login, end turn, re-run; explicit "proceed without 21st" = only skip; unknown whoami → 11 with diagnostic. - Why: 5-analyzer audit over 150 skills / 53.5k chars of descriptions; harness shows ~19k, least-invoked lose theirs → 78 name-only this session (LRN-175). ship base = origin/HEAD = main on Gitea; land-and-deploy
gh pr merge --squash+ deploy; autoplan/make-pdf/diagram/careful/guard/freeze hardcode paths only bin + browse/dist linked (LRN-177); context-save without restore; brightdata keyless +bright-data-mcporders WebFetch replaced; security-guidance 0 findings / 6 days, 1 FP (EVAL-024); doctor undercount ×6. 21st CLINot logged in→ user: ask and wait, not skip. - Alternatives rejected: rm symlinks by hand (set/reset re-materialize,
gstack onrestores everything → denylist instead); per-skill toggles inside ui-ux-pro-max (all-or-nothing, unverified); drop superpowers in the same run (7 skills wired in ship-feature/init-project → tier 2, own branch); keep the 21st trio in design profiles (redundant with impeccable + ui-ux-pro-max, CLI signed out); raiseSLASH_COMMAND_TOOL_CHAR_BUDGET(costs context, the opposite goal); keep the official frontend-design plugin and drop the copy (copy is profile-managed and gate-checked); shared 21st auth helper across 3 scripts (breaks 4 fixture suites, changes installer semantics — LRN-178); in-sessionexport TWENTYFIRST_TOKENremedy (env does not persist across tool calls). - Caveats: kept gstack skills still route to removed names in their upstream prose (Skill call fails, doctrine applies); helper tree links every top-level submodule entry (no SKILL.md exposed, asserted); security-guidance commit review quota unmeasured; doctor constants rebased on 2026-09-28 measures;
applyis additive → other machines runset full, notapply. - Reference:
f83f8f702b62f74c86d6d729d715(prune),bd3e525132bcdf(21st gate); contracts2026-09-28-skill-catalog-prune-0554(18 criteria, oracles in.oracles/) and2026-09-28-21st-signin-gate-1215(7); plans r4 / r3 after 3 challengers + 1 confirmation each; GATE 0 MET, verifiers CONFORME (iter 2 / iter 1), security PASS ×2; 42 suites green minus 2 pre-existing T16a. Links BDR-030 BDR-101 BDR-093 BDR-095 BDR-080 BDR-025 BDR-070 LRN-175 LRN-176 LRN-177 LRN-178 BLK-023 EVAL-034.
BDR-106 — superpowers: 7 skills vendored at v6.4.1, plugin dropped
- Date: 2026-09-28
- Status: accepted, feature/superpowers-vendored, merged to develop 2026-09-28 (user go "merge le tier 2")
- Decision: (1) plugins.lock.json
superpowersentry (obra/superpowers @ 5bf4e78 = tag v6.4.1, pathskills, per-skill file lists,always_on: true), fetched byte-for-byte by lib/vendor-skills.sh: brainstorming, writing-plans, subagent-driven-development, test-driven-development, requesting-code-review, using-git-worktrees, writing-skills; STEP 8e vendors, update-all refreshes at the pin, link.sh links, .gitignore ignores. (2) Plugin + marketplace uninstalled (one shot by hand after the fetch proved byte-identical), settings.json keys removed by hand, PROTECTED_PLUGINS = security-guidance only;detect_superpowers=[ -f ~/.claude/skills/brainstorming/SKILL.md ], no plugin fallback; doctor/session-start no longer charge the injection. (3) doctor-vendoredalways_onclass: third lock column,_dv_check_link5th param — always-on externals are link-checked, never "parked". (4) Citers call the bare names; CLAUDE.global.md maps the four non-vendored skills the vendored text still references (executing-plans → SDD, finishing-a-development-branch → gitflow finish, systematic-debugging → bugfix, verification-before-completion → verifier gates). Vendored text never edited (BDR-104 rule). - Why: 7 skills wired (ship-feature, init-project, writing-skills TDD), 8 duplicate personal flows; SessionStart injection 3.6 KB per start/clear/compact + a competing router ("1 % → MUST invoke", BDR-080 conflict); 15 descriptions → 7. Tier 2 of BDR-105.
- Alternatives rejected: shared auth/detect helpers sourced at top level (break the fixture
cpsuites, LRN-178); installer-side uninstall (plugin gone before the fetch on a network failure; precedent = comment only, one-shot by hand); detect with plugin-cache fallback (the marketplace dir matches*superpowers*→ "vendored" on a plugin-only machine, fail-open); rewriting vendored text to fix cross-refs; vendoring all 15; map text spelling the colon form or wrapping identifiers (criteria 3/7 grep line by line — both caught by challengers). - Caveats: upstream cross-refs to the plugin prefix and the 8 dropped skills remain in the vendored text (a call on a dropped name fails, doctrine map applies); no upstream auto-update (bump the pin deliberately); the harness hot-loaded the 7 bare names in the running session after link.sh, the plugin names leave at restart;
superpowers-marketplacecache dir may linger empty; other machines:make plugin(vendors) +make link, then uninstall the cached plugin by hand (CHANGELOG). - Reference:
18f8c89(wiring),ddea411(citers/docs/settings); contract2026-09-28-superpowers-vendored-1357(12 criteria, oracles in.oracles/), plan r3 after 3 challengers (simplicity CONCERNS(2), robustness CONCERNS(3), correctness FATAL(5)) + confirmation CONCERNS(1); executors 2/2 DONE first pass; GATE 0 MET, verifier CONFORME 12/12, security PASS; catalog 82 skills, plugin passive cost 670 t (ui-ux-pro-max only). Links BDR-105 BDR-102 BDR-104 BDR-065 LRN-178 EVAL-034. - Amendment 2026-09-28 (merge):
gitflow finish→65665a5, no conflict, pushed, local + origin copies removed; the 7 vendored skills stay linked after the merge. Whole prune (tiers 1 + 2) on develop.
BDR-107 — Effort tiering: session high, agent pins, skill entry levels, paired phase shifts, max at escalation [accepted] (2026-09-28)
- Decision: settings
effortLevelhigh (was xhigh).effort:pin on 20 repo-authored agents by role: low appliers (hotfixer, release-executor, plugin-probe, validator-analyzer), medium executors (feater, bugfixer, code-cleaner, onboarder, scaffolder), high judgment (refactorer, analyzer, commit-changer, doc-syncer, handover-doc-writer), xhigh challengers + gates (plan-challenger, plugin-advisor, verifier, security-auditor, seo-analyzer, geo-analyzer); none on interviewer/client-handover-writer (inline-load), status-reporter (haiku), impeccable-* (vendored).effort:on 28 tracked user-invoked skills = run entry level (low bookkeeping, medium gitflow/prune-memory, high feat/hotfix/bugfix/refactor/audits-with-fix, xhigh orchestrators) + xhigh on vendored brainstorming/writing-plans (skills-external/, re-applied by install-plugins STEP 8e). Five shifter skillseffort-{low,medium,high,xhigh,max}loaded by orchestrators perlib/effort-shift.md: medium at dispatch span, own level before challenge synthesis, low at bookkeeping tail, max at verify-secure caps (GATE 0/1/2) + ship-feature 4b; re-assert after nested skill / prose gate. STOP texts name$CLAUDE_EFFORT, suggest/effort-max. statusline shows$CLAUDE_EFFORT; banner warns onCLAUDE_CODE_EFFORT_LEVEL. Censuslib/tests/effort-routing.test.sh. Audit scriptlib/effort-audit.py. - Why: session-wide xhigh burned thinking on bookkeeping; EVAL-035: 97 % of thinking in the main loop, sonnet subagents ~26 tok/request → main-loop levers (entry level, shifts) carry the savings; pins = explicitness + future models. A/B
/reconcilehigh→low: requests 18→15, output −27 %, thinking −28 %, time −19 % (EVAL-036). - Harness facts (2.1.283): skill
effort:applies on user slash invocation and on interactive Skill-tool load; the Skill-tool load applies ONLY when paired with another tool call in the same message (lone call = no-op); re-load re-applies (text deduped); not applied in-p/SDK; prompt cache kept across a shift;CLAUDE_CODE_EFFORT_LEVELbeats every frontmatter; one effort per agent file, no call-site override; unpinned agents inherit the level in force at dispatch. - Alternatives rejected: executor pins only (they barely think); escalation-diagnoser agent fable+max (no context, one more agent; main-loop max keeps the failure context); reflection in fable skill-runner children with session medium (loses interactivity); settings.json rewrite mid-run (LRN-098 class);
maxEffortLevelcaps (hide a mis-pin the census should fail); pins on machine-generated skills (find-docs: ctx7 regenerates, gitignored) or gstack skills (spec, skillify). - Caveats: shifts inert headless; a prose gate ending the turn resets to session level (re-assert wired in bugfix and ship-feature 4b); mode-based agents pin their judgment mode; a shift paired with a built-in judgment dispatch would downgrade it (pair with Read/Bash instead);
lib/gitflow-test.shT16a red on this machine = gitleaks not installed, unrelated. - Refs: spec
docs/superpowers/specs/2026-09-28-effort-tiering-design.md, plandocs/superpowers/plans/2026-09-28-effort-tiering.md, LRN-179, EVAL-035, EVAL-036, BDR-077. - Correction (2026-09-28): EVAL-035 counted one record per content block (~2.8× on request counts); deduped figures in EVAL-037: main-loop thinking 99.9% of total thinking (was 96.6%), thinking 5.6% of weighted cost (was 8.4%), sonnet think/request 26→0.2 tok. Conclusions hold, sharper: main loop still carries almost all thinking, executors stay cheap.
- Amendment (2026-10-25, bugfix
8e93507): "none on status-reporter (haiku)" superseded: status-reporter pinseffort: low(itsmechanicalrow); censuseffort-routing.test.shno longer skips haiku agents. Reason: Haiku 5.5 takes effort. Links BLK-035.
BDR-108 — Effort round: every skill carries a level next to its model pin; model pins stay tier aliases [accepted] (2026-09-29)
- Decision: 3 repo skills pinned (skills-perso low, pdf-translate medium, site-motion high). 25 vendored externals (superpowers 7, agent-skills 3, design stack 9, 21st pack 6) get level from
lib/effort-pins.txt, applied bylib/effort-pins.shafter LAST vendoring step of install-plugins.sh (21st pack, STEP 8.7) AND update-all.sh (§7.4). Design stack = ONE level, high. hotfix stays high. Model pins stay aliases (sonnetopushaikufable). Doctrine: design stack loads paired with first Read; census order-locked by line number;lib/effort-audit.pyprints thinking coverage. - Why: user rungs (low fix-a-line · medium day-to-day · high refactor/resisting bug · xhigh architecture/audit · max stuck). Latest version of each tier = cheapest or same price (Sonnet 5.5 = Sonnet 5, Opus 5.5 < Opus 5, Haiku 4.5 alone, Fable 5.1 = Fable 5) → no version arbitration, only tier × effort. Stacked skills: last loaded wins → two levels in a stack = effort depends on load order. Aliases track generation free (transcripts:
sonnet→ sonnet-5 then sonnet-5-5). - Alternatives rejected: full model IDs in frontmatter (maintenance, Agent-tool call site enum cannot pin a version, older gen never cheaper); hotfix → medium (no A/B on a reflection skill yet, EVAL-036); design stack medium; untrack design-motion-principles (only tracked external, gated in contract instead); pins on gstack / impeccable / graphify / find-docs / darwin (machine-owned, BDR-107).
- Gates: GATE 0 MET; verifier ECARTS(3): resync re-apply sat BEFORE the 21st refresh (real, fixed by fresh executor), tracked file out of scope (gated), shellcheck directive unauthorized (clarified) → CONFORME 7/7; security PASS + 4 LOW hardened (criteria 8-9);
make test44 suites rc 0. - Refs: contract
.claude/tasks/contracts/2026-09-29-effort-round-1315.md, BDR-107, BDR-077, LRN-181, LRN-182, BLK-024, EVAL-038.
BDR-109 — Higgsfield pack: npm CLI + cloned skills, OFF by default, two toggles, allowlist [accepted] (2026-09-30)
- Decision:
@higgsfield/cli(latest) installed by install-plugins.sh Step 8.6. 8 upstream skills git-cloned (higgsfield-ai/skills, tracks main, no pin) bylib/higgsfield-skills.shinto gitignoredskills-external/higgsfield-*; refreshed by update-all.sh 7.3b (npm only whennpm ls -gowns the CLI). Twotoggle-external.shtools, both off, in no profile, not in MANAGED_EXTERNALS, not in link.sh:higgsfield= allowlistHIGGSFIELD_MEDIA_SKILLS(7 names),higgsfield-websites= 1 skill, landing-page aid inside Design work, neverhiggsfield website create|deploy|publish. CLAUDE.global.md Skill routing (6 lines, 312/320): explicit ask → enable toggle → Read skill;higgsfield generate costbefore paid run. CLI presence =higgsfield_cli_okprobe, nevercommand -v. doctor: pass/info only. settings.json deny +=npm i -g,npm install --global,npm i --global. - Why: media generation occasional + metered → parked pack costs 0 (8 descriptions ≈ 1.7k tok when linked). websites skill triggers on "landing page", collides with Design work stack, Astro rule, no-deploy doctrine → own toggle, named ask only. Upstream unpinned → allowlist = default deny on added/renamed skills.
- Alternatives rejected:
npx skills add(relinks all 8 into skills/ on every refresh, breaks off-by-default);creativeprofile (profile applyoverwrites the active label, nextmake pluginruns exclusiveset, parks the design stack);+creativeprofile modifier (parser + statusline + census for a label); commit pin (user: track main like 21st; security gate reports 2 MEDIUM, accepted); glob "every higgsfield-* except websites" (renamed upstream skill linked with no review). - Gates: plan challenge 3 lenses + 1 confirmation, 0 BLOCKER, 7 MAJOR closed by named changes; SDD 7 tasks (sonnet), 1 fix round; GATE 0 MET; verifier ECARTS(6) (2 shellcheck suppressions of mine + 4 plan copies) → CONFORME 14/14, again CONFORME after the fix wave; security PASS ×2; final review (opus): 1 Important (drift never reported once enabled) + 5 minors fixed in one wave, 3 deferred with rulings;
make test45 suites rc 0. - Refs: contract
.claude/tasks/contracts/2026-09-30-higgsfield-pack-1412.md, commits 3dad33e..5350221 (feature/higgsfield-pack), BDR-093, BDR-079, BDR-108, LRN-183, LRN-184, LRN-185, LRN-186, LRN-187, LRN-188, BLK-025, EVAL-039. - Status (2026-11-16): accepted, amended by BDR-134: two toggle-external toggles -> pack-higgsfield (profile.sh enable higgsfield), websites skill inside it, pack ON in max only; npm CLI unchanged
BDR-110 — Shell portability: native userland both OS, census on deterministic idioms [accepted] (2026-10-06)
- Decision: every tracked
*.sh+ hook runs on BSD (macOS) and GNU userland as installed. Portable forms: producer captured out of| grep -qpipelines under pipefail (grep -q PAT < <(cmd)tests,if grep -q PAT <<<"$(cmd 2>&1)"prod);sed -i.baktests, temp-sibling copy on user dotfiles;wc -l | tr -d ' '; python3 for perms;touch -t;realpath -memulated (refuses..);perl -e 'alarm shift; exec @ARGV'for bounds;sed -nnotgrep -P;/usr/bin/greppin (LRN-074).lib/tests/portability-census.test.shgreps tracked shell forsed -ino-suffix,stat -c,realpath -m,touch -d,grep -P, bare/bin/grep; file:line allowlist with reason; NOgrep -qrule (not decidable by text, fix structural). - Why: suite built on Ubuntu, repo now also lives on macOS. 13 suites red here; 7 prod scripts broken silently (update-all plugin list empty, design gate UNVERIFIED, gstack write-guard dead). Brew GNU on PATH rejected: brew dependency + two behaviours by PATH.
- Alternatives rejected: prepend coreutils/gnu-sed to PATH in Makefile+hooks;
grep X >/dev/null(GNU grep treats /dev/null stdout like-q, race stays); broad| grep -qcensus (119 hits, fixtures, false confidence). - Gates: 3 lenses (FATAL 6 / CONCERNS 4 / FATAL 2) + confirmation CONCERNS(2), all closed r3; GATE 0 MET 8/8 ×2; verifier CONFORME 9/9; security PASS (1 MEDIUM hardened). Linux run
[deferred]. - Refs: contract
.claude/tasks/contracts/2026-10-06-macos-portability-1105.md, plan.claude/tasks/plans/2026-10-06-macos-portability-1030.md, commit0efdff0(bugfix/macos-portability), BLK-026, LRN-189, LRN-190.
BDR-111 — Manual-push mode = gitflow.autopush false end to end, no new key [accepted] (2026-10-06)
- Decision: user need (work machine): same flow, branches + commits + local merges, nothing pushed, push only by hand. Reuse existing human-set
gitflow.autopush(static deny ongit config gitflow.*), nogitflow.mode. Run A: lib_gitflow_push_offsingle reader forstart/finish/delete_remote;gitflow_deletechecks out CONTAINING base +--unset-upstreambefore-d;_gitflow_sync_basewarns "behind origin, cannot fast-forward" instead of silent|| true;unpushed-guardsilent at Stop, oneℹ manual push mode:SessionStart line counting ALL local branches; doctrine line CLAUDE.global.md. Run B (queued): PreToolUsehooks/push-guard.shdeniesgit pushwhen autopush=false (user: block,! git pushonly), widengitflow.*deny (git config * gitflow.*,git -c,GIT_CONFIG_COUNT=), settings prose, banner, fail-CLOSED on unparseable value in every reader at once. Run C (queued): skills that push alone (/capitalizeSTEP 5Cgit push origin develop, client-handover, release-candidate/tour claims). ORDER: no autopush=false at work before B+C. - Why:
autopush falsealready silenced hooks + remote delete; lib push sites ignored it (bug). Merge is NOT the user's concern (local merge wanted), push is. Fail-open on invalid value kept in A for consistency with untouched hook emitters (AC7). - Alternatives rejected: new
gitflow.mode auto|manual(duplicates autopush); tty-only lock onfinish(user wants local merges);-Dafter ancestor gate (statically denied form, reviewers' red flag); fail-closed in lib only (hooks would still push → inconsistent). - Gates: 3 lenses CONCERNS(1/2/2) + confirmation FATAL(4) → r2 fixes (T22j containing base,
-ufixture, T18n before T18l); feater ×2; GATE 0 7/8 (AC6 = env red); verifier ECARTS(1) = AC6 only; security PASS ×2 (1 MEDIUM fail-open → run B). - Refs: contract
.claude/tasks/contracts/2026-10-06-manual-push-mode-1632.md, plan.claude/tasks/plans/2026-10-06-manual-push-mode-1632.md, commit2fc8830(feature/manual-push-mode, UNMERGED). Extends BDR-095 (c); LRN-161, LRN-191, LRN-192, LRN-193, BLK-022.
BDR-112 — push-guard: text-only PreToolUse deny of Claude's git push in manual-push mode, fail closed [accepted] (2026-10-07)
- Decision: run B of BDR-111.
hooks/push-guard.sh(own PreToolUse groupBash|Monitor, timeout 10) readstool_input.command+cwd; folds\-newline in bash (BSD sed unsafe, LRN-195); three ERE matches on/usr/bin/grep: STRICT (git +-opt [arg]* + push|send-pack, boundaries[^[:alnum:]_.-]/[^[:alnum:]_-]), LOOSE on quote-stripped text (any laterpushword in the same simple command), ALIAS (alias.x=…push). Candidate dirs = cwd + literal-C/cd/pushdtokens (quotes stripped, never eval/expand), dedupsort -u, >20 distinct → deny before any fork. Mode per dir viagit config --bool gitflow.autopushrc: 0 → value, 1 → auto, else → deny; NO work-tree gate (global key = work-machine deployment). Deny = JSONpermissionDecision=denyexit 0, reason carries! <cmd>; EXIT trap emits static deny +exit 0once a push is detected and nothing decided; jq missing → stderr + allow (sibling policy). User gated: fail-closed cases (cap, unenterable dir, git failure) fire in auto mode too. settings.json: 18 deny entries on WRITE forms ofgitflow.*(anygit … configspelling, remove/rename-section,-c, config env overrides, Edit/Write of git config files); soft_deny "pushing in manual-push mode, any form, no per-turn clearance"; routing-around hard_deny names hook refusals; banner🔒 push : manual (autopush=false) — ! git push(%-46s, bytes). - Why:
askinert under auto (LRN-155);hooks/guard-bash.shwithheld (BLK-022) → one narrow rule instead. Trailing*glob matches end-of-string (LRN-194) → no infix rule spares the bare read → Claude losesgit config … gitflow.autopush; hooks/lib keep it; run C getsgitflow.sh push-mode. Text-only guard cannot see scripts/aliases → soft_deny is the declared backstop. - Alternatives rejected: no-jq fallback (greps whole payload, denies in auto, untestable without shim; jq hard dep);
-Cdir unresolvable → allow (fail-open; now skipped, cwd still checked);rev-parsework-tree gate (drops the global key);--default trueread (hides git failure); narrowing deny to spare the read (impossible with end-matching globs). - Gates: 3 lenses CONCERNS(2)/CONCERNS(5)/FATAL(7) + confirmation FATAL(8) → r2 (BSD sed, oracle naming denied tokens, read loss); feater ×3 (58 → 61 → 71 checks); GATE 0 MET ×3; verifier CONFORME, then ECARTS(1) on hardening closed by gated clarification; security PASS ×2 (3 MEDIUM closed: 20k-token flood denied in 0.15 s, git absent → deny,
bash -c 'cd … && git push'extracted; residuals → run D). - Refs: contract
.claude/tasks/contracts/2026-10-07-manual-push-guard-1003.md, plan.claude/tasks/plans/2026-10-07-manual-push-guard-1003.md, commitsa2ac018+6468eda(feature/manual-push-mode, UNMERGED). Links BDR-095, BDR-100, LRN-069, LRN-196. - Amendment 2026-10-07: user probe done on their machine (
autopush=falserepo): no auto push, the bang-prefixed dry-run passes →!commands bypass the PreToolUse guard, design confirmed. Dotfiles installer will prompt for the key (default false) and carrycore.hooksPathin the gitconfig template.
BDR-113 — Skills never push; truth from rev-list facts, mode verb only words the reason [accepted] (2026-10-07)
- Decision: run C of BDR-111. New lib verb
gitflow.sh push-mode(stdoutauto|manual|invalid, rc 0, raw value on stderr, printable ≤64 chars; ignores GITFLOW_NO_PUSH) = the one reader skills may call (baregit config … gitflow.*denied, BDR-112). Skills push NOTHING on their own except the release tag in auto mode on explicit go. Every "on origin / not pushed" line comes fromgit rev-list --count origin/<br>..<br>(or<br> --not --remotes=originfor the tour) read AFTER the action, in its own Bash call; the verb only words the reason (manual vs push FAILED vs invalid). Removed as redundant since BDR-095:/closeSTEP 5Cgit push origin develop(finish pushes develop itself, mode-aware since run A) and/client-handover's "Push to origin now?" question + push block (hooks had pushed; push-guard denies in manual). User hints are complete! git …commands (-u,--atomic origin main develop vX,-C <abs project>), branch name allowlisted^[A-Za-z0-9._/][A-Za-z0-9._/-]*$before any interpolation./release-candidatemanual/invalid or any count ≠ 0 → one user command, STOP, no question; tag gate kept for auto with both counts 0./tour: one-Cfact per project after the report commit, suffix-aware branch name, summary rowon origin | local only → cmd. - Why: a shell gate
[ "$mode" = auto ] && git push …is denied WHOLE by the text-only push-guard and$modedies between Bash calls (LRN-199); the push it gated was redundant anyway (LRN-197); invalid value: lib/hooks still push (fail-open until run D) so "not pushed" from the mode word would lie — the count tells the truth. - Alternatives rejected: gate the existing push on the verb (denied/stateless); keep the GO question (gated nothing); word invalid as manual (false in the lib); per-skill
git configread (denied). - Gates: C1: 3 lenses (1 BLOCKER: shell gate) + confirm CONCERNS(3); feater; GATE 0 MET; verifier CONFORME; security PASS. C2: 3 lenses (BLOCKER: deploy brief said "push done") + confirm CONCERNS(4); feater; verifier CONFORME; security BLOCK(1) branch-name injection (LRN-198) → fixed → CONFORME + PASS. Polish pass: CONFORME + PASS.
- Refs: contracts
.claude/tasks/contracts/2026-10-07-manual-push-skills-c1-1304.md,…-c2-1325.md; plans same slugs; commits5cf049d,6104545,3881f46(feature/manual-push-mode, UNMERGED). Links BDR-068, BDR-095, BDR-042, LRN-069.
BDR-114 — Every gitflow.autopush reader fails closed and names the stop; the lib verb is the single reader [accepted] (2026-10-07)
- Decision: run D of BDR-111. Rule for every reader: unset or
true→ auto (push);false→ manual (no push, silent); anything else (unparseable value, corrupt config, git failure) → NO push and one named line. Readers: lib_gitflow_push_off=[ "$(gitflow_push_mode)" != auto ](verb stderr passes through); emitted post-commit/post-merge hooks (standalone POSIX sh, mirror of the verb:case "$rc:$v" in 0:true|1:*) ;; 0:false) exit 0 ;; *) echo "… NOT pushed, treated as manual push mode" >&2; exit 0 ;; esac); unpushed-guard, session-start banner (autopush badlock line) and push-guard (sources the lib once,gitflow_push_modeper candidate) all read the verb. push-guard residuals: whole-word dir tokens (mixed quoting → deny; fully quoted + inner other-quote and\escapes resolved), payload jq cannot parse → raw scan with JSON escapes folded → static deny, cap BEFORE any per-token fork, T42 base = main. Skill prose: invalid outcome split on the ahead count (0 → "pushed anyway, likely a stale fail-open hook or a manual push"), labels COMMIT + PUSH STATE READ, release-executor version format check by reading. Doctrine: invalid = manual; "never pushes, even when asked". - Why:
--bool --default truecovers a MISSING key only; a typo re-enabled every push silently (the 21-09 hazard class on a work machine). The user chose fail-closed for the guard in run B; D extends it everywhere and keeps a terminal signal (git's own "fatal: bad boolean" used to be the only one; the hooks now print theirs). - Alternatives rejected: regen via
install-hook(writes a LOCAL hooks-path entry) orglobal-hooks(writes the GLOBAL config when the value is missing — it was, LRN-200) →emit-hook > fileonly; temp file for the verb's stderr in a hook (fail-open on a full TMPDIR, predictable path) →2>&1capture (LRN-202); classification before the token cap (13 s flood) → cap first (LRN-201); shell check of the release version string (interpolation sink) → by reading. - Gates: D1 3 lenses + confirm FATAL(1) (global-config write) → emit-hook; feater; GATE 0 MET; verifier CONFORME; security PASS. D2 3 lenses + confirm FATAL(3) (escape alternative, same-quote-inside,
bare=$onewhen unparsed); feater; GATE 0 MET; verifier CONFORME; security BLOCK(1) cap-after-fork → fixed (20k tokens 0.13 s) → CONFORME + PASS. D3 3 lenses + confirm CONCERNS(3); feater; CONFORME + PASS. - Refs: contracts/plans
2026-10-07-manual-push-failclosed-d1-1522,…-guard-residuals-d2-1526,…-prose-d3-1530; commits472cccb,3c59333,64ca0f8(feature/manual-push-mode, UNMERGED). Supersedes the "fail-open on invalid value" line of BDR-111. Links BDR-112, BDR-113, LRN-114, LRN-196. Residuals: TODO "post-run-D residuals" (soft_deny names onlyfalse; stale.githooks/in onboarded repos until reconcile).
BDR-115 — model-router mod: pin = entry default, sub-tasks route finer; one writer per axis; full ids; built-ins-only table until pins go [accepted] (2026-10-08)
- Decision: one function-hooks mod (
mods/model-router/) routes model + effort per request. Rules: (1) a skill/agent pin = DEFAULT route of the run, never ceiling/floor; inside the run every sub-task routes to its phase, declared (routetool,/route,ultrathink) or derived (skill load, agent dispatch). (2) ONE writer per axis:Skill(effort-*)answered by the mod WITHOUT loading the skill (no pairing rule, no doublon); every write lands on the CALLING loop; explicit Agent params frozen per loop for the whole run; agent model written once at spawn. (3) hooks write FULL ids fromconfig.models(LRN-203). (4) wave 1 agents table = built-ins only (Explore sonnet/medium, Plan opus/xhigh); repo agents keep frontmatter as single writer until wave 2 moves pins into the table and deletes frontmatter + shifters + effort-pins + model-gate. (5) precedence: user/routesticky > latest turn route (one slot, last writer wins; non-effort skill load resets it except a prompt rule) > session. (6) main-loop model switch behindmainModelSwitch(default off) + context-window guard (LRN-204). (7) state inregisterclosure, defaults cloned,/route offkill switch, config validated before merge. Load:CLAUDE_CODE_PLUGIN_DIRSin settings env via link.sh (wave 1-B). - Why: user 2026-10-08: existing pins +
effort-*shifters built for this goal with older tools; some pins forced (one level for a skill doing many things). Mods exposeturn.stepmodel/effort rewrite +agent.spawn+tool.callanswers = cleaner, unified, automatic, works headless too (BDR-107 gap). - Alternatives rejected: agents table copying the 21 frontmatter pins in wave 1 (third source of truth, silent override of a frontmatter edit);
scope: agents//route agentsbulk lever (no requirement, sixth precedence tier);modelparam on the model-facing tool (typo → LRN-203 404 class); per-step agent model rewrite (fights engine fallback, beat explicit params);userConfig(one config file instead); marketplace install (live symlink repo model);source-dependent skill-load reset (kept stale shifts). - Gates: plan r1 → r3 through 3 challengers + 1 confirmation (2 BLOCKER + 10 MAJOR closed, EVAL-040); feater DONE first pass; GATE 0 MET; verifier CONFORME 6/6; security PASS + hardening round (criteria 7-11).
- Refs: plan
.claude/tasks/plans/2026-10-08-model-router-mod.md, contract.claude/tasks/contracts/2026-10-08-model-router-w1a-1533.md, BDR-107, BDR-108, BLK-029, LRN-205, LRN-206. - Amendment (2026-10-09, user decisions 2026-10-08 evening): (a) LOAD supersedes the "Load:" line: tracked relative symlink
skills/model-router→../mods/model-router, loaded in place asmodel-router@skills-dirwherever link.sh links~/.claude/skills;CLAUDE_CODE_PLUGIN_DIRSdropped (absolute path, settingsenvhas no$HOMEexpansion, settings.json tracked), local marketplace dropped (addwrites an absolute path into settings.json). Proven by fresh-processclaude plugin list --json. (b) PRECEDENCE amended:ultrathinkand a typed/effort-<l>are the main turn's DEFAULT and MINIMUM (floor slotturnFloor): sticky/routeeffort > turn route effort > floor > engine, then floored; per axis; mid-turn prompt floors the running turn and the next (waitignored). Rationale: user "un choix explicite bat la phase déduite"; a pure floor made/effort-lowa no-op (challenge finding). (c) Per-machine kill switch"enabled": falsein the untracked~/.claude/model-router.json(survives/clear, a failed reload keeps the previous config);enabledPluginswould dirty the tracked settings.json on every machine. (d) Hardening:/routecomposer-only; agent loops effort-only (model fixed at spawn); config caps; typed slash attested atprompt.submit. Commits346d6ae,1ff608a, 6430ac6; contracts2026-10-08-model-router-floor-1835,2026-10-08-model-router-wiring-1835; residuals parked in TODO. - Amendment 2 (2026-10-10, wave 2 closed, commits
bb56f3e+1f2d33b): (a) rule 4 closed: rows for every repo skill (56) + agent (21) + Explore/Plan, PHASES by role (plan/reflect/orchestrate/escalate best · judge big · implement/write/verify/explore/apply work · mechanical cheap;writework/high +applywork/low added). User: pins "deleted or reworked", not copied → rows are the live source, trackedmodel:/effort:frontmatter KEPT as off-state floor, census-locked equal to rows (lib/tests/effort-routing.test.sh). Robustness BLOCKER closed: mod off → agents would inherit parent model. (b) Rule 5 amended: unrowed skill load changes nothing; best-tier skill row lives inrunMainslot surviving turn end (precedence userMain > turnMain > runMain > floor > engine), dropped by/route clear,/route off, user/model, typed non-best skill; turn writers (route tool, prompt rules) never touch it. (c) Agents: model written at spawn WITHIN tier, upward only (never below frontmatter alias); explicit Agent params win; project-defined agent (agent.offer source projectSettings|localSettings) skipped. (d) Typed slash: name-bound marker at prompt.submit (composer|sdk|bridge) + pending slot + idle fallback (no live/spawning loop). (e) Shifterseffort-*,effort-pins.*,model-check.shDELETED; orchestrators callmcp__model-router__routeper phase; gate witness = route answer id, remedy/route on; builtin/effortnot a lever inside a run (leversultrathink,/route effort=max). (f) SemVer: typed/effort-*removal = breaking → next release 3.0.0. Plan.claude/tasks/plans/2026-10-09-model-router-w2-1546.mdr4, contracts2026-10-09-model-router-w2a-1546,2026-10-10-model-router-w2b-1045. Links LRN-210, LRN-211, EVAL-042.
BDR-116 — model-router first-use confirmation: tracked routing.json = source of phases, rows and decisions; engine dialog once per row/phase; project exceptions in user scope; model never writes [accepted] (2026-10-11)
-
Decision: (1)
mods/model-router/routing.json(tracked, reached from every project through the plugin dir$.plugin.root= the existing~/.claude/skills/model-routerlink) is the single source: 11 phases (full routes), 56 skill rows, 23 agent rows,confirmed(kind/name → phase),changed(from/to for an Everywhere change),projects[<key>]exceptions,ask.DEFAULT_CONFIGkeeps only the phases as fallback; rows{}. (2) First use of a rowed typed skill (T1), a rowed agent spawn with no explicit model (T2) or a main-loop phase declared via the route tool (T3) opens$.ui.ask: options Later / Keep / 2 alt phases (Other = phase name; T3 Later/Keep); a change asks Everywhere (row moved +changed) or This project only (projects[key], confirmed = base row so no other project asks). Keep endorses the phase too. One dialog in flight; concurrent uses route unasked; headless/dismissed/garbage = Later; never inside a sub-agent; pre-ask re-read of the file (other sessions' decisions seen). (3) Project key = origin remote normalized (new URLhost+path or strict scp regex; userinfo never read; any remaining@/:/empty host → no key); nolocal:path keys; no remote → Everywhere/Later only. The project tree's.claude/model-router.jsonis NEVER read (a cloned repo must not re-route the user's gate agents). (4) Writers = dialog answers + composer/route ask on|offonly; serialized chain; output capped 64 KB; file never created; later unreadable → previous config kept (kill-switch rule); layers routing.json <~/.claude/model-router.json(itsaskwins). (5) Census reads rows + phases from the file, locks DEFAULT phases == file, tolerates a drift only for achangedrow whose frontmatter ==fromand row ==to(WARN); Keep-only drift still FAILs. (6)/route pending,/route ask on|off;set/confirm/show suffix deferred. -
Why: user 2026-10-10: see in practice whether routing fits ("prompt qui demande de confirmer… mémoire de ce qu'on décide… met à jour la table… exception pour ce projet… persistant sur tous les projets, se redéploie comme le mod"). Tracked file = deploys with the mod via git; user-scope exceptions = security (robustness lens: project-tree layer let a cloned repo downgrade security-auditor to haiku).
-
Alternatives rejected:
$.store(machine-local, re-asks per machine); project file in the tree (security hole + writes into worktrees); shared-promise dedupe for parallel spawns (hook budget: awaiters time out);confirmeddates (git log dates them); dialog edits of phases (blast radius: a phase is shared by many rows); per-layer degrade after first load (one transient read failure wiped 79 rows + the kill switch);local:<realpath>keys (home path in a tracked file). -
Gates: plan r1 → r4 (simplicity CONCERNS(3), correctness FATAL(8) with the census BLOCKER, robustness CONCERNS(8) after a network-killed first run, confirmation CONCERNS(6)); feater DONE + 4 rounds; GATE 0 MET; verifier ECARTS(3)/(2) → CONFORME, re-verify after security ECARTS(1) → fixtures; security BLOCK(1) real (password with
@//stored in the key) → fixed, PASS. Kit 86 → 190 tests. Live T2 dialogs answered by the user from the hot-loaded working-tree mod (LRN-212). -
Refs: contract
.claude/tasks/contracts/2026-10-10-model-router-w3a-confirm-1201.md, plan.claude/tasks/plans/2026-10-10-model-router-w3a-confirm-1201.md, commit22455c0, BDR-115, LRN-210, LRN-211, EVAL-043. -
Amendment (2026-10-11, wave 3-B, commit
604a6c4): clause (2) superseded: the dialog carries CONTEXT (skill description = first sentence of its SKILL.md frontmatter, five YAML forms, hardened read: name allowlist, stat kind file, size cap,clean()Cc/Cf + code points; agent description fromagent.offer, bounded cache; phaseaboutline, new 120-char field on the 11 routing.json phases, kept in memory not on Route) and the REAL next model id + effort. Options Later / Keep / Change (T3 Later / Keep). Change = model (4 fixed alias labels with tier role) → effort among those the phases headed by that alias offer (ascending, ≤ 4, one → skipped, zero → Later) → scope; the pair maps to an existing PHASE (rows stay phase names; row's current phase wins a tie; same phase = Keep); a pair no phase offers = a new phase by hand. Other anywhere = Later + toast (no echo). A main-row change toasts the real decision +/route switch onhint on a held downgrade. Three lenses rejected inline-route rows and dialog phase edits (2 BLOCKERs). First real use: user moved security-auditor tojudge(opus/xhigh) through it; floor aligned (model: opus, 2026-10-11). Links EVAL-044. -
Amendment (2026-10-11, wave 3-C, commit
cd8d72f): clause (6) extended:/route forget <name|all|projects>(composer only) clears decisions in the tracked file through the same writer: a name in every table (confirmed,changed→ row restored to its recordedfromwhen it is a string, the row still equalstoandfromis a known phase;projects[*]pruned), asked again at once;all/projectsconfirm through the engine dialog (Cancel first, anything else = cancelled) and hold the single-dialog slot; nothing written when nothing to forget; the answer names a restored row's file + values to realign (a floor aligned to the decision makes the census FAIL after the restore). No per-user decisions file (user: "seulement le forget"): another user inherits the shared memory and may forget. Residuals (security LOW/MEDIUM): raw error text in the answer, file fragments unsanitized in the answer,floorFilename not allowlisted,__proto__plan/apply mismatch,changed.phasesrestorable. Links EVAL-044. -
Amendment (2026-10-11, wave 4-A, commit
68d7ea6): logging rule:verbose(boolean) logs TRANSITIONS only, built from the decision itself insidesafelybeforenext: main "fable/high → fable/xhigh (: [, ])" once per turn per transition (causes: skill /, route tool, prompt rule, prompt floor, dispatch, sticky /route, session; model: upgrade, switch, fallback: down); one hand-off line per agent dispatch deduped per turn per (type, target) "main … → agent / (row |explicit|fallback|frontmatter, row|explicit|engine)"; later agent effort moves; an answered-by anomaly (agents only, canonical ids, once per agent+model). The host prefixes the plugin name: new lines carry none. The four stream lines are gone. Residuals W3-A/B/C closed: failure texts to the log, file fragments cleaned at render, floorFile allowlisted,__proto__refused, changed scan = rows, dialog Change offers shipped phases only (mem.filePhases= validated seed layer), post-answer write failure keeps the key asked. Rejected: atracelevel (unrequested surface); detecting agent moves at turn.step (decided at spawn). Links EVAL-044. -
Amendment (2026-10-11, wave 4-B, commit
e54a2b5): prompt classifier closes the main-loop gap (plain prompt, no skill, no agent, no route in force). Composerprompt.submit, trimmed text ≥ 12 chars not starting with/, no prompt rule matched, no sticky/turn/run/floor route → one$.model.classify(sample, [design, analysis, coding, bookkeeping, chat]), sample = whole text ≤ 2000 code points else head 500 + tail 1500, nomodeloption (engine small model). Label → phase (design→plan, analysis→reflect, coding→implement, bookkeeping→apply, chat/unknown → nothing) written as the TURN route, EFFORT ONLY (no tier: main model never moves on a guess), may lower, replaced by any later route tool call or typed skill, ignored at a step whose engine effort ≠ session baseline (engineBase: a user/effortbeats the guess). Bounded: race with$.clock.sleep(3000); timeout/rejection count, user abort neither counts nor writes, every guard re-checked after the await (a route landing meanwhile wins); 3 failures in a row → pausecooldownMinutes(×60000, kept across/clear, cleared by/route reload, one toast + status marker· classifier: paused); skipped while the haiku id is marked down or main runs on haiku. No dialog, no routing.json write on a classified route. Config keyclassify(default true,pickSwitch),/route classify on|offsession toggle surviving a rebuild,/route showclassify:field, statusroute: classifier <phase>, verbose line(<phase>: classifier). -
Why: user 2026-10-11: routing must also cover the main conversation when no skill or agent is invoked. Effort-only because a model flip on a 3-s guess would fight the breaker and the user's
/model; turn-scoped because a guess must never outlive its prompt. -
Alternatives rejected: first-use dialog on classified phases (the TODO line said so; a dialog per plain prompt is noise and the phase is already confirmed through T3); writing the guess into routing.json; classifying mid-turn or sub-agent prompts; unbounded await (robustness BLOCKER r1: the classify call sat on the critical path with no clock race);
classifyas a tracked-file writer (session toggle + config key instead). -
Gates: plan r1 → r3 (simplicity CONCERNS(4), robustness FATAL(6) BLOCKER unbounded await, correctness CONCERNS(4); confirmation robustness CONCERNS(4)); feater DONE (423) + 1 round (trim, argumentHint, repeated undefined: 428, each mutation-proven); GATE 0 MET; verifier ECARTS(2) coverage → CONFORME on #2; security PASS (0 findings; LOW accepted: pasted text can steer one turn's effort up, README says so). Abort paths judged by reading (
[gated]clarification). Residual:smallModelBusycheckscfg.models.haikuwhile classify uses the engine's default small model (mismatch only when the two differ). Live AC9 open. -
Refs: contract
.claude/tasks/contracts/2026-10-11-model-router-w4b-classifier-1858.md, plan r3 same slug. Links EVAL-045, LRN-210. -
Amendment (2026-10-13, feature/router-downgrade-cap, commit
2ce203a, user decision): W4-B "EFFORT ONLY" clause superseded. Classifier writes full phase route; main may move DOWN on a guess, never above session model (wantedModelranks vssessionModel, notcur: breaker fallback sonnet→opus, never haiku);ultrathinkfloor model beats guess.mainModelSwitchdefault true, fail-closed picker (non-boolean → off + log). Caps measure COLD READ (LRN-216):coldRead(M) = tokens − served[M].tokenswithinCACHE_TTL_MS1 h, else whole context;downgradeMaxTokens120000 (user delegated value),upgradeMaxTokens200000 same measure; served record written EVERY main step, dropped by/clear+/route reload, stale (context < record) = cold. No return bypass (warm return cheap by construction). Model-loaded helper skill inside best-tier run → effort only (belowRun). Window outgrown (haiku 200k) → back to session model./efforttyped between turns drops guess for that turn only (engineBaseper turn). Rejected: user/modelsuspends classifier (baseline moves, guess follows;/route classify offpins) — trade-off accepted; raw context-size cap (r1: refused cheap re-down to warm sonnet, forced cold fable read); engine-model return bypass (premise false after N sonnet turns). Residuals TODO 2026-10-13: unrowed agentparentModelinheritance on demoted turn,session.usagelag vs new prompt, TTL const. Gates: 3 lenses CONCERNS (10 MAJOR) → r2; confirmation FATAL(7) BLOCKER → r3; feater DONE 450 tests; verifier CONFORME 10/10 first pass; security PASS. Links LRN-216, EVAL-047, LRN-204. -
Amendment 2 (2026-10-13, same branch, commit
1be57a3, user "fix les residus"): three residuals closed. (1) Spawn pin NARROW: built-ingeneral-purposeonly (INHERITING_AGENTS+offers.source === 'built-in'), no explicit model, no row, no fork/workflow, main's own child, main BELOW session model (ranksAbove(session, turnModel)), session model ranked + up → sentsessionModelverbatim, causesession. Rejected: "no model + no row = inherits" (r1 BLOCKER ×2: frontmattermodel:invisible to the hook, would override plugin/project agents; LRN-217); anyturnModel(upgrade would drag agents down). (2) Prompt estimate:ceil(codePoints/3)of text +context+ main's TYPED skill body, summed, first baseline kept; purewithEstimatein sharedreadingFor+mainPlan(texts = step);noteServedRAW (inflated record would trip compaction path); consumed at first main step of its turn; mid-turn →pendingEstimatenext turn;documentattachment → unknown → blocked. (3) TTL:cacheTtlMsfrom engine enum'5m'|'1h'on main's PostModelSwitch (agent_idevents ignored), kept across/clear, show printsttl N min. Residuals left (TODO): TTL before first switch event = 60 min assumption; hooks-below context / dropped prompt = conservative;onAutoSwitchtargets main'slastPlanfor sub-agent fallbacks (pre-existing); LIVE CHECK whetherparentModelfollows the rewrite. Gates: 3 lenses (FATAL ×2, CONCERNS) → r2, confirmation CONCERNS(3) → r3, feater DONE 472 tests, verifier CONFORME 7/7, security PASS. Links LRN-217, LRN-216.
BDR-117 — shared gstack helpers live in lib/gstack-removed.sh, not in a new lib [accepted] (2026-10-12)
- Decision: C5 /refactor 2026-10-12. profile.sh + toggle-external.sh duplicated gstack_skills + park/unpark moves. Host gstack_skills/gstack_parked_names/gstack_park/gstack_unpark in lib/gstack-removed.sh; each takes dirs as args, no caller globals; plain-statement call only (errexit, LRN-215).
- Why: only sourced file 5 fixture suites copy next to both scripts; new lib = every fixture breaks.
- Alternatives rejected: new lib/gstack-helpers.sh + patch 5 fixtures (wider diff, fixture drift risk); keep twins (3 copies drifted once already).
- Cost: file name says denylist, now hosts helpers; header comment states it.
- Refs: commit
8444661. Links LRN-215, EVAL-046.
BDR-118 — Rust default language, always-on rule file [accepted] (2026-10-12)
- Decision: user rule, new project / from scratch / whole-project rewrite → Rust unless other language shows gain (features, security, perf, reliability, maintainability). Lives in
rules/default-language.mdWITHOUTpaths:(always-on), CLAUDE.global.md at 317/320 → BDR-085 exception path. - Scope cut: module refactor or feature inside existing codebase keeps codebase language. "Rust slower to write" alone not a gain; throwaway script is.
- 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.profileGATE-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. - Why: impeccable 4.6 craft-floor + new-work carry frontend-design's anti-default list (eyebrow, numbering, identical cards, hero metric, cream/serif, scattered motion) and add direction roll, 61 deterministic rules, fresh reviewer, PRODUCT.md/DESIGN.md. Gate blocked on frontend-design (likely source of install prompt seen in another project, not traced). 2026-07-05 "complementary, keep both" call assumed frontend-design kept aesthetic direction; no longer true. Skill dist drifts untracked (pin = CLI only).
- Gaps accepted: tells only frontend-design names: middle-dot meta strings, arrow on buttons, short ALL-CAPS labels, tinted near-black. impeccable heavier: ~79k chars, init interview, mandatory seed roll on new world.
- Alternatives rejected: both in gate (conflict: frontend-design lets brief earn an eyebrow, impeccable bans it); uninstall frontend-design (loses light path); impeccable non-blocking (gate stays blind to the main tool).
- Residual: model-router has no impeccable row (frontend-design =
reflect); census test pins the table, own change. - Refs: branch chore/impeccable-build-path. Supersedes TODO 2026-07-05 call (no BDR). Links BDR-094 BDR-025 BDR-105.
BDR-120 — Secure-by-default guardrails: always-on rule + /guardrails scanner [accepted] (2026-10-18)
- Decision: 5 domains (hosting, a11y, Supabase, SMS/email, cloud functions) + API/access hygiene = baseline every project. Rule
rules/secure-by-default.mdalways-on, nopaths:(CLAUDE.global.md at 320/320, BDR-085 path)./guardrails= stdlib py scanner (skills/guardrails/scripts/scan.py, FAIL/WARN/MANUAL, exit 1 on FAIL, read-only, never runs project code) + judgment +.claude/audits/GUARDRAILS.md. security-auditor gate runsapi,supabase; FAIL → HIGH, secret/service_role/password-plaintext → CRITICAL. Passwords folded into api domain on user question, not sixth domain: same gate, same CRITICAL path. - 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 =--baselinevs pre-fix scan (GUARDRAILS-NO-NEW). 2 rounds max, residuals open.--report-onlykeeps audit alone. - Why: user ask. Proof by deterministic scanner, never executor's word; no new circuit to maintain.
- Alternatives rejected: guardrails edits code itself (skips fresh gates); chain to /bugfix per finding (one interview + contract per hit, too heavy for 60 labels); LLM verifier as sole proof (verdict without execution).
- Refs: feature/secure-by-default
73c25d7. Links BDR-120.
BDR-122 — Guardrails split: /a11y standalone on the shared scan engine, injection + exposure domains, exposure proven live by the read-only probe [accepted] (2026-10-19)
- Decision: a11y out of /guardrails →
skills/a11y(own SKILL, Tab-only walk, report.claude/audits/A11Y.md, fix loop = bugfixer + verify-secure gates, scanner oracle A11Y-CLEAR / A11Y-NO-NEW). Shared engineskills/guardrails/scripts/scanner.pyCatalogue(name, domains, rule_domains, manual_rules), marker = name upper; a11yscan.pyloads it viaimportlib.import_moduleaftersys.pathinsert (no noqa). Guardrails = 7 domains: api, hosting, supabase, messaging, functions, injection (INJ-, 6 rules), exposure (EXP-, 9 rules).rules/secure-by-default.mdsix numbered domains; a11y doctrine → lazyrules/a11y.md(paths:globs),rules/web-building.mdpoints at it. Probe exposure block sourcemap / error-body / fields: fail-closed (unobserved = SKIPPED or ERROR, never CLOSED), every plan path starts with/, same scheme+host only, production build target (dev-server OPEN = dev artefact). security-auditor gate keeps--domain api,supabase. INJ-SQL-RAW-UNSAFE = WARN (variable ≠ proof), INJ-SQL-CONCAT = FAIL. - Why: user ask 2026-10-18 (keyboard/alt/labels as own skill; SQL/DB injection; browser-visible info). One engine = one CLI contract, two catalogues, no drift. Lazy a11y rule keeps CLAUDE.global.md at 320.
- Alternatives rejected: a11y as a
--domainflag only (user wanted own report + walk); engine copied into skills/a11y (two CLIs drift); exposure probe against dev server (dev artefacts = false OPEN); semgrep-only (blind to live responses, policies). - Refs: branch feature/a11y-split-inj-exp, contract
.claude/tasks/contracts/2026-10-18-guardrails-a11y-split-inj-exp-2210.md; spec + plan purged at finish (git show 988038c:docs/superpowers/...). Supersedes the domain list of BDR-120; links BDR-121.
BDR-123 — Routing policy: opus session, Fable via rows for orchestrator reflection + merge gates, sonnet writes, ceiling on Fable main [accepted] (2026-10-21)
- Decision: user policy 2026-10-19.
settings.jsonsession modelopus; model-router best-tier rows lift main to Fable for reflection ONLY (brainstorm, plan, contract, audit judgment, loop decisions). Fresh gates (verifier, security-auditor) =auditphase best/xhigh, frontmatter flooropus(LRN-224). Other judges (plan-challenger, analyzer, code review) opus. Executors sonnet; "what to write" (plan, diagnosis, contract) opus. Doctrine ceiling (CLAUDE.global.md Sub-agents rule): main on Fable writes no code past/hotfixscope, hands it to/feator/bugfix. Supersedes BDR-066 "reflection inline on session model (Fable)" + "verifier + security-auditor stay sonnet"; amends BDR-115 "pin = never ceiling" (agent pins unchanged, ceiling lives in doctrine on main writing code). - Why: BLK-032: session on Fable 1M + downgrade cap 120k + keyword
planrule → long sessions wrote code inline on Fable xhigh. Fable reserved for big reflection + important audits, rest opus/sonnet. - Alternatives rejected: fable frontmatter on gates (dead model in credit outage, LRN-224); general-purpose dispatch for small writes (inherits Fable); CLAUDE.global.md budget raise over 320 (bullet compacted instead).
- [deferred] inline-writing best-tier skills = declared exception, visible in this repo only: design Build stack (frontend-design, 21st-ui-build, emil-design-eng, design-motion-principles Create, site-motion, build-threejs-scroll-worlds, scroll-*, 21st-ai), writing-skills, deprecation-and-migration, /tour single-project, /audit-delta STEP 3d, /harden STEP 3. Remap = own task (TODO).
- Known gaps: default keyword prompt rules (plan|design|architecture, why|review|audit|analyze, ultrathink) lift main to Fable unwitnessed → feat C caps them at session model; Fable held down → opus stand-in, ceiling does not bind; stale "session model" citers
skills/feat/SKILL.md:6,skills/code-clean/SKILL.md:36. - Refs: feat A feature/routing-audit-phase
d3635b6a7d747cdae142b; feat B feature/routing-ceiling-ruleef13713887cf89, contract.claude/tasks/contracts/2026-10-21-routing-ceiling-rule-1753.md, plan.claude/tasks/plans/2026-10-21-routing-ceiling-rule-1753.md. Links BDR-066 BDR-115 BLK-032 LRN-224. - Amendment (2026-10-23, feat C
786ee13+ docsd2d590f): keyword-lift gap CLOSED: prompt rules (keywords,ultrathink, user rules) + derivedorchestrateon main Agent dispatch (user pick 2026-10-23) write effort-only routes; model axis falls through to held run or stays on cur. Amends BDR-115 amendment 2026-10-13 clause "ultrathink floor model beats guess": mid-turn ultrathink after classifier demotion keeps guessed model that turn (floor raises effort only). Accepted edges: haiku session → keywords no-op; session model held → keyword turn = plain-turn fallback (sonnet), not fable; no stand-in notch on keyword/dispatch turns; dispatch after demotion orchestrates on demoted model. Rejected: cap inwantedModel(r1) → shadowed held run slot + fail-open onsessionModel'' after /reload-plugins. Contract.claude/tasks/contracts/2026-10-23-router-keyword-cap-0019.md, plan r2.1.claude/tasks/plans/2026-10-23-router-keyword-cap-0019.md. Links LRN-226, EVAL-048. - Amendment (2026-10-25, bugfix
8e93507): accepted edge "haiku session → keywords no-op" REVERSED (user pick: Haiku 5.x like any model). No-effort rule now Haiku 4.x only (NO_EFFORT = 'claude-haiku-4'); on Haiku 5.x keyword rules,ultrathink, sticky effort and derived orchestrate apply, unrouted step passes engine effort. Links BLK-035, LRN-230. - Status (2026-11-16): accepted, amended by BDR-136: ceiling model-agnostic, main loop writes no code outside a skill run on any model, held by router write guard (fail-closed since
859e504); Fable-only /hotfix-scope ceiling gone (0bf4620) - Status (2026-11-16): accepted, amended by BDR-150: no Fable via rows, opus heads best and big; session opus, Fable is the advisor
BDR-124 — Foreign code keeps its own style; limits strict in our code only [accepted] (2026-10-23)
- Decision: CLAUDE.global.md header: strict limits in our code, "Foreign code: keep its style" section wins on foreign code (granularity, layout, naming, comments, idioms; limits = guidelines; no refactor toward our norms unless asked). Origin =
lib/code-origin.sh:git config claude.origin(ours|foreign, per clone, invalid → foreign) > root commit author vsuser.email+ globalclaude.identitylist; undecidable (no git, shallow, no commit) → foreign, said. Session banner linecode : ours|foreign (reason). refactorer, /refactor, /audit-delta conformity follow it; refactorer cites CLAUDE.md limits, no copy. - Why: lima (third-party, 2009): extracted
rtnh_put_via6()for 25-line limit while neighbour branches work inline; user had to inline back reusing in-scope vars/sizeof. - Alternatives rejected: marker file committed in foreign repo (pollutes third-party tree); limits everywhere (breaks foreign style); per-file heuristics (unverifiable).
- Known gaps: "Session start" rule still creates
.claude/memory/in foreign repos (out of scope). CLAUDE.global.md now 328L > 320 warn. - Refs: chore/foreign-code-style
70e0f9a71d28f8052a7045c6e368, merge1a14265. Links LRN-227.
BDR-125 — Context mod: subtract-only JIT injection + deterministic guards; supersedes BDR-031 [accepted] (2026-10-23)
- Decision: user ask "move always-on doctrine into a mod, make it hard". Always-on context = 30.2k tok (
/context, opus, repo root): memory files 11.6k, skill listing 10k, agents 2.6k, system 2.5k, MCP instr 2.2k, tools 1.1k. Mod = (a) SUBTRACT a marked CLAUDE.md/rules section only when it can re-deliver it JIT on a deterministic trigger, (b) turn mechanically checkable rules into tool.call guards (deny + reason). Source text stays in CLAUDE.md/rules with markers: mod off or hook throws → hook skipped → full content loads as today (fail-safe). Per-turn rules (writing-style, communication, workflow core) stay always-on. - Why: BDR-031 premise dead. Proven 2026-10-23 by throwaway probe mod + fresh
claude -p --plugin-dircanaries (unique tokens + negative controls):prompt.contextdrops an instruction file (default-language ABSENT, writing-style PRESENT) and adds blocks;prompt.composeadds system section;prompt.sectiondrops one (auto-memory ABSENT);prompt.submitcontext+tool.callresultcontextinject;prompt.attachmentrewrite ofskill_listingdrops a skill (scrape ABSENT, seo PRESENT); userpaths:rules load on Read (web-security, rest-api). Facts:agent.offerfalse → agent undispatchable ("Agent type not found");command.describeisHidden = typeahead only. - Phases (each a future /ship-feature): 0 no mod: project CLAUDE.md sections → project
paths:rules, higgsfield MCP declared in ~/.claude.json while toggle disabled. 1 context mod: marked-section subtraction + JIT (design, graphify, web/SPA + API + language, secure-by-default domains by fingerprint, gitflow detail, registry format, foreign/our code variant), project fingerprint, drop unused auto-memory section. 2 guards: registry writes (next ID, index row, append-only, English), merge gate (gitflow finishneeds explicit signal in last user msg), commit msg ≤50 words, 80-col/function-length feedback on our code. 3 listings: skill listing filtered by fingerprint + descriptions restored, classifier one-line skill hint replaces routing table, agent descriptions trimmed (names kept; dispatch to verify). 4 active memory: session digest (open BLK, actionable TODO, last journal) re-injected after compaction + per-prompt local heading score (top 3-5 above threshold). - Est. gain: ~13-15k of 30.2k tok (measured chars × measured chars/token ratios; estimate). Main value = relevance + hard guarantees, not tokens.
- Constraints kept: no forced continuation (BDR-083, BDR-087), no per-turn capitalize nag (BDR-037), hints never over-fire (LRN-091), skill hint advisory never forced invocation. Prompt cache: context/sections computed once per conversation; per-prompt context appended (no bust).
- Alternatives rejected: hide executor agents via
agent.offer(breaks dispatch, proven); move writing-style/communication out (apply every turn, same cost); rewrite shown answer (turn.completeonly appends below); Stop-hook enforcement (BDR-083). - Refs: probe
scratchpad/ctxprobe(session-local, not committed), plugin-authoring types 2.1.306 (prompt.context,prompt.compose,prompt.section,prompt.attachment,prompt.submit,tool.call). Supersedes BDR-031; links BLK-009, LRN-175, LRN-054, LRN-091, BDR-115. - Amendment (2026-10-24, user): phase 5 added: per-project virtual profiles, concurrent sessions (today
lib/profile.shglobal: one profile for all open sessions), auto-pick from fingerprint or pinned/profile set, per-skill advert of needed helpers; plugin project-scopeenabledPluginsto verify. Advisor toast refused. Each phase deletes what it obsoletes (scripts, hooks, tests, doctrine). Full specs: TODO "Context mod queue". Probe bench kept at.claude/tasks/plans/2026-10-24-context-mod-probe/. - Amendment 2 (2026-10-24, user: full memory redesign allowed): phase 4 = memory v2 (write + capture + read + feedback), measured on 434 entries: capture is the weak link (5/7 real errors of 2026-10-23 had no entry), not search; haiku rerank of lexical top-30 = 14/22 vs BM25 9/22 on real FR prompts; error 4-gram match exact (429 → BLK-030/031). Storage: augment in place + Meta line + generated Index + single writer
lib/memory.sh+ pre-commit validator (Edit-level guard rejected: real writes go through Bash/python). One-file-per-entry rejected for now (44 citers + 8 project migrations for concurrency/history gains a validator+backfill mostly match). Registry guard moved from phase 2 to 4a; 4a needs no mod. - Amendment 3 (2026-10-24, challenge of phase 1): phase 1 = native context diet, no mod. Proven:
paths:rules load on Read (not on Write of a new file),autoMemoryEnabled: falsedrops the auto-memory section, classic SessionStart/UserPromptSubmit hooks inject context, instruction files reload on compaction natively. Each section goes to the carrier matching its trigger (path rule, hook, skill body, setting, or compression once enforced by 4a/phase 2). Same ~4.4k gain, no mod code, works with mod off. Mod marker subtraction kept only as fallback if a native carrier fails a canary. Fingerprint moves to phase 3. - Amendment 4 (2026-10-25, challenge of phase 2 + profile facts + user answers): phase 2: phrase-list merge gate rejected (3 lenses FATAL: false allows/denies, breaks BDR-068 ritual + release sub-agent) →
$.ui.askconfirmation dialog per branch (user pick), named exceptions, prefilter before.catch, hard_deny extended; commit limit →commit-msggit hook (CLAUDECODE-gated); code limits → classic PostToolUse on added lines, 80 cols only; G2 removed (BLK-022). Phase 5 = native packs: per-project.claude/settings.local.jsonenabledPluginsand per-conversationclaude --settingsproven concurrent (same and different projects); skills-dir plugins obey; plugin skills keep short names; plugin agents need prefix → agents stay global (user); global profile mode deleted (user); 11 profiles kept as pack compositions (user); detection proposes once (user); off pack mid-skill → propose +/reload-plugins(spike). User-scope MCP not switchable per project → MCP into packs. - Amendment 5 (2026-10-25, routing verification + user picks): routing probe bench (
.claude/tasks/plans/2026-10-25-routing-probe/): fresh sessions route explicit intents right (init-project, close, bugfix, reconcile, commit-change, cso), but a small feature ask was coded inline and history shows 11/21 code-writing bug/feature turns inline. User: always through a skill → phase 2 routing guard (main-loop code write outside a skill run denied; docs,.claude/**, sub-agents, in-skill writes free; ceiling bullet rewritten model-agnostic). Interviewer: by design inline in /init-project (C1 routed right), unused only because no new project in the window. Listing: 46/124 skills name-only;SLASH_COMMAND_TOOL_CHAR_BUDGET=60000→ 0 name-only (+~17k chars); raise after packs (user). Order: 0 → 4a → 1 → 5 → 2 → 3 → 4b-4d (user). - 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. Missessh -c, bare shell + heredoc,$(…)command, absolute path, interpreters, quoted literal arg. UnderdefaultMode: autoclassifier approved every miss. rtk-rewrite hook runs before permission eval, deny evaluated on rewritten cmd:git push origin :feature→rtk git push …bypassesgit push * :**(ac23cc6) and askgit push *;cat */*.pemlikewise. Redirects into Edit-denied path denied.askbeatsallow. 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 = nativeaskrules (Bash(bash */gitflow.sh finish*),Bash(gitflow_finish*),Bash(git merge *)), bench r3 G1-G7 all denied,startfree;$.ui.askmod dropped; BDR-068 /close auto-finish costs one click (user accepted). Routing guard hosted in model-router:runMainwrong signal (BEST tier only, never ends), mod state plugin-private; free whenturnMain.source ∈ {skill, model}or/routesticky; Edit/Write/NotebookEdit only, Bash write forms deferred (no measured evasion). Interpreters (python3 -c211,node -e450 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./modelwrites the TRACKED user settings.json (fable landed there 2026-10-25): never the per-project route. Applied: tracked defaultopus, this repo localclaude-fable-5-1[1m]. Phase 5 profile =enabledPlugins+model; doctor warns when trackedmodel≠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
- Status (2026-11-16): accepted, all phases shipped: 0
925dafa, 0b06012ea, 4a017a28b, 19a20ca7, 53cc4e0d, 229624d7, 4bdfadf8a, 4cddb04f4, 4ddcb593a. Phase 3 closed unbuilt 2026-11-03 (60f28a6). Per-phase /context delta unrecorded for 4a 5 2 4b-4d; headless 26.2k (10-29) to 27.1k (11-12), interactive 40k (11-03), gap LRN-270, synced skills cut BDR-141
BDR-126 — model-router /model <name> scope dialog: project / conversation / everywhere [accepted] (2026-10-25)
- Decision:
command.runhook on coremodel. Composer origin, 1 token, name incfg.models(alias or listed full id,[1m]stripped for test,haiku[1m]out), surface present, no dialog open, router on →$.ui.askThis project / This conversation / Everywhere. Project = full id ([1m]verbatim) into<session root>/.claude/settings.local.json+ sticky model route; conversation = sticky route only; both droprunMain, keep sticky effort. Everywhere = drop sticky model+tier, native passthrough. Esc/free text = cancel. Else native, no question. Fail-open to native only BEFORE answer; post-answer own try/catch → text. - Why: native
/modelalways writes tracked user settings.json (BDR-125 am. 8, LRN-098); user wants model per project and per conversation. - Project write rules: mod's first project-tree write. Stat-first absence (LRN-228), links refused (
.claudeand file), regular file only, 64 KiB cap, JSON object only, fixed cause words (never err.message), other keys kept. - Alternatives rejected:
$.config.set(no scope arg); Esc = passthrough (silent tracked write); dialog on unknown names (router can't route them);canonical()for written id (strips[1m]); sharedmodelAnsweredflag (concurrent dispatch clears it). - Residuals: stat-then-write race (no no-follow in
$.fs); dangling-link refusal assumes lstat-like$.fs.stat; engine gitignore of created file unverified; live hot-switch on localmodelchange unverified; worktree session writes worktree's file (documented). Live check pending (LRN-212). - Refs: contract
.claude/tasks/contracts/2026-10-25-model-scope-dialog-1450.md, plan r3 same dirplans/, commits1fde5bb,773fe17. BDR-116, BDR-125, EVAL-049. - Status (2026-10-29): accepted, no-args part superseded by BDR-132 (2026-10-29)
BDR-127 — model-router: /model picker asks its scope; hand pick always switches [accepted] (2026-10-25)
- Decision: (1) picker =
classic.PreModelSwitchsourcepicker: gates (router on, stringrequested_modelin table, surface present) →$.session.id()read → slot held = deny + toastanswer the open dialog first(never native) → else setst.askingsync,void pickerDialog, return{ permissionDecision: 'deny' }. Dialog after 300 ms sleep = sharedscopeDialog(same 3 scopes as BDR-126); Everywhere =$.command.run model <requested>(native write); stalesession.id→ nothing applied. Default/unknown/headless/other sources → native. (2) hand pick:Routed.explicitModelset by dialog answers;decideMainrunshandCallfirst: target usable (not down, fits) → move/keep, no caps, no switch flags; unusable → existingautomaticCallwith no wanted model + one log. Hand pick clears target mark at pick; native user switch (PostModelSwitch command/picker/sdk) drops it, skipped while picker dialog open./route model=keeps caps. - Why: BLK-036 (picker wrote tracked user settings for per-project intent, 3 times on 2026-10-25); user: picker → project or user scope, default opus, hand choice must switch even in long conversation.
- Alternatives rejected:
$.ui.askinside hook (never renders, spike); bypass insideupgradeCall/downgradeCall(breaker never checked on target: 2 BLOCKERs r1); handCallkeep(cur)when unusable (pins down model when hand pick == cur: BLOCKER r2); mod restoring user settings.json after native write (BDR-116); alias pins (user kept full id). - Residuals:
/configModel row still native (PreModelSwitch sourcecommand, same as Everywhere's own run); hand pick dropped at/clear; no timeout on never-answered dialog (slot held → picks denied, no leak); window guard needs awindowsentry (none shipped); PostModelSwitch on denied pick unverified live (guarded). - Refs: contract
.claude/tasks/contracts/2026-10-25-picker-scope-1952.md, plan r3 same name inplans/, commits2202964,5d262d3. BDR-126, BDR-116, BLK-036, LRN-231, EVAL-050.
BDR-128 — Project path rules: one bash oracle, /onboard split subtract-only, generators born split [accepted] (2026-10-27)
- Decision:
.claude/rules/<name>.md, frontmatterpaths: ["a", "b"]one line (block list refused by the oracle, named in the error). One oraclelib/project-rules.sh [-C dir] check | matches | sections | extract | emit: globs on the WORKING TREE (compgen -Gglobstar dotglob, dep dirs filtered unless the glob names one:vendor/**valid),# static-check: skipmarker exempts a rule whose files exist mid-run, a section ends at next#/##outside a fence,extractrefuses (heading count ≠ 1, target exists, glob no match, failed rewrite rc 2 + rule removed). This repo: 4 rules (rules-maintenance, graphify-vendored, mods, transient-artifacts + skip), CLAUDE.md keeps header + Health Stack +## Path-scoped rulespointer./onboard split: main loop classifies (sections), verifies every glob (matches), row shape[a-z0-9][a-z0-9-]*/ no'|/.., gate, onboarderMODE: splitexecutes (S0 preflight incl.check+ gitignore negation ordered a-f, S1 extract per row, S2 pointer +cat -s, S3 check + commit +cat-file -e HEAD:per rule, two STOP shapes, rollbackreset -q+checkout). Generators: onboarder PHASE 5b + scaffolder 3bemitdocker/testing/ci fromtemplates/project-rules/when a glob matches.hooks/instructions-loaded.shpermanent (InstructionsLoaded→~/.claude/logs/instructions-loaded.jsonl, field allowlist, exit 0 always, rotate 5 MB).!.claude/rules/after.claude/*here + socle. - Why: project CLAUDE.md 5,285 → 584 bytes,
/contextMemory files 11.6k → 9.6k, project row 2.1k → 166 tokens; rules load on Read only, proven in main + sub-agent (LRN-232). Phase 0 of BDR-125: no mod, subtract-only, deterministic oracle inmake test. - Alternatives rejected: block-list
paths:parsing (spec shape inline; pre-flightcheckat S0/S1 moves the failure before any write); mod-based injection (BDR-125 says phase 0 no mod); dep-dir filter unconditional (vetoedvendor/**);git add .claude/rulesdir (a pre-existing rule made visible by the negation would ride along); whole-file Write for the pointer (subtract-only). - Residuals:
###granularity before faunosteo (12.6 KB path-bound content under always-on## Project conventions;##-only moves 1.5%), user decides (TODO 0b);gameheading with'refused until renamed or extract by index;extract -ndry run deferred; T11b + AC2 hardcode 4 rules;InstructionsLoadedkey on older CLIs unverified (checkclaude --versionon work machine before pull); pre-commit.claude/**exemption lets a rules-only commit land on develop → phase 2. - Refs: spec
docs/superpowers/specs/2026-10-26-claude-md-split-design.md, plan r3docs/superpowers/plans/2026-10-26-claude-md-split.md, contract.claude/tasks/contracts/2026-10-26-claude-md-split-0042.md, commits abfa416..0b59687. BDR-125, BDR-003, BDR-065, LRN-154, LRN-232, LRN-233, EVAL-051.
BDR-129 — Memory registries v2: lib/memory.sh single writer, format: 2 without Index, shared parser, rc 6 chokepoint, oracle upgrade [accepted] (2026-10-28)
- Decision:
lib/memory.sh= single writer + reader of.claude/memoryregistries (add/status/journal/index/check [--staged]/upgrade,-C dir). v2 = same file,format: 2frontmatter, no## Index. Status parser shared withlib/reconcile.sh: strict on v2 (heading[tag]or labelled status line, last wins,memory_closed= resolved|superseded|deprecated), legacy lexical reader kept on v1 (13 v1 repos: open sets identical).memory-commit.shrunscheck --staged: staged v2 registry rewriting an entry line, new duplicate, bad heading, open fence, deletion or downgrade → unstaged, rc 6. Lock = bash noclobber file in git common dir, token unlock, serialized steal, verified backup restored on failure/signal.upgrade: Index-only dates/statuses → body lines, dialect headings →## ID — title (date), one-way verdict repair (v1-closed→strict-open only), oracle else rc 2 file untouched; refuses duplicate IDs, non-table Index. - 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);mkdirlock (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 + specdocs/superpowers/{plans,specs}/2026-10-27-memory-v2-write*, commits a423594..aab9e4d, upgrade9698473. 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.shblock only whengraphify-out/graph.jsonexists (threshold + one reminder clause stay, sub-agents never see the banner); never SPA + Rust default →lib/architecture-defaults.mdRead 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:
/context30.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: projectdropped 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./modelwrites never committed (model per project lives in.claude/settings.local.json); tracked default"model": "opus","switchModelsOnFlag": truestays. UI-written keys ("theme") stay uncommitted, stashed aroundgitflow 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/restorethe live file (symlink of ~/.claude/settings.json). - Rejected: commit
/model+ theme as is (doctor warns tracked ≠ opus).
BDR-132 — Bare /model opens the router dialog: model, variant, scope [accepted] (2026-10-29)
- Decision: bare
/model(composer, router on, surface, no dialog open) → router dialog incommand.run: step 1fable (best)/opus (big)/sonnet (work)/Other model (native picker); step 2Standard/[1m]; step 3 existing scope question (scopeDialog). Asks even for current model. Other model → native picker after slot freed (pick inside it still asks). Esc/free text → "model: no model chosen, nothing changed". Haiku via native row or/model haiku. - Why: user "il faut que ça soit systématique" (option A, 2026-10-29); BLK-037.
- Rejected: 8 rows in one ask (engine cap 2-4, LRN-242); native picker + pin-conflict alert only (option B, not systematic); gateway-id normalization (would switch on routing in a gateway session).
- Supersedes: BDR-126 "no args → native picker untouched". Live proof 2026-10-29: opus → [1m] → This project wrote
claude-opus-5-5[1m]. Contract.claude/tasks/contracts/2026-10-29-bare-model-dialog-1617.md.
BDR-133 — Negated status word in clause does not count, shared v1/v2 negation helper [accepted] (2026-11-01)
Context: v2 parser + v1 legacy reader read Status: not resolved yet as resolved (phase 4a minor, robin_petier EVAL-005 keep, … not accepted until … read accepted). User pick 2026-10-31/11-01.
Decision: status word negated in its clause does not count. Negator not|no|never|pas, at most one word between negator and word, no clause boundary , ; . : ( ) -> → — between. Next non-negated occurrence still counts. One helper mem_has in _MEM_AWK, shared by mem_word (v2) and _mem_v1_word (v1), so upgrade refuses such v1 closure ("unlabelled, mixed or negated line") instead of cementing resolved. Word = maximal [a-z0-9] run, loop not ERE interval (BWK awk).
Alternatives: ignore negation (keeps false closures); line-scope negation (resolved, not open would read none: wrong); NLP (no).
Consequences: real-data replay 14 repos → 1 move (robin_petier EVAL-005 accepted → keep). mawk run in T17 guards BWK-class awk.
BDR-134 — Phase 5: packs are skills-dir plugins, profiles are settings fragments, nothing global (2026-11-02)
- Context: one
~/.claudeserves every project and conversation. Old mechanism global:skills/↔skills-disabled/symlink moves + user-scopeclaude plugin enable|disable+.active-profile. One project's switch changed every open session. - Decision: heavy skill groups = skills-dir plugins
skills/pack-<n>/(manifest + tracked relative symlinks intoskills-external/, 4 real dirs moved). 9 packs: design, scroll3d, seo, web-validate, gstack-dev, gstack-browser, gstack-design, higgsfield (OFF), extras (OFF). Profiles = literal settings fragmentslib/profiles/<n>.json(enabledPluginsexplicit for every pack + managed plugin,deniedMcpServersboth higgsfield connectors on minimal/dev/seo/qa/audit, optionalmodel); 9 profiles (backend, web-full dropped: byte-identical to dev, full). Per projectprofile.sh setmerges into.claude/settings.local.json; per conversationcc <name> <profile>=claude --settings.profile.sh current --plainsingle truth for gate, hooks, statusline, advisor. No profile = manifest defaults = full. Listing budgetSLASH_COMMAND_TOOL_CHAR_BUDGET=50000(0 name-only on full, +4.5k tokens est.). - Rationale: measured 2026-11-01 (CLI 2.1.316): pack skills listed once as
pack:skill, both names invoke;--settingsfalse beats local true;/reload-pluginsreloads a pack mid-session from a local edit but never re-reads a--settingsfile (frozen conversation → relaunch); connectors load under-p, denied per project byserverName, union across files. - Alternatives rejected: keep symlink toggling (global, races between sessions); pack
.mcp.jsonfor higgsfield (duplicates the claude.ai connector, needs interactive OAuth); per-request confirmation of the gate (gate reads settings state, not files). - Supersedes: BDR-030 (gstack via symlinks), BDR-079 (
setsymmetric on externals/MCPs), BDR-101 mechanism (full stays the policy). Amends: BDR-024/025 (show --plain→current --plain), BDR-109 (higgsfield-websiteslives in pack-higgsfield, ON inmaxonly;profile.sh enable higgsfieldreplaces both toggles; npm CLI unchanged). - Accepted risks:
cc.shkeepsset -a; . ~/.claude/.env(all secrets in the claude env, asdtach_claudedid);deniedMcpServersunion =cc x webon adevproject keeps the connectors denied (set webin the project fixes it). - Branch: feature/phase5-profiles-packs; spec docs/superpowers/specs/2026-11-01-phase5-profiles-packs-design.md; contract .claude/tasks/contracts/2026-11-01-phase5-profiles-packs-1300.md. Supersedes BDR-030.
- Status (2026-11-09): accepted, amended 2026-11-09: higgsfield connector denies + census connector rule removed after claude.ai account removal (chore/connector-deny-cleanup); generic deniedMcpServers mechanism in profile.sh kept
BDR-135 — model-router askTier: consent before Fable, tier-name choice stamped on turn and run slots, per-type spawn memory [accepted] (2026-11-02)
- Context: user ask 2026-11-02: model-router must ask before routing main or a rowed spawn onto Fable. feature/router-ask-tier, contract
.claude/tasks/contracts/2026-11-02-router-ask-tier-1434.md, plan r3 after 3 lenses + confirmation. - Decision:
routing.jsonaskTier(best|false, machine override wins, absent = best, missing file = off, bad value logged once + best). Ask fires at route EVENTS only (typed or model-loaded rowed skill, mainroutetool phase, typed/route <phase>, rowed spawn from main), never in turn.step (LRN-231). Guards: router on, not paused, cur not head,askingfree, slot unstamped, slot tier = best, slot = effectivemainModelSlot, surfaces non-empty, then real decision viasnapshot/decideMainlands on head. OptionsFable·Opus instead (big tier)(dropped when opus down) ·Stop asking this session. Choice = TIER NAME onRouted.tierChoice(best|big), stamped on turn slot AND run slot; inherited only same-tier, non-typed writes (typed skill = new span, work route never inherits).bigresolves minus head (opus, else sonnet, head last), phase effort (no stand-in notch). Spawns: one answer per agent type per session (State.tierSpawn), stored answer applied before any guard./route ask-tier on|offviaflagCommand(shared withask);/route showask-tier:. Nothing written toconfirmed. - Why: Fable credits burn on best-tier rows (BLK-030/031); user wants consent per span, not per spawn (audit gates respawn verifier + security-auditor each loop).
- Alternatives rejected: stand-in rewrite (
isStandInkeyed on held head, would print "stands in for" on a user pick); rebuilt decision from parts (diverges fromdecideMain: sticky slot, mainUpgrade off, cap); per-spawn ask (blocking dialog, no timeout, stalls unattended orchestration); generated labels from aliases (contract fixes the exact words); any tier name inaskTier;{ model: alias }on spawn (explicit model bypasses breaker). - Residual (user-accepted, F): Fable held or cap exceeded at the route event → no question, slot unstamped; hold lapse / compaction → next step upgrades unasked (breaker behaviour today).
/model <x>while any dialog holdsaskingfalls to native (pre-existing, BDR-126). - Gates: r1 correctness FATAL(6) robustness FATAL(6) simplicity CONCERNS(4) → r2 → confirmation CONCERNS(6) → r3; feater DONE 28 TIER tests (590 → 618); GATE 0 MET 5/5; verifier CONFORME 11/11 first pass; security PASS (1 LOW fixed:
clean(skill)). Commits9a24a62, docs789fd00. - Refs: BDR-116, BDR-123, BLK-032, LRN-231, LRN-242, LRN-254.
- Status (2026-11-16): accepted, amended by BDR-150: ask-before-Fable inert unless an override heads best with fable; stored answers gate on fableHeadsBest
BDR-136 — Phase 2 guards: native ask merge gate, bench-proven shell rules, rtk rc 3 passthrough, router write guard with a session skill latch, code-limits signal [accepted] (2026-11-02)
- Context: BDR-125 phase 2, feature/phase2-guards, contract
.claude/tasks/contracts/2026-11-02-phase2-guards-1545.md, bench.claude/tasks/plans/2026-11-02-phase2-bench/. - Decision: (1) merge gate = native
askBash(git merge *),Bash(bash *gitflow.sh finish*),Bash(sh *gitflow.sh finish*); every finish prompts once,/close5C +/release-candidateincluded; declined prompt → "nothing merged, branch kept", stop. (2) shell-form asks (sh -c,sh -*c,bash -*c,dash -c, barebash/sh,bash <(,/bin/{sh,bash},/usr/bin/{sh,bash},/usr/bin/env {sh,bash}), deniesawk *system(*,head|tail|cat * .env*+* */.env*, 20rtk readtwins; census T62/T63. Rule lands only when every bench row naming it hits its want + one positive row. (3) rtk hook rc 2|3 → original passes (native rules judge as typed). (4) router write guard: main-loop Edit/Write/NotebookEdit of code (config included; free.md.txt<root>/.claude/minus worktrees,<root>/docs/) redirected untilskillRunlatch (any skill typed or model-loaded on main), a route phase this turn, or typed/route; dropped by/route clear|off,/clear; fail-open. (5) code-limits PostToolUseEdit|Write: added lines > 80 cols, ours only, once per file per session, additionalContext. (6) release finish + tag in main loop (BLK-018 b), executor prep only. - Why: doctrine rules mechanically checkable → deterministic; routing probe 11/21 code turns inline; rtk rewrite let
git push origin :refescape deny/ask. - Alternatives rejected:
$.ui.askmod gate, phrase-list gate (challenges 2026-10-25); 16 routing rows for the guard (run slot drops mid-run, would open first-use + ask-tier dialogs);git -C * merge *(asks on any commit text with " merge ", sub-agent ask refused); quoted finish rule (matcher ignores quote in pattern);gitflow_finish*,bash -s*(bench RAN);Bash(/*)(kills*/rtktwins); per-spawn guard. - Residuals: Bash write forms outside guard; latch reset on register.ts reload; sourced
gitflow_finish,git -C <dir> merge;rtk read -n .envflag-first (security MEDIUM, TODO); code-limits TMPDIR state dir ownership unchecked; silent in this repo (code-origin foreign). - Gates: plan r1 correctness FATAL(8) robustness FATAL(5) → r2 → confirmation CONCERNS(4) → r3; user interactive ask check; SDD 11 tasks; final opus review With fixes → fix wave; GATE 0 ABANDONED(2) user-accepted; verifier ECARTS(6) → ECARTS(2) human-gated; security PASS (1 MEDIUM, 3 LOW). Refs BDR-125, BDR-068, BDR-123, BLK-018, LRN-256, LRN-257.
- Status (2026-11-16): accepted, amended: point (4) router write guard now fails closed via next.called (guard failure holds main-loop code write outside skill run; sub-agents, runs, .md/.txt pass); refused/isError Skill no longer latches.
859e504, BDR-125 gap A6, user choice 2026-11-12
BDR-137 — Phase 4b memory capture mod: error-shaped Bash failures redacted into a per-project store, 4-gram index per call, one note per milestone, memory_pending (2026-11-04)
- Context: BDR-125 phase 4b,
feature/memory-capture(f1d4f9d..HEAD), contract.claude/tasks/contracts/2026-11-03-memory-capture-0100.md, specdocs/superpowers/specs/2026-11-03-memory-capture-design.md, plan r3, spike.claude/tasks/plans/2026-11-03-memory-capture-spike/REPORT.md. Capture = weak link: 5/7 real errors of 2026-10-23 no entry. - Decision: mod
mods/memory(memory@skills-dir). (1) Failure = BashisErrortextExit code N; distinctive line = last line after rtk-trailer strip, must hold a letter AND an error word (ERRORISH, answer 2-amended after 83 % measured noise); permission/guard/tool_use texts never captured; sub-agent failures marked. (2) Redact BEFORE store:KEY=value(TOKEN|API_KEY|SECRET|PASSWORD|PASSWD, digits ok, quote-aware), 7 guardrails shapes, JWT first, Bearer, URL creds,-u/--password/-b(curl)/--cookie,Authorization: Basic|Bearer|token, vendor prefixes (sk-ant-, sk-proj-, github_pat_, glpat-, AIza, npm_),--token|--api-key|--secret, API-key/cookie headers, JSON/YAML password|token|secret|api[_-]?key keys, 40-hex URL user (answers 6-amended, 6-bis). (3) Store$.storekeyp:<root>→ 3 sessions × 50 failures, 2 KiB/entry, milestones 20, red 10, 1 MiB sweep at session creation, one closure write chain. (4) Index per call from BLK/LRN backticked spans ≥ 12 (cap 300), word 4-grams, all-placeholder grams skipped (4-amended), superseded excluded (lexical reader,shortcut:), first ID wins. (5) Milestones main loop only: feat|fix commit (-mand heredoc forms),gitflow.sh finish≠finish chore,make testred→green; onememory: <kind> <label> — n new failure mode(s)note at next composer prompt,st.pendingin closure, never per turn, never Stop, never sub-agent. (6) Toolmemory_pendingdeferred (ToolSearchonce), servedmcp__memory__memory_pending, answer header /index:/ milestones / NEW / known / earlier sessions, 20 000-char cap; consumers capitalize (**Captured first.**), close (alias), feat, bugfix, ship-feature, hotfix (NEW current-session non-sub-agent only), commit-change (both commit-changer dispatches,MEMCAP_EOF_<random>quoted heredoc body only); init-project excluded (7-amended). Off switch~/.claude/memory.json{"enabled": false}read lazily per session; unreadable or non-boolean → on + one log line. - Why: engine facts (spike): refusals come back
isErrorwith the reason in text, nodenyfield;$.storeper plugin, machine-wide, 4 MiB; no$.state;-pprompts originsdk(note proven interactive only). Noise on the shipped rule 83 % (NOISE.md), filter keeps every useful sample, 81 → 27 captures. - Alternatives rejected: classic hooks (no store, no tool); gitleaks as redaction engine (rules compiled in, allowlist ignored); per-session store (lost at /clear); index cache (stale registries); option B no sub-agent capture (loses reviewer findings); option C ship as is (70 % noise per call).
- Residuals: cross-process writes last-writer-wins; non-Bash failures; lexical superseded reader; 40-hex Gitea tokens kept (SHA-shaped);
user:p@ss@hostpartial;key: valuepair rule over-redacts prose (token: expected); session root moves with /cd or a worktree; bare finish on a chore branch counts; common-phrase 4-gram collisions (every ENOENT → known LRN-056 here) → 4c. - Gates: plan r1 correctness FATAL(9) → r2, confirmation CONCERNS(5) → r3; SDD Tasks 1-6 + 8 (sonnet, 7 fix rounds), 7 and 9 controller; headless proof PASS; final opus review Approved with fixes (2 Important, 13 minors, 2 rounds); verifier ECARTS(3) → ECARTS(1) (interactive /clear half, user); security PASS ×3 (coverage rounds). 36+ commits.
BDR-138 — extract-guard: narrow text hook refusing package/archive extraction into system dirs, plus soft_deny, not a full shell parser (2026-11-05)
- Context: user incident 2026-11-04 (Debian package extracted on a VM overwrote system binaries); /feat on feature/extract-guard, contract
.claude/tasks/contracts/2026-11-04-extract-guard-2214.md, plan r3. - Decision:
hooks/extract-guard.sh, PreToolUseBash|Monitor, timeout 10, DENY (not ask). Watched: dpkg/dpkg-deb extract flags, tar extract (bsdtar, gtar), unzip, cpio copy-in and pass-through, recursive cp. System roots: the root dir itself and usr, etc, bin, sbin, lib*, boot, opt, var, srv, root, sys, proc, dev with subdirs; var/tmp, var/folders, HOME free. One POSIX awk scanner (bash 3.2 safe wrapper): re-tokenizes EVERY quoted word holding a blank, command substitutions, backticks, heredoc bodies (depth ≤ 3), no carrier list; detector starts at every watched tool word (covers sudo, find -exec, both vaas-cli ssh forms). Unresolvable destination (variable, substitution, glob, brace) refused; >64 KiB naming a tool refused; awk failure past prefilter refused; jq/awk/grep/sed/tr/wc missing → warn + allow. Remote follows local rules (relative or absent dest passes); quoted script inherits caller's cd (stated FP: cd to the root dir, then an ssh extract); subshell restores cd. PlusautoMode.soft_denyline for intent text hides; doctrine bullet in CLAUDE.global.md § Destructive tools & data loss. - Why: static shell parsing never complete (plan r1 FATAL ×3, r2 FATAL(9)/(7): 30+ forms); ssh, sudo, su, eval, pipe-to-bash already denied statically, real exposed carrier = vaas-cli ssh (remote root); classifier reads intent → soft_deny covers MISSES.
- Alternatives rejected: fine parser with carrier/wrapper lists (r2, endless holes); doctrine + soft_deny only (no deterministic refusal); ask (inert in headless sub-agents, BDR-090); folding into withheld guard-bash.sh (BLK-022 spec would turn red).
- Residuals: destination built outside the text; old-style tar C letter, long-option abbreviations; tool names built by expansion; archive members escaping a safe destination; the cd-then-ssh FP; prose or a heredoc body quoting a complete extraction command into a system dir is refused too (it hit this memory write: memory bodies go through Write + --body-file, prose uses
<pkg> <dir>placeholders). - Gates: verifier ECARTS(2) → CONFORME; security PASS ×2 (4 MEDIUM then 2 MEDIUM fixed: size cap, control-byte RS, obfuscated names, globs, cpio pass-through, busybox timing); 134+ tests under gawk/mawk/busybox awk; make test green. Commits 5507972..f02fd8a, settings
42e37cbvia index, docs8d5a7bd.
BDR-139 — Pre-commit exempts only .claude/{memory,tasks,audits,deploy}/ + .githooks/, --no-renames [accepted] (2026-11-06)
- Date: 2026-11-06
- Status: accepted
- Decision: gitflow pre-commit exempts on main/develop only staged sets wholly under
.claude/memory/,.claude/tasks/,.claude/audits/,.claude/deploy/,.githooks/; listed withgit diff --cached --name-only --no-renames..claude/rules/,.claude/settings.json, agents, skills = code for hook → branch first. Commit c5bd0f8; testslib/gitflow-test.shT21d-h; both hook copies regenerated; citers CLAUDE.global.md, gitflow-aiguillage.md, settings.json prose. - Why:
.claude/**let project config read by every session (rules, settings) land on protected base unreviewed;--name-onlyprinted only rename destination →git mv .claude/rules/x .claude/tasks/xhid deletion. Allowlist = exactly side-car paths skills commit (memory-commit, deploy-commit, /tour audits): no skill flow taxed. Develop history: 1 commit (858e7a7,.claude/settings.json) would now need branch. - Alternatives rejected: keep
.claude/**(BDR-045 status quo, leak stays); also exempt.claude/settings.json(user picked no: config = reviewed change); size/heuristic narrowing (BDR-045 (D), fuzzy). - Residual: hook fails open if
git diff --cachederrors (pre-existing; Gitea protection backstop). Partly revises BDR-045 (exemption narrowed, aiguillage unchanged). See LRN-084.
BDR-140 — Phase 4d memory feedback: offline reader, local labels, two gates, fixed thresholds, /memory-feedback [accepted] (2026-11-08)
- Date: 2026-11-08
- Status: accepted
- Decision: phase 4d feedback = offline reader, no runtime cited flag. Mod logs
cands+mson prompt records (4d.1). Bun readerlib/memory-feedback/(labels, metrics, thresholds, transcripts, reader CLI worksheet|apply|sample) joinsl:<root>log to transcript attachments; redacted text only in scratchpad worksheet;~/.claude/memory-feedback/(0700/0600) keeps labels.tsv (append-only + .bak, repo tagbasename#sha1[0:6]), state.json (gate verdict first-reached times, closed flag), FEEDBACK.md. Two independent gates: prompt 20 labelled asks or 35 d; tool 10 or 35 d, one 35-d extension then closed. Thresholds r1 table inthresholds.tsonly. Skill/memory-feedback(reflect row), user-invoked; banner reminderlib/memory-feedback-remind.sh(5+ d, store changed, silent when closed / recall off). Gate verdict recorded once (NEW line) as EVAL in this repo only (-C). - Why: transcripts live 7 d (BDR-057) → weekly reminder, not raised retention; labels carry client repo names → local, never in git; log alone cannot show usefulness or misses → join + Claude labels + user spot check (LRN-168); tool channel ~3 records/14 d → own gate.
- Alternatives rejected: raise cleanupPeriodDays (reverses secret hygiene); cron job (machinery, background claude); labels committed (client names on Gitea); one joint gate (prompt waits on rare tool channel); Stop-hook cited flag (BDR-125).
- Deviations from spec (user-gated 2026-11-07): reader in lib/ not mods/ (plugin validate/test scope); miss causes no-overlap|overlap only; labels.tsv without cited; noisy/promotion lines carry repo tag.
- Reference: feature/memory-feedback 21483dc..b44b19f; contract .claude/tasks/contracts/2026-11-06-memory-feedback-4d-1825.md. See BDR-125, BDR-137, BDR-100.
- Status (2026-11-12): accepted, 4d.4 built 2026-11-12 (BDR-146, feature/recall-gate1-fixes); later gate reads count only rows after 2026-11-12
BDR-141 — claude.ai-synced skills off via global skillOverrides, not sync flag or profiles [accepted] (2026-11-09)
- Decision: claude.ai-synced skills (19: docx, pptx, xlsx, pdf, docs, computer-use, cv-*, veille-emploi…) turned off by top-level
skillOverrides{name: "off"} in tracked user settings.json. Global so plainclaude(no profile = full, user rule 2026-11-09) gets it. Project re-enables one:{"skillOverrides":{"<name>":"on"}}in.claude/settings.local.json(per-key merge proven). Budget stays 50000. - Why: measured
/contextfull headless 32.2k → 28.5k (Skills 16.2k → 12.5k); budget 50000 paid mostly synced skills (0.5k → 3.7k), our 44 skills keep descriptions even at default budget. Synced skills irrelevant in coding sessions. - Alternatives rejected:
syncClaudeAiSkills: false(moves synced skills to~/.claude/skills/.trash/, not reversible per project); skillOverrides in profile fragments (session without profile reads no fragment); lower budget (40000 = 50000 once synced off, no gain). - Also 2026-11-09: user removed Higgsfield + unused claude.ai connectors at account level → MCP instr 2.4k → 0.77k on full; profile
deniedMcpServersnow dead (cleanup queued). Full headless 32.2k → 26.9k total. - Amends BDR-134 "nothing global": account-level noise cut globally, packs/profiles untouched. Ref: feature/claude-ai-skills-off
47438f4, contract .claude/tasks/contracts/2026-11-09-claude-ai-skills-off-1253.md. See BDR-125.
BDR-142 — Plugin advisor emits tokens; profile set only on a project without profile, gate validates and applies [accepted] (2026-11-11)
- Decision: plugin advisor emits tokens only:
↻ SET <profile>,⚡ ENABLE/⚠️ DISABLE <pack | full plugin id>. SET only when source=default AND profile=full AND target != full; else enable/disable deltas against current (or SET target). Hotfix/quick-fix request never changes profile. DISABLE from project-level probe signals only. Under source=flag: no write,relaunch: cconly. Monorepo = one profile at git root (union). lib/plugin-gate.md (main loop) checks tokens vs closed lists (profiles web/seo/dev/design/qa/audit/minimal, 8 packs w/o higgsfield, 2 managed full ids), buildsprofile.sh -C "<root>"cmds from fixed templates, printsdiffturns off/on, applies only when git toplevel == root, SET first, prints undo. - Why:
setmerges whole fragment (every managed key): a recommendation on a project with chosen packs or a custom state wiped them silently (web project told "backend → dev" lost 6 packs). Advisor has no Bash: lists it "computed" were invented; gate holds the shell. Bareui-ux-pro-maxid refused rc 2. - Alternatives rejected: set anytime with turns-off list (clobbers custom/chosen packs); hotfix → set minimal (task-scoped mass disable, persists project-wide); advisor printing full commands (unvalidated token reaches shell).
- Ref: feature/banner-drop-plugin-dev
80f56ef+9b12b12, plan .claude/tasks/plans/2026-11-11-advisor-packs-vocabulary-1000.md (r3, 2 challenge rounds, 4 exec rounds). Follow-ups in BUGS-FOUND (embedded keyword → SET minimal, extras metered pack, quoting). See BDR-134.
BDR-143 — prune-memory reads statuses via one prefix classifier, unreadable info-only [accepted] (2026-11-12)
- Context: /prune-memory STEP 1.A read raw
status:prose + per-entry frontmatter;memory.sh index decisionStatus empty on game 107/107, config 19/19, faunosteo 76/80 (dialects, v1). - Decision: one classifier
reconcile_status_classify <file> <PREFIX>(lib/reconcile.sh) for decisions + blockers: strict word v2, one-word status/statut label v1 (RECONCILE_BDR_REwidens v1 selector), never## Index.reconcile_blk_classify= BLK wrapper, output byte-identical. Unreadable status = one info-only count line per registry, outside "all", never written by skill, word from user per ID. User gated 2026-11-11. - Alternatives:
memory.sh index decision(reads no status on dialect/v1 projects); one reader per registry (duplicate parsers, BDR-129 drift class); guess word from prose (false open/close). - Consequences: dialect projects (game, faunosteo) get no prune candidate until dialect migration (BUGS-FOUND follow-up). Commit
99f10b2, test RED-9.
BDR-144 — Session start reads TODO and the digest, registries on demand [accepted] (2026-11-12)
- Context: CLAUDE.global.md Session start said read all 5 registries + TODO at every start; phase 4c digest (hooks/session-start.sh) already prints open BLK, Actionable TODO, last journal.
- Decision: read
.claude/tasks/TODO.md+ apply bannermemory digest(open BLK, last journal);+Ncount line -> read those BLK in blockers.md; no digest (foreign repo, memory mod off) -> list open BLK by hand. Registries read when task needs; planning flows scan perlib/analyze-before-plan.md. capitalize closing line aligned. User gated 2026-11-12 (2 re-gates after challenge). - Alternatives: digest only (rejected:
_digest_todoreads only### Actionable, init-project/onboard TODOs lack it -> TODO unread in other projects); full 5-registry read each start (rejected: 78-357 KB files, cost 4a/4c removed). - Consequences: D1b follow-up makes every project TODO digest-readable. Commit
c69ce9c.
BDR-145 — Released deny removal via justified T42 list expiring by version [accepted] (2026-11-12)
- Context: 6 dead deny entries in settings.json (2 mixed Bash forms never match, 4 Write(glob) never block Write) kept alive by push-guard T41/T42 non-weakening lock (BDR-111). User removes them by hand; test must stay green before and after.
- Decision: removal of a released deny entry goes through a justified list in push-guard T42 (exact rows,
#reason line each), forgiven untilremoved_ok_until(=3.0.0); T42e fails once version.txt passes it while list non-empty, list emptied in that bump. T42c proves unlisted removal still fails, T42d simulates exact hand edit. Write twins never shipped -> just leave T41. User gated 2026-11-12 (2 re-gates). - Alternatives: row-absent-from-base -> fail (no green path: base ref flips at finish; red on empty list); NOTE only (not fail-closed); Claude editing settings.json (rejected: own deny list = user hand edit).
- Consequences: CHANGELOG entries land with the user's settings edit (TODO:92). Commit
79f1a3f.
BDR-146 — Recall gate 1 fixes: idle needs 8 words, 2 picks, no-overlap misses accepted, 4d.4 prune step D [accepted] (2026-11-12)
- Decision: gate 1 (EVAL-058) fixes: idle recall fires only at ≥ 8 content words (
IDLE_MIN_WORDS, fresh/keyword stay 5,IDLE_MSunchanged); rerank keeps ≤ 2 picks (MAX_PICKS2); no-overlap misses ACCEPTED (BM25 already indexes body, register.ts docOf; replay 2026-11-12: 4 misses rank 53-322 of 185/473 with body overlap, BM25 13-38 ms, p90 3355 ms = haiku rerank, not BM25); 4d.4 built: /prune-memory STEP 1.D reads FEEDBACK.md for repo tag, noisy → title + lesson sentence rewrite (commit subjectnoisy-rewrite <ID>= idempotence token), promotion → BDR-100 mechanism proposal +memory.sh status <ID> "<current word>, promoted to <mechanism>". - Why: idle 44 % on short follow-ups ("ok on y va"); 3rd pick 35 %; user brief "resserrer, pas supprimer".
- Alternatives rejected: drop idle (user: tighten); index body (already done); add
promotedto_MEM_WORDS(classifier change for annotation only). - Residual: metricsOf has no fix-date split, pre-fix rows keep 3rd-pick + idle actions in later FEEDBACK.md (TODO); tool-channel noisy entries not fixed by title rewrite (body spans).
- Reference: feature/recall-gate1-fixes
7e87d77+ 39f9790; contract .claude/tasks/contracts/2026-11-12-recall-gate1-fixes-1830.md; plan r3; gates: 3 lenses (BLOCKER x3) + confirmation, GATE 0 MET, verifier ECARTS(2)→CONFORME x2, security PASS x2. See BDR-140, EVAL-058, BDR-100. - Status (2026-11-13): accepted, residual closed
9f9412a(block H5): precision/triggers/miss share post-fix only (cutoff = merged3d5e6c2026-11-12T19:53:59Z), actions wait for 20 post-fix asks, 3rd-pick signal retired, reminder waits for the post-fix sample
BDR-147 — D1b: the session digest is the TODO source at start; Actionable section else first 3 items, overflow marker [accepted] (2026-11-12)
- Decision: D1b: session digest = only TODO source at session start.
_digest_todoreads## Actionableor### Actionable(/^###? Actionable([ \t\r]|$)/), section empty/absent → file's first 3 top-level- [ ]items; headings + items inside<!-- -->ignored;- todo: +N not shown, read .claude/tasks/TODO.mdmarker when 800 cap drops todo lines (room reserved only on overflow). Seeds (init-project, capitalize:83 guarded, onboard STEP 9 fresh format) emit## Actionable+ comment. CLAUDE.global.md Session start step 1 no longer orders a TODO.md Read (digest carries it; no digest → read it). Local repos migrated insert-only: empty## Actionable+ comment under H1,chore/todo-actionableper repo. - Why: only this repo had
### Actionable; every other project's digest showed no TODO, so D1 kept the Read; a cap drop with no Read = silent loss → marker. - Alternatives rejected: move open items under Actionable per repo (conflicts: faunosteo feature branch edits TODO.md +231/-10, game +8); keep the Read forever (always-on cost D1 wanted gone); onboarder.md stub edited (FILE SCOPE; fallback covers it).
- Reference: feature/digest-todo-fallback
1124758+ 63bea87; contract .claude/tasks/contracts/2026-11-12-digest-todo-fallback-2130.md; 3 lenses CONCERNS (0 BLOCKER) → r2 → confirmation CONCERNS → r3; GATE 0 MET; verifier 5/6 MET + criterion 5 (make test) closed by orchestrator run; security PASS. Supersedes D1's "TODO.md stays read at start". See BDR-125.
BDR-148 — Design-toolchain hook retired: path rule + always-on pointer carry design routing; supersedes hook clauses of BDR-125 Am.7, BDR-130, BDR-098, BDR-021 [accepted] (2026-11-13)
- Context: block E (user 2026-11-12 "hook design : SUPPRIMER"). Measure 2026-10-31 (journal, TODO "Measure the design hook's re-Read cost"): 59 fires, 0 Reads of
rules/web-building.md, fires on non-design prompts. feature/design-hook-removal9c038fd. - Decision: hook
hooks/design-toolchain-reminder.sh+ its test + itsUserPromptSubmitentry deleted. Design routing carriers =rules/web-building.mdpath rule (component/style file edits) + one always-on CLAUDE.global.md line "Design / UI → Read web-building.md § Design work" (new-file turns the path rule misses). No replacement hook. - Why: hook cost one Bash per prompt, zero measured effect; path rule + pointer line already cover the trigger set. Fewer per-turn hooks = BDR-125 "no per-turn nag".
- Alternatives rejected: narrow the hook's signals (still 0 Reads measured, nothing proves a narrower set reads); keep as log-only (user data log
~/.claude/logs/design-toolchain-fires.logleft in place, no new writes). - Heading pin: only the "Design work" prefix stays pinned (CLAUDE.global.md citer, doctrine-citers census row
rules/web-building.md:Design work,_citers_resolveprefix match). Full heading "Design work — full toolchain" has no citer left; T7c (real hook fixture) → T8i synthetic one-line fixture, quoted label kept whole. - Supersedes / amends: BDR-125 Amendment 7 "hook one-liner" carrier clause; BDR-130 "hook one-liner says Read it" + "hook = pointer"; BDR-098 "design hook needs the section in context" + hook heading-match reference; BDR-021 Durability "design-toolchain-reminder.sh quotes it". Hand-off: open sessions log a non-blocking hook error per prompt until restarted.
BDR-149 — Skill routing section = gstack/pack cases only; our skills route by description (BDR-130 Deferred + BDR-125 phase 3 done) [accepted] (2026-11-13)
- Context: block E2 (user 2026-11-12 "lignes « Skill routing » → description: des skills"), BDR-130 Deferred + BDR-125 phase 3 bullet. feature/skill-routing-descriptions
3b30153. - Decision: CLAUDE.global.md § Skill routing keeps only what no description can carry: gstack counterweight (investigate on explicit ask only, bugs → bugfix; gstack ship retired BDR-105, ship/PR → ship-feature, deploy → deploy), document-release/doc fallback, Design pointer, plan-eng-review, superpowers aliases, pack-aware SEO/GEO/W3C line (
profile.sh enable seo|web-validate+/reload-plugins), cso, media pack, OFF paragraph covering every pack. Dropped: file-count split, tour, reconcile, capitalize/close (descriptions already say it). bugfix triggers += "error", "500", "stack trace + fix"; ship-feature += "ship this feature". 311 → 306 lines. - Why: skills route by description (listing always loaded); a doctrine line duplicating a description = always-on cost, zero routing gain. gstack injects its own "Bugs → /investigate" routing: the counterweight line must stay always-on (robustness challenge, 3 lenses r2).
- Alternatives rejected: drop every routing line (loses the gstack counterweight + pack-off remedy); "never gstack ship" text in ship-feature description (ship retired from every pack, lib/gstack-removed.list: dead text); trigger "open a PR" (no skill opens a PR).
- Accepted: description triggers not pinned by a test (darwin rewrite risk, MINOR); listing budget +~60 chars.
- Amends: BDR-130 Deferred item done; BDR-125 phase 3 "Skill routing table lines → descriptions" done.
BDR-150 — Fable = advisor only, never auto-routed; Opus heads best and big [accepted] (2026-11-16)
- Context: user 2026-11-16: Fable set as advisor (
/advisor, settingsadvisorModel: fable,bdbf1cd); "no auto-route on Fable, Opus = strongest model to auto-route; advisor called whenever a smarter agent is needed". feature/router-no-fable, contract.claude/tasks/contracts/2026-11-16-router-no-fable-1100.md, plan r3 after 2 challenge rounds. - Decision: DEFAULT_CONFIG tiers
bestandbig= ['opus','sonnet']; fable kept inmodelsand atfallback[0](capability rank: hand pick of fable ranks above opus, breaker never moves up to it). Row Change dialog (CHOICE_ALIASES) drops fable; bare /model keeps it ("fable (custom)"). Ask-before-Fable (askTier) fires only when alias heading best = fable (override); stored "instead" answers gate on fableHeadsBest;/route ask-tier onreplies inert. "tiers.best does not lead the fallback chain" log deleted. routing.json untouched (askTier "best"): mod runs live from tree, old-code sessions would route Fable unasked onaskTier: false. Agents floor = tier head (opus) for every tier. - Why: Fable reasoning now comes via advisor tool (server tool, hooks cannot see/refuse it); routing main/agents to Fable duplicated cost (BLK-030 credits) and ceiling logic.
- Alternatives rejected: tiers in tracked routing.json (new layer code, breaks machine-key doctrine); per-machine
~/.claude/model-router.json(not portable to work machine, near hard_deny mod clause); removing askTier feature (churn; kept dormant,shortcut:at TIER_HEAD); fable out offallback(appended last → hand-picked fable ranks below haiku); routing.jsonaskTier: false(live-install consent gap). - Residuals: opus outage → best/big agents spawn on held opus (gates fail, verify-secure retries then escalates; was move-up to Fable); single opus outage → sonnet stands in with effort notch; fable-baseline session (native Everywhere) demoted to opus per downgrade caps, sessionPin pins general-purpose to fable; skill row answering opus+xhigh in Change lands on
plan. Test rig: shipped tiers default,legacyTiers: trueon 47 fable-mechanics tests. - Gates: r1 3 lenses CONCERNS → r2 → re-challenge CONCERNS → r3; feater DONE 661 tests; GATE 0 MET; verifier CONFORME; security PASS (MEDIUM fixed: stored answer survives ask-tier off); commits
24b0f35, docs42385d2. - Refs: amends BDR-123, BDR-135; supersedes LRN-224; BLK-030, BDR-077 (Fable dispatch pins: separate run).
- Status (2026-11-17): accepted, completed: pins opus
beebfe2(gate row 'fixed at spawn' passes a pinned sub-agent), doctrinec3507ea(main loop calls advisor, sub-agents do not, absent advisor -> proceed, advice waives no gate) - Status (2026-11-17): accepted, amended
6ef3069: main loop named call points (before a skill's plan, once per verify-secure run at first gate loop failing twice, before merge); plan-challenger/verifier/security-auditor at most one call before verdict, advice add-only (security: STEP 3 class severity, no class -> REPORTED LOW); other sub-agents do not - Status (2026-11-17): accepted, amended
58a5273: plan point in lib/challenge-plan.md (on written plan before challengers, once per skill run, Advisor: row in CHALLENGE SUMMARY, no attribution in plan); stuck lines inline in verify-secure-loop (main-loop calls only since GATE 0); dispatched analyzer joins; trigger before recommending doctrine/architecture/public-interface change