diff --git a/.claude/memory/decisions.md b/.claude/memory/decisions.md index ad4a9b7..92eabae 100644 --- a/.claude/memory/decisions.md +++ b/.claude/memory/decisions.md @@ -1614,3 +1614,9 @@ Supersedes [[BDR-030]]. - **Status (2026-11-17)**: accepted, amended 6022b9d: B2 stuck trigger in 6 gate skills (points to verify-secure-loop); end-of-run call before done/merge in feat, bugfix, ship-feature, init-project, a11y, guardrails, audit-delta+tour (fix applied only), release-candidate STEP 4; own budget; gate flows print diff stat, fix back through gates; verifier/security-auditor/plan-challenger advise only when dispatched; auditor raise upward only; plan-challenger protocol mirror. Commits f48343e 24354d9 6022b9d - **Status (2026-11-18)**: accepted, amended 51f343f: B3: challenge route rides first lib/challenge-plan.md call; summary Advisor row in 12 callers; feat/bugfix skip end call when GATE 0 MET + verifier CONFORME + security PASS (not DEGRADED, TOOL line) first attempt, ADVISOR field shows skip; item 3 reuse clause names later code commits - **Status (2026-11-20)**: accepted, amended 7979b9b..b71db28: allowed set + opus code review (ship-feature STEP 6, init-project STEP 10, standalone SDD final) one call via brief; never-call lines in opus agents/briefs; SubagentStart hook hooks/subagent-advisor.sh backstop; standalone SDD workers sonnet; Advisor row reason sub-agent + +## BDR-151 — Done and triage levers: done = oracles green, MINOR fold-or-drop, placed-decision skip, contract dry run, TODO +n/-m [accepted] (2026-11-20) +- **Decision**: six done/triage levers adopted (user 2026-11-20). Done = GATE 0 MET + verifier CONFORME + security PASS on same diff; later review reopens only with reproducible evidence (command failing on HEAD, real output shown wrong); scenario → one try to make it a failing command, else MINOR. MINOR on plan/diff: fold before dispatch or drop as `MINOR dropped:` line (report + run plan), never TODO/BUGS-FOUND/registry; security finding never droppable → user. Challenge skip for placed decision: text dictated by decision, decision = user's own words or challenged in run that wrote it, caller runs verify-secure-loop after dispatch. Contract dry run before dispatch: `- run-base: ` in contract + `gates.sh run` on mktemp copy. TODO loop notes start SHA in TODO.md. Memory-commit report ends `· TODO +n / -m`, counted before step 2. Verifier STEP 4: added plan files, appended `MINOR dropped:` lines, handed contract (whole if untracked, else EVIDENCE/run-base/[gated]) in scope. +- **Why**: session c9afbcbf open TODO 44→50 while closing items; MINOR→backlog was habit, no rule; challenge on placement runs found no MAJOR; verifier ECARTS were own contract bookkeeping. +- **Alternatives rejected**: TODO cap/expiry (cap 10 starts violated); "fix if under five minutes" post-gate exit; base from merge-base (overcounts multi-run branch) or pending diff only (misses earlier commits); verifier exempting whole `.claude/tasks/plans/` (142 durable plans, BDR-065 amendment). +- **Reference**: 19dfe7e, 39cf9dd, docs e8c061e; handoff plan .claude/tasks/plans/2026-11-20-done-and-triage-levers.md; contract .claude/tasks/contracts/2026-11-20-done-triage-levers-1413.md. Follow-up /feat (contract-interview, ship-feature STEP 6, init-project STEP 10, run_base `--end-of-options`, [gated] only untracked) open in TODO. diff --git a/.claude/memory/evals.md b/.claude/memory/evals.md index bc17883..9060c12 100644 --- a/.claude/memory/evals.md +++ b/.claude/memory/evals.md @@ -461,3 +461,10 @@ Dogfood: 3 blind lenses attacked the v1 plan for the plan-challenge feature itse - **Result**: 3.0.0 cut; E1/E2/G/H1-H7/BLK-049/Fable 5.2/perl runner merged, all `make test` green; F faunosteo branch ready (user merges). Every phase 0/0b/4a/1/5/2/4b-4d TODO line closed, BUGS-FOUND BDR-125 items fixed or closed with reason. - **Anomalies**: (1) gates caught what executors missed: H6b verifier ECARTS (profile.test.sh:123 comment silenced shellcheck from that line on; my brief said "counts equal to HEAD", gate said "clean"); perl plan r1 FATAL(3) (impossible digest assertion without tty, single quotes = SC2016, timeout(1) misread) and r2 still let a fast-failing runner pass timing-only tests. (2) my own slips: contract without EVIDENCE lines (H7, gates ERROR), reconcile loop misused `reconcile_blk_open`, awk print `" || "` tripped our own H4a deny row. (3) E3 npm -g edit refused by auto-mode classifier twice → user hand edit. (4) one feater died on API 403 mid-run, gates proved its diff. (5) doc audits found real drift twice (CLAUDE.global.md `open: unknown` clause, MIGRATION step 1 restoring enabledPlugins only). - **Action**: keep fresh gates + confirmation challenger (they paid every time); briefs quote the contract criterion verbatim, never paraphrase it; LRN-289/290 written; gates.sh label guard TODO stays. + +## EVAL-060 — /feat done-triage-levers: r1 9 MAJOR on unrecorded base, r2 2 MAJOR in r1 fixes, gates first pass (2026-11-20) +- **Subject**: /feat done-triage-levers 2026-11-20 (6 doctrine levers, 5 files + 1 gated citer). +- **Method**: advisor on plan, 3-lens challenge r1, 1 confirmation r2, GATE 0/1/2, positive control on untouched tree, scratch-clone simulation each revision. +- **Result**: advisor 5 pre-challenge fixes (exact prose in plan, criterion 12 oracle, TODO n/a, pass B batch). r1: 9 MAJOR → 5 distinct; all 3 lenses converged on unrecorded `base`; 2 on verifier scope too wide (142 durable plans). r2: 2 MAJOR inside r1 fixes (count after commit = silent 0; DONE claimed to bind ship-feature/init-project act sites unchanged). Gates first pass: MET 12/12, CONFORME, PASS (semgrep). Citer re-loop (effort-shift) MET 13/13, CONFORME, PASS. +- **Anomalies**: first dogfood of triage: GATE 2 REPORTED 2 items (run_base option injection LOW, [gated] lines on tracked contract) routed to user, not dropped → follow-up /feat. Census reads `§ Advisor point 1` as heading name (LRN-296 again). Doc-sync found un-patched citer (effort-shift § Advisor point 1). +- **Action**: challenge earned cost on a mechanism run (keep). Follow-up /feat + MEASURE line in TODO. Rule "rule changed → patch citers" needs a grep for every `§ ` the change discharges, before the plan. diff --git a/.claude/memory/journal.md b/.claude/memory/journal.md index 97dc74b..cac2fa3 100644 --- a/.claude/memory/journal.md +++ b/.claude/memory/journal.md @@ -789,3 +789,4 @@ rules: ## 2026-11-20 - /ship-feature advisor-subagent-scope (7979b9b 6be0669 b71db28): leak root cause = advisor server tool on every sub-agent, no filter, opus ignores CLAUDE.md attachment; rule moved into agent defs/briefs + SubagentStart hook + SDD sonnet pin; LRN-303; behavioural proof pending next usage table. +- /feat done-triage-levers (19dfe7e 39cf9dd, docs e8c061e): six levers in verify-secure-loop/challenge-plan/capitalize-commit/verifier/CLAUDE.global + effort-shift citer. r1 3 lenses 9 MAJOR (unrecorded base), r2 2 MAJOR in r1 fixes; gates first pass. BDR-151 LRN-304 EVAL-060. Follow-up /feat (5 files) + MEASURE line in TODO. Branch UNMERGED. diff --git a/.claude/memory/learnings.md b/.claude/memory/learnings.md index 26224a5..5ac6d3d 100644 --- a/.claude/memory/learnings.md +++ b/.claude/memory/learnings.md @@ -2180,3 +2180,9 @@ Rule: when editing a doctrine file under structure locks, grep the test's lock s - **Context**: 2026-11-19/20 advisor leak (Run C table: general-purpose 30 calls 7.1M tok, 29 from standalone SDD on opus in another repo). Fix 7979b9b..b71db28: rule in each agent definition/brief, SDD workers sonnet, hook backstop. - **Apply**: to scope any harness-listed server tool per sub-agent: put rule in agent definition or dispatcher brief, not CLAUDE.md; word allowance as explicit permission ("one call allowed"); hook = backstop only; behavioural proof = transcript tally, not delivery. - **Reference**: hooks/subagent-advisor.sh, lib/effort-shift.md § Advisor, LRN-294, LRN-295, LRN-301, BDR-150 + +## LRN-304 — Run-movement counter must run before the commit step; after it the diff is a silent +0 (2026-11-20) +- **Pattern**: snippet measuring a run's working-tree movement must run BEFORE the step that commits it. Read after `memory-commit.sh commit` (stages `.claude/tasks`), tree == HEAD, `git diff HEAD` empty rc 0 → silent `+0 / -0`. Fixture must cover the committed case, not only uncommitted. +- **Context**: 2026-11-20 /feat done-triage-levers, lever 6 `TODO +n / -m`. r1 put count in DO step 3 ("taken before step 2" in prose, but placed after). Contract CHECK ran on uncommitted fixture → green. r2 confirmation challenger traced step order → MAJOR. Fix: count in DO step 1, run-base SHA from contract, root pathspec `:/` (subdir cwd = silent 0 too), `--no-color --no-ext-diff`. +- **Apply**: any "report what the run changed" counter: place it before the commit step in the doc's own numbering; base = SHA recorded at run start, never a branch name; fixture rows: uncommitted, committed, subdir cwd, bad SHA → n/a. +- **Reference**: lib/capitalize-commit.md DO step 1, lib/memory-commit.sh MC_PATHS, LRN-298 (placement semantics), LRN-193 diff --git a/.claude/tasks/TODO.md b/.claude/tasks/TODO.md index 008d3e5..82431ac 100644 --- a/.claude/tasks/TODO.md +++ b/.claude/tasks/TODO.md @@ -4,7 +4,9 @@ Done history before 2026-10-08 removed 2026-10-23 (git keeps it: `git log -p -- .claude/tasks/TODO.md`); decisions live in `.claude/memory/`. ### Done, triage and loop levers (user 2026-11-20: "oui lance une session neuve avec les six leviers") -- [ ] NEXT, fresh session: /feat the six levers in .claude/tasks/plans/2026-11-20-done-and-triage-levers.md (done = oracles green, reopen only on reproducible evidence; MINOR fixed before dispatch or dropped; no challenge on a placed decision; loop on a frozen list; contract dry run + plan artifacts in scope; `TODO +n / -m` in summaries). 5 files: lib/verify-secure-loop.md, lib/challenge-plan.md, CLAUDE.global.md (1 line), lib/capitalize-commit.md, agents/verifier.md +- [x] DONE 19dfe7e + 39cf9dd (docs e8c061e) /feat feature/done-triage-levers, UNMERGED: /feat the six levers in .claude/tasks/plans/2026-11-20-done-and-triage-levers.md (done = oracles green, reopen only on reproducible evidence; MINOR fixed before dispatch or dropped; no challenge on a placed decision; loop on a frozen list; contract dry run + plan artifacts in scope; `TODO +n / -m` in summaries). 5 files: lib/verify-secure-loop.md, lib/challenge-plan.md, CLAUDE.global.md (1 line), lib/capitalize-commit.md, agents/verifier.md (contract .claude/tasks/contracts/2026-11-20-done-triage-levers-1413.md) +- [ ] NEXT: follow-up /feat (user 2026-11-20, pass B + GATE 2 answers), 5 files: lib/contract-interview.md STEP 4 (dry run + `- run-base:` from every contract-writing flow: guardrails, a11y, ship-feature, init-project, bugfix fast path, hotfix); skills/ship-feature STEP 6 (:262/:344) and skills/init-project STEP 10 (:280/:382) "Fix all CRITICAL" bound by lever 1 (reopen only on reproducible evidence); lib/capitalize-commit.md:75 `git diff --end-of-options` + `^[0-9a-f]{7,40}$` check on `run_base` (GATE 2 LOW); agents/verifier.md STEP 4 `[gated]` lines in scope only on an untracked contract (GATE 2 design note) +- [ ] MEASURE 2026-11-20 levers, after ~5 runs from 19dfe7e: dispatches/run, `TODO +n / -m` per run (measurement lines counted apart), `MINOR dropped:` lines per run plan, challenge skips taken → EVAL. Tripwires (reopen the levers): a BUGS-FOUND entry whose cause matches a `MINOR dropped:` line of a merged run; net open TODO growing run over run; a placed-decision skip on a run that settled an open choice ### Advisor call points (user 2026-11-17: "oui 1 et 2, et le 3 aussi"; amends BDR-150) - [x] Run A DONE 6ef3069, merged fc2d84d (docs 09277f5, audits c1a0c32, memory 78a6942) /feat feature/advisor-call-points: CLAUDE.global § Workflow + lib/effort-shift.md § Advisor + plan-challenger/verifier/security-auditor one-call rule (contract .claude/tasks/contracts/2026-11-17-advisor-call-points-1130.md) diff --git a/.claude/tasks/contracts/2026-11-20-done-triage-levers-1413.md b/.claude/tasks/contracts/2026-11-20-done-triage-levers-1413.md new file mode 100644 index 0000000..07545fe --- /dev/null +++ b/.claude/tasks/contracts/2026-11-20-done-triage-levers-1413.md @@ -0,0 +1,77 @@ +# CONTRACT — done-triage-levers +- date: 2026-11-20 | flow: feat | branch: feature/done-triage-levers +- status: active +- run-base: 68a4d8b + +## REQUEST (verbatim — IMMUTABLE) +Implémente les six leviers décrits dans .claude/tasks/plans/2026-11-20-done-and-triage-levers.md (TODO "NEXT, fresh session"). Suis le plan tel quel : 5 fichiers, challenge maintenu car c'est un nouveau mécanisme. + +## CLARIFICATIONS +none — request complete (the handoff plan names the six levers, their substance and their five carriers; placement and exact prose are settled in the run plan .claude/tasks/plans/2026-11-20-done-triage-levers-1413.md, challenged r1 by three lenses) +Q: CLAUDE.global.md lever-4 line wording / A: keep "A TODO loop notes its start SHA in TODO.md, runs that list + user adds; new items: report, run if one breaks its work." [gated 2026-11-20] +Q: strings `MINOR dropped: ` and `Challenge: skipped (placed decision: …)` / A: both OK [gated 2026-11-20] +Q: extend scope to (a) lib/contract-interview.md STEP 4 and (b) skills/ship-feature STEP 6 + skills/init-project STEP 10? / A: both (a) and (b). Three more files exceed /feat's five-file cap: this run stays on its five files, (a)+(b) run as a follow-up /feat right after this one (3 files) [gated 2026-11-20] +Q: GATE 2 REPORTED (1) LOW `$run_base` reaches `git diff` without `--end-of-options`/SHA check (lib/capitalize-commit.md:75), (2) verifier STEP 4 accepts `[gated]` lines on a tracked contract / A: fix both in the follow-up /feat (now 5 files: contract-interview, ship-feature, init-project, capitalize-commit, verifier) [gated 2026-11-20] + +## ACCEPTANCE CRITERIA +1. Lever 1, done = oracles green: lib/verify-secure-loop.md has `## DONE: oracles green, reopened only on evidence`: done at GATE 0 MET + GATE 1 CONFORME + GATE 2 PASS; a review reopens only with reproducible evidence (a command failing on HEAD, or real output shown wrong); a plausible scenario gets one attempt at a failing command, else it is a MINOR; a behavioural claim is done at locks green + one live probe + one dated measurement. + CHECK: f=lib/verify-secure-loop.md; grep -q '^## DONE: oracles green, reopened only on evidence$' $f && grep -q 'only with reproducible evidence: a command that fails on HEAD, or real$' $f && grep -q '^output shown wrong. A plausible scenario alone does not reopen the run:$' $f && grep -q '^the main loop tries once to turn it into a failing command, and if it$' $f && grep -q '^the rule") is done at its locks green, one live probe and one dated$' $f && echo LEVER1_OK + EXPECT: LEVER1_OK + EVIDENCE: MET exit=0 marker-found :: LEVER1_OK +2. Lever 2, MINOR triage: lib/verify-secure-loop.md has `## MINOR triage: fold before dispatch, or drop`: a MINOR on the run's plan or diff is folded before dispatch or dropped; no post-gate fix round; a drop is one `MINOR dropped:` line in the report and the run's plan file, nothing in TODO.md / BUGS-FOUND.md / a registry; backlog only on reproducible evidence or user ask; a security finding is never droppable and goes to the user; doc-syncer's `[MINOR]` patch class, guardrails, gates and user questions are untouched. + CHECK: f=lib/verify-secure-loop.md; grep -q '^## MINOR triage: fold before dispatch, or drop$' $f && grep -q '^fix round after the gates for a MINOR: it costs a full gate cycle. A drop$' $f && grep -q 'is one line, `MINOR dropped: `, in the run report and appended to$' $f && grep -q 'the run.s plan file; nothing goes to TODO.md, BUGS-FOUND.md or any$' $f && grep -q 'what the user asks for. Never a droppable MINOR: a security finding (a$' $f && grep -q '^Untouched by this triage: doc-syncer.s `\[MINOR\]` patch class, the safety$' $f && echo LEVER2_OK + EXPECT: LEVER2_OK + EVIDENCE: MET exit=0 marker-found :: LEVER2_OK +3. Lever 3, placed decision: lib/challenge-plan.md has `## SKIP: a placed decision` before `## DISPATCH`: skip = no challengers and no plan advisor call; three required conditions (text dictated by the decision; the decision is the user's own words or was challenged in the run that wrote it; the caller runs verify-secure-loop.md after its dispatch); the open-choice test, never code versus text, in doubt challenge; the skip is the include's own path (user decision 2026-11-20) and discharges the plan point of effort-shift § Advisor; the caller prints `Challenge: skipped (placed decision: …)`. + CHECK: f=lib/challenge-plan.md; s=$(grep -n '^## SKIP: a placed decision$' $f | cut -d: -f1); d=$(grep -n '^## DISPATCH' $f | cut -d: -f1); [ -n "$s" ] && [ "$s" -lt "$d" ] && grep -q '^no challengers and no plan advisor call. Three conditions, all required:$' $f && grep -q '^decision.s text is the user.s own words, or was challenged in the run that$' $f && grep -q '^user did not dictate), never code versus text; in doubt, challenge. The$' $f && grep -q '^skip is this include.s own path (user decision 2026-11-20): a skill.s$' $f && grep -q '^discharges the plan point (`lib/effort-shift.md` § Advisor). The caller prints$' $f && grep -q '^`Challenge: skipped (placed decision: )` in$' $f && echo LEVER3_OK + EXPECT: LEVER3_OK + EVIDENCE: MET exit=0 marker-found :: LEVER3_OK +4. Lever 2 at the challenge synthesis: lib/challenge-plan.md's SYNTHESIZE MINOR bullet says each MINOR is folded now or dropped, gives the drop format inline, routes a security finding to the user, and cites `lib/verify-secure-loop.md` § MINOR triage. + CHECK: f=lib/challenge-plan.md; grep -q '^ Each MINOR is folded into the plan now or dropped: a drop is one$' $f && grep -q '^ `MINOR dropped: ` line in the report and the plan file, nothing$' $f && grep -q '^ (`lib/verify-secure-loop.md` § MINOR triage).$' $f && echo SYNTH_OK + EXPECT: SYNTH_OK + EVIDENCE: MET exit=0 marker-found :: SYNTH_OK +5. Lever 4, frozen loop list: CLAUDE.global.md's Planning & TODO section says a TODO loop notes its start SHA in TODO.md, runs that list plus user adds, reports new items and runs one only if it breaks its work; the file stays at or under 320 lines and the new lines at or under 80 chars. + CHECK: f=CLAUDE.global.md; [ "$(wc -l < $f)" -le 320 ] && awk '/^## Planning & TODO/{p=1;next} /^## /{p=0} p' $f > /tmp/.cg5.$$ && grep -q '^ then carries one line per run. A TODO loop notes its start SHA in TODO.md,$' /tmp/.cg5.$$ && grep -q '^ runs that list + user adds; new items: report, run if one breaks its work.$' /tmp/.cg5.$$ && [ "$(git diff -U0 68a4d8b -- $f | grep '^+[^+]' | awk 'length($0)>81' | wc -l)" -eq 0 ] && rm -f /tmp/.cg5.$$ && echo LEVER4_OK + EXPECT: LEVER4_OK + EVIDENCE: MET exit=0 marker-found :: LEVER4_OK +6. Lever 5 main-loop side: lib/verify-secure-loop.md's header says its first section runs before the dev dispatch; `## BEFORE THE FIRST DISPATCH: contract dry run (main loop)` sits before `## GATE 0`, applies when the flow wrote a contract with `CHECK:` lines, records `- run-base: ` (a SHA), runs `gates.sh run` on a `mktemp -d` copy from the project root (no ERROR, NOT-MET only for undone work and for that reason, already-MET valid only for keep-green rows), states the scratch-copy simulation for prose oracles inline, and fixes bad oracles before any floor loop. lib/challenge-plan.md restates the two actions outside the SKIP condition, before the executor dispatch. + CHECK: f=lib/verify-secure-loop.md; b=$(grep -n '^## BEFORE THE FIRST DISPATCH: contract dry run (main loop)$' $f | cut -d: -f1); g=$(grep -n '^## GATE 0' $f | cut -d: -f1); [ -n "$b" ] && [ "$b" -lt "$g" ] && grep -q '^section runs before the dev step is dispatched). Turns a$' $f && grep -q '^When the flow wrote a contract with `CHECK:` lines, the main loop does two$' $f && grep -q '^ `- run-base: ` (a SHA, never a branch name;$' $f && grep -q '^2. Copies the contract to a `mktemp -d` path and, from the project root,$' $f && grep -q '^ to a scratch copy of the repo and run the CHECKs there (LRN-296).$' $f && grep -q '^A bad oracle is fixed in the contract here, before any floor loop.$' $f && grep -q '^Challenged or skipped: when the flow wrote a contract with `CHECK:` lines,$' lib/challenge-plan.md && grep -q '^before the executor dispatch the main loop records `- run-base:` in the$' lib/challenge-plan.md && grep -q '^(`lib/verify-secure-loop.md` § BEFORE THE FIRST DISPATCH).$' lib/challenge-plan.md && echo DRYRUN_OK + EXPECT: DRYRUN_OK + EVIDENCE: MET exit=0 marker-found :: DRYRUN_OK +7. Lever 5 verifier side: agents/verifier.md STEP 4 counts run artifacts in scope by default (name-status plus untracked): a plan file the diff ADDS under `.claude/tasks/plans/` or `docs/superpowers/plans/`; on an existing plan, appended `MINOR dropped:` lines only; the CONTRACT handed to the verifier, whole when untracked or added, else only its `EVIDENCE:`, `- run-base:` and `[gated]` lines; any other plan or contract change stays out of scope. lib/verify-secure-loop.md's out-of-scope bullet points to it. + CHECK: f=agents/verifier.md; awk '/^## STEP 4/{p=1;next} /^## /{p=0} p' $f > /tmp/.vf7.$$; grep -q '^`FILE SCOPE` says: a plan file the diff ADDS under `.claude/tasks/plans/`$' /tmp/.vf7.$$ && grep -q '^`MINOR dropped:` lines only; the CONTRACT you were handed, whole when$' /tmp/.vf7.$$ && grep -q '^untracked or added, else only its `EVIDENCE:` lines, `- run-base:` line and$' /tmp/.vf7.$$ && grep -q '^`\[gated\]` entries. Any other change to a plan or a contract stays out of$' /tmp/.vf7.$$ && grep -q '^ default (`agents/verifier.md`, STEP 4).$' lib/verify-secure-loop.md && rm -f /tmp/.vf7.$$ && echo SCOPE_OK + EXPECT: SCOPE_OK + EVIDENCE: MET exit=0 marker-found :: SCOPE_OK +8. Lever 6, `TODO +n / -m`: lib/capitalize-commit.md computes `` in DO step 1, before step 2's commit; `run_base` is a SHA from the contract's `- run-base:` line else `git rev-parse HEAD` at that point (with a `shortcut:` note); a failing diff gives `TODO n/a`; step 3 and both rc 0 templates carry `· `. The 6-line snippet, on a fixture where a run closes one open item, edits a closed one and adds two, yields `TODO +2 / -1` with the start SHA (uncommitted, then committed, run from a subdirectory), the same with `HEAD` on the uncommitted change, and `TODO n/a` on an unknown SHA. + CHECK: f=$PWD/lib/capitalize-commit.md; a=$(grep -n '^ Then, still before step 2, count the run.s TODO movement as ``:$' $f | cut -d: -f1); c=$(grep -n '^2. Commit surgically' $f | cut -d: -f1); [ -n "$a" ] && [ "$a" -lt "$c" ] && grep -q '^3. Report by (rc, mem_hash). Every report line ends with `· ` (step 1):$' $f && grep -q '`✅ mémoire committée · `' $f && grep -q '`CAPITALIZE: rien à committer · `' $f && grep -q 'never the gitflow base branch: the contract.s `- run-base:` line' $f && grep -q '`git rev-parse HEAD` now (shortcut: without a contract only the pending' $f && t=$(mktemp -d) && s=$t/s.sh && awk '/^ if d=\$\(git diff --no-color/{p=1} p{print} p&&/todo="TODO n\/a"; fi$/{exit}' $f | sed 's/^ //' > $s && [ "$(wc -l < $s)" -eq 6 ] && mkdir $t/r && cd $t/r && git init -q && mkdir -p .claude/tasks sub && printf -- '- [ ] a\n- [ ] b\n- [x] old\n' > .claude/tasks/TODO.md && git add . && git -c user.email=t@t -c user.name=t commit -qm base && b=$(git rev-parse HEAD) && printf -- '- [x] a DONE\n- [ ] b\n- [x] old edited\n- [ ] c\n- [ ] d\n' > .claude/tasks/TODO.md && r1=$(run_base=$b bash -c ". $s; echo \"\$todo\"") && r2=$(run_base=HEAD bash -c ". $s; echo \"\$todo\"") && r3=$(run_base=0123456789abcdef0123456789abcdef01234567 bash -c ". $s; echo \"\$todo\"") && git add . && git -c user.email=t@t -c user.name=t commit -qm run && r4=$(cd sub && run_base=$b bash -c ". $s; echo \"\$todo\"") && echo "R1=$r1 R2=$r2 R3=$r3 R4=$r4" + EXPECT: R1=TODO +2 / -1 R2=TODO +2 / -1 R3=TODO n/a R4=TODO +2 / -1 + EVIDENCE: MET exit=0 marker-found :: R1=TODO +2 / -1 R2=TODO +2 / -1 R3=TODO n/a R4=TODO +2 / -1 +9. No em-dash in any line this run adds to the five files, and all five files are changed. + CHECK: n=$(git diff -U0 68a4d8b -- lib/verify-secure-loop.md lib/challenge-plan.md CLAUDE.global.md lib/capitalize-commit.md agents/verifier.md | grep '^+[^+]' | grep -c '—'); [ "$n" -eq 0 ] && [ "$(git diff --name-only 68a4d8b -- lib/verify-secure-loop.md lib/challenge-plan.md CLAUDE.global.md lib/capitalize-commit.md agents/verifier.md | wc -l)" -eq 5 ] && echo NODASH_OK + EXPECT: NODASH_OK + EVIDENCE: MET exit=0 marker-found :: NODASH_OK +10. Locking suites stay green (doctrine census incl. the new § citations, escalate-route count, challenge wiring, advisor row lock). + CHECK: make test suite="lib/tests/doctrine-citers.test.sh lib/tests/effort-routing.test.sh lib/tests/plan-challenger.test.sh lib/tests/subagent-advisor.test.sh" 2>&1 | tail -1 + EXPECT: all suites green + EVIDENCE: MET exit=0 marker-found :: all suites green +11. Loop and gate suites stay green. + CHECK: make test suite="lib/tests/loops-light.test.sh lib/tests/loops-heavy.test.sh lib/tests/gates.test.sh lib/tests/contract-verifier.test.sh lib/tests/model-routing.test.sh lib/tests/curated-config-guard.test.sh" 2>&1 | tail -1 + EXPECT: all suites green + EVIDENCE: MET exit=0 marker-found :: all suites green +12. Not loosened: apart from the changes criteria 1-8 name (criterion 13's file is outside this count), no existing line of the five files is removed or weakened. Exactly 8 lines are removed against 68a4d8b, each an anchor the plan extends or re-wraps (verify-secure-loop.md header line 3 and "otherwise the dev removes the file.", CLAUDE.global.md "then carries one line per run.", verifier.md's two STEP 4 lines "Compare against the contract's `FILE SCOPE`. Report every out-of-scope" / "file. Disposition is NOT your call: …", capitalize-commit.md "3. Report by (rc, mem_hash):" and its two rc 0 templates); GATE 0 and the security gate read as before. + CHECK: n=$(git diff --numstat 68a4d8b -- lib/verify-secure-loop.md lib/challenge-plan.md CLAUDE.global.md lib/capitalize-commit.md agents/verifier.md | awk '{d+=$2} END{print d+0}'); [ "$n" -eq 8 ] && echo REMOVED_8 + EXPECT: REMOVED_8 + EVIDENCE: MET exit=0 marker-found :: REMOVED_8 +13. [gated 2026-11-20] Citer: lib/effort-shift.md § Advisor point 1 says the plan advisor call is skipped with the challenge for a placed decision, citing `lib/challenge-plan.md` § SKIP; the census still resolves every citation. + CHECK: f=lib/effort-shift.md; grep -q '^ challengers see it (`lib/challenge-plan.md`), at most once per skill run;$' $f && grep -q '^ skipped with the challenge for a placed decision (`lib/challenge-plan.md` § SKIP).$' $f && make test suite=lib/tests/doctrine-citers.test.sh 2>&1 | tail -1 | grep -q 'all suites green' && echo CITER_OK + EXPECT: CITER_OK + EVIDENCE: MET exit=0 marker-found :: CITER_OK + +## FILE SCOPE +- lib/verify-secure-loop.md +- lib/challenge-plan.md +- CLAUDE.global.md +- lib/capitalize-commit.md +- agents/verifier.md +- lib/effort-shift.md [gated 2026-11-20] (citer of lever 3) +- this contract and .claude/tasks/plans/2026-11-20-done-triage-levers-1413.md (run artifacts) diff --git a/.claude/tasks/plans/2026-11-20-done-triage-levers-1413.md b/.claude/tasks/plans/2026-11-20-done-triage-levers-1413.md new file mode 100644 index 0000000..6302b41 --- /dev/null +++ b/.claude/tasks/plans/2026-11-20-done-triage-levers-1413.md @@ -0,0 +1,347 @@ +# PLAN r3 — done-triage-levers (/feat, 2026-11-20 14:13) + +Source: handoff plan `.claude/tasks/plans/2026-11-20-done-and-triage-levers.md` (six levers, +five carriers, user-approved). Contract: `.claude/tasks/contracts/2026-11-20-done-triage-levers-1413.md`. +Base: develop 68a4d8b. Branch: feature/done-triage-levers. + +## Mechanism (exact text: § EXACT DIFF below) + +- [ ] lib/verify-secure-loop.md + - header line 3: the include runs after the dev step, except its first section (before dispatch). + - new `## BEFORE THE FIRST DISPATCH: contract dry run (main loop)` before `## GATE 0` (lever 5, + main-loop side), only when the flow wrote a contract with `CHECK:` lines: (1) record + `- run-base: ` in the contract header (a SHA; feeds lever 6); (2) from + the project root, `gates.sh run` on a `mktemp -d` copy of the contract (real ledger stays + pending): no ERROR, NOT-MET only for undone work and for that reason, a row already MET + valid only when the work must keep it green; prose oracles: simulate the planned text on a + scratch copy and run the CHECKs there (LRN-296, stated inline). Bad oracle fixed before any + floor loop. + - out-of-scope bullet: "Run artifacts are in scope by default (`agents/verifier.md`, STEP 4)." + - after `## Order invariant`: `## DONE: oracles green, reopened only on evidence` (lever 1, + one attempt to turn a scenario into a failing command) and + `## MINOR triage: fold before dispatch, or drop` (lever 2: findings on the run's plan or diff; + drop line in the report and the run's plan file; security findings never droppable, to the + user; doc-syncer `[MINOR]` patch class untouched). + - unchanged: the three `route(phase="escalate")` (effort-routing lock = 3). +- [ ] lib/challenge-plan.md + - new `## SKIP: a placed decision` before `## DISPATCH` (lever 3): three required conditions + (dictated text; the decision is the user's own words or was challenged in the run that wrote + it; the caller runs verify-secure-loop.md after its dispatch); open-choice test, in doubt + challenge; the skip is the include's own path (user decision 2026-11-20) and discharges the + plan point of effort-shift § Advisor; the `Challenge: skipped (…)` line replaces the summary. + - second paragraph, outside the skip condition: the two dry-run actions restated inline, before + the executor dispatch, citing § BEFORE THE FIRST DISPATCH (pre-dispatch reach of lever 5). + - SYNTHESIZE MINOR bullet: fold or drop, drop format inline, security → user, cites § MINOR triage. +- [ ] CLAUDE.global.md — Planning & TODO last bullet (lever 4): "A TODO loop notes its start SHA + in TODO.md, runs that list + user adds; new items: report, run if one breaks its work." + 319 → 320 lines (guard fires only above 320). +- [ ] lib/capitalize-commit.md — DO step 1, before step 2's commit (lever 6): compute ``; + `run_base` = the contract's `- run-base:` SHA, else `git rev-parse HEAD` then (`shortcut:`: + only pending TODO edits); 6-line snippet, `--no-color --no-ext-diff`, root pathspec + `:/.claude/tasks/TODO.md`; failing diff → `TODO n/a`; step 3 and both rc 0 templates carry + `· `. +- [ ] agents/verifier.md — STEP 4 (lever 5), with `--name-status` plus untracked: in scope by + default = a plan file the diff ADDS under `.claude/tasks/plans/` or `docs/superpowers/plans/`; + appended `MINOR dropped:` lines on an existing plan; the CONTRACT handed to the verifier, whole + when untracked or added, else only its `EVIDENCE:`, `- run-base:`, `[gated]` lines; any other + plan or contract change stays out of scope. + +## Executor steps +1. Extract the EXACT DIFF block of this file and apply it atomically: + `t=$(mktemp -d); awk '/^```diff$/{p=1;next} p&&/^```$/{exit} p' + /home/bchanot/Documents/claude/.claude/tasks/plans/2026-11-20-done-triage-levers-1413.md + > "$t/levers.patch"`, then, from the repo root, `git apply --check "$t/levers.patch"` and + `git apply "$t/levers.patch"` (same shell call, so `$t` survives). git apply is + all-or-nothing; recovery if anything goes wrong: `git checkout -- lib/verify-secure-loop.md + lib/challenge-plan.md CLAUDE.global.md lib/capitalize-commit.md agents/verifier.md`. +2. `bash ~/.claude/lib/gates.sh run .claude/tasks/contracts/2026-11-20-done-triage-levers-1413.md` + → `GATES — VERDICT: MET`. +3. No other edit. No commit. + +## Edge cases +- CLAUDE.global.md at exactly 320 lines: the session-start guard fires only above 320. +- `run_base` unknown SHA or failing diff → `TODO n/a`; start SHA counts uncommitted and + committed edits, from a subdirectory too; `HEAD` taken before the commit counts pending edits + (all fixture-tested, criterion 8). +- `- run-base:` header line: `gates.sh status` parses it unchanged (PENDING(12) checked). +- `§` citations (§ BEFORE THE FIRST DISPATCH, § MINOR triage, § Advisor): resolved by the + doctrine-citers census, flip-tested (renaming a heading turns T6 red). +- Contract CHECKs pinned to 68a4d8b, not `develop`. + +## Proof done before dispatch +Fresh scratch clone + r3 text: 12/12 criteria MET (10 suites green, fixture 4 cases, 8 removed +lines). Positive control on the +untouched tree: 10 NOT-MET, the 2 keep-green suite rows MET. + +## Challenge r1 (3 lenses: correctness CONCERNS(3), robustness CONCERNS(4), simplicity CONCERNS(1)) +- `base` never recorded (3 lenses) → `- run-base:` SHA written at the dry run, `HEAD` fallback, + name distinct from the gitflow base, `--no-color --no-ext-diff`. +- verifier scope too wide, `.claude/tasks` mislabelled transient (2 lenses) → only ADDED plan + files and EVIDENCE/run-base/[gated] contract changes; edits to existing plans stay out. +- dry run unreached before dispatch → header line 3 fixed, actions restated inline in + challenge-plan.md outside the skip; unreached flows named below. +- security findings droppable → never a droppable MINOR, to the user. +- post-gate review precedence → DONE binds ship-feature STEP 6 / init-project STEP 10. +- MINORs taken: `gates.sh run` on a mktemp copy instead of hand runs; LRN-296 reduced to a + citation; SKIP conditions (user's own words or challenged; caller has gates), discharges the + advisor plan point; drop line also in the plan file (tripwire traceable); doc-syncer `[MINOR]` + untouched; triage limited to plan or diff findings; frozen list anchored on the start SHA; + applier dropped for `git apply` of this diff (atomic, named recovery); drop format inline at + SYNTHESIZE; dry run conditional on a contract with CHECKs. +- MINOR dropped: tripwire "open TODO still growing" confounded by measurement lines; the dated + measurement lines are counted apart at the EVAL, no text change. + +## Challenge r2 (confirmation, correctness: CONCERNS(2)), closed in r3 +- `HEAD` fallback read after step 2's commit → silent `+0 / -0` → count moved to DO step 1, + before the commit; fixture adds the committed and subdirectory cases. +- DONE claimed to bind ship-feature STEP 6 / init-project STEP 10, act sites unchanged → sentence + dropped; both sites go to the pass B scope question. +- MINORs taken: verifier clause keyed on the handed CONTRACT (untracked/added = whole) and on + appended `MINOR dropped:` lines of an existing plan, `--name-status` + untracked; dry run cwd + = project root; LRN-296 procedure inline, "never" dropped; skip grounded in the user decision + of 2026-11-20; lever-4 start SHA written into TODO.md by the loop; executor step names the + plan's absolute path and keeps `$t`; root pathspec `:/`; ship-feature and init-project named + unreached below. +- No further re-challenge: lib/challenge-plan.md allows one confirmation pass. + +## This run under lever 1 (a behavioural claim) +Locks: the three `§` citations (census T6) and this contract's CHECKs. Live probe: the next +/feat or /bugfix run (dry run + run-base, SKIP decision, MINOR drops, `TODO +n / -m` line). +Dated measurement: the TODO line written at capitalize, "2026-11-20 levers: after ~5 runs, log +dispatches/run, TODO +n/-m per run (measurement lines apart), `MINOR dropped:` lines per plan, +any post-merge bug traced to a dropped MINOR (EVAL)"; tripwires: a BUGS-FOUND entry whose cause +matches a `MINOR dropped:` line of a merged run, or net open TODO growing run over run. + +## User answers (pass B, 2026-11-20): CLAUDE.global line kept, both strings OK, scope (a)+(b) yes → follow-up /feat (3 files) after this run + +## Questions asked (pass B) +- The CLAUDE.global.md line wording (loaded in every session). +- The strings `MINOR dropped: ` and `Challenge: skipped (placed decision: …)`. +- Scope beyond five files: (a) lib/contract-interview.md STEP 4 would reach the dry run + + run-base from every contract-writing flow; (b) ship-feature STEP 6 (:262/:344) and + init-project STEP 10 (:280/:382) still say "Fix all CRITICAL", unbound by lever 1. + +## Not done (named) +- No skill file changes (five-file limit). Unreached by the pre-dispatch pointer: guardrails and + a11y (contract + executor, no challenge-plan.md), bugfix's trivial fast path and hotfix's + cosmetic skip (no challenge read), bugfix STEP 3b (reads challenge-plan.md before its contract + exists), ship-feature and init-project (dispatch in a later turn, after a human gate). + Contract-less flows count `TODO` from `HEAD` (pending edits only). +- Lever 1 does not bind ship-feature STEP 6 / init-project STEP 10 (their text unchanged). +- Proof of the change after ~5 runs (EVAL) stays a TODO line, per the handoff plan. + +## Disposition (STEP 0.6) +- honors BDR-062/BDR-098: CLAUDE.global.md ≤ 320 (one line added). +- honors BDR-065 (amendment: `.claude/tasks/{contracts,plans}` durable): the verifier default + covers only plan files a run ADDS and EVIDENCE/run-base/[gated] contract changes; an edit to + an existing plan stays a gap. +- honors BDR-075: the three-lens challenge stays for every run with an open choice; the skip is + limited to placement of a user's own or already-challenged decision (user approval of lever 3). +- honors BDR-049/BDR-083: fresh blind verifier and GATE 0 untouched. +- applies LRN-296 (scratch simulation), LRN-297 (pointer restates the actions at the act site), + LRN-298 (placement by line order in CHECKs 3 and 6), LRN-281/LRN-173 (EVIDENCE lines, literal + markers, CHECKs run on the precedent and on the untouched tree). + +## EXACT DIFF (against develop 68a4d8b) + +```diff +diff --git a/CLAUDE.global.md b/CLAUDE.global.md +index 778434e..e87a323 100644 +--- a/CLAUDE.global.md ++++ b/CLAUDE.global.md +@@ -113,7 +113,8 @@ code" wins. Repo-specific instructions override both. + - Once it qualifies: plan before code → one subtask = one coherent change + → check off as you go → high-level note at each milestone. A plan a skill + persists (`.claude/tasks/plans/`, contract) satisfies the rule; TODO.md +- then carries one line per run. ++ then carries one line per run. A TODO loop notes its start SHA in TODO.md, ++ runs that list + user adds; new items: report, run if one breaks its work. + + ## After code changes + 1. Run tests, lint, build, type-check if available. Report what was +diff --git a/agents/verifier.md b/agents/verifier.md +index cd3f0ec..15b7b5b 100644 +--- a/agents/verifier.md ++++ b/agents/verifier.md +@@ -101,8 +101,15 @@ Parse the single `FLOOR GUARD:` line: + ## STEP 4 — SCOPE CHECK + + List the files actually touched (`git diff --name-only` over `DIFF`). +-Compare against the contract's `FILE SCOPE`. Report every out-of-scope +-file. Disposition is NOT your call: the orchestrator treats each one as a ++Compare against the contract's `FILE SCOPE` (`git diff --name-status` ++plus untracked files). Run artifacts are in scope by default, whatever ++`FILE SCOPE` says: a plan file the diff ADDS under `.claude/tasks/plans/` ++or `docs/superpowers/plans/`; on an existing plan, appended ++`MINOR dropped:` lines only; the CONTRACT you were handed, whole when ++untracked or added, else only its `EVIDENCE:` lines, `- run-base:` line and ++`[gated]` entries. Any other change to a plan or a contract stays out of ++scope. Report every other out-of-scope file. ++Disposition is NOT your call: the orchestrator treats each one as a + gap — the dev removes it or justifies it, and an accepted justification + only enters the contract through a human micro-gate. + +diff --git a/lib/capitalize-commit.md b/lib/capitalize-commit.md +index 59bc2ac..de907ec 100644 +--- a/lib/capitalize-commit.md ++++ b/lib/capitalize-commit.md +@@ -63,14 +63,30 @@ never a shell argument. + - `chore(memory): BLK-010 resolved — bugfix profile path` + - `chore(memory): journal — hotfix copy typo` (journal-only, nothing else) + ++ Then, still before step 2, count the run's TODO movement as ``: ++ `TODO +n / -m`, the open TODO items the run added and removed (closed or ++ dropped); a reworded open item counts on both sides. `run_base` is a SHA, ++ never the gitflow base branch: the contract's `- run-base:` line ++ (`lib/verify-secure-loop.md` § BEFORE THE FIRST DISPATCH), else ++ `git rev-parse HEAD` now (shortcut: without a contract only the pending ++ TODO edits count; edits committed earlier in the run are missed). A ++ failing `git diff` → `TODO n/a`, never a silent `+0 / -0`. ++ ++ if d=$(git diff --no-color --no-ext-diff "$run_base" \ ++ -- ':/.claude/tasks/TODO.md' 2>/dev/null); then ++ n=$(printf '%s\n' "$d" | grep -c '^+ *- \[ \]') ++ m=$(printf '%s\n' "$d" | grep -c '^- *- \[ \]') ++ todo="TODO +$n / -$m" ++ else todo="TODO n/a"; fi ++ + 2. Commit surgically via the helper, capturing the memory-commit hash it prints: + + mem_hash=$(bash "$HOME/.claude/lib/memory-commit.sh" commit "") + rc=$? + +-3. Report by (rc, mem_hash): +- - rc 0, mem_hash non-empty → `✅ mémoire committée ` +- - rc 0, mem_hash empty → `CAPITALIZE: rien à committer` (helper no-op) ++3. Report by (rc, mem_hash). Every report line ends with `· ` (step 1): ++ - rc 0, mem_hash non-empty → `✅ mémoire committée · ` ++ - rc 0, mem_hash empty → `CAPITALIZE: rien à committer · ` (helper no-op) + - rc 3 → unsafe git state (detached / merge in progress); + memory stays in the working tree for a manual + commit — surface the helper's stderr. +diff --git a/lib/challenge-plan.md b/lib/challenge-plan.md +index fd69e67..2941ff1 100644 +--- a/lib/challenge-plan.md ++++ b/lib/challenge-plan.md +@@ -30,6 +30,27 @@ SOLID, synthesis is a no-op. It only costs more when a lens lands a real finding + The main loop's advisor call before the dispatch (below) is the costliest + single item: once per skill run. + ++## SKIP: a placed decision ++ ++A run that only places a decision the user already made skips this phase: ++no challengers and no plan advisor call. Three conditions, all required: ++the exact text or change is dictated by that decision (no new design); the ++decision's text is the user's own words, or was challenged in the run that ++wrote it; and the caller runs `lib/verify-secure-loop.md` after its ++dispatch, so the gates still run. The test is whether the run settles an ++open choice of its own (a mechanism, a condition, a threshold, wording the ++user did not dictate), never code versus text; in doubt, challenge. The ++skip is this include's own path (user decision 2026-11-20): a skill's ++challenge step that reads this section runs as written, and the skip ++discharges the plan point (`lib/effort-shift.md` § Advisor). The caller prints ++`Challenge: skipped (placed decision: )` in ++place of its CHALLENGE SUMMARY. ++ ++Challenged or skipped: when the flow wrote a contract with `CHECK:` lines, ++before the executor dispatch the main loop records `- run-base:` in the ++contract and runs `gates.sh run` on a `mktemp -d` copy of it ++(`lib/verify-secure-loop.md` § BEFORE THE FIRST DISPATCH). ++ + ## DISPATCH — three fresh challengers, in parallel, blind + + **Advisor first (main loop).** Before the first dispatch, with no main-loop +@@ -88,6 +109,10 @@ Parse each `CHALLENGE — LENS: … — VERDICT:` line and merge the FINDINGS: + - **Severity-driven, not consensus.** Any `[BLOCKER]` from ANY single lens is + must-address — the lenses are orthogonal, so a lone security/rollback finding + is real, never outvoted by lens-count. Cross-lens agreement only RANKS the MINORs. ++ Each MINOR is folded into the plan now or dropped: a drop is one ++ `MINOR dropped: ` line in the report and the plan file, nothing ++ in TODO.md or a registry; a security finding goes to the user ++ (`lib/verify-secure-loop.md` § MINOR triage). + - **RE-THINK the aspect the challenge pointed at.** For each BLOCKER (and each + MAJOR you accept): revise the plan on THAT aspect — a NAMED, diffable change to + the plan, never a self-authored "addressed" line. A BLOCKER you consciously keep +diff --git a/lib/verify-secure-loop.md b/lib/verify-secure-loop.md +index b2aaa32..1141a1e 100644 +--- a/lib/verify-secure-loop.md ++++ b/lib/verify-secure-loop.md +@@ -1,6 +1,7 @@ + # Verify + secure loop — shared orchestrator include (feat, bugfix, guardrails, a11y) + +-Runs in the ORCHESTRATOR MAIN LOOP after the dev step completes. Turns a ++Runs in the ORCHESTRATOR MAIN LOOP after the dev step completes (its first ++section runs before the dev step is dispatched). Turns a + finished diff into a verified, security-cleared change through two fresh + gates and bounded loops. Loop decisions live here, in the main loop + (LRN-083: subagents = execution + report). The dev step is a dispatched +@@ -17,6 +18,26 @@ Nominal path is cheap — a free floor run, then + one verifier dispatch + one security dispatch, done. The loop only costs + more when it actually loops. + ++## BEFORE THE FIRST DISPATCH: contract dry run (main loop) ++ ++When the flow wrote a contract with `CHECK:` lines, the main loop does two ++things before the dev step is dispatched: ++ ++1. Records the run's start commit in the contract header, once: ++ `- run-base: ` (a SHA, never a branch name; ++ `lib/capitalize-commit.md` counts the run's TODO movement from it). ++2. Copies the contract to a `mktemp -d` path and, from the project root, ++ runs `bash ~/.claude/lib/gates.sh run `, so the real ledger stays ++ `pending`. Expected: no `ERROR(n)` (malformed ledger: fix it here), ++ NOT-MET rows only where the work is not done yet, each failing for that ++ reason and not for a syntax error, a missing tool or a wrong path. A row ++ already MET is valid only when the work must keep it green (a suite, a ++ line cap); any other is vacuous. A marker that can never match fails ++ like undone work: for oracles that grep prose, apply the planned text ++ to a scratch copy of the repo and run the CHECKs there (LRN-296). ++ ++A bad oracle is fixed in the contract here, before any floor loop. ++ + ## GATE 0 — DETERMINISTIC FLOOR (no dispatch, no model) + + Before spending a verifier dispatch, execute the oracles the contract itself +@@ -92,7 +113,8 @@ Parse its single `VERIFY — VERDICT:` line: + cannot fix unverifiability); do not spend a loop on it. + - Out-of-scope files: a dev justification is accepted ONLY through the human + micro-gate that appends `[gated ]` to the contract's FILE SCOPE; +- otherwise the dev removes the file. ++ otherwise the dev removes the file. Run artifacts are in scope by ++ default (`agents/verifier.md`, STEP 4). + - Structural failure (`ERROR(…)`, missing/duplicated VERDICT line, + unparsable, crash, `CONFORME` without `PROOF` or without `FLOOR`) → retry + ONCE with a fresh verifier; a 2nd structural failure → human escalation. +@@ -147,3 +169,31 @@ verifier's verdict meaningless. REQUEST conformity is + always re-checked BEFORE security on any re-loop — a security fix that breaks + the feature must not slip through because only the security gate re-ran. + Never the reverse order. ++ ++## DONE: oracles green, reopened only on evidence ++ ++A run is done when its oracles are green: GATE 0 MET (the suite criterion ++included), GATE 1 CONFORME and GATE 2 PASS on the same diff. After done, a ++review (the end-of-run advisor call, a code review, a re-read) reopens the ++run only with reproducible evidence: a command that fails on HEAD, or real ++output shown wrong. A plausible scenario alone does not reopen the run: ++the main loop tries once to turn it into a failing command, and if it ++cannot, the finding is a MINOR (below). A behavioural claim ("agents obey ++the rule") is done at its locks green, one live probe and one dated ++measurement: a TODO line that carries the date and the tripwires that ++would reopen it. ++ ++## MINOR triage: fold before dispatch, or drop ++ ++A MINOR finding on the run's plan or diff (from a challenger, a review, an ++advisor) is either folded into the plan before the dispatch or dropped. No ++fix round after the gates for a MINOR: it costs a full gate cycle. A drop ++is one line, `MINOR dropped: `, in the run report and appended to ++the run's plan file; nothing goes to TODO.md, BUGS-FOUND.md or any ++registry. The backlog takes only findings with reproducible evidence, or ++what the user asks for. Never a droppable MINOR: a security finding (a ++GATE 2 `REPORTED` item, a secret, an injection, authorization or exposure ++issue from any review) goes to the user, who decides fix or record. ++Untouched by this triage: doc-syncer's `[MINOR]` patch class, the safety ++guardrails, every gate, and the user's questions on visible, public-name ++and scope choices. +``` diff --git a/CHANGELOG.md b/CHANGELOG.md index 9c057d0..124b7d4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -23,6 +23,7 @@ The BDR-125 context queue is delivered: phases 0, 0b, 4a, 1, 5, 2 and 4b-4d ship - **model-router: Fable leaves auto-routing**: the `best` and `big` tiers default to opus then sonnet (were fable>opus>sonnet and opus>fable>sonnet), so Opus is the strongest model the router routes to and Fable is the advisor (`advisorModel` in settings.json). Fable stays in the model table and first in the fallback rank, so a hand pick of fable ranks above opus. The first-use Change dialog offers opus, sonnet and haiku; the bare `/model` dialog still offers fable, labelled `fable (custom)`. The ask before Fable only fires when a machine override puts fable at the head of `best`: otherwise `/route ask-tier on` answers `(inert: best is not headed by fable)` and `/route show` prints `ask-tier: inert`. An agent on a best or big row keeps its opus frontmatter when Opus is down. The `tiers.best does not lead the fallback chain` log is gone; `routing.json` is unchanged. Tests: `mods/model-router/hooks/register.test.ts`; `lib/tests/effort-routing.test.sh` floors every row on its tier's head. The `/client-handover` skill-runner children and the `lib/model-gate.md` dispatch doctrine pin `model: "opus"` instead of `"fable"` (BDR-150: Fable is the advisor, never a dispatch target), and the model gate lets a sub-agent pass when the route answer says its model is `fixed at spawn`. Tests: `lib/tests/model-routing.test.sh` refuses any fable dispatch pin under agents/, skills/ and lib/; `lib/tests/effort-routing.test.sh` checks the 7 opus/effort="high" client-handover dispatches. - **Advisor doctrine (`CLAUDE.global.md` § Workflow, `lib/effort-shift.md` § Advisor, `lib/challenge-plan.md`, `lib/verify-secure-loop.md`, `agents/plan-challenger.md`, `agents/verifier.md`, `agents/security-auditor.md`, `agents/analyzer.md`, `skills/{feat,bugfix,hotfix,ship-feature,init-project,onboard,code-clean,harden,a11y,guardrails,audit-delta,tour,release-candidate}/SKILL.md`, `skills/pack-seo/skills/{seo,geo}/SKILL.md`, `skills/pack-web-validate/skills/web-validate/SKILL.md`)**: when a stronger model is needed (an approach to settle before building, a stuck problem, a long task before calling it done, a change to recommend to the doctrine, the architecture or a public interface), the main loop calls the advisor tool (Fable, settings `advisorModel`, set by `/advisor`), at least on the written plan before the plan challengers are dispatched (`lib/challenge-plan.md`, every skill that challenges a plan, once per skill run, not before a re-challenge: an answer that lands a real flaw revises the plan file as plain plan text with no advisor attribution, the advice never enters a challenger brief, and the CHALLENGE SUMMARY of every caller gains an `Advisor:` row (the plan change it drove, `called, no change` or `not called (absent | error | already called this run)`), each caller sending its route before the challenge with the first tool call of `lib/challenge-plan.md`; the ORCHESTRATOR PROTOCOL in `agents/plan-challenger.md` mirrors this advisor-first step and the row), once per verify-secure run at the first gate loop to fail twice (floor, conformity, security, or a second structural failure, counting main-loop calls since GATE 0 first ran; the advice stays in the main loop and never enters an executor brief; every cap or escalation STOP carries it and says whether it predates the last iteration), and before proposing a merge (`gitflow finish`) or calling a long task done: one end-of-run call per skill run, never skipped for an earlier plan or stuck call, except that audit-delta and tour skip it when the run applied no fix and feat and bugfix skip it when GATE 0 said MET, the verifier CONFORME and security PASS (not DEGRADED), each on its first attempt, their summary's `ADVISOR` field then reading `skipped (gates clean on first pass)`. It sits at the commit step of feat and bugfix and at the end step of ship-feature, init-project, a11y and guardrails: the main loop first prints the run's diff stat, the answer goes into the reply or finish proposal as an `Advisor:` line, or into the feat/bugfix summary's `ADVISOR` field, a fix it drives goes back through the gates, and a later merge proposal reuses the last run's answer, or its skip, and names any code commit made after it (doc and memory commits excepted). It also sits at the end of audit-delta and tour when the run applied a fix (tour: main loop only, never a runner), and at release-candidate STEP 4 before the go / hold ask. In those three the answer is reported only: a fix it calls for waits for a new run, and at the release gate it makes hold the recommended answer. The same six gate skills carry a `Stuck:` line that points at the verify-secure rule. Inside a skill run these points cover the triggers: no second call for the same recommendation. `plan-challenger`, `verifier`, `security-auditor` and `analyzer` may call it only when dispatched as a sub-agent, at most once per dispatch, late, before their verdict or report; the analyzer's output rests on the code it read, never on the advice alone, and advice proposing a design or a fix counts only where the brief asks for one. For the three gates advice only adds: the verifier may go back to a contract criterion and tags a resulting NOT-MET `(advisor-prompted)`, never clearing a gap on advice; the challenger never drops or lowers a finding on advice alone; the security-auditor tags an added finding `advisor:` at that class's severity (REPORTED LOW when it matches no class), and tags a raised one `+advisor` only when the class's severity is higher than the finding's own; a raise that does not apply, or matches no class, changes nothing (no tag, no PROOF count). Its PROOF ends with `; advisor added/raised`. Executors and every other sub-agent do not call it, even when the tool is listed. Advisor absent or erroring → proceed as written; advice waives no gate, cap or guard and, at a loop cap, feeds the STOP diagnosis. Fable on main comes only from a hand pick, a typed `/route model=fable`, a phase naming `model: fable` or a machine override that puts fable in a tier (BDR-150). Prose that still named Fable as the `audit` row head or a skill-runner pin (`agents/plan-challenger.md`, `lib/challenge-plan.md`, `lib/effort-shift.md`, `skills/tour/SKILL.md`) now says opus. - **gates.sh timeout**: the default per-CHECK timeout (`GATES_TIMEOUT`) is 600 s, up from 120 s. A full `make test` (about 135 s) went NOT-MET on the timeout alone. A run lasts the sum of its CHECKs: a caller with a shorter limit (a foreground tool call stops at 600 s) runs it in the background, and a killed run writes nothing back, so the floor stays PENDING. +- **Done and triage levers (`lib/verify-secure-loop.md`, `lib/challenge-plan.md`, `lib/capitalize-commit.md`, `agents/verifier.md`, `CLAUDE.global.md`)**: a run is done when its oracles are green (GATE 0 MET, verifier CONFORME and security PASS on the same diff); a later review reopens it only with reproducible evidence, a command that fails on HEAD or real output shown wrong. A MINOR finding is folded into the plan before the dispatch or dropped as one `MINOR dropped: ` line in the run report and plan file, never in TODO.md or a registry; a security finding is never dropped and goes to the user. A run that only places a decision the user already made skips the plan challenge and its advisor call and prints `Challenge: skipped (placed decision: …)`. Before the first dispatch the main loop records `- run-base: ` in the contract and dry-runs its CHECKs with `gates.sh run` on a `mktemp -d` copy. A TODO loop notes its start SHA in TODO.md and runs that list plus user additions. The memory-commit report line ends with `· TODO +n / -m` (`TODO n/a` when the diff fails). The verifier counts run artifacts in scope: an added plan file, appended `MINOR dropped:` lines, the contract's `EVIDENCE:`, `- run-base:` and `[gated]` lines. ### Removed - `hooks/design-toolchain-reminder.sh`, its `UserPromptSubmit` entry in `settings.json` (`ctx7-reminder` stays the only one) and its suite `lib/tests/design-toolchain-reminder.test.sh`. Measured 2026-10-31: 59 fires, 0 Reads of `rules/web-building.md`. Design routing stays with the `rules/web-building.md` path rule and the `CLAUDE.global.md` pointer. The fire log `~/.claude/logs/design-toolchain-fires.log` is left in place. diff --git a/CLAUDE.global.md b/CLAUDE.global.md index 778434e..e87a323 100644 --- a/CLAUDE.global.md +++ b/CLAUDE.global.md @@ -113,7 +113,8 @@ code" wins. Repo-specific instructions override both. - Once it qualifies: plan before code → one subtask = one coherent change → check off as you go → high-level note at each milestone. A plan a skill persists (`.claude/tasks/plans/`, contract) satisfies the rule; TODO.md - then carries one line per run. + then carries one line per run. A TODO loop notes its start SHA in TODO.md, + runs that list + user adds; new items: report, run if one breaks its work. ## After code changes 1. Run tests, lint, build, type-check if available. Report what was diff --git a/README.md b/README.md index 5384554..b9543f2 100644 --- a/README.md +++ b/README.md @@ -76,7 +76,10 @@ decisions) to the `best` tier, opus at the phase's effort. Fable is never auto-routed: it is the advisor (`advisorModel` in settings.json) and a hand pick. The main loop calls the advisor at least on the written plan before the plan challengers see it (`lib/challenge-plan.md`, once per skill run; the -CHALLENGE SUMMARY's `Advisor:` row records what it changed), once per +CHALLENGE SUMMARY's `Advisor:` row records what it changed; skipped with +the challenge when the run only places a decision the user already made, +`Challenge: skipped (placed decision: …)` standing in for the summary), +once per verify-secure run at the first gate loop to fail twice (the advice stays in the main loop, never in an executor brief; a cap or escalation STOP carries it), before proposing a merge or calling a long task done (two skips: diff --git a/USAGE.md b/USAGE.md index 377ff89..fe333ac 100644 --- a/USAGE.md +++ b/USAGE.md @@ -200,7 +200,7 @@ l'outil `mcp__model-router__route` (`lib/effort-shift.md`). Les skills externes vendorés (pile design, superpowers, agent-skills, skills scroll MengTo, 21st) ont aussi leur ligne. -Taper un skill qui a une ligne route la boucle principale dessus. Une ligne du tier best (plan, reflect, orchestrate, escalate ; `audit` est une ligne d'agent, jamais tapée) tient d'un tour à l'autre pendant tout le run, jusqu'à `/route clear`, `/route off`, un `/model` tapé ou choisi dans le sélecteur, ou un skill d'un autre tier tapé. Un `/model ` tapé, ou un choix dans le sélecteur `/model`, avec un modèle de la table demande sa portée (Échap ne change rien). Le changement du sélecteur est d'abord retenu (le moteur affiche qu'un hook l'a bloqué), puis la question vient ; un choix fait pendant qu'un autre dialogue est ouvert est refusé (`answer the open dialog first`) : This project écrit l'id complet dans `model` du `.claude/settings.local.json` du projet (créé s'il manque, à garder dans le `.gitignore`) et pose une route de modèle tenue ; This conversation pose la route seule, sans rien écrire ; Everywhere lance le `/model` natif (`settings.json` utilisateur, tous les projets). Default dans le sélecteur, sans argument, avec un nom inconnu, en headless (`-p`) ou mod coupé, le `/model` natif passe sans question. Un modèle choisi dans ce dialogue change toujours : ni plafond de relecture à froid, ni `mainUpgrade` ni `mainModelSwitch`. S'il est en panne, la boucle principale reste où elle est jusqu'à son retour. Un changement natif (ligne Model de `/config` comprise) ou `/clear` l'abandonne ; un `/route model=` tapé garde les plafonds. La ligne Model de `/config` écrit toujours le `settings.json` utilisateur, et un dialogue jamais répondu n'a pas de délai. Pour relancer un tour bloqué : `ultrathink` dans le prompt (plancher d'effort du tour) ou `/route effort=max` (tient jusqu'à `/route clear`). Le `/effort` intégré n'a pas d'effet dans un run : les lignes et les routes passent devant. Les règles de mots-clés du prompt (`plan`, `design`, `architecture`… prennent l'effort de plan ; `pourquoi`, `review`, `audit`… celui de reflect), `ultrathink` et un lancement d'agent par la boucle principale (route `orchestrate` dérivée, tenue jusqu'à la fin de ses agents en arrière-plan) ne fixent que le niveau d'effort du tour, jamais le modèle : ils ne font jamais monter la boucle principale au-dessus du modèle de la session, et un run best tenu garde son modèle. Fable n'arrive sur la boucle principale que par un choix à la main (`/model`, sélecteur), un `/route model=fable` tapé, une phase qui nomme `model: fable` ou une config machine qui le place dans un tier : aucun tier ni aucune phase livrés ne le contiennent. Fable sert de conseiller (outil advisor, `advisorModel` dans settings.json, réglé par `/advisor`) : la boucle principale l'appelle au moins sur le plan écrit, avant que les challengers du plan le voient (`lib/challenge-plan.md`, une fois par run de skill ; la ligne `Advisor:` du CHALLENGE SUMMARY dit ce qu'il a changé), une fois par run verify-secure à la première boucle de porte qui échoue deux fois (le conseil reste dans la boucle principale, jamais dans le brief d'un exécutant ; un STOP au plafond ou en escalade le reprend), avant de proposer un merge ou de déclarer finie une longue tâche (deux exceptions : `/feat` et `/bugfix` le sautent quand GATE 0 a dit MET, le verifier CONFORME et la sécurité PASS, pas DEGRADED, chacun au premier essai, et leur champ `ADVISOR` affiche alors `skipped (gates clean on first pass)` ; `/audit-delta` et `/tour` le sautent quand le run n'a appliqué aucun fix), et avant de recommander un changement de la doctrine, de l'architecture ou d'une interface publique ; plan-challenger, verifier, security-auditor, `analyzer` et une revue de code sur opus (`/ship-feature` STEP 6, `/init-project` STEP 10, revue finale d'un subagent-driven-development lancé seul) peuvent l'appeler une fois, seulement quand ils sont lancés comme sous-agents, avant leur verdict ou leur rapport : un conseil peut ajouter un constat ou relever sa sévérité, jamais le retirer, l'abaisser ni l'effacer ; les autres sous-agents ne l'appellent jamais, même quand l'outil est listé, et le hook SubagentStart `hooks/subagent-advisor.sh` leur rappelle la règle au lancement. Conseiller absent ou en erreur : on continue ; un conseil ne lève aucune porte, aucun plafond ni aucune garde. Un prompt tapé sans règle, skill ni route en cours passe par un classifieur (un appel au petit modèle, 3 secondes au plus) : le tour prend la route de la phase devinée : son niveau d'effort, et son modèle, jamais au-dessus de celui de la session. Une devinette `coding` ou `bookkeeping` fait descendre la boucle principale vers un modèle moins cher quand `mainModelSwitch` est actif (par défaut) et que la relecture à froid tient sous `downgradeMaxTokens` (120000 tokens par défaut). Cette relecture compte aussi le prompt qui vient d'être envoyé (un token pour 3 caractères), et un document joint bloque la descente pour cette étape. Le cache compte comme chaud pendant le TTL du moteur (`cache_ttl`, 5 ou 60 minutes), 60 minutes par défaut. `/route classify off` ou `"classify": false` dans la config machine le coupe, et un `/effort` tapé entre deux tours annule la devinette pour ce tour seulement. Avant d'envoyer la boucle principale sur un modèle, celui vers lequel elle se déplace comme celui qu'elle garde (le modèle de la session compris), le mod l'essaie une fois (un appel minimal, 8 secondes au plus) : sans réponse, ce modèle est marqué en panne (raison `probe`) et la décision est reprise une fois ; `"probe": false` dans la config machine coupe cet essai, et `/route show` affiche `probe:`. Quand un modèle inférieur remplace la tête de son tier en panne (Sonnet pour Opus sur une phase best ; Opus pour Fable si une config machine met fable en tête de best), le niveau propre de la phase monte d'un cran (reflect xhigh, plan max, orchestrate high) ; un niveau demandé explicitement ou un plancher ne bouge jamais. Les sous-agents reçoivent le modèle de leur ligne au lancement (dans leur tier, jamais en dessous de leur frontmatter) et son niveau à chaque étape ; un `model` ou `effort` explicite sur l'appel gagne. Explore tourne en sonnet/medium, Plan en opus/xhigh. Un agent intégré `general-purpose` lancé par la boucle principale sans `model`, pendant que celle-ci tourne sous le modèle de la session (descente, ou repli quand un modèle est en panne), part sur le modèle de la session au lieu d'hériter du modèle inférieur ; les autres types d'agents ne sont jamais épinglés ainsi. `/route show` affiche la route en cours, slot de run compris (`main: run `), et le switch avec son plafond et ce TTL (`switch: on (downgrade, cap 120000 tokens cold, ttl 60 min)`). Première utilisation : la première fois qu'un skill avec ligne est tapé, qu'un agent avec ligne est lancé ou qu'une phase est déclarée sur la boucle principale via l'outil `route`, le mod demande une fois si la route convient. La question donne le contexte : la description du skill (première phrase du frontmatter de son `SKILL.md`) ou celle de l'agent, la phase avec sa ligne `about` (champ de la phase dans `routing.json`), puis le modèle et le niveau réels de l'étape suivante ; une phase déclarée dit aussi qui l'utilise. Pour une ligne : Later, Keep ou Change ; pour une phase déclarée : Later ou Keep. Change demande le modèle (opus, sonnet, haiku, chacun avec son tier ; fable n'est pas proposé), puis le niveau parmi ceux des phases de ce modèle (opus : medium, high, xhigh ou max ; sonnet : low, medium, high ou xhigh ; haiku n'en a qu'un, la question est sautée), puis Everywhere ou This project only (exception rangée sous le remote origin du dépôt réduit à `host/path`, jamais d'identifiants). Une ligne reste un nom de phase : le couple modèle et niveau désigne une phase existante, et la même phase qu'avant vaut Keep. Un couple qu'aucune phase n'offre s'ajoute à la main comme nouvelle phase dans `routing.json`. Après un changement sur un skill, un toast donne le modèle et le niveau réels, et rappelle `/route switch on` quand le switch est coupé, ou nomme le plafond quand la relecture à froid bloque la descente. La réponse est écrite dans `routing.json` ; Later, un texte libre (Other) ou un dialogue fermé redemande à une session suivante. Un seul dialogue à la fois, jamais en headless (`-p`) ni dans un sous-agent, et le modèle n'écrit jamais ce fichier. Chaque réponse laisse le repo de config modifié : commite-le depuis ce repo. `/route pending` liste ce qui reste à confirmer, `/route ask off|on` coupe ou rallume le dialogue, `/route forget ` efface une décision (une ligne changée revient à la phase livrée ; `all` et `projects` demandent d'abord). Si une config machine met fable en tête du tier best (aucun tier livré ne le fait), avant qu'une route envoie la boucle principale, ou un agent à ligne, sur Fable depuis un autre modèle, le mod pose une question une seule fois par portée (origine, phase et sa ligne `about`, modèle et niveau) : `Fable`, `Opus instead (big tier)` (Opus à la place : le tier big, niveau de la phase inchangé, le label reste vrai : l'option disparaît si Opus est en panne) ou `Stop asking this session` (ne plus demander cette session : rien n'est écrit, `/clear` la réarme). Un skill chargé par le modèle compte comme une ligne de skill ; un agent n'a qu'une réponse par type et par session ; jamais en headless (`-p`) ni dans un sous-agent ; un dialogue fermé lance Fable. Pas de question quand la décision ne tomberait pas sur Fable (`mainUpgrade` coupé, plafond de relecture, fenêtre, Fable en panne) : si la panne cesse plus tard, la boucle monte sans question, comme le disjoncteur le fait déjà. La clé `askTier` de `routing.json` (`best`, ou `false` pour couper) se règle par `/route ask-tier on|off`, la config machine gagne, et `/route show` affiche `ask-tier:`. Tant que best n'est pas mené par fable, la question est inerte : `/route ask-tier on` répond `ask-tier on (inert: best is not headed by fable)` et `/route show` affiche `ask-tier: inert`. +Taper un skill qui a une ligne route la boucle principale dessus. Une ligne du tier best (plan, reflect, orchestrate, escalate ; `audit` est une ligne d'agent, jamais tapée) tient d'un tour à l'autre pendant tout le run, jusqu'à `/route clear`, `/route off`, un `/model` tapé ou choisi dans le sélecteur, ou un skill d'un autre tier tapé. Un `/model ` tapé, ou un choix dans le sélecteur `/model`, avec un modèle de la table demande sa portée (Échap ne change rien). Le changement du sélecteur est d'abord retenu (le moteur affiche qu'un hook l'a bloqué), puis la question vient ; un choix fait pendant qu'un autre dialogue est ouvert est refusé (`answer the open dialog first`) : This project écrit l'id complet dans `model` du `.claude/settings.local.json` du projet (créé s'il manque, à garder dans le `.gitignore`) et pose une route de modèle tenue ; This conversation pose la route seule, sans rien écrire ; Everywhere lance le `/model` natif (`settings.json` utilisateur, tous les projets). Default dans le sélecteur, sans argument, avec un nom inconnu, en headless (`-p`) ou mod coupé, le `/model` natif passe sans question. Un modèle choisi dans ce dialogue change toujours : ni plafond de relecture à froid, ni `mainUpgrade` ni `mainModelSwitch`. S'il est en panne, la boucle principale reste où elle est jusqu'à son retour. Un changement natif (ligne Model de `/config` comprise) ou `/clear` l'abandonne ; un `/route model=` tapé garde les plafonds. La ligne Model de `/config` écrit toujours le `settings.json` utilisateur, et un dialogue jamais répondu n'a pas de délai. Pour relancer un tour bloqué : `ultrathink` dans le prompt (plancher d'effort du tour) ou `/route effort=max` (tient jusqu'à `/route clear`). Le `/effort` intégré n'a pas d'effet dans un run : les lignes et les routes passent devant. Les règles de mots-clés du prompt (`plan`, `design`, `architecture`… prennent l'effort de plan ; `pourquoi`, `review`, `audit`… celui de reflect), `ultrathink` et un lancement d'agent par la boucle principale (route `orchestrate` dérivée, tenue jusqu'à la fin de ses agents en arrière-plan) ne fixent que le niveau d'effort du tour, jamais le modèle : ils ne font jamais monter la boucle principale au-dessus du modèle de la session, et un run best tenu garde son modèle. Fable n'arrive sur la boucle principale que par un choix à la main (`/model`, sélecteur), un `/route model=fable` tapé, une phase qui nomme `model: fable` ou une config machine qui le place dans un tier : aucun tier ni aucune phase livrés ne le contiennent. Fable sert de conseiller (outil advisor, `advisorModel` dans settings.json, réglé par `/advisor`) : la boucle principale l'appelle au moins sur le plan écrit, avant que les challengers du plan le voient (`lib/challenge-plan.md`, une fois par run de skill ; la ligne `Advisor:` du CHALLENGE SUMMARY dit ce qu'il a changé ; sauté avec le challenge quand le run ne fait que placer une décision déjà prise par l'utilisateur, la ligne `Challenge: skipped (placed decision: …)` remplaçant alors le CHALLENGE SUMMARY), une fois par run verify-secure à la première boucle de porte qui échoue deux fois (le conseil reste dans la boucle principale, jamais dans le brief d'un exécutant ; un STOP au plafond ou en escalade le reprend), avant de proposer un merge ou de déclarer finie une longue tâche (deux exceptions : `/feat` et `/bugfix` le sautent quand GATE 0 a dit MET, le verifier CONFORME et la sécurité PASS, pas DEGRADED, chacun au premier essai, et leur champ `ADVISOR` affiche alors `skipped (gates clean on first pass)` ; `/audit-delta` et `/tour` le sautent quand le run n'a appliqué aucun fix), et avant de recommander un changement de la doctrine, de l'architecture ou d'une interface publique ; plan-challenger, verifier, security-auditor, `analyzer` et une revue de code sur opus (`/ship-feature` STEP 6, `/init-project` STEP 10, revue finale d'un subagent-driven-development lancé seul) peuvent l'appeler une fois, seulement quand ils sont lancés comme sous-agents, avant leur verdict ou leur rapport : un conseil peut ajouter un constat ou relever sa sévérité, jamais le retirer, l'abaisser ni l'effacer ; les autres sous-agents ne l'appellent jamais, même quand l'outil est listé, et le hook SubagentStart `hooks/subagent-advisor.sh` leur rappelle la règle au lancement. Conseiller absent ou en erreur : on continue ; un conseil ne lève aucune porte, aucun plafond ni aucune garde. Un prompt tapé sans règle, skill ni route en cours passe par un classifieur (un appel au petit modèle, 3 secondes au plus) : le tour prend la route de la phase devinée : son niveau d'effort, et son modèle, jamais au-dessus de celui de la session. Une devinette `coding` ou `bookkeeping` fait descendre la boucle principale vers un modèle moins cher quand `mainModelSwitch` est actif (par défaut) et que la relecture à froid tient sous `downgradeMaxTokens` (120000 tokens par défaut). Cette relecture compte aussi le prompt qui vient d'être envoyé (un token pour 3 caractères), et un document joint bloque la descente pour cette étape. Le cache compte comme chaud pendant le TTL du moteur (`cache_ttl`, 5 ou 60 minutes), 60 minutes par défaut. `/route classify off` ou `"classify": false` dans la config machine le coupe, et un `/effort` tapé entre deux tours annule la devinette pour ce tour seulement. Avant d'envoyer la boucle principale sur un modèle, celui vers lequel elle se déplace comme celui qu'elle garde (le modèle de la session compris), le mod l'essaie une fois (un appel minimal, 8 secondes au plus) : sans réponse, ce modèle est marqué en panne (raison `probe`) et la décision est reprise une fois ; `"probe": false` dans la config machine coupe cet essai, et `/route show` affiche `probe:`. Quand un modèle inférieur remplace la tête de son tier en panne (Sonnet pour Opus sur une phase best ; Opus pour Fable si une config machine met fable en tête de best), le niveau propre de la phase monte d'un cran (reflect xhigh, plan max, orchestrate high) ; un niveau demandé explicitement ou un plancher ne bouge jamais. Les sous-agents reçoivent le modèle de leur ligne au lancement (dans leur tier, jamais en dessous de leur frontmatter) et son niveau à chaque étape ; un `model` ou `effort` explicite sur l'appel gagne. Explore tourne en sonnet/medium, Plan en opus/xhigh. Un agent intégré `general-purpose` lancé par la boucle principale sans `model`, pendant que celle-ci tourne sous le modèle de la session (descente, ou repli quand un modèle est en panne), part sur le modèle de la session au lieu d'hériter du modèle inférieur ; les autres types d'agents ne sont jamais épinglés ainsi. `/route show` affiche la route en cours, slot de run compris (`main: run `), et le switch avec son plafond et ce TTL (`switch: on (downgrade, cap 120000 tokens cold, ttl 60 min)`). Première utilisation : la première fois qu'un skill avec ligne est tapé, qu'un agent avec ligne est lancé ou qu'une phase est déclarée sur la boucle principale via l'outil `route`, le mod demande une fois si la route convient. La question donne le contexte : la description du skill (première phrase du frontmatter de son `SKILL.md`) ou celle de l'agent, la phase avec sa ligne `about` (champ de la phase dans `routing.json`), puis le modèle et le niveau réels de l'étape suivante ; une phase déclarée dit aussi qui l'utilise. Pour une ligne : Later, Keep ou Change ; pour une phase déclarée : Later ou Keep. Change demande le modèle (opus, sonnet, haiku, chacun avec son tier ; fable n'est pas proposé), puis le niveau parmi ceux des phases de ce modèle (opus : medium, high, xhigh ou max ; sonnet : low, medium, high ou xhigh ; haiku n'en a qu'un, la question est sautée), puis Everywhere ou This project only (exception rangée sous le remote origin du dépôt réduit à `host/path`, jamais d'identifiants). Une ligne reste un nom de phase : le couple modèle et niveau désigne une phase existante, et la même phase qu'avant vaut Keep. Un couple qu'aucune phase n'offre s'ajoute à la main comme nouvelle phase dans `routing.json`. Après un changement sur un skill, un toast donne le modèle et le niveau réels, et rappelle `/route switch on` quand le switch est coupé, ou nomme le plafond quand la relecture à froid bloque la descente. La réponse est écrite dans `routing.json` ; Later, un texte libre (Other) ou un dialogue fermé redemande à une session suivante. Un seul dialogue à la fois, jamais en headless (`-p`) ni dans un sous-agent, et le modèle n'écrit jamais ce fichier. Chaque réponse laisse le repo de config modifié : commite-le depuis ce repo. `/route pending` liste ce qui reste à confirmer, `/route ask off|on` coupe ou rallume le dialogue, `/route forget ` efface une décision (une ligne changée revient à la phase livrée ; `all` et `projects` demandent d'abord). Si une config machine met fable en tête du tier best (aucun tier livré ne le fait), avant qu'une route envoie la boucle principale, ou un agent à ligne, sur Fable depuis un autre modèle, le mod pose une question une seule fois par portée (origine, phase et sa ligne `about`, modèle et niveau) : `Fable`, `Opus instead (big tier)` (Opus à la place : le tier big, niveau de la phase inchangé, le label reste vrai : l'option disparaît si Opus est en panne) ou `Stop asking this session` (ne plus demander cette session : rien n'est écrit, `/clear` la réarme). Un skill chargé par le modèle compte comme une ligne de skill ; un agent n'a qu'une réponse par type et par session ; jamais en headless (`-p`) ni dans un sous-agent ; un dialogue fermé lance Fable. Pas de question quand la décision ne tomberait pas sur Fable (`mainUpgrade` coupé, plafond de relecture, fenêtre, Fable en panne) : si la panne cesse plus tard, la boucle monte sans question, comme le disjoncteur le fait déjà. La clé `askTier` de `routing.json` (`best`, ou `false` pour couper) se règle par `/route ask-tier on|off`, la config machine gagne, et `/route show` affiche `ask-tier:`. Tant que best n'est pas mené par fable, la question est inerte : `/route ask-tier on` répond `ask-tier on (inert: best is not headed by fable)` et `/route show` affiche `ask-tier: inert`. Garde d'écriture : un Edit, Write ou NotebookEdit d'un fichier de code par la boucle principale est redirigé avec « model-router: code is written inside a skill run… » tant qu'aucun skill n'a tourné sur la boucle principale dans la session (tapé ou chargé par le modèle ; un skill refusé ou inconnu ne compte pas), qu'aucune phase n'a été déclarée ce tour, et qu'aucun `/route` tapé ne tient. Chemins libres : `.md`, `.txt`, le `.claude/` du projet sauf `worktrees/`, et `docs/`. Les sous-agents écrivent librement. Si la vérification du garde échoue elle-même (exception ou délai dépassé), l'écriture est retenue au lieu de passer, avec « model-router: the write guard failed (), so this write is held… », journalisé une fois par session ; les sous-agents, un skill en cours, une phase déclarée ou un `/route` tapé, et les fichiers `.md` / `.txt` passent toujours, et une erreur levée par l'outil lui-même est transmise telle quelle. `/route clear`, `/route off` et `/clear` réarment le garde ; `/route off` le coupe aussi, et `"enabled": false` dans `~/.claude/model-router.json` coupe le routeur et le garde. Un choix à la main avec `/model` ne l'ouvre pas, et un rechargement de `register.ts` le remet à zéro. diff --git a/agents/verifier.md b/agents/verifier.md index cd3f0ec..15b7b5b 100644 --- a/agents/verifier.md +++ b/agents/verifier.md @@ -101,8 +101,15 @@ Parse the single `FLOOR GUARD:` line: ## STEP 4 — SCOPE CHECK List the files actually touched (`git diff --name-only` over `DIFF`). -Compare against the contract's `FILE SCOPE`. Report every out-of-scope -file. Disposition is NOT your call: the orchestrator treats each one as a +Compare against the contract's `FILE SCOPE` (`git diff --name-status` +plus untracked files). Run artifacts are in scope by default, whatever +`FILE SCOPE` says: a plan file the diff ADDS under `.claude/tasks/plans/` +or `docs/superpowers/plans/`; on an existing plan, appended +`MINOR dropped:` lines only; the CONTRACT you were handed, whole when +untracked or added, else only its `EVIDENCE:` lines, `- run-base:` line and +`[gated]` entries. Any other change to a plan or a contract stays out of +scope. Report every other out-of-scope file. +Disposition is NOT your call: the orchestrator treats each one as a gap — the dev removes it or justifies it, and an accepted justification only enters the contract through a human micro-gate. diff --git a/lib/capitalize-commit.md b/lib/capitalize-commit.md index 59bc2ac..de907ec 100644 --- a/lib/capitalize-commit.md +++ b/lib/capitalize-commit.md @@ -63,14 +63,30 @@ never a shell argument. - `chore(memory): BLK-010 resolved — bugfix profile path` - `chore(memory): journal — hotfix copy typo` (journal-only, nothing else) + Then, still before step 2, count the run's TODO movement as ``: + `TODO +n / -m`, the open TODO items the run added and removed (closed or + dropped); a reworded open item counts on both sides. `run_base` is a SHA, + never the gitflow base branch: the contract's `- run-base:` line + (`lib/verify-secure-loop.md` § BEFORE THE FIRST DISPATCH), else + `git rev-parse HEAD` now (shortcut: without a contract only the pending + TODO edits count; edits committed earlier in the run are missed). A + failing `git diff` → `TODO n/a`, never a silent `+0 / -0`. + + if d=$(git diff --no-color --no-ext-diff "$run_base" \ + -- ':/.claude/tasks/TODO.md' 2>/dev/null); then + n=$(printf '%s\n' "$d" | grep -c '^+ *- \[ \]') + m=$(printf '%s\n' "$d" | grep -c '^- *- \[ \]') + todo="TODO +$n / -$m" + else todo="TODO n/a"; fi + 2. Commit surgically via the helper, capturing the memory-commit hash it prints: mem_hash=$(bash "$HOME/.claude/lib/memory-commit.sh" commit "") rc=$? -3. Report by (rc, mem_hash): - - rc 0, mem_hash non-empty → `✅ mémoire committée ` - - rc 0, mem_hash empty → `CAPITALIZE: rien à committer` (helper no-op) +3. Report by (rc, mem_hash). Every report line ends with `· ` (step 1): + - rc 0, mem_hash non-empty → `✅ mémoire committée · ` + - rc 0, mem_hash empty → `CAPITALIZE: rien à committer · ` (helper no-op) - rc 3 → unsafe git state (detached / merge in progress); memory stays in the working tree for a manual commit — surface the helper's stderr. diff --git a/lib/challenge-plan.md b/lib/challenge-plan.md index fd69e67..2941ff1 100644 --- a/lib/challenge-plan.md +++ b/lib/challenge-plan.md @@ -30,6 +30,27 @@ SOLID, synthesis is a no-op. It only costs more when a lens lands a real finding The main loop's advisor call before the dispatch (below) is the costliest single item: once per skill run. +## SKIP: a placed decision + +A run that only places a decision the user already made skips this phase: +no challengers and no plan advisor call. Three conditions, all required: +the exact text or change is dictated by that decision (no new design); the +decision's text is the user's own words, or was challenged in the run that +wrote it; and the caller runs `lib/verify-secure-loop.md` after its +dispatch, so the gates still run. The test is whether the run settles an +open choice of its own (a mechanism, a condition, a threshold, wording the +user did not dictate), never code versus text; in doubt, challenge. The +skip is this include's own path (user decision 2026-11-20): a skill's +challenge step that reads this section runs as written, and the skip +discharges the plan point (`lib/effort-shift.md` § Advisor). The caller prints +`Challenge: skipped (placed decision: )` in +place of its CHALLENGE SUMMARY. + +Challenged or skipped: when the flow wrote a contract with `CHECK:` lines, +before the executor dispatch the main loop records `- run-base:` in the +contract and runs `gates.sh run` on a `mktemp -d` copy of it +(`lib/verify-secure-loop.md` § BEFORE THE FIRST DISPATCH). + ## DISPATCH — three fresh challengers, in parallel, blind **Advisor first (main loop).** Before the first dispatch, with no main-loop @@ -88,6 +109,10 @@ Parse each `CHALLENGE — LENS: … — VERDICT:` line and merge the FINDINGS: - **Severity-driven, not consensus.** Any `[BLOCKER]` from ANY single lens is must-address — the lenses are orthogonal, so a lone security/rollback finding is real, never outvoted by lens-count. Cross-lens agreement only RANKS the MINORs. + Each MINOR is folded into the plan now or dropped: a drop is one + `MINOR dropped: ` line in the report and the plan file, nothing + in TODO.md or a registry; a security finding goes to the user + (`lib/verify-secure-loop.md` § MINOR triage). - **RE-THINK the aspect the challenge pointed at.** For each BLOCKER (and each MAJOR you accept): revise the plan on THAT aspect — a NAMED, diffable change to the plan, never a self-authored "addressed" line. A BLOCKER you consciously keep diff --git a/lib/effort-shift.md b/lib/effort-shift.md index e11aa09..3fdff95 100644 --- a/lib/effort-shift.md +++ b/lib/effort-shift.md @@ -106,7 +106,8 @@ target (BDR-150). It is a server tool: the router cannot see or refuse it. Main loop, at least at these points (for work outside them, see the triggers in CLAUDE.global.md § Workflow): 1. Before settling an approach: on the written plan, before the - challengers see it (`lib/challenge-plan.md`), at most once per skill run. + challengers see it (`lib/challenge-plan.md`), at most once per skill run; + skipped with the challenge for a placed decision (`lib/challenge-plan.md` § SKIP). 2. When stuck: once per verify-secure run, at the first gate loop to fail twice (floor, conformity, security, or a second structural failure), before re-dispatching or escalating. At a cap the STOP diagnosis diff --git a/lib/verify-secure-loop.md b/lib/verify-secure-loop.md index b2aaa32..1141a1e 100644 --- a/lib/verify-secure-loop.md +++ b/lib/verify-secure-loop.md @@ -1,6 +1,7 @@ # Verify + secure loop — shared orchestrator include (feat, bugfix, guardrails, a11y) -Runs in the ORCHESTRATOR MAIN LOOP after the dev step completes. Turns a +Runs in the ORCHESTRATOR MAIN LOOP after the dev step completes (its first +section runs before the dev step is dispatched). Turns a finished diff into a verified, security-cleared change through two fresh gates and bounded loops. Loop decisions live here, in the main loop (LRN-083: subagents = execution + report). The dev step is a dispatched @@ -17,6 +18,26 @@ Nominal path is cheap — a free floor run, then one verifier dispatch + one security dispatch, done. The loop only costs more when it actually loops. +## BEFORE THE FIRST DISPATCH: contract dry run (main loop) + +When the flow wrote a contract with `CHECK:` lines, the main loop does two +things before the dev step is dispatched: + +1. Records the run's start commit in the contract header, once: + `- run-base: ` (a SHA, never a branch name; + `lib/capitalize-commit.md` counts the run's TODO movement from it). +2. Copies the contract to a `mktemp -d` path and, from the project root, + runs `bash ~/.claude/lib/gates.sh run `, so the real ledger stays + `pending`. Expected: no `ERROR(n)` (malformed ledger: fix it here), + NOT-MET rows only where the work is not done yet, each failing for that + reason and not for a syntax error, a missing tool or a wrong path. A row + already MET is valid only when the work must keep it green (a suite, a + line cap); any other is vacuous. A marker that can never match fails + like undone work: for oracles that grep prose, apply the planned text + to a scratch copy of the repo and run the CHECKs there (LRN-296). + +A bad oracle is fixed in the contract here, before any floor loop. + ## GATE 0 — DETERMINISTIC FLOOR (no dispatch, no model) Before spending a verifier dispatch, execute the oracles the contract itself @@ -92,7 +113,8 @@ Parse its single `VERIFY — VERDICT:` line: cannot fix unverifiability); do not spend a loop on it. - Out-of-scope files: a dev justification is accepted ONLY through the human micro-gate that appends `[gated ]` to the contract's FILE SCOPE; - otherwise the dev removes the file. + otherwise the dev removes the file. Run artifacts are in scope by + default (`agents/verifier.md`, STEP 4). - Structural failure (`ERROR(…)`, missing/duplicated VERDICT line, unparsable, crash, `CONFORME` without `PROOF` or without `FLOOR`) → retry ONCE with a fresh verifier; a 2nd structural failure → human escalation. @@ -147,3 +169,31 @@ verifier's verdict meaningless. REQUEST conformity is always re-checked BEFORE security on any re-loop — a security fix that breaks the feature must not slip through because only the security gate re-ran. Never the reverse order. + +## DONE: oracles green, reopened only on evidence + +A run is done when its oracles are green: GATE 0 MET (the suite criterion +included), GATE 1 CONFORME and GATE 2 PASS on the same diff. After done, a +review (the end-of-run advisor call, a code review, a re-read) reopens the +run only with reproducible evidence: a command that fails on HEAD, or real +output shown wrong. A plausible scenario alone does not reopen the run: +the main loop tries once to turn it into a failing command, and if it +cannot, the finding is a MINOR (below). A behavioural claim ("agents obey +the rule") is done at its locks green, one live probe and one dated +measurement: a TODO line that carries the date and the tripwires that +would reopen it. + +## MINOR triage: fold before dispatch, or drop + +A MINOR finding on the run's plan or diff (from a challenger, a review, an +advisor) is either folded into the plan before the dispatch or dropped. No +fix round after the gates for a MINOR: it costs a full gate cycle. A drop +is one line, `MINOR dropped: `, in the run report and appended to +the run's plan file; nothing goes to TODO.md, BUGS-FOUND.md or any +registry. The backlog takes only findings with reproducible evidence, or +what the user asks for. Never a droppable MINOR: a security finding (a +GATE 2 `REPORTED` item, a secret, an injection, authorization or exposure +issue from any review) goes to the user, who decides fix or record. +Untouched by this triage: doc-syncer's `[MINOR]` patch class, the safety +guardrails, every gate, and the user's questions on visible, public-name +and scope choices.