playmaker-cli 0.13.0__tar.gz → 0.14.0__tar.gz

{playmaker_cli-0.13.0 → playmaker_cli-0.14.0}/CHANGELOG.md

@@ -5,6 +5,66 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.14.0] - 2026-09-30
+
+### Added
+
+- **`--effort` for the `claude` lane.** `[agents.claude] effort = "xhigh"` or
+  `playmaker dispatch|continue … --effort <low|medium|high|xhigh|max>` is forwarded to
+  Claude Code's own `--effort`, right after `--model`, on dispatch and resume. The flag
+  overrides the config for one run (carried through `PLAYMAKER_CLAUDE_EFFORT`, never
+  persisted); an invalid value fails before any process starts; other lanes accept and
+  ignore it with a note.
+- **Banked limit resets in `playmaker quotas`.** The Codex block shows
+  `Banked resets  N (M usable now)` and each reset's expiry (from
+  `wham/rate-limit-reset-credits`, same bearer token). Claude's reset is not reachable
+  with the CLI token (CodexBar reads it from the web session) and stays out.
+- **The coach's ledger.** `scripts/ledger.py` keeps one JSON line per landed work package
+  in `~/.playmaker/ledger.jsonl` (`add`, `fix`, `escape`, `stats`, `tail`), and
+  `scripts/ledger-hook.py` — a Claude Code `PostToolUse` hook on `Bash` — writes the row
+  on every `git commit` from the WP's review directory, with an optional junior model
+  (`[ledger] junior = "codex:<model>"`) filling the soft fields. Fields, mapping and the
+  settings snippet: `references/ledger.md`.
+- **`--risk seams` in `review-board.sh`.** A one-seat board over the joints between the
+  work packages of one fan-out, after each passed its own board and the global gate.
+
+### Changed
+
+- **The coach skill, 2026-09-30 revision** (`skills/playmaker-coach`): routing is
+  «fit before headroom» (class the WP, then the ledger, then the pool floors, then
+  headroom); map vs. semantic recon; an integration step with a seam review before
+  landing; fixed board columns; a first-minute check on every detached dispatch and no
+  waiting on closed lanes; policy load order is personal, then repo. Reviewer roster
+  lines are an ordered preference list — the script seats exactly 1/2/3/1 for
+  routine/normal/high/seams after skipping the implementer and holds the rest in
+  reserve; fewer than required stops it (`PM_REVIEW_ALLOW_SHORT=1` overrides).
+- **`review-board.sh` protects its artefacts.** Previous verdicts are archived on a new
+  dispatch and ignored by `--collect` when older than the current patch; `--dry-run`
+  no longer truncates `sessions.txt`; untracked files under the review paths are listed
+  with the `git add -N` hint; `board.env` records risk, round and required count;
+  `--collect` marks `failed`/`killed` seats DEAD, parses the last object carrying the
+  contract, and prints `verdicts: k/N` (`BOARD INCOMPLETE` while short). The prompt
+  interpolates the base ref, forbids edits and scratch files inside the tree, tells a
+  seat that cannot run the gate to report it under `unverifiable`, and asks the `risk`
+  lens to falsify the acceptance criteria.
+
+### Fixed
+
+- **`playmaker quotas` no longer refreshes the Claude OAuth token.** The probe shared
+  the keychain entry and the single-use refresh token with the Claude Code CLI, and the
+  race logged the CLI out. The probe now only reads; when the token is expired it lets
+  the CLI refresh it (`[quotas] claude_refresh_via_cli`, default on) or shows
+  `login expired — run: claude auth login`. An outage after a successful refresh is
+  reported as an outage, not as an expired login.
+- **The reset-credits inventory is best-effort**: a failing secondary request no
+  longer sinks the whole Codex block.
+- **The ledger's writers take a lock and rewrites are atomic.** `ledger.py add` (and so
+  the hook) appends under an `flock`; `fix` and `escape` hold the same lock across their
+  read-modify-write and publish through a temp file and `os.replace`, so two coach sessions
+  committing at once cannot lose a row or tear the file; a trailing partial line is skipped
+  by the readers instead of stopping them. `--effort` is validated in the CLI before a
+  detached run spawns.
+
 ## [0.13.0] - 2026-09-30
 
 ### Added

{playmaker_cli-0.13.0 → playmaker_cli-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: playmaker-cli
-Version: 0.13.0
+Version: 0.14.0
 Summary: Playing-coach CLI for orchestrating Claude Code, Codex, Antigravity, Kimi Code, Muse Code and opencode sub-agents in parallel.
 Project-URL: Homepage, https://github.com/vladsafedev/playmaker
 Project-URL: Repository, https://github.com/vladsafedev/playmaker
@@ -375,6 +375,16 @@ A bare name is resolved on `PATH`; a path is used as-is. opencode installs to
 `.zshrc` — so a dispatch from cron, an editor, or the coach can't find it
 otherwise, and playmaker would report the agent as unavailable.
 
+**claude** also accepts an effort level — Claude Code's `--effort
+low|medium|high|xhigh|max`, which trades speed for reasoning depth (the
+motivating case: running Opus review boards at `xhigh`). Set the lane default
+once with `effort = "xhigh"` under `[agents.claude]`; `playmaker dispatch
+claude --effort <level>` and `playmaker continue <id> --effort <level>`
+override it for one run without persisting anything. The flag is accepted and
+ignored on every other lane so scripts can pass it uniformly, and when it is
+unset everywhere no `--effort` flag is sent at all — Claude Code's own default
+applies.
+
 ## Notifications
 
 Every detached dispatch pings when it finishes. With
@@ -436,9 +446,13 @@ The `Weekly`, `Weekly · Fable` and `Sonnet` rows above are the point: they are
 **separate buckets**. So is the `Codex — Spark` block, every agy row, and the
 whole Z.ai block. Routing a subtask is choosing which of them to spend.
 
-- **Claude** — OAuth usage API; token from the Claude Code Keychain entry.
+- **Claude** — OAuth usage API; token from the Claude Code Keychain entry. When
+  it expires, Claude Code itself refreshes it; the quota probe never rotates the
+  shared refresh token.
   Model-scoped weekly buckets come from the usage API's `limits[]` array and
   print as `Weekly · <model>`.
+  `[quotas] claude_refresh_via_cli` defaults to `true`; set it to `false` to
+  report `login expired — run: claude auth login` without spawning `claude`.
 - **Codex** — ChatGPT `wham/usage` API; token from `~/.codex/auth.json`. The
   Spark model's own 5-hour and weekly windows come from
   `additional_rate_limits[]` and print as their own `Codex — Spark` block.

{playmaker_cli-0.13.0 → playmaker_cli-0.14.0}/README.md

@@ -348,6 +348,16 @@ A bare name is resolved on `PATH`; a path is used as-is. opencode installs to
 `.zshrc` — so a dispatch from cron, an editor, or the coach can't find it
 otherwise, and playmaker would report the agent as unavailable.
 
+**claude** also accepts an effort level — Claude Code's `--effort
+low|medium|high|xhigh|max`, which trades speed for reasoning depth (the
+motivating case: running Opus review boards at `xhigh`). Set the lane default
+once with `effort = "xhigh"` under `[agents.claude]`; `playmaker dispatch
+claude --effort <level>` and `playmaker continue <id> --effort <level>`
+override it for one run without persisting anything. The flag is accepted and
+ignored on every other lane so scripts can pass it uniformly, and when it is
+unset everywhere no `--effort` flag is sent at all — Claude Code's own default
+applies.
+
 ## Notifications
 
 Every detached dispatch pings when it finishes. With
@@ -409,9 +419,13 @@ The `Weekly`, `Weekly · Fable` and `Sonnet` rows above are the point: they are
 **separate buckets**. So is the `Codex — Spark` block, every agy row, and the
 whole Z.ai block. Routing a subtask is choosing which of them to spend.
 
-- **Claude** — OAuth usage API; token from the Claude Code Keychain entry.
+- **Claude** — OAuth usage API; token from the Claude Code Keychain entry. When
+  it expires, Claude Code itself refreshes it; the quota probe never rotates the
+  shared refresh token.
   Model-scoped weekly buckets come from the usage API's `limits[]` array and
   print as `Weekly · <model>`.
+  `[quotas] claude_refresh_via_cli` defaults to `true`; set it to `false` to
+  report `login expired — run: claude auth login` without spawning `claude`.
 - **Codex** — ChatGPT `wham/usage` API; token from `~/.codex/auth.json`. The
   Spark model's own 5-hour and weekly windows come from
   `additional_rate_limits[]` and print as their own `Codex — Spark` block.

{playmaker_cli-0.13.0 → playmaker_cli-0.14.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "playmaker-cli"
-version = "0.13.0"
+version = "0.14.0"
 description = "Playing-coach CLI for orchestrating Claude Code, Codex, Antigravity, Kimi Code, Muse Code and opencode sub-agents in parallel."
 readme = "README.md"
 requires-python = ">=3.11"

{playmaker_cli-0.13.0 → playmaker_cli-0.14.0}/skills/playmaker-coach/SKILL.md

@@ -1,14 +1,13 @@
 ---
 name: playmaker-coach
-description: Team-lead mode for coding work. Decompose the task into work packages, dispatch them to Claude/Codex/Antigravity(agy)/opencode/Kimi Code(kimi)/Muse Code(muse) workers through the `playmaker` CLI, then run an automatic multi-agent review board over every diff before it lands, and drive the fix cycles. Use for ANY request that will change code in more than one place, needs an independent review pass, or has two or more parts that can run at once — "implement", "add", "fix", "refactor", "wire up", "сделай", "почини", "добавь", "реализуй", "собери". NOT for answering a question, reading or explaining code, a single-line edit, or a git/ops command.
+description: Team-lead mode for coding work. Decompose the task into work packages, dispatch them to Claude/Codex/Antigravity(agy)/opencode workers through the `playmaker` CLI, then run an automatic multi-agent review board over every diff before it lands, and drive the fix cycles. Use for ANY request that will change code in more than one place, needs an independent review pass, or has two or more parts that can run at once — "implement", "add", "fix", "refactor", "wire up", "сделай", "почини", "добавь", "реализуй", "собери". NOT for answering a question, reading or explaining code, a single-line edit, or a git/ops command.
 ---
 
 # playmaker-coach — you are the tech lead, not the typist
 
-`playmaker` dispatches sub-tasks to Codex / Antigravity (`agy`) / opencode / Kimi Code (`kimi`) /
-Muse Code (`muse`) / a sibling Claude, tracks them, and returns their threads. This skill is the
-judgment on top: what to split, who gets which slice, how to size it so verifying is cheap, and
-**how the review board runs**.
+`playmaker` dispatches sub-tasks to Codex / Antigravity (`agy`) / opencode / a sibling Claude,
+tracks them, and returns their threads. This skill is the judgment on top: what to split,
+who gets which slice, how to size it so verifying is cheap, and **how the review board runs**.
 
 **The coach produces plans, prompts, verdicts and integration — not feature diffs.** Your context
 window is the most expensive resource on the table. Every file you read yourself and every line you
@@ -18,9 +17,9 @@ summarization, and even the drafting of worker prompts when the task is big enou
 Two loops run under your hand, always both:
 
 ```
-decompose → dispatch → prove on disk → REVIEW BOARD → adjudicate → continue → land
-                                            ↑______________________|
-                                                 max 2 cycles
+decompose → dispatch → prove on disk → REVIEW BOARD → adjudicate → continue
+                                            ↑______________________|   max 2 cycles
+all WPs green → integrate → GLOBAL GATE → SEAM REVIEW (≥2 interacting WPs) → land → ledger row
 ```
 
 ## 1. Activation gate
@@ -48,21 +47,29 @@ outside the skill so it survives `playmaker skill install --force`. Read, in thi
 later files override earlier ones:
 
 ```bash
-cat ./.playmaker/policy.md      2>/dev/null   # repo policy (gates, protected paths, conventions)
-cat ~/.playmaker/policy.md      2>/dev/null   # personal policy (quota economics, lane defaults)
+cat ~/.playmaker/policy.md      2>/dev/null   # personal policy (tiers, quota economics, lane defaults)
+cat ./.playmaker/policy.md      2>/dev/null   # repo policy (gates, protected paths, conventions) — wins
 ls  ./.playmaker/agents/*.md    2>/dev/null || ls ~/.playmaker/agents/*.md 2>/dev/null
 ```
 
-Agent profiles describe each lane's strengths, ceiling, and quota position — trust a profile over
-the generic defaults here. If no policy file exists, say so once in the plan and use these defaults.
+Agent profiles describe each lane's traps, mechanics and quota position — trust a profile over the
+generic defaults here, never over the policy's tier table or a dated owner order: profiles say how a
+lane behaves, policy says what it may be given. A newer dated order beats an older line anywhere. If no policy file exists, say so once in the plan and use these defaults.
 
 ## 3. Protocol
 
 ### 3.1 Recon — delegate it
 
-Codebase exploration is the highest-leverage thing to delegate: raw reading is exactly what the
-cheapest model does as well as you do. Before your own `grep`/`Read` sweep, dispatch a read-only
-recon with an explicit deliverable and `--sync`, and read a 200-word report instead of ten files:
+Codebase exploration is the highest-leverage thing to delegate. Two kinds, two tiers:
+
+- **Map recon** — locate files, symbols, call sites, line ranges, inventories. Raw reading: the
+  cheapest lane (Gemini Flash) does it as well as you do.
+- **Semantic recon** — invariants, ownership, contracts, side effects, impact radius, «why is it like
+  this». Judgment: a senior lane (Kimi K3 for many-file sweeps, Gemini Pro, Codex). A cheap model
+  returns a confident wrong map, and you plan on it.
+
+Before your own `grep`/`Read` sweep, dispatch the matching kind with an explicit deliverable and
+`--sync`, and read a 200-word report instead of ten files:
 
 ```bash
 playmaker dispatch agy --model <cheap-tier> --cwd "$(pwd)" --sync --read-only \
@@ -78,14 +85,17 @@ playmaker quotas               # capacity per MODEL, not per agent; re-probes it
 ```
 
 Read at model granularity: separate buckets inside one provider are separate capacity. The aim is
-**level-loading** — finish the week with every pool drawn down evenly, except the one reserved for
-the coach — not hoarding the pools other people also use. Details and per-provider quirks:
+**accepted work per point of scarce quota**, with prepaid capacity spent before it resets.
+Level-loading — every pool drawn down evenly by week's end, except the coach's own — is the
+tie-breaker between lanes that fit a WP equally, never a reason to queue a WP behind a closed lane. Details and per-provider quirks:
 `references/quotas.md`.
 
 ### 3.3 Decompose into work packages
 
-2–5 WPs on the first pass. A WP is dispatchable only when all five hold — this is what makes review
-cheap and re-prompting rare:
+2–5 WPs on the first pass. Name each WP's **class** first — `mechanical | feature | terminal-heavy |
+repo-recon | architecture | high-risk` — it decides which senior lanes are eligible (policy: fit before
+headroom), which lenses the board gets, and it is the first field of the ledger row. Then a WP is
+dispatchable only when all five hold — this is what makes review cheap and re-prompting rare:
 
 1. **Hard file boundary.** "Edit only `x.ts` and its spec" — never "do the backend part".
 2. **A gate the worker runs itself** — `tsc --noEmit`, a named spec file, a lint pass. It must exit 0
@@ -105,7 +115,7 @@ policy first, then `references/lanes.md`.
 
 ### 3.4 Propose, then wait
 
-Post the plan as: WP → lane+model → why → gate → done-condition, plus the reviewer pair per WP and
+Post the plan as: WP → class → lane+model → why → gate → done-condition, plus the reviewer pair per WP and
 the current per-model capacity. **Dispatch nothing until the user approves.** Approval may be
 partial ("go but reroute tests"); restate the modified plan in one line, then dispatch.
 
@@ -119,19 +129,27 @@ playmaker dispatch <agent> --model <name> --batch "$B" --cwd "$(pwd)" --prompt "
 Detached by default — that is the point; never `--sync` a whole fan-out. Always pass `--cwd`,
 `--batch` (one summary ping for the batch), and `--model` unless the profile says otherwise.
 Prompt shape: `references/prompt-templates.md`. Per-agent traps (agy scratch dir, opencode relative
-paths, codex model roster, kimi's K2.7 default and exit codes, muse's sandbox): `references/agent-gotchas.md`.
+paths, codex model roster): `references/agent-gotchas.md`.
 
 Parallel WPs that touch the same files go in **git worktrees**, one per WP, or they will collide.
 
+Within a minute of every detached dispatch, `playmaker get <id> --json`: a quota or auth refusal
+finishes in seconds as `failed`, pings nobody, and looks exactly like a slow worker. Give every
+dispatch a deadline (recon 15 minutes; a WP by its size) and on expiry check the process is alive
+(`playmaker logs <id>`, its RSS) before waiting longer. Never wait for a closed lane.
+
 ### 3.6 Prove it on disk before you believe it
 
 `done` means "the process exited cleanly with text", not "code changed". playmaker ≥0.9 marks a
 zero-change write task `no_changes` — treat it exactly as a failure. On older builds, check yourself:
 
 ```bash
-git -C "<cwd>" status --short        # empty tree on a write WP = NOT done
+git -C "<cwd>" status --short --untracked-files=all   # empty tree on a write WP = NOT done
 ```
 
+New files are invisible to `git diff`: `git add -N <new files>` before the board, and compare
+`git diff --stat` with what the worker claims it changed.
+
 Then run the WP's own gate yourself, once, cheaply. A WP that fails its gate never reaches the
 review board — it goes straight back to the worker.
 
@@ -157,10 +175,18 @@ Non-negotiables:
 - Every finding carries `file:line` + a concrete failure scenario. **No evidence → dropped.** You
   arbitrate, and a reviewer's confidence is an input, not a verdict.
 - Fixes go back via `playmaker continue <impl-id>` as a numbered list — the worker still has its
-  context. Re-review runs on the **delta only**.
+  context. Re-review runs on the **delta only** — which means passing the round-1 state as the
+  base-ref (a wip commit in the worktree, squashed before landing); with the original base the
+  patch is cumulative and reviewers re-open settled code.
+- A ruling that changes the scope goes into `spec.md` before the next round — reviewers refute
+  against the spec, and a stale spec produces false blockers. Before charging a finding to the
+  worker, check it is not already present on the base ref.
 - **Two cycles maximum.** Still blocking after two → stop and escalate to the user with both
   verdicts. A third round at the same lane is the most expensive way to use a cheap model.
 - Land only at **zero blocking findings**.
+- On `high`, the `risk` seat is told to **falsify** the acceptance criteria — a command, input or repro
+  per criterion it attacked, not only an argument; its `pass` lists what it tried. A seat that cannot
+  execute (the `claude` lane runs with binaries forbidden) never holds `correctness` — give it `contracts`.
 
 ### 3.8 Keep a board file
 
@@ -173,11 +199,39 @@ Long fan-outs outlive your context. Maintain `./.playmaker/board.md` — one row
 Update it at dispatch, at gate, after each review round. On resume, read the board before anything
 else. It is also what you paste back to the user as the status report.
 
+The columns are fixed — one layout, not one per board: a resumed session and the ledger both parse
+them. At landing, the ledger hook writes the WP's row to the cross-repo ledger on `git commit`; read its
+`[ledger]` line and correct the soft fields with `python3 ~/.playmaker/scripts/ledger.py fix wp=… k=v`.
+When the hook matched nothing, append the row by hand: `python3 ~/.playmaker/scripts/ledger.py add
+wp=… class=… impl_lane=… …` (fields: `~/.playmaker/policy.md`, «Ledger»). It keeps what board prose loses: class, first-gate pass, blocking findings that survived
+adjudication, cycles, wall time — the evidence the routing step reads.
+
 ### 3.9 Failures
 
-Surface them; never silently retry. A failed dispatch (missing binary, bad auth, rejected model)
-gets a re-routed plan proposed to the user, not a second attempt at the same string. Diagnosis per
-agent: `references/agent-gotchas.md`.
+Surface them; never silently retry — and never wait. A failed dispatch (missing binary, bad auth,
+rejected model, quota) is neither a fix cycle nor a worker failure: re-route the WP to the next live
+senior lane now, with the full context in a fresh prompt, and record the substitution in the board.
+Ask the user only when no eligible lane is left. Diagnosis per agent: `references/agent-gotchas.md`.
+
+### 3.10 Integrate before landing — when the fan-out had two or more WPs
+
+Two green WPs can be wrong together. Per-WP gates and boards prove the parts; nothing above proves the
+whole. Once every WP is green:
+
+```
+integrate on one tree (worktrees merged in dependency order)
+  → GLOBAL GATE — the repo's minimum bar plus the union of the WPs' own gates, run by you
+  → if ≥2 WPs touched interacting modules:
+      SEAM REVIEW — pm-review <batch>-seams <base-before-first-WP> --risk seams --impl-agent <main lane>
+  → commit, one WP per commit, in integration order → ledger rows
+```
+
+"Interacting" = shared types or packages, the same service or screen, a migration and its consumers,
+event or config names, shared state. The seam reviewer gets a spec that lists the seams and reads only
+those: changed interfaces, duplicated or conflicting assumptions, incompatible types, migration order,
+naming, config, shared state. The packages' internals already passed their own boards — re-reviewing
+them is the third round the protocol forbids. Roster: the `seams` block in `reviewers.conf`;
+`--impl-agent` is the lane that implemented most of the fan-out.
 
 ## 4. What the coach may still type by hand
 
@@ -210,3 +264,6 @@ editor on product code, ask whether that is a WP you failed to write.
 - **Dispatching a WP you cannot verify in one command and one paragraph.**
 - **Omitting `--model`** and letting a CLI default drain a top-tier bucket.
 - **Reading whole agent threads** when `summary` answers the question.
+- **Landing two green WPs without running the tree they make together.** Per-WP gates prove the
+  parts; the global gate and the seam review prove the whole.
+- **Routing by headroom alone.** Class first, then the ledger's floor, then the pool floors, then headroom.

{playmaker_cli-0.13.0 → playmaker_cli-0.14.0}/skills/playmaker-coach/references/agent-gotchas.md

@@ -65,39 +65,6 @@ line from `agy models` / `opencode models` rather than typing it.
 - Neither trap applies to **review** dispatches, which write nothing — which makes opencode a
   perfectly good reviewer even where it is a shaky implementer.
 
-## kimi (Kimi Code CLI)
-
-- There is **no read-only mode below the prompt**: `-p` refuses `--auto`, `--yolo` and `--plan`
-  (exit 1) and already runs with auto-approval. Only dispatch work you would run unattended anyway.
-- The session id arrives **only in the trailing `session.resume_hint` line**, so `playmaker list`
-  shows the agent session late — do not conclude a dispatch failed just because the id has not
-  appeared yet.
-- Sessions are **per-cwd**: `kimi session list` from another directory shows nothing. Track the
-  session through playmaker, not through the CLI.
-- The stream carries **no token/cost fields** — there is nothing to budget against mid-run.
-- Exit codes: **exit 1 is non-retryable** (auth, quota, unknown model — "is not configured in
-  config.toml"); **exit 75 is retryable**. Fix the cause on 1, re-dispatch on 75.
-- K3 is **slow on real tickets** — never `--sync` a big WP; dispatch detached and poll.
-- Needs **Node ≥ 22.19** — hence the wrapper binary; point `[agents.kimi] binary` at it.
-- **Always pass `-m kimi-code/k3-256k`** — the CLI default is the weaker K2.7 `kimi-for-coding`.
-
-## muse (Muse Code CLI)
-
-- The default run keeps Muse's **sandbox**: approval off, workspace trusted, writes inside the
-  repo fine — but writes **outside** it are denied, so `uv run pytest` fails initializing
-  `~/.cache/uv` (npm/pnpm caches alike). A WP whose gate needs those caches needs
-  `[agents.muse] yolo = true`.
-- **Without workspace trust Muse ignores the repo's AGENTS.md.** playmaker passes
-  `--trust-workspace` by default; `trust_workspace = false` drops it, and repo rules stop
-  applying.
-- Exit codes: **0** turn completed; **1** run failed (bad model, auth) — the reason is in the
-  terminal event and stderr's last line; **2** usage error; **130/143** SIGINT/SIGTERM.
-- **Resume only from the same cwd** — a `--session-id` elsewhere would need
-  `--allow-workspace-switch`, which playmaker never passes.
-- stderr **always** carries informational lines such as `muse: workspace root: …`, even on
-  success — they are not errors.
-- The stream has **no cost fields** — token usage exists only in the session log on disk.
-
 ## Worktrees
 
 Parallel WPs that touch the same files collide. Give each its own git worktree and dispatch with

playmaker_cli-0.14.0/skills/playmaker-coach/references/lanes.md

@@ -0,0 +1,117 @@
+> **Opus 5 lane — OUT of the review board (owner order 2026-09-08):** `playmaker dispatch claude -m opus` draws the Anthropic all-models weekly — the bucket the coach session falls back to (as Opus) when the Fable weekly runs out — and was eating it fast. It no longer holds the `high` risk seat by default (that was the 2026-09-02 order); `codex` does. Opus is weighted by the Fable weekly instead: while `Weekly · Fable` ≥ 50% it fills the risk seat on `high` boards that Codex implemented, ¼ of that at 25–50%, nothing below 25% or when the all-models weekly is under 50%. Never for implementation or recon, never on `normal`. Table and flip: `~/.playmaker/policy.md`, `~/.playmaker/reviewers.conf`.
+
+> **GEMINI ONLY on agy (owner order 2026-09-02):** never dispatch `claude-*` or `gpt-oss-*` models on the `agy` lane. Want a Claude? Don't dispatch one: the coach session is the Claude, and the Anthropic bucket is out of the board (2026-09-08). See `~/.playmaker/policy.md`.
+
+# Execution lanes — where work runs
+
+All Claude work — coach, in-session sub-agents, external `claude -p` — draws from the **same Claude
+subscription**. So routing is about *which bucket* you spend and *where the result lands*, not who
+pays. Four lanes:
+
+1. **Coach (this thread).** Interactive Claude Code on the top-tier weekly bucket — the scarcest,
+   hardest to replenish. Serial, and the most expensive in *context*. Reserve for orchestration,
+   architecture judgment, adjudication, final integration.
+
+2. **In-session sub-agents (the Task/Agent tool).** Run inside this session, write files (they
+   inherit the coach's permission mode), return straight into the coach's context, run in parallel.
+   Same subscription. Use when the coach folds the result in directly.
+
+3. **External dispatch — `playmaker dispatch claude`.** A tracked, detached stream you can monitor
+   and `continue` independently. Same subscription, and since September 2026 the same bucket: Sonnet has no
+   separate weekly (`seven_day_sonnet: null`), so this lane spends the coach's own all-models weekly.
+   Default `--model sonnet` (`haiku` for trivial mechanical work), and only when policy allows it. playmaker runs it in `acceptEdits`: it writes freely
+   inside `--cwd` and is refused outside it, so keep every path in the prompt inside `--cwd`.
+
+4. **External dispatch — `codex` / `agy` / `opencode`.** Each on its own subscription or plan — the
+   home for write-heavy parallel implementation that can leave the Anthropic subscription.
+   - **`agy` (Antigravity)** carries more than Google models: alongside Gemini Flash and Pro tiers it
+     serves **Claude Sonnet/Opus (Thinking)** and a GPT-OSS tier. Its Claude runs on *Google's* pool —
+     capable judgment that spends none of the Anthropic bucket, but a generation behind the
+     frontier: treat the whole lane as **middle** (see Model tiers below). Note the internal
+     split: all Gemini models share one bucket, Claude and GPT-OSS share another.
+   - **`opencode`** is the widest lane: one CLI over ~75 providers addressed as `provider/model` — a
+     GLM coding plan, or a model running locally on this machine, which spends no subscription quota
+     at all.
+
+**Never write an agy or opencode model name from memory** — run `agy models` / `opencode models` and
+copy a line. Both rosters and their spelling move with releases, and playmaker validates `--model`
+against the live roster, failing the dispatch on a stale name.
+
+## Routing cheat-sheet
+
+| The work… | Lane | Why |
+|---|---|---|
+| writes files, coach integrates the result directly | in-session sub-agent | write-capable, returns into context |
+| is an independent stream to monitor separately | `dispatch claude --model sonnet` | tracked, detached — but on the coach's own subscription (Sonnet has no separate bucket): policy says when, and it is rarely |
+| is heavy reasoning only the coach can do | coach | top tier, serial |
+| is write-heavy and can leave Claude | codex / agy / opencode | their own quotas |
+| wants Claude-flavoured judgment without spending the Anthropic bucket | `dispatch agy --model <claude-opus-thinking>` | middle tier — a generation behind; never the only senior eye |
+| is bulk work with every subscription low | `dispatch opencode --model <plan>/<model>` | a separate plan, untouched by the others |
+| is mechanical and privacy-sensitive, or all quotas spent | `dispatch opencode --model <local>/<model>` | runs on this machine, costs wall-clock only |
+
+## Model tiers — senior / middle / junior
+
+> **Superseded on this machine by the tier table in `~/.playmaker/policy.md` (owner order
+> 2026-09-04): there is no middle tier there, and `agy` Claude models are junior. The rows below are
+> the skill's generic defaults for a machine without a policy file.
+
+**Judge a lane by the model actually serving it, never by the lane's name.** Model rosters move
+faster than this file; re-derive the table whenever a lane surprises you, and correct it here.
+
+| Tier | What is actually there | Give it |
+|---|---|---|
+| **Senior** | the coach's own session (Fable 5.1, falling back to Opus 5.5); **`codex`** — the real Codex CLI on the ChatGPT plan (`--model` omitted; verify with `codex --version`); **`opencode` / GLM** (`zai-coding-plan/glm-*`) | architecture, spec interpretation, cross-module integration, adjudication, anything irreversible |
+| **Near-senior** | **`agy gemini-3.1-pro-high`** — not quite the three above, but close enough to carry a review lens or a hard WP on its own | the always-on review seat, demanding implementation, deep recon |
+| **Middle** | the rest of `agy` / Antigravity — its **Claude 4.6 / Sonnet 4.6** are a generation behind the frontier despite the name — plus GPT-OSS | well-specified implementation against a ready plan, refactors, CRUD by convention, a second opinion |
+| **Reserve** | `dispatch claude --model sonnet` / `--model opus` — Sonnet 5.5 and Opus 5.5, senior capability on the coach's own subscription | nothing by default: tier is capability, allocation is the policy's call — a seat only on the owner's word |
+| **Junior** | Gemini **Flash** tiers, Codex Spark | mass reading, codebase sweeps, mechanical diffs, tight fix→check loops |
+
+Two traps this table exists to prevent — both have bitten in practice:
+
+1. **A lane serving "Claude Opus" is not necessarily the current Opus.** Antigravity's Claude
+   models trail the frontier by a full generation. Cheap, capable, worth using — but *middle*,
+   not senior. Their verdicts are an input you weigh, not an authority you defer to.
+   Conversely, do **not** file GLM as cheap because it is cheap: it is a senior lane.
+2. **`codex` is the Codex CLI, not a Google model.** The lane name is not evidence of the engine.
+
+**On irreversible work** — deletions, migrations, money paths, auth, public contracts — a middle
+lane may never be the only senior-grade eye. Pair it with `codex`, or adjudicate that hunk yourself.
+
+Match the WP to the tier, then reserve the most-depleted senior model for the lightest role —
+usually the coach's own adjudication — and push volume down to junior lanes.
+
+## Junior fan-out — where it is safe
+
+Route down by default when **all** of these hold:
+
+1. **Self-verifiable outcome** — a green command the worker runs itself. An objective gate replaces
+   senior judgment.
+2. **Tight file boundary plus a pattern to mirror** — CRUD by existing convention, a test scaffolded
+   from a neighbouring spec, a story or doc from a template.
+3. **Low blast radius** — one WP, dark or flagged code, no schema or contract change; a bad diff is
+   cheap to throw away.
+4. **Read-only by nature** — recon, sweeps, summarization, fact-check tables. Zero risk beyond
+   wasted tokens.
+
+## Where juniors are never safe
+
+Regardless of how well specified — these stay with a senior lane or the coach:
+
+- **Money paths**: billing, entitlement ledgers, IAP/Stripe webhooks, refunds, idempotency.
+- **Schema migrations, backfills, destructive data operations.**
+- **Auth, session, and security-sensitive code.**
+- **Frozen public API contracts** and whatever the repo's policy marks human-review-required.
+- **Anything without a one-sentence done-condition.** Juniors do not resolve spec ambiguity, they
+  amplify it.
+
+A junior diff that touches this list is a routing bug: pull the WP back, do not patch it in review.
+
+## Escalation
+
+A worker that fails its own gate **twice** escalates one tier — never a third attempt at the same
+tier. Two failures at the top tier means the WP is wrong, not the worker: re-scope it.
+
+## Two-stage senior review
+
+Juniors produce the fact-check and consistency reports; seniors render verdicts *on top of those
+reports* rather than re-reading the world. This is the cheapest way to buy senior judgment.

playmaker_cli-0.14.0/skills/playmaker-coach/references/ledger.md

@@ -0,0 +1,77 @@
+# The ledger and its hook
+
+`~/.playmaker/ledger.jsonl` holds one JSON object per work package — the cross-repo evidence the
+routing step reads. `scripts/ledger.py` maintains it (`add` / `fix` / `escape` / `stats` / `tail`);
+it honours `PM_LEDGER` for tests. Rows whose note starts with "backfill" are historical — never
+rewrite them.
+
+## Fields
+
+`date`, `repo`, `wp`, `class`, `risk`, `impl_lane`, `impl_model`, `gate_first_pass`, `reviewers`
+(list), `blocking_r1`, `blocking_accepted`, `blocking_rejected`, `cycles`, `rounds`, `wall_min`,
+`quota_note`, `outcome`, `commit`, `note`, `escaped_from` (list). Unknown fields are `-`; ints are
+ints or `-`.
+
+## How the hook maps a review dir to a row
+
+On every `git commit` the PostToolUse hook (`scripts/ledger-hook.py`) matches the commit to the WP
+under `.playmaker/reviews/` whose `diff-r*.patch` file list overlaps the commit's files the most
+(ties → newest patch; dirs untouched for 14+ days are ignored), then fills:
+
+| Field | Source |
+|---|---|
+| `date`, `repo`, `wp`, `commit`, `outcome` | today, toplevel basename, review-dir name, short sha, `landed` |
+| `class`, `impl_lane`, `impl_model`, `risk` | spec.md header `class:` / `impl: <lane> <model>` / `risk:` (`routine|normal|high|seams`; see review-board.md); risk may also come from a pre-header spec title ("… risk high") or `board.env`; else `-` |
+| `reviewers` | union of lanes over `sessions.txt` and every archived `sessions.txt`, short form (`kimi-k3`, `glm-5.3`, `agy-gemini-pro`, `codex`, `muse`, `claude-opus`) |
+| `rounds` | number of `diff-r*.patch` |
+| `cycles` | number of `fix-r<N>.md` with N ≥ 1 |
+| `gate_first_pass` | `n` if `fix-r0.md` exists (the first gate did not pass), else `-` |
+| `blocking_r1` | blocking findings across round-1 verdicts (oldest archive when rounds > 1), deduped by `file:line` |
+| `blocking_accepted`, `blocking_rejected` | `-` (soft — the junior or the coach fills them) |
+| `wall_min` | minutes from spec.md mtime to the commit |
+| `note` | `auto-hook` plus the junior outcome |
+
+A commit that matches nothing gets a one-line hint (`ledger.py add wp=… class=… impl_lane=…`); a
+commit whose `(wp, commit)` row already exists is skipped. Every run is logged to
+`~/.playmaker/logs/ledger-hook.log`. The hook never blocks or fails the commit.
+
+## The junior
+
+A junior model fills the fields the mechanics left as `-`; it never blanks or overrides a set value.
+It runs as `codex exec -m gpt-5.3-codex-spark -s read-only -C <review dir> --skip-git-repo-check
+--output-last-message <tmp>` with a 60 s timeout, reading spec.md, all verdicts, the fix lists,
+board.env and the board.md line, and answering one JSON object. Configure it in
+`~/.playmaker/config.toml` (or turn it off with `"none"`):
+
+```toml
+[ledger]
+junior = "codex:gpt-5.3-codex-spark"
+```
+
+Any failure, timeout or non-JSON keeps the mechanical values; the reason lands in `note`.
+
+## Fixing a row
+
+```bash
+python3 ~/.playmaker/scripts/ledger.py fix wp=<wp> [repo=<r>] [commit=<sha>] k=v …
+```
+
+updates the LAST matching row in place, validated like `add`. When the hook matched nothing, append
+the row by hand with `ledger.py add`.
+
+## Registering the hook (the coach edits ~/.claude/settings.json)
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {"type": "command", "command": "python3 <installed skill dir>/scripts/ledger-hook.py", "timeout": 120}
+        ]
+      }
+    ]
+  }
+}
+```

{playmaker_cli-0.13.0 → playmaker_cli-0.14.0}/skills/playmaker-coach/references/prompt-templates.md

@@ -8,20 +8,25 @@ scope, gate, done-condition, context.
 ```
 <one sentence: what to build and why it exists>
 
+Working directory is <cwd>. Every path below is relative to it — never absolute, never a bare filename.
+
 SCOPE — edit ONLY these files:
   <path/a.ts>
   <path/b.spec.ts>
 Do not touch anything else. If the change appears to require another file, stop and say so in your
-final answer instead of editing it.
+final answer instead of editing it. Never commit. Never install or update dependencies — if the task
+seems to need one, stop and report.
 
 CONTEXT you need (do not go looking for more):
   - Mirror the pattern in <path/neighbour.ts>.
   - Convention: <naming / error handling / logging rule>.
   - Spec: <the two or three sentences that actually constrain this>.
 
-ACCEPTANCE — run this yourself and keep iterating until it exits 0:
+ACCEPTANCE — run this yourself and iterate until it exits 0, at most two failed attempts; after the
+second failure stop and report both attempts with their last output:
   <cmd, e.g. npx tsc --noEmit -p <tsconfig> && npx eslint <paths>>
-Paste the final output of that command into your answer.
+Paste the last ~30 lines of that command's output, its exit code, and the test and file counts it
+printed.
 
 DONE when: <one sentence the coach can confirm in seconds>.
 
@@ -31,6 +36,11 @@ prompt did not specify.
 
 ## Reviewer
 
+Generated by `scripts/review-board.sh` — do not hand-write it; the two versions used to drift
+(patch path, git rules, round wording). To seat a reviewer by hand — a substitute for a dead lane —
+copy `.playmaker/reviews/<wp>/prompt-<lane>-<lens>.md`, dispatch it `--read-only` on the new lane,
+and append `<id>|<lane>|<model>|<lens>` to `sessions.txt`. The shape, for reference:
+
 ```
 You are reviewing one work package. You did NOT write it. Your job is to REFUTE it, not to
 summarize it. Change nothing — this is a read-only review.
@@ -78,7 +88,8 @@ Reply with a one-line note per item saying what you changed.
 ## Recon (read-only)
 
 ```
-Recon only — change no files.
+Recon only — change no files. Working directory is <cwd>. One session: no sub-agents of your own.
+Report as your final message, write nothing to disk. Budget: 15 minutes.
 
 Find, in <dir>:
   (a) <thing>