work-items: triage/work lanes have no documented no-local-checkout mode — seam assumes a project root

[kyle-sexton]

Category: improvement (operational)
Lane that hit it: triage

Triggering example

Autonomous triage lane invoked as /work-items:triage from a home directory (C:\Users\KyleSexton, not a git repo) targeting the remote melodic-software/claude-code-plugins. The provider mutations (label edits, comments, list) route fine through gh -R <repo>, but two skill steps assume a local project checkout that did not exist:

1. Role-label resolution (reference/tracker-seam.md "Role-label resolution is an action-entry invariant"): reads .work-item-tracker.json at the project root to resolve canonical roles from config.role_labels. With no checkout, there is no binding file — the action silently falls back to documented defaults (agent-ready/needs-human/recurring). Here the defaults happened to match the repo's live labels, but a repo that remapped roles would be queried under the wrong strings with no signal.
2. Redundancy / rejected-concept check (triage workflow step 1): "search the codebase for an existing implementation" and match against docs/out-of-scope/. Neither is possible without a working tree; I had to manually git clone the repo to run these, which the skill never instructs.

What happened vs. what should happen

• Happened: skill assumes it runs inside the consuming repo; a remote-only / no-checkout invocation degrades silently (role defaults) or is blocked (redundancy/codebase search) with no documented remediation. The operator improvises a clone.
• Should: either (a) document that these lanes require a local checkout and stop with a clear remediation when CLAUDE_PROJECT_DIR/git-toplevel is absent (mirroring the existing jq/seam presence checks), or (b) define a remote-repo mode where the binding + codebase checks resolve against a fetched/target repo. Silent role-default fallback in particular should be an explicit warning, not silent.

Scope note

Affects triage (redundancy + role resolution) and work (frontier/claim also read the binding). track/decompose likely too. The seam presence-check pattern already exists for jq and the dispatcher — this is the same class of missing entry-invariant for "am I in a resolvable project context".

[kyle-sexton]

New example (work lane): checkout present but unbound hits the same gap

Live /loop /work-items:work lane, 2026-07-19, targeting melodic-software/claude-code-plugins with a real local checkout at D:\repos\github.com\melodic-software\claude-code-plugins (git top-level resolves fine). This is NOT a no-checkout case — yet the same entry-invariant gap fires:

• There is no .work-item-tracker.json at the project root (this repo develops the work-items plugin but is not itself a bound consumer), so the seam dead-ends at Step 1:
  work-item-tracker: no binding found (.work-item-tracker.json) — see CONTRACT.md Setup
• The skill's documented preflight (reference/tracker-seam.md "two entry-point presence checks") checks jq + the dispatcher script, but NOT binding presence — so the failure surfaces as a raw seam error mid-flow at frontier/claim, not as an upfront actionable "run /work-items:setup first".

Reinforces this issue's "Should (a)": the binding-presence check belongs alongside the existing jq/seam presence checks as a third entry invariant, stopping with a clear remediation — and it should trigger on unbound checkout, not only no checkout. I proceeded via direct gh assignee as the claim mechanism for this lane.

Category: improvement (operational). Lane: work.

[kyle-sexton]

This was generated by AI during triage.

Additional concrete example (same lane, this cycle). With no local checkout, the T2 medium-tier route ("spawn a planning subagent that explores the codebase") had no repo to read. Workaround used: pointed the planning subagents at the installed plugin cache (~/.claude/plugins/cache/melodic-software/<plugin>/<version>/) as the exploration surface. It worked for drafting confident plans, but the cache is the published/installed artifact and is version-lagged from repo HEAD — plans reference the shipped version, not the branch a fix would land on. A documented no-local-checkout mode should say whether codebase-dependent steps (redundancy check, out-of-scope ledger, T2 exploration) should (a) shallow-clone the target repo, (b) read via gh api contents, or (c) fall back to the installed cache with a version caveat.

[kyle-sexton]

This was generated by AI during triage.

Triage → needs-human. Design fork on the work-items seam: (a) add a project-context presence-check that stops with clear remediation when CLAUDE_PROJECT_DIR/git-toplevel is absent (mirroring the existing jq/dispatcher presence checks) and make the silent role-default fallback an explicit warning, vs (b) define a first-class remote-repo mode where the binding + codebase/redundancy checks resolve against a fetched/target repo. The silent role-default fallback is a real correctness risk — a repo that remapped config.role_labels would be queried under the wrong strings with no signal. Priority: medium (work-items is outside the week's north-star plugin set).

[kyle-sexton]

This was generated by AI during triage.

Additional triggering example (2026-07-19 triage loop cycle) — a third degradation variant.

Same setup as the original report (autonomous /work-items:triage from C:\Users\KyleSexton, no local checkout, targeting the remote repo). This cycle did not clone the repo. For the T2 planning subagents that needed to read skill source to draft absorption plans, the workaround was to point them at the installed plugin cache (~/.claude/plugins/cache/melodic-software/<plugin>/<version>/) as a source-of-truth proxy, since the cache mirrors the shipped skill content.

It worked for behavioral-contract planning, but it sharpens the gap this issue raises:

• The cache is a version-pinned snapshot, not the repo's working tree — it can lag main, and it carries no un-released changes. A redundancy or out-of-scope-ledger check run against it would silently reflect the installed version, not the target repo's HEAD.
• The docs/out-of-scope/ ledger and step-1 codebase-redundancy search are not in the plugin cache at all (only skill dirs are), so those step-1 checks remained impossible without a clone or a remote fetch.

Reinforces remediation option (b): a remote-repo mode should resolve the codebase/ledger checks against a fetched target-repo tree at the correct ref, not an ambient cache or the operator's improvised clone.

[kyle-sexton]

This was generated by AI (needs-human decision-brief pass).

Decision brief (2-minute read)

Problem. The work-items triage/work lanes assume they run inside a resolvable project checkout, but two entry states break silently: a no-checkout (remote-only) invocation, and — per the maintainer comment on this issue — an unbound checkout (a git top-level exists but no .work-item-tracker.json). In both, role-label resolution falls back to defaults silently and the codebase / out-of-scope-ledger checks have no working tree.

Today. Verified on main:

• plugins/work-items/reference/tracker-seam.md:29 names exactly two required entry presence checks (jq + the dispatcher script); binding presence is not one of them. :82 and :101 document role-label resolution falling back to defaults (agent-ready / needs-human / recurring) when .work-item-tracker.json or the config.role_labels entry is absent — silently, no warning.
• plugins/work-items/skills/work/SKILL.md:43,65-66,78,91,134 resolve the tracker + role labels via ${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel)} with no stop-and-remediate when neither resolves, and read config.role_labels "using recurring only when the file or entry is absent" — the same silent default.
• This repo itself has no .work-item-tracker.json (it develops the plugin, it is not a bound consumer), so the maintainer's "unbound checkout" case is reproducible here today.

Options.

1. RECOMMENDED — Add binding-presence as a third entry invariant that stops loudly, and make the role-default fallback an explicit warning. Mirror the existing jq/dispatcher presence checks: before the first verb, if there is no resolvable project context (CLAUDE_PROJECT_DIR / git-toplevel absent) OR no .work-item-tracker.json binding, stop with a clear remediation (run /work-items:setup / bind the provider). When roles do resolve from defaults because the file is absent, emit a loud warning rather than proceeding silently. Reversible: additive guard, removable if a remote mode later supersedes it. Aligns with operator precedents — discover conventions via setup, never pre-prescribe (planning: branch-name grammar hardcoded to Conventional Commits types, no consumer seam #415); context/permission degradations must surface loudly to the human (source-control:babysit-prs: safety.md's 'never retry a harness permission denial' rule doesn't match auto-mode classifier's actual (retriable) behavior #455); and work-items(work): per-issue execution should compose installed skills as a role-separated mini-SDLC (implementer ≠ reviewer ≠ verifier, ephemeral fresh-context agents) #513's convention-gap protocol (surface, never invent-and-proceed). The silent role-default is a real correctness risk: a repo that remapped config.role_labels is queried under the wrong strings with no signal.
2. First-class remote / no-checkout mode. Define a mode where binding + codebase / out-of-scope / redundancy checks resolve against a fetched target-repo tree at the correct ref (shallow clone or gh api contents) — not the operator's improvised clone or the version-lagged plugin cache, both workarounds the reporter had to use. Reversible but larger: a new resolution path + ref-selection semantics across triage/work/track/decompose. Best deferred with a trigger: someone actually needs unattended remote-only triage/work at scale.

Cross-links. #513 (operator item 4 — convention-gap protocol; its dispatched subagents also need a resolvable project context, reinforcing the guard). #455 (denials/degradations surface loudly). #415 (discover conventions via setup, never pre-prescribe).

Decision asked: Adopt Option 1 (loud binding-presence guard + loud role-default warning) now and defer Option 2 (remote mode) with a trigger, or commit to building the remote mode as the primary fix?

[kyle-sexton]

Operator decision (2026-07-19, decision-session final batch; relayed). ACCEPTED — the brief's RECOMMENDED option verbatim: binding-presence becomes a third loud entry invariant (stop-and-remediate, per the #455 loud-surfacing precedent); the silent role-default fallback becomes a loud warning; full remote-repo mode deferred with recorded trigger. Re-intake: removing needs-human, adding priority: needs-triage.