@mgiles/perk 3.1.0 → 3.3.0

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

@@ -2,7 +2,7 @@
   "$defs": {
     "ContinuationOut": {
       "additionalProperties": false,
-      "description": "This lineage's pending sync-continuation manifest (contracts.md \u00a78.44/\u00a78.49) \u2014 a\nmachine-local CLI-side observation. ``parseable: false`` rows carry nulls for every\nfield the unreadable file cannot account for.",
+      "description": "This lineage's pending sync-continuation manifest (contracts.md \u00a78.44/\u00a78.49) \u2014 a\nmachine-local CLI-side observation. ``parseable: false`` rows carry nulls for every\nfield the unreadable file cannot account for. ``targets_contained`` is additive trailing\ngrowth (\u00a78.44/\u00a78.51): whether the manifest's named targets pass the canonical\n``continuation.validated_targets`` containment validation against the configured worktree\nroot \u2014 the warm conflict dispatch requires it ``true`` (version skew fails closed: an\nolder CLI omits the field and the warm side refuses to dispatch).",
       "properties": {
         "operation_id": {
           "anyOf": [
@@ -66,6 +66,11 @@
         "parseable": {
           "title": "Parseable",
           "type": "boolean"
+        },
+        "targets_contained": {
+          "default": false,
+          "title": "Targets Contained",
+          "type": "boolean"
         }
       },
       "required": [
@@ -123,6 +128,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 +373,10 @@
             }
           ],
           "title": "Expected Pr Base"
+        },
+        "handoff": {
+          "title": "Handoff",
+          "type": "string"
         }
       },
       "required": [
@@ -263,7 +395,8 @@
         "published_head_sha",
         "observed_remote_head_sha",
         "observed_pr_base",
-        "expected_pr_base"
+        "expected_pr_base",
+        "handoff"
       ],
       "title": "LayerOut",
       "type": "object"
@@ -406,6 +539,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 +645,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"

package/shared/schemas/outputs/pr-review-context.schema.json

@@ -1,6 +1,45 @@
 {
+  "$defs": {
+    "DiffSource": {
+      "enum": [
+        "github",
+        "local-git"
+      ],
+      "type": "string"
+    },
+    "TextFileRefOut": {
+      "additionalProperties": false,
+      "description": "One materialized text section: its absolute ``path`` plus the sizes a reviewer pages\nagainst \u2014 ``max_line_bytes`` is the longest line's UTF-8 length (compared against Pi's\nper-line ``read`` bound to pick the byte-slice fallback).",
+      "properties": {
+        "path": {
+          "title": "Path",
+          "type": "string"
+        },
+        "bytes": {
+          "title": "Bytes",
+          "type": "integer"
+        },
+        "lines": {
+          "title": "Lines",
+          "type": "integer"
+        },
+        "max_line_bytes": {
+          "title": "Max Line Bytes",
+          "type": "integer"
+        }
+      },
+      "required": [
+        "path",
+        "bytes",
+        "lines",
+        "max_line_bytes"
+      ],
+      "title": "TextFileRefOut",
+      "type": "object"
+    }
+  },
   "additionalProperties": false,
-  "description": "The ``--json`` serialization boundary of :class:`PrReviewContextResult`\n(flat; field order load-bearing). ``pr`` maps from the domain ``pr_number``.",
+  "description": "The ``--json`` serialization boundary of :class:`PrReviewContextResult` \u2014 a pointer\nenvelope (field order load-bearing). ``pr`` maps from the domain ``pr_number``; ``body``,\n``diff`` and ``plan_body`` are file references into ``context_dir`` (in stack mode they\nalias the LAST ``stack[]`` member's files \u2014 the top PR's text is written once).",
   "properties": {
     "success": {
       "title": "Success",
@@ -48,24 +87,28 @@
       "title": "Title",
       "type": "string"
     },
-    "body": {
-      "title": "Body",
+    "context_dir": {
+      "title": "Context Dir",
       "type": "string"
     },
+    "body": {
+      "$ref": "#/$defs/TextFileRefOut"
+    },
     "diff": {
-      "title": "Diff",
-      "type": "string"
+      "$ref": "#/$defs/TextFileRefOut"
     },
     "plan_body": {
       "anyOf": [
         {
-          "type": "string"
+          "$ref": "#/$defs/TextFileRefOut"
         },
         {
           "type": "null"
         }
-      ],
-      "title": "Plan Body"
+      ]
+    },
+    "diff_source": {
+      "$ref": "#/$defs/DiffSource"
     }
   },
   "required": [
@@ -77,9 +120,11 @@
     "base_ref",
     "head_ref",
     "title",
+    "context_dir",
     "body",
     "diff",
-    "plan_body"
+    "plan_body",
+    "diff_source"
   ],
   "title": "PrReviewContextOut",
   "type": "object"

package/shared/schemas/outputs/pr-review-stack-context.schema.json

@@ -0,0 +1,196 @@
+{
+  "$defs": {
+    "DiffSource": {
+      "enum": [
+        "github",
+        "local-git"
+      ],
+      "type": "string"
+    },
+    "StackContextMemberOut": {
+      "additionalProperties": false,
+      "description": "One ``stack[]`` per-member section (bottom\u2192top order); text fields are file references\nunder ``context_dir/stack/<pr>/``.",
+      "properties": {
+        "pr": {
+          "title": "Pr",
+          "type": "integer"
+        },
+        "base_ref": {
+          "title": "Base Ref",
+          "type": "string"
+        },
+        "head_ref": {
+          "title": "Head Ref",
+          "type": "string"
+        },
+        "title": {
+          "title": "Title",
+          "type": "string"
+        },
+        "body": {
+          "$ref": "#/$defs/TextFileRefOut"
+        },
+        "diff": {
+          "$ref": "#/$defs/TextFileRefOut"
+        },
+        "plan_body": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/TextFileRefOut"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "diff_source": {
+          "$ref": "#/$defs/DiffSource"
+        }
+      },
+      "required": [
+        "pr",
+        "base_ref",
+        "head_ref",
+        "title",
+        "body",
+        "diff",
+        "plan_body",
+        "diff_source"
+      ],
+      "title": "StackContextMemberOut",
+      "type": "object"
+    },
+    "TextFileRefOut": {
+      "additionalProperties": false,
+      "description": "One materialized text section: its absolute ``path`` plus the sizes a reviewer pages\nagainst \u2014 ``max_line_bytes`` is the longest line's UTF-8 length (compared against Pi's\nper-line ``read`` bound to pick the byte-slice fallback).",
+      "properties": {
+        "path": {
+          "title": "Path",
+          "type": "string"
+        },
+        "bytes": {
+          "title": "Bytes",
+          "type": "integer"
+        },
+        "lines": {
+          "title": "Lines",
+          "type": "integer"
+        },
+        "max_line_bytes": {
+          "title": "Max Line Bytes",
+          "type": "integer"
+        }
+      },
+      "required": [
+        "path",
+        "bytes",
+        "lines",
+        "max_line_bytes"
+      ],
+      "title": "TextFileRefOut",
+      "type": "object"
+    }
+  },
+  "additionalProperties": false,
+  "description": "The ``--stack`` envelope: the single-PR fields (describing the top PR) plus the\nadditive per-member sections and the combined-diff reference. A separate model so\nnon-stack calls stay byte-identical (no null stack keys).",
+  "properties": {
+    "success": {
+      "title": "Success",
+      "type": "boolean"
+    },
+    "error_type": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "title": "Error Type"
+    },
+    "message": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "title": "Message"
+    },
+    "branch": {
+      "title": "Branch",
+      "type": "string"
+    },
+    "pr": {
+      "title": "Pr",
+      "type": "integer"
+    },
+    "base_ref": {
+      "title": "Base Ref",
+      "type": "string"
+    },
+    "head_ref": {
+      "title": "Head Ref",
+      "type": "string"
+    },
+    "title": {
+      "title": "Title",
+      "type": "string"
+    },
+    "context_dir": {
+      "title": "Context Dir",
+      "type": "string"
+    },
+    "body": {
+      "$ref": "#/$defs/TextFileRefOut"
+    },
+    "diff": {
+      "$ref": "#/$defs/TextFileRefOut"
+    },
+    "plan_body": {
+      "anyOf": [
+        {
+          "$ref": "#/$defs/TextFileRefOut"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "diff_source": {
+      "$ref": "#/$defs/DiffSource"
+    },
+    "stack": {
+      "items": {
+        "$ref": "#/$defs/StackContextMemberOut"
+      },
+      "title": "Stack",
+      "type": "array"
+    },
+    "combined_diff": {
+      "$ref": "#/$defs/TextFileRefOut"
+    }
+  },
+  "required": [
+    "success",
+    "error_type",
+    "message",
+    "branch",
+    "pr",
+    "base_ref",
+    "head_ref",
+    "title",
+    "context_dir",
+    "body",
+    "diff",
+    "plan_body",
+    "diff_source",
+    "stack",
+    "combined_diff"
+  ],
+  "title": "PrReviewStackContextOut",
+  "type": "object"
+}