Assemble the implementation-ready spec

[mayfieldiv]

Part of #104

Question

Compile every decision on this map into a single implementation-ready spec in the legit repo (structure, seams, data model, UI behavior, config), sliced into implementation issues an agent session can pick up cold. This closes the map.

[mayfieldiv]

Resolution: the spec

Implementation-ready spec compiled from wayfinder map
#104 (tickets #105–#111).
Every decision here was settled on the map; this comment restates them in
implementation order and slices them into issues. This comment is the
spec's canonical home — deliberately not a repo file. Full research
evidence lives on local branches: research/github-subissues-dependencies
and research/local-dialects (each holding one doc under
docs/research/); their load-bearing findings are summarized in #105/#106
and inlined below where implementation depends on them.

Destination. A read-only ticket queue toggled from the PR view (t)
across Tracked Repos + cwd, reading both GitHub-tracked and local wayfinder
maps, filterable AFK/HITL, with a detail page and one-key copy of a fixed
handoff prompt.

Non-negotiables (from the map's Notes):

• Read-only: the TUI never claims or resolves tickets.
• Tolerant parsing of all observed dialects; never amend wayfinder skill
  conventions or tracker docs to make parsing easier.
• Copy template (fixed, not configurable):
  <ticket title> | /wayfinder <map ref> - resolve <ticket ref>
  — title first so an agent harness derives a session name.
• Vocabulary is CONTEXT.md's (### Wayfinder tickets section): Effort, Map,
  Destination, Ticket, Type, Mode, Claim, Dependency, External/Unknown
  Dependency, Blocks, Frontier, Fetch Unit, Main Worktree, Wayfinder Root.
  "Frontier" in every label and count — never "takeable".

Out of scope for the whole effort: interleaving tickets into the PR
list; prompt-template customization; any TUI write action; GitLab; amending
wayfinder conventions. Ticket↔PR links are a separate effort
(#114). GHES is not
targeted: the body-line fallback dialect is detected and degrades visibly
(§4.4) but is not parsed into the model in v1.

---

1. Domain model

Already landed: CONTEXT.md's ### Wayfinder tickets glossary, the
Relationships lines, and the Fetch Unit / Refresh / Fetch Priority /
Focused PR / Fetch Age extensions — merged to main via PR #113
(merge commit 620c3a8). Implementation types mirror it:

• Effort = one Map + its Tickets, belonging to exactly one Tracked
  Repo. GitHub-vs-local is an attribute (enum EffortSource { GitHub, Local }),
  not a different container type.
• Ticket lifecycle is two orthogonal axes: Open/Closed plus Claim
  (Option<String>). Blocked-ness is always derived, never stored.
• Type is an open string (unknown values shown verbatim); Mode is
  derived from Type, never stored: research → AFK; prototype,
  grilling → HITL; task and unknown → Either.
• Dependency targets are ticket refs that may be same-effort, external
  (another Effort), or unknown (target can't be found or read). A Ticket
  with any open or Unknown Dependency is off the Frontier.
• Frontier = open + unclaimed + every Dependency target closed + no
  Unknown Dependency.

Identity: a TicketKey (GitHub: repo slug + issue number; local:
canonical file path) and an EffortKey (GitHub: repo slug + map issue
number; local: canonical effort dir path). The limiter's affinity key
widens to carry Pr(PrKey) | Ticket(TicketKey) (§5.2).

2. Config extension (from #110)

2.1 Schema

A repos entry stays a bare "owner/repo" string or an object:

{
  "slug": "owner/repo",            // optional
  "mainWorktreePath": "~/code/x",  // optional; renames sourceClone
  "worktreeRoot": "…",             // rejected on slug-less entries
  "wayfinderRoots": ["docs/wayfinder", "/abs/path"]  // optional
}

• At least one of slug / mainWorktreePath required; both together is
  the normal case.
• sourceClone → mainWorktreePath is a hard rename, no alias.
  deny_unknown_fields stays on, so an old config fails with a precise
  one-line error naming the rename — that error is the migration path.
• Slug-less entries are local-only repos: no Repo Tab, no PR machinery;
  worktreeRoot on one is a validation error. Display name = basename of
  the expanded path; identity/dedup key = canonicalized path. No name
  field in v1.
• Paths: ~ expansion + relative-to-cwd at use time. Validation stays
  shape-only at load (non-empty, no control chars, field-combination
  rules) — no existence checks.
• wayfinderRoots replaces the built-in probe list for that repo,
  never extends it. Relative entries resolve against each probed worktree
  root; absolute entries allowed. Per-repo only — no global key.

2.2 Discovery semantics

• Built-in probe roots: docs/wayfinder/, .wayfinder/, .scratch/.
• Per repo: start at mainWorktreePath, fan out across
  git worktree list — probe every linked worktree, skip missing/prunable
  ones; a non-git base is probed alone.
• cwd: walk cwd → its git toplevel, probing each level (finds nested
  monorepo roots like apps/mac-agent/docs/wayfinder/). If the cwd repo
  matches a configured entry with wayfinderRoots, the explicit roots win.
• A root either is a single Effort (map.md directly inside — match the
  filename case-insensitively; MAP.md exists in the wild) or contains
  Effort subdirectories. Tolerate both shapes.
• Discovery source and Effort attribution are distinct steps; today
  attribution follows discovery as a default, not a definition (keeps the
  door open for a future cross-repo tracker without reserving any schema).

3. Local dialect parsing (from #106, #110 addendum)

Full inventory: local branch research/local-dialects,
docs/research/local-wayfinder-dialects.md. The parser
normalizes three observed layouts into the §1 model, tolerantly — parse
failures degrade per-Effort (§5.5), never crash, never silently drop.

3.1 Layouts

Layout	Marker	Tickets
Older (all real data)	map.md (may open with <!-- wayfinder:map -->)	tickets/NN-slug.md
Current docs	map.md	issues/NN-slug.md
Single-effort root	map.md/MAP.md directly at the wayfinder root	either dir name

Probe tickets/ and issues/ in both; an assets/ dir (effort-level or
nested under tickets/) is never tickets. Match map.md
case-insensitively.

3.2 Ticket fields

Older dialect — YAML frontmatter (----delimited):
status: open|closed, type:, assignee: (the claim; empty/missing =
unclaimed), blocked-by: [NN, …] (bare ints, same-effort),
external-blocked-by: (optional key; list of relative paths
../../<effort>/tickets/NN-slug.md — resolve against the ticket file's
dir; a path outside the effort is an External Dependency, an unreadable
one an Unknown Dependency).

Newer dialect — no frontmatter; leading prose lines: Status:
(claimed/resolved — no open/closed vocabulary), Type:,
Blocked by: NN, NN. Mapping: resolved → Closed; claimed → Open +
claimed (claimant unknown, render as claimed without a name); no Status:
line → Open + unclaimed. No external-dependency equivalent exists.

Normalization rules the corpus demands:

• closed covers both resolved and out-of-scope; no structural
  distinction — don't try to detect one.
• A populated assignee on an open ticket = claimed; presence of the key
  with no value = unclaimed.
• "Superseded" blockquotes, ## Closure vs ## Resolution vs
  ## Progress headings, handoff sections: all body prose. The
  status/Status field is the only lifecycle authority.
• Title = the H1 line, not the filename slug (slugs drift after rescopes).
  Ticket ref for display = the file slug (01-inventory), §6.2.
• Unknown Type strings pass through verbatim, Mode Either.

4. GitHub map reading (from #105)

Full findings: local branch research/github-subissues-dependencies,
docs/research/github-subissues-dependencies.md. Verified live
2026-08-10; both features GA and universally on at github.com.

4.1 Transport split

• Whole-map read → graphql.rs (the N+1 collapse that justified
  fetch_review_status): one query, measured cost 10 of 5,000 points/hr,
  flat in map size. first:100/first:50 are GitHub's hard relation
  caps, so hasNextPage can't be true — select pageInfo anyway.
  Verbatim (from the research doc §1d):

  query($owner:String!, $repo:String!, $label:String!) {
    rateLimit { cost remaining resetAt }
    repository(owner:$owner, name:$repo) {
      issues(first:10, labels:[$label], states:[OPEN]) {
        pageInfo { hasNextPage endCursor }
        nodes {
          number title state url body
          subIssuesSummary { total completed percentCompleted }
          subIssues(first:100) {
            pageInfo { hasNextPage endCursor }
            nodes {
              number title state stateReason url
              assignees(first:5) { nodes { login } }
              labels(first:10) { nodes { name } }
              issueDependenciesSummary { blockedBy blocking totalBlockedBy totalBlocking }
              blockedBy(first:50) {
                pageInfo { hasNextPage endCursor }
                nodes { number state title repository { nameWithOwner } }
              }
            }
          }
        }
      }
    }
  }

• Single-ticket refresh → rest.rs: GET /issues/{n} carries state,
  labels, assignee, both summaries, parent_issue_url. Comments via the
  existing list_issue_comments.

• Never call GET …/parent (404s when parentless; parent_issue_url on
  every payload already answers it). Every 404 stays a genuine error —
  including the token-without-Issues-read case, which surfaces as 404.

4.2 Blocked-ness derivation

Derive Frontier/blocked from the blockedBy list filtered on
state == OPEN, plus the Unknown-Dependency check — never from the
issueDependenciesSummary counter:

• The summary is eventually consistent (~10s after a close).
• The blockedBy list retains closed blockers; only the summary filters.
  So blockedBy.totalCount ≠ open-blocker count; filter per node.

One source of truth, and it's the one the detail page renders. A
blockedBy node whose repo ≠ the map's repo is an External Dependency;
read the repo from the payload, never assume.

4.3 Code placement

Addition	Where
Issue, IssueState, SubIssuesSummary, DependenciesSummary wire types	src/github/types.rs (after IssueComment) — not rest.rs; don't repeat the PR-in-rest.rs wart
TicketKey (or generalized key) beside PrKey	src/github/rest.rs:71-83; note PrKey::html_url() hardcodes /pull/, issues need /issues/
fetch_wayfinder_map	src/github/graphql.rs, modelled on fetch_review_status / fetch_review_threads; must impl GraphQlErrors or failures parse as empty successes
get_issue, list_issues_with_label	src/github/rest.rs beside list_issue_comments; get_all hardcodes per_page-only params — generalize it or pre-bake the query string
Parsers + fixture tests	permissive #[serde(default)] posture; pure parse_* functions tested against fixtures in rest/tests.rs / graphql/tests.rs
Dispatch	new Cmd variants in src/app/cmd.rs, routed through request(...) — limiting is opt-in exactly once, at that layer

Recorded decisions from the research's open questions: map reads stay
background (no interactive priority for them — §5.1), so the limiter never
needs to learn the GraphQL point budget (at cost 10 it never binds); GHES
out of scope.

4.4 Fallback dialect: detect and degrade

Native sub-issues/dependencies are the only parsed path in v1. If a map
issue has zero sub-issues but its body carries a task list, or a ticket
body opens with Part of #n / Blocked by: #n lines, surface a visible
per-Effort degradation notice (effort card renders an error line, §5.5)
rather than silently showing an empty Effort. Body-line parsing ships
when a real task-list map appears, not before. Where both exist, native
wins; a stale Part of line is advisory, never an error.

5. Fetch model (from #111)

The PR fetch design transposed, stated per Fetch Unit (a PR's
enrichment, or an Effort's ticket data — one GitHub map read or one local
probe) so nothing couples to effort shape.

5.1 Lanes

• Only GitHub HTTP acquires limiter permits. Local discovery (worktree
  enumeration, root probes, file reads) bypasses the limiter: one async
  task per Tracked Repo, streaming one Msg per Effort — the per-repo
  PR-listing idiom, not the permit machinery. NetworkStats stays
  HTTP-only.
• The per-repo map read is unit-wide work — affinity None, background
  lane, never promoted (the analog of the open-PR listing).
• Drill-in body+comments and any per-ticket fetch carry ticket affinity
  and ride Focus Promotion.
• No speculative per-row fetches on the ticket list: the map read already
  delivered everything the list and summary show; cursor movement is
  network-silent. Enter triggers the first per-ticket fetch.

5.2 Limiter widening (the one non-additive change)

Waiter affinity widens from Option<PrKey> to a small enum
(Pr(PrKey) | Ticket(TicketKey)); set_focus takes the same. Touches
limiter.rs (Waiter.pr, Inner.focused, is_interactive, acquire,
set_focus) and the runtime.rs call site, plus model.rs's focused-PR
plumbing. One focused entity globally; focus follows the active surface —
t demotes pending PR fetches, toggling back restores them.

5.3 r / R

• r = re-read the Fetch Unit backing the selected ticket (GitHub: one
  map read; local: re-probe). On the detail view, r additionally
  re-fetches the open ticket's body + comments (the REST path, §4.1).
• R = re-read every Fetch Unit in the current view scope (all efforts on
  "All efforts"; just the selected effort when the rail filters).
• No Re-list/Refresh split: one map read reconciles membership and
  enrichment together.
• Dedupe: a refreshing set keyed by Fetch Unit; re-press while in flight
  is a no-op for that unit. Indicator on the effort card and its queue
  rows; completion message "Refreshed N efforts".

5.4 Fetch Age

Stamped per Fetch Unit when its read settles; shown on the effort card
and the ticket detail header. No separate per-ticket stamp from drill-in.

5.5 Failures

• With stale data: PR precedent — 8s status-bar error, clear the unit from
  the refreshing set so retry re-dispatches, keep stale data with age
  counting.
• Startup failure (no stale data): the effort card renders an error line
  ("couldn't read — r to retry") and zero tickets — never silently
  missing. Covers the scope-shaped 404 (§4.1), local probe failures
  (unreadable dir, malformed map), and the fallback-dialect degradation
  (§4.4).

5.6 Initial load

Discovery probes + map reads dispatch eagerly at startup alongside the PR
fan-out, background lane, so t lands on data. No periodic refresh or
retry in v1 — manual r/R plus honest Fetch Age.

6. Ticket list surface (from #108)

Reference implementation: branch prototype/ticket-list-surface,
examples/ticket_list_prototype.rs (cargo run --example ticket_list_prototype) — the "Efforts pane" variant won.

6.1 Layout — three regions

• Effort rail (left, ~38 cols): All efforts entry + one card per
  Effort — repo-coloured repo · map name, github|local · N/M decided · N frontier, Destination line. Map-level context lives here.
• Queue (centre): flat cross-effort list grouped by takeability tiers
  — ── Frontier (green), ── Claimed (amber), ── Blocked (red —
  deliberately high-contrast). Unknown-dep tickets fold into Blocked, sort
  last, flagged with a red ⟨dep? <ref>⟩ marker. Within a tier: effort
  order, then ticket order.
• Summary panel (right, ~44 cols): ref + title, effort + destination,
  type · mode, state, age, waits on (↑) / blocks (↓) with target
  titles resolved (unreadable target renders red "can't find or read"),
  and the copy-prompt preview line p <string>.

6.2 Columns

Ticket | Repo | Type | Title | Block | Age — Repo second, matching the
PR list.

• No Mode column: the Type cell is coloured by mode (AFK blue, HITL
  magenta, Either muted).
• No State column: tier headers + title markers (⟨claimed X⟩,
  ⟨after Y⟩, ⟨dep? Z⟩) + summary carry state.
• Ticket refs: GitHub #NNN; local = file slug. Column sized to widest
  visible ref, capped at 14 chars with middle-ellipsis.
• Block column: red ↑N open upstream Dependencies, blue ↓N open
  downstream dependents.

6.3 Behaviour

• t toggles PR view ↔ ticket view.
• Repo Tabs (h/l) work unchanged and reset the effort filter.
• J/K moves the effort filter through the rail; j/k stays on
  tickets — no pane-focus mode.
• m cycles the mode filter all → AFK → HITL with a chip row; task +
  unknown Types show in both filtered views, visibly tagged.
• p copies the fixed handoff prompt; y copies the ticket URL (local:
  file path). (Design the ticket detail page #109 amended Design the ticket list surface #108's original y-copies-prompt.)
• Closed Tickets hidden entirely — only the N/M decided counts. A
  visibility toggle is a possible later addition, not v1.

6.4 Narrow widths (implementation latitude)

Rail + summary don't both fit below ~130 columns. Follow the PR list's
width-threshold pattern: summary panel drops first, then a State column
returns when tier grouping alone can't carry state. Exact thresholds and
collapse order are the implementer's call — this is the map's one
remaining fog item, deliberately delegated; match PR-list precedent and
verify in the real TUI.

7. Ticket detail page (from #109)

7.1 Navigation

Enter on a list row opens the detail. Dependency rows are focusable and
enterable: Enter drills into the target — including closed targets (the
only route to resolutions, since the list hides closed Tickets) and
External Dependencies. Unknown Dependencies are never enterable.
Dep-hopping pushes a nav stack; Esc pops one level; from the root detail,
Esc returns to the list.

7.2 Composition (top to bottom)

1. Header: ref + title; repo-coloured effort name + Destination
   one-liner (all the map context v1 shows — no map detail page);
   type · mode coloured as in the list; state line in tier vocabulary
   (Frontier / claimed by X / blocked / closed); Fetch Age; claim.
2. Body card: the ticket body as a markdown Card (local closed tickets
   naturally include ## Resolution — no structural extraction).
3. Dependencies: waits on (↑) shows all targets — open red,
   closed muted ✓, Unknown red "<raw ref> — can't find or read".
   blocks (↓) shows open dependents only, blue. External Dependencies
   carry a repo-coloured effort qualifier.
4. Comments (GitHub Efforts only): all issue comments as Cards,
   chronological, no resolution-comment detection — by convention the
   resolution is the trailing comment.

7.3 Keys

• Enter is contextual: focused card → toggle its Details Groups; focused
  dependency row → drill in.
• p = copy handoff prompt; y = copy ticket URL / file path; o =
  open GitHub URL (no-op local); b = hide bot comments (shared app-level
  preference); r per §5.3. t is unbound here (no surface-jump that
  would discard the nav stack).

7.4 Machinery

• Reuse verbatim: markdown pipeline, push_card framing,
  DetailFocus algebra, URL-keyed parse-once body cache, section_intro,
  comment_byline, collapse_body, panel_width.
• Sibling modules, not generalization: a third ViewMode variant
  holding TicketDetailState (same fields as DetailState, ticket key +
  nav stack instead of PrKey); ticket_detail_items.rs with the flatter
  sequence Body → dependency rows → comments; ticket_detail_content
  building cards through the shared machinery. DetailItems stays
  PR-shaped.
• normalize_detail refactored entity-agnostic —
  (scroll, focus, followed, content, viewport) — so both detail views
  share the scroll/focus algorithm.
• Drill-in lazily fetches body + comments, like PR Detail (§5.1).

---

8. Implementation slicing

Eight issues. Each is one agent session, references the spec sections it
implements, and lands independently green (tests + cargo fmt/clippy).
Dependency edges are the build order (wired natively on the issues);
issues without an edge between them can run in parallel. AGENTS.md rules
apply throughout (manual TUI testing via herdr/tmux; never post to GitHub
without approval).

#	Issue	Spec	Blocked by
1	#115 Config: mainWorktreePath rename, slug-less repos, wayfinderRoots	§2.1	—
2	#116 Ticket domain types, keys, and derivations	§1	—
3	#117 GitHub transport: whole-map GraphQL read + single-ticket REST refresh	§4	2
4	#118 Local Effort discovery and dialect parser	§2.2, §3	1, 2
5	#119 Widen the limiter's affinity key to PRs and Tickets	§5.2	2
6	#120 Fetch integration: efforts and tickets through the runtime	§5 (minus 5.2)	3, 4, 5
7	#121 Ticket list surface	§6	6
8	#122 Ticket detail page	§7	7

#115 and #116 are labelled ready-for-agent; label the rest as their
dependencies close.

Map bookkeeping

The map's one remaining fog item (responsive collapse at narrow widths) is
delegated to #121 as implementation latitude per §6.4 rather than ticketed
— it is a width-threshold detail with PR-list precedent, not a decision
the map needs to hold. With that, nothing is left to decide and the map
closes.