@besales/ops-framework 0.1.0

package/bin/learning-loop.mjs

@@ -0,0 +1,658 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  getFlag,
+  parseCliArgs,
+  projectContext,
+} from './lib/check-context-utils.mjs';
+
+export const CANDIDATES_FILE = 'learning-candidates.md';
+export const INDEX_FILE = 'learning-index.json';
+export const APPROVED_FILE = 'approved-learning.md';
+export const REPORT_FILE = 'learning-report.md';
+export const REVIEW_FILE = 'learning-review.md';
+const PROJECT_PLAYBOOK_TARGET_PREFIX = 'project-playbook/';
+const MEMORY_TARGET_PREFIX = 'memory/';
+
+export function main() {
+  const command = process.argv[2];
+  const args = parseCliArgs(process.argv.slice(3));
+  try {
+    if (command === 'memory-candidates') {
+      writeMemoryCandidates({ limit: Number(getFlag(args, 'limit', 20)) });
+      return;
+    }
+    if (command === 'learning-index') {
+      writeLearningIndex();
+      return;
+    }
+    if (command === 'learning-review') {
+      writeLearningReview();
+      return;
+    }
+    if (command === 'update-memory') {
+      updateMemory({ applyApproved: args.flags.has('apply-approved') });
+      return;
+    }
+    if (command === 'learning-audit') {
+      auditLearning();
+      return;
+    }
+    if (command === 'learning-report') {
+      writeLearningReport();
+      return;
+    }
+    fail('Usage: ops-agent memory-candidates|learning-index|learning-review|update-memory|learning-audit|learning-report');
+  } catch (error) {
+    fail(error.message);
+  }
+}
+
+export function writeMemoryCandidates({ limit }) {
+  ensureMemoryRoot();
+  const candidates = collectLearningCandidates({ limit });
+  const content = [
+    '# Learning Candidates',
+    '',
+    'Generated candidates from retrospective/check/verify/task artifacts.',
+    '',
+    'Human must promote, defer or reject candidates through `learning-index.json` before memory/playbooks are updated.',
+    '',
+    ...candidates.map((candidate, index) => [
+      `## LC-${String(index + 1).padStart(3, '0')}`,
+      '',
+      `- Source: \`${candidate.source}\``,
+      `- Source artifact: \`${candidate.sourceArtifact}\``,
+      `- Reason hash: \`${candidate.reasonHash}\``,
+      `- Kind: \`${candidate.kind}\``,
+      `- Learning layer: \`${candidate.learningLayer}\``,
+      `- Confidence: \`${candidate.confidence}\``,
+      `- Problem: ${candidate.problem}`,
+      `- Lesson: ${candidate.lesson}`,
+      `- Repeat risk: ${candidate.repeatRisk}`,
+      `- Candidate: ${candidate.text}`,
+      `- Proposed wording: ${candidate.proposedWording}`,
+      `- Suggested target: \`${candidate.suggestedTarget}\``,
+      '',
+    ].join('\n')),
+  ].join('\n');
+  fs.writeFileSync(path.join(projectContext.memoryRoot, CANDIDATES_FILE), content.endsWith('\n') ? content : `${content}\n`);
+  console.log(`Learning candidates written: ${path.join(projectContext.memoryRoot, CANDIDATES_FILE)}`);
+  console.log(`- candidates: ${candidates.length}`);
+}
+
+export function writeLearningIndex() {
+  ensureMemoryRoot();
+  const candidatesPath = path.join(projectContext.memoryRoot, CANDIDATES_FILE);
+  if (!fs.existsSync(candidatesPath)) {
+    throw new Error(`Missing ${CANDIDATES_FILE}. Run ops-agent memory-candidates first.`);
+  }
+  const entries = parseLearningCandidatesMarkdown(fs.readFileSync(candidatesPath, 'utf8'))
+    .map((candidate) => ({
+      id: candidate.id,
+      source: candidate.source,
+      sourceArtifact: candidate.sourceArtifact,
+      reasonHash: candidate.reasonHash,
+      kind: candidate.kind,
+      learningLayer: candidate.learningLayer,
+      confidence: candidate.confidence,
+      problem: candidate.problem,
+      lesson: candidate.lesson,
+      repeatRisk: candidate.repeatRisk,
+      candidate: candidate.text,
+      proposedWording: candidate.proposedWording,
+      decision: 'pending',
+      target: candidate.suggestedTarget,
+      notes: '',
+    }));
+  const index = {
+    schemaVersion: 1,
+    generatedAt: new Date().toISOString(),
+    instructions: 'Human edits decision to promote/defer/reject. update-memory only applies decision=promote.',
+    entries,
+  };
+  fs.writeFileSync(path.join(projectContext.memoryRoot, INDEX_FILE), `${JSON.stringify(index, null, 2)}\n`);
+  console.log(`Learning index written: ${path.join(projectContext.memoryRoot, INDEX_FILE)}`);
+  console.log(`- entries: ${entries.length}`);
+}
+
+export function writeLearningReview({ memoryRoot = projectContext.memoryRoot, projectRoot = projectContext.projectRoot } = {}) {
+  fs.mkdirSync(memoryRoot, { recursive: true });
+  const indexPath = path.join(memoryRoot, INDEX_FILE);
+  if (!fs.existsSync(indexPath)) {
+    throw new Error(`Missing ${INDEX_FILE}. Run ops-agent learning-index first.`);
+  }
+  const index = JSON.parse(fs.readFileSync(indexPath, 'utf8'));
+  const entries = index.entries || [];
+  const pending = entries.filter((entry) => !entry.decision || entry.decision === 'pending');
+  const content = [
+    '# Learning Review',
+    '',
+    `Generated at: \`${new Date().toISOString()}\``,
+    '',
+    '## Human Approval Contract',
+    '',
+    'The framework proposes learning candidates, but a human decides what becomes durable memory or playbook guidance.',
+    '',
+    'Allowed decisions in `learning-index.json`:',
+    '',
+    '- `promote`: apply this entry with `ops-agent update-memory --apply-approved`.',
+    '- `defer`: keep for later review; do not apply now.',
+    '- `reject`: discard as noise, wrong, duplicated or too task-specific.',
+    '- `rewrite`: idea is useful, but wording/target must be edited before promotion.',
+    '',
+    'For `rewrite`, edit `proposedWording`, `target` and `notes`, then change `decision` to `promote` when ready.',
+    '',
+    'Shared playbook candidates are manual-review only and require a separate shared-framework task.',
+    '',
+    '## Review Summary',
+    '',
+    `- Learning index: \`${relativeProjectPath(indexPath, projectRoot)}\``,
+    `- Total entries: ${entries.length}`,
+    `- Pending entries: ${pending.length}`,
+    `- Already promoted: ${entries.filter((entry) => entry.decision === 'promote').length}`,
+    `- Deferred: ${entries.filter((entry) => entry.decision === 'defer').length}`,
+    `- Rejected: ${entries.filter((entry) => entry.decision === 'reject').length}`,
+    `- Rewrite needed: ${entries.filter((entry) => entry.decision === 'rewrite').length}`,
+    '',
+    '## Decision Checklist',
+    '',
+    '- Promote only lessons that are true beyond one accidental moment.',
+    '- Prefer project playbooks for concrete routes, commands, services, environments and provider quirks.',
+    '- Prefer project memory for durable architecture/product/process facts.',
+    '- Prefer shared playbook manual review only for generic cross-project rules.',
+    '- Reject raw logs, duplicate JSON fields, vague reminders and already-covered rules.',
+    '',
+    '## Pending Decisions',
+    '',
+    ...renderReviewEntries(pending),
+    '',
+  ].join('\n');
+  fs.writeFileSync(path.join(memoryRoot, REVIEW_FILE), content.endsWith('\n') ? content : `${content}\n`);
+  console.log(`Learning review written: ${path.join(memoryRoot, REVIEW_FILE)}`);
+  console.log(`- pending: ${pending.length}`);
+}
+
+export function updateMemory({ applyApproved }) {
+  ensureMemoryRoot();
+  if (!applyApproved) {
+    console.log('No changes applied. Re-run with --apply-approved after human edits learning-index.json.');
+    return;
+  }
+  const indexPath = path.join(projectContext.memoryRoot, INDEX_FILE);
+  if (!fs.existsSync(indexPath)) {
+    throw new Error(`Missing ${INDEX_FILE}. Run ops-agent learning-index first.`);
+  }
+  const index = JSON.parse(fs.readFileSync(indexPath, 'utf8'));
+  const approved = (index.entries || []).filter((entry) => entry.decision === 'promote');
+  if (!approved.length) {
+    console.log('No approved learning entries to apply.');
+    return;
+  }
+  const byTarget = groupApprovedByTarget(approved);
+  for (const [target, entries] of byTarget.entries()) {
+    const targetPath = resolveApprovedTarget(target);
+    const previous = fs.existsSync(targetPath) ? fs.readFileSync(targetPath, 'utf8').trimEnd() : buildInitialTargetContent(target);
+    const addition = entries.map((entry) => formatApprovedEntry(entry)).join('\n');
+    fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+    fs.writeFileSync(targetPath, `${previous}\n${addition}\n`);
+    console.log(`Approved learning appended: ${targetPath}`);
+  }
+  console.log(`- applied: ${approved.length}`);
+  writeLearningReport();
+}
+
+export function auditLearning() {
+  ensureMemoryRoot();
+  const indexPath = path.join(projectContext.memoryRoot, INDEX_FILE);
+  if (!fs.existsSync(indexPath)) {
+    console.log('Learning audit: no learning-index.json found.');
+    return;
+  }
+  const index = JSON.parse(fs.readFileSync(indexPath, 'utf8'));
+  const counts = {};
+  for (const entry of index.entries || []) {
+    counts[entry.decision] = (counts[entry.decision] || 0) + 1;
+  }
+  console.log('Learning audit');
+  console.log(`- total: ${(index.entries || []).length}`);
+  for (const [decision, count] of Object.entries(counts)) {
+    console.log(`- ${decision}: ${count}`);
+  }
+  console.log(`- report: ${path.join(projectContext.memoryRoot, REPORT_FILE)}`);
+}
+
+export function writeLearningReport({ memoryRoot = projectContext.memoryRoot, projectRoot = projectContext.projectRoot } = {}) {
+  fs.mkdirSync(memoryRoot, { recursive: true });
+  const indexPath = path.join(memoryRoot, INDEX_FILE);
+  const candidatesPath = path.join(memoryRoot, CANDIDATES_FILE);
+  const index = fs.existsSync(indexPath)
+    ? JSON.parse(fs.readFileSync(indexPath, 'utf8'))
+    : { entries: [] };
+  const entries = index.entries || [];
+  const counts = countBy(entries, (entry) => entry.decision || 'pending');
+  const targetCounts = countBy(entries, (entry) => entry.target || 'memory/approved-learning.md');
+  const promoted = entries.filter((entry) => entry.decision === 'promote');
+  const pending = entries.filter((entry) => !entry.decision || entry.decision === 'pending');
+  const content = [
+    '# Learning Report',
+    '',
+    `Generated at: \`${new Date().toISOString()}\``,
+    '',
+    '## Summary',
+    '',
+    `- Candidates file: \`${relativeProjectPath(candidatesPath, projectRoot)}\``,
+    `- Learning index: \`${relativeProjectPath(indexPath, projectRoot)}\``,
+    `- Learning review: \`${relativeProjectPath(path.join(memoryRoot, REVIEW_FILE), projectRoot)}\``,
+    `- Total entries: ${entries.length}`,
+    `- Pending human decisions: ${pending.length}`,
+    `- Promoted entries: ${promoted.length}`,
+    `- Deferred entries: ${counts.defer || 0}`,
+    `- Rejected entries: ${counts.reject || 0}`,
+    '',
+    '## Decisions By Target',
+    '',
+    ...Object.entries(targetCounts).map(([target, count]) => `- \`${target}\`: ${count}`),
+    ...(Object.keys(targetCounts).length ? [] : ['- No learning targets yet.']),
+    '',
+    '## Promoted Learning',
+    '',
+    ...renderReportEntries(promoted),
+    '',
+    '## Pending Review',
+    '',
+    ...renderReportEntries(pending),
+    '',
+    '## Closeout Visibility',
+    '',
+    '- Run `ops-agent memory-candidates` after retrospective/check/verify feedback is complete.',
+    '- Run `ops-agent learning-index` to create human-reviewable decisions.',
+    '- Run `ops-agent learning-review` to create a human-readable approval pack.',
+    '- Edit `learning-index.json`: set each useful entry to `promote`, `defer` or `reject`.',
+    '- Run `ops-agent update-memory --apply-approved` to write approved entries into project memory or project playbooks.',
+    '- Re-run `ops-agent learning-report` and show this report during closeout.',
+    '',
+  ].join('\n');
+  fs.writeFileSync(path.join(memoryRoot, REPORT_FILE), content.endsWith('\n') ? content : `${content}\n`);
+  console.log(`Learning report written: ${path.join(memoryRoot, REPORT_FILE)}`);
+}
+
+export function collectLearningCandidates({ limit, tasksRoot = projectContext.tasksRoot } = {}) {
+  const candidates = [];
+  const seen = new Set();
+  if (!fs.existsSync(tasksRoot)) {
+    return candidates;
+  }
+  const taskDirs = fs.readdirSync(tasksRoot)
+    .filter((name) => name.startsWith('TASK-'))
+    .sort()
+    .reverse();
+  for (const taskName of taskDirs) {
+    for (const fileName of ['retrospective.md', 'feedback.md', 'execution-feedback.md', 'verify.md', 'check.md']) {
+      const sourceArtifact = `${taskName}/${fileName}`;
+      const filePath = path.join(tasksRoot, taskName, fileName);
+      if (!fs.existsSync(filePath)) {
+        continue;
+      }
+      const lines = fs.readFileSync(filePath, 'utf8').split(/\r?\n/);
+      for (const line of lines) {
+        const normalized = normalizeCandidateText(line);
+        if (!isLearningCandidateLine(normalized)) {
+          continue;
+        }
+        if (normalized.length < 20) {
+          continue;
+        }
+        const reasonHash = learningReasonHash(normalized);
+        if (seen.has(reasonHash)) {
+          continue;
+        }
+        seen.add(reasonHash);
+        candidates.push(buildLearningCard({
+          source: sourceArtifact,
+          sourceArtifact,
+          reasonHash,
+          text: normalized,
+        }));
+        if (candidates.length >= limit) {
+          return candidates;
+        }
+      }
+    }
+  }
+  return candidates;
+}
+
+export function parseLearningCandidatesMarkdown(content) {
+  const entries = [];
+  const sections = content.split(/^##\s+/m).slice(1);
+  for (const section of sections) {
+    const [rawId, ...bodyLines] = section.split('\n');
+    const body = bodyLines.join('\n');
+    const id = rawId.trim();
+    const source = readMarkdownField(body, 'Source');
+    const sourceArtifact = readMarkdownField(body, 'Source artifact') || source;
+    const reasonHash = readMarkdownField(body, 'Reason hash') || learningReasonHash(readMarkdownField(body, 'Candidate'));
+    const kind = readMarkdownField(body, 'Kind') || classifyLearningKind(readMarkdownField(body, 'Candidate'));
+    const learningLayer = readMarkdownField(body, 'Learning layer') || learningLayerForKind(kind);
+    const confidence = readMarkdownField(body, 'Confidence') || confidenceForCandidate(readMarkdownField(body, 'Candidate'));
+    const problem = readMarkdownField(body, 'Problem') || summarizeProblem(readMarkdownField(body, 'Candidate'));
+    const lesson = readMarkdownField(body, 'Lesson') || summarizeLesson(readMarkdownField(body, 'Candidate'));
+    const repeatRisk = readMarkdownField(body, 'Repeat risk') || summarizeRepeatRisk(readMarkdownField(body, 'Candidate'));
+    const text = readMarkdownField(body, 'Candidate');
+    const proposedWording = readMarkdownField(body, 'Proposed wording') || proposeLearningWording(text, kind);
+    const suggestedTarget = readMarkdownField(body, 'Suggested target') || suggestLearningTarget(text);
+    if (!id || !source || !text) {
+      continue;
+    }
+    entries.push({
+      id,
+      source,
+      sourceArtifact,
+      reasonHash,
+      kind,
+      learningLayer,
+      confidence,
+      problem,
+      lesson,
+      repeatRisk,
+      text,
+      proposedWording,
+      suggestedTarget,
+    });
+  }
+  return entries;
+}
+
+export function buildLearningCard({ source, sourceArtifact, reasonHash, text }) {
+  const kind = classifyLearningKind(text);
+  return {
+    source,
+    sourceArtifact,
+    reasonHash,
+    kind,
+    learningLayer: learningLayerForKind(kind),
+    confidence: confidenceForCandidate(text),
+    problem: summarizeProblem(text),
+    lesson: summarizeLesson(text),
+    repeatRisk: summarizeRepeatRisk(text),
+    text,
+    proposedWording: proposeLearningWording(text, kind),
+    suggestedTarget: suggestLearningTarget(text),
+  };
+}
+
+export function normalizeCandidateText(line) {
+  return line
+    .replace(/^[-*]\s*/, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+export function learningReasonHash(text) {
+  return crypto.createHash('sha256').update(text.toLowerCase()).digest('hex').slice(0, 16);
+}
+
+function isLearningCandidateLine(text) {
+  if (isLearningMetadataLine(text)) {
+    return false;
+  }
+  return /(memory|playbook|learning|повтор|вывод|стоит|нужно|should|must|route|provider|deploy|rollout|acceptance|gate)/i.test(text);
+}
+
+function isLearningMetadataLine(text) {
+  return /^(classification|rationale|requires new human gate|requires research refresh|requires plan refresh|supervisor decision|created at|event id|source|source artifact|reason hash|kind|learning layer|confidence|problem|lesson|repeat risk|suggested target):/i.test(text)
+    || /^"[^"]+"\s*:/i.test(text)
+    || /^"?classification"?\s*:/i.test(text)
+    || /^"?requires[A-Za-z\s]*"?\s*:/i.test(text);
+}
+
+function classifyLearningKind(text) {
+  if (/(shared|cross-project|reusable|generic|across projects|общ(ий|ая)|переиспольз)/i.test(text)) {
+    return 'shared-playbook-candidate';
+  }
+  if (/(playbook|route|scenario|acceptance|rollout|deploy|provider|source sync|source-sync|worker|backfill|replay)/i.test(text)) {
+    return 'project-playbook-candidate';
+  }
+  return 'project-memory-candidate';
+}
+
+function learningLayerForKind(kind) {
+  if (kind === 'shared-playbook-candidate') {
+    return 'shared-playbook-manual-review';
+  }
+  if (kind === 'project-playbook-candidate') {
+    return 'project-playbook-overlay';
+  }
+  return 'project-memory';
+}
+
+function confidenceForCandidate(text) {
+  if (/(must|обязан|нельзя|hard gate|block|regression|повтор|again|снова)/i.test(text)) {
+    return 'high';
+  }
+  if (/(should|нужно|стоит|лучше|важно|missing|risk)/i.test(text)) {
+    return 'medium';
+  }
+  return 'low';
+}
+
+function summarizeProblem(text) {
+  if (/(повтор|again|снова|regression)/i.test(text)) {
+    return 'A repeated issue or regression risk was observed in task artifacts.';
+  }
+  if (/(feedback|фидбэк|memory|памят|learning|ретроспектив)/i.test(text)) {
+    return 'A process observation should be preserved so future tasks do not lose useful context.';
+  }
+  if (/(playbook|acceptance|route|provider|rollout|deploy|worker|gate)/i.test(text)) {
+    return 'A reusable procedure or checklist gap was identified.';
+  }
+  return 'A task artifact contains a potentially reusable lesson.';
+}
+
+function summarizeLesson(text) {
+  if (/(optimization|оптим|n\+1|repeated scan|o\(n\^2\)|complexity)/i.test(text)) {
+    return 'Future plans should include a bounded optimization review before implementation on similar hot paths.';
+  }
+  if (/(feedback|фидбэк)/i.test(text)) {
+    return 'User feedback must be captured as a first-class learning source at any task stage.';
+  }
+  if (/(ui|route|acceptance|browser|visible)/i.test(text)) {
+    return 'Future UI-visible work should carry concrete acceptance scenarios and project-specific route coverage.';
+  }
+  if (/(provider|source sync|source-sync|ingestion|pagination|rate limit|oauth)/i.test(text)) {
+    return 'Future provider/source-sync work should reuse explicit idempotency, retry and parity checks.';
+  }
+  if (/(production|rollout|deploy|runtime|environment)/i.test(text)) {
+    return 'Future production-runtime work should include rollout, rollback and post-deploy evidence.';
+  }
+  return 'Preserve the lesson and review it before similar future work.';
+}
+
+function summarizeRepeatRisk(text) {
+  if (/(must|обязан|нельзя|hard gate|block|regression|повтор|again|снова)/i.test(text)) {
+    return 'high: likely to repeat or cause a gate failure if not captured.';
+  }
+  if (/(should|нужно|стоит|важно|missing|risk)/i.test(text)) {
+    return 'medium: useful for reducing future rework.';
+  }
+  return 'low: keep for review, but do not promote without human confirmation.';
+}
+
+function proposeLearningWording(text, kind) {
+  const prefix = kind === 'project-playbook-candidate'
+    ? 'Project playbook rule'
+    : kind === 'shared-playbook-candidate'
+      ? 'Shared playbook candidate'
+      : 'Project memory note';
+  return `${prefix}: ${text}`;
+}
+
+function suggestLearningTarget(text) {
+  const kind = classifyLearningKind(text);
+  if (kind === 'shared-playbook-candidate') {
+    return 'shared-playbook/manual-review';
+  }
+  if (kind === 'project-playbook-candidate') {
+    if (/(ui|route|visible|acceptance|screen|browser)/i.test(text)) {
+      return `${PROJECT_PLAYBOOK_TARGET_PREFIX}ui-acceptance.md`;
+    }
+    if (/(source sync|source-sync|provider|ingestion|pagination|rate limit|oauth)/i.test(text)) {
+      return `${PROJECT_PLAYBOOK_TARGET_PREFIX}source-sync-provider.md`;
+    }
+    if (/(production|rollout|deploy|runtime|environment)/i.test(text)) {
+      return `${PROJECT_PLAYBOOK_TARGET_PREFIX}production-rollout.md`;
+    }
+    return `${PROJECT_PLAYBOOK_TARGET_PREFIX}project-notes.md`;
+  }
+  return `${MEMORY_TARGET_PREFIX}${APPROVED_FILE}`;
+}
+
+function readMarkdownField(body, fieldName) {
+  const pattern = new RegExp(`^- ${escapeRegExp(fieldName)}: (.*)$`, 'm');
+  const match = pattern.exec(body);
+  if (!match) {
+    return '';
+  }
+  return match[1].replace(/^`|`$/g, '').trim();
+}
+
+function ensureMemoryRoot() {
+  fs.mkdirSync(projectContext.memoryRoot, { recursive: true });
+}
+
+function groupApprovedByTarget(entries) {
+  const byTarget = new Map();
+  for (const entry of entries) {
+    const target = entry.target || `${MEMORY_TARGET_PREFIX}${APPROVED_FILE}`;
+    const current = byTarget.get(target) || [];
+    current.push(entry);
+    byTarget.set(target, current);
+  }
+  return byTarget;
+}
+
+function resolveApprovedTarget(target) {
+  if (target === 'shared-playbook' || target.startsWith('shared-playbook/')) {
+    throw new Error('shared-playbook promotion is manual; copy approved entries into the shared package through a reviewed task.');
+  }
+  if (target === 'project-playbook') {
+    throw new Error(`Project playbook target must include a file name, for example ${PROJECT_PLAYBOOK_TARGET_PREFIX}ui-acceptance.md.`);
+  }
+  if (target === 'memory') {
+    return path.join(projectContext.memoryRoot, APPROVED_FILE);
+  }
+  if (target.startsWith(MEMORY_TARGET_PREFIX)) {
+    return safeProjectRelativeTarget(projectContext.memoryRoot, target.slice(MEMORY_TARGET_PREFIX.length));
+  }
+  if (target.startsWith(PROJECT_PLAYBOOK_TARGET_PREFIX)) {
+    if (!projectContext.projectPlaybooksRoot) {
+      throw new Error('Project playbooks root is not configured in ops.playbooksDir.');
+    }
+    return safeProjectRelativeTarget(projectContext.projectPlaybooksRoot, target.slice(PROJECT_PLAYBOOK_TARGET_PREFIX.length));
+  }
+  if (target === 'defer') {
+    throw new Error('Promoted entries cannot target defer.');
+  }
+  throw new Error(`Unsupported learning target: ${target}`);
+}
+
+function safeProjectRelativeTarget(root, relativeTarget) {
+  if (!relativeTarget || path.isAbsolute(relativeTarget) || relativeTarget.split(/[\\/]+/).includes('..')) {
+    throw new Error(`Unsafe learning target path: ${relativeTarget || '<missing>'}`);
+  }
+  return path.join(root, relativeTarget);
+}
+
+function buildInitialTargetContent(target) {
+  const title = target.startsWith(PROJECT_PLAYBOOK_TARGET_PREFIX)
+    ? '# Project Playbook Learning'
+    : '# Approved Learning';
+  return `${title}\n`;
+}
+
+function formatApprovedEntry(entry) {
+  return [
+    '',
+    `## ${entry.id}`,
+    '',
+    `- Target: \`${entry.target}\``,
+    `- Source: \`${entry.source}\``,
+    `- Confidence: \`${entry.confidence || 'unknown'}\``,
+    `- Problem: ${entry.problem || 'Not specified.'}`,
+    `- Lesson: ${entry.lesson || 'Not specified.'}`,
+    `- Repeat risk: ${entry.repeatRisk || 'Not specified.'}`,
+    `- Learning: ${entry.proposedWording || entry.candidate}`,
+    entry.notes ? `- Notes: ${entry.notes}` : '',
+  ].filter(Boolean).join('\n');
+}
+
+function countBy(entries, readKey) {
+  const counts = {};
+  for (const entry of entries) {
+    const key = readKey(entry);
+    counts[key] = (counts[key] || 0) + 1;
+  }
+  return counts;
+}
+
+function renderReportEntries(entries) {
+  if (!entries.length) {
+    return ['- None.'];
+  }
+  return entries.flatMap((entry) => [
+    `### ${entry.id}`,
+    '',
+    `- Decision: \`${entry.decision || 'pending'}\``,
+    `- Target: \`${entry.target || 'memory/approved-learning.md'}\``,
+    `- Source: \`${entry.sourceArtifact || entry.source}\``,
+    `- Kind: \`${entry.kind || 'unknown'}\``,
+    `- Confidence: \`${entry.confidence || 'unknown'}\``,
+    `- Problem: ${entry.problem || 'Not specified.'}`,
+    `- Lesson: ${entry.lesson || 'Not specified.'}`,
+    `- Proposed wording: ${entry.proposedWording || entry.candidate}`,
+    '',
+  ]);
+}
+
+function renderReviewEntries(entries) {
+  if (!entries.length) {
+    return ['- None.'];
+  }
+  return entries.flatMap((entry) => [
+    `### ${entry.id}`,
+    '',
+    `- Source: \`${entry.sourceArtifact || entry.source}\``,
+    `- Current decision: \`${entry.decision || 'pending'}\``,
+    `- Suggested target: \`${entry.target || 'memory/approved-learning.md'}\``,
+    `- Kind: \`${entry.kind || 'unknown'}\``,
+    `- Learning layer: \`${entry.learningLayer || learningLayerForKind(entry.kind)}\``,
+    `- Confidence: \`${entry.confidence || 'unknown'}\``,
+    `- Repeat risk: ${entry.repeatRisk || 'Not specified.'}`,
+    `- Problem: ${entry.problem || 'Not specified.'}`,
+    `- Lesson: ${entry.lesson || 'Not specified.'}`,
+    `- Proposed wording: ${entry.proposedWording || entry.candidate}`,
+    '',
+    'Decision to set in `learning-index.json`: `promote | defer | reject | rewrite`',
+    '',
+  ]);
+}
+
+function relativeProjectPath(filePath, projectRoot = projectContext.projectRoot) {
+  return path.relative(projectRoot, filePath) || path.basename(filePath);
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function fail(message) {
+  console.error(`Error: ${message}`);
+  process.exit(1);
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1])) {
+  main();
+}