---
name: "convention-linear"
type: convention
description: How Aled's work is expressed in Linear specifically — the teams and projects, the issue states per workflow, the label taxonomy, the agent single-select group and its routing values (including the lowercase operator-per-venture values such as operator-bara), the Pipeline people-vs-opportunity model and its Gmail/surfaced labels, document and decision-log filing, and issue numbering. Read whenever a task touches the Linear workspace — creating or updating issues, choosing teams/projects/labels, filing docs, or running agent work in Linear. This is the tool layer; convention-ticket holds the tracker-agnostic discipline that this maps onto Linear. Getting team, labels, or states wrong creates real cleanup, so consult this first rather than guessing.
license: CC BY-NC-SA 4.0
---

> *This is the canonical copy of this skill. The corresponding Linear doc (*`convention-linear`*) is a reference copy. Edit here; re-sync to Linear after changes.*

# Linear workspace conventions

Aled runs all his work through Linear, the **system of record**. This convention is the **tool layer**: it says how the tracker-agnostic discipline in `convention-ticket` is expressed in *this* workspace — its teams, states, and labels. Read `convention-ticket` for the working discipline (how a ticket is shaped, captured, validated, and routed); read this for the Linear specifics that enact it. Where the two touch, this document names the concrete Linear binding and points back to `convention-ticket` for the why.

The failure modes here are silent — a stale label, an issue in the wrong state, a decision never logged — and they cost real cleanup later. Follow precisely.

## The workspace: teams and where work goes

Five teams. Route to the right team first, then the right project within it.

| Team | Key | What it holds |
| -- | -- | -- |
| **Apps** | `APP` | Product/app builds, cross-cutting build infrastructure, and the careerOS system. Projects: os.Claude (how Claude is operated — skills, routines, agent instructions), app.fitness, Luna MVP — Retirement Navigator, bot.Trader; the cOS.\* careerOS projects — cOS.System (architecture, philosophy, canon), cOS.Content (truth captures `tc.*`, case studies, CV, narrative), cOS.Build (engineering, website, automation), cOS.App (AI behaviour for the portfolio product), cOS.Reporting (inbound product signals); and the gtd.\* GTD projects (Capture, Configure, Build, Health, Home, Family, MBN, CareerOS). Owned by `operator-apps`, except the bot.Trader project, which is `operator-bottrader`'s. |
| **MBN** | `MBN` | Made by — Neud, the homeware venture and its BARA relaunch. Projects: mbn.website (the Shopify storefront theme), mbn.brand, mbn.growth. Owned by `operator-bara`. Also holds the ~117 closed careerOS issues left behind by the 2026-07-14 rename (`MBN-21`…`MBN-237`) — history, not live work. |
| **Pipeline** | `PIPE` | People and opportunities (see "The Pipeline model" below). Projects: Network (the people layer), Roles, Advisory, Pitches (the opportunity funnels). No operator — not a delivery vertical, and out of scope for the operator sweeps and for triage. |
| **A1** | `A1` | The Association of One consultancy. Projects: a1.OS (standards and playbooks — the practice's operating system), a1.Brand (A1's own identity and the client-facing document system), and one project per client engagement (a1.MeirionPritchard, a1.Heroes). Owned by `operator-a1`. |
| **Mr Pritchard** | `MRP` | Editorial and personal brand. Projects: Articles (long-form, canon voice), Substack (short-form), LinkedIn (posts), Operations (decision log, project instructions, get-started). Editorial cascades: an Article is the parent; its Substack and LinkedIn derivatives are sub-issues. Owned by `operator-mrp`. |

**Every delivery-team row names its owning operator, because refinement reads the value from here.** `operator-<venture>` is set at refine on the ticket's owning row (*Operator attribution*; `skill-triage`, APP-1217), and the refining leg is instructed to resolve the vertical from this table — which named an operator on one row of five, so the instruction resolved for MBN and for nothing else. The rows above now carry it. **Apps is the one team resolved by project rather than by team:** tickets in its bot.Trader project carry `operator-bottrader` and the rest of the team carries `operator-apps`. That is what the board holds today — APP-681, APP-669 and APP-787 all sit in the Apps team carrying `operator-bottrader` — and it is recorded here as the write a refiner should make, not as a portfolio ruling. Whether bot.Trader is an Apps bet or a peer vertical is an open Owner question (APP-995, Urgent, Todo, `human` plus Aled); answered either way, the allocation changes and the label does not.

(**`[pulse-refine]` ruling, 2026-09-11.** The *what* it sits inside is the refine-sets-the-label rule in *Operator attribution* (APP-1217). Evidence: APP-1274, APP-1275.)

Quick routing:

* A *person* → Pipeline / Network. An *opportunity* → Pipeline / Roles, Advisory, or Pitches, titled for the opportunity (never the person).
* How Claude is operated (skills, routines, agent instructions) → Apps / os.Claude.
* careerOS system work → Apps / the `cOS.*` projects. careerOS is a set of projects, not a team.
* Made by — Neud / BARA work → the MBN team (mbn.website, mbn.brand, mbn.growth).
* A1 client work → the A1 team, one project per client; A1 standards and playbooks → a1.OS.
* Editorial → Mr Pritchard (Articles → Substack → LinkedIn).

If the right home is genuinely ambiguous, ask rather than guess. A misfiled ticket is worse than a clarifying question.

### The 2026-07-14 restructure — careerOS demoted, MBN promoted

The team set changed on 2026-07-14, and two traps follow from it.

**careerOS is no longer a team.** Its five `cOS.*` projects moved into **Apps**, and the ~12 live issues moved with them, renumbered `COS-*` → `APP-*` (git branch names regenerated to match). The old careerOS team was **renamed to MBN**, key `COS` → `MBN`, rather than deleted — the plan's team limit allows no new team — so its ~117 closed careerOS issues stayed behind and were reprefixed `MBN-21`…`MBN-237`. The three `mbn.*` projects then moved into it, their issues renumbered `APP-*` → `MBN-238`…`MBN-260`, keeping project membership, milestones, parent/child links, and state.

**So an old `COS-###` reference is dead, not merely renamed.** The live issue is now a *different* `APP-###`, and the `MBN-###` sharing that number is an unrelated closed careerOS issue. Never resolve a `COS-###` from an older doc, comment, or branch name by substituting the number — look the issue up by title. And any sweep scoped by team must read the table above rather than a remembered list: `careerOS` now resolves to nothing, and MBN work is missed entirely by a scope list that predates the change (worked cases: APP-521, APP-522).

Mechanics worth knowing before any future restructure: moving an issue between teams renumbers it and detaches its project unless that project already sits in the target team; the connector refuses to move a project whose team still owns its issues, which is safer than the UI, which silently orphans them; there is no bulk archive for issues in either the UI or the connector; team create and rename are UI-only. (Captured by the restructure session, 2026-07-14.)

## Project descriptions — the standing structure

A Linear **project description** carries four sections, in this order, and both a new project and a rewritten one are written against them (operator ruling 2026-10-19, on the Owner's delegation of the placement call the same day — `APP-2465`):

| Section | What it holds |
| -- | -- |
| **Purpose** | What the project is for, in one or two sentences — the outcome it exists to produce, not the activity it contains. |
| **Audience and how we communicate** | Who the work is for, and the register and channel it reaches them through. |
| **Goals** | What has to be true for the project to have worked, written so a later reader can test it rather than agree with it. |
| **Decisions** | The calls already taken and not to be re-judged, each dated. |

**The audience section is skipped and the skip is noted — never left blank and never deleted.** Where nothing in the project is customer-facing — an internal tool, a configuration project, a canon project — write `none — internal only` under the heading. An absent or empty section carries no information, so the skip is the fact worth recording: a present heading carrying a stated skip is what tells a deliberate skip from an unwritten section, and it is what stops the next reader asking the question again.

**Existing projects are brought over as next touched. No bulk rewrite.** A description is restructured when something else already takes you into the project — a new milestone, a status change, a charter session — never as a sweep of its own. The live set will therefore be mixed for a long time, and a four-section description on one project is no evidence about any other.

**The structure binds here; `convention-ticket` stays tracker-agnostic.** The four sections name the description field of a Linear *project*, which is a Linear object with no tracker-agnostic equivalent, so this convention is its home and `convention-ticket` carries no copy of it.

**No template enforces this, and none exists to.** `list_templates` returns an empty set for this workspace on every type, `project` included (read 2026-10-20). The structure is held by the writer, exactly as the closing-comment rule in *Issue states* is. Creating a project template, if one is ever wanted, is a workspace-config lever and the Owner's.

## The Pipeline model — people vs opportunities

The Pipeline team has two layers, and keeping them distinct is the whole point of the structure:

* **People layer — `Network`.** Every contact lives here, inbound or outbound. The unit is a *person*. A person enters here and never moves out; the relationship persists regardless of what it produces.
* **Opportunity layers — `Roles`, `Advisory`, `Pitches`.** Concrete opportunities, each titled for the *opportunity* — **never for a person**. An opportunity issue is created only when something real exists.

The rule: **a person never appears in an opportunity funnel, and an opportunity is never titled with a person's name.** When a relationship produces something concrete, an opportunity issue is spawned in the right funnel and *linked back* to the person in Network via a native relation. One person can throw off several opportunities over time; each is its own linked issue; the person stays put.

This is why Advisory may look near-empty: it holds live advisory *engagements*, not advisory *leads*. Leads are people, and people are in Network.

### Gmail capture labels (the `pipeline/` family)

Mail is fed into the funnels by labelling Gmail threads with the `pipeline/` prefix (renamed 2026-06-02 from `job-search/`). The sweeps read these:

* `pipeline/roles` — a specific role → swept into Roles
* `pipeline/recruiter-internal` / `pipeline/recruiter-agency` — a recruiter → swept into Network
* `pipeline/network` — a general contact → swept into Network, no `opp:` unless signalled
* `pipeline/advisory` — a person near an advisory opportunity → swept into Network, stamped `opp:advisory` (advisory *intent*; does NOT route to the Advisory project)
* `pipeline/triaged` — the processed-marker added by every sweep so threads aren't re-swept

### Surfaced / graduation labels (Linear)

The link between the people layer and the opportunity funnels runs on structured labels, not free-text scanning:

* `surfaced:role` / `surfaced:advisory` / `surfaced:pitch` — a concrete role / advisory opening / A1 new-business item has surfaced from this Network relationship
* `surfaced:done` — graduated; an opportunity issue has been created and linked (prevents re-graduation)

The feeding sweeps add `surfaced:role` / `surfaced:advisory` automatically when they spot a concrete opening; add a marker by hand after a call surfaces something. The graduation routine reads these markers, creates the linked opportunity issue, then swaps the trigger label for `surfaced:done`.

## Issue states

The capture → refined → ready lifecycle in `convention-ticket` maps onto these Linear states. Two workflows are in play, by team:

**Apps, A1 (engineering/kanban):** `Backlog`, `Refinement`, `Todo`, `In Progress`, `In Review`, `Blocked`, `Done`, `Canceled`, `Duplicate`. MBN runs the same set.

**Mr Pritchard (editorial) — a different set, and three of the states canon used to claim for it do not exist.** Verified live via `list_issue_statuses(team: "Mr Pritchard")`, 2026-07-20: `Backlog` (backlog) · `Defined` (backlog) · `Todo` (unstarted) · `Ready` (started) · `In Progress` (started) · `In Review` (started) · `Scheduled` (completed) · `Published` (completed) · `Canceled` · `Duplicate`. There is **no `Refinement`, no `Blocked`, and no `Done`.** The mapping for a skill written against the engineering set:

| Engineering state | On Mr Pritchard |
| -- | -- |
| `Refinement` (refined-and-parked) | **`Defined`** — the team's second backlog-type state, and the one that means refined but not yet actionable |
| `Blocked` | **`In Review`**, carrying `human`, assigned to Aled, priority escalated by age — the team has no Blocked, and an editorial item's blocker is almost always Aled's own call anyway |
| `Done` | **`Published`** for anything that ships; **`Scheduled`** where it is queued to ship on a date |
| A decision taken, nothing shipped | **`Canceled`** — the team's only terminal state that makes no publication claim |
| A deliverable that **shipped as input to other work**, not as a publication | **`Canceled`** as well — `Published` and `Scheduled` both assert publication and this did not publish, and it is not a decision-with-nothing-shipped either. The closing comment says **which of the two it is** and names the tickets the output fed, by ID |

**A completed-type state on Mr Pritchard is a publication claim.** Verified live via `list_issue_statuses(team: "Mr Pritchard")`, 2026-09-10: the team's only two `completed`-type states are `Scheduled` and `Published`, and **both assert that something shipped**. `Canceled` is canceled-type and appeared in no mapping row. So a ticket whose entire deliverable was a *decision* — a call taken, a direction settled, an option declined, nothing published — had no honest terminal state, and closing it as `Published` records a publication that never happened (worked case: MRP-3, closed `Published` with nothing published). It closes **`Canceled`** instead: the canceled-type state asserts only that the ticket is finished, which is exactly and only what is true. `Canceled` here is not a judgement on the work's value — on this team it is the terminal state that makes no shipping claim — so the **closing comment carries the ruling**: state the decision taken, and state that the ticket is closed as *decided, not shipped*, so a later reader does not read `Canceled` as abandoned.

(**`[pulse-refine]` ruling, 2026-09-10.** A **how/where** call under the APP-1099 what/how split — `core-operating-model`, *Canon authority splits by what and how*. The *what* it sits inside is the Owner's decision of 2026-07-20 that this mapping table exists precisely so the question is not re-judged per run, APP-620. The reasoning: creating a new editorial state would be a workspace-config lever and therefore the Owner's; choosing among the states that already exist is mechanism choice where canon already leans, which is Pulse's. The Owner retains the override. APP-1216.)

**The non-shipping side of the table has two rows, not one, and the closing comment is what tells them apart.** The row above answers the case where nothing shipped. It does not answer the case where something genuinely shipped and was never **published** — a deliverable produced as **input to other work**, consumed by other tickets, with no publication anywhere. On this team that item has no honest state either: `Published` and `Scheduled` are the only completed-type states and **both assert publication**, which did not happen, and the decision row does not describe it, because something was in fact produced and handed on. It closes **`Canceled`** for the same reason the decision case does — it is the only terminal state on this team that makes **no shipping claim** — and that is where the two cases converge and why the comment has to separate them. So a `Canceled` close on Mr Pritchard states, in the closing comment, **which of the two it is: decided-not-shipped, or delivered-as-input **And a ticket's own body text does not override this table.** Where a ticket carries an embedded instruction naming the state to close into — a template's closing step, a cycle-commit-generated directive, a hand-written "close as X when done" — and that state disagrees with the mapping above, **the live mapping governs and the instruction is traced to its provenance** per `convention-ticket`'s *provenance test*, never followed literally. The instruction was written against the team's states as they stood when it was authored, and a team's state set changes; on an editorial team the divergence is not cosmetic, because the only completed-type state there **is a publication claim**, so following the body would assert that something published when nothing did. The caught instance is `MRP-81` (`APP-2479`).** — and where it is the second, it names the tickets the output fed, by ID. **The comment is load-bearing, not courtesy.** `Canceled` carries no information on its own; it is the absence of a claim. An uncommented `Canceled` close is therefore **indistinguishable from abandonment** to every later retro, report and cycle-goal document that reads the state field, and the reading that follows is the expensive one: a false *cancelled with no reason* manufactures work, because it re-commissions output that already exists and discards a correct diagnosis along with it. That cost is measured, not hypothetical — `APP-2281` records it at **six tickets closed unmet partly on that reading, and a duplicate commission**. (Worked case: MRP-78, delivered and then closed `Canceled` with no reason two days after `APP-2281`'s reading-side rule published, its deliverable having shipped as input onto four other tickets. The reading-side rule held — the run read the thread and reported the work as delivered — and both gaps that remained were at the writing act. Who closed MRP-78, and why, is **unknowable from this surface** and is not asserted here; the hand-off comment, the close time and the cycle-goal document contents were **not re-read** on this pass. APP-2406, antecedent APP-2281.)

(**`[pulse-refine]` ruling, 2026-10-19 — a how/where call, and a deliberate decision not to build a detector.** The *what* it sits inside is the same one the 2026-09-10 ruling above cites: the Owner's decision of 2026-07-20 that this mapping table exists precisely so the question is not re-judged per run, APP-620. Adding the missing row and naming what its closing comment must carry is mechanism choice inside that decision, which is Pulse's. **A detector that flags an uncommented `Canceled` close is deliberately not added**, and the reason is a property of the surface rather than a question of effort. The connector exposes **no per-field** `updatedBy`, so a close cannot be attributed to whoever made it; a detector therefore fires on **the Owner's own UI closes as readily as on an agent's**, and what it would produce is a standing queue asking him to annotate his own decisions — the opposite of the relief the rule is for. Canon already forbids the fallback of shipping it anyway as a report: a sweep that names without repairing is not sanctioned. So the requirement stays a **writing-act rule with no detector behind it**, and it is enforced by the writer holding it, as the hand-off rules in *Reading Linear safely* are. If the connector later exposes per-field attribution, the ruling is worth revisiting on that fact alone. The Owner retains the override. APP-2406.)

Use the mapping rather than deciding per run: this was previously a judgement call, and the same evidence produced two defensible answers on the same run (MRP-21, MRP-23, 2026-07-20). A Blocked-state sweep simply does not apply to Mr Pritchard — read `In Review` there instead. (APP-620.)

**The Owner lane carries an estimate (Owner ruling 2026-09-03, APP-1003).** Any ticket routed to `human` and assigned to Aled carries Linear's native **estimate**, on the Exponential scale every team now runs (Apps, A1, MBN and Mr Pritchard: Exponential, allow-zero off, extended scale off, count-unestimated off): **1** = 15 minutes — a one-word verdict is a 1 · **2** = 30 minutes · **4** = one hour · **8** = two hours · **16** = over two hours, which routes to Relay to split. No `owner:*` size label — one mechanism, native, readable by every sweep, and the same field that makes cycle velocity meaningful. Aide writes it at sweep time (`skill-attention-sweep`, its one Linear write); the morning brief, `skill-time-block` and `task-cycle-planning`'s capacity note read it. **An Owner-lane ticket with no estimate is an Aide defect, never a small item** — count-unestimated is off precisely so a missing estimate shows as a gap, not as a guessed 1. This is what lets the Owner triage `In Review` on Mr Pritchard by glance: the state says it waits on him, the estimate says whether he can clear it standing up. (Worked case: MRP-41, one word and one label, beside MRP-45, fifteen minutes of recall against two `## Gaps` lists — same state, same label, same assignee, 2026-08-17.)

**And the lane admits only acts that are his — a DoD-complete agent deliverable is not one (APP-2046).** The estimate above sizes what sits in the lane; it does not test whether it belongs there. `In Review` + `human` on a child of a sign-off parent carries two opposite things: **(a)** an agent deliverable with every acceptance and definition-of-done box met, needing an operator review nobody owns, and **(b)** work genuinely waiting on a judgement only the Owner can make. Under APP-1352 — the Owner's ruling that the operator does the full assessment and brings him only the judgement calls — (a) is the operator's: it reviews the deliverable against its own criteria, moves the executor off `human` to `operator-<venture>`, and closes it, leaving the **parent** to carry the sign-off. So a completed deliverable enters the lane only where something in *this* ticket is the Owner's; where the next act is the parent's sign-off, the child closes and only the parent enters. Stated at the state so it binds every reader of the lane rather than one sweep: a lane read tests **completeness** as well as age — an item whose thread claims every box met is an (a), not a wait. (Worked case: MRP-55, delivered 2026-09-24, eleven days in the lane across three stand-ups that correctly declined to re-escalate it, then written into the committed cycle goal `mrp.cycle-goal.2026-W41` as *"the blocker on the opener"* — a committed plan built on a state one document read would have corrected. A review queue mixing (a) and (b) also reads as larger than the Owner's actual lane, which is itself the binding constraint. `[pulse-refine]` **where/how** call under the APP-1099 what/how split; the *what* it sits inside is APP-1352. APP-2046.)

**Pipeline (forward-moving funnel):** `Captured`, `Backlog` (= identified, not yet actioned), `Todo`, `Awaiting` (acted, ball in their court), `Active` (live back-and-forth), `Engaged` (resolved well), `Passed` (no fit / cold / withdrew), `Canceled`. Network oscillates (active and dormant) rather than completing — read warmth from the labels, not the column.

The bindings to `convention-ticket`:

* **Captured → `Backlog`.** New tickets the operator hasn't refined go in **Backlog**, not Todo. Todo means "ready to action." Don't move things to Todo on his behalf unless he's said it's ready.
* **Refined-and-parked → `Refinement`.** The human refinement gate, reserved for tickets needing the operator's input or deliberate go. Agents treat Refinement tickets as read-only, with the comment-since-last-agent-comment exception (see *triage*). A no-gap refined ticket parks here **unassigned**; one carrying a genuine question is assigned to Aled. **A refined leaf that is ready except for a sibling dependency is not parked here** — it is ready, so it goes to **Todo carrying a blocked-by relation**, never Refinement (see `convention-ticket` *Structure*). The builder skips it while the blocker stands and picks it up when it clears, so no manual re-promotion is needed.
* **Ready → `Todo`.** Only Aled promotes to Todo unless he's said otherwise. A ready-but-blocked ticket also lives here, carrying its blocked-by relation. **Invariant: a ticket in Todo under a delivery executor carries both literal headings, whoever put it there.** Those headings are `## Acceptance criteria` and `## Definition of done`, each with a checkbox list beneath. The check was written at the promoting acts: triage's route, the operator loop's promotion (`skill-operating-loop` step 6, APP-1327) and the claim gate (`skill-build-ticket` step 3b). So a ticket **created straight into Todo** passes none of them until a builder bounces it. Stated at the state, the check binds every writer that lands a ticket in Todo, a breakdown or filing leg included. Any sweep that reads Todo treats a leaf missing either heading as not ready and returns it to **Backlog** under `agent:R3-LAY`. **The floor is also satisfied by an explicit dated commissioning comment from the Owner or an operator, carrying the angle, the deliverable and the deadline — so a sweep reads the latest Owner comment before it bounces.** The invariant was written against tickets promoted with no brief at all, and it does not contemplate a full, dated brief living in a *comment* on a capture-type ticket whose own template structurally carries no acceptance-criteria or definition-of-done sections. Read literally against that shape, two canon rules collide: this floor binds every sweep to bounce, while `skill-fleet-dispatch` holds that eligibility is whether the input can be **obtained** and never whether the brief is good enough, and its enumerated tests say nothing about headings. The qualification is stated **here**, at the state, because stating it here binds every sweep that reads Todo — the same reason the floor itself is stated at the state rather than at each promoting act; a cross-reference from `skill-fleet-dispatch` is optional and nothing waits on it. Two things it does not do. It does not soften the floor into a refinement bar: the presence-not-quality reading below covers a commissioning comment too, which satisfies the floor by being present, dated and specific, never by being good. And it does not release a ticket with no brief anywhere — not in the headings, not in a comment — where the bounce stands exactly as before. (Worked case: on 2026-10-15 a fleet-dispatch sweep found a capture-type ticket resting in Todo with neither heading in its body, using its editorial template's own sections instead, and carrying in a dated Owner stand-up comment from the previous day the angle, the format, the deliverable and a review deadline. The sweep read that comment as the operative brief and dispatched rather than bouncing a ticket the Owner had hand-briefed minutes before; it landed In Review. The call was right and was a field judgement no rule stated, which is what this qualification fixes. The ticket's own body and comment are **unverified from this surface** — read only through that run's account — APP-2388.) It is the Todo-side twin of `convention-ticket`'s "an agent executor never rests in the refinement gate". It sets a heading-presence floor, not a refinement bar: what else a connector-fleet executor needs stays the open question in APP-810. (Worked case: on 2026-09-18 the MBN-297 breakdown created MBN-301 and MBN-302 straight into Todo and moved MBN-299 there. None of the three carried both headings, and MBN-302 carried no executor at all. The weekly BARA loop returned all three to Backlog at 11:20 — APP-1537.)

**A ready-but-blocked leaf rests in Todo whoever its executor is — a connector-fleet value included.** The rule above is executor-agnostic by construction, and it is restated here because it has been read as though it were not: the numbered placements in `skill-triage` are written around the `F0-RGE` / `human` / `R3-LAY` axis, so a refined leaf carrying a connector-fleet executor — `P1-XEL`, `R3-ACH`, `SO-N4R` and the rest — has been left resting in a backlog-type state and counted as an unrouted row on every poll. Once a leaf has a real executor and its only outstanding gap is a sequencing dependency, it belongs in **Todo carrying its blocked-by relation**, never parked: the executor self-skips while the blocker stands, which is the relation doing its job, and parking it instead hides a routed ticket inside the unrouted population, where every later sweep pays to re-derive a routing decision that was already made. The connector-fleet routing instruction's "leave it in Todo, unassigned" and this rule are the same placement seen from two sides, not two rules to choose between, and neither turns on which value the `agent` group holds. (Worked case: MBN-285, MBN-286, MBN-289 and MBN-294 — four children of MBN-284, filed in one sitting on 2026-09-12 — each already carried `agent:R3-ACH`, and MBN-308 already carried a formal `blocks` relation to all four, so each had cleared its routing decision and had a named blocker. All four still sat in Backlog on 2026-09-26, resurfacing as apparently-unrouted on every poll, until that day's triage run promoted them to Todo by analogy with the engineering placement table rather than by any rule that named their executor; the 2026-09-27 dispatch sweep then read all four in Todo, self-skipped on the standing blocker, and reported the shape as working as designed — APP-1791.)
* **A ticket in a cycle cannot rest in a backlog-type state.** Adding a ticket in `Backlog` or `Refinement` (`Backlog` or `Defined` on Mr Pritchard) to a cycle moves it to **Todo** automatically, and moving a cycle ticket back to a backlog-type state drops its cycle membership. Every refined-and-parked state on every delivery team is backlog-type (verified via `list_issue_statuses` on Apps, A1, MBN and Mr Pritchard, 2026-09-22), so a committed ticket has no parking state: it rests in Todo or a started state. The forward move is Linear platform behaviour, per Linear's own docs (*Team pages*, Backlog): *"Any issues here will be updated to active (To do) status if they're moved to a cycle"*; no setting is documented to switch it off. The reverse was observed on A1-451, 2026-09-21. Two consequences follow. First, committing a ticket is a state write: an untriaged ticket committed to a cycle lands in Todo without passing the Backlog gate, so the commit itself can breach the Todo invariant above. Second, that invariant's remedy — return a heading-less leaf to **Backlog** — would silently undo the Owner's commit on a cycle ticket. So a sweep reading Todo checks `cycleId` first and repairs a cycle ticket **in place** (`skill-triage` *Executor-presence sweep*). Taking a ticket out of a committed cycle amends the commit, which is the Owner's (*Labels*, cycle membership). (APP-1581, 2026-09-21; worked case: the W39 membership write force-moved seven tickets to Todo, five never triaged — APP-1583.)
* **Review → `In Review`** and sign-off → `Done` by Aled — see Pattern A in `convention-ticket`. **Done requires every box in *both* the `## Acceptance criteria` and `## Definition of done` sections ticked** (or struck with a recorded one-line waiver): the merge leg and Aled do not move a ticket to Done while any acceptance or definition-of-done box is unticked and unwaived. The `type:*` label selects which per-type template (skeleton + DoD) the ticket is instantiated from at refine — see `convention-ticket` *Per-type ticket formats*. This is the Linear binding of the Definition-of-Done rule in `convention-ticket`.
* **`Blocked`.** Set by the build leg when it hits an unresolvable blocker mid-run (no write access, a missing dependency or credential, a requirement too ambiguous to act on safely). The ticket leaves In Progress, carries `human` (the `agent`-group value), and is assigned to Aled, who clears it and moves it back to Todo. Distinct from a blocked-by relation (a genuine inter-ticket dependency). **Reserve Blocked for a genuine external blocker that separate work must clear.** An item whose *only* outstanding need is Aled's own review or sign-off — including an acceptance criterion that cannot be verified in the loop's environment but needs no further work, just his eyes — is **not** Blocked: it belongs in **In Review**, carrying `human`, assigned to Aled, escalated to **Urgent** only if it lingers. Routing a review-only item to Blocked mis-signals it as dependency-bound and hides it from the "In Review = awaiting your sign-off" surface (worked case: A1-129, 2026-07-06).

  **The unverifiable-DoD box — the test is "would separate work make it verifiable?", not "can the loop verify it?".** A ticket with every acceptance criterion met and one outstanding definition-of-done box the loop's environment cannot tick reads as ambiguous between the two states, and both `convention-linear` and `routine-delivery-loop`'s routing table have been applied to it with opposite results — A1-216 and A1-217 sat in Blocked from 2026-07-15 on a reading that no pass then corrected. The distinguishing question is not whether the *agent* can tick the box, which it never can; it is whether **anything other than Aled's judgement would change that**:

  - **Nothing would — only his waiver clears it** (an "it looks right" judgement, a call no instrument can make). → **In Review**, `human`, assigned, escalating by age. This is the `routine-delivery-loop` *operator-verify-only clean pass* route, and it is the same review-only rule as above. **An item whose only outstanding need is the Owner's own waiver or sign-off carries `human` in the `agent` group and the Owner as assignee** (Owner ruling, 2026-10-20 — the A1-656 / A1-679 session words, *"it is either with relay or with me (and therefore a human label)"*, become the standing reading; reported via Aide in the `APP-2279` form; `APP-2432`). The executor value is **not** cleared and the judgement is **not** routed to `operator-<venture>` under *Operator attribution* below: an Owner waiver is not a judgement an operator can make, so that route is reserved for a judgement an operator actually can, and the two readings cannot compete again. And the executor value is **re-derived at each transition from whoever holds the ticket next** — a slice started on a fleet value that passes to the Owner *becomes* `human` at that moment, whatever instruction was given at claim time, because an ad-hoc claim-time instruction to keep a label does not survive a hand-off. Distinct from `APP-2381`, whose fix covers a ticket already carrying `human` being told to set a review label.
  - **Separate work would** — the box is unverifiable because an *instrument is missing* (the repo has no CI, a credential is unset, an environment is unreachable). → **Blocked**, `human`, assigned, **carrying a blocked-by relation to the ticket that installs the instrument** — filed if it does not exist. Blocked without that relation is the failure mode: it reads as dependency-bound while naming no dependency, so nothing ever clears it and nobody can tell the two cases apart.

  * **Another surface would — the criterion is verifiable, just not from this leg's surface.** No instrument is missing and nothing needs excusing; the box simply cannot be ticked from where the leg is running — a criterion naming one runtime while the loop executes on another, a rendered-surface check on a leg with no browser. → **Route the criterion to the surface that can verify it**, via `skill-fleet-dispatch` / `skill-dispatch-run`, carrying the criterion verbatim and the skill that tests it. Not a waiver (nothing is excused) and **not Blocked** (no instrument is missing): the ticket stays in its lane and only the leg changes. This is the reconciliation of the two-way split above with APP-618's rule already in this file — *"the Forge CLI lacks the MCP" is not "Claude lacks it" … route such work to the surface that can do it* — which the split predates and was never squared with. (Worked case: APP-1130, a spike whose acceptance criterion required proof "on at least one live scheduled Cowork run" while the delivery loop was executing on scheduled Claude Code remote. The run could do every substantive step and could not, structurally, ever tick that one box — not for want of effort or an instrument, but because it was running on a different runtime from the one the criterion named. It was routed to In Review on `human` as a judgement call made without a rule, and the same evidence would have supported Blocked. APP-1136.)

    **And a spike marks surface-derived observations as unconfirmed rather than asserting them.** An observation carried into a ticket from an interactive session on another surface — a transcript field name, a metric's definition — is written as *to be confirmed*, not as settled fact: refine cannot tell the two apart, so a false given propagates into acceptance criteria unchallenged. (APP-1130's notes asserted a transcript field `attributionSkill` that does not exist in the current format, and defined `cold_start_tokens` in a way that under-reads it; both were written from an interactive session elsewhere and carried in as fact — APP-1136.)

  A waiver routes around a missing instrument; it never replaces one (APP-555, APP-568) — so the second case is where the instrument gets ticketed rather than quietly waived every time. Distinct from who *owns* the waiver (APP-568) and from how the criterion should have been written so a machine could tick it (APP-555, APP-579); this is only where the ticket rests while it is outstanding. (APP-620.)

## Escalating a stalled decision item — by age, not repetition

A surfaced decision item that sits unanswered — a human-decision ticket assigned to Aled, or a canon note awaiting his call — **escalates by age; it never collects repeat comments.** The comment-idempotency guard in `skill-triage` / `skill-coordinate` already stops the re-posting: once a standing recommendation is on the ticket and nothing material has changed, the sweep stays silent. But silence is only half the remedy — an item left silent is an item going nowhere. So as a surfaced decision item ages unanswered, the surfacing skills escalate it. The two are compatible, not in tension: the idempotency guard governs *comments* (don't restate), this ladder governs *priority and state* (do escalate).

0. **Confirm the item is still live before escalating it.** The ladder amplifies; it must not amplify a dead item. Where the item's stated justification is a claim about a connector-held resource — store state, calendar, inbox, scheduler — re-verify it against the connector before raising anything. Where the state has moved, correct the record and withdraw or restate the recommendation instead of escalating it; the idempotency guard is what stops anyone re-checking, so this step is written explicitly. (MBN-250's "hide the three bundles" was moot when written and would have climbed to Urgent on age — APP-990.) **And read the ticket for a stated hold before raising priority on age.** The limb above asks whether the external world moved; this one asks whether the ticket itself already says why it is waiting. Before the ladder raises anything, read the body for a **stated hold** — a *Blocked until* section, a dated bundling decision, an Owner note naming the condition the item waits on — and where that hold is still live, treat it as the reason age has not moved rather than as the defect age is evidence of. **Age is evidence of a stall only where nothing in the ticket explains it.** Where the body explains it, escalating converts a deliberate wait into a false Urgent and pushes the genuine queue down the brief. Where the stated hold has expired or its condition has been met, the item is live again and the ladder applies normally; where the hold is live, leave priority alone and say so in no comment at all — the idempotency guard still governs. (Worked case, as reported: MBN-270 was escalated to Urgent on age while its own body recorded a deliberate 2026-09-01 hold to bundle the publish with the rest of Phase 1; caught and reverted in the same run — APP-1212.) **And read the owning project's `status` before raising priority, because a hold expressed at project level is invisible to every ticket-level rule.** The two limbs above ask whether the external world moved and whether the ticket says why it waits. Neither reaches the commonest hold of all: the Owner parks a **bet**, which is a decision recorded once at the right altitude, on the project — and the tickets beneath it say nothing, correctly, because the hold is not theirs to state. So a ticket under a parked bet passes both limbs honestly and climbs the ladder on age. Before the ladder raises anything: read the owning project's `status` field directly — every issue carries `projectId` and every project carries `status`, so one `get_project` per distinct project answers it, batched per project and never per ticket — and treat a project on **`Hold`**, or in any paused-type or terminal status, as **a stated hold covering every ticket beneath it**. Leave priority alone, write no comment (the idempotency guard still governs), and note the project status as the reason age has not moved. **Never propagate a hold label onto the tickets** (Owner decision on APP-1651, 2026-09-22): the status field is the one always-current source, and a label needs something to apply *and* remove it in sync with the status changing, which is the double-bookkeeping this system avoids. Where the project comes off Hold, the item is live again and the ladder applies normally. This is the **write-side** counterpart of the read-side rules already in canon — the target-date rule under *Reading Linear safely* below, which governs dates and not age, and `skill-build-ticket`'s candidate-**eligibility** exclusion, which governs selection and not priority — and the gap was precisely that neither of those touches the ladder, which is the thing that actually writes priority to the board and pushes items up the Owner's brief. A false Urgent on a deliberately parked bet is not a neutral error: the brief is priority-ordered, so it displaces genuine queue items, and it converts a decision the Owner has taken into a question that reads as unanswered. (Worked case: the `task-apps-operator-loop` delta run of 2026-09-23 escalated APP-1570 High → Urgent on age and reverted it nine minutes later on discovering `app.Luna` had been moved to **Hold** by the Owner on 2026-09-21; the run followed canon at every step — APP-1570's premise was true and its own body states no hold, because the hold is on the project. The precondition existed in canon exactly once at the time, in `skill-portfolio-allocation` Pass 1's *no date escalation* for an inactive bet, which a single-outcome operator never opens. APP-1676, the write-side limb of APP-1651 and the same shape as APP-1212 above.)
1. **Route to the operator first, the Owner second.** A judgement item carries `operator-<venture>` and escalates to `human` + Aled only on age or at the mandate's edge; that second rung is what the ladder lacked when six of seven Forge tickets sat behind human-lane blockers with nowhere further to climb (APP-723).

   Two live classes start below High on purpose — a gap ticket on a parked bet held at Low by the APP-978 carve-out, and a small isolated gap on an otherwise complete cascade raised at Low deliberately — so a ladder whose first rung is High converts a considered Low into a false High on the first escalation. One rung at a time keeps the ladder a direction rather than a jump. (Worked case: APP-1040, one KPI line on the workspace's most complete cascade, was moved Low → Medium by judgement on the 2026-09-14 review because the ladder as written offered only High; the judgement was right and the re-derivation is what this clause removes — APP-1422, the same shape as APP-689 and APP-978.)

   Then **raise priority as the wait lengthens — one rung per escalation, from wherever the item sits**, with **High** and **Urgent** as the named upper rungs rather than the only ones — so the item climbs the brief rather than restating itself in a fresh comment.
2. **Flag its age in the daily brief** — `task-daily-report` surfaces a long-waiting operator item with how long it has sat ("sitting N days"), so the wait itself is visible without a new comment on the ticket.
3. **Move to Blocked only if it has genuinely become a blocker** for other work — not as a substitute for the priority ladder. A decision-only item that blocks nothing stays in **In Review** / **Refinement** on `human` (per the Blocked rule above); Blocked is for a real dependency, not for "this has waited a while".

This is the second half of the APP-384 idempotency fix: that guard stopped the noise, this defines the signal. Escalate the priority and, where warranted, the state; never re-post the same comment. (Operator instruction, Aled 2026-07-13, on APP-325 — three near-identical "decision needed" comments across 14 days before the decision was taken.)

## Labels

Every ticket carries the labels that classify it.

**Type:** `epic`, `feature`, `story`, `task`, `bug`, and `spike` — **all passed bare, none prefixed.** The type value also **selects the ticket template** — its section skeleton and its standing definition-of-done — which the author pastes in at refine (see `convention-ticket` *Per-type ticket formats*). They are displayed as `type:task` in the Linear UI because they are grouped labels under a `type` parent, but the **name the workspace holds, and the only string `save_issue` resolves, is the bare one**.

**Passing the prefixed form fails — and how it fails changed.** `save_issue` now **rejects** `type:task` outright rather than dropping it silently; earlier the same call swallowed it, which is worse. Either way the remedy is the same: pass `task`, `epic`, `feature`, `story`, `bug`, `spike`. Verify against a live ticket if in doubt — a read shows the true names (`["task","PUL-5E","work:configuration"]`). This convention previously documented the prefixed form as correct for everything except `spike`, which sent every author down the failing path. (Worked case: `task-fleet-dispatch` run, 2026-07-18, hit the rejection while filing its own friction note — APP-587.)

**`spike` is passed bare, like every other type value.** The label was added to the workspace by Aled on 2026-07-02 for APP-419; the convention entry is APP-420's drain. It was documented then as the *exception* to a prefixed `type:*` set — the whole set is bare, so it is simply the rule (APP-587). A spike is a time-boxed investigation whose deliverable is a decision record and follow-on tickets, never a merged PR — the format and routing live in `convention-ticket` *Per-type ticket formats*.

**So the naming debt is now in one group only, the workstream group** — `engineering` bare against `work:*` prefixed (below). The `type` group is uniformly bare.

**Every group's value is passed bare — `agent:PR-1SM` in prose names the group and the value, and is never a string to write.** Canon, skill text and ticket bodies all write the executor as `agent:PR-1SM`, `agent:R3-LAY`, `agent:F0-RGE`, because that form names the group as well as the value and the Linear UI displays it that way. The workspace stores the leaf alone: a `list_issue_labels` read on A1 returns `PR-1SM`, `F0-RGE`, `R3-LAY`, `PUL-5E` and `human`, each with parent `agent` and no prefix in its own name. So `save_issue(labels: ["agent:PR-1SM", …])` is rejected — *Could not find label "agent:PR-1SM" for labels* — and because the call is atomic, the `patch`, `state` and `assignee` writes bundled with it are lost with it (*Single-select* below; *Writing Linear safely*). The read-side twin is already stated under *Reading Linear safely*: the label filter takes the bare value too. **This binds hardest on an instruction a ticket body hands an agent to follow verbatim.** An `## On completion` line reading "move the ticket to In Review, set `agent:PR-1SM`, leave unassigned" is a routing instruction in this convention's shorthand, not a literal label argument: read it as "set the `agent` group to `PR-1SM`", and where such a line is authored fresh, write the bare value. (Worked case: the A1-570 dispatch-run, 2026-09-30, took its own `## On completion` line literally, had the whole `save_issue` rejected, and had to re-send the checkbox patch in a second call after retrying with `PR-1SM`. APP-179 fixed the same mismatch for the loop's label *scans* in June; the write-time reading of ticket prose was not covered — APP-1882.)

**Executor:** one value from the `agent` **single-select group** — there is no separate executor label. Human-owned work is the value `human` in that group; functional-agent work is one of the branded agent values. **Operator ownership is not an executor value.** Since 2026-09-03 the lowercase `operator-<venture>` values live in their own **`operator` label group**, set independently of the `agent` group, so a ticket states two facts at once — *who executes* (`agent`) and *which vertical's operator owns the outcome* (`operator`) — and a ticket may carry `PUL-5E` + `operator-a1`, or `F0-RGE` + `operator-bara`, without either evicting the other (Owner decision, Aled 2026-09-03, APP-1103; see *Operator attribution*). **`human` means "no agent can do this", and nothing else.** A credential only the Owner holds, a physical device, an Apple account, a design master he must draw — those are `human`, assigned to Aled. A fail-safe that needs **a judgement** — is this blocker real, should scope bend, is a third attempt worth it, does this CI failure need a call — routes to the owning vertical's `operator-<venture>`, not to `human`: the operator is the gate within a vertical (`core-operating-model`, Layer 3), the daily stand-up reads that queue as its primary input (`skill-operating-loop`, *The two cadences*), and the Owner is the second hop, reached on age or at the mandate's edge. The test at the point of routing is one question: *could any agent with the right mandate decide this?* If yes, it is the operator's. The five categories the Owner fixed on 2026-09-03 make that test concrete: **strategic context** (does this criterion earn its delay, does this scope change alter what is measured), **how and where** (placement, sequencing, delivery shape, mechanism where canon already leans) and **prioritisation within the mandate** route to `operator-<venture>`; **human faculties** (eyes on a rendered surface, a credential, host or physical access, anything irreversible or public) and **authority** (money, a mandate change, security posture, real-consequence accountability) route to `human` + Aled, always. The routing comment names the category and the question; the operator decides it where the consequence is in-vertical, reversible or bounded in cost, and on-mandate, and otherwise forwards it naming the failed test (`skill-operating-loop` step 5; `convention-comms-owner`, *The forward format* — APP-962). (Owner instruction 2026-08-22, ruled for all five operators 2026-09-02: six fail-safes across `routine-delivery-loop`, `skill-build-ticket` and `skill-merge-pr` had one destination, so throughput and escalation shared a lane and autonomous throughput was capped by where the fail-safes pointed, not by capability — APP-1035.) The `agent` group is single-select, so setting one of *its* values evicts the previous: `human` evicts the `R3-LAY` triage marker exactly like `F0-RGE` does. That eviction is the **executor axis only** — `operator-<venture>` lives in its own group and evicts nothing, so routing a judgement to the operator is a separate write, not a relabel of the executor (*Operator attribution*).

* `human` — decisions, design, launch ops, anything human-owned. (Label `human`, parent `agent`. This replaced the retired `exec:human` label, which has not been in use for a long time; treat any lingering `exec:human` reference as meaning the `agent`-group `human` value.) **Work that needs an MCP the Forge CLI lacks (e.g. a Figma export) and is realistically a one-off manual action defaults to `human` + assigned to Aled**, not to a runner-less agent value: a ticket parked on a value that no delivery loop or scheduled runner picks up looks routed but stalls unowned (worked case: A1-124, an `agent:claude` Figma export that sat in Todo and bounced to Backlog with nothing to run it, 2026-07-06). **But "the Forge CLI lacks the MCP" is not "Claude lacks it" — check the other Claude surfaces before defaulting to the operator.** The Cowork connector surface holds Chrome, Figma, Gmail, Calendar and computer use, and the fleet-dispatch path (`skill-fleet-dispatch` / `skill-dispatch-run`) exists precisely to run connector-surface work — a Figma export, a browser-based runtime check, a preview inspection are *dispatchable*, not the operator's. Route such work to the surface that can do it and reserve `human` for what genuinely needs Aled: approval or judgement, an account / billing / credential action, anything irreversible or public, and physical-world steps. Offer the agent hand-off first and manual steps only as a fallback, and never route the operator to a terminal for a command a Claude surface holds. Defaulting to `human` on one surface's limit generalises a capability gap into a Claude-wide one and lands avoidable work in the human lane — the binding constraint (APP-575). (Worked case: A1-116's PostHog runtime verification sat Blocked on the operator on the stated grounds that "no sandbox has a live browser" — true of the Forge CLI, false of the Cowork surface's Chrome tools — APP-618.) The rule runs the other way too: **a remedy or evidence constraint states the surface it assumes**, and where the executing leg does not hold that surface it is not an option for that leg. "Re-read the passage in the Linear UI" is a human-at-a-browser remedy; a `skill-dispatch-run` leg reads documents through `get_document` only and has no UI to re-read from, so an instruction offering that as one of two options offers it one (MRP-47, 2026-08-18 — APP-1015).
* `agent` **group (single-select)** — which executor owns the work (the former `exec:agent:*`, `exec:human`, and `author:claude-code` labels were retired and folded here). This enumeration **must agree with the `core-fleet-roster` fleet table** — reconcile both whenever the fleet changes:
  * `agent:R3-LAY`, `agent:F0-RGE`, `agent:PR-1SM` — the triage / build / review roles of the delivery loop (the routing pattern in `convention-ticket`, bound to Linear here)
  * `agent:SC-0UT` — Scout, the pipeline agent: captures people and opportunities into the Pipeline team and keeps them clean. It works the Pipeline funnels (*The Pipeline model* above), not the delivery projects, so it never appears in the Relay / Forge / Prism loop.
  * `agent:PUL-5E` — Pulse, the ops / self-improvement agent. Owns the **friction queue** (below): it does *not* execute delivery-loop work, so a ticket carrying it is propose-only intake, not a build candidate. Setting it on a Backlog ticket (in place of the `agent:R3-LAY` default) is what keeps that ticket out of the Relay→Forge loop.
  * `agent:SO-N4R`, `agent:P1-XEL`, `agent:R3-ACH`, `agent:DR-4FT` — the commercial fleet: Sonar (design strategy, discovery & service design), Pixel (brand & design system), Reach (marketing & GTM), Draft (writing: copy, UX writing and long-form drafting). Run on the connector surface (Figma, Gmail, Shopify) via the fleet-dispatch path, not the Forge delivery loop.
  * `agent:ATL-4S` — Atlas, planning and cross-operator portfolio arbitration. **One slice live** — cycle review and commit proposal (propose-only on cycle membership; `agent-atlas`, APP-629); the rest of its composition stays future. Its ceremony is the self-contained connector-surface task `task-cycle-planning` (APP-429, APP-630) — a process, not a skill, and not driven by a routine; authored, and until its schedule is wired the live slice runs only when invoked by hand.
  * `operator-<venture>` (lowercase) — **not an `agent`-group value since 2026-09-03**: the five operator values were re-parented into their own `operator` group (no ticket lost its value — APP-681 retained `operator-bottrader`). They are listed here only so the enumeration stays complete for a reader of an old ticket; the group itself is described under *Operator attribution* below and `core-operating-model`, Layer 3. Lowercase like `human`, not branded like the functional fleet, so agent-vs-operator-vs-human still reads at a glance (APP-1103). Live values: **`operator-bara`** (Made by — Neud / BARA), **`operator-bottrader`** (bot.Trader — one operator holding two mandates, Path A platform/gauntlet and Path B agent, reported separately; APP-541), **`operator-apps`** (the Apps accelerator — a *portfolio* of careerOS, app.fitness, Luna, os.Claude and GTD; allocates fleet capacity across bets) **`operator-a1`** (the A1 practice plus its live client engagements) and **`operator-mrp`** (Mr Pritchard editorial — AI-filled, mandate from the Mr P charter MRP-18). One value is one *operator*, not one mandate.
  * `A1-DE` — **Aide**, the Owner-serving personal chief-of-staff (`core-fleet-roster` *Owner-serving agents*): sweeps Aled's committed cycle for what needs him and books his hold-window time. Reads Linear (read-only), writes only his calendar — a personal / Owner-serving role, distinct from the functional fleet and the vertical operators. MVP, not yet built (blocked on the APP-428 planning-and-time layer); carried in the enumeration because the live `agent` group already holds the value.
  * **Legacy tool-era values — `agent:codex`, `agent:gpt`, `agent:replit`.** Holdovers from when work was routed by which tool would run it (Claude vs Codex), before the role-based fleet. They map to no current role, should not be set on new work, and are retired from the workspace `agent` group once no open ticket carries each. `agent:claude` was the same class — retired 2026-07-06, removed from this enumeration, and its open work re-routed (e.g. an MCP-only export → `human`; a discovery audit → `SO-N4R`).
* **Single-select:** an issue carries exactly one `agent:*` at a time; setting a new one evicts the previous, so a handoff is just setting the next role. **But the eviction happens only through `save_issue`'s `labels` parameter, which is a full replace — `addLabels` does not evict, it errors.** `addLabels: ["PR-1SM"]` on a ticket carrying `F0-RGE` returns `400 invalid_request` — *"The label 'F0-RGE' is in the same group as 'PR-1SM'. Only one label in a group can be applied to an issue."* — and because the whole call fails, the state, assignee and relation changes bundled into it are lost too, so a run whose comment says the ticket was routed has written nothing. Every `agent`-group write — a triage route, the exec hand-off, a QA route, a Blocked fail-safe, an operator hand-off — is therefore made with `labels: [...]` carrying the **full** label set: re-read the ticket's current labels immediately before the write, swap only the `agent`-group value, and restate every other label exactly (the bare type label, the workstream label, any `cycle:` or `domain:` label). Getting that list short drops the others silently — the same silent-drop class as the `work:engineering` trap above, arriving through the remedy. `addLabels` is safe only for adding a label from a *different* group or one with no group; the tool schema's own advice to prefer `addLabels` for incremental changes is wrong for this group. `removeLabels` + `addLabels` in one call **works** — the 2026-09-09 run tried it and the pair, issued in a single `save_issue` call, removed the sitting `agent`-group value and applied the new one without the group-collision rejection; the removal is applied before the addition, so the two values are never both present. That is the datum this line asked for. **The full-replace `labels: [...]` form stays the documented one**: it is correct for every `agent`-group write, it needs no reasoning about ordering inside the call, and because it restates the whole label set it cannot drop a sibling by omission. The tested pair is the **narrower alternative** — where a run is confined to swapping the one grouped value and has *not* re-read the ticket's other labels, `removeLabels` + `addLabels` swaps that value without asserting the rest of the set, which is the safer shape for exactly that case. Either form is fine; `addLabels` **alone**, on a value whose group is already occupied, is still the rejection above. (Worked cases: the A1-380 exec hand-off, 2026-09-03 — APP-1102; six Backlog→Forge routes on A1-382–387 in the 2026-09-04 triage pass, every call rejected and re-issued as full `labels` arrays — APP-1116.)
* `labels` **and** `addLabels`**/**`removeLabels` are mutually exclusive parameters — the exclusivity is about the *call*, not about the groups (APP-1319). The rule above is about a group collision: `addLabels` on a value whose group is already occupied is rejected. There is a second, independent rejection one level up. Passing `labels: [...]` **together with** `addLabels` or `removeLabels` in the same `save_issue` call fails outright — `Error: labels cannot be combined with addLabels or removeLabels` — whatever groups the values belong to, and even where the `addLabels` value is a perfectly safe add from a different group. The two shapes are alternatives, never composable: either you assert the whole label set, or you mutate it incrementally. And because the whole call fails, any state, assignee, comment or relation write bundled into it is lost too, exactly as in the group-collision case above — so a run whose comment says the ticket was routed has written nothing. **The shape this bites is the common one:** a triage or coordinate write that swaps the `agent`-group value *and* adds an `operator-<venture>` label in the same pass — a hand-off, or a connector-fleet route with an operator tag. *Operator attribution* below correctly says setting `operator-<venture>` evicts nothing and is an `addLabels`-safe write; that is true of the value and false of the **pairing**, and the two facts read as one unless this is stated. So for a write that touches both groups at once: **fold the operator value into the one** `labels` **full-replace array** — re-read the ticket's labels, swap the `agent`-group value, add the `operator-<venture>` value, restate every other label exactly — rather than pairing `labels` with `addLabels`. Where a run has *not* re-read the ticket's other labels, the tested narrower alternative applies unchanged: `removeLabels` + `addLabels` in one call, which may carry the operator add alongside the `agent`-group swap because neither parameter is `labels`. (Worked case: MBN-277, routed to the connector fleet on 2026-09-11 — first call `labels: ["task","domain:MBN","work:content-data","R3-ACH"]` plus `addLabels: ["operator-bara"]`, rejected on the parameter exclusivity; retried as a single `labels` array including `operator-bara`, succeeded. The tool schema states the exclusivity; canon did not — APP-1319.)
* **Backlog default:** a ticket entering Backlog carries `agent:R3-LAY` so Relay triages it; the executor (`agent:F0-RGE` etc.) is set by Relay at routing, not at creation. Pre-assigning an executor at creation skips the triage gate. **Exception — canon-improvement work in os.Claude:** a canon-change intake ticket — a `FRICTION:` capture note, or any ticket whose deliverable is a saved `.skill` (a skill, convention, agent or operator edit) — enters Backlog carrying `agent:PUL-5E` (never `agent:R3-LAY`), deliberately bypassing delivery-loop triage; the Pulse retro drain processes it. `R3-LAY` is not excluded from os.Claude — it still owns ordinary delivery triage there; it simply does not own canon improvement (Pulse does). **A `PUL-5E` note never carries an operator-owned action.** Since 2026-09-03 setting `operator-<venture>` evicts **nothing** — the value sits in its own group beside `agent:PUL-5E`, so the note keeps its Pulse executor and stays in the drain, and the operator-owned action rides along inside a ticket that is *drained, never delivered*. No delivery leg ever picks such an action up, and ownership recorded only in a comment is invisible to every sweep (APP-685). (The retired reason — that setting the operator value evicted the note from the drain — described the pre-APP-1103 single-select shape; the rule survives its reasoning.) Split the action out as its own ticket in the vertical's project carrying `operator-<venture>`, and where the canon change waits on it, relate the note `blockedBy` that ticket. (The interim on APP-613 and APP-963 — `PUL-5E` kept, assignee cleared, operator named in prose — is the shape this rule replaces; 2026-09-03, APP-962.) See *os.Claude Backlog routing by work type* below. **The default binds at creation, on every surface that creates a ticket.** It is not a property of the triage and refine paths that happen to apply it: an in-session build pass, an operator working by hand, and a product's own Linear-write path are all creating surfaces, and none is exempt — the default exists so Relay can see the ticket at all. **An author's prose note that a ticket is "capture only" is not an exception to it.** A ticket nobody routes is a ticket nobody reads, so the honest shape for deliberately-unplanned capture is the default label *plus* the capture note in the body, letting triage park it — never the absence of a label. The `PUL-5E` carve-out above stays the only exception. Worked case `APP-2477`: two app.Triage leaves were filed into Backlog on 2026-10-19 carrying `operator-apps` and a `type` value and **no `agent`-group value at all** — `APP-2428`, a FIX, backfilled `agent:R3-LAY` the next day as ordinary hygiene, and `APP-2462`, a SCOPE whose own Notes read *"Capture only. This is not on the current build plan."*, left unrouted. Both were caught only because a daily operator stand-up's carry-set read walks Backlog directly. Distinct root from `APP-2270` and `APP-730`, which are a no-executor ticket surviving *past* Backlog into Defined or Todo and so invisible to the carry and review-queue reads; this is the gap at creation, in Backlog itself.

**Workstream:** the group is `work`, but the labels are **not uniformly named** — pass the exact name the workspace holds, not a guessed prefixed form. `engineering` is a true grouped label (parent group `work`, bare name `engineering`), so it is passed as **`engineering`**, not `work:engineering`. Every other workstream label is a **flat label whose full name carries the prefix**: `work:product`, `work:experience`, `work:ai-behaviour`, `work:content-data`, `work:configuration`, `work:infrastructure`, `work:analytics` — passed exactly as written. Passing `work:engineering` (the prefixed form for the one grouped label) matches nothing and is **silently dropped** by `save_issue` — no error, caught only by reading the write-back (worked case: 2026-07-01, APP-406). This is the same silent-failure class as the read-filter traps in *Reading Linear safely*; until the taxonomy is normalised (all flat, or all grouped) the exact names above are what to pass. Normalising the `engineering` label to match the flat `work:*` naming is a workspace-config tidy worth doing, but the doc records the live names meanwhile.

**Cycle membership: planned versus unplanned is derived from structure — and `cycle:unplanned` is retired (Owner ruling, Aled 2026-10-19T09:44:52.436Z, `APP-1788`; the derivation as stated in `task-cycle-planning` Step 1, `APP-2400`).** With cycle automation switched off on the delivery teams (Owner decision, Aled 2026-09-03, `APP-1007` — *Active issues & due date* off on Apps, A1 and MBN; *Completed issues* stays on), being in a cycle is a decision rather than a side effect of status, so the planned/unplanned split has to be measurable — and it is measured by **derivation**, never by a label. Three rules. **(1) Planned is the committed list.** The definition of *planned* for a cycle is the ticket list in that team's per-cycle goal document (`<team>.cycle-goal.YYYY-Www`, *Documents and the decision log*); the Owner's write of that document is the commit, and nothing else is (`APP-1095`). **(2) Membership is set by commit or by coordinate, never by automation.** A ticket enters a cycle either on the committed list, or by `skill-coordinate`'s Pass 7 add — a started ticket with no cycle is added to the current cycle; no Linear automation adds or carries work, and a `PUL-5E` note is never added at all (*Never in a delivery cycle*). **(3) Nobody labels it — not at the door, not anywhere.** *Unplanned goal-serving* work is every ticket created after the commit's `commit_ts` and before the window closes that serves the goal **by structure**: it sits in the goal's project (`basis: project`), is a child of a committed ticket (`child`), or carries a blocks, blocked-by or related relation to one (`relation`) — taking the first that holds, in that order. The share is `unplanned ÷ (committed + unplanned)`, and it is null where there was no commit or no goal-serving work; standing-target tickets are planned by construction and are never counted here. `task-cycle-planning` reports it per team at each boundary, and `skill-plan` reads a rising share as a planning signal, not a delivery one. **The label itself is retired from this registry and is not to be created.** It never existed: `list_issue_labels(name: "cycle:unplanned")` returns an empty set with `hasNextPage: false` (read 2026-10-20, control-tested against `work:configuration`, which returns one row), so no ticket has ever carried it and no figure was ever derived from it. The Owner left whether the label itself was retired to the drain; the label is retired from canon rather than created in the workspace, so the standing config action above it is withdrawn and no Owner lever is outstanding here.

**Dispatch markers — `dispatch:attended-only`.** One label sits outside every group above and is named here so it has a home in the taxonomy rather than living only in the skill that tests it: **`dispatch:attended-only`**, a flat label with a colon in its name and no parent group — the `work:*` shape, not the grouped `type` / `agent` shape, so it is passed as the literal string `dispatch:attended-only`. It marks a ticket that can only be completed in an **attended** session, because its one write path is an approval-gated connector call, and `skill-fleet-dispatch` tests for it in the compact `list_issues` read that already carries the labels — one label test per sweep instead of a comment-thread re-read. It is set once, on a ticket confirmed to need an interactive run, by the owning `operator-<venture>` leg or by whichever leg recorded the gated-call stop, and it is never inferred from prose. **The label does not exist in this workspace yet:** a full `list_issue_labels` read on 2026-09-25 returned the complete set with `hasNextPage: false` and no `dispatch:` label of any kind, so the first setter creates it — and until one does, the attended-only test is a read with no writer and no label. It can only ever return false, and the tickets it exists to protect re-derive "must run attended" from an old comment thread on every sweep. That is the same failure shape as `operator-<venture>` before APP-1217 — canon defining a read against a label nothing sets — and it is what A1-344 has cost five sweeps running: APP-1642 named setting the label as the ticket-side half of its own change, its canon-side half drained on 2026-09-23, and the label was still unset when the sweeps of 2026-09-24, 09-25, 09-26 and 09-27 each re-derived the same disposition from two 2026-08-18 comments (APP-1713).

**Dispatch markers — `dispatch:operator-instruction`.** The second flat marker, in the same shape and for the same reason: a colon in its name, no parent group, passed as the literal string `dispatch:operator-instruction`. It marks a **leaf deliberately carrying `operator-<venture>` and no executor** — a ceremony-filed operator instruction, set by `task-cycle-planning` at filing, in the vertical's home delivery team, so that it reads first in the operator-routed queue the operator's daily pass takes before anything else. `skill-triage`'s executor-presence sweep is its tester, and the test is **structural, on the label, never a read of the body's prose**: a leaf in Todo carrying this marker is a valid held state, takes no repair and no `agent:R3-LAY`, and keeps the label. Without the marker such a ticket is indistinguishable from one authored straight into Todo by oversight, which is exactly what that sweep exists to catch — so the sweep repairs it, and repairing it reintroduces the up-to-seven-day lag `APP-2100`'s design removed, an `agent:R3-LAY` ticket waiting on the Backlog/Todo triage poll's own cap and rotation rather than on the daily operator read. Three live instances stood in the colliding shape when this was written — A1-674 (2026-10-12, its body stating that the absence is deliberate), A1-718 and MBN-336 (both 2026-10-19) — and the `task-triage` run of 2026-10-20 correctly **held** all three rather than repairing against a stated, dated design intent, which is the ambiguous-and-consequential hold-and-ask case working as written. Defined here and tested in the skill is the same division `dispatch:attended-only` was introduced for, for the same stated reason: one label test per sweep instead of a prose read a worker must interpret. The label does not exist in this workspace yet, so the first filing creates it; until the three instances above carry it they are reconciled **by applying the marker, never by repairing them to `agent:R3-LAY`** (`APP-2475`, `APP-2100`).

**Pipeline-specific (on Network / opportunity issues):**

* Contact type: `contact:network`, `contact:reconnect`, `contact:loose`, `contact:recruiter-internal`, `contact:recruiter-agency`
* Opportunity mode: `opp:advisory`, `opp:fractional`, `opp:consulting`, `opp:fulltime` — applied only when signalled
* Warmth: `warmth:warm`, `warmth:cool`, `warmth:cold`
* Role stage (Roles issues): `stage:applied`, `stage:screen`, `stage:interview-1`, etc.
* Surfaced markers: `surfaced:role` / `surfaced:advisory` / `surfaced:pitch` / `surfaced:done`
* Reporting: `reporting:contact`

A typical engineering ticket carries one `type:`, one `work:`, and one `agent`-group value — `human` or one `agent:*` (`agent:R3-LAY` while in Backlog; the real executor set at routing). A Network contact carries a `contact:*`, `reporting:contact`, `task`, and an `opp:*` only where a mode is known.

`author:*` marks who *created* something; the execution axis is the `agent` group.

## Operator attribution

An **operator** (`core-operating-model`, Layer 3) owns a vertical and is represented on the board by a lowercase `operator-<venture>` value in its own **`operator` label group** — five values, `operator-a1`, `operator-apps`, `operator-bara`, `operator-bottrader`, `operator-mrp` — a domain role, deliberately not droid-branded. The group is **separate from the `agent` group and the two are set independently** (Owner decision, Aled 2026-09-03, applied in the workspace the same day, APP-1103): two facts were competing for one field — who executes, and which vertical's operator owns the outcome — and the moment a ticket needed an executor *and* an operator it must query before proceeding (APP-962), one single-select group could not hold both. **The reading rule:** the executor is read from the `agent` group, the owning vertical from the `operator` group; neither is inferred from the other, and an operator sweeps its own work by its `operator` value **across teams**, not by project (an os.Claude canon note carrying `operator-a1` is A1's to see). There is **no `owner` group**: the Owner has a Linear account, so "waiting on Aled" stays the native assignee field, and `human` stays in the `agent` group as a genuine executor value ("Aled does this"), distinct from "Aled decides this" (assignee plus the APP-962 forward format, sized by the estimate — APP-1003). Rules:

* The value marks work the **operator owns and is accountable for** — typically an epic or initiative-level ticket for its vertical, or a ticket it is driving. It does not replace the functional executor on a build leaf: when an operator dispatches build work through Relay, that leaf still carries `agent:R3-LAY`→`agent:F0-RGE` in the normal way. The operator value sits on the *owning* ticket, not on every leaf beneath it.
* **Setting `operator-<venture>` evicts nothing.** It sits alongside whatever `agent`-group value the ticket carries; setting it is an `addLabels`-safe write (the value has no `agent`-group sibling), and it is never used to hand execution to the operator. **The hand-off write (Owner ruling, Aled 2026-09-04,** APP-1117). Where a delivery leg routes a *judgement* to the operator (*Executor* above; APP-1035, APP-962), the write is — the executor **cleared** (no `agent`-group value at all), the ticket's `operator-<venture>` present (set it if the owning ticket's value was never inherited), the assignee **cleared**, and one comment naming the escalation category and the question (`skill-operating-loop` step 5). The state follows the leg's own rule: **Blocked** where a genuine external blocker stands, **In Review** where the item is review-only (*Issue states*). Clearing the executor is the load-bearing half, because an `operator-*` label sits *beside* an executor value rather than replacing it: a fail-safe that left `agent:R3-LAY` or `agent:PR-1SM` in place would leave the merge sweep re-firing and QA re-queueing on a ticket that is held for a decision. "Evict" was the mechanism of the old single-select shape, not a requirement — the Owner declined an `operator` value in the `agent` group precisely so that `human` keeps the narrow meaning APP-1035 gave it.

  **Scope and queue are two different reads, and both are ruled.** **Scope** = every ticket carrying `operator-<venture>`, executor or not — what the operator stand-up reads for what moved, what is in flight, what is blocked. **Queue** = the subset carrying `operator-<venture>` **and no executor** — the judgements actually pending on the operator. Re-routing a held ticket (setting `F0-RGE`, or `human` + Aled) **leaves the queue and stays in scope**, so the operator keeps sight of work it has handed on without that work counting as an outstanding decision. The operator resolves both reads by its `operator` label workspace-wide (`skill-operating-loop`, *The read recipe*), never by project. **And the label those two reads depend on is set at refine, not only on a delivery-loop hold.** A vertical whose tickets never receive the value has both reads return empty **by construction**, and the emptiness reads as a quiet vertical rather than as a missing label. Verified 2026-09-10: a workspace-wide `list_issues(label: "operator-mrp", includeArchived: true)` returned **zero issues** with `hasNextPage: false` — so Mr Pritchard's queue and scope reads are defined against a label no writer sets, and canon defines a read with no writer. `operator-<venture>` is therefore set at **refine**, on the ticket's owning row, by the leg that refines it (`skill-triage`); the hand-off write above sets it only where the owning ticket's value was never inherited, which is a repair and not the primary write. (APP-1217; the reciprocal rule lands on the `skill-triage` row.)

  **A sweep reads *no executor + an operator label* as a valid held state, never an anomaly.** `skill-triage`'s executor-presence sweep — and any sweep that repairs an executor-less ticket — must not restore an executor onto a ticket carrying `operator-<venture>`: doing so cancels the hold and re-arms the loop the hand-off just disarmed. *No executor and no operator label* stays the anomaly it has always been. (Owner ruling, Aled 2026-09-04, APP-1117. The retired form of this bullet — set `operator-<venture>` in the `agent` group and let it evict — writes a label that has matched nothing in that group since APP-1103.)

  **The held state is scoped to where a hold can rest.** The hand-off write above lands a ticket in **Blocked** or **In Review**. Nothing in the ruling places a hold in Todo or In Progress, the two states the build and fleet loops select from. *No executor + an operator label* is therefore a valid held state anywhere outside those two. On a **leaf in Todo or In Progress** it is an unrouted ticket and a triage defect: the vertical's label with no executor, most often on a ticket authored straight into Todo. The executor-presence sweep repairs it and keeps the label. A **non-leaf parent** is the standing exception. It is never routed, so no executor plus its operator label is its correct form in every state (`skill-triage`, *Executor-presence sweep*; APP-1554). (Refine how/where ruling, 2026-09-21. This clarifies the Owner ruling of 2026-09-04, APP-1117, whose text defines this shape as the operator-hold write; the Owner retains the override. Worked case: MBN-302, created straight into Todo with no executor and now carrying `operator-bara` — APP-1537.)

  **A leg that hands the operator a decision as it closes its own ticket files that decision as a ticket — a closing comment reaches no queue.** The hand-off write above is the mid-run case: one ticket, held, carrying the question. The at-close case is different and entirely legitimate — a leg finishes exactly what it was asked to do and correctly declines a call that is not its own — and it leaves no held ticket behind. Recorded in the closing comment, the hand-off sits where nothing polls: closed tickets are read by no sweep, a comment body is not a queue, and the queue read is *`operator-<venture>` and no executor*, which a ticket closing on its own valid executor never enters. So the closing leg files the decision as its own ticket in the vertical's project, carrying `operator-<venture>` and no executor, unassigned, its body naming the escalation category and the question in the form the hand-off write uses, and relates the closing ticket to it. This is the remedy *Labels* (*Backlog default*) already applies to a `PUL-5E` note carrying an operator-owned action, and the same principle as a dependency that must be a relation rather than a prose line (`convention-ticket`, *Obligations belong in structure, not prose*; APP-685). **Surfacing the symptom is not surfacing the instruction.** Where the work the decision concerns is already on the board, the queue returns those tickets and the stand-up reports them accurately as unchanged; neither read says a named decision is waiting on the operator, so the decision ages while the tickets do not. (Worked case: APP-1427 closed Done on 2026-09-24 with a full and honest closing comment handing `operator-apps` the Hold-versus-live reconciliation of APP-514 and APP-509. It kept `R3-LAY` to its close, because Relay's PM work was its deliverable, so it never entered the operator queue; APP-514 and APP-509 did carry `operator-apps` and no executor, and were duly restated as unchanged hygiene in the `apps.standup` entries of 2026-09-28, 09-29 and 09-30. The call was taken six days late, by a run that found it while reading APP-1427's thread for an unrelated reason — APP-1907.)
* The enumeration of operator values lives in `core-fleet-roster` (*Operators*) and must agree with the Linear `agent` group — reconcile both when a venture gains an operator.
* Anything an operator cannot do within its mandate — a strategic pivot, a budget-envelope breach, a goal-set change — is escalated to the **Owner** (Aled): assign him and comment the recommendation, never action it unilaterally. This is the operator-tier mirror of the delivery loop's "the operator is the gate", one level up.

## Agent routing — the Relay / Forge / Prism loop, in Linear

The routing pattern (triage → build → review → gate) from `convention-ticket`, bound to Linear's labels and states. There is no Linear agent app user — `@claude-code` is a label, not a user, so triggering is by label, driven by polling Cloud Routines. **The gate is by work type, not universal.** Flagged work, bounce-cap escalations, QA blocks and merge failures stop for Aled; unflagged, clean, unblocked work is merged by the loop's own clean-pass routing to `agent:R3-LAY`, which *is* the approval signal (`convention-ticket` *Gate*, decision 2026-06-30, APP-402 — which superseded the earlier "nothing merges without his approval" blanket this line carried; `routine-delivery-loop`). An ops-sync canon-publish ticket sits squarely in the second class: its content is a digest-verified copy of canon the Owner already approved when he saved it, so a clean Prism verdict merges it without a further approval from him (Owner decision, Aled 2026-09-08, APP-1163).

* `agent:R3-LAY` — triage and PM. Sets status / priority / links; if execution is needed, sets `agent:F0-RGE`, moves to **Todo** (never Backlog), clears the assignee, and comments the acceptance criteria. Also carries the **post-review merge gate**: when Aled approves a reviewed ticket by setting `agent:R3-LAY` (evicting `agent:PR-1SM`) and giving his `@relay` signal, the merge leg squash-merges and closes it. **That merge-gate reading binds only where the ticket's definition of done names a PR.** Where the definition of done names none, an approval is not a merge signal and `agent:R3-LAY` is the wrong value to write: the approved deliverable takes `human` with the reviewer assigned at the point of approval — `operator-<venture>`, or Aled where the operator has already ruled — which is the disposition `skill-merge-pr` step 1's no-PR exit reaches anyway, so writing `agent:R3-LAY` only defers it by a run. `agent:R3-LAY` on a no-PR ticket is a **false merge candidate**, and it is not free: the out-of-band merge sweep pays a full fetch-ticket, fetch-comments and fetch-PR investigation per occurrence to establish that there is nothing to merge, then writes the no-PR exit by hand. Worked case `APP-2505`: a bulk approve pass on 2026-10-19 set the merge signal on five In Review tickets, of which only two (A1-380 and A1-386, both correctly parked on standing `[merge] not ready` holds) had an open PR; the other three named no PR in their definition of done — `APP-125`, a content deliverable; A1-276, whose one open box is a human-only GitHub UI click; and `APP-1622`, a SPIKE delivered 2026-09-22. Third occurrence in one bulk pass, and A1-276's second on the same ticket. Approving a reviewed ticket and releasing it to merge are two acts, and the definition of done is the only thing that distinguishes them.
* `agent:F0-RGE` — execution. Claims the ticket by moving to In Progress and clearing the assignee (status is the lock; no separate lock label). Opens a PR (never merges), sets `agent:PR-1SM`, moves to In Review, **leaving it unassigned**.
* `agent:PR-1SM` — review. Reads the PR against the embedded criteria, posts a plain-language verdict, then **assigns Aled** (leaving the label `agent:PR-1SM`). Switching to `agent:R3-LAY` is Aled's approval action.

**Setting a fleet executor clears the assignee in the same write.** The three bullets above each clear the assignee at their own transition, and each has been patched separately when something did not — the unblock relabel, Linear's GitHub auto-assign (APP-936, APP-1699), the In Review transition (APP-404), the Done → In Progress reopen (APP-811). The invariant they are all instances of is stated once, here, so a fifth producer needs no fifth patch: **a ticket carrying a fleet `agent:` value — `F0-RGE`, `PR-1SM`, `R3-LAY` — carries no assignee, and any pass that sets or changes the `agent` value to one of them clears the assignee in the same `save_issue`.** `human` and the `operator-*` values are the opposite case and are untouched: those *are* assigned, and that is how an Owner-held ticket is told apart from residue. This binds on writes we make. An assignee already sitting on a fleet-labelled ticket is not interpretable after the fact and is **surfaced, never silently cleared** — `routine-delivery-loop`'s *An assignee on a Todo candidate means surface, not claim* is that half and is unchanged. (Worked case: A1-351 was unblocked on 2026-09-24 with `human` swapped for `F0-RGE` and the Owner commenting that Forge should build on it; the assignee set while the ticket was Blocked-on-Owner survived the relabel, and the delivery loop then held it out as Owner-pulled on every run from 2026-09-26 to 2026-09-29 — the opposite of what the Owner had just asked for. APP-60, APP-61 and A1-550 carry the same shape from other producers — APP-1790.)

With the ticket assigned to him at `agent:PR-1SM`, Aled either bounces it (**In Review → Todo with a note** re-triggers the build leg on the same ticket) or approves by **setting `agent:R3-LAY` and giving his `@relay` signal**, triggering merge.

**`R3-LAY` is a triage marker, not a resting executor.** Once a ticket is triaged or refined it carries its *real* executor, and `agent:R3-LAY` is evicted — `agent:F0-RGE` (or another agent) for agent work, **`human`** (the `agent`-group value) for human-owned work such as a decision, a design, launch ops, or an on-device verify. So triage sets `human` at refinement for human-owned work, the mirror of setting `agent:F0-RGE` when execution is needed; a refined human-owned ticket then carries `human`, is assigned to Aled, and drops out of the `agent:R3-LAY` triage poll rather than re-surfacing on every run for no work. Setting `human` is the documented action, not a consequential call — no suggest-mode hesitation is warranted for it. This holds for a human-owned ticket parked in **Refinement** too: where it still carries the old `agent:R3-LAY` (a pre-convention leftover), the executor-hygiene relabel to `human` is the sanctioned migration that drops it from the poll — a routing change, not a re-refinement of content (see `skill-triage` *Refinement comment sweep*). A ticket in **Todo** must carry a real executor; `agent:R3-LAY` lingering there is an anomaly to fix, not a valid resting state. **But `agent:R3-LAY` in Todo has two readings, and the test is whether anything ever evicts the marker.** The anomaly rule holds where the ticket's *deliverable* is something Relay would route to someone else — a build, a design, a decision — so the marker should have evicted at routing and its lingering is the hygiene defect to fix. It does **not** apply where Relay's own PM work *is* the deliverable — a DECOMPOSE, RECONCILE, or restructure task whose output *is* the routing: there the marker is **valid and terminal**, because Relay is the executor rather than the router and nothing downstream ever evicts it, so relabelling such a ticket off `R3-LAY` would break a genuine work-item. This is the same leaf-vs-non-leaf / does-anything-evict-the-marker test `skill-triage`'s poll exclusions turn on, not a new taxonomy: valid where Relay's PM work is the deliverable, an anomaly where the deliverable is something Relay would route onward (`APP-921`).

Concurrency: the build leg only picks up `agent:F0-RGE` tickets in **Todo**, and skips its run if any `agent:F0-RGE` ticket is already In Progress (one agent per repo). Scope: the loop runs across delivery projects only and must never touch the Pipeline team.

## The Pulse friction queue — canon-improvement intake

A second, parallel intake into Apps / os.Claude that the delivery loop never touches. It exists because the surface that *spots* friction (a Claude Code routine, a headless run) is rarely the surface where a `.skill` can be *saved* — but filing a Linear note is something every surface can do. So friction is captured as a queue note first, and the artefact is produced later by the Pulse retro drain, where the save button works.

* **Shape:** a Backlog ticket in Apps / os.Claude, title prefixed `FRICTION:`, labels `task` + `work:configuration` (bare type value — see *Labels*), executor **`agent:PUL-5E`**, unassigned. The `FRICTION:` prefix and `agent:PUL-5E` together mark it as canon-improvement intake.
* **Who fills it:** `skill-ops-retro` in capture mode — embedded as a skill's final step, or run headless / on Claude Code. Capture is a note (an observation), never a proposed canon edit and never a Forge hand-off. **This holds unconditionally:** a concluded design, planning, or discussion session is *not* an implicit instruction to author the change — the session captures the note to this queue and stops. Authoring canon happens only in an explicit drain (`task-pulse-retro`, or Aled's explicit "drain / author this now"); a session never decides to author on its own read of intent (see `core-operating-model`, *Changing canon*).
* **Who drains it:** `task-pulse-retro` (the scheduled Pulse retro), or `skill-ops-retro` run on demand. It reads the queue, assesses each note against current canon, produces ready-to-save artefacts, comments the outcome, and moves the note to **Done**.
* **Distinct from `skill-issue-capture`.** That captures runtime/repo problems (`FIX:`/`OPS:`/`DRIFT:`) which *do* route to Forge or the operator as delivery work. `FRICTION:` is ops-layer canon improvement, drained into a save-and-then-publish artefact, never executed by Forge directly. Keeping the two lanes apart preserves the split: repo changes go through Forge; canon changes go through the save button.
* **Reading it:** the agent-group filter takes the bare value `PUL-5E`; a `Backlog` filter also returns Refinement, so re-check each ticket's state name (see *Reading Linear safely*).
* **Never in a delivery cycle.** An `agent:PUL-5E` note is propose-only canon-intake — it is drained, never delivered — so it must not carry a cycle. Adding one to a committed cycle inflates that cycle's scope and burn against work the delivery loop will never complete, and a canon-decision note left resting in Blocked pollutes `skill-plan`'s Blocked-ticket health check with a ticket that is resting by design. Keep `PUL-5E` notes out of the cycle; that is the fix, not dropping Blocked — `skill-ops-retro`'s deliberate Blocked + Urgent surface for a canon decision awaiting the Owner is a legitimate resting state, and `skill-plan` accordingly excludes `PUL-5E` from both delivery scope and its Blocked health check (`APP-870`). **But the rule as written above is an instruction to writers, and writers are not what breaches it — Linear's *Completed issues* cycle automation adds the cycle at the close, on every note the drain closes.** Observed 2026-09-12 06:02–06:05Z against the Apps board, reading `PUL-5E` notes with their `cycleId`: in **Backlog, 43 notes and not one carries a cycle** — every writer is clean, `skill-coordinate` Pass 7 correctly never adds a note, and the drain correctly never sets a cycle; in **Done, 59 of the 60 most recently updated notes carry one**, the sole exception being APP-422, closed 2026-07-02. The values are not one stale assignment but **successive Apps cycles** — the current cycle on everything closed since 2026-09-07, the prior cycle on the 2026-09-03/04 closes, the one before on the 2026-08-10/15 closes, and so on back through mid-July — which is the signature of an event firing at each close rather than of a bad write. **Reproduced live, twice:** APP-1318 and APP-1353 each carried no cycle in Backlog and each came back from a `state: "Done"` write carrying `cycleId b11b9c39-ca0d-4644-b368-167c0c2e0042`, with no cycle named in either write. The cause is the cycle-automation split of 2026-09-03 (APP-1007): *Active issues & due date* was turned **off** on Apps, A1 and MBN and *Completed issues* was deliberately left **on**, and that second toggle adds a completing issue that has no cycle to the current one. It is doing exactly what it says; nothing told it that one class of ticket is propose-only intake. **So read the rule as a property of the board, not of the writers: it is breached at the close, by automation, while every writer obeys it — and a reader must not conclude the rule is held merely because no one is setting a cycle.** The consequence the rule already names is the consequence that is happening: the Apps cycle's completed-issue count is now mostly canon intake (**30 notes closed on 2026-09-11 alone**, against a handful of genuine delivery completions), which distorts `task-cycle-planning`'s planned-versus-unplanned share — a drained note is in the cycle and is not on the committed list, so it reads as unplanned *delivery* work — `skill-plan`'s reading of a rising unplanned share as a planning signal, and the `completedIssueCountHistory` cross-check of APP-890, all computed over a set that is mostly intake. **Two halves close it, and both are outside this convention's gift.** (Config action, Owner: turn *Completed issues* off on the Apps team — a workspace-config lever, so it is named here, never filed and never authored, and it is the only half that stops the add recurring.) Or, if that automation is wanted for delivery work, accept the add and fix it at the **reading end**: exclude `PUL-5E` from cycle reporting — from planned-versus-unplanned, from velocity, and from the completed-count cross-check — which is the same exclusion `skill-plan` already applies to delivery scope and the Blocked health check. A writer-side clear at the close is a partial mitigation only, not a guarantee: this run passed `cycle: null` on the APP-1353 close and the returned object still showed the cycle, so any self-healing rule owes a read-back (`skill-ops-retro`, step 5). (Observed figures, 2026-09-12; APP-1386.) **Measured again on 2026-09-23, and unchanged:** APP-1634, closed 04:01:28Z carrying no cycle, came back holding `cycleId 59e71de1-f5bc-455c-8425-aeca0aaa090b` — the current Apps cycle — from a write that named no cycle at all; and five of the 2026-09-22 author pass's closes (APP-1576, APP-1578, APP-1620, APP-1631, APP-1211) still carry that same cycle today. (APP-1647.) **Re-measured on 2026-09-24: the ratio above is stale, the rule is not.** Every Done `PUL-5E` note on the Apps board was read this run with its `cycleId` (500 notes captured, figures computed rather than eyeballed — observed). On this bullet's own basis, the **60 most recently updated** Done notes, **25 carry a cycle, not 59 of 60**; taking the **26 most recently completed**, **3 do**. So the 2026-09-12 ratio no longer describes the board and must not be quoted as a current rate. Nothing about the mechanism or the consequence changes: the two live reproductions stand, a close still returned a cycle no write named as recently as 2026-09-23, and the two closing halves are still the two closing halves. **The cause of the fall is deliberately not asserted here** — whether *Completed issues* is still on for Apps is a workspace-config fact and is not readable from this surface, so a lower ratio is equally consistent with the Owner having taken the config action this bullet names, with writer-side clears on the 2026-09-23 drain, and with a change in what the drain closes. Read every figure in this bullet as a dated observation of a breach that was live on its date, and **re-measure before quoting a rate rather than carrying one forward**. (Observed 2026-09-24 by the refine pass itself; the 2026-09-23 measurement's note of record is APP-1647.) **Confirmed from both ends on 2026-10-22, with one detail this bullet did not carry: the clear's own response is silent.** On all six of that run's *assessed, not warranted* closes — six for six — a `save_issue(state: "Done")` write auto-populated cycle `4f7e0dcc` on notes whose `cycleId` read `null` immediately before the write, with no cycle named in any of the six calls; the isolated `cycle: null` save that followed each one came back **omitting the `cycleId` key entirely**, so the clear's own write-back proves nothing and only the separate re-read proves the clear. Both halves of the instruction above therefore hold as written — the automation fires at the close, and the clear must be isolated and read back. (Session-observed 2026-10-22 by the refine pass itself.)

## os.Claude Backlog routing by work type

In os.Claude specifically, the Backlog executor is chosen by the *nature* of the work, not a blanket default. The blanket `agent:R3-LAY` default still holds for ordinary delivery work, but two kinds of work are born on a different executor:

* **Canon improvement / friction → `agent:PUL-5E`.** `FRICTION:` capture notes and any canon-change intake (a ticket whose deliverable is a saved `.skill` — a skill, convention, agent or operator profile). Drained by the Pulse retro, never the delivery loop.
* **Repo-native or publish work → the delivery loop, straight through.** A change to a repo file (`CLAUDE.md`, `build-manifest.ts`, site code) or an ops-sync publish ticket is ordinary Forge work: it carries `agent:R3-LAY` in Backlog and is routed to `agent:F0-RGE` at triage like any build ticket. In os.Claude this routing is **straight-through** — because the deliverable needs no human decision, triage promotes it directly to **Todo** rather than holding it in Backlog under a suggest-mode comment for a separate confirm (the suggest-mode carve-out in `skill-triage`). Suggest-mode-hold still applies to any os.Claude ticket carrying a human decision.
* **Everything else** — operator-written, or surfaced from elsewhere, needing triage — **→ `agent:R3-LAY`**, the standard default.

So `agent:R3-LAY` is the triage marker for delivery work, not a label every os.Claude ticket wears: canon-improvement work is born on `agent:PUL-5E`. This is the Linear binding of the canon / repo / publish three-lane split defined in `core-operating-model`.

## Reading Linear safely

Several connector behaviours bite the Linear-reading and -writing skills (triage, coordinate, plan, daily-report, merge, exec) **silently** — a run looks clean while reading, or acting on, the wrong thing. They live here, once, so every reading and writing skill inherits them rather than repeating the warning.

* **A ticket's state and labels do not say who holds it — at a review label the discriminator is the *assignee*, and canon already settles it in a place a reading pass never opens.** `agent:PR-1SM` + **In Review** is **two different states wearing one label**: the review leg sets the label at the hand-off and leaves it in place through its own verdict, so the label alone never separates *review pending* from *review done, Owner holds*. *Agent routing* above does settle it, but as a **producer** spec — Forge "sets `agent:PR-1SM`, moves to In Review, **leaving it unassigned**", Prism "posts a plain-language verdict, then **assigns Aled** (leaving the label `agent:PR-1SM`)" — so a pass reading a ticket to answer *who holds this and what is next* does not go there and does not find it. Stated as the reader rule: **`PR-1SM` unassigned means the review is pending; `PR-1SM` assigned to Aled means the verdict is in and the ticket is waiting on the Owner**, and the wait clock starts at that assignment, not at the label. This is also the one sanctioned exception to the fleet-assignee invariant above — a ticket carrying a fleet `agent:` value "carries no assignee" — so a post-verdict assignee on a `PR-1SM` ticket is **the signal, not residue to surface**; applying the invariant alone inverts the answer. So **the assignee is the discriminator, not the thread.** The thread stays the *corroborating* read, and it is the only read for three things: **what** a verdict actually said, a **contradiction between two verdicts** on one ticket, and any case where the fields and the thread conflict — there the thread wins on substance. But a full thread read is never the price of answering who holds a ticket: the compact `fields` set a sweep already pulls answers that deterministically, which matters because making every state read a comment read is the intake cost of `APP-1144`. (Worked case: A1-556, read first-hand 2026-10-08 — In Review, `PR-1SM`, **assignee Aled** — was reported on 2026-10-07 as still awaiting Prism's design-parity review, from the description, labels and state. Prism had posted two verdicts: 2026-09-29T00:23Z *divergences to fix*, closing "Assigning to Aled for the sign-off/bounce call", and 2026-09-29T10:30Z *on bar — clean pass*, which cited this routing rule correctly and left label and assignee as-is — and which does not mention the Inter-for-`Helvetica Neue LT Pro` substitution the first verdict raised, the verdict-to-verdict contradiction a fields-only read also missed. A `[coordinate]` comment of 2026-10-02 had already said in plain terms that the review was done and the ticket was waiting on the Owner. The producer held the rule; the reader did not have it where it reads. The Owner corrected the report twice and reports the shape is frequent — APP-2156.)
* **Where the ticket's subject is an event outside Linear, the ticket is not the record of it — a line characterising such an item carries a Calendar and Gmail read, with its time, alongside the thread read.** For an item whose subject is a thing that happens in the world — a meeting held or not held, a deliverable sent or not sent, a client reply received or not — the ticket is a **lagging, hand-maintained copy** of an event that happened somewhere else. Its state, its fields and its thread are **structurally incapable of being the record**: nothing about the session running, the deck landing in the client's inbox or the reply arriving touches Linear until a person or an agent chooses to type it, and that typing is exactly the step that does not happen when a run is busy. So the failure is not that the ticket is wrong occasionally; it is that the ticket is **not the instrument**, and no amount of reading it more carefully makes it one. **A stale ticket and a genuinely stalled item are byte-identical on a fields read** — same state, same assignee, same `updatedAt` — and "no movement in two days" reads as diligence rather than as a gap, so the failure is **self-concealing, in the direction that manufactures work**: it reports a session to re-book and a deck to re-send, both of which already happened. And it does not stop at the retro — a false world-side claim propagates straight into the documents the retro writes, into the per-team comments it posts, and into the Owner notifications it raises, each of which looks independently sourced. **Bound the cost the way the sibling thread rule is bounded** (`skill-operating-loop`, `APP-1935` / `APP-2167`; the closed-side extension in `task-cycle-planning`, `APP-2281`): the read fires on the items a retro or report **names as a cause, or as a goal's pass condition** — not on every open ticket, and not on the population. **The discriminator is readable from what the pass already has open**, off the ticket's own verb and its acceptance criteria: a title opening `SESSION:`, `CALL:`, `WORKSHOP:` or `DISPATCH:`, or a `GATE:` naming an external party, and any acceptance criterion naming a person **outside the fleet** — a client, a supplier, a collaborator. Those are the world-side items; everything else is Linear-internal and the thread read already covers it. **The second-order point is the transferable one: both connectors were loaded and available on the run that got this wrong.** Nothing was missing from the surface, nothing failed, nothing had to be installed — the run simply was not told to open them. This is therefore a gap in **what the artefact tells a run to open**, not a tooling gap, which is the same shape as the comment-image rule above in this section: the connector exposes the read, and the discipline to take it is what canon owes. (Worked case: the 2026-10-16 W42→W43 boundary retro reported a client session **cancelled** and a deck **undelivered**, judging both from the Linear thread alone. The session had run that morning and the deck had been emailed two days earlier; both connectors were loaded throughout. The correcting reads, made afterwards, were **one calendar read and one Gmail search, in under a minute**. Every world-side fact here — the calendar event and its creation time, the three Gmail threads, the 20:13Z send, the comment times on the A1 ticket and the Owner's quoted correction — is the **filing leg's report**; no Calendar or Gmail call was made from the refine surface that wrote this rule, and the rule does not depend on any of them being exact. APP-2407.)
* **Comment authorship is unreliable — read the body, not the author field.** The connector stamps every comment's `author` as the account owner (Aled), whoever actually wrote it. To tell an operator comment from an agent one — the signal the sweeps gate on — read the body's leading marker (`[exec]`, `[qa-review]`, `[coordinate]`, `Relay — …`, `pm-triage …`, `[plan]`), never `author.name`. An unprefixed comment is the operator's — **with one exception the default cannot cover: a verdict.** The operator does not run reviews, so an unmarked comment asserting a *completed review outcome* or a *tool-derived finding* — "on bar", "divergences", a parity verdict, a node-level structural claim — is not his statement and is not evidence. Read it as unattributed, verify the finding independently before acting on it, and say on the ticket that it was unattributed. Two tells are cheap and worth checking: a dedup key or timestamp reused from another comment rather than derived, and content that does not match how the named pass actually works, such as a Figma structural verdict argued from CSS variable syntax. Confident and plausible is what makes the case expensive, not what makes it safe. (Worked case: a comment claiming a completed design-parity review, verdict "on bar", appeared on A1-557 about nine and a half hours before any independent review ran — unmarked, reusing the builder's own dedup timestamp, and describing token binding verified "directly in the rendered code" on a ticket about a Figma file. The genuine review refused to trust it and re-checked; nobody could account for what produced it — APP-1859.)
* **The producer half of the same rule: every agent-authored comment opens with its own marker, before any other text.** The reader rule above is only sound if the writers hold it up, and an agent comment with no leading marker is **worse than no signal** — the rule above then reads it as a settled operator statement rather than as the open question it actually is. The marker is the **first thing in the body**: a bracketed tag (`[exec]`, `[qa-review]`, `[coordinate]`, `[plan]`) or a `Name — ` lead-in (`Relay — …`), never a skill or role name surfacing mid-sentence, which reads as prose and gates nothing. (Worked cases, all 2026-09-11 to 09-13: two `bot.Trader` comments, both opening "Decision needed" and closing respectively "Why I left it to you" and "Routed to `operator-bottrader`" — both plainly agent hand-offs, both unmarked, and both therefore readable as the operator's own words; and one Reach deliverable on MBN-274 opening "Resolved via `skill-content-studio`", set against the correctly marked "Reach — content run complete." posted by the same skill two days earlier, so the same producer both holds and breaks the rule inside one week. APP-1405, APP-1404.)
* **An image in a comment, description or document is content, not decoration — extract it before reasoning about the item.** `list_comments` and `get_issue` return the image markdown inline, so the body *looks* complete while the load-bearing part of it is silently unconsumed — the same silent-failure class as the filter traps below, on the content rather than the scope. This is a discipline gap, not a tooling one: the connector exposes **`extract_images`** for exactly this ("view screenshots, diagrams, or other images embedded in Linear issues, comments, or documents"), and it works first time when called. So where a returned body carries an image reference, call `extract_images` and view it **before** answering a question about the ticket, asserting its state, or searching externally for information the ticket may already hold — a screenshot is usually attached *because* the text alone was not sufficient. It binds hardest on the sweeps whose decisions gate a run (`skill-coordinate`, `skill-triage`, `skill-review-pr`, `skill-design-parity`, `skill-merge-pr`), where an operator decision conveyed in a screenshot would be missed outright. Attachments carry the same risk in weaker form — `get_issue` lists them, nothing obliges opening them. (Worked case: A1-117, 2026-07-20 — an operator comment carried npm commands, an import line and a screenshot of Vercel's Speed Insights *Get Started* panel; the text was processed, the image ignored, and a web search was run to reconstruct an answer the screenshot gave precisely. He had to notice the drop and push back, which is the failure the evidence-first discipline exists to prevent — APP-617.)
* **`list_issues` state and label filters have three traps.** Filtering `state: "Backlog"` also returns **Refinement** tickets — both share the underlying `backlog` type — so a "Backlog only" sweep must re-check each ticket's state **name**, not trust the filter. And the agent-group label filter takes the **bare value** (`R3-LAY`), not the displayed form (`agent:R3-LAY`), which silently matches nothing. **And a `state` filter naming a state the team does not have returns a silent zero** — `state: "Done"` on Mr Pritchard, whose completed-type states are `Published` and `Scheduled`. For any cross-team or multi-team read of closed work, filter on the status **type** (`state: "completed"`), never on a state name; see the `completedAt` bullet below (APP-1993).
* **And a fourth trap on the same two params: a *valid* `state` + `label` pair can return a silently **incomplete** set — cross-check the count against a single-dimension read.** The three traps above fail recognisably once known: a wrong underlying type, a wrong label form, a zero. This one returns a plausible, healthy-looking result that is short by a few rows, with nothing marking what is missing — the same failure shape as the `cycle` param bullet below, now on the combined state-and-label filter. Observed as a workspace-wide `list_issues(state: "In Review", label: "human")` returning 35 rows, 16 of which bucketed to one team, while a team-scoped `list_issues(team, state)` read cross-checked against each row's own labels found **19** genuine members of that bucket; the three missing rows carried `human` on a direct `get_issue` read, and two of them had been returned correctly by the same combined filter eight days earlier, so this is the filter losing rows rather than membership changing. So where a combined-filter count is the deliverable — a review queue, an operator's own queue, any set a report hands up as authoritative — **filter on one dimension in the call and test the other client-side**, or take the single-dimension read as the count and let the combined filter only corroborate it. Where the two disagree, the narrower-returning read is the suspect and never the arbiter, and a combined-filter count that has not been cross-checked is handed up as suspected-incomplete, naming what it covered. Third member of this family after APP-326, the combined label-and-state filter returning nothing at all, and APP-496, the state filter conflating Backlog and Refinement — and the first observed as a partial undercount rather than a total miss. (The row counts, the three identifiers and the eight-day-earlier comparison are the filing leg's **report**; no Linear read was taken from the authoring surface. APP-2772.)
* **A `state` filter for a backlog-type state does not narrow the read — scope it with `team` as well, or it overflows.** The `state` param appears to match on the underlying `statusType`, not the literal state name, so every team's backlog-type state (both `Backlog` and `Refinement`) matches at once and the query returns a workspace-wide sweep. With full descriptions attached (see the overflow bullet below) this exceeds the tool's token limit **even with a label filter already set** — `list_issues(label: "F0-RGE", state: "Backlog")` and the same call for `Refinement` each overflowed at ~64k characters, while `state: "Blocked"` and `state: "In Review"` on the identical query returned cleanly. So a backlog-type read is the one case where a label filter is *not* enough narrowing: pass `team` (and where possible `project`) alongside `state`, or read the non-backlog states and infer. This is the same silent-failure family as the two traps above — the call does not error, it simply refuses to return (worked case: delivery-loop zero-eligible diagnostic, 2026-07-17, APP-577).
* **Detect the Linear connector by exact tool name, never by the substring "linear".** The connector's tools surface under a UUID-prefixed server id (`mcp__80c602c6-…__get_issue`), so a keyword search for "linear" returns nothing even when the connector is attached. Load and detect with `ToolSearch "select:<prefix>__get_issue,<prefix>__list_comments,<prefix>__save_issue,<prefix>__save_comment"`; treat an empty `search_mcp_registry(["linear"])` as genuinely not attached, and tools present under the UUID prefix as attached-but-not-yet-surfaced. A scheduled run that stops on "no Linear tools" after a substring search has not established absence. (Worked case: the 2026-09-02 `task-pulse-refine` run reported "cannot run — Linear absent" and lost the day's pass; the tools were present under the UUID prefix in the next turn — APP-1075.)
* **`get_initiative` name lookup fails on dotted names — list first, then query by ID.** `get_initiative` with a dotted name query (`a1.AledPritchard`, `a1.Muse`, and every other `a1.*` initiative) returns `invalid_request: Variable "$id" of required type "String!" was not provided` — the tool needs the query to resolve to a single unambiguous match, and a dotted name does not resolve cleanly. The working pattern is `list_initiatives` first (its name search is unaffected) to get the UUID, then `get_initiative` by ID. Any skill that calls `get_initiative` directly by name (plan, goal-review, strategy-charter) should use the list-then-ID pattern rather than losing a round-trip per lookup. The underlying lookup behaviour is the connector's; the list-then-ID pattern is the canon mitigation (worked case: weekly plan run, all six a1.* initiatives, 2026-07-10).

* **A project shorthand in a repo's `CLAUDE.md` can name an initiative, or no object at all — resolve the object *type* before writing to it.** A repo file saying "Tracked in Linear: team A1, project `a1.MeirionPritchard`" is a human shorthand, not a resolved reference, and the failure is not a lookup quirk: the name belongs to an **initiative**, and the real project carries a suffix the shorthand drops. `save_issue(project: <that name>)` fails with `Could not find project`, and retrying with the initiative's own UUID as `project` fails again with `projectId contained an entry that could not be found` — two errors that read as a bad name rather than as a wrong object class. So resolve a shorthand against `list_projects` **and** `list_initiatives` and match on the object type before any write, and where the listing is large, match on the **substring** rather than the whole name, because the live project is routinely the shorthand plus a qualifier. Correct the shorthand in the repo file in passing, so the next session does not pay for it again. (Worked case: assoc-one/meirionpritchard-com's `CLAUDE.md` names `a1.MeirionPritchard`; that is an initiative, and the project is `a1.MeirionPritchard · Work section`, P-A1-19 — three round-trips to resolve what should have been one lookup, 2026-09-29 — APP-1855.)
* **`list_issues`' `project` name lookup fails on a name containing `&` — scope by the project UUID.** A `project` filter passed by name fails when the name contains an `&`: the literal ampersand arrives HTML-entity-escaped as `&amp;`, so `list_issues(project: "aledpritchard.com · Site & presence")` returned `Could not find project "aledpritchard.com · Site &amp; presence"`, while the identical call scoped by the project's UUID returned cleanly. The reading sweeps that gate on project liveness — coordinate, `skill-plan`, `task-daily-report` — resolve projects from `list_projects` and then re-query `list_issues(project: <name>)` per state, so any project whose name carries an `&` (or another character liable to entity-escaping) silently returns zero for the name-scoped read while looking like a healthy empty project — the same silent-scope failure class as the state-filter and liveness-gate traps above. The sweep already holds every project's ID from the `list_projects` liveness call, so **scope `list_issues` by the project UUID, not the name**, wherever a name might carry an `&`; it removes the class deterministically at no cost. Whether the escaping is the connector's or the tool-call serialisation's is the open question; the ID-scoping mitigation holds either way. (Worked case: `task-coordinate`, 2026-07-22 — APP-646.)
* **`list_issues`' `cycle` filter needs a resolved cycle ID — the literal `"current"` silently returns zero.** `list_cycles` takes a `type` enum of `current` / `previous` / `next` and returns the matching cycle object with its real UUID, so it is reasonable to assume the vocabulary carries across. It does not: passing `cycle: "current"` to `list_issues` returns `{"issues":[],"hasNextPage":false}` for every team, with no error. The working pattern is the same list-then-ID shape as `get_initiative` above — **call `list_cycles(teamId, type: "current")` first to resolve the UUID, then pass that UUID to `list_issues`' `cycle` param.** Any skill sweeping a committed cycle (`skill-attention-sweep`, `skill-plan`, `skill-coordinate`) must do the two-step resolution; a sweep that trusted the empty result would conclude "no cycle committed, nothing to sweep" and stop, reporting a false negative on a genuinely committed cycle. (Worked case: `task-aide-loop`'s first live run, 2026-07-17 — `list_issues(team: "Apps", cycle: "current")` returned 0 while `list_cycles` confirmed a live cycle of scope 74, 55 completed, for that exact team. APP-580.)
* **And a resolved "current" cycle can be dead — compare its `endsAt` against the session clock before trusting it.** The two-step resolution above returns cleanly and still hands back a cycle whose boundary has passed: on 2026-08-10, `list_cycles(teamId, type: "current")` returned cycle 3 — `endsAt` **2026-08-02**, eight days over, with no cycle 4 created — as the current cycle for all three delivery teams, with no error and no flag distinguishing it from a live one. A cycle stays "current" until the next one exists, so an unrun boundary ceremony leaves a closed cycle standing in that slot indefinitely. So after resolving the UUID, **compare `endsAt` to today and treat a passed end date as "no live committed cycle — this team is at a boundary"**: the same branch as no cycle at all, falling back to milestone and priority, and surfacing the overdue boundary as a health flag rather than reporting a dead cycle's burn as mid-flight status. Every cycle-sweeping consumer inherits the blind spot — `skill-plan` (where the guard is now authored), `skill-attention-sweep`, `skill-coordinate`, and `task-cycle-planning` Step 0. There is a second-order trap behind it: a run that trusts the dead cycle also tends to *infer* the date from the cycle end or a ticket title rather than from the clock, and so dates its own output into the past. (Worked case: the 2026-08-10 plan run reported the lapsed cycle as in flight, drafted a focus summary dated 2026-07-31, and called an already-passed BARA target "tomorrow" — caught only by a comment's own `createdAt` — APP-761.)
* **And a resolved, live cycle still reads back an *incomplete* set through the `cycle` param — derive membership another way, and cross-check the count.** With a good UUID and a live boundary, `list_issues(cycle: <uuid>)` returned six of the nine issues genuinely in the cycle — and the six rendered as a healthy, complete-looking result rather than an obvious error, so nothing marked the three as missing. The mitigation has two halves: **derive cycle membership from a team-scoped read filtered on `cycleId` client-side, never from the `cycle` param; and cross-check any enumerated set against the cycle's `issueCountHistory` / `completedIssueCountHistory` before reporting it.** The cross-check is the load-bearing half — it is what caught the miss, and it is cheap. **Where this rule and the per-project read-scope rule below disagree, membership wins and the sweep is paginated, not narrowed.** Deriving membership needs the whole team, because a ticket in no project is swept by nobody; per-project scoping governs the **body** read of the active set, which happens after membership is settled, and the two rules are sequential rather than in conflict once that is said. The working pattern is a team-scoped `list_issues` with a compact `fields` set that includes `cycleId`, paged by `hasNextPage`, filtered client-side, then cross-checked against `issueCountHistory`. On Apps **every page is expected to exceed the tool's token limit**, and that overflow is the normal route rather than a failure: each call still succeeds server-side and persists its result to a file, which is parsed in place of the response — the same recovery as the `get_document` spill below, opened with the Read tool. A run that treats the overflow as an error stops on a sweep that in fact completed, and a run that reads the responses inline spends most of its context on tickets it does not need. (Worked case: `task-cycle-planning`, 2026-09-14 — five pages of 250 on Apps at a minimal `fields` set, all five overflowing at 90–107k characters; A1 two pages, both overflowing; MBN one page clean. All three teams reconciled exactly against `issueCountHistory` once the persisted files were parsed — APP-1426.) This interacts with the read-scope rule below (a ticket in no project is swept by nobody): an incomplete set is not evidence of absence, so never infer that a ticket is out of the cycle from its not appearing in a cycle-scoped query. Whether the drop is the connector's or the `cycle` param's is the open question; the derive-and-cross-check mitigation holds either way. **When the enumerated set and the cycle's own count disagree, the run proceeds and reports the mismatch as a caveat — never a hard-fail** (Owner ruling, Aled 2026-09-03, APP-890): the ceremony or sweep states the mismatch on its proposal or report, names the missing IDs where it can, and never infers that a ticket is out of the cycle from its absence in a cycle-scoped query. A hard-fail would have stopped the only boundary run that has ever fired; a named caveat keeps the Owner informed without silencing the ceremony. The same posture governs APP-895's strictness question. (Worked case: Apps cycle 5, `task-cycle-planning` boundary run, 2026-08-14 — APP-882, APP-783 and APP-667 each carried the cycle-5 UUID and were absent from the cycle-scoped query — APP-890.)
* **For the Apps cycle read, the per-project scoping is the *expected* path, not a fallback discovered on overflow.** Canon frames per-project scoping as conditional ("scope per project rather than per team when a project's compact rows are still large", in the `fields` bullet below), which makes each run rediscover it. Fix it forward: **a team cycle above ~120 issues — or read for the non-completed states only — reads per-project by default.** The supporting fact is that **completed counts already come from `list_cycles` history, so the whole-cycle body read exists only to inspect the *active* tickets — a much smaller set** than the cycle's total. So `skill-plan` Pass 2's per-project cycle read is the default path for Apps, not an overflow contingency. Sequencing matters against APP-890 above: fixing the overflow alone would give a clean, complete-looking, still-incomplete read, so APP-890's correctness fix dominates and comes first — derive-and-cross-check membership, *then* scope the body read per project. (APP-894.)
* **The `query` param searches descriptions as well as titles — there is no title-only filter, so a workspace-wide title-prefix sweep is not achievable.** A dedupe implemented as `list_issues(query: "STRATEGY", limit: 50)` fails twice over: it **overflows** (every result carries its full body — ~75k characters), and what it does return is mostly tickets that merely *mention* the word somewhere in their description. Both failures read as something else — one like a tool error, the other like a healthy list of hits — so neither announces itself. Any prefix-convention dedupe (`STRATEGY:`, `FRICTION:`, `OPS:`) must therefore be **scoped by `team` (and `project` where one applies) and narrowed by state**, then matched on titles within that small result. Where a global sweep is genuinely unavoidable, expect the overflow and parse the saved payload out-of-band for `"title":"<PREFIX>` rather than raising the limit. (Worked case: `task-strategy-review`, 2026-07-20, recovered only by grepping the overflow file and re-querying per hit — APP-591.)
* **`list_comments` at the default limit can time out at 180s — ask for a small limit first.** Two comment reads issued in parallel each hit the 180-second timeout at the default limit and both succeeded immediately on retry at `limit: 10`. This matters most to the sweeps whose *eligibility* tests depend on comment reads (`skill-fleet-dispatch`, `skill-build-ticket`, `skill-coordinate`): a timed-out read doesn't fail the run, it just returns nothing, so an unmet dependency named in a comment goes unseen and the sweep proceeds as if the ticket were clean. Start at `limit: 10` and widen only when the tail of a thread is genuinely needed. (Worked case: `task-fleet-dispatch`, 2026-07-18, MBN-250 and APP-524 — APP-587.)
* **A batch of parallel reads can return its result blocks in an order other than the call order — bind each result to its issue from the block's own content, never from its position in the batch.** The bullet above fans comment reads out in parallel for speed; the order of what comes back is not part of that bargain. Two or more `list_comments` reads issued in one batch may surface their result blocks shuffled relative to the order they were issued, so a reader that pairs the nth block with the nth call silently attributes one ticket's thread to another — and the mis-attribution reads perfectly, because every block is individually well-formed and nothing errors. So carry the issue identifier out of each block's own body and match on that; where a block names no identifier of its own, re-issue that read alone rather than inferring which call it answered. Same class as the two traps above — a read that returns successfully and hands back the wrong thing — and costlier, because a wrong thread passes an eligibility test the ticket never satisfied. (`APP-2859`.)
* **A timeout is a different failure from an overflow, and it wants the opposite remedy — the working ceiling is `limit: 25` per project+state call.** Everything above about narrowing scope is written against *overflow* (the tool-result token limit). A correctly-scoped call can still **time out at 180s**: `list_issues(project: "os.Claude", state: "Blocked", limit: 50)` returned `timed out after 180s`, and the identical call at `limit: 25` returned in seconds. Overflow wants narrower **scope**; a timeout wants a smaller **page**. So scope by project and state as documented, then cap the page at ~25 and follow `hasNextPage` rather than asking for a big page once. Without the ceiling written down it gets rediscovered by burning a three-minute call each time. (Worked case: `task-coordinate`, 2026-07-20 — APP-594.)
* **A `state` write that names a state the team does not have is a silent no-op — read it back.** `save_issue(id: "MRP-21", state: "Refinement")` returned **HTTP success with the state unchanged at `Backlog` and `updatedAt` unmoved**: no error, no warning, nothing in the payload showing the param matched nothing. A run that trusted its own write would report the ticket parked in Refinement while it sat in Backlog re-surfacing on every poll. This is the write-side sibling of the dropped `work:engineering` label — same silent-drop family, different field. Check the team's real state set (see *Issue states*, and `list_issue_statuses` for a team you have not written to before) and read the write back. (Worked case: `task-triage`, 2026-07-20 — APP-620.)
* **A `targetDate` cannot be cleared through the connector, and `""` is a silent no-op.** `save_project.targetDate` and `save_initiative.targetDate` are typed as `TimelessDate` **string only** — unlike `lead` or `assignee`, which are `anyOf: [string, null]` and document "Null to remove". `targetDate: ""` returns HTTP 200 with the date unchanged and `updatedAt` unmoved; `targetDate: "null"` errors with `invalid_request`. **Clearing a target date is UI-only.** Related: `save_initiative.status` enumerates Proposed, Planned, Active, Completed, Canceled — there is **no Hold**, so an initiative cannot express "parked" at all, while a project can (`Hold`, type `planned`). **So do not depend on the write — depend on a reading rule: a target date on a `Hold` project, or on an initiative whose projects are all on Hold, is not a commitment and is never surfaced as urgency, a lapse, or a reason to promote work.** Parking is a decision; a deadline is a commitment, and the board must not assert one we have suspended. This is not hypothetical — the 2026-07-17 plan run read initiative targets and proposed re-targeting app.fitness and promoting parked Luna work, both on dates behind a Hold. (Aled's instruction, 2026-07-17; APP-586. The lifecycle and health semantics of project status proper are APP-418's.)
* **`list_projects` returns trashed projects as ordinary live rows unless `trashed` is selected in `fields` — select it on any project read that is reported or gated on.** A portfolio read on 2026-09-28 returned 51 projects, five of them in the trash (`gtd.Home`, `gtd.Health`, `gtd.Family`, `gtd.MBN`, `gtd.CareerOS`), each as a plain row at `status: Backlog` with nothing distinguishing it, and the set was presented to the Owner as the live portfolio; the identical call with `trashed` added returned 46. So the projection changes the result set, which is not what the parameter name implies, and `includeArchived: false` does not cover it. This is worse than the filter traps above rather than another of them: they return too few or too many real objects, this one returns **deleted objects asserted as live**, so a liveness gate reads a trashed project's `statusType` as a real one. Two corroborations from the same read: `save_project(id: "P-APP-13", state: "Canceled")` returned `400 invalid_request — Could not modify trashed project`, and `list_issues(project: "gtd.Home")` returned `Could not find project` minutes after that project had appeared healthy. So **resolve a single project by its P-TEAM-N identifier rather than by name** — a trashed project fails a name lookup loudly, which is the one place this class announces itself. Untested and therefore not asserted: whether `list_issues`, `list_initiatives` and `list_documents` behave the same for their own deleted objects, and whether a ticket stranded in a trashed project is reachable by any sweep. (APP-1844, 2026-09-28, corrected 2026-09-29.)
* **A ticket in no project is swept by nobody — a project-scoped read cannot report what it cannot see.** Coordinate, plan and the daily report all gate on project liveness (`statusType == started`), which is correct and deliberate — but "sweep the live projects" silently means a ticket with no `projectId` is out of every sweep's reach. A parked project's ticket returns when the project restarts; a projectless ticket never returns at all. The worst case is an **outcome epic**: it carries the engagement's acceptance criteria and is the ticket the operator closes to declare the outcome met, and its absence also breaks the roll-up, so the project board shows the leaves without their parent. So a project-scoped sweep is incomplete by construction, and the counterpart check belongs beside it: where a parent with children carries no project and its children unanimously share one, that is a structural defect to surface. (Worked case: A1-110, the a1.Firmup outcome epic with nine-plus children all correctly homed, found only incidentally by an unrelated `get_issue`, 2026-07-21 — APP-622. Third member of the readable-but-wrong parent family with the terminal-state parent and the cross-team parent of APP-565.)
* **`list_issues` takes a `fields` param — select compact fields and the full-description overflow does not arise.** The connector *does* expose field selection: pass `fields` (e.g. `["title","status","labels","assignee","project","parentId","url"]`) and each row returns only those keys, with the long `description` body omitted, so a whole-team or whole-project read that would otherwise exceed the tool's token limit comes back clean. This is the first and usually the only defence needed — reach for it before narrowing by state, project, or limit, and pull a single ticket's full body with `get_issue` only when you actually need it. (Verified on the `task-pulse-retro` drain, 2026-08-10: the entire `PUL-5E` Backlog read in one `limit:100` call with a compact `fields` set, no overflow, where the same read at default fields had historically forced a per-project subagent parse — APP-742.) The earlier guidance here — that the connector exposes *no* field-selection option, so an out-of-band subagent parse is the standard mitigation — was wrong; the `fields` param retires that parse as a routine step. It survives only as a genuine last resort: where the full `description` bodies of a large set are all needed in one pass (not just their compact rows), save the raw result and hand a subagent a character-range slice returning the compact fields (id/title/status/labels/assignee/project/parentId). A whole-team query at **default** fields still returns every body and still overflows (Apps has run ~387k characters), so the rule is to set `fields`, not to drop the narrowing habits entirely — scope per project rather than per team when a project's compact rows are still large.
* **Compact `fields` is not unlimited — a large page can still overflow, so cap the page as well as the fields.** The `fields` remedy strips the description bodies, but it does not make the row count free: a single `list_issues` at `limit: 250` with a compact `fields` set still overflowed the tool's token limit on a busy team. So `fields` and a bounded page are complementary, not alternatives — select compact fields *and* keep the page modest, following `hasNextPage` rather than asking for 250 rows at once. This sharpens the `fields` remedy above rather than contradicting it: compact fields stays the first defence, but it does not retire paging. (APP-828.)
* **A bulk** `list_issues` **read with** `description` **in** `fields` **returns clipped bodies — read full descriptions with** `get_issue`**.** Selecting `description` in a bulk read returned each row's description cut at about 500 characters, and at `limit: 100` the page still overflowed (about 60k characters). A clipped description reads as whole, like the `list_documents` content truncation below (APP-906), so never judge a ticket's headings, acceptance criteria or estimate inputs from one. Where a pass needs many full bodies, read them per ticket with `get_issue`; where a bulk read has already spilled to a saved file, extract from that file (the overflow route in this section). (Observed once — `task-aide-loop`, 2026-09-21, the APP-1307 estimate pass — APP-1597.)
* **The `fields` enum holds no relations member — blocked-by state cannot be read from `list_issues` at any field set, and `get_issue` omits relations unless asked.** Checked against the live tool schema, 2026-08-10 — **and the enumeration that follows is superseded as an inventory, though not as a conclusion. Re-measured live 2026-10-19:** `get_issue`'s `fields` enum now carries `stateHistory`, `relations`, `attachments` and `documents`, while `list_issues`' enum carries **none** of the four. The two enums have diverged, and the divergence is the reason the blocked-by conclusion below is not a quirk of one reading: per-ticket history and per-ticket relations are reachable only through the per-ticket call, and no amount of `list_issues` field tuning reaches them, because the members that would carry them are not in that tool's enum at all. Read the 2026-08-10 list below as the dated snapshot it is, not as today's membership — the conclusion it reaches is unaffected and stands as written. The snapshot: `fields` enumerates `id`, `title`, `description`, `projectMilestone`, `priority`, `estimate`, `url`, `gitBranchName`, the timestamps, `dueDate` and the SLA fields, `status`, `statusType`, `labels`, `triageIntel`, `createdBy`, `assignee`, `delegate`, `project`, `projectId`, `parentId`, `team`, `teamId` and `cycleId`. So *hierarchy* is selectable (`parentId`) but *relations are not* — there is no `blockedBy`, `blocks`, `relatedTo` or `relations` member, and no separate relations parameter on the tool. A list read therefore cannot distinguish a blocked ticket from a free one however it is scoped, and no amount of `fields` tuning changes that. The only source is **`get_issue(includeRelations: true)`**, and `includeRelations` **defaults to `false`** — a plain `get_issue` returns the ticket with no relations rather than an error, which reads exactly like a ticket with no blockers. Four consequences worth holding:

  - **The per-candidate `get_issue` is an irreducible floor, so make the blocked-by test the *last* filter** — after label, state, project and team have cut the candidate set as small as it will go. Any eligibility scan gating on blocked-by pays one read per surviving candidate, every run.
  - **Never infer "not blocked"** from a list row, or from a `get_issue` that did not pass `includeRelations: true`. And **never infer "correctly blocked" from a resolved status**: a blocker reaching Done says the blocker shipped, not that it covered what the dependent needed — a mis-targeted relation resolves as cleanly as a correct one. The write-side rule (`convention-ticket`: a `blockedBy` carries a one-line statement of what the blocker must deliver) is what makes coverage testable at release; on the read side, compare that line against the blocker's outcome before treating the dependent as released (MBN-250 → MBN-262, APP-1014).
  - **The follow-on blocker-state reads are *not* irreducible.** Having collected the blocker IDs, resolve whether each is Done or Canceled against a compact `list_issues(team: …, fields: ["title","status","statusType"])` map of the teams in scope — cheap since the `fields` param above — rather than a `get_issue` per blocker.

  - **A nonempty `fields` selection overrides `includeRelations`, and a multi-blocker ticket needs every row checked.** `get_issue(includeRelations: true, fields: ["title","status","labels","parentId","assignee"])` returns **no relations key at all** — not an empty one, not an error — because a nonempty `fields` selection overrides the include options; relations arrive only when `"relations"` is itself named in `fields`. So on any read that selects fields, pass **`includeRelations: true` *and* `"relations"` in `fields`**, and treat a missing relations key as *unread*, never as unblocked. Then read **every `blockedBy` row the call returns**: a triage or promotion write that clears one named blocker clears none of the others, so a ticket whose prose names one of three blockers reads as released while two stay open. (13 wasted re-reads on the 2026-10-09 fleet-dispatch sweep; MBN-287 sat 4 days in Todo, apparently-ready and actually blocked by MBN-285 and MBN-286, after a triage comment verified only the prose-named MBN-270 — APP-2203. Distinct from APP-1943, which is prose-vs-formal: here the formal relations were read, just not all of them.)

  The corollary is on the write side: a dependency recorded only in prose — a triage comment naming blockers — is invisible to this check entirely, so set a real `blockedBy` relation (see *Writing Linear safely*). (Worked case: `routine-delivery-loop`, 2026-07-26 and unchanged on 2026-08-04 — 5 `F0-RGE` Todo candidates plus 4 blockers cost 9 reads to conclude the queue was empty, and the identical reads recurred on every run for as long as the blocks stood, one of them since mid-June. MBN-251's blockers were at first discoverable only through a triage comment carrying pre-renumber IDs, and became visible to the scan only once real relations were set — APP-685.)
* **`get_document` on a large document overflows to a host temp path the sandbox cannot reach — open the persisted payload with the Read tool, not the shell.** A document of ~50KB is enough: the result exceeds the tool limit and is persisted to a file under `/var/folders/…` on the *host*, which the Linux sandbox does not mount, so a shell `grep` of it fails and the read looks **empty rather than truncated** — the failure presents as an absent document, not an oversized one. The recovery is to open that persisted payload with the **Read** tool, which does reach it. And unlike `list_issues`, the document endpoint offers **no field-selection and no section-fetch mode**, so the `fields` remedy above does not transfer and there is no narrowing to fall back on: the payload is all-or-nothing. This composes badly with a **full-content** write — passing `content` replaces the whole document, so a partial read followed by a whole-document write clobbers everything that was never read. **But a whole-document write is not the only form: `save_document` takes a `patch` parameter**, the same shape as `save_issue`'s, with ops `replace | insert_before | insert_after | prepend | append | replace_range`. So an overflowing document is *extended* rather than rewritten: `{"op": "append", "text": "…"}` needs no anchor, carries none of the existing text into the call, and is the correct route for a growing log or standup document — which also means the transcription risk *Writing Linear safely* warns about never arises, because the append carries no hand-typed `<issue>` tag for anything already there and Linear auto-links the bare `<TEAM>-###` references in the new text itself. Only `append` has been exercised on a document; `replace`, `insert_before`, `insert_after`, `prepend` and `replace_range` are **unverified** there, and the silent-corruption class recorded below for `save_issue`'s `patch` has no tested document-side equivalent — so read the result back either way, per the write-echo rule. The stated limits are **50 operations per call**, applied in order and atomically, so one failing operation aborts the whole save and leaves the document as it was, and **every anchor must match the current content exactly once**, exactly as `save_issue`'s must. (Worked case: a `task-a1-operator-standup` run of 2026-09-23 faced reproducing ~70,000 characters of `a1.standup`, including dozens of UUID references it had never had in context because the *read* had already overflowed to a saved file; one `append` added the new entry alone, touched none of the existing ~68,000 characters, and read back clean — 67,650 → 72,597 characters. Canon had denied that this form existed while, in the write-echo bullet below, already narrating two successive `save_document` patches of its own — APP-1667.) Treat a document read that returned nothing usable as a hard stop before any write, never as an empty document. (Worked case: `skill-dispatch-run` on the `task-fleet-dispatch` run of 2026-07-28, editing `spec.meirion-design-system` — APP-702.) Three residuals the core trap does not cover, all found on the growing weekly decision-log bucket. First, **`list_documents` with `fields: ["content"]` also truncates**, so it is not the escape hatch a reader reaches for when `get_document` overflows — it returns a clipped body that reads as whole, not an error. Second, the read-back-after-a-patched-write rule is still tractable on a document too large to re-read, via **slice verification**: compare the document's character length before and after the write against the expected delta, count `### ` headings against the expected number, and probe each known entry title for **exactly one** occurrence — three cheap checks that together catch an over-delete or a silent no-op without re-reading the whole body. Third, there is a **second, harder failure mode** distinct from the spill-to-host-file case above: the read can return a **hard error** (`exceeds maximum allowed tokens`) rather than returning inline. **The clause this replaces claimed that form leaves no persisted payload to open with Read, and that is not what this surface does.** Re-measured 2026-11-06, `a1.standup.2026-W45` at **77,731** characters and `bara.standup.2026-W45` at **62,771** both returned `exceeds maximum allowed tokens` **and** persisted a payload, the error naming the saved file — so on this surface the recovery is to **open the named file and slice it by character range**, not to fall back to the write side. Slice-verification is kept for the **write** side, where it answers a different question, and a hard error reported as leaving no payload is treated as a case to **re-measure** rather than as an established threshold — the figure of around 61k included, since what binds is the *returned* payload, which Linear inflates by expanding bare identifiers into full `<issue …/>` tags on read (`APP-2912`). (Worked case: the bot.Trader operator daily read, 2026-08-14 — `bottrader.log-decisions.2026-W33`, growing monotonically past both limits — APP-906.)
* **Don't mutate on a parsed or bulk-read field — re-fetch it with `get_issue` immediately before a state-changing write, and re-confirm it the same way before a load-bearing assertion about a named ticket.** The rule began as a write rule, and that scoping left it without a read-side half: a pass that only *says* something about a ticket changes nothing, so nothing in the rule asked it to re-confirm anything. It should. **Before a pass characterises a named ticket as an anomaly — silently held, unrouted, overdue — it re-confirms that ticket's relevant fields with a direct `get_issue`.** An anomaly claim about a named ticket is the cheapest class of finding to assert and the most expensive to get wrong in the false-positive direction: it reads as confident and plausible, it names a ticket the Owner can open, and nothing downstream re-reads it before he does. The check costs one call, because it is scoped to the handful a bulk read flags as noteworthy and never to the population — that scoping is what makes it affordable, and it is the reason this is stated as a rule rather than as a caution. Whether a wrong row comes from a subagent's transcription or from a quirk of the bulk read itself is **left unasserted**: the remedy is identical either way, which is why one observation is enough to carry it. (Worked case: on 2026-10-15 an operator stand-up's compact bulk read, selecting `labels` among its fields, reported a named ticket as carrying no `human` — which would have made it that vertical's one live silently-held item under the read recipe, and put a false "nobody has looked at this" into a stand-up the Owner reads. A direct `get_issue` taken immediately before the entry was written returned the label set with `human` present, and the ticket's own history showed no label write near the read, so the row was wrong at read time rather than stale from a real change. One instance, one ticket, one field, one run — reported — APP-2389.) The write half, which this rule began as, follows. When a sweep will *change* a field (state, labels) and the candidate came from a bulk `list_issues` — especially the overflow-forced out-of-band subagent parse above, whose positional column alignment is unreliable — confirm the ticket's *current* `status` (and any other field the write depends on) via `get_issue` just before writing. A parsed `state` column has gone stale silently (worked case: triage applied in-thread cancellation decisions to four already-Canceled tickets and posted confirming comments, 2026-06-29 — harmless noise on closed tickets, but the same trust on a live state or label write would act on the wrong ticket). The read filter trap above tells you the *list* can mislead; this tells you to re-verify the single field you are about to write.
* **A write's response can lag per field, not per write — read back every field the call wrote, not only the state.** The widening case is a single call: on APP-1611 (`skill-build-ticket` hand-off, 2026-09-22) one `save_issue` passing `state: "In Review"`, `assignee: null` and a full `labels` replace echoed the **old** state *and* the **old** assignee, while the `labels` value in the very same response came back correct. So the stale echo selects fields *within* one response rather than lagging the call as a whole, and the read-back accordingly owes coverage of **every field the write set**, not the state alone. An immediate `get_issue` showed all three had in fact landed; a run that had trusted the echo would have handed the ticket off believing it was still In Progress and still assigned to Aled (APP-1650). The original, state-only case: When `save_issue` moves a ticket between states (notably In Progress → In Review), the response object sometimes still shows the *old* state even though the write succeeded and the Linear UI shows the new one (worked case: APP-375, APP-376, delivery loop, 2026-06-30). A second identical write returns the correct state, but the loop should not branch on the first response: after any state-change write, read the state back — via the next `get_issue`, or by treating a re-fetch as ground truth — before deciding the ticket's actual state, rather than retrying blindly or misjudging the transition from a stale response. This is the write-side mirror of the re-fetch-before-write rule above: that one distrusts a stale *read* before writing; this one distrusts a stale *response* after writing. The underlying cause — a Linear API propagation race or MCP-tool cache — is the connector's, not ours to fix; the defensive read-back is the canon mitigation. **And one read-back is not enough — the stale window outlasts the write's own response, so a write is confirmed only when two consecutive independent reads agree.** Everything above treats the immediate `get_issue` as ground truth. On 2026-10-04 it was not. A `save_issue` on A1-581 passing `removeLabels: ["PR-1SM"]` + `addLabels: ["operator-a1"]` returned 200 with a full payload still showing the **old** label set — and so did the next **two** independent reads (`get_issue`, then `list_issues`), each with `updatedAt` unmoved. The third read showed the new set and a bumped `updatedAt`; a separate `removeLabels` call issued in between errored *"not on issue… and cannot be removed"*, proving the first write had in fact landed server-side while three successive reads denied it. A near-identical shape recurred minutes later on the merge leg's own full `labels` replace evicting `R3-LAY`: first post-write read stale, second correct. So the lag is **not** confined to the write's returned payload, and it is not confined to `state` and `assignee` — **labels lag the same way.** The rule: after any `save_issue` write, re-read until **two consecutive independent reads return the same value for every field the write set**, and treat a single disagreeing read as *inconclusive*, never as a failed write. **This governs the retry-once-on-no-op rule in *Writing Linear safely* below (APP-1448), which it would otherwise contradict:** an apparent no-op — 200 with the field absent and `updatedAt` unmoved — is indistinguishable at one read from a stale echo, so take the two agreeing reads **before** retrying. The cost of getting this wrong is not a wasted call: an automated leg that reads one stale response on a bounce-cap executor-clear or a post-merge label eviction concludes a routing write failed, and then either retries destructively or escalates on a false premise. (APP-2023; the state+assignee case is APP-1650, the per-field case APP-1611.) **And the rule confirms a write; it never diagnoses one.** Everything above addresses the pass that *made* the write, in the session that made it, where only two readings exist — landed, or not yet visible. A later pass comparing a ticket's current labels against an older comment's claim is in a different position and the two agreeing reads do not serve it: they establish that the current state is being read correctly and say nothing about *why* it disagrees with the comment. Three readings compete there — the write never landed, the write landed and was since undone, or the write landed, was correctly acted on, and the resulting state is identical to the pre-write state. The hand-off write (*Operator attribution*) **produces that third shape by design**: `operator-<venture>`, no `agent`-group value, no `human` is both the correct resting state of a genuine operator hold and the correct resting state of a fleet executor that has just completed and cleared itself (`skill-dispatch-run` step 5), and it can be seconds old. So before any pass concludes from a comment-versus-label disagreement that a write silently failed — and above all before it re-applies the write — it reads the **full comment thread** (`list_comments`) for activity intervening between that comment and the read, and checks the ticket's own `startedAt`, `completedAt` and `updatedAt` against the comment's timestamp. Where the thread shows the claimed write was made and consumed, there is no failure to repair, and re-arming the executor undoes a hand-off that was never broken. Where the thread is silent, the silent-failure reading stands and is reported with the thread read that supports it. (Worked case: on 2026-10-13 `task-mrp-operator-standup` read MRP-78 — In Review, `operator-mrp`, no executor, no `human` — against a 2026-10-12 11:25Z comment claiming *Executor set to* `agent:R3-ACH`, took the two agreeing reads this bullet prescribes, concluded a silent write failure, and re-applied `R3-ACH` by full `labels` replace. Reach had in fact run 07:05–07:08Z that same morning and cleared its own executor on completion; `startedAt` was stamped 07:05:19Z, newer than the comment, and the 07:06–07:08Z completion comments were one `list_comments` away. Caught and reverted in the same run before anything left the session. The run's own timings and the revert are reported from its filing and not re-read here — APP-2302.)
* **A write to a ticket resting in In Review or Blocked used to revert its state and reassign it silently — the automation behind that was disabled on 2026-09-02; keep the read-back as cheap belt-and-braces, not as the standing mitigation.** Until then a workspace automation re-applied "active state + assign creator" *after* a write landed, on more trigger paths than first documented: a call passing `state` and `assignee: null` together, a **labels-only** write and an **assignee-only** write each reverted an In Review ticket to In Progress and set the assignee to the creator (worked cases: A1-49 / APP-404 combined-call, 2026-07-01; A1-125 labels-only ×2, A1-124 and APP-439 assignee-only, 2026-07-06; A1-149 assignee-only, 2026-07-09 — APP-478; APP-1023 assignee-only on the QA hand-off, 2026-08-18 — APP-1024). The clean fix was always the workspace setting, and it has now been made (Owner decision, Aled 2026-09-02): both "move issue to started" toggles are off, the PR automations on the Apps, A1 and MBN teams are set to No action, and auto-assign was already off. What remains is defensive and cheap: **after a `save_issue` write to a ticket that should be resting in In Review or Blocked, glance at the returned `status` (or the next `get_issue`); if it regressed, re-set it in a follow-up call and record the instance on a FRICTION note** — a fresh reversion now means a re-enabled or previously unnoticed rule, not the known one. One residual no setting switches off stays: linking a PR assigns the PR author to an *unassigned* issue; the `skill-build-ticket` mitigation (APP-936) covers that and is unaffected. (This supersedes the earlier standing-mitigation form of this bullet; the pattern is kept because a read-back costs one field-glance and the failure it guarded against was silent and in the safe-looking direction.)
* **A relative-duration `updatedAt` / `createdAt` filter is silently dropped — pass an absolute ISO timestamp, and check the oldest returned row against the boundary.** The `updatedAt` param's own schema advertises the ISO-8601 duration form (`-P7D`, `-P1D`), but passing it returns **HTTP success with the filter not applied** — a clean-looking page of ~100 plausible rows, including tickets last touched months before the window. The identical read with an **absolute timestamp** (`updatedAt: "2026-08-17T12:00:00Z"`) narrows correctly on every team and project. This is the third member of the silent-filter family beside the `state: "Backlog"` over-return and the `cycle: "current"` under-return, and the most convincing of the three because a hundred plausible rows read as a healthy result. It bites exactly the passes that cannot tolerate it — the movement-since-last-run reads: `skill-goal-review` Pass 2, `task-strategy-review`, `skill-plan`, `skill-coordinate`'s comment watermark, and the operator stand-ups' "what moved yesterday" step — a run that trusts it reports months-old completions as this week's movement, inflating throughput and reporting a stalled venture as active. So pass an absolute timestamp, never a duration, and after any time-windowed read glance at the oldest returned item against the boundary — one look catches a dropped filter, nothing else will. (Not verified whether `createdAt` and other duration-accepting tools drop it identically; the absolute-timestamp form is safe everywhere, so prefer it unconditionally. Composes with APP-1011: `updatedAt` is also bulk-re-stamped, so it is a weak activity signal even when the filter applies. APP-1046.)
* **`completedAt` is now filterable — it was not on 2026-09-10 and it is on 2026-11-11, so filter on it directly rather than reaching for the `updatedAt` substitute first.** Two dated reads of the live tool schema, both kept, because the change between them is the point. **Checked against the live tool schema, 2026-09-10:** `list_issues` exposed `completedAt` in the **`fields` enum only**; the only two time params it filtered on were `createdAt` and `updatedAt`, so "what closed in this window" had no direct query and a skill that prescribed one could not be followed literally — `skill-operating-loop`'s read recipe (*what closed and what was raised* to be read "time-windowed on `completedAt` and `createdAt`, never `updatedAt`") was right about the signal and impossible as a filter. That remains a correct observation of its date and is kept as the record. **Re-read on this surface, 2026-11-11:** `list_issues` now carries a `completedAt` **filter** param, documented in the live tool schema as *"Completed after: ISO-8601 date/duration (e.g., -P1D). Excludes issues that are not completed"* — so it is a time bound and a completed-only filter in one, and `skill-operating-loop`'s recipe is now literally followable. **The working form:** pass an absolute `completedAt` timestamp at the window's start, scoped by `team` or `project`, and select `completedAt` in `fields` to read each row's own value back; because the param already excludes anything not completed, a `state` passed alongside it is redundant rather than required. Verified by one call this run — `list_issues(completedAt: "2026-11-09T10:22:39.000Z", label: "PUL-5E", state: "Done", team: "Apps")` returned ten rows, every one's own `completedAt` at or after the boundary, `hasNextPage: false`. That call named the state `Done`, which team `Apps` has; **it is not a licence to name a state** — the filter-on-the-type rule below is untouched and still governs wherever a `state` is passed. **And read the schema, not this bullet, before concluding a param does not exist:** this one moved under canon between two dated reads two months apart, and the only reason it was caught is that someone re-read it. (`APP-1993` and `APP-1210` carry the 2026-09-10 state and the substitute; the 2026-11-11 re-read and the verifying call are **observed on the refine surface this run** and carry no filing note.)  **The two-step substitute that follows remains correct and is now the fallback rather than the first move** — reach for it where the window has to be bounded on something other than completion, or on a surface found to still lack the filter. The working substitute is two steps: filter on the status **type**, `state: "completed"` — scoped by `team` or `project`, with an **absolute** `updatedAt` timestamp at the window's start (per the bullet above) — then compare each returned row's own `completedAt` against the boundary **client-side** and discard the rest. Select `completedAt` explicitly in `fields`; it is not in the default row. **Filter on the type, never on the state name `Done`, and this is not a style preference — the named form returns a silent zero on any team that has no state of that name.** Mr Pritchard has none: its states are Scheduled, Ready, Defined, Published, In Review, In Progress, Todo, Backlog, Duplicate and Canceled, and its two **completed**-type states are `Published` and `Scheduled` (verified by `list_issue_statuses`, re-verified 2026-10-05). `list_issues(team: "Mr Pritchard", state: "Done", …)` returns `{"issues":[]}` with no error; `state: "completed"` on the same call returns the real set — six completions all-time, the most recent 2026-09-01T18:27:45Z. Every pass that reads closed work by the literal name is affected on that team — `skill-coordinate`'s movement read, `task-daily-report`, the operator stand-ups' *what moved yesterday*, `skill-goal-review` Pass 2, `skill-operating-loop`'s what-closed read, `task-cycle-planning`'s throughput step — and all of them report a dormant board as a *clean* board. **The shape that makes it the worst member of the silent-filter family: the false negative can agree with the truth.** For the cycle under test the honest answer was also zero, so a run trusting the bad query would have produced the right number by coincidence, with no discrepancy to notice — while the figures it actually needed (a 31-day dry spell, and four completions on 2026-09-01) stayed invisible. A false negative that agrees with the truth never announces itself. (APP-1993. The write-side sibling is the silent-no-op bullet above — a `state` write naming a state the team does not have, APP-620. Two tickets, MRP-7 and MRP-8, were flipped to `Published` at 2026-09-01T18:30:15Z and reverted to `Todo` 23–25 seconds later: visible in state history, absent from every completed-set read, and **not** counted as completions — where a `completedAt` read and a state-history read of a team disagree, the state-history one is the misleading one.) **The coincidence that makes the substitute safe is worth stating, because it looks like the trap next door:** a Done transition is a write, so it stamps `updatedAt` as well — a ticket that closed inside the window therefore cannot fall outside an `updatedAt` window covering it, and the pre-filter can only be too wide, never too narrow. `updatedAt` remains a cache key and not an activity log (APP-1011); here it is used only as a cheap over-inclusive **pre-filter** to bound the page, with `completedAt` — set once, never re-stamped — doing the actual selection. Nothing about this weakens the cache-key warning; it is the reason the client-side check is not optional. (APP-1210.)
* **An empty page with `hasNextPage: true` is inconclusive — never read absence from it.** `list_issues` can return `{"issues":[],"hasNextPage":true}`: no matches *on this page* while more pages exist. Read as a human reads it, that says "no such ticket", which is precisely what a dedupe or eligibility gate needs to know — and it is not what the response means. Where a read's *emptiness* is load-bearing (a dedupe, an eligibility test, an "is there already a ticket for this" check), follow the cursor or re-run at a wider scope before concluding absence; never infer "no such ticket exists" from a single empty page. Same silent-shape family as the incomplete cycle-scoped read (APP-890) — a plausible partial result with nothing marking the absence. (Worked case: a `query: "STRATEGY"` project read returned an empty page with `hasNextPage: true` while the unfiltered project held 25 issues; correct that run only by luck — APP-979.)
* **An exhaustive cursor-paginated sweep ordered by `updatedAt` can lose a row mid-scan — order it by `createdAt`, or treat the result as provisional and cross-check its membership against an independent query.** The two bullets above distrust a *filter* on `updatedAt` and a *single empty page*. This one distrusts a read with neither fault: the scope was right, the `fields` selection was right, and it was paged by `cursor` all the way to `hasNextPage: false`. `list_issues` orders by `updatedAt` **by default** and offers only `createdAt` as the alternative, so an exhaustive sweep walks a key that **anything touching a ticket re-stamps — including the sweep's own sibling calls in the same session.** The **suspected** mechanism, and it is a suspicion rather than anything observed: where a row's `updatedAt` changes between the fetch of page N and the fetch of page N+1, the row can move across the page boundary and appear on neither — gone from the page it moved out of, and behind the cursor by the time it reaches where it moved to. **The rule does not rest on that being the right mechanism.** Whatever moved it, a fully paginated read of an active board returned a complete-looking result that was short by one row, and `hasNextPage: false` is what made it look complete — so take that flag for exactly what it is: **it proves the pages were walked to the end, never that the population was covered.** Two remedies, either sufficient. **Order an exhaustive sweep by a key nothing re-stamps** — `createdAt`, set once at creation, so no row can move while the scan is in flight; this is the one to reach for when the sweep's whole purpose is completeness, and ordering by creation costs a long-overdue sweep nothing, since it sorts client-side on `dueDate` anyway. Or keep the default order and treat the enumerated set as **provisional**, cross-checking its membership against an independent query — a state-bucketed read, or the same population reached another way — before asserting completeness. That is the same derive-and-cross-check discipline the `cycle`-param bullet above already prescribes, for the same reason and with the same division of labour: the cross-check is the cheap half and it is the half that catches the miss. **The selection bias is what makes this a rule rather than a caveat.** The rows an overdue sweep exists to surface are the ones nobody has touched for months, so the one incidental re-touch that moves a row across a page boundary lands preferentially on exactly the item the sweep was run to find — and the sweep then reports a clean board in the case where it is most wrong, which is the silent direction this whole section is about. (Worked case: `task-a1-operator-standup`, 2026-10-26 — a team-scoped `list_issues(team: "A1", limit: 250)` overdue-date sweep paged by cursor to `hasNextPage: false` across three pages, 750 rows, default order. `A1-24` was absent from both pages that should have carried it, and surfaced only because a separate state-scoped read in the same session returned it; several other calls in that session touched it. Caught before anything was written, so there was no downstream consequence — the finding is the canon gap, not a missed escalation. The sweep's three pages, its 750-row count and its saved page files are the standup leg's **report** and were not re-run here; `A1-24`'s own particulars were re-read live — due 2026-08-07, `statusType: started`, team A1, project `a1.assoc-one`, 80 days overdue at the run date, and the single oldest item the sweep should have returned. Distinct from APP-2131, a label-scope miss, and APP-2339, an undated-signal miss: in both of those the scope or the signal was wrong, while here both were correct and the sort key was the fault. APP-2671.)
* **`get_status_updates` overflows and has no `fields` or scope narrowing — read it per-project with a short window, and recover a spill with the Read tool.** The status-update endpoint is the health-report backbone (`convention-project-status`), and a natural cross-venture read — `get_status_updates(type: "project", createdAt: "-P21D", limit: 40)` — returned 111k characters and overflowed; the `type: "initiative"` form overflowed too. None of the documented overflow playbook transfers: the `fields` remedy (APP-742) is `list_issues`-only and this tool exposes no `fields` param, so the bodies — the whole point of a status update, routinely 3–5k characters each under the operator-report format — cannot be stripped; the narrow-by-scope remedies have no equivalent beyond *one project at a time* or *a shorter window*; and the `get_document` entry (APP-906) names only that tool. The payload grows monotonically as the operator layer matures (each of the five weekly operator loops writes a long status update per project), so the same window costs more every week. The second-order risk is the load-bearing one: a run that does not recognise the spill can read it as *no updates in the window* rather than *too many*, and `convention-project-status` says a missing health signal means **no signal, never on track** — so the wrong branch is taken silently, the APP-895 infer-absence-from-a-partial-read failure with a health assertion on the end of it. So default the cross-venture health read to **per-project with `limit: 1–2`** (the analogue of APP-894's "per-project scoping is the expected path, not a fallback") rather than a windowed sweep, and where a call does overflow to a host temp path, open that persisted payload with the **Read** tool, never a shell `grep`. (Possible companion: operator status-update bodies have become long-form Owner reports, so `convention-comms-owner` may want a length discipline for the update body — named for the Owner, not authored here. APP-1045.)

## Writing Linear safely — never reference an issue that does not exist yet

The traps above are read-side and write-side: the call succeeds and does the wrong thing. There is a third of the same shape on the **reference** side, and it is the most convincing of the lot, because the result renders perfectly.

**A pass that writes on a rule about a ticket's category reads that ticket's own thread first, and never overwrites an explicit terminal verdict.** A blanket rule and a field-shape heuristic are both cheaper to run than reading history, and both silently discard a deliberate prior decision. So before a categorical write — a relabel, a state bounce, a re-route — read the thread and skip the ticket where a prior pass recorded a considered terminal verdict; surface the disagreement instead of resolving it. **In particular, In Review with no PR attached and the criteria unchecked is the expected resting shape of a correct no-op**, not evidence that nothing was delivered. (Worked cases, one delivery-loop run of 2026-09-28: eight `human`-lane tickets relabelled to R3-LAY under a blanket "no human faculty in it" rule that did not distinguish *no judgement needed* from *needs Aled's eyes*, corrected the same run — A1-380, A1-386, A1-417, MBN-277, MBN-315, MBN-318, APP-531, APP-1718; and A1-533, routed In Review + `human` + Aled on 2026-09-26 as a genuine no-op already satisfied on unmodified `main`, bounced back to Todo + F0-RGE on 2026-09-28 without the explaining comment being read, and restored — APP-1838.)

* **An `APP-###` written before that issue exists resolves to whatever issue already holds the number.** Linear does not error on a forward reference — it binds it to an unrelated live ticket and embeds a working link carrying that ticket's real title. Nothing in the write-back signals a problem: the table renders, the links work, and only opening one reveals it points elsewhere. Hit twice in a single `task-triage` session, 2026-07-21 — `APP-429`'s planned children table cited three numbers before the children were created and bound all three to unrelated FRICTION notes; `APP-627` cited a number for a note that in fact landed elsewhere. Both were caught only by reading the write-back's auto-linked titles and noticing they did not match intent.
* **So: create first, reference second.** Take the `id` from the create response and write *that* into prose. Where a parent must list its children, this is deliberately **two writes** — create the children with `parentId` set, then update the parent body with the returned IDs. Never draft a body around numbers you expect to be assigned.
* **The rule binds hardest on `blockedBy` / `blocks` / `relatedTo`.** A guessed ID there creates a *real* relation to the wrong ticket — harder to spot than wrong prose, and it changes what the delivery loop and the Pulse drain will act on. **And a relation write aimed at a ticket that already carries a differently-typed edge to the same ticket does not add a second edge — it converts the one that is there.** Treating these params as append-only is right about the **named parameter** and wrong across types: passing `blocks: [X]` where X is already in `relatedTo` leaves the ticket with a `blocks` edge to X and **no** `relatedTo` edge to X. Nothing errors and nothing is reported. Observed 2026-10-05 on APP-1735: `save_issue(id, blocks: ["A1-413", "A1-389"])` landed, both tickets were in `relatedTo` **before** the write, and both were **absent from `relatedTo` after** it — Linear converted the two existing relation records rather than adding to them. The net effect was what that sweep wanted, but the two `relatedTo` edges were consumed, not kept. **So the common move of promoting a prose prerequisite into a formal relation — which *Reading Linear safely* explicitly asks for, in the relations bullet's write-side corollary — silently destroys any existing `relatedTo` to that ticket, and a sweep that wants both kinds of edge cannot have both.** Decide which edge type is the one worth keeping *before* the write, because no single call holds two. This is the same silent-eviction family as the single-select `labels` replace below, reached from relations instead of labels. The read-back rule in the next bullet is the only thing that reports it, and here it must be a `get_issue(includeRelations: true)` on the endpoints rather than a glance at the response: **the `save_issue` response omitted the relations block entirely on all three relation writes made in that session**, so no relation write is self-evidencing. (Session-observed 2026-10-05 on APP-1735; **no note, closes nothing**. The guessed-ID half above remains APP-637 / APP-1326's.)
* **A description `patch` can materialise a relation edge from a long-standing inline mention — re-read the relation set after any body write.** The two traps above are relation writes going wrong: a guessed ID creating a real edge to the wrong ticket, and a differently-typed relation write converting the edge already there instead of adding one. This is the same silent-relation family reached from a third direction, and it is the one no relation discipline guards, because **no relation was written at all**. A `save_issue` carrying only a description `patch` on APP-1144 took that ticket from **three** `relatedTo` edges to **four**: the new edge, to APP-1131, was created from an inline mention that had sat unchanged in the body for weeks and had never been an edge. Nothing in the call asked for a relation and nothing in the response reported one — the `save_issue` response omits the relations block, exactly as the bullet above records. So the direction of the damage is inverted: there a relation write destroys an edge, here a non-relation write creates one. The consequence is this estate's rather than Linear's, because the drain's own premise re-tests and the coordinate sweeps read `relatedTo` and `blockedBy` as **deliberate** — an edge nobody authored is indistinguishable from one somebody did, and a later pass acts on it as intent. **So after any `save_issue` carrying a description or a `patch` on a ticket whose body mentions other tickets, re-fetch with `get_issue(includeRelations: true)` and compare the relation set against what it was before the write; report an edge you did not ask for rather than leaving it asserted.** Where the before-state was never snapshotted the comparison cannot be made, and the relation set is then read as unattributable rather than as authored. The cosmetic half of the same mechanism, recorded as an observation and not as a rule: a `patch` on APP-1713 **re-rendered pre-existing bold around issue mentions** with no wording changed, which is harmless on the page and is the visible tell that a body write re-parses mentions it never touched. (Session-observed 2026-10-22 by the refine pass's own blocked-clearance pass; **no note, closes nothing**.)
* **Read the write-back.** The response returns the auto-linked titles; after any write containing issue references, confirm they match what was intended. Nothing else will tell you.
* **Cite an issue by its bare identifier and let Linear resolve it — never hand-author the** `<issue id=…>` **tag.** The forward-reference trap above is about an ID that does not exist yet. There is a sibling failure where **every ID exists**: composing several inline references in one paragraph by hand-typing the full tag, and copying a real UUID onto the wrong ticket's label. Linear binds the reference on the `id` attribute alone — the visible label and the `href` are ignored — so the tag reads correctly, renders correctly, resolves to a real ticket, and points at the wrong one. A `get_document` read-back confirms the binding without revealing the mismatch, because the mismatch is between the `id` and the label you typed beside it, not between the write and the store. It is invisible without re-fetching each referenced issue and diff-checking its real UUID against what you typed. So write the bare identifier as plain text — `A1-410`, `APP-1302` — and let Linear's own auto-link build the `id`/`href` pair on save; a resolver that never sees a hand-typed UUID structurally cannot transpose one. Reserve the explicit tag for the case that genuinely needs it, and then write one reference per write rather than several in one paragraph. The rule compounds with *Read the write-back*: bare identifiers make the write-back's auto-linked titles a **real** check, because the title Linear returns was derived from the identifier you meant rather than echoing a label you typed by hand. (Worked case: the `a1.standup` entry of 2026-09-11 hand-authored four tags in one patch referencing four already-existing tickets; two carried a neighbouring ticket's real UUID — the tag labelled `A1-409` held A1-362's UUID, the tag labelled `A1-410` held A1-409's — both well-formed, both resolving, caught only because the run happened to hold each real UUID from earlier `get_issue` calls and cross-checked out of care. Corrected by a further `replace` patch and verified by re-reading. APP-1326; distinct in mechanism from APP-637.)
* **Cite a pull request as a full markdown link, never as `PR #N` or a bare `#N` — the number alone resolves against the wrong repo and says nothing.** `#N` is repo-ambiguous by construction: several repos in scope share PR numbers, and Linear binds a bare number to one of them without asking. The result has this section's whole signature — it renders as an ordinary PR chip carrying that PR's **real title**, so nothing in the write-back looks wrong until you read the title and find it belongs to another repo's work. Write `[owner/repo#N](https://github.com/owner/repo/pull/N)`, which is unambiguous and resolves correctly, and then **read the returned title back** and confirm it is the PR you meant — the same check the bullets above require for issue references, for the same reason. Repairing a wrong binding is the same edit: replace the bare reference with the explicit link. (Worked case: a `save_issue` patch on A1-499, 2026-09-23, wrote "PR #170" into two checkbox notes and Linear bound both to `assoc-one/claude-ops#170`, an unrelated ops-sync PR, instead of `assoc-one/meirionpritchard-com#170`. Caught only by reading the write-back and noticing the chip's title named an APP-774 canon publish. Same family as the forward reference and the hand-typed tag above, for PR references instead of issue references — APP-1698.)

The blast radius is worst on canon intake, where the pattern is most natural: a wrong reference on a `FRICTION:` note or a parent epic sends the Pulse drain to the wrong work, and the drain cannot know — it reads a plausible table of plausible tickets. (APP-637.)

* **`save_issue`'s `patch` can silently over-delete or no-op — read the description back after every patched write.** The `patch` param (partial anchored edits applied in place of a full description) sits in the same silent-write family. In one session a `replace` op over-deleted — it removed a whole section rather than the anchored span it named — and a follow-up `insert_before` / `insert_after` returned HTTP success while changing nothing; neither errored. Scope the blame before condemning the mechanism: the *same session* applied `patch` cleanly to a Linear **document**, so the defect is **`save_issue`-specific**, not `patch` itself. So when patching an issue, prefer small, tightly anchored ops over a broad `replace`; where a whole section is at stake apply one op and confirm it before the next rather than batching; and after any patched `save_issue`, re-fetch the issue and check the intended change landed and nothing adjacent was lost — the returned object is not proof. (APP-860.) **Two further failure modes corrupt a structure that survives, and the read-back above is the only thing that catches them.** Seen on 2026-09-10 on `A1-412`, across two consecutive patched writes. An `insert_after` carrying a markdown table returned HTTP success with **leading characters eaten from most cells** — `desktop` stored as `ktop`, `960 x 171` as `x 171`, one column emptied outright — leaving a plausible table asserting wrong measurements rather than an obviously broken one. The repair then made it worse: a `replace_range` substituting a fenced block for the damaged table produced an unclosed fence that swallowed the remainder of the body, and separately **degraded two `<issue>` reference tags to single characters** (`A1-413` to `a`, `A1-393` to `b`). Neither write errored. This is harder to detect than the over-delete above, which at least removes a visible chunk: here the structure stands and the *values inside it* change, and `convention-ticket`'s evidence-pinning rule assumes the pinned figures survive the write — a silently altered measurement is an acceptance criterion a builder can satisfy while building the wrong thing. **So where a patched write comes back wrong, do not patch the repair — write the full `description`.** The same content that `patch` corrupted twice reproduced exactly on one full-`description` write: numbers intact, both references resolved back to proper links, one fence. And where a ticket body carries load-bearing numbers, **prefer a fenced code block to a markdown table** — the code block survived where the table did not. **But give that fence a single-word label, because Linear truncates a multi-word fence label to its first word.** A block opened as a fence labelled `NEW TEXT` is stored and read back labelled `NEW` — silently, with the fence's *contents* intact. Observed on `save_document` across several Pulse manifest child documents on 2026-10-05. It is the same renderer-normalisation family as the emphasis-and-autolink trap below, and it lands on the one construct that is being recommended here as the safe harbour, so the harbour needs the qualification: **the fence protects what is inside it, not the label on it**, and any convention that keys a reader on a multi-word label is broken by storage rather than by the writer. The workaround that held is a single-token label (`NEWTEXT`) plus a bold caption line immediately above the fence, which survives both a label-matching and a caption-matching reader. Three further normalisations were observed in the same writes, all of them **outside** a fence and none of them inside one: a bare `A1-###` is expanded into an issue mention exactly as a bare `APP-####` is, so the two behave alike and neither survives as plain text; the spaces around a backtick nested inside another code span are eaten; and bold markers migrate across adjacent inline code. The working rule is the one the fence already implies — **put anything that must match byte for byte inside a fence, and treat everything outside one as paraphrase.** (Session-observed 2026-10-05; **no note, closes nothing**. The pull-request case is already canon above and is not restated: the same run auto-linked the prose string `PR #368` into a pull-request mention pointing at an **unrelated** review, which is exactly what the cite-a-pull-request-as-a-full-markdown-link bullet forbids — fresh corroboration for it, not a new rule.) The issue-vs-document scoping above is unchanged and untested against this class: whether the same corruption reaches `save_document` was not checked, so treat documents as unverified rather than safe. (APP-1305.)
* **The truncation on a fence's opening line eats what sits beside the label, so a comment carrying anything structural is read back and compared against what was sent.** The rule above says a multi-word fence label is stored as its first word with the block's contents intact; what it does not say is where the rest of that opening line goes. It is consumed with the label rather than rendered unstyled, so a probe line, a caption or an annotation written alongside a multi-word label is lost outright and leaves nothing on the page to notice its absence. Measured by this refine run on a `[pulse-refine]` comment on `APP-1009`: a probe line written on the fence's opening line was absent from the stored comment, caught on read-back and repaired on the next write. The write response carried the text as sent, so the loss was invisible there — which makes the read-back, not the renderer, the operative half of this rule. So where a comment carries anything structural — a fenced block, a probe line, a caption a later reader keys on — re-read it with `list_comments` and compare it against what was sent; and keep a fence's opening line to a single-token label, with everything else on a line of its own. Measured on one comment write on one issue: whether a `save_issue` description or a `save_document` body loses the same text was not tested, so treat them as subject to it rather than exempt. (Session-observed by the 2026-10-30 refine run; **no note, closes nothing**.)
* **A literal markdown-special character inside emphasis-wrapped prose silently mangles the paragraph — wrap it in a code span, never a backslash.** The corruption classes above are the connector eating or over-deleting content. This one is markdown doing exactly what markdown does, on content the writer believed was plain text, and it reports success like the rest. On APP-1904 (`skill-build-ticket`, 2026-10-03) an italicised intro to the `apps.mandate` document named the `cOS.*` project family inline as prose: `*… the cOS.* system, …*`. The bare `*` inside `cOS.*` **closed the outer emphasis early**, and the damage cascaded across the remainder of the paragraph — a later bare domain-looking token, `app.fitness` (a Linear project name, not a domain), was silently **auto-linked** to `http://app.fitness`, and the closing parenthetical rendered with a literal escaped `\*` instead of closing the italics. Nothing errored, and the truncated `save_document` response preview looked right. It was caught only by reading the document back in full with `get_document` and diffing against the intended text. **So: when a literal `*`, `_`, or a bare dotted token that could be read as a domain has to appear inside emphasis-wrapped prose, put it in a code span (backticks) — `` `cOS.*` ``, `` `app.fitness` `` — which keeps it out of markdown's emphasis and autolink parsing entirely.** Do **not** backslash-escape it: the escape is stored literally and reads back as a visible backslash (the observed run's read-back showed `\____\_` for an escaped placeholder — functional and wrong on the page). The read-back rule that caught it is the one already stated above and it is the only thing that catches this: the write's own truncated response is not evidence. (APP-2009. Observed on `save_document`; the same emphasis parsing applies to `save_issue` descriptions and comment bodies, which were not separately tested — treat them as subject to it rather than exempt.)

* **A table cell that begins with `>` loses the character on save — give the comparison in words or wrap the cell in a code span.** The trap above is markdown parsing content the writer believed was plain text; this is the same family inside a table, where the loss inverts a meaning instead of mangling a paragraph. A leading `>` is read as a blockquote marker, stripped, and the remainder of the cell stored as prose, so a KPI target written `> 0 at window end` is stored and read back as `0 at window end` — a floor silently rewritten as an exact value, with nothing left on the page to notice its absence. The write response carries the text as sent, so the read-back is again the only half that catches it. So in any table cell give a comparison as words (*positive*, *at least four*) or inside a code span, and treat a leading `-`, `*` or `#` the same way. (Worked case, **observed** by the first unattended `task-bottrader-weekly-report` run, 2026-11-13: two KPI target cells written `> 0 at window end` and `> 0%` were stored as `0 at window end` and `0%`, a target inverted in meaning, caught on the 15:14 GMT read-back and reworded to "positive" at 15:16 — `APP-3105`.)
* **An escape code typed into a plain string param is stored as the escape code — type the real character in `title` and `description`, and read the first line of every written title back.** The classes above are the connector mangling content it was handed correctly. This one is content arriving wrong and being stored faithfully: `\u2014`, `\n` and their family, written into a `save_issue` or `save_document` plain string param, survive into the stored text as the backslash sequence rather than the character. The Linear MCP server's own instructions already say to send content directly, with real newlines rather than literal backslash-n — so the trap is stated, but it is stated where a writing pass does not re-read it, and it carries two consequences the instruction does not name. (a) **The damage outlives the repair.** Titles written this way on 2026-10-13 were corrected in a second write and now read clean — but a link auto-generated into another issue's body before the repair still carries the frozen bad slug, because an auto-generated link copies the slug into *other* issues' stored text and fixing the title never reaches it. Every reference written before the repair stays wrong, and only a grep across the citing bodies finds them. (b) **A literal newline escape collapses a whole description to one line** — seen on `APP-2301`, whose stored body opens with a `## What happened` heading followed by two escaped breaks and so never renders a heading at all. The write response echoes the stored text, so the read-back rule above catches both on the *first* write provided it is actually run on the title and on the description's first break; nothing else will. (APP-2315. Whether the double-escape originates in the authoring pass's own serialisation or in the connector's handling is not determinable from the observed runs — the rule is the same either way. A reported asymmetry, that identical escapes decode correctly inside a `patch` array, could not be re-verified from the repaired board state, so do not rely on it: type real characters in every param.)
* **Omitting `health` on `save_status_update` returns `"health":"onTrack"` silently — always pass the value explicitly.** A `save_status_update` call that leaves `health` unset does not default to null and does not error; it writes `onTrack` and returns HTTP success with no warning, so a run reporting a genuinely at-risk or off-track project would post a healthy signal it never chose. Same silent-failure family as the state and `targetDate` no-ops above — HTTP success, no warning, a value invented — but worse, because the invented value is a health assertion the board and the daily read then trust. Pass `health` on every status-update write, chosen deliberately, never left to the default. (The worst-of roll-up rule for a project carrying several mandates lives in `convention-project-status`.) (APP-886.)
* **A valid `save_issue` field write can return 200 and apply nothing, with `updatedAt` unmoved — read the write-back on every field, and retry once on a no-op.** Every silent-drop rule above turns on an input the connector could not match: a state the team does not have, an empty `targetDate`, a mis-spelled label, an omitted `health`. This one has no bad input. `save_issue(id: "A1-122", estimate: 16)` returned HTTP 200 carrying the full issue body with **no** `estimate` field and `updatedAt` unmoved at `2026-08-10T11:50:38.512Z`; an identical call seconds later returned `estimate: 16`. The same shape hit `APP-648` in the same batch — 2 of 25 writes, alongside two loud `502 upstream_unavailable` failures that also succeeded on retry, so the connector was under strain and the concerning half is the pair that reported success. So the read-the-write-back rule binds on **any** field a `save_issue` sets, not only labels and the description: confirm the field came back carrying the value written, and where it did not, **retry the identical call once** before treating the write as landed. A count of attempted writes is not a count of applied ones, and a pass that reports the second as the first makes its own backlog look like it is falling faster than it is. (APP-1448; the transport-error rule below governs the mirror case, where the write landed and the call errored.)
* **A state write to a parent can carry its sub-issues with it — read the children back after closing a parent, and restore any the write moved.** The rule above reads the written field back on the ticket that was written. This one reads a ticket **nobody wrote**: where a parent-closes-children automation is on for the team, one `save_issue` moving a parent to a terminal state returns a clean response for that ticket while stamping every open sub-issue with the same state and the same `completedAt`. The response names only the parent, so a read is the only signal. So after any write that moves a parent into a completed or canceled state, **re-read its sub-issues' states** and return any the write carried to the state it held — and expect it hardest on an editorial cascade, Mr Pritchard's piece-as-parent with derivatives-as-sub-issues wiring (*The workspace: teams and where work goes*), because that cascade closes the parent **first** by design and dates its derivatives after publication, so every derivative is open at the moment the parent closes. Whether the automation is on is a team setting this connector does not expose — `get_team` on Mr Pritchard returns identity and visibility fields only — so the setting is an **unverified premise** named here rather than asserted, and the re-read is the remedy that does not depend on it. (Worked case: **observed** 2026-11-17 — `MRP-110` was set Published on 2026-11-16 and `MRP-7` (Substack notes, due 17 Nov) and `MRP-8` (LinkedIn post, due 18 Nov) were both stamped Published at `completedAt` 2026-11-16T15:41:56Z with neither posted, matching `MRP-110`'s own `completedAt` to the second; both were reverted and read back from the live board this run as Todo with `completedAt` null. The automation's existence is **reported** by the filing note; the `get_team` read above returned no field that would confirm or deny it. `APP-3138`.)
* **An `agent`-group handoff is a full `labels` replace, never `addLabels` — and a full replace must restate every label.** `addLabels` 400s against the single-select group and takes the bundled state and assignee writes down with it; `labels` evicts correctly but drops silently any label the list omits. Re-read, swap the one value, restate the rest, read the write-back (*Labels*, Single-select — APP-1102, APP-1116).

* **A `human`-gated ticket hands off by state and assignee, never by a review label — `human` and `agent:PR-1SM` are mutually exclusive by construction.** The bullet above gives the mechanism and *Agent routing* gives the resting shape; what falls between them is the join, and it is where a slice template goes wrong. `agent` is single-select and `human` is a value *inside* that group, so an on-completion line telling a human-gated ticket to "move to In Review, set `agent:PR-1SM`, leave it unassigned" is self-contradictory before any call is made: the only way to apply the review label is to drop the very label that keeps the ticket Owner-gated. **The collision is semantic, not an API refusal**, which is the part worth holding — the 400 that comes back reads like a transport or permission problem, and a leg that retries its way past it drops the gate and leaves the ticket looking routed. So the hand-off for a `human`-gated ticket is **In Review, `human` kept, Aled assigned, and the gate named in a comment**: no review label, and no substitute label standing in for one. The assignee carries what the label would have said, which is the reader rule *Reading Linear safely* already states for a review label — and the Owner's own approval is what later evicts `human`, by setting the next `agent` value. (Worked case: a DS CHECK ticket carrying `human`, 2026-10-13 — its on-completion line read "move the ticket to In Review, set `agent:PR-1SM`, leave it unassigned"; `addLabels` was refused because `human` sits in the same group, the only route to the review label was to drop the gate, and the leg correctly rested the ticket In Review with `human` kept and no review label. A sibling slice ticket carries the same template line, so this is a template shape and not one ticket's mistake. One run, two tickets, reported — APP-2381.)

* **`save_issue`'s accepted top-level keys are `state`, `assignee` and `labels` — the Linear-API-looking names `status`, `stateId`, `assigneeId` and `labelIds` are rejected outright.** Each wrong guess returns a clean `Unrecognized key` validation error *before* any write, so nothing is corrupted and nothing is half-applied — but on a scheduled or unattended run the rejection reads like a permission or state-machine refusal rather than a param-name miss, and each guess costs a full round trip. The working shapes: `state` takes the state **name** (`"In Progress"`), never an id; `assignee` takes a user id (or name, email, or `"me"`); `labels` takes label ids and is a **full replace**, per the bullet above. Three consecutive rejections on one claim step is the observed cost, not a hypothetical (A1-643 dispatch, 2026-10-09 — APP-2201).
* **Closing an issue as Duplicate is one write, not two — set `duplicateOf` alone and let the state follow.** `save_issue(state: "Duplicate", duplicateOf: …)` in a single call returns `400 invalid_request` — *"Issues can only be moved to a duplicate state when a duplicate issue relation exists."* The message reads as an ordering requirement with a second write at the end of it, and that inference is wrong: setting `duplicateOf` on its own **also moves the issue to Duplicate**, so the follow-up state write the error implies is not needed and a run that issues it is writing a state the connector has already set. Pass `duplicateOf` and read the response back — it returns `status: "Duplicate"`, `statusType: "duplicate"` and a stamped `canceledAt`. **Now read that convenience the other way round, because it is the same mechanism and it is a trap: `duplicateOf` *enacts* the close, so it is never a way to *suggest* one.** The rule above is written from the case where the implicit state move is what you wanted. Where it is not, the move happens anyway: a `duplicateOf` passed in the same `save_issue` call as an explicit `state` **silently overrides that state**, and the write-back returns `Duplicate` with `canceledAt` stamped rather than the state that was asked for, with no error raised to say the call did two things. That is live on exactly the routings that most tempt a run to name a candidate duplicate — `skill-build-ticket` step 3a's already-satisfied path (In Review, executor `human`, assigned to Aled, evidence commented) and any recommend-but-do-not-decide hand-off, where the close is explicitly reserved for sign-off. Naming the candidate in the field looks like attaching supporting evidence and is in fact performing the close. **So a duplicate a run recommends but is not authorised to enact goes in comment prose only, naming the candidate by identifier, and the `duplicateOf` field is written only when closing is the intended outcome of that call** (APP-226 governs the leg that *is* authorised to close). Nothing but this bullet's own read-the-write-back discipline reports it. (Worked case: APP-1270, routed already-satisfied against APP-1322 on 2026-10-03 — one `save_issue` carrying `state: "In Review"` and `duplicateOf: "APP-1322"` returned `status: "Duplicate"`, `statusType: "duplicate"` and a populated `canceledAt`; caught on the write-back read and corrected by a second write clearing `duplicateOf` and re-asserting the state — APP-2008.) This is the same family as the `addLabels` bullet above and a different mechanism: that one is a parameter conflict, this one is an ordering precondition whose second step turns out to be implicit. (Worked cases: APP-1391, APP-1398 and APP-1404 on the 2026-09-14 refine run, and APP-1442, APP-1428 and APP-1431 on 2026-09-15, each closed from a single `duplicateOf` write — APP-1418.)
* **A project milestone can be created and edited and cannot be deleted — so a milestone set is sized once.** The connector's whole milestone surface is `list_milestones`, `get_milestone` and `save_milestone`; `save_milestone` carries `project`, `id`, `name`, `description` and `targetDate` and **no delete, archive or trash lever**, and there is no `delete_milestone` tool at all — measured against the full deferred tool set on the refine surface, alongside the four `delete_*` tools that **do** exist (`delete_attachment`, `delete_comment`, `delete_diff_comment`, `delete_status_update`), which is what makes this a capability gap rather than an unsearched roster. So a superseded milestone has exactly **two** dispositions: **repurpose it in place** — rename, re-describe and re-date the existing row — or **name it for the Owner to delete** in the run's report, a workspace action no run can reach. Neither is a write that disappears it, so a build that sizes a milestone set **sizes it once** and does not stage a provisional set it intends to prune: an over-sized set is permanent furniture on the project, and the pruning write the plan assumes does not exist. (Worked case: the 2026-11-06 `aledpritchard.com` Launch build setup, **reported** — no board or repo state is readable from the refine surface; the tool-surface absence above is **observed** here. `APP-2920`.)
* **A transport-level error on a Linear mutation is not proof the write failed — read it back before retrying.** Every rule above guards the one direction: a write that reports success and did not land. This is the mirror of it, and the natural response to it is the response that duplicates. A `502 upstream_unavailable` can be returned **after** the mutation has already committed, so on any transport error re-read the thing written — the comment list, the field, the document's **content**, the state — before issuing a second call. **On a document, diff the content, never the timestamp.**

* **Clear a nullable param in a write of its own — bundled with another field it either takes the whole call down or silently no-ops.** `save_issue`'s nullable params do not reliably clear when they are passed alongside another field, and they fail in two opposite directions. **Loud:** on A1-346, 2026-09-21 07:10Z, `save_issue(id: "A1-346", state: "Todo", assignee: null)` returned `Could not find user "null" for assignee` and **the whole call failed — the bundled `state` write was lost with it**; a follow-up passing only `state` succeeded. The same coercion hit `cycle` on **4 of 24** Pulse-close writes on 2026-09-22 (`Could not find cycle "null"`), so it is intermittent rather than deterministic, and it selects per *param* rather than per field type. **Silent:** on APP-1634, 2026-09-23, `save_issue(id: "APP-1634", state: "Done", cycle: "null")` returned **success with the cycle still set** — no error at all — and the follow-up `save_issue(id: "APP-1634", cycle: "null")` carrying nothing else cleared it, read back clear; `save_issue(id: "APP-1572", assignee: "null")` on its own likewise cleared the assignee, read back clear. **So the rule is the isolated write:** set the other fields in one call, and clear the nullable param in a second call that names nothing else. Bundled, the clear either errors and takes its sibling write down with it, or reports success and does nothing — two different failures, and both are worse than the isolated form — but **isolation protects against those two failure modes and does not make the write land.** **Corrected 2026-10-23: the claim this bullet carried until today, that the isolated form has not failed, is false.** On APP-2546, 2026-10-22, three *isolated* `save_issue(assignee: "")` calls each returned 200 and each silently did nothing, `updatedAt` frozen across all three and `get_issue` still showing the assignee set; only `assignee: null` cleared it. So **an isolated nullable write is still read back** — isolation buys the sibling field's survival and a visible error, never a landed clear — and `""` is a silent no-op in **both** forms, bundled and isolated alike. Isolation and sentinel are two separate questions: the isolation rule above settles how to shape the call, and the sentinel decides whether anything happens at all. The three sentinels a writer plausibly reaches for behave three different ways, tabulated at the end of this bullet. (The three isolated-call observations are **reported** from APP-2594's comment thread, 2026-10-22, and were not re-observed on the refine surface; the bundled-form halves above stand on their own earlier measurements.) `assignee` (APP-1471) and `cycle` (APP-1647) are one class here; `delegate` and `parentId` carry the same nullable shape and are **untested**, so treat them the same way until someone measures them. **Stated honestly about its own evidence:** this surface cannot distinguish a genuine JSON `null` from the string `"null"` in its own tool-call serialisation, so the rule is written against the *observable* behaviour — isolated clears, bundled does not — rather than against which form reached the wire; establishing the coercion itself needs a surface that can tell the two apart. **And prove the clear by the read-back, never by the timestamp:** the APP-1634 clear landed while `updatedAt` stayed unadvanced at `2026-09-23T04:01:28.275Z` — another instance of the successful-write-with-`updatedAt`-unmoved phenomenon (APP-1417), which is why the read-back and not the timestamp is the proof. (APP-1471 for `assignee`, APP-1647 for `cycle`; measured 2026-09-21 and 2026-09-23.) **For `cycle` the read-back proves the state and not the act — and the state is what canon asks for.** `get_issue` and `save_issue` **omit** `cycle` / `cycleId` entirely when no cycle is set rather than rendering an explicit null, so an absent key after the clear is indistinguishable from an absent key before it. That is a gap in *attribution*, not in *proof*: the rule a PUL-5E close has to satisfy is that the note carries no cycle, and an absent key establishes exactly that. So read the field back as the bullet requires, record "no `cycle` key present" as the positive result, and do not fall back to treating "the call returned no error" as the evidence — a successful-looking call with the value still set is the failure the bullet exists to catch, and only the read distinguishes them. Where attribution matters, snapshot the field before the write as well; where it does not, do not spend the call. Note the contrast with `assignee`, which does return a distinguishable empty state (APP-1471), so the two nullable params do not read back alike. (Worked case: 7 of 16 fanned author subagents on the 2026-09-29 pass each independently reported they could not confirm clearance from the read-back, while 3 others — whose notes did carry a cycle — confirmed it cleanly; and 11 of 11 Backlog PUL-5E notes read on 2026-09-30 returned no `cycle` key — APP-1851.) A successful `save_document` can return with `updatedAt` unadvanced: two successive patches to one manifest child on 2026-09-14 both landed, both visibly changed the stored text, and neither moved the field from `2026-09-14T04:01:40.524Z`, while a patch to a different child forty minutes earlier advanced it exactly as expected. The field is reliable in one direction only — an advanced `updatedAt` proves a write landed, an unadvanced one proves nothing — so it closes a transport-error check positively and never negatively, and a run that reads it as a negative re-issues the write this bullet exists to prevent. The likely mechanism is Linear coalescing rapid successive edits into one revision; that is unconfirmed and the rule does not depend on it. This is the document-side limit on the `updatedAt`-unmoved evidence the `state` and `targetDate` bullets above rely on, which stands for issue and project writes. (APP-1417; the transport-error worked cases are APP-1399's.) On an advisory marker a duplicate is harmless; on a verdict, a routing write, a state change or a full-replace document write it duplicates something downstream legs act on. (Worked cases: a `[qa] REVIEWING HEAD:` marker posted at 13:05:47Z returned 502, the retry succeeded at 13:06:21Z, and a later `list_comments` showed **both** had landed — APP-1399. And on 2026-09-14 at 03:55:31Z a `save_document` patch to `osclaude.pulse-manifest.skill-telemetry-capture` returned `502 upstream_unavailable`; the run read the document's `updatedAt` back before retrying and found the write had already landed, so a blind retry would have appended the same paragraph twice. Two instances on two different tool surfaces — a comment write and a document patch — is what makes this a rule rather than one bad minute.)

* **Setting `duplicateOf` is the whole close — never bundle it with a `state` write.** A `save_issue` carrying both `state: "Duplicate"` and `duplicateOf` is **rejected** with `Issues can only be moved to a duplicate state when a duplicate issue relation exists`, because the state validates against a relation the same call has not yet created. The `duplicateOf` write **alone** both creates the relation and moves the issue to Duplicate, so the bundled form is not merely redundant, it is the one form that cannot work. This is the companion to the isolated-clear rule above and it fails in the opposite direction: there a bundled clear returns success and silently no-ops, here a bundled state returns a 400 that takes the whole close down with it, so a pass that treats the error as transient and retries the same shape never closes the note at all. **And the same completion automation reaches an issue whose cycle was already empty** — a `state: "Done"` write auto-assigned a cycle to an issue reading `cycleId: null` beforehand, so the isolated `cycle: null` follow-up is run after every close rather than only where a cycle was visible going in. (Worked case, **observed** on this run's own enactment leg, 2026-11-16: three Duplicate closes were each rejected in the bundled form and each landed from the `duplicateOf` write alone, read back as Duplicate with the relation present; and `APP-3109` entered its close with `cycleId: null`, was auto-assigned a cycle by the `Done` write, and read back clear only after the isolated follow-up. Session-observed; no queue note folds this finding.)

  **The three clear-sentinels for `save_issue.assignee`, and what each one actually does.** `null` measured 2026-09-21 and 2026-09-23; `""` and `"none"` **reported** 2026-10-22 from APP-2594 and its comment thread, three instances — APP-2540, APP-2546, APP-2543 — and not re-observed on the refine surface.

  | Sentinel passed | What happens | How it shows |
  | -- | -- | -- |
  | `null` (JSON) | **Clears intermittently.** | The clear lands and reads back clear (`APP-1471`) on some calls and is rejected as `Could not find user "null" for assignee` on others, so the unqualified *Clears* this row carried until today is falsified: `APP-1471` → `APP-2594` → `APP-2835` → `APP-2854` are all closed and the recurrence continues, with `APP-2882` the fifth-plus instance of the rejection, and the guidance below to reach for `null` and nothing else holds only with a retry attached. **The first thing to try on `Could not find user "null"` or `Could not find cycle "null"` is a schema reload, then the identical call again — observed:** on one session a `save_issue(id, cycle: null)` returned `Could not find cycle "null"` — the string `"null"` reached the wire where JSON `null` was intended — and the identical call succeeded after the tool's schema was reloaded with `ToolSearch` (`select:mcp__Linear__save_issue`); both forms were issued minutes apart from that one session and only the schema reload sat between them, which is why reload-then-retry recovers it. A second lever is **reported** from that note's own thread and was not observed here: split the state/label write from the clear, so a rejected clear cannot take a sibling write down with it. As this bullet already states, this surface cannot distinguish a genuine JSON `null` from the string `"null"` in its own tool-call serialisation, so this row is written against the **observable** behaviour — clears on some calls, rejected on others, recoverable by reload-then-retry — and not against which form reached the wire. |
  | `""` (empty string) | **Surface- and call-dependent, not a constant.** | A silent no-op on every call measured to 2026-10-22 — HTTP 200, no error, every other field in the same call lands correctly, the assignee stays set and `updatedAt` stays frozen, bundled and isolated alike (`APP-2540`, `APP-2546`) — and, on one isolated call, a clear that landed and read back clear, with the typed `null` rejected on that same ticket minutes earlier (`APP-2917`, filed on `APP-2963`). Both outcomes have recurred: `""` no-opped twice on one ticket, with and without a trailing newline, while `null` was rejected on every attempt (`APP-2974`), and it no-opped again before the identical typed clear succeeded later in the same session (`APP-2982`). So this row is a set of dated observations and not a property of the field, and only a `get_issue` read-back tells you which outcome you got. (The post-2026-10-22 instances are **reported** from `APP-2963`'s comment thread and were not re-observed on the refine surface.) |
  | `"none"`, or any other non-sentinel word | **Loud error, whole call rejected.** | `Could not find user "none" for assignee`; nothing in that call lands, so a bundled `state` or `labels` write is lost with it (APP-2543). |

  The middle row is the dangerous one, and it is dangerous precisely because it is the only one that looks like it worked: a loud rejection is recoverable in flight in one corrected call, while a 200 with every sibling field correct is indistinguishable from success without the read-back. The empty string is also the most plausible thing to reach for, because the declared type `["string","null"]` accepts it without complaint. So **reach for `null` and nothing else** as the opening move — the phrase the `null` row above quotes, now a statement of order and not a guarantee — and prove it by the read-back this bullet already requires. **The rows above are dated observations and not a settled contract, and the standing instruction is the read-back and not the sentinel:** across five instances on the same two candidate values (`APP-2594`, `APP-2917`, `APP-2974`, `APP-2982`, `APP-2680`, all filed on `APP-2963`) each sentinel has now been seen to clear, to no-op and to be rejected, so there is no form that removes and a run that trusts one without reading back has proved nothing. Where the read-back shows the typed `null` did not land, take the single recovery this section already prescribes — a schema reload, then the identical call again — and only then the one other candidate with a landed clear on record, `""`, again proved by a `get_issue` read-back. `""` is the one value the row above no longer settles, which is what separates trying it once from re-deriving a measurement canon already holds: this adds one bounded step to the hand-off clear's give-up below and removes none of it, and **it is not a licence to walk the sentinel space** — where the second candidate also reads back unlanded, stop at that bounded give-up, leave the assignee and name it, rather than reaching for a third value. (The five instances are **reported** from `APP-2963`'s comment thread and were not re-observed on the refine surface; and as this bullet already states, which of a JSON `null` or the string `"null"` reaches the wire is undistinguishable from this surface, so this guidance is written against observable behaviour alone.)

  **And the claim step does not pass `assignee` at all — omit the parameter at claim, and pass a correctly-typed `null` at hand-off.** The table above settles which sentinel clears; this settles where each belongs, because the cost actually being paid is not a wrong clear but a rediscovery. Two halves of the contract are undocumented in the tool's own schema, and a step that knows neither burns a call on each: the parameter is **`assignee`**, never the Linear-API-looking `assigneeId` the bullet above records as rejected outright, and its clear value is **JSON `null`** — the *string* `"null"` is rejected exactly as the word `"none"` is, so quoting the sentinel fails no more gracefully than inventing one. Each exec claim step that rediscovers this spends two failed calls before the third lands, every time, and the resolution is to stop clearing at claim altogether: **omit `assignee` from the claim write** — a field not passed is a field not touched, and a claim has no business clearing an assignee it is about to set — and pass a correctly-typed `assignee: null`, in a write of its own per this bullet's isolation rule, at **hand-off**, which is the one moment the clear is wanted. **And the hand-off clear has a bounded give-up: one reload-then-retry, then leave the assignee and name it.** Where the typed `assignee: null` is rejected at hand-off, take the single recovery this section already prescribes — a schema reload, then the identical call again — and where that second call also fails, **stop there**: leave the auto-assigned assignee in place and name it in the hand-off comment as **PR-attach residue rather than a live decision signal**, which does not block the hand-off. **Do not walk the sentinel space.** `""`, `" "`, `"none"`, `"None"`, `"unassigned"` and omitting the parameter are each already settled in the table above as a silent no-op or a loud rejection, so trying them is re-deriving a measurement canon already holds. Three legs reached this same disposition independently with no canon to cite, which is what earns writing it rather than a sixth re-derivation; the remedy at source is unchanged and still the Owner's — turning **off** auto-assign-on-PR-attach in Linear's GitHub integration settings, a workspace-config action and not a canon edit. (The three legs' calls and rejections are **reported** from their filing notes and were not re-observed on the refine surface. `APP-2943`.) Third instance of the exact pattern, which is what earns it a stated contract here rather than a caution. (Worked case: an exec claim step spending two rejected `save_issue` calls — one on the parameter name, one on a quoted sentinel — before the typed form landed, with `APP-2817` the predecessor instance of the same two-call cost. Both instances are **reported** from their filing notes and were not re-observed on the refine surface, the same standing as the `""` and `"none"` rows above. `APP-2835`.)

## Documents and the decision log

**Filing a document:** use the document tool, set `title` and the parent `project`. One doc per artefact. Type-prefix the title: `skill.`, `routine.`, `task.`, `adr.`. Omit `icon` on `save_document` unless a known-good name is to hand — `icon: "Document"` returns `400 icon is not a valid icon`, the tool exposes no enumeration, and the retry without the field succeeds (MRP-47, 2026-08-18 — APP-1015).

**Document titles are stem-first.** A document a vertical, venture or team owns opens its title with that owner's **registered stem**, then what the document is: `osclaude.log-decisions`, `bara.owner-session-agenda`, `mbn.cycle-goal.2026-W38`. The stem is a lookup, not a derivation — it is registered once in `convention-naming`, which rules every name above the canon-artefact line, and never re-derived per document. Putting it first is what makes the project-scoped, prefix-matched listing described in *Find a document by exact title* below work at all: a title that buries its owner mid-string cannot be found by the lookup canon prescribes. The type-prefixed forms named just above (`skill.`, `routine.`, `task.`, `adr.`) are the **canon-register family inside os.Claude** and keep their shape; everything a vertical owns is stem-first. Where a form elsewhere in this section is written as `<project>.` — the ADR form, the per-round design-review form — read `<project>` as the owner's registered stem, which is usually the project name and is not always (APP-1381).

**Find a document by exact title with a project-scoped listing paged to the end — never from the first page of a** `query` **search.** `list_documents(query: …)` does not rank an exact title match first. A dotted index shares its title as a prefix with every one of its children, and the query returns the children: `list_documents(query: "osclaude.pulse-manifest", limit: 50)` returned a full page of `osclaude.pulse-manifest.<target>` children and never the index itself. The index surfaced only on a project-scoped listing paged through by `cursor`, sorted among its children rather than above them. The safe lookup is `list_documents(projectId: <owning project>, query: <title>, fields: ["id","title","updatedAt"])`**, following** `cursor` **until** `hasNextPage` **is false, then filtering client-side on exact title equality.** A first-page miss never proves absence — the document-side twin of the empty-page rule in *Reading Linear safely* (APP-979). It matters most before a **create**: a lookup that concludes "none exists" from a partial result files a duplicate, such as a second cycle-goal document or a second manifest child. (Worked case: `task-owner-standup`, 2026-09-21, resolving `osclaude.pulse-manifest` for its Pulse pointer — APP-1576.)

**A standing document with no project parent is reached only by a workspace-wide listing, so the project-scoped lookup above is run with that second pass behind it.** The safe lookup resolves a document that has an owning project; a document parented to an initiative alone carries `project: null`, and no `projectId` value matches it, so every project-scoped attempt returns the same empty result however many projects are tried. The asymmetry earns the second pass because the two failures are not alike: a workspace-wide listing paged to the end costs one further query and a few pages, while a project-scoped miss returns an answer shaped exactly like absence and is then reported as absence, which is the one reading that stops the loop looking. So where the project-scoped listing resolves nothing, repeat it workspace-wide — no `projectId` filter, `query` set to the exact title, `cursor` followed until `hasNextPage` is false, filtered client-side on exact title equality — and only a miss surviving both passes is an absence. Standing documents are where this bites, the mandate, the owner-session agenda and the stand-up index being routinely filed on an initiative and never on a project, and `skill-operating-loop`'s absent-source branch already defines absence as resolving nothing on the initiative and nothing workspace-wide (`APP-3072`). (Worked case: `bara.standup.2026-W46` told the Owner on two consecutive entries, 2026-11-11 and 2026-11-12, that `bara.mandate` and `bara.owner-session-agenda` do not exist on this surface, the first naming two projects searched and the second all three — **reported** from the filing note. Both resolve by exact title workspace-wide and are parented to the BARA relaunch initiative with `project: null` — **observed** on this surface, 2026-11-16 — `MBN-350`.)

**An architecture decision record is a document titled `<project>.adr.<slug>`, never a comment.** A comment needs no name and cannot be cited from anywhere else, and a decision record is exactly the artefact a follow-on ticket, a later spike and the decision log all have to point at; the durable-artefact rule in this section already settles the general case — anything meant to be found again is attached as a native Link, and a comment scrolls out of sight down a thread. So file the record as a Linear document in the owning project, dotted and type-prefixed like every other document here: `osclaude.adr.managed-agents-surface`, with the dot carrying its usual meaning in this section — the artefact lives in Linear, not in the skills store — and the slug naming the question decided rather than the ticket that asked it. `convention-ticket`'s `spike` format owns what a spike must *deliver*; this rule owns what that deliverable is called and which store holds it. (Worked case: the 2026-09-07 `skill-architecture-spike` run on APP-1120, the Managed Agents surface assessment, had three title prefixes to choose from, none of which fits a decision record, and a step offering "a Linear document or a comment on the ticket" with no tiebreak. It named the record `osclaude.adr-managed-agents-surface`, derived from this section's dot rule and the `osclaude.` prefix its sibling documents carry — a defensible guess, not a documented form — and a workspace search for `spike decision record adr` returned nothing, because it was the first ADR ever filed as a document. `spike` is a live ticket type whose deliverable is a decision record and follow-on tickets, never a merged PR, so every later spike run would have derived its own answer; APP-534 is what that drift costs — a session searched the wrong store because the naming form was never stated. The one existing record is renamed to `osclaude.adr.managed-agents-surface`. APP-1156.)

**The dot is the tell: a dotted name is a Linear document, a hyphenated name is a skills-store artefact.** `playbook.website-build` lives in Linear; `playbook-client-onboard` lives in the skills store. The two naming forms have always meant different stores, and nothing said so — which is exactly how a session searches the wrong one, finds nothing, and concludes the artefact does not exist. Read a dotted reference as "look in Linear", a hyphenated one as "look in the store", and where a skill's prose points at a Linear-native artefact, name the store explicitly rather than leaving the reader to infer it from the punctuation. (Worked case: a session searched the skills store for `playbook-website-build`, found no match, and captured that it "doesn't exist" — while `playbook.website-build` sat live and actively maintained in a1.OS. `playbook-client-onboard`'s "sits on the a1.OS shelf beside playbook.website-build" was the line that misdirected it: it reads as a cross-reference to a sibling skill — 2026-07-15, APP-534.)

**Some canon is Linear-native and has no skills-store copy — a1.OS is the standing case.** The A1 practice's operating system lives as **Linear documents in the a1.OS project**: `playbook.website-build`, `standard.web-build`, `standard.proposal`, `standard.scope-of-work`. These are canon for A1 delivery work, actively maintained, and **not** in the skills store — so a session auditing web-build or client work against "all relevant conventions and playbooks" must read a1.OS's documents as well as the store, and `list_skills` returning nothing is not evidence of absence. Whether this canon eventually folds into the skills store is an open question for the Owner; until it does, both stores are live and the dot tells you which is which.

**The decision log** is realised in Linear as a set of project documents: an index doc (`osclaude.log-decisions`) and one child doc per ISO week (`osclaude.log-decisions.YYYY-Www`). To log a decision, append the entry to the current week's doc — creating it if needed — then update that week's row in the index table. Weekly buckets exist for the **read** side and for a hard **write** ceiling. The write *mechanism* is solved: `save_document` takes a `patch` parameter, and `{"op": "append", …}` adds an entry without touching what is already there (*Reading Linear safely*, the `get_document` overflow entry). What `append` does not solve is reading — a single monotonically growing log passes `get_document`'s overflow threshold and then needs the save-to-file-and-slice recovery path to be read at all, and it cannot be searched in one call. A dated child per ISO week keeps every read bounded, so the buckets stay. The earlier rationale, that the write was full-replace with no append, was wrong about the mechanism and right about the conclusion: do not rewrite a large document by hand. Append to it instead (APP-1667). **Nor can `append` cross Linear's 250,000-character document cap, and at the cap a log stops accepting entries altogether.** `log.meirion-decisions` (A1 team, project `a1.MeirionPritchard · Work section`) is a single monolithic document at roughly 250,380 characters — it was never migrated to index-plus-children — and on 2026-10-03 a `save_document` patch inserting D094 was rejected outright: *"content must be shorter than or equal to 250000 characters."* No write that does not **shrink** the document can land, so the log can take neither the entry nor, being its own index, the index row pointing at the child the entry went into instead (`log.meirion-decisions.2026-W40`, filed the same day). The weekly child is therefore live and **unreferenced**: a reader of the main log will not find D094. **So the bucket rule is a write-side guarantee and not only a read-side convenience — a log kept on index-plus-weekly-children never approaches the cap, and a log that is not on that scheme eventually cannot be written to at all.** The surviving `log.meirion-decisions` monolith needs a one-off Owner-approved split: restructuring a live decision record is the Owner's, and it is named here, never authored. *The 250,380-character size and the missing D094 index row are reported from APP-2017 and are unverified — reading the document means pulling about 250KB into the run and reproducing the refusal needs a write; what was confirmed is only that both documents exist in that project.* (APP-2017.) The log's structure, entry format, and lifecycle are canon in `convention-decision-log`; this is only the Linear mapping, and the cap and the migration trigger are stated there too.

**Append a new dated entry with every issue reference written as a bare identifier — never by copying a neighbouring entry's stored issue markup.** *Writing Linear safely* above rules the general case, but it is filed with the issue-write traps and a loader appending to a document is not reading it — so the rule is restated nowhere and pointed at here. The hazard is specific to this surface: a read of one of these documents returns the stored markup, so the previous entry a new one is drafted against is saturated with resolved issue tags, and the eye pattern-matches their shape onto a plain identifier — which then needs a UUID, and takes the nearest one in context rather than the right one. So write the bare identifier and let Linear resolve it on save; reuse a sibling entry's prose structure freely and its markup never. This binds on every append-style document whose own history carries these tags — the stand-up buckets, the decision-log buckets and the Owner-session agendas. (Worked case: an `apps.standup` entry of 2026-10-08 hand-typed tags for two tickets and gave both an unrelated ticket's UUID, lifted from a few lines below in the same document; both rendered, both resolved, both bound to that ticket, and the mismatch was caught only by a read-back noticing the resolved titles did not match the bullets — the same root as APP-1326's `a1.standup` case, recurring after the rule was live, because the rule is filed where the writer of an issue reads and not where the writer of a document does — APP-2166.)

**The per-cycle cycle-goal document** — the committed goal and shape of a cycle, produced by `task-cycle-planning` at commit — is filed as a Linear **document**, one per cycle, in the owning delivery team's operations / planning project (the same documents store the decision log lives in), with a dotted, type-prefixed title on the **team key, lowercased** — `apps.cycle-goal.YYYY-Www`, `a1.cycle-goal.YYYY-Www`, `mbn.cycle-goal.YYYY-Www`, `mrp.cycle-goal.YYYY-Www` — never a project-derived prefix. The team form is the one `task-cycle-planning`, `skill-attention-sweep` and `skill-coordinate` are all specified against, and it is the only form that yields one document per team; a project-derived prefix collides the moment a team owns more than one project. The parent project is named, not derived: Apps → os.Claude, A1 → a1.OS, MBN → mbn.growth, Mr Pritchard → its operations project. **A consumer resolving this document searches on the shared `cycle-goal` segment, never on a prefix**, so a prefix disagreement degrades to a near-miss a run can report rather than to an absence it reads as "never committed". (Worked case: the 2026-09-14 boundary run created `apps.`, `a1.` and `mbn.cycle-goal.2026-W38` off the task artefact, three hours after a `skill-plan` run had tested freshness against `osclaude.cycle-goal.*` — the prefix this convention previously gave as its example — and reported the documents missing. Had they already existed, that test would still have reported them missing. APP-1424; the deterministic-resolution failure is APP-1054's, one layer up in the name rather than the location.)

**Author-pass note:** the three live documents were verified this run — `apps.cycle-goal.2026-W38`, `a1.cycle-goal.2026-W38` and `mbn.cycle-goal.2026-W38`, filed to os.Claude, a1.OS and mbn.growth, with no `osclaude.cycle-goal.*` anywhere. The **Mr Pritchard cell is inferred**, not observed: no MRP goal document exists yet, so `mrp.cycle-goal.YYYY-Www` and "its operations project" are derived from `task-cycle-planning`'s team set. It is a document, not an issue, so it never sits inside the cycle as scope and never inflates the cycle's burn. **The document carries the committed ticket list** — the enumerated IDs the Owner is committing the team to — and that list is the definition of *planned* for the cycle: anything in the cycle and not on it is unplanned — derived from structure and never labelled, per the cycle-membership entry in *Labels* above, whose retired label is not to be created (Owner ruling, Aled 2026-10-19T09:44:52.436Z, `APP-1788`; the derivation as stated in `task-cycle-planning` Step 1, `APP-2400`; the committed-list definition is still `APP-1095`'s). Read the dot as "look in Linear", per the naming rule above (`APP-815`). **The `task-cycle-planning` commit proposal is posted as a comment on that document**, one per team per boundary — never on a team-mirror initiative or a project — so a consumer testing freshness can resolve "the latest proposal" deterministically for every team, including one with no mirror initiative (APP-1054). **And the Owner's approval is the goal-document write itself**, dated after the latest proposal comment: a cycle-membership write is not an approval marker, because the delivery loop and the boundary auto-transfer both produce membership writes with no Owner involved (APP-987). `task-cycle-planning` defines the signal; `skill-attention-sweep`, `task-aide-loop` and `assistant-aide` test it. (Owner decision, Aled 2026-09-03.)

**The per-round design-review document** — the table of every Figma (or other design-tool) comment from one review round, with its verbatim text, the element it sits on, its per-comment permalink, the agreed approach and its status — is filed as a Linear **document** in the client or venture project, one per round, titled `<project>.design-review.YYYY-MM-DD` (e.g. `a1-meirionpritchard.design-review.2026-07-17`). It is a document, not an issue: the tickets raised from it link back to it, and it stays the round's status until every row is closed. `skill-design-review-round` owns the process; `convention-ticket` governs the tickets that come out of it. A second round on the same file is a second dated document, never an edit to the first. (Owner ruling, Aled 2026-09-03 — APP-743.)

**Durable artefacts attach as native Links, not comments.** An operator-decision artefact — a decision record, an approved proposal, or an external document the ticket's outcome turns on — is attached to its issue as a **native Linear Link** (the Links sidebar, via `save_issue`'s `links: [{url, title}]`), not pasted into a comment. A comment scrolls out of sight down a thread and is invisible to anyone scanning the issue header; a Link sits in the sidebar as a first-class, titled reference that survives the thread. Reserve comments for discussion and the running narrative, and attach anything meant to be found again as a Link (`APP-878`).

**A proposal a sign-off hangs on is a durable artefact.** A positioning draft, a spec, a design or approach writeup — anything the ticket's *outcome* turns on and the Owner is being asked to approve, amend or reject — is the same class as a decision record, not a comment. File it as a Linear **document** in the owning project, dotted and type-prefixed per the naming rule above, and attach it to its ticket as a native **Link**; the reviewing ticket's `## Definition of done` names the document. This binds hardest on connector-fleet deliverables (Sonar, Pixel, Reach), whose output is routinely a proposal posted for the Owner's call, and it makes the artefact citable from downstream tickets instead of re-readable only by scrolling a thread. **Where a proposal has already been posted as a comment, the repair is to file the document and link it — not to escalate the ticket's priority**, which treats the symptom and leaves the artefact buried. (Worked case: APP-524's agents-site v2 positioning draft — the actor, hero proposition, capability set and copy guardrails the whole epic hangs on — posted as a plain comment on 2026-07-15 and left In Review, assigned, for 28 days; surfaced on 2026-09-07 only by a triage run escalating its priority. Aled's own read: "that is a bad use of a Linear feature and one that is easy for me to miss." APP-1135.)

**Issue numbers** are auto-assigned by Linear (each team has its own key — COS, APP, PIPE, A1, MRP). Never invent them.

## Canon and source-of-truth discipline (Linear)

* **Linear is canon — with one scoped exception.** Project MD files, the website, and synced copies are *derived from* Linear. When they disagree, Linear wins (or Linear needs updating — the file never silently becomes the source).
* **Exception — skill, convention, agent, and operator artefact content.** The **Claude-side saved skills are canon**; edit content there. The `assoc-one/claude-ops` GitHub repo is a **one-way published mirror, downstream of Claude** — the agents site builds from it and the remote Cloud Routines clone it, so it must be kept current, but it never feeds back. Publishing is **Claude → repo, via tickets**: `skill-ops-sync` detects when Claude is ahead and raises the publish tickets. The repo is canon only for its own repo-native files. (Supersedes the 2026-06-05 repo-is-canon rule; decision: osclaude.log-decisions, 2026-06-16.)
* For the general "don't edit canon silently" and "don't fabricate" rules, see `convention-ticket`.

## Quick checklist before creating or updating anything in Linear

- [ ] Right team and project? (Pipeline for people/opportunities; A1 for the consultancy; Mr Pritchard for editorial; MBN for Made by — Neud; Apps for builds and the careerOS `cOS.*` system.)
- [ ] Person → Network; opportunity → Roles/Advisory/Pitches titled for the opportunity, linked back?
- [ ] Backlog (not Todo) if Aled hasn't refined it?
- [ ] Correct label set? (engineering: one `type:`/`work:`, plus one `agent`-group value — `human` or one `agent:*` — and, where a vertical owns the outcome, its `operator-<venture>` from the separate `operator` group (set independently, evicts nothing — APP-1103); `agent:R3-LAY` while in Backlog, real executor set at routing; Pipeline: `contact:`/`reporting:contact`/`task`, `opp:` only where known. Type: pass bare — `task`, never `type:task`. Workstream: pass `engineering` bare, the rest as `work:*` — see *Labels*.)
- [ ] Assignee — Aled only where a genuine human action is needed? (Operator-mandate-edge escalations assign Aled as Owner.)
- [ ] Any comment assigning the operator an action written as numbered, novice-friendly steps — one action per line, commands spelled out literally, a decision kept separate from a thing to type (see `convention-ticket` *Writing an instruction the operator has to action*)?
- [ ] Hierarchy and milestone set? (Leaf under the right epic/feature; milestone where the project has them. Epics never carry `agent:F0-RGE`.)
- [ ] Ticket shape, Pattern A criteria, notes section — per `convention-ticket`?
- [ ] Consequential decision made? → decision-log entry added.
- [ ] Artefact content authored Claude-side (canon), published to `claude-ops` via a ticket?
- [ ] Tone clean per `cos.tov`?
