Business Workflow DAG and Step Contract Design

Wrote docs/architecture/tasks/mortgage-wf-001/workflow-design/workflow-spec.md. Complete workflow DAG specification establishing 14 step transitions, parallel execution branches, human approval timers, and automated compensation rollbacks.

skill: workflow-design

Workflow Specification: Commercial Mortgage Refinancing [WF-MORT-001]

Summary

This specification establishes the workflow Directed Acyclic Graph (DAG), step transition rules, human-in-the-loop checkpoints, and automated compensation handlers for commercial-mortgage-refinance-workflow v2.0 under run ID mortgage-wf-001. It governs 14 processing steps orchestrating commercial property refinancing deals up to $25M spanning up to 45 days. It decisively resolves the workflow skip vulnerability demonstrated in incident INC-4945 (where an ad-hoc cron database polling script skipped the mandatory Environmental Review step due to a database row lock, accidentally approving an unvetted $18M loan on a contaminated property). The specification establishes a

deterministic workflow DAG, coordinates

parallel verification branches (Title, Appraisal, Environmental), enforces a Credit Committee human approval signal gate with an automated 14-day escalation timer, and provides

atomic compensation rollbacks on application rejection.

Detailed Description

Long-running business workflows that depend on ad-hoc database flags (status = 'PENDING_APPROVAL') evaluated by scheduled cron jobs suffer from race conditions, missing step execution, and zero observability. When multiple cron workers poll the same tables, database locks cause queries to skip rows, leading to skipped regulatory steps. A formal Workflow DAG specification models execution as an explicit state machine: step transitions depend strictly on verified prior step outputs, parallel branches join deterministically, and human approvals wait on durable external signal listeners without burning CPU cycles.

Refinance Application Submitted ($25M Cap)
                  │
                  ▼
[ Step 1: Intake & Entity KYC Validation ]
                  │
       ┌──────────┼──────────┐ (Parallel Verification Fan-Out)
       ▼          ▼          ▼
[ Step 2: Title ] [ Step 3: Appraisal ] [ Step 4: Environmental ]
  Title Search      Property Valuation     Phase 1 EPA Audit (MANDATORY)
       │          │          │
       └──────────┼──────────┘
                  ▼ (Join Barrier: All 3 Steps Must Complete)
[ Step 5: Loan-to-Value (LTV) Ratio Calculation ]
                  │
                  ▼ (LTV <= 65% Validated)
[ Step 6: Human Checkpoint: Credit Committee Approval ]
  ├── Awaits Signal: `CreditCommitteeDecision`
  └── 14-Day Timer: Auto-Escalates to Chief Risk Officer if Unanswered
                  │
       ┌──────────┴──────────┐
       ▼ (APPROVED)          ▼ (REJECTED / EXPIRED)
[ Step 7: Escrow Close ] [ Compensation Handler: Deal Abort ]
  Disburse Funds           Release Liens & Archive Audit Log

Criteria and weights

Comparison

Result

Option C is selected. The workflow is modeled as a deterministic Directed Acyclic Graph; parallel steps synchronize at explicit join barriers; human approvals are gated behind durable signal channels.

Required Mechanisms

1. Workflow DAG Step Execution Matrix [MC-SM-01]

2. Join Barrier & Mandatory Step Invariant [MC-JB-01]

• The Environmental Audit Invariant:
  • Step

S05 (LtvCovenantCalculation) cannot be scheduled until Step

S04 (EnvironmentalAudit) emits a cryptographically signed status ENVIRONMENTAL_CLEAR.

• Bypassing or short-circuiting S04 via configuration override is physically prohibited by workflow engine schema validation.

3. Human Approval Checkpoint & Timer Escalation [MC-HA-01]

• Step S06 pauses workflow execution, persisting state to storage while awaiting an external signal:
  • Signal Name: CreditCommitteeDecision (APPROVE or REJECT).

14-Day Timer: If no signal is received within

336 hours (14 days), the workflow triggers an automated escalation alert to the Chief Risk Officer and extends the timer by 48 hours.

4. Automated Compensation & Rollback Handlers [MC-CR-01]

• If the application is rejected at S05 or S06:
  • Handler CompensateRefinanceApplication executes:
    1. Releases temporary title liens placed during S02.
    2. Refunds unallocated borrower application fees.
    3. Emits MortgageApplicationArchivedEvent to compliance WORM storage.

Invariants and Contracts

Mandatory Step Execution Invariant [INV-WF-01]
  Workflow execution must not proceed past join barriers until all dependent parallel steps have completed.
  Skipping mandatory steps (Title, Appraisal, Environmental) is strictly barred.

Durable Signal Timer SLA [INV-WF-02]
  Human approval steps must configure explicit timeout timers. Workflows must not remain in
  unbounded waiting states indefinitely without automated escalation alarms.

Per-Step Idempotency Token Enforcement [INV-WF-03]
  Every step invocation must carry a deterministic idempotency token derived from `deal_id` and `step_id`.
  Worker retries following network glitches must never re-execute side-effecting financial transactions.

Explicit Unknowns

• External title agency API webhook reliability during municipal holiday closures (G-1).
• Workflow history event log storage footprint on Amazon S3 when archiving 45-day deal timelines (G-2).

Traceability

Verification

No validator was supplied, so no command was run.

Reviewer self-check against workflow design standards:

• Step Integrity: PASS. Join barrier strictly enforces Title, Appraisal, and Environmental completion.
• Human Governance: PASS. Credit Committee approval gated behind durable signal with 14-day SLA timer.
• Compensation Safety: PASS. Rollback handlers release liens and refund fees upon rejection.
• Markdown Hygiene: PASS. Native Markdown syntax strictly adheres to rule_markdown.md.

Open Decisions

• DEC-WF-01: Elena Rostova to determine whether appraisal disputes should branch into a secondary arbitration sub-workflow or restart Step S03 (Owner: Elena Rostova).

Next steps

1. Core Engineering encodes the 14-step DAG in the workflow definition repository.
2. Platform team configures the Credit Committee portal to dispatch signed approval signals.
3. Conduct staging simulation executing 50 concurrent deals with simulated human signal approvals.