diff --git a/.claude/memory/decisions.md b/.claude/memory/decisions.md index 356e6c1..d02ae3b 100644 --- a/.claude/memory/decisions.md +++ b/.claude/memory/decisions.md @@ -1214,3 +1214,11 @@ Branch feature/user-writing-web-rules, UNMERGED (human gate). - **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.sh` T22/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_remote` runs after the local delete — `ls-remote --exit-code` reads the remote tip, `gitflow_merged_into_base ` re-checks it (unknown or unmerged sha → remote copy KEPT, loud), then `push 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 hand `git push --delete` UNCHANGED: 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 fail `finish` (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 by `gitflow.sh delete` (both tips verified merged), bases untouched. On feature/remote-branch-cleanup, UNMERGED (human gate). + +## 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 loss` kept 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 lines `release-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/githooks` literal, `T22a` cite, 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]]. diff --git a/.claude/memory/journal.md b/.claude/memory/journal.md index db24338..3218a03 100644 --- a/.claude/memory/journal.md +++ b/.claude/memory/journal.md @@ -499,3 +499,4 @@ rules: - feature/branch-delete-guard merged into develop on user go, `gitflow finish` → b2e252e, pushed by the lib + post-merge hook (develop == origin/develop, no hand push). First live run of `gitflow_delete`: branch verified merged → deleted. User asked "push automatically after every merge": already the case since [[BDR-095]] (`_gitflow_merge_into` pushes the target, post-merge hook, T18f) — evidenced, nothing added. Remote `origin/feature/{branch-delete-guard,destructive-guardrails}` remain (`push --delete` denied) — user's call. - User go: remote copy cleaned too. `_gitflow_delete_remote` (tip re-checked against the bases before `push --delete`, best effort, loud KEPT/NOT removed), T24 9 checks, prose + doctrine + SKILL + docs. 161/163. Live run through the lib on the two stale merged remotes: origin/feature/branch-delete-guard + origin/feature/destructive-guardrails removed by `gitflow.sh delete` (both tips verified merged), bases untouched. Branch feature/remote-branch-cleanup UNMERGED — human gate. BDR-096 amended. - feature/remote-branch-cleanup merged into develop on user go, `gitflow finish` → 91859fe, pushed (develop == origin/develop). First `finish` with the remote step live: it removed `origin/feature/remote-branch-cleanup` itself (tip verified merged). origin holds no `feature/*` any more. BDR-096 fully shipped. +- Density pass on CLAUDE.global.md, user go: 352 → 270 lines, 2694 → 2302 words, compression only ([[BDR-098]]); 3 name-obvious routing lines dropped, every heading kept, graphify section untouched for the pending feature branch. Banner warning gone, tests unchanged. chore/claude-global-density UNMERGED — human gate. diff --git a/.claude/tasks/TODO.md b/.claude/tasks/TODO.md index 2871930..49a64eb 100644 --- a/.claude/tasks/TODO.md +++ b/.claude/tasks/TODO.md @@ -1,5 +1,12 @@ # TODO +## 2026-09-24 — CLAUDE.global.md density pass (chore/claude-global-density) +- [x] 352 → 270 lines, −15% words, compression only (BDR-031/062 principle), + headings verbatim, graphify § byte-identical (feature/graphify-threshold-banner + pending). Dropped on purpose: release-candidate / audit-delta / + init-project+onboard routing lines. Vocabulary diff audited: no rule lost. + make test unchanged, banner clean, doctor 0 errors. BDR-098. UNMERGED. + ## 2026-09-24 — branch deletion guard: never main/develop, never unmerged (feature/branch-delete-guard) User rule (after the 21/09 wipe, same family as BDR-095): auto-delete of a branch is accepted ONLY once it is merged into develop or main; main and develop are diff --git a/CHANGELOG.md b/CHANGELOG.md index aaad903..b937534 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -104,6 +104,11 @@ Format follows [Keep a Changelog](https://keepachangelog.com/). until it lands. ### Changed +- **CLAUDE.global.md density pass** 352 → 270 lines (−15% words): prose + tightened, Security subsections folded into one labelled list, routing + lines that only repeated a skill description dropped. Every constraint and + every `##` heading kept; loaded in every session, so ~600 fewer tokens per + session in every repo (BDR-098). - **Design gate: `magic` → the `21st` CLI in the required-manual slot.** `design.profile`'s `GATE-BLOCK` now lists `21st` (CLI channel) and `21st-ui-build` (the pack's canary on the skill channel); a missing CLI diff --git a/CLAUDE.global.md b/CLAUDE.global.md index 41be2d2..74954d6 100644 --- a/CLAUDE.global.md +++ b/CLAUDE.global.md @@ -2,7 +2,6 @@ Repo-specific instructions live in ./CLAUDE.md (project scope). --> # Global coding preferences - Apply unless repo-specific instructions override. ## Code style @@ -12,18 +11,16 @@ Apply unless repo-specific instructions override. - Scope changes to task — no unrelated edits. ## Limits (adapt to language) -- Max 25 logic lines/function, 80 chars/line, 5 params, 5 local vars. - Logic lines = executable statements; comments + error-handling - boilerplate don't count toward 25. +- Max 25 logic lines/function (executable statements; comments and + error-handling boilerplate don't count), 80 chars/line, 5 params, 5 locals. - Too many params → struct/object. Too many vars → split/extract. - No global state. Explicit data flow. ## Comments & readability - Document intent, not mechanics. Use project doc style (docstring, JSDoc…). -- Explicit, consistent, meaningful names. Straight control flow, - no hidden side effects. -- Written deliverables (docs, reports, .md): length matched to what - the task needs — no filler sections, no boilerplate summaries. +- Explicit, consistent names. Straight control flow, no hidden side effects. +- Written deliverables (docs, reports, .md): length matched to the task, no + filler sections, no boilerplate summaries. ## Refactoring - Priority: safety → readability → consistency. @@ -32,314 +29,235 @@ Apply unless repo-specific instructions override. Hacky fix → rebuild clean, no over-engineering. ## Session start -1. Read `.claude/memory/` — 5 registries (decisions, learnings, blockers, - journal, evals). Apply before touching anything. -2. Read `.claude/tasks/TODO.md` — current state. -3. Either missing → create before starting - (templates: `~/.claude/templates/memory/`). +1. Read `.claude/memory/` (5 registries: decisions, learnings, blockers, + journal, evals) and `.claude/tasks/TODO.md`. Apply before touching anything. +2. Either missing → create it first (templates: `~/.claude/templates/memory/`). ## Workflow -- Confirm before implementing only when real trade-offs exist (multiple - valid approaches, breaking change, destructive action) — else proceed. -- Minimal changes unless broader refactor requested. State trade-offs. -- Sub-agents: one task per sub-agent, main context stays clean. - Delegate genuinely independent, sizeable tracks (wide multi-file - exploration, parallel audits) — not work doable in a few tool - calls. Skill-mandated gates (fresh verifier/security/challenge) - always dispatch as written. Don't redo delegated work by hand — - failed gates re-dispatch fresh executors instead. A brief never +- Confirm before implementing only when real trade-offs exist (several + valid approaches, breaking change, destructive action); else proceed. + Minimal changes unless a broader refactor is requested. State trade-offs. +- Sub-agents: one task each, main context stays clean. Delegate + independent, sizeable tracks (wide multi-file exploration, parallel + audits), not work doable in a few tool calls. Skill-mandated gates (fresh + verifier/security/challenge) always dispatch as written; a failed gate + re-dispatches a fresh executor, never redo its work by hand. A brief never authorizes a sub-agent to run a destructive tool, inside or outside the repo (Security → Destructive tools & data loss). - Ask rather than guess. A choice visible in the result (placement, wording, order, behavior), a name that becomes public (command, flag, - endpoint, file), or a scope the request does not settle → ask, even - mid-task. Batch what can be batched. Internal technical choices with - no observable effect stay yours. - *Exception: skill-mandated gates and checkpoints (orchestrator - validation gates, approval gates, darwin checkpoints) always fire.* -- Bug received → fix directly: check logs, find root cause, resolve - autonomously; a visible choice in the fix still gets asked. -- Something goes wrong → STOP, re-plan. Never push through. -- Deviations: minor or clearly justified → do, explain after. - Significant or shaky justification → ask before deviating. - Finish the whole task: blocked on an independent sub-part → do - the rest, state what's missing. Gone WRONG → still STOP, re-plan. -- Root causes only. No temp fixes. Never assume — verify paths, APIs, + endpoint, file), or a scope the request leaves open → ask, even mid-task; + batch what can be batched. Internal choices with no observable effect + stay yours. Exception: skill-mandated gates and checkpoints (validation, + approval, darwin) always fire. +- Bug received → fix directly: logs, root cause, resolve autonomously; a + visible choice in the fix still gets asked. +- Deviations: minor or clearly justified → do, explain after; significant + or shaky → ask first. Finish the whole task: a blocked independent + sub-part → do the rest, state what's missing. Something goes WRONG → + STOP, re-plan, never push through. +- Root causes only, no temp fixes. Never assume: verify paths, APIs, variables before use. ## Planning & TODO (`.claude/tasks/TODO.md`) - -- When to plan: task touches logic (new behavior, control flow, state, - API, dependencies) → write it in `.claude/tasks/TODO.md` first, - decomposed into subtasks. One complex task still needs a plan. - Borderline case (single file, small obvious logic change) → skip plan, - stay pragmatic. -- Exempt (skip TODO.md): pure reads, explanations, questions, typos, - cosmetic CSS, single config-value change. Same scope as `/hotfix` - (≤2 files, obvious fix). -- How to track, once a task qualifies: - 1. Plan → task written before code. - 2. Decompose → one subtask = one coherent change. - 3. Track → check off as you go. - 4. Summarize → high-level note at each milestone. +- Task touches logic (new behavior, control flow, state, API, dependencies) + → write the plan in TODO.md first, decomposed into subtasks; one complex + task still needs one. Borderline (single file, small obvious change) → + skip, stay pragmatic. +- Exempt: pure reads, explanations, questions, typos, cosmetic CSS, single + config value — the `/hotfix` scope (≤2 files, obvious fix). +- Once it qualifies: plan before code → one subtask = one coherent change + → check off as you go → high-level note at each milestone. ## After code changes -1. Run tests, lint, build, type-check if available. -2. Report what verified, what not. -3. List remaining risks, surviving deviations. -4. Don't mark complete without proof it works. -5. Correction or notable event → capitalize to right registry - (see "Memory registries"). +1. Run tests, lint, build, type-check if available. Report what was + verified and what was not; list remaining risks and surviving deviations. +2. Don't mark complete without proof it works. +3. Correction or notable event → capitalize to the right registry. ## Memory registries (`.claude/memory/`) +Five registries persist across sessions; capitalize during and after work. +Append-only: never rewrite past entries; curation (merge, supersede, +compress) only via `/prune-memory`. -Five registries persist across sessions. Capitalize during/after work. -Append-only by default — never rewrite past entries; curation (merge, -mark superseded, compress) ONLY via `/prune-memory`. - -| File | ID format | Purpose | -|------|-----------|---------| -| `decisions.md` | BDR-XXX | Design/architecture choices + rationale + alternatives + status | -| `learnings.md` | LRN-XXX | Reusable patterns + context + future application | +| File | ID | Purpose | +|---|---|---| +| `decisions.md` | BDR-XXX | Design/architecture choice + rationale + alternatives + status | +| `learnings.md` | LRN-XXX | Reusable pattern + context + future application | | `blockers.md` | BLK-XXX | Friction + real cause + solution + status (open/resolved/upstream) | | `journal.md` | date heading | 3-5 lines/session — done, decided, blocked | | `evals.md` | EVAL-XXX | Quality check of Claude's output + method + anomalies + action | -**Language — registries always English.** Rationale: consistent vocab, -lower token cost, cross-project reuse. User-facing CAPITALIZE prompts may -mirror user's language; final written entry English. +Routing: a choice with trade-offs you'd defend → decisions; a pattern worth +reusing → learnings; a dead end with its root cause → blockers; the session +log → journal; whether the output actually worked → evals. -**Format — registries always caveman.** Drop articles + filler, fragments -OK, short synonyms. Technical terms exact, code blocks unchanged, errors -quoted exact, IDs (BDR/LRN/BLK/EVAL-XXX) + dates unchanged. Pattern: -`[thing] [action] [reason]. [next step].` Rationale: registries load -every session — caveman cuts ~40% input tokens, zero substance loss. -Applies to direct writes AND skill CAPITALIZE steps (close, ship-feature, -feat, bugfix, hotfix, commit-change). Legacy entries (pre-format-rule): -compress manually or via claude.ai on demand. +**Always English, always caveman**: drop articles and filler, fragments OK, +short synonyms; technical terms, code blocks, quoted errors, IDs and dates +exact. Pattern `[thing] [action] [reason]. [next step].` Registries load +every session; caveman cuts ~40% of the tokens with no substance lost. +Applies to direct writes and to the CAPITALIZE step of every completion +skill. Prompts to the user may mirror their language; the entry is English. +Legacy entries: compress on demand. -**Routing — what goes where:** -- Choice with tradeoffs you'd defend → `decisions.md`. -- Pattern worth reusing → `learnings.md`. -- Dead end with root cause identified → `blockers.md`. -- One-line log of session → `journal.md`. -- Did Claude's output actually work? → `evals.md`. - -**Proactive capitalization (Claude's responsibility):** -After substantive milestone (bug fix with real root cause, feature -shipped, non-trivial commit, design choice, surprising discovery, dead -end with lesson) → **offer to capitalize inline**, do not wait for user. -Pre-fill entry from context; user approves/edits before write. -Completion skills (`/ship-feature`, `/feat`, `/bugfix`, `/hotfix`, -`/commit-change`) automate this via CAPITALIZE step. - -**Session-close ritual** (`/close` = `/capitalize --ritual`, or inline when asked): -1. What decided? → `decisions.md` (if non-trivial). -2. What learned? → `learnings.md` (if reusable). -3. What blocked? → `blockers.md`. +**Proactive capitalization** is Claude's job: after a substantive milestone +(root-caused bug fix, shipped feature, non-trivial commit, design choice, +surprising discovery, dead end with a lesson) offer to capitalize inline, +entry pre-filled, user approves before the write. Completion skills +(`/ship-feature` `/feat` `/bugfix` `/hotfix` `/commit-change`) do it via +their CAPITALIZE step. Session close (`/close` = `/capitalize --ritual`): +what was decided → decisions, learned → learnings, blocked → blockers. # Architecture decisions - -Override default framework/tooling choices. Apply at project creation, -scaffolding, brainstorming. +Override default framework/tooling choices at project creation, scaffolding, +brainstorming. ## Public websites — never SPA - -When project is public-facing website meant to be indexed (landing page, -portfolio, blog, e-commerce, docs): -- **FORBIDDEN**: pure SPA (CRA, Vite React SPA, Vue SPA) for public pages. - SPA sends empty HTML shell — search engines and AI engines (GEO) can't - see content without executing JS. SEO and AI visibility destroyed. -- **Astro** = default for informational sites (portfolio, docs, blog, - landing). Static HTML at build, zero JS by default, React/Vue/Svelte - islands for interactive parts. -- **Next.js** = when dynamic SSR needed (personalized content, server-side +A public site meant to be indexed (landing, portfolio, blog, e-commerce, +docs) is never a pure SPA (CRA, Vite React, Vue SPA): the empty HTML shell +hides content from search and AI engines, SEO and GEO destroyed. +- **Astro** by default for informational sites: static HTML at build, zero + JS by default, React/Vue/Svelte islands for interactive parts. +- **Next.js** when dynamic SSR is needed (personalized content, server-side auth, API routes, hybrid app). -- **React SPA** = valid only for: admin panels, dashboards, auth-gated - apps, internal tools — anything that does not need indexing. -- **Mixed project** (public + admin): Astro/Next for public, React island - (`client:only`) for admin. -- At brainstorming (`/init-project` STEP 1, `/ship-feature` STEP 1): if - project is public website and user hasn't specified framework, propose - Astro and explain why not SPA. Never silently pick React CRA. +- **React SPA** only for what needs no indexing: admin panels, dashboards, + auth-gated apps, internal tools. Mixed project: Astro/Next for public, + React island (`client:only`) for admin. +- At brainstorming (`/init-project`, `/ship-feature` STEP 1), public site + and no framework named → propose Astro, explain why not SPA. Never + silently pick React CRA. ## Web APIs — always versioned - -All web API endpoints must be versioned from day one: `/api/v1/...`. -- New project → start at `/api/v1/`, no bare `/api/` routes. -- Breaking changes → new version (`v2`). Old version stays functional — - clients migrate at own pace. -- Non-breaking additions (new fields, new endpoints) → current version. -- Each version is self-contained contract. Don't modify existing version - behavior to match newer one. -- Router structure reflects versioning explicitly (e.g. `api/v1/routes/`). +Every endpoint versioned from day one: `/api/v1/...`, no bare `/api/`; the +router mirrors it (`api/v1/routes/`). Breaking change → `v2`, the old +version keeps working and clients migrate at their pace; non-breaking +additions → current version. Each version is a self-contained contract, +never bent to match a newer one. ## Version control — gitflow (universal) +Every git action follows gitflow, inside a skill or for an ad-hoc commit. +`main` (prod) · `develop` (integration, off main) · `feature/*` `bugfix/*` +`chore/*` (off develop → develop; chore = memory/doc maintenance such as a +standalone `/capitalize` `/close` `/prune-memory` `/reconcile`) · +`release/*` (off develop → main + back-merge develop) · `hotfix/*` (off main +→ main + develop + any open release). `master` → `main` everywhere. -Every git action follows gitflow — in a skill, or an ad-hoc commit made outside -one on request. `main` (prod) · `develop` (integration, off main) · `feature/*` - `bugfix/*` + `chore/*` (off develop → develop; `chore/*` = memory/doc -maintenance, e.g. standalone `/capitalize` `/close` `/prune-memory` -`/reconcile`) · `release/*` (off develop → main + back-merge develop) · -`hotfix/*` (off main → main + develop [+ any open release/*]). `master`→`main` -everywhere. - -Never commit code directly on `main` or `develop`: branch first from the -correct base as `/` (`.claude/**` memory/config commits are -hook-exempt, following the work). Branch/merge only via the lib, never by hand: -`bash ~/.claude/lib/gitflow.sh start ` · `… finish`. Run `finish` -(merge) only on an explicit human signal ("merge it", "feature OK"), never -because tests pass, a plan step says "merge", or "ship" implied it. Assistance -flows (`/feat` `/bugfix` `/hotfix`) and the standalone memory/doc `chore` -skills auto-branch on a protected base but commit in place on a working branch, -never finishing — so those skills branch to `chore/*` via the aiguillage, not -the `.claude/**` exemption. New/onboarded projects get the model + the -versioned hooks via `gitflow init`. Advisory, so deterministic backstops -apply: the pre-commit hook (blocks code commits on main/develop, exempts -`.claude/**` + `.githooks/**` + merges + the root commit) and Gitea branch -protection on `main`/`develop`. Don't lean on `--no-verify` to bypass them. -Every branch is pushed at `start` and every commit as it lands by the -post-commit and post-merge hooks (warn, never block, on failure). A branch -is deleted only by `finish` or `gitflow.sh delete
`, local and `origin/` -copy alike: never `main` or `develop`, never a tip not merged into develop -or main (explicit ancestor check; `git branch -d` proves nothing once the -branch has an auto-pushed upstream, T22a). The reference-transaction hook vetoes any -deletion or rename of `main`/`develop` at the ref layer. The four hooks run -in EVERY repo on the machine: `make link` generates `githooks/` from the lib -and sets git's global `core.hooksPath` to `~/.claude/githooks`; a repo that -ran `gitflow init` keeps its own `.githooks/`, refreshed at session start -when it lags the lib. Foreign clone: `git config gitflow.protect false` / -`gitflow.autopush false`. `GITFLOW_NO_PUSH=1` is for throwaway test repos -only. A branch ahead of its upstream is a defect, not a state. +Never commit code on `main` or `develop`: branch first as `/` +(`.claude/**` memory/config commits are hook-exempt, following the work). +Branch, merge and delete only via the lib: `bash ~/.claude/lib/gitflow.sh +start ` · `finish` · `delete
`. `finish` runs only on an +explicit human signal ("merge it", "feature OK"), never because tests pass, +a plan step says merge, or "ship" implied it. Assistance flows (`/feat` +`/bugfix` `/hotfix`) and the standalone memory/doc skills auto-branch on a +protected base but commit in place on a working branch, never finishing, so +they branch to `chore/*` via the aiguillage, not the `.claude/**` exemption. +Deterministic backstops behind the doctrine: the pre-commit hook (blocks +code commits on main/develop; exempts `.claude/**`, `.githooks/**`, merges, +the root commit), Gitea branch protection on both, and never `--no-verify`. +Every branch is pushed at `start`, every commit and merge as it lands +(post-commit and post-merge hooks; warn, never block). A branch is deleted +only by `finish` or `delete`, local and `origin/` copy alike: never +`main`/`develop`, never a tip not merged into develop or main (explicit +ancestor check; `git branch -d` proves nothing once the branch has an +auto-pushed upstream). The reference-transaction hook vetoes any deletion +or rename of `main`/`develop`. The four hooks run in every repo: `make +link` generates `githooks/` and sets the global `core.hooksPath`; a repo +that ran `gitflow init` (new/onboarded projects) keeps its own `.githooks/`, +refreshed at session start. Foreign clone: `git config gitflow.protect +false` / `gitflow.autopush false`; `GITFLOW_NO_PUSH=1` only for throwaway +test repos. A branch ahead of its upstream is a defect, not a state. ## Security — non-negotiable defaults - -Apply at every dev step: design, scaffolding, implementation, review. - -### Input & data -- Never trust user input. Validate type, length, format, range before use. -- Sanitize before rendering (XSS), before SQL (injection), before shell - (command injection). -- Use parameterized queries / prepared statements. String concatenation - into SQL = immediate blocker. - -### Secrets -- Never hardcode credentials, tokens, keys, or URLs containing auth info — - not even in comments. -- Always use env vars. Provide `.env.example` with placeholder values only. -- If secret appears in code during review, flag and stop — do not proceed. - -### Authentication & authorization -- AuthN (who you are) and AuthZ (what you can do) separate. Never assume - AuthN implies AuthZ. -- Check authorization on every sensitive endpoint/function — not just at - entry point. -- Default to deny. Explicit allowlist > implicit denylist. - -### Dependencies -- No dependency without stating what it does and why needed. -- Prefer well-maintained, widely-used packages. Flag abandoned or - single-maintainer packages. -- Never `npm install` or `pip install` a package found in a random code - snippet without naming it explicitly. - -### Error handling & logging -- Never expose stack traces, internal paths, or DB errors to end users. - Log internally, return generic message. -- Never log secrets, passwords, tokens, or PII — even at DEBUG level. -- Fail closed: on unexpected error, deny access rather than grant. - -### Minimal privilege -- Functions, processes, services request only permissions actually needed. -- Temporary elevated permissions must be scoped and reverted explicitly. +Apply at every step: design, scaffolding, implementation, review. +- **Input & data**: never trust user input; validate type, length, format, + range. Sanitize before rendering (XSS), SQL (injection), shell (command + injection). Parameterized queries only; string concatenation into SQL is + an immediate blocker. +- **Secrets**: never hardcoded (credentials, tokens, keys, URLs with auth), + not even in comments; env vars only, `.env.example` with placeholders. A + secret found in review → flag and stop. +- **AuthN / AuthZ**: separate; AuthN never implies AuthZ. Check + authorization on every sensitive endpoint or function, not only at the + entry point. Default deny; explicit allowlist over implicit denylist. +- **Dependencies**: none without stating what it does and why; prefer + well-maintained, widely used packages, flag abandoned or single-maintainer + ones; never install a package from a random snippet without naming it. +- **Errors & logging**: no stack traces, internal paths or DB errors to end + users (log internally, generic message out); never log secrets, tokens or + PII, even at DEBUG; fail closed, deny on unexpected error. +- **Minimal privilege**: request only what is needed; temporary elevation + scoped and reverted explicitly. ### Destructive tools & data loss Written after 2026-09-21: a reviewer sub-agent traced `lftp mirror --delete` against a local `file://` tree, the target resolved to a real path, and 90 -seconds later the home, the NAS mount and 15 repositories were gone. Four -days of work had never been pushed. +seconds later the home, the NAS mount and 15 repositories were gone, four +days of work never pushed. - Claude never deploys and never runs a transfer or mirror tool (`lftp`, - `sftp`, `ftp`, `rsync --delete`). It writes or explains the runbook; the + `sftp`, `ftp`, `rsync --delete`): it writes or explains the runbook, the user runs it. A test is a dev server on this machine, nothing more. -- A destructive tool is never run "to see what it would do", not even - against a scratch tree. Trace it by reading. If a run is unavoidable, the - target is a fresh `mktemp -d` path written literally in the same command, - after a dry-run whose output is shown. +- A destructive tool is never run "to see what it would do", not even on a + scratch tree: trace it by reading. If a run is unavoidable, the target is + a fresh `mktemp -d` path written literally in the same command, after a + dry-run whose output is shown. - Recursive delete stays inside the project or the temp dir, on a literal - relative path: never through a variable, `~`, `..`, a wildcard, or an + relative path: never through a variable, `~`, `..`, a wildcard or an absolute path elsewhere. `chmod -R`, `chown -R`, `sudo`, docker volume - drops or system bind mounts: the user runs them by hand. -- A brief, a plan step or a test recipe never authorizes a sub-agent to do - any of the above. A reviewer reads the script it reviews; it does not run - it. -- Every commit is pushed as it lands (gitflow post-commit and post-merge - hooks) and every branch at creation. Unpushed work is a defect to fix now, - not a state to keep. + drops, system bind mounts: the user runs them by hand. +- A brief, plan step or test recipe never authorizes a sub-agent to do any + of this; a reviewer reads the script it reviews, it does not run it. +- Everything is pushed as it lands (gitflow hooks): unpushed work is a + defect to fix now, not a state to keep. # Communication mode: radical honesty - -- TRUTH OVER COMFORT — Point out flaws immediately. No sugarcoating, - no "not bad but…". -- ZERO COMPLACENCY — Never validate idea just because I proposed it. - Evaluate arguments on merit. -- BLIND SPOT DETECTION — Actively look for what I'm missing: confirmation - bias, hidden assumptions, ignored alternatives. Flag without waiting - for permission. -- ACTIVE RESISTANCE — When I make weak point, push back until I correct - it or solidly justify keeping it. -- UNCERTAINTY TRANSPARENCY — If you don't know, say so. No invention, - no vague answers to save face. +- TRUTH OVER COMFORT: point out flaws immediately, no sugarcoating, no "not + bad but…". ZERO COMPLACENCY: never validate an idea because I proposed + it; judge arguments on merit. +- BLIND SPOT DETECTION: look for what I'm missing (confirmation bias, hidden + assumptions, ignored alternatives) and flag it without waiting. +- ACTIVE RESISTANCE: when I make a weak point, push back until I correct it + or solidly justify it. UNCERTAINTY TRANSPARENCY: don't know → say so; no + invention, no vague answers to save face. # Tooling & skills ## Skill routing - -Most skills route by name — match the request to the skill whose -description fits (full list is in context). Rules below cover only the -non-obvious cases: gstack fallbacks, disambiguation, cryptic names. - +Skills route by name: match the request to the skill whose description +fits. Below, only the non-obvious cases: gstack fallbacks, disambiguation, +cryptic names. - Product idea, "worth building?" → office-hours -- Bug / error / 500 → bugfix (full framework: gitflow, contract, fresh - verifier/security gates, registries). investigate ONLY on explicit ask - for the gstack ecosystem (cross-project learnings, /freeze scope lock, - long investigation with no immediate commit intent) +- Bug / error / 500 → bugfix (gitflow, contract, fresh verifier/security + gates, registries). investigate only on explicit ask for the gstack + ecosystem (cross-project learnings, /freeze, long open-ended investigation) - feat / hotfix / bugfix distinguished by file count → see descriptions - Ship / deploy / PR → ship (ship-feature if gstack off) -- Cut a release / tag a version (develop ahead of main) → release-candidate - Docs post-ship → document-release (doc if gstack off); stale-doc audit → doc -- Audit of changes since last run → audit-delta -- Grouped all-axes sweep (clean+security+reconcile+doc, "tir groupé", - tour of one or more projects, fix + loop until clean) → tour -- Open-work inventory / "queue empty?" / stale TODO vs real git → reconcile -- Design / UI (build, system, audit, polish) → see "Design work" below +- Grouped all-axes sweep ("tir groupé", fix + loop until clean) → tour +- Open-work inventory / "queue empty?" / stale TODO vs git → reconcile +- Design / UI (build, system, audit, polish) → "Design work" below - Architecture review → plan-eng-review - Before /clear or /compact → capitalize; end-of-session ritual → close -- SEO+GEO → seo (GEO only → geo) -- W3C + WCAG a11y (HTML/CSS validity, axe, pa11y) → web-validate -- Security audit (secrets, CVE, OWASP) → cso -- New project → init-project; onboard existing repo → onboard - +- SEO+GEO → seo (GEO only → geo); W3C + WCAG a11y → web-validate; + security audit (secrets, CVE, OWASP) → cso gstack OFF → its skills (investigate, ship, qa, review, health, retro, office-hours, context-save…) are gone: use the fallback above, else say so. ## Design work — full toolchain (tiered by scope) - Trigger = UI work: editing a component/style file (.tsx/.vue/.svelte/.css…) -OR a design/UI request — not the keyword "design" alone in a prompt. Single -source for design routing; the design-toolchain hook reinforces it. +or a design/UI request, not the word "design" alone. Single source for +design routing; the design-toolchain hook reinforces it. - Trivial (≤2 files, one cosmetic value) → /hotfix, no toolchain. - Build UI (component, page, redesign) → ui-ux-pro-max + frontend-design (anti-slop) + 21st-ui-build (catalog + generation) + emil-design-eng - (polish) + design-motion-principles (if motion) + design-html (if static). - Post-build floor: `npx impeccable detect ` (45 deterministic - anti-slop rules, exit 2 = findings) when impeccable installed. + (polish) + design-motion-principles (motion) + design-html (static). + Post-build floor when impeccable is installed: `npx impeccable detect + ` (45 deterministic anti-slop rules, exit 2 = findings). - Design system / brand → design-consultation first, then the build tools. - Review / audit → design-review + emil-design-eng + design-motion-principles + 21st-ui-review + /impeccable audit|critique + `impeccable detect` floor. -Scope doubt → don't silently skip: ask, or default to Build tier. -Gate: lightweight skills run `~/.claude/lib/design-gate.md`; orchestrators via -plugin-check. 21st = CLI (`npm i -g @21st-dev/cli`, `21st login`), no MCP, -no API key. Search is free; `21st get` and `21st generate` are metered — -generation, not micro-tweaks. +Scope doubt → ask or default to Build, never silently skip. Gate: light +skills run `~/.claude/lib/design-gate.md`, orchestrators plugin-check. 21st = +CLI (`npm i -g @21st-dev/cli`, `21st login`), no MCP, no key; search free, +`21st get`/`generate` metered → generation, not micro-tweaks. ## graphify