vibepro 0.1.0-alpha.0

package/src/session-learning.js

@@ -0,0 +1,164 @@
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { getWorkspaceDir, initWorkspace, toWorkspaceRelative } from './workspace.js';
+
+const LEARNING_STATUSES = new Set(['candidate', 'reviewed', 'accepted', 'rejected']);
+
+export async function recordSessionLearning(repoRoot, options = {}) {
+  const root = path.resolve(repoRoot);
+  await initWorkspace(root);
+  const store = await readLearningStore(root);
+  const learning = {
+    id: options.id ?? buildLearningId(store.learnings.length + 1),
+    kind: options.kind ?? 'repeated_mistake',
+    summary: requireText(options.summary, 'harness learn requires --summary <text>'),
+    source: options.source ?? 'manual',
+    evidence: options.evidence ?? null,
+    pattern: options.pattern ?? null,
+    status: normalizeLearningStatus(options.status ?? 'candidate'),
+    skill_candidate: options.skillCandidate ?? null,
+    target_surfaces: parseList(options.targets ?? []),
+    created_at: new Date().toISOString()
+  };
+  const next = {
+    ...store,
+    updated_at: learning.created_at,
+    learnings: [
+      learning,
+      ...store.learnings.filter((item) => item.id !== learning.id)
+    ]
+  };
+  await writeLearningStore(root, next);
+  return {
+    learning,
+    store: summarizeLearningStore(next),
+    artifacts: {
+      json: toWorkspaceRelative(root, getLearningStorePath(root))
+    }
+  };
+}
+
+export async function reviewSessionLearnings(repoRoot) {
+  const root = path.resolve(repoRoot);
+  await initWorkspace(root);
+  const store = await readLearningStore(root);
+  const markdown = renderSessionLearningsReview(store);
+  const reviewPath = path.join(getHarnessDir(root), 'session-learnings-review.md');
+  await mkdir(path.dirname(reviewPath), { recursive: true });
+  await writeFile(reviewPath, markdown);
+  return {
+    store: summarizeLearningStore(store),
+    learnings: store.learnings,
+    artifacts: {
+      json: toWorkspaceRelative(root, getLearningStorePath(root)),
+      review_markdown: toWorkspaceRelative(root, reviewPath)
+    },
+    markdown
+  };
+}
+
+export function renderSessionLearningRecordSummary(result) {
+  return `# Session Learning Recorded
+
+- id: ${result.learning.id}
+- kind: ${result.learning.kind}
+- status: ${result.learning.status}
+- store: ${result.artifacts.json}
+`;
+}
+
+export function renderSessionLearningsReviewSummary(result) {
+  return result.markdown;
+}
+
+function renderSessionLearningsReview(store) {
+  const candidates = store.learnings.filter((item) => item.status === 'candidate');
+  const lines = [
+    '# Session Learnings Review',
+    '',
+    `Total: ${store.learnings.length}`,
+    `Candidates: ${candidates.length}`,
+    '',
+    'This report proposes updates for Skills / AGENTS.md / CLAUDE.md. It does not modify those files automatically.',
+    '',
+    '## Candidates',
+    ''
+  ];
+  if (candidates.length === 0) {
+    lines.push('- none');
+  } else {
+    for (const item of candidates) {
+      lines.push(`### ${item.id}: ${item.summary}`);
+      lines.push('');
+      lines.push(`- kind: ${item.kind}`);
+      lines.push(`- source: ${item.source}`);
+      if (item.evidence) lines.push(`- evidence: ${item.evidence}`);
+      if (item.pattern) lines.push(`- pattern: ${item.pattern}`);
+      lines.push(`- target surfaces: ${item.target_surfaces.join(', ') || '-'}`);
+      lines.push(`- skill candidate: ${item.skill_candidate ?? '-'}`);
+      lines.push('');
+    }
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+async function readLearningStore(root) {
+  try {
+    return JSON.parse(await readFile(getLearningStorePath(root), 'utf8'));
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    return {
+      schema_version: '0.1.0',
+      updated_at: null,
+      learnings: []
+    };
+  }
+}
+
+async function writeLearningStore(root, store) {
+  const storePath = getLearningStorePath(root);
+  await mkdir(path.dirname(storePath), { recursive: true });
+  const tempPath = `${storePath}.${process.pid}.tmp`;
+  await writeFile(tempPath, `${JSON.stringify(store, null, 2)}\n`);
+  await rename(tempPath, storePath);
+}
+
+function summarizeLearningStore(store) {
+  return {
+    schema_version: store.schema_version,
+    updated_at: store.updated_at,
+    total: store.learnings.length,
+    candidate: store.learnings.filter((item) => item.status === 'candidate').length,
+    accepted: store.learnings.filter((item) => item.status === 'accepted').length,
+    rejected: store.learnings.filter((item) => item.status === 'rejected').length
+  };
+}
+
+function getHarnessDir(root) {
+  return path.join(getWorkspaceDir(root), 'harness');
+}
+
+function getLearningStorePath(root) {
+  return path.join(getHarnessDir(root), 'session-learnings.json');
+}
+
+function buildLearningId(index) {
+  return `learning-${String(index).padStart(3, '0')}`;
+}
+
+function normalizeLearningStatus(status) {
+  if (!LEARNING_STATUSES.has(status)) {
+    throw new Error(`learning status must be one of: ${[...LEARNING_STATUSES].join(', ')}`);
+  }
+  return status;
+}
+
+function requireText(value, message) {
+  if (!value) throw new Error(message);
+  return value;
+}
+
+function parseList(values) {
+  return values.flatMap((value) => String(value).split(',')).map((value) => value.trim()).filter(Boolean);
+}

package/src/skills-manager.js

@@ -0,0 +1,157 @@
+import { mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SKILLS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'skills');
+const TARGET_SKILLS_DIR = path.join('.claude', 'skills');
+
+export async function listBundledSkills() {
+  const entries = await readdir(SKILLS_DIR, { withFileTypes: true });
+  const skills = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const skillPath = path.join(SKILLS_DIR, entry.name, 'SKILL.md');
+    const content = await readFile(skillPath, 'utf8');
+    const metadata = parseSkillFrontmatter(content);
+    skills.push({
+      name: metadata.name ?? entry.name,
+      description: metadata.description ?? '',
+      source_path: skillPath,
+      relative_path: path.join('skills', entry.name, 'SKILL.md')
+    });
+  }
+  return skills.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export async function installBundledSkills(repoRoot, options = {}) {
+  const root = path.resolve(repoRoot);
+  const skills = await listBundledSkills();
+  const results = [];
+  for (const skill of skills) {
+    const source = skill.source_path;
+    const target = path.join(root, TARGET_SKILLS_DIR, skill.name, 'SKILL.md');
+    const sourceContent = await readFile(source, 'utf8');
+    const targetContent = await readOptional(target);
+    const exists = targetContent !== null;
+    const same = exists && targetContent === sourceContent;
+    let status = 'up_to_date';
+    if (!same) {
+      if (!exists) status = options.dryRun ? 'would_install' : 'installed';
+      else if (options.force) status = options.dryRun ? 'would_overwrite' : 'overwritten';
+      else status = 'skipped';
+    }
+    if (!options.dryRun && ['installed', 'overwritten'].includes(status)) {
+      await mkdir(path.dirname(target), { recursive: true });
+      await writeFile(target, sourceContent);
+    }
+    results.push({
+      name: skill.name,
+      description: skill.description,
+      status,
+      target_path: toDisplayPath(root, target),
+      source_path: skill.relative_path
+    });
+  }
+  return {
+    mode: 'install',
+    dry_run: Boolean(options.dryRun),
+    force: Boolean(options.force),
+    target_root: root,
+    target_dir: path.join(root, TARGET_SKILLS_DIR),
+    skills: results,
+    summary: summarizeSkillResults(results)
+  };
+}
+
+export async function verifyBundledSkills(repoRoot) {
+  const root = path.resolve(repoRoot);
+  const skills = await listBundledSkills();
+  const results = [];
+  for (const skill of skills) {
+    const sourceContent = await readFile(skill.source_path, 'utf8');
+    const target = path.join(root, TARGET_SKILLS_DIR, skill.name, 'SKILL.md');
+    const targetContent = await readOptional(target);
+    let status = 'ok';
+    if (targetContent === null) status = 'missing';
+    else if (targetContent !== sourceContent) status = 'outdated';
+    results.push({
+      name: skill.name,
+      description: skill.description,
+      status,
+      target_path: toDisplayPath(root, target),
+      source_path: skill.relative_path
+    });
+  }
+  const summary = summarizeSkillResults(results);
+  return {
+    mode: 'verify',
+    target_root: root,
+    target_dir: path.join(root, TARGET_SKILLS_DIR),
+    overall_status: results.every((item) => item.status === 'ok') ? 'ok' : 'needs_install',
+    skills: results,
+    summary
+  };
+}
+
+export function renderSkillsList(skills) {
+  return [
+    '# VibePro Skills',
+    '',
+    ...skills.map((skill) => `- ${skill.name}: ${skill.description}`)
+  ].join('\n') + '\n';
+}
+
+export function renderSkillsInstall(result) {
+  return renderSkillResult('VibePro Skills Install', result);
+}
+
+export function renderSkillsVerify(result) {
+  return renderSkillResult('VibePro Skills Verify', result);
+}
+
+function renderSkillResult(title, result) {
+  return `${title}
+
+Target: ${result.target_dir}
+
+${result.skills.map((skill) => `- ${skill.name}: ${skill.status} (${skill.target_path})`).join('\n')}
+
+Summary: ${Object.entries(result.summary).map(([key, value]) => `${key}=${value}`).join(', ')}
+`;
+}
+
+function parseSkillFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return {};
+  const metadata = {};
+  for (const line of match[1].split('\n')) {
+    const index = line.indexOf(':');
+    if (index === -1) continue;
+    const key = line.slice(0, index).trim();
+    const value = line.slice(index + 1).trim().replace(/^["']|["']$/g, '');
+    metadata[key] = value;
+  }
+  return metadata;
+}
+
+async function readOptional(filePath) {
+  try {
+    await stat(filePath);
+    return await readFile(filePath, 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+function summarizeSkillResults(results) {
+  return results.reduce((summary, item) => {
+    summary[item.status] = (summary[item.status] ?? 0) + 1;
+    return summary;
+  }, {});
+}
+
+function toDisplayPath(root, filePath) {
+  const relative = path.relative(root, filePath);
+  return relative.startsWith('..') ? filePath : relative;
+}

package/src/spec-drift.js

@@ -0,0 +1,378 @@
+import { execFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { promisify } from 'node:util';
+
+import { buildSpecFingerprint } from './spec-fingerprint.js';
+import { matchGlob } from './spec-validator.js';
+import { readInferredSpec, readSuppressions, writeSuppressions } from './spec-store.js';
+
+const execFileAsync = promisify(execFile);
+const SUPPRESS_DEMOTE_THRESHOLD = 3;
+
+export async function buildSpecDrift(repoRoot, options = {}) {
+  const root = path.resolve(repoRoot);
+  const storyId = options.storyId ?? null;
+  if (!storyId) {
+    return emptyDrift({ status: 'inconclusive', reason: 'storyId required' });
+  }
+
+  const spec = options.spec ?? (await readInferredSpec(root, storyId));
+  if (!spec) {
+    return emptyDrift({ storyId, status: 'inconclusive', reason: 'no inferred spec found' });
+  }
+
+  const fingerprint = options.fingerprint ?? (await buildSpecFingerprint(root, { storyId }));
+  const suppressions = await readSuppressions(root, storyId);
+
+  const items = [];
+
+  for (const clause of spec.clauses ?? []) {
+    items.push(...(await detectSpecCodeDrift(root, clause)));
+    items.push(...(await detectSpecTestDrift(root, clause)));
+  }
+
+  items.push(...detectCodeTestDrift(spec, fingerprint));
+
+  if (options.againstRef) {
+    items.push(...(await detectSpecPrDrift(root, spec, options.againstRef)));
+  }
+
+  const finalItems = applySuppressions(items, suppressions);
+  await updateSuppressionLedger(root, storyId, finalItems, suppressions);
+
+  const summary = summarizeAxes(finalItems);
+  const status = finalItems.length > 0 ? 'drift_detected' : 'clean';
+
+  return {
+    schema_version: '0.1.0',
+    story_id: storyId,
+    spec_id: spec.previous_spec_id ?? null,
+    evaluated_at: new Date().toISOString(),
+    status,
+    summary,
+    items: finalItems
+  };
+}
+
+export function renderDriftMarkdown(drift) {
+  if (!drift) return '# Spec Drift\n\n- 未生成\n';
+  const lines = ['# Spec Drift', ''];
+  lines.push(`- Status: ${drift.status}`);
+  lines.push(`- Story: ${drift.story_id}`);
+  lines.push(`- Evaluated at: ${drift.evaluated_at}`);
+  lines.push('');
+  if (drift.summary) {
+    lines.push('| Axis | Count |');
+    lines.push('|------|-------|');
+    for (const [axis, count] of Object.entries(drift.summary)) {
+      lines.push(`| ${axis} | ${count} |`);
+    }
+    lines.push('');
+  }
+  if (!drift.items || drift.items.length === 0) {
+    lines.push('## Items', '', '- なし');
+    return `${lines.join('\n')}\n`;
+  }
+  lines.push('## Items');
+  for (const item of drift.items) {
+    lines.push('');
+    lines.push(`### ${item.id} [${item.severity}] (${item.axis})`);
+    lines.push(`- Clause: ${item.clause_id ?? '-'}`);
+    lines.push(`- Title: ${item.title}`);
+    if (item.detail) lines.push(`- Detail: ${item.detail}`);
+    if (item.suggested_action) lines.push(`- Suggested action: ${item.suggested_action}`);
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+async function detectSpecCodeDrift(repoRoot, clause) {
+  const items = [];
+  const patterns = clause?.verifiable_by?.code_pattern ?? [];
+  for (let i = 0; i < patterns.length; i += 1) {
+    items.push(...(await checkPattern(repoRoot, clause, patterns[i], 'spec_code', `code_pattern[${i}]`)));
+  }
+  for (const ref of clause?.origin?.code_refs ?? []) {
+    if (!ref?.file) continue;
+    const stats = await statFile(repoRoot, ref.file);
+    if (!stats.exists) {
+      items.push({
+        id: `DRIFT-${randomDriftId()}`,
+        axis: 'spec_code',
+        clause_id: clause.id,
+        severity: 'high',
+        title: `${clause.id} の参照ファイルが存在しない`,
+        detail: `${ref.file} が repository に無い (Code が削除/移動された可能性)`,
+        suggested_action: `clause "${clause.id}" の origin.code_refs を更新するか、Spec を再生成する`
+      });
+      continue;
+    }
+    if (ref.anchor && !(await fileIncludes(repoRoot, ref.file, ref.anchor))) {
+      items.push({
+        id: `DRIFT-${randomDriftId()}`,
+        axis: 'spec_code',
+        clause_id: clause.id,
+        severity: 'medium',
+        title: `${clause.id} の anchor が ${ref.file} に見つからない`,
+        detail: `anchor "${ref.anchor}" が ${ref.file} に存在しない (リネーム/削除の可能性)`,
+        suggested_action: `clause "${clause.id}" の anchor を更新するか、Spec を再生成する`
+      });
+    }
+  }
+  return items;
+}
+
+async function detectSpecTestDrift(repoRoot, clause) {
+  const items = [];
+  const patterns = clause?.verifiable_by?.test_pattern ?? [];
+  for (let i = 0; i < patterns.length; i += 1) {
+    items.push(...(await checkPattern(repoRoot, clause, patterns[i], 'spec_test', `test_pattern[${i}]`)));
+  }
+  if (patterns.length === 0 && clause.type === 'invariant') {
+    items.push({
+      id: `DRIFT-${randomDriftId()}`,
+      axis: 'spec_test',
+      clause_id: clause.id,
+      severity: 'low',
+      title: `${clause.id} を機械検証する test_pattern が宣言されていない`,
+      detail: '不変条件は test_pattern を持つことを推奨',
+      suggested_action: `clause "${clause.id}" に verifiable_by.test_pattern を追加`
+    });
+  }
+  return items;
+}
+
+async function checkPattern(repoRoot, clause, pattern, axis, locator) {
+  const items = [];
+  if (!pattern?.file_glob) return items;
+  const matched = await matchGlob(repoRoot, pattern.file_glob);
+  if (matched.length === 0) {
+    items.push({
+      id: `DRIFT-${randomDriftId()}`,
+      axis,
+      clause_id: clause.id,
+      severity: 'medium',
+      title: `${clause.id}.${locator} の file_glob にマッチするファイルが無い`,
+      detail: `file_glob "${pattern.file_glob}" matched 0 files`,
+      suggested_action: 'pattern.file_glob を更新するか、不要なら spec から削除する'
+    });
+    return items;
+  }
+  if (pattern.must_contain && !(await anyFileContains(repoRoot, matched, pattern.must_contain))) {
+    items.push({
+      id: `DRIFT-${randomDriftId()}`,
+      axis,
+      clause_id: clause.id,
+      severity: 'high',
+      title: `${clause.id}.${locator}.must_contain が満たされていない`,
+      detail: `must_contain "${pattern.must_contain}" が ${pattern.file_glob} のいずれにも存在しない`,
+      suggested_action: clause.type === 'invariant'
+        ? '実装が不変条件を満たしていない可能性。Code を修正するか Spec を再評価する'
+        : 'Spec と実装の整合性を確認する'
+    });
+  }
+  if (pattern.must_not_contain) {
+    const offender = await firstFileContaining(repoRoot, matched, pattern.must_not_contain);
+    if (offender) {
+      items.push({
+        id: `DRIFT-${randomDriftId()}`,
+        axis,
+        clause_id: clause.id,
+        severity: 'high',
+        title: `${clause.id}.${locator}.must_not_contain 違反`,
+        detail: `must_not_contain "${pattern.must_not_contain}" が ${offender} に存在する`,
+        suggested_action: '不変条件と矛盾する実装。Code を修正するか Spec を再評価する'
+      });
+    }
+  }
+  if (pattern.must_cover && !(await anyFileContains(repoRoot, matched, pattern.must_cover))) {
+    items.push({
+      id: `DRIFT-${randomDriftId()}`,
+      axis,
+      clause_id: clause.id,
+      severity: axis === 'spec_test' ? 'high' : 'medium',
+      title: `${clause.id}.${locator}.must_cover が満たされていない`,
+      detail: `must_cover "${pattern.must_cover}" が ${pattern.file_glob} のテストで参照されていない`,
+      suggested_action: 'テストを追加するか、clause の verifiable_by.test_pattern を見直す'
+    });
+  }
+  return items;
+}
+
+function detectCodeTestDrift(spec, fingerprint) {
+  const items = [];
+  if (!fingerprint?.test_fingerprint?.files) return items;
+  const allExpects = fingerprint.test_fingerprint.files
+    .flatMap((file) => file.cases.flatMap((entry) => entry.expects))
+    .map((entry) => entry.toLowerCase());
+  for (const branch of fingerprint.code_fingerprint?.branches ?? []) {
+    if (!branch.domain_keywords || branch.domain_keywords.length === 0) continue;
+    const condition = (branch.condition ?? '').toLowerCase();
+    if (!condition) continue;
+    const fragment = condition.split(/\s+/).find((token) => token.length >= 4) ?? condition.slice(0, 12);
+    if (!fragment) continue;
+    const covered = allExpects.some((expect) => expect.includes(fragment));
+    if (!covered) {
+      items.push({
+        id: `DRIFT-${randomDriftId()}`,
+        axis: 'code_test',
+        clause_id: null,
+        severity: 'low',
+        title: `${branch.file} の domain 分岐がテスト で参照されていない`,
+        detail: `condition "${branch.condition}" を検証している assertion / case が見当たらない`,
+        suggested_action: 'domain 分岐に対する test を追加するか、Spec を更新して分岐の意図を明示する'
+      });
+      if (items.length >= 8) return items;
+    }
+  }
+  return items;
+}
+
+async function detectSpecPrDrift(repoRoot, spec, againstRef) {
+  const items = [];
+  let stdout;
+  try {
+    const result = await execFileAsync('git', ['diff', '--name-only', againstRef, '--', '.'], {
+      cwd: repoRoot,
+      encoding: 'utf8'
+    });
+    stdout = result.stdout;
+  } catch {
+    return items;
+  }
+  const changedFiles = stdout.split('\n').map((line) => line.trim()).filter(Boolean);
+  for (const clause of spec.clauses ?? []) {
+    const referencedFiles = (clause?.origin?.code_refs ?? []).map((ref) => ref.file).filter(Boolean);
+    const touched = referencedFiles.filter((file) => changedFiles.includes(file));
+    if (touched.length === 0) continue;
+    items.push({
+      id: `DRIFT-${randomDriftId()}`,
+      axis: 'spec_pr',
+      clause_id: clause.id,
+      severity: 'medium',
+      title: `${clause.id} が参照するコードが PR で変更されている`,
+      detail: `${touched.join(', ')} が ${againstRef} と比べて変更されている。Spec の見直しが必要かもしれない`,
+      suggested_action: 'Spec を再生成 (vibepro spec fingerprint → write) し、clause の有効性を確認する'
+    });
+  }
+  return items;
+}
+
+function summarizeAxes(items) {
+  const summary = { spec_code_drift: 0, spec_test_drift: 0, code_test_drift: 0, spec_pr_drift: 0 };
+  for (const item of items) {
+    if (item.axis === 'spec_code') summary.spec_code_drift += 1;
+    else if (item.axis === 'spec_test') summary.spec_test_drift += 1;
+    else if (item.axis === 'code_test') summary.code_test_drift += 1;
+    else if (item.axis === 'spec_pr') summary.spec_pr_drift += 1;
+  }
+  return summary;
+}
+
+function applySuppressions(items, suppressions) {
+  const suppressedKeys = new Map();
+  for (const entry of suppressions.items ?? []) {
+    if (entry.expires_at && new Date(entry.expires_at) < new Date()) continue;
+    suppressedKeys.set(entry.key, entry);
+  }
+  return items.map((item) => {
+    const key = driftKey(item);
+    if (suppressedKeys.has(key)) {
+      return { ...item, severity: demoteSeverity(item.severity), suppression_applied: true };
+    }
+    return item;
+  });
+}
+
+async function updateSuppressionLedger(repoRoot, storyId, items, suppressions) {
+  const ledger = { schema_version: suppressions.schema_version ?? '0.1.0', items: [...(suppressions.items ?? [])] };
+  const now = new Date().toISOString();
+  for (const item of items) {
+    if (item.severity !== 'high') continue;
+    const key = driftKey(item);
+    const existing = ledger.items.find((entry) => entry.key === key);
+    if (!existing) {
+      ledger.items.push({ key, first_seen_at: now, ack_count: 0, expires_at: null });
+      continue;
+    }
+    existing.ack_count = (existing.ack_count ?? 0) + 1;
+    existing.last_seen_at = now;
+    if (existing.ack_count >= SUPPRESS_DEMOTE_THRESHOLD && !existing.expires_at) {
+      existing.expires_at = futureIso(30);
+      existing.demoted_at = now;
+    }
+  }
+  await writeSuppressions(repoRoot, storyId, ledger);
+}
+
+function driftKey(item) {
+  return `${item.axis}|${item.clause_id ?? ''}|${item.title}`;
+}
+
+function demoteSeverity(severity) {
+  if (severity === 'high') return 'medium';
+  if (severity === 'medium') return 'low';
+  return 'low';
+}
+
+function futureIso(days) {
+  const d = new Date();
+  d.setUTCDate(d.getUTCDate() + days);
+  return d.toISOString();
+}
+
+function emptyDrift({ storyId = null, status, reason }) {
+  return {
+    schema_version: '0.1.0',
+    story_id: storyId,
+    spec_id: null,
+    evaluated_at: new Date().toISOString(),
+    status,
+    reason,
+    summary: { spec_code_drift: 0, spec_test_drift: 0, code_test_drift: 0, spec_pr_drift: 0 },
+    items: []
+  };
+}
+
+async function fileIncludes(repoRoot, relativeFile, anchor) {
+  try {
+    const content = await readFile(path.join(repoRoot, relativeFile), 'utf8');
+    return content.includes(anchor);
+  } catch {
+    return false;
+  }
+}
+
+async function anyFileContains(repoRoot, files, needle) {
+  for (const file of files) {
+    if (await fileIncludes(repoRoot, file, needle)) return true;
+  }
+  return false;
+}
+
+async function firstFileContaining(repoRoot, files, needle) {
+  for (const file of files) {
+    if (await fileIncludes(repoRoot, file, needle)) return file;
+  }
+  return null;
+}
+
+async function statFile(repoRoot, relativeFile) {
+  try {
+    const { stat } = await import('node:fs/promises');
+    const stats = await stat(path.join(repoRoot, relativeFile));
+    return { exists: stats.isFile() };
+  } catch (error) {
+    if (error.code === 'ENOENT') return { exists: false };
+    throw error;
+  }
+}
+
+function randomDriftId() {
+  const chars = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789';
+  let id = '';
+  for (let i = 0; i < 6; i += 1) {
+    id += chars[Math.floor(Math.random() * chars.length)];
+  }
+  return id;
+}