@mgiles/perk 1.0.1

package/shared/providers.yaml

@@ -0,0 +1,221 @@
+# perk provider-selection supported set — the THIRD parsed cross-plane contract
+# (sibling of registry.yaml and bindings.yaml).
+#
+# Authored once here, bundled into each build artifact (wheel -> perk/_shared/,
+# npm tarball -> shared/), and parsed directly by both planes at runtime: the
+# Python reader is perk/substrate/providers.py, the TS reader is extension/substrate/providers.ts. No
+# codegen step — both planes read this same file.
+#
+# This is the SUPPORTED SET (the full catalog of providers perk knows how to wire),
+# distinct from the per-repo SELECTION (the flat `[providers]` table in .pi/perk.toml,
+# which is just a pointer into this catalog). Because both planes read this with their
+# full YAML readers, it can carry nested structure — notably the Pi `package_filter`
+# object — that the narrow-TOML config reader cannot.
+#
+# Vocabulary — each provider entry:
+#   id      — the stable provider id. NOT the cache.plan-ref `provider` string:
+#             that field is the ISSUE BACKEND (the stamped `backend_id`, e.g.
+#             "github"), not the seam id — see contracts.md §8.10 / §8.21.
+#   seam    — `plan` | `todo` | `askuser` | `footer` | `web` (the five seams pluggability-taxonomy.md scope-fenced).
+#   package — the foreign Pi package spec added to .pi/settings.json `packages`
+#             (e.g. "npm:@tombell/pi-plan"); `null` for perk's own bundled reference
+#             provider (nothing to add — perk produces the contract natively). NOT
+#             universal: the `web` seam's reference provider (`pi-web-access`) is itself
+#             a FOREIGN package because perk owns no native web implementation — its
+#             `default: true` entry carries a non-null `package` (the documented exception).
+#   adapter — the perk-owned shim module that bridges the foreign surface to the
+#             artifact boundary (cache.plan-ref / perk:checkpoint); `null` for the
+#             reference provider.
+#   default — exactly ONE `true` per seam: the behavior-preserving no-config pick.
+#   package_filter — optional Pi object-form filter (extensions/skills/… arrays)
+#             merged into the foreign package's `packages` entry to enable only the
+#             conflicting surface. perk's own package is NEVER filtered (it defers at
+#             runtime instead — adapter-architecture.md Invariant 2).
+#
+# Validation split (mirrors bindings.yaml): the shape-only loaders (perk/substrate/providers.py,
+# extension/substrate/providers.ts) check schema_version, id uniqueness, seam membership, and
+# exactly-one-default-per-seam. Cross-checks — does the repo's `[providers]` selection
+# name a provider that exists / has the right seam? — are `doctor`'s job, NOT the
+# loaders. The Python plane is the authoritative validator.
+#
+# Status (Node 2.1 → 3.2): this file ships the substrate (the three reference entries +
+# foreign entries per seam), and ALL THREE seams now have a REAL foreign provider. The PLAN
+# adapter landed at Node 2.3: `tombell-plan` is a REAL, selectable plan provider —
+# `planAdapterTombell` bridges `@tombell/pi-plan`'s free-form prose surface to perk's
+# canonical `plan_save` → `cache.plan-ref` contract, and perk VACATES the plan surface at
+# REGISTRATION time (not just handler-time) under a foreign plan selection so the foreign
+# `/plan`/`Ctrl+Alt+P`/`--plan` are the sole registrants (Pi suffixes duplicate command
+# names). The TODO adapter landed at Node 3.2: `juicesharp-todo` is a REAL, selectable todo
+# provider — `todoAdapterJuicesharp` carries perk's implement-progress discipline onto
+# `@juicesharp/rpiv-todo`'s checklist overlay (injection-only, active-workflow-gated), and
+# perk's own checkpoints simply DEFER at runtime (Node 3.1) — NO registration-time vacating,
+# because the todo seam has no command-name collision (`/checkpoints` vs the overlay's own
+# command). The DEFAULT path (the reference providers) is the hard guarantee.
+#
+# The ASKUSER seam is an INTERFACE seam (no durable artifact to bridge): its stable contract is
+# the tool NAME `ask_user_question` plus its non-terminating-answer semantics. `juicesharp-ask-user`
+# (`@juicesharp/rpiv-ask-user-question`) registers a tool with the IDENTICAL name, and tools
+# (unlike commands) do NOT get `:N` suffixes — a same-named tool replaces/warns by extension load
+# order. So the adapter is VACATE-ONLY (`adapter: null`, no shim, no injected context): under a
+# foreign askuser selection perk's `registerAskUser` registers NOTHING at REGISTRATION time,
+# leaving exactly one `ask_user_question` standing. Under the default (`perk-ask-user`) the foreign
+# package is never installed, so perk's tool is the sole registrant.
+#
+# The FOOTER seam is the SECOND INTERFACE seam (no durable artifact to bridge), mirroring askuser
+# but with INSTALL-SITE (runtime) vacating rather than registration-time vacating: perk installs
+# its own footer (`installPerkFooter`) inside the `session_start` event handler, so under a foreign
+# `[providers] footer` selection perk simply does NOT call `installPerkFooter` (a runtime guard at
+# that single install site, keyed off `ctx.cwd`), leaving the foreign footer (`pi-powerline-footer`,
+# `pi-bar`, or `@tombell/pi-status`) as the sole footer surface. `adapter: null`, no shim: for
+# `pi-powerline-footer`/`pi-bar` perk's objective/checkpoints progress reaches the foreign footer
+# automatically via the already-publishing composed `perk` `setStatus` slot (both render extension
+# statuses), so the bridge is automatic; `@tombell/pi-status` is the exception (it does NOT render
+# extension statuses — see the `pi-status-footer` note below).
+# Fail-safe: any config-read error resolves to the reference id → perk installs its footer (the
+# default path is the hard zero-change guarantee).
+#
+# Two more footer outcomes round out the catalog so the footer is governed EXCLUSIVELY by
+# `[providers] footer` (no footer outcome ever needs a manual `packages` edit):
+#   - `pi-status-footer` (`npm:@tombell/pi-status`) is vacate-only like the two above, BUT — unlike
+#     `powerline-footer`/`pi-bar-footer` — pi-status does NOT render extension statuses, so perk's
+#     objective/checkpoints progress is NOT shown in the footer when it is selected. This is an
+#     accepted limitation (it matches what pi-status already does today); perk does not build a
+#     status-bridge adapter for it (it is a genuine interface seam).
+#   - `pi-default` (`package: null`) is the "install nothing / leave pi's stock built-in footer"
+#     option: perk vacates (gate false), convergence adds no package, so pi's own footer stands.
+#
+# The WEB seam is the THIRD INTERFACE seam (no durable artifact to bridge), but with a genuine
+# novelty: it is the FIRST seam whose `default: true` provider has a NON-NULL `package`. perk owns
+# no native web-research implementation, so the behavior-preserving reference (`pi-web-access`,
+# zero-config Exa search + content fetch + the bundled `librarian` skill) is itself a foreign npm
+# package. Selection simply SWAPS which web package the provider-convergence installs — `adapter:
+# null`, no shim, and there is NO perk surface to vacate at registration time because perk registers
+# NO web tools of its own. The read-only allowlist statically carries the UNION of all known web
+# tool names (inert when absent); perk does NOT normalize tool names across providers. `librarian`
+# is pi-web-access-specific (it depends on `fetch_content`'s GitHub-clone path) and is accepted as
+# lost under a foreign web selection. Fail-safe: any config-read error resolves to `pi-web-access`,
+# keeping today's behavior exactly.
+
+schema_version: 1
+
+providers:
+  - id: perk-plan            # perk's own planMode/planSave over toolGating
+    seam: plan
+    package: null            # null ⇒ perk's bundled reference provider (no foreign package)
+    adapter: null            # null ⇒ no shim needed; perk produces the contract natively
+    default: true            # the behavior-preserving no-config pick for the plan seam
+  - id: perk-checkpoints     # perk's own checkpoints
+    seam: todo
+    package: null
+    adapter: null
+    default: true            # the behavior-preserving no-config pick for the todo seam
+  - id: perk-ask-user        # perk's own ask_user_question tool (extension/doors/askUser.ts)
+    seam: askuser
+    package: null
+    adapter: null
+    default: true            # the behavior-preserving no-config pick for the askuser seam
+
+  # --- foreign entries ---
+  - id: tombell-plan         # REAL plan provider (Node 2.3) — planAdapterTombell bridges it
+    seam: plan
+    package: "npm:@tombell/pi-plan"   # the foreign Pi package to add to `packages`
+    adapter: "planAdapterTombell"     # the perk-owned shim bridging surface → cache.plan-ref
+    default: false
+    # No `package_filter`: `@tombell/pi-plan`'s sole extension is its root `index.ts` (not under
+    # `extensions/`), so omitting the filter ("load all of that type") loads exactly that one
+    # extension. The `package_filter` field stays in the vocabulary for future providers.
+  - id: plannotator-plan   # REAL plan provider — planAdapterPlannotator bridges its browser review
+    seam: plan
+    package: "npm:@plannotator/pi-extension"   # the foreign Pi package to add to `packages`
+    adapter: "planAdapterPlannotator"          # the perk-owned shim bridging plan_review → its event API
+    default: false
+    # AUGMENT posture (contrast with tombell-plan's REPLACE posture): plannotator does not replace
+    # perk's plan surface — perk's `/plan` command, authoring injection, and read-only gate STAY
+    # registered; perk skips only the two real registration collisions (`--plan` flag and the
+    # `Ctrl+Alt+P` shortcut, both of which plannotator also registers — duplicate flag/shortcut
+    # registration is the known potentially-fatal Pi behavior). The bridge is the model-callable
+    # `plan_review` tool (planAdapterPlannotator) → plannotator's `plannotator:request` plan-review
+    # event flow (its browser review UI). Saving stays the human-run `/plan-save`.
+    # No `package_filter`: `@plannotator/pi-extension`'s `pi.extensions` is `["./"]` (the sole
+    # extension is the package root), so omitting the filter loads exactly that one extension.
+  - id: juicesharp-todo      # REAL todo provider (Node 3.2) — todoAdapterJuicesharp bridges it
+    seam: todo
+    package: "npm:@juicesharp/rpiv-todo"   # the foreign Pi package to add to `packages`
+    adapter: "todoAdapterJuicesharp"       # the perk-owned shim carrying progress discipline onto it
+    default: false
+    # No `package_filter`: `@juicesharp/rpiv-todo` is a single-concern checklist overlay, so omitting
+    # the filter ("load all of that type") loads its bundled extension. The smoke's manual half is the
+    # gate that no perk surface collides; a targeted `extensions` filter is a follow-up if one ever does.
+  - id: juicesharp-ask-user  # REAL askuser provider — VACATE-ONLY (interface seam, no adapter)
+    seam: askuser
+    package: "npm:@juicesharp/rpiv-ask-user-question"   # the foreign Pi package to add to `packages`
+    adapter: null            # VACATE-ONLY: the foreign tool shares the exact name `ask_user_question`,
+                             # so perk's `registerAskUser` registers NOTHING under this selection —
+                             # there is no durable artifact to bridge (interface seam), and the
+                             # foreign tool self-documents via its own `promptGuidelines`.
+    default: false
+    # No `package_filter`: the verified manifest is `{"extensions": ["./index.ts"]}`, so omitting the
+    # filter ("load all of that type") loads exactly that one extension — the same reasoning as the
+    # tombell-plan / juicesharp-todo entries.
+  - id: perk-footer          # perk's own footer (extension/surfaces/surfaces.ts installPerkFooter)
+    seam: footer
+    package: null
+    adapter: null
+    default: true            # the behavior-preserving no-config pick for the footer seam
+  - id: powerline-footer     # REAL footer provider — VACATE-ONLY (interface seam, no adapter)
+    seam: footer
+    package: "npm:pi-powerline-footer"   # the foreign Pi package to add to `packages`
+    adapter: null            # VACATE-ONLY: the footer produces no durable artifact (interface seam),
+                             # and pi-powerline-footer already renders perk's `perk` setStatus slot in
+                             # its extension_statuses segment, so the bridge is automatic (no shim).
+    default: false
+    # No `package_filter`: load the package's sole footer extension ("load all of that type").
+  - id: pi-bar-footer        # REAL footer provider — VACATE-ONLY (interface seam, no adapter)
+    seam: footer
+    package: "npm:pi-bar"   # the foreign Pi package to add to `packages`
+    adapter: null            # VACATE-ONLY: pi-bar replaces pi's footer and "keeps extension statuses
+                             # visible", so perk's `perk` setStatus slot appears automatically — no shim.
+    default: false
+    # No `package_filter`: load the package's sole footer extension ("load all of that type").
+  - id: pi-status-footer     # REAL footer provider — VACATE-ONLY (interface seam, no adapter)
+    seam: footer
+    package: "npm:@tombell/pi-status"   # the foreign Pi package to add to `packages`
+    adapter: null            # VACATE-ONLY: the footer produces no durable artifact (interface seam).
+                             # UNLIKE powerline/pi-bar, pi-status does NOT render extension statuses,
+                             # so perk's objective/checkpoints progress is NOT shown in the footer
+                             # under this selection (an accepted limitation — matches pi-status today;
+                             # no status-bridge adapter is built).
+    default: false
+    # No `package_filter`: load the package's sole footer extension ("load all of that type").
+  - id: pi-default           # "install nothing" footer provider — leaves pi's stock built-in footer
+    seam: footer
+    package: null            # null ⇒ perk adds NO package; pi's own built-in footer stands.
+    adapter: null            # VACATE-ONLY: perk's footer-install gate is false (resolved id ≠
+                             # perk-footer), so perk skips installPerkFooter; nothing else to add.
+    default: false
+  - id: pi-web-access        # web seam DEFAULT — the FOREIGN reference provider (perk owns no native web impl)
+    seam: web
+    package: "npm:pi-web-access"   # NON-NULL default package: the novelty — perk has no native web provider
+    adapter: null            # VACATE-ONLY interface seam: no durable artifact, and perk registers NO web
+                             # tools, so there is no perk surface to vacate. Selection just swaps the package.
+    default: true            # the behavior-preserving no-config pick (zero-config Exa search + `librarian`)
+    # No `package_filter`: `pi-web-access`'s sole extension is its root `./index.ts` (verified via
+    # `npm view pi-web-access pi`), so omitting the filter loads exactly that one extension.
+  - id: ollama-web-search    # REAL web provider — VACATE-ONLY (interface seam, no adapter)
+    seam: web
+    package: "npm:@ollama/pi-web-search"   # the foreign Pi package to add to `packages`
+    adapter: null            # VACATE-ONLY: web is an interface seam (no artifact); perk registers no web
+                             # tools, so nothing to vacate. Tools: `ollama_web_search`/`ollama_web_fetch`
+                             # (needs a local Ollama daemon). Divergent names — perk allowlists the union.
+    default: false
+    # No `package_filter`: verified manifest is `{"extensions": ["./index.ts"]}`, so omitting the
+    # filter loads exactly that one extension.
+  - id: juicesharp-web-tools # REAL web provider — VACATE-ONLY (interface seam, no adapter)
+    seam: web
+    package: "npm:@juicesharp/rpiv-web-tools"   # the foreign Pi package to add to `packages`
+    adapter: null            # VACATE-ONLY: interface seam, no artifact; perk registers no web tools.
+                             # Tools: `web_search`/`web_fetch` (needs an API key; default provider Brave;
+                             # registers a `/web-tools` command — no perk collision).
+    default: false
+    # No `package_filter`: verified manifest is `{"extensions": ["./index.ts"]}`, so omitting the
+    # filter loads exactly that one extension (the juicesharp single-extension convention).

package/shared/registry.yaml

@@ -0,0 +1,199 @@
+# perk stage registry — the language-neutral contract both planes read (Q4/Q6).
+#
+# Authored once here, bundled into each build artifact (wheel -> perk/_shared/,
+# npm tarball -> shared/), and parsed directly by both planes at runtime: the
+# Python CLI generates its subcommands from it (T4); the TS extension drives its
+# in-session transitions from it (Phase 1+). No codegen step (Q6).
+#
+# T2 locks the descriptor *shape*, the stage *graph*, and the state-key
+# *vocabulary*. The drift-prone per-stage state I/O (`requires`/`reads`/`writes`)
+# is left empty and filled as each handler lands (Phase 1+) — locking the shape,
+# not authoring fiction about unbuilt stages.
+
+schema_version: 1
+
+# ---------------------------------------------------------------------------
+# State-key vocabulary (Q4). `requires`/`reads`/`writes` draw ONLY from these,
+# written as dotted "<tier>.<key>" strings (e.g. "github.plan"). The self-check
+# flattens this map to a set for membership validation.
+# ---------------------------------------------------------------------------
+state_keys:
+  # Tier 1 · GitHub — the canonical source of truth.
+  github:
+    - plan            # the plan issue (header + body)
+    - objective       # the objective issue (storage + mechanics live in P2.T9; its stage in T10)
+    - pr              # the pull request
+    - labels          # repo labels (e.g. perk:plan)
+    - comments        # discussion comments
+    - review-threads  # review threads (distinct API from comments)
+    - learn           # the perk:learn knowledge-capture issue (P2.T8b)
+  # Tier 2 · .pi/workflow/ — the local cache (see contracts.md §8.1).
+  cache:
+    - plan            # materialized plan body cache
+    - plan-ref        # provider-agnostic plan->branch ref (see contracts.md §8.4)
+    - scratch         # per-run inter-process workflow files
+    - handoff         # pre-session CLI->extension cold-door state
+    - markers         # existence-based friction semaphores (e.g. pending-learn)
+    - session-data    # the run-scoped session data dir artifacts (scratch/runs/<run_id>/data/; #339 Node 2.1)
+  # Tier 3 · session entries — transient in-session state.
+  session:
+    - workflow-state  # the single `perk:workflow-state` record (contracts.md §8.3)
+
+# ---------------------------------------------------------------------------
+# Stages — the loop (Q5): objective-author -> objective-save -> objective-plan -> plan ->
+# save -> implement -> submit -> address -> land -> learn.
+#
+# Every field is locked EXCEPT `requires`/`reads`/`writes` (empty until handlers
+# land). `run_id` is uniform AND shape-locked by the validator: `perk/substrate/registry.py`
+# `_check_doors_and_run_id` enforces `warm == keep` and `cold_local`/`cold_remote == mint`
+# for every stage (Q2). It is a shape-locked map, NOT free per-stage data — the field is kept
+# because the shape is the contract, not because stages vary.
+# `command` is the human/contract LABEL for the stage's command, not the routing table: the
+# actual dedicated cold-door routing lives in code via `perk/cli/stages.py` `DEDICATED_STAGES`
+# (the generic launcher generator skips those ids). The field documents intent; it does not route.
+# `doors.cold_remote` records which stages a remote runner may run (cli-vs-pi §4.5) —
+# a real registry-recorded constraint, not merely "not built yet". P2.T8c flips it
+# `true` on `implement` + `address` (the agentic, headless-runnable stages a Phase-3 CI
+# worker drives); `plan`/`save` need interactive local exploration and
+# `submit`/`land`/`learn` are quick deterministic ops, so they stay `false`. Phase 2
+# *builds + resolves* the target (the resolver + this door + the --json descriptor);
+# Phase 3 *drives* it. Revisable in Phase 3.
+# ---------------------------------------------------------------------------
+stages:
+  - id: objective-author
+    summary: Draft a new objective + roadmap (read-only authoring).
+    mode: read-only
+    worktree: none            # interactive authoring, like plan — no branch, no objective yet
+    doors: { warm: true, cold_local: true, cold_remote: false }  # interactive local authoring
+    run_id: { warm: keep, cold_local: mint, cold_remote: mint }
+    command: objective author  # P3.T2: dedicated seeded cold door (perk objective author)
+    requires: []                       # nothing exists yet — this stage CREATES the objective
+    reads: []
+    writes: [session.workflow-state, cache.session-data]   # the read-only `mode` append (the gate toggle); #352 Node 2.1: objective_draft writes the objective-draft artifact + its session_artifacts pointer
+    predecessors: []                   # the new single initial (authoring precedes everything)
+    successors: [objective-save]
+
+  - id: objective-save
+    summary: Persist the drafted objective to GitHub; the read-only -> read-write boundary.
+    mode: read-write
+    worktree: none            # still no branch; save writes the objective issue
+    doors: { warm: true, cold_local: true, cold_remote: false }
+    run_id: { warm: keep, cold_local: mint, cold_remote: mint }
+    command: objective save   # P3.T2: the objective_save terminating tool + /objective-save command
+    requires: []
+    reads: []
+    writes: [github.objective, session.workflow-state]  # create the objective issue; link active_objective
+    predecessors: [objective-author]
+    successors: [objective-plan]
+
+  - id: objective-plan
+    summary: Select the next objective node and author a bounded plan (read-only).
+    mode: read-only
+    worktree: none            # interactive planning, like plan — no branch yet
+    doors: { warm: true, cold_local: true, cold_remote: false }  # interactive local exploration
+    run_id: { warm: keep, cold_local: mint, cold_remote: mint }
+    command: objective plan   # P2.T10: dedicated cold door (perk objective plan) + /objective-plan
+    requires: [github.objective]                        # an objective issue must exist
+    reads: [github.objective]                           # roadmap nodes + next-node selection
+    writes: [github.objective, session.workflow-state, cache.session-data]  # mark node planning; set active_objective; #339 Node 2.1: plan_draft writes the working-plan artifact + its session_artifacts pointer
+    predecessors: [objective-save]                      # P3.T2: objective-save now precedes planning
+    successors: [plan]
+
+  - id: plan
+    summary: Explore the codebase and draft a plan (read-only).
+    mode: read-only
+    worktree: none            # no implementation branch exists yet
+    doors: { warm: true, cold_local: true, cold_remote: false }
+    run_id: { warm: keep, cold_local: mint, cold_remote: mint }
+    command: plan             # slash = /plan (perk-owned P2.T2a; toggles the read-only tool gate)
+    requires: []
+    reads: []
+    writes: [session.workflow-state, cache.session-data]  # P2.T2a: /plan enter/exit appends `mode`; #339 Node 2.1: plan_draft writes the working-plan artifact + its session_artifacts pointer
+    predecessors: [objective-plan]    # P2.T10: objective-plan is the new single initial
+    successors: [save]
+
+  - id: save
+    summary: Persist the plan to GitHub; the read-only -> read-write boundary.
+    mode: read-write
+    worktree: none            # still no branch; save writes the plan issue + ref
+    doors: { warm: true, cold_local: true, cold_remote: false }
+    run_id: { warm: keep, cold_local: mint, cold_remote: mint }
+    command: plan save        # cold: the merged `perk plan save` door (Node 3.2); warm twin: the plan_save tool + /plan-save command
+    requires: []
+    reads: []
+    writes: [github.plan, cache.plan-ref, session.workflow-state]  # T2a: plan issue; T2b: plan-ref pointer; T3: warm door appends active_plan_ref
+    predecessors: [plan]
+    successors: [implement]
+
+  - id: implement
+    summary: Do the work on a branch (requires fresh context; cold-only).
+    mode: read-write
+    worktree: create          # first stage that needs a branch/worktree (folds in erk's `prepare`)
+    doors: { warm: false, cold_local: true, cold_remote: true }  # P2.T8c: a Phase-3 CI worker can run it
+    run_id: { warm: keep, cold_local: mint, cold_remote: mint }
+    command: implement
+    requires: [cache.plan-ref]   # T4: cold door derives plan-<pr_id> from the active ref
+    reads: [cache.plan-ref]      # T4: positions the worktree from the ref (agent reads github.plan)
+    writes: [session.workflow-state]  # T4: the worktree session links active_plan_ref on session_start
+    predecessors: [save]
+    successors: [submit]
+
+  - id: submit
+    summary: Push the branch and open a draft PR.
+    mode: read-write
+    worktree: reuse
+    doors: { warm: true, cold_local: true, cold_remote: false }
+    run_id: { warm: keep, cold_local: mint, cold_remote: mint }
+    command: pr submit
+    requires: [cache.plan-ref]              # T5a: reads the active ref to derive the branch
+    reads: [cache.plan-ref, github.plan]    # T5a: ref -> branch; plan issue title for the PR
+    writes: [github.pr, github.plan]        # T5a: open the draft PR; populate staged branch/pr header
+    predecessors: [implement]
+    successors: [address]
+
+  - id: address
+    summary: Classify PR review feedback (isolated child) and resolve the threads.
+    mode: read-write
+    worktree: reuse
+    doors: { warm: true, cold_local: true, cold_remote: true }  # P2.T8c: a Phase-3 CI worker can run it
+    run_id: { warm: keep, cold_local: mint, cold_remote: mint }
+    command: pr address
+    # P2.T7: a spawned read-only child (borrowed pi-subagents) fetches + classifies feedback;
+    # the parent fixes only actionable items and batch-resolves the threads (`resolve_review_threads`).
+    requires: [github.pr]                                          # the PR whose feedback we address
+    reads: [cache.plan-ref, github.pr, github.review-threads, github.comments]
+    writes: [github.review-threads, github.comments, github.pr, session.workflow-state]
+    predecessors: [submit]
+    successors: [land]
+
+  - id: land
+    summary: Merge the ready/approved PR and reconcile; sets the pending-learn marker.
+    mode: read-write
+    worktree: reuse
+    doors: { warm: true, cold_local: true, cold_remote: false }
+    run_id: { warm: keep, cold_local: mint, cold_remote: mint }
+    command: pr land
+    requires: [github.pr]                    # T5b: the PR to merge must exist
+    reads: [cache.plan-ref, github.pr, github.objective]   # T5b ref->branch->PR; T11a node lookup
+    writes: [github.pr, cache.markers, github.objective]   # T5b merge+marker; T11a mechanical node-done
+    predecessors: [address]
+    successors: [learn]
+
+  - id: learn
+    summary: Capture learnings from the landed run; clears the pending-learn marker.
+    mode: read-write
+    worktree: reuse           # pending-learn blocks worktree deletion until this runs (Q5)
+    doors: { warm: true, cold_local: true, cold_remote: false }
+    run_id: { warm: keep, cold_local: mint, cold_remote: mint }
+    command: learn
+    # P2.T8b: deepened from a thin marker-clear into a real knowledge-capture pass — with a
+    # summary, create a perk:learn issue (idempotent via the perk:learn-scoped find_learn_issue) +
+    # back-link comment, then clear pending-learn; without one, the thin marker-clear (no issue).
+    # P2.T17: now launches PRIMED (launch.py _learn_prompt) — the cold session opens investigating
+    # the landed change; bare warm /learn injects perk-learn guidance (interactive). No new I/O
+    # keys (no new gateway op) — the existing learn tool / learn capture worker still persist.
+    requires: [cache.markers]                # pending-learn gates the worktree
+    reads: [cache.markers, cache.plan-ref]   # was it set? + the plan ref -> issue number/run_id
+    writes: [cache.markers, github.learn, github.comments]  # clear marker; create learn issue + back-link
+    predecessors: [land]
+    successors: []