Files
claude/.claude/tasks/contracts/2026-11-02-phase2-guards-1545.md
T

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.ask mod 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 ask rules in settings.json, no mod: Bash(bash */gitflow.sh finish*), Bash(gitflow_finish*), Bash(git merge *); evaluate in the same bench Bash(git pull *) and git push x:develop forms 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 edit permissions.ask to skip the gate".
  • Routing guard (user pick: "always through a skill") hosted in mods/model-router: tool.call on Edit/Write/NotebookEdit of a code file by the MAIN loop (no agentId) → deny with reason "route through /hotfix (≤2 files, obvious), /feat, /bugfix or /ship-feature" UNLESS this turn's turnMain.source ∈ {skill, model} or a /route sticky 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 (no updatedInput), re-pin hooks/.rtk-hook.sha256, hook test; rc=0 reads: census that every Bash(cat|head|tail <glob>) deny has its Bash(rtk read <glob>) twin, twins added. settings.json ask += 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*) (NOT Bash(/*)); 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: turnMain is nulled at every main turn end, so a best-tier run is carried by runMain (rowed best skills: feat, bugfix, hotfix, ship-feature…) while turnMain.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; .md and .claude/** free per spec; config files (.json, .yml, .toml, settings.json, routing.json) decided at the brainstorm.
  • Q4 the model's own route tool call sets source: '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 ask from 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 spellings head -N .env (native gap too). The 6 rtk cat|head|tail deny 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|tail entries: 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):

  1. 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.
  2. Guard run signal: runMain !== null OR turnMain.source ∈ {skill, model} OR a /route sticky (userMain); rows added in routing.json for the unrowed code-writing skills (folds TODO "deferred (BDR-123)").
  3. Code file = any path except .md, .txt, .claude/**, docs/**; config files (.json, .yml, .toml, settings.json, routing.json) count as code.
  4. A model route tool call lifts the guard (spec kept); hard_deny gains "never a route call or /route to pass the guard".
  5. Merge gate ask rules: Bash(git merge *), Bash(git -C * merge *), Bash(bash *gitflow.sh finish*), Bash(sh *gitflow.sh finish*), Bash(gitflow_finish*); no git pull *; git push x:develop covered by the existing git push * ask once the rc=3 passthrough lands.
  6. Ask inside a sub-agent measured headless in the bench; BLK-018 option (b) coded regardless: /release-candidate runs finish in the main loop.
  7. rtk twins: Bash(rtk read <glob>) and Bash(*/rtk read <glob>) for the 14 cat/head/tail deny entries, plus head -* .env* / tail -* .env* forms if the bench proves the native gap; census = static test; the 6 rtk cat|head|tail entries stay (T42).
  8. Code-limits hook: once per file per session (TMPDIR sentinel keyed on session_id), added lines from git diff -U0 when 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.
  9. 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])

  1. settings.json permissions.ask holds the merge-gate rules decided at the brainstorm; each is proven in the bench (run.sh analogue, --setting-sources local) to prompt/deny the finish and merge forms and to leave gitflow.sh start and plain git free; the bench rows are saved under .claude/tasks/plans/<date>-phase2-bench/.

  2. settings.json permissions.ask gains the shell forms and permissions.deny gains Bash(awk *system(* plus the rtk read twins decided at the brainstorm, each proven in the bench; no existing deny entry removed (T41/T42 green); Bash(/*) absent.

  3. hooks/rtk-rewrite.sh rc=3 → exit 0 with no updatedInput (the native rules see the original command); the pin hooks/.rtk-hook.sha256 matches 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) and rtk rewrite of the bench's git push origin :feature analogue is no longer rewritten by the hook.

  4. mods/model-router: a tool.call hook 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).

  5. 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, as additionalContext, never a deny or block; suite with a temp HOME and fixtures (ours vs foreign, over vs under, cap, dedupe); registered in settings.json hooks.PostToolUse.

  6. settings.json autoMode: hard_deny gains the two decided lines (never edit permissions.ask to 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; $defaults stays first (doctor check).

  7. 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 ask is inert under auto; every citer patched (doctrine-citers census green).

  8. make test all suites green, shellcheck clean, mods suite green (claude plugin test); settings.json changes on the branch limited to permissions.ask/deny, autoMode, hooks.PostToolUse (no UI write, no model). 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

  9. Proof recorded (plan, journal): the routing bench L3 prompt enters a skill in a clone under the guard; the long-brief replay; /close ritual finishes after one click (user-run, interactive); guard off = today.

  10. 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.

  11. [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 row auto), 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) ::

  12. [gated 2026-11-02] Guard: register.test.ts holds the GUARD tests of plan Task 3 + R3 (redirect before any skill, free paths, ~/.claude and 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

  13. [gated 2026-11-02] Hooks: the rtk suite holds T11-T13 and the pin matches; the code-limits suite passes 15 checks (T15, the symlinked-path case, added by the final-review fix wave db2937d; count updated by the controller, intent unchanged); 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=15 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: MET exit=0 marker-found :: HOOKS-OK

  14. [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.PostToolUse registers code-limits, the branch diff of settings.json carries no theme, model or switchModelsOnFlag change. 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

  15. [gated 2026-11-02] Release and capitalize: no SPAN: finish or finish+tag left in skills, agents, lib, README.md, USAGE.md; release-candidate STEP 5 runs gitflow.sh finish and git tag -a in 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

  16. [gated 2026-11-02] (replaces 11, user-approved) Bench: the directory holds run.sh, bench.sh, cases.tsv, results.tsv (permissionMode column, every row auto), rtk.tsv, approved.txt, phase2.jq; approved.txt holds Bash(bash *gitflow.sh finish*); the quoted call-site form bash "$HOME/…/gitflow.sh" finish is 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
  • USAGE.md (write guard documented, final-review Important 3) [gated 2026-11-02]
  • 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