work-items(work): tracker seam never bound in claude-code-plugins itself — .work-item-tracker.json absent, every seam verb exit-3's

[kyle-sexton]

Lane: work · Category: operational

Triggering example

Fresh /loop /work-items:work session, first list-frontier --autonomous call this cycle:

work-item-tracker: no binding found (.work-item-tracker.json) — see CONTRACT.md Setup

(exit 3)

Observed vs expected

• Observed: melodic-software/claude-code-plugins — the flagship dogfood repo for this very plugin family — has never had .work-item-tracker.json committed (git log --oneline -- .work-item-tracker.json is empty on main). Every work-item-tracker.sh seam verb (list-frontier, claim, reclaim) hard-errors here. The work lane's standing rules (labels status: ready/status: needs-decision, issue numbers work-items(work): status: ready issues with an open PR stay pickable — no in-review state (re-pick risk) #463/repo: per-change version bump + top-insert CHANGELOG serialize concurrent same-plugin PRs (conflict by construction) #464 conventions) were clearly written assuming direct gh label queries, not the seam — so prior "work" cycles bypassed the seam entirely rather than hitting this.
• Expected: either (a) the repo runs /work-items:setup apply once to seed provider: github + lease_ttl_hours, so /work-items:work's own Selection Priority and seam-based claim/reclaim actually function here, or (b) if the operator's standing lane rules are meant to be the authoritative selection spec on this repo (bypassing the skill's built-in tiers by design), the skill/lane docs should say so explicitly instead of silently degrading to exit 3 every cycle.

Notes

• This session did NOT bind the seam unprompted — it's a tracked write to main that also governs the other loop lane (T4/work-2), and per the skill's own apply semantics deserves a real interview (provider choice, lease TTL, recurring-schedule seeding), not a one-off guess mid-cycle. Selection this cycle proceeded via direct gh issue list --label "status: ready" instead, per the operator's explicit pick-order rules.
• Adjacent but distinct: work-items: triage/work lanes have no documented no-local-checkout mode — seam assumes a project root #449 (seam assumes a project root exists at all — no-local-checkout mode) and planning: wayfind hardcodes GitHub Issues/gh as the only tracker backend, bypassing the work-item-tracker seam #416 (wayfind hardcodes gh, bypassing the seam) are both about the seam's design; this is "the seam was never turned on for this repo," a pure setup gap.

[kyle-sexton]

This was generated by AI during triage.

T3 — routing needs-human + wayfind: interview. The issue's own text calls for "a real interview (provider choice, lease TTL, recurring-schedule seeding)" before binding .work-item-tracker.json on this repo — it's a tracked write to main governing multiple concurrent loop lanes (work, work-2), not a default an autonomous pass should guess. This cycle continued selecting via direct gh label queries per the operator's standing lane rules, consistent with the issue's fallback option (b).

[kyle-sexton]

Decision brief — generated by AI on the wayfind: interview lane. ~2-minute read. Recommends; binds nothing.

Problem

claude-code-plugins — the flagship dogfood repo for the work-items plugin family — has never committed .work-item-tracker.json, so every seam verb (list-frontier, claim, reclaim) exit-3's here and the work lane has been silently bypassing the seam via direct gh label queries. Binding the seam is a tracked write to main that governs two concurrent loop lanes (work, work-2), so it warrants a decision rather than an autonomous guess.

The real fork (this is the decision)

The issue's own "Expected" gives two paths:

• (a) Bind the seam — run /work-items:setup apply once to seed the binding, so /work-items:work's built-in Selection Priority and seam-based race-safe claim/reclaim actually function here.
• (b) Formalize the bypass — if the operator's standing lane rules (direct gh issue list --label ... pick-order) are meant to be the authoritative selection spec on this repo by design, say so explicitly in the skill/lane docs instead of degrading to exit-3 every cycle.

Everything below (provider, TTL, schedule) is a sub-decision that only exists under (a).

Today — what's implemented

• Seam ships bundled with the plugin; it resolves plugin-dir-canonical via CLAUDE_PLUGIN_ROOT, project-root fallback (plugins/work-items/reference/tracker-seam.md "Provider-neutral over the seam"). In this repo the engine lives under plugins/work-items/tools/work-item-tracker/, not vendored at project root — so binding presumes the plugin is installed when the loop runs here; it is not "write the file and every verb works" independent of the install.
• Binding shape (plugins/work-items/tools/work-item-tracker/CONTRACT.md "Setup (binding file)"): tracked .work-item-tracker.json at repo root — schema_version, one provider, config.lease_ttl_hours (REQUIRED; absent → exit 3). Owner/repo are never recorded (derived from the git remote at runtime).
• Two bundled adapters: github and local-markdown. Missing binding → exit 3, no inline wizard (CONTRACT.md "Exit codes", "Setup").
• Recurring schedule is a separate tracked file .github/recurring-schedule.json ({"items":[...]}) that due/recheck/work read; absent today as well. It is not a tracker record and does not route through the seam (setup SKILL.md "Resolving the paths").
• Confirmed absent on main: both .work-item-tracker.json and .github/recurring-schedule.json (contents API 404).

Sub-decisions under (a)

Provider — effectively forced

local-markdown is disqualified as a coordination surface, not merely less preferred: CONTRACT.md ("local-markdown adapter") states it is "NEVER a coordination surface" and its manifest declares reclaim: false (exit 6). This repo runs concurrent lanes needing race-safe claim + idempotent stale-lease reclaim, which only github provides among the bundled adapters. → github.

Lease TTL

config.lease_ttl_hours default is 24 (setup SKILL.md step 3, marked RECOMMENDED). Reclaim runs an activity check at session start (non-lease comments since renewed_at, open cross-referenced PRs — CONTRACT.md "Lease protocol"), so TTL never steals active work; it only bounds how long a crashed session's claim lingers before another lane can reclaim it. 24h is safe; go shorter only if crashed-claim latency would bite the loop cadence. → 24.

Recurring schedule seeding — separable, deferrable

Binding + TTL can ship without touching the schedule. Options: seed the empty {"items":[]} skeleton now (stops due/work degrading, seeds nothing); run the full setup interview to seed real recurring items (quarterly dependency/lint/CI/security reviews per setup SKILL.md step 3); or defer entirely. Schedule seeding starts cadence clocks and creates issues, so it is the part most worth a deliberate interview.

Role labels — no action

The repo already uses needs-human (the default human-gated vocab; this very issue carries it). Defaults agent-ready/needs-human/recurring align, so no config.role_labels remap is needed (setup SKILL.md "Canonical role labels").

Reversibility (decomposed — not a blanket claim)

• Binding file itself: trivially reversible (edit/delete the JSON).
• Provider choice: near-irreversible once both lanes coordinate through it — a switch mid-flight strands live leases on real issues. This is the sticky one.
• TTL: freely tunable later.
• Schedule seeding: separable and deferrable; creates issues + starts cadence clocks, so treat as its own commitment.

Options

RECOMMENDED — (a) bind github, lease_ttl_hours: 24, empty schedule skeleton now; defer real recurring seeding to its own interview. Rationale: this is the dogfood repo — its own seam going unused is the credibility gap, and (a) converges with the direction of #416 (fix seam-bypass), #478/#479 (absorb the loop rules into the skills, i.e. onto the seam). Binding + a conservative 24h TTL are the low-blast-radius parts; the {"items":[]} skeleton stops recurring-action degradation without committing to any cadence clock. Both lanes should be paused/coordinated for the single tracked commit to main.

Option 2 — (a) full setup, including a real recurring-schedule interview now. One pass gets binding + a live maintenance cadence. Costs more up-front decision time and commits to cadence clocks + created issues immediately (higher, less-reversible blast radius).

Option 3 — (a) bind github + TTL only, no schedule file at all. Minimal. due/recheck/work keep reporting "no recurring schedule configured" until a later pass — an accepted, visible degradation rather than a silent exit-3.

Option 4 — (b) document the bypass instead of binding. Only defensible as a deliberate, documented decision that the operator's gh-query pick-order is the authoritative spec here. Weigh against it: it cuts against #416 (which treats seam-bypass as a bug to fix) and #478/#479 (converging onto the seam), so it reads as a documentation stopgap, not a resolution — say so if chosen.

Cross-links

• planning: wayfind hardcodes GitHub Issues/gh as the only tracker backend, bypassing the work-item-tracker seam #416 — wayfind hardcodes gh, bypassing the seam (same seam-adoption arc).
• work-items(work): absorb v4 loop-prompt execution rules into the skill #479 / work-items(triage): absorb v4 loop-prompt routing rules into the skill #478 — absorb the v4 loop-prompt execution/routing rules into work/triage; directly explains why the standing lane rules assumed direct gh queries rather than the seam.
• work-items: triage/work lanes have no documented no-local-checkout mode — seam assumes a project root #449 — seam assumes a project root (no-local-checkout mode); the issue names it adjacent-but-distinct.
• feat(work-items): decision-session skill (/work-items:decide) — batched operator decision loop over needs-human/needs-decision #556 — /work-items:decide batched operator decision loop over needs-human/needs-decision; light relevance — this issue is itself the kind of needs-human item such a loop would batch.