docs(work-items): centralize escalation-marker grammar

plugins/work-items/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "work-items",
-  "version": "0.35.10",
+  "version": "0.35.11",
   "description": "Manages development work items through a provider-neutral tracker seam that ships with the plugin (bundled dispatcher plus github and local-markdown adapters; seam plugin-dir canonical, adapters consumer-local-first): dashboard, taxonomy-labeled creation, a race-safe assignee-plus-lease claim protocol, recurring-schedule checks, TODO scanning, stale-lease auditing, plan decomposition into vertical-slice items, raw-intake triage (issues and unsolicited PRs through raw, verified, briefed, autonomous-eligible states), plus the two work-items loop lanes of the loop-lane convention: a self-paced autonomous work-loop drain (work-class admission gate, adaptive item cap, PR-only) and an attended attend-queue escalation lane. The re-runnable setup skill binds the provider (.work-item-tracker.json), seeds the recurring-schedule seam (.github/recurring-schedule.json), and remaps canonical role labels.",
   "author": {
     "name": "Melodic Software",

plugins/work-items/CHANGELOG.md

@@ -3,6 +3,15 @@
 All notable changes to the `work-items` plugin are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning.
 
+## [0.35.11]
+
+### Changed
+
+- **Escalation-marker grammar has one canonical source (#1672).** `reference/escalation-marker.md`
+  now defines the marker comment prefix, kind enum, author-match suppression rule, and
+  label-plus-comment pairing; `work-loop` and `attend-queue` cite it instead of restating the
+  grammar in prose.
+
 ## [0.35.10]
 
 ### Added

plugins/work-items/reference/escalation-marker.md

@@ -0,0 +1,29 @@
+# Escalation marker — machine-readable comment grammar
+
+Worker lanes escalate to the attended queue by pairing the human-gated role label with a
+machine-marked HTML comment. `attend-queue` discriminates escalated rows from parked items wearing
+the same role label by matching this prefix — a marker missing the `<!--` / `-->` wrapper does not
+match.
+
+## Comment prefix (first line)
+
+```text
+<!-- work-items:escalation lane=<lane> kind=<kind> -->
+```
+
+| Token | Values |
+| --- | --- |
+| `<lane>` | Lane id (`work-loop`, `attend-queue`, …) |
+| `<kind>` | `escalated` \| `ratify-c3` \| `routed-advisory` |
+
+## Writer / reader contract
+
+1. Resolve the human-gated role label from `config.role_labels` (never a literal).
+2. Post the marker comment (first line exactly as above, remainder is the human-readable question).
+3. Apply the role label in the **same** label edit as any label removals the outcome requires.
+
+`attend-queue` matches on author **and** marker prefix — suppress duplicate markers from the same
+write identity, never from marker text alone.
+
+Loop-lane escalation record files (`.claude/lane-escalations/…`) are optional exhaust; the tracker
+item plus marker comment is the escalation of record when the record write fails.

plugins/work-items/skills/attend-queue/SKILL.md

@@ -52,9 +52,10 @@ citation. This skill restates none of them; it adds only the attended-lane mecha
 Build a single merged view, oldest first, each row tagged by kind:
 
 1. **`[escalated]`** — open items carrying the human-gated role label (**resolved from the
-   binding's `config.role_labels`, never compared as a literal**; warn loudly on a defaulted
-   resolution) that also carry a machine-marked escalation comment whose first line starts with
-   `<!-- work-items:escalation` — the marker is what discriminates a worker-**escalated** item
+   binding's `config.role_labels`, never compared as a literal**; absent entries fall back to
+   documented defaults) that also carry a machine-marked escalation comment per
+   [`${CLAUDE_PLUGIN_ROOT}/reference/escalation-marker.md`](${CLAUDE_PLUGIN_ROOT}/reference/escalation-marker.md)
+   — the marker is what discriminates a worker-**escalated** item
    from an operator-**parked** one; both wear the same role label, so the label alone never
    qualifies a row. Marker kinds `escalated` (a worker question) and `routed-advisory` (a
    workflow-bot advisory routed by the worker loop's intake sweep) both list here;

plugins/work-items/skills/work-loop/SKILL.md

@@ -230,9 +230,9 @@ while the latch is set (clear it on a fresh healthy snapshot after the pause end
      composes") for the clean/dirty accounting below.
 5. **Escalate.** Anything the gate or execution rejects for human judgment follows the
    convention's escalation contract: the human-gated role label **resolved from
-   `config.role_labels`, never a literal**, plus a machine-marked escalation comment whose first
-   line is `<!-- work-items:escalation lane=work-loop kind=escalated|ratify-c3|routed-advisory -->`
-   — the marker,
+   `config.role_labels`, never a literal**, plus a machine-marked escalation comment per
+   [`${CLAUDE_PLUGIN_ROOT}/reference/escalation-marker.md`](${CLAUDE_PLUGIN_ROOT}/reference/escalation-marker.md)
+   (`lane=work-loop`, `kind=escalated|ratify-c3|routed-advisory`) — the marker,
    not a second label, is what discriminates a worker-escalated item from an operator-parked one.
    The same step performs the contract's escalation record write, **immediately before posting
    that comment**: create `.claude/lane-escalations/<UTC-stamp>-<item>-work-loop.json` (stamp