[RFC]: Intelligent review and dynamic presentation surfaces for the long-horizon control plane

[huangruiteng]

Outcome

Define and incrementally ship an intelligent review and presentation surface for LoopX: a typed interaction layer that minimizes human attention without hiding material risk, authority, evidence, or planning context.

The target is not “more AI copy in the dashboard.” It is a control-plane compiler that can answer, for every material state delta or proposed action:

• who needs to see it;
• whether it should interrupt now, join a digest, remain available on demand, or stay silent;
• what is the smallest evidence-backed decision frame;
• whether the action may execute directly, needs compact review, or requires an explicit protected gate;
• which fallback remains safe while a decision is pending;
• which receipt/readback proves what happened afterwards.

This follows LoopX's product objective: maximize Agent output while minimizing Human Attention, and its technical objective: run reliably without intervention, run better with high-value intervention.

Why the current surface is not yet one coherent system

Main already contains strong but separately evolved pieces:

• attention_queue and Goal Channel projections decide which Goal state is visible;
• typed Chat action proposals provide preview/apply, state fingerprints, validation evidence, gates, and receipts;
• planning_horizon and action portfolio expose bounded strategic context to Agents;
• review_batch_v0 provides deterministic cold-path ranking and exact decision-digest binding;
• periodic report turns material stage boundaries into bounded human-facing summaries;
• Effect Program and domain reducers provide ordered effects, readback, settlement, and replay semantics;
• Dashboard, Lark Goal Channel, CLI status, review packets, and reports render different projections.

But these pieces do not yet share one interaction vocabulary. The practical symptoms are:

1. some reversible actions pay a redundant confirmation cost;
2. some important states show a recommended action without the alternatives, fallback, evidence gap, or broader planning horizon needed to judge it;
3. every channel makes its own compression choices, so Dashboard, IM, digest, and CLI can differ in salience or completeness;
4. “needs attention,” “needs a decision,” “needs authority,” and “should notify now” are too easy to conflate;
5. model-generated summaries can improve readability but cannot safely own risk, authority, or completeness;
6. receipts exist, but the post-action surface does not always make the verified outcome and recovery path proportionate to the action.

PR #3785 is a useful first vertical example: Goal stop remains a typed preview/apply operation with optimistic rollback, gate escalation, readback, and receipt, while the ready reversible path no longer asks for a second click. Resume and delete retain review. That policy is currently local to the UI and should not become a growing list of button-name exceptions.

Product definition: an intelligent review surface

An intelligent review surface is a role-aware, channel-aware, evidence-bounded projection of current truth and possible transitions. It covers four connected jobs:

1. Intelligent selection

• prefer material deltas over repeated snapshots;
• distinguish blocking authority needs, optional leverage, execution anomalies, progress milestones, and ordinary background activity;
• deduplicate related facts and preserve supersession/lineage;
• suppress unchanged monitor polls and stale recommendations;
• keep completeness and overflow explicit when information is omitted.

2. Intelligent presentation

• show the decision-relevant delta first, not raw control-plane state;
• use progressive disclosure: compact first screen, evidence and diagnostics on demand;
• preserve source, freshness, confidence/evidence status, and current planning context;
• adapt density to Dashboard, mobile/IM, digest, or Agent handoff without changing semantics;
• present alternatives and a safe fallback when a preferred action is blocked or not yet executable.

Presentation intelligence also includes choosing the right form, not only
the right amount of text. Depending on the typed fact shape and audience, the
same control plane may prefer:

• a status glance or decision card for one bounded action;
• a comparison table for route/provider/replan alternatives;
• a timeline for stage progress, recovery, or settlement history;
• a dependency graph for Todo, Explore, or cross-Agent relations;
• an evidence matrix for acceptance or benchmark claims;
• a milestone report for weekly or bounded-stage review;
• a dynamic Dashboard for frequently changing multi-lane state;
• a linear document or living Wiki for durable shared context.

Main already contains useful domain-local precedents: Explore presentation
selects canonical/executive views and board styles from typed signals while
preserving source lineage; periodic-report compiles one normalized document
into Markdown/HTML before separately authorized delivery; content-ops has typed
layout plans and layout validation. The RFC should reuse these lessons without
creating one universal renderer.

3. Intelligent review and interaction

• silent: no material user value; preserve state without notification;
• inform: show or digest a verified result; no decision required;
• direct_with_receipt: apply a ready, reversible, bounded action and make rollback/readback visible;
• compact_review: ask one focused decision with delta, consequence, alternatives, and evidence;
• protected_gate: require explicit scoped authority for irreversible, high-blast-radius, privacy/permission-expanding, or otherwise protected effects;
• repair_escalation: surface state drift, incomplete evidence, stale fingerprints, or failed readback instead of pretending an action completed.

These are interaction modes, not authority grants. A presentation compiler may require more review than the domain minimum; it may never weaken a canonical gate or convert missing evidence into permission.

4. Intelligent feedback

• distinguish accepted proposal, effect attempted, effect committed, readback verified, and projection reconciled;
• keep success lightweight but inspectable;
• make failure actionable without forcing the user through a generic drawer;
• escalate a newly discovered gate or stale state to the correct review surface;
• bind later decisions and retries to stable action/state digests.

Proposed architecture boundary

Introduce one provider-neutral typed read model, provisionally interaction_surface_plan_v0, compiled from existing authoritative facts:

canonical Goal/Todo/Gate/Evidence/Receipt state
  + typed action proposal / planning inventory / material delta
  + surface context (role, channel, capacity)
  -> TypeScript interaction-surface compiler
       -> attention selection
       -> review frame
       -> interaction mode
       -> disclosure/completeness plan
       -> abstract presentation form + artifact lifecycle plan
       -> receipt/readback presentation
  -> Dashboard | Lark | digest | CLI/review packet | Agent handoff

The compiler owns projection policy only. It does not own:

• Goal/Todo transitions or replan rules;
• canonical permission classification or decision-scope consumption;
• provider effects;
• effect settlement or receipt truth;
• arbitrary model inference from raw logs or prose.

Minimum item shape

The RFC should refine a compact shape similar to:

{
  "surface_item_id": "stable-id",
  "subject": {"kind": "goal_action", "id": "...", "revision": "..."},
  "audience": "operator",
  "attention_kind": "decision",
  "interaction_mode": "compact_review",
  "material_delta": {"changed": ["..."], "unchanged": ["..."]},
  "decision_frame": {
    "question": "...",
    "recommended_option": "...",
    "alternatives": ["..."],
    "safe_fallback": "..."
  },
  "risk_facts": {
    "reversibility": "reversible",
    "blast_radius": "goal_local",
    "authority": "already_scoped",
    "privacy_change": false
  },
  "evidence": {
    "status": "complete",
    "refs": ["..."],
    "freshness": "current"
  },
  "disclosure": {
    "summary_fields": ["..."],
    "detail_ref": "...",
    "complete": true,
    "omitted_count": 0
  },
  "presentation": {
    "intent": "review_milestone",
    "preferred_form": "milestone_report",
    "fallback_form": "linear_document",
    "persistence": "durable_artifact",
    "update_mode": "supersede",
    "reason_codes": ["bounded_stage_closed"]
  },
  "post_action": {
    "required_readback": true,
    "receipt_ref": null,
    "undo_or_recovery": "..."
  }
}

Risk facts must be typed domain outputs or policy inputs, never inferred from button labels or substring rules. Invalid combinations should be unrepresentable or rejected: for example, a protected authority requirement cannot compile to direct_with_receipt.

The form plan is provider-neutral. A living Wiki may be rendered by Lark Wiki,
a repository document, or another provider; a milestone report may become
Markdown, HTML, a Lark document, or a card. Creating/updating Wiki content,
publishing HTML, or sending a report remains a separate effect with stable
artifact identity, source revision/digest, idempotency, authority, and exact
readback. A generated artifact is not proof of publication.

To avoid duplicated maintenance, living documents should default to
projection-backed patching with stable semantic block ids, explicit
supersession/retirement, and unchanged-block preservation—not whole-page model
rewrites.

The role of models

Models may help with:

• compressing an already bounded fact set into clearer language;
• proposing salience ranks, grouping, titles, or likely user questions;
• adapting explanation depth to an audience;
• detecting a possible missing alternative or evidence gap for deterministic validation.

Models may not own:

• permission or authority classification;
• evidence completeness;
• irreversible/direct-execution decisions;
• the identity or digest of the state being reviewed;
• receipt/readback truth;
• silent suppression of a canonical gate or repair condition.

The typed compiler must remain useful without a model. Optional model advice is an untrusted proposal, validated against the same bounded facts and measurable for false suppression/escalation.

Coverage across the long-horizon lifecycle

The RFC should explicitly cover, without implementing all at once:

Phase	High-value surface
Goal authoring	clarify objective, acceptance, boundary, and missing authority without exposing a giant form
Planning/replan	show material strategy delta, affected frontier, alternatives, and acceptance gap
Execution	keep ordinary progress quiet; expose bounded session state and meaningful intervention points
Monitor/wait	show material change and released successor, not repeated unchanged polling
Gate/decision	ask one scoped question and show safe independent fallback work
Delivery	show artifact/evidence delta, review readiness, and exact protected effect
Settlement	show committed/readback-verified outcome, partial failure, retry, or repair
Terminal/acceptance	distinguish Todo exhaustion from Goal acceptance and explain remaining gaps

Relationship to existing contracts

• Attention queue / Goal Channel projection: remain source read models; the new plan compiles presentation and interaction from them rather than replacing status truth.
• Typed Chat action proposal: remains the preview/apply and fingerprint boundary; the plan determines how a proposal is presented, not whether the domain action is legal.
• review_batch_v0: remains a cold-path multi-candidate ranking and digest-binding contract. It can become one input or sink, but is not the hot-path per-item interaction policy.
• Planning inventory/horizon: remains Agent-facing planning context. Shared facts and completeness should be reused; operator review must not create a second Todo worldview.
• Human Attention Wishlist: remains an optional, non-blocking human-leverage subtype. Wishlist delivery is one attention kind, not the general surface compiler.
• Periodic report: remains a capability-owned stage summary and delivery workflow. Its material trigger and audience selection can feed digest surfaces.
• Effect Program: provides effect identity, order, failure, replay, and settlement facts. It must not become a generic UI policy engine.
• Capability hooks: may contribute bounded provider-neutral projection candidates, but core admits schemas and owns final interaction semantics; providers gain no write authority.

Smallest useful implementation slice

1. Characterize current Dashboard action paths: direct Goal stop; reviewed resume/delete; protected gate; stale/readback failure.
2. Define a TypeScript action_review_plan_v0 subset for typed action proposals, including closed interaction modes and typed risk facts.
3. Compile current Goal lifecycle behavior through that pure reducer and render the same Dashboard behavior from its output.
4. Preserve the existing Python preview/apply service and receipt contract; do not migrate action execution in this slice.
5. Add fixture parity plus negative/mutation cases proving a protected or incomplete proposal cannot become direct.
6. Expose exact completeness and detail refs, but do not add a second source store.

This slice converts #3785 from a UI-local policy into one typed, testable vertical contract while staying reviewable and reversible.

Later stages

• compile attention queue deltas into inform | digest | interrupt | silent delivery plans;
• reuse the same plan in Lark Goal Channel and dashboard first-screen projections;
• add replan/acceptance review frames and planning-context disclosure;
• integrate review_batch_v0 for bounded multi-item review sessions;
• add optional model-assisted explanation/ranking behind deterministic validation and shadow evaluation;
• learn per-operator presentation preferences only after privacy, portability, reset, and evaluation contracts are explicit.

Non-goals

• replacing canonical state with frontend state;
• replacing domain gates with an AI risk score;
• auto-approving protected effects;
• streaming all Agent reasoning or raw logs to the user;
• making every status item actionable;
• introducing a global generic effect executor;
• requiring an LLM to render the control plane;
• implementing personalization, notification scheduling, and every channel in the first PR.

Validation and product metrics

Protocol and implementation validation:

• deterministic output and stable total ordering;
• exact revision/digest binding and stale rejection;
• protected/incomplete/unknown cases fail to review or repair, never direct;
• direct actions retain preview, apply, rollback, readback, and receipt;
• dashboard/Lark/digest fixtures preserve semantic parity while using different density;
• omitted/overflow facts expose completeness and a truthful detail path;
• public/private boundary tests reject raw transcripts, logs, credentials, and local paths;
• accessibility and mobile review flows remain operable.

Product evaluation should measure:

• human interventions and attention minutes per accepted Goal outcome;
• false interrupts and missed material escalations;
• decision latency and decision reversal/regret rate;
• repeated opening of detail immediately after a compact review (under-disclosure signal);
• stale-action and failed-readback recovery rate;
• user understanding of what changed and whether the effect actually committed;
• Agent throughput and Goal acceptance quality, so attention reduction cannot hide degraded outcomes.

Deliverables

• bilingual architecture RFC with decision boundary, schemas, illegal states, rollout, and validation;
• RFC index entry and links to this tracking issue and [Direction]: Operator surface and IM integration #3244;
• characterization fixtures for current action/review paths;
• TypeScript action-review-plan vertical slice;
• Dashboard integration without behavior regression;
• follow-up issue for cross-channel attention/digest compilation;
• provider-neutral dynamic form and living-document artifact contract;
• later shadow evaluation for optional model advice.

Related: #3244, #3479, #3778, #3785, Human Attention Wishlist RFC, Goal artifact lifecycle projection RFC, Desktop Execution Frontends RFC, Agent Loop Effect Interpreter RFC.

[huangruiteng]

RFC implementation is now available in #3787. It expands the proposal from action confirmation into a typed intelligent interaction surface: attention selection, review mode, disclosure depth, dynamic form selection, and durable report/Wiki artifact lifecycles. The RFC keeps canonical state and provider authority separate from presentation planning; its first implementation slice remains the bounded TypeScript action_review_plan_v0 vertical.