mishkan-harness 0.1.0

package/payload/mishkan/workflows/mishkan-deep-research.js

@@ -0,0 +1,251 @@
+// mishkan-deep-research — pipelined research with adversarial verification.
+//
+// Same shape as Anthropic's bundled /deep-research but using MISHKAN's
+// six research-pipeline stages (Jakin, Ezra, Caleb, Shaphan, Shemaiah,
+// Baruch). The Anthropic version fans web searches across angles and
+// cross-checks; this one threads them through MISHKAN's roles so the
+// research-log.json contract is honoured at the end.
+//
+// Patterns: pipeline (Ezra brief → per-sub-question fan-out) +
+// adversarial verification (3-vote refute per finding) + barrier
+// (Shemaiah needs all summarised findings to evaluate coverage).
+//
+// Args: { intent: "raw research query", agent: "calling agent alias",
+//         team: "calling agent team", sprint: "S2",
+//         applied_to_task: "T-12" | "exploration" }
+
+export const meta = {
+  name: 'mishkan-deep-research',
+  description: 'Run the MISHKAN research pipeline as a workflow: Jakin clarifies, Ezra formulates, Caleb fans out across sub-questions, 3-vote adversarial verify per finding, Shaphan compresses, Shemaiah evaluates, Baruch reports.',
+  whenToUse: 'Any unknown that needs the web and where false-confident answers are costly. Cheaper alternative for routine lookups: the sequential research-pipeline skill via Task delegation.',
+  phases: [
+    { title: 'Clarify',   detail: 'Jakin sharpens intent' },
+    { title: 'Formulate', detail: 'Ezra writes brief, checks curated library' },
+    { title: 'Research',  detail: 'Caleb fans out per sub-question; 3-vote verify per claim' },
+    { title: 'Compress',  detail: 'Shaphan summarises surviving findings' },
+    { title: 'Evaluate',  detail: 'Shemaiah judges; curated cross-reference' },
+    { title: 'Report',    detail: 'Baruch emits research-log.json' },
+  ],
+}
+
+if (!args?.intent || !args?.agent || !args?.team || !args?.sprint) {
+  throw new Error('mishkan-deep-research requires args: { intent, agent, team, sprint, applied_to_task? }')
+}
+
+const INTENT_SCHEMA = {
+  type: 'object',
+  required: ['clarified_intent', 'open_questions', 'ready_for_formulation'],
+  properties: {
+    clarified_intent:      { type: ['string', 'null'] },
+    open_questions:        { type: 'array', items: { type: 'string' } },
+    ready_for_formulation: { type: 'boolean' },
+  },
+}
+
+const BRIEF_SCHEMA = {
+  type: 'object',
+  required: ['research_brief', 'curated_library_match'],
+  properties: {
+    research_brief: {
+      type: 'object',
+      required: ['sub_questions', 'priority_sources', 'acceptance_criteria'],
+      properties: {
+        sub_questions:       { type: 'array', items: { type: 'string' }, minItems: 1, maxItems: 7 },
+        priority_sources:    { type: 'array', items: { type: 'string' } },
+        acceptance_criteria: { type: 'string' },
+      },
+    },
+    curated_library_match:   { type: 'boolean' },
+    curated_library_extract: { type: ['string', 'null'] },
+  },
+}
+
+const FINDINGS_SCHEMA = {
+  type: 'object',
+  required: ['findings', 'coverage'],
+  properties: {
+    findings: {
+      type: 'array',
+      items: {
+        type: 'object',
+        required: ['claim', 'source', 'confidence'],
+        properties: {
+          claim:      { type: 'string' },
+          source:     { type: 'string' },
+          confidence: { enum: ['high', 'medium', 'low', 'unverified'] },
+        },
+      },
+    },
+    coverage: {
+      type: 'object',
+      required: ['answered', 'unanswered'],
+      properties: {
+        answered:          { type: 'array' },
+        unanswered:        { type: 'array' },
+        unanswered_reason: { type: 'string' },
+      },
+    },
+  },
+}
+
+const VERDICT_SCHEMA = {
+  type: 'object',
+  required: ['refuted', 'reason'],
+  properties: {
+    refuted: { type: 'boolean' },
+    reason:  { type: 'string' },
+  },
+}
+
+const EVAL_SCHEMA = {
+  type: 'object',
+  required: ['verdict', 'confidence', 'gaps', 'curated_library_agreement', 'notes'],
+  properties: {
+    verdict:                    { enum: ['resolved', 'partial', 'blocked'] },
+    confidence:                 { enum: ['high', 'medium', 'low'] },
+    gaps:                       { type: 'array', items: { type: 'string' } },
+    curated_library_agreement:  { enum: ['agrees', 'conflicts', 'not_covered'] },
+    notes:                      { type: 'string' },
+  },
+}
+
+// --- Stage 1: Jakin clarifies ------------------------------------------
+phase('Clarify')
+const intent = await agent(
+  `Act as Jakin. Apply jakin-intent-clarification-craft. The raw query: ${JSON.stringify(args.intent)}. ` +
+  `Return clarified intent + open questions. No fabricated readiness.`,
+  { label: 'jakin:clarify', phase: 'Clarify', agentType: 'jakin', schema: INTENT_SCHEMA }
+)
+
+if (!intent.ready_for_formulation) {
+  log(`Jakin returned ready_for_formulation=false; ${intent.open_questions.length} open questions.`)
+  return {
+    outcome: 'blocked',
+    stage_blocked: 'jakin',
+    open_questions: intent.open_questions,
+    research_log: null,
+  }
+}
+
+// --- Stage 2: Ezra formulates ------------------------------------------
+phase('Formulate')
+const brief = await agent(
+  `Act as Ezra. Apply ezra-research-formulation-craft. Clarified intent: ${JSON.stringify(intent.clarified_intent)}. ` +
+  `Check curated library first via mcp__cognee-curated__search. If match, set curated_library_match=true and include curated_library_extract.`,
+  { label: 'ezra:formulate', phase: 'Formulate', agentType: 'ezra', schema: BRIEF_SCHEMA }
+)
+
+// Curated short-circuit: skip Caleb/Shaphan, go straight to Shemaiah evaluating the curated extract.
+if (brief.curated_library_match) {
+  log('Ezra short-circuit — curated library match. Skipping web research.')
+
+  phase('Evaluate')
+  const verdict = await agent(
+    `Act as Shemaiah. Apply shemaiah-evaluation-craft. Evaluate the curated extract against the original ` +
+    `sub-questions. The brief: ${JSON.stringify(brief)}. The extract is the only source.`,
+    { label: 'shemaiah:evaluate-curated', phase: 'Evaluate', agentType: 'shemaiah', schema: EVAL_SCHEMA }
+  )
+
+  phase('Report')
+  const log_short = {
+    agent: args.agent, team: args.team, sprint: args.sprint,
+    trigger: 'faced_problem',
+    query_intent: intent.clarified_intent,
+    tools_invoked: ['jakin', 'ezra', 'shemaiah', 'baruch'],
+    research_output_summary: brief.curated_library_extract,
+    applied_to_task: args.applied_to_task || 'exploration',
+    outcome: verdict.verdict,
+    knowledge_graph_write: false,
+    curated_library_match: true,
+    cognee_node_id: null,
+  }
+  return { outcome: verdict.verdict, research_log: log_short, source: 'curated' }
+}
+
+// --- Stage 3: Caleb pipelines across sub-questions ---------------------
+// Pipeline: each sub-question runs through (research → 3-vote adversarial verify)
+// independently. Faster wall-clock than barrier(research) → barrier(verify).
+phase('Research')
+const verified = await pipeline(
+  brief.research_brief.sub_questions,
+
+  // Stage A: Caleb researches one sub-question.
+  (q, _, i) => agent(
+    `Act as Caleb. Apply caleb-web-research-craft. Sub-question: ${JSON.stringify(q)}. ` +
+    `Priority sources: ${JSON.stringify(brief.research_brief.priority_sources)}. ` +
+    `Acceptance: ${brief.research_brief.acceptance_criteria}. Return findings + coverage.`,
+    { label: `caleb:Q${i + 1}`, phase: 'Research', agentType: 'caleb', schema: FINDINGS_SCHEMA }
+  ),
+
+  // Stage B: for each finding from stage A, 3-vote adversarial verify.
+  // 2/3 refute → drop the finding.
+  async (researchResult, q, i) => {
+    if (!researchResult?.findings?.length) return { sub_question: q, findings: [], coverage: researchResult?.coverage }
+    const survived = await parallel(researchResult.findings.map((f) => async () => {
+      const votes = await parallel([0, 1, 2].map((v) => () => agent(
+        `Adversarial verifier ${v + 1}/3. Try to REFUTE this finding. Default to refuted=true if uncertain. ` +
+        `Finding: ${JSON.stringify(f)}. Source: ${f.source}.`,
+        { label: `verify:Q${i + 1}:f${f.claim.slice(0, 24)}:v${v + 1}`, phase: 'Research',
+          agentType: 'shemaiah', schema: VERDICT_SCHEMA }
+      )))
+      const refuted = votes.filter(Boolean).filter(v => v.refuted).length
+      return refuted >= 2 ? null : f
+    }))
+    return {
+      sub_question: q,
+      findings: survived.filter(Boolean),
+      coverage: researchResult.coverage,
+      killed_by_verify: researchResult.findings.length - survived.filter(Boolean).length,
+    }
+  }
+)
+
+const allFindings = verified.filter(Boolean).flatMap(v => v.findings)
+const totalKilled = verified.filter(Boolean).reduce((n, v) => n + (v.killed_by_verify || 0), 0)
+log(`Research+verify done: ${allFindings.length} findings survived; ${totalKilled} refuted by adversarial vote.`)
+
+// --- Stage 4: Shaphan compresses ---------------------------------------
+phase('Compress')
+const summary = await agent(
+  `Act as Shaphan. Apply shaphan-summarisation-craft. Findings from ${verified.length} sub-questions: ` +
+  `${JSON.stringify(allFindings)}. Coverage per sub-question: ` +
+  `${JSON.stringify(verified.filter(Boolean).map(v => ({ q: v.sub_question, coverage: v.coverage })))}. ` +
+  `Preserve every source and confidence. Surface contradictions explicitly.`,
+  { label: 'shaphan:compress', phase: 'Compress', agentType: 'shaphan' }
+)
+
+// --- Stage 5: Shemaiah evaluates ---------------------------------------
+phase('Evaluate')
+const verdict = await agent(
+  `Act as Shemaiah. Apply shemaiah-evaluation-craft. Brief: ${JSON.stringify(brief.research_brief)}. ` +
+  `Summary: ${JSON.stringify(summary)}. Cross-reference the curated library via mcp__cognee-curated__search. ` +
+  `Return verdict + confidence + gaps + curated_library_agreement.`,
+  { label: 'shemaiah:evaluate', phase: 'Evaluate', agentType: 'shemaiah', schema: EVAL_SCHEMA }
+)
+
+// --- Stage 6: Baruch reports -------------------------------------------
+phase('Report')
+const research_log = {
+  agent: args.agent, team: args.team, sprint: args.sprint,
+  trigger: 'faced_problem',
+  query_intent: intent.clarified_intent,
+  tools_invoked: ['jakin', 'ezra', 'caleb', 'shaphan', 'shemaiah', 'baruch'],
+  research_output_summary: typeof summary === 'string' ? summary : JSON.stringify(summary),
+  applied_to_task: args.applied_to_task || 'exploration',
+  outcome: verdict.verdict,
+  knowledge_graph_write: false,            // Baruch sets to true if writing a node downstream
+  curated_library_match: false,
+  cognee_node_id: null,
+}
+
+return {
+  outcome: verdict.verdict,
+  confidence: verdict.confidence,
+  gaps: verdict.gaps,
+  research_log,
+  stats: {
+    sub_questions: brief.research_brief.sub_questions.length,
+    findings_surviving: allFindings.length,
+    findings_refuted: totalKilled,
+  },
+}

package/payload/mishkan/workflows/mishkan-init.js

@@ -0,0 +1,156 @@
+// mishkan-init — pipelined project bootstrap.
+//
+// The sequence-before-implementation chain (PRD → SRS → CONTRACT →
+// ARCHITECTURE → THREAT_MODEL → C4) currently runs as a sequential skill.
+// As a workflow with overlapping stages, downstream agents start as soon
+// as their upstream dependency lands — cutting init from hours to
+// minutes without violating the sequence rule (each artefact still has
+// its prerequisite, just no idle gap between them).
+//
+// Patterns: pipeline with explicit dependencies (PRD → SRS, SRS → both
+// CONTRACT and ARCHITECTURE in parallel, ARCHITECTURE → C4, ARCHITECTURE
+// → THREAT_MODEL) + fan-out where dependencies allow.
+//
+// Args: {
+//   project_name: "aiobi-forms",
+//   project_root: "/path/to/project",
+//   raw_intent: "<paragraph: what is being built, for whom, with what constraints>",
+//   stack_hint: "Laravel 11 + Nuxt 3" | "FastAPI + React" | ...
+// }
+
+export const meta = {
+  name: 'mishkan-init',
+  description: 'Pipelined PRD → SRS → CONTRACT → ARCHITECTURE → THREAT_MODEL → C4. Downstream stages start as soon as their upstream dependency lands; sequence rule preserved.',
+  whenToUse: 'Once per project at /mishkan-init. Brownfield mode uses the same shape with read-existing instead of write-new at each stage.',
+  phases: [
+    { title: 'PRD',          detail: 'Nehemiah writes the product requirement document' },
+    { title: 'SRS',          detail: 'Nathan turns PRD into a testable system requirement spec' },
+    { title: 'CONTRACT+ARCH',detail: 'Zadok writes CONTRACT; Nathan writes ARCHITECTURE — in parallel' },
+    { title: 'THREAT+C4',    detail: 'Benaiah writes THREAT_MODEL; Meshullam writes C4 diagrams — in parallel' },
+    { title: 'Settle',       detail: 'Bezalel signs off on the artefact set; Jehoshaphat scaffolds docs/' },
+  ],
+}
+
+if (!args?.project_name || !args?.project_root || !args?.raw_intent) {
+  throw new Error('mishkan-init requires: { project_name, project_root, raw_intent, stack_hint? }')
+}
+
+const ARTEFACT_SCHEMA = {
+  type: 'object',
+  required: ['artefact', 'path', 'summary'],
+  properties: {
+    artefact: { type: 'string' },
+    path:     { type: 'string', description: 'relative path under project_root' },
+    summary:  { type: 'string' },
+    open_questions: { type: 'array', items: { type: 'string' } },
+  },
+}
+
+const STACK = args.stack_hint || 'undetermined'
+
+// --- Stage 1: PRD ------------------------------------------------------
+phase('PRD')
+const prd = await agent(
+  `Act as Nehemiah. Apply nehemiah-pm-craft. Write PRD.md for ${args.project_name} from the raw intent: ` +
+  `${args.raw_intent}. Stack hint (informational only): ${STACK}. ` +
+  `Write to ${args.project_root}/docs/PRD.md. Include: problem, who-for, success criteria (numeric where possible), ` +
+  `explicitly-out-of-scope (three items minimum), constraints.`,
+  { label: 'nehemiah:prd', phase: 'PRD', agentType: 'nehemiah', schema: ARTEFACT_SCHEMA }
+)
+
+// --- Stage 2: SRS depends on PRD --------------------------------------
+phase('SRS')
+const srs = await agent(
+  `Act as Nathan. Apply nathan-architecture-craft. Write SRS.md for ${args.project_name}. ` +
+  `Read the PRD at ${prd.path}. Produce testable requirements: every F-N requirement has an acceptance test ` +
+  `shape; every NF-N requirement is numeric; constraints called out explicitly; assumptions named. ` +
+  `Write to ${args.project_root}/docs/SRS.md.`,
+  { label: 'nathan:srs', phase: 'SRS', agentType: 'nathan', schema: ARTEFACT_SCHEMA }
+)
+
+// --- Stage 3: CONTRACT + ARCHITECTURE in parallel ---------------------
+// Both depend on SRS only; they can run concurrently.
+phase('CONTRACT+ARCH')
+const [contract, architecture] = await parallel([
+  () => agent(
+    `Act as Zadok. Apply zadok-contract-craft. Write CONTRACT.md for ${args.project_name}. ` +
+    `Read the SRS at ${srs.path}. Author invariants + guarantees: error envelope (code/message/request_id), ` +
+    `pagination shape (cursor only), naming conventions, idempotency clauses where applicable, versioning ` +
+    `policy. Three things explicitly out of scope. Write to ${args.project_root}/docs/CONTRACT.md.`,
+    { label: 'zadok:contract', phase: 'CONTRACT+ARCH', agentType: 'zadok', schema: ARTEFACT_SCHEMA }
+  ),
+  () => agent(
+    `Act as Nathan. Apply nathan-architecture-craft. Write ARCHITECTURE.md for ${args.project_name}. ` +
+    `Read the SRS at ${srs.path}. Produce: system-in-one-diagram (C4 L1 to be drawn by Meshullam), ` +
+    `system-in-one-paragraph, bounded contexts named with ownership rules, data flow on the golden path, ` +
+    `consistency map per data store, failure modes with fallbacks, links to ADRs (none yet, structure ready). ` +
+    `Write to ${args.project_root}/docs/ARCHITECTURE.md.`,
+    { label: 'nathan:architecture', phase: 'CONTRACT+ARCH', agentType: 'nathan', schema: ARTEFACT_SCHEMA }
+  ),
+])
+
+// --- Stage 4: THREAT_MODEL + C4 in parallel ---------------------------
+// THREAT_MODEL needs ARCHITECTURE (trust boundaries derived from it).
+// C4 needs ARCHITECTURE (containers drawn from the named bounded contexts).
+// Neither needs CONTRACT, so the parallelism is real.
+phase('THREAT+C4')
+const [threat, c4] = await parallel([
+  () => agent(
+    `Act as Benaiah. Apply benaiah-devsecops-craft. Write THREAT_MODEL.md for ${args.project_name}. ` +
+    `Read ARCHITECTURE.md at ${architecture.path}. Walk STRIDE per asset and trust boundary. Mitigations are ` +
+    `concrete (not "use TLS" but "mTLS at Traefik with cert rotation every 90 days via cert-manager"). ` +
+    `Open items routed to specialists named. Write to ${args.project_root}/docs/THREAT_MODEL.md.`,
+    { label: 'benaiah:threat-model', phase: 'THREAT+C4', agentType: 'benaiah', schema: ARTEFACT_SCHEMA }
+  ),
+  () => agent(
+    `Act as Meshullam. Apply meshullam-infra-design-craft. Produce C4 diagrams for ${args.project_name}. ` +
+    `Read ARCHITECTURE.md at ${architecture.path}. Generate at least L1 (Context) and L2 (Containers). ` +
+    `Source format Mermaid or PlantUML committed alongside rendered output. Write to ` +
+    `${args.project_root}/docs/diagrams/C4/.`,
+    { label: 'meshullam:c4', phase: 'THREAT+C4', agentType: 'meshullam', schema: ARTEFACT_SCHEMA }
+  ),
+])
+
+// --- Stage 5: Settle — Bezalel signs off, Jehoshaphat scaffolds docs --
+phase('Settle')
+const [signoff, docsScaffold] = await parallel([
+  () => agent(
+    `Act as Bezalel. Apply bezalel-cto-craft. Review the six artefacts produced for ${args.project_name}: ` +
+    `${JSON.stringify({ prd, srs, contract, architecture, threat, c4 })}. ` +
+    `Apply the quality bar: every artefact dated; every requirement testable; every contract clause sourceable; ` +
+    `every threat anchored. Return a sign-off { status: 'accepted' | 'changes_requested', notes }.`,
+    {
+      label: 'bezalel:signoff',
+      phase: 'Settle',
+      agentType: 'bezalel',
+      schema: {
+        type: 'object',
+        required: ['status', 'notes'],
+        properties: {
+          status: { enum: ['accepted', 'changes_requested'] },
+          notes:  { type: 'string' },
+          changes_requested: { type: 'array', items: { type: 'string' } },
+        },
+      },
+    }
+  ),
+  () => agent(
+    `Act as Jehoshaphat. Apply documentation-craft. Scaffold the docs/ tree for ${args.project_name} ` +
+    `at ${args.project_root}/docs/: ADR index, runbooks/, changelog stub, README, Diátaxis quadrant ` +
+    `placeholders. Do not author content; create the scaffold and the index.`,
+    { label: 'jehoshaphat:scaffold', phase: 'Settle', agentType: 'jehoshaphat', schema: ARTEFACT_SCHEMA }
+  ),
+])
+
+return {
+  project_name: args.project_name,
+  project_root: args.project_root,
+  artefacts: {
+    prd, srs, contract, architecture, threat, c4,
+    docs_scaffold: docsScaffold,
+  },
+  bezalel_signoff: signoff,
+  next: signoff?.status === 'accepted'
+    ? `Init complete. Begin Sprint S0; Nehemiah leads. Hand the directory state to Y4NN for git init + first commit.`
+    : `Init blocked on changes_requested. Address Bezalel's notes; re-run mishkan-init or run targeted skill invocations.`,
+}

package/payload/mishkan/workflows/mishkan-migration-wave.js

@@ -0,0 +1,180 @@
+// mishkan-migration-wave — pipeline + worktree-isolated transformation
+// across many files.
+//
+// The MISHKAN-shaped equivalent of the canonical migration workflow
+// (Bun Zig→Rust port: hundreds of files in parallel, two reviewers each,
+// fix-loop until tests green). Adapted to MISHKAN's roles: the transformer
+// is the team's implementer (Hizkiah for backend, Salma for frontend, etc.)
+// and the reviewers are QA + the relevant Lead's specialist.
+//
+// Patterns: pipeline (find → transform → review → verify, each file
+// independent) + worktree isolation per agent (parallel writes don't
+// conflict) + judge panel on review (2 independent reviewers must agree).
+//
+// Args: {
+//   project_root: "/path/to/project",
+//   target_glob: "src/**/*.tsx",
+//   transformation: "<one-paragraph description of what to do to each file>",
+//   transformer_agent: "salma" | "hizkiah" | "oholiab" | ...
+//   reviewers: ["jahaziel", "asaph"]   // 2+ specialists who verify
+//   verify_command: "pnpm test --filter=changed"  // optional; runs after each file
+//   max_files: 200
+// }
+
+export const meta = {
+  name: 'mishkan-migration-wave',
+  description: 'Apply a defined transformation to N files in parallel with 2 reviewers each, optional per-file verify. The MISHKAN shape of the canonical large-migration workflow.',
+  whenToUse: 'Refactors, framework swaps, contract renames, API deprecations, language ports. Anywhere the transformation is per-file and the test suite (or a typecheck/build) can verify each.',
+  phases: [
+    { title: 'Discover',  detail: 'enumerate target files' },
+    { title: 'Transform', detail: 'per-file transformer in an isolated worktree' },
+    { title: 'Review',    detail: 'two reviewers per file (judge panel; both must accept)' },
+    { title: 'Verify',    detail: 'optional per-file test/typecheck/build' },
+    { title: 'Report',    detail: 'per-file status; the wave summary' },
+  ],
+}
+
+if (!args?.project_root || !args?.target_glob || !args?.transformation || !args?.transformer_agent) {
+  throw new Error('mishkan-migration-wave requires: { project_root, target_glob, transformation, transformer_agent, reviewers?, verify_command?, max_files? }')
+}
+
+const REVIEWERS = (args.reviewers && args.reviewers.length >= 2)
+  ? args.reviewers.slice(0, 4)
+  : ['uriah', 'jahaziel']     // sensible default; QA-style
+const MAX_FILES = args.max_files || 200
+
+const TRANSFORM_RESULT_SCHEMA = {
+  type: 'object',
+  required: ['file', 'changed', 'rationale'],
+  properties: {
+    file:      { type: 'string' },
+    changed:   { type: 'boolean' },
+    rationale: { type: 'string' },
+    notes:     { type: 'string' },
+  },
+}
+
+const REVIEW_SCHEMA = {
+  type: 'object',
+  required: ['accept', 'reason'],
+  properties: {
+    accept:    { type: 'boolean' },
+    reason:    { type: 'string' },
+    blockers:  { type: 'array', items: { type: 'string' } },
+  },
+}
+
+const VERIFY_SCHEMA = {
+  type: 'object',
+  required: ['passed', 'detail'],
+  properties: {
+    passed: { type: 'boolean' },
+    detail: { type: 'string' },
+  },
+}
+
+// --- Stage 1: Discover -------------------------------------------------
+phase('Discover')
+const discovery = await agent(
+  `List files under ${args.project_root} matching glob ${JSON.stringify(args.target_glob)}. ` +
+  `Cap at ${MAX_FILES}. Return JSON object { files: [...] }.`,
+  {
+    label: 'discover:targets',
+    phase: 'Discover',
+    agentType: 'Explore',
+    schema: { type: 'object', required: ['files'], properties: { files: { type: 'array', items: { type: 'string' } } } },
+  }
+)
+const files = (discovery?.files || []).slice(0, MAX_FILES)
+log(`${files.length} files match for migration; ${REVIEWERS.length} reviewers per file`)
+
+if (files.length === 0) {
+  return { wave_status: 'no-op', files_changed: [], files_rejected: [], files_failed_verify: [] }
+}
+
+// --- Stage 2-4: per-file pipeline -------------------------------------
+// Each file runs through (transform → review → verify) independently.
+// Transformer runs in an isolated worktree so parallel writes don't
+// conflict; if both reviewers accept and verify passes, we keep it.
+const wave = await pipeline(
+  files,
+
+  // Stage 2: Transform in an isolated worktree.
+  (file, _, i) => agent(
+    `Act as ${args.transformer_agent}. Apply the transformation to ${args.project_root}/${file}. ` +
+    `Transformation: ${args.transformation}. ` +
+    `Read the file first, then Edit it in-place. Do not refactor surrounding code. ` +
+    `Return { file: "${file}", changed: true|false, rationale, notes? }.`,
+    {
+      label: `transform:${file.slice(-40)}`,
+      phase: 'Transform',
+      agentType: args.transformer_agent,
+      isolation: 'worktree',
+      schema: TRANSFORM_RESULT_SCHEMA,
+    }
+  ),
+
+  // Stage 3: Two reviewers in parallel; both must accept.
+  async (transformResult, file) => {
+    if (!transformResult || !transformResult.changed) {
+      return { file, transform: transformResult, review: { accept: false, reason: 'no change emitted' }, verify: null }
+    }
+    const reviews = await parallel(REVIEWERS.map((reviewer) => () => agent(
+      `Act as ${reviewer}. Review the transformed ${args.project_root}/${file}. ` +
+      `The transformation was: ${args.transformation}. The transformer's rationale: ` +
+      `${transformResult.rationale}. Accept only if (a) the transformation is correctly applied at every site ` +
+      `in the file, (b) no unrelated changes were introduced, and (c) the file still type-checks at the local ` +
+      `level. Block on any finding.`,
+      { label: `review:${reviewer}:${file.slice(-32)}`, phase: 'Review',
+        agentType: reviewer, schema: REVIEW_SCHEMA }
+    )))
+    const accepts = reviews.filter(Boolean).filter(r => r.accept).length
+    const allAccept = accepts === REVIEWERS.length
+    return {
+      file,
+      transform: transformResult,
+      review: { accept: allAccept, reviews: reviews.filter(Boolean), accepts, required: REVIEWERS.length },
+      verify: null,
+    }
+  },
+
+  // Stage 4: Optional verify (run the test/typecheck on the changed file scope).
+  async (stage3) => {
+    if (!stage3 || !stage3.review.accept) return { ...stage3, verify: { passed: false, detail: 'skipped — review did not accept' } }
+    if (!args.verify_command) return { ...stage3, verify: { passed: true, detail: 'no verify_command configured; accepted on review alone' } }
+    const v = await agent(
+      `Run the verify command for the changes to ${stage3.file}: ${args.verify_command}. ` +
+      `Cd to ${args.project_root} before running. Return { passed, detail }.`,
+      { label: `verify:${stage3.file.slice(-40)}`, phase: 'Verify',
+        agentType: 'uriah', schema: VERIFY_SCHEMA }
+    )
+    return { ...stage3, verify: v || { passed: false, detail: 'verifier returned null' } }
+  }
+)
+
+// --- Stage 5: Report --------------------------------------------------
+phase('Report')
+const safe = wave.filter(Boolean)
+const changed = safe.filter(w => w.transform?.changed)
+const accepted_by_review = changed.filter(w => w.review.accept)
+const verify_pass = accepted_by_review.filter(w => w.verify?.passed)
+const verify_fail = accepted_by_review.filter(w => w.verify?.passed === false)
+const rejected_by_review = changed.filter(w => !w.review.accept)
+
+log(`Migration wave: ${changed.length} transformed, ${accepted_by_review.length} review-accepted, ` +
+    `${verify_pass.length} verify-passed, ${verify_fail.length} verify-failed, ${rejected_by_review.length} rejected.`)
+
+return {
+  wave_status: verify_fail.length === 0 && rejected_by_review.length === 0 ? 'clean' : 'partial',
+  files_changed_verified:        verify_pass.map(w => w.file),
+  files_changed_review_rejected: rejected_by_review.map(w => ({ file: w.file, reasons: w.review.reviews.filter(r => !r.accept).map(r => r.reason) })),
+  files_changed_verify_failed:   verify_fail.map(w => ({ file: w.file, detail: w.verify.detail })),
+  files_no_change:               safe.filter(w => !w.transform?.changed).map(w => w.file),
+  totals: {
+    files_in_scope: files.length,
+    transformed: changed.length,
+    review_accepted: accepted_by_review.length,
+    verify_passed: verify_pass.length,
+    final_clean: verify_pass.length,
+  },
+}