20 KiB
CONTRACT — phase2-guards
- date: 2026-11-02 | flow: ship-feature | branch: feature/phase2-guards (off develop
13ccef6, after the router-ask-tier and todo-reconcile merges) - status: active
REQUEST (verbatim — IMMUTABLE)
Phase 2 of the context mod queue (BDR-125), TODO.md "Phase 2, guards": native ask merge gate in settings.json, routing guard hosted in mods/model-router, shell deny hygiene (rtk rc=3 passthrough + read twins, targeted ask/deny rules, limits written down), code-limits PostToolUse hook, commit-msg hook deferred; designed 2026-10-25, already challenged (3 lenses + Fable re-challenge)
(user brief 2026-11-02, step 3: "Phase 2 (garde-fous, conçue le 2026-10-25, déjà challengée) via /ship-feature". The spec it points at is .claude/tasks/TODO.md lines 87-100 at develop 3cc4e0d, reproduced here as the design seed:)
- Killed by the challenges: the phrase-list merge gate; the
$.ui.askmod gate; G2 destructive guard (BLK-022, user-driven); whole-file code-limit reports; parsing commit text from Bash; Bash write-form detection in the routing guard. - Merge gate = native
askrules in settings.json, no mod:Bash(bash */gitflow.sh finish*),Bash(gitflow_finish*),Bash(git merge *); evaluate in the same benchBash(git pull *)andgit push x:developforms before adding them. Trade-off accepted: the BDR-068 /close auto-finish gets one dialog click; release-executor finish prompts too (its dispatcher runs finish inline if a sub-agent cannot prompt, BLK-018 option b). hard_deny line: "never editpermissions.askto skip the gate". - Routing guard (user pick: "always through a skill") hosted in
mods/model-router:tool.callon Edit/Write/NotebookEdit of a code file by the MAIN loop (noagentId) → deny with reason "route through /hotfix (≤2 files, obvious), /feat, /bugfix or /ship-feature" UNLESS this turn'sturnMain.source ∈ {skill, model}or a/routesticky is in force. Free: docs (.md),.claude/**, sub-agents, any write inside a skill run. Bash write forms deferred. hard_deny gains "a guard redirect is not a refusal to route around: enter the skill". Doctrine: the ceiling bullet becomes "the main loop writes no code outside a skill run, whatever the model". Proof: routing bench cases (L3 must enter a skill), long-brief replay in a clone, false-deny fixtures (doc edits, executor edits, in-skill edits), guard-off = today. - Shell deny hygiene (bench
.claude/tasks/plans/2026-10-25-bash-deny-probe/; mode stays auto): rtk hook rc=3 → pass through unchanged (noupdatedInput), re-pinhooks/.rtk-hook.sha256, hook test; rc=0 reads: census that everyBash(cat|head|tail <glob>)deny has itsBash(rtk read <glob>)twin, twins added. settings.jsonask+=Bash(sh -c *),Bash(bash),Bash(sh),Bash(bash -s*),Bash(bash <(*),Bash(/bin/sh *),Bash(/bin/bash *),Bash(/usr/bin/env bash*),Bash(/usr/bin/env sh*)(NOTBash(/*));deny+=Bash(awk *system(*. Interpreters go to the soft_deny prose. Each pattern proven in the bench before landing. P41 ("ask inert under auto") is contradicted by measurement: fix the item. Limits written down in one place (settings soft_deny note + README permissions). Folds TODO "docker host-root mount spellings" and the T42 dead-entry drop list if the release lands first. Interim accepted. - Commit message hook: DEFERRED.
- Code limits: classic PostToolUse hook, added lines only (Edit new_string, Write content), our code only (
lib/code-origin.sh), 80 columns only, at most 5 reports, once per file per turn,additionalContext, never a deny. - Proof: evasion matrix per rule (bench), the /close ritual finishes after one click, destructive commands never run live (plugin test with stubs only). Cleanup: compress the gitflow section only for the forms now enforced.
Session constraints (same brief): default model opus; verifier, security-auditor and plan-challengers pinned on opus; never commit a /model or UI write of settings.json (LRN-253: settings.json changes land through the git index, the working copy is patched with jq into a temp file and copied back); plan text through Write/Edit (BLK-039); destructive steps on the live tree in the main loop after the user's go, mv over rm (BLK-040).
CLARIFICATIONS
Pass A (gaps found by the STEP 0d read-before, asked at the STEP 1 brainstorm batch; answers land below [gated]):
- Q1 branch base: feature/router-ask-tier (unmerged) and the TODO chore both touch files phase 2 edits (register.ts, register.test.ts, TODO.md). Phase 2 branches off develop only after they merge (user signal), else conflicts and stale slot code (LRN-251, LRN-254).
- Q2 "inside a skill run" signal:
turnMainis nulled at every main turn end, so a best-tier run is carried byrunMain(rowed best skills: feat, bugfix, hotfix, ship-feature…) whileturnMain.source ∈ {skill, model}only holds within one turn. Unrowed code-writing skills (impeccable, design-html, qa, review, higgsfield-websites: 41 skills have no row) never set either → their inline writes would be denied unless rowed (TODO "deferred (BDR-123)" item) or another signal is chosen. - Q3 what is a "code file" for the guard and the hook;
.mdand.claude/**free per spec; config files (.json,.yml,.toml, settings.json, routing.json) decided at the brainstorm. - Q4 the model's own
routetool call setssource: 'model'and would lift the guard without a skill; the spec lists it as free; the prose must forbid calling it for that purpose. - Q5 an
askfrom a sub-agent: prompt or deny? Unverified; drives BLK-018 option (b) for release-executor's finish span. - Q6
Bash(git pull *): trailing*also matches the bare form (LRN-194);git pull*is allowed today and the lib pulls; Gitea protects develop/main against direct pushes. - Q7 twin census premise drifted: rtk 0.50.0 mirrors the user settings deny (rc=2 on
cat */*.pem); remaining gap = rules rtk does not read (project/local/--settings) and flag spellingshead -N .env(native gap too). The 6rtk cat|head|taildeny entries stay (T42 forbids removal). - Q8 code-limit hook: "once per file per turn" has no turn boundary in a PostToolUse payload; Write content = the whole file; columns in bytes vs characters.
- Q9 the hard_deny "Routing around a guardrail" clause says a refusal ends the attempt; the guard's deny says "enter the skill": the two must be reconciled in the same entry, CLAUDE.global.md Workflow clause included.
- Q10 T42 dead-entry drop and the 6 obsolete
rtk cat|head|tailentries: removing deny entries is the user's own edit (hard_deny "Disarming"); out of Claude's scope.
Brainstorm answers [gated 2026-11-02] (user: "oui aux recommandations", recommendations 1-9):
- Branch base: feature/router-ask-tier and chore/todo-reconcile-bdr125 merge first, on an explicit merge signal (not given yet); then feature/phase2-guards off develop.
- Guard run signal:
runMain !== nullORturnMain.source ∈ {skill, model}OR a/routesticky (userMain); rows added in routing.json for the unrowed code-writing skills (folds TODO "deferred (BDR-123)"). - Code file = any path except
.md,.txt,.claude/**,docs/**; config files (.json,.yml,.toml, settings.json, routing.json) count as code. - A model
routetool call lifts the guard (spec kept); hard_deny gains "never aroutecall or/routeto pass the guard". - Merge gate ask rules:
Bash(git merge *),Bash(git -C * merge *),Bash(bash *gitflow.sh finish*),Bash(sh *gitflow.sh finish*),Bash(gitflow_finish*); nogit pull *;git push x:developcovered by the existinggit push *ask once the rc=3 passthrough lands. - Ask inside a sub-agent measured headless in the bench; BLK-018 option (b) coded regardless: /release-candidate runs
finishin the main loop. - rtk twins:
Bash(rtk read <glob>)andBash(*/rtk read <glob>)for the 14 cat/head/tail deny entries, plushead -* .env*/tail -* .env*forms if the bench proves the native gap; census = static test; the 6rtk cat|head|tailentries stay (T42). - Code-limits hook: once per file per session (TMPDIR sentinel keyed on session_id), added lines from
git diff -U0when the file is tracked else new_string/content, columns in characters, extensions sh bash ts js mjs py rs jq, fires in sub-agents too. - Dead deny entries: removal is the user's hand edit (list handed over); P41: README and SETTINGS.md corrected, the template ask list stays.
Plan challenge round 1 (2026-11-02, correctness FATAL(8), robustness FATAL(5), simplicity CONCERNS(1)) → plan r2; three amendments reverse or widen gated answers and await the user at the STEP 3 gate: (a) answer 2: the guard latches on any skill run in the session instead of adding 16 routing rows; (b) answer 5: Bash(git -C * merge *) dropped, Bash(bash "*gitflow.sh" finish*) added; (c) answer 7: extra shell and cat flag forms, each bench-approved. See the spec § R2 amendments.
STEP 3 gate [gated 2026-11-02] (user: "oui aux trois, le prompt s'affiche, lance"): plan r3 (docs/superpowers/plans/2026-11-02-phase2-guards.md, fccdb1e) approved; amendments (a) skill latch instead of rows, (b) git -C * merge * dropped + quoted finish rule, (c) extra shell and cat flag forms (bench-approved only) accepted. Interactive fact, user-run 2026-11-02 in an auto-mode session with --settings '{"permissions":{"ask":["Bash(git merge *)"]}}': git merge -h raised the prompt "Ask rule Bash(git merge *) overrides auto mode for this command" (Yes / No). Task 8 may state that ask prompts under auto mode.
Merge-gate review [gated 2026-11-02] (user answers after GATE 1 ECARTS(6)): criterion 16 replaces 11; criterion 1's gitflow_finish* clause abandoned as a stated residual; criterion 5 amended: matcher Edit|Write (NotebookEdit cannot report: .ipynb is outside the extension list) and no temp HOME in the suite (the hook never reads HOME; it finds lib/ from its own resolved path), per plan r3 conf 7; criterion 7 amended: the gitflow section gains the enforcement sentence and keeps its prose (only "finish on an explicit human signal" is now enforced), per the approved spec. Criterion 9's /close one-click check runs after the merge, from develop, by the user (a chore branch /close creates is the only one it finishes; on this feature branch it commits in place).
ACCEPTANCE CRITERIA (seed, enriched at STEP 3 [gated])
-
settings.json
permissions.askholds the merge-gate rules decided at the brainstorm; each is proven in the bench (run.shanalogue,--setting-sources local) to prompt/deny the finish and merge forms and to leavegitflow.sh startand plain git free; the bench rows are saved under.claude/tasks/plans/<date>-phase2-bench/. -
settings.json
permissions.askgains the shell forms andpermissions.denygainsBash(awk *system(*plus thertk readtwins decided at the brainstorm, each proven in the bench; no existing deny entry removed (T41/T42 green);Bash(/*)absent. -
hooks/rtk-rewrite.sh rc=3 → exit 0 with no
updatedInput(the native rules see the original command); the pinhooks/.rtk-hook.sha256matches the file; lib/tests/rtk-rewrite.test.sh holds the rc=3 case (precondition-skipped when the live rtk does not return 3 for the probe) andrtk rewriteof the bench'sgit push origin :featureanalogue is no longer rewritten by the hook. -
mods/model-router: a
tool.callhook on Edit, Write and NotebookEdit denies a MAIN-loop write of a code file with the reason text decided at the brainstorm unless the run signal decided there holds; docs,.claude/**, sub-agents and in-run writes pass; the guard is off with the router (/route off,enabled:false); tests cover deny, each free path, guard-off, and the fixture set of false denies (doc edit, executor edit, in-skill edit across a user reply). -
hooks/code-limits.sh (PostToolUse Edit|Write|NotebookEdit): reports added lines over 80 columns of our code only (
lib/code-origin.sh= ours), at most 5 lines per report, the once-per-file rule decided at the brainstorm, asadditionalContext, never a deny or block; suite with a temp HOME and fixtures (ours vs foreign, over vs under, cap, dedupe); registered in settings.jsonhooks.PostToolUse. -
settings.json autoMode: hard_deny gains the two decided lines (never edit
permissions.askto skip the gate; a guard redirect is not a refusal) reconciled with the "Routing around a guardrail" entry; soft_deny gains the interpreter/limits note decided at the brainstorm;$defaultsstays first (doctor check). -
Doctrine: CLAUDE.global.md ceiling bullet model-agnostic; Workflow refusal clause carries the guard exception; gitflow section compressed for the forms now enforced, the BDR-068 sentence kept; ≤ 320 lines; README permissions section and templates/settings/SETTINGS.md no longer claim
askis inert under auto; every citer patched (doctrine-citers census green). -
make testall suites green, shellcheck clean, mods suite green (claude plugin test); settings.json changes on the branch limited topermissions.ask/deny,autoMode,hooks.PostToolUse(no UI write, nomodel). CHECK: cd /home/bchanot/Documents/claude && t=$(make test 2>&1) && printf '%s\n' "$t" | grep -q 'all suites green' && shellcheck ./.sh hooks/.sh lib/*.sh && echo GREEN EXPECT: GREEN EVIDENCE: MET exit=0 marker-found :: GREEN -
Proof recorded (plan, journal): the routing bench L3 prompt enters a skill in a clone under the guard; the long-brief replay;
/closeritual finishes after one click (user-run, interactive); guard off = today. -
TODO: phase 2 item ticked with what shipped; folded items (docker mount spellings, P41) closed or re-queued with the measured fact; T42 dead-entry drop handed to the user.
-
[gated 2026-11-02]Bench:.claude/tasks/plans/2026-11-02-phase2-bench/holds run.sh, bench.sh, cases.tsv, results.tsv (permissionMode column, every kept rowauto), rtk.tsv, approved.txt and phase2.jq; a rule is in approved.txt only when every row naming it hit its want and one of them expects ASKED/DENIED; M3q (quoted finish form) ASKED. CHECK: cd /home/bchanot/Documents/claude/.claude/tasks/plans/2026-11-02-phase2-bench && [ -s approved.txt ] && grep -qF 'Bash(bash "gitflow.sh" finish)' approved.txt && awk -F'\t' '$2=="M3q"' results.tsv | tail -1 | grep -q 'ASKED' && echo BENCH-OK EXPECT: BENCH-OK EVIDENCE: NOT-MET exit=1 (nonzero) :: -
[gated 2026-11-02]Guard: register.test.ts holds the GUARD tests of plan Task 3 + R3 (redirect before any skill, free paths,~/.claudeand worktrees are code, sub-agent free, latch across a typed apply skill and a model-loaded unrowed skill, sub-agent Skill call does not latch, route-tool phase for one turn, typed /route, /route clear and /route off→on re-arm, /model hand pick does not open, /clear re-arms,/../paths are code); the mods suite is green. CHECK: cd /home/bchanot/Documents/claude && [ "$(/usr/bin/grep -c "^test('GUARD:|^ test(`GUARD:" mods/model-router/hooks/register.test.ts)" -ge 14 ] && a=$(make test suite=lib/tests/mods.test.sh 2>&1) && printf '%s\n' "$a" | grep -q 'all suites green' && echo GUARD-OK EXPECT: GUARD-OK EVIDENCE: MET exit=0 marker-found :: GUARD-OK -
[gated 2026-11-02]Hooks: the rtk suite holds T11-T13 and the pin matches; the code-limits suite passes 14 checks; both hooks shellcheck clean and ≤ 80 columns. CHECK: cd /home/bchanot/Documents/claude && (cd hooks && sha256sum -c .rtk-hook.sha256 >/dev/null) && a=$(make test suite=lib/tests/rtk-rewrite.test.sh 2>&1) && printf '%s\n' "$a" | grep -q 'all suites green' && b=$(make test suite=lib/tests/code-limits.test.sh 2>&1) && printf '%s\n' "$b" | grep -q 'PASS=14 FAIL=0' && shellcheck hooks/rtk-rewrite.sh hooks/code-limits.sh && [ "$(awk 'length($0) > 80' hooks/code-limits.sh | wc -l)" = 0 ] && echo HOOKS-OK EXPECT: HOOKS-OK EVIDENCE: NOT-MET exit=1 (nonzero) :: -
[gated 2026-11-02]Settings: every approved rule and every rtk read twin is present (push-guard T62, T63 green), no old entry left any permissions or autoMode list (set check against develop),hooks.PostToolUseregisters code-limits, the branch diff of settings.json carries notheme,modelorswitchModelsOnFlagchange. CHECK: cd /home/bchanot/Documents/claude && a=$(make test suite=lib/tests/push-guard.test.sh 2>&1) && printf '%s\n' "$a" | grep -q 'all suites green' && [ "$(jq -n --slurpfile o <(git show develop:settings.json) --slurpfile n <(git show HEAD:settings.json) '"permissions","allow"],["permissions","ask"],["permissions","deny"],["autoMode","allow"],["autoMode","soft_deny"],["autoMode","hard_deny" | map(. as $p | ($o[0] | getpath($p)) - ($n[0] | getpath($p))) | add | length')" = 0 ] && git show HEAD:settings.json | jq -e '.hooks.PostToolUse[] | select(.hooks[0].command == "bash ~/.claude/hooks/code-limits.sh")' >/dev/null && ! git diff develop..HEAD -- settings.json | grep -qE '^[-+] *"(theme|model|switchModelsOnFlag)"' && echo SETTINGS-OK EXPECT: SETTINGS-OK EVIDENCE: MET exit=0 marker-found :: SETTINGS-OK -
[gated 2026-11-02]Release and capitalize: noSPAN: finishorfinish+tagleft in skills, agents, lib, README.md, USAGE.md; release-candidate STEP 5 runsgitflow.sh finishandgit tag -ain the main loop; capitalize 5C and STEP 6 name the declined-prompt outcome. CHECK: cd /home/bchanot/Documents/claude && ! /usr/bin/grep -rqn 'SPAN: finish|finish+tag' skills agents lib README.md USAGE.md && /usr/bin/grep -q 'git tag -a v<X.Y.Z> main' skills/release-candidate/SKILL.md && /usr/bin/grep -qi 'declined' skills/capitalize/SKILL.md && echo RELEASE-OK EXPECT: RELEASE-OK EVIDENCE: MET exit=0 marker-found :: RELEASE-OK -
[gated 2026-11-02](replaces 11, user-approved) Bench: the directory holds run.sh, bench.sh, cases.tsv, results.tsv (permissionMode column, every rowauto), rtk.tsv, approved.txt, phase2.jq; approved.txt holdsBash(bash *gitflow.sh finish*); the quoted call-site formbash "$HOME/…/gitflow.sh" finishis ASKED under it, isolated (M3x) and with the live settings (L6). CHECK: cd /home/bchanot/Documents/claude/.claude/tasks/plans/2026-11-02-phase2-bench && for f in run.sh bench.sh cases.tsv results.tsv rtk.tsv approved.txt phase2.jq; do [ -s "$f" ] || exit 1; done && grep -qF 'Bash(bash gitflow.sh finish)' approved.txt && awk -F'\t' '$2=="M3x"' results.tsv | tail -1 | grep -q 'ASKED' && awk -F'\t' '$2=="L6"' results.tsv | tail -1 | grep -q 'ASKED' && ! awk -F'\t' '$2 ~ /^[A-Z][0-9]/ && $6 != "" && $6 != "auto"' results.tsv | grep -q . && echo BENCH-OK EXPECT: BENCH-OK EVIDENCE: MET exit=0 marker-found :: BENCH-OK
ABANDON: 1 the Bash(gitflow_finish*) clause is impossible as a static rule: the bench shows the sourced-function form source …/gitflow.sh; gitflow_finish RAN under it (M5), so it is not added; the form rests on the soft_deny "Static rule blind spots" entry and is named in README "Static rule limits"; no skill types it (they all type bash … gitflow.sh finish, asked). User-accepted residual 2026-11-02.
ABANDON: 11 the M3q clause is impossible: the permission matcher does not match a literal quote inside a pattern (M3q Bash(bash "*gitflow.sh" finish*) RAN, M6q RAN), so that rule cannot be approved; the clause's purpose (the quoted finish form every skill types is asked) is met by Bash(bash *gitflow.sh finish*) (M3x ASKED isolated, L6 ASKED live); handoff: criterion 16, approved by the user 2026-11-02.
FILE SCOPE (final, STEP 3 [gated 2026-11-02])
- settings.json (
permissions.ask,permissions.deny,autoMode.hard_deny/soft_deny,hooks.PostToolUse) through the index recipe - hooks/rtk-rewrite.sh, hooks/.rtk-hook.sha256, lib/tests/rtk-rewrite.test.sh
- hooks/code-limits.sh (new), lib/tests/code-limits.test.sh (new)
- mods/model-router/hooks/register.ts, register.test.ts
- CLAUDE.global.md, README.md, templates/settings/SETTINGS.md, lib/tests/push-guard.test.sh (T62, T63), skills/release-candidate/SKILL.md, agents/release-executor.md, skills/capitalize/SKILL.md (5C declined prompt)
- .claude/tasks/plans/2026-11-02-phase2-bench/ (bench, approved.txt, phase2.jq, long-brief.txt), .claude/tasks/TODO.md, docs/superpowers/{specs,plans} (transient), CHANGELOG.md