docs(effort): BDR-107 id, CHANGELOG entry, spec corrected for the rulings (vendored pins, exclusions, pairing rule)

CHANGELOG.md

@@ -7,6 +7,7 @@ Format follows [Keep a Changelog](https://keepachangelog.com/).
 ## [Unreleased]
 
 ### Added
+- **Effort tiering (BDR-107)**: reasoning effort routed per role and per phase. Session default `high`; `effort:` pins on the 20 repo-authored agents; entry level on 28 tracked user-invoked skills plus the two vendored superpowers skills (re-applied by `install-plugins.sh` after resync); five shifter skills `effort-low` … `effort-max` loaded at phase boundaries per `lib/effort-shift.md`, always sent with the step's first tool call (a lone Skill call is a no-op on 2.1.283), with `max` at the verify-secure caps and ship-feature 4b; `/effort-max` as the turn-scoped relaunch lever; statusline shows the live level; session banner warns when `CLAUDE_CODE_EFFORT_LEVEL` silences the pins; census `lib/tests/effort-routing.test.sh`; transcript audit `lib/effort-audit.py`.
 - **Design gate asks the user to sign in to 21st instead of skipping it**:
   `lib/design-tool-gate.sh` adds a three-state 21st auth predicate
   (`twentyfirst_auth_state`, honors `TWENTYFIRST_TOKEN`/`API_KEY_21ST` or a

agents/client-handover-writer.md

@@ -262,7 +262,7 @@ the gate.
 this pipeline (initial audits, fix-loop re-dispatches, commit-change,
 web-validate) carries `model: "fable"` — the child hosts gated orchestration
 on the pipeline's behalf; it must never inherit the session model.
-EFFORT SHIFTS: follow `$HOME/.claude/lib/effort-shift.md` (BDR-NEXT): medium when a dispatch span starts, own level before challenge synthesis, low at the bookkeeping tail, max at escalation; every shift goes in the same message as the step's first tool call, a lone Skill call is a no-op.
+EFFORT SHIFTS: follow `$HOME/.claude/lib/effort-shift.md` (BDR-107): medium when a dispatch span starts, own level before challenge synthesis, low at the bookkeeping tail, max at escalation; every shift goes in the same message as the step's first tool call, a lone Skill call is a no-op.
 
 For web projects, dispatch in **a single message with two parallel Agent calls** (each with `model: "fable"`):
 

docs/superpowers/specs/2026-09-28-effort-tiering-design.md

@@ -34,6 +34,8 @@ repo.
 | Subagent frontmatter `effort:` | Applied to the subagent. Absent → **inherits the session level**. | built-in on sonnet printed `xhigh`; impeccable agent pinned `medium` printed `medium` |
 | Skill frontmatter `effort:`, user-typed `/skill` | Applied for the **rest of the turn**, AskUserQuestion included. | headless `/effort-probe-low`: every request at `low` |
 | Skill frontmatter `effort:`, loaded by Claude through the Skill tool, **interactive** session | Applied for the rest of the turn. Last loaded skill wins, up and down. | this session: `xhigh` → probe max → `$CLAUDE_EFFORT=max`, request records `effort=max` → probe xhigh → back to `xhigh` |
+| Same, pairing rule | Applies **only when the Skill call shares the assistant message with another tool call after it**; a lone Skill call is a no-op. The paired call already runs at the new level. | this session, 8/8 observations |
+| Same, re-load | A shifter already loaded in the conversation re-applies its effort when loaded again (paired); only its text is deduped. | this session |
 | Same, **headless** (`-p`) | **Not applied** (neither `effort:` nor `model:`). | three `-p` runs, transcript effort unchanged |
 | Prompt cache on a mid-turn shift | **Preserved** on Fable 5.1: first request at max read 206,996 cached tokens, wrote 1,164. | this session |
 | Agent tool call site | No `effort` parameter (only `model`). One agent file = one effort. | tool schema |
@@ -97,14 +99,16 @@ Applies from the user's invocation for the rest of the turn.
 | effort | Skills |
 |---|---|
 | low | status, commit-change, release-candidate, doc, capitalize, close, reconcile, deploy, profile, plugin-check |
-| medium | gitflow, prune-memory, find-docs |
+| medium | gitflow, prune-memory |
 | high | feat, hotfix, bugfix, refactor, web-validate, harden, seo, geo |
-| xhigh | ship-feature, init-project, onboard, tour, audit-delta, analyze, code-clean, client-handover, spec, skillify, brainstorming, writing-plans |
+| xhigh | ship-feature, init-project, onboard, tour, audit-delta, analyze, code-clean, client-handover, brainstorming, writing-plans |
-| unlisted | session default, by design (gstack and plugin skills are external; graphify is machine-owned) |
+| unlisted | session default, by design: gstack skills (`spec` and `skillify` are gstack), plugin skills, and machine-generated skills (`graphify`, `find-docs`) |
 
-`brainstorming` and `writing-plans` are vendored superpowers skills: the
+`brainstorming` and `writing-plans` are vendored superpowers skills living in
-one-line patch drifts from upstream at each resync; a census lock (§7)
+`skills-external/` (gitignored, symlinked into `skills/`): the pin is applied
-makes the loss loud.
+to the real file and never committed; `install-plugins.sh` re-applies it after
+every resync, and the census checks it whenever the file is present (visible
+SKIP otherwise).
 
 A skill loaded by Claude as a sub-step (feat → commit-change) also shifts
 the level for the rest of the turn (interactive, §2), so orchestrators
@@ -121,6 +125,9 @@ mirroring `lib/model-gate.md`:
 - A shift is a `Skill(effort-<level>)` call on the main loop. Never inside a
   dispatched agent (agents run on their pin). One tool round-trip,
   cache-safe (§2).
+- **Pairing rule**: the shift is sent in the same assistant message as the
+  step's first tool call, shift first; a lone Skill call is a no-op (§2).
+  Re-loading a shifter re-applies its effort.
 - Orchestrator wiring, three points each: `effort-medium` when the plan is
   closed and the dispatch phase starts; `effort-low` before the
   capitalize / journal / doc-commit tail; `effort-max` at an escalation
@@ -176,7 +183,7 @@ each subagent's effort (2.1.243).
 |---|---|
 | `settings.json` | `effortLevel` → `high` (curated config: read the diff, LRN-098) |
 | `agents/*.md` (20) | `effort:` line per D2; `skills/init-project/SKILL.md:98` citer |
-| `skills/*/SKILL.md` (33) | `effort:` line per D3, including the two vendored superpowers skills |
+| `skills/*/SKILL.md` (28 tracked) + `skills-external/{brainstorming,writing-plans}/SKILL.md` (not committed) | `effort:` line per D3; `install-plugins.sh` re-applies the two vendored pins after resync |
 | `skills/effort-{low,medium,high,xhigh,max}/SKILL.md` | new, frontmatter + one sentence |
 | `lib/effort-shift.md` | new include: protocol, wiring points, escalation, turn reset, headless note |
 | `lib/model-gate.md` §4 | one paragraph: effort is the second axis, pointer to the include |
@@ -185,6 +192,7 @@ each subagent's effort (2.1.243).
 | orchestrator SKILL.md (feat, hotfix, bugfix, ship-feature, init-project, onboard, tour, code-clean, seo, geo, harden, web-validate, client-handover, audit-delta) | include line + the three wiring points; ship-feature 4b max |
 | `hooks/statusline.sh`, `hooks/session-start.sh` | live effort display; env-var warning |
 | `lib/tests/effort-routing.test.sh` | new census suite (§7) |
+| `lib/effort-audit.py` | transcript audit script (§9) |
 | `CHANGELOG.md`, `.claude/memory/*` | release note; BDR + LRN + EVAL + journal (§8) |
 
 ## 7. Tests and census (`make test`)
@@ -196,8 +204,9 @@ New suite `lib/tests/effort-routing.test.sh`, `grep -qF` locks in the
    in its first 10 frontmatter lines, level in the allowed set; the "none"
    list has no `effort:`.
 2. Tier locks per D2 (one `has` per agent).
-3. Skill locks per D3 (one `has` per skill), including `brainstorming` and
+3. Skill locks per D3 (one per skill); the two vendored skills are checked
-   `writing-plans` (the resync alarm).
+   when present (visible SKIP otherwise); `install-plugins.sh` carries the
+   re-apply block.
 4. The five shifter skills exist with the exact `name:` and `effort:`.
 5. `lib/effort-shift.md` is included by every orchestrator in the §6 list;
    `verify-secure-loop.md` and `ship-feature/SKILL.md` contain the

hooks/session-start.sh

@@ -107,7 +107,7 @@ fi
 REPO_DIR="${_repo_dir:-}"
 unset _claude_real _repo_dir
 
-# Effort tiering (BDR-NEXT): this env var beats every skill/agent `effort:` pin.
+# Effort tiering (BDR-107): this env var beats every skill/agent `effort:` pin.
 EFFORT_WARN=""
 if [ -n "${CLAUDE_CODE_EFFORT_LEVEL:-}" ]; then
   EFFORT_WARN="⚠️  CLAUDE_CODE_EFFORT_LEVEL=${CLAUDE_CODE_EFFORT_LEVEL} set: skill/agent effort pins ignored"

hooks/statusline.sh

@@ -34,7 +34,7 @@ if [ -z "$PROFILE" ] || [ "$PROFILE" = "none" ]; then
 fi
 
 # Effort level: the live value when the harness exports it (skill/agent
-# `effort:` shifts included, BDR-NEXT), else the persisted settings.json key
+# `effort:` shifts included, BDR-107), else the persisted settings.json key
 # (.effortLevel — set by /effort or manual edit; symlinked into ~/.claude).
 EFFORT="${CLAUDE_EFFORT:-}"
 if [ -z "$EFFORT" ] && [ -f "$REPO/settings.json" ]; then

install-plugins.sh

@@ -934,7 +934,7 @@ for _ext_skill in "${EXT_SKILL_NAMES[@]}"; do
 done
 echo ""
 
-# Effort tiering (BDR-NEXT): the vendored brainstorming/writing-plans carry an
+# Effort tiering (BDR-107): the vendored brainstorming/writing-plans carry an
 # effort pin upstream lacks; re-apply after every resync (census lock in
 # lib/tests/effort-routing.test.sh alarms if this ever stops working).
 for _s in brainstorming writing-plans; do

lib/effort-shift.md

@@ -1,4 +1,4 @@
-# Effort shift — phase-level reasoning effort on the main loop (BDR-NEXT)
+# Effort shift — phase-level reasoning effort on the main loop (BDR-107)
 
 Shared include, companion of `lib/model-gate.md`: the gate fixes WHICH model
 reflects, this include fixes HOW HARD each phase thinks. The rungs are the

lib/model-gate.md

@@ -46,6 +46,6 @@ the main loop's behalf (skill-runners), otherwise its complexity tier
 (opus = dispatched judgment, sonnet = execution/collection, haiku = short
 mechanical probes).
 
-Effort is the second axis of the same table (BDR-NEXT): every typed agent
+Effort is the second axis of the same table (BDR-107): every typed agent
 carries an `effort:` pin next to `model:`, and the main loop shifts per phase
 through `lib/effort-shift.md`. Nothing dispatched inherits either axis.

lib/tests/effort-routing.test.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# lib/tests/effort-routing.test.sh — census: effort tiering (BDR-NEXT)
+# lib/tests/effort-routing.test.sh — census: effort tiering (BDR-107)
 # agent pins, skill entry levels, shifter skills, orchestrator wiring, settings.
 # shellcheck disable=SC2015  # A && ok || ko is deliberate here: ok/ko never fail, so C never masks a true A
 set -u

skills/audit-delta/SKILL.md

@@ -29,7 +29,7 @@ Run `$HOME/.claude/lib/model-gate.md`. Reflection here (planning, audit
 judgment, loop decisions) requires Fable/Opus. Verdict `small` → STOP: the
 gate prints the remedy; end the turn — no later step, no dispatch. Nominal
 (big) path is silent.
-EFFORT SHIFTS: follow `$HOME/.claude/lib/effort-shift.md` (BDR-NEXT): medium when a dispatch span starts, own level before challenge synthesis, low at the bookkeeping tail, max at escalation; every shift goes in the same message as the step's first tool call, a lone Skill call is a no-op.
+EFFORT SHIFTS: follow `$HOME/.claude/lib/effort-shift.md` (BDR-107): medium when a dispatch span starts, own level before challenge synthesis, low at the bookkeeping tail, max at escalation; every shift goes in the same message as the step's first tool call, a lone Skill call is a no-op.
 
 Audit only what changed since the last run, on the axes the user picks.
 Per axis: **audit → approval gate → fix → re-verify → marker update**,

skills/bugfix/SKILL.md

@@ -26,7 +26,7 @@ allowed-tools:
 MODEL GATE (blocking): run `$HOME/.claude/lib/model-gate.md` BEFORE any
 step below. Verdict `small` → STOP — print the gate's remedy, end the
 turn, dispatch nothing.
-EFFORT SHIFTS: follow `$HOME/.claude/lib/effort-shift.md` (BDR-NEXT): medium when a dispatch span starts, own level before challenge synthesis, low at the bookkeeping tail, max at escalation; every shift goes in the same message as the step's first tool call, a lone Skill call is a no-op.
+EFFORT SHIFTS: follow `$HOME/.claude/lib/effort-shift.md` (BDR-107): medium when a dispatch span starts, own level before challenge synthesis, low at the bookkeeping tail, max at escalation; every shift goes in the same message as the step's first tool call, a lone Skill call is a no-op.
 
 ## REQUEST
 $ARGUMENTS

skills/code-clean/SKILL.md

@@ -26,7 +26,7 @@ allowed-tools:
 MODEL GATE (blocking): run `$HOME/.claude/lib/model-gate.md` BEFORE any
 step below. Verdict `small` → STOP — print the gate's remedy, end the
 turn, dispatch nothing.
-EFFORT SHIFTS: follow `$HOME/.claude/lib/effort-shift.md` (BDR-NEXT): medium when a dispatch span starts, own level before challenge synthesis, low at the bookkeeping tail, max at escalation; every shift goes in the same message as the step's first tool call, a lone Skill call is a no-op.
+EFFORT SHIFTS: follow `$HOME/.claude/lib/effort-shift.md` (BDR-107): medium when a dispatch span starts, own level before challenge synthesis, low at the bookkeeping tail, max at escalation; every shift goes in the same message as the step's first tool call, a lone Skill call is a no-op.
 
 ## TARGET
 $ARGUMENTS

skills/feat/SKILL.md

@@ -26,7 +26,7 @@ allowed-tools:
 MODEL GATE (blocking): run `$HOME/.claude/lib/model-gate.md` BEFORE any
 step below. Verdict `small` → STOP — print the gate's remedy, end the
 turn, dispatch nothing.
-EFFORT SHIFTS: follow `$HOME/.claude/lib/effort-shift.md` (BDR-NEXT): medium when a dispatch span starts, own level before challenge synthesis, low at the bookkeeping tail, max at escalation; every shift goes in the same message as the step's first tool call, a lone Skill call is a no-op.
+EFFORT SHIFTS: follow `$HOME/.claude/lib/effort-shift.md` (BDR-107): medium when a dispatch span starts, own level before challenge synthesis, low at the bookkeeping tail, max at escalation; every shift goes in the same message as the step's first tool call, a lone Skill call is a no-op.
 
 ## REQUEST
 $ARGUMENTS

skills/geo/SKILL.md

@@ -29,7 +29,7 @@ Run `$HOME/.claude/lib/model-gate.md`. Reflection here (planning, audit
 judgment, loop decisions) requires Fable/Opus. Verdict `small` → STOP: the
 gate prints the remedy; end the turn — no later step, no dispatch. Nominal
 (big) path is silent.
-EFFORT SHIFTS: follow `$HOME/.claude/lib/effort-shift.md` (BDR-NEXT): medium when a dispatch span starts, own level before challenge synthesis, low at the bookkeeping tail, max at escalation; every shift goes in the same message as the step's first tool call, a lone Skill call is a no-op.
+EFFORT SHIFTS: follow `$HOME/.claude/lib/effort-shift.md` (BDR-107): medium when a dispatch span starts, own level before challenge synthesis, low at the bookkeeping tail, max at escalation; every shift goes in the same message as the step's first tool call, a lone Skill call is a no-op.
 
 Dispatches the `geo-analyzer` subagent (audit + fix bundle), then applies
 the bundle from THIS main loop at **L1** — same shape as `/web-validate`

skills/harden/SKILL.md

@@ -29,7 +29,7 @@ Run `$HOME/.claude/lib/model-gate.md`. Reflection here (planning, audit
 judgment, loop decisions) requires Fable/Opus. Verdict `small` → STOP: the
 gate prints the remedy; end the turn — no later step, no dispatch. Nominal
 (big) path is silent.
-EFFORT SHIFTS: follow `$HOME/.claude/lib/effort-shift.md` (BDR-NEXT): medium when a dispatch span starts, own level before challenge synthesis, low at the bookkeeping tail, max at escalation; every shift goes in the same message as the step's first tool call, a lone Skill call is a no-op.
+EFFORT SHIFTS: follow `$HOME/.claude/lib/effort-shift.md` (BDR-107): medium when a dispatch span starts, own level before challenge synthesis, low at the bookkeeping tail, max at escalation; every shift goes in the same message as the step's first tool call, a lone Skill call is a no-op.
 
 This skill orchestrates a narrow-scope hardening audit: TLS + security
 headers + redirects + canonical + custom 404 + server configs. It

skills/hotfix/SKILL.md

@@ -24,7 +24,7 @@ allowed-tools:
 MODEL GATE (blocking): run `$HOME/.claude/lib/model-gate.md` BEFORE any
 step below. Verdict `small` → STOP — print the gate's remedy, end the
 turn, dispatch nothing.
-EFFORT SHIFTS: follow `$HOME/.claude/lib/effort-shift.md` (BDR-NEXT): medium when a dispatch span starts, own level before challenge synthesis, low at the bookkeeping tail, max at escalation; every shift goes in the same message as the step's first tool call, a lone Skill call is a no-op.
+EFFORT SHIFTS: follow `$HOME/.claude/lib/effort-shift.md` (BDR-107): medium when a dispatch span starts, own level before challenge synthesis, low at the bookkeeping tail, max at escalation; every shift goes in the same message as the step's first tool call, a lone Skill call is a no-op.
 
 ## REQUEST
 $ARGUMENTS

skills/init-project/SKILL.md

@@ -14,7 +14,7 @@ Run `$HOME/.claude/lib/model-gate.md`. Reflection here (planning, audit
 judgment, loop decisions) requires Fable/Opus. Verdict `small` → STOP: the
 gate prints the remedy; end the turn — no later step, no dispatch. Nominal
 (big) path is silent.
-EFFORT SHIFTS: follow `$HOME/.claude/lib/effort-shift.md` (BDR-NEXT): medium when a dispatch span starts, own level before challenge synthesis, low at the bookkeeping tail, max at escalation; every shift goes in the same message as the step's first tool call, a lone Skill call is a no-op.
+EFFORT SHIFTS: follow `$HOME/.claude/lib/effort-shift.md` (BDR-107): medium when a dispatch span starts, own level before challenge synthesis, low at the bookkeeping tail, max at escalation; every shift goes in the same message as the step's first tool call, a lone Skill call is a no-op.
 
 ## REQUEST
 $ARGUMENTS

skills/onboard/SKILL.md

@@ -14,7 +14,7 @@ Run `$HOME/.claude/lib/model-gate.md`. Reflection here (planning, audit
 judgment, loop decisions) requires Fable/Opus. Verdict `small` → STOP: the
 gate prints the remedy; end the turn — no later step, no dispatch. Nominal
 (big) path is silent.
-EFFORT SHIFTS: follow `$HOME/.claude/lib/effort-shift.md` (BDR-NEXT): medium when a dispatch span starts, own level before challenge synthesis, low at the bookkeeping tail, max at escalation; every shift goes in the same message as the step's first tool call, a lone Skill call is a no-op.
+EFFORT SHIFTS: follow `$HOME/.claude/lib/effort-shift.md` (BDR-107): medium when a dispatch span starts, own level before challenge synthesis, low at the bookkeeping tail, max at escalation; every shift goes in the same message as the step's first tool call, a lone Skill call is a no-op.
 
 ## REQUEST
 $ARGUMENTS

skills/seo/SKILL.md

@@ -30,7 +30,7 @@ Run `$HOME/.claude/lib/model-gate.md`. Reflection here (planning, audit
 judgment, loop decisions) requires Fable/Opus. Verdict `small` → STOP: the
 gate prints the remedy; end the turn — no later step, no dispatch. Nominal
 (big) path is silent.
-EFFORT SHIFTS: follow `$HOME/.claude/lib/effort-shift.md` (BDR-NEXT): medium when a dispatch span starts, own level before challenge synthesis, low at the bookkeeping tail, max at escalation; every shift goes in the same message as the step's first tool call, a lone Skill call is a no-op.
+EFFORT SHIFTS: follow `$HOME/.claude/lib/effort-shift.md` (BDR-107): medium when a dispatch span starts, own level before challenge synthesis, low at the bookkeeping tail, max at escalation; every shift goes in the same message as the step's first tool call, a lone Skill call is a no-op.
 
 This skill orchestrates TWO specialist agents running in parallel, then
 merges their output into a single `.claude/audits/SEO.md` report. It is the main

skills/ship-feature/SKILL.md

@@ -14,7 +14,7 @@ Run `$HOME/.claude/lib/model-gate.md`. Reflection here (planning, audit
 judgment, loop decisions) requires Fable/Opus. Verdict `small` → STOP: the
 gate prints the remedy; end the turn — no later step, no dispatch. Nominal
 (big) path is silent.
-EFFORT SHIFTS: follow `$HOME/.claude/lib/effort-shift.md` (BDR-NEXT): medium when a dispatch span starts, own level before challenge synthesis, low at the bookkeeping tail, max at escalation; every shift goes in the same message as the step's first tool call, a lone Skill call is a no-op.
+EFFORT SHIFTS: follow `$HOME/.claude/lib/effort-shift.md` (BDR-107): medium when a dispatch span starts, own level before challenge synthesis, low at the bookkeeping tail, max at escalation; every shift goes in the same message as the step's first tool call, a lone Skill call is a no-op.
 
 ## REQUEST
 $ARGUMENTS

skills/tour/SKILL.md

@@ -30,7 +30,7 @@ Run `$HOME/.claude/lib/model-gate.md`. Reflection here (planning, audit
 judgment, loop decisions) requires Fable/Opus. Verdict `small` → STOP: the
 gate prints the remedy; end the turn — no later step, no dispatch. Nominal
 (big) path is silent.
-EFFORT SHIFTS: follow `$HOME/.claude/lib/effort-shift.md` (BDR-NEXT): medium when a dispatch span starts, own level before challenge synthesis, low at the bookkeeping tail, max at escalation; every shift goes in the same message as the step's first tool call, a lone Skill call is a no-op.
+EFFORT SHIFTS: follow `$HOME/.claude/lib/effort-shift.md` (BDR-107): medium when a dispatch span starts, own level before challenge synthesis, low at the bookkeeping tail, max at escalation; every shift goes in the same message as the step's first tool call, a lone Skill call is a no-op.
 
 One pipeline per project: **security → clean → re-verify → reconcile →
 doc → convergence re-audit**, looping until a full pass applies zero new

skills/web-validate/SKILL.md

@@ -28,7 +28,7 @@ Run `$HOME/.claude/lib/model-gate.md`. Reflection here (planning, audit
 judgment, loop decisions) requires Fable/Opus. Verdict `small` → STOP: the
 gate prints the remedy; end the turn — no later step, no dispatch. Nominal
 (big) path is silent.
-EFFORT SHIFTS: follow `$HOME/.claude/lib/effort-shift.md` (BDR-NEXT): medium when a dispatch span starts, own level before challenge synthesis, low at the bookkeeping tail, max at escalation; every shift goes in the same message as the step's first tool call, a lone Skill call is a no-op.
+EFFORT SHIFTS: follow `$HOME/.claude/lib/effort-shift.md` (BDR-107): medium when a dispatch span starts, own level before challenge synthesis, low at the bookkeeping tail, max at escalation; every shift goes in the same message as the step's first tool call, a lone Skill call is a no-op.
 
 This skill orchestrates a narrow-scope standards audit :