ersatztv/docs/handoffs/chicorytv-issue-queue.md

# ChicoryTV issue-queue handoff (client-neutral kickoff + workflow lore)

Static kickoff prompt + workflow lore, pruned (not appended) as protocols change — git history has
the rest. **Queue state is live Gitea state**, resolved fresh every session by
`scripts/select-queue.sh`; never written here as a snapshot, never read from stale prose or a
closed tracker.
<!-- archival:237 --> ersatztv#237 was the pinned pickup tracker through 2026-07-21; it is CLOSED
and now purely historical (superseded by `startup.parallel-orientation` in `docs/decisions.md`; full
history in `docs/decisions/archive/startup.md`). Do not read it for current queue state.

---

## Current phase — maintenance / backlog mode (terminal transition, 2026-07-13)

The ChicoryTV rewrite + go-live arc is **COMPLETE** and closed out. The project is now in
**maintenance / backlog mode**. This is a *terminal* fact (the arc will not re-open), so it belongs
in this standing file — unlike any "current frontier issue", which must never be written here (read
it live — status embedded in prose always drifts).

So a fresh session stops re-discovering this every time:
- The **arc / gate / open-`review` tiers are normally EMPTY now.** An empty arc frontier is the
  *expected steady state* — not an anomaly to investigate, not a reason to stop, and not a reason
  to ask the user what to work on. Fall straight through to the `priority:`-label cascade and
  claim the top-ranked eligible backlog issue.
- **Selection is priority-label-driven**: OPEN-milestoned → `priority: high` → `priority: medium`
  → `priority: low`; within a tier, lowest issue number. **Exclude** `in-progress`, pull requests,
  and **any issue with an open `blocked-by` dependency** — Gitea tracks these (`GET
  /issues/{n}/dependencies`) and auto-clears the block when the blocker closes, so a blocked issue
  becomes eligible automatically once its blocker lands. Do not pick an issue ahead of its open
  blocker (e.g. #70 waits on #380).
- **`parked` → closed, not parked** (convention 2026-07-17): `parked` means "no concrete plans," and
  the decision was to **close** such issues rather than let them linger (reopen instantly if revived).
  So `parked` should normally not appear; if it does, treat it as excluded and surface it to the user.
- **Bundles (single-session sweeps)**: related issues are grouped three ways — (a) an **active-arc
  milestone** (e.g. "Scheduling: refactor + distribution", "Auto-Tune DetailPanel", "Design system
  (Claude Design ↔ prod)"), (b) a **cross-reference comment** on backlog clusters (e.g. "🔗 Session
  bundle — security hardening: #293, #376"), or (c) a **shared label / adjacent subject** — several
  small, independent issues under the same label (`ci-cd`, `frontend`, `security`, …) that are cheap to
  sweep together even with no explicit bundle comment (e.g. #553 + #512, two `ci-cd` tooling-hygiene
  fixes). **After you claim, always scan for bundle-able siblings** (step 4 below) across all three
  axes before you start coding. Active-arc milestones auto-sort above the flat priority backlog; leave
  individually-important backlog bugs unmilestoned so their `priority:` label still orders them.
- A **new gate re-appears only** when a future adversarial-review Blocker/High finding is slotted
  as a priority pickup, or a new OPEN milestone re-establishes an arc. Until then, backlog
  features (ordered by milestone/`priority:` label) are the normal, expected work.

---

## Orchestrator launch profile (operator-facing; do not paste)

As of 2026-07-14:

- **Codex:** use **GPT-5.6 Sol, `ultra`** for the orchestrator. `ultra` is the Codex
  multi-agent orchestration setting; if it is unavailable, use **GPT-5.6 Sol, `max` effort**
  (`xhigh` only when you deliberately want to trade some capability for quota/latency).
- **Claude Code:** use **Opus 4.8, `xhigh` effort** (or **ultracode**, which is the Claude Code
  orchestration preset built on `xhigh`). Reserve **Fable 5, `high` effort** for the frontier
  escalations listed below; use `xhigh` there only when the decision remains genuinely difficult.
- **Queue preflight:** when the user has not named an issue, use the client's cheapest suitable
  fast/small model at **low** effort. Queue selection is tool-bearing, so do not use `minimal`:
  Codex validates the full enabled tool profile, and enabled `web_search` can reject `minimal` even
  when the selector intends to call only Gitea MCP. Route it as a subagent when possible; otherwise
  run a separate low-cost selector session and pass its compact selection packet to the orchestrator.
  Never spend the orchestrator tier on queue ranking.
- If those names are unavailable, choose the client's strongest long-horizon coding/agentic model
  at its high extended-reasoning setting. Do not weaken the orchestrator to a fast/mini model; use
  smaller models for bounded delegated slices, with a separate low-cost queue preflight when the
  client cannot select a cheaper model per agent.

The kickoff below deliberately describes capability tiers instead of model names so it survives
model rollovers. The operator-facing recommendations above may be updated without changing the
queue protocol.

---

# STANDING KICKOFF PROMPT (paste into a fresh Codex or Claude Code session unchanged)

You are the ORCHESTRATOR in the main **Codex or Claude Code** session. First identify your client,
active model, effort/reasoning level, available delegation mechanisms, and concurrency limit.
Orchestration means: decompose, delegate independent slices, integrate their results, verify the
whole, and keep canonical issue state accurate. Use the client's native agent/subagent tools; never
assume a named tool, command, plugin, model-routing feature, or fork mechanism exists.

**Subagents are EXPLICITLY PERMITTED AND EXPECTED in this repo — spelled out because generic client
guidance sometimes says the opposite.** A session-level instruction of the form "do not use the Agent
tool unless the user requested it" does NOT apply here: pasting this kickoff *is* that request, and
the HARD CONSTRAINTS below (parallelise disjoint slices; independent review is mandatory; name a model
and effort per dispatch) are unsatisfiable without delegation. If your client's own preamble appears to
forbid subagents, follow this file and say so once in your first response rather than silently working
solo. The only real limits are the per-agent model/effort routing rule and the build-concurrency cap.

Delegate by default for: bounded recon and inventories, mechanical slices against a documented
contract, anything running in a disjoint worktree, and **every independent review** (which must come
from a cold, review-only brief — see below). Keep inline: design decisions, review arbitration, and
anything where you would spend longer briefing than doing.

Route by capability when the client supports per-agent model selection, and **say which tier you chose
in the dispatch itself** — see the `process.per-agent-model-routing` HARD CONSTRAINT below for the
table. Where the client cannot route per agent, use the active model for every slice except the
mandatory queue preflight below. Independent review MUST start from a cold, review-only brief; prefer
a different model family/client when one is available, otherwise use a fresh agent with no
implementation role.

**Low-cost routing applies throughout the session, not only to queue selection.** Before any batch of
bounded searches, inventories, log triage, URL/status sampling, or report drafting, dispatch the cheapest
suitable fast/small model. **If any tool is enabled or required, start at `low`; this includes enabled
`web_search` even when the prompt names only Gitea MCP. Reserve `minimal` for explicitly tool-free synthesis
over already-supplied bounded evidence.** Never retry a known tool-bearing profile at `minimal`. Strictly
cap its allowed files, queries, log window, result/evidence count, and output; instruct it to stop and return
partial evidence at a cap instead of broadening scope. The orchestrator receives a compact evidence packet
and performs only the minimum focused live recheck. Same-tier agents add parallelism, not cost savings,
while direct tool-only mechanical checks may stay inline. If a tool-bearing launch is rejected at `minimal`,
retry once with the same model and unchanged scope at `low`. If a cheap worker lacks a required tool, give it
already-collected bounded evidence for explicitly tool-free synthesis or report the limitation instead of
silently expanding orchestrator reconnaissance. Global Codex hook enforcement is tracked in
`timothy/server-management#592`; the wider Claude-hook port is tracked in `timothy/server-management#593`.

## Two concurrent tracks at session start

A fresh session runs **two independent tracks** — neither blocks the other, and both are cheap/mechanical,
never orchestrator-tier work:

- **Track A — Orientation** (always, regardless of whether an issue is named): read `AGENTS.md` and
  `CLAUDE.md` when present, then `docs/README.md`'s task-signal map, and the active decisions catalog
  `docs/decisions/README.md`. This is what replaces re-deriving conventions from source or from a
  pinned tracker's prose — see "Knowledge retrieval" below for the full catalog-first / breadcrumb-rule
  contract.
- **Track B — Selection** (only when the user has NOT named an issue): run the deterministic selector,
  `ETV_GITEA_BASICAUTH=user:pass scripts/select-queue.sh [N]`. It does the mechanical parts a cheap
  model used to get wrong IN CODE: excludes `in-progress`/`parked`/PRs/bot-authored issues (Renovate's
  Dependency Dashboard #22, ersatztv#553), resolves
  `GET /issues/{n}/dependencies` on every candidate (dropping any with an OPEN blocker), tiers by
  LOCAL `.milestone.state`/`review`/`priority:` filters (never the server `?milestones=` name filter,
  which no-ops on `:`/`+`), and orders by (tier, priority, issue#). **Its DEPS/tiering/ordering are
  deterministic — trust them, do not re-derive them by hand** (the hand-derivation failure modes the
  script encodes are recorded at `ci.gitea-milestone-filter-noop`). It also raises two JUDGMENT flags it deliberately does
  not decide — `CLAIM?` (a claim can precede the label) and `UMBRELLA?` (an epic whose children are the
  real pickups) — resolve ONLY those by reading the flagged issue's comments/body. The script does not
  rank an arc tier (there is no active arc right now — maintenance/backlog mode, see above); if a new
  arc/milestone is ever established, add it as a script tier rather than reverting to prose-derived
  ranking. If the script is unavailable (no creds / Gitea down), it fails open (prints a notice, exits
  0) — in that case fall back to a single low-cost model session querying live tiers directly
  (OPEN-milestone → `review` → `priority: high/medium/low`), never to inline sorting by the
  orchestrator.
  **If the user names an issue, skip Track B entirely** and go straight to focused retrieval (below)
  plus a live claimability check on that issue; this explicit user choice is the sole path by which a
  `parked` issue may be worked.

Dispatch exactly one selector on the cheapest suitable model at `low` effort when the client can route
a cheaper subagent; otherwise run it in a separate low-cost session before starting or resuming the
orchestrator and pass in its packet. **Do not fall back to inline sorting or an equally expensive
selector.** If no cheaper route or session is available, pause and request the selector packet rather
than consuming orchestrator tokens on queue ranking.

FIRST read `AGENTS.md` and `CLAUDE.md` when present, then `docs/README.md` and the sections its
task-signal map points to for your task, plus the Lessons below. Apply both client instruction files; where they differ, follow the
stricter safety/completion requirement unless a higher-priority instruction resolves the conflict.

FRONTIER ESCALATION — these moments go to the strongest available reasoning model. In Claude Code,
prefer Fable; in Codex, prefer the strongest frontier model at extended-high reasoning. If you are
already running that profile, handle them inline. Otherwise delegate with a SELF-CONTAINED brief
(scope, exact question, evidence, file paths, and doc pointers), or ask the user to switch models when
the client cannot route the escalation. Do not block merely because one brand-specific model is absent:
- Architecture/API design decisions (e.g. #202's media-source API shape) and anything
  `[PLAN-MODE]`-tagged.
- Parity verdicts for blazor-route-parity.md (per-capability diff sign-off) and #91b
  removal go/no-go.
- Reconciling contradictory independent-review findings and the final
  pre-merge judgment on gate PRs.
- Stuck after two genuinely different approaches, or evidence contradicts the issue/docs.
Everything else (claiming, worktrees, dispatching implementers, CI monitoring, protocol
bookkeeping, routine merges of green reviewed PRs with user consent) stays at your level.

## Knowledge retrieval (MemPalace + catalog + Gitea — the #642 seam)

**MemPalace = candidate discovery only**, retrieved at a bounded `k`; every passage **verified
against its cited Markdown/Gitea source** before use. **Default wing = `ErsatzTV-Decisions`** (active
`docs/decisions.md` + `docs/decisions/*.md` + catalog). History wings `ErsatzTV-Decisions-Archive`
(`docs/decisions/archive/**`) and `Gitea-ErsatzTV` (issues/comments incl. closing records) are touched
**only** when the question is explicitly "what did the rule *used to be*." "What is the current rule
for X" never touches the history wings.

The four load-bearing orientation bullets — carry these **VERBATIM** wherever this contract is
referenced (`docs/README.md` too):

1. **Current conventions/decisions → catalog-first.** Start at `docs/decisions/README.md`; discover
   via the `ErsatzTV-Decisions` wing (active) / `ErsatzTV-Decisions-Archive` (superseded/retired).
   **Resolve by topic/key, never by chasing a file path.**
2. **Issue history → evidence, not authority.** The `Gitea-ErsatzTV` wing is historical narrative
   that may be stale; it never overrides current Markdown.
3. **The breadcrumb rule (the crux behavior change).** A file path named inside a *historical issue
   comment* (e.g. "grep `docs/decisions.md` 2026-07-17", "see …") is a **breadcrumb, not a live
   pointer.** Find the current rule via the catalog / active wing **by concept**; do not treat the
   named path as current. (Why it's safe: still-current → in the active wing, breadcrumb resolves;
   superseded → the active wing returns the *successor* and a literal follow lands on a record that
   announces its own `status: superseded`; retired → the active wing returns nothing, which is itself
   the signal. The validator-enforced move-to-`archive/` is what prevents the catastrophic "superseded
   rule read as current" case.)
4. **Fallback when MemPalace is stale/down:** `docs/decisions/README.md` catalog, then
   `` rg '^`key: <dotted.key>`' docs/decisions/ ``. MemPalace is never authority nor sole fallback.

**Graceful degradation (calibration, not a correctness cliff):** even an under-oriented agent that
literally greps `docs/decisions.md` post-#521 gets valid-but-*incomplete* results (misses topic files
+ archived records), never *wrong* ones — that file holds only active records. So this is a
completeness/latency risk during rollout, not a correctness cliff.

**Altitude / precedence:** `docs/decisions.md` (+ topic files) is **normative/current** ("the rule is
X") — the `ErsatzTV-Decisions` wing, authority for "what is the current rule." Gitea issues are
**evidentiary/historical** ("we worked X on date D; spec, discussion, outcome") — the `Gitea-ErsatzTV`
wing, authority for "how was this handled / what was the context." A decision record points to its
issue; the issue carries the provenance the record compresses. Same fact, two altitudes — canonical
Markdown wins for "current."

**Issues in MemPalace are for DISCOVERY, not queue state.** Encounter a problem → search MemPalace →
find relevant docs AND relevant open issue(s): this **avoids filing duplicates** and **surfaces
bundles** (related issues to pick up together). But a MemPalace issue hit is a *candidate*:
open/closed/claimed/blocked/priority flip constantly and MemPalace lags (seconds–1h, up to a week if
the webhook is down), so a hit may be a since-closed issue shown open, or miss a just-filed one.
**Always re-confirm live state in Gitea (`scripts/select-queue.sh`) before acting** — never treat a
MemPalace issue hit as current queue state.

**What to mine per issue:** open issue → the BODY (dedup + bundle-clustering; no closing record yet).
Closed issue → body + the `## Closing record` (how it was resolved). Ephemeral comments (claim /
progress / `Review-verdict:`) → skip or de-weight both ways — process exhaust, not the knowledge
store. The `## Closing record` is the one structured per-issue summary meant for retrieval + export.

**Staleness bounds** (so agents know when to distrust a hit): webhook re-mine in seconds; hourly
reconcile; weekly full sweep catches file moves/deletes. Worst case before a supersession takes effect
in retrieval: ~1h, or ~1 week if the webhook is down and only the move happened. When in doubt, fall
back to exact search (bullet 4 above).

**Never** derive live queue state from MemPalace, #237, or historical comments.

Then work the queue:
1. Run the two tracks above (orientation always; selection unless an issue is named).
2. If Track B ran: apply its ranked shortlist. The orchestrator makes one focused live recheck of the
   winner (still OPEN, unclaimed, not blocked) before claiming; if it changed, check the next fallback.
   **An empty backlog is not a stopping condition** — if the selector returns any eligible candidate,
   claim its top-ranked winner; do not ask the user to choose merely because candidates belong to
   different workstreams. Never invent a fix-size, recency, or perceived-relevance tiebreaker.
3. **Claim it — but CHECK FOR AN EXISTING CLAIM FIRST, and the label is not the whole check.**
   The `in-progress` label prevents duplicate *pickup*; it does not prevent duplicate *work*, because
   another session may already be implementing an issue it has not labelled (or labelled after you
   read the list). Before writing any code, run all four — they are cheap and they fail differently:

   a. **Open PRs referencing the issue.** `GET /repos/{owner}/{repo}/pulls?state=open` and look for
      `fixes #N` / `refs #N` in the body, or the number in the branch name. This is the check that
      would have caught ersatztv#649 being implemented twice.
   b. **Remote branches naming the issue.** `git ls-remote --heads origin '*<N>*'` — a branch usually
      exists before the PR does.
   c. **Recent comments on the issue**, not just its labels — a "claiming" comment from another
      session may predate the label, which is exactly what `CLAIM?` from `select-queue.sh` flags.
   d. **`git fetch origin main`**, so you are reading current state rather than your session's
      opening snapshot.

   If any of those hit, do not start: report it to the user and take the next candidate. If none do,
   claim with the `in-progress` label **and** a "claiming" comment (reviewer-repo audits are claimed
   by comment only). Treat a claim as live until a later comment explicitly releases or abandons it,
   and exclude audits with a posted deliverable even while the issue remains open for implementer
   replies.

   **Re-fetch `origin/main` before every push, not only at branch time.** A long session can run for
   hours across several review rounds; `main` moves underneath it. A branch cut from a stale base
   whose diff is computed against that stale base will silently show *other people's merged work as
   deletions*, and pushing it reverts them. Rebase (never merge main in) and re-run the local gate
   whenever the fetch shows movement. → `process.parallel-session-claim`
4. **Scan for bundle-able siblings** (always, right after claiming — not optional). Check all three
   bundle axes from "Bundles" above: the claimed issue's **milestone**, its **cross-references /
   backlinks**, and its **shared label(s)** (list the other open issues under each of its labels).
   Surface any small, independent siblings to the user with a size/fit read and a recommendation, and
   fold the agreed ones into this session (parallel worktrees for disjoint slices). This is how #22's
   sibling-cluster fixes (#553 + #512) got swept together; skipping it silently narrows a session that
   could have closed two or three issues for barely more cost.
5. Read the issue bodies (they carry the task context/evidence) and work the item(s) under the
   HARD CONSTRAINTS below.
6. Finish the session: run the **H12 qualification audit**
   (`ETV_GITEA_BASICAUTH=user:pass scripts/issue-qualification-audit.sh`) and add a `priority:`
   label to anything it lists (every issue you filed this session included); post a `## Closing
   record` (template below) on each issue you closed or substantially progressed; remove your
   `in-progress` labels; and complete the per-issue Task Completion Protocol from the applicable
   `AGENTS.md` / `CLAUDE.md` instructions (including the `done` workflow when required).
7. **Leave the shared checkout fresh** (H13): run `scripts/refresh-shared-checkout.sh`. It
   fast-forwards `/Users/timothy/ersatztv` to `origin/main` and refreshes `web/node_modules` if the
   lockfile moved; it refuses and changes nothing unless that tree is on a clean, non-ahead `main`.
   A NO-OP is a normal result — report it and carry on.

## Closing record (session-end / issue-close artifact)

Post this as the structured closing comment on any issue you close (or substantially progress) — it
is both the human-readable summary and the per-issue unit MemPalace mines for retrieval:

```markdown
## Closing record
**Outcome:** <what shipped / what didn't; PR link>
**Root cause:** <for bug fixes/incidents — why the problem existed, or "unknown, see follow-up #N">
**Decisions/conventions changed:** <keys added/superseded in docs/decisions.md, or "none">
**Reusable knowledge:** <a fact/gotcha worth surfacing to a future session or MemPalace search>
**Verification:** <tests run, live-E2E, CI status>
**Deferred:** <anything explicitly punted, with a follow-up issue link, or "none">
**Docs updated:** <which docs/*.md files changed in this PR, or "none required and why">
```

HARD CONSTRAINTS:
- **Work in a worktree off `origin/main` — always**, including a one-line docs commit. Never commit in
  `/Users/timothy/ersatztv` and never read its git state to learn about `main`. → `process.shared-tree-readonly`
- **One committing agent per worktree.** Give each parallel slice its own; read-only review agents may
  share. → `process.one-worktree-one-committing-agent`
- **Never commit or merge inside a worktree you did not create** — land on a sibling-owned branch with a
  plumbing merge. → `process.foreign-worktree-plumbing-merge`
- **Parallelize by default** on genuinely disjoint slices (normally 2–3 delegated agents). Cap builds at
  3–4 and gate on FREE RAM, not CPU. **Never set `ETV_UPDATE_GOLDENS`.** → `process.build-concurrency-limits`
- **Name the model + effort for every dispatched agent, in the dispatch itself** — bounded recon → cheapest
  fast tier at `low`; mechanical slice against a documented contract → mid tier; judgment-heavy (design,
  compiler/parser, security, migrations, review arbitration) → orchestrator tier; independent review →
  a different model family than the implementer. Omitting it silently inherits the orchestrator tier, so
  state the choice out loud. → `process.per-agent-model-routing`
- **Local gate + cold-context review BEFORE the push**, never after — and the push is licensed by a
  **CLEAN verdict, not by a review having run.** Zero outstanding findings on the current tree, however
  many rounds that takes; "round 1's findings are fixed" and "the mechanism has been cleared" are both
  reasons to keep reviewing, not to push. Each extra push auto-cancels the live run, and a cancelled job
  reads as `failure` at the commit-status endpoint — so an early push manufactures phantom reds on top of
  the wasted runner time. → `process.local-gate-before-push`, `ci.cancelled-is-not-a-verdict`
- **Independent review is mandatory** for locks/concurrency, auth/security, API write-path handlers, DB
  migrations, or >~150 changed C# lines; a skip must be stated with its reason. → `process.independent-review-rubric`
- **Batch your pushes — you cannot cancel a CI run.** Only the operator can cancel, in the browser.
  → `ci.batch-pushes-no-cancel-route`
- **Do not gate your push on host health** — trust the build queue. → `ci.no-host-health-gating`
- **Arm the CI monitor at PR-open**, on the head sha. → `ci.monitor-armed-at-pr-open`
- **Before any push touching `.cs`, BOM-check the touched set** and run the format gate under `bash -c`.
  → `process.bom-format-detection-recipe`
- **Keep a PR branch current by REBASING on `origin/main`** — never merge main in; regenerate (never
  hand-resolve) generated artifacts after a conflicted rebase. → `release.format-as-you-touch-rebase`
- **Live-E2E via `scripts/e2e-local.sh` before the push** for write-path/UI changes; curl download
  endpoints, never browser tabs; use a fresh config dir.
  → `testing.live-e2e-prepush-timing`, `testing.e2e-local-fresh-config-dir`
- **Merge consent is DERIVED, not asked.** The H6/H10 gate auto-grants when the `## Done-when` boxes are
  ticked, a fresh `Review-verdict` references the current head, and CI is green; confirm in conversation
  only when the gate ASKS. Prior pre-approvals never carry over. → `release.merge-consent-autogrant`
- **Post every review verdict with `scripts/post-review-verdict.sh <pr> <VERDICT>`** — never hand-write the
  comment. It also writes the `review-verdict/h10` commit status, which is the REQUIRED check that actually
  gates the merge; a comment alone leaves it absent. Being sha-bound is the point: a commit pushed after an
  auto-merge is scheduled clears it, so scheduled merges can no longer land unreviewed code.
  → `release.verdict-status-check`
- **After the push, fixes are follow-up commits** — never amend or force-push a pushed branch.
  → `process.pr-routine-sequence`

---

# Lessons / workflow lore (STANDING workflow/orchestration rules only)

> **Scope**: *how we work* — orchestration, CI triage, review routing, cross-session hygiene. Each rule
> below is one or two lines plus its decision `key:`; the evidence, the incident that produced it and the
> full rationale live in that record (`docs/decisions/workflow-process.md` for most of them). **Keep it
> that way** — `docs.no-session-narrative` is the general rule (a doc records the end state; the path to
> it goes in the commit message), and it binds here with one extra cost on top: this file is pasted into
> every session's kickoff, so a paragraph here is a tax paid by every future session, while a record is
> retrieved only when it is needed (#542).
>
> Editing: prune covered and stale bullets rather than appending — this is not append-only and git keeps
> the history. If you add a rule, write the record first and cite it here.

**Orientation**
- Read `docs/README.md` → the convention docs first; point agents at named sections, recon only the
  task-specific delta. → `docs.convention-docs-session-start`
- Run `scripts/select-queue.sh` for queue selection; trust its deps/tiering/ordering and resolve only its
  `CLAIM?`/`UMBRELLA?` flags. → `startup.parallel-orientation`
- A session that runs several issues at once is an orchestrated session: `docs/handoffs/orchestration.md`
  owns its mechanics and `orchestrator-prompt.md` starts it; every slot is still bound by this file.
  → `process.orchestrated-session`
- Claim with `in-progress` before working — but **check for an existing claim first** (open PRs
  referencing the issue, remote branches naming it, comments predating the label, a fresh
  `git fetch`), because a label prevents duplicate *pickup*, not duplicate *work*: #649 was
  implemented twice to completion. And re-fetch `origin/main` before every push — a branch on a stale
  base reverts whatever merged meanwhile. → `process.parallel-session-claim`

**Building and reviewing**
- The PR routine is a fixed sequence; for API changes build the app project FIRST, then
  `./scripts/update-openapi.sh`, then `npm run generate:api`. → `process.pr-routine-sequence`
- Re-review the FIX COMMIT, not just the initial diff; loop until a clean verdict or an explicit
  acceptable-defer, and file a tracked issue for anything deferred. → `release.review-verdict-gate`
- When independent reviews disagree, escalate to the frontier judge — and escalate the proposed FIX with
  the finding. → `process.review-disagreement-frontier-judge`
- "Make X consistent with Y" findings are new code; for any timer/effect ask when it fires, including on
  mount. → `process.consistency-fix-new-code-scrutiny`
- Before trusting a "single owner / no cross-release" claim, grep the whole host project for every
  producer — the background scheduler is the usual miss. → `process.lock-ownership-enumerate-producers`
- Before deleting a "workaround", enumerate every behavior it provided.
  → `process.enumerate-workaround-behaviors-before-deleting`
- Concurrency tests need a stress loop and a negative control that inverts the real condition — never
  `if (true)`. → `ffmpeg.work-ahead-slot-atomic`
- Enumerate lazy LanguageExt returns in tests; live-E2E is the only net for that class.
  → `release.live-e2e-required`
- Harden a soon-to-grow feature with a runtime posture, not a hardcoded clamp.
  → `process.harden-with-runtime-posture-not-clamp`

**Reading a red CI run** (check these before diagnosing your diff)
- A **killed** job reports `conclusion: failure` — read the log tail for the `❌ Failure - Main` marker;
  log timestamps are UTC, the host is UTC+2. → `ci.killed-job-triage`
- **`cancelled` is not a verdict**, and the endpoint you poll hides it: `commits/{sha}/status` has no
  `cancelled` state and reports one as `failure`. Resolve the job `conclusion` via
  `actions/runs/{id}/jobs` before believing a red. → `ci.cancelled-is-not-a-verdict`
- A failure inside a **setup/cache step**, before your code compiles, is environmental.
  → `ci.infra-shaped-red-under-load`
- A lone **`decisions lifecycle`** red is a known flake: do **nothing**, the operator reruns it. A
  convincing local explanation is always available — check this rule before theorising.
  → `ci.decisions-lifecycle-flake`
- Heavy-render web tests need explicit per-test vitest timeouts. → `ci.web-test-per-test-timeouts`
- Verify locally and trust it; CI confirms (~9 min warm, seconds for docs-only).
  → `ci.verify-locally-ci-confirms`

**Tooling gotchas**
- E2E cleanup kills only PIDs it started — never `pkill -f "dotnet ErsatzTV.dll"`; a foreign listener
  is reported, not reaped. Carry this into every delegated E2E brief.
  → `testing.e2e-cleanup-scope-by-pid`
- Playwright-MCP: curl download endpoints, never open a tab; on repeated stalls prefer
  `pgrep -f ms-playwright-mcp` and kill only your own PID (that record still says `pkill -f`; the same
  shared-host reap is being reconciled in #596). → `testing.playwright-mcp-download-and-recovery`
- Channel branding is NOT testable through the troubleshooting-playback API.
  → `testing.troubleshoot-path-cannot-test-branding`
- Codex cheap workers launch via `codex exec`, not `spawn_agent`. → `process.codex-cheap-worker-launch`
- A dropped subagent connection is transient — resume via SendMessage, don't restart.
  → `process.subagent-drop-resume`
- Fixing onto an unmerged feature branch: branch off it, FF-push, and beware the sibling-worktree path
  leak. → `process.branch-off-feature-branch`

**Session end**
- Run the H12 audit and label everything it flags. → `process.issue-qualification-audit`
- Run `scripts/refresh-shared-checkout.sh` so the next session's checkout is current.
  → `session.shared-checkout-refresh`