docs: deferred stop, doctor opus[1m] (README, USAGE, CHANGELOG)

This commit is contained in:
bchanot committed 2026-11-21 21:09:17 +01:00
1 parent 828f3284dc
commit a732c6c0e3
3 files changed
+7 -6

No files matched your search

+2 -1
View File
@@ -23,7 +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:<STEP 3 class>` at that class's severity (REPORTED LOW when it matches no class), and tags a raised one `<rule>+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 <n> 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`, `lib/contract-interview.md`, `skills/{ship-feature,init-project}/SKILL.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. The post-gate code review (`/ship-feature` STEP 6, `/init-project` STEP 10) fixes a CRITICAL or Important finding only when it carries that evidence (it used to fix every CRITICAL): without it, one attempt at a failing command, else the finding is triaged as a MINOR; a security finding goes to the user. The review loop back to implementation applies to those items, capped at 2 cycles. A MINOR finding is folded into the plan before the dispatch or dropped as one `MINOR dropped: <finding>` 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: …)`. A BLOCKER or MAJOR that the one confirmation challenger still lands on a point the revision touched is not revised a second time: it is tagged `[deferred <date>]` with the finding quoted, for the human to accept at the plan gate. Before the first dispatch, right after the flow's branch step, the main loop records `- run-base: <sha>` in the contract (a value written before the branch step is replaced by `git rev-parse HEAD` after it) and dry-runs its CHECKs with `gates.sh run` on a `mktemp -d` copy. Every flow that writes a contract with `CHECK:` lines does this, whether or not it challenges its plan, `/ship-feature` and `/init-project` included (`lib/contract-interview.md` STEP 4); a flow's own positive control on the unfixed tree stands for the `gates.sh` half, and `- run-base:` is still recorded. A TODO loop notes its start SHA in TODO.md and runs that list plus user additions. The memory commit's message and its report line end with `· TODO +n / -m`, so `git log --oneline --grep '· TODO'` lists each run's movement; `TODO n/a` when the diff fails or the run base is not a 7-40 hex SHA (the diff now passes `--end-of-options` before it). The verifier counts run artifacts in scope: an added plan file, appended `MINOR dropped:` lines, the contract's `EVIDENCE:`, `- run-base:` and `[gated]` lines.
- **Done and triage levers (`lib/verify-secure-loop.md`, `lib/challenge-plan.md`, `agents/plan-challenger.md`, `lib/capitalize-commit.md`, `lib/contract-interview.md`, `skills/{ship-feature,init-project}/SKILL.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. The post-gate code review (`/ship-feature` STEP 6, `/init-project` STEP 10) fixes a CRITICAL or Important finding only when it carries that evidence (it used to fix every CRITICAL): without it, one attempt at a failing command, else the finding is triaged as a MINOR; a security finding goes to the user. The review loop back to implementation applies to those items, capped at 2 cycles. A MINOR finding is folded into the plan before the dispatch or dropped as one `MINOR dropped: <finding>` 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: …)`. A BLOCKER or MAJOR that the one confirmation challenger still lands on a point the revision touched is not revised a second time: it is tagged `[deferred <date>]` with the finding quoted. Every `[deferred]` point, from either pass, stops the run once at the end of the challenge step, before the caller's next step and whatever gate the caller holds later, with one batched question to the human (each finding quoted, each option's effect stated): keep (the plan runs as written), cut (the item leaves the plan, and the report or envelope the caller applies from) or reopen (the main loop revises it). After a cut or a reopen the run goes on with no further challenge unless the human asks for one; that one confirmation challenger's deferred points are asked once, with no challenger after them. A keep or cut answer is appended to the contract's CLARIFICATIONS as `[gated <date>]`, amending in the same entry every criterion that requires a cut item, and joins the CONSTRAINTS of every later challenge, so it is never re-asked. /hotfix asks the question itself, with no escalation; with no human reachable (a sub-agent run, headless) the run stops and hands the points back. This deferred stop is the challenge's one hard stop; otherwise it stays advisory. Before the first dispatch, right after the flow's branch step, the main loop records `- run-base: <sha>` in the contract (a value written before the branch step is replaced by `git rev-parse HEAD` after it) and dry-runs its CHECKs with `gates.sh run` on a `mktemp -d` copy. Every flow that writes a contract with `CHECK:` lines does this, whether or not it challenges its plan, `/ship-feature` and `/init-project` included (`lib/contract-interview.md` STEP 4); a flow's own positive control on the unfixed tree stands for the `gates.sh` half, and `- run-base:` is still recorded. A TODO loop notes its start SHA in TODO.md and runs that list plus user additions. The memory commit's message and its report line end with `· TODO +n / -m`, so `git log --oneline --grep '· TODO'` lists each run's movement; `TODO n/a` when the diff fails or the run base is not a 7-40 hex SHA (the diff now passes `--end-of-options` before it). 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.
@@ -40,6 +40,7 @@ The BDR-125 context queue is delivered: phases 0, 0b, 4a, 1, 5, 2 and 4b-4d ship
- Hooks: `hooks/code-limits.sh` keeps its per-session state in a private dir (`mkdir -m 700` without `-p`, else an existing dir is accepted only if it is ours, a directory and mode 700); `hooks/session-start.sh` bounds `memory.sh` and the feedback reminder with `timeout`, else `gtimeout`, else a perl alarm (stock macOS), never unbounded; each runner kills the command's whole process group at the deadline, and the perl one also TERMs a leftover after a normal exit; the gitflow pre-commit hook (generator `lib/gitflow.sh` and both copies) blocks when `git diff --cached` or its filter fails instead of letting the commit through. Tests: `lib/tests/code-limits.test.sh` T16, `lib/tests/session-digest.test.sh` SD19 and SD19b, new `lib/tests/precommit-failclosed.test.sh` PC1-PC4.
- `hooks/session-start.sh`: the memory digest prints `- open: none` when no blocker is open and `- open: unknown (memory.sh index failed)` when `memory.sh index blocker` fails or times out. Both cases used to print no blocker line, so a failed read looked like a clean slate. `lib/profile-state.jq` (`profile.sh current --plain`): a newline or CR in a printed value becomes a space, and a plugin id that does not match `\A[A-Za-z0-9._-]+@[A-Za-z0-9._-]+\z` is dropped, so a settings value can no longer forge a `plugin:` line. Tests: `lib/tests/session-digest.test.sh` SD9a-SD9d, SD12; `lib/tests/profile.test.sh` T28.
- doctor.sh: the user-scope residue check compares `enabledPlugins` and `skillOverrides` between HEAD and the working `settings.json` (it compared `enabledPlugins` only), so a UI write into user-scope `skillOverrides` that dirties the tracked file is now reported; the pass and skip lines name both keys. MIGRATION "Profiles and packs" step 1 restores both keys.
- `doctor.sh`: the `settings.json` model check passes on `opus[1m]`, the tracked default, and warns on any other value. It checked for `opus`, so a clean install warned on the tracked model.
- Agents and skills (77041e5): client-handover reads the project root through a quoted heredoc and refuses a root with control characters; `lib/plugin-gate.md` prints single-quoted remedies, never runs an unsafe root, checks against the git common dir and refuses `$HOME` (as `lib/profile.sh` now does); plugin-advisor recommends `minimal` only from project signals; onboard and tour use the packs vocabulary; graphify labels match the install trap.
- `mods/` type-check under `claude plugin validate --strict` (CLI 2.1.323 started type-checking mods): 17 sites narrowed, failure behaviour unchanged (6433e4d, BLK-049); the write guard has since moved to fail-closed (see Changed).
- model-router: a Skill call whose answer carries `isError` (refused or unknown skill) no longer opens the write guard for the rest of the session. Test: `mods/model-router/hooks/register.test.ts` (GUARD: an isError Skill answer leaves the latch closed).
+4 -4
View File
@@ -70,9 +70,9 @@ commands, settings, secrets, maintenance.
## Agent model routing (model-tiering v2)
Doctrine: the main loop runs on the `opus` session model; the model-router rows
route main-loop reflection (brainstorm, plan, contract, audit judgment, loop
decisions) to the `best` tier, opus at the phase's effort. Fable is never
Doctrine: the main loop runs on the `opus[1m]` session model; the model-router
rows route main-loop reflection (brainstorm, plan, contract, audit judgment,
loop 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
@@ -326,7 +326,7 @@ cd my-existing-project/
/ship-feature "feature description"
# → STEP 0: plugin check, project context, contract
# → STEP 1-2: brainstorm + plan (vendored superpowers skills)
# → STEP 2b: adversarial plan-challenge (3 lenses, report-only)
# → STEP 2b: adversarial plan-challenge (3 lenses, report-only; a `[deferred]` point stops once: keep / cut / reopen)
# → STEP 3: validation gate — user approval required
# → STEP 4: implement (TDD)
# → STEP 5: verify + secure (fresh verifier and security-auditor gates)
+1 -1
View File
@@ -387,7 +387,7 @@ Ajouter un archétype : créer `~/.claude/lib/project-archetypes/<name>.md` (voi
# Feature simple, pas d'orchestration lourde
/feat "ajouter un endpoint GET /api/v1/users/:id/stats"
# → plan + challenge, exécuteur `feater`, gates fraîches verifier + sécurité
# Pas de brainstorming superpowers, pas de gate de validation
# Pas de brainstorming superpowers, pas de gate de validation (seul un point `[deferred]` du challenge arrête le run, une fois : garder / couper / rouvrir)
```
**Choisir entre /ship-feature et /feat :**