@colin4k1024/tsp 2.5.2 → 2.5.4

package/scripts/lib/heartbeat-scheduler.js

@@ -14,9 +14,11 @@
 const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
-const yaml = require ? undefined : undefined; // yaml parsing fallback below
+const yaml = require('js-yaml');
 
 const { createGoal, saveGoal } = require('./completion-oracle');
+const loopStateStore = require('./loop-state-store');
+const { parseLoopSpecContent } = require('./loop-spec');
 
 const DEFAULT_CONFIG = {
   interval: '30m',
@@ -75,12 +77,40 @@ function parseSimpleYaml(content) {
 }
 
 function loadConfig(projectRoot) {
-  const configPath = path.join(projectRoot || process.cwd(), '.claude', 'heartbeat.yaml');
-  if (!fs.existsSync(configPath)) return DEFAULT_CONFIG;
+  const root = projectRoot || process.cwd();
+  const loopSpecPath = path.join(root, '.tsp', 'loop.yaml');
+  if (fs.existsSync(loopSpecPath)) {
+    try {
+      const loopSpec = parseLoopSpecContent(fs.readFileSync(loopSpecPath, 'utf-8'), loopSpecPath);
+      return {
+        ...DEFAULT_CONFIG,
+        interval: loopSpec.cadence,
+        scans: loopSpec.gates.map(gate => ({
+          name: gate.name,
+          command: `${gate.command} 2>&1; echo EXIT:$?`,
+          onFailure: SCAN_ACTIONS.autoGoal,
+          description: gate.description || gate.name,
+        })),
+        budget: {
+          ...DEFAULT_CONFIG.budget,
+          maxDollarsPerHour: loopSpec.budget.maxDollars,
+        },
+      };
+    } catch {
+      return DEFAULT_CONFIG;
+    }
+  }
+
+  const configPath = [
+    path.join(root, '.tsp', 'heartbeat.yaml'),
+    path.join(root, '.claude', 'heartbeat.yaml'),
+  ].find(candidate => fs.existsSync(candidate));
+
+  if (!configPath) return DEFAULT_CONFIG;
 
   try {
     const content = fs.readFileSync(configPath, 'utf-8');
-    const parsed = parseSimpleYaml(content);
+    const parsed = yaml.load(content, { schema: yaml.JSON_SCHEMA }) || parseSimpleYaml(content);
     return { ...DEFAULT_CONFIG, ...parsed.heartbeat };
   } catch {
     return DEFAULT_CONFIG;
@@ -147,14 +177,7 @@ function createTriageItem(scan, result) {
 }
 
 function appendToTriageInbox(item) {
-  const home = process.env.HOME || process.env.USERPROFILE || '';
-  const inboxDir = path.join(home, '.claude', 'triage');
-  if (!fs.existsSync(inboxDir)) {
-    fs.mkdirSync(inboxDir, { recursive: true });
-  }
-  const inboxPath = path.join(inboxDir, 'inbox.jsonl');
-  fs.appendFileSync(inboxPath, JSON.stringify(item) + '\n', 'utf-8');
-  return inboxPath;
+  return loopStateStore.appendTriageItem(item);
 }
 
 function createGoalFromScanFailure(scan, result) {
@@ -181,7 +204,7 @@ function runHeartbeat(projectRoot) {
   if (config.scans.length === 0) {
     return {
       status: 'no_scans',
-      message: 'No scans configured in .claude/heartbeat.yaml',
+      message: 'No scans configured in .tsp/loop.yaml, .tsp/heartbeat.yaml, or .claude/heartbeat.yaml',
       results: [],
     };
   }
@@ -216,14 +239,10 @@ function runHeartbeat(projectRoot) {
 function getHeartbeatStatus(projectRoot) {
   const config = loadConfig(projectRoot);
 
-  const home = process.env.HOME || process.env.USERPROFILE || '';
-  const lastRunPath = path.join(home, '.claude', 'heartbeat-last-run.json');
   let lastRun = null;
-  if (fs.existsSync(lastRunPath)) {
-    try {
-      lastRun = JSON.parse(fs.readFileSync(lastRunPath, 'utf-8'));
-    } catch { /* ignore */ }
-  }
+  try {
+    lastRun = loopStateStore.loadHeartbeat('last-run');
+  } catch { /* ignore */ }
 
   return {
     configured: config.scans.length > 0,
@@ -236,11 +255,7 @@ function getHeartbeatStatus(projectRoot) {
 }
 
 function saveLastRun(result) {
-  const home = process.env.HOME || process.env.USERPROFILE || '';
-  const lastRunPath = path.join(home, '.claude', 'heartbeat-last-run.json');
-  const dir = path.dirname(lastRunPath);
-  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
-  fs.writeFileSync(lastRunPath, JSON.stringify(result, null, 2), 'utf-8');
+  return loopStateStore.saveHeartbeat('last-run', result);
 }
 
 function parseInterval(interval) {

package/scripts/lib/install/request.js

@@ -3,7 +3,7 @@
 const { validateInstallModuleIds } = require('../install-manifests');
 const { normalizeInstallTarget } = require('../install-targets/registry');
 
-const LEGACY_INSTALL_TARGETS = ['claude', 'cursor', 'antigravity', 'codex', 'opencode'];
+const LEGACY_INSTALL_TARGETS = ['claude', 'cursor', 'antigravity', 'codex', 'opencode', 'cangming'];
 
 function dedupeStrings(values) {
   return [...new Set((Array.isArray(values) ? values : []).map(value => String(value).trim()).filter(Boolean))];

package/scripts/lib/install-manifests.js

@@ -8,7 +8,7 @@ const {
 } = require('./install-targets/registry');
 
 const DEFAULT_REPO_ROOT = path.join(__dirname, '../..');
-const SUPPORTED_INSTALL_TARGETS = ['claude', 'cursor', 'antigravity', 'codex', 'gemini', 'opencode', 'codebuddy', 'copilot', 'windsurf', 'augment'];
+const SUPPORTED_INSTALL_TARGETS = ['claude', 'cursor', 'antigravity', 'codex', 'gemini', 'opencode', 'cangming', 'codewhale', 'codebuddy', 'copilot', 'windsurf', 'augment'];
 const COMPONENT_FAMILY_PREFIXES = {
   baseline: 'baseline:',
   language: 'lang:',
@@ -54,6 +54,14 @@ const LEGACY_COMPAT_BASE_MODULE_IDS_BY_TARGET = Object.freeze({
     'platform-configs',
     'workflow-quality',
   ],
+  codewhale: [
+    'rules-core',
+    'agents-core',
+    'commands-core',
+    'hooks-runtime',
+    'platform-configs',
+    'workflow-quality',
+  ],
 });
 const LEGACY_LANGUAGE_ALIAS_TO_CANONICAL = Object.freeze({
   cpp: 'cpp',

package/scripts/lib/install-targets/cangming-home.js

@@ -0,0 +1,143 @@
+const fs = require('fs');
+const path = require('path');
+
+const {
+  createInstallTargetAdapter,
+  createManagedOperation,
+  normalizeRelativePath,
+} = require('./helpers');
+
+const PLUGIN_NAME = require('../team-skills-data.json').plugin.name;
+
+function addOperation(operations, seen, operation) {
+  const key = `${operation.sourceRelativePath}=>${operation.destinationPath}`;
+  if (seen.has(key)) {
+    return;
+  }
+  seen.add(key);
+  operations.push(operation);
+}
+
+function addCopyOperation(operations, seen, moduleId, sourceRelativePath, destinationPath, strategy = 'preserve-relative-path') {
+  addOperation(operations, seen, createManagedOperation({
+    moduleId,
+    sourceRelativePath,
+    destinationPath,
+    strategy,
+  }));
+}
+
+function sourceDir(input, sourceRelativePath) {
+  return path.join(input.repoRoot || '', normalizeRelativePath(sourceRelativePath));
+}
+
+function rootAgentFileName(sourcePath, fileName) {
+  const normalizedSourcePath = normalizeRelativePath(sourcePath);
+  if (normalizedSourcePath === 'agents/specialists' || normalizedSourcePath.startsWith('agents/specialists/')) {
+    return `specialist-${fileName}`;
+  }
+  return fileName;
+}
+
+function addRootAgentOperations(operations, seen, moduleId, sourceRelativePath, input, targetRoot) {
+  const normalizedSourcePath = normalizeRelativePath(sourceRelativePath);
+  if (normalizedSourcePath !== 'agents' && !normalizedSourcePath.startsWith('agents/')) {
+    return;
+  }
+
+  const agentDirs = normalizedSourcePath === 'agents'
+    ? ['roles', 'specialists']
+    : [''];
+
+  for (const agentDir of agentDirs) {
+    const sourcePath = agentDir ? path.join(normalizedSourcePath, agentDir) : normalizedSourcePath;
+    const absoluteSourceDir = sourceDir(input, sourcePath);
+    if (!input.repoRoot || !fs.existsSync(absoluteSourceDir)) {
+      continue;
+    }
+
+    const stat = fs.statSync(absoluteSourceDir);
+    if (stat.isFile() && path.extname(absoluteSourceDir) === '.md') {
+      const fileName = rootAgentFileName(path.dirname(sourcePath), path.basename(sourcePath));
+      addCopyOperation(
+        operations,
+        seen,
+        moduleId,
+        sourcePath,
+        path.join(targetRoot, 'agents', fileName),
+        'flatten-agent-copy'
+      );
+      continue;
+    }
+
+    if (!stat.isDirectory()) {
+      continue;
+    }
+
+    for (const entry of fs.readdirSync(absoluteSourceDir, { withFileTypes: true }).sort((left, right) => (
+      left.name.localeCompare(right.name)
+    ))) {
+      if (entry.isFile() && entry.name.endsWith('.md')) {
+        const fileName = rootAgentFileName(sourcePath, entry.name);
+        addCopyOperation(
+          operations,
+          seen,
+          moduleId,
+          path.join(sourcePath, entry.name),
+          path.join(targetRoot, 'agents', fileName),
+          'flatten-agent-copy'
+        );
+      }
+    }
+  }
+}
+
+function planCangmingOperations(input, adapter) {
+  const targetRoot = adapter.resolveRoot(input);
+  const pluginRoot = path.join(targetRoot, 'plugins', PLUGIN_NAME);
+  const operations = [];
+  const seen = new Set();
+
+  for (const module of Array.isArray(input.modules) ? input.modules : []) {
+    for (const rawSourcePath of Array.isArray(module.paths) ? module.paths : []) {
+      const sourceRelativePath = normalizeRelativePath(rawSourcePath);
+
+      addCopyOperation(
+        operations,
+        seen,
+        module.id,
+        sourceRelativePath,
+        path.join(pluginRoot, sourceRelativePath),
+        'plugin-copy'
+      );
+
+      if (sourceRelativePath === 'commands' || sourceRelativePath.startsWith('commands/')) {
+        const commandSuffix = sourceRelativePath === 'commands'
+          ? ''
+          : sourceRelativePath.slice('commands/'.length);
+        addCopyOperation(
+          operations,
+          seen,
+          module.id,
+          sourceRelativePath,
+          path.join(targetRoot, 'command', commandSuffix),
+          'opencode-command-copy'
+        );
+      }
+
+      addRootAgentOperations(operations, seen, module.id, sourceRelativePath, input, targetRoot);
+    }
+  }
+
+  return operations;
+}
+
+module.exports = createInstallTargetAdapter({
+  id: 'cangming-home',
+  target: 'cangming',
+  kind: 'home',
+  rootSegments: ['.config', 'cangming'],
+  installStatePathSegments: ['ecc-install-state.json'],
+  nativeRootRelativePath: '.cangming',
+  planOperations: planCangmingOperations,
+});

package/scripts/lib/install-targets/codewhale-home.js

@@ -0,0 +1,187 @@
+const fs = require('fs');
+const path = require('path');
+
+const {
+  createInstallTargetAdapter,
+  createManagedOperation,
+  normalizeRelativePath,
+} = require('./helpers');
+
+const PLUGIN_NAME = require('../team-skills-data.json').plugin.name;
+
+function addOperation(operations, seen, operation) {
+  const key = `${operation.sourceRelativePath}=>${operation.destinationPath}`;
+  if (seen.has(key)) {
+    return;
+  }
+  seen.add(key);
+  operations.push(operation);
+}
+
+function addCopyOperation(operations, seen, moduleId, sourceRelativePath, destinationPath, strategy = 'preserve-relative-path') {
+  addOperation(operations, seen, createManagedOperation({
+    moduleId,
+    sourceRelativePath,
+    destinationPath,
+    strategy,
+  }));
+}
+
+function sourceDir(input, sourceRelativePath) {
+  return path.join(input.repoRoot || '', normalizeRelativePath(sourceRelativePath));
+}
+
+function addAgentOperations(operations, seen, moduleId, sourceRelativePath, input, targetRoot) {
+  const normalizedSourcePath = normalizeRelativePath(sourceRelativePath);
+  if (normalizedSourcePath !== 'agents' && !normalizedSourcePath.startsWith('agents/')) {
+    return;
+  }
+
+  const agentDirs = normalizedSourcePath === 'agents'
+    ? ['roles', 'specialists']
+    : [''];
+
+  for (const agentDir of agentDirs) {
+    const sourcePath = agentDir ? path.join(normalizedSourcePath, agentDir) : normalizedSourcePath;
+    const absoluteSourceDir = sourceDir(input, sourcePath);
+    if (!input.repoRoot || !fs.existsSync(absoluteSourceDir)) {
+      continue;
+    }
+
+    const stat = fs.statSync(absoluteSourceDir);
+    if (stat.isFile() && path.extname(absoluteSourceDir) === '.md') {
+      const fileName = path.basename(sourcePath);
+      addCopyOperation(
+        operations, seen, moduleId, sourcePath,
+        path.join(targetRoot, 'agents', fileName),
+        'flatten-agent-copy'
+      );
+      continue;
+    }
+
+    if (!stat.isDirectory()) {
+      continue;
+    }
+
+    for (const entry of fs.readdirSync(absoluteSourceDir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      if (entry.isFile() && entry.name.endsWith('.md')) {
+        const prefix = agentDir === 'specialists' ? 'specialist-' : '';
+        addCopyOperation(
+          operations, seen, moduleId,
+          path.join(sourcePath, entry.name),
+          path.join(targetRoot, 'agents', `${prefix}${entry.name}`),
+          'flatten-agent-copy'
+        );
+      }
+    }
+  }
+}
+
+function addRuleOperations(operations, seen, moduleId, sourceRelativePath, input, targetRoot) {
+  const normalizedSourcePath = normalizeRelativePath(sourceRelativePath);
+  if (normalizedSourcePath !== 'rules' && !normalizedSourcePath.startsWith('rules/')) {
+    return;
+  }
+
+  const absoluteSourceDir = sourceDir(input, normalizedSourcePath);
+  if (!input.repoRoot || !fs.existsSync(absoluteSourceDir) || !fs.statSync(absoluteSourceDir).isDirectory()) {
+    return;
+  }
+
+  const entries = fs.readdirSync(absoluteSourceDir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+  for (const entry of entries) {
+    const entryPath = path.join(absoluteSourceDir, entry.name);
+    if (entry.isDirectory()) {
+      const subEntries = fs.readdirSync(entryPath, { withFileTypes: true });
+      for (const sub of subEntries) {
+        if (sub.isFile() && sub.name.endsWith('.md')) {
+          addCopyOperation(
+            operations, seen, moduleId,
+            path.join(normalizedSourcePath, entry.name, sub.name),
+            path.join(targetRoot, 'rules', entry.name, sub.name),
+            'rule-copy'
+          );
+        }
+      }
+    } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      addCopyOperation(
+        operations, seen, moduleId,
+        path.join(normalizedSourcePath, entry.name),
+        path.join(targetRoot, 'rules', entry.name),
+        'rule-copy'
+      );
+    }
+  }
+}
+
+function planCodeWhaleOperations(input, adapter) {
+  const targetRoot = adapter.resolveRoot(input);
+  const operations = [];
+  const seen = new Set();
+
+  for (const module of Array.isArray(input.modules) ? input.modules : []) {
+    for (const rawSourcePath of Array.isArray(module.paths) ? module.paths : []) {
+      const sourceRelativePath = normalizeRelativePath(rawSourcePath);
+
+      // Skills: preserve directory structure
+      if (sourceRelativePath === 'skills' || sourceRelativePath.startsWith('skills/')) {
+        addCopyOperation(
+          operations, seen, module.id, sourceRelativePath,
+          path.join(targetRoot, 'skills', sourceRelativePath.replace(/^skills\/?/, '')),
+          'skill-copy'
+        );
+      }
+
+      // Commands: flatten to commands/
+      if (sourceRelativePath === 'commands' || sourceRelativePath.startsWith('commands/')) {
+        const commandSuffix = sourceRelativePath === 'commands'
+          ? ''
+          : sourceRelativePath.slice('commands/'.length);
+        addCopyOperation(
+          operations, seen, module.id, sourceRelativePath,
+          path.join(targetRoot, 'commands', commandSuffix),
+          'command-copy'
+        );
+      }
+
+      // Agents: flatten roles + specialists
+      addAgentOperations(operations, seen, module.id, sourceRelativePath, input, targetRoot);
+
+      // Rules: preserve namespace/file structure
+      addRuleOperations(operations, seen, module.id, sourceRelativePath, input, targetRoot);
+
+      // Contexts: direct copy
+      if (sourceRelativePath === 'contexts' || sourceRelativePath.startsWith('contexts/')) {
+        const contextSuffix = sourceRelativePath === 'contexts'
+          ? ''
+          : sourceRelativePath.slice('contexts/'.length);
+        addCopyOperation(
+          operations, seen, module.id, sourceRelativePath,
+          path.join(targetRoot, 'contexts', contextSuffix),
+          'context-copy'
+        );
+      }
+
+      // Hooks: copy hooks directory for reference, config.toml injection handled by post-install
+      if (sourceRelativePath === 'hooks' || sourceRelativePath.startsWith('hooks/')) {
+        addCopyOperation(
+          operations, seen, module.id, sourceRelativePath,
+          path.join(targetRoot, 'hooks', sourceRelativePath.replace(/^hooks\/?/, '')),
+          'hook-copy'
+        );
+      }
+    }
+  }
+
+  return operations;
+}
+
+module.exports = createInstallTargetAdapter({
+  id: 'codewhale-home',
+  target: 'codewhale',
+  kind: 'home',
+  rootSegments: ['.codewhale'],
+  installStatePathSegments: ['ecc-install-state.json'],
+  nativeRootRelativePath: '.codewhale',
+  planOperations: planCodeWhaleOperations,
+});

package/scripts/lib/install-targets/registry.js

@@ -1,8 +1,10 @@
 const antigravityProject = require('./antigravity-project');
 const augmentProject = require('./augment-project');
+const cangmingHome = require('./cangming-home');
 const claudeHome = require('./claude-home');
 const codebuddyProject = require('./codebuddy-project');
 const codexHome = require('./codex-home');
+const codewhaleHome = require('./codewhale-home');
 const copilotHome = require('./copilot-home');
 const cursorProject = require('./cursor-project');
 const geminiProject = require('./gemini-project');
@@ -22,6 +24,8 @@ const ADAPTERS = Object.freeze([
   codexHome,
   geminiProject,
   opencodeHome,
+  cangmingHome,
+  codewhaleHome,
   codebuddyProject,
   copilotHome,
   windsurfProject,

package/scripts/lib/loop-oracle.js

@@ -0,0 +1,5 @@
+'use strict';
+
+// Compatibility layer for the loop-engineering runtime. The existing goal
+// oracle remains the implementation while callers migrate to loop naming.
+module.exports = require('./completion-oracle');

package/scripts/lib/loop-spec.js

@@ -0,0 +1,168 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+
+class LoopSpecError extends Error {
+  constructor(message, details = {}) {
+    super(message);
+    this.name = 'LoopSpecError';
+    this.details = details;
+    this.code = details.code || 'loop_spec_error';
+  }
+}
+
+function ensureObject(value, label, filePath) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new LoopSpecError(`${label} must be an object`, {
+      filePath,
+      code: 'invalid_payload',
+    });
+  }
+}
+
+function ensureNonEmptyString(value, label, filePath) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new LoopSpecError(`${label} must be a non-empty string`, {
+      filePath,
+      code: 'invalid_field',
+    });
+  }
+}
+
+function ensurePositiveNumber(value, label, filePath) {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+    throw new LoopSpecError(`${label} must be a positive number`, {
+      filePath,
+      code: 'invalid_budget',
+    });
+  }
+}
+
+function normalizeGate(gate, index, filePath) {
+  ensureObject(gate, `loop.gates[${index}]`, filePath);
+  ensureNonEmptyString(gate.name, `loop.gates[${index}].name`, filePath);
+  ensureNonEmptyString(gate.command, `loop.gates[${index}].command`, filePath);
+
+  return {
+    name: gate.name.trim(),
+    command: gate.command.trim(),
+    description: typeof gate.description === 'string' && gate.description.trim()
+      ? gate.description.trim()
+      : null,
+  };
+}
+
+function normalizeBudget(budget, filePath) {
+  ensureObject(budget, 'loop.budget', filePath);
+  ensurePositiveNumber(budget.maxIterations, 'loop.budget.maxIterations', filePath);
+  ensurePositiveNumber(budget.maxDollars, 'loop.budget.maxDollars', filePath);
+  ensureNonEmptyString(budget.maxDuration, 'loop.budget.maxDuration', filePath);
+
+  if (!/^(\d+)(m|h)$/.test(budget.maxDuration)) {
+    throw new LoopSpecError('loop.budget.maxDuration must use Nm or Nh format', {
+      filePath,
+      code: 'invalid_budget_duration',
+    });
+  }
+
+  return {
+    maxIterations: budget.maxIterations,
+    maxDuration: budget.maxDuration,
+    maxDollars: budget.maxDollars,
+  };
+}
+
+function normalizeActor(actor, label, filePath) {
+  ensureObject(actor, label, filePath);
+  ensureNonEmptyString(actor.role, `${label}.role`, filePath);
+
+  return {
+    role: actor.role.trim(),
+    writeAccess: actor.writeAccess === true,
+  };
+}
+
+function normalizeLoopSpec(payload, filePath = '<inline>') {
+  ensureObject(payload, 'loop spec', filePath);
+  ensureObject(payload.loop, 'loop', filePath);
+
+  const loop = payload.loop;
+  ensureNonEmptyString(loop.id, 'loop.id', filePath);
+  ensureNonEmptyString(loop.description, 'loop.description', filePath);
+  ensureNonEmptyString(loop.cadence, 'loop.cadence', filePath);
+  ensureNonEmptyString(loop.skill, 'loop.skill', filePath);
+  ensureNonEmptyString(loop.stateFile, 'loop.stateFile', filePath);
+
+  if (!/^(\d+)(m|h|d)$/.test(loop.cadence)) {
+    throw new LoopSpecError('loop.cadence must use Nm, Nh, or Nd format', {
+      filePath,
+      code: 'invalid_cadence',
+    });
+  }
+
+  if (!Array.isArray(loop.gates) || loop.gates.length === 0) {
+    throw new LoopSpecError('loop.gates must include at least one hard verification gate', {
+      filePath,
+      code: 'missing_gates',
+    });
+  }
+
+  return {
+    id: loop.id.trim(),
+    description: loop.description.trim(),
+    cadence: loop.cadence.trim(),
+    skill: loop.skill.trim(),
+    stateFile: loop.stateFile.trim(),
+    gates: loop.gates.map((gate, index) => normalizeGate(gate, index, filePath)),
+    maker: normalizeActor(loop.maker, 'loop.maker', filePath),
+    checker: normalizeActor(loop.checker, 'loop.checker', filePath),
+    budget: normalizeBudget(loop.budget, filePath),
+    escalation: {
+      onBudgetExhausted: loop.escalation?.onBudgetExhausted || 'triage',
+      onSecurityFinding: loop.escalation?.onSecurityFinding || 'human',
+    },
+  };
+}
+
+function parseLoopSpecContent(content, filePath = '<inline>') {
+  let payload;
+  try {
+    payload = yaml.load(content, {
+      filename: path.basename(filePath),
+      schema: yaml.JSON_SCHEMA,
+    });
+  } catch (error) {
+    throw new LoopSpecError(`Failed to parse loop spec YAML: ${error.message}`, {
+      filePath,
+      code: 'yaml_parse_error',
+    });
+  }
+
+  return normalizeLoopSpec(payload, filePath);
+}
+
+function loadLoopSpecFile(filePath) {
+  let content;
+  try {
+    content = fs.readFileSync(filePath, 'utf8');
+  } catch (error) {
+    throw new LoopSpecError(`Failed to read loop spec file: ${error.message}`, {
+      filePath,
+      code: 'read_error',
+    });
+  }
+
+  return {
+    path: filePath,
+    loop: parseLoopSpecContent(content, filePath),
+  };
+}
+
+module.exports = {
+  LoopSpecError,
+  normalizeLoopSpec,
+  parseLoopSpecContent,
+  loadLoopSpecFile,
+};