Workflow Completeness Contract

Purpose

A feature is not complete because its records can be created and listed. It is complete when every participant can move the work from intent to a clear terminal state without searching the application for the next action.

This contract applies to org, portal, overview, analytics, search, Today, reminders, and every future generated recommendation.

The Unit Of Product Design

The unit of design is a workflow, not a page.

Every workflow must define:

1. the initiating intent
2. the durable record that owns the work
3. every valid state and transition
4. the actor responsible in each state
5. the action available to that actor
6. the destination where the action is performed
7. the handoff to the next actor
8. the completion condition
9. the escalation or follow-up rule
10. the org and portal projections of the same truth

A page is only one projection of that workflow.

Workflow Actionability Contract

Any UI that claims something needs attention must carry these fields from backend truth:

• exact cause: the record or records that triggered it
• exact actor: the role or person who acts next
• exact state: the current durable state
• exact action: a valid transition available now
• exact destination: the record surface where that transition is available
• permission result: whether the viewer can perform it or is only observing it
• completion condition: the state change that removes the item
• escalation: what should happen if it remains unresolved

Generated copy may explain these fields. It must never invent or substitute for them.

Surface Rules

• Detail surfaces expose the current state, its meaning, and the valid next transitions.
• Collection queues group work by actor and state, not by vague health language.
• Overview selects high-value interventions from those same typed records.
• Analytics links to the owning resolution surface, not merely the parent record.
• Search and Today preserve the exact record identifier when opening work.
• Success states hand off to the next likely job when another actor or feature owns the next step.
• The portal shows only explicitly client-visible records, but preserves the same state and next-action truth.
• A permission-limited viewer sees the responsible actor and destination without being offered an action they cannot perform.
• Hiding an intervention lasts only until its causal record, state, action, or count changes.

Core Workflow Map

Workflow	Durable owner	Agency loop	Client loop	Completion
Project delivery	projects, projectTasks, projectUpdates	plan → perform → publish → complete	review progress → respond	project complete with no open delivery exception
Delivery blocker	projectBlockers	record cause/owner/action → resolve	view client-visible cause and agency next action	last open blocker resolved; project resumes
Time	timeEntries	draft/returned → submit → approve/return → lock → invoice	summarized billing visibility only	approved work is invoiced or intentionally non-billable
File request	fileRequests	request → review response → close	acknowledge → submit requested item	request closed with response provenance
Project update	projectUpdates, portalResponses	draft → publish → process feedback	acknowledge/approve/request changes	response handled and update superseded or accepted
Invoice	invoiceRecords plus Stripe	prepare → finalize/send → collect/adjust/void	review → pay	paid, void, or explicitly uncollectible
Subscription	subscriptionRecords plus Stripe	create → monitor → change/cancel	view coverage and billing state	active coverage or intentional termination
Quote/contract	commercial record plus responses/signatures	prepare → send → revise/execute	review → accept/sign/request changes	accepted/executed or declined/expired
Portal access	contact + identity + grant	invite → monitor → revoke/repair	accept → use → recover access	active intended grant or explicit revocation
Reminder	reminders	schedule → surface → complete/dismiss	none in v1	completed or intentionally dismissed
Support/new work	request record	triage → respond → close	submit → receive response	acknowledged resolution or accepted work

Current Implementation Decisions

Project blockers

• blocked is no longer a free-form project status choice.
• Adding a blocker records the cause, next actor, next action, follow-up date, and visibility, then marks the project blocked.
• Resolving the last blocker restores the project to its previous working state.
• Legacy blocked projects without blocker records show an explicit repair state.
• Client-visible blockers project into portal project next actions.

Time submission and review

• States are draft, submitted, returned, and approved.
• Only the entry owner submits draft or returned time.
• Reviewers can approve submitted time or return it with a required reason.
• Editing a reviewed entry resets it to draft and clears review provenance.
• Only approved time can be locked and treated as invoice-ready.
• Overview interventions distinguish submit, review, and returned-correction work.

Typed interventions

Overview attention records carry a subject, state, actor, action, destination, and record count. Direct routes currently cover project blockers, time entries, invoices, billing setup, and contact setup. The same shape is the required extension point for the remaining workflows.

Personal and team work queues

• Today is the execution surface; Overview remains the agency-level prioritization surface.
• Today combines tasks with typed operational work from blockers, time review, file submissions, client requests, and unprocessed client feedback.
• Multi-person teams default to work assigned to the viewer plus actionable shared queues. Solo workspaces remove redundant team-scope controls and show the complete queue.
• Operational items retain their exact record destination and never masquerade as completable tasks when their real workflow requires review, resolution, or a response.

Client feedback processing

• Portal responses are durable work until an authorized agency user marks them handled.
• A response records handling time, handler, and an optional internal handling note.
• Reopening a response returns it to Today without changing the client-authored response.
• The client workspace is the resolution surface for this handoff; deep links focus the exact response.

Public-Beta Completion Audit

Use this as the release gate for each feature family.

Feature family	Current workflow status	Next hardening gate
Projects/tasks/updates	Core loop live; blockers, response processing, and typed feedback outcomes are first-class	surface resulting task, revision, or reply links in the feedback-handling UI
Time	submission, return, approval, and lock loop live	add pagination and bulk reviewer actions without weakening transition rules
Billing	provider-backed lifecycle live; missing-profile setup is actionable	make every overdue/coverage intervention point to the exact affected commercial record
Files/requests	request and response records live	open exact request from every analytics/search projection and clarify close ownership
Portal	shared project blockers and next actions live	unify client attention into typed portal interventions
Quotes/contracts	durable commercial states live	audit every revision/signature/decline handoff and terminal-state copy
Access/people	grant model live	audit invite failure, expiry, recovery, and revocation destinations
Today/reminders	personal/team operational queue and exact destinations live	add configurable escalation policies for overdue work
Analytics	project-risk routing is reason-aware	replace remaining parent-level links with exact causal destinations

Definition Of Done

A feature cannot be marked complete while any common state:

• has no visible next action
• routes to a surface where that action is unavailable
• merges different responsible actors into one queue
• claims a cause that the backend cannot identify
• disappears without a durable state transition
• remains visible after its completion condition
• exposes internal-only detail to the portal
• requires users to reconstruct context by scanning unrelated pages