@mgiles/perk 2.1.0 → 2.3.0

package/shared/contracts.md

@@ -1,7 +1,7 @@
 # perk cross-plane contracts
 
 The language-neutral contracts both planes obey, authored once here and bundled into each
-build artifact. This document holds the numbered **prose contract sections** (`§8.1`–`§8.40`,
+build artifact. This document holds the numbered **prose contract sections** (`§8.1`–`§8.41`,
 non-contiguous: `§8.8` is skipped and `§8.6a` exists; no parser): the Python CLI (`perk`)
 and the TS extension (`@mgiles/perk`) each implement one side, against the exact names/paths/
 fields pinned in each section. `perk doctor` verifies conformance. The numbering convention:
@@ -336,7 +336,7 @@ end of the section).
 | `active_plan_ref` | object \| null | the provider-agnostic plan ref (§8.4); null during early `plan` |
 | `active_objective` | string \| null | the active objective id (`/objective <id>` sets it, `/objective clear` nulls it) |
 | `last_review_batch` | object \| null | the last processed review batch: `{ pr, counts:{actionable,informational,praise,question}, resolved_thread_ids:[…], at:ISO }` |
-| `last_pr_review` | object \| null | the last `/pr-review` outcome posted via the warm `post_pr_review` tool: `{ pr, verdict, angles, comment_count, mode, at:ISO }`; best-effort tier (the PR review is the canonical record) |
+| `last_pr_review` | object \| null | the last `/pr-review` (or the experimental `/pr-review-dynamic`) outcome posted via the shared warm `post_pr_review` tool: `{ pr, verdict, angles, comment_count, mode, at:ISO }`; best-effort tier (the PR review is the canonical record) |
 | `last_review` | object \| null | the last review-door outcome posted via the warm `submit_pr_review` tool: `{ pr, event, comment_count, mode, at:ISO }`; best-effort tier (the submitted PR review is the canonical record) |
 | `session_artifacts` | object \| null | per-name session-artifact provenance pointers `{run_id, name, path, digest, at}` (§8.1); appends carry the **whole merged map** (per-field LWW); strict-append tier |
 | `objective_node_claim` | object \| null | the objective node this session has claimed `planning` (`{ objective, node }`); written by the warm `objective_node` tool on a successful `planning` transition, cleared on a successful non-planning transition for the same node and after a successful node-linked plan save; best-effort tier (cheaply reconstructable; loud-but-non-fatal) |
@@ -386,9 +386,12 @@ swallowed**: a failed advance shows a visible `⚠ … NOT advanced — re-run /
 **Tool gating.** The `mode` field **structurally gates tools** — enforcement, not prompting. When
 `mode == "read-only"` the interior (`extension/substrate/toolGating.ts`): (1) restricts the
 active tool set to `READ_ONLY_TOOLS` (`read`/`grep`/`find`/`ls`/`bash` + `ask_user_question` +
-`plan_review` + the `plan_draft`/`objective_draft` session-data carve-outs + `objective_node`
+`plan_review` + the `plan_draft`/`objective_draft`/`gist_draft` session-data carve-outs + `objective_node`
 (delegates a bounded node transition to the canonical Python plane) + the **`web` seam**
-providers' research tools, the read-only Linear tools, and the pi-subagents delegation family
+providers' research tools, the read-only Linear tools, the pi-fff search family (both mode
+name-sets — `fffind`/`ffgrep`/`fff-multi-grep` + override's `multi_grep`; the override names
+`find`/`grep` are already present — local search belongs in read-only exploration, and FFF's
+frecency state lives under `~/.pi/agent/fff/`, outside the worktree), and the pi-subagents delegation family
 (`subagent`/`wait` + the parent supervisor pair — the gated objective-plan explorer spawn must be
 reachable; **accepted no-backstop posture**: spawned children are unscoped by design (§8.40
 adopt-never-impersonates) — the explorer's agent def is write-blocked by its `tools` frontmatter,
@@ -470,10 +473,10 @@ session-lifecycle gates + the warm `/implement` handoff (`extension/doors/lifecy
 adapter (`extension/factories/planMode.ts`, `extension/adapters/todoAdapterJuicesharp.ts`; §8.10
 owns the provider seams); in-process read-only child sessions
 (`extension/worker/readOnlySession.ts`); the read-only CI executor
-(`extension/doors/ciExecutor.ts`); the spawned delegation seam + `/address` + `/pr-review` + `/pr-review-terminal` + `/pr-review-browser`
-(`extension/doors/address.ts` / `prReview.ts` / `prReviewTerminal.ts` /
+(`extension/doors/ciExecutor.ts`); the spawned delegation seam + `/address` + `/pr-review` + `/pr-review-dynamic` + `/pr-review-terminal` + `/pr-review-browser`
+(`extension/doors/address.ts` / `prReview.ts` / `prReviewDynamic.ts` / `prReviewTerminal.ts` /
 `prReviewBrowser.ts` / `submitPrReview.ts` / `hunkHandoff.ts` / `plannotatorHandoff.ts`, `agents/*.md`, `skills/perk-address/` /
-`perk-pr-review/` / `perk-pr-review-terminal/` / `perk-pr-review-browser/`; the gateway op shapes stay in §8.4); the conflict-resolution drive
+`perk-pr-review/` / `perk-pr-review-dynamic/` / `perk-pr-review-terminal/` / `perk-pr-review-browser/`; the gateway op shapes stay in §8.4); the conflict-resolution drive
 (`extension/doors/submit.ts`; the probe contract stays in §8.4).
 
 
@@ -687,6 +690,11 @@ add_pr_reaction{ pr_number }                        -> void
     # failure (mutations raise; nothing review-shaped is lost).
 ```
 
+The experimental `/pr-review-dynamic` door shares `post_pr_review`/`review-post` and the clean
+guard unchanged — angle selection is delegated to a fresh `perk.review-angle-selector` lane and
+normalized in module-rendered code (`extension/waves/prReviewDynamicWave.ts`); the baseline
+`/pr-review` stays canonical.
+
 ### PR-review toolbox ops (checkout / cleanup / review-submit)
 
 The two human-in-the-loop review doors (`/pr-review-terminal`, `/pr-review-browser`) review a
@@ -797,7 +805,7 @@ waves to `POST <url>/api/external-annotations`
 side: LEFT→"old" / RIGHT-or-omitted→"new", text: "[severity/confidence] …"}]}`; batches are
 atomic; 201 returns `{ids}` — captured for cleanup). The wave cadence: on
 `/pr-review-browser` a wave is pushed per ARRIVING fenced-JSON batch inside the streaming
-`wait({timeoutMs})` loop (a `path`+`line` ledger dedupes — a pushed anchor is never re-pushed —
+`subagent_wait({timeoutMs})` loop (a `path`+`line` ledger dedupes — a pushed anchor is never re-pushed —
 and the discipline is hold-and-accumulate: a refused POST before any door failure notice means
 "not up yet", retried on the next wait-loop return, never a degrade).
 `line: null` findings ARE pushed on this surface (path → `scope: "file"`, none →
@@ -882,19 +890,28 @@ pieces; a neutral re-home is a deferred residual).
   `prompts/stages/pr-review-terminal/foreign.md` (the untrusted-foreign-code posture, the triage
   loop, the posting contract, and the `perk pr review cleanup` step).
 - **The streaming fan-out (foreign + active; guidance-driven — no door plumbing):** the guidance
-  spawns the 2–3 reviewers as ONE async `subagent` call (a `tasks` array, `context: "fresh"`,
-  `async: true`; each child's task names its angle, the PR number, and the worktree path ONLY —
-  never the surface handle), then loops `wait({ timeoutMs })` while the run is active. The why:
-  progress updates neither wake `wait()` nor enter pi-subagents' `pending` map — delivery is an
-  injected steer message when a tool call returns — so the timed wait loop IS the streaming
-  cadence and the parent must hold its turn open (an ended turn stops streaming). Each arriving
-  fenced-JSON batch is pushed into hunk incrementally with **`path`+`line` dedupe** (an
+  spawns the 2–3 reviewers as ONE async `subagent` call in `workflowScript` mode (top-level
+  `async: true` + `context: "fresh"` — workflow-level defaults flowing to every lane; the script
+  is a single all-settled `runs.all` with one item per angle — a stable angle-slug `key`,
+  `phase`/`label` trace metadata, and a task naming the angle, the PR number, and the worktree
+  path ONLY — never the surface handle; a failed lane resolves `{key, ok: false, error}` without
+  sinking its siblings; the script returns the mapped per-lane outputs so the full reports
+  persist in the run's `status.json`), then loops `subagent_wait({ timeoutMs })` while the run
+  is active. The why: progress updates never wake `subagent_wait` and never enter pi-subagents'
+  `pending` map — delivery is an injected (now `triggerTurn`-bearing) message when a tool call
+  returns — so the timed wait loop IS the streaming cadence and the parent holds its turn open
+  (an ended turn degrades streaming to churny per-batch wake-ups instead of a held relay). Each
+  arriving fenced-JSON batch is pushed into hunk incrementally with **`path`+`line` dedupe** (an
   in-conversation ledger; a pushed anchor is never re-pushed; hold-and-accumulate until the
-  handshake connects). On the grouped completion notification the parent reconciles from the
-  fenced-JSON **completion reports** (union + dedupe — the source of truth for triage and
-  posting; streamed batches were provisional), pushes any not-yet-pushed remainder, and — when
-  the handshake never connected — applies the unchanged check-in posture (ask, wait, degrade
-  only on the human's explicit choice).
+  handshake connects). On completion — the workflow notification carries only a truncated
+  return preview, never the reports — the parent retrieves the full reports via
+  `subagent({action: "status", id})` (the per-lane step lines + the `Dir:` line) → `read`
+  `<Dir>/status.json` → `workflow.value`, reconciles from the fenced-JSON **completion
+  reports** (union + dedupe — the source of truth for triage and posting; streamed batches were
+  provisional; an `ok: false` lane is reported honestly to the human — angle + error, never
+  papered over), pushes any not-yet-pushed remainder, and — when the handshake never connected
+  — applies the unchanged check-in posture (ask, wait, degrade only on the human's explicit
+  choice).
 - **Active mode (no PR arg):** the shared active-PR resolution ladder — `perk pr url --json` →
   `resolveReviewTarget` with the plan-ref's pinned base. A resolved PR → the same flow re-homed
   to the human's own worktree (`active.md`: no checkout and **no cleanup step**; the children
@@ -1023,8 +1040,9 @@ core), imported by this door and `/pr-review-terminal`'s active mode.
   `prompts/stages/pr-review-browser/foreign.md` (the untrusted-foreign-code posture, the
   `perk pr review cleanup` step).
 - **The streaming fan-out (foreign + active; guidance-driven — no door plumbing):** the 2–3
-  adversarial reviewers spawn as ONE async `subagent` call and the parent holds the
-  `wait({timeoutMs})` streaming loop, exactly as on `/pr-review-terminal` — but each arriving
+  adversarial reviewers spawn as ONE async `subagent` call in `workflowScript` mode and the
+  parent holds the
+  `subagent_wait({timeoutMs})` streaming loop, exactly as on `/pr-review-terminal` — but each arriving
   fenced-JSON batch is pushed as ONE atomic wave to `POST <url>/api/external-annotations` (the
   ledger dedupe + hold-and-accumulate discipline in the findings-stream block above). Children
   never receive the surface handle — not the URL, not the port. Once the fan-out turn ends the
@@ -1169,11 +1187,12 @@ carries `base` from the `plan-header` so resume paths recover the pinned value.
 
 **Label taxonomy (minimal):** `perk:plan` (green `1f883d`), `perk:learn` (purple `8250df`),
 `perk:objective` (indigo `5319e7`, description "perk objective issue"), `perk:objective-node`
-(indigo `5319e7`, on Linear project-backed roadmap node-issues), and `perk:consolidated` (gray
-`6e7781`, description "perk learn issue consolidated into docs/learned"), each **lazily created**
-by its gateway create-op on first use. Query by a **single** label — GitHub label filters are
-AND-semantics. (On Linear, `perk init` / `doctor --fix` proactively ensure the five `perk:*`
-labels at **workspace** scope — §8.21.)
+(indigo `5319e7`, on Linear project-backed roadmap node-issues), `perk:gist` (yellow `fbca04`,
+description "perk gist issue (a rough statement of intent)" — §8.41), and `perk:consolidated`
+(gray `6e7781`, description "perk learn issue consolidated into docs/learned"), each **lazily
+created** by its gateway create-op on first use. Query by a **single** label — GitHub label
+filters are AND-semantics. (On Linear, `perk init` / `doctor --fix` proactively ensure the six
+`perk:*` labels at **workspace** scope — §8.21.)
 
 **The `pending-learn` semaphore.** An existence-only `cache.markers` file
 (`.perk/workflow/markers/pending-learn`, name shared as `PENDING_LEARN` in both planes): **`land`
@@ -1317,13 +1336,16 @@ second `--fix` at `fixed == []`).
 **Groups.** `environment` (tools; required tools missing = `fail`; optional tools (e.g. ast-grep)
 missing = `warn`) · `github` (auth/access; non-fatal `warn`) ·
 `linear` (verify-gated Linear readiness — auth/team/labels; present only when the committed
-`[issues] backend` is `"linear"`; warn-level, the github D3 mirror; `--fix` ensures the five perk
+`[issues] backend` is `"linear"`; warn-level, the github D3 mirror; `--fix` ensures the six perk
 labels — §8.21) · `runner` (remote-runner prereqs; report-only, non-fatal — §8.16) ·
 `package` (settings wiring + perk-package ref reconcile + the `extension-install` install-ownership
 check + the `required-perk-version` managed check over the committed `.perk/required-perk-version`
 pin + the report-only `cli-version` CLI-vs-repo-pin warning (warn, never fail) + the report-only
 `resource-overrides` probe over pi resource overrides that touch perk's own resources (warn, never
-fail, no `--fix` arm — §8.6a);
+fail, no `--fix` arm — §8.6a) + the report-only `subagent-compat` pi-subagents surface probe
+(installed version + source-file markers for the orchestration surfaces perk's guidance assumes;
+`info` when not installed; warn on divergence, never fail; no `--fix` arm — the package stays
+unpinned);
 `--fix` also migrates a former git-clone consumer forward by removing the orphaned clone — §8.6a) ·
 `repository` (gitignore/agents blocks + config present/valid) ·
 `registry` (the registry self-check) · `skills` (the skills-CLI manifest fragment + the
@@ -1528,6 +1550,7 @@ perk's workflow skills are prompt-hidden; `transclude` exists for the user-bindi
 | trigger | skill | mode |
 |---|---|---|
 | `stage:plan` | `perk-plan` | `nudge` |
+| `stage:gist-author` | `perk-gist-author` | `nudge` |
 | `stage:objective-author` | `perk-objective-author` | `nudge` |
 | `stage:objective-plan` | `perk-objective-plan` | `nudge` |
 | `stage:implement` | `perk-implement` | `nudge` |
@@ -1538,6 +1561,7 @@ perk's workflow skills are prompt-hidden; `transclude` exists for the user-bindi
 | `command:learn-docs` | `perk-learn-docs` | `nudge` |
 | `command:learn-code` | `perk-learn-code` | `nudge` |
 | `command:pr-review` | `perk-pr-review` | `nudge` |
+| `command:pr-review-dynamic` | `perk-pr-review-dynamic` | `nudge` |
 | `command:pr-review-terminal` | `perk-pr-review-terminal` | `nudge` |
 | `command:pr-review-browser` | `perk-pr-review-browser` | `nudge` |
 | `command:skills-create` | `perk-skill-author` | `nudge` |
@@ -1847,7 +1871,11 @@ test on both planes).
 
 **`perk init` two-directional settings wiring:** provider wiring composes on top of the static
 `_desired_packages` (perk + `BORROWED_PACKAGES`: `npm:@tombell/pi-diff`,
-`npm:pi-subagents`) layer within the same `_converge_settings` body — `npm:pi-web-access` is **no
+`npm:pi-subagents`, `npm:@ff-labs/pi-fff`) layer within the same `_converge_settings` body —
+perk launches inject the env default `PI_FFF_MODE=override` at **both spawn sites** (local
+`_exec_pi`, remote `_spawn_worker`) with operator env winning by merge order, so stage sessions
+get FFF as `find`/`grep` while warm/bare sessions keep pi-fff's additive default mode
+(`fffind`/`ffgrep`) — `npm:pi-web-access` is **no
 longer borrowed** (#529): it is the `web` seam's `default: true` provider, converged via the
 provider path (see the web status note in contracts-history.md §8.10), so a default repo still installs it but deselecting `web`
 removes it like any provider package —
@@ -1934,7 +1962,8 @@ compaction drift; `doctor --fix` reconverges). **Committed-only read** (a `local
 table touches nothing; removing it leaves the written keys to clean up by hand (perk cannot prove
 ownership of a bare settings key). Relatedly, `[models.subagents]` values are **blessed** to carry
 the same `:thinking` suffix (and pi-subagents' `inherit` sentinel — child inherits the parent
-session's model), resolved by pi-subagents on the per-call inline `model` override; doctor's
+session's model), resolved by pi-subagents from the workflow-level `model` the guidance passes
+on the `subagent` workflowScript call; doctor's
 warn-level `models` check flags suspicious suffixes (alphabetic-only last-colon segment outside
 the vocabulary) across `[models].default`, `[models.subagents]` values, and
 `[models.stages.<id>].model`. Resulting precedence — cold launch: explicit `perk <stage>
@@ -1965,6 +1994,19 @@ pi-subagents' `applyBuiltinOverrides` consults **before** the bulk flag and whic
 never touches; a **user-global** `~/.pi/agent/settings.json` re-enable does **not** work (the
 project bulk-disable is checked before user-scope overrides).
 
+**`tuiMode` seed (init-owned):** perk seeds `"tuiMode": "fullscreen"` into `.pi/settings.json`
+**write-when-absent** — the third convergence shape beside write-when-present
+(`[compaction]`/`[models]`) and constant-enforced (`subagents.disableBuiltins`): the key is
+written once, only when absent, and never overwrites a present key (any value — presence, not
+value, is the guard). Python-plane-only (pi consumes `settings.json` itself; the extension never
+reads it), composed inside `_converge_settings`
+(`perk/convergence/init/settings.py::_converge_tui_mode`) so it rides the `settings-wiring`
+`ManagedConvergence`. **Excluded** from the desired/observed managed-state settings portions: a
+seeded default is user-ownable after the seed — including it would misclassify an opt-out as
+`locally-modified`. The opt-out is committing any `tuiMode` value (e.g. `"regular"`), which
+survives init/doctor; a user-global `/settings` change does **not** durably override the project
+key (pi merges project settings over global).
+
 > **Interactive save discipline (as of Node 2.5 the present + `/plan-save` flow is
 > FALLBACK-ONLY on every interactive path — perk-plan included):** the prior
 > `PLAN_AUTHORING_CONTEXT` ending ("disable plan mode (/plan off), then call the plan_save
@@ -2114,13 +2156,18 @@ stream's terminal `run_finished` event (§8.12) — the same frozen object, carr
 channel.
 
 > **Open dependency (carried risk).** The `address` drive's seeded prompt instructs the model to
-> spawn `perk.review-classifier` via the borrowed `pi-subagents` `subagent` tool. `pi-subagents`
-> now loads in the worker from the managed settings `packages` list (Gap 4 above). The worker's
-> address prompt now also injects the configured classifier model when `[models.subagents]
-> review-classifier` is set in the worktree's `.perk/config.toml` (#196), as a per-call inline `model`
-> override byte-identical to `_address_prompt`'s parity twin. The **subagent-under-worker live
-> smoke** stays an open dependency **deferred to the Phase-3 `doctor workflow`**;
-> Node 1.2 does not prove it.
+> run `perk.review-classifier` via ONE foreground `workflowScript` call on the borrowed
+> `pi-subagents` `subagent` tool (direct `{agent, task}` execution was removed upstream at 0.43).
+> `pi-subagents` now loads in the worker from the managed settings `packages` list (Gap 4 above).
+> The worker's address prompt now also injects the configured classifier model when
+> `[models.subagents] review-classifier` is set in the worktree's `.perk/config.toml` (#196), as a
+> workflow-level `model` default on that one call, byte-identical to `_address_prompt`'s parity
+> twin. The seeded classify call also passes a top-level `outputSchema` (rendered from the shared
+> template's `prompts/common/output-schemas/review-classifier.md` include) — the classifier's
+> report is engine-validated structured output read from the projection's `report`
+> (`structuredOutput`), so `ok: true` ⟺ a schema-valid report is present. The
+> **subagent-under-worker live smoke** stays an open dependency **deferred to the Phase-3
+> `doctor workflow`**; Node 1.2 does not prove it.
 
 ## §8.12 · The structured run-event stream (Node 1.3)
 
@@ -3009,8 +3056,9 @@ init/doctor probe — report-shaped, never raises; phases short-circuit auth →
   remediation "export LINEAR_API_KEY (create a personal API key at linear.app Settings →
   Security & access), or set [linear] api_key in .perk/local.toml".
 - `linear-team` — ok: `team <key> found`; failure: warn with the error detail.
-- `linear-labels` — all five perk labels present (`perk:plan`, `perk:learn`, `perk:consolidated`,
-  `perk:objective`, `perk:objective-node`): ok; otherwise warn listing the missing names,
+- `linear-labels` — all six perk labels present (`perk:plan`, `perk:learn`, `perk:consolidated`,
+  `perk:objective`, `perk:objective-node`, `perk:gist`): ok; otherwise warn listing the missing
+  names,
   remediation "run `perk init` or `perk doctor --fix`". perk's labels are created
   **workspace-scoped** (no `teamId` on create — Linear's cross-team-label guidance; the lookup is
   unscoped, so a pre-existing team-scoped label still counts).
@@ -3031,14 +3079,14 @@ safely auto-create them).
 
 **The `--fix` label repair gesture** (`_fix_linear_labels`, verify-gated like the skills sync —
 network I/O, so never a `ManagedConvergence`): when `fix` AND `verify` AND linear is selected AND
-key + team are available, `check_readiness(..., ensure_labels=True)` ensures the five labels;
+key + team are available, `check_readiness(..., ensure_labels=True)` ensures the six labels;
 created names land on `fixed` (`Linear: created label perk:plan`), failures on `fix_errors`.
 Lookup-first idempotency: a converged workspace reports nothing (the doctor idempotency rule).
 
 **The init readiness step** (`perk/convergence/init/__init__.py::_linear_readiness`, verify-gated, non-fatal — the
 GitHub D3 mirror: file convergence already succeeded). Only when `verify` AND the committed
 backend is `"linear"`: missing key/team degrade to an errored `LinearReport`; otherwise the probe
-runs with `ensure_labels=True` (init converges the five perk labels upfront; the lazy write-time
+runs with `ensure_labels=True` (init converges the six perk labels upfront; the lazy write-time
 `ensure_label` calls remain the safety net). Created labels are reported through the
 `LinearReport` (the `--json` `linear` key, §8.5; the human `✓ Linear: <user>, team <key>` line) —
 **never** appended to `InitReport.changes`, which stays a pure filesystem-delta list.
@@ -3213,6 +3261,34 @@ one-stop current shape.
   | `plannotator-plan` | `PLAN_ADAPTER_PLANNOTATOR_CONTEXT` | browser bridge | present + `/plan-save` |
   | `tombell-plan` | `PLAN_ADAPTER_TOMBELL_CONTEXT` (conditioned injection, Node 2.6) | first-party in-TUI review | present + `/plan-save` (incl. tombell's own interactive `/plan` `setActiveTools` restriction arm) |
 
+- **Plannotator "Direct Edits" (browser edits of the reviewed document).** Plannotator's
+  plan-review browser lets the reviewer edit the reviewed document directly; the edits arrive as
+  PROSE inside the existing `feedback` string, never a new envelope field — a `# Direct Edits`
+  section (heading + preamble + a ```` ```diff ```` fence containing a jsdiff
+  `createTwoFilesPatch(…, { context: 3 })` patch, `trimEnd()`'d, against the exact bytes perk
+  submitted), composed FIRST, with non-sentinel annotation feedback following after
+  `\n\n---\n\n` (format pin: plannotator `packages/editor/directEdits.ts`
+  `buildDirectEditsSection`/`composeFeedbackWithDirectEdits` @ v0.26.1 — prose, not a pinned
+  API). perk handles it asymmetrically per arm:
+  - **Plan arm, APPROVE:** mechanical apply — strict extraction (`extractDirectEdits`,
+    `extension/adapters/planAdapterPlannotator.ts`) → strict clean-apply (`applyUnifiedDiff`,
+    `extension/substrate/unifiedDiff.ts`, a vendored zero-runtime-dep applier; null on any
+    anomaly) → `writePlanDraft` write-back (reviewed bytes == artifact bytes == saved bytes) →
+    save the EDITED bytes with `details.edited: true` and the annotation remainder as the only
+    surviving feedback. The **fail-open ladder**: no section → today's path byte-stable; a
+    heading that cannot be parsed / applied / written back → the verbatim save plus a loud
+    warning in the approved text and `details.direct_edits_applied: false` (the diff stays in
+    the surfaced feedback for a manual follow-up). Worst-case upstream format drift degrades to
+    exactly the pre-Direct-Edits behavior.
+  - **Objective arm, APPROVE with a Direct Edits section:** NO save — the save seam re-reads the
+    STRUCTURED draft, so rendered-markdown edits (roadmap-table rows included) cannot be folded
+    back mechanically. The arm returns a NON-terminating revise round (`details.status:
+    "revise"`, `reason: "direct_edits"`, gate untouched): the model folds the diff into
+    `objective_draft`, then calls `plan_review` again to confirm. perk never saves an objective
+    the reviewer explicitly edited away from.
+  - **DENY (both arms):** model-mediated — the feedback (diff included) passes through verbatim
+    for the `plan_draft`/`objective_draft` rewrite.
+
 - **Link/`consumed_learn` recovery carriers.** Approval-triggered saves carry **no model params**;
   the **cold** `handoff_extra` carrier (→ §8.2) and the **warm** `objective_node_claim` carrier
   (→ §8.3) recover `objective_id`/`node_id` with identical semantics — fill both-or-neither,
@@ -4510,6 +4586,30 @@ evidence --render --json`) and **also writes `<bundle_dir>/manifest.json`** —
 children can `read` the manifest (they cannot read the door's stdout). Written unconditionally on
 a materialized bundle, deterministic (no wall-clock); no write on a skip.
 
+**The analyst wave (the report-wave module).** The multi-angle analyst fan-out runs through the
+Perk-owned report-wave module (`extension/waves/reportWave.ts`) via the flow-scoped
+**`run_learn_wave`** tool (`extension/doors/learn.ts` — non-terminating; the parent continues to
+reconcile): the module renders the tested `workflowScript`, spawns it async over the pi-subagents
+v1 extension RPC (`mission: false`, `context: "fresh"`), blocks under the module-owned timeout,
+and reads the durable `status.json` aggregate — the wave mechanics are CODE, never model-authored
+prompt mechanics. Analyst reports are **engine-validated structured output** against the TS-owned
+`LEARN_ANALYST_REPORT_SCHEMA` (`extension/waves/learnWave.ts` — closed shape, all-required,
+`target` required-nullable, deliberately NO verdict↔candidates conditional: the parent derives
+the real verdict from `candidates[]`, so salvaging an inconsistent report beats failing its
+lane), replacing fenced-JSON scraping — covered angle ⟺ ok lane ⟺ schema-valid report.
+Completeness is the module's **`best-effort`** policy as tested implementation: a lane-level
+failure is an explicitly-reported **skipped angle** (never a failed pass, no retry); a
+**wave-level** failure is a loud tool soft-failure (`error_type` = the wave failure reason) —
+never a silent fallback to model-authored scripts — and the guidance routes the parent to a
+single-context analysis of the bundle instead. The **angle policy is tool-enforced**
+(`angleSelectionError`): 2–4 angles, no duplicates, only the four known slugs
+(`session-deviations` / `plan-vs-implementation` / `existing-docs` / `validation-risk`), and
+`session-deviations` always included; violations are `bad_input`. The tool takes the
+guidance-rendered `bundle_dir` (the model relays it verbatim — the same trust plane as the task
+text), derives `manifest.json` itself (`bad_input` when absent), and resolves the analyst model
+from `[models.subagents] learn-analyst` at execute time (the wave's workflow-level `model`
+default). The manifest write rule above and the DECISION vocabulary are unchanged.
+
 **The `learn` tool's classification params.** The warm `learn` tool carries `decision` (a
 JSON-schema enum of the five captured tokens) + `target` (string), threaded to `perk learn
 capture --decision/--target`. The tool-boundary decode mirrors the `summary` strictness: a
@@ -4815,10 +4915,13 @@ stage (a forked implement session is an implement session); **adopt never impers
 subagent children stay unscoped — their fresh branch carries no stage). Stage-borrowing cold
 doors land on real stage ids (`plan from`/`plan replan`/`learn docs`/`learn code` borrow `plan`;
 `objective replan`/`objective author --from` borrow `objective-author`; `skills create/refine`
-borrow `save`), so the per-stage sets cover every borrower. **Scoped universe:
+borrow `save`), so the per-stage sets cover every borrower. The gist stages (`gist-author`,
+`gist-save` — §8.41) each carry `ask_user_question` + `gist_draft` + `gist_save` + the research
+families (the objective-author shape; `plan_review` governs via the gate-ON set). **Scoped universe:
 `PERK_TOOLS ∪ BORROWED_TOOLS`** — perk's own name-keyed census plus the enumerated
 borrowed-package census (the web-provider union, pi-mono-linear's 25 tools, pi-subagents'
-delegation four, `todo`, `plannotator_submit_plan`); builtins and un-enumerated foreign names
+delegation four, pi-fff's search names — both mode name-sets, `fffind`/`ffgrep`/`fff-multi-grep`
+plus override's `multi_grep` — `todo`, `plannotator_submit_plan`); builtins and un-enumerated foreign names
 pass through untouched (fail-open — enumeration is diet-completeness, not correctness).
 
 **The borrowed census posture.** Static names, inert when absent (the `READ_ONLY_TOOLS`
@@ -4833,7 +4936,7 @@ appear in `BORROWED_TOOLS`; hygiene-tested). Foreign packages that run their own
 `setActiveTools` (plannotator's phase machinery, @tombell/pi-plan's plan mode) win between
 perk's rebuild points (the fail-open direction), and a mid-session rebuild re-installs perk's
 stage set over a foreign restriction — recorded interplay, not re-engineered. Stage placement:
-the research families (web union + Linear reads) ride EVERY stage list; delegation
+the research families (web union + Linear reads + FFF local search) ride EVERY stage list; delegation
 (`subagent`/`wait`/the supervisor pair) and `todo` are worktree-family only among the gate-OFF
 stage lists (delegation additionally rides the read-only gate — §8.3);
 `LINEAR_MUTATING_TOOLS` (incl. `linear_configure_auth`, which writes `~/.pi/agent/auth.json`)
@@ -4870,3 +4973,76 @@ lever the gate's allowlist uses; `edit`/`write`/`bash` blocking remains the gate
 config surface for the map (the §8.39 non-interference posture; fail-open on unknown ids covers
 version skew). **Bare-session zero-change guarantee:** a session that never engages either
 concern gets **zero `setActiveTools` calls** — bare warm sessions stay byte-identical.
+
+## §8.41 · The gist tier (lightweight statements of intent)
+
+A **gist** is a backend-tracked **statement of intent** — a rough, thematically
+problem-space-focused note of "something we would likely want to do", upstream of both plans and
+objectives. It is **code-informed but carries no implementation strategy** (no steps, no roadmap,
+no estimates); the lightness lives in the ARTIFACT and the skill guidance, not the machinery. A
+gist's **scope** (`plan` | `objective`) records its intended consumption tier: a storage
+discriminator on Linear (issue vs project), a header hint on GitHub.
+
+**Registry topology (settled decision).** The two gist stages (`gist-author` → `gist-save`) form
+a **separate, disconnected component** — no edges into the main loop. Gists are optional; nothing
+routes off "which stage is initial" except the validator, which requires **at least one** initial
+stage (zero initials — a pure cycle — stays an error). Consumption happens via the unchanged
+§8.29/§8.30 in-place adoption doors (`perk plan from <gist>` /
+`perk objective author --from <gist>`), never via stage edges: a gist is consumable because it is
+an ordinary OPEN backend object without plan/objective metadata.
+
+**Metadata.** The `perk:gist` label (yellow `fbca04`, description "perk gist issue (a rough
+statement of intent)"), lazily created by its create-op on first use — the sixth `perk:*` label.
+The `gist-header` metadata block carries `run_id`, `created`, and `scope` (`plan` | `objective`;
+lenient read — an unknown stored scope parses to `None`). Per-backend storage:
+
+- **GitHub** — an issue: the html-style `gist-header` block rendered into the body above the
+  prose.
+- **Linear, scope `plan`** — an issue: clean transcoded prose body + a `gist-header` **native
+  attachment** (kind `gist-header`, URL `https://perk.invalid/gist/<run_id>`, title
+  "Perk gist", subtitle = scope; the §8.24 attachment-metadata posture).
+- **Linear, scope `objective`** — a **project**: the overview carries an inline-code
+  `gist-header` block above the transcoded prose. No milestones, no node-issues, no metadata
+  sentinel — deliberately light; the overview block IS the identity (projects have no
+  attachments).
+
+**The `IssueBackend` gist trio** (docstring contracts mirroring the learn trio):
+`find_gist_issue{run_id}` (label + header-key scoped — cannot return a plan/learn issue),
+`create_gist_issue{title, body, run_id, scope, dry_run}` (idempotent via the finder; stamps
+`scope` into the header), and `list_gist_issues{} -> GistSummary[]{id, title, url, body, scope,
+adopted}` — every OPEN `perk:gist` issue; raises on infra failure, never masks as empty. The
+`ObjectiveStore` grows the project-tier pair in the no-op-return family:
+`create_gist_source{title, prose, run_id, dry_run} -> ObjectiveRef | None` (`None` = "no project
+surface" — the CLI falls back to the issue tier; the Linear project store creates/finds the gist
+project) and `list_gist_sources{} -> GistSummary[]` (`()` outside the project store).
+
+**Adopted detection.** A gist whose stored metadata ALSO carries the adopting tier's metadata
+(distinct keys — adoption stamps additively beside the `gist-header`, no collision) is
+**adopted**: on GitHub the `plan-header`/`objective-header` block joins the body; on a Linear
+issue the signal is a `plan-header` attachment; on a Linear project it is the **Reconcilable
+region** the adoption composer writes into the overview (the objective headers ride the
+sentinel's attachments, never an overview block; the original gist overview — with its
+`gist-header` — survives verbatim in the Immutable archive note, keeping the project scannable
+as a gist). `perk gist list` default **hides** adopted gists (the "what's still unconsumed" backlog
+view); `--all` shows everything with an adopted marker. No gist-specific consumption
+bookkeeping: in-place adoption means the gist *becomes* the plan/objective and inherits its
+lifecycle.
+
+**The save worker (`perk gist create --json`).** Options `--body <path>` (required), `--title`,
+`--scope [plan|objective]`, `--run-id`, `--dry-run`. Scope resolution: explicit `--scope` > the
+`gist_scope` **handoff** key (a declared `Handoff` field, stashed by `perk gist author --scope`
+— the `adopt_from` handoff pattern; best-effort recovery, never blocks a save) > `"plan"`. Scope
+`objective` routes to `ObjectiveStore.create_gist_source` first, falling back to the issue tier
+on a `None` return; scope `plan` goes to the issue backend directly. Envelope:
+`{"success": true, "error_type": null, "gist": {"id", "url", "existed"}, "scope", "dry_run"}` —
+opaque string ids (§8.21). Human output prints the created/found line plus a consumption hint
+(`perk plan from <id>` / `perk objective author --from <id>`).
+
+**The warm flow** is the full review-first mirror of plan/objective authoring: the `gist_draft`
+tool (the third draft-file tool — §8.1's carve-out family; artifact `gist-draft.json`, shape
+`{schema_version: 1, title?, scope?, prose}`) keeps the draft current; `plan_review` in a
+`gist-author` session reviews the **rendered markdown** (title + scope line + prose — never raw
+JSON), VIEW-ONLY first-party (the objective-arm shape; deny+feedback is the change channel);
+APPROVED auto-saves via `gistApprovalSave` → the `gist_save` tool / `perk gist create`;
+`/gist-save` is the manual failsafe. No draft → soft-skip `reason: "no_gist_draft"`. No session
+linkage after save — nothing consumes a gist in-session.

package/shared/registry.yaml

@@ -27,6 +27,7 @@ state_keys:
     - comments        # discussion comments
     - review-threads  # review threads (distinct API from comments)
     - learn           # the perk:learn knowledge-capture issue (P2.T8b)
+    - gist            # the perk:gist statement-of-intent issue (contracts.md §8.41)
   # Tier 2 · .perk/workflow/ — the local cache (see contracts.md §8.1).
   cache:
     - plan            # materialized plan body cache
@@ -41,7 +42,10 @@ state_keys:
 
 # ---------------------------------------------------------------------------
 # Stages — the loop (Q5): objective-author -> objective-save -> objective-plan -> plan ->
-# save -> implement -> submit -> address -> land -> learn.
+# save -> implement -> submit -> address -> land -> learn — plus the OPTIONAL gist
+# component (gist-author -> gist-save), deliberately disconnected from the loop:
+# a saved gist is consumed by the in-place adoption doors (`perk plan from`,
+# `perk objective author --from`), not by stage edges (contracts.md §8.41).
 #
 # Every field is locked EXCEPT `requires`/`reads`/`writes` (empty until handlers
 # land). `run_id` is uniform AND shape-locked by the validator: `perk/substrate/registry.py`
@@ -59,6 +63,32 @@ state_keys:
 # local-only by design — review, merge, and judgment capture stay where a human is.
 # ---------------------------------------------------------------------------
 stages:
+  - id: gist-author
+    summary: Draft a gist — a rough statement of intent (read-only authoring).
+    mode: read-only
+    worktree: none            # interactive authoring, like plan — no branch, no gist yet
+    doors: { warm: true, cold_local: true, cold_remote: false }  # interactive local authoring
+    run_id: { warm: keep, cold_local: mint, cold_remote: mint }
+    command: gist author      # dedicated seeded cold door (perk gist author)
+    requires: []                       # nothing exists yet — this stage CREATES the gist
+    reads: []
+    writes: [session.workflow-state, cache.session-data]   # the read-only `mode` append; gist_draft writes the gist-draft artifact + its session_artifacts pointer
+    predecessors: []                   # an initial of the disconnected gist component
+    successors: [gist-save]
+
+  - id: gist-save
+    summary: Persist the drafted gist to the issue backend; the read-only -> read-write boundary.
+    mode: read-write
+    worktree: none            # still no branch; save writes the gist issue/project
+    doors: { warm: true, cold_local: true, cold_remote: false }
+    run_id: { warm: keep, cold_local: mint, cold_remote: mint }
+    command: gist save        # the gist_save terminating tool + /gist-save command
+    requires: []
+    reads: []
+    writes: [github.gist, session.workflow-state]  # create the gist issue/project
+    predecessors: [gist-author]
+    successors: []            # a terminal — consumption happens via the adoption doors, not edges
+
   - id: objective-author
     summary: Draft a new objective + roadmap (read-only authoring).
     mode: read-only