123 KiB
Guardrails a11y split, injection and exposure domains — Implementation Plan
For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (
- [ ]) syntax for tracking.
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 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=<file>, 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 (criteria 4, 5 and 11 amended on 2026-10-19 after the plan challenge, shown at the validation gate: real a11y path, test -f, non-zero rule counts)
Revision 2 (after the three-lens challenge): per-language injection patterns (a $1 placeholder, a typed sql<T> 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. Revision 3 (confirmation pass): quote-matched concat patterns with + in every language, the dev env lock scoped to the exposure domain, DEBUG anchored at column 0, error rules on every server file, hydrated exclusion limited to type-shaped values, Next pages and a root App counted as client code, sourcemap SKIPPED on a non-200 script, a truncated body, an off-host map or an empty list, plan validation that never raises, conditional stash pop, the contract amended on disk.
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".
- Regexes: module-level
re.compilewith explicit flags, run throughcommon.hits(finditer), never throughproject.matcheswith.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 ofcode_files. - Probe: GET, HEAD, OPTIONS only plus the existing opt-in POST burst;
--authorizedrequired; 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 false-positive class the challenge found has a
benignlock; the clean fixtures report0 FAIL, 0 WARN. Portable shell: nosed -i, nogrep -P, nostat -c. - Git: work on
feature/a11y-split-inj-exp; commit per task withgit add <explicit files>; nevergit add -A; never stagesettings.json;mods/model-router/routing.jsonis 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.pyor 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=<file>for the suites a task touches; one fullmake testin Task 9.
Review Focus
- A double-quoted Postgres placeholder (
"… where owner = $1") must stay silent:parameterized-querylock, Task 2. - A typed tagged template (
sql<number>`select … ${id}`) must stay silent:typed-sql-taglock, Task 2. - Server-side logging of a stack (
logger.error(…, err.stack)) must stay silent whilenew Response(err.stack)in a route fails:logger-stacklock anderror-stackmutant, Task 3. - An unreachable base page gives a SKIPPED sourcemap row, never CLOSED:
unreachable base pagetest, Task 5. - A refused or non-JSON route gives a SKIPPED fields row, never CLOSED:
fields on a 401andfields on a non-JSON bodytests, Task 5.
Task 1: Extract the scan engine into scanner.py
Files:
- Create:
skills/guardrails/scripts/scanner.py - Modify:
skills/guardrails/scripts/scan.py(whole file) - Test:
lib/tests/guardrails-scan.test.sh(unchanged, must stay green)
Interfaces:
-
Produces:
scanner.Catalogue(name, domains, rule_domains, manual_rules)andscanner.main(argv, catalogue) -> int. The check-mode markers are<NAME>-CLEAR <n>and<NAME>-NO-NEWwithNAME = catalogue.name.upper(). -
Step 1: Read the current engine
Run: sed -n 1,251p skills/guardrails/scripts/scan.py. Every function below is the same logic with the module constants replaced by cat.<field>.
- Step 2: Create
skills/guardrails/scripts/scanner.py
#!/usr/bin/env python3
"""Static scan engine shared by the guardrails and a11y scanners.
A Catalogue names the check modules, the rule prefixes and the MANUAL
rules; its name gives the report title and the markers the check modes
print. The engine reads a project tree as data and never executes it.
Exit codes: 0 no FAIL, 1 at least one FAIL, 2 usage error.
Two check modes replace the report and its exit code:
--assert-absent RULE:path,... exit 0 and print <NAME>-CLEAR only when
none of these FAIL/WARN pairs remain (a fix contract's oracle);
--baseline before.json compare with an earlier --json run, exit 0 and
print <NAME>-NO-NEW only when no FAIL/WARN hit appeared.
"""
import argparse
import json
import sys
from collections import Counter
from dataclasses import dataclass
from pathlib import Path
from checks.common import Project
SEVERITY_RANK = {"FAIL": 0, "WARN": 1, "MANUAL": 2}
GATED = ("FAIL", "WARN")
@dataclass(frozen=True)
class Catalogue:
"""What one scanner CLI exposes."""
name: str # report title and marker prefix (upper-cased)
domains: dict # ordered: domain name -> check module
rule_domains: dict # rule prefix (before the first '-') -> domain
manual_rules: frozenset = frozenset()
@property
def marker(self):
return self.name.upper()
@dataclass(frozen=True)
class Result:
findings: list
applicable: list
skipped: list
def parse_args(argv, cat):
parser = argparse.ArgumentParser(
description=f"{cat.name} static scan: reads the tree, runs nothing")
parser.add_argument("path", help="project root to scan")
parser.add_argument(
"--domain", default=",".join(cat.domains),
help="comma list among: " + ", ".join(cat.domains))
parser.add_argument(
"--exclude", default="",
help="comma list of relative paths to skip (copies, vendored code)")
parser.add_argument("--json", action="store_true", help="JSON output")
parser.add_argument(
"--assert-absent", default="", metavar="RULE:path,...",
help="contract oracle: pass only when these pairs are gone")
parser.add_argument(
"--baseline", default="", metavar="JSON",
help="earlier --json run: report fixed, remaining and new hits")
return parser.parse_args(argv)
def _split(value):
return [part.strip() for part in value.split(",") if part.strip()]
def run_checks(project, cat, names):
findings, applicable, skipped = [], [], []
for name in names:
module = cat.domains[name]
if module.applies(project):
applicable.append(name)
findings += module.check(project)
else:
skipped.append(name)
findings.sort(key=lambda f: (
SEVERITY_RANK[f.severity], f.domain, f.path, f.line))
return Result(findings, applicable, skipped)
def summarize(findings):
return {sev: sum(f.severity == sev for f in findings)
for sev in SEVERITY_RANK}
def _domain_lines(domain, findings):
rows = [f for f in findings if f.domain == domain]
return [f"\n[{domain}]"] + (
[f" {f.severity:<6} {f.rule:<24} {f.path}:{f.line} {f.message}"
for f in rows] or [" no finding"])
def _summary_line(findings):
totals = summarize(findings)
return "\nsummary: " + ", ".join(
f"{n} {sev}" for sev, n in totals.items())
def render_text(project, cat, result):
lines = [
f"{cat.name} scan: {project.root} ({len(project.files)} files)",
"scanned: " + (", ".join(result.applicable) or "none"),
]
if result.skipped:
lines.append("not applicable: " + ", ".join(result.skipped))
for domain in result.applicable:
lines += _domain_lines(domain, result.findings)
return "\n".join(lines + [_summary_line(result.findings)])
def render_json(project, result):
return json.dumps({
"root": str(project.root), "files": len(project.files),
"applicable": result.applicable, "not_applicable": result.skipped,
"summary": summarize(result.findings),
"findings": [f.as_dict() for f in result.findings],
}, indent=2)
def _rule_domain(cat, rule):
return cat.rule_domains.get(rule.split("-", 1)[0])
def _pairs(value):
"""'RULE:path,RULE:path' -> [(rule, path)]; a missing path stays ''."""
return [tuple(p.strip() for p in item.partition(":")[::2])
for item in _split(value)]
def _assert_error(cat, value):
for rule, path in _pairs(value):
if not path or not _rule_domain(cat, rule):
return f"bad --assert-absent item {rule}:{path}, want RULE:path"
if rule in cat.manual_rules:
return f"{rule} is MANUAL: no static scan can prove it fixed"
return ""
def _hits(findings):
return Counter((f.rule, f.path) for f in findings if f.severity in GATED)
def _load_baseline(path):
data = json.loads(Path(path).read_text(encoding="utf-8"))
return Counter((f["rule"], f["path"]) for f in data["findings"]
if f["severity"] in GATED)
def _baseline_error(path):
if not path:
return ""
try:
_load_baseline(path)
except (OSError, ValueError, KeyError, TypeError) as exc:
return f"unreadable baseline {path}: {exc}"
return ""
def _usage_error(cat, args):
unknown = [n for n in _split(args.domain) if n not in cat.domains]
if unknown:
return f"unknown domain {unknown}"
if not Path(args.path).is_dir():
return f"not a directory: {args.path}"
return (_assert_error(cat, args.assert_absent)
or _baseline_error(args.baseline))
def _pair_status(cat, hits, applicable, pair):
rule, path = pair
if _rule_domain(cat, rule) not in applicable:
return False, f" CONTROL {rule} {path}: domain not scanned, " \
"absence proves nothing"
if hits[pair]:
plural = "s" if hits[pair] > 1 else ""
return False, f" PRESENT {rule} {path} ({hits[pair]} hit{plural})"
return True, f" CLEAR {rule} {path}"
def assert_absent(project, cat, result, pairs):
"""Positive control first: an empty tree or an unscanned domain fails."""
hits = _hits(result.findings)
rows = [_pair_status(cat, hits, result.applicable, p) for p in pairs]
lines = [text for _, text in rows]
if not project.files:
lines.insert(0, " CONTROL no file scanned, absence proves nothing")
ok = bool(project.files) and all(passed for passed, _ in rows)
marker = [f"{cat.marker}-CLEAR {len(pairs)}"] if ok else []
return ok, lines + marker
def _moved(more, less):
"""Pairs where `more` holds extra hits over `less`, with the surplus."""
return [(key, more[key] - less[key]) for key in sorted(more)
if more[key] > less[key]]
def _rows(tag, moved, sign):
return [f" {tag:<5} {rule} {path} ({sign}{n})"
for (rule, path), n in moved]
def baseline_report(cat, before, result):
after = _hits(result.findings)
fixed, new = _moved(before, after), _moved(after, before)
summary = (f"baseline: {sum(n for _, n in fixed)} fixed, "
f"{sum((before & after).values())} remaining, "
f"{sum(n for _, n in new)} new")
lines = _rows("FIXED", fixed, "-") + _rows("NEW", new, "+") + [summary]
return not new, lines + ([] if new else [f"{cat.marker}-NO-NEW"])
def _check_modes(project, cat, result, args):
checks = []
if args.assert_absent:
checks.append(
assert_absent(project, cat, result, _pairs(args.assert_absent)))
if args.baseline:
checks.append(
baseline_report(cat, _load_baseline(args.baseline), result))
return checks
def _scan(cat, args):
project = Project(Path(args.path), _split(args.exclude))
result = run_checks(project, cat, _split(args.domain))
checks = _check_modes(project, cat, result, args)
if not checks:
text = (render_json(project, result) if args.json
else render_text(project, cat, result))
print(text)
return 1 if any(f.severity == "FAIL" for f in result.findings) else 0
for _, lines in checks:
print("\n".join(lines))
return 0 if all(ok for ok, _ in checks) else 1
def main(argv, cat):
args = parse_args(argv, cat)
error = _usage_error(cat, args)
if error:
print(f"usage error: {error}", file=sys.stderr)
return 2
return _scan(cat, args)
- Step 3: Rewrite
skills/guardrails/scripts/scan.pyas the catalogue
Replace the whole file with (a11y stays in the catalogue for now; Task 4 removes it, Tasks 2 and 3 add the new domains):
#!/usr/bin/env python3
"""Static guardrails scan: the guardrails catalogue on the shared engine.
See scanner.py for the modes and exit codes.
"""
import sys
import scanner
from checks import a11y, apis, functions, hosting, messaging, supabase
CATALOGUE = scanner.Catalogue(
name="guardrails",
domains={
"api": apis,
"hosting": hosting,
"a11y": a11y,
"supabase": supabase,
"messaging": messaging,
"functions": functions,
},
rule_domains={
"API": "api", "HOST": "hosting", "A11Y": "a11y", "SB": "supabase",
"MSG": "messaging", "FN": "functions",
},
manual_rules=frozenset({
"HOST-WAF-DDOS", "HOST-SPEND-CAP", "SB-RLS-LIVE",
"FN-CAP-UNVERIFIED", "FN-BUDGET-STOP",
}),
)
if __name__ == "__main__":
sys.exit(scanner.main(sys.argv[1:], CATALOGUE))
- Step 4: Run the suite, it must be green with the same counts as before
Run: make test suite=lib/tests/guardrails-scan.test.sh
Expected: passed: 106 failed: 0 and all suites green. Also python3 -B skills/guardrails/scripts/scan.py lib/tests/fixtures/guardrails-good | head -3 prints guardrails scan: … (17 files) then scanned: api, hosting, a11y, supabase, messaging, functions.
- Step 5: Commit
git add skills/guardrails/scripts/scanner.py skills/guardrails/scripts/scan.py
git commit -m "refactor(guardrails): extract the scan engine into scanner.py, scan.py keeps the catalogue"
Task 2: Shared helpers in common.py, domain injection, mutants and benign locks
Files:
- Modify:
skills/guardrails/scripts/checks/common.py(appendTEST_PATH,BUILT_SEGMENTS,code_files,hits,dedupe_lines) - Create:
skills/guardrails/scripts/checks/injection.py - Modify:
skills/guardrails/scripts/scan.py(catalogue: addinjectionlast, prefixINJ) - Test:
lib/tests/guardrails-scan.test.sh(new== injectionblock, benign locks)
Interfaces:
-
Produces:
common.code_files(project, exts=SOURCE_EXTS) -> [Path](hand-written source: no test, fixture or mock path, no built dir, no minified file),common.hits(project, files, regex, rule, message) -> [Finding](compiled regex,finditer),common.dedupe_lines(findings)(first finding per (path, line) wins),common.TEST_PATH. RulesINJ-SQL-RAW-UNSAFE,INJ-SQL-CONCAT,INJ-SHELL-DB-TOOL(FAIL),INJ-SQL-DYNAMIC-EXEC,INJ-POSTGREST-FILTER,INJ-NOSQL-OPERATOR(WARN). Task 4 re-points the check-mode tests toINJ-SQL-CONCAT:src/pages/api/notes.ts. -
Step 1: Append the shared helpers to
checks/common.py
TEST_PATH = re.compile(
r"\.(?:test|spec|e2e|stories)\.|(?:^|/)(?:tests?|__tests__|spec|e2e"
r"|fixtures?|mocks?)/", re.I)
BUILT_SEGMENTS = {"public", "static", "www", "assets"}
MINIFIED_NAME = re.compile(r"\.min\.|\.bundle\.", re.I)
LONG_LINE = 5000
def _minified(project, path):
if MINIFIED_NAME.search(path.name):
return True
return any(len(line) > LONG_LINE
for line in project.text(path).splitlines())
def code_files(project, exts=SOURCE_EXTS):
"""Hand-written source: no tests, fixtures, built dirs, minified files."""
return [p for p in non_doc_files(project)
if p.suffix.lower() in exts
and not TEST_PATH.search(project.rel(p))
and not set(project.segments(p)) & BUILT_SEGMENTS
and not _minified(project, p)]
def hits(project, files, regex, rule, message):
"""One finding per match of a compiled regex over the given files."""
return [project.found(rule, path, m.start(), message)
for path in files
for m in regex.finditer(project.text(path))]
def dedupe_lines(findings):
"""One finding per (path, line): the first emitted wins."""
seen, out = set(), []
for finding in findings:
if (finding.path, finding.line) not in seen:
seen.add((finding.path, finding.line))
out.append(finding)
return out
- Step 2: Write the failing mutants and benign locks
In lib/tests/guardrails-scan.test.sh, add API=src/pages/api/notes.ts next to the other path variables (after SMS=…). Right before echo "== benign patterns stay silent", add:
echo "== injection"
mutant sql-template FAIL INJ-SQL-CONCAT \
"printf '%s\n' 'const q = \`select id from notes where owner = \${owner}\`;' >> $API"
mutant sql-concat FAIL INJ-SQL-CONCAT \
"printf '%s\n' 'const q = \"select id from notes where owner = \" + owner;' >> $API"
mutant sql-fstring FAIL INJ-SQL-CONCAT \
"printf '%s\n' 'cur.execute(f\"delete from notes where id = {note_id}\")' > src/lib/cleanup.py"
mutant sql-php-interpolation FAIL INJ-SQL-CONCAT \
"printf '%s\n' '<?php \$r = \$db->query(\"select id from notes where owner = \$owner\");' > src/lib/notes.php"
mutant sql-py-concat FAIL INJ-SQL-CONCAT \
"printf '%s\n' 'cur.execute(\"select id from notes where owner = \" + owner)' > src/lib/cleanup.py"
mutant sql-quoted-value FAIL INJ-SQL-CONCAT \
"printf '%s\n' \$'const q = \"select id from notes where owner = \\'\" + owner + \"\\'\";' >> $API"
mutant sql-php-dot FAIL INJ-SQL-CONCAT \
"printf '%s\n' \$'<?php \$r = \$db->query(\"select id from notes where owner = \\'\" . \$owner . \"\\'\");' > src/lib/notes.php"
mutant sql-raw-unsafe FAIL INJ-SQL-RAW-UNSAFE \
"printf '%s\n' 'const rows = await prisma.\$queryRawUnsafe(statement);' >> $API"
mutant sql-dynamic-exec WARN INJ-SQL-DYNAMIC-EXEC \
"printf '%s\n' \"execute 'select count(*) from ' || tbl into n;\" >> $SQL"
mutant postgrest-filter WARN INJ-POSTGREST-FILTER \
"printf '%s\n' 'const { data } = await supabase.from(\"notes\").select().or(\`owner.eq.\${who}\`);' >> $API"
mutant nosql-operator WARN INJ-NOSQL-OPERATOR \
"printf '%s\n' 'const doc = await Notes.findOne({ owner: req.body.owner });' >> $API"
mutant shell-db-tool FAIL INJ-SHELL-DB-TOOL \
"printf '%s\n' 'execSync(\`pg_dump --table=\${table} app > backup.sql\`);' > src/lib/backup.ts"
And after the existing benign cases, add:
benign parameterized-query \
"printf '%s\n' 'const r = await db.query(\"select id from notes where owner = \$1\", [owner]);' >> $API"
benign tagged-sql-template \
"printf '%s\n' 'const r = await sql\`select id from notes where owner = \${owner}\`;' >> $API"
benign typed-sql-tag \
"printf '%s\n' 'const r = await sql<Note[]>\`select id from notes where owner = \${owner}\`;' >> $API"
benign express-raw-webhook \
"printf '%s\n' 'app.post(\"/hook\", express.raw({ type: \"application/json\" }), onHook);' >> $API"
benign ui-copy-select \
"printf '%s\n' 'const hint = \`Select a plan from the list, \${name}\`;' >> $TSX"
benign ui-copy-delete \
"printf '%s\n' 'const label = \"Delete from favorites \" + item.title;' >> $TSX"
benign jquery-not \
"printf '%s\n' 'const rows = \$(\".row\").not(\".row-\" + id);' >> $TSX"
benign argv-db-tool \
"printf '%s\n' 'spawnSync(\"pg_dump\", [\"--table\", table, \"app\"]);' > src/lib/backup.ts"
benign format-dynamic-exec \
"printf '%s\n' \"execute format('select count(*) from %I', tbl) into n;\" >> $SQL"
benign test-path-sql \
"mkdir -p src/__tests__; printf '%s\n' 'const q = \`select id from notes where owner = \${owner}\`;' > src/__tests__/notes.test.ts"
benign minified-bundle \
"printf '%s\n' 'const q=\`select id from notes where owner = \${o}\`;' > src/lib/app.min.js"
benign long-line-bundle \
"head -c 6000 /dev/zero | tr '\\0' x > src/lib/bundle.js; printf '%s\n' ' const q=\`select id from notes where owner = \${o}\`;' >> src/lib/bundle.js"
- Step 3: Run the suite, the twelve mutants must fail
Run: make test suite=lib/tests/guardrails-scan.test.sh 2>&1 | grep -c 'FAIL .* raises'
Expected: 12 (the rules do not exist yet). The two $'…' snippets use ANSI-C quoting so the SQL string can hold a single quote; after the outer double quotes are processed, eval sees $'const q = "… = \'" + owner + "\'";'. The benign locks already pass, which is the point of writing them first.
- Step 4: Create
skills/guardrails/scripts/checks/injection.py
"""Injection checks: SQL built from input, raw ORM escapes, dynamic SQL,
PostgREST filters, NoSQL operators, a shell into a DB tool."""
import re
from .common import Rule, blank_comments, code_files, dedupe_lines, hits
DOMAIN = "injection"
JS_EXTS = (".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".vue", ".svelte",
".astro")
SQL_EXTS = (".sql", ".pgsql", ".plpgsql")
GAP = r"[^'\"`]{0,200}"
STMT = (
rf"(?:select\b{GAP}\bfrom\b{GAP}\b(?:where|join|limit|order\s+by"
rf"|group\s+by)\b|select\s+\*\s+from\b"
rf"|insert\s+into\s+[\w.\"]+{GAP}\b(?:values|select)\b"
r"|insert\s+into\s+[\w.\"]+\s*\(|update\s+[\w.\"]+\s+set\b"
r"|delete\s+from\s+[\w.\"]+\s+where\b"
r"|\bwhere\s+[\w.\"]+\s*(?:=|like\b|in\b|<|>)"
r"|create\s+(?:table|index)\s|drop\s+(?:table|index)\s"
r"|alter\s+table\s|truncate\s+table\s)")
DQ = r"[^\"\n]{0,200}"
SQ = r"[^'\n]{0,200}"
def _quoted(tail):
"""A double- or single-quoted SQL statement string followed by tail."""
return rf"\"{DQ}?{STMT}{DQ}\"{tail}|'{SQ}?{STMT}{SQ}'{tail}"
CONCAT = {
JS_EXTS: re.compile(
rf"(?<![\w$)\]>])`[^`]{{0,400}}?{STMT}[^`]{{0,400}}?\$\{{|"
+ _quoted(r"\s*\+\s*[\w$(]"), re.I),
(".py",): re.compile(
rf"\bf['\"][^'\"\n]{{0,200}}?{STMT}|"
+ _quoted(r"\s*(?:%\s*[\w(]|\.format\(|\+\s*[\w(])"), re.I),
(".php",): re.compile(
rf"\"{DQ}?{STMT}{DQ}\$[A-Za-z_]\w*|"
+ _quoted(r"\s*\.\s*\$[A-Za-z_]"), re.I),
(".rb",): re.compile(rf"\"{DQ}?{STMT}{DQ}#\{{", re.I),
(".rs",): re.compile(rf"format!\(\s*\"{DQ}?{STMT}", re.I),
(".go",): re.compile(rf"fmt\.Sprintf\(\s*\"{DQ}?{STMT}", re.I),
}
RAW = {
JS_EXTS: re.compile(
r"(?:\$queryRawUnsafe|\$executeRawUnsafe|\bknex\.raw"
r"|\bsequelize\.query|\b[Ss]equelize\.literal)\s*\(\s*(?![\s'\"`)])"),
(".py",): re.compile(
r"\.objects\.raw\(\s*(?![\s'\"`)])|\.extra\(\s*(?![\s'\"`)])"),
(".rb",): re.compile(r"\.where\(\s*\"[^\"\n]{0,200}#\{"),
}
SQLA_TEXT = re.compile(r"\btext\s*\(\s*(?![\s'\"`)])")
DYNAMIC_EXEC = re.compile(r"\bexecute\s+(?:'[^']*'|\w+)\s*\|\|", re.I)
POSTGREST = re.compile(
r"\.(?:or|filter|not|match|textSearch)\(\s*(?:`[^`\n]{0,200}\$\{"
r"|['\"][^'\"\n]{0,200}['\"]\s*\+\s*[\w$])")
NOSQL = re.compile(
r"\$where\s*:\s*(?:['\"`]|\w)"
r"|\.(?:find|findOne|findOneAndUpdate|findOneAndDelete|updateOne"
r"|updateMany|deleteOne|deleteMany|countDocuments|replaceOne)\(\s*"
r"(?:req\.(?:body|query|params)\b"
r"|\{\s*\w+\s*:\s*req\.(?:body|query|params)\.\w+\s*[,}])")
SHELL_DB = re.compile(
r"\b(?:exec|execSync|spawn|spawnSync|system|popen|subprocess\.\w+"
r"|os\.system|Command::new|shell_exec|passthru|proc_open)\s*\("
r"[^\n]{0,300}?\b(?:psql|mysql|mysqldump|pg_dump|pg_restore|mongosh"
r"|mongo|mongodump|redis-cli|sqlite3|clickhouse-client)\b[^\n]{0,300}?"
r"(?:\$\{|\+\s*[\w$]|#\{|\{\w+\}|%s|\$[A-Za-z_])")
def applies(project):
return bool(project.with_ext(*JS_EXTS, ".py", ".php", ".rb", ".rs",
".go", *SQL_EXTS))
def _by_ext(files, exts):
return [p for p in files if p.suffix.lower() in exts]
def _per_language(project, files, table, rule, message):
out = []
for exts, regex in table.items():
out += hits(project, _by_ext(files, exts), regex, rule, message)
return out
def _raw_unsafe(project, files):
rule = Rule(DOMAIN, "INJ-SQL-RAW-UNSAFE", "FAIL")
msg = "raw SQL escape fed a non-literal: bind the values"
sqla = [p for p in _by_ext(files, (".py",))
if "sqlalchemy" in project.text(p)]
return (_per_language(project, files, RAW, rule, msg)
+ hits(project, sqla, SQLA_TEXT, rule, msg))
def _concat(project, files):
return _per_language(
project, files, CONCAT, Rule(DOMAIN, "INJ-SQL-CONCAT", "FAIL"),
"SQL built from an expression: use placeholders")
def _dynamic_exec(project):
rule = Rule(DOMAIN, "INJ-SQL-DYNAMIC-EXEC", "WARN")
out = []
for path in code_files(project, SQL_EXTS):
text = blank_comments(project.text(path))
for m in DYNAMIC_EXEC.finditer(text):
out.append(project.found(
rule, path, m.start(),
"EXECUTE built with ||: use format() with %I/%L and USING"))
return out
def _postgrest(project, files):
client = [p for p in _by_ext(files, JS_EXTS)
if "supabase" in project.text(p)]
return hits(project, client, POSTGREST,
Rule(DOMAIN, "INJ-POSTGREST-FILTER", "WARN"),
"PostgREST filter string built from a value: use .eq()")
def _nosql(project, files):
return hits(project, _by_ext(files, JS_EXTS), NOSQL,
Rule(DOMAIN, "INJ-NOSQL-OPERATOR", "WARN"),
"filter taken from the request: allowlist fields, cast")
def _shell_db(project, files):
return hits(project, files, SHELL_DB,
Rule(DOMAIN, "INJ-SHELL-DB-TOOL", "FAIL"),
"DB tool run through a shell with input: pass an argv")
def check(project):
files = code_files(project)
found = _raw_unsafe(project, files) + _concat(project, files)
found += _dynamic_exec(project) + _postgrest(project, files)
found += _nosql(project, files) + _shell_db(project, files)
return dedupe_lines(found)
- Step 5: Register the domain in
scan.py
In CATALOGUE: add injection to the from checks import … line (alphabetical: a11y, apis, functions, hosting, injection, messaging, supabase), add "injection": injection, as the LAST entry of domains, and "INJ": "injection", in rule_domains.
- Step 6: Run the suite
Run: make test suite=lib/tests/guardrails-scan.test.sh
Expected: all PASS, including clean has no FAIL or WARN (the fixture's 0001_init.sql has execute function … without ||) and empty project marks hosting not applicable (injection sits after hosting). A mutant or lock that fails is a regex bug: fix the regex against the snippet, never the snippet.
- Step 7: Commit
git add skills/guardrails/scripts/checks/common.py skills/guardrails/scripts/checks/injection.py skills/guardrails/scripts/scan.py lib/tests/guardrails-scan.test.sh
git commit -m "feat(guardrails): injection domain (INJ-*): per-language SQL concat and raw escapes, dynamic EXECUTE, PostgREST, NoSQL, shell into DB tools; shared code_files/hits/dedupe helpers"
Task 3: Domain exposure: walker lists large files, client_reachable shared, mutants and benign locks
Files:
- Modify:
skills/guardrails/scripts/checks/common.py(walker returns large files;client_reachableand its constants) - Modify:
skills/guardrails/scripts/checks/supabase.py(usecommon.client_reachableandcommon.CLIENT_EXTS; delete its own_client_reachable,SERVER_SEGMENTS,CLIENT_SEGMENTS,CLIENT_EXTS,SCRIPT_EXTS) - Modify:
skills/guardrails/scripts/checks/passwords.py(rename_log_argstolog_args, public; update its one caller) - Create:
skills/guardrails/scripts/checks/exposure.py - Modify:
skills/guardrails/scripts/scan.py(catalogue:exposurelast, prefixEXP) - Test:
lib/tests/guardrails-scan.test.sh
Interfaces:
-
Consumes:
apis.ENV_NAME,ENV_SAMPLE,ignore_patterns,is_ignored_env,route_files;passwords.log_args,passwords.LOGGED_NAME;common.code_files,hits,dedupe_lines. -
Produces:
common.client_reachable(project, path) -> bool,common.CLIENT_EXTS,Project.large(regular files overMAX_BYTES, never read: paths only). RulesEXP-CONSOLE-DATA,EXP-HYDRATED-SENSITIVE,EXP-MARKUP-COMMENT,EXP-DATA-ATTR-SENSITIVE,EXP-ERROR-MESSAGE,EXP-RESPONSE-WIDE(WARN),EXP-SOURCEMAP-PUBLIC(FAIL / WARN),EXP-ERROR-STACK,EXP-DEBUG-ON(FAIL). -
Step 1: Walker: list large files without reading them
In checks/common.py replace _is_scannable, _kept_files and the Project.__init__ body:
def _candidate(path):
"""A regular, non-symlink, non-binary file the walker may list."""
if path.name in SKIP_FILES or path.suffix.lower() in BINARY_EXTS:
return False
try:
return path.is_file() and not path.is_symlink()
except OSError:
return False
def _small(path):
try:
return path.stat().st_size <= MAX_BYTES
except OSError:
return False
def _kept_files(root, base, names, prefixes):
for name in names:
path = Path(base) / name
if _candidate(path) and not _excluded(root, path, prefixes):
yield path, _small(path)
and in Project.__init__:
listed = sorted(_walk(self.root, prefixes))
self.files = [p for p, small in listed if small]
self.large = [p for p, small in listed if not small]
_walk is unchanged (it yields what _kept_files yields). Run make test suite=lib/tests/guardrails-scan.test.sh: still green (the symlink and size behaviour of files is identical).
- Step 2: Move
client_reachableintocommon.py
Append to checks/common.py:
SERVER_SEGMENTS = {
"functions", "api", "server", "scripts", "tests", "test", "migrations",
"seed", ".github", "supabase", "tools",
}
CLIENT_SEGMENTS = {
"components", "public", "static", "client", "browser", "www", "islands",
}
CLIENT_EXTS = (".vue", ".svelte", ".html", ".htm")
CLIENT_SCRIPT_EXTS = (".ts", ".tsx", ".js", ".jsx", ".mjs")
def client_reachable(project, path):
"""Heuristic: this file's text ends up in a browser bundle or page."""
segments = set(project.segments(path))
if segments & SERVER_SEGMENTS:
return False
if path.suffix.lower() in CLIENT_EXTS:
return True
if path.suffix.lower() not in CLIENT_SCRIPT_EXTS:
return False
head = project.text(path)[:300]
return bool(segments & CLIENT_SEGMENTS) or "use client" in head
In supabase.py: add CLIENT_EXTS, client_reachable to the from .common import … line; delete the module's SERVER_SEGMENTS, CLIENT_SEGMENTS, CLIENT_EXTS, SCRIPT_EXTS constants and its _client_reachable function; change the single call site (if _client_reachable(project, path)) to if client_reachable(project, path). The project.with_ext(*SOURCE_EXTS, *CLIENT_EXTS) line keeps working through the import. In passwords.py rename _log_args to log_args (definition and its one call). Run the suite again: green.
- Step 3: Write the failing mutants and benign locks
Add to lib/tests/guardrails-scan.test.sh after the == injection block:
echo "== exposure"
mutant console-data WARN EXP-CONSOLE-DATA \
"printf '%s\n' 'console.log(\"saved\", session);' >> $TSX"
mutant sourcemap-next FAIL EXP-SOURCEMAP-PUBLIC \
"printf '%s\n' 'module.exports = { productionBrowserSourceMaps: true };' > next.config.js"
mutant sourcemap-vite-inline FAIL EXP-SOURCEMAP-PUBLIC \
"printf '%s\n' 'export default { build: { sourcemap: \"inline\" } };' > vite.config.ts"
mutant sourcemap-webpack-warn WARN EXP-SOURCEMAP-PUBLIC \
"printf '%s\n' 'module.exports = { devtool: \"eval-source-map\" };' > webpack.config.js"
mutant sourcemap-public-dir FAIL EXP-SOURCEMAP-PUBLIC \
"mkdir -p public/assets; printf '%s\n' '{\"version\":3,\"sources\":[\"src/app.ts\"],\"mappings\":\"AAAA\"}' > public/assets/app.js.map"
mutant sourcemap-large-map FAIL EXP-SOURCEMAP-PUBLIC \
"mkdir -p public; head -c 1100000 /dev/zero | tr '\\0' a > public/app.js.map"
mutant hydrated-sensitive WARN EXP-HYDRATED-SENSITIVE \
"printf '%s\n' 'export async function getServerSideProps() { return { props: { accessToken: process.env.CRM_TOKEN } }; }' > src/pages/account.tsx"
mutant markup-comment WARN EXP-MARKUP-COMMENT \
"printf '%s\n' '<!-- staging login: see the internal wiki before release -->' > src/pages/index.html"
mutant data-attr-sensitive WARN EXP-DATA-ATTR-SENSITIVE \
"printf '%s\n' '<div data-api-key={key}>x</div>' >> $TSX"
mutant error-stack FAIL EXP-ERROR-STACK \
"printf '%s\n' 'export function onError(err: Error) { return new Response(err.stack, { status: 500 }); }' >> $API"
mutant error-message WARN EXP-ERROR-MESSAGE \
"printf '%s\n' 'export function onFail(err: Error) { return Response.json({ error: err.message }, { status: 500 }); }' >> $API"
mutant debug-on FAIL EXP-DEBUG-ON \
"printf '%s\n' 'DEBUG = True' > src/settings.py"
mutant debug-env FAIL EXP-DEBUG-ON \
"printf '%s\n' 'APP_DEBUG=true' > .env.production"
mutant response-wide WARN EXP-RESPONSE-WIDE \
"printf '%s\n' 'const { data } = await db.from(\"profiles\").select(\"*\");' >> $API"
mutant error-stack-single-file FAIL EXP-ERROR-STACK \
"printf '%s\n' 'app.use((err, req, res, next) => res.status(500).send(err.stack));' > server.js"
mutant hydrated-identifier WARN EXP-HYDRATED-SENSITIVE \
"printf '%s\n' 'export async function getServerSideProps() { const token = await crm(); return { props: { accessToken: token } }; }' > src/pages/account.tsx"
mutant console-next-page WARN EXP-CONSOLE-DATA \
"printf '%s\n' 'export default function Home({ user }) { console.log(\"render\", user); return null; }' > src/pages/index.tsx"
And these benign locks next to the Task 2 ones:
benign console-plain-string \
"printf '%s\n' 'console.log(\"ready\");' >> $TSX"
benign console-string-data \
"printf '%s\n' 'console.log(\"loading data\");' >> $TSX"
benign console-server-file \
"printf '%s\n' 'console.log(\"saved\", session);' >> $API"
benign logger-stack \
"printf '%s\n' 'logger.error(\`notes failed \${res.statusCode}\`, err.stack);' >> $API"
benign client-console-stack \
"printf '%s\n' 'console.warn(\"load failed\", err.stack);' >> $TSX"
benign vite-hidden-sourcemap \
"printf '%s\n' 'export default { build: { sourcemap: \"hidden\" } };' > vite.config.ts"
benign vendored-map \
"mkdir -p static/css; printf '%s\n' '{\"version\":3,\"mappings\":\"AAAA\"}' > static/css/bootstrap.min.css.map"
benign level-map \
"mkdir -p public/levels; printf '%s\n' 'tiles 10x10' > public/levels/1.map"
benign debug-from-env \
"printf '%s\n' 'DEBUG = os.environ.get(\"DEBUG\") == \"1\"' > src/settings.py"
benign debug-local-settings \
"printf '%s\n' 'DEBUG = True' > src/settings_local.py"
benign debug-lowercase-elsewhere \
"printf '%s\n' ' debug = True' > src/lib/tools.py"
benign errorhandler-dev-guard \
"printf '%s\n' 'if (process.env.NODE_ENV === \"development\") app.use(errorhandler());' >> $API"
benign flask-config-class \
"printf '%s\n' 'class DevelopmentConfig(Config):' ' DEBUG = True' > src/config.py"
benign error-generic-message \
"printf '%s\n' 'export function onFail() { return Response.json({ error: \"internal error\" }, { status: 500 }); }' >> $API"
benign ts-type-token \
"printf '%s\n' 'export async function getServerSideProps() { return { props: {} }; }' 'type Session = { token: string; };' > src/pages/account.tsx"
benign no-semicolon-type \
"printf '%s\n' 'export async function getServerSideProps() { return { props: {} }; }' 'interface Props {' ' token: string' '}' > src/pages/account.tsx"
benign prisma-multiline-select \
"printf '%s\n' 'const u = await prisma.user.findUnique({' ' where: { id },' ' select: { id: true },' '});' >> $API"
benign csrf-hidden-input \
"printf '%s\n' '<input type=\"hidden\" name=\"csrf_secret\" value={csrf} />' >> $TSX"
benign csrf-data-attr \
"printf '%s\n' '<form data-csrf-secret={csrf}>x</form>' >> $TSX"
# A committed .env.development trips the api domain's API-ENV-NOT-IGNORED by
# design (the fixture's .gitignore lists .env only), so this lock is scoped
# to the exposure domain: a dev env file must raise no EXP finding.
cp -R "$GOOD" "$WORK/env-dev"
printf '%s\n' 'APP_DEBUG=true' 'GENERATE_SOURCEMAP=true' > "$WORK/env-dev/.env.development"
out=$(scan --domain exposure "$WORK/env-dev")
check "a dev env file raises no exposure finding" \
"$(printf '%s\n' "$out" | grep -c ' 0 FAIL, 0 WARN')" 1
- Step 4: Run the suite, the seventeen mutants must fail
Run: make test suite=lib/tests/guardrails-scan.test.sh 2>&1 | grep -c 'FAIL .* raises'
Expected: 18: the seventeen mutants plus the exposure-scoped dev-env check, whose --domain exposure is a usage error until the domain exists.
- Step 5: Create
skills/guardrails/scripts/checks/exposure.py
"""Exposure checks: what the browser can see that it should not."""
import re
from . import passwords
from .apis import ENV_NAME, ENV_SAMPLE, ignore_patterns, is_ignored_env
from .apis import route_files
from .common import Rule, client_reachable, code_files, dedupe_lines, hits
DOMAIN = "exposure"
MARKUP_EXTS = (".html", ".htm", ".astro", ".php", ".ejs", ".hbs", ".twig",
".njk", ".liquid")
ATTR_EXTS = MARKUP_EXTS + (".jsx", ".tsx", ".vue", ".svelte")
DEV_TOKEN = re.compile(
r"(?:^|[._-])(?:dev|development|local|test|testing)(?:[._-]|$)", re.I)
CONSOLE = re.compile(
r"\bconsole\.(?:log|info|debug|dir|table)\s*\(([^\n]{0,300})")
DATA_NAMES = re.compile(
r"\b(?:users?|profile|session|token|account|customer|order|payment"
r"|response|res|data|result|rows|body|headers|props|state|error|err"
r"|json|payload|record|items?)\b", re.I)
SENSITIVE = (
r"(?:token|accessToken|refreshToken|secret|apiKey|api_key|password"
r"|passwordHash|password_hash|serviceRole|service_role|privateKey"
r"|private_key|ssn|iban|stripeSecret|clientSecret)")
LOADER = re.compile(
r"getServerSideProps|getStaticProps"
r"|export\s+(?:async\s+)?function\s+(?:loader|load)\b"
r"|export\s+const\s+(?:loader|load)\b|window\.__\w+__\s*=")
TYPEISH = (r"(?:string|number|boolean|null|undefined|unknown|any|never"
r"|[A-Z][\w<>\[\]|]*)")
HYDRATED = re.compile(
rf"\b{SENSITIVE}\s*:(?!\s*{TYPEISH}\s*(?:[;,}}]|$))", re.M)
COMMENT = re.compile(r"<!--(.*?)-->", re.S)
COMMENT_WORDS = re.compile(
r"\b(?:todo|fixme|hack|xxx|debug|password|passwd|secret|token"
r"|api[-_ ]?key|internal|staging|localhost|admin|remove before"
r"|do not commit|don'?t commit|temporary)\b", re.I)
DATA_ATTR = re.compile(
r"\b(data-[\w-]*(?:secret|api-?_?key|password|passwd|jwt|private"
r"|credential|service-?role)[\w-]*)\s*=", re.I)
HIDDEN_INPUT = re.compile(r"<input\b[^>\n]{0,300}>", re.I)
SENSITIVE_NAME = re.compile(
r"secret|api[-_]?key|password|passwd|jwt|private|credential", re.I)
SAFE_NAME = re.compile(r"csrf|xsrf|authenticity|nonce", re.I)
SENDING = (
r"(?:\bres\.(?:status|json|send|end|write)\b"
r"|\breply\.(?:send|code|status)\b|\bctx\.body\b|\bResponse\("
r"|Response\.json\(|\bjsonify\(|\bJSONResponse\(|\bHTTPException\("
r"|\bdetail\s*=|\becho\b)")
ERR = r"(?:err|error|e|exc|exception)"
ERROR_STACK = re.compile(
rf"{SENDING}[^\n]{{0,300}}?(?:\b{ERR}\.stack\b|traceback\.format_exc"
rf"|getTraceAsString\(\))"
rf"|\b(?:json|send)\s*\(\s*\{{[^}}\n]{{0,200}}\berror\s*:\s*{ERR}\s*[,}}]")
ERROR_MESSAGE = re.compile(
rf"{SENDING}[^\n]{{0,300}}?(?:\b{ERR}\.message\b|\bstr\({ERR}\)"
rf"|\brepr\({ERR}\)|->getMessage\(\))")
SETTINGS_NAME = re.compile(r"^(?:settings|config)", re.I)
DEBUG_SETTINGS = re.compile(r"^DEBUG\s*=\s*True\b", re.M)
DEBUG_ENV = re.compile(
r"^\s*(?:APP_DEBUG\s*=\s*true|FLASK_DEBUG\s*=\s*1)\b", re.M | re.I)
DEBUG_CODE = re.compile(
r"app\.debug\s*=\s*True|app\.run\([^)\n]{0,200}debug\s*=\s*True")
DEBUG_HANDLER = re.compile(
r"^(?![^\n]*(?:development|NODE_ENV))[^\n]*app\.use\(\s*errorhandler\(\)",
re.M)
DEBUG_RAILS = re.compile(r"consider_all_requests_local\s*=\s*true")
NEXT_MAPS = re.compile(r"productionBrowserSourceMaps\s*:\s*true")
VITE_MAPS = re.compile(r"\bsourcemap\s*:\s*(?:true|['\"]inline['\"])")
WEBPACK_DEVTOOL = re.compile(
r"\bdevtool\s*:\s*['\"](?:source-map|eval[\w-]*|inline[\w-]*"
r"|cheap[\w-]*)['\"]")
ENV_MAPS = re.compile(r"^\s*GENERATE_SOURCEMAP\s*=\s*true\b", re.M | re.I)
ANGULAR_MAPS = re.compile(r"\"sourceMap\"\s*:\s*true")
PUBLIC_DIRS = {"public", "static", "assets", "www"}
VENDORED = re.compile(r"\.min\.|vendor|bootstrap|jquery", re.I)
USERS = (r"(?:users|profiles|accounts|customers|members|employees"
r"|patients|clients)")
WIDE = re.compile(
rf"\.from\(\s*['\"]{USERS}['\"]\s*\)\s*\.select\(\s*['\"]\*['\"]\s*\)"
rf"|select\s+\*\s+from\s+{USERS}\b"
r"|\b(?:user|profile|account|customer|member)\.(?:findUnique|findFirst"
r"|findMany)\(\s*\{(?![^\n]{0,300}\b(?:select|omit)\s*:)[^\n]{0,300}\}"
r"\s*\)", re.I)
def applies(project):
return bool(project.with_ext(".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs",
".py", ".php", ".rb", ".vue", ".svelte",
".astro", *MARKUP_EXTS))
def _named(project, prefix):
return [p for p in project.files if p.name.startswith(prefix)]
def _client(project, path):
"""client_reachable, plus Next pages and a root App component."""
if client_reachable(project, path):
return True
segments = project.segments(path)
return (path.suffix.lower() in (".tsx", ".jsx") and "api" not in segments
and ("pages" in segments or path.stem == "App"))
def _console_data(project, files):
rule = Rule(DOMAIN, "EXP-CONSOLE-DATA", "WARN")
out = []
for path in (p for p in files if _client(project, p)):
for m in CONSOLE.finditer(project.text(path)):
if passwords.LOGGED_NAME.search(m.group(1)):
continue
if DATA_NAMES.search(passwords.log_args(m.group(1))):
out.append(project.found(
rule, path, m.start(),
"data logged to the browser console"))
return out
def _map_config(project):
fail = Rule(DOMAIN, "EXP-SOURCEMAP-PUBLIC", "FAIL")
warn = Rule(DOMAIN, "EXP-SOURCEMAP-PUBLIC", "WARN")
out = hits(project, _named(project, "next.config"), NEXT_MAPS, fail,
"production source maps enabled")
out += hits(project, _named(project, "vite.config"), VITE_MAPS, fail,
"build source maps enabled: use 'hidden' or false")
prod = _named(project, "webpack.prod")
other = [p for p in _named(project, "webpack") if p not in prod]
out += hits(project, prod, WEBPACK_DEVTOOL, fail,
"devtool emits readable source maps in production")
out += hits(project, other, WEBPACK_DEVTOOL, warn,
"devtool emits readable source maps: confirm not in prod")
return out + hits(project, project.named("angular.json"), ANGULAR_MAPS,
warn, "sourceMap true: confirm not the production build")
def _env_files(project):
"""Committed env files that are not samples and not dev/local/test."""
patterns = ignore_patterns(project)
return [p for p in project.files if ENV_NAME.fullmatch(p.name)
and not p.name.endswith(ENV_SAMPLE)
and not DEV_TOKEN.search(p.name[4:] or "x")
and not is_ignored_env(p, patterns)]
def _public_map(project, path):
return (set(project.segments(path)) & PUBLIC_DIRS
and not VENDORED.search(project.rel(path)))
def _map_files(project):
rule = Rule(DOMAIN, "EXP-SOURCEMAP-PUBLIC", "FAIL")
out = hits(project, _env_files(project), ENV_MAPS, rule,
"GENERATE_SOURCEMAP=true ships source maps")
small = [p for p in project.with_ext(".map")
if _public_map(project, p) and '"mappings"' in project.text(p)]
large = [p for p in project.large
if p.suffix.lower() == ".map" and _public_map(project, p)]
return out + [project.found(rule, p, 0, "source map in a public directory")
for p in small + large]
def _hydrated(project, files):
loaders = [p for p in files if LOADER.search(project.text(p))]
return hits(project, loaders, HYDRATED,
Rule(DOMAIN, "EXP-HYDRATED-SENSITIVE", "WARN"),
"sensitive key in server-to-client state")
def _markup_comments(project):
rule = Rule(DOMAIN, "EXP-MARKUP-COMMENT", "WARN")
return [project.found(rule, path, m.start(),
"HTML comment shipped to the browser carries "
"internal notes")
for path in project.with_ext(*MARKUP_EXTS)
for m in COMMENT.finditer(project.text(path))
if COMMENT_WORDS.search(m.group(1))]
def _hidden_sensitive(tag):
if not re.search(r"type\s*=\s*[\"']?hidden\b", tag, re.I):
return False
name = re.search(r"name\s*=\s*[\"']([^\"']+)", tag, re.I)
return bool(name and SENSITIVE_NAME.search(name.group(1))
and not SAFE_NAME.search(name.group(1)))
def _data_attrs(project):
rule = Rule(DOMAIN, "EXP-DATA-ATTR-SENSITIVE", "WARN")
out = []
for path in project.with_ext(*ATTR_EXTS):
text = project.text(path)
out += [project.found(rule, path, m.start(),
"sensitive value in a data-* attribute")
for m in DATA_ATTR.finditer(text)
if not SAFE_NAME.search(m.group(1))]
out += [project.found(rule, path, m.start(),
"sensitive value in a hidden input")
for m in HIDDEN_INPUT.finditer(text)
if _hidden_sensitive(m.group(0))]
return out
def _errors(project, files):
server = [p for p in files if not client_reachable(project, p)]
stack = hits(project, server, ERROR_STACK,
Rule(DOMAIN, "EXP-ERROR-STACK", "FAIL"),
"stack trace or error object sent to the client")
message = hits(project, server, ERROR_MESSAGE,
Rule(DOMAIN, "EXP-ERROR-MESSAGE", "WARN"),
"raw exception message sent to the client")
return dedupe_lines(stack + message)
def _settings_modules(project, files):
return [p for p in files if p.suffix == ".py"
and (SETTINGS_NAME.match(p.name)
or "settings" in project.segments(p))
and not DEV_TOKEN.search(p.stem)]
def _debug(project, files):
rule = Rule(DOMAIN, "EXP-DEBUG-ON", "FAIL")
out = hits(project, _settings_modules(project, files), DEBUG_SETTINGS,
rule, "DEBUG = True in a settings module")
out += hits(project, _env_files(project), DEBUG_ENV, rule,
"debug mode on in a committed env file")
out += hits(project, files, DEBUG_CODE, rule,
"debug mode enabled in code")
out += hits(project, files, DEBUG_HANDLER, rule,
"dev error handler mounted without an environment guard")
return out + hits(project, project.named("production.rb"), DEBUG_RAILS,
rule, "full error pages enabled in production")
def _response_wide(project):
return hits(project, route_files(project), WIDE,
Rule(DOMAIN, "EXP-RESPONSE-WIDE", "WARN"),
"whole rows of a user table returned: select the fields")
def check(project):
files = code_files(project)
found = _console_data(project, files) + _map_config(project)
found += _map_files(project) + _hydrated(project, files)
found += _markup_comments(project) + _data_attrs(project)
found += _errors(project, files) + _debug(project, files)
return found + _response_wide(project)
Notes: _env_files strips the leading .env before the dev-token test so .env.development, .env.local and .env.test are skipped while .env.production and .env are kept (the api domain's API-ENV-NOT-IGNORED still judges whether such a file belongs in git). The error rules scan every non-client source file, so a single-file server.js or app.py counts; logger-stack stays silent because the SENDING prefix requires a real sending call (res.status does not match res.statusCode), and client-console-stack because ContactForm.tsx is client-reachable. DEBUG = True is anchored at column 0: a Flask class DevelopmentConfig attribute is indented and stays silent. route_files is still imported for _response_wide. ENV_NAME and ENV_SAMPLE exist in apis.py.
- Step 6: Register the domain
In scan.py: import exposure (alphabetical: a11y, apis, exposure, functions, hosting, injection, messaging, supabase), add "exposure": exposure, as the LAST domains entry (after injection), and "EXP": "exposure", in rule_domains.
- Step 7: Run the suite
Run: make test suite=lib/tests/guardrails-scan.test.sh
Expected: every check PASS, clean has no FAIL or WARN included (the fixture's hidden name="token" carries no sensitive word; notes.ts returns { ok: true }). A mutant or lock that fails is a regex bug: fix the regex, never the snippet, unless the snippet contradicts the spec table.
- Step 8: Commit
git add skills/guardrails/scripts/checks/common.py skills/guardrails/scripts/checks/supabase.py skills/guardrails/scripts/checks/passwords.py skills/guardrails/scripts/checks/exposure.py skills/guardrails/scripts/scan.py lib/tests/guardrails-scan.test.sh
git commit -m "feat(guardrails): exposure domain (EXP-*): console data, source maps (config, public dir, large files), hydrated state, shipped comments, data attributes, error bodies in routes, debug mode, wide responses"
Task 4: Split accessibility out: /a11y scanner, fixture and suite; guardrails drops the domain
Files:
- Move:
skills/guardrails/scripts/checks/a11y.py→skills/a11y/scripts/a11y_checks.py(git mv) - Create:
skills/a11y/scripts/scan.py - Move:
lib/tests/fixtures/guardrails-good/src/styles.css→lib/tests/fixtures/a11y-good/src/styles.css(git mv; its only users were the a11y focus mutants) - Create:
lib/tests/fixtures/a11y-good/src/components/ContactForm.tsx(copy; the guardrails fixture keeps its own for the EXP tests) - Create:
lib/tests/a11y-scan.test.sh - Modify:
skills/guardrails/scripts/scan.py(dropa11yfrom the catalogue) - Modify:
lib/tests/guardrails-scan.test.sh(drop the a11y blocks, re-point check modes and CLI tests)
Interfaces:
-
Consumes:
scanner.Catalogue,scanner.main(Task 1). -
Produces:
python3 -B skills/a11y/scripts/scan.py <path> [--domain a11y] [--exclude] [--json] [--assert-absent A11Y-…:path] [--baseline f.json], markersA11Y-CLEAR <n>andA11Y-NO-NEW, report headera11y scan: …, exit 2 with a named message when the guardrails engine directory is missing. -
Step 1: Move the module and fix its import
mkdir -p skills/a11y/scripts
git mv skills/guardrails/scripts/checks/a11y.py skills/a11y/scripts/a11y_checks.py
In skills/a11y/scripts/a11y_checks.py change from .common import Rule, blank_markup_comments to from checks.common import Rule, blank_markup_comments. Nothing else changes in the file.
- Step 2: Create
skills/a11y/scripts/scan.py
#!/usr/bin/env python3
"""Static accessibility scan: keyboard, visible focus, alt text, labels.
Runs the guardrails scan engine (skills/guardrails/scripts/scanner.py) on
the a11y catalogue. Same options and exit codes; markers A11Y-CLEAR and
A11Y-NO-NEW.
"""
import importlib
import sys
from pathlib import Path
ENGINE = Path(__file__).resolve().parents[2] / "guardrails" / "scripts"
if not ENGINE.is_dir():
print(f"usage error: scan engine missing at {ENGINE} "
"(the guardrails skill must be installed)", file=sys.stderr)
sys.exit(2)
sys.path.insert(0, str(ENGINE))
scanner = importlib.import_module("scanner")
a11y_checks = importlib.import_module("a11y_checks")
CATALOGUE = scanner.Catalogue(
name="a11y",
domains={"a11y": a11y_checks},
rule_domains={"A11Y": "a11y"},
)
if __name__ == "__main__":
sys.exit(scanner.main(sys.argv[1:], CATALOGUE))
- Step 3: Create the a11y fixture
mkdir -p lib/tests/fixtures/a11y-good/src/components
git mv lib/tests/fixtures/guardrails-good/src/styles.css lib/tests/fixtures/a11y-good/src/styles.css
cp lib/tests/fixtures/guardrails-good/src/components/ContactForm.tsx lib/tests/fixtures/a11y-good/src/components/ContactForm.tsx
- Step 4: Create
lib/tests/a11y-scan.test.sh(thenchmod +x)
The suite proves the a11y catalogue: the clean fixture, one mutant per rule, the two benign locks, the A11Y markers, the gates.sh wiring and the rejection of guardrails rules and domains. Engine behaviour (symlinks, size cap, --exclude, JSON shape, empty tree) is proven once in guardrails-scan.test.sh on the same code.
#!/usr/bin/env bash
# lib/tests/a11y-scan.test.sh — floor of the /a11y scanner catalogue.
# The clean fixture must scan with zero FAIL and zero WARN. Each mutant breaks
# one rule on a copy of it and must raise that rule at the expected severity
# (positive control). The A11Y-CLEAR / A11Y-NO-NEW markers, the gates.sh
# contract wiring and the rejection of guardrails rules are checked too; the
# shared engine itself is proven in guardrails-scan.test.sh.
set -u
ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
SCAN="$ROOT/skills/a11y/scripts/scan.py"
GOOD="$ROOT/lib/tests/fixtures/a11y-good"
WORK="$(mktemp -d)"; trap 'rm -rf "$WORK"' EXIT
PASS=0; FAIL=0; LAST_OUT=""
check() { # check <label> <got> <want>
if [ "$2" = "$3" ]; then PASS=$((PASS+1)); echo " PASS $1"
else FAIL=$((FAIL+1)); echo " FAIL $1 (got '$2', want '$3')"; fi
}
scan() { python3 -B "$SCAN" "$@"; }
# edit <file> <sed-expr>: in-place edit without sed -i (BSD/GNU portable).
edit() { sed "$2" "$1" > "$1.new" && mv "$1.new" "$1"; }
has() { # has <SEVERITY> <RULE>: the last scan raised it
printf '%s\n' "$LAST_OUT" | grep -Eq "^ +$1 +$2 " && echo yes || echo no
}
mutant() { # mutant <label> <SEVERITY> <RULE> <snippet run inside a copy>
local label="$1" sev="$2" rule="$3" snippet="$4" dir
dir="$WORK/$label"
cp -R "$GOOD" "$dir" || { check "$label copy" failed ok; return; }
if ! ( cd "$dir" && eval "$snippet" ) >/dev/null 2>&1; then
check "$label setup" failed ok; return
fi
LAST_OUT=$(scan "$dir")
check "$label raises $sev $rule" "$(has "$sev" "$rule")" yes
}
benign() { # benign <label> <snippet>: a legitimate pattern raises nothing
local label="$1" snippet="$2" dir="$WORK/$1" out
cp -R "$GOOD" "$dir" || { check "$label copy" failed ok; return; }
if ! ( cd "$dir" && eval "$snippet" ) >/dev/null 2>&1; then
check "$label setup" failed ok; return
fi
out=$(scan "$dir")
check "$label raises no FAIL or WARN" \
"$(printf '%s\n' "$out" | grep -c ' 0 FAIL, 0 WARN')" 1
}
TSX=src/components/ContactForm.tsx
echo "== clean fixture"
out=$(scan "$GOOD"); rc=$?
check "clean exit code" "$rc" 0
check "clean has no FAIL or WARN" \
"$(printf '%s\n' "$out" | grep -c ' 0 FAIL, 0 WARN')" 1
check "report is titled a11y" \
"$(printf '%s\n' "$out" | grep -c '^a11y scan: ')" 1
echo "== rules"
mutant img-alt FAIL A11Y-IMG-ALT "edit $TSX 's/ alt=\"Company logo\"//'"
mutant field-label FAIL A11Y-FIELD-LABEL "edit $TSX '/<label htmlFor=\"email\">/d'"
mutant click-keyboard FAIL A11Y-CLICK-NO-KEYBOARD "edit $TSX 's/ onKeyDown={go}//'"
mutant tabindex-positive WARN A11Y-TABINDEX-POSITIVE \
"edit $TSX 's/tabIndex={0}/tabIndex={2}/'"
mutant focus-css-warn WARN A11Y-FOCUS-OUTLINE \
"printf 'a:focus { outline: none; }\n' > src/styles.css"
mutant focus-css-fail FAIL A11Y-FOCUS-OUTLINE \
"printf 'a:focus { outline: none; }\n' > src/styles.css; edit $TSX 's/outline-none focus-visible:ring-2 focus-visible:ring-blue-500/x/'"
mutant focus-tailwind FAIL A11Y-FOCUS-OUTLINE \
"edit $TSX 's/outline-none focus-visible:ring-2 focus-visible:ring-blue-500/outline-none/'"
echo "== benign patterns stay silent"
benign comment-with-img-tag \
"printf '%s\n' '// the <img> below is decorative' >> $TSX"
benign dialog-overlay-click \
"printf '%s\n' '<div role=\"dialog\" aria-label=\"x\" onClick={go}>y</div>' >> $TSX"
echo "== check modes (contract oracle and re-pass baseline)"
IMG="A11Y-IMG-ALT:$TSX"
cp -R "$GOOD" "$WORK/cm"; edit "$WORK/cm/$TSX" 's/ alt="Company logo"//'
out=$(scan "$WORK/cm" --assert-absent "$IMG"); rc=$?
check "positive control: the oracle fails while the hit is there" "$rc" 1
check "a failing oracle never prints the marker" \
"$(printf '%s\n' "$out" | grep -c A11Y-CLEAR)" 0
out=$(scan "$GOOD" --assert-absent "$IMG"); rc=$?
check "the oracle passes once the hit is gone" "$rc" 0
check "a passing oracle prints the marker" \
"$(printf '%s\n' "$out" | grep -c '^A11Y-CLEAR 1$')" 1
scan "$GOOD" --assert-absent "HOST-NO-RATE-LIMIT:$TSX" >/dev/null 2>&1
check "a guardrails rule is unknown here (exit 2)" "$?" 2
scan "$WORK/cm" --json > "$WORK/cm-before.json"
out=$(scan "$GOOD" --baseline "$WORK/cm-before.json"); rc=$?
check "baseline lists the fixed hit" \
"$(printf '%s\n' "$out" | grep -c '^ FIXED A11Y-IMG-ALT ')" 1
check "baseline with no new hit exits 0 with the marker" \
"$rc:$(printf '%s\n' "$out" | grep -c '^A11Y-NO-NEW$')" "0:1"
scan "$GOOD" --json > "$WORK/clean-before.json"
out=$(scan "$WORK/cm" --baseline "$WORK/clean-before.json"); rc=$?
check "baseline with a new hit exits 1 without the marker" \
"$rc:$(printf '%s\n' "$out" | grep -c A11Y-NO-NEW)" "1:0"
# contract <dir> <file>: a fix contract whose oracle is the scanner itself
contract() {
cat > "$2" <<EOC
# CONTRACT — a11y-oracle-test
## ACCEPTANCE CRITERIA
1. every image in the contact form has an alt
CHECK: python3 -B '$SCAN' '$1' --assert-absent '$IMG'
EXPECT: A11Y-CLEAR
EVIDENCE: pending
## FILE SCOPE
$TSX
EOC
}
contract "$WORK/cm" "$WORK/c-unfixed.md"
bash "$ROOT/lib/gates.sh" run "$WORK/c-unfixed.md" >/dev/null 2>&1
check "gates.sh: the oracle is UNMET before the fix" "$?" 2
contract "$GOOD" "$WORK/c-fixed.md"
bash "$ROOT/lib/gates.sh" run "$WORK/c-fixed.md" >/dev/null 2>&1
check "gates.sh: the oracle is MET after the fix" "$?" 0
echo "== cli"
scan --domain api "$GOOD" >/dev/null 2>&1; check "a guardrails domain exits 2" "$?" 2
echo "---"
echo "passed: $PASS failed: $FAIL"
[ "$FAIL" -eq 0 ]
- Step 5: Run the new suite
Run: make test suite=lib/tests/a11y-scan.test.sh
Expected: failed: 0. If import a11y_checks fails, print sys.path from the script: ENGINE must resolve to <repo>/skills/guardrails/scripts.
- Step 6: Remove a11y from the guardrails catalogue
In skills/guardrails/scripts/scan.py: drop a11y from the import line and from domains, drop "A11Y": "a11y", from rule_domains. Update the docstring first line to Static guardrails scan: API, hosting, Supabase, messaging, functions, injection, exposure. (wrap under 80 columns).
- Step 7: Rewrite the a11y-coupled parts of
lib/tests/guardrails-scan.test.sh
- Delete the whole
echo "== a11y"block (the sevenmutant … A11Y-…calls). - Delete the two benign cases
comment-with-img-taganddialog-overlay-click(they now live in the a11y suite). - In the check-modes block, replace the sample pair and its setup:
IMG="A11Y-IMG-ALT:$TSX"→INJ="INJ-SQL-CONCAT:$API"cp -R "$GOOD" "$WORK/cm"; edit "$WORK/cm/$TSX" 's/ alt="Company logo"//'→cp -R "$GOOD" "$WORK/cm"; printf '%s\n' 'const q =select id from notes where owner = ${owner};' >> "$WORK/cm/$API"- every
"$IMG"→"$INJ"; the--domain api --assert-absentline stays on--domain api(injection unscanned → CONTROL);A11Y-IMG-ALTin thegrep -c '^ FIXED …'and'^ NEW …'checks →INJ-SQL-CONCAT; the "item without a path" line →scan "$GOOD" --assert-absent INJ-SQL-CONCAT. - In
contract(): criterion text →1. no SQL built from input in the notes route,'$IMG'→'$INJ', the## FILE SCOPEvalue →$API.
- In the CLI block:
out=$(scan --domain a11y "$GOOD")andcheck "domain filter keeps a11y" … '^\[a11y\]'→out=$(scan --domain injection "$GOOD")andcheck "domain filter keeps injection" … '^\[injection\]'.- add after
bad domain exits 2:scan --domain a11y "$GOOD" >/dev/null 2>&1; check "a11y is no longer a guardrails domain (exit 2)" "$?" 2 - the
--excludetest:edit "$WORK/excl/$TSX" 's/ alt="Company logo"//'→printf '%s\n' 'const q =select id from notes where owner = ${owner};' >> "$WORK/excl/$API"and--exclude src/components→--exclude src/pages.
- In the clean-fixture block add:
check "a11y is not scanned" "$(printf '%s\n' "$out" | grep -c '^\[a11y\]')" 0.
- Step 8: Run both suites
Run: make test suite='lib/tests/guardrails-scan.test.sh lib/tests/a11y-scan.test.sh'
Expected: all suites green.
- Step 9: Commit
git add skills/a11y/scripts/scan.py skills/a11y/scripts/a11y_checks.py skills/guardrails/scripts/scan.py lib/tests/a11y-scan.test.sh lib/tests/fixtures/a11y-good lib/tests/fixtures/guardrails-good/src/styles.css lib/tests/guardrails-scan.test.sh
git commit -m "feat(a11y): standalone scanner on the shared engine (A11Y-CLEAR / A11Y-NO-NEW); guardrails drops the a11y domain"
Task 5: Probe exposure, fail closed: source maps, error bodies, sensitive keys; path validation; fetch keeps error bodies
Files:
- Modify:
skills/guardrails/scripts/probe.py - Test:
lib/tests/guardrails-probe.test.sh
Interfaces:
-
Produces: plan key
exposure(object; optionalscripts: [path],error_routes: [path]), probe idssourcemap:<script path>(orsourcemapfor a SKIPPED row),error-body:<path>,fields:<path>, domainexposure. Every plan path (routes[].path,supabase.cross_user_paths[],cors_path,rate_limit.path,exposure.scripts[],exposure.error_routes[]) must be a string starting with/(exit 2 otherwise).Response.headersis thehttp.client.HTTPMessage(case-insensitive.get), no longer adict. -
Step 1: Extend the fixture server and write the failing tests
In lib/tests/guardrails-probe.test.sh, inside the do_GET handler of server.py, add before return self._send(404, b""):
if path == "/":
return self._send(200, b'<html><script src="/app.js"></script>'
b'<script src="/clean.js"></script>'
b'<script src=/inline.js></script>'
b'<script src="https://cdn.invalid/x.js"></script>'
b'</html>')
if path == "/app.js":
return self._send(200, b"console.log(1);\n//# sourceMappingURL=app.js.map\n")
if path == "/app.js.map":
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'"next_page_token": "abc", "hashtags": []}',
{"Content-Type": "application/json"})
And replace do_OPTIONS so header names are lowercase on /lower:
def do_OPTIONS(self):
origin = self.headers.get("Origin", "")
upper = ("Access-Control-Allow-Origin", "Access-Control-Allow-Credentials")
names = tuple(n.lower() for n in upper) if self.path == "/lower" else upper
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 plan files already in this suite):
echo "== exposure probes"
cat > "$WORK/exposure.json" <<EOF
{"base_url": "$BASE",
"routes": [{"path": "/api/me"}, {"path": "/api/guarded"}, {"path": "/api/private"}],
"exposure": {"error_routes": ["/boom"]}}
EOF
OUT="$(probe --authorized "$WORK/exposure.json")"
check "a served source map is OPEN" \
"$(verdict "$OUT" 'sourcemap:/app.js')" OPEN
check "an inline data: source map is OPEN" \
"$(verdict "$OUT" 'sourcemap:/inline.js')" OPEN
check "a script with no map is CLOSED" \
"$(verdict "$OUT" 'sourcemap:/clean.js')" CLOSED
check "a foreign-host script is never probed" \
"$(printf '%s\n' "$OUT" | grep -c 'cdn.invalid')" 0
check "a traceback in an error body is OPEN" \
"$(verdict "$OUT" 'error-body:/boom')" OPEN
check "the random 404 path is CLOSED" \
"$(verdict "$OUT" 'error-body:/guardrails-probe-')" CLOSED
check "sensitive keys in a JSON response are OPEN" \
"$(verdict "$OUT" 'fields:/api/me')" OPEN
check "the sensitive key names are listed, never the values" \
"$(printf '%s\n' "$OUT" | grep -A1 'fields:/api/me' | grep -c 'api_key, password_hash$')" 1
check "fields on a 401 is SKIPPED, never CLOSED" \
"$(verdict "$OUT" 'fields:/api/guarded')" SKIPPED
check "fields on a non-JSON body is SKIPPED" \
"$(verdict "$OUT" 'fields:/api/private')" SKIPPED
cat > "$WORK/unreachable.json" <<EOF
{"base_url": "http://127.0.0.1:1", "exposure": {}}
EOF
OUT="$(probe --authorized "$WORK/unreachable.json")"
check "an unreachable base page gives a SKIPPED sourcemap row" \
"$(verdict "$OUT" 'sourcemap')" SKIPPED
printf '{"base_url": "%s", "exposure": {"error_routes": ["boom"]}}\n' "$BASE" > "$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
printf '{"base_url": "%s", "routes": ["/x"]}\n' "$BASE" > "$WORK/badroute2.json"
probe --authorized "$WORK/badroute2.json" >/dev/null 2>&1
check "a route that is not an object exits 2" "$?" 2
printf '{"base_url": "%s", "exposure": true}\n' "$BASE" > "$WORK/badexp4.json"
probe --authorized "$WORK/badexp4.json" >/dev/null 2>&1
check "a boolean exposure block exits 2 without a traceback" "$?" 2
printf '{"base_url": "%s", "exposure": {"scripts": ["/does-not-exist.js"]}}\n' "$BASE" > "$WORK/stale.json"
OUT="$(probe --authorized "$WORK/stale.json")"
check "a listed script that answers 404 is SKIPPED, never CLOSED" \
"$(verdict "$OUT" 'sourcemap:/does-not-exist.js')" SKIPPED
printf '{"base_url": "%s", "exposure": {"scripts": []}}\n' "$BASE" > "$WORK/noscript.json"
OUT="$(probe --authorized "$WORK/noscript.json")"
check "an empty scripts list still gives a SKIPPED sourcemap row" \
"$(verdict "$OUT" 'sourcemap')" SKIPPED
cat > "$WORK/lower.json" <<EOF
{"base_url": "$BASE", "cors": true, "cors_path": "/lower"}
EOF
OUT="$(probe --authorized "$WORK/lower.json")"
check "lowercase CORS header names are still read" \
"$(verdict "$OUT" 'cors-reflect')" OPEN
- Step 2: Run the suite, the new checks must fail
Run: make test suite=lib/tests/guardrails-probe.test.sh 2>&1 | grep -c ' FAIL '
Expected: at least 14 (the sourcemap, error-body and fields rows are absent; lowercase CORS reads CLOSED; the six 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 (headers stay the HTTPMessage, whose .get is case-insensitive; the body of an HTTP error is read instead of dropped):
def _error_body(exc):
try:
return exc.read(BODY_CAP)
except (OSError, ValueError, AttributeError):
return b""
def _response_from(resp):
return Response(resp.status, resp.headers, resp.read(BODY_CAP))
def fetch(session, method, url, headers=None, body=None):
if session.budget <= 0:
return Response(None, {}, b"", "request budget exhausted")
session.budget -= 1
req = urllib.request.Request(
url, data=body, method=method, headers=headers or {})
try:
with session.opener.open(req, timeout=session.timeout) as resp:
return _response_from(resp)
except urllib.error.HTTPError as exc:
return Response(exc.code, exc.headers, _error_body(exc))
except (urllib.error.URLError, OSError, ValueError) as exc:
return Response(None, {}, b"", str(exc))
_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:
SCRIPT_CAP = 10
SCRIPT_SRC = re.compile(r"<script[^>]+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|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}") # used with fullmatch
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):
def _same_host(context, url):
"""Absolute url when it stays on context's host, else None."""
full = urljoin(context, url)
return full if urlsplit(full).netloc == urlsplit(context).netloc else None
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):
urls = [script_url + ".map"]
header = resp.headers.get("sourcemap") or resp.headers.get("x-sourcemap")
if header:
urls.append(header)
tail = resp.body[-600:].decode("utf-8", "ignore")
comment = MAP_COMMENT.search(tail)
if comment:
urls.append(comment.group(1))
return list(dict.fromkeys(urls))
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:
return "SKIPPED", url, "map url on another host, not fetched"
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):
pid = f"sourcemap:{urlsplit(script_url).path}"
resp = fetch(session, "GET", script_url)
if resp.error:
return Probe("exposure", pid, "ERROR", script_url, resp.error)
if resp.status != 200:
return Probe("exposure", pid, "SKIPPED", script_url,
f"HTTP {resp.status}: script not served, map not read")
if len(resp.body) >= BODY_CAP:
return Probe("exposure", pid, "SKIPPED", script_url,
"script body truncated: its map comment was not read")
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 = [base + s for s in listed][:SCRIPT_CAP]
note = "" if urls else "no script listed in exposure.scripts"
if note:
return [Probe("exposure", "sourcemap", "SKIPPED", base, note)]
return [_sourcemap_probe(session, u) for u in urls]
def _error_probe(session, base, path):
target = base + path
resp = fetch(session, "GET", target)
return _verdict(
("exposure", f"error-body:{path}", target), resp,
bool(TRACE_MARKERS.search(resp.body)),
("error body carries a stack trace or an internal path",
"error body carries no trace marker"))
def _error_paths(cfg):
random_path = "/guardrails-probe-" + os.urandom(6).hex()
return [random_path] + list(cfg.get("error_routes") or [])
def _keys(data, depth=0):
if depth > 4:
return []
if isinstance(data, dict):
found = [k for k in data if isinstance(k, str)]
for value in data.values():
found += _keys(value, depth + 1)
return found
if isinstance(data, list):
found = []
for value in data[:5]:
found += _keys(value, depth + 1)
return found
return []
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.fullmatch(k)]
hidden = len(keys) - len(shown)
return ", ".join(shown) + (f" (+{hidden} unprintable)" if hidden else "")
def _json_body(resp):
try:
return json.loads(resp.body), True
except ValueError:
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():
token = os.environ.get("GUARDRAILS_JWT2")
return {"Authorization": f"Bearer {token}"} if token else None
def _fields_probe(session, base, route):
target = base + route["path"]
verdict, note = _fields_verdict(fetch(session, "GET", target, _bearer()))
return Probe("exposure", f"fields:{route['path']}", verdict, target, note)
def probe_exposure(session, plan):
cfg = plan.get("exposure")
if cfg is None:
return []
base = plan["base_url"].rstrip("/")
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_exposure, probe_rate_limit)
Extend plan validation (replace _plan_error):
def _obj(plan, key):
value = plan.get(key)
return value if isinstance(value, dict) else {}
def _plan_paths(plan):
"""Every path the probe would append to base_url (None when malformed)."""
routes = plan.get("routes") or []
cfg, supa, rate = _obj(plan, "exposure"), _obj(plan, "supabase"), \
_obj(plan, "rate_limit")
return ([r.get("path") if isinstance(r, dict) else None for r in 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"):
if cfg.get(key) is not None and not isinstance(cfg[key], list):
return f"exposure.{key} must be a list"
return ""
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"
error = _exposure_error(plan.get("exposure"))
if error:
return error
bad = [p for p in _plan_paths(plan)
if not isinstance(p, str) or not p.startswith("/")]
return 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 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 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
git add skills/guardrails/scripts/probe.py lib/tests/guardrails-probe.test.sh
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"
Task 6: The /a11y skill: SKILL.md, references, prompts, lazy rule, routing row, profiles, locks
Files:
- Create:
skills/a11y/SKILL.md,skills/a11y/references/checks.md,skills/a11y/test-prompts.json,rules/a11y.md - Modify:
rules/web-building.md(two fragments point atrules/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:
-
Consumes:
skills/a11y/scripts/scan.py(Task 4),lib/contract-interview.md(flowa11y),lib/verify-secure-loop.md, thebugfixeragent. -
Produces: the public
/a11ycommand, report.claude/audits/A11Y.md, branchbugfix/a11y-<date>, baseline.claude/audits/.a11y-baseline.json. -
Step 1: Write
skills/a11y/SKILL.md
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.
---
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. 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 <url you own>] [--report-only]'
---
# /a11y
Checks a project's accessibility baseline (`rules/a11y.md`), then fixes what
the user accepts and proves each fix. A scanner reads the tree as data and
finds what text can prove: a missing alt, an unlabeled field, a click with no
keyboard path, a focus outline removed, a positive tabindex. This skill judges
the hits, walks the main flow with the keyboard when a browser is available,
proposes fixes, applies the accepted ones and scans again until every accepted
fix is proven.
The scanner proves absence of a baseline, never presence of accessibility. A
clean scan means "no static finding", and the report says exactly that. Full
WCAG conformance (contrast, structure, ARIA semantics, axe or pa11y runs) is
`/web-validate`'s job.
## MODEL GATE (blocking, before any other step)
Run `$HOME/.claude/lib/model-gate.md`. Judging hits and writing alt and label
text requires Fable or Opus. Verdict `small` → STOP: the gate prints the
remedy. ROUTING: follow `$HOME/.claude/lib/effort-shift.md` (phases via
`mcp__model-router__route`); each step below names its phase.
## STEP 1: Scope
Work in the project the user names, else the current directory. Say in one
line what you will scan. `--report-only` stops after STEP 5: audit, no fix.
## STEP 2: Run the scanner
```
python3 -B "$HOME/.claude/skills/a11y/scripts/scan.py" <path>
```
Add `--exclude a/b,c` to skip copies or vendored code, `--json` for machine
output. Exit 0 means no FAIL, 1 means at least one, 2 is a usage error. It
never executes project code. Severities: **FAIL**, the baseline is provably
missing; **WARN**, a pattern that is often wrong, judgment needed.
## STEP 3: Judge every FAIL and WARN
Read the file around each line. Label it CONFIRMED, FALSE POSITIVE (say why)
or ACCEPTED RISK (the user decides, never you). A decorative image with
`alt=""`, a field labeled through `aria-labelledby`, a click handler on a
`role="presentation"` overlay and an outline swapped for a visible border or
ring are the usual false positives; `references/checks.md` lists the blind
spots. Check them before calling a hit false.
## STEP 4: Keyboard walk (on `--live`, read-only)
With a dev server the user names, walk the main flow with Tab only through
`/browse`: every control reached in a sensible order, the focus visible at
each stop, Enter and Space working on what looks clickable, Escape closing
what opened. Record each stop that fails with the page and the element.
Without a browser tool, or without `--live`, the report marks the walk
"not done": a static scan cannot see a keyboard trap, a focus order or a
modal that loses focus.
## STEP 5: Report
Write `.claude/audits/A11Y.md`: one table with status PASS, FAIL, WARN or
N/A per rule, the evidence, the fix in one line, and the keyboard walk's
result (done, with its stops, or not done). PASS means "no static finding".
Keep it short; no filler sections. `--report-only`, or nothing CONFIRMED:
reply with counts, the FAILs with file:line and the walk's stops, then stop.
## STEP 6: Propose fixes
`mcp__model-router__route(phase="plan")`: wording is the deepest thinking in
this run, it goes to the plan row.
One proposal per CONFIRMED finding, grouped by rule and file; merge pairs
that one change closes (one `:focus-visible` rule closes every outline
removal in a stylesheet). FALSE POSITIVE and ACCEPTED RISK get no proposal.
Each proposal:
- **number, rule, file(s)**, and the problem in one line;
- **the fix**, concrete: file:line and the change. A missing alt gets a
description of what the image shows, or `alt=""` when it is decorative; an
unlabeled field gets a `label for`, a wrapping label or `aria-label`; a
clickable `div` becomes a `button`, or gains `role`, `tabindex` and a key
handler; a removed outline gets a `:focus-visible` style;
- **choices the user sees**: the alt text and the label wording, each with
your proposed value, named so the user can change it. These are content,
never invented silently: they ship only with the user's acceptance;
- **risk**: what it can break (`button` reset styles, a changed tab order).
`DECISION` when no wording is defensible (an image you cannot describe);
- **proof**: the scanner pairs that must disappear (`RULE:path`), and the
walk stop that must pass when `--live` ran.
Save the proposals to `.claude/tasks/plans/<YYYY-MM-DD>-a11y-<HHMM>.md` and
append them to the report. In the reply, show them as a numbered list, one or
two lines each, DECISION marked.
## STEP 7: Approval (gate, ends the turn)
Nothing is applied without the user's explicit acceptance. Ask once, then
stop the turn:
```
Which fixes do I apply? "all" (every proposal except DECISION ones),
numbers ("1,3,5-7"), "none", or an amendment ("2 with the alt 'Team photo'").
A DECISION proposal needs its number plus your wording.
```
On resume, `mcp__model-router__route(phase="reflect")`. "none" → stop,
proposals stay in the report. An amendment rewrites that proposal in the plan
file before anything else. Accepted set empty → stop.
## STEP 8: Apply
1. **Branch.** Not a git repository → stop: fixes need a diff to review.
On `main`/`develop`, `bash ~/.claude/lib/gitflow.sh start bugfix
a11y-<YYYY-MM-DD>`; on a working branch, stay. Never `finish`.
2. **Baseline**, before any edit:
`python3 -B <scan.py> <root> --json > .claude/audits/.a11y-baseline.json`.
A derived file: never staged, never committed.
3. **Contract** per `$HOME/.claude/lib/contract-interview.md` (STEP 4
template, `flow: a11y`). REQUEST = the user's acceptance verbatim plus the
accepted proposals. One criterion per accepted proposal, its oracle the
scanner itself:
```
1. <proposal 1 in one line>
CHECK: python3 -B "$HOME/.claude/skills/a11y/scripts/scan.py" '<abs root>' --assert-absent 'RULE:path,RULE:path'
EXPECT: A11Y-CLEAR
EVIDENCE: pending
```
Add one criterion for the project suite when one exists
(`CHECK: <test command> && echo TESTS-GREEN`, `EXPECT: TESTS-GREEN`). The
keyboard walk is a criterion without CHECK: STEP 9 settles it. FILE SCOPE
= the files the accepted proposals name. Paths go in single quotes; a path
holding a single quote is named to the user, never written into a CHECK.
4. **Positive control.** Run each oracle once on the unfixed tree: it must
fail. An oracle that passes before the fix proves nothing; drop it, find
why, and say so.
5. **Dispatch the executor**, one fresh `bugfixer` for the accepted set
(batches of 8 proposals at most, one after the other on the same branch):
```
mcp__model-router__route(phase="orchestrate") # send with the Agent call
Agent(subagent_type="bugfixer")
prompt: "CONTRACT: <path>
DIAGNOSIS: <each accepted finding: rule, file:line, evidence>
FIX PLAN: <the accepted proposals verbatim, with the user's wording; the
regression check of each is its contract oracle, plus the project test
the proposal names>
BRANCH: <current branch>
Apply to the letter. No commit, no branch ops, no security dispatch.
Finish with the BUGFIX-EXEC REPORT."
```
`NEED-DECISION` routes per MID-RUN CLARIFICATION of the contract include:
a wording, visible or scope question goes to the user verbatim.
`BLOCKED` → surface it, stop.
6. **Gates** per `$HOME/.claude/lib/verify-secure-loop.md`, `CONTRACT` the
path above, `DIFF` the executor's working-tree diff, `TEST` the suite.
GATE 0 runs every scanner oracle (the per-fix proof), GATE 1 a fresh
verifier, GATE 2 a fresh security-auditor. Loop caps and escalation are
the include's; loop decisions stay in this main loop.
## STEP 9: Re-pass (prove it all)
`mcp__model-router__route(phase="reflect")`. The gates proved each accepted
fix on its own; this pass proves the whole tree.
1. Full scan against the baseline:
```
python3 -B <scan.py> <root> --baseline .claude/audits/.a11y-baseline.json
```
Every accepted pair must show `FIXED`, and the run must end on
`A11Y-NO-NEW` (exit 0). A `NEW` hit is a regression the fix made.
2. Live: when STEP 4 ran, walk the same flow again once the user has reloaded
the dev server and says go. Each stop a proposal named must now pass.
3. Add an "after" column to `.claude/audits/A11Y.md`: proposal, before,
after, evidence.
Anything not fixed, or a NEW hit → one more round from STEP 6, limited to
those items. Two rounds at most: after the second, stop with the residuals
open and say so plainly. Never report a fix the re-pass did not prove.
## STEP 10: Commit and hand over
1. **Commit gate.** Show files, `git diff --stat` and the message, wait for
the user's go:
```
A11Y: READY TO COMMIT
FILES : <list>
MESSAGE : fix(a11y): <rules fixed, one line>
```
Then `git add <files touched>` (never `-A`, never the baseline file) and
commit, project convention else 50 words at most.
2. `mcp__model-router__route(phase="apply")` for the tail. Reply with: fixed
and proven (proposal, rule, file), still open and why, the walk's result,
the branch name. Merge waits for the user's explicit signal.
3. Offer to capitalize a reusable lesson (a false-positive class, a fix
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 (expected about 910 bytes).
- Step 2: Write
skills/a11y/references/checks.md
# Accessibility checks
Rule ids the scanner emits, what each proves, and the fix. Severity is the
default; a judged hit can be a false positive.
| Rule | Sev | Catches | Fix |
|---|---|---|---|
| A11Y-IMG-ALT | FAIL | `img` or `Image` without `alt` | describe it, or `alt=""` if decorative |
| A11Y-FIELD-LABEL | FAIL | native input, select, textarea with no label | `label for`, wrapping label or `aria-label` |
| A11Y-CLICK-NO-KEYBOARD | FAIL | click handler on a div or span lacking role, tabindex or key handler | use a `button` |
| A11Y-FOCUS-OUTLINE | FAIL / WARN | focus outline removed; WARN when a `:focus-visible` style exists elsewhere | style `:focus-visible` instead |
| A11Y-TABINDEX-POSITIVE | WARN | `tabindex` above 0 | use 0 or -1 and fix the DOM order |
## Blind spots
The scanner is regex over markup and styles. It cannot see:
- keyboard traps, focus order, a modal that keeps or loses focus, color
contrast: the `--live` walk covers the first three, `/web-validate` the
fourth
- a label wired through `aria-labelledby` to an element in another file
- components whose markup is built at runtime, minified bundles, anything
over 1 MB
- `.astro` files for the click rule (never flagged)
By design the scanner ignores: 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 `img` tags inside comments.
## Fix loop: oracles and re-pass
Every accepted fix is proven by the scanner itself, never by the executor's
word. Two check modes replace the report and its exit code:
| Mode | Passes when | Marker | Used by |
|---|---|---|---|
| `--assert-absent RULE:path,...` | none of these FAIL/WARN pairs remains, the domain was scanned, the tree is not empty | `A11Y-CLEAR <n>` | a contract `CHECK:` run by `lib/gates.sh` (GATE 0) |
| `--baseline before.json` | no FAIL/WARN hit appeared since the earlier `--json` run | `A11Y-NO-NEW` | STEP 9 re-pass |
Pairs match on rule and file, not line: a fix moves lines. An empty tree
fails the assertion, because absence there proves nothing. Run every oracle
once before the fix: it must fail. The baseline lists `FIXED` and `NEW`
pairs with their hit counts; a `NEW` hit after a fix is a regression.
- Step 3: Write
skills/a11y/test-prompts.json
[
{"id": 1, "prompt": "vérifie l'accessibilité de base de ~/Documents/faunosteo : clavier, alt, labels", "expected": "Runs the a11y scanner on the path, reads each A11Y FAIL and WARN in context, marks the keyboard walk not done (no --live), writes .claude/audits/A11Y.md, proposes fixes with alt and label wording as visible choices, stops for approval"},
{"id": 2, "prompt": "il manque des alt sur les images du site, corrige", "expected": "Scans, confirms each A11Y-IMG-ALT hit, proposes one alt text per image (or alt=\"\" for decorative ones) as a named choice, applies only after acceptance on a bugfix branch with --assert-absent oracles, re-scans against the baseline"},
{"id": 3, "prompt": "Walk my app at http://localhost:3000 with the keyboard only and tell me where focus gets lost", "expected": "Static scan first, then the Tab walk through /browse on the named localhost target, records each stop with no visible focus or unreachable control, reports them next to the static findings, fixes nothing without approval"},
{"id": 4, "prompt": "est-ce que mon site passe les critères WCAG AA ?", "expected": "Routes to /web-validate for WCAG conformance; runs /a11y only if the user asks for the keyboard/alt/label baseline"},
{"id": 5, "prompt": "a11y --report-only sur ce projet", "expected": "Scan and judgment only, report written, counts and file:line in the reply, no proposal, no branch, no edit"}
]
- Step 4: Write
rules/a11y.mdand pointrules/web-building.mdat it
rules/a11y.md:
---
paths: ["**/*.tsx", "**/*.jsx", "**/*.vue", "**/*.svelte", "**/*.astro", "**/*.html", "**/*.css", "**/*.scss"]
---
# Accessibility baseline (audit and fix: `/a11y`)
- Everything reachable and usable by keyboard, focus always visible.
`:focus-visible` styled, never `outline: none` without a replacement.
- Every image has an `alt` (empty when decorative). Every field has a label;
a placeholder is not a label.
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
stashed=0
if [ -n "$(git status --short mods/model-router/routing.json)" ]; then
git stash push -m "pre-existing routing dialog decisions" -- mods/model-router/routing.json && stashed=1
fi
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"))'.
git add mods/model-router/routing.json
git commit -m "chore(model-router): a11y skill row (reflect)"
if [ "$stashed" = 1 ]; then git stash pop; fi
git stash list
After the pop (only when the push ran), 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
- In
lib/profiles/audit.profile,dev.profile,web-full.profile,full.profile,max.profile: add the linea11y personalright after theguardrails …personalline. Inlib/profiles/web.profile: add it right after theweb-validate …personalline. The name column is 34 characters wide:a11yplus 30 spaces. lib/tests/model-routing.test.sh: adda11yat the end of thefor s in ship-feature … guardrails; dolist and change the comment to# 1) gate wired in the 17 reflection skills (orchestrators, /analyze, /guardrails, /a11y).lib/tests/loops-light.test.sh: find howGSKis defined near the top (GSK="$R/skills/guardrails/SKILL.md"or similar) and defineASKthe same way forskills/a11y/SKILL.md. After the guardrails block add:echo "── skills/a11y/SKILL.md (fix loop reuses the bugfix circuit) ──" tf "a11y contract include" "$ASK" "lib/contract-interview.md" tf "a11y uses shared include" "$ASK" "lib/verify-secure-loop.md" tf "a11y dispatches bugfixer" "$ASK" 'subagent_type="bugfixer"' tf "a11y scanner is the oracle" "$ASK" "EXPECT: A11Y-CLEAR" tf "a11y positive control" "$ASK" "Positive control" tf "a11y approval gate" "$ASK" "Nothing is applied without the user's explicit acceptance" tf "a11y re-pass baseline" "$ASK" "A11Y-NO-NEW"lib/verify-secure-loop.mdline 1:(feat, bugfix, guardrails)→(feat, bugfix, guardrails, a11y).lib/contract-interview.mdline 117:…|onboard|guardrails>→…|onboard|guardrails|a11y>.agents/bugfixer.mdline 3:dispatched by /bugfix (or /guardrails for accepted fixes)→dispatched by /bugfix (or /guardrails and /a11y for accepted fixes).
- Step 7: Commit, then run the censuses on the committed tree
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.
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> 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
Files:
-
Modify:
skills/guardrails/SKILL.md,skills/guardrails/references/checks.md,skills/guardrails/test-prompts.json,rules/secure-by-default.md -
Test:
make test suite='lib/tests/loops-light.test.sh lib/tests/model-routing.test.sh lib/tests/skill-routing-census.test.sh lib/tests/doctrine-citers.test.sh' -
Step 1:
skills/guardrails/SKILL.mdfrontmatter
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. 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 <url you own>] [--report-only]'.
- Step 2:
skills/guardrails/SKILL.mdbody
- STEP 1:
Domains: \api`, `hosting`, `a11y`, `supabase`, `messaging`, `functions`.→Domains: `api`, `hosting`, `supabase`, `messaging`, `functions`, `injection`, `exposure`.` - STEP 4: replace the
- **A11y**: …bullet (two lines) with:- **Injection**: for each INJ hit, trace the interpolated value to its 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**: 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. - 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.` - 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 `/`.` - STEP 5.3: after
CLOSED means it was refused or empty.addSKIPPED and ERROR mean the target was not observed: never read either as proof of a fix. - 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. - 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). - 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.
- Step 3:
skills/guardrails/references/checks.md
- Delete the
## a11ysection (heading and table). - Add after the
## hostingsection:## injection Patterns are per language: a Postgres `$1` placeholder, a tagged template (`sql\`…\``, `sql<T>\`…\``), 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`, `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, 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 | ## exposure | 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…); 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, 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 | - Blind spots list: replace
- keyboard traps, focus order, modal focus handling, color contrastwith- a SQL string assembled across several lines, or passed through a variable before the query call (trace it by hand) - whether a template literal's tag parameterizes: tagged templates are trusted - 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 - "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. - Live probe section: in the plan JSON example add, before the closing brace,
,\n "exposure": {"error_routes": ["/api/v1/notes/not-a-number"]}; after theEnvironment, from test keys only…sentence addThe 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:after the verdict paragraph add| sourcemap | `sourcemap:<script>` | a source map with sources answered 200 for a page script, or the script carries an inline map | EXP-SOURCEMAP-PUBLIC | | error-body | `error-body:<path>` | a 404 or a named error route returned a stack trace or an internal path | EXP-ERROR-STACK, EXP-DEBUG-ON | | fields | `fields:<path>` | a JSON 200 carried a password, salt, token, key or secret-like key (identifier-shaped names printed, never values) | EXP-RESPONSE-WIDE, EXP-HYDRATED-SENSITIVE |An exposure target the probe could not observe (unreachable page, no same-host script, a refused or non-JSON route, a map fetch that failed) is SKIPPED or ERROR, never CLOSED. Run the exposure block against a production build or a staging URL: a dev server serves maps and tracebacks by design, and its OPEN verdicts are dev artefacts, not findings.; and in the safety paragraph, aftera redirect to another host is never followed, so a key never leaves the named host.addA script on another host is never fetched. An error route is a path you own and name; the probe never guesses one beyond its single random 404.
- Step 4:
skills/guardrails/test-prompts.json
Append two entries before the closing ]:
{"id": 7, "prompt": "cherche les failles d'injection SQL dans ~/Documents/zenquality", "expected": "Runs the scanner's injection domain, traces each INJ hit to the source of the interpolated value, labels constants and cast values FALSE POSITIVE, proposes parameterized rewrites with the binding as a visible choice, applies only after acceptance with --assert-absent oracles"},
{"id": 8, "prompt": "est-ce que mon site laisse voir trop de choses dans le navigateur ? console, network, inspecteur", "expected": "Runs the exposure domain, reads each EXP hit in context, offers the live probe with an exposure block against a production build the user names, reports source maps served, error bodies and sensitive keys next to the static findings, never prints a response value, marks dev-server OPENs as dev artefacts"}
- Step 5:
rules/secure-by-default.md
Only what CLAUDE.global.md's Security section and this file's "Every API" section do not already say (parameterized queries, generic errors and "only needed fields" are already there).
- Line 1:
# Secure by default: five domains and every API→# Secure by default: six domains and every API. - Replace the
## 2. Accessibilitysection (heading and its two bullets) with:## 2. Injection - Raw escapes (`$queryRawUnsafe`, `knex.raw`, `text()`, `.raw()`) take bound values only; dynamic SQL in a function goes through `format()` with `%I` / `%L` and `USING`. - A filter object never comes straight from the request: allowlist the fields, cast the values. No shell command carries input into a DB tool. ## 3. Exposure (what the browser can see) - No data in the browser console, no source map in production, no debug flag in a committed config. - Hydrated state, `data-*` attributes, hidden fields and shipped HTML comments carry no token, hash, key or secret. - Renumber:
## 3. Supabase→## 4. Supabase,## 4. SMS and email→## 5. SMS and email,## 5. Cloud functions→## 6. Cloud functions. - Keyboard, alt and label doctrine now lives in
rules/a11y.md(Task 6): nothing else to add here.
- Step 6: Run the suites
Run: make test suite='lib/tests/loops-light.test.sh lib/tests/model-routing.test.sh lib/tests/skill-routing-census.test.sh lib/tests/doctrine-citers.test.sh'
Expected: all suites green.
- Step 7: Commit
git add skills/guardrails/SKILL.md skills/guardrails/references/checks.md skills/guardrails/test-prompts.json rules/secure-by-default.md
git commit -m "docs(guardrails): injection and exposure in the skill, the rule catalogue, the probe plan and secure-by-default; a11y handed to /a11y"
Task 8: Docs and routing citers: README, USAGE, CHANGELOG, global routing line, web-validate, seo and harden triggers, interviewer
Files:
-
Modify:
README.md,USAGE.md,CHANGELOG.md,CLAUDE.global.md:276,skills/web-validate/SKILL.md(description block),skills/seo/SKILL.md:11,skills/harden/SKILL.md:357,agents/interviewer.md:27 -
Test:
make test suite='lib/tests/skill-routing-census.test.sh lib/tests/doctrine-citers.test.sh';wc -l CLAUDE.global.md= 320 -
Step 1: README.md
- Replace the
/guardrailsrow with:| `/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) | - Add right after it:
| `/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` | /web-validaterow:W3C HTML/CSS validity + WCAG 2.1 accessibility audit→W3C HTML/CSS validity + WCAG 2.1 conformance audit (keyboard/alt/label basics → /a11y).
- Step 2: USAGE.md
First table (| Validité HTML/CSS + a11y | …): change to | Validité HTML/CSS + conformité WCAG | \/web-validate` |, add after it | Accessibilité de base (clavier, alt, labels) puis corriger | `/a11y` |, and change the guardrails row to | Auditer garde-fous (RLS, consentement, fonctions, mots de passe, injection SQL, fuites navigateur) puis corriger | `/guardrails` |`.
Second table: | \/web-validate` | Audit W3C + WCAG a11y | …→| `/web-validate` | Audit W3C + conformité WCAG | Avant livraison projet web ; bases clavier/alt/labels → /a11y |; add after it | `/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 |; change the guardrails row's first cell to Vérifier hébergement, Supabase RLS, consentement SMS/email, fonctions cloud, stockage des mots de passe, injection SQL, exposition navigateurand append to its third cell ; sonde `exposure` sur un build de production (source maps, corps d'erreur, clés sensibles)`.
- Step 3: CHANGELOG.md (Unreleased)
- In the
**Secure-by-default guardrails**bullet:makes five domains baseline on every project→makes six domains baseline on every project; deleteaccessibility (keyboard, visible focus, alt text, field labels),; aftercloud functions (no self-trigger, instance cap, budget stop)add, 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). After the sentence endingverdicts OPEN / CLOSED / SKIPPED / ERROR.addAnexposureblock 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/. - Add a new bullet right after it:
- **/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.
- Step 4: CLAUDE.global.md line 276
- SEO+GEO → seo (GEO only → geo); W3C + WCAG a11y → web-validate; → - SEO+GEO → seo (GEO only → geo); W3C + WCAG conformance → web-validate;. Then wc -l CLAUDE.global.md must still print 320.
- Step 5:
skills/web-validate/SKILL.md,skills/seo/SKILL.md,skills/harden/SKILL.md
web-validate description block: replace the two Triggers: lines and the disclaim line with
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.
and in the first sentence W3C HTML/CSS validity or WCAG 2.1 accessibility audit → W3C HTML/CSS validity or WCAG 2.1 conformance audit.
skills/seo/SKILL.md line 11: W3C/a11y → /web-validate → W3C/WCAG → /web-validate; keyboard, alt, labels → /a11y (keep the line under 80 columns; wrap inside the description block if needed).
skills/harden/SKILL.md line 357: a11y / WCAG (owned by /web-validate …) → WCAG conformance (owned by /web-validate) and the keyboard, alt and label baseline (owned by /a11y), keeping the rest of the line.
- Step 6:
agents/interviewer.mdline 27
note under QUALITY which of the five guardrail domains apply → note under QUALITY which of the six guardrail domains apply, and whether the accessibility baseline (\rules/a11y.md`) applies`.
- Step 7: Run the censuses and the stale-list grep
Run: make test suite='lib/tests/skill-routing-census.test.sh lib/tests/doctrine-citers.test.sh'
Expected: all suites green.
Run: grep -rn 'api,hosting,a11y' skills/guardrails rules agents README.md USAGE.md CHANGELOG.md; grep -n 'five domains\|five guardrail\|five baseline' rules/secure-by-default.md agents/interviewer.md README.md; grep -rn 'a11y → /web-validate\|W3C/a11y' skills/*/SKILL.md CLAUDE.global.md
Expected: no output.
- Step 8: Commit
git add README.md USAGE.md CHANGELOG.md CLAUDE.global.md skills/web-validate/SKILL.md skills/seo/SKILL.md skills/harden/SKILL.md agents/interviewer.md
git commit -m "docs: /a11y and the injection and exposure domains in README, USAGE, CHANGELOG; routing boundaries (web-validate, seo, harden, global line, interviewer)"
Task 9: Whole-branch verification
Files: none modified unless a check fails (then fix in the owning task's files and commit with a fix: message).
- Step 1: Full suite and shellcheck
Run: make test (expected all suites green, or only the two pre-existing T16a gitflow failures named in .claude/tasks/TODO.md; anything else is a regression of this branch).
Run: shellcheck *.sh hooks/*.sh lib/*.sh (expected: no output).
- Step 2: Contract oracles
Run: bash ~/.claude/lib/gates.sh run .claude/tasks/contracts/2026-10-18-guardrails-a11y-split-inj-exp-2210.md
Expected: every CHECK: criterion MET, evidence written back. Criteria 4, 5 and 11 were amended on disk on 2026-10-19 (after the plan challenge, before Task 1): they read skills/a11y/scripts/a11y_checks.py, require the file to exist and require a non-zero rule count (15 INJ+EXP rules, 5 A11Y rules), so a wrong path or an empty glob fails instead of passing vacuously. Verify with grep -n 'a11y_checks.py' <contract> (three hits) before running the gates.
- Step 3: Smoke the two CLIs and the tree by hand
python3 -B skills/guardrails/scripts/scan.py lib/tests/fixtures/guardrails-good | head -4
python3 -B skills/a11y/scripts/scan.py lib/tests/fixtures/a11y-good | head -4
git stash list
git status --short
Expected: scanned: api, hosting, supabase, messaging, functions, injection, exposure; scanned: a11y; an empty stash list; in the status only the two pre-existing M files (mods/model-router/routing.json, settings.json) and the untracked contract ?? .claude/tasks/contracts/2026-10-18-guardrails-a11y-split-inj-exp-2210.md, which the ship-feature memory commit (STEP 7) picks up with its evidence.