@mgiles/perk 3.1.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

@@ -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,31 @@ 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: 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
+                              # 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-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"
+}