cc4pm 1.8.0

package/scripts/lib/skill-improvement/health.js

@@ -0,0 +1,118 @@
+'use strict';
+
+const HEALTH_SCHEMA_VERSION = 'ecc.skill-health.v1';
+
+function roundRate(value) {
+  return Math.round(value * 1000) / 1000;
+}
+
+function rankCounts(values) {
+  return Array.from(values.entries())
+    .map(([value, count]) => ({ value, count }))
+    .sort((left, right) => right.count - left.count || left.value.localeCompare(right.value));
+}
+
+function summarizeVariantRuns(records) {
+  return records.reduce((accumulator, record) => {
+    const key = record.run && record.run.variant ? record.run.variant : 'baseline';
+    if (!accumulator[key]) {
+      accumulator[key] = { runs: 0, successes: 0, failures: 0 };
+    }
+
+    accumulator[key].runs += 1;
+    if (record.outcome && record.outcome.success) {
+      accumulator[key].successes += 1;
+    } else {
+      accumulator[key].failures += 1;
+    }
+
+    return accumulator;
+  }, {});
+}
+
+function deriveSkillStatus(skillSummary, options = {}) {
+  const minFailureCount = options.minFailureCount || 2;
+  if (skillSummary.failures >= minFailureCount) {
+    return 'failing';
+  }
+
+  if (skillSummary.failures > 0) {
+    return 'watch';
+  }
+
+  return 'healthy';
+}
+
+function buildSkillHealthReport(records, options = {}) {
+  const filterSkillId = options.skillId || null;
+  const filtered = filterSkillId
+    ? records.filter(record => record.skill && record.skill.id === filterSkillId)
+    : records.slice();
+
+  const grouped = filtered.reduce((accumulator, record) => {
+    const skillId = record.skill.id;
+    if (!accumulator.has(skillId)) {
+      accumulator.set(skillId, []);
+    }
+    accumulator.get(skillId).push(record);
+    return accumulator;
+  }, new Map());
+
+  const skills = Array.from(grouped.entries())
+    .map(([skillId, skillRecords]) => {
+      const successes = skillRecords.filter(record => record.outcome && record.outcome.success).length;
+      const failures = skillRecords.length - successes;
+      const recurringErrors = new Map();
+      const recurringTasks = new Map();
+      const recurringFeedback = new Map();
+
+      skillRecords.forEach(record => {
+        if (!record.outcome || record.outcome.success) {
+          return;
+        }
+
+        if (record.outcome.error) {
+          recurringErrors.set(record.outcome.error, (recurringErrors.get(record.outcome.error) || 0) + 1);
+        }
+        if (record.task) {
+          recurringTasks.set(record.task, (recurringTasks.get(record.task) || 0) + 1);
+        }
+        if (record.outcome.feedback) {
+          recurringFeedback.set(record.outcome.feedback, (recurringFeedback.get(record.outcome.feedback) || 0) + 1);
+        }
+      });
+
+      const summary = {
+        skill: {
+          id: skillId,
+          path: skillRecords[0].skill.path || null
+        },
+        totalRuns: skillRecords.length,
+        successes,
+        failures,
+        successRate: skillRecords.length > 0 ? roundRate(successes / skillRecords.length) : 0,
+        status: 'healthy',
+        recurringErrors: rankCounts(recurringErrors).map(entry => ({ error: entry.value, count: entry.count })),
+        recurringTasks: rankCounts(recurringTasks).map(entry => ({ task: entry.value, count: entry.count })),
+        recurringFeedback: rankCounts(recurringFeedback).map(entry => ({ feedback: entry.value, count: entry.count })),
+        variants: summarizeVariantRuns(skillRecords)
+      };
+
+      summary.status = deriveSkillStatus(summary, options);
+      return summary;
+    })
+    .sort((left, right) => right.failures - left.failures || left.skill.id.localeCompare(right.skill.id));
+
+  return {
+    schemaVersion: HEALTH_SCHEMA_VERSION,
+    generatedAt: new Date().toISOString(),
+    totalObservations: filtered.length,
+    skillCount: skills.length,
+    skills
+  };
+}
+
+module.exports = {
+  HEALTH_SCHEMA_VERSION,
+  buildSkillHealthReport
+};

package/scripts/lib/skill-improvement/observations.js

@@ -0,0 +1,108 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const OBSERVATION_SCHEMA_VERSION = 'ecc.skill-observation.v1';
+
+function resolveProjectRoot(options = {}) {
+  return path.resolve(options.projectRoot || options.cwd || process.cwd());
+}
+
+function getSkillTelemetryRoot(options = {}) {
+  return path.join(resolveProjectRoot(options), '.claude', 'ecc', 'skills');
+}
+
+function getSkillObservationsPath(options = {}) {
+  return path.join(getSkillTelemetryRoot(options), 'observations.jsonl');
+}
+
+function ensureString(value, label) {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new Error(`${label} must be a non-empty string`);
+  }
+
+  return value.trim();
+}
+
+function createObservationId() {
+  return `obs-${Date.now()}-${process.pid}-${Math.random().toString(16).slice(2, 8)}`;
+}
+
+function createSkillObservation(input) {
+  const task = ensureString(input.task, 'task');
+  const skillId = ensureString(input.skill && input.skill.id, 'skill.id');
+  const skillPath = typeof input.skill.path === 'string' && input.skill.path.trim().length > 0
+    ? input.skill.path.trim()
+    : null;
+  const success = Boolean(input.success);
+  const error = input.error == null ? null : String(input.error);
+  const feedback = input.feedback == null ? null : String(input.feedback);
+  const variant = typeof input.variant === 'string' && input.variant.trim().length > 0
+    ? input.variant.trim()
+    : 'baseline';
+
+  return {
+    schemaVersion: OBSERVATION_SCHEMA_VERSION,
+    observationId: typeof input.observationId === 'string' && input.observationId.length > 0
+      ? input.observationId
+      : createObservationId(),
+    timestamp: typeof input.timestamp === 'string' && input.timestamp.length > 0
+      ? input.timestamp
+      : new Date().toISOString(),
+    task,
+    skill: {
+      id: skillId,
+      path: skillPath
+    },
+    outcome: {
+      success,
+      status: success ? 'success' : 'failure',
+      error,
+      feedback
+    },
+    run: {
+      variant,
+      amendmentId: input.amendmentId || null,
+      sessionId: input.sessionId || null,
+      source: input.source || 'manual'
+    }
+  };
+}
+
+function appendSkillObservation(observation, options = {}) {
+  const outputPath = getSkillObservationsPath(options);
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.appendFileSync(outputPath, `${JSON.stringify(observation)}${os.EOL}`, 'utf8');
+  return outputPath;
+}
+
+function readSkillObservations(options = {}) {
+  const observationPath = path.resolve(options.observationsPath || getSkillObservationsPath(options));
+  if (!fs.existsSync(observationPath)) {
+    return [];
+  }
+
+  return fs.readFileSync(observationPath, 'utf8')
+    .split(/\r?\n/)
+    .filter(Boolean)
+    .map(line => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        return null;
+      }
+    })
+    .filter(record => record && record.schemaVersion === OBSERVATION_SCHEMA_VERSION);
+}
+
+module.exports = {
+  OBSERVATION_SCHEMA_VERSION,
+  appendSkillObservation,
+  createSkillObservation,
+  getSkillObservationsPath,
+  getSkillTelemetryRoot,
+  readSkillObservations,
+  resolveProjectRoot
+};

package/scripts/lib/tmux-worktree-orchestrator.js

@@ -0,0 +1,491 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+function slugify(value, fallback = 'worker') {
+  const normalized = String(value || '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+  return normalized || fallback;
+}
+
+function renderTemplate(template, variables) {
+  if (typeof template !== 'string' || template.trim().length === 0) {
+    throw new Error('launcherCommand must be a non-empty string');
+  }
+
+  return template.replace(/\{([a-z_]+)\}/g, (match, key) => {
+    if (!(key in variables)) {
+      throw new Error(`Unknown template variable: ${key}`);
+    }
+    return String(variables[key]);
+  });
+}
+
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+
+function formatCommand(program, args) {
+  return [program, ...args.map(shellQuote)].join(' ');
+}
+
+function normalizeSeedPaths(seedPaths, repoRoot) {
+  const resolvedRepoRoot = path.resolve(repoRoot);
+  const entries = Array.isArray(seedPaths) ? seedPaths : [];
+  const seen = new Set();
+  const normalized = [];
+
+  for (const entry of entries) {
+    if (typeof entry !== 'string' || entry.trim().length === 0) {
+      continue;
+    }
+
+    const absolutePath = path.resolve(resolvedRepoRoot, entry);
+    const relativePath = path.relative(resolvedRepoRoot, absolutePath);
+
+    if (
+      relativePath.startsWith('..') ||
+      path.isAbsolute(relativePath)
+    ) {
+      throw new Error(`seedPaths entries must stay inside repoRoot: ${entry}`);
+    }
+
+    const normalizedPath = relativePath.split(path.sep).join('/');
+    if (seen.has(normalizedPath)) {
+      continue;
+    }
+
+    seen.add(normalizedPath);
+    normalized.push(normalizedPath);
+  }
+
+  return normalized;
+}
+
+function overlaySeedPaths({ repoRoot, seedPaths, worktreePath }) {
+  const normalizedSeedPaths = normalizeSeedPaths(seedPaths, repoRoot);
+
+  for (const seedPath of normalizedSeedPaths) {
+    const sourcePath = path.join(repoRoot, seedPath);
+    const destinationPath = path.join(worktreePath, seedPath);
+
+    if (!fs.existsSync(sourcePath)) {
+      throw new Error(`Seed path does not exist in repoRoot: ${seedPath}`);
+    }
+
+    fs.mkdirSync(path.dirname(destinationPath), { recursive: true });
+    fs.rmSync(destinationPath, { force: true, recursive: true });
+    fs.cpSync(sourcePath, destinationPath, {
+      dereference: false,
+      force: true,
+      preserveTimestamps: true,
+      recursive: true
+    });
+  }
+}
+
+function buildWorkerArtifacts(workerPlan) {
+  const seededPathsSection = workerPlan.seedPaths.length > 0
+    ? [
+        '',
+        '## Seeded Local Overlays',
+        ...workerPlan.seedPaths.map(seedPath => `- \`${seedPath}\``)
+      ]
+    : [];
+
+  return {
+    dir: workerPlan.coordinationDir,
+    files: [
+      {
+        path: workerPlan.taskFilePath,
+        content: [
+          `# Worker Task: ${workerPlan.workerName}`,
+          '',
+          `- Session: \`${workerPlan.sessionName}\``,
+          `- Repo root: \`${workerPlan.repoRoot}\``,
+          `- Worktree: \`${workerPlan.worktreePath}\``,
+          `- Branch: \`${workerPlan.branchName}\``,
+          `- Launcher status file: \`${workerPlan.statusFilePath}\``,
+          `- Launcher handoff file: \`${workerPlan.handoffFilePath}\``,
+          ...seededPathsSection,
+          '',
+          '## Objective',
+          workerPlan.task,
+          '',
+          '## Completion',
+          'Do not spawn subagents or external agents for this task.',
+          'Report results in your final response.',
+          `The worker launcher captures your response in \`${workerPlan.handoffFilePath}\` automatically.`,
+          `The worker launcher updates \`${workerPlan.statusFilePath}\` automatically.`
+        ].join('\n')
+      },
+      {
+        path: workerPlan.handoffFilePath,
+        content: [
+          `# Handoff: ${workerPlan.workerName}`,
+          '',
+          '## Summary',
+          '- Pending',
+          '',
+          '## Files Changed',
+          '- Pending',
+          '',
+          '## Tests / Verification',
+          '- Pending',
+          '',
+          '## Follow-ups',
+          '- Pending'
+        ].join('\n')
+      },
+      {
+        path: workerPlan.statusFilePath,
+        content: [
+          `# Status: ${workerPlan.workerName}`,
+          '',
+          '- State: not started',
+          `- Worktree: \`${workerPlan.worktreePath}\``,
+          `- Branch: \`${workerPlan.branchName}\``
+        ].join('\n')
+      }
+    ]
+  };
+}
+
+function buildOrchestrationPlan(config = {}) {
+  const repoRoot = path.resolve(config.repoRoot || process.cwd());
+  const repoName = path.basename(repoRoot);
+  const workers = Array.isArray(config.workers) ? config.workers : [];
+  const globalSeedPaths = normalizeSeedPaths(config.seedPaths, repoRoot);
+  const sessionName = slugify(config.sessionName || repoName, 'session');
+  const worktreeRoot = path.resolve(config.worktreeRoot || path.dirname(repoRoot));
+  const coordinationRoot = path.resolve(
+    config.coordinationRoot || path.join(repoRoot, '.orchestration')
+  );
+  const coordinationDir = path.join(coordinationRoot, sessionName);
+  const baseRef = config.baseRef || 'HEAD';
+  const defaultLauncher = config.launcherCommand || '';
+
+  if (workers.length === 0) {
+    throw new Error('buildOrchestrationPlan requires at least one worker');
+  }
+
+  const workerPlans = workers.map((worker, index) => {
+    if (!worker || typeof worker.task !== 'string' || worker.task.trim().length === 0) {
+      throw new Error(`Worker ${index + 1} is missing a task`);
+    }
+
+    const workerName = worker.name || `worker-${index + 1}`;
+    const workerSlug = slugify(workerName, `worker-${index + 1}`);
+    const branchName = `orchestrator-${sessionName}-${workerSlug}`;
+    const worktreePath = path.join(worktreeRoot, `${repoName}-${sessionName}-${workerSlug}`);
+    const workerCoordinationDir = path.join(coordinationDir, workerSlug);
+    const taskFilePath = path.join(workerCoordinationDir, 'task.md');
+    const handoffFilePath = path.join(workerCoordinationDir, 'handoff.md');
+    const statusFilePath = path.join(workerCoordinationDir, 'status.md');
+    const launcherCommand = worker.launcherCommand || defaultLauncher;
+    const workerSeedPaths = normalizeSeedPaths(worker.seedPaths, repoRoot);
+    const seedPaths = normalizeSeedPaths([...globalSeedPaths, ...workerSeedPaths], repoRoot);
+    const templateVariables = {
+      branch_name: branchName,
+      handoff_file: handoffFilePath,
+      repo_root: repoRoot,
+      session_name: sessionName,
+      status_file: statusFilePath,
+      task_file: taskFilePath,
+      worker_name: workerName,
+      worker_slug: workerSlug,
+      worktree_path: worktreePath
+    };
+
+    if (!launcherCommand) {
+      throw new Error(`Worker ${workerName} is missing a launcherCommand`);
+    }
+
+    const gitArgs = ['worktree', 'add', '-b', branchName, worktreePath, baseRef];
+
+    return {
+      branchName,
+      coordinationDir: workerCoordinationDir,
+      gitArgs,
+      gitCommand: formatCommand('git', gitArgs),
+      handoffFilePath,
+      launchCommand: renderTemplate(launcherCommand, templateVariables),
+      repoRoot,
+      sessionName,
+      seedPaths,
+      statusFilePath,
+      task: worker.task.trim(),
+      taskFilePath,
+      workerName,
+      workerSlug,
+      worktreePath
+    };
+  });
+
+  const tmuxCommands = [
+    {
+      cmd: 'tmux',
+      args: ['new-session', '-d', '-s', sessionName, '-n', 'orchestrator', '-c', repoRoot],
+      description: 'Create detached tmux session'
+    },
+    {
+      cmd: 'tmux',
+      args: [
+        'send-keys',
+        '-t',
+        sessionName,
+        `printf '%s\\n' 'Session: ${sessionName}' 'Coordination: ${coordinationDir}'`,
+        'C-m'
+      ],
+      description: 'Print orchestrator session details'
+    }
+  ];
+
+  for (const workerPlan of workerPlans) {
+    tmuxCommands.push(
+      {
+        cmd: 'tmux',
+        args: ['split-window', '-d', '-t', sessionName, '-c', workerPlan.worktreePath],
+        description: `Create pane for ${workerPlan.workerName}`
+      },
+      {
+        cmd: 'tmux',
+        args: ['select-layout', '-t', sessionName, 'tiled'],
+        description: 'Arrange panes in tiled layout'
+      },
+      {
+        cmd: 'tmux',
+        args: ['select-pane', '-t', '<pane-id>', '-T', workerPlan.workerSlug],
+        description: `Label pane ${workerPlan.workerSlug}`
+      },
+      {
+        cmd: 'tmux',
+        args: [
+          'send-keys',
+          '-t',
+          '<pane-id>',
+          `cd ${shellQuote(workerPlan.worktreePath)} && ${workerPlan.launchCommand}`,
+          'C-m'
+        ],
+        description: `Launch worker ${workerPlan.workerName}`
+      }
+    );
+  }
+
+  return {
+    baseRef,
+    coordinationDir,
+    replaceExisting: Boolean(config.replaceExisting),
+    repoRoot,
+    sessionName,
+    tmuxCommands,
+    workerPlans
+  };
+}
+
+function materializePlan(plan) {
+  for (const workerPlan of plan.workerPlans) {
+    const artifacts = buildWorkerArtifacts(workerPlan);
+    fs.mkdirSync(artifacts.dir, { recursive: true });
+    for (const file of artifacts.files) {
+      fs.writeFileSync(file.path, file.content + '\n', 'utf8');
+    }
+  }
+}
+
+function runCommand(program, args, options = {}) {
+  const result = spawnSync(program, args, {
+    cwd: options.cwd,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe']
+  });
+
+  if (result.error) {
+    throw result.error;
+  }
+  if (result.status !== 0) {
+    const stderr = (result.stderr || '').trim();
+    throw new Error(`${program} ${args.join(' ')} failed${stderr ? `: ${stderr}` : ''}`);
+  }
+  return result;
+}
+
+function commandSucceeds(program, args, options = {}) {
+  const result = spawnSync(program, args, {
+    cwd: options.cwd,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe']
+  });
+  return result.status === 0;
+}
+
+function canonicalizePath(targetPath) {
+  const resolvedPath = path.resolve(targetPath);
+
+  try {
+    return fs.realpathSync.native(resolvedPath);
+  } catch (_error) {
+    const parentPath = path.dirname(resolvedPath);
+
+    try {
+      return path.join(fs.realpathSync.native(parentPath), path.basename(resolvedPath));
+    } catch (_parentError) {
+      return resolvedPath;
+    }
+  }
+}
+
+function branchExists(repoRoot, branchName) {
+  return commandSucceeds('git', ['show-ref', '--verify', '--quiet', `refs/heads/${branchName}`], {
+    cwd: repoRoot
+  });
+}
+
+function listWorktrees(repoRoot) {
+  const listed = runCommand('git', ['worktree', 'list', '--porcelain'], { cwd: repoRoot });
+  const lines = (listed.stdout || '').split('\n');
+  const worktrees = [];
+
+  for (const line of lines) {
+    if (line.startsWith('worktree ')) {
+      const listedPath = line.slice('worktree '.length).trim();
+      worktrees.push({
+        listedPath,
+        canonicalPath: canonicalizePath(listedPath)
+      });
+    }
+  }
+
+  return worktrees;
+}
+
+function cleanupExisting(plan) {
+  runCommand('git', ['worktree', 'prune', '--expire', 'now'], { cwd: plan.repoRoot });
+
+  const hasSession = spawnSync('tmux', ['has-session', '-t', plan.sessionName], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe']
+  });
+
+  if (hasSession.status === 0) {
+    runCommand('tmux', ['kill-session', '-t', plan.sessionName], { cwd: plan.repoRoot });
+  }
+
+  for (const workerPlan of plan.workerPlans) {
+    const expectedWorktreePath = canonicalizePath(workerPlan.worktreePath);
+    const existingWorktree = listWorktrees(plan.repoRoot).find(
+      worktree => worktree.canonicalPath === expectedWorktreePath
+    );
+
+    if (existingWorktree) {
+      runCommand('git', ['worktree', 'remove', '--force', existingWorktree.listedPath], {
+        cwd: plan.repoRoot
+      });
+    }
+
+    if (fs.existsSync(workerPlan.worktreePath)) {
+      fs.rmSync(workerPlan.worktreePath, { force: true, recursive: true });
+    }
+
+    runCommand('git', ['worktree', 'prune', '--expire', 'now'], { cwd: plan.repoRoot });
+
+    if (branchExists(plan.repoRoot, workerPlan.branchName)) {
+      runCommand('git', ['branch', '-D', workerPlan.branchName], { cwd: plan.repoRoot });
+    }
+  }
+}
+
+function executePlan(plan) {
+  runCommand('git', ['rev-parse', '--is-inside-work-tree'], { cwd: plan.repoRoot });
+  runCommand('tmux', ['-V']);
+
+  if (plan.replaceExisting) {
+    cleanupExisting(plan);
+  } else {
+    const hasSession = spawnSync('tmux', ['has-session', '-t', plan.sessionName], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe']
+    });
+    if (hasSession.status === 0) {
+      throw new Error(`tmux session already exists: ${plan.sessionName}`);
+    }
+  }
+
+  materializePlan(plan);
+
+  for (const workerPlan of plan.workerPlans) {
+    runCommand('git', workerPlan.gitArgs, { cwd: plan.repoRoot });
+    overlaySeedPaths({
+      repoRoot: plan.repoRoot,
+      seedPaths: workerPlan.seedPaths,
+      worktreePath: workerPlan.worktreePath
+    });
+  }
+
+  runCommand(
+    'tmux',
+    ['new-session', '-d', '-s', plan.sessionName, '-n', 'orchestrator', '-c', plan.repoRoot],
+    { cwd: plan.repoRoot }
+  );
+  runCommand(
+    'tmux',
+    [
+      'send-keys',
+      '-t',
+      plan.sessionName,
+      `printf '%s\\n' 'Session: ${plan.sessionName}' 'Coordination: ${plan.coordinationDir}'`,
+      'C-m'
+    ],
+    { cwd: plan.repoRoot }
+  );
+
+  for (const workerPlan of plan.workerPlans) {
+    const splitResult = runCommand(
+      'tmux',
+      ['split-window', '-d', '-P', '-F', '#{pane_id}', '-t', plan.sessionName, '-c', workerPlan.worktreePath],
+      { cwd: plan.repoRoot }
+    );
+    const paneId = splitResult.stdout.trim();
+
+    if (!paneId) {
+      throw new Error(`tmux split-window did not return a pane id for ${workerPlan.workerName}`);
+    }
+
+    runCommand('tmux', ['select-layout', '-t', plan.sessionName, 'tiled'], { cwd: plan.repoRoot });
+    runCommand('tmux', ['select-pane', '-t', paneId, '-T', workerPlan.workerSlug], {
+      cwd: plan.repoRoot
+    });
+    runCommand(
+      'tmux',
+      [
+        'send-keys',
+        '-t',
+        paneId,
+        `cd ${shellQuote(workerPlan.worktreePath)} && ${workerPlan.launchCommand}`,
+        'C-m'
+      ],
+      { cwd: plan.repoRoot }
+    );
+  }
+
+  return {
+    coordinationDir: plan.coordinationDir,
+    sessionName: plan.sessionName,
+    workerCount: plan.workerPlans.length
+  };
+}
+
+module.exports = {
+  buildOrchestrationPlan,
+  executePlan,
+  materializePlan,
+  normalizeSeedPaths,
+  overlaySeedPaths,
+  renderTemplate,
+  slugify
+};