Add channel-neutral responsibility review and lifecycle controls

[George-RD]

What to build

Owner surface must be channel-neutral: OwnerReviewRequest renders identically on Telegram and WhatsApp, decisions are principal-bound and channel-independent. Inventory the 28 chat-id leaks below the adapter boundary and wire them as independent tracked gaps.

Acceptance criteria

1. Implement channel-neutral OwnerReviewRequest structure. 2. Support Telegram and WhatsApp adapters simultaneously. 3. Inventory and track all channel-ID-dependent code paths. 4. Route each to a separate tracked issue.

Blocked by

T10 assessment findings; Bell fit review

Fence: Do not start before the Bell fit review lands on build-on. Route through delivery vehicle in DIRECTION.md.

Original report

Why

The progressive-delegation experience is currently being designed as Telegram text plus inline buttons. Telegram is a useful first renderer, but it must not become the product or security model. OpenSpine already supports a local terminal owner channel and anticipates future communication surfaces.

The owner should make one digest-bound decision about a governed review object. Telegram, terminal, web, or another verified owner channel should only render and submit that decision.

The current lifecycle also lacks the complete employee-management controls promised by #123: Reject, narrow/amend, Pause, Resume, and clear post-use receipts.

Scope

1. Owner review object

Implement the OwnerReviewRequest contract settled in #126. It must be stored/content-addressed and bind:

• review type and proposal provenance/evidence;
• owner-facing job/responsibility description;
• exact action descriptor and reviewed scope;
• budgets, rate, expiry, drift behavior, and any conditional default;
• effects that become reusable;
• effects that remain approval-required or denied;
• artifact/version/digest identities;
• available decisions;
• expiry and current lifecycle state.

The review object must be the security-relevant source rendered by every owner surface. A renderer cannot add scope or decisions that are absent from it.

2. Generic owner decisions

Define channel-neutral, principal-bound decision intents:

• Approve exact reviewed version;
• Reject without activation;
• Request a narrower/amended proposal;
• Pause an active responsibility;
• Resume the same reviewed version when still compatible;
• Revoke immediately;
• inspect provenance/diff/receipt.

A narrow/edit operation must create a new immutable proposal/version and new digest. It must not mutate bytes under an existing approval.

3. Standing-rule lifecycle

Add an owner-controlled paused state distinct from system-triggered needs_review and terminal revoked.

Required behavior:

• paused rules are absent from live consultation;
• resume revalidates policy, descriptor, executor, connector/account, reviewed scope, and compatibility before returning active;
• revoke is immediate and idempotent;
• rejected proposals never enter live consultation;
• expired or drifted rules cannot be resumed without a new reviewed version.

4. Renderers

Telegram

Render the generic review object with bounded copy and appropriate buttons. Keep existing verified-private-owner assumptions. Telegram callback data identifies the review/decision, not connector-specific implementation details.

Local terminal

Render the same review as a readable decision card/numbered prompt and submit the same decision intent. This proves the lifecycle is not Telegram-defined.

Future web/mobile surfaces should require no lifecycle rewrite.

5. Truthful proposal language

• "Lyra noticed repeated work" appears only for repeated-approval evidence.
• Manual or owner-requested proposals state their real origin.
• Owner-facing action language comes from reviewed action descriptors, never a guessed leaf verb.
• Scope is shown from the exact reviewed scope.
• Copy never says work will happen automatically unless the action is execution-backed and the complete scope is enforceable.
• Internal terms such as task grant, standing rule, and artifact lifecycle remain available behind details but are not required for the decision.

6. Receipts and exception surface

After reusable admission, send/store a concise receipt containing:

• what effect occurred;
• which reviewed responsibility/version covered it;
• the target in owner-readable form;
• remaining relevant budget;
• audit/detail reference.

Scope mismatch, budget exhaustion, pause, expiry, drift, or policy change should surface as a short exception/approval request, not repeat the entire permission model.

TDD matrix

• Telegram and terminal render the same canonical review fields and produce equivalent decisions.
• Approve is bound to exact review/artifact/scope digests.
• Reject consumes/closes the pending decision and activates nothing.
• Narrow creates a new proposal and invalidates no historical evidence.
• Pause immediately restores normal approval behavior.
• Resume succeeds only when compatibility revalidation passes.
• Revoke removes live consultation immediately and is idempotent.
• A copied/foreign/replayed callback cannot act for another owner or review.
• Oversized content cannot leave a persisted unreviewable proposal.
• Manual proposal copy never claims repeated approval evidence.
• Unsupported/unexecutable action never receives an Approve-to-automate review.

Invariants

• Owner channel is presentation and authenticated input, not authority logic.
• Every decision remains kernel-verified and digest-bound.
• No model or worker can approve, amend, resume, or revoke authority.
• Preference review remains visually and semantically separate from authority review.

Done when

• One stored review object can be rendered and decided through both Telegram and terminal.
• Approve, Reject, Pause, Resume, and Revoke have owner-path tests.
• Narrow/amend creates a new immutable reviewed proposal.
• Proposal text is provenance-, scope-, and execution-truthful.
• Generic lifecycle code contains no Gmail-specific behavior.

Relationship

Parent: #123.

Requires: #126. Can proceed in parallel with #127/#128 once the contracts are settled.

Blocks the complete Gmail proof.

[George-RD]

Additional channel-neutrality requirement

The current storage/API seam is still Telegram-shaped even outside the renderer: task grants and pending rows carry a raw bound_chat_id: i64, and callbacks/replies use that integer directly. A canonical review object alone will not make the lifecycle portable.

Add a kernel-owned OwnerSurfaceRef/reply target contract (name to settle in #126) that can represent at least:

• verified Telegram private owner chat;
• authenticated local terminal/device session;
• future verified web/mobile owner session;
• optional channel-thread binding from AD-148.

The surface reference must be typed, principal-bound, authenticated/MAC-covered where it crosses a grant, and separated from connector-specific rendering IDs. Telegram IDs may remain in adapter storage, but generic review, decision, pending-action, notification, and receipt code must not accept a naked chat integer.

Migration/compatibility tests should prove existing Telegram grants/pending rows remain valid or fail closed, and terminal review must not fake a Telegram chat ID to reuse the lifecycle.

[coderabbitai]

Coding Plan

Summary

• Define OwnerReviewRequest as one stored, content-addressed, digest-bound review object that is the single security-relevant source every owner surface renders.
• Add channel-neutral, principal-bound DecisionIntent values wired through the existing POST /v1/actions → gate() path, so every decision stays kernel-verified and digest-bound.
• Add an owner-controlled paused standing-rule state with a compatibility-revalidated resume modeled on the artifact.reconfirm ceremony, keeping revoke immediate and idempotent.
• Add a renderer abstraction with Telegram and terminal implementations, plus truthful proposal copy, post-use receipts, and a short exception surface, so the lifecycle is provably not Telegram-defined.

Design Choices

Design Choice 1: How should the OwnerReviewRequest lifecycle state be modeled?

Options Considered:

1. Reuse the artifact Lifecycle enum directly for the review object state.
2. Add a dedicated OwnerReviewState enum for the review object, and keep the standing-rule runtime status as its own typed enum.

Chosen Option: 2

Rationale: A dedicated OwnerReviewState enum keeps decision availability explicit. It avoids overloading Lifecycle with owner-only paused semantics. The standing-rule runtime status stays a separate concern with its own CHECK constraint.

Design Choice 2: How should terminal owner decisions be authenticated as principal-bound?

Options Considered:

1. Generalize resolve() to accept a trait/enum of channel proofs and build a new proof type per channel.
2. Reuse the existing per-channel owner-verification seams (Telegram VerifiedOwnerContext, terminal local_cli_owner envelope check) and bind the resolved principal_id onto the decision.

Chosen Option: 2

Rationale: Reusing the existing verification seams avoids a large identity-layer refactor. It keeps the change scoped. It still yields a channel-neutral principal_id for the decision record.

Design Choice 3: How should "Resume" revalidate compatibility?

Options Considered:

1. Require the full propose → evaluate → approve → activate ceremony for every resume.
2. Add a lightweight resume path that reuses the artifact.reconfirm revalidation shape (byte/digest re-verification, version-staleness, current-version re-check) and refuses expired/drifted rules.

Chosen Option: 2

Rationale: The reconfirm ceremony already implements the exact resume-with-revalidation pattern. Reusing its shape satisfies the requirement. It does this without forcing owners through a full re-approval for a compatible, still-current version.

💡 User Tips

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

Implementation Steps

Phase 1: OwnerReviewRequest contract and content-addressed storage

This phase defines the security-relevant review object and its persistence. The object becomes the single source that every owner surface renders. No renderer may add scope or decisions absent from it.

Task 1: Define the OwnerReviewRequest schema

Add the channel-neutral review contract as a new schema module.

• Create a new module in crates/openspine-schemas/src/ (for example owner_review.rs) and export it from lib.rs.
• Define OwnerReviewRequest binding all ticket-required fields: review type, proposal provenance/evidence, owner-facing responsibility description, exact action descriptor (an ActionId plus canonical structured arguments, mirroring PlanStep), reviewed scope (a rendered, digest-bound projection of the Caveat chain), budgets/rate/expiry/drift behavior, any conditional default, reusable effects, still-approval-required or denied effects, artifact/version/digest identities (ArtifactRef), available decisions, expiry, and current lifecycle state.
• Add an OwnerReviewType enum to distinguish review categories (for example standing-rule proposal, plan approval, draft approval) and a ReviewProvenance field that records real origin (owner-requested, manual, or miner repeated-approval), following the non-retrofittable ArtifactLineage pattern.
• Add an OwnerReviewState enum (for example Pending, Approved, Rejected, Paused, Resumed, Revoked, Expired) and a can_transition validator, mirroring the Lifecycle/TimerDispatchState enum-plus-validator idiom.
• Add a canonical digest() over the whole structured object using digest_of, so the rendered text and the approved digest cannot diverge (WYSIWYS parity, D-045).

Task 2: Persist and content-address the review object

Store the review object so it is durable and content-addressed.

• Serialize the OwnerReviewRequest plaintext and store it through the existing ArtifactStore::put, keeping the returned ArtifactRef as the stored reference; retrieval reuses ArtifactStore::get with its read-time digest re-verification.
• Add a new store module under crates/openspine-kernel/src/store/ (for example owner_review.rs) that persists a review row keyed by id, its ArtifactRef, its OwnerReviewState, the bound principal id, and expires_at, plus an append_audit_conn write inside the same transaction.
• Refuse to persist an approvable review whose full owner-facing rendering would be truncated on the target channel, so oversized content cannot leave a persisted unreviewable proposal.

🤖 Prompt for AI agents

Implement Phase 1: define the channel-neutral OwnerReviewRequest schema and
persist it as a content-addressed object. The goal is to establish the single
security-relevant review object that every owner surface renders.

Steps:
- Create a new module in `crates/openspine-schemas/src/` (for example
`owner_review.rs`) and export it from `lib.rs`.
- Define `OwnerReviewRequest` with these fields: review type, proposal
provenance/evidence, owner-facing responsibility description, exact action
descriptor (an `ActionId` plus canonical structured arguments, mirroring
`PlanStep`), reviewed scope (a rendered, digest-bound projection of the `Caveat`
chain), budgets/rate/expiry/drift behavior, any conditional default, reusable
effects, still-approval-required or denied effects, artifact/version/digest
identities (`ArtifactRef`), available decisions, expiry, and current lifecycle
state.
- Add an `OwnerReviewType` enum to distinguish review categories (for example
standing-rule proposal, plan approval, draft approval).
- Add a `ReviewProvenance` field that records real origin (owner-requested,
manual, or miner repeated-approval), following the non-retrofittable
`ArtifactLineage` pattern.
- Add an `OwnerReviewState` enum (for example `Pending`, `Approved`, `Rejected`,
`Paused`, `Resumed`, `Revoked`, `Expired`) with a `can_transition` validator,
mirroring the `Lifecycle`/`TimerDispatchState` enum-plus-validator idiom.
- Add a canonical `digest()` over the whole structured object using `digest_of`,
so rendered text and the approved digest cannot diverge (WYSIWYS parity, D-045).
- Serialize the `OwnerReviewRequest` plaintext and store it through the existing
`ArtifactStore::put`, keeping the returned `ArtifactRef` as the stored
reference. Use `ArtifactStore::get` for retrieval, which re-verifies the digest
at read time.
- Add a new store module under `crates/openspine-kernel/src/store/` (for example
`owner_review.rs`) that persists a review row keyed by id, its `ArtifactRef`,
its `OwnerReviewState`, the bound principal id, and `expires_at`, plus an
`append_audit_conn` write inside the same transaction.
- Refuse to persist an approvable review when its full owner-facing rendering
would be truncated on the target channel, so no oversized content leaves a
persisted unreviewable proposal.

Phase 2: Standing-rule paused lifecycle and revalidated resume

This phase adds the owner-controlled paused state and the resume/revoke semantics. It keeps paused distinct from system-triggered needs_review and terminal revoked.

Task 1: Introduce a typed standing-rule status and the paused state

Replace the free-form status handling with an explicit status set that includes paused.

• Update crates/openspine-kernel/src/store/standing_rules.rs to add paused to the allowed status values and add a CHECK(status IN (...)) constraint that currently does not exist.
• Audit every live-consultation query site that filters status = 'active' (active_standing_rule_for_action, consult_and_reserve_standing_rule, reserve_standing_rule_budget, standing_rule_is_current, the currency re-check in finalize_standing_rule_reservation, and the EXISTS guard in standing_rules_pending.rs) so paused rules are absent from live consultation.
• Decide and document the supersession behavior in activate_standing_rule_in_tx when a new version activates over a paused rule.

Task 2: Add pause, resume, and revoke store operations

Add owner-controlled transitions with distinct audit events.

• Add pause_standing_rule and resume_standing_rule methods alongside the existing revoke_standing_rule, each writing a distinct audit event (for example standing_rule.paused, standing_rule.resumed), mirroring the standing_rule.revoked pattern.
• Keep revoke immediate and idempotent (touch only rows not already revoked).
• Ensure a pause immediately restores normal approval behavior, because the rule leaves live consultation.

Task 3: Implement compatibility-revalidated resume

Resume only a still-compatible, still-current reviewed version.

• Model resume on the artifact.reconfirm ceremony in pipeline/artifact_reconfirmation.rs: re-verify the reviewed bytes and digest, re-check the rule is still the exact version that was paused, and revalidate policy, descriptor, executor, connector/account, and reviewed scope before returning the rule to active.
• For connector/account revalidation, reuse ConnectorRegistry::breaker_state for connector health and treat account/credential validity per connector without adding connector-specific branches into generic resume code.
• Refuse to resume an expired or drifted rule; require a new reviewed version instead. Write a distinct audit event per rejection reason.
• Use the committed: bool "race already handled, say nothing" idiom so a concurrent resume tap is a safe no-op.

🤖 Prompt for AI agents

Implement Phase 2: add an owner-controlled `paused` standing-rule state,
distinct pause/resume/revoke operations, and a compatibility-revalidated resume
path. The goal is to keep `paused` distinct from system-triggered `needs_review`
and terminal `revoked`, and to ensure resume only reactivates a
still-compatible, still-current reviewed version.

Steps:
- In `crates/openspine-kernel/src/store/standing_rules.rs`, add `paused` to the
allowed status values and add a `CHECK(status IN (...))` constraint, which does
not currently exist.
- Audit every live-consultation query site that filters `status = 'active'`:
`active_standing_rule_for_action`, `consult_and_reserve_standing_rule`,
`reserve_standing_rule_budget`, `standing_rule_is_current`, the currency
re-check in `finalize_standing_rule_reservation`, and the `EXISTS` guard in
`standing_rules_pending.rs`. Update each so `paused` rules are absent from live
consultation.
- Decide and document the supersession behavior in
`activate_standing_rule_in_tx` for the case where a new version activates over a
`paused` rule.
- Add `pause_standing_rule` and `resume_standing_rule` methods alongside the
existing `revoke_standing_rule`. Each method must write a distinct audit event
(for example `standing_rule.paused`, `standing_rule.resumed`), mirroring the
`standing_rule.revoked` pattern.
- Keep revoke immediate and idempotent: touch only rows not already `revoked`.
- Ensure a pause immediately restores normal approval behavior, because the
paused rule leaves live consultation.
- Model the resume path on the `artifact.reconfirm` ceremony in
`pipeline/artifact_reconfirmation.rs`: re-verify the reviewed bytes and digest,
re-check that the rule is still the exact version that was paused, and
revalidate policy, descriptor, executor, connector/account, and reviewed scope
before returning the rule to `active`.
- For connector/account revalidation, reuse `ConnectorRegistry::breaker_state`
for connector health. Treat account/credential validity per connector without
adding connector-specific branches into generic resume code.
- Refuse to resume an expired or drifted rule. Require a new reviewed version
instead. Write a distinct audit event per rejection reason.
- Use the `committed: bool` "race already handled, say nothing" idiom so a
concurrent resume tap is a safe no-op.

Research

The kernel mediates every effect through the pure gate() function in openspine-gate. This function is kernel-verified and digest-bound. No channel bypasses it.

Standing rules store a free-form status TEXT column (active, needs_review, revoked) in crates/openspine-kernel/src/store/standing_rules.rs. Live consultation filters strictly by status = 'active'.

Approval today is Telegram-only and Approve-only. The system uses per-feature callback parsers in crates/openspine-kernel/src/telegram.rs, near-duplicate handlers in pipeline/approval.rs and pipeline/plan_approval.rs, and a generic action-keyed post-approval registry in pipeline/post_approval.rs.

The artifact store (artifact_store.rs) content-addresses encrypted blobs by SHA-256 digest with put/get and read-time re-verification.

Owner identity is anchored by the channel-neutral Principal type. Telegram proves ownership through VerifiedOwnerContext. The terminal lane proves it through envelope fields (Source::Cli + VerificationMethod::LocalCliAuth).

The artifact.reconfirm ceremony (pipeline/artifact_reconfirmation.rs) is the closest existing analog to a revalidated resume.

No OwnerReviewRequest contract, paused state, renderer abstraction, or receipt object exists yet.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement Phase 1: define the channel-neutral OwnerReviewRequest schema and
persist it as a content-addressed object. The goal is to establish the single
security-relevant review object that every owner surface renders.

Steps:
- Create a new module in `crates/openspine-schemas/src/` (for example
`owner_review.rs`) and export it from `lib.rs`.
- Define `OwnerReviewRequest` with these fields: review type, proposal
provenance/evidence, owner-facing responsibility description, exact action
descriptor (an `ActionId` plus canonical structured arguments, mirroring
`PlanStep`), reviewed scope (a rendered, digest-bound projection of the `Caveat`
chain), budgets/rate/expiry/drift behavior, any conditional default, reusable
effects, still-approval-required or denied effects, artifact/version/digest
identities (`ArtifactRef`), available decisions, expiry, and current lifecycle
state.
- Add an `OwnerReviewType` enum to distinguish review categories (for example
standing-rule proposal, plan approval, draft approval).
- Add a `ReviewProvenance` field that records real origin (owner-requested,
manual, or miner repeated-approval), following the non-retrofittable
`ArtifactLineage` pattern.
- Add an `OwnerReviewState` enum (for example `Pending`, `Approved`, `Rejected`,
`Paused`, `Resumed`, `Revoked`, `Expired`) with a `can_transition` validator,
mirroring the `Lifecycle`/`TimerDispatchState` enum-plus-validator idiom.
- Add a canonical `digest()` over the whole structured object using `digest_of`,
so rendered text and the approved digest cannot diverge (WYSIWYS parity, D-045).
- Serialize the `OwnerReviewRequest` plaintext and store it through the existing
`ArtifactStore::put`, keeping the returned `ArtifactRef` as the stored
reference. Use `ArtifactStore::get` for retrieval, which re-verifies the digest
at read time.
- Add a new store module under `crates/openspine-kernel/src/store/` (for example
`owner_review.rs`) that persists a review row keyed by id, its `ArtifactRef`,
its `OwnerReviewState`, the bound principal id, and `expires_at`, plus an
`append_audit_conn` write inside the same transaction.
- Refuse to persist an approvable review when its full owner-facing rendering
would be truncated on the target channel, so no oversized content leaves a
persisted unreviewable proposal.
===============================================================================

Task: 2

Implement Phase 2: add an owner-controlled `paused` standing-rule state,
distinct pause/resume/revoke operations, and a compatibility-revalidated resume
path. The goal is to keep `paused` distinct from system-triggered `needs_review`
and terminal `revoked`, and to ensure resume only reactivates a
still-compatible, still-current reviewed version.

Steps:
- In `crates/openspine-kernel/src/store/standing_rules.rs`, add `paused` to the
allowed status values and add a `CHECK(status IN (...))` constraint, which does
not currently exist.
- Audit every live-consultation query site that filters `status = 'active'`:
`active_standing_rule_for_action`, `consult_and_reserve_standing_rule`,
`reserve_standing_rule_budget`, `standing_rule_is_current`, the currency
re-check in `finalize_standing_rule_reservation`, and the `EXISTS` guard in
`standing_rules_pending.rs`. Update each so `paused` rules are absent from live
consultation.
- Decide and document the supersession behavior in
`activate_standing_rule_in_tx` for the case where a new version activates over a
`paused` rule.
- Add `pause_standing_rule` and `resume_standing_rule` methods alongside the
existing `revoke_standing_rule`. Each method must write a distinct audit event
(for example `standing_rule.paused`, `standing_rule.resumed`), mirroring the
`standing_rule.revoked` pattern.
- Keep revoke immediate and idempotent: touch only rows not already `revoked`.
- Ensure a pause immediately restores normal approval behavior, because the
paused rule leaves live consultation.
- Model the resume path on the `artifact.reconfirm` ceremony in
`pipeline/artifact_reconfirmation.rs`: re-verify the reviewed bytes and digest,
re-check that the rule is still the exact version that was paused, and
revalidate policy, descriptor, executor, connector/account, and reviewed scope
before returning the rule to `active`.
- For connector/account revalidation, reuse `ConnectorRegistry::breaker_state`
for connector health. Treat account/credential validity per connector without
adding connector-specific branches into generic resume code.
- Refuse to resume an expired or drifted rule. Require a new reviewed version
instead. Write a distinct audit event per rejection reason.
- Use the `committed: bool` "race already handled, say nothing" idiom so a
concurrent resume tap is a safe no-op.

💡 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!

[coderabbitai]

🔗 Related PRs

#9 - Implement implement-selected-thread-email-preview-slice (Step 5) [merged]
#14 - Implement harden-approval-and-budgets: WYSIWYS, grant budgets, token hashing (Step 7) [merged]
#19 - Implement implement-artifact-lifecycle-slice: propose/approve/activate (PR-5) [merged]
#29 - docs: interview round - AD-145..153 settle the remaining open questions [merged]
#95 - feat(kernel): standing rules (AD-010/106/013/012, D-107) [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!