mindforge-cc 11.7.1 → 11.8.1

package/.mindforge/dynamic-workflows/scripts/debug-detective.js

@@ -0,0 +1,124 @@
+export const meta = {
+  name: 'debug-detective',
+  description: '4-hypothesis parallel investigation → evidence gathering → scientific RCA',
+  whenToUse: 'When debugging a hard-to-reproduce bug, production issue, or mysterious failure with unclear root cause',
+  phases: [
+    { title: 'Intake', detail: 'Document symptoms, context, and reproduction steps' },
+    { title: 'Hypothesize', detail: '4 parallel hypothesis agents from different angles' },
+    { title: 'Evidence', detail: 'Parallel evidence gathering per hypothesis' },
+    { title: 'RCA', detail: 'Scientific root cause analysis from evidence' },
+    { title: 'Fix', detail: 'Targeted fix plan with regression test spec' },
+  ],
+};
+
+export default async function run({ agent, parallel, pipeline, phase, log, args, budget }) {
+  const INTAKE_SCHEMA = {
+    type: 'object',
+    properties: {
+      bugSummary: { type: 'string' },
+      symptoms: { type: 'array', items: { type: 'string' } },
+      reproducible: { type: 'boolean' },
+      affectedComponents: { type: 'array', items: { type: 'string' } },
+      recentChanges: { type: 'array', items: { type: 'string' } },
+      environment: { type: 'string' },
+    },
+    required: ['bugSummary', 'symptoms', 'affectedComponents'],
+  };
+
+  const HYPOTHESIS_SCHEMA = {
+    type: 'object',
+    properties: {
+      angle: { type: 'string' },
+      hypothesis: { type: 'string' },
+      reasoning: { type: 'string' },
+      evidenceNeeded: { type: 'array', items: { type: 'string' } },
+      probability: { type: 'string', enum: ['high', 'medium', 'low'] },
+    },
+    required: ['angle', 'hypothesis', 'reasoning', 'evidenceNeeded', 'probability'],
+  };
+
+  const EVIDENCE_SCHEMA = {
+    type: 'object',
+    properties: {
+      hypothesis: { type: 'string' },
+      supportingEvidence: { type: 'array', items: { type: 'string' } },
+      refutingEvidence: { type: 'array', items: { type: 'string' } },
+      verdict: { type: 'string', enum: ['strongly-supported', 'weakly-supported', 'inconclusive', 'refuted'] },
+      confidence: { type: 'number' },
+    },
+    required: ['hypothesis', 'supportingEvidence', 'refutingEvidence', 'verdict', 'confidence'],
+  };
+
+  const RCA_SCHEMA = {
+    type: 'object',
+    properties: {
+      rootCause: { type: 'string' },
+      causalChain: { type: 'array', items: { type: 'string' } },
+      contributingFactors: { type: 'array', items: { type: 'string' } },
+      whyNowExplanation: { type: 'string' },
+      confidence: { type: 'string', enum: ['high', 'medium', 'low'] },
+    },
+    required: ['rootCause', 'causalChain', 'confidence'],
+  };
+
+  const FIX_SCHEMA = {
+    type: 'object',
+    properties: {
+      fixDescription: { type: 'string' },
+      filestoChange: { type: 'array', items: { type: 'string' } },
+      implementationSteps: { type: 'array', items: { type: 'string' } },
+      regressionTestSpec: { type: 'string' },
+      riskOfFix: { type: 'string', enum: ['low', 'medium', 'high'] },
+    },
+    required: ['fixDescription', 'implementationSteps', 'regressionTestSpec'],
+  };
+
+  const bugReport = args || 'No bug report provided — describe the bug, symptoms, and context in args.';
+
+  phase('Intake');
+  log(`Analyzing bug report: ${bugReport.slice(0, 80)}`);
+  const intake = await agent(
+    `Analyze this bug report and extract structured information: "${bugReport}"\n\nIdentify: bug summary, specific symptoms observed, whether reproducible, affected components/files, any recent changes that might be related, and environment (prod/staging/dev, OS, browser, etc.).`,
+    { schema: INTAKE_SCHEMA, label: 'intake' }
+  );
+  if (!intake) { log('Warning: agent returned null for intake, skipping'); return { bugReport, error: 'agent-null' }; }
+  log(`Bug: ${intake.bugSummary} | Affects: ${intake.affectedComponents.join(', ')}`);
+
+  phase('Hypothesize');
+  const context = `Bug: ${intake.bugSummary}\nSymptoms: ${intake.symptoms.join(', ')}\nAffected: ${intake.affectedComponents.join(', ')}\nRecent changes: ${(intake.recentChanges || []).join(', ')}`;
+  const hypotheses = await parallel([
+    () => agent(`Generate a hypothesis from a CODE perspective for this bug: ${context}\n\nFocus on: logic errors, off-by-one, null/undefined handling, async/await issues, type coercion. What specific code defect could cause these symptoms?`, { schema: HYPOTHESIS_SCHEMA, label: 'hypothesis-code', phase: 'Hypothesize' }),
+    () => agent(`Generate a hypothesis from a STATE/DATA perspective for this bug: ${context}\n\nFocus on: database state corruption, stale cache, race condition, shared mutable state, session/cookie issues. What data or state problem could cause these symptoms?`, { schema: HYPOTHESIS_SCHEMA, label: 'hypothesis-state', phase: 'Hypothesize' }),
+    () => agent(`Generate a hypothesis from an INTEGRATION/ENVIRONMENT perspective for this bug: ${context}\n\nFocus on: API contract mismatch, network timeout, environment variable, dependency version conflict, OS/browser differences. What external factor could cause these symptoms?`, { schema: HYPOTHESIS_SCHEMA, label: 'hypothesis-integration', phase: 'Hypothesize' }),
+    () => agent(`Generate a hypothesis from a REGRESSION perspective for this bug: ${context}\n\nFocus on: what recent change (deploy, config, dependency update) most likely introduced this. Which commit or change is the prime suspect?`, { schema: HYPOTHESIS_SCHEMA, label: 'hypothesis-regression', phase: 'Hypothesize' }),
+  ]);
+
+  phase('Evidence');
+  const validHypotheses = hypotheses.filter(Boolean);
+  log(`${validHypotheses.length} hypotheses — gathering evidence in parallel`);
+
+  const evidence = await parallel(
+    validHypotheses.map(h => () => agent(
+      `Gather evidence for or against this hypothesis about the bug "${intake.bugSummary}":\n\nHypothesis: ${h.hypothesis}\nEvidence needed: ${h.evidenceNeeded.join(', ')}\n\nLook in the codebase for: ${h.evidenceNeeded.join(', ')}. Report what you find that supports OR refutes this hypothesis. Rate your verdict.`,
+      { schema: EVIDENCE_SCHEMA, label: `evidence:${h.angle.slice(0, 20)}`, phase: 'Evidence' }
+    ))
+  );
+
+  phase('RCA');
+  const evidenceSummary = evidence.filter(Boolean).map(e => `${e.hypothesis}: ${e.verdict} (${e.confidence}%) — supports: [${e.supportingEvidence.slice(0, 2).join(', ')}] refutes: [${e.refutingEvidence.slice(0, 1).join(', ')}]`).join('\n');
+  const rca = await agent(
+    `Perform a scientific root cause analysis for: "${intake.bugSummary}"\n\nEvidence summary:\n${evidenceSummary}\n\nIdentify the root cause (the specific defect that, if fixed, would prevent the bug), the causal chain (how root cause leads to symptoms), contributing factors, and why it appeared now. Rate your confidence.`,
+    { schema: RCA_SCHEMA, label: 'rca' }
+  );
+  if (!rca) { log('Warning: agent returned null for rca, skipping'); return { bugReport, intake, hypotheses: validHypotheses, evidence: evidence.filter(Boolean), error: 'agent-null' }; }
+  log(`RCA: ${rca.rootCause.slice(0, 80)} (confidence: ${rca.confidence})`);
+
+  phase('Fix');
+  const fix = await agent(
+    `Design a targeted fix for this bug.\n\nRoot cause: ${rca.rootCause}\nCausal chain: ${rca.causalChain.join(' → ')}\nAffected components: ${intake.affectedComponents.join(', ')}\n\nProvide: exact fix description, which files to change, step-by-step implementation, a regression test specification that would catch this bug if reintroduced, and risk assessment of the fix.`,
+    { schema: FIX_SCHEMA, label: 'fix' }
+  );
+  if (!fix) { log('Warning: agent returned null for fix, skipping'); return { bugReport, intake, hypotheses: validHypotheses, evidence: evidence.filter(Boolean), rca, error: 'agent-null' }; }
+
+  return { bugReport, intake, hypotheses: validHypotheses, evidence: evidence.filter(Boolean), rca, fix };
+}

package/.mindforge/dynamic-workflows/scripts/dependency-health.js

@@ -0,0 +1,110 @@
+export const meta = {
+  name: 'dependency-health',
+  description: 'Parallel per-dependency audit (CVEs / licenses / staleness / maintenance) → risk matrix',
+  whenToUse: 'When auditing dependencies before a release, security review, or due diligence',
+  phases: [
+    { title: 'Inventory', detail: 'Extract full dependency tree from package manifests' },
+    { title: 'Audit', detail: 'Parallel audit per batch: CVEs, license risk, staleness, maintenance status' },
+    { title: 'RiskMatrix', detail: 'Consolidate into risk matrix with severity tiers' },
+    { title: 'Action', detail: 'Prioritized upgrade / replace / accept recommendations' },
+  ],
+};
+
+export default async function run({ agent, parallel, pipeline, phase, log, args, budget }) {
+  const INVENTORY_SCHEMA = {
+    type: 'object',
+    properties: {
+      dependencies: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            name: { type: 'string' },
+            version: { type: 'string' },
+            type: { type: 'string', enum: ['prod', 'dev', 'peer', 'optional'] },
+          },
+          required: ['name', 'version', 'type'],
+        },
+      },
+      packageManager: { type: 'string' },
+    },
+    required: ['dependencies', 'packageManager'],
+  };
+
+  const BATCH_SCHEMA = {
+    type: 'object',
+    properties: {
+      audits: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            name: { type: 'string' },
+            cveRisk: { type: 'string', enum: ['critical', 'high', 'medium', 'low', 'none'] },
+            licenseRisk: { type: 'string', enum: ['copyleft', 'permissive', 'unknown', 'proprietary'] },
+            staleness: { type: 'string', enum: ['current', 'minor-behind', 'major-behind', 'abandoned'] },
+            maintenanceStatus: { type: 'string', enum: ['active', 'slow', 'stale', 'archived', 'unknown'] },
+            recommendation: { type: 'string', enum: ['upgrade', 'replace', 'accept', 'remove'] },
+            notes: { type: 'string' },
+          },
+          required: ['name', 'cveRisk', 'licenseRisk', 'staleness', 'maintenanceStatus', 'recommendation'],
+        },
+      },
+    },
+    required: ['audits'],
+  };
+
+  const ACTION_SCHEMA = {
+    type: 'object',
+    properties: {
+      summary: { type: 'string' },
+      immediateUpgrades: { type: 'array', items: { type: 'string' } },
+      replaceWithAlternatives: { type: 'array', items: { type: 'object', properties: { current: { type: 'string' }, replacement: { type: 'string' }, reason: { type: 'string' } }, required: ['current', 'replacement', 'reason'] } },
+      acceptableRisks: { type: 'array', items: { type: 'string' } },
+      licenseIssues: { type: 'array', items: { type: 'string' } },
+    },
+    required: ['summary', 'immediateUpgrades', 'replaceWithAlternatives', 'acceptableRisks'],
+  };
+
+  const target = args || 'current project (run from repo root)';
+
+  phase('Inventory');
+  log(`Inventorying dependencies in: ${target}`);
+  const inventory = await agent(
+    `Extract the complete dependency list from package manifests in: "${target}". Look for package.json, requirements.txt, Pipfile, go.mod, Gemfile, Cargo.toml, or similar. List each dependency with its current version and type (prod/dev/peer/optional). Identify the package manager used.`,
+    { schema: INVENTORY_SCHEMA, label: 'inventory' }
+  );
+  if (!inventory) { return { target, error: 'inventory-agent-null' }; }
+  const allDeps = inventory.dependencies || [];
+  log(`Found ${allDeps.length} dependencies (${inventory.packageManager})`);
+
+  const BATCH_SIZE = 10;
+  const batches = [];
+  for (let i = 0; i < allDeps.length; i += BATCH_SIZE) {
+    batches.push(allDeps.slice(i, i + BATCH_SIZE));
+  }
+  log(`Auditing in ${batches.length} batches of up to ${BATCH_SIZE}`);
+
+  phase('Audit');
+  const batchResults = await parallel(
+    batches.map((batch, idx) => () => agent(
+      `Audit these dependencies for security and health: ${batch.map(d => `${d.name}@${d.version}`).join(', ')}. For each: (1) known CVEs or security advisories, (2) license type (MIT/Apache/GPL/etc.), (3) staleness (how far behind latest), (4) maintenance status (active/slow/stale/archived). Provide upgrade/replace/accept/remove recommendation.`,
+      { schema: BATCH_SCHEMA, label: `audit-batch-${idx}`, phase: 'Audit' }
+    ))
+  );
+
+  phase('RiskMatrix');
+  const allAudits = batchResults.filter(Boolean).flatMap(b => b.audits || []);
+  const critical = allAudits.filter(a => a.cveRisk === 'critical' || a.cveRisk === 'high');
+  const licenseIssues = allAudits.filter(a => a.licenseRisk === 'copyleft' || a.licenseRisk === 'unknown');
+  log(`${critical.length} high/critical CVE risks, ${licenseIssues.length} license issues`);
+
+  phase('Action');
+  const matrixText = allAudits.filter(a => a.cveRisk !== 'none' || a.recommendation !== 'accept').slice(0, 20).map(a => `${a.name}: CVE=${a.cveRisk}, license=${a.licenseRisk}, staleness=${a.staleness}, status=${a.maintenanceStatus} → ${a.recommendation}`).join('\n');
+  const actions = await agent(
+    `Create a dependency action plan for: "${target}"\n\nRisk matrix:\n${matrixText}\n\nPrioritize: (1) immediate upgrades for critical CVEs, (2) replacements for abandoned/high-risk deps, (3) acceptable-risk accepts, (4) license issues to resolve. For replacements, suggest specific alternative packages.`,
+    { schema: ACTION_SCHEMA, label: 'action-plan' }
+  );
+
+  return { target, inventory, audits: allAudits, actions, stats: { total: allDeps.length, criticalCVE: critical.length, licenseIssues: licenseIssues.length } };
+}

package/.mindforge/dynamic-workflows/scripts/design-system-audit.js

@@ -0,0 +1,115 @@
+export const meta = {
+  name: 'design-system-audit',
+  description: '5 parallel dimension auditors (spacing/color/typography/icons/a11y) → consistency score',
+  whenToUse: 'When auditing a UI codebase for design system consistency before a design review, refactor, or component library update',
+  phases: [
+    { title: 'Inventory', detail: 'Discover design tokens, component files, and styling approach' },
+    { title: 'Audit', detail: '5 parallel dimension auditors: spacing, color, typography, icons, accessibility' },
+    { title: 'Score', detail: 'Aggregate consistency scores per dimension and overall' },
+    { title: 'Report', detail: 'Design system health report with specific violation fixes' },
+  ],
+};
+
+export default async function run({ agent, parallel, pipeline, phase, log, args, budget }) {
+  const INVENTORY_SCHEMA = {
+    type: 'object',
+    properties: {
+      stylingApproach: { type: 'string' },
+      tokenFiles: { type: 'array', items: { type: 'string' } },
+      componentFiles: { type: 'array', items: { type: 'string' } },
+      designSystem: { type: 'string' },
+    },
+    required: ['stylingApproach', 'componentFiles'],
+  };
+
+  const DIM_SCHEMA = {
+    type: 'object',
+    properties: {
+      dimension: { type: 'string' },
+      score: { type: 'number' },
+      violations: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            file: { type: 'string' },
+            severity: { type: 'string', enum: ['critical', 'high', 'medium', 'low'] },
+            description: { type: 'string' },
+            fix: { type: 'string' },
+          },
+          required: ['severity', 'description', 'fix'],
+        },
+      },
+      positives: { type: 'array', items: { type: 'string' } },
+    },
+    required: ['dimension', 'score', 'violations'],
+  };
+
+  const REPORT_SCHEMA = {
+    type: 'object',
+    properties: {
+      overallScore: { type: 'number' },
+      summary: { type: 'string' },
+      dimensionScores: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            dimension: { type: 'string' },
+            score: { type: 'number' },
+            topIssue: { type: 'string' },
+          },
+          required: ['dimension', 'score', 'topIssue'],
+        },
+      },
+      topFixes: { type: 'array', items: { type: 'string' } },
+      tokenizationGaps: { type: 'array', items: { type: 'string' } },
+    },
+    required: ['overallScore', 'summary', 'dimensionScores', 'topFixes'],
+  };
+
+  const target = args || 'current codebase (run from repo root)';
+
+  phase('Inventory');
+  log(`Design system audit target: ${target}`);
+  const inventory = await agent(
+    `Inventory the design system foundations of: "${target}". Identify: (1) styling approach (CSS modules, Tailwind, styled-components, CSS-in-JS, etc.), (2) design token files (variables, theme files, constants), (3) component files (UI components, primitives), (4) which design system library is used if any (shadcn, MUI, Chakra, etc.).`,
+    { schema: INVENTORY_SCHEMA, label: 'inventory' }
+  );
+  if (!inventory) { log('Warning: agent returned null for inventory, skipping'); return { target, error: 'agent-null' }; }
+  log(`Styling: ${inventory.stylingApproach}, ${inventory.componentFiles.length} component files`);
+
+  phase('Audit');
+  const ctx = `Styling: ${inventory.stylingApproach}. Design system: ${inventory.designSystem || 'custom'}. Token files: ${(inventory.tokenFiles || []).join(', ')}`;
+
+  const DIMENSIONS = [
+    { label: 'spacing', prompt: `Audit SPACING CONSISTENCY in: "${target}". ${ctx}. Check: Are spacing values taken from a defined scale (4px/8px/16px etc.)? Are there magic numbers (arbitrary pixel values)? Is padding/margin/gap consistent for similar components? Are layout spacings reusing tokens? Score 0-100 (100=perfectly consistent) and list all violations with fixes.` },
+    { label: 'color', prompt: `Audit COLOR USAGE in: "${target}". ${ctx}. Check: Are colors from the defined palette/tokens only? Are there hardcoded hex values that bypass tokens? Is color used for meaning (red=error, green=success) consistently? Are brand colors consistent? Score 0-100 and list all violations.` },
+    { label: 'typography', prompt: `Audit TYPOGRAPHY SCALE in: "${target}". ${ctx}. Check: Are font sizes from a defined type scale? Are font weights consistent for similar hierarchy levels? Are line-heights defined? Is the heading hierarchy (h1>h2>h3) visually consistent? Score 0-100 and list violations.` },
+    { label: 'icons', prompt: `Audit ICON CONSISTENCY in: "${target}". ${ctx}. Check: Is a single icon library used consistently? Are icon sizes consistent for the same context (nav icons vs inline icons)? Are icon meanings consistent (same icon for same action everywhere)? Are there mixed icon styles (outline vs filled)? Score 0-100 and list violations.` },
+    { label: 'accessibility', prompt: `Audit ACCESSIBILITY in the design system of: "${target}". ${ctx}. Check: Do color combinations meet WCAG AA contrast ratio (4.5:1 for normal text, 3:1 for large)? Are interactive elements at least 44x44px touch targets? Are focus states visible? Are disabled states visually distinct? Score 0-100 and list violations.` },
+  ];
+
+  const auditResults = await parallel(
+    DIMENSIONS.map(d => () => agent(d.prompt, { schema: DIM_SCHEMA, label: `audit:${d.label}`, phase: 'Audit' }))
+  );
+
+  phase('Score');
+  const validAudits = auditResults.filter(Boolean);
+  const avgScore = validAudits.length > 0
+    ? Math.round(validAudits.reduce((sum, a) => sum + (a.score || 0), 0) / validAudits.length)
+    : 0;
+  log(`Dimension scores: ${validAudits.map(a => `${a.dimension}=${a.score}`).join(', ')} | Overall: ${avgScore}`);
+
+  phase('Report');
+  const dimSummary = validAudits.map(a => `${a.dimension}: ${a.score}/100, top issue: ${(a.violations[0] || {}).description || 'none'}`).join('\n');
+  const allViolations = validAudits.flatMap(a => a.violations.map(v => `[${a.dimension}/${v.severity}] ${v.description}`)).slice(0, 15).join('\n');
+
+  const report = await agent(
+    `Generate a design system health report for: "${target}"\n\nDimension scores:\n${dimSummary}\n\nTop violations:\n${allViolations}\n\nOverall consistency score: ${avgScore}/100\n\nProvide: executive summary, dimension score table with top issue each, top 5 priority fixes, and which values should be tokenized but aren't.`,
+    { schema: REPORT_SCHEMA, label: 'report' }
+  );
+  if (!report) { return { target, inventory, audits: validAudits, error: 'report-agent-null' }; }
+
+  return { target, inventory, audits: validAudits, report };
+}

package/.mindforge/dynamic-workflows/scripts/documentation-gen.js

@@ -0,0 +1,91 @@
+export const meta = {
+  name: 'documentation-gen',
+  description: 'Parallel per-file doc generation → style normalization → publish-ready documentation',
+  whenToUse: 'When generating or refreshing documentation for a codebase, API, or module',
+  phases: [
+    { title: 'Scope', detail: 'Discover files needing documentation' },
+    { title: 'Generate', detail: 'Parallel doc generation per file/module' },
+    { title: 'Normalize', detail: 'Style consistency pass across all generated docs' },
+    { title: 'Publish', detail: 'Assemble README, API reference, and changelog entries' },
+  ],
+};
+
+export default async function run({ agent, parallel, pipeline, phase, log, args, budget }) {
+  const FILE_LIST_SCHEMA = {
+    type: 'object',
+    properties: {
+      files: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            path: { type: 'string' },
+            type: { type: 'string', enum: ['module', 'class', 'function', 'api-route', 'config', 'util'] },
+            priority: { type: 'string', enum: ['high', 'medium', 'low'] },
+            currentDocStatus: { type: 'string', enum: ['none', 'partial', 'outdated', 'current'] },
+          },
+          required: ['path', 'type', 'priority', 'currentDocStatus'],
+        },
+      },
+    },
+    required: ['files'],
+  };
+
+  const DOC_SCHEMA = {
+    type: 'object',
+    properties: {
+      path: { type: 'string' },
+      summary: { type: 'string' },
+      description: { type: 'string' },
+      parameters: { type: 'array', items: { type: 'object', properties: { name: { type: 'string' }, type: { type: 'string' }, description: { type: 'string' }, required: { type: 'boolean' } }, required: ['name', 'type', 'description'] } },
+      returns: { type: 'string' },
+      examples: { type: 'array', items: { type: 'string' } },
+      sideEffects: { type: 'array', items: { type: 'string' } },
+    },
+    required: ['path', 'summary', 'description'],
+  };
+
+  const PUBLISH_SCHEMA = {
+    type: 'object',
+    properties: {
+      readmeSection: { type: 'string' },
+      apiReference: { type: 'string' },
+      quickStart: { type: 'string' },
+      changelogEntries: { type: 'array', items: { type: 'string' } },
+    },
+    required: ['readmeSection', 'apiReference', 'quickStart'],
+  };
+
+  const target = args || 'current codebase (run from repo root)';
+
+  phase('Scope');
+  log(`Scoping documentation for: ${target}`);
+  const fileList = await agent(
+    `Discover all files in: "${target}" that need documentation. Focus on: public APIs, exported functions/classes, route handlers, configuration modules. For each file note its type (module/class/function/api-route/config/util), documentation priority (high=public API, medium=internal, low=util), and current doc status (none/partial/outdated/current). Skip test files and auto-generated files.`,
+    { schema: FILE_LIST_SCHEMA, label: 'scope' }
+  );
+
+  const highAndMedium = ((fileList || {}).files || []).filter(f => f.priority === 'high' || f.priority === 'medium').slice(0, 15);
+  log(`Generating docs for ${highAndMedium.length} priority files`);
+
+  phase('Generate');
+  const docs = await parallel(
+    highAndMedium.map(f => () => agent(
+      `Generate complete documentation for the file at "${f.path}" in codebase: "${target}". It is a ${f.type}. Write: (1) one-line summary, (2) full description with purpose and usage context, (3) all parameters with types and descriptions, (4) return value description, (5) 1-2 concrete usage examples, (6) any side effects or important caveats.`,
+      { schema: DOC_SCHEMA, label: `doc:${f.path.split('/').pop().replace('.', '-')}`, phase: 'Generate' }
+    ))
+  );
+
+  phase('Normalize');
+  const validDocs = docs.filter(Boolean);
+  const docSummaries = validDocs.map(d => `${d.path}: ${d.summary}`).join('\n');
+  log(`${validDocs.length} docs generated — normalizing style`);
+
+  phase('Publish');
+  const publish = await agent(
+    `Assemble publish-ready documentation for: "${target}"\n\nGenerated docs:\n${docSummaries}\n\nProduce: (1) README API section (markdown table of all public exports with one-line descriptions), (2) full API reference (each entry with params, returns, example), (3) quick-start guide showing the most common 3-5 use cases, (4) CHANGELOG entry lines for newly documented items.`,
+    { schema: PUBLISH_SCHEMA, label: 'publish' }
+  );
+
+  return { target, fileList, docs: validDocs, publish };
+}

package/.mindforge/dynamic-workflows/scripts/multi-repo-sync.js

@@ -0,0 +1,63 @@
+export const meta = {
+  name: 'multi-repo-sync',
+  description: 'Parallel per-repo audit → cross-repo divergence map → sync plan',
+  whenToUse: 'When managing multiple related repos and need to find/fix divergence in shared config, deps, or conventions',
+  phases: [
+    { title: 'Discover', detail: 'List target repos and their relationships' },
+    { title: 'Audit', detail: 'Parallel audit per repo for divergence from the reference' },
+    { title: 'DivergenceMap', detail: 'Cross-repo divergence map with severity' },
+    { title: 'SyncPlan', detail: 'Prioritized sync plan — what to align and how' },
+  ],
+};
+
+export default async function run({ agent, parallel, pipeline, phase, log, args, budget }) {
+  const REPO_SCHEMA = {
+    type: 'object',
+    properties: {
+      repos: { type: 'array', items: { type: 'object', properties: { name: { type: 'string' }, path: { type: 'string' }, role: { type: 'string' } }, required: ['name', 'path'] } },
+      referenceRepo: { type: 'string' },
+      syncDimensions: { type: 'array', items: { type: 'string' } },
+    },
+    required: ['repos', 'syncDimensions'],
+  };
+
+  const AUDIT_SCHEMA = {
+    type: 'object',
+    properties: {
+      repo: { type: 'string' },
+      divergences: { type: 'array', items: { type: 'object', properties: { dimension: { type: 'string' }, severity: { type: 'string', enum: ['critical', 'high', 'medium', 'low'] }, description: { type: 'string' }, fix: { type: 'string' } }, required: ['dimension', 'severity', 'description', 'fix'] } },
+    },
+    required: ['repo', 'divergences'],
+  };
+
+  const SYNC_SCHEMA = {
+    type: 'object',
+    properties: {
+      summary: { type: 'string' },
+      syncItems: { type: 'array', items: { type: 'object', properties: { repo: { type: 'string' }, dimension: { type: 'string' }, action: { type: 'string' }, priority: { type: 'string', enum: ['p0', 'p1', 'p2'] } }, required: ['repo', 'dimension', 'action', 'priority'] } },
+    },
+    required: ['summary', 'syncItems'],
+  };
+
+  const target = args || 'current workspace (list repo paths in args, comma-separated)';
+
+  phase('Discover');
+  const discovery = await agent(`Discover all related repositories in: "${target}". List each repo's name, path, and role (primary/service/library/config). Identify the reference/canonical repo (if any) and what dimensions should be synchronized: dependencies, CI config, lint config, code conventions, shared utilities, test patterns.`, { schema: REPO_SCHEMA, label: 'discover' });
+  if (!discovery) { return { target, error: 'discovery-agent-null' }; }
+  log(`Found ${discovery.repos.length} repos, ${discovery.syncDimensions.length} sync dimensions`);
+
+  phase('Audit');
+  const audits = await parallel(
+    discovery.repos.map(r => () => agent(`Audit repo "${r.name}" at "${r.path}" against the reference "${discovery.referenceRepo || 'best practices'}". Check dimensions: ${discovery.syncDimensions.join(', ')}. For each divergence: dimension, severity, what differs, and exact fix.`, { schema: AUDIT_SCHEMA, label: `audit:${r.name}`, phase: 'Audit' }))
+  );
+
+  phase('DivergenceMap');
+  const allDivergences = audits.filter(Boolean).flatMap(a => a.divergences.map(d => ({ repo: a.repo, ...d })));
+  log(`${allDivergences.length} divergences across ${discovery.repos.length} repos`);
+
+  phase('SyncPlan');
+  const divergenceText = allDivergences.slice(0, 20).map(d => `[${d.severity}] ${d.repo}/${d.dimension}: ${d.description} → ${d.fix}`).join('\n');
+  const syncPlan = await agent(`Create a sync plan for: "${target}"\n\nDivergences:\n${divergenceText}\n\nPrioritize by severity and group by dimension for efficient batching. P0=critical/security, P1=high/consistency, P2=medium/nice-to-have.`, { schema: SYNC_SCHEMA, label: 'sync-plan' });
+
+  return { target, discovery, audits: audits.filter(Boolean), syncPlan };
+}

package/.mindforge/dynamic-workflows/scripts/mutation-testing.js

@@ -0,0 +1,148 @@
+export const meta = {
+  name: 'mutation-testing',
+  description: 'Mutant generator → parallel kill-test agents → mutation score + survival report',
+  whenToUse: 'When assessing test suite quality — finds tests that pass even when code is subtly broken',
+  phases: [
+    { title: 'Analyze', detail: 'Identify mutable source lines: conditions, operators, return values' },
+    { title: 'Mutate', detail: 'Generate 10-15 specific mutation descriptions' },
+    { title: 'Kill', detail: 'Parallel kill-test per mutation — would existing tests catch it?' },
+    { title: 'Report', detail: 'Mutation score report with killed/survived/timeout breakdown' },
+  ],
+};
+
+export default async function run({ agent, parallel, pipeline, phase, log, args, budget }) {
+  const SOURCE_SCHEMA = {
+    type: 'object',
+    properties: {
+      sourceFiles: { type: 'array', items: { type: 'string' } },
+      testFiles: { type: 'array', items: { type: 'string' } },
+      mutableLines: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            file: { type: 'string' },
+            lineNumber: { type: 'number' },
+            code: { type: 'string' },
+            mutationType: { type: 'string', enum: ['condition', 'operator', 'return-value', 'boundary', 'negation', 'constant'] },
+          },
+          required: ['file', 'code', 'mutationType'],
+        },
+      },
+    },
+    required: ['sourceFiles', 'testFiles', 'mutableLines'],
+  };
+
+  const MUTATIONS_SCHEMA = {
+    type: 'object',
+    properties: {
+      mutations: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            id: { type: 'string' },
+            file: { type: 'string' },
+            original: { type: 'string' },
+            mutated: { type: 'string' },
+            mutationType: { type: 'string' },
+            description: { type: 'string' },
+          },
+          required: ['id', 'file', 'original', 'mutated', 'mutationType', 'description'],
+        },
+      },
+    },
+    required: ['mutations'],
+  };
+
+  const KILL_SCHEMA = {
+    type: 'object',
+    properties: {
+      mutationId: { type: 'string' },
+      status: { type: 'string', enum: ['killed', 'survived', 'timeout', 'equivalent'] },
+      killedBy: { type: 'string' },
+      reason: { type: 'string' },
+      suggestedTest: { type: 'string' },
+    },
+    required: ['mutationId', 'status', 'reason'],
+  };
+
+  const REPORT_SCHEMA = {
+    type: 'object',
+    properties: {
+      mutationScore: { type: 'number' },
+      summary: { type: 'string' },
+      killed: { type: 'number' },
+      survived: { type: 'number' },
+      timeout: { type: 'number' },
+      equivalent: { type: 'number' },
+      survivorDetails: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            mutation: { type: 'string' },
+            suggestedTest: { type: 'string' },
+          },
+          required: ['mutation', 'suggestedTest'],
+        },
+      },
+      topWeaknesses: { type: 'array', items: { type: 'string' } },
+    },
+    required: ['mutationScore', 'summary', 'killed', 'survived', 'topWeaknesses'],
+  };
+
+  const target = args || 'current codebase (run from repo root)';
+
+  phase('Analyze');
+  log(`Analyzing source for mutable lines in: ${target}`);
+  const sourceAnalysis = await agent(
+    `Analyze the source code in: "${target}" to identify mutable lines for mutation testing. Find: (1) conditional expressions (if/else, ternary, switch), (2) arithmetic/comparison operators (+, -, *, /, >, <, ==, !=), (3) return values in key functions, (4) boundary values (0, -1, +1, null checks), (5) boolean negations. Also identify source files and their test files. List the 15 most testable mutable lines.`,
+    { schema: SOURCE_SCHEMA, label: 'analyze' }
+  );
+  if (!sourceAnalysis) { return { target, error: 'sourceAnalysis-agent-null' }; }
+  log(`Found ${sourceAnalysis.mutableLines.length} mutable lines across ${sourceAnalysis.sourceFiles.length} source files`);
+
+  phase('Mutate');
+  const mutableContext = sourceAnalysis.mutableLines.slice(0, 15).map(l => `${l.file}:${l.lineNumber || '?'} [${l.mutationType}] \`${l.code}\``).join('\n');
+  const mutationSpec = await agent(
+    `Generate 10-15 specific mutations for testing the test suite quality of: "${target}"\n\nMutable lines:\n${mutableContext}\n\nFor each mutation: assign unique ID (M01, M02...), show original code, mutated code, mutation type, and plain-English description of what changed. Focus on mutations that SHOULD be caught by good tests — boundary off-by-ones, condition flips, operator swaps.`,
+    { schema: MUTATIONS_SCHEMA, label: 'mutate' }
+  );
+  if (!mutationSpec) { return { target, sourceAnalysis, error: 'mutationSpec-agent-null' }; }
+  log(`Generated ${mutationSpec.mutations.length} mutations`);
+
+  phase('Kill');
+  const killResults = await parallel(
+    mutationSpec.mutations.map(m => () => agent(
+      `Assess if the existing test suite in: "${target}" would CATCH this mutation.\n\nMutation ${m.id}: In file ${m.file}, changed \`${m.original}\` to \`${m.mutated}\`.\nDescription: ${m.description}\n\nLook at the test files. Would any existing test fail if this mutation were applied? Answer: killed (test would fail), survived (no test catches it), equivalent (mutation doesn't change behavior), or timeout (unclear). If survived, suggest a specific test that would kill it.`,
+      { schema: KILL_SCHEMA, label: `kill:${m.id}`, phase: 'Kill' }
+    ))
+  );
+
+  phase('Report');
+  const killData = killResults.filter(Boolean);
+  const killed = killData.filter(r => r.status === 'killed').length;
+  const survived = killData.filter(r => r.status === 'survived').length;
+  const timeout = killData.filter(r => r.status === 'timeout').length;
+  const equivalent = killData.filter(r => r.status === 'equivalent').length;
+  const total = killed + survived + timeout;
+  const mutationScore = total > 0 ? Math.round((killed / total) * 100) : 0;
+
+  log(`Mutation score: ${mutationScore}% (${killed} killed, ${survived} survived, ${timeout} timeout)`);
+
+  const survivorSummary = killData
+    .filter(r => r.status === 'survived')
+    .map(r => {
+      const mutation = mutationSpec.mutations.find(m => m.id === r.mutationId);
+      return `${r.mutationId}: ${mutation ? mutation.description : r.mutationId} — suggested test: ${r.suggestedTest || 'none'}`;
+    })
+    .join('\n');
+
+  const report = await agent(
+    `Write a mutation testing report for: "${target}"\n\nMutation score: ${mutationScore}% (${killed}/${total} killed)\nKilled: ${killed}, Survived: ${survived}, Timeout: ${timeout}, Equivalent: ${equivalent}\n\nSurvivors:\n${survivorSummary || 'none'}\n\nDescribe: overall test suite quality, top weaknesses in test coverage exposed by survivors, specific suggested tests to add, and interpretation of the mutation score.`,
+    { schema: REPORT_SCHEMA, label: 'report' }
+  );
+
+  return { target, sourceAnalysis, mutations: mutationSpec.mutations, killResults: killData, report };
+}