@dzhechkov/skills-feature-adr 1.3.40 → 1.3.41

package/README.md

@@ -175,6 +175,52 @@ Workflow({ scriptPath: '.claude/workflows/feature-adr.js',
           models: { code: 'opus', qe: 'codex:gpt-5.6:high', architecture: 'opus', router: 'fable' } } })
 ```
 
+### Usage-adaptive routing — pre-emptive Codex switch at ≥ 70% Claude usage
+
+The `codex-fallback` knobs above are **reactive** — they catch a stage *after* it dies on a limit. At
+true exhaustion even the fallback dispatch can die, so the pipeline also switches **pre-emptively**:
+when model routing is opted into, it probes Claude **SESSION** (active 5h-block) and **WEEKLY** (rolling
+7d) usage at each phase boundary via `dz usage --json` (from `@dzhechkov/harness-cli`), and moves the
+remaining stages to Codex **before** hitting the wall.
+
+| Knob (`args.*`) | Default | Effect |
+|---|---|---|
+| `usageAdaptive` | `true` when routing is requested; `false` otherwise | `true` forces it on by itself; `false` disables all probes (byte-identical to no-routing runs) |
+| `usageThreshold` | `70` | the `>=` percent (SESSION **or** WEEKLY) that triggers the switch |
+| `usageReasoning` | built-in map | per-stage reasoning under the override (design/code/plan → `xhigh`; router/qe/fleet → `high`) |
+
+**Two-way, hysteretic, fail-safe:**
+
+- `>= usageThreshold` on **either** metric ⇒ ALL remaining stages switch to `codex:<top>`.
+- Both metrics back below (positive numbers, not nulls) ⇒ the normal model mix is **restored**.
+- A probe whose agent **dies** (often *means* the limit was hit) fail-safe-switches to Codex; a
+  value-null (limits not configured) flips nothing — no flapping, no false switches.
+- A reactive belt remains: a stage agent returning null while not overridden also flips the switch for
+  the *remaining* stages.
+
+**Observability:** switched stages carry ` (usage-switched)` in `modelsUsed`; results include
+`usageEvents` (`[{phase, sessionPct, weeklyPct, action}]`, action ∈
+`switch|restore|keep|fail-safe-switch|reactive-switch|none`) and `usageThreshold`.
+
+**Config (optional):** percentages are local-transcript **estimates** (no official usage API); they stay
+`null` — and never trigger a switch — until you set your plan's limits in `.dz/config.json`:
+
+```json
+{ "memory": { "usage": { "sessionTokenLimit": 200000000, "weeklyTokenLimit": 1000000000 } } }
+```
+
+```js
+// Claude codes until usage crosses 70%, then every remaining stage runs on Codex until it drops back:
+Workflow({ scriptPath: '.claude/workflows/feature-adr.js',
+  args: { slug: 'add-oauth', description: '…', tier: 'L',
+          models: { code: 'opus' }, usageAdaptive: true, usageThreshold: 70 } })
+```
+
+> Note: under the override, coder **and** QE both run on Codex — the cross-model self-QE guard is
+> consciously suspended (a Claude QE reviewer is exactly the agent that dies under limit pressure). The
+> ` (usage-switched)` suffix + `usageEvents` keep it auditable; re-run an independent QE after limits
+> reset if the switch fired during Step 8.
+
 ---
 
 ## Spec-Driven Development (SDD)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/skills-feature-adr",
-  "version": "1.3.40",
+  "version": "1.3.41",
   "description": "Adaptive Feature Development skill pack for Claude Code — 11-step pipeline with Complexity Router (S/M/L/XL), ADR-driven architecture, 15 agentic-qe skills, multi-agent fleet QE. Supports --full-qe, --full-qe-extended, --with-learning, and --knowledge-extractor modes.",
   "bin": {
     "skills-feature-adr": "./bin/cli.js"
@@ -13,6 +13,10 @@
     "CHANGELOG.md",
     "docs/"
   ],
+  "scripts": {
+    "test": "node --test \"test/**/*.test.js\"",
+    "prepack": "node -e \"const fs=require('fs');const bad=['.claude','.skills-feature-adr.json'].filter(p=>fs.existsSync(p));if(bad.length){console.error('prepack guard: stray init artifacts in package dir: '+bad.join(', ')+' — remove before packing');process.exit(1)}\""
+  },
   "keywords": [
     "claude",
     "claude-code",
@@ -57,8 +61,5 @@
   },
   "publishConfig": {
     "access": "public"
-  },
-  "scripts": {
-    "test": "node --test \"test/**/*.test.js\""
   }
-}
+}