@mgiles/perk 2.3.0 → 3.1.0

package/shared/providers.yaml

@@ -16,7 +16,7 @@
 #   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; see
+#   seam    — `plan` | `footer` | `web` (the three seams; see
 #             pluggability-taxonomy.md for the scope fence).
 #   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
@@ -25,7 +25,7 @@
 #             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
+#             artifact boundary (cache.plan-ref); `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)
@@ -39,38 +39,23 @@
 # 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
+# Status: this file ships the substrate (the reference entries + foreign entries per seam), and
+# every seam has a REAL foreign provider. The PLAN adapter: `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.
+# names). 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
+# The FOOTER seam is one of the TWO INTERFACE seams (with web; no durable artifact to bridge),
+# vacated at the INSTALL SITE (runtime) rather than registration time: 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
+# `pi-powerline-footer`/`pi-bar` perk's objective progress reaches the foreign footer
+# automatically via the already-publishing single-value `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).
@@ -79,14 +64,14 @@
 # `[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
+#     objective 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
+# The WEB seam is the OTHER INTERFACE seam (no durable artifact to bridge), but with a genuine
+# novelty: it is the ONLY 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:
@@ -102,6 +87,17 @@
 # IS the surface pick). The hunk CLI converges unconditionally (init/doctor's best-effort
 # `review-cli` install/verify); the plannotator package rides the plan seam's `plannotator-plan`
 # entry.
+#
+# There is NO askuser seam anymore: it is RETIRED to a REQUIRED BORROW. After perk's first-party
+# `ask_user_question` tool was deleted the seam had exactly one selectable provider — nothing to
+# select (the borrow-vs-seam criterion) — so `ask_user_question` is now the borrowed
+# `@juicesharp/rpiv-ask-user-question` questionnaire, installed for every repo via
+# `BORROWED_PACKAGES` (convergence/init/settings.py).
+#
+# There is NO todo seam anymore: it is RETIRED to a REQUIRED BORROW. After the seam had exactly
+# one selectable provider — nothing to select (the borrow-vs-seam criterion) — the checklist
+# overlay became the borrowed `@juicesharp/rpiv-todo`, installed for every repo via
+# `BORROWED_PACKAGES` (convergence/init/settings.py).
 
 schema_version: 1
 
@@ -111,16 +107,6 @@ providers:
     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
@@ -145,25 +131,6 @@ providers:
     # 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
@@ -189,7 +156,7 @@ providers:
     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
+                             # so perk's objective 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

package/shared/registry.yaml

@@ -28,6 +28,7 @@ state_keys:
     - review-threads  # review threads (distinct API from comments)
     - learn           # the perk:learn knowledge-capture issue (P2.T8b)
     - gist            # the perk:gist statement-of-intent issue (contracts.md §8.41)
+    - stack           # the native stacked-PR resource (contracts.md §8.47)
   # Tier 2 · .perk/workflow/ — the local cache (see contracts.md §8.1).
   cache:
     - plan            # materialized plan body cache
@@ -52,6 +53,11 @@ state_keys:
 # `_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.
+# `worktree` vocabulary (positioned by the one selector/positioner, `launch.resolve_worktree`
+# — contracts.md §8.38): `none` = the invoking checkout; `create` = create the `plan-<id>`
+# branch/worktree when missing (idempotent validated reuse when present); `reuse` = reuse a
+# VALIDATED local checkout, or (learn excepted) restore the EXISTING `origin/plan-<id>` branch
+# non-destructively when the checkout is missing — `reuse` never creates a new plan branch.
 # `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.
@@ -72,7 +78,7 @@ stages:
     command: gist author      # dedicated seeded cold door (perk gist author)
     requires: []                       # nothing exists yet — this stage CREATES the gist
     reads: []
-    writes: [session.workflow-state, cache.session-data]   # the read-only `mode` append; gist_draft writes the gist-draft artifact + its session_artifacts pointer
+    writes: [session.workflow-state, cache.session-data, cache.scratch]   # the read-only `mode` append; gist_draft writes the gist-draft artifact + its session_artifacts pointer; eligible turns may provision agent scratch
     predecessors: []                   # an initial of the disconnected gist component
     successors: [gist-save]
 
@@ -85,7 +91,7 @@ stages:
     command: gist save        # the gist_save terminating tool + /gist-save command
     requires: []
     reads: []
-    writes: [github.gist, session.workflow-state]  # create the gist issue/project
+    writes: [github.gist, session.workflow-state, cache.scratch]  # create the gist issue/project; eligible turns may provision agent scratch
     predecessors: [gist-author]
     successors: []            # a terminal — consumption happens via the adoption doors, not edges
 
@@ -98,7 +104,7 @@ stages:
     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
+    writes: [session.workflow-state, cache.session-data, cache.scratch]   # the read-only `mode` append (the gate toggle); #352 Node 2.1: objective_draft writes the objective-draft artifact + its session_artifacts pointer; eligible turns may provision agent scratch
     predecessors: []                   # the new single initial (authoring precedes everything)
     successors: [objective-save]
 
@@ -111,7 +117,7 @@ stages:
     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
+    writes: [github.objective, session.workflow-state, cache.scratch]  # create the objective issue; link active_objective; eligible turns may provision agent scratch
     predecessors: [objective-author]
     successors: [objective-plan]
 
@@ -124,7 +130,7 @@ stages:
     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
+    writes: [github.objective, session.workflow-state, cache.session-data, cache.scratch]  # mark node planning; set active_objective; #339 Node 2.1: plan_draft writes the working-plan artifact + its session_artifacts pointer; eligible turns may provision agent scratch
     predecessors: [objective-save]                      # P3.T2: objective-save now precedes planning
     successors: [plan]
 
@@ -137,7 +143,7 @@ stages:
     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
+    writes: [session.workflow-state, cache.session-data, cache.scratch]  # P2.T2a: /plan enter/exit appends `mode`; #339 Node 2.1: plan_draft writes the working-plan artifact + its session_artifacts pointer; eligible turns may provision agent scratch
     predecessors: [objective-plan]    # P2.T10: objective-plan is the new single initial
     successors: [save]
 
@@ -150,7 +156,7 @@ stages:
     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
+    writes: [github.plan, cache.plan-ref, session.workflow-state, cache.scratch]  # T2a: plan issue; T2b: plan-ref pointer; T3: warm door appends active_plan_ref; eligible turns may provision agent scratch
     predecessors: [plan]
     successors: [implement]
 
@@ -163,7 +169,7 @@ stages:
     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
+    writes: [session.workflow-state, cache.scratch]  # T4: the worktree session links active_plan_ref on session_start; eligible turns may provision agent scratch
     predecessors: [save]
     successors: [submit]
 
@@ -175,23 +181,26 @@ stages:
     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
+    # Stacked route (§8.47): the delivery publish operation reads the objective (train +
+    # journal fold) and the native stack, and writes the journal (objective comments), the
+    # checkpoint pair (plan header), and the stack registration. Incremental touches neither.
+    reads: [cache.plan-ref, github.plan, github.objective, github.stack]
+    writes: [github.pr, github.plan, github.objective, github.stack, cache.scratch]
     predecessors: [implement]
     successors: [address]
 
   - id: address
-    summary: Classify PR review feedback (isolated child) and resolve the threads.
+    summary: Classify PR review feedback, publish committed fixes, then resolve the threads.
     mode: read-write
     worktree: reuse
     doors: { warm: true, cold_local: true, cold_remote: true }  # bounded agentic stage — remotely runnable
     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`).
+    # The isolated child classifies; the parent fixes, then §8.52's finalizer routes through
+    # submit before resolving. The stacked route owns the objective journal + native stack.
     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]
+    reads: [cache.plan-ref, github.plan, github.pr, github.review-threads, github.comments, github.objective, github.stack]
+    writes: [github.review-threads, github.comments, github.pr, github.plan, github.objective, github.stack, session.workflow-state, cache.scratch]
     predecessors: [submit]
     successors: [land]
 
@@ -204,14 +213,16 @@ stages:
     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, github.plan]   # T5b merge+marker; T11a mechanical node-done; §8.36 learn_state header stamp
+    writes: [github.pr, cache.markers, github.objective, github.plan, cache.scratch]   # T5b merge+marker; T11a mechanical node-done; §8.36 learn_state header stamp; eligible turns may provision agent scratch
     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)
+    worktree: reuse           # pending-learn blocks worktree deletion until this runs (Q5);
+                              # learn NEVER restores a missing checkout (post-merge the remote
+                              # branch is commonly gone; its session evidence is machine-local)
     doors: { warm: true, cold_local: true, cold_remote: false }
     run_id: { warm: keep, cold_local: mint, cold_remote: mint }
     command: learn
@@ -223,6 +234,19 @@ stages:
     # 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, github.plan]  # clear marker; create learn issue + back-link; §8.36 learn_state header stamp
+    writes: [cache.markers, github.learn, github.comments, github.plan, cache.scratch]  # clear marker; create learn issue + back-link; §8.36 learn_state header stamp; eligible turns may provision agent scratch
     predecessors: [land]
     successors: []
+
+  - id: audit
+    summary: Judge session-audit evidence packets via the auditor wave (dev-only door in perk-dev).
+    mode: read-only
+    worktree: none            # runs in the invoking checkout; the one write is gitignored scratch
+    doors: { warm: false, cold_local: true, cold_remote: false }
+    run_id: { warm: keep, cold_local: mint, cold_remote: mint }
+    command: audit judge      # label only — the dedicated cold door lives in perk-dev, not perk
+    requires: []
+    reads: []
+    writes: [session.workflow-state, cache.scratch]  # the claim append; run_audit_wave writes <bundle>/verdicts.json under scratch
+    predecessors: []          # a deliberately isolated node — the dev-only audit component
+    successors: []

package/shared/schemas/inputs/review-post-batch.schema.json

@@ -29,7 +29,7 @@
     }
   },
   "additionalProperties": false,
-  "description": "The strict `/pr-review` batch shape (`{verdict, summary, comments?, fyi?}`).\n\n`comments`/`fyi` stay nullable so an explicit `null` is tolerated (today's behavior),\nnormalized to `[]` in conversion. `line: int` under strict rejects `bool`/`float`/`str`\n(preserving the old `isinstance(line, bool)` guard).",
+  "description": "The strict `/pr-review` batch shape.\n\n`comments`/`fyi` stay nullable so an explicit `null` is tolerated (today's behavior),\nnormalized to `[]` in conversion. `line: int` and `expected_pr: int` reject\n`bool`/`float`/`str` under strict validation.",
   "properties": {
     "verdict": {
       "enum": [
@@ -73,6 +73,19 @@
       ],
       "default": null,
       "title": "Fyi"
+    },
+    "expected_pr": {
+      "anyOf": [
+        {
+          "exclusiveMinimum": 0,
+          "type": "integer"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "Expected Pr"
     }
   },
   "required": [