From 6eba3248b0e5978ffe38b710c52ebb9e2662326f Mon Sep 17 00:00:00 2001 From: bchanot Date: Sun, 18 Oct 2026 23:51:57 +0200 Subject: [PATCH] docs(ship-feature): plan revision 2 after the three-lens challenge (per-language injection, fail-closed probe, scoped exposure rules) --- .../plans/2026-10-18-guardrails-a11y-split.md | 1063 ++++++++++------- 1 file changed, 648 insertions(+), 415 deletions(-) diff --git a/docs/superpowers/plans/2026-10-18-guardrails-a11y-split.md b/docs/superpowers/plans/2026-10-18-guardrails-a11y-split.md index 83b8c26..2a66a49 100644 --- a/docs/superpowers/plans/2026-10-18-guardrails-a11y-split.md +++ b/docs/superpowers/plans/2026-10-18-guardrails-a11y-split.md @@ -4,33 +4,35 @@ **Goal:** Move accessibility out of `/guardrails` into a standalone `/a11y` skill sharing the scan engine, add the `injection` and `exposure` scanner domains, extend the read-only probe with an `exposure` block, and patch every citer. -**Architecture:** `scan.py` is split into a parametrized engine (`scanner.py`, a `Catalogue` of domains, prefixes and marker) and two thin catalogue CLIs (guardrails, a11y). Two new check modules follow the `apis.py` pattern (regex constants, `applies`, `check`, private `_x(project)` lists, `project.found`). The probe gains one `probe_exposure` entry in `PROBES` plus two shared fixes to `fetch`. Doctrine, routing rows, profiles, locks and docs are patched in the same branch. +**Architecture:** `scan.py` is split into a parametrized engine (`scanner.py`, a `Catalogue` of domains and prefixes) and two thin catalogue CLIs (guardrails, a11y). Two new check modules follow the `apis.py` pattern (module-level compiled regexes, `applies`, `check`, private `_x(project, files)` lists) on shared helpers added to `checks/common.py` (`code_files`, `hits`, `dedupe_lines`, `client_reachable`). The probe gains one `probe_exposure` entry in `PROBES`, fails closed (ERROR / SKIPPED, never CLOSED on an unobserved target), validates every plan path and keeps 4xx/5xx bodies. Doctrine, routing rows, profiles, locks and docs are patched in the same branch. **Tech Stack:** Python 3 stdlib (`python3 -B`), bash test suites run through `make test suite=`, shellcheck, gitflow lib. **Spec:** `docs/superpowers/specs/2026-10-18-guardrails-a11y-split-design.md` -**Contract:** `.claude/tasks/contracts/2026-10-18-guardrails-a11y-split-inj-exp-2210.md` +**Contract:** `.claude/tasks/contracts/2026-10-18-guardrails-a11y-split-inj-exp-2210.md` (criteria 4, 5 and 11 amended at the validation gate: real a11y path, non-zero rule counts) + +**Revision 2 (after the three-lens challenge):** per-language injection patterns (a `$1` placeholder, a typed `sql` tag, Express `raw()` and UI copy stay silent), compiled regexes with bounded gaps and shared helpers, exposure rules scoped to route files, settings modules and non-dev env files, `.map` files over 1 MB listed by the walker, a fail-closed probe with path validation, exposure probed against a production build, the guardrails description under 1024, routing.json staged alone, web-building and seo/harden citers patched. ## Global Constraints - Scanner: read-only, stdlib only, never executes project code, severities FAIL / WARN / MANUAL only, exit 0 / 1 / 2. A clean scan means "no static finding". -- Probe: GET, HEAD, OPTIONS only plus the existing opt-in POST burst; `--authorized` required; same-host redirects only; shared budget 200; secrets from env only; never print a response value, only key names. +- Regexes: module-level `re.compile` with explicit flags, run through `common.hits` (`finditer`), never through `project.matches` with `.pattern` (the module's flags would be lost). Every gap that spans a line is bounded (`{0,200}` / `{0,300}` / `{0,400}`), never `[^\n]*` after a cheap anchor. Minified files, built dirs (`public`, `static`, `www`, `assets`) and test paths are out of `code_files`. +- Probe: GET, HEAD, OPTIONS only plus the existing opt-in POST burst; `--authorized` required; every plan path validated as a string starting with `/`; same-host redirects only; shared budget 200; secrets from env only; never print a response value, only identifier-shaped key names. A target that was not observed is ERROR or SKIPPED, never CLOSED. - Code style: max 25 logic lines per function, 80 columns, 5 params, 5 locals. One check module per domain exposing `DOMAIN`, `applies(project)`, `check(project)`. -- Tests: every rule has a mutant at its default severity; every known false-positive class has a `benign` lock; the clean fixtures report ` 0 FAIL, 0 WARN`. Portable shell: no `sed -i`, no `grep -P`, no `stat -c`. -- Git: work on `feature/a11y-split-inj-exp`; commit per task with `git add `; never `git add -A`; never stage `settings.json` or the pre-existing hunks of `mods/model-router/routing.json`; never push by hand (hooks push). -- Rule, heading and label citers are patched in the same task that changes them (BDR-100). -- Locked single-line strings in SKILL.md files (loops-light) must stay on one line. -- Fixture payloads are realistic, never canonical textbook examples; fixture names stay neutral. +- Tests: every rule has a mutant at its default severity; every false-positive class the challenge found has a `benign` lock; the clean fixtures report ` 0 FAIL, 0 WARN`. Portable shell: no `sed -i`, no `grep -P`, no `stat -c`. +- Git: work on `feature/a11y-split-inj-exp`; commit per task with `git add `; never `git add -A`; never stage `settings.json`; `mods/model-router/routing.json` is committed through the Task 6 stash of that one file; never push by hand (hooks push). +- Safety-classifier fallback (BLK-022 class): if an executor's write of `injection.py` or a mutant block is withheld, the main loop writes that file itself with a single full-file Write against the task's test block as its spec, then re-dispatches the rest of the task. +- Rule, heading and label citers are patched in the same task that changes them (BDR-100). Locked single-line strings in SKILL.md files (loops-light) stay on one line. - Run `make test suite=` for the suites a task touches; one full `make test` in Task 9. ## Review Focus -1. A tagged SQL template (`` sql`select * from notes where id = ${id}` ``) must stay silent: pinned by the `tagged-sql-template` benign lock in Task 2. -2. A console call in a server file (`src/pages/api/notes.ts`) must stay silent while the same call in `src/components/` warns: pinned by `console-server-file` in Task 3. -3. A `' b'' + b'' b'' b'') if path == "/app.js": @@ -1175,12 +1321,16 @@ In `lib/tests/guardrails-probe.test.sh`, inside the `do_GET` handler of `server. return self._send(200, b'{"version":3,"sources":["src/app.ts"],"mappings":""}') if path == "/clean.js": return self._send(200, b"console.log(2);\n") + if path == "/inline.js": + return self._send(200, b"console.log(3);\n//# sourceMappingURL=" + b"data:application/json;base64,eyJ2ZXJzaW9uIjozfQ==\n") if path == "/boom": return self._send(500, b"Traceback (most recent call last):\n" b' File "app.py", line 12, in handler\n') if path == "/api/me": return self._send(200, b'{"id": 1, "email": "t@t.io", ' - b'"password_hash": "x", "profile": {"api_key": "y"}}', + b'"password_hash": "x", "profile": {"api_key": "y"}, ' + b'"next_page_token": "abc", "hashtags": []}', {"Content-Type": "application/json"}) ``` @@ -1194,18 +1344,20 @@ And replace `do_OPTIONS` so header names are lowercase on `/lower`: self._send(204, b"", {names[0]: origin, names[1]: "true"}) ``` -Then add a test block before `echo "== JSON output"` (the inner heredocs use `EOF` exactly like the existing plan files in this suite): +Then add a test block before `echo "== JSON output"` (the inner heredocs use `EOF` exactly like the plan files already in this suite): ```bash echo "== exposure probes" cat > "$WORK/exposure.json" < "$WORK/unreachable.json" < "$WORK/badexp.json" probe --authorized "$WORK/badexp.json" >/dev/null 2>&1 check "an error route not starting with / exits 2" "$?" 2 printf '{"base_url": "%s", "exposure": []}\n' "$BASE" > "$WORK/badexp2.json" probe --authorized "$WORK/badexp2.json" >/dev/null 2>&1 check "a non-object exposure block exits 2" "$?" 2 +printf '{"base_url": "%s", "exposure": {"scripts": "/app.js"}}\n' "$BASE" > "$WORK/badexp3.json" +probe --authorized "$WORK/badexp3.json" >/dev/null 2>&1 +check "a scripts string instead of a list exits 2" "$?" 2 +printf '{"base_url": "%s", "routes": [{"path": ".evil.invalid/x"}]}\n' "$BASE" > "$WORK/badroute.json" +probe --authorized "$WORK/badroute.json" >/dev/null 2>&1 +check "a route path that could leave the host exits 2" "$?" 2 cat > "$WORK/lower.json" <&1 | grep -c ' FAIL '` -Expected: at least 9 (the sourcemap, error-body and fields rows are absent; lowercase CORS reads CLOSED; the two exit-2 checks get 1). +Expected: at least 12 (the sourcemap, error-body and fields rows are absent; lowercase CORS reads CLOSED; the four exit-2 checks get 1 or 0). - [ ] **Step 3: Patch `probe.py`** Imports: add `import re` and change the parse import to `from urllib.parse import quote, urljoin, urlsplit`. -Replace `_response_from` and `fetch`: +Replace `_response_from` and `fetch` (headers stay the `HTTPMessage`, whose `.get` is case-insensitive; the body of an HTTP error is read instead of dropped): ```python -def _headers(message): - return {k.lower(): v for k, v in message.items()} - - def _error_body(exc): try: return exc.read(BODY_CAP) @@ -1258,7 +1420,7 @@ def _error_body(exc): def _response_from(resp): - return Response(resp.status, _headers(resp.headers), resp.read(BODY_CAP)) + return Response(resp.status, resp.headers, resp.read(BODY_CAP)) def fetch(session, method, url, headers=None, body=None): @@ -1271,45 +1433,49 @@ def fetch(session, method, url, headers=None, body=None): with session.opener.open(req, timeout=session.timeout) as resp: return _response_from(resp) except urllib.error.HTTPError as exc: - return Response(exc.code, _headers(exc.headers), _error_body(exc)) + return Response(exc.code, exc.headers, _error_body(exc)) except (urllib.error.URLError, OSError, ValueError) as exc: return Response(None, {}, b"", str(exc)) ``` -In `_cors_open`: `headers.get("access-control-allow-origin", "")` and `headers.get("access-control-allow-credentials", "")`. +`_cors_open` is unchanged. Change the `Response.headers` annotation comment to `headers: object # http.client.HTTPMessage: .get() ignores case`. Add the constants after `BODY_CAP`: ```python SCRIPT_CAP = 10 -SCRIPT_SRC = re.compile(rb"]+src=[\"']([^\"']+)[\"']", re.I) -MAP_COMMENT = re.compile(rb"//[#@]\s*sourceMappingURL=(\S+)") +SCRIPT_SRC = re.compile(r"]+src=[\"']?([^\"'\s>]+)", re.I) +MAP_COMMENT = re.compile(r"//[#@]\s*sourceMappingURL=(\S+)") TRACE_MARKERS = re.compile( rb"Traceback \(most recent call last\)|\bat [\w.$<> ]+ \([^)\n]*:\d+:\d+\)" rb"|File \"[^\"\n]+\", line \d+|SQLSTATE\[|syntax error at or near" rb"|node_modules/|/var/www/|Stack trace:|#\d+ /[\w/.-]+\.php\(\d+\)") SENSITIVE_KEY = re.compile( - r"password|passwd|pwd|hash|salt|secret|token|api_?key|service_?role" - r"|private|ssn|iban|cvv|card_?number", re.I) + r"(?:^|_)(?:password|passwd|pwd|salt|secret|api_?key|service_?role" + r"|private_?key|(?:access|refresh|id|auth|api|session)_token|jwt|ssn" + r"|iban|cvv|card_?number)(?:$|_)") +IDENT = re.compile(r"^[A-Za-z_][\w-]{0,31}$") ``` -Add the probes before `PROBES = (…)` and append `probe_exposure` to the tuple: +Add the probes before `PROBES = (…)` and place `probe_exposure` BEFORE `probe_rate_limit` in the tuple (the burst is the largest budget consumer; exposure must not starve behind it): ```python def _same_host(context, url): """Absolute url when it stays on context's host, else None.""" - text = url.decode("utf-8", "ignore") if isinstance(url, bytes) else url - full = urljoin(context, text) + full = urljoin(context, url) return full if urlsplit(full).netloc == urlsplit(context).netloc else None -def _script_urls(session, base, cfg): - listed = cfg.get("scripts") - if listed is None: - page = fetch(session, "GET", base + "/") - listed = [m.group(1) for m in SCRIPT_SRC.finditer(page.body)] - urls = [u for u in (_same_host(base + "/", s) for s in listed) if u] - return list(dict.fromkeys(urls))[:SCRIPT_CAP] +def _page_scripts(session, base): + """(urls, note): same-host scripts of the base page, or why none.""" + page = fetch(session, "GET", base + "/") + if page.error: + return [], f"base page unreachable: {page.error}" + text = page.body.decode("utf-8", "ignore") + urls = [u for u in (_same_host(base + "/", s) + for s in SCRIPT_SRC.findall(text)) if u] + urls = list(dict.fromkeys(urls))[:SCRIPT_CAP] + return urls, "" if urls else "no same-host script on the base page" def _map_candidates(script_url, resp): @@ -1317,14 +1483,27 @@ def _map_candidates(script_url, resp): header = resp.headers.get("sourcemap") or resp.headers.get("x-sourcemap") if header: urls.append(header) - comment = MAP_COMMENT.search(resp.body[-600:]) + tail = resp.body[-600:].decode("utf-8", "ignore") + comment = MAP_COMMENT.search(tail) if comment: urls.append(comment.group(1)) - return [u for u in (_same_host(script_url, u) for u in urls) if u] + return list(dict.fromkeys(urls)) -def _map_served(resp): - return resp.status == 200 and b'"sources"' in resp.body +def _map_verdict(session, script_url, candidates): + """(verdict, target, note) over the candidate map urls, fail closed.""" + for url in candidates: + if url.startswith("data:"): + return "OPEN", script_url, "inline source map in the script" + target = _same_host(script_url, url) + if not target: + continue + resp = fetch(session, "GET", target) + if resp.error or resp.status is None: + return "ERROR", target, resp.error or "no response" + if resp.status == 200 and b'"sources"' in resp.body: + return "OPEN", target, "source map served with its sources" + return "CLOSED", script_url, "no source map served for this script" def _sourcemap_probe(session, script_url): @@ -1332,13 +1511,20 @@ def _sourcemap_probe(session, script_url): resp = fetch(session, "GET", script_url) if resp.error: return Probe("exposure", pid, "ERROR", script_url, resp.error) - served = next((u for u in dict.fromkeys(_map_candidates(script_url, resp)) - if _map_served(fetch(session, "GET", u))), None) - if served: - return Probe("exposure", pid, "OPEN", served, - "source map served with its sources") - return Probe("exposure", pid, "CLOSED", script_url, - "no source map served for this script") + verdict, target, note = _map_verdict( + session, script_url, _map_candidates(script_url, resp)) + return Probe("exposure", pid, verdict, target, note) + + +def _sourcemaps(session, base, cfg): + listed = cfg.get("scripts") + if listed is None: + urls, note = _page_scripts(session, base) + else: + urls, note = [base + s for s in listed][:SCRIPT_CAP], "" + if note: + return [Probe("exposure", "sourcemap", "SKIPPED", base, note)] + return [_sourcemap_probe(session, u) for u in urls] def _error_probe(session, base, path): @@ -1372,12 +1558,38 @@ def _keys(data, depth=0): return [] -def _sensitive_keys(body): +def _snake(key): + return re.sub(r"(?<=[a-z0-9])(?=[A-Z])", "_", key).replace("-", "_").lower() + + +def _sensitive_keys(data): + return sorted({k for k in _keys(data) if SENSITIVE_KEY.search(_snake(k))}) + + +def _key_note(keys): + """Identifier-shaped key names only; anything else is counted.""" + shown = [k for k in keys if IDENT.match(k)] + hidden = len(keys) - len(shown) + return ", ".join(shown) + (f" (+{hidden} unprintable)" if hidden else "") + + +def _json_body(resp): try: - data = json.loads(body or b"null") + return json.loads(resp.body), True except ValueError: - return [] - return sorted({k for k in _keys(data) if SENSITIVE_KEY.search(k)}) + return None, False + + +def _fields_verdict(resp): + if resp.error: + return "ERROR", resp.error + data, is_json = _json_body(resp) + if resp.status != 200 or not is_json: + return "SKIPPED", f"HTTP {resp.status}: no JSON body to read" + keys = _sensitive_keys(data) + if keys: + return "OPEN", "response carries sensitive keys: " + _key_note(keys) + return "CLOSED", "no sensitive key in the response" def _bearer(): @@ -1387,12 +1599,8 @@ def _bearer(): def _fields_probe(session, base, route): target = base + route["path"] - resp = fetch(session, "GET", target, _bearer()) - keys = _sensitive_keys(resp.body) if resp.status == 200 else [] - return _verdict( - ("exposure", f"fields:{route['path']}", target), resp, bool(keys), - ("response carries sensitive keys: " + ", ".join(keys), - "no sensitive key in the response")) + verdict, note = _fields_verdict(fetch(session, "GET", target, _bearer())) + return Probe("exposure", f"fields:{route['path']}", verdict, target, note) def probe_exposure(session, plan): @@ -1400,31 +1608,39 @@ def probe_exposure(session, plan): if cfg is None: return [] base = plan["base_url"].rstrip("/") - out = [_sourcemap_probe(session, u) - for u in _script_urls(session, base, cfg)] + out = _sourcemaps(session, base, cfg) out += [_error_probe(session, base, p) for p in _error_paths(cfg)] out += [_fields_probe(session, base, r) for r in plan.get("routes", [])] return out PROBES = (probe_supabase, probe_cross_user, probe_routes, - probe_cors, probe_rate_limit, probe_exposure) + probe_cors, probe_exposure, probe_rate_limit) ``` -Extend plan validation: +Extend plan validation (replace `_plan_error`): ```python +def _plan_paths(plan): + cfg = plan.get("exposure") or {} + supa = plan.get("supabase") or {} + rate = plan.get("rate_limit") or {} + return ([r.get("path") if isinstance(r, dict) else r + for r in plan.get("routes", [])] + + list(supa.get("cross_user_paths") or []) + + [plan.get("cors_path", "/"), rate.get("path", "/")] + + list(cfg.get("scripts") or []) + + list(cfg.get("error_routes") or [])) + + def _exposure_error(cfg): if cfg is None: return "" if not isinstance(cfg, dict): return "exposure must be an object" for key in ("scripts", "error_routes"): - items = cfg.get(key) or [] - if not all(isinstance(i, str) for i in items): - return f"exposure.{key} must be a list of strings" - if any(not r.startswith("/") for r in cfg.get("error_routes") or []): - return "exposure.error_routes entries must start with /" + if cfg.get(key) is not None and not isinstance(cfg[key], list): + return f"exposure.{key} must be a list" return "" @@ -1432,21 +1648,24 @@ def _plan_error(plan): method = plan.get("rate_limit", {}).get("method", "GET").upper() if method not in READ_METHODS and method != "POST": return f"rate_limit method {method} is not a probe method" - return _exposure_error(plan.get("exposure")) + error = _exposure_error(plan.get("exposure")) + bad = [p for p in _plan_paths(plan) + if not isinstance(p, str) or not p.startswith("/")] + return error or (f"plan path {bad[0]!r} must start with /" if bad else "") ``` -Module docstring: after the `GUARDRAILS_JWT2` line add ` (also sent as bearer by the fields probe when set)`; in the first paragraph add the sentence `With an exposure block in the plan it also reads what the page's scripts, error bodies and JSON responses give away.` +Module docstring: after the `GUARDRAILS_JWT2` line add ` (also sent as bearer by the fields probe when set)`; in the first paragraph add `With an exposure block in the plan it also reads what the page's scripts, error bodies and JSON responses give away; a target it could not observe is ERROR or SKIPPED, never CLOSED.` - [ ] **Step 4: Run the suite** Run: `make test suite=lib/tests/guardrails-probe.test.sh` -Expected: `failed: 0`, including the untouched `json reports the open count` = 4 (`plan.json` has no `exposure` block) and `the burst is capped` = 25. +Expected: `failed: 0`, including the untouched `json reports the open count` = 4 (`plan.json` has no `exposure` block and its paths all start with `/`) and `the burst is capped` = 25. The `next_page_token` and `hashtags` keys of `/api/me` must not appear in the key list (segment matching). - [ ] **Step 5: Commit** ```bash git add skills/guardrails/scripts/probe.py lib/tests/guardrails-probe.test.sh -git commit -m "feat(guardrails): exposure probe (source maps served, error bodies, sensitive keys); fetch keeps error bodies, headers lowercased" +git commit -m "feat(guardrails): exposure probe (source maps served or inline, error bodies, sensitive keys) that fails closed; every plan path validated; fetch keeps error bodies" ``` --- @@ -1455,7 +1674,7 @@ git commit -m "feat(guardrails): exposure probe (source maps served, error bodie **Files:** - Create: `skills/a11y/SKILL.md`, `skills/a11y/references/checks.md`, `skills/a11y/test-prompts.json`, `rules/a11y.md` -- Modify: `mods/model-router/routing.json` (one row), `lib/profiles/{audit,dev,web,web-full,full,max}.profile`, `lib/tests/model-routing.test.sh`, `lib/tests/loops-light.test.sh`, `lib/verify-secure-loop.md:1`, `lib/contract-interview.md:117`, `agents/bugfixer.md:3` +- Modify: `rules/web-building.md` (two fragments point at `rules/a11y.md`), `mods/model-router/routing.json` (one row), `lib/profiles/{audit,dev,web,web-full,full,max}.profile`, `lib/tests/model-routing.test.sh`, `lib/tests/loops-light.test.sh`, `lib/verify-secure-loop.md:1`, `lib/contract-interview.md:117`, `agents/bugfixer.md:3` - Test: `make test suite='lib/tests/effort-routing.test.sh lib/tests/profile-census.test.sh lib/tests/model-routing.test.sh lib/tests/loops-light.test.sh lib/tests/skill-routing-census.test.sh'` **Interfaces:** @@ -1464,13 +1683,13 @@ git commit -m "feat(guardrails): exposure probe (source maps served, error bodie - [ ] **Step 1: Write `skills/a11y/SKILL.md`** -The description is one single-quoted line. The seven locked sentences (`lib/contract-interview.md`, `lib/verify-secure-loop.md`, `subagent_type="bugfixer"`, `EXPECT: A11Y-CLEAR`, `Positive control`, `Nothing is applied without the user's explicit acceptance`, `A11Y-NO-NEW`) and `lib/model-gate.md` must each sit on one line, as below. +The description is one single-quoted line (896 characters). The seven locked sentences (`lib/contract-interview.md`, `lib/verify-secure-loop.md`, `subagent_type="bugfixer"`, `EXPECT: A11Y-CLEAR`, `Positive control`, `Nothing is applied without the user's explicit acceptance`, `A11Y-NO-NEW`) and `lib/model-gate.md` must each sit on one line, as below. ````markdown --- name: a11y effort: high -description: 'Use when a web project needs its accessibility baseline checked and fixed: everything reachable by keyboard with a visible focus, an alt on every image, a label on every field. Runs a deterministic scanner (A11Y-* rules: img alt, field label, click without keyboard, focus outline removed, positive tabindex), judges each hit, walks the main flow with Tab only on --live (through /browse, else marked not done), writes .claude/audits/A11Y.md, then proposes fixes with the alt and label wording as visible choices, applies only the ones the user accepts (bugfixer executor, fresh verifier and security gates, the scanner as oracle) and re-scans to prove each one. Triggers: "a11y", "accessibilité", "accessibility basics", "clavier", "focus visible", "alt manquant", "label sur les champs", "tab order", "corrige l''accessibilité". Full WCAG conformance (axe, pa11y, W3C) → /web-validate; security guardrails → /guardrails.' +description: 'Use when a web project needs its accessibility baseline checked and fixed: everything reachable by keyboard with a visible focus, an alt on every image, a label on every field. Full WCAG conformance (axe, pa11y, W3C) → /web-validate; security guardrails → /guardrails. Deterministic scanner (A11Y-* rules: img alt, field label, click without keyboard, focus outline removed, positive tabindex), judgment, a Tab-only walk of the main flow on --live (through /browse, else marked not done), report .claude/audits/A11Y.md, then fixes proposed with the alt and label wording as visible choices, applied only on acceptance (bugfixer executor, fresh verifier and security gates, the scanner as oracle) and re-scanned to prove each one. Triggers: "a11y", "accessibilité", "accessibility basics", "clavier", "focus visible", "alt manquant", "label sur les champs", "tab order", "corrige l''accessibilité".' argument-hint: '[project path] [--exclude paths] [--live ] [--report-only]' --- @@ -1669,7 +1888,7 @@ open and say so plainly. Never report a fix the re-pass did not prove. pattern), entry pre-filled, written only on approval. ```` -Measure the description: `awk 'NR==4' skills/a11y/SKILL.md | sed 's/^description: //' | wc -c` must print 1024 or less. +Measure the description: `awk 'NR==4' skills/a11y/SKILL.md | sed 's/^description: //' | wc -c` must print 1024 or less (expected about 910 bytes). - [ ] **Step 2: Write `skills/a11y/references/checks.md`** @@ -1732,7 +1951,9 @@ pairs with their hit counts; a `NEW` hit after a fix is a regression. ] ``` -- [ ] **Step 4: Write `rules/a11y.md`** +- [ ] **Step 4: Write `rules/a11y.md` and point `rules/web-building.md` at it** + +`rules/a11y.md`: ```markdown --- @@ -1747,16 +1968,18 @@ paths: ["**/*.tsx", "**/*.jsx", "**/*.vue", "**/*.svelte", "**/*.astro", "**/*.h a placeholder is not a label. ``` -- [ ] **Step 5: Add the routing row without sweeping the pre-existing hunks** +In `rules/web-building.md` (same globs, so both load together on UI files): the fragment `visible `:focus-visible` ring;` in the "Touch targets" bullet becomes `keyboard and focus per `rules/a11y.md`;` and the fragment `alt text on images` in the "Before declaring a public site done" paragraph becomes `accessibility baseline (`rules/a11y.md`)`. Nothing else in that file changes. + +- [ ] **Step 5: Add the routing row, committing that one file alone** ```bash -git status --short mods/model-router/routing.json settings.json +git status --short mods/model-router/routing.json ``` -If either file shows `M`, stash those two files first (and only them): +If it shows `M` (the pre-existing dialog decisions), stash that single file: ```bash -git stash push -m "pre-existing: routing dialog decisions + settings env key" -- mods/model-router/routing.json settings.json +git stash push -m "pre-existing routing dialog decisions" -- mods/model-router/routing.json ``` Then in `mods/model-router/routing.json`, in the `skills` block, add the line ` "a11y": "reflect",` right after ` "guardrails": "reflect",`. Validate: `python3 -I -c 'import json; json.load(open("mods/model-router/routing.json"))'`. @@ -1765,10 +1988,10 @@ Then in `mods/model-router/routing.json`, in the `skills` block, add the line ` git add mods/model-router/routing.json git commit -m "chore(model-router): a11y skill row (reflect)" git stash pop -git status --short mods/model-router/routing.json settings.json +git stash list ``` -The last status must show both files `M` again (the pre-existing diffs restored) and `git stash list` must be empty. A pop conflict means the a11y line sits next to a dialog hunk: keep both, `git add` nothing, continue. +After the pop, `git stash list` must be empty and `git status --short` must show routing.json `M` again (the pre-existing hunks restored, at line 106 and later; the a11y row sits at line 78). A pop that reports a conflict is a STOP: do not touch the index, do not continue the task; report the conflict to the user with `git status` and wait. `settings.json` is never stashed and never staged. - [ ] **Step 6: Profiles, locks and flow enums** @@ -1789,18 +2012,18 @@ The last status must show both files `M` again (the pre-existing diffs restored) 5. `lib/contract-interview.md` line 117: `…|onboard|guardrails>` → `…|onboard|guardrails|a11y>`. 6. `agents/bugfixer.md` line 3: `dispatched by /bugfix (or /guardrails for accepted fixes)` → `dispatched by /bugfix (or /guardrails and /a11y for accepted fixes)`. -- [ ] **Step 7: Run the censuses** +- [ ] **Step 7: Commit, then run the censuses on the committed tree** -Run: `make test suite='lib/tests/effort-routing.test.sh lib/tests/profile-census.test.sh lib/tests/model-routing.test.sh lib/tests/loops-light.test.sh lib/tests/skill-routing-census.test.sh'` -Expected: `all suites green`. A skill-routing WARN naming `a11y~web-validate` above 0.50 means the two descriptions still read alike: trim shared words from the a11y description (never from web-validate's, Task 8 handles that file) and re-measure. - -- [ ] **Step 8: Commit** +The effort-routing census reads `git ls-files`, so the a11y row is only checked once `skills/a11y/SKILL.md` is committed: commit first, then test. ```bash -git add skills/a11y/SKILL.md skills/a11y/references/checks.md skills/a11y/test-prompts.json rules/a11y.md lib/profiles/audit.profile lib/profiles/dev.profile lib/profiles/web.profile lib/profiles/web-full.profile lib/profiles/full.profile lib/profiles/max.profile lib/tests/model-routing.test.sh lib/tests/loops-light.test.sh lib/verify-secure-loop.md lib/contract-interview.md agents/bugfixer.md +git add skills/a11y/SKILL.md skills/a11y/references/checks.md skills/a11y/test-prompts.json rules/a11y.md rules/web-building.md lib/profiles/audit.profile lib/profiles/dev.profile lib/profiles/web.profile lib/profiles/web-full.profile lib/profiles/full.profile lib/profiles/max.profile lib/tests/model-routing.test.sh lib/tests/loops-light.test.sh lib/verify-secure-loop.md lib/contract-interview.md agents/bugfixer.md git commit -m "feat(a11y): skill (scan, keyboard walk, report, fix loop on the bugfix circuit), lazy rules/a11y.md, profiles, locks" ``` +Run: `make test suite='lib/tests/effort-routing.test.sh lib/tests/profile-census.test.sh lib/tests/model-routing.test.sh lib/tests/loops-light.test.sh lib/tests/skill-routing-census.test.sh'` +Expected: `all suites green`. A red census is fixed in place and committed as `fix(a11y): census` before moving on. A skill-routing WARN naming `a11y~web-validate` above 0.50 (the challenge measured 0.18 to 0.23) means the description drifted: trim shared words from the a11y description, never from web-validate's (Task 8 owns that file). + --- ### Task 7: `/guardrails` skill text, reference, prompts and the secure-by-default rule @@ -1811,10 +2034,10 @@ git commit -m "feat(a11y): skill (scan, keyboard walk, report, fix loop on the b - [ ] **Step 1: `skills/guardrails/SKILL.md` frontmatter** -Replace the `description:` line with this single-quoted line (then measure it: `awk 'NR==4' skills/guardrails/SKILL.md | sed 's/^description: //' | wc -c` ≤ 1024): +Replace the `description:` line with this single-quoted line (994 characters, 1002 bytes; then measure: `awk 'NR==4' skills/guardrails/SKILL.md | sed 's/^description: //' | wc -c` must print 1024 or less): ``` -description: 'Use when auditing a project against the baseline guardrails and fixing what fails: hosting (rate limit, CDN and firewall, 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 (SQL built from input, raw escapes, NoSQL operators, shell into DB tools), exposure (console data, source maps, hydrated state, error bodies, debug mode, wide responses), plus API hygiene (auth on every route, CORS, secrets, password storage). Deterministic scanner, judgment, .claude/audits/GUARDRAILS.md, then fixes applied only on acceptance (bugfixer, fresh verifier and security gates) and re-scanned to prove them; optional read-only live probe on a target the user owns. Triggers: "guardrails", "garde-fous", "RLS activée ?", "faille sql", "injection", "qu''est-ce qui fuit dans le navigateur", "plafond de dépense", "mots de passe en clair ?", "corrige les garde-fous", "sonde le projet en direct". Headers and TLS → /harden; secrets, CVE, dependencies → /cso; keyboard, alt, labels → /a11y.' +description: 'Use when auditing a project against the baseline guardrails and fixing what fails. Headers and TLS → /harden; secrets, CVE, dependencies → /cso; keyboard, alt, labels → /a11y. Domains: hosting (rate limit, CDN, spend cap), Supabase (RLS, owner policies, no service_role client-side), SMS and email (consent, unsubscribe, STOP), cloud functions (no self-trigger, instance cap, budget stop), injection (SQL from input, raw escapes, NoSQL, shell into DB tools), exposure (console data, source maps, hydrated state, error bodies, debug mode, wide responses), plus API hygiene (auth, CORS, secrets, passwords). Scanner, judgment, .claude/audits/GUARDRAILS.md, fixes applied only on acceptance (bugfixer, verifier and security gates), re-scanned to prove them; optional read-only probe of a target you own. Triggers: "guardrails", "garde-fous", "RLS activée ?", "faille sql", "fuite navigateur", "plafond de dépense", "mots de passe en clair ?", "corrige les garde-fous", "sonde le projet en direct".' ``` `argument-hint`: `'[project path] [--domain api,hosting,supabase,messaging,functions,injection,exposure] [--exclude paths] [--live ] [--report-only]'`. @@ -1828,15 +2051,17 @@ description: 'Use when auditing a project against the baseline guardrails and fi source. A constant, an allowlisted identifier or a value already cast to a number is a FALSE POSITIVE; anything that can come from a request, a file or another user's row is CONFIRMED. - - **Exposure**: open the main page in a browser and read what the console, - the network responses and the DOM carry: a token in a `data-*` - attribute, a user object logged, a full row in an API answer. With - `--live`, the probe answers for served source maps, error bodies and - sensitive keys; the rest is read by hand. + - **Exposure**: read the code behind each EXP hit: is the logged object, + the hydrated key or the returned row really user data? With `--live` + against a production build (STEP 5), the probe answers for served + source maps, error bodies and sensitive keys; without it, say so. ``` -3. STEP 5.1: after `and a \`rate_limit\` route if the user wants that one burst.` add the sentence `Add an \`exposure\` block (\`{}\` for the defaults, \`error_routes\` for a route you own that answers an error to a malformed id, never a path you guess) so the probe reads source maps, error bodies and response keys.` -4. STEP 8 proposal examples: `the label text for a field.` → `the parameter binding for a query.`; `(label wording, CORS origins, owner column,\n rate-limit numbers)` → `(allowlisted filter fields, CORS origins, owner column,\n rate-limit numbers)`. -5. STEP 9 example: `("2 with the label 'Email'")` → `("2 with the fields ['id','status']")`. +3. STEP 5, paragraph 1: after `a staging or\nproduction URL only on an explicit, specific go.` add: `The \`exposure\` block runs against a production build or a staging URL (\`next build && next start\`, \`vite preview\`, framework debug off): a dev server serves source maps and tracebacks by design, so its exposure OPEN verdicts are dev artefacts, reported as such, with no proposal and no re-pass requirement.` +4. STEP 5.1: after `and a \`rate_limit\` route if the user wants that one burst.` add: `Add an \`exposure\` block (\`{}\` for the defaults, \`error_routes\` for a route you own that answers an error to a malformed id, never a path you guess) so the probe reads source maps, error bodies and response keys; every path in the plan starts with \`/\`.` +5. STEP 5.3: after `CLOSED means it was refused or empty.` add `SKIPPED and ERROR mean the target was not observed: never read either as proof of a fix.` +6. STEP 8: `A live OPEN verdict\nwith no static finding gets a proposal whose proof is the probe alone.` → `A live OPEN verdict\nwith no static finding gets a proposal whose proof is the probe alone,\nunless STEP 5 marked it a dev artefact.` +7. STEP 8 proposal examples: `the label text for a field.` → `the parameter binding for a query.`; `(label wording, CORS origins, owner column,\n rate-limit numbers)` → `(allowlisted filter fields, CORS origins, owner column,\n rate-limit numbers)`. +8. STEP 9 example: `("2 with the label 'Email'")` → `("2 with the fields ['id','status']")`. Every locked sentence from loops-light stays untouched and on one line. @@ -1847,12 +2072,16 @@ Every locked sentence from loops-light stays untouched and on one line. ```markdown ## injection + Patterns are per language: a Postgres `$1` placeholder, a tagged template + (`sql\`…\``, `sql\`…\``), an argv array and test or fixture paths are + silent by design. + | Rule | Sev | Catches | Fix | |---|---|---|---| - | INJ-SQL-RAW-UNSAFE | FAIL | `$queryRawUnsafe`, `$executeRawUnsafe`, `knex.raw`, `.raw()`, `.extra()`, `sequelize.query`, `Sequelize.literal`, SQLAlchemy `text()` fed a variable; ActiveRecord `where("… #{}")` | bind the values, or the tagged `$queryRaw` | - | INJ-SQL-CONCAT | FAIL | a SQL statement string built with `${}`, `+`, an f-string, `%`, `.format`, PHP `$var`, Ruby `#{}`, `format!`, `Sprintf` | placeholders and a parameter list | + | INJ-SQL-RAW-UNSAFE | FAIL | `$queryRawUnsafe`, `$executeRawUnsafe`, `knex.raw`, `sequelize.query`, `Sequelize.literal`, Django `.objects.raw()` / `.extra()`, SQLAlchemy `text()` fed a variable; ActiveRecord `where("… #{}")` | bind the values, or the tagged `$queryRaw` | + | INJ-SQL-CONCAT | FAIL | a SQL statement (select … from … where, insert into, update … set, delete … where, create/drop/alter) built with `${}`, `+`, an f-string, `%`, `.format`, PHP `$var`, Ruby `#{}`, `format!`, `Sprintf` | placeholders and a parameter list | | INJ-SQL-DYNAMIC-EXEC | WARN | plpgsql `EXECUTE '…' \|\| x` | `format('… %I %L', …)` and `USING` | - | INJ-POSTGREST-FILTER | WARN | supabase-js `.or()`, `.filter()`, `.not()`, `.match()`, `.textSearch()` with an interpolated string | `.eq()` and friends, validated values | + | INJ-POSTGREST-FILTER | WARN | supabase-js `.or()`, `.filter()`, `.not()`, `.match()`, `.textSearch()` with an interpolated string, in a file that uses supabase | `.eq()` and friends, validated values | | INJ-NOSQL-OPERATOR | WARN | Mongo `$where` with a string; a filter taken from `req.body`, `req.query` or `req.params` | allowlist the fields, cast to string, `sanitizeFilter` | | INJ-SHELL-DB-TOOL | FAIL | a shell call naming psql, mysql, mysqldump, pg_dump, mongosh, redis-cli, sqlite3… with an interpolated argument | an argv array, no shell, validated input | @@ -1860,15 +2089,15 @@ Every locked sentence from loops-light stays untouched and on one line. | Rule | Sev | Catches | Fix | |---|---|---|---| - | EXP-CONSOLE-DATA | WARN | `console.log/info/debug/dir/table` in client-reachable code with a data argument (user, session, response, token, body…) | strip console calls in the production build, log server-side | - | EXP-SOURCEMAP-PUBLIC | FAIL / WARN | `productionBrowserSourceMaps: true`, vite `sourcemap: true`, `GENERATE_SOURCEMAP=true`, webpack `devtool` readable maps (FAIL in `webpack.prod*`, WARN elsewhere), a `.map` under `public/`; angular `sourceMap: true` (WARN) | off, or `hidden` and upload to the error tracker | - | EXP-HYDRATED-SENSITIVE | WARN | a token, secret, key, password or ssn-like key returned by `getServerSideProps`, `getStaticProps`, a Remix `loader`, a SvelteKit `load` or set on `window.__STATE__` | return only the fields the page renders | + | EXP-CONSOLE-DATA | WARN | `console.log/info/debug/dir/table` in client-reachable code with a data argument (user, session, response, token, body…); string literals are ignored | strip console calls in the production build, log server-side | + | EXP-SOURCEMAP-PUBLIC | FAIL / WARN | `productionBrowserSourceMaps: true`, vite `sourcemap: true` or `'inline'`, `GENERATE_SOURCEMAP=true` in a committed non-dev env file, webpack `devtool` readable maps (FAIL in `webpack.prod*`, WARN elsewhere), a real `.map` under `public/` or `static/` (any size; vendored and `.min.` maps excluded); angular `sourceMap: true` (WARN) | off, or `hidden` and upload to the error tracker | + | EXP-HYDRATED-SENSITIVE | WARN | a token, secret, key, password or ssn-like key returned by `getServerSideProps`, `getStaticProps`, a Remix `loader`, a SvelteKit `load` or set on `window.__STATE__`; a TS type member is skipped | return only the fields the page renders | | EXP-MARKUP-COMMENT | WARN | `` shipped to the browser (html, astro, php, ejs, hbs, twig, njk, liquid) with todo, fixme, debug, password, token, internal, staging, admin… | delete it, or move it to a code comment the build strips | - | EXP-DATA-ATTR-SENSITIVE | WARN | `data-*` attribute or hidden input named secret, api-key, password, jwt, private, credential (csrf excluded) | keep it server-side, send an opaque id | - | EXP-ERROR-STACK | FAIL | `err.stack`, the error object, `traceback.format_exc()` or `getTraceAsString()` in a response | generic message out, full error in the server log | - | EXP-ERROR-MESSAGE | WARN | `err.message`, `str(e)`, `$e->getMessage()` sent as is | map to a safe message; validation errors are fine, DB errors are not | - | EXP-DEBUG-ON | FAIL | `DEBUG = True`, `APP_DEBUG=true`, `FLASK_DEBUG=1`, `app.debug = True`, `consider_all_requests_local = true`, `errorhandler()` | env-driven, false in production | - | EXP-RESPONSE-WIDE | WARN | a route returning `select *` / `select('*')` / `findUnique` without `select` or `omit` on a users-like table | an explicit field list | + | EXP-DATA-ATTR-SENSITIVE | WARN | `data-*` attribute or hidden input named secret, api-key, password, jwt, private, credential (csrf, xsrf, authenticity, nonce excluded) | keep it server-side, send an opaque id | + | EXP-ERROR-STACK | FAIL | in a route file: `err.stack`, the error object, `traceback.format_exc()` or `getTraceAsString()` in a response | generic message out, full error in the server log | + | EXP-ERROR-MESSAGE | WARN | in a route file: `err.message`, `str(e)`, `$e->getMessage()` sent as is | map to a safe message; validation errors are fine, DB errors are not | + | EXP-DEBUG-ON | FAIL | `DEBUG = True` in a settings module (not dev/local/test), `APP_DEBUG=true` / `FLASK_DEBUG=1` in a committed non-dev env file, `app.debug = True`, `consider_all_requests_local = true`, `errorhandler()` mounted without an environment guard | env-driven, false in production | + | EXP-RESPONSE-WIDE | WARN | a route returning `select *` / `select('*')` on a users-like table, or a single-line Prisma `findUnique/findFirst/findMany` without `select` or `omit` | an explicit field list | ``` 3. Blind spots list: replace `- keyboard traps, focus order, modal focus handling, color contrast` with ``` @@ -1879,16 +2108,18 @@ Every locked sentence from loops-light stays untouched and on one line. - built output (`dist/`, `.next/`) and runtime state such as `__NEXT_DATA__`: only the live probe sees a served map or a hydrated token + - a multi-line Prisma call or a value object spread into state: the + single-line rules stay silent - what the console or an XHR carries once the page runs: a browser walk ``` -4. "By design the scanner ignores" paragraph: remove `fields that are never rendered (\`hidden\`, \`display: none\`), click handlers that only stop propagation or sit on \`role="presentation"\`, focus styles that swap the outline for a border or shadow, ` and append `, tagged SQL templates, placeholders with a separate parameter list, an argv array handed to a DB tool, console calls in server code, \`sourcemap: 'hidden'\`, a debug flag read from the environment, and a hidden input named csrf, xsrf, authenticity or nonce` before the final period. -5. Live probe section: in the plan JSON example add, before the closing brace, `,\n "exposure": {"error_routes": ["/api/v1/notes/not-a-number"]}`; after the `Environment, from test keys only…` sentence add `The fields probe sends \`GUARDRAILS_JWT2\` as a bearer when it is set.`; add three rows to the probe table: +4. "By design the scanner ignores" paragraph: remove `fields that are never rendered (\`hidden\`, \`display: none\`), click handlers that only stop propagation or sit on \`role="presentation"\`, focus styles that swap the outline for a border or shadow, ` and append `, tagged SQL templates, placeholders with a separate parameter list, an argv array handed to a DB tool, console calls in server code, logging calls that carry a stack, \`sourcemap: 'hidden'\`, a debug flag read from the environment, dev, local and test env files and settings modules, minified files and built directories, and a hidden input or data attribute named csrf, xsrf, authenticity or nonce` before the final period. +5. Live probe section: in the plan JSON example add, before the closing brace, `,\n "exposure": {"error_routes": ["/api/v1/notes/not-a-number"]}`; after the `Environment, from test keys only…` sentence add `The fields probe sends \`GUARDRAILS_JWT2\` as a bearer when it is set. Every path in the plan starts with \`/\`: a path that could leave the named host is a usage error.`; add three rows to the probe table: ``` - | sourcemap | `sourcemap: