feat(planning): wayfind absorbs the wayfinder decisions and accept list

.changes/planning/work-resolve-issue-issue-12477-41523574219-1-ef8a5f4e.md

@@ -0,0 +1,12 @@
+---
+bump: minor
+---
+
+### Added
+
+- `wayfind`: two settings in `docs/conventions/planning.yaml`. `wayfind_research_start` (default `auto`) starts a research item without asking when only research is on the frontier, and asks first otherwise. `wayfind_hitl_concurrency` (default `1`) caps how many `needs-human` items of one map can be claimed at once across sessions. Both are in the schema and in `reference/config.md` (#12477).
+- `wayfind`: shared work files go on one dossier branch per map. The map's Notes link it, and it is deleted when the map closes (#12477).
+
+### Changed
+
+- `wayfind`: absorbs the owner-approved parts of Matt Pocock's wayfinder (#12477). Interview is the entry. Chart reads an existing interview ledger; with none, it offers the interview preloaded and runs it inline. The user confirms the destination before any item exists. Items are created first, and their edges and cross-references are written in a second pass with real ids and absolute URLs. A bare run proposes `chart` and waits. `work` takes an optional item and defaults to the first frontier item in creation order. It reads the map body and child list, opening an item's body only when needed, and consults the skills the map's Notes list. `needs-human` marks only items that need the user's intent or vision, whatever their type. No Notes line overrides "plan, don't do". The map closes to `/planning:prd`, `/work-items:decompose` or `/work-items:work`, or to a decision record or general summary, and the destination skill reads Decisions-so-far and the resolution comments. The `wayfind-closed-plan-destination` case now expects `/work-items:decompose`.

plugins/planning/README.md

@@ -2,15 +2,15 @@
 
 A Claude Code plugin for the **pre-implementation planning pipeline**: everything
 between a rough idea and approved, executable work. Eleven pipeline skills covering
-charting a too-big, foggy effort as a decision map, divergence, product intent, the
+charting a too-big, foggy effort as a map of decision items, divergence, product intent, the
 engineering contract, contract validation, hand-off of a decision another person
 holds, goal authoring, design exploration, the design→plan gate, adversarial review,
 and the implementation plan itself, plus a re-runnable `setup` action that settles
 where artifacts land in the consuming repo.
 
 | Skill | Stage | What it does |
 |---|---|---|
-| `/planning:wayfind` | Chart | Charts a too-big-AND-foggy effort as a shared decision map on the work-item tracker, then works its frontier one decision at a time, routing each to the right skill until the fog clears and a Brief / PRD / PLAN can be handed onward. An escalation from an interview that outgrew one session, never the first step. |
+| `/planning:wayfind` | Chart | Charts a too-big-AND-foggy effort as a shared map of decision items on the work-item tracker, then works its frontier one decision at a time, routing each to the right skill until the fog clears and the map closes to `/planning:prd`, `/work-items:decompose` or `/work-items:work`. An escalation from an interview that outgrew one session, never the first step. |
 | `/planning:brainstorm` | Diverge | Turns a rough problem into codebase-grounded candidate approaches ordered cheapest→most ambitious; the user reacts, then work routes onward scoped. |
 | `/planning:prd` | Product intent | Produces a Product Requirements Document (problem, users, success metrics) in three tiers (one-pager, consumer-feature, B2B-internal) with a synthesize path and a review mode. Acceptance-criteria capture asks once about missing unwanted-behavior and state-driven cases (skipped and reported unexamined on the `synthesize` path). |
 | `/planning:interview` | Engineering contract | Locks a task contract (goal, constraints, acceptance criteria, named assumptions) into a PLAN.md Brief, synthesizing when intent is clear, running frontier-rounds Q&A when it isn't, or interviewing relentlessly on request. Acceptance-criteria capture asks once about missing unwanted-behavior and state-driven cases, and emits EARS-tagged criteria when the team's convention selects that format. The `surface` option can render rounds on a local page the session watches. The `product` action interviews a product idea against product principles and ends in a verdict. |

plugins/planning/evals/wayfind-closed-plan-destination/graders/names-decompose-step.md

@@ -0,0 +1,6 @@
+---
+type: regex
+pattern: '(?:^|[.!?;,\n—–]\s*)(?:(?!\b(?:not|never|skip|instead of|rather than|unless)\b|n''t\b|\bno need\b)[^.!?;,\n—–])*?(?:/?work-items:decompose\b|\bdecompose (?:it|the (?:map|plan|decisions|destination)) into\b)'
+flags: i
+arm: both
+---

plugins/planning/evals/wayfind-closed-plan-destination/prompt.md

@@ -1,11 +1,11 @@
 ---
-description: "Contract case for the wayfind map-closure hand-off when the decision map is closed, the frontier holds no item and the destination is a PLAN. Why hard: the reflex is to restart charting, or to go back to an interview, instead of handing the destination to the planning step."
+description: "Contract case for the wayfind map-closure hand-off when the map is closed, the frontier holds no item and the destination is a plan of build work. Why hard: the reflex is to restart charting, go back to an interview, or send a plan destination to the design and plan steps, instead of handing the map to /work-items:decompose."
 tags: [wayfind, handoff]
 runs: 3
 max_turns: 12
 timeout_seconds: 600
 allowed_tools: [Read, Glob, Grep, Skill]
-expected_outcome: "The user is told to produce the implementation plan next, directly or with the design step ahead of it, since the map has done its job and its destination is a plan, with no further charting or interviewing"
+expected_outcome: "The user is told to run /work-items:decompose next on the closed map, since the map has done its job and its destination is a set of build items, with no further charting or interviewing"
 ---
 
-Use the wayfind skill. The tracker is unreachable from here, so work from the map state I describe and do not look for files. Our decision map for migrating the billing service to a new message broker is fully closed: the frontier holds no item, every decision item is closed, and the map's destination is an implementation PLAN, not a Brief or a PRD. Hand off: what should I run next?
+Use the wayfind skill. The tracker is unreachable from here, so work from the map state I describe and do not look for files. Our map for migrating the billing service to a new message broker is fully closed: the frontier holds no item, every decision item is closed, and the map's destination is an implementation PLAN, not a Brief or a PRD. Hand off: what should I run next?

plugins/planning/evals/wayfind-closed-plan-destination/samples/names-decompose-step.json

@@ -0,0 +1,34 @@
+{
+  "pass": [
+    {
+      "answer": "The map is closed and its destination is a plan of build work, so close the map issue and run `/work-items:decompose` with the map's URL.",
+      "why": "the skill's own hand-off"
+    },
+    {
+      "answer": "Don't restart charting. Run work-items:decompose next and point it at the map's decisions.",
+      "why": "negation about charting, decompose step named without the slash"
+    },
+    {
+      "answer": "Hand it on: decompose the map into work items, reading Decisions-so-far and each resolution comment.",
+      "why": "names the decompose step in prose"
+    }
+  ],
+  "fail": [
+    {
+      "answer": "Your map's destination is an implementation plan, but first restart charting with /planning:wayfind chart to check nothing was missed.",
+      "why": "restates the destination and restarts charting"
+    },
+    {
+      "answer": "Don't run /work-items:decompose yet; go back to /planning:interview and re-check the decisions.",
+      "why": "negated decompose step"
+    },
+    {
+      "answer": "Run /planning:design ahead of /planning:plan to write the implementation plan.",
+      "why": "the closure target before the map closed to prd, decompose or work"
+    },
+    {
+      "answer": "Run /planning:wayfind work to pick the next frontier item.",
+      "why": "keeps working the map"
+    }
+  ]
+}

plugins/planning/reference/config.md

@@ -45,6 +45,8 @@ never used in its place. An invalid value never stops the run.
 | `time_units` | `true`, `false` (bare YAML booleans) | `false` | the procedure in [`../context/problem-framing.md`](../context/problem-framing.md) "Time units": whether an estimate or budget of work may be stated in hours, days or weeks | repository file over user config over default |
 | `pre_confirmed_label` | a tracker label name (non-empty string) | unset | same procedure, "Pre-confirmed": the label that marks an item's stated problem confirmed in an unattended run; choose one only people with write access apply, never one a workflow or agent applies | repository file over default |
 | `work_size` | an object with `appetite`, `size`, `uncertainty`, each a map of level name to a quoted one-line description | appetite and size `Small`, `Medium`, `Large`; uncertainty `Known`, `Knowable`, `Unknown`; descriptions below | same procedure, "Work size": the levels the Brief's `### Work size` names | repository file over default |
+| `wayfind_research_start` | `auto`, `confirm` | `auto` (owner decision Q532, 2026-10-15) | `/planning:wayfind` chart step 6 and work step 4: `auto` starts a research item without asking when the frontier holds only research items, else asks first in an interactive session; `confirm` always asks first. An unattended session starts only research items without `needs-human` | repository file over default |
+| `wayfind_hitl_concurrency` | an integer, 1 or more | `1` (owner's Topic 10 accept list, 2026-10-15) | `/planning:wayfind` work step 4: the most `needs-human` items of one map claimed at once across sessions; research items never count | repository file over default |
 | `shared_session.uploads` | `true`, `false` | `false` | `/planning:interview` shared lane, at start: guests may offer files | repository file over default |
 | `shared_session.names` | `full`, `initials`, `someone` | `full` | same: what guests see of who answered and voted | repository file over default |
 | `shared_session.digest_names` | `true`, `false` | `false` | same: whether the round sent to Claude names who answered, except people a question is aimed at, who are always named | repository file over default |

plugins/planning/schemas/planning.schema.json

@@ -46,6 +46,17 @@
       "type": "string",
       "minLength": 1
     },
+    "wayfind_research_start": {
+      "description": "When /planning:wayfind starts a research item in an interactive session. auto: without asking when the frontier holds no item other than research items, otherwise after the user confirms. confirm: always after the user confirms. An unattended session starts only research items without needs-human, whatever this says.",
+      "enum": ["auto", "confirm"],
+      "default": "auto"
+    },
+    "wayfind_hitl_concurrency": {
+      "description": "The most needs-human items of one /planning:wayfind map that may be claimed at once, across every session. Research items never count against it.",
+      "type": "integer",
+      "minimum": 1,
+      "default": 1
+    },
     "work_size": {
       "description": "The levels the Brief's Work size uses, per dimension: an ordered map of level name to a one-line quoted description. A dimension set here replaces that dimension's default as a whole. The last level of size is the split trigger, whatever it is named.",
       "type": "object",