@mgiles/perk 1.0.1 → 2.0.0

package/shared/providers.yaml

@@ -16,7 +16,8 @@
 #   id      — the stable provider id. NOT the cache.plan-ref `provider` string:
 #             that field is the ISSUE BACKEND (the stamped `backend_id`, e.g.
 #             "github"), not the seam id — see contracts.md §8.10 / §8.21.
-#   seam    — `plan` | `todo` | `askuser` | `footer` | `web` (the five seams pluggability-taxonomy.md scope-fenced).
+#   seam    — `plan` | `todo` | `askuser` | `footer` | `web` (the five seams; see
+#             pluggability-taxonomy.md for the scope fence).
 #   package — the foreign Pi package spec added to .pi/settings.json `packages`
 #             (e.g. "npm:@tombell/pi-plan"); `null` for perk's own bundled reference
 #             provider (nothing to add — perk produces the contract natively). NOT
@@ -95,6 +96,12 @@
 # is pi-web-access-specific (it depends on `fetch_content`'s GitHub-clone path) and is accepted as
 # lost under a foreign web selection. Fail-safe: any config-read error resolves to `pi-web-access`,
 # keeping today's behavior exactly.
+#
+# There is NO review seam: the two surface-named review doors (`/pr-review-terminal` — the hunk
+# terminal TUI; `/pr-review-browser` — the plannotator browser UI) are the selection (the command
+# IS the surface pick). The hunk CLI converges unconditionally (init/doctor's best-effort
+# `review-cli` install/verify); the plannotator package rides the plan seam's `plannotator-plan`
+# entry.
 
 schema_version: 1
 

package/shared/registry.yaml

@@ -27,7 +27,7 @@ state_keys:
     - comments        # discussion comments
     - review-threads  # review threads (distinct API from comments)
     - learn           # the perk:learn knowledge-capture issue (P2.T8b)
-  # Tier 2 · .pi/workflow/ — the local cache (see contracts.md §8.1).
+  # Tier 2 · .perk/workflow/ — the local cache (see contracts.md §8.1).
   cache:
     - plan            # materialized plan body cache
     - plan-ref        # provider-agnostic plan->branch ref (see contracts.md §8.4)
@@ -52,12 +52,11 @@ state_keys:
 # actual dedicated cold-door routing lives in code via `perk/cli/stages.py` `DEDICATED_STAGES`
 # (the generic launcher generator skips those ids). The field documents intent; it does not route.
 # `doors.cold_remote` records which stages a remote runner may run (cli-vs-pi §4.5) —
-# a real registry-recorded constraint, not merely "not built yet". P2.T8c flips it
-# `true` on `implement` + `address` (the agentic, headless-runnable stages a Phase-3 CI
-# worker drives); `plan`/`save` need interactive local exploration and
-# `submit`/`land`/`learn` are quick deterministic ops, so they stay `false`. Phase 2
-# *builds + resolves* the target (the resolver + this door + the --json descriptor);
-# Phase 3 *drives* it. Revisable in Phase 3.
+# a settled design decision, not merely "not built yet". It is `true` exactly on the
+# bounded agentic stages (`implement`, `address`), where the goal is already pinned by
+# a plan or by reviewer feedback. The interactive/exploratory stages (planning above
+# all) and the quick deterministic human-gate ops (`submit`/`land`/`learn`) are
+# local-only by design — review, merge, and judgment capture stay where a human is.
 # ---------------------------------------------------------------------------
 stages:
   - id: objective-author
@@ -129,7 +128,7 @@ stages:
     summary: Do the work on a branch (requires fresh context; cold-only).
     mode: read-write
     worktree: create          # first stage that needs a branch/worktree (folds in erk's `prepare`)
-    doors: { warm: false, cold_local: true, cold_remote: true }  # P2.T8c: a Phase-3 CI worker can run it
+    doors: { warm: false, cold_local: true, cold_remote: true }  # bounded agentic stage — remotely runnable
     run_id: { warm: keep, cold_local: mint, cold_remote: mint }
     command: implement
     requires: [cache.plan-ref]   # T4: cold door derives plan-<pr_id> from the active ref
@@ -155,7 +154,7 @@ stages:
     summary: Classify PR review feedback (isolated child) and resolve the threads.
     mode: read-write
     worktree: reuse
-    doors: { warm: true, cold_local: true, cold_remote: true }  # P2.T8c: a Phase-3 CI worker can run it
+    doors: { warm: true, cold_local: true, cold_remote: true }  # bounded agentic stage — remotely runnable
     run_id: { warm: keep, cold_local: mint, cold_remote: mint }
     command: pr address
     # P2.T7: a spawned read-only child (borrowed pi-subagents) fetches + classifies feedback;
@@ -175,7 +174,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]   # T5b merge+marker; T11a mechanical node-done
+    writes: [github.pr, cache.markers, github.objective, github.plan]   # T5b merge+marker; T11a mechanical node-done; §8.36 learn_state header stamp
     predecessors: [address]
     successors: [learn]
 
@@ -194,6 +193,6 @@ 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]  # clear marker; create learn issue + back-link
+    writes: [cache.markers, github.learn, github.comments, github.plan]  # clear marker; create learn issue + back-link; §8.36 learn_state header stamp
     predecessors: [land]
     successors: []

package/shared/schemas/contracts/bindings.schema.json

@@ -0,0 +1,38 @@
+{
+  "$defs": {
+    "BindingEntry": {
+      "description": "Tolerant parse shape for one stored ``bindings.yaml`` entry.\n\nLenient base: unknown keys dropped (``extra=\"ignore\"``); absent keys default to ``\"\"`` so\n``validate()`` reports them as content findings. A present non-string scalar is a genuine\ntype error and raises (translated to ``BindingsError`` at the load boundary).",
+      "properties": {
+        "trigger": {
+          "default": "",
+          "title": "Trigger",
+          "type": "string"
+        },
+        "skill": {
+          "default": "",
+          "title": "Skill",
+          "type": "string"
+        },
+        "mode": {
+          "default": "",
+          "title": "Mode",
+          "type": "string"
+        }
+      },
+      "title": "BindingEntry",
+      "type": "object"
+    }
+  },
+  "description": "Whole-file parse shape.\n\n``schema_version`` stays OUT of the model (a structural pre-check in ``load_bindings`` owns\nits byte-identical message; ``extra=\"ignore\"`` drops the key here). A non-list ``bindings:``\nraises.",
+  "properties": {
+    "bindings": {
+      "items": {
+        "$ref": "#/$defs/BindingEntry"
+      },
+      "title": "Bindings",
+      "type": "array"
+    }
+  },
+  "title": "BindingsFile",
+  "type": "object"
+}

package/shared/schemas/contracts/providers.schema.json

@@ -0,0 +1,89 @@
+{
+  "$defs": {
+    "ProviderEntry": {
+      "description": "The lenient per-entry parse model at the file boundary.\n\n``id``/``seam`` are typed ``str | None`` (not ``str = \"\"``) so an explicit YAML ``null`` parses\ncleanly; the converter normalizes ``None -> \"\"`` and ``validate()`` then surfaces the\nmissing-``id`` / bad-``seam`` content findings. Other fields coerce leniently (drop unknown\nkeys, coerce ordinary scalars) per the lenient base \u2014 content findings are the *validator*'s\njob, never construction's.",
+      "properties": {
+        "id": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Id"
+        },
+        "seam": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Seam"
+        },
+        "package": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Package"
+        },
+        "adapter": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Adapter"
+        },
+        "default": {
+          "type": "boolean",
+          "default": false,
+          "title": "Default"
+        },
+        "package_filter": {
+          "anyOf": [
+            {
+              "additionalProperties": true,
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Package Filter"
+        }
+      },
+      "title": "ProviderEntry",
+      "type": "object"
+    }
+  },
+  "description": "The lenient whole-file parse model.\n\n``schema_version`` is deliberately NOT a field: it stays a structural pre-check in\n``load_providers`` (it must run before generic validation and raise its own message).\n``extra=\"ignore\"`` drops it (and any other top-level key) from this model.",
+  "properties": {
+    "providers": {
+      "items": {
+        "$ref": "#/$defs/ProviderEntry"
+      },
+      "title": "Providers",
+      "type": "array"
+    }
+  },
+  "title": "ProvidersFile",
+  "type": "object"
+}

package/shared/schemas/contracts/registry.schema.json

@@ -0,0 +1,98 @@
+{
+  "$defs": {
+    "StageEntry": {
+      "description": "The lenient per-stage parse model at the file boundary.\n\nSame fields/defaults as the ``Stage`` domain dataclass; tolerant parsing\n(drop unknown keys, coerce ordinary scalars) per the lenient base.",
+      "properties": {
+        "id": {
+          "default": "",
+          "title": "Id",
+          "type": "string"
+        },
+        "summary": {
+          "default": "",
+          "title": "Summary",
+          "type": "string"
+        },
+        "mode": {
+          "default": "",
+          "title": "Mode",
+          "type": "string"
+        },
+        "worktree": {
+          "default": "",
+          "title": "Worktree",
+          "type": "string"
+        },
+        "doors": {
+          "additionalProperties": true,
+          "title": "Doors",
+          "type": "object"
+        },
+        "run_id": {
+          "additionalProperties": true,
+          "title": "Run Id",
+          "type": "object"
+        },
+        "command": {
+          "default": "",
+          "title": "Command",
+          "type": "string"
+        },
+        "requires": {
+          "items": {
+            "type": "string"
+          },
+          "title": "Requires",
+          "type": "array"
+        },
+        "reads": {
+          "items": {
+            "type": "string"
+          },
+          "title": "Reads",
+          "type": "array"
+        },
+        "writes": {
+          "items": {
+            "type": "string"
+          },
+          "title": "Writes",
+          "type": "array"
+        },
+        "predecessors": {
+          "items": {
+            "type": "string"
+          },
+          "title": "Predecessors",
+          "type": "array"
+        },
+        "successors": {
+          "items": {
+            "type": "string"
+          },
+          "title": "Successors",
+          "type": "array"
+        }
+      },
+      "title": "StageEntry",
+      "type": "object"
+    }
+  },
+  "description": "The lenient whole-file parse model.\n\n``schema_version`` is deliberately NOT a field: it stays a structural\npre-check in ``load_registry`` (it must run before generic validation and\nraise its own message). ``extra=\"ignore\"`` drops it (and any other top-level\nkey) from this model.",
+  "properties": {
+    "state_keys": {
+      "additionalProperties": true,
+      "title": "State Keys",
+      "type": "object"
+    },
+    "stages": {
+      "items": {
+        "$ref": "#/$defs/StageEntry"
+      },
+      "title": "Stages",
+      "type": "array"
+    }
+  },
+  "title": "RegistryFile",
+  "type": "object"
+}

package/shared/schemas/inputs/handoff-arg.schema.json

@@ -0,0 +1,6 @@
+{
+  "additionalProperties": true,
+  "description": "Minimal strict parse: the ``--handoff`` payload must be a JSON object.\n\nThe handoff is open-ended (cache ``HandoffModel`` is ``extra=\"allow\"``), so this only\nenforces the object shape (a list/scalar fails loudly with a field path).",
+  "title": "HandoffArgInput",
+  "type": "object"
+}

package/shared/schemas/inputs/resolve-threads-batch.schema.json

@@ -0,0 +1,37 @@
+{
+  "$defs": {
+    "ResolveThreadInput": {
+      "additionalProperties": false,
+      "description": "One strict batch item (`{thread_id, comment?}`); a typo/wrong type fails loudly.",
+      "properties": {
+        "thread_id": {
+          "title": "Thread Id",
+          "type": "string"
+        },
+        "comment": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "title": "Comment"
+        }
+      },
+      "required": [
+        "thread_id"
+      ],
+      "title": "ResolveThreadInput",
+      "type": "object"
+    }
+  },
+  "description": "The strict batch root: a JSON array of thread items (a non-array fails loudly).",
+  "items": {
+    "$ref": "#/$defs/ResolveThreadInput"
+  },
+  "title": "ResolveThreadsBatch",
+  "type": "array"
+}

package/shared/schemas/inputs/review-post-batch.schema.json

@@ -0,0 +1,84 @@
+{
+  "$defs": {
+    "ReviewCommentInput": {
+      "additionalProperties": false,
+      "description": "One inline review finding in the machine-authored batch (strict: a typo fails loudly).",
+      "properties": {
+        "path": {
+          "minLength": 1,
+          "title": "Path",
+          "type": "string"
+        },
+        "line": {
+          "title": "Line",
+          "type": "integer"
+        },
+        "body": {
+          "minLength": 1,
+          "title": "Body",
+          "type": "string"
+        }
+      },
+      "required": [
+        "path",
+        "line",
+        "body"
+      ],
+      "title": "ReviewCommentInput",
+      "type": "object"
+    }
+  },
+  "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).",
+  "properties": {
+    "verdict": {
+      "enum": [
+        "clean",
+        "actionable"
+      ],
+      "title": "Verdict",
+      "type": "string"
+    },
+    "summary": {
+      "minLength": 1,
+      "title": "Summary",
+      "type": "string"
+    },
+    "comments": {
+      "anyOf": [
+        {
+          "items": {
+            "$ref": "#/$defs/ReviewCommentInput"
+          },
+          "type": "array"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "Comments"
+    },
+    "fyi": {
+      "anyOf": [
+        {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "Fyi"
+    }
+  },
+  "required": [
+    "verdict",
+    "summary"
+  ],
+  "title": "ReviewBatchInput",
+  "type": "object"
+}

package/shared/schemas/inputs/review-submit-batch.schema.json

@@ -0,0 +1,66 @@
+{
+  "$defs": {
+    "ReviewSubmitCommentInput": {
+      "additionalProperties": false,
+      "description": "One inline comment in the machine-authored submission batch (strict: a typo fails loudly).\n\n`line` is **non-nullable** by design: unanchorable (`line: null`) findings are folded into\nthe review body upstream, during the triage curation \u2014 never submitted as inline comments.",
+      "properties": {
+        "path": {
+          "minLength": 1,
+          "title": "Path",
+          "type": "string"
+        },
+        "line": {
+          "title": "Line",
+          "type": "integer"
+        },
+        "side": {
+          "default": "RIGHT",
+          "enum": [
+            "LEFT",
+            "RIGHT"
+          ],
+          "title": "Side",
+          "type": "string"
+        },
+        "body": {
+          "minLength": 1,
+          "title": "Body",
+          "type": "string"
+        }
+      },
+      "required": [
+        "path",
+        "line",
+        "body"
+      ],
+      "title": "ReviewSubmitCommentInput",
+      "type": "object"
+    }
+  },
+  "additionalProperties": false,
+  "description": "The strict `review-submit` batch shape (`{body, comments?}` \u2014 the event rides the flag).\n\nNo `fyi` field: in-session triage color is structurally unpostable through this door\n(strict extra-forbid rejects it). `comments` stays nullable so an explicit `null` is\ntolerated, normalized to `[]` in conversion.",
+  "properties": {
+    "body": {
+      "default": "",
+      "title": "Body",
+      "type": "string"
+    },
+    "comments": {
+      "anyOf": [
+        {
+          "items": {
+            "$ref": "#/$defs/ReviewSubmitCommentInput"
+          },
+          "type": "array"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "Comments"
+    }
+  },
+  "title": "ReviewSubmitBatchInput",
+  "type": "object"
+}

package/shared/schemas/inputs/structured-roadmap-node.schema.json

@@ -0,0 +1,102 @@
+{
+  "$defs": {
+    "NodeStatus": {
+      "description": "A roadmap node's explicit status (open #3: never inferred from a PR column).",
+      "enum": [
+        "pending",
+        "planning",
+        "in_progress",
+        "done",
+        "blocked",
+        "skipped"
+      ],
+      "title": "NodeStatus",
+      "type": "string"
+    }
+  },
+  "additionalProperties": false,
+  "description": "Strict machine-input shape for one ``objective create --roadmap`` / ``objective_save`` node.\n\nMirrors the TS ``ROADMAP_PARAM_SCHEMA`` (``additionalProperties: false``): unknown keys fail\nloudly. ``status`` and ``depends_on`` are the only intentionally-coercing fields under the\notherwise-strict model (a raw enum value / a list of strings).",
+  "properties": {
+    "id": {
+      "title": "Id",
+      "type": "string"
+    },
+    "description": {
+      "title": "Description",
+      "type": "string"
+    },
+    "status": {
+      "$ref": "#/$defs/NodeStatus",
+      "default": "pending"
+    },
+    "slug": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "Slug"
+    },
+    "pr": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "Pr"
+    },
+    "depends_on": {
+      "anyOf": [
+        {
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "Depends On"
+    },
+    "comment": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "Comment"
+    },
+    "adopt_issue": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "Adopt Issue"
+    }
+  },
+  "required": [
+    "id",
+    "description"
+  ],
+  "title": "StructuredRoadmapNode",
+  "type": "object"
+}