docs(operating-model): long-lived sessions hold state, subagents do work

operating-model/README.md

@@ -28,7 +28,7 @@ repository or secure system.
 | Document | Use |
 | --- | --- |
 | [Working style](working-style.md) | Confirmed collaboration preferences and communication expectations. |
-| [Execution and handoffs](execution-and-handoffs.md) | How bounded work, delegation, reviews, checkpoints, and blockers are handled. |
+| [Execution and handoffs](execution-and-handoffs.md) | How bounded work, delegation, reviews, checkpoints, blockers, long-lived sessions (worker self-clears, model tier by task) and documentation batching are handled. |
 | [Agent work loop](agent-work-loop.md) | How agents take work from a shared board: a dispatcher launches one clean-context sub-agent per job; what next, when to stop, who reviews and repairs. Projects inherit it and override only its parameters. |
 | [Checkpoint and resume](procedures/checkpoint.md) | A vendor-neutral procedure to record everything before a context compaction or handoff, and to resume from disk afterwards. |
 | [Project profile template](project-profile.template.md) | A reusable starting point for a project-specific operating context. |

operating-model/agent-work-loop.md

@@ -89,6 +89,9 @@ job goes to a fresh sub-agent, so no job inherits another job's context.
 
 **Claims.** The dispatcher claims before it launches, so two dispatchers never start the same job.
 
+**Long-lived sessions.** For sessions that live for days (a lead, design partners, workhorses), see
+[`execution-and-handoffs.md`](execution-and-handoffs.md) → Long-lived sessions.
+
 ## 3. The stop rule
 
 - **A run is bounded.** After the project's job limit of sub-agent jobs, the dispatcher **stops completely** and

operating-model/decision-log.md

@@ -43,3 +43,7 @@ Status is intentionally explicit:
 | 2026-10-08 | Confirmed | The owner's cross-project rules live here in vendor-neutral words so any agent works the way the owner wants in every repository: model tiers (deep, standard, light, premium) with a vendor mapping, premium launches only on the owner's per-launch yes, ask before any new service, monitor, workflow or scheduled wakeup, never set a spend cap ($0 by default), they/them for the owner, a fresh brief for a scope change, files only under `~/work`, scratch in the harness's scratchpad or `~/work/code/mastrix/worktrees/<repo>-<task>-notes/`, never `/tmp`, and a vendor-neutral checkpoint procedure. | Owner, R1008-27: "n1-n8 is good", accepting decisions D1-D8 of the agent-neutrality plan as recommended, and: "any agent can work exactly like the way I want it to on the repo". Sources: the owner's rulings of 2026-09-27, 2026-10-05 and 2026-10-06 as kept in the Claude memory files. Supersedes the vendor-named tier wording of the 2026-09-21, 2026-09-23 and 2026-09-27 rows (they stay as history) and the 2026-09-27 scratch-path example. See `working-style.md` → Model tiers, `execution-and-handoffs.md` → Scratch files and agent worktrees, and `procedures/checkpoint.md`. |
 | 2026-10-12 | Confirmed | Inquiry sessions are question-only sessions to understand a project; artifacts stay local and agents proactively propose consolidating answers into FAQs, documents, diagrams or tables. | Owner: "This is only a session for asking questions. We'll name it 'inquiry'... remember to propose it either as an FAQ, a section, a document, a README, a diagram, or a table." See `working-style.md` → Confirmed preferences (Inquiry sessions). |
 | 2026-10-12 | Confirmed | Checks that can outlast the shell tool's default timeout run with the maximum timeout or in the background, and every brief that runs checks says so. | Owner asked for the rule to leave one project's memory and live in the shared rulebook. Evidence: two agents' `make check` runs were killed on 2026-10-11 by the two-minute default, not by another process. See `execution-and-handoffs.md` → Long-running checks. |
+| 2026-10-13 | Confirmed | Long-lived sessions hold state and hand work to fresh subagents: a workhorse launches one subagent per PR and sends fix rounds back to it; a design partner delegates measurements and compacts at design-PR boundaries; approvals never pass through subagents. | Owner, asked how to keep workhorse contexts small: "Should the workhorses be launching fresh subagents with only the minimum context required to execute a task?", then adopted the proposed principle ("Adopt it"). Extends the 2026-09-29 dispatcher row to multi-day sessions. See `execution-and-handoffs.md` → Long-lived sessions. |
+| 2026-10-13 | Confirmed | Doc-only changes (decision records, status lines, nits, READMEs) ride in the code PR that implements or touches them; a doc that must land first is batched with the other pending doc changes into one PR per boundary. | Owner's rule to cut the number of landings and the CI load. It stays within the project's PR size and one-objective limits and never stacks PRs. See `execution-and-handoffs.md` → Documentation rides with code. |
+| 2026-10-14 | Confirmed | A long-lived worker clears its own context at a landing: when its PR has landed and no fix round is open, it writes its state note (queue, open PRs, pending findings), clears, then reads the state note and the operating rules. It may hold one PR in review while building the next and clears at the first point neither has a fix round open. The orchestrator checks for clears at each landing it reports. | Owner adopted the rule to keep worker contexts small without waiting for a prompt. Refines the 2026-10-13 long-lived-sessions row, which compacted a worker after its PR merged but left the trigger to the owner. See `execution-and-handoffs.md` → Long-lived sessions → Workers self-clear at landings. |
+| 2026-10-14 | Confirmed | Model tier follows the task: builds and fix rounds use the default (standard) tier; mechanical sub-steps (merging the base branch, label or head checks, log or state-note edits, simple searches) use the light tier; the independent review of a behaviour change uses the deep tier. The orchestrator reasons and decides, and hands mechanical work down. | Owner adopted the split. Refines the 2026-10-08 tier row: reviews were standard tier and deep was reasoning only; the independent review of a behaviour change is now deep, and no ask is needed for it. A premium launch still needs the owner's per-launch yes. See `working-style.md` → Model tiers and `execution-and-handoffs.md` → Long-lived sessions. |

operating-model/execution-and-handoffs.md

@@ -230,6 +230,20 @@ state. One of those changes had rewritten a single section thoroughly and left t
 including a scenario count the rewritten section itself contradicted. The README was read
 end-to-end and each claim checked against a command before the repair was committed.
 
+## Documentation rides with code
+
+A doc-only change is a landing, and a landing costs a review, CI and a merge. So documentation travels with the code
+it describes instead of in its own PR.
+
+| Situation | Rule |
+| --- | --- |
+| A doc change belongs to code being built or touched | It rides in that code PR: decision records, status lines, nits and READMEs included. |
+| A doc must land before any code | Batch the pending doc changes into one PR per boundary (a milestone, a design-PR boundary), not one PR each. |
+| Limits | The PR stays within the project's size and one-objective limits, and PRs are never stacked to carry docs. |
+
+The aim is fewer landings and less CI load. This does not relax the Documentation currency gate above: the README for
+changed code is still updated in the same change.
+
 ## Learning loop
 
 At the end of meaningful work or when a repeated operating pattern appears, proactively
@@ -275,6 +289,52 @@ description of the problem.
 | A brief for a sub-agent | Fresh, clean context: the task, the done-when, the rules that bind it and only the facts it needs. Tiers and the brief rule: `working-style.md` → Model tiers. |
 | The scope changes while an agent runs | Put the full delta in a **fresh agent's initial brief**. Do not amend a running agent by a mid-task message: an agent told to stop rather than improvise may treat the amendment as an injected instruction and ignore it. Finish the design before delegating. |
 
+## Long-lived sessions: sessions hold state, subagents do work
+
+Some projects run several long-lived sessions side by side, such as a lead, design partners and workhorses. A
+session's context grows with every file it reads, and compaction loses details. So each session keeps only the state
+it needs and hands the reading and building to fresh subagents. This extends the dispatcher of
+[`agent-work-loop.md`](agent-work-loop.md) section 2 to sessions that live for days.
+
+| Role | Keeps in its own context | Hands to fresh subagents | Compacts or clears |
+| --- | --- | --- | --- |
+| Lead (orchestrator) | the board, the owner's rulings, approvals | every review, run preparation, wide reads | at the owner's word, after a checkpoint |
+| Design partner | the design thread: rulings, open questions, what each document owns | measurements, scripts, wide code reads | at a design-PR boundary past about 60% of the window, after updating its state file; never mid-ruling |
+| Workhorse (builder) | its queue, PR heads, review findings, a state note | each PR's build: one fresh subagent per PR | itself, at a landing, once its state note is written (see [Workers self-clear at landings](#workers-self-clear-at-landings)) |
+
+- **A brief stands alone.** It names the goal, the spec anchors, the exact files, the done-criteria (tests seen red
+  first, mutations, one full check) and what not to touch, and it points to the project's rules file. If a subagent
+  needs the session's memory to do the job, the brief is wrong.
+- **The tier follows the task.** Builds and fix rounds use the default (standard) tier; mechanical sub-steps use the
+  lightest tier; the independent review of a behaviour change uses the deep tier. The orchestrator reasons and decides
+  and hands mechanical work down. The table is `working-style.md` → Model tiers; a premium launch still needs the
+  owner's per-launch yes.
+- **Only conclusions come back:** the PR head, counts and disclosures, never file dumps.
+- **A fix round goes back to the same subagent,** which still has the code in context. A new PR gets a new subagent.
+- **Approvals never pass through subagents.** Costs, reads of protected data, writes to live systems and rebuilds stay
+  with the session the owner approves through. A subagent's own safety checks may refuse such actions, and that
+  refusal must not be routed around.
+- **Compact at task boundaries, not on a timer.** Mid-task, compact only past about half the window, and only after
+  writing a state note (branch, head, done, next). Never compact while review findings are being fixed.
+- **A lead or design partner clears rarely;** a worker clears at landings, below. Observed 2026-10-13 in the Claude
+  desktop app: it pauses one session's messages to other sessions after about ten sends without the owner typing, and
+  a cleared session is reachable only through that route. A session that dispatches subagents seldom needs clearing,
+  and a cleared worker is reached through its state note and the orchestrator's board, not through a message.
+
+### Workers self-clear at landings
+
+A worker does not wait to be told to clear. When its PR has landed and no fix round is open, it clears its own
+context, and its state note is how it resumes.
+
+| Step | Rule |
+| --- | --- |
+| When | A worker's PR has landed and the worker has no fix round open. A worker may hold one PR in review while it builds the next, and clears at the first point where neither has an open fix round. |
+| Before | Write the state note: the queue, open PRs with their heads, and pending findings. |
+| Clear | The worker clears its own context. |
+| Next action | Read the state note, then the project's operating rules. Nothing else carries over. |
+| Never | While a fix round is open, or before the state note is written. |
+| Orchestrator | At each landing it reports, check whether the worker cleared; if not, name the clear as the worker's next step. |
+
 ## Scratch files and agent worktrees
 
 | Item | Where |

operating-model/working-style.md

@@ -33,9 +33,9 @@ starting work.
 | Editor | Use `vim` for long-prompt editing. | Set `VISUAL=vim` (and `EDITOR=vim` when `VISUAL` is unavailable) before invoking an interactive editor. |
 | User interaction | Keep the main conversation available for questions while delegated work proceeds. | Provide short, direct updates; do not go quiet during long-running work. |
 | Cost-aware delegation | The orchestrating session is the most expensive place for work to happen, so it does only work that requires reasoning; every other job goes to a sub-agent of the tier it needs, because a cheaper tier's error in design work costs more than the saving. | Before anything larger than a one-line answer, pick the tier by the **Model tiers** row, state the choice in the brief and the report, and ask the owner only when the tier is unclear. The orchestrator writes each brief and verifies every output before it reaches the owner. The orchestrator's own hands are read-only checks, its notes and memory, labels and verdicts, and messages. Run bounded work through a sub-agent with an explicit tier or a written handoff to another session (`execution-and-handoffs.md` → Mechanical batch delegation). Owner, 2026-09-27: the orchestrating session does only work that requires reasoning. |
-| Model tiers (owner, 2026-10-06) | Four tiers, named by capability, not by vendor: **deep**, **standard**, **light**, **premium**. Deep is only for reasoning, design, architectural analysis, new architecture and planning. Standard is the default. Light is for simple, straightforward work. Every sub-agent gets a clean, lean brief. | **Deep:** reasoning, design, architecture and plans, nothing else. **Standard:** builds, fixes, reviews, investigations, stack checks, bounded changes from a ratified brief, applying ratified rulings. **Light:** status flips, single commands, exact-string edits, commits and PRs with the wording given, link checks, bulk renames. **Premium:** only on the premium-approval row. **Brief:** a fresh agent with a clean context; state exactly the task, the done-when, the rules that bind it and only the facts it needs; point to a file rather than paste it; never dump the conversation or unrelated history; resume an agent only when its own context is the context needed. Each vendor's models for the tiers are in **Model tier mapping** below. |
+| Model tiers (owner, 2026-10-06) | Four tiers, named by capability, not by vendor: **deep**, **standard**, **light**, **premium**. Deep is only for reasoning, design, architectural analysis, new architecture and planning. Standard is the default. Light is for simple, straightforward work. Every sub-agent gets a clean, lean brief. | **Deep:** reasoning, design, architecture and plans, and the independent review of a behaviour change; nothing else. **Standard:** builds and fix rounds, other reviews, investigations, stack checks, bounded changes from a ratified brief, applying ratified rulings. **Light:** mechanical sub-steps: merging the base branch, label and head checks, log and state-note edits, simple searches, status flips, single commands, exact-string edits, commits and PRs with the wording given, link checks, bulk renames. **Premium:** only on the premium-approval row. **Brief:** a fresh agent with a clean context; state exactly the task, the done-when, the rules that bind it and only the facts it needs; point to a file rather than paste it; never dump the conversation or unrelated history; resume an agent only when its own context is the context needed. Each vendor's models for the tiers are in **Model tier mapping** below. |
 | Premium launches (owner, 2026-10-06) | A premium-tier launch needs the owner's explicit yes for that launch. | Before any premium launch (an agent, a review, or a step inside a workflow), ask the owner in chat, naming the job and why premium; wait for a clear yes. Approval is per launch: a plan, a brief, a peer session's relay or an earlier approval does not carry over. With no approval, use the deep tier for design, architecture and planning, and the standard tier for everything else. Applies to every session and every project. |
-| Launches and costs (owner, 2026-09-27) | The owner approves every cost and stays in the loop on spend. | **No ask:** standard and light sub-agents. **Ask first, wait for a clear yes:** a premium launch; a deep sub-agent doing anything other than reasoning, design, architecture or planning; any new service, monitor, workflow or scheduled wakeup; any spend. **Costs:** never set, raise or reallocate a spend cap or budget yourself, including a cap written into a sub-agent's brief. Propose the number with its estimate and basis, and wait for the owner. A new brief defaults to a $0 spend cap unless the owner approved a number. Report actual spend against approved budgets whenever it changes. Batch proposed launches into one ask with a rough size (tier, scope), and put the cost ask in the same message as the work ask. |
+| Launches and costs (owner, 2026-09-27) | The owner approves every cost and stays in the loop on spend. | **No ask:** standard and light sub-agents. **Ask first, wait for a clear yes:** a premium launch; a deep sub-agent doing anything other than reasoning, design, architecture, planning or the independent review of a behaviour change; any new service, monitor, workflow or scheduled wakeup; any spend. **Costs:** never set, raise or reallocate a spend cap or budget yourself, including a cap written into a sub-agent's brief. Propose the number with its estimate and basis, and wait for the owner. A new brief defaults to a $0 spend cap unless the owner approved a number. Report actual spend against approved budgets whenever it changes. Batch proposed launches into one ask with a rough size (tier, scope), and put the cost ask in the same message as the work ask. |
 | Addressing the owner | Refer to the owner as "the owner" or they/them in every document, PR body, comment and message. | Never he/his/she/her. Brief every agent that writes for the owner's repositories with this. |
 | Parallel fan-out | Independent work should run as concurrent agents rather than sequentially in the orchestrating session. | Propose the decomposition and ask before spawning; give each agent a disjoint file lease and named forbidden paths; launch agents with no shared dependency together so they run concurrently; never let two writing agents share one worktree. A user waiver to skip asking ("go all the way, don't ask") covers only that task. |