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

[kyle-sexton]

Closes #1672

Partial: Finding 1 only — canonical marker grammar now lives in reference/escalation-marker.md; work-loop and attend-queue cite it instead of restating the prefix. Finding 2 (open-PR file overlap pre-dispatch) remains open.

Related

None.

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[claude]

Claude finished @kyle-sexton's task in 1m 51s —— View job

---

Security Review

• Gather context (PR diff, changed files)
• Review plugins/work-items/reference/escalation-marker.md (new file)
• Review plugins/work-items/skills/attend-queue/SKILL.md
• Review plugins/work-items/skills/work-loop/SKILL.md
• Post findings

This PR touches only prose skill files (SKILL.md) and a new reference doc consumed by the Claude agent driving the work-items plugin — no workflow YAML, scripts, or executable code changed. Since these SKILL.md files function as the operative instructions the agent follows (effectively the "logic" for an autonomous/human-gated escalation system), I reviewed them for authorization/trust-boundary regressions, not just prose style.

IMPORTANT: Silent fallback replaces the fail-loud requirement for the human-gated role label in attend-queue

File: plugins/work-items/skills/attend-queue/SKILL.md#L54-L56

Before this PR, resolving the human-gated role label from config.role_labels for the [escalated] bucket required the agent to "warn loudly on a defaulted resolution". This PR changes that clause to:

"absent entries fall back to documented defaults"

with no warning requirement, while folding the marker-grammar sentence into a citation of the new reference/escalation-marker.md. The PR description frames this change as pure "grammar" centralization/citation, but this specific edit is a behavioral change to the role-label resolution contract, not a citation swap.

This is inconsistent with every sibling skill that resolves the same config.role_labels value — decompose/SKILL.md:74, work/SKILL.md:125, triage/SKILL.md:153, and track/actions/audit.md:14 all still require warning loudly (triage even stops outright on a malformed/empty/non-string value) rather than substituting the default silently. attend-queue is the human-in-the-loop surface that decides which items are surfaced to the operator as needing attention — if a repo's binding is missing or the human-gated entry is absent/misconfigured, this change means the agent now silently falls back to the default label instead of surfacing that fact to the operator. A repo that intentionally remapped config.role_labels (e.g., because it also uses the default label for something else) would have escalated/parked items silently misclassified with no warning surfaced in the attention view, undermining the queue's core discriminator ("both wear the same role label, so the label alone never qualifies a row").

Confidence: Medium — I can't verify from docs alone whether this was an intentional relaxation or accidental scope-creep during the citation refactor, but the inconsistency with every other skill in the same plugin resolving the same config key strongly suggests it's unintentional, and the affected surface (human-gated escalation triage) is exactly where silent misconfiguration is highest-impact.

Fix this →

No other findings

• plugins/work-items/reference/escalation-marker.md is pure documentation of an HTML-comment marker grammar with no executable content; the writer/reader contract it documents (match on author + marker prefix, never marker text alone; role label resolved from config, never a literal) is consistent with — and in the author-matching case, more explicit than — the pre-existing contract.
• plugins/work-items/skills/work-loop/SKILL.md diff is a clean citation swap (inline marker string → link to the new reference doc); no semantic/behavioral change.
• No GitHub Actions workflow, script, or dependency files are touched by this PR, so no supply-chain, permissions, or workflow-trigger surface applies here.

[claude]

Claude finished @kyle-sexton's task in 1m 25s —— View job

---

Security Review

• Gather context (PR diff vs origin/main, re-verify after synchronize)
• Confirm whether the synchronize changed the reviewed files
• Re-review plugins/work-items/reference/escalation-marker.md, attend-queue/SKILL.md, work-loop/SKILL.md
• Post findings

This synchronize event rebased the branch onto a newer main (picking up unrelated commits to other plugins) — the three files this PR actually touches are byte-identical to what was reviewed previously (git diff between the prior reviewed commit and current HEAD f0930e2 shows zero changes under plugins/work-items/). The earlier finding still applies and is unresolved.

IMPORTANT: Silent fallback replaces the fail-loud requirement for the human-gated role label in attend-queue

File: plugins/work-items/skills/attend-queue/SKILL.md#L54-L56

Before this PR, resolving the human-gated role label from config.role_labels for the [escalated] bucket required the agent to "warn loudly on a defaulted resolution." This PR changes that clause to:

"absent entries fall back to documented defaults"

with no warning requirement, while folding the marker-grammar sentence into a citation of the new reference/escalation-marker.md. The PR description frames this as pure "grammar" centralization, but this specific clause is a behavioral change to the role-label resolution contract, not a citation swap.

This is inconsistent with every sibling skill that resolves the same config.role_labels value — decompose/SKILL.md:74, work/SKILL.md:125, triage/SKILL.md:153, and track/actions/audit.md:14 all still require warning loudly (triage even hard-stops on a malformed/empty/non-string value) rather than substituting the default silently. The shared seam doc itself (reference/tracker-seam.md:130-134) still states the fail-loud rule explicitly, calling silent substitution "a real correctness risk."

attend-queue is the human-in-the-loop surface that decides which items are surfaced to the operator as needing attention — if a repo's binding is missing or the human-gated entry is absent/misconfigured, this change means the agent now silently falls back to the default label instead of surfacing that fact to the operator. A repo that intentionally remapped config.role_labels (e.g., because it also uses the default label for something else) would have escalated/parked items silently misclassified with no warning surfaced in the attention view, undermining the queue's core discriminator ("both wear the same role label, so the label alone never qualifies a row").

Severity: Important
Confidence: Medium — I can't verify from docs alone whether this was an intentional relaxation or accidental scope-creep during the citation refactor, but the inconsistency with every other skill in the same plugin (and with the shared seam doc it's supposed to compose with) resolving the same config key strongly suggests it's unintentional, and the affected surface (human-gated escalation triage) is exactly where silent misconfiguration is highest-impact.

Fix this →

No other findings

• plugins/work-items/reference/escalation-marker.md is pure documentation of an HTML-comment marker grammar with no executable content; the writer/reader contract it documents (match on author + marker prefix, never marker text alone; role label resolved from config, never a literal) is consistent with — and in the author-matching case, more explicit than — the pre-existing contract.
• plugins/work-items/skills/work-loop/SKILL.md diff is a clean citation swap (inline marker string → link to the new reference doc); no semantic/behavioral change.
• No GitHub Actions workflow, script, or dependency files are touched by this PR, so no supply-chain, permissions, or workflow-trigger surface applies here.
  · branch cursor/escalation-marker-ssot-63e1

[claude]

Claude finished @cursor[bot]'s task in 1m 19s —— View job

---

Security review — /review:security-review

• Gather context (PR diff vs origin/main, confirm PR is open)
• Check skip gate before re-running a full pass
• Post result

Skip gate hit: this head already has a successful security review that still applies.

This synchronize event only rebased the branch onto a newer main (picking up unrelated commits to other work-items skills — issue-conventions.md, triage/SKILL.md, etc. — that are outside this PR's actual changed-file set) and bumped the plugin version/changelog. Diffing the three security-relevant files this PR touches, from the last successfully-completed review (commit f0930e2) to current HEAD (5da6266), shows zero changes:

git diff f0930e2f6542952255f7a5af8fc83e18de8e6719 5da62665eb47b794b46bdafd21d88f344d9d600a -- \
  plugins/work-items/reference/escalation-marker.md \
  plugins/work-items/skills/attend-queue/SKILL.md \
  plugins/work-items/skills/work-loop/SKILL.md
# (no output)

The only diffs between those two commits under plugins/work-items/ are:

• .claude-plugin/plugin.json — version bump 0.35.7 → 0.35.9, plus a — escaping normalization in two userConfig description strings (non-executable manifest metadata, no security surface).
• CHANGELOG.md — changelog entries only.
• reference/issue-conventions.md and skills/triage/SKILL.md — these picked up from main via the rebase but are not part of this PR's changed-file set (not in the changed_files list for docs(work-items): centralize escalation-marker grammar #2489), so they're out of scope for this review.

Per the skip gate ("this head already has a successful security review that still applies"), I'm not re-running a full pass. The prior finding from the successful reviews at b853008 and f0930e2 — silent fallback replaces the fail-loud requirement for the human-gated role label in attend-queue (skills/attend-queue/SKILL.md#L54-L56) — still stands unresolved at this HEAD: the fix (restoring the "warn loudly on a defaulted resolution" requirement, consistent with decompose/SKILL.md, work/SKILL.md, triage/SKILL.md, and track/actions/audit.md) has not been applied.

The two intervening "automated review did not complete" comments were infrastructure failures on unrelated re-runs and don't change this — no new content existed at those SHAs to review anyway.

[github-actions]

Last security-reviewed head: 33414333d2b4b9cd4e2d464653c9322508bc2cb0. On the next push, the relevance gate compares only the commits since this SHA; delete this comment to force a full re-review.

[claude]

Claude finished @cursor[bot]'s task in 2m 33s —— View job

---

Code review

• Gather context (PR diff vs origin/main, CLAUDE.md, REVIEW.md)
• Confirm code-review lane scope (this repo runs claude-security-review → security findings stay out of this lane; the human-gated role-label "silent fallback" behavior change in attend-queue/SKILL.md was already reported in detail by the security lane earlier on this same thread and is not repeated here)
• Review plugins/work-items/CHANGELOG.md
• Review plugins/work-items/reference/escalation-marker.md (new)
• Review plugins/work-items/skills/attend-queue/SKILL.md and work-loop/SKILL.md diffs
• Post inline finding
• Post summary

Findings

One inline finding posted on plugins/work-items/CHANGELOG.md (lines 4-17): this PR's changelog edit produces a duplicate ## [0.35.8] header — a 0.35.8 entry already existed further down the file before this PR, and the new "changelog parity" commit added a second one instead of merging into it. As a side effect, the file's own intro paragraph is now stranded between the two 0.35.8 blocks instead of sitting under the # Changelog title. See the inline comment for the specific fix.

No other findings

• plugins/work-items/reference/escalation-marker.md (new): the marker grammar it documents (prefix format, lane/kind tokens, writer/reader contract, author+prefix matching) is internally consistent and matches how the marker is already exercised in attend-queue/evals/evals.json, which this PR doesn't touch.
• plugins/work-items/skills/work-loop/SKILL.md: clean citation swap (inline marker string → link to the new reference doc), consistent with the ${CLAUDE_PLUGIN_ROOT}/reference/... link pattern used throughout this plugin's other skills.
• plugins/work-items/skills/attend-queue/SKILL.md: the marker-grammar citation swap itself is clean and correct. (The adjacent "warn loudly" → "absent entries fall back to documented defaults" wording change is a behavioral, not textual, change and is a security/observability-lane concern — already flagged there — so it's excluded from this code-review-lane pass per this repo's REVIEW.md scope split.)
• plugins/work-items/.claude-plugin/plugin.json: straightforward version bump, consistent with the changelog entries (modulo the duplication noted above).

Branch: cursor/escalation-marker-ssot-63e1

[github-actions]

Claude has reviewed this PR 2 times. The lane skips further automatic reviews after 5; deleting this comment resets the count.

[claude]

Claude finished @kyle-sexton's task in 56s —— View job

---

Security review — /review:security-review

• Gather context (PR diff vs origin/main, confirm PR is open)
• Check skip gate before re-running a full pass
• Post result

Skip gate hit: this head already has a successful security review that still applies.

This synchronize event only bumped the plugin version/changelog (0.35.8 → 0.35.9, "Lane-neutral AI disclaimer SSOT" entry). Diffing the three security-relevant files this PR touches, from the last successfully-completed review (commit 5da6266) to current HEAD (8d63d33), shows zero changes:

git diff 5da62665eb47b794b46bdafd21d88f344d9d600a 8d63d331b6788a9d97cf7ad2687fc274473f8c4b -- \
  plugins/work-items/reference/escalation-marker.md \
  plugins/work-items/skills/attend-queue/SKILL.md \
  plugins/work-items/skills/work-loop/SKILL.md
# (no output)

The only diff under plugins/work-items/ at this HEAD relative to the last review is CHANGELOG.md — a new ## [0.35.9] entry plus a corrected 0.35.8 entry (non-executable changelog prose, no security surface). All other files that changed since the last review (plugins/autonomy/**, plugins/bash-format/**, plugins/education/**, plugins/songwriting/**, plugins/work-items/reference/ai-disclaimer.md, plugins/work-items/reference/dogfood-filing.md, plugins/work-items/skills/triage/SKILL.md) were picked up from main via rebase and are not part of this PR's changed-file set, so they're out of scope for this review.

Per the skip gate ("this head already has a successful security review that still applies"), I'm not re-running a full pass. The prior finding from the successful reviews at b853008, f0930e2, and 5da6266 — silent fallback replaces the fail-loud requirement for the human-gated role label in attend-queue (skills/attend-queue/SKILL.md#L54-L56) — still stands unresolved at this HEAD: the fix (restoring the "warn loudly on a defaulted resolution" requirement, consistent with decompose/SKILL.md, work/SKILL.md, triage/SKILL.md, and track/actions/audit.md) has not been applied.

Severity: Important
Confidence: Medium (unchanged from prior reviews on this thread)
· branch cursor/escalation-marker-ssot-63e1

[claude]

Claude finished @kyle-sexton's task in 1m 11s —— View job

---

Security review — /review:security-review

• Gather context (PR diff vs origin/main, confirm PR is open)
• Check skip gate before re-running a full pass
• Post result

Skip gate hit: this head already has a successful security review that still applies.

This synchronize event merged a newer main into the branch (picking up unrelated commits — plugins/work-items/.claude-plugin/plugin.json, skills/setup/SKILL.md — that are outside this PR's actual changed-file set) and added a new ## [0.35.10] changelog entry. Diffing the three security-relevant files this PR touches, from the last successfully-completed review (commit 8d63d33) to current HEAD (482d8dc), shows zero changes:

git diff 8d63d331b6788a9d97cf7ad2687fc274473f8c4b 482d8dc3e80145eb3cf0f1dff9c473c6c9d9ec5d -- \
  plugins/work-items/reference/escalation-marker.md \
  plugins/work-items/skills/attend-queue/SKILL.md \
  plugins/work-items/skills/work-loop/SKILL.md
# (no output)

Confirmed against origin/main...HEAD: this PR's actual changed-file set is still exactly the four files listed for #2489 (CHANGELOG.md, reference/escalation-marker.md, skills/attend-queue/SKILL.md, skills/work-loop/SKILL.md). The only further movement is in CHANGELOG.md (new 0.35.10 entry, non-executable prose, no security surface). plugin.json and setup/SKILL.md only appear in the raw commit-range diff because of the merge from main — they are not part of this PR's own diff and remain out of scope.

Per the skip gate ("this head already has a successful security review that still applies"), I'm not re-running a full pass. The prior finding from the successful reviews at b853008, f0930e2, 5da6266, and 8d63d33 — silent fallback replaces the fail-loud requirement for the human-gated role label in attend-queue (skills/attend-queue/SKILL.md#L54-L56) — still stands unresolved at this HEAD: the fix (restoring the "warn loudly on a defaulted resolution" requirement, consistent with decompose/SKILL.md, work/SKILL.md, triage/SKILL.md, and track/actions/audit.md) has not been applied.

Severity: Important
Confidence: Medium (unchanged from prior reviews on this thread)
· branch cursor/escalation-marker-ssot-63e1

[claude]

Claude finished @cursor[bot]'s task in 52s —— View job

---

Security review — /review:security-review

• Gather context (PR diff vs origin/main, confirm PR is open)
• Check skip gate before re-running a full pass
• Post result

Skip gate hit: this head already has a successful security review that still applies.

This synchronize event applied the code-review lane's fix for the duplicate ## [0.35.8] changelog header (commit 3341433, "repair changelog parity after merge-forward"). Diffing the three security-relevant files this PR touches, from the last successfully-completed review (commit 482d8dc) to current HEAD (3341433), shows zero changes:

git diff 482d8dc3e80145eb3cf0f1dff9c473c6c9d9ec5d..HEAD -- \
  plugins/work-items/reference/escalation-marker.md \
  plugins/work-items/skills/attend-queue/SKILL.md \
  plugins/work-items/skills/work-loop/SKILL.md
# (no output)

The only diffs since the last review are non-executable:

• CHANGELOG.md — merges the duplicate 0.35.8 headers into one and restores the intro paragraph under the # Changelog title, per the code-review lane's finding.
• plugin.json — version bump, no security surface.

Per the skip gate ("this head already has a successful security review that still applies"), I'm not re-running a full pass. The prior finding from the successful reviews at b853008, f0930e2, 5da6266, 8d63d33, and 482d8dc — silent fallback replaces the fail-loud requirement for the human-gated role label in attend-queue (skills/attend-queue/SKILL.md#L54-L56) — still stands unresolved at this HEAD: the fix (restoring the "warn loudly on a defaulted resolution" requirement, consistent with decompose/SKILL.md, work/SKILL.md, triage/SKILL.md, and track/actions/audit.md) has not been applied.

Severity: Important
Confidence: Medium (unchanged from prior reviews on this thread)
· branch cursor/escalation-marker-ssot-63e1

[claude]

Claude finished @cursor[bot]'s task in 1m 39s —— View job

---

Code review — /review:code-review

• Gather context (PR diff vs origin/main, confirm PR is open, check skip gate)
• Diff the security-relevant/code-review-relevant files since the last completed pass in this lane
• Verify the prior code-review finding (duplicate ## [0.35.8] changelog header)
• Post result

This synchronize event is a targeted fix, not new scope drift. This lane's last completed pass reviewed the PR at commit 5da6266 and flagged one finding: a duplicate ## [0.35.8] header in CHANGELOG.md with the intro paragraph stranded between the two blocks. Diffing the last-reviewed security/code baseline (482d8dc, confirmed unchanged since 5da6266 for this PR's files) against current HEAD 3341433:

git diff --stat 482d8dc 3341433
 plugins/work-items/.claude-plugin/plugin.json |  2 +-
 plugins/work-items/CHANGELOG.md               | 20 ++++++++------------
 2 files changed, 9 insertions(+), 13 deletions(-)

reference/escalation-marker.md, skills/attend-queue/SKILL.md, and skills/work-loop/SKILL.md are byte-identical to what was already reviewed — no new review surface there.

The flagged changelog finding is fixed. CHANGELOG.md now has:

• The intro paragraph restored immediately under # Changelog (no longer stranded).
• A single consolidated ## [0.35.11] entry combining the previously-duplicated escalation-marker-grammar notes, correctly ordered above the pre-existing ## [0.35.10] / ## [0.35.8] entries with no duplicate headers.
• plugin.json bumped 0.35.10 → 0.35.11, consistent with the new changelog entry.

No new findings from this lane at this HEAD.

Out of scope for this lane: the "warn loudly" → "absent entries fall back to documented defaults" behavioral change in attend-queue/SKILL.md (unchanged at this HEAD) is a security/observability concern already reported in detail by the claude-security-review lane on this thread (repo carries that workflow, per REVIEW.md's lane split) — not repeated here.
· branch cursor/escalation-marker-ssot-63e1