docs: /a11y and the injection and exposure domains in README, USAGE, CHANGELOG; routing boundaries (web-validate, seo, harden, global line, interviewer)

This commit is contained in:
bchanot committed 2026-10-19 00:52:23 +02:00
1 parent fe0b229efc
commit 0de2e8a48a
8 files changed
+20 -14

No files matched your search

+2 -1
View File
@@ -7,7 +7,8 @@ Format follows [Keep a Changelog](https://keepachangelog.com/) and this project
## [Unreleased]
### Added
- **Secure-by-default guardrails**: `rules/secure-by-default.md` (always on) makes five domains baseline on every project, plus systematic API and access hygiene (auth on every route, CORS, secrets, passwords hashed with argon2id or bcrypt, never compared in clear, logged or hardcoded): hosting (rate limit, CDN and firewall, hard spend cap), accessibility (keyboard, visible focus, alt text, field labels), Supabase (RLS on every table, owner-scoped policies, no service role key client-side), SMS and email (recorded consent, unsubscribe, STOP), cloud functions (no self-trigger, instance cap, budget stop). `/guardrails` audits them: a stdlib Python scanner (`skills/guardrails/scripts/scan.py`, FAIL / WARN / MANUAL, exit 1 on FAIL) then judgment, report in `.claude/audits/GUARDRAILS.md`. The security-auditor gate runs the scanner's `api` and `supabase` domains and blocks on FAIL. Items only a provider dashboard can set stay MANUAL, never claimed done. An optional read-only live probe (`skills/guardrails/scripts/probe.py`, `--live`) confirms a finding from outside on a target the user owns and names: anon-read, cross-user, no-auth route, CORS reflection and a capped rate-limit burst, verdicts OPEN / CLOSED / SKIPPED / ERROR. It sends GET, HEAD and OPTIONS only (one opt-in POST burst, capped at 25), requires `--authorized`, takes secrets from the environment never the command line, never follows a redirect to another host, and stops at a request budget. After the report, `/guardrails` proposes fixes (plan phase, so Fable when the router can switch), applies only the ones the user accepts through the `bugfixer` executor and the `lib/verify-secure-loop.md` gates, then re-scans: each accepted fix is a contract criterion whose oracle is the scanner (`--assert-absent RULE:path`, marker `GUARDRAILS-CLEAR`), and a full pass against the pre-fix baseline (`--baseline`, marker `GUARDRAILS-NO-NEW`) catches regressions; a live probe replays on the user's go; two rounds at most, residuals reported open; `--report-only` keeps the audit alone. Suites: `lib/tests/guardrails-scan.test.sh` (clean fixture plus one mutant per rule, check modes, `gates.sh` integration) and `lib/tests/guardrails-probe.test.sh` (probe logic against a localhost fixture server).
- **Secure-by-default guardrails**: `rules/secure-by-default.md` (always on) makes six domains baseline on every project, plus systematic API and access hygiene (auth on every route, CORS, secrets, passwords hashed with argon2id or bcrypt, never compared in clear, logged or hardcoded): hosting (rate limit, CDN and firewall, hard spend cap), Supabase (RLS on every table, owner-scoped policies, no service role key client-side), SMS and email (recorded consent, unsubscribe, STOP), cloud functions (no self-trigger, instance cap, budget stop), injection (bound values in raw escapes, `format()` for dynamic SQL, allowlisted filters, no shell into a DB tool), exposure (no data in the console, no production source map, no debug flag, no secret in hydrated state, data attributes, hidden fields or shipped comments). `/guardrails` audits them: a stdlib Python scanner (`skills/guardrails/scripts/scan.py`, FAIL / WARN / MANUAL, exit 1 on FAIL) then judgment, report in `.claude/audits/GUARDRAILS.md`. The security-auditor gate runs the scanner's `api` and `supabase` domains and blocks on FAIL. Items only a provider dashboard can set stay MANUAL, never claimed done. An optional read-only live probe (`skills/guardrails/scripts/probe.py`, `--live`) confirms a finding from outside on a target the user owns and names: anon-read, cross-user, no-auth route, CORS reflection and a capped rate-limit burst, verdicts OPEN / CLOSED / SKIPPED / ERROR. An `exposure` block in the plan adds three read-only probes, meant for a production build or a staging URL: a served or inline source map for the page's scripts, a stack trace in a 404 or a user-named error route, sensitive keys in a JSON response (identifier-shaped names printed, never values); a target the probe could not observe is SKIPPED or ERROR, never CLOSED, and every plan path must start with `/`. It sends GET, HEAD and OPTIONS only (one opt-in POST burst, capped at 25), requires `--authorized`, takes secrets from the environment never the command line, never follows a redirect to another host, and stops at a request budget. After the report, `/guardrails` proposes fixes (plan phase, so Fable when the router can switch), applies only the ones the user accepts through the `bugfixer` executor and the `lib/verify-secure-loop.md` gates, then re-scans: each accepted fix is a contract criterion whose oracle is the scanner (`--assert-absent RULE:path`, marker `GUARDRAILS-CLEAR`), and a full pass against the pre-fix baseline (`--baseline`, marker `GUARDRAILS-NO-NEW`) catches regressions; a live probe replays on the user's go; two rounds at most, residuals reported open; `--report-only` keeps the audit alone. Suites: `lib/tests/guardrails-scan.test.sh` (clean fixture plus one mutant per rule, check modes, `gates.sh` integration) and `lib/tests/guardrails-probe.test.sh` (probe logic against a localhost fixture server).
- **/a11y skill**: accessibility leaves `/guardrails` and becomes its own skill. Same A11Y-* rules (img alt, field label, click without keyboard, focus outline removed, positive tabindex) on the shared scan engine (`skills/guardrails/scripts/scanner.py`, a `Catalogue` per CLI; `skills/a11y/scripts/scan.py`, markers `A11Y-CLEAR` / `A11Y-NO-NEW`), a Tab-only walk of the main flow on `--live` through `/browse` (marked not done otherwise), report `.claude/audits/A11Y.md`, fixes proposed with the alt and label wording as the user's choice, applied through the bugfix circuit (`bugfixer`, verify-secure gates, `bugfix/a11y-<date>`), re-pass against a baseline. The keyboard, alt and label doctrine moves from `rules/secure-by-default.md` to the lazy `rules/a11y.md` (loads on UI files only; `rules/web-building.md` points at it). `/guardrails` scans `injection` (INJ-*) and `exposure` (EXP-*) instead, with per-language SQL patterns, shared `code_files` / `hits` / `dedupe_lines` / `client_reachable` helpers and a walker that lists files over 1 MB by path; `--domain a11y` is a usage error there. `/web-validate` keeps full WCAG conformance. Suite `lib/tests/a11y-scan.test.sh`; routing row `reflect`; profiles audit, dev, web, web-full, full, max.
- **model-router mod**: `mods/model-router/`, a Claude Code mod (function-hooks plugin), routes every repo skill and agent from phase rows (`plan`, `reflect`, `orchestrate`, `escalate`, `judge`, `implement`, `write`, `verify`, `explore`, `apply`, `mechanical`; built-ins Explore on sonnet/medium, Plan on opus/xhigh). A typed skill routes the main loop to its row, and a best-tier row holds across turns in a run slot until `/route clear`, `/route off`, a user `/model` or a typed skill on a non-best row. Agents get their row's model at spawn (within the tier, upward only) and its effort on every step; explicit Agent params win. Orchestrators declare their phases through the `mcp__model-router__route` tool. `ultrathink` in a prompt sets the turn's minimum effort and `/route effort=max` holds until `/route clear`; the built-in `/effort` is not a lever inside a run. `/route show` names the run slot (`main: run <phase>`), and a `null` row in the override drops a default row. The model gets a `route` tool and the user a `/route` command (`show|clear|off|on|reload|pending|ask on|off|forget <name|all|projects>|<phase>|model=<alias|id> effort=<level>|switch on|off|verbose on|off`). Optional per-machine config `~/.claude/model-router.json`, where `"enabled": false` turns it off on that machine. The spinner suffix and the status line show the route in force. It loads in every session through the tracked symlink `skills/model-router` (`model-router@skills-dir`). `make doctor` gains a Mods section; suite `make test suite=lib/tests/mods.test.sh`. Known limits: a main-loop switch runs only while the cold read it costs (the context minus what the target model's prompt cache holds) fits `upgradeMaxTokens` (200000) or `downgradeMaxTokens` (120000), and a downgrade also needs `mainModelSwitch` (on by default, off on any non-boolean value); the hooks send full model ids, so the `models` table has to follow new versions.
- **model-router first-use confirmation**: `mods/model-router/routing.json` (tracked) is the single source of the phase table and of every skill and agent row, and keeps the decisions: `confirmed`, `changed` (`from`/`to`), `projects` exceptions keyed by the origin remote reduced to `host/path` (credentials and local paths never stored), and `ask`. The first use of a rowed typed skill, a rowed agent spawn or a main-loop phase declared through the `route` tool opens a dialog with context: the skill's description (first sentence of its `SKILL.md` frontmatter) or the agent's, the phase with its `about` line (a new field on each of the 11 phases) and the model id and effort the next step really runs on. A row offers Later, Keep or Change; a main-loop phase Later or Keep. Change asks the model (fable, opus, sonnet, haiku with their tier), then the effort among those the phases of that model use (skipped when there is only one), then Everywhere or This project only; the pair maps to an existing phase (rows stay phase names, the same phase counts as Keep, a pair no phase offers is added by hand as a new phase). A skill-row change toasts the model and effort it now runs on, with the `/route switch on` hint when the main loop holds back a downgrade; a free-text answer counts as Later. One dialog at a time, never in headless (`-p`) runs or inside a sub-agent. Only a dialog answer, `/route ask on|off` or `/route forget` (which takes decisions back; a changed row returns to its shipped phase, the frontmatter floors stay yours to realign) writes the file (serialized, 64 KiB cap, never created when absent); each write asks you to commit it from the config repo. `/route pending` lists unconfirmed rows and phases. Layers: routing.json < `~/.claude/model-router.json` (its `ask` wins); a project's `.claude/model-router.json` is never read. Tests: `mods/model-router/hooks/register.test.ts`.
- **Manual-push mode**: `git config gitflow.autopush false` (human-set) now stops every push the gitflow lib makes, not only the post-commit / post-merge hooks. `gitflow start` and `finish` branch, commit and merge locally and push nothing; `gitflow delete` leaves the `origin/` copy in place and prints `git push origin --delete <br>` for the user to run. `hooks/unpushed-guard.sh` stays silent at turn end in this mode and opens each session with one `ℹ manual push mode:` line counting the commits no remote holds across every local branch; an unparseable or unreadable `gitflow.autopush` value is treated as manual push mode too, and that line names it. `hooks/push-guard.sh` (PreToolUse, `Bash|Monitor`) refuses any `git push` Claude types while `gitflow.autopush` reads false in the session cwd or in a literal `-C`/`cd` directory the command names (global config counts outside a repo); the refusal tells the user to run it with `! git push`. It reads the mode through the same lib verb as every other reader and fails closed: an unparseable or unreadable value reads as manual, and an internal error, a missing `lib/gitflow.sh`, more than 20 distinct directory tokens in one command (capped before any token is classified), a `cd`/`-C` directory token mixing quoted and unquoted parts, or a payload jq cannot parse whose raw text looks like a push refuse the push (these pathological cases fire in auto mode too). Directory tokens are read as whole shell words, adjacent quoted segments and backslash escapes included. Once the text looks like a push, the command is split into simple commands (quotes, escapes, separators, heredoc bodies dropped) and a push must be git's own subcommand in one of them: `grep "git push"`, `git log -S "git push"`, `git config --get push.default`, `git stash push`, a heredoc quoting a push or a commit message naming one are allowed; `bash -c` scripts are re-checked, wrappers (`sudo`, `env`, `eval`, `xargs`, `timeout`, `git subtree`...) and assignments keep the text verdict. The misses listed in its header fall to a new `autoMode.soft_deny` rule that no request in the turn clears. The session banner adds `🔒 push : manual (autopush=false) — ! git push` when the key reads false, and `🔒 push : manual (autopush bad) — ! git push` when the value is invalid. Skills read the mode through a new lib verb, `bash ~/.claude/lib/gitflow.sh push-mode`: it prints `auto`, `manual` or `invalid` (rc 0) and names an invalid value on stderr (printable characters only, 64 at most). It is the one reader a skill may call, since the `git config` read of the key is denied to Claude. Skills push nothing on their own, except the `/release-candidate` tag in auto-push mode on an explicit go. Every "on origin" or "not pushed" line they print comes from `git rev-list --count origin/<br>..<br>` read after the fact, with the complete `! git …` command when something is left for the user to push. An invalid value (anything but unset, true or false, or a read that fails) is manual push mode for every reader and is named where it is read (see Fixed). Tests: `lib/gitflow-test.sh` T11b (push-mode verb), T18m and T18q blocks, `lib/tests/unpushed-guard.test.sh` T10-T16, `lib/tests/push-guard.test.sh` (98 checks).
+1 -1
View File
@@ -273,7 +273,7 @@ cryptic names.
finishing-a-development-branch → `gitflow finish` (human signal)
systematic-debugging → bugfix
verification-before-completion → the verifier gates
- SEO+GEO → seo (GEO only → geo); W3C + WCAG a11y → web-validate;
- SEO+GEO → seo (GEO only → geo); W3C + WCAG conformance → web-validate;
security audit (secrets, CVE, OWASP) → cso
- Media generation (image, video, audio, brand kit), explicit ask →
Higgsfield pack, off by default: `bash ~/.claude/lib/toggle-external.sh
+3 -2
View File
@@ -228,10 +228,11 @@ a different package, ships its own conflicting `graphify` bin) — see
| `/reconcile` | Confront declared status (TODO, registries) against real git/fs state — surface stale items |
| `/pdf-translate` | Translate a PDF to another language, output as HTML (via Vision) |
| `/explain-diff` | Explain a diff, commit, branch or PR as one self-contained HTML page (background, intuition, code walkthrough, 5-question quiz), saved outside the repo |
| `/guardrails` | Audit the five baseline guardrails (hosting, a11y, Supabase RLS, SMS/email consent, cloud functions) plus API hygiene (auth, CORS, secrets, password storage): deterministic scanner, then judgment, report in `.claude/audits/GUARDRAILS.md`. Then proposes fixes, applies the ones you accept and re-scans to prove each one. `--live <url you own>` adds a read-only probe that confirms a hole from outside |
| `/guardrails` | Audit the six baseline guardrails (hosting, Supabase RLS, SMS/email consent, cloud functions, injection, browser exposure) plus API hygiene (auth, CORS, secrets, password storage): deterministic scanner, then judgment, report in `.claude/audits/GUARDRAILS.md`. Then proposes fixes, applies the ones you accept and re-scans to prove each one. `--live <url you own>` adds a read-only probe that confirms a hole from outside (routes, CORS, rate limit, and against a production build: source maps served, error bodies, sensitive keys) |
| `/a11y` | Accessibility baseline: keyboard reachability with a visible focus, an alt on every image, a label on every field. Deterministic scanner, Tab walk on `--live`, report in `.claude/audits/A11Y.md`, fixes proposed with the wording as your choice, applied on acceptance and re-scanned to prove them. Full WCAG → `/web-validate` |
| `/close` | End-of-session ritual — alias for `/capitalize --ritual` (dedup + TODO reconcile + 3-question reflection) |
| `/harden` | Web hardening audit — HTTPS/TLS, HSTS, CSP, security headers |
| `/web-validate` | W3C HTML/CSS validity + WCAG 2.1 accessibility audit |
| `/web-validate` | W3C HTML/CSS validity + WCAG 2.1 conformance audit (keyboard/alt/label basics → /a11y) |
| `/geo` | GEO-only audit — AI-search visibility (ChatGPT, Perplexity, Claude, Gemini…) |
| `/client-handover` | Final project delivery — audits + branded deliverable (Markdown / HTML / PDF) |
| `/profile` | Activate a skill profile (web / seo / web-full / full / max / backend / design / dev / qa / audit / minimal) (default: full) |
+6 -4
View File
@@ -115,12 +115,13 @@ Tu veux...
| État réel du travail ouvert | `/reconcile` |
| Fin de session (= /capitalize --ritual) | `/close` |
| Audit web (TLS, CSP, headers) | `/harden` |
| Validité HTML/CSS + a11y | `/web-validate` |
| Validité HTML/CSS + conformité WCAG | `/web-validate` |
| Accessibilité de base (clavier, alt, labels) puis corriger | `/a11y` |
| Visibilité IA (GEO seul) | `/geo` |
| Livraison client finale | `/client-handover` |
| Traduire un PDF | `/pdf-translate` |
| Comprendre un changement pas suivi | `/explain-diff` |
| Auditer garde-fous (RLS, a11y, consentement, fonctions, mots de passe) puis corriger | `/guardrails` |
| Auditer garde-fous (RLS, consentement, fonctions, mots de passe, injection SQL, fuites navigateur) puis corriger | `/guardrails` |
| Sonder le projet en direct (lecture seule, cible à toi) | `/guardrails --live <url>` |
| Changer profil skills | `/profile` |
| Audit/polish design (anti-slop) | `/impeccable` |
@@ -161,11 +162,12 @@ Tu veux...
| `/reconcile` | Connaître l'état réel du travail ouvert (TODO/registres douteux) | Confronte statut déclaré vs git/fs réel |
| `/close` | Fin de session | Alias de /capitalize --ritual — dedup + TODO + réflexion 3 questions |
| `/harden` | Audit sécurité web (SSL, CSP, HSTS) | Projet web avec config HTTP |
| `/web-validate` | Audit W3C + WCAG a11y | Avant livraison projet web |
| `/web-validate` | Audit W3C + conformité WCAG | Avant livraison projet web ; bases clavier/alt/labels → /a11y |
| `/a11y` | Vérifier clavier, focus visible, alt, labels puis corriger | Scanner déterministe, parcours Tab sur `--live`, rapport `.claude/audits/A11Y.md`, propositions à valider (textes d'alt et de label = ton choix), re-passe qui prouve chaque correction |
| `/client-handover` | Livraison client | Audits finaux + livrable brandé |
| `/pdf-translate` | Traduire un PDF vers une autre langue | Sortie HTML fidèle (images, layout, style préservés) |
| `/explain-diff` | Comprendre un commit, une branche ou une PR qu'on n'a pas suivis | Page HTML autonome hors du repo : contexte, intuition, code, quiz de 5 questions |
| `/guardrails` | Vérifier hébergement, a11y, Supabase RLS, consentement SMS/email, fonctions cloud, stockage des mots de passe | Scanner déterministe, jugement, rapport `.claude/audits/GUARDRAILS.md`, propositions de correction à valider, re-passe qui prouve chaque correction ; `--live <url à toi>` sonde en lecture seule |
| `/guardrails` | Vérifier hébergement, Supabase RLS, consentement SMS/email, fonctions cloud, stockage des mots de passe, injection SQL, exposition navigateur | Scanner déterministe, jugement, rapport `.claude/audits/GUARDRAILS.md`, propositions de correction à valider, re-passe qui prouve chaque correction ; `--live <url à toi>` sonde en lecture seule ; sonde `exposure` sur un build de production (source maps, corps d'erreur, clés sensibles) |
| `/impeccable` | Audit/polish design + détecteur anti-slop déterministe | 23 verbes ; `npx impeccable detect` (exit 0/2) |
| `/tour` | Sweep groupé sur un ou plusieurs projets | Sécu + nettoyage + reconcile + doc, boucle jusqu'à un pass propre |
| `/route` | Voir ou fixer la route du mod model-router | show / clear / off / on / reload / pending / ask on\|off / <phase> / model=… effort=… / switch on\|off / classify on\|off (classifieur de prompt) / verbose on\|off (transitions seules) |
+1 -1
View File
@@ -24,7 +24,7 @@ Gather context. Produce complete PROJECT BRIEF as single source of truth.
| "I don't know / you decide" | Propose ONE concrete default + why, ask yes/no | Take the default, mark `(assumed)`, list in OPEN DECISIONS |
| Contradictory answers (e.g. embedded runtime + managed cloud DB) | Name the contradiction, ask which side wins | Put BOTH options in OPEN DECISIONS; do not silently pick one |
| Language not stated (new project / from scratch / whole-project rewrite) | Propose Rust + why (`rules/default-language.md`); name the contraindication if another language fits better (browser frontend, mandated platform, missing ecosystem) | Rust, marked `(assumed)`, listed in OPEN DECISIONS |
| Project has an API, a database, messaging, cloud functions or a UI | Apply `rules/secure-by-default.md`: note under QUALITY which of the five guardrail domains apply, and list each dashboard-only item (spend cap, WAF, budget alert) in OPEN DECISIONS as manual | A domain applies and nothing is planned: list it in OPEN DECISIONS, never drop it silently |
| Project has an API, a database, messaging, cloud functions or a UI | Apply `rules/secure-by-default.md`: note under QUALITY which of the six guardrail domains apply, and whether the accessibility baseline (`rules/a11y.md`) applies, and list each dashboard-only item (spend cap, WAF, budget alert) in OPEN DECISIONS as manual | A domain applies and nothing is planned: list it in OPEN DECISIONS, never drop it silently |
| Partial answer to the block | Re-ask ONLY the missing items in the follow-up round | Missing fields → `none stated` + OPEN DECISIONS entry |
| Feature list balloons (>10) | Keep the 10 the user ranks first as V1 | Overflow goes to OUT OF SCOPE with a `(deferred by budget)` tag |
+1 -1
View File
@@ -354,7 +354,7 @@ Agent(
- Legal pages (mentions légales, CGV, privacy) — unless the issue is
a security-header gap on those pages, not their content
- Content quality, keyword density, readability
- a11y / WCAG (owned by /web-validate — W3C + WCAG audit)
- WCAG conformance (owned by /web-validate) and the keyboard, alt and label baseline (owned by /a11y)
- W3C HTML / CSS syntactic validity (owned by /web-validate)
If you detect an out-of-scope issue, DROP IT silently. Do NOT mention
+2 -1
View File
@@ -8,7 +8,8 @@ description: |
geo-analyzer concurrently, merges into .claude/audits/SEO.md.
Triggers: "seo", "referencement", "meta tags", "JSON-LD", "sitemap",
"robots.txt", "local SEO", "llms.txt", "ChatGPT visibility".
GEO only → /geo. W3C/a11y → /web-validate. Bugs → /bugfix.
GEO only → /geo. W3C/WCAG → /web-validate; keyboard, alt, labels →
/a11y. Bugs → /bugfix.
argument-hint: optional keywords/scope, e.g. "local SEO plombier 91 94 77" or "SaaS B2B content strategy"
allowed-tools:
- Read
+4 -3
View File
@@ -3,10 +3,11 @@ name: web-validate
effort: high
description: |
Use when a web project needs W3C HTML/CSS validity or WCAG 2.1
accessibility audit. Dispatches the validator-analyzer agent, strict
conformance audit. Dispatches the validator-analyzer agent, strict
scope (no meta/security-header noise).
Triggers: "validate", "w3c", "wcag", "a11y", "accessibility", "axe",
"pa11y", "accessibilité", "conformité web".
Triggers: "validate", "w3c", "wcag", "conformité wcag", "axe",
"pa11y", "conformité web", "validité html".
Keyboard, alt and label basics and their fixes → /a11y.
CSP/HSTS/404 → /harden. Meta/sitemap → /seo. AI engines → /geo.
argument-hint: "[URL] [--fix] [--local|--full] [--no-external]"
allowed-tools: