mindforge-cc 11.7.1 → 11.8.0

package/.mindforge/dynamic-workflows/scripts/accessibility-audit.js

@@ -0,0 +1,119 @@
+export const meta = {
+  name: 'accessibility-audit',
+  description: 'WCAG 2.2 parallel per-criterion audit → 3-vote adversarial verify failures → remediation spec',
+  whenToUse: 'When auditing a UI for WCAG 2.2 compliance before launch, legal review, or accessibility certification',
+  phases: [
+    { title: 'Scope', detail: 'Define target UI and map components/pages to audit' },
+    { title: 'Audit', detail: '6 parallel WCAG principle auditors (Perceivable/Operable/Understandable/Robust + ARIA + Keyboard)' },
+    { title: 'Verify', detail: '3-vote adversarial verification of all Level A and AA failures' },
+    { title: 'Spec', detail: 'Remediation spec with exact ARIA attributes, HTML fixes, and WCAG references' },
+  ],
+};
+
+export default async function run({ agent, parallel, pipeline, phase, log, args, budget }) {
+  const AUDIT_SCHEMA = {
+    type: 'object',
+    properties: {
+      principle: { type: 'string' },
+      issues: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            wcagCriterion: { type: 'string' },
+            level: { type: 'string', enum: ['A', 'AA', 'AAA'] },
+            severity: { type: 'string', enum: ['blocker', 'critical', 'major', 'minor'] },
+            component: { type: 'string' },
+            description: { type: 'string' },
+            fix: { type: 'string' },
+          },
+          required: ['wcagCriterion', 'level', 'severity', 'description', 'fix'],
+        },
+      },
+    },
+    required: ['principle', 'issues'],
+  };
+
+  const VERDICT_SCHEMA = {
+    type: 'object',
+    properties: {
+      isRealIssue: { type: 'boolean' },
+      affectsRealUsers: { type: 'boolean' },
+      reason: { type: 'string' },
+    },
+    required: ['isRealIssue', 'affectsRealUsers', 'reason'],
+  };
+
+  const REMEDIATION_SCHEMA = {
+    type: 'object',
+    properties: {
+      summary: { type: 'string' },
+      wcagLevel: { type: 'string', enum: ['Level A non-compliant', 'Level AA non-compliant', 'Level AA compliant', 'Level AAA compliant'] },
+      criticalFixes: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            issue: { type: 'string' },
+            wcagRef: { type: 'string' },
+            fix: { type: 'string' },
+            codeExample: { type: 'string' },
+          },
+          required: ['issue', 'wcagRef', 'fix', 'codeExample'],
+        },
+      },
+    },
+    required: ['summary', 'wcagLevel', 'criticalFixes'],
+  };
+
+  const target = args || 'current UI codebase (run from repo root)';
+
+  phase('Scope');
+  log(`Accessibility audit target: ${target}`);
+
+  const AUDITORS = [
+    { label: 'perceivable', prompt: `Audit WCAG 2.2 Perceivable criteria for: "${target}". Check: 1.1.1 Non-text content (alt text), 1.2.x captions/transcripts, 1.3.x info/structure (semantic HTML, labels), 1.4.x distinguishable (contrast ratio ≥4.5:1, resize text, no reliance on color alone). List every failure with WCAG criterion, level (A/AA/AAA), severity, and exact fix.` },
+    { label: 'operable', prompt: `Audit WCAG 2.2 Operable criteria for: "${target}". Check: 2.1.x keyboard accessible (all functionality via keyboard, no traps), 2.2.x enough time (no time limits, pause/stop/hide), 2.3.x seizures (no flashing ≥3Hz), 2.4.x navigable (skip links, page titles, focus order, link purpose), 2.5.x input modalities (touch target ≥24×24px). List every failure with criterion, level, and fix.` },
+    { label: 'understandable', prompt: `Audit WCAG 2.2 Understandable criteria for: "${target}". Check: 3.1.x readable (lang attribute, unusual words), 3.2.x predictable (no context changes on focus, consistent navigation), 3.3.x input assistance (error identification, labels/instructions, error suggestion, error prevention). List every failure with criterion, level, and fix.` },
+    { label: 'robust', prompt: `Audit WCAG 2.2 Robust criteria for: "${target}". Check: 4.1.2 Name/Role/Value (all UI components have accessible name, role, state/value), 4.1.3 Status messages (announced to AT without focus). Also check for valid, parseable HTML. List every failure with criterion, level, and fix.` },
+    { label: 'aria', prompt: `Audit ARIA usage for: "${target}". Check: roles match actual element behavior, required aria-* properties present, aria-labelledby/describedby IDs exist, no aria-hidden on interactive elements, no redundant role+element, proper live region usage. List every failure with fix showing correct ARIA attributes.` },
+    { label: 'keyboard', prompt: `Audit keyboard navigation for: "${target}". Check: tab order is logical, visible focus indicator present (not just outline:none), modals trap focus and release on close, custom widgets (accordions, tabs, dropdowns, sliders) follow ARIA authoring practices keyboard patterns, no keyboard traps. List every failure with fix.` },
+  ];
+
+  phase('Audit');
+  const audits = await parallel(
+    AUDITORS.map(a => () => agent(a.prompt, { schema: AUDIT_SCHEMA, label: `audit:${a.label}`, phase: 'Audit' }))
+  );
+
+  phase('Verify');
+  const allIssues = audits.filter(Boolean).flatMap(a => (a.issues || []).map(i => ({ ...i, principle: a.principle })));
+  const levelAandAA = allIssues.filter(i => i.level === 'A' || i.level === 'AA');
+  log(`${allIssues.length} total issues, ${levelAandAA.length} Level A/AA → 3-vote verify`);
+
+  const verified = await parallel(
+    levelAandAA.map(issue => () =>
+      parallel([
+        () => agent(`Is this WCAG ${issue.level} accessibility issue real, or a false positive? Try to REFUTE it. Issue: "${issue.description}" (${issue.wcagCriterion}). Default isRealIssue=false only if clearly not applicable.`, { schema: VERDICT_SCHEMA, label: `v1:${issue.wcagCriterion}`, phase: 'Verify' }),
+        () => agent(`Would a real assistive technology user (screen reader, keyboard-only, low-vision) actually encounter this issue? Issue: "${issue.description}" (${issue.wcagCriterion}). Be specific about which user group is affected.`, { schema: VERDICT_SCHEMA, label: `v2:${issue.wcagCriterion}`, phase: 'Verify' }),
+        () => agent(`Is the WCAG criterion reference accurate for this issue? "${issue.description}" cited as ${issue.wcagCriterion} Level ${issue.level}. Confirm or correct the WCAG reference.`, { schema: VERDICT_SCHEMA, label: `v3:${issue.wcagCriterion}`, phase: 'Verify' }),
+      ]).then(votes => {
+        if (!votes) return { ...issue, confirmed: false };
+        const confirmed = votes.filter(Boolean).filter(v => v.isRealIssue).length;
+        return { ...issue, confirmed: confirmed >= 2 };
+      })
+    )
+  );
+
+  const confirmedIssues = verified.filter(Boolean).filter(i => i.confirmed);
+  log(`${confirmedIssues.length}/${levelAandAA.length} Level A/AA issues confirmed`);
+
+  phase('Spec');
+  const issueSummary = confirmedIssues.slice(0, 15).map(i => `[${i.level}/${i.severity}] ${i.wcagCriterion}: ${i.description} → Fix: ${i.fix}`).join('\n');
+  const remediation = await agent(
+    `Create an accessibility remediation spec for: "${target}"\n\nConfirmed WCAG issues:\n${issueSummary}\n\nFor each critical/blocker issue provide: WCAG reference, exact fix description, and a code example (HTML/ARIA/CSS) showing the corrected implementation. Determine the overall WCAG compliance level.`,
+    { schema: REMEDIATION_SCHEMA, label: 'remediation-spec' }
+  );
+  if (!remediation) { return { target, confirmedIssues, error: 'remediation-agent-null', stats: { total: allIssues.length, levelAAFailures: levelAandAA.length, confirmed: confirmedIssues.length } }; }
+
+  return { target, audits: audits.filter(Boolean), confirmedIssues, remediation, stats: { total: allIssues.length, levelAAFailures: levelAandAA.length, confirmed: confirmedIssues.length } };
+}

package/.mindforge/dynamic-workflows/scripts/ai-model-eval.js

@@ -0,0 +1,82 @@
+export const meta = {
+  name: 'ai-model-eval',
+  description: '4-parallel model benchmark agents → scoring matrix → cost/performance recommendation',
+  whenToUse: 'When choosing between AI models or providers for a use case — benchmark quality, speed, and cost simultaneously',
+  phases: [
+    { title: 'Scope', detail: 'Define evaluation criteria and test prompts for the use case' },
+    { title: 'Benchmark', detail: '4 parallel model evaluators (quality / reasoning / speed / cost)' },
+    { title: 'Score', detail: 'Scoring matrix across all dimensions' },
+    { title: 'Recommend', detail: 'Ranked recommendation with break-even cost analysis' },
+  ],
+};
+
+export default async function run({ agent, parallel, pipeline, phase, log, args, budget }) {
+  const CRITERIA_SCHEMA = {
+    type: 'object',
+    properties: {
+      useCase: { type: 'string' },
+      testPrompts: { type: 'array', items: { type: 'string' } },
+      priorities: { type: 'array', items: { type: 'string' } },
+      modelsToEvaluate: { type: 'array', items: { type: 'string' } },
+    },
+    required: ['useCase', 'testPrompts', 'priorities', 'modelsToEvaluate'],
+  };
+
+  const EVAL_SCHEMA = {
+    type: 'object',
+    properties: {
+      dimension: { type: 'string' },
+      scores: { type: 'array', items: { type: 'object', properties: { model: { type: 'string' }, score: { type: 'number' }, notes: { type: 'string' } }, required: ['model', 'score'] } },
+    },
+    required: ['dimension', 'scores'],
+  };
+
+  const RECOMMENDATION_SCHEMA = {
+    type: 'object',
+    properties: {
+      winner: { type: 'string' },
+      rationale: { type: 'string' },
+      ranking: { type: 'array', items: { type: 'object', properties: { model: { type: 'string' }, totalScore: { type: 'number' }, bestFor: { type: 'string' } }, required: ['model', 'totalScore', 'bestFor'] } },
+      costNote: { type: 'string' },
+    },
+    required: ['winner', 'rationale', 'ranking'],
+  };
+
+  const useCase = args || 'general purpose AI assistant for coding tasks';
+
+  phase('Scope');
+  const criteria = await agent(`Define evaluation criteria and test prompts for this AI model use case: "${useCase}". Create 3-5 representative test prompts that reflect the actual workload. List evaluation priorities (quality/speed/cost/context-length/reasoning) in order of importance. Suggest which models to evaluate (e.g., claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5, gpt-4o, gemini-2.0-flash).`, { schema: CRITERIA_SCHEMA, label: 'scope' });
+  if (!criteria) { return { useCase, error: 'criteria-agent-null' }; }
+  log(`Evaluating ${criteria.modelsToEvaluate.length} models on ${criteria.priorities.length} dimensions`);
+
+  phase('Benchmark');
+  const DIMENSIONS = [
+    { label: 'quality', prompt: `Evaluate OUTPUT QUALITY of these models for: "${useCase}". Test prompts: ${criteria.testPrompts.slice(0, 3).join(' | ')}. Models: ${criteria.modelsToEvaluate.join(', ')}. Score each 0-100 for accuracy, completeness, and usefulness. Base scores on published benchmarks (MMLU, HumanEval, SWE-bench, coding evals) and known model capabilities.` },
+    { label: 'reasoning', prompt: `Evaluate REASONING CAPABILITY of these models for: "${useCase}". Models: ${criteria.modelsToEvaluate.join(', ')}. Score 0-100 for multi-step reasoning, code understanding, logical deduction. Reference published benchmarks (MATH, BBH, ARC).` },
+    { label: 'speed-latency', prompt: `Evaluate SPEED AND LATENCY of these models: ${criteria.modelsToEvaluate.join(', ')}. Score 0-100 (100=fastest). Include: typical time-to-first-token, output tokens/second, and whether the model supports streaming. Reference publicly available benchmarks and known provider SLAs.` },
+    { label: 'cost-efficiency', prompt: `Evaluate COST EFFICIENCY of these models for: "${useCase}" with typical usage of ~1000 input tokens and ~500 output tokens per call. Models: ${criteria.modelsToEvaluate.join(', ')}. Score 0-100 (100=cheapest). Include: price per 1M input/output tokens from official pricing pages, estimated monthly cost at 100K calls/month.` },
+  ];
+
+  const evals = await parallel(
+    DIMENSIONS.map(d => () => agent(d.prompt, { schema: EVAL_SCHEMA, label: `eval:${d.label}`, phase: 'Benchmark' }))
+  );
+
+  phase('Score');
+  const validEvals = evals.filter(Boolean);
+  const modelScores = {};
+  criteria.modelsToEvaluate.forEach(model => {
+    modelScores[model] = validEvals.reduce((sum, e) => {
+      const s = (e.scores || []).find(sc => sc.model === model);
+      return sum + (s ? s.score : 0);
+    }, 0);
+  });
+  const sorted = Object.entries(modelScores).sort((a, b) => b[1] - a[1]);
+  if (sorted.length > 0) log(`Scoring complete — top model: ${sorted[0][0]}`);
+
+  phase('Recommend');
+  const scoreText = Object.entries(modelScores).sort((a, b) => b[1] - a[1]).map(([m, s]) => `${m}: ${s} total`).join(', ');
+  const recommendation = await agent(`Provide a model recommendation for: "${useCase}"\n\nScores: ${scoreText}\n\nPriorities: ${criteria.priorities.join(' > ')}\n\nRank all models, declare the winner with rationale, note the best model for each specific priority, and include a cost note for the top 2 models.`, { schema: RECOMMENDATION_SCHEMA, label: 'recommend' });
+  if (!recommendation) { return { useCase, criteria, evals: validEvals, modelScores, error: 'recommendation-agent-null' }; }
+
+  return { useCase, criteria, evals: validEvals, modelScores, recommendation };
+}

package/.mindforge/dynamic-workflows/scripts/api-contract-test.js

@@ -0,0 +1,114 @@
+export const meta = {
+  name: 'api-contract-test',
+  description: 'Writer/Reviewer pattern: spec reader vs implementation reader → contract violation report',
+  whenToUse: 'When validating that an API implementation matches its OpenAPI/GraphQL/Protobuf spec',
+  phases: [
+    { title: 'ReadSpec', detail: 'Parse the API specification (OpenAPI/GraphQL/Protobuf/docs)' },
+    { title: 'ReadImpl', detail: 'Read the actual implementation in a fresh context' },
+    { title: 'Diff', detail: 'Cross-reference spec contracts vs implementation' },
+    { title: 'Report', detail: 'Violation report with severity and fix instructions' },
+  ],
+};
+
+export default async function run({ agent, parallel, pipeline, phase, log, args, budget }) {
+  const SPEC_SCHEMA = {
+    type: 'object',
+    properties: {
+      apiName: { type: 'string' },
+      endpoints: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            method: { type: 'string' },
+            path: { type: 'string' },
+            requestSchema: { type: 'string' },
+            responseSchema: { type: 'string' },
+            authRequired: { type: 'boolean' },
+            errorCodes: { type: 'array', items: { type: 'string' } },
+          },
+          required: ['method', 'path', 'responseSchema'],
+        },
+      },
+    },
+    required: ['apiName', 'endpoints'],
+  };
+
+  const IMPL_SCHEMA = {
+    type: 'object',
+    properties: {
+      implementedEndpoints: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            method: { type: 'string' },
+            path: { type: 'string' },
+            actualRequestHandling: { type: 'string' },
+            actualResponseShape: { type: 'string' },
+            authImplemented: { type: 'boolean' },
+          },
+          required: ['method', 'path', 'actualResponseShape'],
+        },
+      },
+    },
+    required: ['implementedEndpoints'],
+  };
+
+  const VIOLATION_SCHEMA = {
+    type: 'object',
+    properties: {
+      violations: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            endpoint: { type: 'string' },
+            severity: { type: 'string', enum: ['breaking', 'non-breaking', 'warning'] },
+            type: { type: 'string' },
+            specSays: { type: 'string' },
+            implDoes: { type: 'string' },
+            fix: { type: 'string' },
+          },
+          required: ['endpoint', 'severity', 'type', 'specSays', 'implDoes', 'fix'],
+        },
+      },
+      summary: { type: 'string' },
+      breakingCount: { type: 'number' },
+      compatible: { type: 'boolean' },
+    },
+    required: ['violations', 'summary', 'breakingCount', 'compatible'],
+  };
+
+  const target = args || 'current API (provide spec file path and implementation path as args)';
+
+  phase('ReadSpec');
+  log(`Reading API spec from: ${target}`);
+  const spec = await agent(
+    `Read and extract the complete API contract from the spec file(s) in: "${target}". Look for OpenAPI/Swagger YAML, GraphQL schema files, Protobuf files, or API documentation. Extract every endpoint with its method, path, request/response schema, auth requirements, and error codes.`,
+    { schema: SPEC_SCHEMA, label: 'read-spec' }
+  );
+  if (!spec) { log('Warning: agent returned null for spec, skipping'); return { target, error: 'agent-null' }; }
+  log(`Spec: ${spec.apiName} — ${spec.endpoints.length} endpoints`);
+
+  phase('ReadImpl');
+  const impl = await agent(
+    `Read the actual API IMPLEMENTATION in: "${target}". Look for route handlers, controllers, resolvers, or gRPC handlers. For each endpoint extract the actual request handling logic, response shape being returned, and whether auth is checked. Do NOT read the spec — only the implementation code.`,
+    { schema: IMPL_SCHEMA, label: 'read-impl' }
+  );
+  if (!impl) { log('Warning: agent returned null for impl, skipping'); return { target, error: 'agent-null' }; }
+  log(`Implementation: ${impl.implementedEndpoints.length} endpoints found`);
+
+  phase('Diff');
+  const specText = spec.endpoints.map(e => `${e.method} ${e.path}: response=${e.responseSchema}, auth=${e.authRequired}, errors=${(e.errorCodes || []).join(',')}`).join('\n');
+  const implText = impl.implementedEndpoints.map(e => `${e.method} ${e.path}: response=${e.actualResponseShape}, auth=${e.authImplemented}`).join('\n');
+
+  phase('Report');
+  const report = await agent(
+    `Compare the API specification against the implementation and identify contract violations.\n\nSPEC:\n${specText}\n\nIMPLEMENTATION:\n${implText}\n\nFor each violation: classify as breaking (response shape/auth differs) or non-breaking (extra fields, missing optional), state what the spec says vs what the impl does, and provide the exact fix.`,
+    { schema: VIOLATION_SCHEMA, label: 'violations' }
+  );
+  if (!report) { return { target, spec, impl, error: 'report-agent-null' }; }
+
+  return { target, spec, impl, report };
+}

package/.mindforge/dynamic-workflows/scripts/api-migration.js

@@ -0,0 +1,156 @@
+export const meta = {
+  name: 'api-migration',
+  description: 'Breaking change detection → versioning strategy → migration guide → compatibility matrix',
+  whenToUse: 'When planning or documenting an API version migration — detect breaking changes and generate consumer migration guidance',
+  phases: [
+    { title: 'Detect', detail: 'Detect breaking vs non-breaking changes between old and new API versions' },
+    { title: 'Version', detail: 'Propose versioning strategy: semver, URL versioning, or header versioning' },
+    { title: 'Guide', detail: 'Generate migration guide for API consumers' },
+    { title: 'Matrix', detail: 'Compatibility matrix: which client versions work with which API versions' },
+  ],
+};
+
+export default async function run({ agent, parallel, pipeline, phase, log, args, budget }) {
+  const CHANGES_SCHEMA = {
+    type: 'object',
+    properties: {
+      apiName: { type: 'string' },
+      oldVersion: { type: 'string' },
+      newVersion: { type: 'string' },
+      breakingChanges: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            endpoint: { type: 'string' },
+            changeType: { type: 'string', enum: ['removed-endpoint', 'renamed-field', 'changed-type', 'removed-field', 'changed-auth', 'changed-status-code', 'changed-behavior'] },
+            description: { type: 'string' },
+            impactedClients: { type: 'string' },
+          },
+          required: ['endpoint', 'changeType', 'description'],
+        },
+      },
+      nonBreakingChanges: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            endpoint: { type: 'string' },
+            changeType: { type: 'string', enum: ['added-endpoint', 'added-optional-field', 'added-header', 'performance-improvement', 'deprecation-notice'] },
+            description: { type: 'string' },
+          },
+          required: ['endpoint', 'changeType', 'description'],
+        },
+      },
+    },
+    required: ['apiName', 'breakingChanges', 'nonBreakingChanges'],
+  };
+
+  const VERSIONING_SCHEMA = {
+    type: 'object',
+    properties: {
+      strategy: { type: 'string', enum: ['url-versioning', 'header-versioning', 'semver-package', 'content-negotiation'] },
+      rationale: { type: 'string' },
+      versionIdentifier: { type: 'string' },
+      deprecationPolicy: { type: 'string' },
+      sunsetTimeline: { type: 'string' },
+    },
+    required: ['strategy', 'rationale', 'versionIdentifier', 'deprecationPolicy'],
+  };
+
+  const GUIDE_SCHEMA = {
+    type: 'object',
+    properties: {
+      summary: { type: 'string' },
+      migrationSteps: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            step: { type: 'number' },
+            title: { type: 'string' },
+            description: { type: 'string' },
+            codeExample: { type: 'string' },
+            requiredBy: { type: 'string' },
+          },
+          required: ['step', 'title', 'description'],
+        },
+      },
+      searchAndReplace: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            find: { type: 'string' },
+            replaceWith: { type: 'string' },
+            context: { type: 'string' },
+          },
+          required: ['find', 'replaceWith'],
+        },
+      },
+    },
+    required: ['summary', 'migrationSteps'],
+  };
+
+  const MATRIX_SCHEMA = {
+    type: 'object',
+    properties: {
+      matrix: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            clientVersion: { type: 'string' },
+            apiV1Compatible: { type: 'boolean' },
+            apiV2Compatible: { type: 'boolean' },
+            migrationRequired: { type: 'boolean' },
+            notes: { type: 'string' },
+          },
+          required: ['clientVersion', 'apiV1Compatible', 'apiV2Compatible', 'migrationRequired'],
+        },
+      },
+      supportEndsDate: { type: 'string' },
+      recommendation: { type: 'string' },
+    },
+    required: ['matrix', 'recommendation'],
+  };
+
+  const target = args || 'current API (provide old/new version paths or describe the changes in args)';
+
+  phase('Detect');
+  log(`Detecting API changes in: ${target}`);
+  const changes = await agent(
+    `Analyze the API changes in: "${target}". Compare old vs new API versions. Classify each change as: BREAKING (removed endpoints, renamed/removed fields, changed types, auth changes, status code changes) or NON-BREAKING (added endpoints, added optional fields, performance improvements, deprecation notices). Include the old and new version identifiers.`,
+    { schema: CHANGES_SCHEMA, label: 'detect-changes' }
+  );
+  if (!changes) { log('Warning: agent returned null for changes, skipping'); return { target, error: 'agent-null' }; }
+  log(`API: ${changes.apiName} — ${changes.breakingChanges.length} breaking, ${changes.nonBreakingChanges.length} non-breaking changes`);
+
+  phase('Version');
+  const breakingSummary = changes.breakingChanges.map(c => `${c.endpoint}: ${c.changeType} — ${c.description}`).join('\n');
+  const versioning = await agent(
+    `Propose a versioning strategy for: "${changes.apiName}" migrating from ${changes.oldVersion || 'v1'} to ${changes.newVersion || 'v2'}.\n\nBreaking changes:\n${breakingSummary}\n\nRecommend: URL versioning (/v1, /v2), header versioning (API-Version: 2), or semver package versioning. Include: rationale, deprecation policy, and sunset timeline for the old version.`,
+    { schema: VERSIONING_SCHEMA, label: 'versioning' }
+  );
+  if (!versioning) { log('Warning: agent returned null for versioning, skipping'); return { target, changes, error: 'agent-null' }; }
+  log(`Strategy: ${versioning.strategy} — sunset: ${versioning.sunsetTimeline}`);
+
+  phase('Guide');
+  const guide = await agent(
+    `Write a migration guide for consumers of: "${changes.apiName}" upgrading from ${changes.oldVersion || 'v1'} to ${changes.newVersion || 'v2'}.\n\nBreaking changes:\n${breakingSummary}\n\nVersioning: ${versioning.strategy} (${versioning.versionIdentifier})\n\nProvide: (1) executive summary of what changed and why, (2) numbered migration steps in order, each with description and code example, (3) search-and-replace patterns for automated migration (what to find and replace in client code).`,
+    { schema: GUIDE_SCHEMA, label: 'guide' }
+  );
+  if (!guide) { log('Warning: agent returned null for guide, skipping'); return { target, changes, versioning, error: 'agent-null' }; }
+  log(`Migration guide: ${guide.migrationSteps.length} steps`);
+
+  phase('Matrix');
+  const allChanges = [...changes.breakingChanges, ...changes.nonBreakingChanges];
+  const changeSummary = allChanges.slice(0, 10).map(c => `${c.endpoint}: ${c.changeType}`).join(', ');
+  const matrix = await agent(
+    `Create a compatibility matrix for: "${changes.apiName}"\n\nChanges: ${changeSummary}\n\nVersioning: ${versioning.strategy}\nDeprecation policy: ${versioning.deprecationPolicy}\n\nFor typical client version groups (very-old, old, current, new), show compatibility with each API version and whether migration is required. Include support end date and overall recommendation.`,
+    { schema: MATRIX_SCHEMA, label: 'matrix' }
+  );
+  if (!matrix) { return { target, changes, versioning, guide, error: 'matrix-agent-null' }; }
+
+  return { target, changes, versioning, guide, matrix };
+}

package/.mindforge/dynamic-workflows/scripts/architecture-modernization.js

@@ -0,0 +1,111 @@
+export const meta = {
+  name: 'architecture-modernization',
+  description: 'Legacy architecture map → target design → migration sequencing → risk gates',
+  whenToUse: 'When planning a major architecture overhaul: monolith-to-services, framework upgrade, or platform migration',
+  phases: [
+    { title: 'Map', detail: 'Map current architecture: components, dependencies, coupling, pain points' },
+    { title: 'Design', detail: '3 parallel target architecture proposals with trade-off analysis' },
+    { title: 'Select', detail: 'Judge panel selects best design, synthesizes hybrid' },
+    { title: 'Sequence', detail: 'Migration sequencing with risk gates and rollback checkpoints' },
+    { title: 'Roadmap', detail: 'Sprint-by-sprint modernization roadmap' },
+  ],
+};
+
+export default async function run({ agent, parallel, pipeline, phase, log, args, budget }) {
+  const MAP_SCHEMA = {
+    type: 'object',
+    properties: {
+      components: { type: 'array', items: { type: 'object', properties: { name: { type: 'string' }, responsibility: { type: 'string' }, coupling: { type: 'string', enum: ['tight', 'loose', 'very-tight'] }, painPoints: { type: 'array', items: { type: 'string' } } }, required: ['name', 'responsibility', 'coupling'] } },
+      primaryPainPoints: { type: 'array', items: { type: 'string' } },
+      technicalDebt: { type: 'array', items: { type: 'string' } },
+    },
+    required: ['components', 'primaryPainPoints', 'technicalDebt'],
+  };
+
+  const DESIGN_SCHEMA = {
+    type: 'object',
+    properties: {
+      name: { type: 'string' },
+      approach: { type: 'string' },
+      components: { type: 'array', items: { type: 'string' } },
+      pros: { type: 'array', items: { type: 'string' } },
+      cons: { type: 'array', items: { type: 'string' } },
+      migrationComplexity: { type: 'string', enum: ['low', 'medium', 'high', 'very-high'] },
+      timeEstimate: { type: 'string' },
+    },
+    required: ['name', 'approach', 'pros', 'cons', 'migrationComplexity'],
+  };
+
+  const VERDICT_SCHEMA = {
+    type: 'object',
+    properties: {
+      winner: { type: 'string' },
+      rationale: { type: 'string' },
+      hybridAdjustments: { type: 'array', items: { type: 'string' } },
+      targetArchDescription: { type: 'string' },
+    },
+    required: ['winner', 'rationale', 'targetArchDescription'],
+  };
+
+  const ROADMAP_SCHEMA = {
+    type: 'object',
+    properties: {
+      phases: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            phaseNum: { type: 'number' },
+            name: { type: 'string' },
+            work: { type: 'array', items: { type: 'string' } },
+            riskGates: { type: 'array', items: { type: 'string' } },
+            rollbackCheckpoint: { type: 'string' },
+            durationWeeks: { type: 'number' },
+          },
+          required: ['phaseNum', 'name', 'work', 'riskGates', 'rollbackCheckpoint'],
+        },
+      },
+      totalDurationWeeks: { type: 'number' },
+      criticalDependencies: { type: 'array', items: { type: 'string' } },
+    },
+    required: ['phases', 'totalDurationWeeks'],
+  };
+
+  const target = args || 'current codebase (describe your modernization goal in args)';
+
+  phase('Map');
+  log(`Mapping current architecture for: ${target}`);
+  const archMap = await agent(
+    `Map the current architecture of: "${target}". Identify all major components, their responsibilities, coupling levels (tight/loose), and pain points. List the primary architectural pain points and technical debt items that motivate modernization.`,
+    { schema: MAP_SCHEMA, label: 'arch-map' }
+  );
+  if (!archMap) { log('Warning: agent returned null for archMap, skipping'); return { target, error: 'agent-null' }; }
+  log(`Found ${archMap.components.length} components, ${archMap.primaryPainPoints.length} pain points`);
+
+  phase('Design');
+  const mapContext = `Current architecture: ${archMap.components.map(c => `${c.name}(${c.coupling} coupling)`).join(', ')}\nPain points: ${archMap.primaryPainPoints.join(', ')}`;
+  const designs = await parallel([
+    () => agent(`Design a CONSERVATIVE modernization architecture for: "${target}". ${mapContext}. Propose incremental improvements with minimal disruption — strangler fig pattern, adapter layers, gradual extraction. Optimize for low migration risk.`, { schema: DESIGN_SCHEMA, label: 'design-conservative', phase: 'Design' }),
+    () => agent(`Design an AGGRESSIVE modernization architecture for: "${target}". ${mapContext}. Propose a modern target state — microservices, event-driven, serverless, or modern monolith. Optimize for long-term maintainability.`, { schema: DESIGN_SCHEMA, label: 'design-aggressive', phase: 'Design' }),
+    () => agent(`Design a PRAGMATIC modernization architecture for: "${target}". ${mapContext}. Balance risk vs benefit — modular monolith, domain-driven boundaries, selective extraction of high-value services. Optimize for team productivity.`, { schema: DESIGN_SCHEMA, label: 'design-pragmatic', phase: 'Design' }),
+  ]);
+
+  phase('Select');
+  const designsText = designs.filter(Boolean).map(d => `Option: ${d.name}\nApproach: ${d.approach}\nPros: ${d.pros.join(', ')}\nCons: ${d.cons.join(', ')}\nComplexity: ${d.migrationComplexity}\nTime: ${d.timeEstimate}`).join('\n\n');
+  const verdict = await agent(
+    `Select the best modernization architecture for: "${target}"\n\nThree options:\n${designsText}\n\nChoose the winner based on: migration risk, team capability, business continuity, long-term value. Suggest hybrid adjustments that take the best elements from runners-up. Describe the final target architecture.`,
+    { schema: VERDICT_SCHEMA, label: 'design-select' }
+  );
+  if (!verdict) { log('Warning: agent returned null for verdict, skipping'); return { target, archMap, designs: designs.filter(Boolean), error: 'agent-null' }; }
+  log(`Selected: ${verdict.winner} — ${verdict.rationale.slice(0, 80)}`);
+
+  phase('Roadmap');
+  phase('Sequence');
+  const roadmap = await agent(
+    `Create a phased migration roadmap for: "${target}"\n\nTarget architecture: ${verdict.targetArchDescription}\n\nCurrent pain points: ${archMap.primaryPainPoints.join(', ')}\n\nSequence the work into migration phases with: specific work items, risk gates (conditions that must be true before proceeding), rollback checkpoints, and duration estimates. Ensure each phase is independently deployable.`,
+    { schema: ROADMAP_SCHEMA, label: 'sequence' }
+  );
+  if (!roadmap) { return { target, archMap, designs: designs.filter(Boolean), verdict, error: 'roadmap-agent-null' }; }
+
+  return { target, archMap, designs: designs.filter(Boolean), verdict, roadmap };
+}