@mgiles/perk 3.0.0 → 3.2.0

package/shared/registry.yaml

@@ -78,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]
 
@@ -91,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
 
@@ -104,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]
 
@@ -117,20 +117,20 @@ 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]
 
   - 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
+    worktree: none            # interactive planning, like plan — no branch yet; the cold door overrides to a transient reuse stage for a stacked child layer with a live predecessor branch (§8.46)
     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
+    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]
 
@@ -143,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]
 
@@ -156,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]
 
@@ -169,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]
 
@@ -185,7 +185,7 @@ stages:
     # 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]
+    writes: [github.pr, github.plan, github.objective, github.stack, cache.scratch]
     predecessors: [implement]
     successors: [address]
 
@@ -200,7 +200,7 @@ stages:
     # 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.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]
+    writes: [github.review-threads, github.comments, github.pr, github.plan, github.objective, github.stack, session.workflow-state, cache.scratch]
     predecessors: [submit]
     successors: [land]
 
@@ -213,7 +213,7 @@ 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]
 
@@ -234,7 +234,7 @@ 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: []
 
@@ -250,3 +250,18 @@ stages:
     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: []
+
+  - id: stack-review
+    summary: Review a stacked PR train in the plannotator browser with judgment-routed per-PR posting.
+    mode: read-write          # deliberate parity with the warm /stack-review-browser door — the
+                              # human is present and nothing auto-posts (contracts.md §8.4)
+    worktree: none            # runs in the invoking checkout; the review checkout is the
+                              # detached review-<top> worktree the cold door materialized
+    doors: { warm: false, cold_local: true, cold_remote: false }  # interactive browser flow — local-only by design
+    run_id: { warm: keep, cold_local: mint, cold_remote: mint }
+    command: objective stack review  # label — the dedicated cold door under the objective stack group
+    requires: []
+    reads: []
+    writes: [github.pr, github.review-threads, session.workflow-state, cache.scratch]  # per-PR review posting via submit_pr_review; the claim append; scratch
+    predecessors: []          # a deliberately isolated node — the stacked-review 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": [

package/shared/schemas/outputs/objective-doctor.schema.json

@@ -1,5 +1,35 @@
 {
   "$defs": {
+    "_CorruptionFindingOut": {
+      "additionalProperties": false,
+      "description": "One kind-corruption finding over the objective's issue-tier carrier (report-only \u2014\n``--fix`` never touches it; no repair code path exists).",
+      "properties": {
+        "code": {
+          "title": "Code",
+          "type": "string"
+        },
+        "carrier": {
+          "title": "Carrier",
+          "type": "string"
+        },
+        "message": {
+          "title": "Message",
+          "type": "string"
+        },
+        "remediation": {
+          "title": "Remediation",
+          "type": "string"
+        }
+      },
+      "required": [
+        "code",
+        "carrier",
+        "message",
+        "remediation"
+      ],
+      "title": "_CorruptionFindingOut",
+      "type": "object"
+    },
     "_DriftConditionOut": {
       "additionalProperties": false,
       "properties": {
@@ -432,6 +462,13 @@
           "type": "null"
         }
       ]
+    },
+    "corruption": {
+      "items": {
+        "$ref": "#/$defs/_CorruptionFindingOut"
+      },
+      "title": "Corruption",
+      "type": "array"
     }
   },
   "required": [
@@ -442,7 +479,8 @@
     "fix",
     "redirected_from",
     "train",
-    "train_fix"
+    "train_fix",
+    "corruption"
   ],
   "title": "ObjectiveDoctorOut",
   "type": "object"

package/shared/schemas/outputs/objective-stack-status.schema.json

@@ -123,6 +123,129 @@
       "title": "FindingOut",
       "type": "object"
     },
+    "GateBlockerOut": {
+      "additionalProperties": false,
+      "description": "One planning-gate blocker row (contracts.md \u00a78.46) \u2014 the shared machine\ndiscriminator every gate-carrying envelope serializes.\n\n``kind`` is ``\"technical\"`` (a train readiness veto \u2014 ``code``/``message`` verbatim, or\nthe gate-owned defensive ``dependency_not_ready``) or ``\"handoff\"`` (a handoff-blocked\ndirect dependency \u2014 fields-only, no prose: consumers read the pinned fields). Handoff\nrows derive from a verified-PUBLISHED layer, so ``plan``/``pr``/``remediation`` are\nalways populated there (the nullable wire types exist for the technical rows).",
+      "properties": {
+        "kind": {
+          "title": "Kind",
+          "type": "string"
+        },
+        "code": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "title": "Code"
+        },
+        "message": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "title": "Message"
+        },
+        "dependency_node_id": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "title": "Dependency Node Id"
+        },
+        "plan": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "title": "Plan"
+        },
+        "pr": {
+          "anyOf": [
+            {
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "title": "Pr"
+        },
+        "handoff_state": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "title": "Handoff State"
+        },
+        "stamped_head": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "title": "Stamped Head"
+        },
+        "current_head": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "title": "Current Head"
+        },
+        "remediation": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "title": "Remediation"
+        }
+      },
+      "required": [
+        "kind",
+        "code",
+        "message",
+        "dependency_node_id",
+        "plan",
+        "pr",
+        "handoff_state",
+        "stamped_head",
+        "current_head",
+        "remediation"
+      ],
+      "title": "GateBlockerOut",
+      "type": "object"
+    },
     "LayerOut": {
       "additionalProperties": false,
       "properties": {
@@ -245,6 +368,10 @@
             }
           ],
           "title": "Expected Pr Base"
+        },
+        "handoff": {
+          "title": "Handoff",
+          "type": "string"
         }
       },
       "required": [
@@ -263,7 +390,8 @@
         "published_head_sha",
         "observed_remote_head_sha",
         "observed_pr_base",
-        "expected_pr_base"
+        "expected_pr_base",
+        "handoff"
       ],
       "title": "LayerOut",
       "type": "object"
@@ -406,6 +534,41 @@
       "title": "OrphanedResidueOut",
       "type": "object"
     },
+    "PlanningGateOut": {
+      "additionalProperties": false,
+      "description": "The composed planning-gate block (contracts.md \u00a78.46): the evaluated candidate\n(``None`` when no candidate exists), the technical-AND-handoff verdict for\nplanning/fresh starts, and the blocker rows.",
+      "properties": {
+        "node_id": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "title": "Node Id"
+        },
+        "ready": {
+          "title": "Ready",
+          "type": "boolean"
+        },
+        "blockers": {
+          "items": {
+            "$ref": "#/$defs/GateBlockerOut"
+          },
+          "title": "Blockers",
+          "type": "array"
+        }
+      },
+      "required": [
+        "node_id",
+        "ready",
+        "blockers"
+      ],
+      "title": "PlanningGateOut",
+      "type": "object"
+    },
     "TrainOut": {
       "additionalProperties": false,
       "properties": {
@@ -477,6 +640,14 @@
           "default": 0,
           "title": "Landed Prefix Len",
           "type": "integer"
+        },
+        "planning_gate": {
+          "$ref": "#/$defs/PlanningGateOut",
+          "default": {
+            "node_id": null,
+            "ready": false,
+            "blockers": []
+          }
         }
       },
       "required": [

package/shared/schemas/outputs/pr-land.schema.json

@@ -2,7 +2,7 @@
   "$defs": {
     "LandPrOut": {
       "additionalProperties": false,
-      "description": "The serialization boundary of the picked :class:`github.PullRequest` subset\n(field order load-bearing).",
+      "description": "The serialization boundary of :class:`delivery.LandResult.PrSummary`\n(field order load-bearing).",
       "properties": {
         "number": {
           "title": "Number",
@@ -22,7 +22,7 @@
     },
     "LearnConsumeOut": {
       "additionalProperties": false,
-      "description": "The serialization boundary of :class:`LearnConsumeUpdate` (field order load-bearing).",
+      "description": "The serialization boundary of :class:`delivery.LandResult.LearnUpdate`\n(field order load-bearing).",
       "properties": {
         "closed": {
           "items": {
@@ -52,7 +52,7 @@
     },
     "ObjectiveLandOut": {
       "additionalProperties": false,
-      "description": "The serialization boundary of :class:`ObjectiveLandUpdate` (field order load-bearing).\n\n``id`` maps from the domain ``objective`` field (the linked objective id).",
+      "description": "The serialization boundary of :class:`delivery.LandResult.ObjectiveUpdate`\n(field order load-bearing).\n\n``id`` maps from the domain ``objective`` field (the linked objective id).",
       "properties": {
         "id": {
           "anyOf": [

package/shared/schemas/outputs/pr-ready.schema.json

@@ -22,7 +22,7 @@
     }
   },
   "additionalProperties": false,
-  "description": "The ``--json`` serialization boundary of :class:`PrReadyResult` (order load-bearing).",
+  "description": "The ``--json`` serialization boundary of :class:`PrReadyResult` (order load-bearing \u2014\nthe nine continuation fields are tail-additive).\n\nNull semantics: dry-run \u2192 all nine continuation fields null; incremental \u2192\n``stacked=false``, rest null; stacked success \u2192 all populated (``reconcile_notice`` /\n``reconcile_retry`` are CLI-composed presentation: the ready-time reconcile pass was not\nlaunched \u2014 the worker never launches \u2014 plus the copyable re-run gesture; ``plan`` /\n``parent_checkpoint`` are the continuation evidence consumers compose the pinned diff\nrange from, contracts.md \u00a78.66).",
   "properties": {
     "success": {
       "title": "Success",
@@ -60,6 +60,105 @@
     "dry_run": {
       "title": "Dry Run",
       "type": "boolean"
+    },
+    "stacked": {
+      "anyOf": [
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "title": "Stacked"
+    },
+    "objective": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "title": "Objective"
+    },
+    "node": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "title": "Node"
+    },
+    "stamped_head": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "title": "Stamped Head"
+    },
+    "stamp_advanced": {
+      "anyOf": [
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "title": "Stamp Advanced"
+    },
+    "reconcile_notice": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "title": "Reconcile Notice"
+    },
+    "reconcile_retry": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "title": "Reconcile Retry"
+    },
+    "plan": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "title": "Plan"
+    },
+    "parent_checkpoint": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "title": "Parent Checkpoint"
     }
   },
   "required": [
@@ -68,7 +167,16 @@
     "message",
     "pr",
     "was_draft",
-    "dry_run"
+    "dry_run",
+    "stacked",
+    "objective",
+    "node",
+    "stamped_head",
+    "stamp_advanced",
+    "reconcile_notice",
+    "reconcile_retry",
+    "plan",
+    "parent_checkpoint"
   ],
   "title": "PrReadyOut",
   "type": "object"