--- name: session-management-rule description: "Standing rules for spawning and running sessions — the clobber incident, the phantom-session root cause, how the owner wants work reported, and the owner's delegated-judgment rulings on audits and the gate" metadata: node_type: memory type: feedback originSessionId: session-management-rule --- Owner rule (2026-06-29): **"you can create new sessions at will, just ensure tasks [don't] conflict with each other."** Also: **"you should be doing new sessions anyways"** — the owner prefers fresh sessions over piling everything onto one long one, because long sessions bloat and eventually hit "prompt too long". ## The one constraint: sessions must not conflict - **Serialize pushes** — never let two sessions push/commit to the same branch at once; coordinate so one lands before the next starts. - **No overlapping file edits** — partition by file/area, or run strictly one-at-a-time where they'd touch shared files. The repo is essentially **not safely parallelizable**; assume serial. **⚠️ CRITICAL — INCIDENT 2026-06-29 (this is why the rule exists).** The code sessions are NOT reliably worktree-isolated — they share the working tree. I spawned a *read-only* diagnosis session while a build session was MID-EDIT, and the diagnosis session's startup `git reset --hard` **silently wiped the build session's uncommitted edits.** The build session detected it and recovered, but it could have lost work. **LESSON: never run two repo sessions at the same time — not even a "read-only" one — because every session resets hard on startup and clobbers any other session's uncommitted work.** Run ONE repo session at a time. Wait for the current one to finish (idle + pushed) before starting or messaging another. The owner separately runs a dev server in another chat; coordinate so resets don't collide. (The governing protocol lives in `CLAUDE.md` + `rules/`.) **A consequence worth stating plainly:** because every session resets on startup, a unit's work MUST be pushed before rotating to the next session or it is wiped. Pushing at unit/session boundaries is therefore legitimate, not over-pushing. **To actually STOP a running session, use the real stop control** — a `send_message` only QUEUES behind the current turn, it does NOT halt it. (Owner caught me describing a queued message as "stopped" — [[always-acknowledge-actions]]: never claim a stop that didn't happen.) ## Phantom sessions — incidents, then the real root cause **⚠️ Incident 2026-06-29:** a spawn call that returned "timed out" had OFTEN created the session anyway, which then ran the prompt autonomously in the background. I assumed timeout = no session and re-routed the same unit → DUPLICATE phantom sessions all touching the branch concurrently. They mostly resolved without corruption, but that was luck. **⚠️ Refined 2026-07-01:** the phantom can appear with a DELAY — listing sessions immediately after a timeout may show NOTHING, then the phantom appears later. So after a spawn timeout: **WAIT (30–60s) and re-list before re-dispatching.** For a read-only session a duplicate is only wasted cost; for an EDIT session two concurrent editors is a clobber. There is no reliable stop for a running code session, so *preventing* dupes matters far more than cleaning them up. **⭐ ROOT CAUSE CLARIFIED (owner 2026-07-08) — the cause was ON ME.** The owner confirmed a new session per task is FINE (good for tokens and for visibility) — **"I'll accept requests whenever I can."** A spawn request sits unaccepted not because it failed, but because **the owner is busy and clicks Accept when he gets to it.** If I assume failure and start/reuse another session meanwhile, the owner later clicks Accept — not knowing I moved on — and the original ALSO spawns. That is the phantom. **RULE: after sending a spawn request, do NOT infer failure from slowness, and do NOT fall back to an old session. WAIT for the owner to accept — it could be a while. One request per task, then patience.** Only treat it as a real problem if the owner says he never got a request or explicitly declined. This supersedes the earlier "reuse idle sessions" instinct. **⚠️ SESSION VISIBILITY OVERRIDE (owner 2026-07-02: "do it in a new session" / "you still didn't start the next step").** The owner tracks progress via the desktop **Code tab**, where each session shows by TITLE. Reusing an old idle session (my token optimization) makes the work INVISIBLE to him — the session keeps its stale title, so he can't see that new work started and thinks nothing is happening. **Start each new unit in a NEW, clearly-titled session. Visibility and owner trust OUTWEIGH the token savings of reuse.** ## ⭐ OPERATING MODEL — a few specialists, not an autonomous swarm Owner asked (2026-07-08): specialized auditors vs a large autonomous agent team? **Verdict: NO large autonomous team.** Reasoning: the repo isn't safely parallelizable (shared working tree), it's a single coherent owner-vision that a swarm would drift from, and coordination overhead would buy the cost of parallelism with none of the benefit. The lean version already exists — Dispatch orchestrates; Opus plans/audits, Sonnet implements, Fable designs; the automated gate is the always-on auditor; the parked domain audits ARE the specialists, run as focused passes. Nothing new to set up. The one worthwhile upgrade: reusable **auditor prompt templates** in the Library, plus leaning on the available design skills as ready specialist auditors. ## ⚙️ AUTOMATIC MODEL OPTIMIZATION Owner 2026-07-02: *"you should optimize how you use the different AIs… automatically as per rules. fable 5 can be used anytime you decide, even before that chapter."* Standing practice, no need to ask: - **Fable** = creative/design/vision/immersive-writing/ideation (mockups, aesthetic exploration, creative audits, immersive copy) — usable ANYTIME I judge it helps. - **Opus** = deep reasoning, rigorous planning and audits, architecture, correctness/data-safety-critical work. - **Sonnet** = efficient implementation and routine changes. Still honor the plan → implement → audit flow (`CLAUDE.md` + `rules/`); just pick the model that fits each stage's nature. ## TOKEN-EFFICIENCY PRACTICES (adopted 2026-06-30, owner-approved — efficiency only, never less quality or fewer reports) 1. **⚠️ CORRECTED (owner 2026-07-08 — the old wording caused a real regression that STALLED PROGRESS).** The old rule said "stop polling, rely on the completion report" — but there is NO async completion trigger; polling is the only way to learn a session finished. So "rely on completion" was self-defeating: I stopped polling → never noticed completions → went silent → waited for the owner to "yo" me → the next unit never got dispatched → the pipeline stalled. **THE HARD REQUIREMENT WINS: after dispatching, HOLD AND POLL to completion, then IMMEDIATELY report AND dispatch the next queued unit — without the owner having to prompt.** The token concern is real but narrow: avoid *wasteful over-polling* by using BOUNDED reads (small limits; don't re-pull a whole growing transcript) — NOT by refusing to poll. **NEVER end a turn with "I'll report when it lands" and then stop — that is the exact failure.** 2. **Rotate build sessions every 1–3 units (a "chapter"), not by turn count.** Per-turn cost grows roughly quadratically with session length; the late turns of a marathon session are the most expensive tokens in a build, and they hit "prompt too long". A fresh session re-pays only a bounded reload. Hand off with a compact brief (acceptance criteria + the prior unit's final report). 3. **Single-flight on spawns** — never double-dispatch on a timeout (see the phantom root cause above). 4. **Trim dispatch prompts and reports** of redundant context restatement. Keep FULL notify-on-everything to the owner — that is non-negotiable; cut only orchestration-side bloat. 5. **One fetch/reset per session; don't re-read files already in context; bound large command output** (tail/summary, fetch detail only on failure). **Why:** the owner wants sessions managed proactively and kept from clobbering each other, AND token usage kept down. Efficiency only — never cut the gate's guarantees, coverage, thinking depth, or the owner's reports. ## ⚠️ HARD FEEDBACK — DO NOT CUT SESSIONS SHORT (owner 2026-06-30, a REPEATED pain point) Owner: **"why do you keep cutting the code sessions off telling it to stop when it's not completed what it has going on? just ruining the ideas fr."** I misread a THOROUGH session (parallel grounding subagents, mid-consolidation, high turn count) as a stuck loop and sent it stop/wrap-up messages — degrading exactly the analysis quality the owner wants. Same mistake as: **"why you rushing yourself? I told you take your time with the token audit."** **LESSON: "keep moving" = orchestration hygiene (don't idle-poll, report promptly, rotate sessions between UNITS). It does NOT mean rushing or interrupting a session mid-task.** A high turn count or a long research phase is NOT a stall — deep grounding is the point. Let sessions run to their own natural completion; intervene only if genuinely erroring, off-scope, or the owner asks. When in doubt, WAIT. Never tell an analysis/build session to "stop researching and just write it." **Depth > speed on the actual work, always.** ## 🧭 GUIDE MODE — how the owner wants to be led Owner 2026-07-03: **"there is so many plans I don't know where to start… I want you to help guide me through all of this until implementation is actually ready and well thought out / proven."** The owner is overwhelmed by the number of plans and wants ME to carry the organizing burden and surface **ONE clear next step at a time**. Present the single next decision, not the whole pile. The design-phase flow he signed off on, as a durable pattern: **nothing ships until a design is PROVEN and owner-signed-off** — plan → Fable designs a VERTICAL SLICE as a mockup → owner approves/tweaks → build and prove that one instance → replicate the proven pattern to the rest. Gameplay ideation may run in parallel and is not a gate on design work. Related standing rule: when a redesign touches muscle memory, **LEAD WITH A MOCKUP** for owner approval before implementing (owner: *"mockups make sense... if that's what would be better, yes"*). ## STANDING BUILD RULES (owner) - **EVERY dev ship MUST include HOW TO TEST IT** (owner directive 2026-07-02: *"everytime something ships live on dev, you need to tell me how to test it. make sure that's in rules"*). No exceptions — explicit, step-by-step, mobile-readable test instructions in the report. For a VISIBLE change: the exact taps to see it. For an INVISIBLE/foundational change: say so plainly and give the "nothing should change — verify it still works" check. - **Update the owner frequently** (owner: *"ensure you update me whenever possible just like you just now did"*) — per-unit progress notes, plain and short. - **PROPORTIONATE audits — judgment delegated to me** (owner 2026-07-01: *"if you don't feel something needs audited or the audit can be held off on, do whatever you recommend"*). The full gate runs regardless — that's the always-on net. The extra deep audit pass is reserved for genuinely HIGH-RISK / foundational units: boot/lifecycle, anything touching state/saves/data-migration, the event bus, the record store, the AI contract — the black-screen/data-loss class. For LOW-RISK units (golden-master-verified pure refactors, test-only, docs/hygiene, small well-tested connectors) skip or batch the separate audit. - **PROPORTIONATE GATE — owner authorized 2026-07-02:** *"skip the gate whenever you feel it's not necessary as long as the gate will be tested/improved before release … same effectiveness while speeding up."* Policy: the FAST gate (test runners + lint + format + parity) stays the default on every commit — it's cheap and it's the core correctness net; broken code cascades into the next session. The SLOW browser checks MAY be skipped on units that don't affect UI/boot/render, but MUST run for UI/boot/render-affecting units, at chapter boundaries, and **ALWAYS before any release**, which restores the full guarantee for the shipped state. **NEVER skip the gate on data-safety / high-risk units.** This explicit authorization is what satisfies the standing "never bypass the pre-push gate unless the owner authorizes" rule — and ONLY under these conditions. - **Dev/staging is where in-progress atmosphere features get tested.** The developer/debug console is staging-only — never shown to prod players — and grows a trigger per feature as each lands, so ambient features are actually testable before release. (Its scheduling lives in `QUEUE.md`.) *Correction 2026-07-20: version pins, branch/round state, protocol numbers and roadmap sequencing were stripped from this file — they belong to `QUEUE.md` (roadmap), `CLAUDE.md` + `rules/` (protocols), `CHANGELOG.md` + git log (what shipped) and `APP_VERSION` in source. Only the reasoning, incidents and owner rulings are kept here.*