@mgiles/perk 3.1.0 → 3.2.0

package/shared/registry.yaml

@@ -124,7 +124,7 @@ stages:
   - 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
@@ -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/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-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"