fix(work-items): reconcile role_labels docs and resolve all three roles at the seam

[kyle-sexton]

Closes #1561

Summary

• Drop the contradictory loud-warning mandate; absent config.role_labels entries are sanctioned silent defaults per setup's omit-defaults instruction.
• Export WIT_AUTONOMOUS_ELIGIBLE_LABEL and WIT_RECURRING_MAINTENANCE_LABEL from binding.sh alongside WIT_HUMAN_GATED_LABEL.
• Extend binding.test.sh coverage for all three roles.

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.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 389a01a2b5

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[claude]

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

---

Security Review

• Gather context (PR diff, changed files)
• Review changed files for security issues
• Post final findings

Scope: plugins/work-items/reference/label-taxonomy.md, plugins/work-items/reference/tracker-seam.md, plugins/work-items/skills/attend-queue/SKILL.md, plugins/work-items/skills/triage/SKILL.md, plugins/work-items/tools/work-item-tracker/lib/binding.sh, plugins/work-items/tools/work-item-tracker/lib/binding.test.sh.

No workflow files, secrets handling, or executable code paths with untrusted-input surfaces are touched by this PR.

No security vulnerabilities found.

Details on what I checked:

• binding.sh — The new WIT_AUTONOMOUS_ELIGIBLE_LABEL / WIT_RECURRING_MAINTENANCE_LABEL exports (binding.sh#L63-L66) are a straight copy of the pre-existing human_gated pattern: values are read via jq -r (no eval, no shell interpolation of untrusted content into a command), and are exported as plain env vars. No new attack surface — same trust model as the field this mirrors.
  • The provider field is regex-restricted (^[a-zA-Z0-9_-]+$, binding.sh#L45) because it's used to build an adapter directory path; the two new role-label values aren't used for path construction anywhere in this diff, so the lack of an equivalent format check isn't a path-traversal issue here.
  • I checked for existing consumers of the two new exported vars elsewhere in the plugin — none yet reference them outside binding.test.sh, so this PR doesn't newly activate any unsafe downstream usage.
• binding.test.sh — Only adds test coverage; no behavioral change.
• Doc changes (label-taxonomy.md, tracker-seam.md, attend-queue/SKILL.md, triage/SKILL.md) — These reconcile documentation with binding.sh's actual (pre-existing) behavior: absent config.role_labels entries were already defaulted silently in code (no warning was ever emitted by binding.sh); the docs previously mandated a "loud warning" that didn't match the shipped default-omission design from /work-items:setup. This is a documentation/behavior reconciliation, not a weakening of an actual enforced control — the human-gated label's malformed/empty/non-string case is still explicitly called out as a hard configuration error in the updated docs, distinct from the sanctioned silent-default case.

[claude]

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

---

Security Review

• Gather context (PR diff, changed files)
• Review changed files for security issues
• Post final findings

Scope: plugins/work-items/reference/label-taxonomy.md, plugins/work-items/reference/tracker-seam.md, plugins/work-items/skills/attend-queue/SKILL.md, plugins/work-items/skills/triage/SKILL.md, plugins/work-items/tools/work-item-tracker/lib/binding.sh, plugins/work-items/tools/work-item-tracker/lib/binding.test.sh.

No workflow files are touched by this PR, so no pull_request_target/workflow_run/permissions/pin concerns apply (and those lanes are zizmor's territory per this repo's review policy regardless).

No security vulnerabilities found.

Details on what I checked:

• binding.sh#L63-L66 — the new WIT_AUTONOMOUS_ELIGIBLE_LABEL / WIT_RECURRING_MAINTENANCE_LABEL exports are a straight copy of the pre-existing human_gated pattern (L61-L62, unchanged by this diff): values are read via jq -r (no eval, no shell interpolation of untrusted content into a command) and exported as plain env vars/data strings — not built into shell commands or paths.
  • provider is regex-restricted (^[a-zA-Z0-9_-]+$, L45) because it's used to build an adapter directory path; the two new role-label values are never used for path construction, so the lack of an equivalent format check isn't a path-traversal issue here.
  • I confirmed via grep that the only consumers of the three WIT_*_LABEL vars outside this diff (frontier.sh, work-item-tracker.sh) treat them as opaque label-text data passed to jq/adapter query args, not interpolated into eval or command strings — so a malformed value (empty string, or a jq -r-rendered array/object) can't escalate to command injection. It's a data-shape gap, not a code-execution or auth-bypass one, and it's pre-existing behavior this PR extends to two more fields rather than something newly introduced — noting it here for completeness since another reviewer flagged it, but it doesn't rise to a security finding under this review's scope (logic/injection/access-control with real exploitability), and .work-item-tracker.json is repo-owner-authored setup config, not attacker-controlled input in the trust model this tool operates in.
• binding.test.sh — test-only, no behavioral change.
• Doc changes (label-taxonomy.md, tracker-seam.md, attend-queue/SKILL.md, triage/SKILL.md) — reconcile prompt instructions with binding.sh's actual (pre-existing) silent-default behavior; no privilege/authorization semantics change — the human-gated label's malformed/empty/non-string case remains a documented hard configuration error, distinct from the sanctioned silent-default-on-absence case. These are LLM-facing instructions, not executable access control, so a documentation/behavior mismatch here isn't a code-level vulnerability.

[claude]

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

---

Security Review

• Gather context (PR diff, changed files)
• Review changed files for security issues
• Post final findings

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

Diffed the security-relevant files at HEAD (3c21bed8) against the last commit that received a completed, passing Claude security review (6525c9e9, 17:20:47 review):

git diff 6525c9e9..3c21bed8 -- plugins/work-items/reference/label-taxonomy.md \
  plugins/work-items/reference/tracker-seam.md \
  plugins/work-items/skills/attend-queue/SKILL.md \
  plugins/work-items/skills/triage/SKILL.md \
  plugins/work-items/tools/work-item-tracker/lib/binding.sh \
  plugins/work-items/tools/work-item-tracker/lib/binding.test.sh

Zero output — none of the six security-relevant files changed. The only commits added since that review are:

• 5ee5ec0 — style fix (MD012 blank-line lint) in CHANGELOG.md
• aef139c — version bump to 0.35.8 for changelog parity
• 3c21bed — version bump to 0.35.9

All three touch only plugins/work-items/.claude-plugin/plugin.json (version string) and plugins/work-items/CHANGELOG.md (prose), neither of which is executable code or a trust-boundary surface.

No security vulnerabilities found. The 6525c9e9 review's findings still apply at this head: the new WIT_AUTONOMOUS_ELIGIBLE_LABEL / WIT_RECURRING_MAINTENANCE_LABEL exports in binding.sh mirror the pre-existing WIT_HUMAN_GATED_LABEL pattern (jq -r read, exported as plain data — no eval/command interpolation), and the doc changes reconcile prompt instructions with binding.sh's pre-existing silent-default behavior without altering authorization semantics.
· branch cursor/role-labels-seam-resolve-63e1

[github-actions]

Last security-reviewed head: aa2c3669af7869d1b96b56d7abb58f8898001274. 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 3m 2s —— View job

---

Code Review (/review:code-review)

• Gather context (PR diff, changed files, CLAUDE.md/REVIEW.md)
• Check skip gate (PR is open, not draft, has meaningful review surface — proceeding)
• Review changed files for correctness/maintainability
• Post findings

Scope: plugins/work-items/reference/label-taxonomy.md, plugins/work-items/reference/tracker-seam.md, plugins/work-items/skills/attend-queue/SKILL.md, plugins/work-items/skills/triage/SKILL.md, plugins/work-items/tools/work-item-tracker/lib/binding.sh, plugins/work-items/tools/work-item-tracker/lib/binding.test.sh (security-flavored questions are out of scope for this lane — see the separate security-review comments above).

Posted 3 inline findings anchored to changed lines:

1. attend-queue/SKILL.md:57 — the new link to reference/escalation-marker.md points at a file that doesn't exist anywhere in the repo (confirmed via Glob/git log --all), leaving the escalation-marker syntax undefined for the attention view.
2. triage/SKILL.md:180 — same issue for reference/ai-disclaimer.md: the literal disclaimer prefix was replaced with a link to a file that doesn't exist, so autonomous triage sessions lose the concrete prefix text.
3. binding.sh:63-66 — the new autonomous-eligible/recurring-maintenance defaulting logic doesn't reject present-but-malformed values (empty string falls back silently; a non-string like [] is rendered by jq -r and exported as literal label text "[]"), contradicting the "present malformed/empty/non-string entry is a configuration error" rule this same PR asserts in label-taxonomy.md. Pre-existing for human_gated (lines 61-62), but this PR extends the same gap to two more fields while tightening the documented contract.

One whole-PR finding no single changed line carries:

The PR's stated goal is to "drop the contradictory loud-warning mandate," and it does rewrite label-taxonomy.md and part of tracker-seam.md's "Role-label resolution is an action-entry invariant" section to say silent-default is sanctioned. But the same mandate is still asserted, unchanged, in several other places — including within the very file this PR edited:

• tracker-seam.md:57-60 and tracker-seam.md:69 — the "gh-native mode" section still says role resolution "falls to defaults with a loud warning" and that a missing binding must be "loud and routable, never silent," directly contradicting the "silently" language this PR just wrote a few dozen lines away in the same document.
• skills/work/SKILL.md:125
• skills/track/SKILL.md:30
• skills/track/actions/due.md:16, recheck.md:16, audit.md:14
• skills/decompose/SKILL.md:74

All of these still instruct the executing skill to "warn loudly" / "never silent" on a defaulted role label — exactly the behavior the new canonical rule says is sanctioned and expected. A repo that follows the normal /work-items:setup-generated binding (which intentionally omits default-valued entries) will still trigger a standing warning from every one of these lanes. This needs to be reconciled in the same change (either finish updating every consumer, or don't change the canonical rule yet) — otherwise the taxonomy and its own source file's consumers actively disagree with each other.
· branch cursor/role-labels-seam-resolve-63e1

[github-actions]

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

[claude]

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

---

Security Review

• Gather context (PR diff, changed files)
• Invoke /review:security-review skill and follow its procedure
• Post final findings

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

Current PR diff (gh pr diff 2487, base → HEAD 508defa091174041109ace6c3466366f1b2484c0) touches only:

• plugins/work-items/.claude-plugin/plugin.json (version bump 0.35.9 → 0.35.12, plus incidental Unicode em-dash normalization in two userConfig description strings — text only, no schema/permission change)
• plugins/work-items/CHANGELOG.md (prose)
• plugins/work-items/reference/label-taxonomy.md
• plugins/work-items/reference/tracker-seam.md
• plugins/work-items/tools/work-item-tracker/lib/binding.sh
• plugins/work-items/tools/work-item-tracker/lib/binding.test.sh

Diffing the four security-relevant files against the last commit that received a completed, passing Claude security review (3c21bed8, 17:20:47 review, reconfirmed 18:58:42):

git diff 3c21bed88ffb26f1d1621f5453fe7cbea2ec4d47..HEAD -- \
  plugins/work-items/reference/label-taxonomy.md \
  plugins/work-items/reference/tracker-seam.md \
  plugins/work-items/tools/work-item-tracker/lib/binding.sh \
  plugins/work-items/tools/work-item-tracker/lib/binding.test.sh

Zero output — none of the four security-relevant files changed since that review. The only commits added since then (3c21bed8 → 508defa0, a merge-forward of main) touch plugin.json (version string + em-dash normalization) and CHANGELOG.md (prose) — neither is executable code or a trust-boundary surface. No workflow files, secrets handling, or permissions changes are in scope.

Note for context (not a security finding): the merge-forward brought plugins/work-items/reference/escalation-marker.md and plugins/work-items/reference/ai-disclaimer.md into the tree from main (#2489), which appear to resolve the dangling-reference issues flagged by earlier code-review/Codex passes on attend-queue/SKILL.md:57 and triage/SKILL.md:180 — those two files are no longer part of this PR's diff against origin/main.

No security vulnerabilities found. The 6525c9e9/3c21bed8 review's findings still apply at this head: WIT_AUTONOMOUS_ELIGIBLE_LABEL / WIT_RECURRING_MAINTENANCE_LABEL in binding.sh#L63-L66 mirror the pre-existing WIT_HUMAN_GATED_LABEL pattern (jq -r read, exported as plain data — no eval/command interpolation into shell), and the doc changes reconcile prompt instructions with binding.sh's pre-existing silent-default behavior without altering authorization semantics. The present-but-malformed-value gap (empty string / non-string like [] bypassing the documented hard-error) noted by the code-review lane is a correctness/doc-contract issue, not a security vulnerability under this lane's scope — .work-item-tracker.json is repo-owner-authored config, not attacker-controlled input, and the resulting values are never interpolated into eval or command strings.

[claude]

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

---

Code Review (/review:code-review)

• Gather context (PR diff, changed files, CLAUDE.md/REVIEW.md)
• Check skip gate (PR open, not draft — proceeding)
• Review changed files for correctness/maintainability
• Post findings

Scope: plugins/work-items/reference/label-taxonomy.md, plugins/work-items/reference/tracker-seam.md, plugins/work-items/skills/attend-queue/SKILL.md, plugins/work-items/skills/triage/SKILL.md, plugins/work-items/tools/work-item-tracker/lib/binding.sh, plugins/work-items/tools/work-item-tracker/lib/binding.test.sh (security-flavored questions are out of scope for this lane).

Re-reviewed at HEAD 508defa (the merge-forward-from-main commit). Two previously-flagged findings are now resolved, and one posted as a fresh inline comment because it's still open in this diff.

Resolved since the last review pass:

• attend-queue/SKILL.md:57 (link to reference/escalation-marker.md) and triage/SKILL.md:180 (link to reference/ai-disclaimer.md) previously pointed at files that didn't exist. Both files now exist — merged in from main via 9c8963f and 1739ae5 respectively — and both are complete: escalation-marker.md defines the full comment-prefix grammar and writer/reader contract; ai-disclaimer.md defines the canonical form and {lane} substitution rule. No further action needed here.

Still open (posted inline):

• binding.sh:66 — present-but-malformed role_labels entries (empty string, or non-string like []) still aren't rejected for any of the three roles, contradicting the "malformed/empty/non-string is a configuration error" rule this PR itself writes into label-taxonomy.md:57 and tracker-seam.md:137. Pre-existing for human_gated; this PR extends the same gap to the two new roles while tightening the documented contract. Details and a suggested fix direction are in the inline comment.

Whole-PR finding (no single changed line carries it):

The PR's summary says it drops the "contradictory loud-warning mandate," and it does so in label-taxonomy.md and the new "Role-label resolution is an action-entry invariant" section of tracker-seam.md (silent default when a config.role_labels file or entry is absent). But several other consumers of this exact rule — untouched by this PR — still explicitly instruct "warn loudly" for the identical absent-file-or-entry case, not the different "no binding file at all" gh-native-mode case tracker-seam.md:59-60 legitimately keeps loud:

• skills/work/SKILL.md:125 — "warn loudly when [a role defaults because] the file or entry is absent"
• skills/track/SKILL.md:30 — same "warn loudly rather than [silent]" language
• skills/track/actions/due.md:16, recheck.md:16, audit.md:14 — "warn loudly when it defaults for that reason (surface it, never silent)"
• skills/decompose/SKILL.md:74 — "warn loudly when a role defaults because the binding or its config.role_labels entry is absent, rather than substituting silently"

A repo following the normal /work-items:setup-generated binding (which intentionally omits default-valued entries by design) will still trigger a standing warning from every one of these five lanes, directly contradicting the canonical rule this PR just established two directory levels up. This still needs reconciling in the same change — either finish updating every consumer of the old rule, or don't change the canonical text yet.
· branch cursor/role-labels-seam-resolve-63e1

[claude]

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

---

Security Review (/review:security-review)

• Gather context (PR diff, changed files)
• Invoke /review:security-review skill and follow its procedure
• Post final findings

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

Diffed the security-relevant files at HEAD (aa2c3669) against the last commit that received a completed, passing Claude security review (508defa0, 20:23:49Z review):

git diff 508defa091174041109ace6c3466366f1b2484c0..aa2c3669af7869d1b96b56d7abb58f8898001274 -- \
  plugins/work-items/reference/label-taxonomy.md \
  plugins/work-items/reference/tracker-seam.md \
  plugins/work-items/skills/attend-queue/SKILL.md \
  plugins/work-items/skills/triage/SKILL.md \
  plugins/work-items/tools/work-item-tracker/lib/binding.sh \
  plugins/work-items/tools/work-item-tracker/lib/binding.test.sh

The only in-range diff is a WIT_LEASE_TTL_MINUTES hunk in binding.sh, but that's a catch-up artifact of the merge-forward, not something this PR introduces: git diff origin/main...HEAD (the PR's actual diff against its base) shows zero changes to that hunk — it's already present on origin/main (landed there via a2afaa8, unrelated to this PR, before 508defa0's merge-forward point). Confirmed with:

git diff origin/main...HEAD -- plugins/work-items/reference/label-taxonomy.md \
  plugins/work-items/reference/tracker-seam.md \
  plugins/work-items/skills/attend-queue/SKILL.md \
  plugins/work-items/skills/triage/SKILL.md \
  plugins/work-items/tools/work-item-tracker/lib/binding.sh \
  plugins/work-items/tools/work-item-tracker/lib/binding.test.sh

which shows this PR's own contribution to those six files is unchanged since the last full review — still just the WIT_AUTONOMOUS_ELIGIBLE_LABEL / WIT_RECURRING_MAINTENANCE_LABEL exports (mirroring the pre-existing WIT_HUMAN_GATED_LABEL jq -r read/export pattern — no eval/command interpolation) plus the doc reconciliation in label-taxonomy.md / tracker-seam.md. The only other changes since 508defa0 are the version bump (0.35.13 → 0.35.14) in plugin.json and prose in CHANGELOG.md — neither is executable code or a trust-boundary surface.

No security vulnerabilities found. The prior reviews' findings still apply at this head: the two new exported labels carry the same trust model as WIT_HUMAN_GATED_LABEL (plain jq -r-read data, never interpolated into eval or a shell command), and .work-item-tracker.json is repo-owner-authored setup config, not attacker-controlled input. The present-but-malformed-value gap (empty string / non-string like [] bypassing the documented hard-error, e.g. binding.sh#L61-L66) flagged repeatedly by the code-review lane remains a correctness/doc-contract issue, not a security vulnerability under this lane's scope.
· branch cursor/role-labels-seam-resolve-63e1

[claude]

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

---

Code Review (/review:code-review)

• Gather context (PR diff, changed files, CLAUDE.md/REVIEW.md)
• Check skip gate (this head already has a successful review from this lane that still applies)
• Review changed files for correctness/maintainability
• Post findings

Skip gate: this head already has a successful review from this lane that still applies.

Diffed the PR-scoped files (git diff origin/main...HEAD) at current HEAD aa2c3669af7869d1b96b56d7abb58f8898001274 against the last commit that received a completed code-review pass from this lane (508defa0, 20:57:01 review):

git diff 508defa091174041109ace6c3466366f1b2484c0..aa2c3669af7869d1b96b56d7abb58f8898001274 -- \
  plugins/work-items/reference/label-taxonomy.md \
  plugins/work-items/reference/tracker-seam.md \
  plugins/work-items/tools/work-item-tracker/lib/binding.test.sh

Zero output for those three files. binding.sh does show a diff between the two commits, but it's entirely the unrelated lease_ttl_minutes feature merged forward from main — confirmed by comparing git diff origin/main...HEAD -- .../binding.sh at this head against the same file's PR-scoped diff at 508defa0: the role_labels hunk (human-gated / autonomous-eligible / recurring-maintenance) this PR actually touches is unchanged. The only commits added since 508defa0 are a merge-forward of main (fa762fb et al.) touching unrelated plugins, none of which intersect this PR's actual diff against origin/main.

No new findings — the prior pass's results still apply:

• Resolved (confirmed already in the 20:57:01 pass): the dangling references to reference/escalation-marker.md (attend-queue/SKILL.md:57) and reference/ai-disclaimer.md (triage/SKILL.md:180) — both files now exist, merged in from main.

• Still open, already posted inline on this PR: binding.sh:61-66 — present-but-malformed role_labels entries (empty string, or non-string like []) still aren't rejected for any of the three roles, contradicting the "malformed/empty/non-string is a configuration error" rule this PR itself writes into label-taxonomy.md/tracker-seam.md. Validate that a present entry is a non-empty string before applying the default-on-absent logic, distinguishing "key absent" from "key present but empty/non-string" for all three roles.

• Still open, whole-PR finding (no single changed line carries it): several consumers of the old "warn loudly on defaulted role label" rule — untouched by this PR — still contradict the new "silent default is sanctioned" canonical text this PR just wrote in label-taxonomy.md/tracker-seam.md:

  • skills/work/SKILL.md:125
  • skills/track/SKILL.md:30
  • skills/track/actions/due.md:16, recheck.md:16, audit.md:14
  • skills/decompose/SKILL.md:74

  This still needs reconciling in the same change — either finish updating every consumer of the old rule, or don't change the canonical text yet.

Per the skip-gate rule, since no PR-scoped file changed since the last completed pass, no new inline comments were posted this run — the two findings above remain outstanding from the prior review.
· branch cursor/role-labels-seam-resolve-63e1