planning: wayfind hardcodes GitHub Issues/gh as the only tracker backend, bypassing the work-item-tracker seam

[kyle-sexton]

Plugin: planning · Categories: hardcoded opinion (1), missing externalization (2), side-effect surface (3)
Source: work-readiness sweep (read-only audit vs docs/PLUGIN-PHILOSOPHY.md + docs/MIGRATION-PLAYBOOK.md)

Findings

• plugins/planning/skills/wayfind/SKILL.md:7-11 — allowed-tools lists only gh reads (gh issue list*, gh issue view*, gh api user*, gh label list*); :16-17 pre-computed gh api user / gh issue list
• plugins/planning/skills/wayfind/context/tracker-mechanics.md:1-4,31-141 — entire mechanics are direct gh; :3 "operates the map through the GitHub Issues backend directly"
• plugins/planning/skills/plan/context/plan-template.md:300-325 — tracker-write phase template hardcodes gh issue list/create/comment

Why it breaks agnosticism

MIGRATION-PLAYBOOK's persistence/external-integration section mandates backend-neutral work-item vocabulary and a swappable backend seam. The sibling /work-items:track binds a work-item-tracker seam (referenced by questionnaire.md:42, devils-advocate.md:167), but wayfind re-implements GitHub-direct. A consumer on Jira/Azure DevOps/GitLab cannot use wayfind at all; GitHub is presented as universal, and gh is an undeclared hard prerequisite in plugin-form terms.

Fix direction

Route wayfind's tracker reads/writes through the same work-item-tracker seam /work-items binds. If GitHub-native is intentional, declare gh + GitHub Issues as a stated prerequisite per PLUGIN-PHILOSOPHY "Prerequisites and failure behavior" and expose the backend as a documented seam rather than an assumption.

[kyle-sexton]

This was generated by AI during triage.

Triage → needs-human. Decide as a set with #417 and #418 (wayfind/plan tracker cluster). Load-bearing decision: route wayfind through the work-item-tracker seam that /work-items binds vs. declare gh/GitHub Issues as a stated prerequisite per PLUGIN-PHILOSOPHY. That choice drives #417 (consume-only kill-switch) and #418 (fold plan close-out under the same seam+gate). Architectural scope. Priority: high.

[kyle-sexton]

Maintainer decision (2026-07-19, batch-approved; relayed by planning session). Decision carrier for the tracker-seam boundary cluster (#416, #418, context #379).

1. Planning routes through the work-item-tracker seam — wayfind and plan call the seam dispatcher for tracker reads AND writes. Basis: the seam's CONTRACT.md already names wayfind maps as its canonical work-map container; declaring planning GitHub-native would repudiate that shipped design.
2. Wayfind chart-mode is declared writable-backend-only in the skill contract. The local-markdown-hybrid (chart locally while reading a read-only backend) is DEFERRED with trigger: someone actually needs charting against a consume-only backend.
3. No new tracker-write userConfig gate. Two axes, one mechanism each: backend capability = the seam's existing exit-6 gate; user posture = the canonical outward_write_mode key decided on source-control: no read/consume-only posture — "safe" babysit tier and pull-request monitor write to GitHub autonomously #440. Do not build a third.

[kyle-sexton]

This was generated by AI during triage. · Category: hardcoded opinion / missing externalization / side-effect · Priority: priority: high (week north-star: backend-agnostic work-readiness). Routed status: ready.

Route wayfind (and plan's tracker-write phases) through the work-item-tracker seam

/planning:wayfind operates its decision map by hand-rolling gh/GitHub Issues directly, and /planning:plan's tracker-write phases emit gh issue create inline. Both bypass the work-item-tracker seam that all five sibling /work-items skills already bind. This is drift, not design: wayfind's own tracker-mechanics still claims it mirrors "the same idiom as the sibling /work-items skill" — but the sibling has since moved entirely onto the seam, leaving wayfind the lone holdout still speaking gh.

The architectural case is not "add a new integration" — it is "adopt the one the seam was already built to serve." The seam contract is titled provider-neutral, its direction is locked by ADR 0022, and its Containers and state section explicitly names wayfind maps carrying the work-map label as a first-class container use case. The seam already reserves wayfind's exact model; wayfind simply never picked it up. Declaring gh a permanent prerequisite would contradict a contract that already anticipates this skill by name.

Operation → seam-path mapping

Coordination — maps directly onto seam verbs (a clean win; deletes hand-rolled machinery):

wayfind operation	Seam verb
Create the map (container)	create-item with the work-map label
Create a typed decision item as a sub-issue	create-item with --parent (+ --blocked-by, type label)
Wire a dependency edge	link-blocks
Pre-check assignees + claim-comment-order collision check	claim (assignee + lease, race-safe, same-identity aware)
Back off on a lost claim (delete comment / unassign)	handled inside claim's back-off (supersede own lease, exit conflict)
Session-start reclaim of stale in-progress items	reclaim
Single-item fetch	get-item

Routing claim through the seam retires wayfind's bespoke claim-comment-order lease outright — the seam claim verb is that protocol's productized, conformance-tested form. This is a net deletion of duplicated coordination logic, not new surface.

Provider mechanics — route through the bound adapter's operations reference (the seam's designed answer for these; NOT gaps):

• Resolution comment and map-closure comment
• Closing a decision item / closing the map
• Materializing mode (needs-human label edit) — or fold into create-item labels at creation
• Current-user login for the pre-computed context header
• Taxonomy-presence check for wayfind's own map labels (work-map, wayfind: *, needs-human)

These already belong on the adapter path by the seam's own division of labor (comments, close, label edits, filtered reads are provider-specific). Framing them as unmet needs would be wrong — the seam explicitly delegates them.

Scope and the one structural gap

Structural gap (needs a seam-owner decision — new verb or verb extension, ADR-0022 territory): map-scoped frontier + container-children enumeration.

• list-frontier is repo-global, and its list rows drop parent linkage (the GitHub list surface omits it), so wayfind cannot core-side-filter the frontier down to one map's sub-items.
• Worse, an unassigned, unblocked container passes the frontier filter and would surface itself.
• Wayfind also needs to enumerate a map's closed children for its Decisions-so-far invariant check — no current verb returns a container's child set (get-item gives parent, not children).

Candidate shapes for the seam owner to weigh (do not design here): a --parent scoping flag on list-frontier, or a list-sub-items <container> verb. This is the seam owner's call, not wayfind's. [Triage note: filed as a distinct seam-enhancement issue — see the self-observation link in comments; it affects any container-based seam consumer, not only wayfind.]

Cross-plugin seam-location concern (scope/risk, not a blocker): the seam ships with the work-items plugin; the planning plugin ships no copy. So the plugin-dir-canonical resolution won't locate the seam from wayfind's plugin root, leaving only the consumer-vendored fallback. Routing wayfind through the seam therefore requires a way for the planning plugin to resolve the work-items-owned seam (a declared plugin dependency, or a shared/agreed location). Solvable — must be named in the plan, not left implicit.

Map-body writes (Decisions-so-far index, Not-yet-specified prose) stay wayfind-specific edits on the adapter path — they are map anatomy, orthogonal to the seam's item model.

Coupling to the consume-only decision (#440)

• Orthogonal in principle: whatever tracker operations wayfind performs should resolve through the seam binding, regardless of whether writes are suppressed. Seam-routing is correct either way.
• Coupled in scope: if source-control: no read/consume-only posture — "safe" babysit tier and pull-request monitor write to GitHub autonomously #440 lands consume-only, every write-side row above (create, claim, link-blocks, reclaim, close, comment) collapses out, leaving only the read-side structural gap. If it does not, wayfind needs the full write set through the seam. Sequence source-control: no read/consume-only posture — "safe" babysit tier and pull-request monitor write to GitHub autonomously #440 first so this plan's scope is known before implementation.

Acceptance criteria

• Wayfind and plan resolve all tracker reads and writes through the seam binding — no inline provider commands remain in the skill cores; coordination goes through seam verbs, provider mechanics through the bound adapter's operations reference.
• A non-GitHub backend (Jira / Azure DevOps / GitLab, or the offline reference adapter) can drive wayfind end-to-end without editing plugin source — only the repo's tracker binding changes.
• Wayfind's hand-rolled claim-comment-order lease is removed in favor of the seam claim verb.
• Any operation that must stay GitHub-specific is declared as an adapter capability (surfaced through the capabilities manifest / operations reference), never silently assumed by the skill core.
• The map-scoped-frontier gap is resolved by an agreed seam verb or extension owned by the seam, not worked around inside wayfind.
• The cross-plugin seam-resolution path (planning → work-items-owned seam) is decided and documented.

Decision defaulted: route wayfind + plan tracker reads/writes through the work-item-tracker seam (per the repo's MIGRATION-PLAYBOOK backend-neutrality mandate + the seam CONTRACT / ADR-0022), rather than declaring gh/GitHub Issues a permanent prerequisite — veto before merge