TenantAtlas/specs/332-product-process-flow-system-v1/spec.md

Feature Specification: Spec 332 - Product Process Flow System v1

• Feature Branch: 332-product-process-flow-system-v1
• Created: 2026-05-24
• Updated: 2026-05-25
• Status: Draft
• Input: restore-run create wizard drift review + repo implementation + tests

Reconciliation Note

Spec 332 was reconciled from the narrower specs/332-restore-run-preview-productization path into the intended specs/332-product-process-flow-system-v1 scope. The previous path underrepresented the actual product/process-flow goal and caused restore safety state to drift too late into Preview.

Restore Preview productization remains part of Spec 332, but it is only one consumer slice. The primary deliverable is a reusable Product Process Flow pattern with Restore Run Create as the first consumer.

Spec Candidate Check (mandatory — SPEC-GATE-001)

• Problem: Restore safety, proof, and gate progression became concentrated too late in the wizard. Step 1 drifted toward a plain backup selector, while meaningful restore readiness moved mostly into Preview.
• Today's failure: Operators cannot judge restore viability from the start of the flow. This weakens safe decision-making, obscures the next blocked gate, and hides proof/evidence structure until late in a high-risk workflow.
• User-visible improvement: Restore Run shows a reusable Product Process Flow from the first step: a decision card, backup quality summary, full vertical restore safety gates, restore proof aside, and collapsed diagnostics. Later steps show compact safety status, while Preview remains decision-first.
• Smallest enterprise-capable version: Introduce a reusable Product Process Flow pattern and wire it into the existing Restore Run create wizard. Reuse existing restore safety, preview, and backup quality resolvers. No new persisted entities.
• Explicit non-goals: No new restore execution engine, no new queue orchestration, no new Graph contract layer, no new risk taxonomy, and no new route family.
• Permanent complexity imported: Shared wizard presentation pattern, bounded Blade/UI state, step gating, and focused feature/browser regression coverage.
• Why now: Restore is high-risk and operator-critical. Safety/proof state must be truthful from step 1, not deferred until preview.
• Why not local: The flow pattern is reusable across risky multi-step workflows. Leaving it embedded only in Preview encourages repeated drift and inconsistent operator guidance.
• Approval class: Core Enterprise
• Red flags triggered: UI surface behavior change (wizard), high-risk operator workflow, evidence/proof messaging. Defense: bounded reuse, explicit copy rules, feature tests, browser smoke.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexität: 1 | Produktnähe: 2 | Wiederverwendung: 2 | Gesamt: 11/12
• Decision: approve

Spec Scope Fields (mandatory)

• Scope: tenant (environment-bound restore wizard)
• Primary Routes:
  • /admin/workspaces/{workspace}/environments/{environment}/restore-runs/create
• Data Ownership:
  • Uses existing RestoreRun draft state; no new tables.
  • Safety, proof, preview, diagnostics, and backup quality state remain derived from existing restore/backup resolvers.
• RBAC:
  • Tenant membership required.
  • Existing restore capabilities remain the authority; this spec does not change authorization policy rules.

UI Surface Impact (mandatory — UI-COV-001)

• No UI surface impact
• Existing page changed
• New page/route added
• Navigation changed
• Filament panel/provider surface changed
• New modal/drawer/wizard/action added
• New table/form/state added
• Customer-facing surface changed
• Dangerous action changed
• Status/evidence/review presentation changed
• Workspace/environment context presentation changed

UI/Productization Coverage (mandatory)

• Route/page/surface: Restore Run create wizard, with Product Process Flow pattern applied across Step 1 through Confirm.
• Design depth: Manual Review Required (operator-critical, risky workflow).
• Repo-truth level: repo-verified (feature + browser tests).
• New pattern required: yes; reusable Product Process Flow pattern using existing restore safety / proof / backup quality state.
• Screenshot required: no (covered by dedicated browser smoke assertions).
• Dangerous-action review required: yes; execute restore remains high-friction and must not imply recovery proof before execution/post-run evidence exists.
• Coverage files updated or explicitly not needed: N/A - scope is covered via focused feature tests + browser smoke.

Goals

1. Introduce a reusable Product Process Flow pattern for risky multi-step product workflows.
2. Apply that pattern to Restore Run Create without changing the underlying restore domain model.
3. Show restore safety from the start of the wizard, not only in Preview.
4. Keep Preview decision-first, but no longer as the only place where safety/proof state appears.
5. Keep Confirm high-friction before execution.
6. Prevent false recovery-proof claims before execution/post-run evidence exists.

Product Contract

Step 1: Select Backup Set

Render, in this order:

1. Restore Safety decision card
   • Status
   • Reason
   • Impact
   • Primary next action
2. Backup set selector
3. Backup quality summary
   • item count
   • degraded items
   • metadata-only items
   • assignment issues
   • orphaned assignments
   • clear copy that input quality does not prove that execution is safe or that recovery is verified
4. Full vertical Product Process Flow
   • Title: Restore safety gates
   • Steps:
     • Usable source selected
     • Target selected
     • Scope/dependency mapping
     • Validation
     • Preview
     • Confirmation
     • Execution and evidence when represented separately
5. Restore Proof aside
   • Source backup
   • Target environment
   • Requested by
   • Restore scope
   • Operation proof
   • Post-run evidence
   • Diagnostics
6. Diagnostics collapsed by default

Step 2 and later

• Show step-specific content first.
• Show compact Restore Safety Status instead of the full seven-gate flow by default.
• Keep Restore Proof available where useful.
• Keep dependency mapping details hidden by default until the resolver is opened explicitly.
• When dependency mapping is expanded, present it as Resolve target mappings with resolver progress, one shared explanation, and no repeated per-row helper copy.
• Block Next while required mappings remain unresolved.
• When dependency mapping opens the target group picker without cached directory groups, show a task-specific empty state:
  • modal heading: Resolve target group mapping
  • source group context remains visible
  • empty state copy explains cache availability, not tenant group absence
  • primary CTA uses Open group sync unless direct in-modal sync is explicitly supported
  • search/filter controls do not dominate the modal when the cache is empty
• Show:
  • completed gates count (for example 2/7 gates complete)
  • next gate
  • execution available/unavailable state
  • View safety gates

Step 3: Validate

• Validation blockers remain explicit.
• Next is blocked when validation is blocked.

Step 4: Preview

• Preview remains decision-first.
• Compact safety status is shown by default.
• Preview copy must reflect actual gate state and avoid false blocker language once Preview is complete.

Step 5: Confirm

• Confirmation remains high-friction before execution.
• No false recovery-proof claim is shown before execution/post-run evidence exists.

Non-Goals

• No changes to restore execution behavior, queue orchestration, or Graph contract paths.
• No new persisted state families, tables, or enum taxonomies.
• No separate “trust framework” outside the Product Process Flow pattern and Restore Run consumer.

Implementation Notes

• Reuse existing restore safety, preview integrity, execution readiness, and backup quality resolvers.
• Prefer shared Product Process Flow presentation primitives over one-off Preview-only copy.
• Keep diagnostics collapsed by default and avoid raw payload presentation in the default wizard path.
• Gating continues to use Filament wizard step lifecycle hooks and Halt where appropriate.

Testing / Lane / Runtime Impact

• Test purpose / classification: Feature + Browser smoke
• Validation lanes: confidence + browser
• Updated tests:
  • Step 1 renders full Product Process Flow
  • Step 1 renders Restore Safety decision card
  • Step 1 renders Restore Proof aside
  • Step 1 usable source gate reflects actual backup contents
• Step 2+ render compact safety status
• Step 2 resolver mode stays explicit and blocks progression while required mappings remain unresolved
• Step 2 empty group picker renders task-specific cache-empty guidance
  • Preview remains decision-first
  • Diagnostics remain collapsed
  • No false recovery-proof claims are visible

Acceptance Criteria

• Only one Spec 332 directory exists in the repo: specs/332-product-process-flow-system-v1.
• Step 1 is not a bare backup selector page.
• Step 1 renders the full Product Process Flow, Restore Safety decision card, backup quality summary, Restore Proof aside, and collapsed diagnostics.
• A backup with usable captured items marks the usable source gate complete.
• A backup with zero/no captured items does not mark the usable source gate complete.
• Step 2 and later render compact Restore Safety Status by default, not the full gate flow.
• Step 2 hides mapping details by default and only shows resolver details after explicit expansion.
• Step 2 blocks Next until required mappings are resolved.
• The Step 2 group mapping picker shows task-specific cache-empty guidance and does not imply the tenant has no groups.
• Preview remains decision-first and is not the only place where safety/proof state appears.
• Confirm remains high-friction before execution.
• No false recovery-proof claim appears before execution/post-run evidence exists.
• Feature tests and browser smoke pass.