work-items: tracker seam has no container-scoped frontier or child-enumeration verb — containers surface themselves on the global frontier

[kyle-sexton]

Lane: triage · Category: bug (correctness) + improvement (missing verb) · Source: surfaced by the #416 planning pass (route wayfind through the work-item-tracker seam)

Triggering example

Planning #416 (route planning:wayfind through the work-item-tracker seam) mapped wayfind's operations onto seam verbs. Coordination mapped cleanly (create-item, claim, link-blocks, reclaim, get-item) EXCEPT one structural gap that no current verb covers: enumerating the frontier scoped to a single container (map), and enumerating a container's children.

Wayfind operates a decision map — a container item (carrying the work-map label) with typed decision sub-items. To drive it through the seam it must (a) list the unblocked, unassigned frontier within one map, and (b) enumerate a map's closed children for its "Decisions-so-far" invariant check.

Observed vs expected

• Observed:
  1. list-frontier is repo-global — there is no --parent/container scope, so a consumer cannot core-side-filter the frontier down to one container's sub-items.
  2. The frontier list rows drop parent linkage (the GitHub list surface omits it), so a consumer cannot even post-filter by parent from the returned rows.
  3. A container surfaces itself: an unassigned, unblocked container item passes the frontier filter and appears as its own frontier item — a correctness wart for any container-based consumer, not only wayfind.
  4. No child-enumeration verb: get-item returns an item's parent, but nothing returns a container's child set, so the closed-children invariant check has no seam path.
• Expected: the seam offers a container-scoped frontier and a child enumeration, and excludes container items from their own frontier. Candidate shapes (design owned by the seam, ADR-0022 territory — NOT prescribed here): a --parent <container> scoping flag on list-frontier, and/or a list-sub-items <container> verb; plus a rule that a container is never its own frontier item.

Why it matters beyond wayfind

Any container/parent-child consumer of the seam hits this — the seam's own CONTRACT reserves work-map containers as a first-class use case, but the read side to operate one within scope is missing. This gap blocks #416's clean implementation (it would otherwise be worked around inside wayfind, which the plan explicitly rejects as the seam owner's call).

Note

Distinct from #416 (wayfind routing — the consumer) and #379 (Jira adapter — a different backend). This is the seam's own read-verb coverage for containers. Owner: work-items plugin (seam CONTRACT + adapters).

[kyle-sexton]

This was generated by AI during triage. · Category: bug (correctness) + improvement (missing verb) · Priority: priority: high (work-items seam is pipeline infra; blocks #416's clean implementation). Routed needs-human + wayfind: design.

Why needs-human

The item splits into a trivial correctness fix and a genuine seam-API design decision:

• Correctness (clear): a container item should not surface itself on its own frontier — a bounded fix.
• Design (open, needs a human): adding a container-scoped frontier and a child-enumeration capability to the seam is new public API surface on the work-item-tracker CONTRACT — ADR-0022 territory. The candidate shapes (a --parent <container> scoping flag on list-frontier vs a new list-sub-items <container> verb; how the GitHub adapter and any future adapter realize it; whether list rows must carry parent linkage) are a seam-owner API decision, not a maintainer-vetoable default. New cross-backend verb semantics must be designed deliberately, not defaulted.

What the human/seam-owner decides

The verb shape (scoping flag vs new verb), its cross-adapter contract, and whether frontier rows must expose parent linkage — then the container-self-exclusion correctness fix rides along.

Dependency

Blocks the clean implementation of #416 (route wayfind through the seam), which needs exactly this read-side capability and explicitly declined to work around it inside wayfind. Owner: work-items plugin (seam CONTRACT + adapters).

[kyle-sexton]

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

Decision brief (2-minute read)

Builds on the triage note above (which named the correctness fix vs. the open API decision) — this adds the verified seam state and a starting proposal for the verb shape. The verb decision is the seam owner's call, not a maintainer-vetoable default.

Problem. The tracker seam's read side can't operate a container within scope: there is no way to list one map's frontier or enumerate a container's children, and an unblocked/unassigned container surfaces itself on the global frontier. This blocks #416 (route wayfind through the seam), which needs exactly this read capability and declined to work around it in the consumer.

Today (verified in plugins/work-items/tools/work-item-tracker/):

• Core public verbs (CONTRACT.md:47-55): create-item, get-item, claim, renew-lease, reclaim, link-blocks, add-sub-item, list-frontier, capabilities. There is a write verb for the parent/child edge (add-sub-item) and sub_items: true is a declared capability (CONTRACT.md:232), but no read/enumerate counterpart.
• list-frontier is repo-global — a CORE-side derivation over the adapter's list-items, filtered state==open AND blocked_by_count==0 AND no assignee (CONTRACT.md:54,58-62). No --parent scope.
• Bulk list-items rows drop parent linkage: GitHub's list surface omits it, so rows carry parent_id: null; get-item is the only authoritative source for parent (CONTRACT.md:138-140). So the frontier cannot be post-filtered by parent from returned rows.
• Containers are work-map-labeled ordinary items and are never claimable by workers, yet "frontier machinery is label-agnostic and simply never surfaces items that are assigned or blocked" (CONTRACT.md:219-223) — nothing excludes a container itself, so an idle top-level map appears as its own frontier item.

All four defects in the issue are confirmed accurate against the CONTRACT.

Options (verb shape — realizes the container-scoped read; correctness fix rides along in all):

• Option A — one new enumerate verb list-sub-items <container> [--state open|closed|all]; derive container-scoped frontier core-side by composing it with the existing frontier filter. RECOMMENDED. Enumeration is the missing half of an edge whose write half (add-sub-item) already ships — so this closes a known asymmetry, not new invented surface. Querying children directly by container sidesteps the parent_id: null constraint above (no need to teach every adapter's hot list-items path to carry parent linkage), and the same primitive serves both needs: frontier-within-map (compose + filter open/unblocked/unassigned) and the closed-children invariant (--state closed). Reversibility: high — additive verb; the derived --parent flag on list-frontier is additive; realize per provider via its native sub-item enumeration where offered, core-side fallback otherwise.
• Option B — add only list-frontier --parent <container>, realized by making adapters populate parent_id in bulk list-items rows. Avoids a new verb, but taxes the hot list path on every provider (GitHub would need extra per-item fetches or a GraphQL change) and still leaves the closed-children invariant with no path (frontier is open-only). Rejected: partial coverage at higher cost.
• Option C — two distinct verbs (list-sub-items + a separate native list-frontier --parent). More surface than A for the same capability; A already yields scoped frontier by composing one primitive. Justified only if a provider gains a native "unblocked children" query worth exposing directly (none does today).

Correctness fix (all options): exclude work-map-labeled items from list-frontier output — grounded in the existing "containers are never claimable by workers" rule (CONTRACT.md:221), so it is a bounded, principled behavior change rather than a special case.

Cross-links.

• planning: wayfind hardcodes GitHub Issues/gh as the only tracker backend, bypassing the work-item-tracker seam #416 — the blocked consumer (route wayfind through the seam); this is its missing read-side capability. It is the tracker-seam carrier that constrains this issue.
• Seam-API design — the triage flags this as ADR-0022 territory; the new verb's cross-adapter contract (and whether frontier rows must expose parent linkage) is the seam owner's decision to record there.
• Distinct from feat(work-items): Jira adapter for the work-item-tracker seam #379 (Jira adapter — different backend), as the triage already noted.

[kyle-sexton]

Decision brief (2-minute read)

Problem. The tracker seam's frontier is repo-global with no container scope, and there is no verb to enumerate a container's children — so a work-map container even surfaces itself as a workable frontier item. This blocks routing wayfind (#416, already decided to go through the seam) and any parent-child consumer.

Today. Verified against the checkout at 789ec6c:

• list-frontier [--autonomous] [--repo] is a CORE-side derivation over the adapter's list-items, filtering state==open ∧ blocked_by_count==0 ∧ unassigned (tools/work-item-tracker/CONTRACT.md:54-60, lib/frontier.sh wit_filter_frontier). No --parent scope exists — the frontier is repo-global.
• The GitHub adapter's list-items rows carry parent_id: null — the provider's list surface omits parent data; get-item is authoritative for linkage (CONTRACT.md:138-140). So a consumer cannot even post-filter the frontier by parent.
• Frontier machinery is "label-agnostic" and excludes only assigned/blocked items (CONTRACT.md:217-222), so an open, unblocked, unassigned work-map container passes the filter and appears as its own frontier item.
• No child-enumeration verb exists. The core verb set is create-item / get-item / claim / renew-lease / reclaim / link-blocks / add-sub-item / list-frontier(+list-items at the adapter) / capabilities. add-sub-item (a write) already proves GitHub's sub-issue API is wired, but there is no read counterpart; get-item returns a child's parent, never a parent's children.

Options. The issue explicitly leaves the verb shape to the seam owner; you are that owner, so this recommends a shape for ratification, not a default.

• RECOMMENDED — one new core read verb list-sub-items <container> (returns normalized child rows: state, assignees, blocked_by_count, labels), plus exclude work-map-labeled items from wit_filter_frontier. Core derives BOTH of work-items: tracker seam has no container-scoped frontier or child-enumeration verb — containers surface themselves on the global frontier #498's reads from the one verb: the container-scoped frontier by reusing the existing wit_filter_frontier over the children, and the closed-children invariant by filtering state==closed. Clears all four observed problems: repo-global frontier → scoped read; rows-drop-parent-linkage → made moot (a direct parent→children query needs no post-filter); container-self-surface → the work-map exclusion (a deliberate change to the currently label-agnostic filter, CONTRACT.md:222 — small but a real contract-semantics change, not a no-op); no child verb → this is it. Tie-breaker: because GitHub's list-items returns parent_id: null, a core-side --parent filter is NOT derivable without changing list-items — whereas a direct children query matches the native GitHub sub-issue API add-sub-item already uses. Reversibility: fully additive and back-compat — the capabilities manifest gates it, unsupported adapters exit-6 (matches planning: wayfind hardcodes GitHub Issues/gh as the only tracker backend, bypassing the work-item-tracker seam #416's "capability = the exit-6 gate, don't add a new mechanism"). Fits feat(work-items): Jira adapter for the work-item-tracker seam #379: it is a READ verb, squarely inside Jira's already-approved read/resolve scope; adapter cost is one script each (github sub-issue list, local-markdown children, future jira parent= JQL). Future risk: direct-children only — a future deep-descendant need would want --recursive or repeated calls (depth ≤ 8 per limits); record as deferred.
• --parent <container> flag on list-frontier (no closed-children verb). Smaller surface, but (a) leaves the closed-children invariant work-items: tracker seam has no container-scoped frontier or child-enumeration verb — containers surface themselves on the global frontier #498 also needs unsolved, and (b) is NOT cheaply core-derivable anyway — GitHub's list rows drop parent_id, so it still forces an adapter change, at similar cost to a verb with worse ergonomics (global scan filtered down vs a direct query). Solves half the problem.
• Correctness-fix-only now, defer the read verbs. Ship just the work-map frontier exclusion to kill the self-surface wart immediately, defer container-scoped reads. Fast partial, but planning: wayfind hardcodes GitHub Issues/gh as the only tracker backend, bypassing the work-item-tracker seam #416 is already decided to route wayfind through the seam and needs the scoped reads on the critical path — deferral re-blocks it.

Related.

• planning: wayfind hardcodes GitHub Issues/gh as the only tracker backend, bypassing the work-item-tracker seam #416 — tracker-seam carrier; decided to route wayfind/plan through the seam; its exit-6 capability-gate ruling is the pattern any new verb follows.
• feat(work-items): Jira adapter for the work-item-tracker seam #379 — Jira adapter, scoped to read/resolve; a new READ verb fits that scope and bounds cross-adapter cost.
• work-items(triage): pre-planning enrichment path — attach explore/research/plan/design artifacts to issues before the human decision point #515 — pre-planning enrichment; a downstream consumer that would also read container-scoped children.
• The self-exclusion correctness fix rides along with whichever option ships.

[kyle-sexton]

Operator decision (2026-07-19, decision-session batch 2; relayed).

ACCEPTED — the decision brief's RECOMMENDED option verbatim.

Re-intake: removing needs-human, adding priority: needs-triage for routing.

[kyle-sexton]

This was generated by AI during triage.

T3 — needs-human. Issue explicitly frames the seam-verb shape as "ADR-0022 territory — NOT prescribed here" with candidate shapes offered but not decided (container-scoped --parent flag on list-frontier vs a separate list-sub-items verb, plus the self-listing correctness fix). Genuine open seam-architecture design space owned by the work-items plugin maintainer — not a single defaultable fork.

Blocks other work: this issue blocks #416's clean implementation (per its own "Why it matters" section). Rule 5a applies: priority: high + native blocked by dependency recorded on #416 so the blocked state stays machine-visible.