convoke-agents 3.1.0 → 3.2.0

package/_bmad/bme/_team-factory/lib/spec-differ.js

@@ -0,0 +1,176 @@
+'use strict';
+
+const fs = require('fs-extra');
+const yaml = require('js-yaml');
+
+/** @typedef {import('./types/factory-types').TeamSpec} TeamSpec */
+
+/**
+ * Step completion states.
+ * @type {Object<string, string>}
+ */
+const STEP_ORDER = ['orient', 'scope', 'connect', 'review', 'generate', 'validate'];
+
+/**
+ * Determine the resume point for a spec file by reading its progress section.
+ * Returns the first step that is not 'complete'.
+ *
+ * For the 'generate' step, also checks per-agent completion status
+ * and returns which agents still need generation.
+ *
+ * @param {string} specPath - Absolute path to the spec file
+ * @returns {Promise<ResumeResult>}
+ */
+async function findResumePoint(specPath) {
+  let raw;
+  try {
+    raw = await fs.readFile(specPath, 'utf8');
+  } catch (err) {
+    return { resumable: false, resumeStep: null, pendingAgents: [], errors: [`Cannot read spec file: ${err.message}`] };
+  }
+
+  let doc;
+  try {
+    doc = yaml.load(raw);
+  } catch (err) {
+    return { resumable: false, resumeStep: null, pendingAgents: [], errors: [`Invalid YAML: ${err.message}`] };
+  }
+
+  if (!doc || !doc.progress) {
+    return { resumable: false, resumeStep: null, pendingAgents: [], errors: ['Spec file has no progress section'] };
+  }
+
+  const progress = doc.progress;
+
+  // Find first non-complete step
+  for (const step of STEP_ORDER) {
+    const status = typeof progress[step] === 'string' ? progress[step] : null;
+
+    if (step === 'generate' && typeof progress[step] === 'object') {
+      // Generate step has per-agent tracking
+      const pending = [];
+      for (const [agentId, agentStatus] of Object.entries(progress[step])) {
+        if (agentStatus !== 'complete') {
+          pending.push(agentId);
+        }
+      }
+      if (pending.length > 0) {
+        return { resumable: true, resumeStep: 'generate', pendingAgents: pending, errors: [] };
+      }
+      // All agents complete — continue to next step
+      continue;
+    }
+
+    if (status !== 'complete') {
+      return { resumable: true, resumeStep: step, pendingAgents: [], errors: [] };
+    }
+  }
+
+  // All steps complete
+  return { resumable: false, resumeStep: null, pendingAgents: [], errors: [], allComplete: true };
+}
+
+/**
+ * Compare two spec objects and return which fields changed.
+ * Used for displaying diffs when resuming or in express mode.
+ *
+ * @param {TeamSpec} oldSpec - Previous spec state
+ * @param {TeamSpec} newSpec - Current spec state
+ * @returns {SpecDiff}
+ */
+function diffSpecs(oldSpec, newSpec) {
+  const changes = [];
+
+  // Compare top-level scalar fields
+  const scalarFields = ['team_name', 'team_name_kebab', 'description', 'composition_pattern', 'factory_version'];
+  for (const field of scalarFields) {
+    if (oldSpec[field] !== newSpec[field]) {
+      changes.push({ field, oldValue: oldSpec[field], newValue: newSpec[field] });
+    }
+  }
+
+  // Compare agent count
+  const oldAgentCount = (oldSpec.agents || []).length;
+  const newAgentCount = (newSpec.agents || []).length;
+  if (oldAgentCount !== newAgentCount) {
+    changes.push({ field: 'agents.length', oldValue: String(oldAgentCount), newValue: String(newAgentCount) });
+  }
+
+  // Compare agent IDs
+  const oldIds = (oldSpec.agents || []).map(a => a.id).sort();
+  const newIds = (newSpec.agents || []).map(a => a.id).sort();
+  const addedAgents = newIds.filter(id => !oldIds.includes(id));
+  const removedAgents = oldIds.filter(id => !newIds.includes(id));
+  if (addedAgents.length > 0) {
+    changes.push({ field: 'agents.added', oldValue: '', newValue: addedAgents.join(', ') });
+  }
+  if (removedAgents.length > 0) {
+    changes.push({ field: 'agents.removed', oldValue: removedAgents.join(', '), newValue: '' });
+  }
+
+  // Compare contract count (Sequential only)
+  const oldContracts = (oldSpec.contracts || []).length;
+  const newContracts = (newSpec.contracts || []).length;
+  if (oldContracts !== newContracts) {
+    changes.push({ field: 'contracts.length', oldValue: String(oldContracts), newValue: String(newContracts) });
+  }
+
+  // Compare progress
+  for (const step of STEP_ORDER) {
+    const oldStatus = typeof oldSpec.progress?.[step] === 'string' ? oldSpec.progress[step] : stableStringify(oldSpec.progress?.[step]);
+    const newStatus = typeof newSpec.progress?.[step] === 'string' ? newSpec.progress[step] : stableStringify(newSpec.progress?.[step]);
+    if (oldStatus !== newStatus) {
+      changes.push({ field: `progress.${step}`, oldValue: oldStatus || 'undefined', newValue: newStatus || 'undefined' });
+    }
+  }
+
+  return {
+    hasChanges: changes.length > 0,
+    changeCount: changes.length,
+    changes,
+  };
+}
+
+/**
+ * JSON.stringify with sorted keys for order-independent comparison.
+ * @param {*} obj
+ * @returns {string}
+ */
+function stableStringify(obj) {
+  if (obj === null || obj === undefined) return String(obj);
+  if (typeof obj !== 'object') return JSON.stringify(obj);
+  const sorted = Object.keys(obj).sort().reduce((acc, key) => {
+    acc[key] = obj[key];
+    return acc;
+  }, {});
+  return JSON.stringify(sorted);
+}
+
+/**
+ * @typedef {Object} ResumeResult
+ * @property {boolean} resumable - True if there's a step to resume from
+ * @property {string|null} resumeStep - The step to resume from
+ * @property {string[]} pendingAgents - For generate step: agents still pending
+ * @property {string[]} errors
+ * @property {boolean} [allComplete] - True if all steps are complete
+ */
+
+/**
+ * @typedef {Object} SpecDiff
+ * @property {boolean} hasChanges
+ * @property {number} changeCount
+ * @property {SpecChange[]} changes
+ */
+
+/**
+ * @typedef {Object} SpecChange
+ * @property {string} field - Dot-path to the changed field
+ * @property {string} oldValue
+ * @property {string} newValue
+ */
+
+module.exports = {
+  findResumePoint,
+  diffSpecs,
+  STEP_ORDER,
+};

package/_bmad/bme/_team-factory/lib/spec-parser.js

@@ -0,0 +1,201 @@
+'use strict';
+
+const fs = require('fs-extra');
+const path = require('path');
+const yaml = require('js-yaml');
+
+/** @typedef {import('./types/factory-types').TeamSpec} TeamSpec */
+
+const SCHEMAS_DIR = path.join(__dirname, '..', 'schemas');
+
+/**
+ * Load and validate a team spec YAML file.
+ * Selects schema by composition_pattern, validates required fields and naming.
+ *
+ * @param {string} specPath - Absolute path to team spec YAML file
+ * @returns {Promise<{ valid: boolean, spec: TeamSpec|null, errors: string[] }>}
+ */
+async function parseSpec(specPath) {
+  let raw;
+  try {
+    raw = await fs.readFile(specPath, 'utf8');
+  } catch (err) {
+    return { valid: false, spec: null, errors: [`Cannot read spec file: ${err.message}`] };
+  }
+
+  let doc;
+  try {
+    doc = yaml.load(raw);
+  } catch (err) {
+    return { valid: false, spec: null, errors: [`Invalid YAML: ${err.message}`] };
+  }
+
+  if (!doc || typeof doc !== 'object') {
+    return { valid: false, spec: null, errors: ['Spec file is empty or not an object'] };
+  }
+
+  // Determine pattern and load schema
+  const pattern = doc.composition_pattern;
+  if (!pattern) {
+    return { valid: false, spec: null, errors: ['Missing required field: composition_pattern'] };
+  }
+
+  const schemaFile = pattern === 'Sequential'
+    ? 'schema-sequential.json'
+    : pattern === 'Independent'
+      ? 'schema-independent.json'
+      : null;
+
+  if (!schemaFile) {
+    return { valid: false, spec: null, errors: [`Unknown composition_pattern: "${pattern}". Expected "Independent" or "Sequential"`] };
+  }
+
+  // Load schema for reference (structural validation below)
+  const schemaPath = path.join(SCHEMAS_DIR, schemaFile);
+  let schema;
+  try {
+    schema = JSON.parse(await fs.readFile(schemaPath, 'utf8'));
+  } catch (err) {
+    return { valid: false, spec: null, errors: [`Cannot load schema ${schemaFile}: ${err.message}`] };
+  }
+
+  // Validate against schema required fields and patterns
+  const errors = validateAgainstSchema(doc, schema, pattern);
+
+  if (errors.length > 0) {
+    return { valid: false, spec: null, errors };
+  }
+
+  return { valid: true, spec: doc, errors: [] };
+}
+
+/**
+ * Validate a parsed document against schema required fields, types, and patterns.
+ * Lightweight validation without ajv — checks required fields, naming patterns, and structural rules.
+ *
+ * @param {Object} doc - Parsed YAML document
+ * @param {Object} schema - JSON Schema object
+ * @param {string} pattern - "Independent" or "Sequential"
+ * @returns {string[]} errors
+ */
+function validateAgainstSchema(doc, schema, pattern) {
+  const errors = [];
+
+  // Check required root fields
+  const required = schema.required || [];
+  for (const field of required) {
+    if (doc[field] === undefined || doc[field] === null) {
+      errors.push(`Missing required field: ${field}`);
+    }
+  }
+
+  // Type checks on key fields
+  if (doc.schema_version !== undefined && typeof doc.schema_version !== 'string') {
+    errors.push(`schema_version must be a string, got ${typeof doc.schema_version}`);
+  } else if (doc.schema_version && !/^\d+\.\d+$/.test(doc.schema_version)) {
+    errors.push(`schema_version "${doc.schema_version}" does not match pattern "N.N" (e.g., "1.0")`);
+  }
+
+  if (doc.composition_pattern !== undefined && doc.composition_pattern !== pattern) {
+    errors.push(`composition_pattern "${doc.composition_pattern}" does not match expected "${pattern}"`);
+  }
+
+  if (doc.team_name !== undefined && (typeof doc.team_name !== 'string' || doc.team_name.length === 0)) {
+    errors.push('team_name must be a non-empty string');
+  }
+
+  // Validate naming patterns
+  const KEBAB_RE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+  const AGENT_ID_RE = /^[a-z]+(-[a-z]+)*$/;
+
+  if (doc.team_name_kebab && !KEBAB_RE.test(doc.team_name_kebab)) {
+    errors.push(`team_name_kebab "${doc.team_name_kebab}" does not match kebab-case pattern: ${KEBAB_RE}`);
+  }
+
+  // Validate agents array
+  if (Array.isArray(doc.agents)) {
+    if (doc.agents.length === 0) {
+      errors.push('agents array must contain at least one agent');
+    }
+    for (let i = 0; i < doc.agents.length; i++) {
+      const agent = doc.agents[i];
+      if (!agent.id) {
+        errors.push(`agents[${i}]: missing required field "id"`);
+      } else if (!AGENT_ID_RE.test(agent.id)) {
+        errors.push(`agents[${i}].id "${agent.id}" does not match agent ID pattern: ${AGENT_ID_RE}`);
+      }
+      if (!agent.role) {
+        errors.push(`agents[${i}]: missing required field "role"`);
+      }
+
+      // Sequential-specific: pipeline_position required
+      if (pattern === 'Sequential' && agent.pipeline_position === undefined) {
+        errors.push(`agents[${i}]: Sequential pattern requires pipeline_position`);
+      }
+    }
+
+    // Check for duplicate agent IDs
+    const ids = doc.agents.map(a => a.id).filter(Boolean);
+    const dupes = ids.filter((id, i) => ids.indexOf(id) !== i);
+    if (dupes.length > 0) {
+      errors.push(`Duplicate agent IDs: ${[...new Set(dupes)].join(', ')}`);
+    }
+  } else if (required.includes('agents')) {
+    errors.push('agents must be an array');
+  }
+
+  // Sequential-specific validations
+  if (pattern === 'Sequential') {
+    if (!Array.isArray(doc.contracts) || doc.contracts.length === 0) {
+      errors.push('Sequential pattern requires at least one contract');
+    } else {
+      for (let i = 0; i < doc.contracts.length; i++) {
+        const c = doc.contracts[i];
+        if (!c.id) errors.push(`contracts[${i}]: missing required field "id"`);
+        if (!c.source_agent) errors.push(`contracts[${i}]: missing required field "source_agent"`);
+        if (!Array.isArray(c.target_agents) || c.target_agents.length === 0) {
+          errors.push(`contracts[${i}]: target_agents must be a non-empty array`);
+        }
+      }
+    }
+
+    if (!doc.integration?.contract_prefix) {
+      errors.push('Sequential pattern requires integration.contract_prefix');
+    }
+  }
+
+  // Validate integration block
+  if (doc.integration) {
+    if (typeof doc.integration !== 'object' || Array.isArray(doc.integration)) {
+      errors.push('integration must be an object');
+    } else if (!doc.integration.output_directory) {
+      errors.push('integration.output_directory is required');
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * Parse a spec from a YAML string (for testing or in-memory use).
+ * Pattern is determined from the document's composition_pattern field.
+ *
+ * @param {string} yamlString - Raw YAML content
+ * @returns {Promise<{ valid: boolean, spec: TeamSpec|null, errors: string[] }>}
+ */
+async function parseSpecFromString(yamlString) {
+  const tmpDir = await fs.mkdtemp(path.join(require('os').tmpdir(), 'bmad-tf-parse-'));
+  const tmpFile = path.join(tmpDir, 'spec.yaml');
+  try {
+    await fs.writeFile(tmpFile, yamlString, 'utf8');
+    return await parseSpec(tmpFile);
+  } finally {
+    await fs.remove(tmpDir);
+  }
+}
+
+module.exports = {
+  parseSpec,
+  parseSpecFromString,
+  validateAgainstSchema,
+};

package/_bmad/bme/_team-factory/lib/spec-writer.js

@@ -0,0 +1,128 @@
+'use strict';
+
+const fs = require('fs-extra');
+const path = require('path');
+const yaml = require('js-yaml');
+
+/** @typedef {import('./types/factory-types').TeamSpec} TeamSpec */
+
+/**
+ * Write a team spec to a YAML file with atomic write safety.
+ * Protocol: write to .tmp → validate parse → rename to target.
+ *
+ * @param {TeamSpec} spec - The team spec object to write
+ * @param {string} targetPath - Absolute path to the output YAML file
+ * @returns {Promise<{ success: boolean, errors: string[] }>}
+ */
+async function writeSpec(spec, targetPath) {
+  if (!spec || typeof spec !== 'object') {
+    return { success: false, errors: ['spec must be a non-null object'] };
+  }
+  if (!targetPath || !path.isAbsolute(targetPath)) {
+    return { success: false, errors: ['targetPath must be an absolute path'] };
+  }
+
+  // Serialize to YAML
+  let yamlContent;
+  try {
+    yamlContent = yaml.dump(spec, {
+      indent: 2,
+      lineWidth: 120,
+      noRefs: true,
+      sortKeys: false,
+      quotingType: '"',
+    });
+  } catch (err) {
+    return { success: false, errors: [`YAML serialization failed: ${err.message}`] };
+  }
+
+  // Atomic write: .tmp → validate → rename
+  const tmpPath = targetPath + '.tmp';
+
+  try {
+    await fs.ensureDir(path.dirname(targetPath));
+    await fs.writeFile(tmpPath, yamlContent, 'utf8');
+  } catch (err) {
+    return { success: false, errors: [`Failed to write temp file: ${err.message}`] };
+  }
+
+  // Validate: re-read and parse to confirm round-trip integrity
+  try {
+    const reRead = await fs.readFile(tmpPath, 'utf8');
+    const parsed = yaml.load(reRead);
+    if (!parsed || typeof parsed !== 'object') {
+      await fs.remove(tmpPath);
+      return { success: false, errors: ['Round-trip validation failed: parsed result is empty or not an object'] };
+    }
+    // Verify key fields survived serialization
+    const checks = [
+      ['team_name_kebab', parsed.team_name_kebab, spec.team_name_kebab],
+      ['composition_pattern', parsed.composition_pattern, spec.composition_pattern],
+      ['agents.length', (parsed.agents || []).length, (spec.agents || []).length],
+    ];
+    for (const [field, actual, expected] of checks) {
+      if (actual !== expected) {
+        await fs.remove(tmpPath);
+        return { success: false, errors: [`Round-trip validation failed: ${field} mismatch ("${actual}" vs "${expected}")`] };
+      }
+    }
+  } catch (err) {
+    await fs.remove(tmpPath).catch(() => {});
+    return { success: false, errors: [`Round-trip validation failed: ${err.message}`] };
+  }
+
+  // Rename .tmp → target
+  try {
+    await fs.rename(tmpPath, targetPath);
+  } catch (err) {
+    await fs.remove(tmpPath).catch(() => {});
+    return { success: false, errors: [`Failed to rename temp file to target: ${err.message}`] };
+  }
+
+  return { success: true, errors: [] };
+}
+
+/**
+ * Update specific fields in an existing spec file.
+ * Loads current spec, merges updates, writes back atomically.
+ *
+ * @param {string} specPath - Absolute path to existing spec file
+ * @param {Object} updates - Fields to update (shallow merge at top level, deep merge for nested objects)
+ * @returns {Promise<{ success: boolean, errors: string[] }>}
+ */
+async function updateSpec(specPath, updates) {
+  let raw;
+  try {
+    raw = await fs.readFile(specPath, 'utf8');
+  } catch (err) {
+    return { success: false, errors: [`Cannot read spec file: ${err.message}`] };
+  }
+
+  let current;
+  try {
+    current = yaml.load(raw);
+  } catch (err) {
+    return { success: false, errors: [`Invalid YAML in existing spec: ${err.message}`] };
+  }
+
+  // Shallow merge with deep merge for known nested objects
+  const merged = { ...current };
+  for (const [key, value] of Object.entries(updates)) {
+    if (key === 'progress' && typeof value === 'object' && typeof merged.progress === 'object') {
+      merged.progress = { ...merged.progress, ...value };
+    } else if (key === 'integration' && typeof value === 'object' && typeof merged.integration === 'object') {
+      merged.integration = { ...merged.integration, ...value };
+    } else if (key === 'metrics' && typeof value === 'object' && typeof merged.metrics === 'object') {
+      merged.metrics = { ...merged.metrics, ...value };
+    } else {
+      merged[key] = value;
+    }
+  }
+
+  return writeSpec(merged, specPath);
+}
+
+module.exports = {
+  writeSpec,
+  updateSpec,
+};

package/_bmad/bme/_team-factory/lib/types/factory-types.js

@@ -0,0 +1,193 @@
+'use strict';
+
+/**
+ * JSDoc type definitions for Team Factory integration wiring modules.
+ * Canonical source for all factory shapes — no runtime code.
+ */
+
+/**
+ * Parsed team spec file shape.
+ * @typedef {Object} TeamSpec
+ * @property {string} schema_version
+ * @property {string} team_name
+ * @property {string} team_name_kebab
+ * @property {string} [description] - Optional team description for config.yaml
+ * @property {string} composition_pattern - "Sequential" or "Independent"
+ * @property {string} created - ISO date string
+ * @property {string} factory_version
+ * @property {AgentSpec[]} agents
+ * @property {ContractSpec[]} contracts
+ * @property {ContractSpec[]} feedback_contracts
+ * @property {IntegrationSpec} integration
+ * @property {Object} progress
+ */
+
+/**
+ * Agent specification from spec file.
+ * @typedef {Object} AgentSpec
+ * @property {string} id
+ * @property {string} role
+ * @property {string[]} capabilities
+ * @property {number} [pipeline_position] - Sequential only
+ * @property {string[]} overlap_acknowledgments
+ */
+
+/**
+ * Contract specification from spec file.
+ * @typedef {Object} ContractSpec
+ * @property {string} id
+ * @property {string} source_agent
+ * @property {string[]} target_agents
+ * @property {string} artifact_title
+ * @property {string} artifact_description
+ * @property {string[]} key_sections
+ * @property {string} file_name
+ * @property {string[]} input_artifacts
+ * @property {boolean} optional
+ */
+
+/**
+ * Integration decisions from spec file.
+ * @typedef {Object} IntegrationSpec
+ * @property {string} output_directory
+ * @property {string} compass_routing - "optional", "per-agent", "required", or "shared-reference"
+ * @property {string} [contract_prefix]
+ */
+
+/**
+ * Config.yaml data shape (matches Gyre/Vortex schema).
+ * @typedef {Object} ConfigData
+ * @property {string} submodule_name
+ * @property {string} description
+ * @property {string} module
+ * @property {string} output_folder
+ * @property {string[]} agents
+ * @property {string[]} workflows
+ * @property {string} version
+ * @property {string} user_name
+ * @property {string} communication_language
+ * @property {boolean} party_mode_enabled
+ * @property {string} core_module
+ */
+
+/**
+ * Module-help.csv row shape.
+ * @typedef {Object} CsvRow
+ * @property {string} module
+ * @property {string} phase
+ * @property {string} name
+ * @property {string} code
+ * @property {number} sequence
+ * @property {string} workflow_file
+ * @property {string} command
+ * @property {string} required
+ * @property {string} agent
+ * @property {string} options
+ * @property {string} description
+ * @property {string} output_location
+ * @property {string} outputs
+ */
+
+/**
+ * Activation validation result per agent.
+ * @typedef {Object} ActivationResult
+ * @property {string} agentFile
+ * @property {ActivationCheck[]} checks
+ * @property {string[]} errors
+ */
+
+/**
+ * Individual activation check.
+ * @typedef {Object} ActivationCheck
+ * @property {string} check - Description of what was checked
+ * @property {boolean} passed
+ * @property {string} [detail] - Additional info if failed
+ */
+
+/**
+ * Collision detection result.
+ * @typedef {Object} Collision
+ * @property {string} field - "submodule_name", "agent", or "workflow"
+ * @property {string} value - The colliding value
+ * @property {string} existingModule - Module that already has this value
+ */
+
+/**
+ * Creator result shape (shared by config-creator and csv-creator).
+ * @typedef {Object} CreatorResult
+ * @property {boolean} success
+ * @property {string} [filePath]
+ * @property {string[]} errors
+ * @property {number} [rowCount] - csv-creator only
+ * @property {Collision[]} [collisions] - config-creator only
+ */
+
+/**
+ * Activation validator result shape.
+ * @typedef {Object} ValidationResult
+ * @property {boolean} valid
+ * @property {ActivationResult[]} results
+ */
+
+/**
+ * Registry writer result shape (Full Write Safety Protocol).
+ * Differs from CreatorResult intentionally — writers return written[]/skipped[] per architecture rule 2.
+ * @typedef {Object} RegistryResult
+ * @property {boolean} success
+ * @property {string[]} written - Const names added to module.exports
+ * @property {string[]} skipped - Reasons for skipping (e.g., 'block already exists')
+ * @property {string[]} errors
+ * @property {boolean} rollbackApplied - True if .bak was restored after verify failure
+ * @property {boolean} [dirty] - True if dirty-tree detection found uncommitted changes
+ * @property {string} [diff] - Git diff output when dirty
+ */
+
+/**
+ * Agent entry in agent-registry.js.
+ * @typedef {Object} RegistryAgentEntry
+ * @property {string} id
+ * @property {string} name - Display name (first name or derived)
+ * @property {string} icon - Unicode emoji character
+ * @property {string} title - Role-based title
+ * @property {string} stream - Team name kebab
+ * @property {RegistryPersona} persona
+ */
+
+/**
+ * Persona sub-object within a registry agent entry.
+ * @typedef {Object} RegistryPersona
+ * @property {string} role
+ * @property {string} identity
+ * @property {string} communication_style
+ * @property {string} expertise
+ */
+
+/**
+ * File manifest entry tracking a created or modified file.
+ * @typedef {Object} ManifestEntry
+ * @property {string} path - File path (relative to project root)
+ * @property {'created' | 'modified'} operation - Whether the file was created or modified
+ * @property {string} module - Team name kebab identifying the owning module
+ */
+
+/**
+ * End-to-end validation result.
+ * @typedef {Object} E2EValidationResult
+ * @property {boolean} valid - True if all checks passed
+ * @property {E2ECheck[]} checks - Individual check results
+ * @property {string[]} errors - Human-readable error messages for failed checks
+ */
+
+/**
+ * Individual end-to-end validation check.
+ * Name uses {PROP}-{SEMANTIC-NAME} format per architecture (line 590).
+ * @typedef {Object} E2ECheck
+ * @property {string} name - Check ID in {PROP}-{SEMANTIC-NAME} format (e.g., CONFIG-EXISTS)
+ * @property {string} stepName - Step that produced the check (e.g., 'structural', 'regression', 'wiring')
+ * @property {boolean} passed - Whether the check passed
+ * @property {string} [expected] - Expected value (included on failure per TF-NFR11)
+ * @property {string} [actual] - Actual value found (included on failure per TF-NFR11)
+ * @property {string} [detail] - Additional context (e.g., file path)
+ */
+
+module.exports = {};