# The completion path on the canonical surface: finish an initiative from the workspace ## Desired outcome An operator takes an initiative from "all work items done" to COMPLETED without leaving the workspace UI. When an initiative is held, the workspace says exactly what holds it — open planning, undisposed deferred scope, an unanswered continuation decision, a running assessment, a holding verdict — and every blocker names the action that clears it. Disposing deferred scope, closing planning, answering a continuation decision, discarding a proposed wave, re-running the assessment, and clearing a holding verdict (waive or attest) are all workspace actions. Nobody has to open the standalone UI, query the database, mint a token, or run the plan CLI to learn why an initiative still shows Active. ## Motivation Two initiatives just finished every work item and then sat in EXECUTING, indistinguishable in the workspace from initiatives still working. Diagnosing and resolving them took direct database queries, internal `/api/*` calls with a hand-minted admin JWT, and the plan CLI on the production box — for what turned out to be routine operator decisions: dispose six deferred-scope entries, answer two continuation checkpoints, close planning, waive one assessment criterion that pointed at deliberately deferred work. None of that was a malfunction. The gate behaved as designed at every step. The problem is that the design is invisible from the workspace: the canonical surface was built for the happy path (create → brief → plan → approve → execute) and the completion path never got routes. The workspace is the platform's UI going forward — the standalone UI is now legacy-frozen — so an initiative's ending must be as operable from the workspace as its beginning. ## Current state - `canonicalWave` serializes wave/state/summary/eligibility/items and **drops `deferredScope`, `continuationCheckpoint`, and `closesPlanningIfApproved`**. No canonical route carries `planningStatus`. The workspace cannot render what it is never sent; its app code has zero occurrences of any of these concepts. - Canonical wave actions are list, approve, and generate/continue (POST to the collection, pass chosen server-side from state). **Close planning, reopen planning, answer a continuation decision, retract a deferred capability, and discard a proposed wave exist only on the internal `/api/*` surface.** - **Defer-and-file has no HTTP surface at all.** It is plan-CLI only, requires `DATABASE_URL` plus a `ROADMAP_DIR` checkout, and writes roadmap markdown into the orchestrator repo — so filing RM-0006…RM-0012 each required a CLI run on the box plus a hand-made PR. The roadmap services already go through a `RoadmapPort` abstraction (`deferAndFileNew(db, port, input)`), so the store behind it is swappable. - **The brief-assessment gate has no canonical surface.** The pending/running/holding/delivered view, waive-criterion, attest-criterion, and reassess exist only internally. The domain already exposes `deriveBriefAssessmentView` as a server-decided view model — documented as existing precisely so clients render the same verdict — but no canonical route serves it. - The one completion signal the workspace does receive — release-readiness blocker "initiative planning is still open" — names the state, not the cause (which entries block and why), offers no action, and sits under Release Readiness where nobody looks while asking "why is this initiative still Active?" - The standalone UI has all the affordances (deferred-scope list with disposition labels, Close/Force-close, ContinuationDecision, BriefAssessmentPanel with a self-refreshing running state), because it bypasses the canonical surface and reads the database through internal routes. It is legacy-frozen; nothing new lands there. - Assessment runs are observable in principle (`brief_assessment_run_started_at` plus a single-flight staleness window); the running/pending states exist in the domain view model. - The roadmap store of record today is git-backed markdown (`roadmap/RM-XXXX-*.md`, currently RM-0001…RM-0012) in the orchestrator repo, read via `RoadmapStore` over `ROADMAP_DIR`. - orchestrator#457 (fixed): retraction and force-close now record dispositions the closure gate honors. The only remaining pre-fix row (retracted, null disposition) sits on a SUPERSEDED plan of the completed Composer initiative, where no gate reads it; no live initiative carries one. ## Product principles - A held initiative explains itself: every blocker is visible where the operator is already looking, states its cause, and carries its action. - Same verdict everywhere. The workspace and the gate must agree, because the workspace renders the same server-decided view the gate evaluates — never a client-side re-derivation. - Waiver and attestation remain opposite records (an operator accepting a gap vs. affirming work was performed) and must be presented as such, never as one "clear" button. - Destructive or scope-losing actions (force-close waiving remaining entries; discarding a proposed wave) are explicit, named, and confirmed — not the default path. - A long-running assessment shows that it is running; the operator never reloads to find out. ## Architectural principles - The canonical `/orchestrator/*` surface is the contract clients are written against; the workspace consumes only it. Closing the gap means extending that contract, not teaching the workspace to reach around it. - Server-decided view models: canonical routes serve the existing domain derivations (`deriveBriefAssessmentView`, `canClosePlanning`/`unresolvedDeferredScope`, release-eligibility reasons) rather than raw rows the client must interpret. - The database is the roadmap's source of record; markdown is a generated export view, never hand-authored. Roadmap access stays behind the existing `RoadmapPort` so the CLI and services swap stores without changing callers. - Actor is server-derived from the verified platform token (ADR-0007); two-tier RBAC as on the rest of the canonical surface (reads member, mutations admin). - Mutations are idempotent under retries (the existing `requestId` pattern) and every one lands in the timeline with its actor and reason. - The dispositions vocabulary (#361/#363/#457) is the single source of truth for what blocks closure; no new parallel flags. - Work splits by repository along the contract line: Xyence/orchestrator — roadmap store migration (DB persistence behind `RoadmapPort`, one-time markdown import, cadenced markdown export back into `roadmap/`); canonical routes and view models for planning status, deferred scope with per-entry disposition and blocking flag, close/reopen planning, answer continuation decision, retract, defer-and-file, discard proposed wave, waive/attest criterion, reassess, and a served brief-assessment view including the running state. Every one of these actions already exists internally or in the CLI; reuse the services. Xyence/workspaces — render the held-state explanation on the initiative page (not only under release readiness); deferred-scope list with dispositions and actions; continuation-decision prompt; discard affordance on a proposed wave; assessment panel with pending/running/holding/delivered states, waive/attest, and a reassess action, self-refreshing while running. Xyence/console — none expected (gateway proxies verbatim). ## Decisions - The roadmap store of record moves into the database, with markdown as a generated export — the existing roadmap files RM-0001 through RM-0012 are the one-time import seed, RM ids remain stable, and this is what makes a canonical defer-and-file action possible (the controller cannot commit to the git repo; the store move removes the need to). - Wave discard joins this initiative — the internal discard action gets a canonical equivalent and a workspace affordance, so a proposed wave can be rejected with a recorded reason from the workspace, not only approved. - Workspace-triggered reassessment is in scope — the operator can re-run the brief assessment from the workspace, subject to the existing single-flight slot; a run already in flight is reported, not duplicated. - The standalone UI is legacy-frozen — no parity fixes land there; the completion path is built once, on the canonical surface, rendered by the workspace. - The markdown export lands back in the repo on a cadence — a generated roadmap snapshot, clearly marked as generated and never hand-edited; the export is asynchronous and never in the critical path of any workspace action, and a filing that succeeded is durable in the database whether or not the next export has run. - Roadmap promotion gets a workspace affordance in a later wave, not this one — plan import and roadmap-status stay CLI-only for now; this is deliberately deferred scope, not an omission, and should be planned as such. - Deferred scope keeps gating planning closure — a terminal disposition is retracted, waived, or durably-filed-deferred with a roadmap id and captured flag; this gate stays. - The brief assessment keeps gating completion — waive and attest remain the two operator paths to clear a holding criterion; this gate stays too. - New canonical actions follow the established POST-to-collection pattern where the server picks the pass from state — the model wave generation already uses; state decides, not client flags. ## Rejected / deferred alternatives - Having the workspace call the internal `/api/` surface directly — that surface is the standalone UI's private plumbing with no contract stability. - Keeping the roadmap store git-backed with the controller opening PRs via its GitHub App credentials — rejected in favor of the database store because a completion action must not depend on a PR merging; the cadenced markdown export is different, being a snapshot off the critical path whose late landing blocks nothing. - Auto-closing planning when the last work item completes — closure is an operator decision precisely because deferred scope may still need disposing; the fix is visibility and reachable actions, not automation that silently waives. - Auto-waiving assessment criteria that match filed roadmap items — the waiver is the operator's judgment; the UI may suggest the linkage. ## Constraints - Single production box; the workspace app and controller stay separate containers speaking HTTPS with the existing service JWT and roles claim. - The roadmap-store migration must import RM-0001…RM-0012 without renumbering — dispositions in live initiative rows link to these ids (`roadmapItemId`), and those links must survive. - The plan CLI keeps working through the migration (re-pointed at the DB-backed port), since it remains the only tool for bulk operations like `import` and `promote` until those get surfaces. - Console gateway proxies the relevant subtrees verbatim; no Console work expected. - Existing internal routes and the standalone UI keep working unchanged throughout; this is additive to the contract. ## Invariants - No initiative can reach COMPLETED with an undisposed deferred-scope entry or an uncleared holding assessment — unchanged. - Every disposition, closure, waiver, attestation, and wave discard records its actor and reason in the timeline. - The closure gate is evaluated from dispositions only; anything the workspace displays derives from the same evaluation the gate uses. - Roadmap RM-ids are stable across the store migration; a `roadmapItemId` recorded before it resolves after it. - No credential reaches the workspace client; canonical mutations remain admin-tier. ## Repository scope - Xyence/orchestrator - Xyence/workspaces - Xyence/console ## Expected behavior - An initiative whose work is done but which is held shows a single, prominent explanation on its workspace page: what holds it, why, and the buttons that resolve it. - The deferred-scope list shows each entry's disposition (deferred-and-filed with its RM link, retracted, waived, still blocking) using the same vocabulary the gate uses. - Answering a continuation decision, retracting an entry, filing an entry to the roadmap, discarding a proposed wave, and closing planning are workspace actions with confirmation and recorded reasons; force-close is separate, named as a waiver of N entries, and confirmed. - Filing an entry to the roadmap creates the roadmap record directly — no CLI, no PR — and the entry immediately shows its RM link. - After closing planning, the page shows "assessment pending," then a visibly-running assessment, then the verdict — without a reload. The operator can re-run the assessment; a run already in flight is reported, not duplicated. - A holding verdict lists each unmet criterion with its evidence and offers waive (reason required) and attest (affirmation required) per criterion; clearing the last one completes the initiative immediately, visibly.