Ship a first-run trust loop instead of a repository setup exercise

[George-RD]

What to build

First-run experience must not require cloning a Git repo or running OpenSpec tools. Replace the repository setup exercise with a single-command trust loop: one trusted principal, one session, one outcome.

Acceptance criteria

1. Remove repository setup ceremony. 2. Implement single-command startup (e.g., 'openspine init --owner'). 3. Document the trust ceremony (seed key, approval, test). 4. Verify bootstrap works end-to-end.

Blocked by

None (parallel work)

Original report

Why

The Growth Arsenal value-equation audit found that OpenSpine's strongest variable is the dream outcome and its weakest variables are time to first value and setup effort.

The current public path asks a new user to configure Docker, socket permissions, Telegram, a model provider, Gmail OAuth, mailbox identity, and a copied Gmail thread ID before they can see the core product promise. The agent-OS sequence also records richer onboarding as deferred until a second deployment exists.

That deferral now conflicts with the product need. Onboarding is not cosmetic. It is how a user learns that OpenSpine is the assistant system, Lyra is the assistant, and the runtime is protecting the first real task.

Product goal

A technical self-hoster should reach one visible, governed result quickly and understand:

1. what Lyra is about to do;
2. what the task may and may not access;
3. which credentials stay outside the worker;
4. where approval is required;
5. what receipt proves after the task.

Scope

• Add a single supported first-run command or guided flow.
• Preflight Docker, socket access, data ownership, Lyra package availability, provider auth, Telegram, Gmail, and the selected mailbox.
• Show failures with one cause and one recovery action rather than raw subsystem errors.
• Replace copied thread IDs with a minimal owner-controlled thread selector or recent-thread picker.
• Show the task boundary in plain language before the first run.
• After completion, show a compact receipt: verified source, selected target, allowed/asked/denied actions, and audit reference.
• Preserve the current deterministic authority pipeline. The onboarding UI may explain the grant; it must not construct or override it.

Done when

• A fresh technical user can reach a successful Lyra draft without reading multiple implementation documents.
• The setup flow distinguishes required configuration, optional capability, and current alpha limits.
• The user sees a real denial or approval boundary during the first successful workflow.
• The flow is exercised at desktop terminal width and a narrow terminal or web surface where applicable.
• Automated tests cover preflight results and the first-run state transitions.

Relationship to architecture

Do not wait for a second deployment target. Keep deployment-specific setup adapters separate from the runtime, but treat the first-run product experience as a current roadmap track.

Roadmap relationship after the progressive-delegation audit

This issue owns time to the first bounded task, not reusable authority itself.

• Ship protocol-neutral progressive delegation so Lyra grows through real work #123 owns the longitudinal progression from repeated decisions to reviewed responsibility.
• Define the protocol-neutral responsibility contract above standing rules #126 and Add channel-neutral responsibility review and lifecycle controls #129 will define the channel-neutral owner-review and receipt vocabulary. This flow should consume those contracts when available rather than inventing onboarding-only grant/review cards.
• Ship recurring Gmail drafts as the first complete delegation proof #130 owns the first reusable Gmail responsibility proof. Its full runtime implementation is not required before this issue can make the existing per-instance draft flow usable.
• The first credible product milestone is the convergence of this first-run task with Ship recurring Gmail drafts as the first complete delegation proof #130's reusable delegation proof.

first bounded result (#118)
        +
reviewed reusable responsibility (#130)
        =
first credible OpenSpine experience

Do not block this issue on the full package store in #117. A bundled/default Lyra path may be used until package installation is productized, provided the setup flow remains truthful about the current source-checkout/package state.

[coderabbitai]

Coding Plan

Summary

• Grow the existing stubbed openspine setup / provider login subcommands into a single guided first-run flow in the kernel binary, driven by a declarative FirstRunStage sequence and a new unified preflight engine that reports one cause and one recovery per subsystem while preserving contract-tested error strings.
• Remove manual thread-ID copying by adding a gmail.readonly-only recent-threads listing plus an owner-trusted Telegram inline-keyboard picker that reuses the unchanged, source-agnostic selection-token/gate machinery.
• Deliver plain-language task-boundary and compact-receipt views built strictly as read-only projections of the already-composed TaskGrant, GateDecision, CounterpartyRef, and hash-chained AuditEvents, mirroring the site's AuthorityTrace vocabulary so a future web surface can reuse the same structured data.
• Keep deployment-specific (Docker/socket) checks in the preflight adapter layer, separate from runtime boot, and cover preflight results and first-run transitions with the established wiremock/tempfile/in-memory-store/trace-assertion test patterns.

Design Choices

Design Choice 1: Which surface should the first-run flow target first — terminal-only, or terminal plus a live web UI?

Options Considered:

1. Build a terminal-first guided flow whose preflight/boundary/receipt data is emitted as structured DTOs that a future web surface can consume; reuse the site's visual vocabulary for copy only.
2. Build both a terminal flow and a new live web dashboard wired to the kernel HTTP API in this ticket.

Chosen Option: 1

Rationale: It satisfies the "where applicable" qualifier and the "narrow terminal" requirement without the large scope and new attack surface of standing up a live web runtime UI, while keeping data shapes web-ready.

Design Choice 2: Should the first-run flow extend the existing `Commands::Setup` stub or introduce a brand-new command?

Options Considered:

1. Grow Commands::Setup into the real guided first-run flow and wire Provider::Login to the existing OAuth helper.
2. Add a separate Commands::FirstRun command alongside the existing stubs.

Chosen Option: 1

Rationale: It reuses the sanctioned hook point and existing cli/setup.rs helpers, avoids a redundant command surface, and matches the "single supported first-run command" scope item.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Guided first-run command and unified preflight

Turn the stubbed setup subcommands into a single guided flow that runs a unified, actionable preflight over every subsystem before the kernel's fail-closed boot checks can surface raw errors. This phase establishes the flow's state machine, the preflight engine with one-cause/one-recovery messaging, and the terminal UX, reusing the existing (currently dead) OAuth/verification/config-rewrite helpers.

Task 1: Add terminal-UX dependencies and a first-run stage model

Establish the interactive-terminal toolkit and the declarative step taxonomy the flow follows.

• Add interactive terminal dependencies (e.g. dialoguer + console, or equivalent) to the workspace Cargo.toml and crates/openspine-kernel/Cargo.toml; none exist today.
• Create a FirstRunStage enum following the pipeline/stages.rs convention: a Copy enum with a single SEQUENCE const array (e.g. Preflight → ProviderAuth → ConnectorSetup → BoundaryPreview → FirstTask → Receipt) as the source of truth, with compile-time structural assertions.
• Place this in a new crates/openspine-kernel/src/cli/first_run.rs module (declared from cli/mod.rs), which orchestrates the flow by advancing through the stage sequence and appending to a trace vector for test assertions.
• Ensure the flow renders responsively at desktop and narrow terminal widths (query terminal width via the console crate; wrap/reflow copy accordingly).

Task 2: Build the unified preflight engine

Introduce a single preflight entry point that checks every subsystem and reports each result with exactly one cause and one recovery action.

• Create a crates/openspine-kernel/src/cli/preflight.rs module exposing a run_preflight() returning a Vec<PreflightCheck>, where each check carries a name, a category (Required / OptionalCapability / AlphaLimit), and a status (Pass or Fail { cause, recovery }).
• Implement checks for: openspine.yaml presence/parse, OPENSPINE_ARTIFACT_KEY presence/format (with a "how to generate" recovery), data-dir ownership/writability, Lyra package availability (load artifacts/lyra/package.yaml via the overlay loader), Docker daemon/socket reachability and image tag match, provider auth, Telegram bot token, Gmail credential pair, and selected mailbox address.
• Reuse existing validators rather than duplicating logic: run_preflight_verification_ping (provider), connectors.telegram().validate_candidate_token_id and gmail.validate_credential_pair via api/connector_breaker.rs::call_with_connector_preflight, and the overlay/package loader for Lyra availability.
• Add a Docker reachability check (currently absent at startup) that pings the daemon through the socket/CLI and maps failure to a single recovery action; keep it a Required check only when sandbox.driver: docker.
• Preserve the exact underlying error strings that openspec/specs/day-2-operations/spec.md contract-tests: the cause field must embed the verbatim subsystem error; the recovery field is an additive friendly wrapper, never a replacement.

Task 3: Wire the guided flow into the CLI dispatch

Replace the no-op stubs so openspine setup and openspine provider login perform real work at the documented hook point.

• Update crates/openspine-kernel/src/main.rs Commands::Setup branch (before Config::load) to invoke cli::first_run, which runs preflight, drives provider OAuth/verification, guides connector setup, and categorizes results (required config vs optional capability vs alpha limit).
• Wire Commands::Provider::Login to the existing cli::setup::run_provider_login → run_preflight_verification_ping → update_openspine_yaml_roles chain (currently #[allow(dead_code)]), including the headless manual-code and device-code fallbacks the OAuth spec already defines.
• Keep deployment-specific setup concerns (Docker/socket specifics) in the preflight adapter layer, separated from runtime boot, per the ticket's architecture note.

Task 4: Test preflight results and first-run transitions

Cover the two explicitly required test areas using established patterns.

• Add unit tests for preflight.rs using wiremock (fake provider/connector endpoints) and tempfile temp dirs/config, asserting each check's category and Pass/Fail { cause, recovery } shape, including that verbatim contract-tested error strings are preserved inside cause.
• Add first-run state-transition tests mirroring pipeline/tests/driver.rs: capture the executed FirstRunStage trace and assert equality against FirstRunStage::SEQUENCE, plus branch tests for early termination on a Required preflight failure.

🤖 Prompt for AI agents

Implement the guided first-run command and unified preflight engine in
`crates/openspine-kernel`, replacing the stubbed `Commands::Setup` /
`Commands::Provider::Login` subcommands with a real, orchestrated flow.

- Add interactive terminal dependencies (e.g. `dialoguer` + `console`) to the
workspace `Cargo.toml` and `crates/openspine-kernel/Cargo.toml`.
- Define a `FirstRunStage` `Copy` enum in
`crates/openspine-kernel/src/cli/first_run.rs` (new module, declared from
`cli/mod.rs`) following the `pipeline/stages.rs` convention, with a single
`SEQUENCE` const array (`Preflight → ProviderAuth → ConnectorSetup →
BoundaryPreview → FirstTask → Receipt`) as the source of truth and compile-time
structural assertions. The flow orchestrator advances through this sequence,
appending to a trace vector for test assertions, and renders responsively at
desktop and narrow terminal widths by querying terminal width via `console` and
wrapping/reflowing copy.
- Create `crates/openspine-kernel/src/cli/preflight.rs` exposing
`run_preflight()` returning `Vec<PreflightCheck>`. Each `PreflightCheck` has a
name, category (`Required` / `OptionalCapability` / `AlphaLimit`), and status
(`Pass` or `Fail { cause, recovery }`).
- Implement checks for: `openspine.yaml` presence/parse,
`OPENSPINE_ARTIFACT_KEY` presence/format (with a "how to generate" recovery),
data-dir ownership/writability, Lyra package availability (via overlay loader
reading `artifacts/lyra/package.yaml`), Docker daemon/socket reachability and
image tag match (Required only when `sandbox.driver: docker`), provider auth,
Telegram bot token, Gmail credential pair, and selected mailbox address.
- Reuse existing validators instead of duplicating logic:
`run_preflight_verification_ping` for provider,
`connectors.telegram().validate_candidate_token_id` and
`gmail.validate_credential_pair` via
`api/connector_breaker.rs::call_with_connector_preflight`, and the
overlay/package loader for Lyra.
- Preserve verbatim subsystem error strings contract-tested by
`openspec/specs/day-2-operations/spec.md` inside the `cause` field; `recovery`
is an additive friendly wrapper only, never a replacement of `cause`.
- Update `crates/openspine-kernel/src/main.rs`: the `Commands::Setup` branch
(before `Config::load`) should invoke `cli::first_run`, which runs preflight,
drives provider OAuth/verification, guides connector setup, and categorizes
results (required config vs optional capability vs alpha limit). Wire
`Commands::Provider::Login` to the existing `cli::setup::run_provider_login` →
`run_preflight_verification_ping` → `update_openspine_yaml_roles` chain (remove
`#[allow(dead_code)]`), including existing headless manual-code and device-code
fallbacks.
- Keep deployment-specific concerns (Docker/socket) in the preflight adapter
layer, separate from runtime boot checks.
- Add unit tests for `preflight.rs` using `wiremock` and `tempfile`, asserting
each check's category and `Pass`/`Fail{cause, recovery}` shape, and that
contract-tested error strings are preserved verbatim inside `cause`.
- Add first-run state-transition tests mirroring `pipeline/tests/driver.rs`,
capturing the executed `FirstRunStage` trace and asserting equality against
`FirstRunStage::SEQUENCE`, plus tests for early termination on a `Required`
preflight failure.

Phase 2: Owner-controlled recent-thread picker

Remove the manual "copy a Gmail thread ID from the URL" step by adding a recent-thread listing capability and a trusted Telegram selection surface, while leaving the selection-token, gate, and dispatch machinery unchanged.

Task 1: Add a recent-threads listing capability to the Gmail connector

Provide the data a picker needs without broadening OAuth scope.

• Add a list_recent_threads(limit) method to crates/openspine-kernel/src/gmail.rs wrapping users.threads.list plus minimal per-thread metadata (subject/sender snippet), returning a bounded, attachment-free list; gmail.readonly already authorizes this, so no scope change is needed.
• Factor the id-shape validation (charset allowlist + length ≤ 64) out of telegram::parse_draft_command into a shared is_valid_gmail_thread_id helper, and apply it to every thread id returned by the picker before it reaches URL interpolation.

Task 2: Add a trusted Telegram thread-selection surface

Replace /draft <id> free-text as the trust anchor with an owner-only inline-keyboard picker.

• Extend the Telegram handling in crates/openspine-kernel/src/pipeline/mod.rs (and telegram.rs) so /draft with no id (or a new /threads command) presents an inline keyboard of recent threads; the kernel stores the candidate thread ids server-side keyed to the owner + message, and the callback payload carries only an opaque index/token the kernel maps back, so the model/shell can never inject a thread id.
• On owner selection, resolve the picked id, run it through is_valid_gmail_thread_id, then call the existing pipeline/selection.rs::build_selection_token unchanged (it is already source-agnostic) and continue into the existing email_preview_lane.
• Preserve the existing /draft <id> text path for backward compatibility, routing both paths through the same validation + token-minting code.

Task 3: Test the picker selection path

Ensure the new trusted surface behaves and validates correctly.

• Add tests in crates/openspine-kernel/src/gmail/tests.rs (via wiremock) for list_recent_threads bounding, attachment stripping, and metadata parsing.
• Add tests confirming the callback-driven selection only mints a token for owner-originated, server-side-known ids that pass is_valid_gmail_thread_id, and that a forged/unknown callback payload is rejected without minting.

🤖 Prompt for AI agents

Implement an owner-controlled recent-thread picker for Gmail/Telegram, removing
the need for manual thread-ID copying while keeping the selection-token, gate,
and dispatch machinery unchanged.

- In `crates/openspine-kernel/src/gmail.rs`, add a `list_recent_threads(limit)`
method wrapping `users.threads.list` plus minimal per-thread metadata
(subject/sender snippet), returning a bounded, attachment-free list. No OAuth
scope change is needed since `gmail.readonly` already authorizes this.
- Factor the id-shape validation (charset allowlist + length ≤ 64) currently
inline in `telegram::parse_draft_command` out into a shared
`is_valid_gmail_thread_id` helper, and apply it to every thread id returned by
the picker before it reaches URL interpolation.
- Extend Telegram handling in `crates/openspine-kernel/src/pipeline/mod.rs` (and
`telegram.rs`) so that `/draft` with no id (or a new `/threads` command)
presents an inline keyboard of recent threads. The kernel must store candidate
thread ids server-side keyed to the owner + message; the callback payload
carries only an opaque index/token that the kernel maps back server-side,
ensuring the model/shell can never inject a thread id directly.
- On owner selection, resolve the picked id, validate it through
`is_valid_gmail_thread_id`, then call the existing
`pipeline/selection.rs::build_selection_token` unchanged (it is already
source-agnostic), and continue into the existing `email_preview_lane`.
- Preserve the existing `/draft <id>` text path for backward compatibility;
route both the picker path and the text path through the same validation +
token-minting code.
- Add tests in `crates/openspine-kernel/src/gmail/tests.rs` using `wiremock` for
`list_recent_threads` bounding, attachment stripping, and metadata parsing.
- Add tests confirming the callback-driven selection only mints a token for
owner-originated, server-side-known ids that pass `is_valid_gmail_thread_id`,
and that a forged/unknown callback payload is rejected without minting a token.

Phase 3: Plain-language task boundary and compact receipt

Surface, from read-only projections of the already-composed grant and audit records, a plain-language boundary preview before the first task and a compact receipt afterward — explaining the authority decision without ever constructing or overriding it.

Task 1: Render the pre-run task boundary in plain language

Show the owner what Lyra is about to do, what it may/may not access, which credentials stay outside the worker, and where approval is required.

• Build a boundary-preview renderer that reads the composed TaskGrant (allowed_actions / approval_required_actions / denied_actions) and the Lyra package memory scope (denied_classes from artifacts/lyra/package.yaml via MemoryScope), and states plainly that secrets remain in the kernel/vault and never enter the worker.
• Reuse the existing PlanApprovalQuestion rendering pattern and the GET /v1/task TaskViewBody shape as the read sources; the renderer must only read these, never call compose_authority/gate.
• Surface this preview to the owner in the existing Telegram draft-approval flow (api/plan.rs::dispatch_plan_preview path) so the first successful workflow explicitly shows a real approval/denial boundary (e.g. email.create_draft asked, email.send denied).

Task 2: Assemble a compact receipt from existing read models

After task completion, prove what happened using only stored decisions.

• Add a receipt-builder function (new read-only projection, e.g. alongside briefcase_visibility.rs) that assembles a Receipt DTO from: CounterpartyRef (verified source / selected target), the TaskGrant allow/ask/deny lists, and the relevant AuditEvents queried by aggregate_id/task_grant_id, using GateDecision for outcomes and AuditEvent.id as the audit reference.
• Emit the receipt to the owner via Telegram as a compact summary and expose it as a structured, read-only JSON DTO (following the GET /v1/task handler pattern in crates/openspine-kernel/src/api/) so a future web surface can render it.
• Model the receipt DTO on the AuthorityTrace.astro field vocabulary (verified source, gate-ledger allow/ask/deny rows, audit reference) so the site component could later consume live data instead of hardcoded demo strings.

Task 3: Test boundary preview and receipt projection

Confirm the explain-only guarantee and correct field mapping.

• Add tests seeding an in-memory Store with a TaskGrant, CounterpartyRef, and chained AuditEvents, asserting the receipt DTO reflects the stored allow/ask/deny decisions and audit id without recomputation.
• Add a test asserting the boundary renderer produces stable plain-language output for a known grant and that it performs no authority composition (purely reads the provided grant/view).

🤖 Prompt for AI agents

Implement plain-language task-boundary preview and compact receipt views, built
strictly as read-only projections of already-composed authority data, never
recomputing decisions.

- Build a boundary-preview renderer that reads the composed `TaskGrant`
(`allowed_actions` / `approval_required_actions` / `denied_actions`) and the
Lyra package memory scope (`denied_classes` from `artifacts/lyra/package.yaml`
via `MemoryScope`), and states plainly that secrets remain in the kernel/vault
and never enter the worker.
- Reuse the existing `PlanApprovalQuestion` rendering pattern and the `GET
/v1/task` `TaskViewBody` shape as the read sources for the renderer; it must
only read these values and must never call `compose_authority`/`gate`.
- Surface the boundary preview to the owner in the existing Telegram
draft-approval flow (`api/plan.rs::dispatch_plan_preview` path) so the first
successful workflow explicitly shows a real approval/denial boundary (e.g.
`email.create_draft` asked, `email.send` denied).
- Add a receipt-builder function as a new read-only projection (e.g. alongside
`briefcase_visibility.rs`) that assembles a `Receipt` DTO from:
`CounterpartyRef` (verified source / selected target), the `TaskGrant`
allow/ask/deny lists, and the relevant `AuditEvent`s queried by
`aggregate_id`/`task_grant_id`, using `GateDecision` for outcomes and
`AuditEvent.id` as the audit reference.
- Emit the receipt to the owner via Telegram as a compact summary, and expose it
as a structured, read-only JSON DTO following the `GET /v1/task` handler pattern
in `crates/openspine-kernel/src/api/`, so a future web surface can render it.
- Model the receipt DTO on the `AuthorityTrace.astro` field vocabulary (verified
source, gate-ledger allow/ask/deny rows, audit reference) so the existing site
component could later consume live data instead of hardcoded demo strings.
- Add tests seeding an in-memory `Store` with a `TaskGrant`, `CounterpartyRef`,
and chained `AuditEvent`s, asserting the receipt DTO reflects the stored
allow/ask/deny decisions and audit id without recomputation.
- Add a test asserting the boundary renderer produces stable plain-language
output for a known grant and performs no authority composition (purely reads the
provided grant/view).

Research

The runtime lives in crates/openspine-kernel (binary openspine), which owns config, secrets, OAuth, connectors, the authority pipeline, and Docker access; openspine-shell is a stateless per-task worker and cannot host setup. The kernel already exposes stubbed Commands::Setup and Commands::Provider::Login subcommands in main.rs, backed by real-but-unwired OAuth login, preflight-ping, and YAML role-binding helpers in cli/setup.rs. Authority decisions flow through pure stages (resolve_route → resolve_persona → compose_authority → gate) producing a read-only TaskGrant and GateDecision; existing read models (GET /v1/task, PlanApprovalQuestion, AuditEvent, CounterpartyRef) already expose everything a boundary preview and receipt need. Gmail supports only single-thread reads today; the selection-token minter (build_selection_token) is source-agnostic and reusable. The static Astro site (AuthorityTrace.astro, LyraScenario.astro) illustrates the exact receipt shape but is not wired to live data. No terminal-UX dependencies exist yet, and the day-2-operations spec contract-tests exact first-run failure strings that must be preserved verbatim.", "creation_status": "new"}

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement the guided first-run command and unified preflight engine in
`crates/openspine-kernel`, replacing the stubbed `Commands::Setup` /
`Commands::Provider::Login` subcommands with a real, orchestrated flow.

- Add interactive terminal dependencies (e.g. `dialoguer` + `console`) to the
workspace `Cargo.toml` and `crates/openspine-kernel/Cargo.toml`.
- Define a `FirstRunStage` `Copy` enum in
`crates/openspine-kernel/src/cli/first_run.rs` (new module, declared from
`cli/mod.rs`) following the `pipeline/stages.rs` convention, with a single
`SEQUENCE` const array (`Preflight → ProviderAuth → ConnectorSetup →
BoundaryPreview → FirstTask → Receipt`) as the source of truth and compile-time
structural assertions. The flow orchestrator advances through this sequence,
appending to a trace vector for test assertions, and renders responsively at
desktop and narrow terminal widths by querying terminal width via `console` and
wrapping/reflowing copy.
- Create `crates/openspine-kernel/src/cli/preflight.rs` exposing
`run_preflight()` returning `Vec<PreflightCheck>`. Each `PreflightCheck` has a
name, category (`Required` / `OptionalCapability` / `AlphaLimit`), and status
(`Pass` or `Fail { cause, recovery }`).
- Implement checks for: `openspine.yaml` presence/parse,
`OPENSPINE_ARTIFACT_KEY` presence/format (with a "how to generate" recovery),
data-dir ownership/writability, Lyra package availability (via overlay loader
reading `artifacts/lyra/package.yaml`), Docker daemon/socket reachability and
image tag match (Required only when `sandbox.driver: docker`), provider auth,
Telegram bot token, Gmail credential pair, and selected mailbox address.
- Reuse existing validators instead of duplicating logic:
`run_preflight_verification_ping` for provider,
`connectors.telegram().validate_candidate_token_id` and
`gmail.validate_credential_pair` via
`api/connector_breaker.rs::call_with_connector_preflight`, and the
overlay/package loader for Lyra.
- Preserve verbatim subsystem error strings contract-tested by
`openspec/specs/day-2-operations/spec.md` inside the `cause` field; `recovery`
is an additive friendly wrapper only, never a replacement of `cause`.
- Update `crates/openspine-kernel/src/main.rs`: the `Commands::Setup` branch
(before `Config::load`) should invoke `cli::first_run`, which runs preflight,
drives provider OAuth/verification, guides connector setup, and categorizes
results (required config vs optional capability vs alpha limit). Wire
`Commands::Provider::Login` to the existing `cli::setup::run_provider_login` →
`run_preflight_verification_ping` → `update_openspine_yaml_roles` chain (remove
`#[allow(dead_code)]`), including existing headless manual-code and device-code
fallbacks.
- Keep deployment-specific concerns (Docker/socket) in the preflight adapter
layer, separate from runtime boot checks.
- Add unit tests for `preflight.rs` using `wiremock` and `tempfile`, asserting
each check's category and `Pass`/`Fail{cause, recovery}` shape, and that
contract-tested error strings are preserved verbatim inside `cause`.
- Add first-run state-transition tests mirroring `pipeline/tests/driver.rs`,
capturing the executed `FirstRunStage` trace and asserting equality against
`FirstRunStage::SEQUENCE`, plus tests for early termination on a `Required`
preflight failure.
===============================================================================

Task: 2

Implement an owner-controlled recent-thread picker for Gmail/Telegram, removing
the need for manual thread-ID copying while keeping the selection-token, gate,
and dispatch machinery unchanged.

- In `crates/openspine-kernel/src/gmail.rs`, add a `list_recent_threads(limit)`
method wrapping `users.threads.list` plus minimal per-thread metadata
(subject/sender snippet), returning a bounded, attachment-free list. No OAuth
scope change is needed since `gmail.readonly` already authorizes this.
- Factor the id-shape validation (charset allowlist + length ≤ 64) currently
inline in `telegram::parse_draft_command` out into a shared
`is_valid_gmail_thread_id` helper, and apply it to every thread id returned by
the picker before it reaches URL interpolation.
- Extend Telegram handling in `crates/openspine-kernel/src/pipeline/mod.rs` (and
`telegram.rs`) so that `/draft` with no id (or a new `/threads` command)
presents an inline keyboard of recent threads. The kernel must store candidate
thread ids server-side keyed to the owner + message; the callback payload
carries only an opaque index/token that the kernel maps back server-side,
ensuring the model/shell can never inject a thread id directly.
- On owner selection, resolve the picked id, validate it through
`is_valid_gmail_thread_id`, then call the existing
`pipeline/selection.rs::build_selection_token` unchanged (it is already
source-agnostic), and continue into the existing `email_preview_lane`.
- Preserve the existing `/draft <id>` text path for backward compatibility;
route both the picker path and the text path through the same validation +
token-minting code.
- Add tests in `crates/openspine-kernel/src/gmail/tests.rs` using `wiremock` for
`list_recent_threads` bounding, attachment stripping, and metadata parsing.
- Add tests confirming the callback-driven selection only mints a token for
owner-originated, server-side-known ids that pass `is_valid_gmail_thread_id`,
and that a forged/unknown callback payload is rejected without minting a token.
===============================================================================

Task: 3

Implement plain-language task-boundary preview and compact receipt views, built
strictly as read-only projections of already-composed authority data, never
recomputing decisions.

- Build a boundary-preview renderer that reads the composed `TaskGrant`
(`allowed_actions` / `approval_required_actions` / `denied_actions`) and the
Lyra package memory scope (`denied_classes` from `artifacts/lyra/package.yaml`
via `MemoryScope`), and states plainly that secrets remain in the kernel/vault
and never enter the worker.
- Reuse the existing `PlanApprovalQuestion` rendering pattern and the `GET
/v1/task` `TaskViewBody` shape as the read sources for the renderer; it must
only read these values and must never call `compose_authority`/`gate`.
- Surface the boundary preview to the owner in the existing Telegram
draft-approval flow (`api/plan.rs::dispatch_plan_preview` path) so the first
successful workflow explicitly shows a real approval/denial boundary (e.g.
`email.create_draft` asked, `email.send` denied).
- Add a receipt-builder function as a new read-only projection (e.g. alongside
`briefcase_visibility.rs`) that assembles a `Receipt` DTO from:
`CounterpartyRef` (verified source / selected target), the `TaskGrant`
allow/ask/deny lists, and the relevant `AuditEvent`s queried by
`aggregate_id`/`task_grant_id`, using `GateDecision` for outcomes and
`AuditEvent.id` as the audit reference.
- Emit the receipt to the owner via Telegram as a compact summary, and expose it
as a structured, read-only JSON DTO following the `GET /v1/task` handler pattern
in `crates/openspine-kernel/src/api/`, so a future web surface can render it.
- Model the receipt DTO on the `AuthorityTrace.astro` field vocabulary (verified
source, gate-ledger allow/ask/deny rows, audit reference) so the existing site
component could later consume live data instead of hardcoded demo strings.
- Add tests seeding an in-memory `Store` with a `TaskGrant`, `CounterpartyRef`,
and chained `AuditEvent`s, asserting the receipt DTO reflects the stored
allow/ask/deny decisions and audit id without recomputation.
- Add a test asserting the boundary renderer produces stable plain-language
output for a known grant and performs no authority composition (purely reads the
provided grant/view).

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[George-RD]

Restructured into the cohesive roadmap (map #182); original preserved below.

[George-RD]

Owner-proxy ruling on the worker's scope call: ACCEPTED — requiring a real Telegram user id for --owner (no placeholder binding a fail-closed authoritative owner) and restricting principal bootstrap to a fresh data root are both correct trust-preserving choices. The deprecated maximalist onboarding rungs (preflight engine/thread picker) stay unbuilt; #117's spec pass picks up install-flow scope.