@mgiles/perk 1.1.0 → 2.1.0

package/prompts/stages/skills/create-from.md

@@ -1,4 +1,4 @@
-You are running perk skills create --from — authoring a NEW repo-specific skill seeded from a source document. Follow the perk-skill-author skill.
+You are running perk skills create --from — authoring a NEW repo-specific skill seeded from a source document. Follow the `perk-skill-author` skill (read `.agents/skills/perk-skill-author/SKILL.md`).
 
   1. The skill directory `{{ repo_skills_rel }}/{{ skill_name }}/` has already been scaffolded with a TODO `SKILL.md` at `{{ skill_path }}`. You will replace the scaffold, authoring the skill FROM the source below.
 {% if seed_url %}

package/prompts/stages/skills/create.md

@@ -1,4 +1,4 @@
-You are running perk skills create — authoring a NEW repo-specific skill. Follow the perk-skill-author skill.
+You are running perk skills create — authoring a NEW repo-specific skill. Follow the `perk-skill-author` skill (read `.agents/skills/perk-skill-author/SKILL.md`).
 
   1. The skill directory `{{ repo_skills_rel }}/{{ skill_name }}/` has already been scaffolded with a TODO `SKILL.md` at `{{ skill_path }}`. Open it and replace the scaffold.
   2. Author the skill: write a concrete, trigger-phrase `description` (the entire discovery surface — name the tasks/phrases, not a vague topic), keep `SKILL.md` lean and self-contained (heavy/reference material goes in sibling `references/`/`scripts/` files the delivery symlink carries for free), and validate the frontmatter (`name` must equal the directory segment `{{ skill_name }}`; `description` non-empty).

package/prompts/stages/skills/refine.md

@@ -1,4 +1,4 @@
-You are running perk skills refine — improving an EXISTING repo-specific skill. Follow the perk-skill-author skill.
+You are running perk skills refine — improving an EXISTING repo-specific skill. Follow the `perk-skill-author` skill (read `.agents/skills/perk-skill-author/SKILL.md`).
 
   1. Read the existing `SKILL.md` at `{{ skill_path }}` and the relevant repo context.
   2. Improve it in place: sharpen the `description` triggers (the entire discovery surface — name the tasks/phrases, not a vague topic), tighten/restructure the body, move heavy/reference material into sibling `references/`/`scripts/` files (the delivery symlink carries them for free), and re-validate the frontmatter (`name` must equal the directory segment `{{ skill_name }}`; `description` non-empty).

package/shared/README.md

@@ -3,33 +3,37 @@
 perk's language-neutral contracts, authored once and **bundled into both build
 artifacts** (the Python wheel as package data `perk/_shared/`; the npm package under
 `shared/`). Each plane reads its *own* bundled copy at runtime — no dependency on
-repo layout (`Q12`).
+repo layout.
 
-Contents (authored in **T2**):
+Contents:
 
 - **`registry.yaml`** — a *parsed* contract: the stage registry (descriptor
-  shape + the six MVP stages + graph) and the `state_keys` vocabulary. Read by both
-  planes (`perk/substrate/registry.py`, `extension/substrate/registry.ts`); validated by
+  shape + stages + graph) and the `state_keys` vocabulary. Read by both
+  planes (`src/perk/substrate/registry.py`, `extension/substrate/registry.ts`); validated by
   `perk registry check`.
 - **`bindings.yaml`** — the second *parsed* contract: the skill-binding set
   (trigger→skill delivery, with a per-binding `nudge`/`transclude` mode). Read by both
-  planes (`perk/substrate/bindings.py`, `extension/substrate/bindings.ts`); see `contracts.md` §8.9.
+  planes (`src/perk/substrate/bindings.py`, `extension/substrate/bindings.ts`); see `contracts.md` §8.9.
 - **`providers.yaml`** — the third *parsed* contract: the provider-selection supported
   set (the catalog of plan/todo/askuser/footer/web providers perk can wire, with each entry's `package` /
   `adapter` / `default` / optional `package_filter`). Read by both planes
-  (`perk/substrate/providers.py`, `extension/substrate/providers.ts`); see `contracts.md` §8.10.
-- **`contracts.md`** — the four *prose* specs implemented once per plane: the
+  (`src/perk/substrate/providers.py`, `extension/substrate/providers.ts`); see `contracts.md` §8.10.
+- **`contracts.md`** — the numbered *prose* contract sections (`§8.1`–`§8.38`,
+  non-contiguous: `§8.8` is skipped and `§8.6a` exists), each pinning the exact
+  names/paths/shapes both planes implement against. The founding four — the
   `.perk/workflow/` layout, the `PERK_RUN_ID` protocol, the `perk:workflow-state`
-  schema, and the GitHub gateway contract.
-- **`contracts-history.md`** — the relocated chronological `Status (…)` changelog
-  sibling of the prose spec, grouped by `§N.M` anchor (keeps `contracts.md` a compact
-  current-spec document).
-- **`schemas/`** — published JSON Schemas for perk's boundary models (the shared-YAML
-  parse contracts, the machine batch inputs, and the `--json` output envelopes),
-  generated from the Pydantic models in `perk/boundary.py` and grouped by role under
-  `contracts/` / `inputs/` / `outputs/`. Reference artifacts bundled into both planes
-  but read at runtime by neither; guarded against drift by
-  `tests/test_contract_schemas.py`. See `contracts.md` §8.34.
+  schema, and the GitHub gateway contract — were the original seed, not the current
+  inventory.
+- **`contracts-history.md`** — the chronological `Status (…)` changelog sibling of the
+  prose spec, grouped by `§N.M` anchor (keeps `contracts.md` a compact current-spec
+  document).
+- **`schemas/`** — committed **golden snapshots** of perk's boundary models (the
+  shared-YAML parse contracts, the machine batch inputs, and the `--json` output
+  envelopes), generated from the Pydantic models in `perk/boundary.py` and grouped by
+  role under `contracts/` / `inputs/` / `outputs/`. Their function is making
+  machine-surface shape changes reviewable in PRs: bundled into both artifacts, read at
+  runtime by neither, drift-guarded by `tests/test_contract_schemas.py`. See
+  `contracts.md` §8.34.
 
-Resolution is proven by T1's per-plane resolvers (`perk/_resources.py`,
+Resolution goes through the per-plane resolvers (`src/perk/_resources.py`,
 `extension/substrate/resources.ts`): installed bundle → editable repo-sibling fallback.

package/shared/bindings.yaml

@@ -20,8 +20,10 @@
 #   trigger — the "<kind>:<id>" string above.
 #   skill   — the skill name (a skills/*/ dir name today).
 #   mode    — per-binding delivery mode:
-#               nudge      — deliver a short pointer to follow the named skill (the skill
-#                            body stays ambient / Pi-discovered).
+#               nudge      — deliver a short pointer to follow the named skill. The pointer
+#                            carries the skill's read path (.agents/skills/<skill>/SKILL.md):
+#                            perk's own stage skills are hidden from the ambient system prompt
+#                            (disable-model-invocation: true) and are reached only through it.
 #               transclude — inline the skill body into the prompt/context.
 #             mode is per-binding (not global): one skill may be a nudge at one trigger
 #             and a transclude at another.
@@ -68,6 +70,12 @@ bindings:
   - trigger: "command:pr-review"
     skill: perk-pr-review
     mode: nudge
+  - trigger: "command:pr-review-terminal"
+    skill: perk-pr-review-terminal
+    mode: nudge
+  - trigger: "command:pr-review-browser"
+    skill: perk-pr-review-browser
+    mode: nudge
   - trigger: "command:skills-create"
     skill: perk-skill-author
     mode: nudge

package/shared/contracts-history.md

@@ -401,6 +401,30 @@ bundled — the Python wheel as package data `perk/_shared/`, the npm package un
 > selection** — it is pi-web-access-specific (it depends on `fetch_content`'s GitHub-clone path),
 > documented and not re-homed. Catalog entries carry no `package_filter` (each package's sole
 > extension is its root `./index.ts`, verified via `npm view <pkg> pi`).
+>
+> **Status (review — the sixth seam, the first DISPATCH seam; RETIRED 2026-07, Objective #1261
+> Node 4.1):** a sixth seam, **`review`**, existed from the toolbox objective's nodes 1.x through
+> 4.1 and is now **retired**. Its shape while live: the first **DISPATCH posture** — no adapter
+> (the seam produces no durable artifact) and nothing to vacate (perk owned no prior guest-review
+> surface); the selection drove **protocol dispatch** inside a dispatching `/review` door — which
+> review surface the door drove (`hunk`, the default: the hunk session CLI handshake, with perk's
+> `submit_pr_review` tool as the only posting path; or `plannotator-review`: the `code-review`
+> `pi.events` bridge behind an `open_plannotator_review` tool plus the agent-driven
+> external-annotations HTTP stream, with the UI's native platform-posting as the GitHub path) and
+> which posting path was primary. The default `hunk` was the first `default: true` entry whose
+> substrate is an **external CLI** (npm `hunkdiff`) rather than a Pi package;
+> `plannotator-review` shared `npm:@plannotator/pi-extension` with `plannotator-plan`, the
+> cross-seam instance of the desired-**union** package convergence. **The retirement (Node 4.1):**
+> once the surface-named doors (`/pr-review-terminal`, `/pr-review-browser`) absorbed both arms
+> (nodes 2.1–3.1), the dispatch had no job left — the command IS the selection. `/review`, its
+> dispatch, `open_plannotator_review`, and the seam rows were deleted; `SEAMS`/`PROVIDER_SEAMS`
+> shrank back to five; the retired `[providers] review` key got the legacy-tripwire treatment
+> (hard-fail on the Python plane, silent-ignore on the TS plane); the hunk-CLI init/doctor
+> handling was already unconditional (a review *surface*, not a selection consequence) and is
+> unchanged; the plannotator package is desired via `plannotator-plan` alone (the union mechanism
+> stays generic, its only cross-seam instance retired). `submit_pr_review` re-homed to
+> `extension/doors/submitPrReview.ts` with an unchanged contract; the `perk-review` skill split
+> into `perk-pr-review-terminal` + `perk-pr-review-browser`.
 
 ## §8.31 · The prompt render seam + golden parity (Objective #791, Node 1.2)