@agile-vibe-coding/avc 0.1.1 → 0.3.1

package/kanban/client/src/components/ceremony/CeremonyWorkflowModal.jsx

@@ -0,0 +1,1133 @@
+import { useState } from 'react';
+import { X, Pencil } from 'lucide-react';
+import { AgentEditorPopup } from '../settings/AgentEditorPopup';
+import { CheckEditorPopup } from '../settings/CheckEditorPopup';
+import { ProviderSwitcherButton } from './ProviderSwitcherButton';
+
+// Human-readable labels for agent slugs
+const AGENT_LABELS = {
+  // Sponsor Call
+  'mission-scope-generator':         'Mission Scope Generator',
+  'mission-scope-validator':         'Mission Scope Validator',
+  'suggestion-ux-researcher':        'UX Researcher',
+  'suggestion-product-manager':      'Product Manager',
+  'suggestion-deployment-architect': 'Deployment Architect',
+  'suggestion-technical-architect':  'Technical Architect',
+  'suggestion-security-specialist':  'Security Specialist',
+  'architecture-recommender':        'Architecture Recommender',
+  'question-prefiller':              'Question Prefiller',
+  'project-documentation-creator':   'Documentation Creator',
+  'validator-documentation':         'Documentation Validator',
+  // Sprint Planning + Seed (shared)
+  'doc-distributor':                      'Doc Distributor',
+  'feature-context-generator':            'Feature Context Generator',
+  // Sprint Planning
+  'epic-story-decomposer':                'Epic/Story Decomposer',
+  'story-scope-reviewer':                 'Story Scope Reviewer',
+  'project-context-extractor':            'Project Context Extractor',
+  'agent-selector':                       'Agent Selector',
+  'context-writer-epic':                  'Context Writer (Epic)',
+  'context-reviewer-epic':                'Context Reviewer (Epic)',
+  'context-writer-story':                 'Context Writer (Story)',
+  'context-reviewer-story':               'Context Reviewer (Story)',
+  'doc-writer-epic':                      'Doc Writer (Epic)',
+  'doc-writer-story':                     'Doc Writer (Story)',
+  'story-doc-enricher':                   'Story Doc Enricher',
+  'validator-selector':                   'Validator Selector',
+  'validator-epic-solution-architect':    'Solution Architect (Epic)',
+  'validator-epic-developer':             'Developer (Epic)',
+  'validator-epic-security':              'Security (Epic)',
+  'validator-epic-backend':               'Backend (Epic)',
+  'validator-epic-frontend':              'Frontend (Epic)',
+  'validator-epic-ux':                    'UX (Epic)',
+  'validator-story-developer':            'Developer (Story)',
+  'validator-story-qa':                   'QA (Story)',
+  'validator-story-test-architect':       'Test Architect (Story)',
+  'validator-story-solution-architect':   'Solution Architect (Story)',
+  'validator-story-security':             'Security (Story)',
+  'validator-story-backend':              'Backend (Story)',
+  'validator-story-frontend':             'Frontend (Story)',
+  'validator-story-ux':                   'UX (Story)',
+  'story-splitter':                   'Story Splitter',
+};
+
+// ── Domain check perspectives (matching src/cli/checks/{epic|story}/*.json) ──
+
+const DOMAIN_CHECK_PERSPECTIVES = [
+  'solution-architect', 'developer', 'security', 'devops', 'cloud',
+  'backend', 'database', 'api', 'frontend', 'ui', 'ux',
+  'mobile', 'data', 'qa', 'test-architect',
+];
+
+// ── Step type config ──────────────────────────────────────────────────────────
+
+const STEP_TYPE_CONFIG = {
+  generate: { label: 'Generate',       cls: 'bg-blue-50 text-blue-700 border-blue-200' },
+  validate: { label: 'Validate',       cls: 'bg-amber-50 text-amber-700 border-amber-200' },
+  refine:   { label: 'Refine',         cls: 'bg-orange-50 text-orange-700 border-orange-200' },
+  input:    { label: 'User Input',     cls: 'bg-purple-50 text-purple-700 border-purple-200' },
+  cross:    { label: 'Cross-validate', cls: 'bg-indigo-50 text-indigo-700 border-indigo-200' },
+  output:   { label: 'Write',          cls: 'bg-emerald-50 text-emerald-700 border-emerald-200' },
+  read:     { label: 'Read',           cls: 'bg-sky-50 text-sky-700 border-sky-200' },
+  process:  { label: 'Process',        cls: 'bg-slate-50 text-slate-600 border-slate-200' },
+};
+
+const PHASE_COLOR_CONFIG = {
+  blue:    { dot: 'bg-blue-500',    label: 'text-blue-600' },
+  purple:  { dot: 'bg-purple-500',  label: 'text-purple-600' },
+  amber:   { dot: 'bg-amber-500',   label: 'text-amber-600' },
+  green:   { dot: 'bg-green-500',   label: 'text-green-600' },
+  emerald: { dot: 'bg-emerald-500', label: 'text-emerald-600' },
+};
+
+// Loop group color palettes
+const LOOP_C = {
+  amber: {
+    border:    'border-amber-400',
+    bg:        'bg-amber-50',
+    hdr:       'bg-amber-100',
+    hdrBorder: 'border-amber-300',
+    text:      'text-amber-800',
+    subtext:   'text-amber-600',
+    line:      'bg-amber-400',
+    chip:      'bg-amber-200 text-amber-900',
+    arrow:     'text-amber-500',
+    condLine:  'bg-amber-300',
+  },
+  indigo: {
+    border:    'border-indigo-400',
+    bg:        'bg-indigo-50',
+    hdr:       'bg-indigo-100',
+    hdrBorder: 'border-indigo-300',
+    text:      'text-indigo-800',
+    subtext:   'text-indigo-600',
+    line:      'bg-indigo-400',
+    chip:      'bg-indigo-200 text-indigo-900',
+    arrow:     'text-indigo-500',
+    condLine:  'bg-indigo-300',
+  },
+};
+
+// ── Phase builders ────────────────────────────────────────────────────────────
+//
+// Step metadata fields (in addition to type / label / agent / agents):
+//   stageKey        — key in ceremony.stages to read/write the model
+//   validationKey   — 'top' (ceremony.validation.model) or area name ('documentation', 'context')
+//   sharedWith      — string shown instead of a select; marks a secondary reference to the same key
+//   loopParamType   — 'missionGen' | 'docContext' | 'crossValidation'
+//   loopParamReadOnly — true: show values read-only (params already editable in a sibling loop)
+
+function buildSponsorCallPhases(ceremony, missionGenValidation) {
+  return [
+    {
+      id: 'mission',
+      label: 'Mission & Scope',
+      color: 'blue',
+      steps: [
+        {
+          type:     'generate',
+          label:    'Generate mission statement & initial scope',
+          model:    ceremony.stages?.suggestions?.model,
+          stageKey: 'suggestions',
+          agent:    'mission-scope-generator',
+        },
+        {
+          type:          'loop-group',
+          loopParamType: 'missionGen',
+          loop: {
+            max:       missionGenValidation?.maxIterations ?? 3,
+            threshold: missionGenValidation?.acceptanceThreshold ?? 95,
+          },
+          steps: [
+            {
+              type:          'validate',
+              label:         'Validate quality against acceptance threshold',
+              model:         ceremony.validation?.model,
+              validationKey: 'top',
+              agent:         'mission-scope-validator',
+            },
+            {
+              type:       'refine',
+              label:      'Refine based on validation issues',
+              model:      ceremony.stages?.suggestions?.model,
+              stageKey:   'suggestions',
+              sharedWith: 'Mission generator',
+              agent:      'mission-scope-generator',
+            },
+          ],
+        },
+      ],
+    },
+    {
+      id: 'questionnaire',
+      label: 'Questionnaire',
+      color: 'purple',
+      steps: [
+        {
+          type:  'input',
+          label: '5 project definition questions (user-provided or skipped)',
+        },
+        {
+          type:       'generate',
+          label:      'Auto-fill any skipped questions',
+          model:      ceremony.stages?.suggestions?.model,
+          stageKey:   'suggestions',
+          sharedWith: 'Mission generator',
+          agents: [
+            { slug: 'suggestion-product-manager',      note: 'fills Initial Scope' },
+            { slug: 'suggestion-ux-researcher',        note: 'fills Target Users' },
+            { slug: 'suggestion-deployment-architect', note: 'fills Deployment Target' },
+            { slug: 'suggestion-technical-architect',  note: 'fills Technical Considerations' },
+            { slug: 'suggestion-security-specialist',  note: 'fills Security & Compliance' },
+          ],
+        },
+        {
+          type:     'generate',
+          label:    'Architecture recommendation',
+          model:    ceremony.stages?.['architecture-recommendation']?.model,
+          stageKey: 'architecture-recommendation',
+          agent:    'architecture-recommender',
+        },
+        {
+          type:     'generate',
+          label:    'Pre-fill answers from architecture analysis',
+          model:    ceremony.stages?.['question-prefilling']?.model,
+          stageKey: 'question-prefilling',
+          agent:    'question-prefiller',
+        },
+      ],
+    },
+    {
+      id: 'documentation',
+      label: 'Documentation',
+      color: 'amber',
+      steps: [
+        {
+          type:     'generate',
+          label:    'Generate project documentation (doc.md)',
+          model:    ceremony.stages?.documentation?.model,
+          stageKey: 'documentation',
+          agent:    'project-documentation-creator',
+        },
+        {
+          type:          'loop-group',
+          loopParamType: 'docContext',
+          loop: {
+            max:       ceremony.validation?.maxIterations ?? 100,
+            threshold: ceremony.validation?.acceptanceThreshold ?? 95,
+          },
+          steps: [
+            {
+              type:          'validate',
+              label:         'Validate documentation quality',
+              model:         ceremony.validation?.documentation?.model ?? ceremony.validation?.model,
+              validationKey: 'documentation',
+              agent:         'validator-documentation',
+            },
+            {
+              type:       'refine',
+              label:      'Improve documentation based on issues',
+              model:      ceremony.stages?.documentation?.model,
+              stageKey:   'documentation',
+              sharedWith: 'Documentation generator',
+              agent:      'project-documentation-creator',
+            },
+          ],
+        },
+      ],
+    },
+    {
+      id: 'output',
+      label: 'Output',
+      color: 'emerald',
+      steps: [
+        { type: 'output', label: '.avc/project/doc.md written', files: [{ name: 'project/doc.md', direction: 'out' }] },
+      ],
+    },
+  ];
+}
+
+function buildSprintPlanningPhases(ceremony) {
+  // Stages that aren't explicitly configured fall back to ceremony.defaultModel
+  const fallbackModel = ceremony.defaultModel;
+
+  return [
+    {
+      id: 'scope',
+      label: 'Scope Collection',
+      color: 'blue',
+      steps: [
+        {
+          type:  'read',
+          label: 'Read project scope',
+          files: [{ name: 'project/doc.md', direction: 'in', note: '.avc/project/doc.md — scope section extracted and sent to decomposer' }],
+        },
+        { type: 'read', label: 'Analyse existing Epics & Stories (deduplication baseline)' },
+      ],
+    },
+    {
+      id: 'decomposition',
+      label: 'Decomposition',
+      color: 'purple',
+      steps: [
+        {
+          type:     'generate',
+          label:    'Decompose scope into Epics and Stories',
+          model:    ceremony.stages?.decomposition?.model ?? fallbackModel,
+          stageKey: 'decomposition',
+          agent:    'epic-story-decomposer',
+          files:    [
+            { name: 'project/doc.md', direction: 'in', note: 'scope text extracted from doc.md' },
+          ],
+        },
+        {
+          type:       'generate',
+          label:      'Detect semantic duplicates among new epics and against existing on-disk epics — merge overlapping items automatically',
+          model:      ceremony.stages?.decomposition?.model ?? fallbackModel,
+          stageKey:   'decomposition',
+          sharedWith: 'Decomposer',
+          agent:      'duplicate-detector',
+        },
+        {
+          type:       'process',
+          label:      'Review each Epic\'s stories and split any that mix too many concerns (one LLM call per Epic in parallel)',
+          model:      ceremony.stages?.decomposition?.model ?? fallbackModel,
+          stageKey:   'decomposition',
+          sharedWith: 'Decomposer',
+          agent:      'story-scope-reviewer',
+        },
+      ],
+    },
+    {
+      id: 'context-generation',
+      label: 'Context Generation',
+      color: 'violet',
+      steps: [
+        {
+          type:     'generate',
+          label:    'Write + independently review each Epic/Story context.md (Write → Review → Refine, up to 3 rounds per item)',
+          model:    ceremony.stages?.['context-generation']?.model ?? fallbackModel,
+          stageKey: 'context-generation',
+          agents: [
+            { slug: 'context-writer-epic',   note: 'writes epic context.md' },
+            { slug: 'context-reviewer-epic',  note: 'audits epic context against source JSON' },
+            { slug: 'context-writer-story',   note: 'writes story context.md' },
+            { slug: 'context-reviewer-story', note: 'audits story context against source JSON' },
+          ],
+          files: [
+            { name: '{epic}/context.md',  direction: 'out' },
+            { name: '{story}/context.md', direction: 'out' },
+          ],
+        },
+      ],
+    },
+    {
+      id: 'validation',
+      label: 'Micro-Check Validation (3-Tier)',
+      color: 'amber',
+      steps: [
+        {
+          type:     'generate',
+          label:    'Extract project context (once) — infers deployment type, tech stack, cloud/mobile presence to filter validators',
+          model:    ceremony.stages?.validation?.model ?? fallbackModel,
+          stageKey: 'validation',
+          agent:    'project-context-extractor',
+        },
+        {
+          type:       'generate',
+          label:      'AI-select relevant validators per Epic / Story — excludes inapplicable roles (e.g. cloud if no cloud services). Runs once per Epic, once per Story.',
+          model:      ceremony.stages?.validation?.model ?? fallbackModel,
+          stageKey:   'validation',
+          sharedWith: 'Validation',
+          agent:      'agent-selector',
+        },
+        {
+          type:     'validate',
+          label:    'Tier 1: Run domain checks per perspective — each check is 1-2 YES/NO LLM calls, run in parallel',
+          model:    ceremony.stages?.validation?.model ?? fallbackModel,
+          stageKey: 'validation',
+          sharedWith: 'Validation',
+          params: [
+            { key: 'concurrency', label: 'Parallel checks', value: ceremony.stages?.validation?.concurrency ?? 5, min: 1, max: 20 },
+            { key: 'batchSize', label: 'Checks per batch', value: ceremony.stages?.validation?.batchSize ?? 8, min: 1, max: 20 },
+          ],
+          checks: DOMAIN_CHECK_PERSPECTIVES.flatMap(p => [
+            { scope: 'epic',  perspective: p, label: `${p} (Epic)` },
+            { scope: 'story', perspective: p, label: `${p} (Story)` },
+          ]),
+        },
+        {
+          type:       'cross',
+          label:      'Tier 2: Cross-reference consistency checks — verify perspectives agree (e.g., security \u2194 API, database \u2194 architecture). Runs after Tier 1 using evidence from domain checks.',
+          model:      ceremony.stages?.validation?.model ?? fallbackModel,
+          stageKey:   'validation',
+          sharedWith: 'Validation',
+          checks: [
+            { scope: 'cross-refs', perspective: 'epic',  label: 'Epic Cross-Refs' },
+            { scope: 'cross-refs', perspective: 'story', label: 'Story Cross-Refs' },
+          ],
+        },
+        {
+          type:       'refine',
+          label:      'Tier 3: Deterministic scoring + auto-fix critical/major failures (atomic per-check fixes with regression revert)',
+          model:      ceremony.stages?.validation?.model ?? fallbackModel,
+          stageKey:   'validation',
+          sharedWith: 'Validation',
+          params: [
+            { key: 'maxFixAttempts', label: 'Max fix attempts', value: ceremony.stages?.validation?.maxFixAttempts ?? 3, min: 0, max: 10 },
+          ],
+        },
+        {
+          type:       'process',
+          label:      'If story still below threshold with 15+ ACs and scope issues detected: split into 2-3 focused stories, replace in epic, and re-validate each split story',
+          model:      ceremony.stages?.validation?.model ?? fallbackModel,
+          stageKey:   'validation',
+          sharedWith: 'Validation',
+          agent:      'story-splitter',
+        },
+      ],
+    },
+    {
+      id: 'output',
+      label: 'Documentation & Output',
+      color: 'emerald',
+      steps: [
+        { type: 'process', label: 'Renumber hierarchy IDs + write context.md files with final IDs' },
+        {
+          type:     'generate',
+          label:    'Generate narrative doc.md for each Epic from its canonical context.md',
+          model:    ceremony.stages?.['doc-generation']?.model ?? fallbackModel,
+          stageKey: 'doc-generation',
+          agent:    'doc-writer-epic',
+          files:    [
+            { name: 'project/doc.md',  direction: 'in',  note: 'project context' },
+            { name: '{epic}/context.md', direction: 'in', note: 'canonical spec — single source of truth' },
+            { name: '{epic}/doc.md',   direction: 'out', note: 'narrative documentation' },
+          ],
+        },
+        {
+          type:     'generate',
+          label:    'Generate narrative doc.md for each Story from its canonical context.md',
+          model:    ceremony.stages?.['doc-generation']?.model ?? fallbackModel,
+          stageKey: 'doc-generation',
+          agent:    'doc-writer-story',
+          files:    [
+            { name: '{epic}/context.md',  direction: 'in',  note: 'parent epic context' },
+            { name: '{story}/context.md', direction: 'in',  note: 'canonical spec — single source of truth' },
+            { name: '{story}/doc.md',     direction: 'out', note: 'narrative documentation' },
+          ],
+        },
+        {
+          type:     'generate',
+          label:    'Enrich Story docs with missing implementation detail — API contracts, error tables, DB fields, business rules. Runs once per Story.',
+          model:    ceremony.stages?.enrichment?.model ?? fallbackModel,
+          stageKey: 'enrichment',
+          agent:    'story-doc-enricher',
+          files:    [
+            { name: '{story}/doc.md',  direction: 'inout', note: 'read then overwritten with enriched content' },
+          ],
+        },
+        {
+          type:  'output',
+          label: 'Write Epic & Story work.json files',
+          files: [
+            { name: '{epic}/work.json',  direction: 'out' },
+            { name: '{story}/work.json', direction: 'out' },
+          ],
+        },
+      ],
+    },
+  ];
+}
+function buildSeedPhases(c) {
+  return [
+    {
+      id: 'decompose',
+      label: 'Decompose Story',
+      color: 'blue',
+      steps: [
+        {
+          type:     'read',
+          label:    'Read story, epic, and project context',
+        },
+        {
+          type:     'generate',
+          label:    'Decompose story into tasks and subtasks',
+          model:    c?.stages?.decomposition?.model,
+          stageKey: 'decomposition',
+          agent:    'task-subtask-decomposer',
+        },
+        {
+          type:     'process',
+          label:    'Validate task/subtask structure and IDs (deterministic)',
+        },
+      ],
+    },
+    {
+      id: 'context-gen',
+      label: 'Task Documentation',
+      color: 'green',
+      steps: [
+        {
+          type:     'generate',
+          label:    'Generate context.md for each task and subtask',
+          model:    c?.stages?.['context-generation']?.model,
+          stageKey: 'context-generation',
+        },
+        {
+          type:     'output',
+          label:    'Write work.json, context.md, and doc.md files',
+        },
+      ],
+    },
+  ];
+}
+
+function buildRunPhases(c) {
+  return [
+    {
+      id: 'implement',
+      label: 'Code Generation',
+      color: 'blue',
+      steps: [
+        {
+          type:     'read',
+          label:    'Create git worktree and read documentation chain',
+        },
+        {
+          type:     'generate',
+          label:    'AI generates code following traceability rules',
+          model:    c?.stages?.['code-generation']?.model,
+          stageKey: 'code-generation',
+          agent:    'code-implementer',
+        },
+      ],
+    },
+    {
+      id: 'validate',
+      label: 'Code Validation',
+      color: 'amber',
+      steps: [
+        {
+          type:     'validate',
+          label:    'Verify code against quality and traceability checks',
+          model:    c?.stages?.['code-validation']?.model,
+          stageKey: 'code-validation',
+          agent:    'code-validator',
+        },
+        {
+          type:     'generate',
+          label:    'Fix violations and regenerate (if needed, up to 3 iterations)',
+          model:    c?.stages?.['code-generation']?.model,
+          stageKey: 'code-generation',
+        },
+      ],
+    },
+    {
+      id: 'test-merge',
+      label: 'Test & Merge',
+      color: 'green',
+      steps: [
+        {
+          type:     'validate',
+          label:    'Run tests in worktree',
+        },
+        {
+          type:     'output',
+          label:    'Commit, merge to main, update function registry',
+        },
+      ],
+    },
+  ];
+}
+
+const CEREMONY_WORKFLOWS = {
+  'sponsor-call':    buildSponsorCallPhases,
+  'sprint-planning': (c) => buildSprintPlanningPhases(c),
+  'seed':            (c) => buildSeedPhases(c),
+  'run':             (c) => buildRunPhases(c),
+};
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function resolveModelName(modelId, models) {
+  if (!modelId) return '—';
+  return models.find((m) => m.modelId === modelId)?.displayName || modelId;
+}
+
+// ── Inline model select ───────────────────────────────────────────────────────
+
+function ModelSelectInline({ value, models, onChange }) {
+  const providers = [...new Set(models.map((m) => m.provider))];
+  return (
+    <select
+      value={value || ''}
+      onChange={(e) => onChange(e.target.value)}
+      onClick={(e) => e.stopPropagation()}
+      className="text-xs border border-slate-300 rounded px-1.5 py-0.5 bg-white text-slate-800 focus:outline-none focus:ring-1 focus:ring-blue-400 max-w-[200px]"
+    >
+      {!value && <option value="">— select —</option>}
+      {providers.map((p) => (
+        <optgroup key={p} label={p.charAt(0).toUpperCase() + p.slice(1)}>
+          {models.filter((m) => m.provider === p).map((m) => (
+            <option key={m.modelId} value={m.modelId}>{m.displayName || m.modelId}</option>
+          ))}
+        </optgroup>
+      ))}
+    </select>
+  );
+}
+
+// ── Agent link ────────────────────────────────────────────────────────────────
+
+function AgentLink({ slug, onOpen }) {
+  const label = AGENT_LABELS[slug] || slug;
+  return (
+    <button
+      type="button"
+      onClick={() => onOpen(slug)}
+      className="inline-flex items-center gap-1 text-[10px] font-medium text-blue-600 hover:text-blue-800 bg-blue-50 hover:bg-blue-100 border border-blue-200 hover:border-blue-300 px-1.5 py-0.5 rounded transition-colors whitespace-nowrap"
+      title={`Edit ${label} agent instructions`}
+    >
+      {label}
+      <Pencil className="w-2.5 h-2.5 flex-shrink-0" />
+    </button>
+  );
+}
+
+function AgentLinks({ step, onOpenAgent }) {
+  const items = step.agents
+    ? step.agents.map((a) => (typeof a === 'string' ? { slug: a, note: null } : a))
+    : step.agent
+      ? [{ slug: step.agent, note: null }]
+      : [];
+
+  if (items.length === 0) return null;
+
+  return (
+    <div className="mt-1.5">
+      <span className="text-[10px] text-slate-400 font-medium">Agent(s)</span>
+      <div className="mt-1 flex flex-col gap-1">
+        {items.map(({ slug, note }) => (
+          <div key={slug} className="flex items-center gap-2 flex-wrap">
+            <AgentLink slug={slug} onOpen={onOpenAgent} />
+            {note && <span className="text-[10px] text-slate-400 italic">{note}</span>}
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+// ── Check links ──────────────────────────────────────────────────────────────
+// Renders clickable check-definition badges inside a scrollable container.
+
+function CheckLinks({ step, onOpenCheck }) {
+  if (!step.checks || step.checks.length === 0) return null;
+
+  return (
+    <div className="mt-1.5">
+      <span className="text-[10px] text-slate-400 font-medium">Check definitions</span>
+      <div className="mt-1 max-h-28 overflow-y-auto border border-slate-100 rounded-md px-1.5 py-1 flex flex-wrap gap-1">
+        {step.checks.map((c) => (
+          <button
+            key={`${c.scope}/${c.perspective}`}
+            type="button"
+            onClick={() => onOpenCheck({ scope: c.scope, perspective: c.perspective })}
+            className="inline-flex items-center gap-1 text-[10px] font-medium text-amber-700 hover:text-amber-900 bg-amber-50 hover:bg-amber-100 border border-amber-200 hover:border-amber-300 px-1.5 py-0.5 rounded transition-colors whitespace-nowrap"
+            title={`Edit ${c.scope}/${c.perspective}.json`}
+          >
+            {c.label}
+            <Pencil className="w-2.5 h-2.5 flex-shrink-0" />
+          </button>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+// ── File tags ─────────────────────────────────────────────────────────────────
+// Renders small ← filename (input) / → filename (output) badges on step cards.
+// Steps can carry a `files` array: [{ name, direction: 'in'|'out', note? }]
+
+function FileTags({ files, className = '' }) {
+  if (!files || files.length === 0) return null;
+  return (
+    <div className={`flex items-center gap-1 flex-wrap ${className}`}>
+      {files.map((f, i) => {
+        const isIn    = f.direction === 'in';
+        const isInOut = f.direction === 'inout';
+        const cls = isInOut
+          ? 'bg-purple-50 text-purple-700 border-purple-200'
+          : isIn
+            ? 'bg-sky-50 text-sky-700 border-sky-200'
+            : 'bg-emerald-50 text-emerald-700 border-emerald-200';
+        const arrow = isInOut ? '↕' : isIn ? '←' : '→';
+        return (
+          <span
+            key={i}
+            className={`inline-flex items-center gap-0.5 text-[10px] font-mono font-medium px-1.5 py-0.5 rounded border whitespace-nowrap ${cls}`}
+            title={f.note}
+          >
+            <span className="font-sans mr-0.5">{arrow}</span>
+            {f.name}
+          </span>
+        );
+      })}
+    </div>
+  );
+}
+
+// ── Step badge ────────────────────────────────────────────────────────────────
+
+function StepBadge({ type }) {
+  const cfg = STEP_TYPE_CONFIG[type] || { label: type, cls: 'bg-slate-50 text-slate-600 border-slate-200' };
+  return (
+    <span className={`inline-block text-xs font-medium px-2 py-0.5 rounded border whitespace-nowrap ${cfg.cls}`}>
+      {cfg.label}
+    </span>
+  );
+}
+
+// ── Plain step card ───────────────────────────────────────────────────────────
+
+function StepCard({ step, models, editable, onStageModelChange, onValidationModelChange, onStageParamChange, onOpenAgent, onOpenCheck }) {
+  const showModel = !['input', 'output', 'read', 'process'].includes(step.type);
+  const canEdit   = editable && !step.sharedWith && (step.stageKey || step.validationKey);
+
+  return (
+    <div className="bg-white border border-slate-200 rounded-lg px-3 py-2.5 shadow-sm">
+
+      {/* Row 1: badge + file tags (flex-1) + model — all vertically centred */}
+      <div className="flex items-center gap-2">
+        <div className="flex-shrink-0">
+          <StepBadge type={step.type} />
+        </div>
+        <FileTags files={step.files} className="flex-1 min-w-0" />
+        {showModel && (
+          step.sharedWith ? (
+            <p className="text-[10px] text-slate-400 italic flex-shrink-0">↑ {step.sharedWith}</p>
+          ) : canEdit ? (
+            <ModelSelectInline
+              value={step.model}
+              models={models}
+              onChange={(modelId) => {
+                if (step.stageKey) onStageModelChange(step.stageKey, modelId);
+                else onValidationModelChange(step.validationKey, modelId);
+              }}
+            />
+          ) : (
+            <p className="text-[10px] text-slate-400 flex-shrink-0">
+              {step.note ? step.note : resolveModelName(step.model, models)}
+            </p>
+          )
+        )}
+      </div>
+
+      {/* Row 2: description + agents — tiny left indent */}
+      <p className="text-xs text-slate-700 leading-snug text-left mt-2 pl-1">{step.label}</p>
+
+      <div className="pl-1">
+        <AgentLinks step={step} onOpenAgent={onOpenAgent} />
+        {onOpenCheck && <CheckLinks step={step} onOpenCheck={onOpenCheck} />}
+      </div>
+
+      {/* Inline params (e.g. concurrency, maxFixAttempts) */}
+      {step.params && step.params.length > 0 && (
+        <div className="mt-2 pl-1 flex items-center gap-3 flex-wrap">
+          {step.params.map((p) => (
+            <label key={p.key} className="flex items-center gap-1.5 text-[11px] text-slate-600">
+              <span className="font-medium">{p.label}:</span>
+              {editable && step.stageKey && onStageParamChange ? (
+                <input
+                  type="number"
+                  min={p.min}
+                  max={p.max}
+                  value={p.value}
+                  onChange={(e) => onStageParamChange(step.stageKey, p.key, Number(e.target.value))}
+                  onClick={(e) => e.stopPropagation()}
+                  className="w-12 text-xs border border-slate-300 rounded px-1.5 py-0.5 bg-white text-slate-800 text-center focus:outline-none focus:ring-1 focus:ring-blue-400"
+                />
+              ) : (
+                <span className="font-mono">{p.value}</span>
+              )}
+            </label>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+
+// ── Loop group card ───────────────────────────────────────────────────────────
+
+function LoopGroupCard({ group, models, editable, onStageModelChange, onValidationModelChange, onStageParamChange, onLoopParamChange, onOpenAgent, onOpenCheck }) {
+  const { loop, steps }   = group;
+  const isIndigo          = steps.some((s) => s.type === 'cross');
+  const c                 = isIndigo ? LOOP_C.indigo : LOOP_C.amber;
+  const hasMulti          = steps.length > 1;
+
+  const canEditLoop = editable && group.loopParamType && !group.loopParamReadOnly;
+
+  return (
+    <div className={`rounded-xl border-2 border-dashed ${c.border} overflow-hidden`}>
+
+      {/* ── Header ── */}
+      <div className={`${c.hdr} border-b-2 border-dashed ${c.hdrBorder} px-3 py-2 flex items-center gap-2 flex-wrap`}>
+        <span className={`text-xl font-black leading-none ${c.text}`}>↺</span>
+        <span className={`text-xs font-bold ${c.text} tracking-wide`}>Iteration Loop</span>
+        <div className="ml-auto flex items-center gap-1.5 flex-wrap">
+          {loop.max != null && (
+            canEditLoop ? (
+              <label className={`text-xs font-semibold ${c.chip} px-2 py-0.5 rounded-full flex items-center gap-1`}>
+                up to
+                <input
+                  type="number" min="1" max="200" value={loop.max}
+                  onChange={(e) => onLoopParamChange(group.loopParamType, 'maxIterations', Number(e.target.value))}
+                  onClick={(e) => e.stopPropagation()}
+                  className="w-10 bg-transparent border-b border-current text-center focus:outline-none"
+                />
+                iter
+              </label>
+            ) : (
+              <span className={`text-xs font-semibold ${c.chip} px-2 py-0.5 rounded-full`}>
+                {group.loopParamReadOnly ? `↑ ${loop.max} iter` : `up to ${loop.max} iter`}
+              </span>
+            )
+          )}
+          {loop.threshold != null && (
+            canEditLoop ? (
+              <label className={`text-xs font-semibold ${c.chip} px-2 py-0.5 rounded-full flex items-center gap-1`}>
+                ≥
+                <input
+                  type="number" min="0" max="100" value={loop.threshold}
+                  onChange={(e) => onLoopParamChange(group.loopParamType, 'acceptanceThreshold', Number(e.target.value))}
+                  onClick={(e) => e.stopPropagation()}
+                  className="w-10 bg-transparent border-b border-current text-center focus:outline-none"
+                />
+                /100
+              </label>
+            ) : (
+              <span className={`text-xs font-semibold ${c.chip} px-2 py-0.5 rounded-full`}>
+                {group.loopParamReadOnly ? `↑ ≥${loop.threshold}/100` : `≥${loop.threshold}/100`}
+              </span>
+            )
+          )}
+        </div>
+      </div>
+
+      {/* ── Steps + right-side loop arrow ── */}
+      <div className={`${c.bg} p-3 flex gap-2 items-stretch`}>
+        <div className="flex-1 flex flex-col">
+          {steps.map((step, i) => (
+            <div key={i}>
+              <StepCard
+                step={step}
+                models={models}
+                editable={editable}
+                onStageModelChange={onStageModelChange}
+                onValidationModelChange={onValidationModelChange}
+                onStageParamChange={onStageParamChange}
+                onOpenAgent={onOpenAgent}
+                onOpenCheck={onOpenCheck}
+              />
+              {i < steps.length - 1 && (
+                <div className="flex items-center gap-2 my-1.5 ml-3">
+                  <div className={`w-px h-4 ${c.condLine}`} />
+                  <span className={`text-xs ${c.subtext} italic`}>score &lt; threshold → retry</span>
+                </div>
+              )}
+            </div>
+          ))}
+        </div>
+
+        {/* Right-side loop-back arrow */}
+        {hasMulti && (
+          <div className={`flex flex-col items-center flex-shrink-0 ${c.arrow}`} style={{ width: 22 }}>
+            <svg width="14" height="14" viewBox="0 0 14 14" fill="none">
+              <path d="M2 7 L7 1 L12 7" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round" />
+            </svg>
+            <div className={`w-0.5 flex-1 ${c.line} my-1 rounded-full`} style={{ minHeight: 36 }} />
+            <span
+              className={`text-[9px] font-bold tracking-widest uppercase ${c.text} opacity-70`}
+              style={{ writingMode: 'vertical-rl', transform: 'rotate(180deg)' }}
+            >
+              retry
+            </span>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+// ── Phase header ──────────────────────────────────────────────────────────────
+
+function PhaseHeader({ label, color }) {
+  const cfg = PHASE_COLOR_CONFIG[color] || { dot: 'bg-slate-400', label: 'text-slate-600' };
+  return (
+    <div className="flex items-center gap-2 mt-5 mb-2">
+      <div className={`w-2 h-2 rounded-full flex-shrink-0 ${cfg.dot}`} />
+      <span className={`text-xs font-semibold uppercase tracking-wide ${cfg.label}`}>{label}</span>
+    </div>
+  );
+}
+
+function Connector() {
+  return <div className="w-px h-4 bg-slate-200 ml-4" />;
+}
+
+// ── Main export ───────────────────────────────────────────────────────────────
+
+export function CeremonyWorkflowModal({
+  ceremony,
+  allCeremonies,
+  apiKeys,
+  models = [],
+  missionGenValidation = null,
+  onClose,
+  onSave,
+  onCeremoniesUpdated,
+  readOnly = false,
+}) {
+  const [draft, setDraft] = useState(() => JSON.parse(JSON.stringify(ceremony || {})));
+  const [missionGenDraft, setMissionGenDraft] = useState(() =>
+    JSON.parse(JSON.stringify(missionGenValidation || { maxIterations: 3, acceptanceThreshold: 95 }))
+  );
+  const [saving, setSaving] = useState(false);
+  const [saveError, setSaveError] = useState(null);
+  const [openAgentSlug, setOpenAgentSlug] = useState(null);
+  const [openCheck, setOpenCheck] = useState(null); // { scope, perspective } | null
+
+  // Phases rebuild from draft every render — always reflect current edits
+  const buildPhases = ceremony?.name ? CEREMONY_WORKFLOWS[ceremony.name] : null;
+  const phases      = buildPhases ? buildPhases(draft, missionGenDraft) : null;
+
+  const isEditable = !readOnly && !!onSave;
+
+  // ── Update helpers ──────────────────────────────────────────────────────────
+
+  const updateStageModel = (stageKey, modelId) => {
+    const found = models.find((m) => m.modelId === modelId);
+    setDraft((prev) => ({
+      ...prev,
+      stages: {
+        ...prev.stages,
+        [stageKey]: {
+          ...prev.stages?.[stageKey],
+          model:    modelId,
+          provider: found?.provider || prev.stages?.[stageKey]?.provider || '',
+        },
+      },
+    }));
+  };
+
+  const updateValidationModel = (area, modelId) => {
+    const found = models.find((m) => m.modelId === modelId);
+    if (area === 'top') {
+      setDraft((prev) => ({
+        ...prev,
+        validation: {
+          ...prev.validation,
+          model:    modelId,
+          provider: found?.provider || prev.validation?.provider || '',
+        },
+      }));
+    } else {
+      setDraft((prev) => ({
+        ...prev,
+        validation: {
+          ...prev.validation,
+          [area]: {
+            ...prev.validation?.[area],
+            model:    modelId,
+            provider: found?.provider || prev.validation?.[area]?.provider || '',
+          },
+        },
+      }));
+    }
+  };
+
+  const updateStageParam = (stageKey, paramKey, value) => {
+    setDraft((prev) => ({
+      ...prev,
+      stages: {
+        ...prev.stages,
+        [stageKey]: {
+          ...prev.stages?.[stageKey],
+          [paramKey]: value,
+        },
+      },
+    }));
+  };
+
+  const updateLoopParam = (loopParamType, field, value) => {
+    if (loopParamType === 'missionGen') {
+      setMissionGenDraft((prev) => ({ ...prev, [field]: value }));
+    } else if (loopParamType === 'docContext') {
+      setDraft((prev) => ({ ...prev, validation: { ...prev.validation, [field]: value } }));
+    }
+  };
+
+  // ── Save / cancel ───────────────────────────────────────────────────────────
+
+  const handleSave = async () => {
+    setSaving(true);
+    setSaveError(null);
+    try {
+      await onSave(draft, missionGenDraft);
+      onClose();
+    } catch {
+      setSaveError('Failed to save. Please try again.');
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  const handleCancel = () => {
+    setDraft(JSON.parse(JSON.stringify(ceremony || {})));
+    setMissionGenDraft(JSON.parse(JSON.stringify(missionGenValidation || { maxIterations: 3, acceptanceThreshold: 95 })));
+    onClose();
+  };
+
+  return (
+    <div className="fixed inset-0 z-[70] flex items-center justify-center">
+      {/* Backdrop: in edit mode clicking outside does nothing to prevent accidental data loss */}
+      <div
+        className="absolute inset-0 bg-black/40"
+        onClick={isEditable ? undefined : onClose}
+      />
+
+      <div
+        className="relative bg-slate-50 rounded-2xl shadow-2xl w-full max-w-xl mx-4 flex flex-col"
+        style={{ height: '85vh' }}
+      >
+        {/* Header */}
+        <div className="flex items-center justify-between px-5 pt-4 pb-3 border-b border-slate-200 flex-shrink-0 bg-white rounded-t-2xl">
+          <div>
+            <h2 className="text-sm font-semibold text-slate-900">
+              {isEditable ? 'Configure Models' : 'Ceremony Workflow'}
+            </h2>
+            <p className="text-xs text-slate-500 mt-0.5">
+              {ceremony?.displayName || ceremony?.name || 'Unknown ceremony'}
+            </p>
+          </div>
+          <div className="flex items-center gap-2">
+            {isEditable && allCeremonies && (
+              <ProviderSwitcherButton
+                ceremonyName={ceremony?.name}
+                ceremonies={allCeremonies.map((c) => c.name === ceremony?.name ? draft : c)}
+                apiKeys={apiKeys}
+                onApplied={(updated) => {
+                  const updatedCeremony = updated.find((c) => c.name === ceremony?.name);
+                  if (updatedCeremony) setDraft(JSON.parse(JSON.stringify(updatedCeremony)));
+                  onCeremoniesUpdated?.(updated);
+                }}
+              />
+            )}
+            <button
+              type="button"
+              onClick={isEditable ? handleCancel : onClose}
+              className="text-slate-400 hover:text-slate-600 transition-colors"
+            >
+              <X className="w-4 h-4" />
+            </button>
+          </div>
+        </div>
+
+        {/* Scrollable body */}
+        <div className="flex-1 overflow-y-auto px-5 pb-5">
+          {phases === null ? (
+            <div className="flex items-center justify-center h-32">
+              <p className="text-sm text-slate-400">Workflow diagram coming soon for this ceremony.</p>
+            </div>
+          ) : (
+            phases.map((phase, pi) => (
+              <div key={phase.id}>
+                <PhaseHeader label={phase.label} color={phase.color} />
+                {phase.steps.map((step, si) => (
+                  <div key={si}>
+                    {step.type === 'loop-group' ? (
+                      <LoopGroupCard
+                        group={step}
+                        models={models}
+                        editable={isEditable}
+                        onStageModelChange={updateStageModel}
+                        onValidationModelChange={updateValidationModel}
+                        onStageParamChange={updateStageParam}
+                        onLoopParamChange={updateLoopParam}
+                        onOpenAgent={setOpenAgentSlug}
+                        onOpenCheck={setOpenCheck}
+                      />
+                    ) : (
+                      <StepCard
+                        step={step}
+                        models={models}
+                        editable={isEditable}
+                        onStageModelChange={updateStageModel}
+                        onValidationModelChange={updateValidationModel}
+                        onStageParamChange={updateStageParam}
+                        onOpenAgent={setOpenAgentSlug}
+                        onOpenCheck={setOpenCheck}
+                      />
+                    )}
+                    {si < phase.steps.length - 1 && <Connector />}
+                  </div>
+                ))}
+                {pi < phases.length - 1 && (
+                  <div className="mt-3 border-t border-dashed border-slate-200" />
+                )}
+              </div>
+            ))
+          )}
+        </div>
+
+        {/* Footer — edit mode only */}
+        {isEditable && (
+          <div className="flex-shrink-0 border-t border-slate-200 bg-white rounded-b-2xl px-5 py-3 flex items-center justify-between">
+            <div>
+              {saveError && <p className="text-xs text-red-600">{saveError}</p>}
+            </div>
+            <div className="flex items-center gap-2">
+              <button
+                type="button"
+                onClick={handleCancel}
+                className="px-3 py-1.5 text-sm text-slate-600 hover:text-slate-900 transition-colors"
+              >
+                Cancel
+              </button>
+              <button
+                type="button"
+                onClick={handleSave}
+                disabled={saving}
+                className="px-4 py-1.5 text-sm font-medium bg-slate-900 text-white rounded-lg hover:bg-slate-700 transition-colors disabled:opacity-40 flex items-center gap-2"
+              >
+                {saving ? (
+                  <>
+                    <span className="w-3.5 h-3.5 border border-white/40 border-t-white rounded-full animate-spin" />
+                    Saving…
+                  </>
+                ) : 'Save Changes'}
+              </button>
+            </div>
+          </div>
+        )}
+      </div>
+
+      {openAgentSlug && (
+        <AgentEditorPopup
+          agentName={`${openAgentSlug}.md`}
+          onClose={() => setOpenAgentSlug(null)}
+        />
+      )}
+
+      {openCheck && (
+        <CheckEditorPopup
+          scope={openCheck.scope}
+          perspective={openCheck.perspective}
+          onClose={() => setOpenCheck(null)}
+        />
+      )}
+    </div>
+  );
+}