The staging backend is working, but the reviewer experience is not. The next build should stop treating the staging page like an engineering audit screen and turn it into a real review workflow: plain language, visible diffs, clear decision paths, and explicit outcomes for approve, reject, and request changes. If Pete cannot tell what changed, why it changed, and what each button does, the feature is not review-ready no matter how solid the underlying promotion flow is.

1. Problem Statement and Goal

The current /uas-database/staging page exposes internal system language instead of supporting a human review decision.

Pete's review feedback surfaced the real problem clearly:

• terms like canonical, promoted, validation clear, evidence refs, and dev labels like Vinny validation are not self-explanatory in the UI
• the page does not explain what counts as approval, what happens after approval, or what happens if Pete does not want to approve a change
• the current side-by-side snapshot view does not highlight what actually changed, so a reviewer can stare at two panels and still not know what decision to make
• there is no first-class reject or send-back path
• the surface looks like a debug/admin view, not a working review queue

The goal is to turn staging into a reviewer-centered change queue where Pete can quickly answer five questions:

1. What changed?
2. Why did it change?
3. What evidence supports it?
4. Should I approve it?
5. If I do not approve it, what should happen next?

2. Success Metric

This work is successful when all of the following are true:

1. Pete can open a staged company change and see a plain-English summary of the proposed edit without reading JSON.
2. The review screen shows changed fields first, with before/after values clearly highlighted.
3. The page supports three explicit human outcomes:

• approve and apply
• request changes
• reject

1. System checks are labeled as system checks, not implied human approval.
2. Internal test labels and debug wording are hidden from the normal reviewer surface.
3. A reviewer can explain what each decision button does without extra coaching from chat.
4. A no-op proposal, meaning no visible change from the live record, is flagged clearly and cannot masquerade as meaningful review work.

Pete should be able to verify this by opening one staged proposal and deciding what to do in under two minutes, without needing a glossary from Vinny.

3. Current State

The shipped staging foundation is documented in the UAS Database First-Class Domain Tranche 2 Handoff.

What exists today:

• a staging queue at /uas-database/staging
• staged proposal records under data/uas-database/staging/
• proposal detail and promotion APIs
• conflict detection when the live company record changed after a proposal was staged
• git-backed history when an accepted proposal is applied

What is missing from the human workflow:

• plain-language labels
• reviewer-focused summaries
• field-level diff presentation
• explicit reject and request-changes actions
• visible explanation of what each decision does
• separation between system validation and human approval
• handling for no-op proposals and dev/test proposals in the normal queue

Today the surface answers engineering questions like “is the base timestamp stale?” but not reviewer questions like “what changed and should I approve it?”

4. Platform Capabilities

OpenClaw and Mission Control already support the core mechanics needed for this feature.

What is already available:

• Mission Control route and API handler patterns for custom app surfaces
• file-backed proposal storage under data/uas-database/staging/
• canonical record write path for approved changes
• conflict detection based on the live company file timestamp
• artifact-driven specs and handoffs
• git-backed history for accepted promotions

What still requires custom implementation:

• reviewer-friendly wording and visual design
• derived diff summaries between live and proposed records
• explicit review states beyond staged and promoted
• reject and request-changes actions and their storage model
• optional dev/test visibility controls so validation records do not pollute the real queue

This is not a native OpenClaw feature. It is a custom Mission Control workflow built on top of file-backed domain logic.

5. Community Patterns

Proven review systems do three things well: they show the change, define the allowed reviewer decisions, and separate “system validity” from “human approval.”

GitHub pull request reviews use three top-level reviewer outcomes: comment, approve, and request changes. Their deeper reviewing proposed changes guidance centers the diff itself, not raw object state. That is the right pattern to copy here.

The lesson for the UAS Database is simple:

• the primary object is the proposed change, not the raw proposal JSON
• the primary action is a review decision, not an implementation verb like “promote to canonical”
• the UI should show what changed first, then allow approve, request changes, or reject

We do not need to clone GitHub visually. We do need to copy its clarity.

6. Options

Option A: Label cleanup only

Pros:

• quickest patch
• improves the worst wording immediately

Cons:

• does not solve “what changed?”
• does not create reject or request-changes paths
• still leaves the page structurally confusing

Option B: Reviewer-first staging workflow

Pros:

• fixes language, workflow, and decision clarity together
• preserves the tranche-2 backend investment
• creates a reusable pattern for future staged record types

Cons:

• more UI and domain work than a label patch
• requires new proposal states and actions

Option C: Company-page review only

Pros:

• reduces one dedicated screen
• may feel more natural when reviewing one company at a time

Cons:

• weakens the inbox/queue model
• makes it harder to see pending work across companies
• mixes authoring and review too tightly

7. Recommendation

Choose Option B.

Do not waste time polishing a structurally confusing review surface. The right move is to keep the tranche-2 storage and promotion engine, but replace the human-facing staging UI with a reviewer-first workflow.

The next build should make these product decisions explicit:

1. Rename the page from Staged proposals to something like Pending company changes.
2. Rename Inbox to Pending changes.
3. Rename Review to Review change.
4. Replace internal verbs like Promote to canonical with Approve and apply.
5. Replace internal statuses with plain-English reviewer statuses.
6. Show a compact “what changed” summary above any raw detail.
7. Show changed fields only by default, with before/after values highlighted.
8. Add Request changes and Reject as first-class decisions.
9. Treat validation as a support signal only, for example: “System checks passed,” not “Validation clear.”
10. Hide raw JSON behind an advanced toggle.
11. Hide or isolate dev/test proposals from the normal reviewer queue.
12. Flag no-op proposals clearly, for example: “No meaningful visible changes detected.”

8. Security Considerations

Main risks:

• a reviewer accidentally applying a change without understanding what it does
• a rejected or sent-back proposal still mutating the live company record
• stale proposals getting applied after the live record changed
• dev/test proposals being mistaken for real content
• raw JSON or internal metadata distracting the reviewer into bad decisions

Mitigations:

• require explicit Approve and apply action before any canonical write
• make Reject and Request changes non-destructive to the live company record
• keep stale proposal blocking in place, but rewrite the message in plain English
• add reviewer-visible explanation for each action before click
• hide advanced/debug material by default
• preserve audit history for every review decision

9. Implementation Scope

Data and state model

Extend staged proposal handling to support reviewer outcomes beyond the current binary state.

At minimum:

• support reviewer states such as:
• pending-review
• approved-applied
• changes-requested
• rejected
• store decision metadata:
• reviewed at
• reviewed by
• decision note or reason
• distinguish system-generated validation/test proposals from real reviewer work, either through a proposal provenance field or a reviewer-visible filter rule

API and domain logic

Update or add:

• mission-control/lib/uas-database/staging.ts
• mission-control/lib/uas-database/history.ts
• mission-control/lib/uas-database-types.ts
• mission-control/app/api/uas-database/staging/route.ts
• mission-control/app/api/uas-database/staging/[id]/route.ts
• new decision routes or a consolidated review-decision route for:
• approve and apply
• request changes
• reject

Add derived helpers for:

• field-level diff generation between live and proposed company records
• no-op detection
• plain-language status mapping
• queue filtering that hides dev/test proposals by default

UI

Rework:

• mission-control/components/uas-database/StagingWorkspace.tsx
• any supporting components extracted from it for cleaner layout and review cards

Expected UX shape:

• left column: pending changes list with clear status, company name, short summary, changed-field count, and review age
• right column: review detail with:
• one-sentence change summary
• plain-English system status
• changed fields first
• linked evidence summary in normal language
• advanced section for JSON only if needed
• three primary reviewer actions:
• approve and apply
• request changes
• reject

Copy changes

Replace wording like:

• canonical → live record
• promoted → approved and applied
• validation clear → system checks passed
• stale base → live record changed after this draft was created
• evidence refs → linked sources

Remove dev-facing copy like:

• Vinny validation
• post-fix validation proposal
• other test or plumbing terms from the normal queue

10. Validation Criteria

Pete should be able to verify the finished build with these checks:

1. Opening /uas-database/staging shows a reviewer-friendly list of pending changes, not an engineering inbox.
2. Every visible proposal answers these questions without opening JSON:

• what changed
• why it changed
• what state it is in

1. Selecting a proposal shows changed fields first, with before/after values.
2. If there are no visible meaningful changes, the page says so clearly.
3. The action buttons are plain English and clearly distinct:

• approve and apply
• request changes
• reject

1. Rejecting a proposal does not alter the live company record.
2. Requesting changes does not alter the live company record and keeps a review trail.
3. Approving and applying updates the live company record and preserves history.
4. A stale proposal shows a plain-English warning that the live record changed after the draft was created.
5. Raw JSON is not required for normal review.
6. Dev/test proposals do not clutter the default reviewer queue.

11. Category

Tool

12. Context Loading

For any work on this feature, load these files in this order:

1. Active product spec: /Users/vinny/.openclaw/workspace/artifacts/spec_mission_control_uas_database.md
2. Domain foundation spec: /Users/vinny/.openclaw/workspace/artifacts/spec_uas_database_first_class_domain.md
3. Current staging implementation handoff: /Users/vinny/.openclaw/workspace/artifacts/uas_database_first_class_domain_tranche2_handoff_2026-04-27.md
4. Current staging UI: /Users/vinny/.openclaw/workspace/mission-control/components/uas-database/StagingWorkspace.tsx
5. Current staging domain logic:

• /Users/vinny/.openclaw/workspace/mission-control/lib/uas-database/staging.ts
• /Users/vinny/.openclaw/workspace/mission-control/lib/uas-database/history.ts
• /Users/vinny/.openclaw/workspace/mission-control/lib/uas-database-types.ts

1. Current staging routes:

• /Users/vinny/.openclaw/workspace/mission-control/app/api/uas-database/staging/route.ts
• /Users/vinny/.openclaw/workspace/mission-control/app/api/uas-database/staging/[id]/route.ts
• /Users/vinny/.openclaw/workspace/mission-control/app/api/uas-database/staging/[id]/promote/route.ts

13. Guardrails

• Do not auto-apply any staged change without an explicit reviewer action.
• Do not let Reject or Request changes mutate the live company record.
• Do not use internal engineering terms as the primary reviewer copy.
• Do not require the reviewer to parse raw JSON to make a normal decision.
• Do not show unchanged fields before changed fields.
• Do not treat system validation as human approval.
• Do not hide stale-draft conflicts; explain them in plain English.
• Do not delete review history when a proposal is rejected or sent back.
• Do not clutter the reviewer queue with developer validation proposals by default.

14. Handoff

The final result should be delivered in three layers:

1. An updated Mission Control staging review UI at /uas-database/staging
2. A short implementation handoff artifact summarizing decisions, changed files, and validation
3. A plain Discord completion note to Pete that explains:

• what changed in the reviewer experience
• how to approve a change
• how to reject or request changes
• what remains for any later tranche