@mgiles/perk 1.0.1 → 1.1.0

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)
@@ -175,7 +175,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 +194,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/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"
+}