@dzhechkov/keysarium 1.5.23 → 1.5.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/keysarium",
-  "version": "1.5.23",
+  "version": "1.5.27",
   "description": "AI Case Research Toolkit for Claude Code — full 7-phase pipeline with feature-adr, dream cycles, background workers, multi-platform support, reward learning, and Cloud.ru AI Factory mapping (--ai-factory flag)",
   "main": "src/cli.js",
   "bin": {

package/templates/.claude/skills/feature-adr/SKILL.md

@@ -375,6 +375,69 @@ Pre-flight, if Codex is `ready` (`codex-companion setup --json`), the orchestrat
 before launching; plain `/feature-adr` offers the same at the planning checkpoint. Omit the Codex knobs
 for today's all-Claude behavior. See `.claude/rules/feature-adr-ultracode.md`.
 
+**Per-stage model routing — `args.models` (one dial, 11 stages).** `args.models` is an optional map that
+routes each pipeline stage to an optimal model. Keys: `{router, requirements, research, adr, ideation,
+ddd, architecture, plan, code, qe, fleet}`. Each value is a **spec**:
+
+- **Claude** — `'fable' | 'opus' | 'sonnet' | 'haiku'` → adds `model` to that stage's `agent()` call
+  (any role `agentType` like `qe-code-reviewer` is PRESERVED).
+- **Codex** — `'codex'` / `'codex:<id>'` / `'codex:<id>:<reasoning>'` (e.g. `'codex:gpt-5.6:xhigh'`;
+  `reasoning ∈ low|medium|high|xhigh`; ids incl. `gpt-5.5`, `gpt-5.6`) → routes the stage to the
+  `codex:codex-rescue` runtime with that `codexModel` + reasoning hint.
+
+**Recommended DEFAULT TABLE** (applied only when you opt into routing — any one `args.models` key or any
+Codex knob flips it on; otherwise every stage stays session-inherited, byte-identical to today):
+
+| Stage | Default | | Stage | Default |
+|---|---|---|---|---|
+| router | `fable` | | architecture | `opus` |
+| requirements | `sonnet` | | plan | `sonnet` |
+| research | `sonnet` (folds into requirements) | | code | *the coder knob* (default Claude `opus`) |
+| adr | `opus` | | qe | *CROSS-MODEL of the coder* (see below) |
+| ideation | `sonnet` | | fleet | `sonnet` |
+| ddd | `opus` (folds into architecture) | | | |
+
+**Cross-model QE default (load-bearing).** When `args.models.qe` is UNSET, QE is auto-routed to the
+**other model family than the coder** — a model that WRITES code must not also SELF-QE; independent
+cross-model review catches what self-review misses. coder=Codex ⇒ QE=Claude (`opus`); coder=Claude ⇒
+QE=Codex (`codex:<top>:high`), or a Claude reviewer if Codex is unavailable (**never blocks**).
+
+**Precedence.** `args.models[stage]` is the general mechanism and WINS on conflict; the legacy
+`planner`/`coder`/`qeReviewer`/`codexModel` knobs are shortcuts that fill a stage only when `args.models`
+does not. `codexModel` sets the default id for a bare `'codex'` spec. Codex-fallback (Claude-first, then
+Codex on limit-exhaustion) stays a knob-only behavior; a direct `models.code='codex'` means codex-first.
+
+**gpt-5.6-ready** — a new Codex id is a DATA-ONLY addition to the `KNOWN_CODEX` allowlist (no control flow).
+**Reporting** — the run result includes `modelsUsed` (the resolved per-stage model) so you see who did what.
+
+*Example:* `Workflow({ scriptPath: '.claude/workflows/feature-adr.js', args: { slug, description, tier:
+'L', models: { code: 'opus', qe: 'codex:gpt-5.6:high', architecture: 'opus', router: 'fable' } } })` —
+Claude writes the code, Codex independently QEs it.
+
+**Usage-adaptive routing (pre-emptive Codex switch under limit pressure).** When routing is opted into,
+the workflow probes Claude SESSION (active 5h-block) and WEEKLY (rolling 7d) usage at EACH phase boundary
+via a minimal `dz usage --json` agent. When either metric is `>= usageThreshold` (default `70`) BEFORE a
+phase launches — OR the probe output is missing (agent-null, which often MEANS the limit was hit) — ALL
+remaining stages switch to `codex:<top>` (design/code/plan at `xhigh`, router/qe/fleet at `high`). When a
+later probe reads BOTH metrics below the threshold (positive numbers, not nulls), the normal Claude+Codex
+mix is RESTORED. Null percentages (unconfigured limits) change NOTHING in either direction. Switched
+stages are tagged ` (usage-switched)` in `modelsUsed`, and every flip is recorded in the result's
+`usageEvents` array (the audit trail — never trust promiseTags for this). Args:
+
+| `args.*` | Default | Effect |
+|---|---|---|
+| `usageAdaptive` | `true` when routing is requested (any `args.models` key or Codex knob); `false` otherwise | `true` forces it on even without other routing; `false` disables all probes (byte-identical to today) |
+| `usageThreshold` | `70` | the `>=` percent (either metric) that triggers the pre-emptive switch |
+| `usageReasoning` | the `OVERRIDE_REASONING` map | per-stage reasoning under the override (merge over the default: design/code/plan → `xhigh`, router/qe/fleet → `high`) |
+
+Configure the limits the probe measures against in `.dz/config.json` — `memory.usage.sessionTokenLimit`
+and `memory.usage.weeklyTokenLimit` (OPTIONAL; absent ⇒ `pct` is `null` and no switch fires). The
+percentages are **ESTIMATES** from local transcript aggregation (there is no official usage API);
+**calibrate** by scaling a limit by `X/100` when a real limit-hit lands at an estimated `X%`.
+**Honest caveat (the wrapper lesson):** at TRUE exhaustion even the Codex dispatch dies because
+`codex:codex-rescue` is a Claude wrapper subagent — so the switch MUST happen BEFORE, which is why the
+70% pre-emptive probe (not just reactive null-detection) is the real defense.
+
 ### Pattern memory loop (self-learning — runs in ALL modes)
 
 **Self-learning is MANDATORY on EVERY `/feature-adr` run — including plain `/feature-adr` without any
@@ -408,6 +471,15 @@ non-blocking — an error or empty result never stalls the pipeline. This layer
 **distinct from the Keysarium reward layer** installed by `--with-learning`: it uses agentic-qe MCP
 memory + the dz store, is UNCONDITIONAL for the dz half (recall/teach/fa-record run in every mode) and Direct-mode-only for the aqe-MCP half, and never touches `.keysarium/memory/`.
 
+**Canonical brain store — `args.brain` (never fragment the loop).** The dz durable loop only compounds if
+Step-0 recall and Step-8 teach hit the SAME store. The workflow pins both to a canonical **brain** —
+`args.brain`, default = the workspace root — via `cd <brain> && dz recall/teach … --project <brain>`, so a
+Step-8 teach issued from a coder that `cd`'d into a target repo still lands in the brain, not that repo's
+`.dz`. Omitting `args.brain` is behaviorally inert for a workspace-CWD run (`brain === repo`). **Share** a
+brain: `dz recall --all --json > patterns.json` → `dz teach --from-json patterns.json --project <brain>`
+(exact-text dedup, idempotent). **Recover** a fragmented store: `cd <stray-repo> && dz recall --all --json >
+/tmp/stray.json` → `dz teach --from-json /tmp/stray.json --project <brain>` to merge it back into the brain.
+
 **Live learning panel (`dz statusline`).** The pipeline **drives** the panel: at each pattern-memory-loop
 step above it records its live state via `dz statusline --fa-record …`, so `dz statusline` can surface
 per-run learning (which feature, which step, how many patterns recalled vs. newly stored). Each of the