@mgiles/perk 3.2.0 → 3.3.0

package/shared/fixtures/issues-table.json

@@ -0,0 +1,130 @@
+{
+  "description": "Perk TOML documents paired with the `[issues] backend`/`team` values the TS subset reader yields (`expected`: extension/substrate/config.ts::resolveIssueDestination via parseTomlSubset — stripped, blank/non-string/absent → null) and whether that read is provably tomllib's (`provable`: resolveIssueRouting reads `keys`; otherwise the save-destination fence widens to the whole `document`). When Python's tomllib reads something else, `tomllib` carries its reading — every such case MUST be unproven. contracts.md §8.23.",
+  "cases": [
+    {
+      "name": "basic strings",
+      "toml": "[issues]\nbackend = \"linear\"\nteam = \"ENG\"\n",
+      "expected": { "backend": "linear", "team": "ENG" },
+      "provable": true
+    },
+    {
+      "name": "literal strings",
+      "toml": "[issues]\nbackend = 'linear'\nteam = 'ENG'\n",
+      "expected": { "backend": "linear", "team": "ENG" },
+      "provable": true
+    },
+    {
+      "name": "multi-line basic strings (unproven: the subset's escape handling is not tomllib's)",
+      "toml": "[issues]\nbackend = \"\"\"linear\"\"\"\nteam = \"\"\"\nENG\"\"\"\n",
+      "expected": { "backend": "linear", "team": "ENG" },
+      "provable": false
+    },
+    {
+      "name": "multi-line literal strings (unproven: only single-line strings are vouched for)",
+      "toml": "[issues]\nbackend = '''linear'''\nteam = '''\nENG'''\n",
+      "expected": { "backend": "linear", "team": "ENG" },
+      "provable": false
+    },
+    {
+      "name": "literal strings keep backslashes verbatim",
+      "toml": "[issues]\nbackend = 'github'\nteam = 'C:\\ENG'\n",
+      "expected": { "backend": "github", "team": "C:\\ENG" },
+      "provable": true
+    },
+    {
+      "name": "inline comments after the strings",
+      "toml": "[issues]\nbackend = \"linear\" # committed\nteam = 'ENG' # the team key\n",
+      "expected": { "backend": "linear", "team": "ENG" },
+      "provable": true
+    },
+    {
+      "name": "surrounding whitespace is stripped (StrippedStr)",
+      "toml": "[issues]\nbackend = \" linear \"\nteam = '  ENG'\n",
+      "expected": { "backend": "linear", "team": "ENG" },
+      "provable": true
+    },
+    {
+      "name": "blank strings read as absent (StrippedStr)",
+      "toml": "[issues]\nbackend = \"\"\nteam = '   '\n",
+      "expected": { "backend": null, "team": null },
+      "provable": true
+    },
+    {
+      "name": "other keys in the table and other tables around it",
+      "toml": "[workflow]\nbase = \"main\"\n\n[issues]\nlabel = \"perk\"\nbackend = \"github\"\n\n[models.stages.plan]\nmodel = \"x\"\n\n[[ci.checks]]\nname = \"t\"\ncommand = \"\"\"\njust test\n\"\"\"\n",
+      "expected": { "backend": "github", "team": null },
+      "provable": true
+    },
+    {
+      "name": "absent table",
+      "toml": "[workflow]\nbase = \"main\"\n",
+      "expected": { "backend": null, "team": null },
+      "provable": true
+    },
+    {
+      "name": "absent key",
+      "toml": "[issues]\nbackend = \"github\"\n",
+      "expected": { "backend": "github", "team": null },
+      "provable": true
+    },
+    {
+      "name": "non-string values (unproven: Python's boundary rejects them outright)",
+      "toml": "[issues]\nbackend = true\nteam = 42\n",
+      "expected": { "backend": null, "team": null },
+      "provable": false
+    },
+    {
+      "name": "empty document",
+      "toml": "",
+      "expected": { "backend": null, "team": null },
+      "provable": true
+    },
+    {
+      "name": "dotted keys (unproven: the subset reader never sees them)",
+      "toml": "issues.backend = \"linear\"\nissues.team = \"ENG\"\n",
+      "expected": { "backend": null, "team": null },
+      "tomllib": { "backend": "linear", "team": "ENG" },
+      "provable": false
+    },
+    {
+      "name": "inline table (unproven: the subset reader never sees it)",
+      "toml": "issues = { backend = \"linear\", team = \"ENG\" }\n",
+      "expected": { "backend": null, "team": null },
+      "tomllib": { "backend": "linear", "team": "ENG" },
+      "provable": false
+    },
+    {
+      "name": "quoted header (unproven: quoted segments can spell any key)",
+      "toml": "[\"issues\"]\nbackend = \"linear\"\nteam = \"ENG\"\n",
+      "expected": { "backend": null, "team": null },
+      "tomllib": { "backend": "linear", "team": "ENG" },
+      "provable": false
+    },
+    {
+      "name": "header with a trailing comment (unproven: the subset reader skips that header)",
+      "toml": "[issues] # routing\nbackend = \"linear\"\n",
+      "expected": { "backend": null, "team": null },
+      "tomllib": { "backend": "linear", "team": null },
+      "provable": false
+    },
+    {
+      "name": "unicode escape (unproven: the subset reader keeps the escape verbatim)",
+      "toml": "[issues]\nbackend = \"\\u0067ithub\"\n",
+      "expected": { "backend": "\\u0067ithub", "team": null },
+      "tomllib": { "backend": "github", "team": null },
+      "provable": false
+    },
+    {
+      "name": "sub-table (unproven: a super-table the subset reader keeps flat)",
+      "toml": "[issues.extra]\nkey = \"x\"\n",
+      "expected": { "backend": null, "team": null },
+      "provable": false
+    },
+    {
+      "name": "array of tables (unproven: tomllib reads a list, never the table)",
+      "toml": "[[issues]]\nbackend = \"linear\"\n",
+      "expected": { "backend": null, "team": null },
+      "provable": false
+    }
+  ]
+}

package/shared/registry.yaml

@@ -251,6 +251,19 @@ stages:
     predecessors: []          # a deliberately isolated node — the dev-only audit component
     successors: []
 
+  - id: objective-refine
+    summary: Author an advisory refinement of a future objective node and save it as the node's marked comment (read-only).
+    mode: read-only
+    worktree: none            # explores the invoking checkout as-is (dirty changes included); never provisions a predecessor checkout
+    doors: { warm: true, cold_local: true, cold_remote: false }  # interactive local authoring (perk objective refine + /objective-refine)
+    run_id: { warm: keep, cold_local: mint, cold_remote: mint }
+    command: objective refine  # dedicated seeded cold door + the warm /objective-refine command
+    requires: [github.objective]                       # an objective with a refinable future node must exist
+    reads: [github.objective, github.comments]         # target selection + the node's existing marked refinement comment
+    writes: [github.comments, session.workflow-state, cache.session-data, cache.scratch]  # the approved/human-authorized refinement comment upsert; the read-only `mode` append; objective_refinement_draft + the imported context artifact; run scratch
+    predecessors: []          # a deliberately isolated node — refinement never enters the executable plan graph (contracts.md §8.67)
+    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

package/shared/schemas/outputs/objective-node-engagement.schema.json

@@ -0,0 +1,318 @@
+{
+  "$defs": {
+    "DescriptionEditOut": {
+      "additionalProperties": false,
+      "description": "One node-issue description edit; ``diff`` is untrusted DATA (null when the backend\nexposes no inline diff).",
+      "properties": {
+        "created_at": {
+          "title": "Created At",
+          "type": "string"
+        },
+        "author": {
+          "$ref": "#/$defs/EngagementAuthorOut"
+        },
+        "diff": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "title": "Diff"
+        }
+      },
+      "required": [
+        "created_at",
+        "author",
+        "diff"
+      ],
+      "title": "DescriptionEditOut",
+      "type": "object"
+    },
+    "EngagementAuthorOut": {
+      "additionalProperties": false,
+      "description": "The classified author of one engagement item (``kind`` + best-available label/id).",
+      "properties": {
+        "kind": {
+          "enum": [
+            "human",
+            "perk",
+            "other_agent",
+            "unknown"
+          ],
+          "title": "Kind",
+          "type": "string"
+        },
+        "display_name": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "title": "Display Name"
+        },
+        "id": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "title": "Id"
+        }
+      },
+      "required": [
+        "kind",
+        "display_name",
+        "id"
+      ],
+      "title": "EngagementAuthorOut",
+      "type": "object"
+    },
+    "EngagementCommentOut": {
+      "additionalProperties": false,
+      "description": "One node-issue comment; ``body`` is untrusted DATA.",
+      "properties": {
+        "id": {
+          "title": "Id",
+          "type": "string"
+        },
+        "body": {
+          "title": "Body",
+          "type": "string"
+        },
+        "created_at": {
+          "title": "Created At",
+          "type": "string"
+        },
+        "edited_at": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "title": "Edited At"
+        },
+        "author": {
+          "$ref": "#/$defs/EngagementAuthorOut"
+        }
+      },
+      "required": [
+        "id",
+        "body",
+        "created_at",
+        "edited_at",
+        "author"
+      ],
+      "title": "EngagementCommentOut",
+      "type": "object"
+    },
+    "NodeContextWarningOut": {
+      "additionalProperties": false,
+      "description": "One advisory failure: the ``surface`` that failed, a stable ``code``, a human\n``message``, and the carrier comment ids the outcome rests on.",
+      "properties": {
+        "surface": {
+          "enum": [
+            "engagement",
+            "refinement"
+          ],
+          "title": "Surface",
+          "type": "string"
+        },
+        "code": {
+          "title": "Code",
+          "type": "string"
+        },
+        "message": {
+          "title": "Message",
+          "type": "string"
+        },
+        "comment_ids": {
+          "items": {
+            "type": "string"
+          },
+          "title": "Comment Ids",
+          "type": "array"
+        }
+      },
+      "required": [
+        "surface",
+        "code",
+        "message",
+        "comment_ids"
+      ],
+      "title": "NodeContextWarningOut",
+      "type": "object"
+    },
+    "NodeRefinementPresentOut": {
+      "additionalProperties": false,
+      "description": "A saved refinement was read, rendered and written: ``file`` points at the full dated\n``<untrusted_node_refinement>`` block under the run scratch dir.",
+      "properties": {
+        "status": {
+          "const": "present",
+          "title": "Status",
+          "type": "string"
+        },
+        "file": {
+          "$ref": "#/$defs/TextFileRefOut"
+        }
+      },
+      "required": [
+        "status",
+        "file"
+      ],
+      "title": "NodeRefinementPresentOut",
+      "type": "object"
+    },
+    "NodeRefinementStatusOut": {
+      "additionalProperties": false,
+      "description": "No refinement pointer: none is saved (``absent``), the backend has no refinement read\n(``unsupported``), or the read/snapshot failed (``unavailable`` \u2014 see ``warnings``).",
+      "properties": {
+        "status": {
+          "enum": [
+            "absent",
+            "unsupported",
+            "unavailable"
+          ],
+          "title": "Status",
+          "type": "string"
+        }
+      },
+      "required": [
+        "status"
+      ],
+      "title": "NodeRefinementStatusOut",
+      "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 ``--json`` serialization boundary of a snapshotted :class:`NodeContext` (field order\nload-bearing; the pre-existing keys come first). ``refinement`` is discriminated on\n``status``: ``present`` always carries a ``file`` pointer \u2014 the file is on disk.",
+  "properties": {
+    "success": {
+      "title": "Success",
+      "type": "boolean"
+    },
+    "error_type": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "title": "Error Type"
+    },
+    "objective": {
+      "title": "Objective",
+      "type": "string"
+    },
+    "node": {
+      "title": "Node",
+      "type": "string"
+    },
+    "comments": {
+      "items": {
+        "$ref": "#/$defs/EngagementCommentOut"
+      },
+      "title": "Comments",
+      "type": "array"
+    },
+    "description_edits": {
+      "items": {
+        "$ref": "#/$defs/DescriptionEditOut"
+      },
+      "title": "Description Edits",
+      "type": "array"
+    },
+    "engagement_status": {
+      "enum": [
+        "present",
+        "absent",
+        "unavailable"
+      ],
+      "title": "Engagement Status",
+      "type": "string"
+    },
+    "refinement": {
+      "discriminator": {
+        "mapping": {
+          "absent": "#/$defs/NodeRefinementStatusOut",
+          "present": "#/$defs/NodeRefinementPresentOut",
+          "unavailable": "#/$defs/NodeRefinementStatusOut",
+          "unsupported": "#/$defs/NodeRefinementStatusOut"
+        },
+        "propertyName": "status"
+      },
+      "oneOf": [
+        {
+          "$ref": "#/$defs/NodeRefinementPresentOut"
+        },
+        {
+          "$ref": "#/$defs/NodeRefinementStatusOut"
+        }
+      ],
+      "title": "Refinement"
+    },
+    "warnings": {
+      "items": {
+        "$ref": "#/$defs/NodeContextWarningOut"
+      },
+      "title": "Warnings",
+      "type": "array"
+    }
+  },
+  "required": [
+    "success",
+    "error_type",
+    "objective",
+    "node",
+    "comments",
+    "description_edits",
+    "engagement_status",
+    "refinement",
+    "warnings"
+  ],
+  "title": "ObjectiveNodeEngagementOut",
+  "type": "object"
+}

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": [

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"