@mgiles/perk 2.0.0 → 2.2.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:
@@ -386,7 +386,7 @@ 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
 (`subagent`/`wait` + the parent supervisor pair — the gated objective-plan explorer spawn must be
@@ -1130,7 +1130,10 @@ validate_pr_body(body, *, pr_number)                -> string[]   (empty == vali
 
 **Plan-header block (the queryable metadata in the issue *body*).** The minimal
 observably-distinct set; rendered as a `perk:metadata-block:plan-header` collapsible YAML
-block; the full plan markdown lives in the `plan-body` first comment:
+block; the full plan markdown lives in the `plan-body` first comment. **Carrier is
+backend-owned:** GitHub renders it in the issue body; **Linear stores the same fields as a
+native issue-attachment envelope** (the §8.24 native-attachment metadata amendment) — the field
+set below is the cross-backend contract either way:
 
 ```
 { run_id: string,              # the §8.2 run that created the plan (idempotency key)
@@ -1166,11 +1169,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`
@@ -1314,7 +1318,7 @@ 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`
@@ -1525,6 +1529,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` |
@@ -2928,7 +2933,13 @@ team = "ENG"         # the Linear team key — required when backend = "linear"
 `load_committed_issues_backend` / `load_committed_issues_team`; TS: `resolveIssueBackendId` reads
 only the committed file). Rationale: the backend decides where canonical durable state
 (plan/learn/objective issues) is *written*; a per-user override would fragment the canonical
-store. **`LINEAR_API_KEY` lives in the environment or the gitignored `.perk/local.toml`
+store. **Main-checkout anchored, both planes.** Both planes resolve the read root to the **main
+checkout** (git-common-dir resolution — Python `git.main_worktree_root(repo_root) or repo_root`,
+TS `mainCheckoutRoot(cwd)`; both fall back to the invocation root outside a git repo), so a
+linked worktree's checkout state (detached HEAD, a stale branch, a checkout without `.perk/`)
+can never change where canonical durable state is written. Deliberate consequence: a plan branch
+that *edits* `[issues]` does not take effect from inside its own worktree — the canonical-store
+selection must not fork mid-plan; it switches when the edit reaches the main checkout. **`LINEAR_API_KEY` lives in the environment or the gitignored `.perk/local.toml`
 `[linear] api_key`** (an exported env var wins over the config) — **never** in a committed file.
 The config read is local-file-only (`config.load_local_linear_api_key`, the inverse of the
 `load_committed_*` readers; fail-soft on malformed TOML — returns `None`, never raised). Two seams
@@ -3000,8 +3011,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).
@@ -3022,14 +3034,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.
@@ -3204,6 +3216,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,
@@ -3543,6 +3583,71 @@ actor is the human user; these changes make perk's footprint read as native:
   round-trip is proven lossless (else dropped). Becoming a true Linear **Agent** (`actor=app`) is a
   separate, out-of-scope follow-up.
 
+**Native-attachment metadata amendment (#1355) — Linear perk metadata rides issue attachments.**
+Linear-only (**GitHub renders are byte-identical**; the issue-tier protocol reshape below is the
+one cross-backend change). The five machine metadata blocks — `plan-header`, `learn-header`,
+`objective-node` (issue-scoped) and `objective-header`, `objective-manifest` (project-scoped) —
+**no longer render into Linear bodies at all**: each rides a native issue **attachment** with a
+machine-readable `metadata` envelope. Bodies/overviews are clean human prose. This supersedes the
+prose-first-composition bullet above (there are no machine blocks left to position), the
+collapsed-toggle deferral (moot), `_insert_or_replace_manifest` (deleted), and every
+list-and-parse find scan. A **clean break**: no legacy read fallback — pre-existing Linear
+artifacts with body-block metadata are simply not found (re-save/re-create them). Still inline in
+bodies (structural sentinels, not metadata): the `plan-body`/marked-comment markers, the
+Reconcilable region markers, the `Adopted-from` archive note, and the copyable command callouts.
+
+- **The envelope** (`perk/backends/linear/attachments.py::encode`): `attachmentCreate` with
+  `metadata: { source: "perk", schema_version: 1, kind: <block key>, payload_json: <JSON fields>,
+  created, title, attributes: {…} }` — `payload_json` is the authoritative field payload (the
+  same fields the body blocks carried); `attributes` duplicates scalars for Linear-side
+  filterability. Cards render human-readable (title = the block kind, subtitle = a salient
+  field). Decode is `find_perk_attachment(nodes, kind=)` — absent → `None` (tolerant),
+  present-but-malformed → raises (fail-loud); `has_perk_attachment` is the presence-only check.
+- **The URL scheme is the identity** (live-verified: Linear accepts non-resolving URLs, and
+  `attachmentCreate` **upserts by `(url, issueId)` with REPLACE metadata semantics** — every
+  write must carry the complete envelope): `https://perk.invalid/plan/<run_id-or-identifier>`,
+  `/learn/<run_id-or-identifier>`, `/node/<issue identifier>` (carry-path stable),
+  `/objective/<run_id>`, `/manifest/<run_id>`. Writers always **reuse a found attachment's URL**
+  (never re-derive — re-deriving would orphan the existing card).
+- **O(1) finds via `attachmentsForURL`** (`find_issue_by_attachment_url`): `find_plan_issue` /
+  `find_learn_issue` / `find_objective` are each ONE workspace-wide exact-URL query (no
+  team-scoped label scans). **Open-only parity rule:** the issue-tier finds treat a hit in a
+  terminal state (`completed`/`canceled`) as not-found — parity with the legacy open-only scan,
+  so a landed plan's run_id never resurrects the closed issue. On **multiple** hits (a landed
+  plan's closed issue + an open re-save sharing the URL) the find prefers the first
+  **non-terminal** hit, so the parity filter is deterministic — never at the mercy of the
+  server's node order. The objective find is
+  state-independent by design (its sentinel is born canceled) and takes the project ref from the
+  hit issue's `project` (a header hit with no project raises — a broken sentinel).
+- **The project metadata sentinel.** Linear exposes no project-attachment mutation, so each
+  perk project carries one **sentinel issue** (`Perk: objective metadata`, empty body, born in
+  the team's canceled state — cosmetic; created **fail-loud** immediately after `projectCreate`,
+  before milestones/node-issues) holding the `objective-header` + `objective-manifest`
+  attachments. Discovery keys on the header **attachment**, never the title. One best-effort
+  `entityExternalLinkCreate` adds it to the project's Resources (fail-open). Readers find it in
+  the same `project_issues` scan they already run (zero extra queries); it is excluded from
+  roadmap reads, engagement, and adoption candidate maps. `update_objective_header` /
+  manifest syncs (`_sync_manifest_*`, `_refresh_manifest_phase_pins`, the drift backfill) are
+  merge-and-upsert against the sentinel's attachments; a sentinel-less project is **not a perk
+  objective** (`get_objective → None`).
+- **Node-issues + unified plans.** The `objective-node` payload rides a `/node/<identifier>`
+  attachment (descriptions are clean prose); a unified node-issue carries TWO envelopes — node +
+  plan — disambiguated by `kind`. The node→plan backlink derivation is unchanged but now keys on
+  the **plan-header attachment's presence**. Attachments cascade-delete with their issue.
+- **Accepted create window (issue tier).** Every Linear create is now two writes — `issueCreate`
+  then the identity-carrying attachment upsert — so a crash between them orphans a header-less
+  issue invisible to the URL finds (a retry mints a fresh one; the orphan is human-visible
+  garbage to close). The same accepted one-round-trip window as the metadata sentinel's,
+  now explicit for plan/learn/node creates too.
+- **The issue-tier protocol reshape (all backends).** `create_plan_issue(title, header_fields,
+  run_id, dry_run)` replaces the pre-rendered `body` param — the backend owns the header carrier
+  (GitHub renders the body block itself, byte-identical; Linear creates a clean empty body + the
+  attachment). Two additive fields: `LearnIssueSummary.header: LearnHeader | None` (decoded
+  backend-side; GitHub parses the body, Linear the attachment — degrade-to-None either way) and
+  `AdoptableIssue.already_plan: bool` (backend-decided — GitHub `has_metadata_block(body,
+  plan-header)`, Linear the plan-header attachment), consumed by `plan from`'s `already_a_plan`
+  refusal.
+
 ## §8.25 · The human-engagement read contract (Objective #682, Node 1.2)
 
 A backend-neutral **READ** surface for human engagement — comments, description edits, and
@@ -3806,14 +3911,17 @@ are verbatim human content". A normally-authored plan leaves it `None`.
   `plan-header` block additively into the issue **body** (human prose preserved verbatim, **title
   untouched**); (c) idempotently prepend the `perk impl <id>` callout above the body; (d) upsert
   the `plan-body` comment carrying the authored markdown. Returns `IssueRef(existed=True)`.
-  Idempotent on re-save; GitHub stamps HTML-encoded, Linear inline-code (Linear-safe).
+  Idempotent on re-save; GitHub stamps the body block HTML-encoded; Linear upserts the
+  plan-header **attachment** instead — the human body stays verbatim apart from the callout
+  (the §8.24 native-attachment metadata amendment).
 
 **The cold door (`perk plan from <issue>`).** A dedicated launcher verb in the `plan` hybrid group
 (mirrors `replan`/`resume`; `from` is a valid Click command string). It performs every Linear/GitHub
 read up front (the read-only plan-mode session has no `gh`/Linear access), then re-launches the
 `plan` stage seeded to author a plan over the materialized source. It **refuses** when: the issue is
 not found (`adopt_not_found`), not OPEN (`adopt_not_open`), or already a perk plan
-(`has_metadata_block(body, plan-header)` → `already_a_plan`, hinting `perk plan replan <id>`).
+(`AdoptableIssue.already_plan` — backend-decided: GitHub the body block, Linear the plan-header
+attachment → `already_a_plan`, hinting `perk plan replan <id>`).
 Engagement is read fail-soft (`render_adopted_engagement` → `<untrusted_adopted_issue_engagement>`;
 `IssueBackendError` → omitted). The source is materialized to `scratch/adopt-<issue_id>.md` (title +
 body wrapped in `<untrusted_adopted_issue>` + the optional engagement block). A **fresh** `run_id`
@@ -3910,18 +4018,21 @@ reconcile. Mapped issues' titles/bodies are independently preserved verbatim by
   `perk objective plan <n>` callout prepended), backfill `objective_comment_id`. `adopt_map` is
   ignored (no child issues).
 - **Linear project-backed (full):** `_LinearProjectOps.project_issues_for_adoption` (a sibling of
-  `project_issues` selecting `title` too; the byte-stable `project_issues` left untouched).
-  `read_objective_source` → the project overview `content` + its issues. `adopt_source_as_objective`
-  composes the new overview preserving the original verbatim (`to_linear_markdown(`
-  Reconcilable(`<model prose>`) + `objective-header`(`adopted_from=source_id`) + `objective-manifest`
-  + `render_adopted_overview_note(<original overview>)` below the markers `)`), `update_project
-  _content` (in place, NOT `create_project`), prepends the callout; one milestone per phase via
-  `ensure_phase_milestone` seeded from `project_milestones` (de-dupe against existing); for each
-  node in `node_sort_key` order a **mapped** node stamps the `objective-node` block additively into
-  the existing issue (title/body verbatim, description PATCH + `perk:objective-node` label added +
-  phase-milestone attach), an **unmapped** node mints a fresh node-issue; blocking relations per
-  explicit `depends_on`. Raises on an `adopt_issue` id not in the project (fail-loud). Idempotent on
-  `run_id`.
+  `project_issues` selecting `title` too; both selections now also carry the attachment nodes —
+  the §8.24 native-attachment metadata amendment).
+  `read_objective_source` → the project overview `content` + its issues (the metadata sentinel
+  excluded). `adopt_source_as_objective` composes the new overview preserving the original
+  verbatim (`to_linear_markdown(` Reconcilable(`<model prose>`) +
+  `render_adopted_overview_note(<original overview>)` below the markers `)`), `update_project
+  _content` (in place, NOT `create_project`), prepends the callout; the
+  `objective-header`(`adopted_from=source_id`) + `objective-manifest` ride a fresh metadata
+  sentinel's attachments (the §8.24 native-attachment metadata amendment); one milestone per
+  phase via `ensure_phase_milestone` seeded from `project_milestones` (de-dupe against existing);
+  for each node in `node_sort_key` order a **mapped** node upserts the `objective-node`
+  attachment onto the existing issue (title/body verbatim — no description write — +
+  `perk:objective-node` label added + phase-milestone attach), an **unmapped** node mints a fresh
+  node-issue; blocking relations per explicit `depends_on`. Raises on an `adopt_issue` id not in
+  the project (fail-loud). Idempotent on `run_id`.
 - **Issue-backed Linear (dormant):** both `read_objective_source` and `adopt_source_as_objective`
   return `None` (honest no-op; keeps `ty` green).
 
@@ -4735,7 +4846,9 @@ 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
@@ -4790,3 +4903,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