From 030189726ad92027f14e31f7faa44441eedae3f8 Mon Sep 17 00:00:00 2001 From: bchanot Date: Mon, 2 Nov 2026 17:04:28 +0100 Subject: [PATCH] chore(tasks): phase 2 contract (brainstorm answers gated), TODO router ask-tier done, phase 2 in progress --- .claude/tasks/TODO.md | 4 +- .../2026-11-02-phase2-guards-1545.md | 64 +++++++++++++++++++ 2 files changed, 66 insertions(+), 2 deletions(-) create mode 100644 .claude/tasks/contracts/2026-11-02-phase2-guards-1545.md diff --git a/.claude/tasks/TODO.md b/.claude/tasks/TODO.md index bfbe86c..12df63b 100644 --- a/.claude/tasks/TODO.md +++ b/.claude/tasks/TODO.md @@ -70,7 +70,7 @@ Shared rules for every phase: - Proof: static glob check per moved rule + logged session; hook tests (design-toolchain-reminder one-liner, session-start graph branch); the four skills Read the lib (grep census); `/context` delta. - Cleanup: CLAUDE.global.md loses the moved sections (one pointer line each where needed), citers patched (doctrine-citers census); BDR-031 citers. -- [ ] **model-router: ask before routing to Fable** (in progress 2026-11-02: /feat on feature/router-ask-tier, contract `.claude/tasks/contracts/2026-11-02-router-ask-tier-1434.md`, plan r3 after 3 lenses + confirmation) (user ask 2026-11-02, after the phase 5 merge: both touch `mods/model-router/routing.json`). `/feat` on the mod: a `routing.json` key `askTier` (default `best`; `/route ask-tier on|off`) makes the router ask, once per span, BEFORE applying a route whose resolved model sits in that tier, with the reason (phase + its `about`, origin: skill row / `/route` / prompt rule / agent row) and the options `Fable` · `Opus instead (big tier)` · `stop asking this session`; no memory in `confirmed` (the existing first-use confirmation stays as is); never asks in `-p` (`askOr` already falls back to LATER). Files: mods/model-router/hooks/register.ts (+ register.test.ts), routing.json, USAGE.md (`/route` section). +- [x] **model-router: ask before routing to Fable** (done 2026-11-02: feature/router-ask-tier 9a24a62 + docs 789fd00, merged d4416fe; BDR-135, LRN-254; GATE 0 MET, verifier CONFORME 11/11, security PASS; contract `.claude/tasks/contracts/2026-11-02-router-ask-tier-1434.md`; live check pending: a typed best-tier skill from an opus session shows the question) (user ask 2026-11-02, after the phase 5 merge: both touch `mods/model-router/routing.json`). `/feat` on the mod: a `routing.json` key `askTier` (default `best`; `/route ask-tier on|off`) makes the router ask, once per span, BEFORE applying a route whose resolved model sits in that tier, with the reason (phase + its `about`, origin: skill row / `/route` / prompt rule / agent row) and the options `Fable` · `Opus instead (big tier)` · `stop asking this session`; no memory in `confirmed` (the existing first-use confirmation stays as is); never asks in `-p` (`askOr` already falls back to LATER). Files: mods/model-router/hooks/register.ts (+ register.test.ts), routing.json, USAGE.md (`/route` section). - [x] **Phase 5, per-project and per-conversation profiles, native packs** (redesigned 2026-10-25, shrunk the same day; shipped 2026-11-02 on feature/phase5-profiles-packs, merged 3cc4e0d: BDR-134, contract .claude/tasks/contracts/2026-11-01-phase5-profiles-packs-1300.md; spec and plan purged at finish (BDR-065), facts in LRN-248 and the contract; gates re-run 2026-11-02: 7/7 MET) - [ ] User steps: MIGRATION "Profiles and packs (2026-11)" step 4 `.bashrc` (source `lib/cc.sh`, drop `dtach_claude` + `alias cc`; closes the TMPDIR item of BLK-021), then `/context` under `cc t full`, `cc t dev`, `cc t web` (phase 3 decides on them). - [ ] Follow-ups: `lib/pack-census.sh:67` `grep -qx` → `grep -qxF`; fragment top-level key allowlist in `lib/pack-census-fragments.jq` (today only `enabledPlugins` keys are compared). Done 2026-11-02: MIGRATION step 2 `$root` re-derivation + autostash-conflict note (0463583, 9cd9591). @@ -86,7 +86,7 @@ Shared rules for every phase: - Proof: two concurrent conversations in one project and two projects, canaries prove different listings, MCP and hooks per pack; `/context` per profile; nothing references `skills-disabled/` or `toggle-external.sh`. - Cleanup: `lib/profile.sh` symlink toggling + `skills-disabled/` (24 entries), user-scope plugin toggling in `set|apply|reset`, `lib/toggle-external.sh` (retire or rewire to packs) + `lib/tests/higgsfield.test.sh` + the CLAUDE.global.md "toggle-external.sh enable higgsfield" lines, every writer of the old layout (install-plugins.sh, update-all.sh, gstack and 21st installers), Makefile `profile*` targets rewired, `/profile` skill rewritten for packs, plugin-gate prose tied to global toggling, banner hint "/plugin-check before starting a new project", doctor profile checks, profile tests rewritten; `lib/profiles/*.profile` → `.json`. -- [ ] **Phase 2, guards** (redesigned 2026-10-25 after a 3-lens challenge, re-challenged the same day: native ask gate, guard hosted in model-router, interpreters in prose, commit-msg hook deferred) +- [ ] **Phase 2, guards** (in progress 2026-11-02: /ship-feature on feature/phase2-guards, contract `.claude/tasks/contracts/2026-11-02-phase2-guards-1545.md`, spec `docs/superpowers/specs/2026-11-02-phase2-guards-design.md` approved) (redesigned 2026-10-25 after a 3-lens challenge, re-challenged the same day: native ask gate, guard hosted in model-router, interpreters in prose, commit-msg hook deferred) - Killed by the challenges: the phrase-list merge gate; the `$.ui.ask` mod gate (its BDR-068 exception detector was never true: finish runs in the user's reply turn; a hard_deny naming mod sources was the robustness BLOCKER); G2 destructive guard (BLK-022, stays a user-driven task); whole-file code-limit reports (1498 lines > 80 cols across 92 files, over-fires); parsing commit text from Bash; Bash write-form detection in the routing guard (no measured Bash evasion, every inline write was Edit/Write). - Merge gate = native `ask` rules in settings.json, no mod (user pick 2026-10-25; bench r3 G1-G7: all forms DENIED headless incl. `"$HOME"`, absolute path, after `source`; `start` RAN): `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 (ask beats allow, no exemption); 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` (owner of the only run signal; mod state is plugin-private, `runMain` is BEST-tier-only and never ends: wrong signal). `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 (explicit escape hatch). Free: docs (.md), `.claude/**`, sub-agents, any write inside a skill run. Bash write forms deferred until a measured evasion. 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. diff --git a/.claude/tasks/contracts/2026-11-02-phase2-guards-1545.md b/.claude/tasks/contracts/2026-11-02-phase2-guards-1545.md new file mode 100644 index 0000000..5420275 --- /dev/null +++ b/.claude/tasks/contracts/2026-11-02-phase2-guards-1545.md @@ -0,0 +1,64 @@ +# 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 )` deny has its `Bash(rtk read )` 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 )` and `Bash(*/rtk read )` 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. + +## 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/-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: pending +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. + +## FILE SCOPE (seed from STEP 0d KEY COMPONENTS; final at STEP 3) +- 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, routing.json (rows for unrowed code-writing skills if decided) +- CLAUDE.global.md, README.md, templates/settings/SETTINGS.md, templates/settings/settings.json (P41), lib/tests/doctrine-citers.test.sh, lib/tests/push-guard.test.sh (T41 list if entries are added to the lock), lib/effort-shift.md (ceiling citers) +- .claude/tasks/plans/-phase2-bench/ (bench rows), .claude/tasks/TODO.md, docs/superpowers/{specs,plans} (transient), CHANGELOG.md