npm package: @peacethinking/mediation-workflows
Description: Deterministic mediation flows — XState v5 machines, workflow templates, voting engine for conflict resolution
Latest version: 0.1.0

# @peacethinking/mediation-workflows

> Deterministic mediation flows — XState v5 machines, workflow templates, voting engine.

Production-ready state machines and workflow infrastructure for building AI-assisted mediation platforms. Includes 8 workflow templates, a pure voting engine with conflict resolution, and psychologically-informed emotional check-in logic.

## Install

```bash
npm install @peacethinking/mediation-workflows
```

## Usage

### XState State Machine

```ts
import { participantWorkflowMachine } from '@peacethinking/mediation-workflows';
import { createActor } from 'xstate';

const actor = createActor(participantWorkflowMachine);
actor.start();

// States: idle -> executingElement -> readyToFinalize -> finalized
//         -> waitingForMediation -> reviewingProposals -> voting -> resolved

actor.send({ type: 'START_WORKFLOW', elements: myWorkflowElements });
actor.send({ type: 'ELEMENT_COMPLETED', elementId: 'step-1', data: { text: '...' } });
actor.send({ type: 'NEXT_ELEMENT' });
```

### Workflow Templates

```ts
import { WORKFLOW_TEMPLATES, getTemplateById, cloneTemplate } from '@peacethinking/mediation-workflows';

// 8 templates: Simple, Standard, Advanced, Two-Party,
//              Coached, Human-Only, Dual-Mediator, Face-to-Face

const template = getTemplateById('template_standard');
const { steps, roles } = cloneTemplate(template);
```

| Template | Category | Key Feature |
|---|---|---|
| Simple | simple | Minimal, AI-only proposals, 1 voting round |
| Standard | standard | + Emotional check-ins (flood + 12-emotion) |
| Advanced | advanced | + Surveys, AI review, mediator gate, 3 rounds |
| Two-Party | simple | No mediator, AI handles everything |
| Coached | advanced | Coach + Trusted Ally roles |
| Human-Only | advanced | No AI, mediator creates all proposals |
| Dual-Mediator | advanced | AI + human mediator, combined proposals |
| Face-to-Face | advanced | Live voice conversation with transcription |

### Voting Engine

```ts
import { computeVoteStatistics, resolveConflicts } from '@peacethinking/mediation-workflows';

const result = computeVoteStatistics(options, totalParticipants);
// { optionStats, isComplete, hasConflicts }

if (result.hasConflicts) {
  const resolution = resolveConflicts(options);
  // Uses preference-rating algorithm (highest avg rating wins)
}
```

### Emotional Check-in

```ts
import { assessFloodLevel, getCheckinRequirement } from '@peacethinking/mediation-workflows';

// Gottman-based flooding assessment
const flood = assessFloodLevel(8, 7, 'en');
// { level: 8, isFlooded: true, recommendation: "You are experiencing significant..." }

// Check if a check-in is required
const req = getCheckinRequirement(dialogueConfig, 'BEFORE_VIEWPOINTS');
// { isMandatory: true, isOptional: false, isAvailable: true }
```

## Workflow Element Types

29 step types organized into 7 categories:

- **Setup**: Consent, Role Briefing, Guidelines, Invitation
- **Understanding**: Viewpoint Input, Additional Context, Ally Context, Coach Guidance, Live Conversation
- **Check-ins**: Flood Level, 12-Emotion Radar, Questionnaire
- **Analysis**: AI Review, AI Analysis, AI Reflection, AI Proposal, Human Proposal
- **Review**: Mediator Review, Coach Review, Proposal Review, Mediator Approval
- **Decision**: Voting, Conditional Acceptance, Finalization
- **Flow**: Wait

## License

MIT