T-HUB/docs/design/spec-review-workflow.md

# Spec — Group Review & Signoff for Posts ("Editorial Workflow")

Status: DRAFT for proposals
Owner: product owner
Date: 2026-10-07
Inputs: user requirements, codebase inventory (explore agent), background research (Hootsuite/Sprout approval features, four-eyes/maker-checker compliance patterns)

## 1. What the user asked for (verbatim intent)

1. Posts can be **primed to go out**, then reviewed and edited by others in the group.
2. Roles: **editors** (can edit, can NOT post/approve) and **reviewers** (give the OK).
3. System configurable so **2–3 people sign off** on a post before it publishes.
4. Reviewers can **approve, or deny with reasoning** (reason mandatory).
5. A **parallel chat** per post with voting/approval buttons.
6. Easy **scrolling through existing working posts** (the in-review queue).
7. When posts publish, they are **archived**.
8. Ability to make our own posts **invisible or delete** them — **admin-only** features.
9. Think through the whole system; spec the needs.

## 2. Current system (facts from codebase inventory)

### 2.1 Publishing state machine
- States in DB CHECK (`migrations/006_publishing.sql:7-8`): `editing, in_review, approved, rejected, scheduled, published`. TS mirrors: `publishing.service.ts:8`, web `api-types.ts:64`.
- Transitions are guarded CAS UPDATEs (`WHERE id=$1 AND state=$4`) via `transition()` helper (`publishing.service.ts:275-292`):
  - `editing→in_review` submitForReview (perm `approval.request`)
  - `in_review→approved` approve (perm `approval.grant`, stamps `reviewer_user_id`)
  - `in_review→rejected` reject (perm `approval.grant`; reason goes ONLY into audit diff, not the draft row)
  - `approved→scheduled` schedule (inserts `scheduled_publications`, perm `publication.schedule`)
  - `scheduled→approved` cancelSchedule
  - `scheduled→published` by scheduler activity (`publish.activity.ts:181-184`)
- **Approval record: NONE.** Only `drafts.reviewer_user_id` (single reviewer, last-writer-wins) + audit events. No quorum structure exists.
- **`rejected` is terminal** — there is NO resubmit path today. This feature must add one.
- Temporal: one workflow `scheduledPublish(idempotencyKey)` proxying one activity, **no signals/queries**. API starts it fire-and-forget with `startDelay`; durable `scheduled_publications` row (pending/in_flight/done/failed) is source of truth; sweeper `publishing_due_schedules()` re-starts missed workflows.

### 2.2 Data model
- `drafts(id, workspace_id, author_user_id, post jsonb, state, reviewer_user_id, created_at, updated_at)` — post payload = `{text, mediaAssetIds[], visibility, scheduledAt?, providerMetadata}`. **No soft-delete, no hidden flag, no delete endpoint at all.**
- `scheduled_publications` — `UNIQUE(draft_id)` (one schedule per draft). `publications` — outcome rows (remote_id, idempotency_key).
- All tables: FORCE RLS tenant_isolation on `app.workspace_id` + workspace-immutability triggers + `sp_app` grants. **Drafts are workspace-scoped only — no group column.**

### 2.3 RBAC
- 10 roles seeded (`002_rbac_seed.sql`): Owner, Admin, Publisher, Editor, Approver, Analyst, Moderator, VideoPublisher, StreamOperator, BroadcastOperator.
- `approval.grant`: only Owner/Admin/Approver. `approval.request`: Owner/Admin/Publisher.
- Enforcement: `RbacGuard` + `@RequirePermission()` decorator; guard verifies HMAC session → workspace `authz_epoch` (fail-closed 401 on mismatch) → permission via `role_permissions JOIN memberships(status='active')` inside `withTenant`.
- **Roles are per-workspace only** (`memberships.role`, UNIQUE(workspace_id,user_id) — one role per user per workspace). **`group_members` has NO role column** — no per-group roles exist.

### 2.4 Groups
- Tables (`008_groups.sql`): groups, group_members (no role), group_connections, group_assets. Denormalized workspace_id + composite FKs prevent cross-tenant groups.
- Epoch: any group_members change fires `bump_authz_epoch()`; sessions carry authzEpoch; guard compares live. Membership mutations mint a replacement token in the same tx (`{token}` response pattern).
- Connection scoping: `getVisibleConnections` — Owner/Admin see all; others see union of group connections via their memberships. Guard-side `userCanUseConnection` reads role from DB.

### 2.5 Realtime & chat
- **No WS transport exists.** `realtime/gateway.ts` is an authz port only (`authorizeSubscription` checks session, workspace, epoch, `stream.view`). No topics, no client code.
- Web Inbox is a fixtures-only two-pane chat UI (conversation list + thread bubbles + reply box). Reusable as visual pattern, no backend.

### 2.6 Frontend
- Compose (`compose/page.tsx`): tiptap editor, target chips, visibility, approval select, schedule; `publish()` chains `create→submit→[approve]→[schedule]` gated on `can()`; "Recent drafts" sidebar with STATE_TONE badges is the only post list today.
- `/approvals` is a 10-line stub; `/calendar` stub.
- Streams columns (`components/streams/column.tsx`): `@tanstack/react-virtual` useVirtualizer, j/k keyboard nav — reusable pattern for the working-posts queue.
- Audit page (236 lines) with diff viewer exists.

### 2.7 Audit
- `audit_log` hash-chained per workspace (`audit_hash = sha256(prev|actor|action|target_id|epoch)`), SECURITY DEFINER append fns, `audit_verify_chain`. Services write via `appendTenantAudit` (after-commit) or same-tx `SELECT audit_append(...)`. Scheduler writes with `actor_role='sp_scheduler'`.

## 3. Background research — patterns to draw from

### Social tools (Hootsuite, Sprout)
- Workflow shapes: **linear, tiered (multi-level), parallel, conditional**. Sprout steps support **Any vs All** sign-off ("any 1 of step's approvers" / "all must approve").
- **Post-locking after approval**: any post-approval edit re-triggers the chain. Hootsuite: "Once approved, the post is locked; changes send it back through approval."
- **Expired queue**: if not approved by scheduledAt, publish FAILS, post moves to Expired (author re-schedules + resubmits). 90-day auto-reject of stale pending items.
- Rejected → author edits → resubmits. Rejection notes surface to author.
- **Approval Activity** panel: every edit (who/when) + threaded internal comments + current step; approvers can edit-before-approve; tag members; notifications (digest + hourly reminders).
- Approvals inbox filters: Assigned-to-me, Created-by-me, Rejected, Expired.
- Teams of approvers (not individuals) to avoid bottlenecks; duplicate-reviewer skip.

### Four-eyes / maker-checker (compliance-grade)
- **Self-approval must be structurally impossible** — server-side check `approver ≠ author`, dedicated error, not policy.
- **Approve a frozen snapshot, not a moving target**: submit seals content (hash); edits after submit = new submission + new approval cycle; prior snapshots stay in audit trail. Reviewer sees the real diff.
- **Deny requires non-empty reason** (empty reason refused); approvals/denials recorded with actor+timestamp+snapshot hash.
- Eligibility re-checked at every transition (not just submit).
- Parallel double-approval (Signavio): parallel split/join, either order, automatic gateway; enforce distinct reviewers at assignment.
- Edge cases to model explicitly: reviewer leaves mid-review (votes revoked? reassigned?), vacation delegation, emergency admin override (logged as override), conflict discovered late.
- State machine enforced in BOTH app logic and DB triggers (defense in depth).
- Metrics: approval cycle time, approvals per reviewer (rubber-stamp detection).

## 4. Requirements (normative for proposals)

### R1 Lifecycle
- New/extended states covering: draft/editing → **primed/submitted for review** → in-review → approved (quorum met) → scheduled → published → **archived**; deny → **needs-changes** (back to author/editor with reasons); **resubmit** path (currently missing — `rejected` is terminal today).
- If a scheduled time passes without quorum → **expired** state (post does NOT publish; author notified; re-prime after re-approval).

### R2 Roles & permissions
- **Editor**: can edit group posts (content), cannot approve, cannot publish.
- **Reviewer**: can approve/deny with mandatory reason, cannot edit content.
- Roles must be assignable **per group** (group-scoped), coexisting with workspace roles. Author can never approve their own post (structural, server-side). Admin/Owner retain override power (logged as override).
- Existing `approval.grant`/`approval.request` permissions are the workspace-level seeds; extend, don't break, current 10-role model.

### R3 Quorum signoff
- Configurable **N approvals required** (2–3 typical) — decide where config lives (workspace default + per-group override? per-connection?) and who sets it (admin-only).
- Parallel (any-N-of-eligible) semantics by default; justify if you add tiered/sequential mode.
- Vote rules: one live vote per reviewer per submission; vote change allowed while in-review (with new reason) or immutable — pick and justify. Deny = single vote sends to needs-changes. Quorum met → auto-transition approved (→ scheduling continues if schedule set).

### R4 Staleness & integrity
- Content edits during review must NOT silently invalidate approvals: pick a model (frozen snapshot + new cycle on edit, vs edit-with-approval-dismissal + diff shown) and justify. Snapshot hash in audit log.
- Reviewer must always see exactly what they're approving (rendered post + diff since last review).

### R5 Review chat
- Per-post thread: messages from group members + **system events** (submitted, edits, approvals/denials with reasons, state changes) rendered inline.
- **Approve / Deny+reason buttons in the chat surface** for eligible reviewers.
- Realtime delivery: no WS transport exists today — propose transport (WS gateway wiring, SSE, or polling) with epoch/authz integration; justify choice.

### R6 Working-posts queue (UI)
- Scrollable list of in-flight posts: state chips, quorum progress (e.g. "2/3 ✓"), filters (needs-my-review, needs-changes, expiring soon), keyboard-friendly (j/k pattern from Streams).
- Post detail: rendered post preview + version diff + chat/vote panel + schedule info.

### R7 Archive & moderation
- Published posts land in an **archive view** (read-only, chat history preserved for record).
- **Hide** (invisible to members; badge for admins) and **delete** (hard or soft — justify) of posts — **space-admin-only**, new permissions, hash-chained audit events, epoch-safe.
- Decide moderation scope: archive-only or also drafts/working posts.

### R8 Security & audit (mandatory repo patterns)
- Everything through existing RbacGuard/`@RequirePermission`, FORCE RLS + tenant isolation on new tables, sequential migration `009_*`, hash-chained audit events for every state transition and vote, epoch re-token where membership/role changes affect pending reviews (reviewer removed from group → their pending votes must be revoked/re-counted).

### R9 Non-goals (this phase)
- Email/external notifications (design the hook, don't build), mobile-specific UI, per-platform conditional routing, AI-assisted review.

## 5. Open design questions (proposals must answer explicitly)

1. Group-scoped role storage: column on `group_members` vs separate `group_member_roles` table vs reusing workspace roles — tradeoffs?
2. Snapshot model: full content copies per version vs content-hash + immutable version rows?
3. Where does quorum config live and what's the precedence (workspace default → group override)?
4. Chat transport: WS (wire the existing authz port) vs SSE vs polling — cost/complexity/ordering guarantees?
5. Deny semantics: 1-deny-returns-to-author vs majority-deny vs configurable; what happens to other cast approvals on deny?
6. Re-review after edit: full reset vs dismiss-only-changed-scope (recommend one, note the other as future)?
7. Scheduled-time race: quorum completes at T-1min to scheduledAt — auto-publish or require manual re-confirm?
8. Author is also the only reviewer in a tiny group — deadlock handling (admin override path)?
9. Migration path for existing single-step approvals (`reviewer_user_id` backfill)?
10. Should reviewers see who else approved before them (peer pressure) or vote blind until quorum?

## 6. Proposal deliverable format (each lane produces `runs/wp5/proposal-<lane>.md`)

1. Executive summary — the 5 sharpest decisions you make.
2. Data model — migration SQL sketch (009+, following repo conventions: FORCE RLS, tenant isolation, immutability triggers, sp_app grants, audit fns reuse).
3. State machine — full state/transition table with guards and who can fire each.
4. RBAC — new permissions, group-role mechanism, self-approval exclusion, admin override.
5. Quorum engine — vote lifecycle, staleness/snapshot semantics, deny handling, race conditions.
6. Review chat — data model, event types, transport decision, authz integration.
7. UI plan — screens (queue, detail, archive), reuse of existing components, keyboard model.
8. Edge cases — the ugly ones (reviewer leaves, deadline race, deadlock, epoch churn mid-vote).
9. Audit & security — event list, chain integration, RLS notes.
10. Phased implementation plan — WP-sized chunks with test gates.
11. Test plan sketch — the 10 tests that would catch the worst regressions.

Constraints: NestJS + Postgres 16 + Temporal patterns as in repo; TS strict, no `as any`; follow existing naming/style; do not break the 10-role seed contract; proposals are designs — do NOT implement.