@besales/ops-framework 0.1.0

package/bin/lib/llm-input-pack-utils.mjs

@@ -0,0 +1,663 @@
+import path from 'node:path';
+import {
+  normalizeHeading,
+  parseMarkdownSections,
+  readRelevantPlaybooks,
+  readJsonFile,
+  readTaskFile,
+  renderRelevantPlaybooks,
+} from './check-context-utils.mjs';
+
+export const LLM_CONTEXT_MODES = ['fast', 'standard', 'strict'];
+export const LLM_CONTEXT_CAPS = {
+  fast: 8000,
+  standard: 20000,
+  strict: 45000,
+};
+
+const TOKEN_ESTIMATE_CHARS_PER_TOKEN = 1.8;
+const PACK_CAP_SAFETY_MULTIPLIER = 1.15;
+const MEMORY_MAX_CHARS = {
+  fast: 3000,
+  standard: 3500,
+  strict: Infinity,
+};
+
+const STRICT_TRIGGER_PATTERNS = [
+  'auth-security',
+  'prisma-schema',
+  'production-runtime',
+  'source-sync-provider',
+];
+
+const CHECK_RELEVANT_SECTIONS = [
+  'цель',
+  'goal',
+  'опора на research',
+  'допущения',
+  'assumptions',
+  'затронутые модули и файлы',
+  'risk tier and execution budget',
+  'ui acceptance scenarios',
+  'complexity / performance budget',
+  'production rollout gate',
+  'source sync / provider gate',
+  'checker context hints',
+  'шаги реализации',
+  'риски и открытые вопросы',
+  'verification plan',
+  'план проверки',
+  'что требует human approval',
+];
+
+const VERIFY_PLAN_SECTIONS = [
+  'цель',
+  'goal',
+  'допущения',
+  'затронутые модули и файлы',
+  'risk tier and execution budget',
+  'ui acceptance scenarios',
+  'complexity / performance budget',
+  'production rollout gate',
+  'source sync / provider gate',
+  'шаги реализации',
+  'риски и открытые вопросы',
+  'verification plan',
+  'план проверки',
+  'что требует human approval',
+];
+
+const VERIFY_EXECUTION_SECTIONS = [
+  'краткое summary',
+  'risk tier / execution budget used',
+  'planned item coverage',
+  'preflight evidence',
+  'execution ledger',
+  'измененные файлы',
+  'запущенные команды',
+  'micro-verify evidence',
+  'slice-verify evidence',
+  'ui acceptance evidence',
+  'complexity / performance evidence',
+  'production rollout evidence',
+  'source sync / provider evidence',
+  'отклонения от плана',
+  'explicit non-actions',
+  'блокеры',
+  'follow-up notes',
+];
+
+const SECTION_ALIASES = new Map([
+  ['goal', ['goal', 'цель']],
+  ['scope', ['scope', 'затронутые модули и файлы', 'affected modules and files']],
+  ['success criteria', ['success criteria', 'acceptance criteria', 'критерии успеха']],
+  ['findings', ['findings', 'finding', 'опора на research', 'опора на findings из research']],
+  ['evidence', ['evidence', 'repo evidence', 'доказательства']],
+  ['repo', ['repo', 'repository', 'repo context']],
+  ['architecture', ['architecture', 'архитектура']],
+  ['standards', ['standards', 'global standards alignment', 'standards alignment']],
+  ['допущения', ['допущения', 'assumptions']],
+  ['assumptions', ['assumptions', 'допущения']],
+  ['risk tier and execution budget', ['risk tier and execution budget', 'execution budget']],
+  ['ui acceptance scenarios', ['ui acceptance scenarios', 'ui acceptance', 'ui scenarios']],
+  ['complexity / performance budget', ['complexity / performance budget', 'complexity performance budget', 'performance budget', 'complexity budget']],
+  ['production rollout gate', ['production rollout gate', 'production rollout', 'rollout gate', 'deployment gate']],
+  ['source sync / provider gate', ['source sync / provider gate', 'source sync provider gate', 'source sync gate', 'provider gate']],
+  ['checker context hints', ['checker context hints', 'checker context']],
+  ['шаги реализации', ['шаги реализации', 'implementation steps', 'implementation slices', 'реализация']],
+  ['риски и открытые вопросы', ['риски и открытые вопросы', 'known risks', 'open questions', 'risks']],
+  ['verification plan', ['verification plan', 'verification and replay plan', 'план проверки']],
+  ['план проверки', ['план проверки', 'verification plan']],
+  ['что требует human approval', ['что требует human approval', 'human approval']],
+  ['краткое summary', ['краткое summary', 'summary']],
+  ['risk tier / execution budget used', ['risk tier / execution budget used', 'execution budget used']],
+  ['planned item coverage', ['planned item coverage']],
+  ['preflight evidence', ['preflight evidence']],
+  ['execution ledger', ['execution ledger']],
+  ['измененные файлы', ['измененные файлы', 'changed files']],
+  ['запущенные команды', ['запущенные команды', 'commands run']],
+  ['micro-verify evidence', ['micro-verify evidence']],
+  ['slice-verify evidence', ['slice-verify evidence']],
+  ['ui acceptance evidence', ['ui acceptance evidence']],
+  ['complexity / performance evidence', ['complexity / performance evidence', 'performance evidence']],
+  ['production rollout evidence', ['production rollout evidence', 'rollout evidence']],
+  ['source sync / provider evidence', ['source sync / provider evidence', 'source sync evidence', 'provider evidence']],
+  ['отклонения от плана', ['отклонения от плана', 'deviations from plan']],
+  ['explicit non-actions', ['explicit non-actions']],
+  ['блокеры', ['блокеры', 'blockers']],
+  ['follow-up notes', ['follow-up notes']],
+  ['verdict', ['verdict']],
+  ['residual risks', ['residual risks']],
+  ['recommended next step', ['recommended next step']],
+]);
+
+const PROTECTED_SECTIONS = new Set([
+  'verification plan',
+  'план проверки',
+  'ui acceptance scenarios',
+  'complexity / performance budget',
+  'production rollout gate',
+  'source sync / provider gate',
+  'измененные файлы',
+  'changed files',
+  'запущенные команды',
+  'commands run',
+  'micro-verify evidence',
+  'slice-verify evidence',
+  'ui acceptance evidence',
+  'complexity / performance evidence',
+  'production rollout evidence',
+  'source sync / provider evidence',
+  'блокеры',
+  'blockers',
+]);
+
+export function resolveLlmContextMode({ requestedMode, riskTriggers = [] } = {}) {
+  const requested = normalizeLlmContextMode(requestedMode);
+  if (requested) {
+    return requested;
+  }
+  return riskTriggers.some((trigger) => STRICT_TRIGGER_PATTERNS.includes(trigger))
+    ? 'strict'
+    : 'standard';
+}
+
+export function normalizeLlmContextMode(value) {
+  const normalized = String(value || '').trim().toLowerCase();
+  return LLM_CONTEXT_MODES.includes(normalized) ? normalized : null;
+}
+
+export function nextLlmContextMode(mode) {
+  if (mode === 'fast') {
+    return 'standard';
+  }
+  if (mode === 'standard') {
+    return 'strict';
+  }
+  return null;
+}
+
+export function estimateTokens(value) {
+  return Math.ceil(String(value || '').length / TOKEN_ESTIMATE_CHARS_PER_TOKEN);
+}
+
+export function estimatePayload(value) {
+  const serialized = typeof value === 'string' ? value : JSON.stringify(value, null, 2);
+  return {
+    bytes: Buffer.byteLength(serialized, 'utf8'),
+    estimatedTokens: estimateTokens(serialized),
+  };
+}
+
+export function buildCheckerLlmInputPack({
+  taskDir,
+  taskId,
+  checkerPromptSha,
+  cacheKey,
+  checkContext,
+  checkEvidence,
+  checkerContextPack,
+  taskManifest,
+  projectMemory,
+  mode = 'standard',
+}) {
+  const selectedMode = normalizeLlmContextMode(mode) || 'standard';
+  const artifacts = selectedMode === 'strict'
+    ? readArtifacts(taskDir, ['brief.md', 'research.md', 'plan.md', 'status.md', 'feedback.md', 'execution-feedback.md'], 'full')
+    : {
+        'brief.md': compactArtifact(taskDir, 'brief.md', selectedMode, ['goal', 'scope', 'success criteria']),
+        'research.md': compactArtifact(taskDir, 'research.md', selectedMode, ['findings', 'evidence', 'repo', 'architecture', 'standards']),
+        'plan.md': compactArtifact(taskDir, 'plan.md', selectedMode, CHECK_RELEVANT_SECTIONS),
+        'status.md': compactStatus(readTaskFile(taskDir, 'status.md')),
+        'feedback.md': compactArtifact(taskDir, 'feedback.md', selectedMode, ['feedback event', 'classification', 'supervisor decision']),
+      };
+
+  const input = {
+    taskId,
+    checkerPromptSha,
+    cacheKey,
+    checkContext: selectedMode === 'strict' ? checkContext : compactCheckContext(checkContext, selectedMode),
+    llmInputPolicy: {
+      stage: 'check',
+      mode: selectedMode,
+      capTokens: LLM_CONTEXT_CAPS[selectedMode],
+      fullContextAvailableViaStrict: selectedMode !== 'strict',
+      contextInsufficientFallback: selectedMode === 'strict' ? 'stop_and_report' : `rerun_${nextLlmContextMode(selectedMode)}`,
+    },
+    checkEvidence: compactGeneratedMarkdown('check-evidence.md', checkEvidence, selectedMode, { fast: 2800, standard: 4000 }),
+    checkerContextPack: compactGeneratedMarkdown('checker-context-pack.md', checkerContextPack, selectedMode, { fast: 3300, standard: 4600 }),
+    relevantPlaybooks: selectedMode === 'strict'
+      ? renderRelevantPlaybooks(readRelevantPlaybooks(checkContext.riskTriggers || []), { mode: 'strict' })
+      : renderRelevantPlaybooks(readRelevantPlaybooks(checkContext.riskTriggers || []), { mode: 'compact' }),
+    taskManifest,
+    projectMemory: compactProjectMemory(projectMemory, selectedMode),
+    taskArtifacts: artifacts,
+    outputContract: {
+      checkMarkdown: 'Markdown for check.md',
+      checkResultJson: {
+        taskId,
+        stage: 'Check',
+        checkerProvider: 'filled by runner',
+        checkerModel: 'filled by runner',
+        planSha: checkContext.planSha,
+        memorySha: checkContext.memorySha,
+        riskProfile: checkContext.riskProfile,
+        verdict: 'return_to_plan | ready_for_human_gate | human_arbitration_required | context_insufficient | checker_failed',
+        failureReason: null,
+        findings: [],
+        readyForHumanGate: false,
+      },
+    },
+  };
+
+  return withPackMetadata(input, selectedMode);
+}
+
+export function buildVerifierLlmInputPack({
+  taskDir,
+  taskId,
+  planSha,
+  executionSha,
+  verifier,
+  mode = 'standard',
+}) {
+  const selectedMode = normalizeLlmContextMode(mode) || 'standard';
+  const taskArtifacts = selectedMode === 'strict'
+    ? readArtifacts(taskDir, [
+        'brief.md',
+        'research.md',
+        'plan.md',
+        'task-manifest.json',
+        'check.result.json',
+        'check.md',
+        'check-resolution.md',
+        'human-gate-summary.md',
+        'execution.md',
+        'execution-ledger.json',
+        'verify.md',
+        'status.md',
+        'feedback.md',
+        'execution-feedback.md',
+        'orchestration-log.md',
+      ], 'full')
+    : {
+        'brief.md': compactArtifact(taskDir, 'brief.md', selectedMode, ['goal', 'scope', 'success criteria']),
+        'research.md': compactArtifact(taskDir, 'research.md', selectedMode, ['findings', 'evidence', 'repo']),
+        'plan.md': compactArtifact(taskDir, 'plan.md', selectedMode, VERIFY_PLAN_SECTIONS),
+        'task-manifest.json': readTaskFile(taskDir, 'task-manifest.json'),
+        'check.result.json': readTaskFile(taskDir, 'check.result.json'),
+        'check.md': compactCheckMarkdown({
+          checkMarkdown: readTaskFile(taskDir, 'check.md'),
+          checkResult: readOptionalJson(taskDir, 'check.result.json'),
+          mode: selectedMode,
+        }),
+        'check-resolution.md': truncateMiddle(readTaskFile(taskDir, 'check-resolution.md'), charLimitForMode(selectedMode, 1500, 3500)),
+        'human-gate-summary.md': truncateMiddle(readTaskFile(taskDir, 'human-gate-summary.md'), charLimitForMode(selectedMode, 1200, 2500)),
+        'execution.md': compactArtifact(taskDir, 'execution.md', selectedMode, VERIFY_EXECUTION_SECTIONS),
+        'execution-ledger.json': readTaskFile(taskDir, 'execution-ledger.json'),
+        'verify.md': compactArtifact(taskDir, 'verify.md', selectedMode, ['verdict', 'findings', 'residual risks', 'recommended next step']),
+        'status.md': compactStatus(readTaskFile(taskDir, 'status.md')),
+        'feedback.md': compactArtifact(taskDir, 'feedback.md', selectedMode, ['feedback event', 'classification', 'supervisor decision']),
+        'orchestration-log.md': compactOrchestrationLog(readTaskFile(taskDir, 'orchestration-log.md'), selectedMode),
+      };
+  const riskTriggers = readOptionalJson(taskDir, 'task-manifest.json')?.context?.riskTriggers || [];
+
+  const input = {
+    taskId,
+    planSha,
+    executionSha,
+    verifier,
+    llmInputPolicy: {
+      stage: 'verify',
+      mode: selectedMode,
+      capTokens: LLM_CONTEXT_CAPS[selectedMode],
+      fullContextAvailableViaStrict: selectedMode !== 'strict',
+      contextInsufficientFallback: selectedMode === 'strict' ? 'stop_and_report' : `rerun_${nextLlmContextMode(selectedMode)}`,
+    },
+    relevantPlaybooks: selectedMode === 'strict'
+      ? renderRelevantPlaybooks(readRelevantPlaybooks(riskTriggers), { mode: 'strict' })
+      : renderRelevantPlaybooks(readRelevantPlaybooks(riskTriggers), { mode: 'compact' }),
+    taskArtifacts,
+  };
+
+  return withPackMetadata(input, selectedMode);
+}
+
+export function isContextInsufficientResult(result) {
+  return result?.verdict === 'context_insufficient'
+    || result?.failureReason === 'context_insufficient';
+}
+
+export function buildContextModeSequence(initialMode) {
+  const modes = [normalizeLlmContextMode(initialMode) || 'standard'];
+  let current = modes[0];
+  while (current && current !== 'strict') {
+    current = nextLlmContextMode(current);
+    if (current) {
+      modes.push(current);
+    }
+  }
+  return modes;
+}
+
+export function summarizePackForConsole(pack) {
+  return [
+    `- llmInputMode: ${pack.meta.mode}`,
+    `- estimatedInputTokens: ${pack.meta.estimatedTokens}`,
+    `- capTokens: ${pack.meta.capTokens}`,
+    `- compactedArtifacts: ${pack.meta.compactedArtifacts.join(', ') || 'none'}`,
+  ];
+}
+
+function withPackMetadata(input, mode) {
+  const serialized = JSON.stringify(input, null, 2);
+  const compactedArtifacts = Object.entries(input.taskArtifacts || {})
+    .filter(([, value]) => isCompactedArtifact(value))
+    .map(([fileName]) => fileName);
+  return {
+    input,
+    meta: {
+      mode,
+      capTokens: LLM_CONTEXT_CAPS[mode],
+      bytes: Buffer.byteLength(serialized, 'utf8'),
+      estimatedTokens: estimateTokens(serialized),
+      compactedArtifacts,
+      overCap: estimateTokens(serialized) * PACK_CAP_SAFETY_MULTIPLIER > LLM_CONTEXT_CAPS[mode],
+      safetyMultiplier: PACK_CAP_SAFETY_MULTIPLIER,
+    },
+  };
+}
+
+function readArtifacts(taskDir, fileNames, delivery) {
+  return Object.fromEntries(fileNames.map((fileName) => [
+    fileName,
+    delivery === 'full'
+      ? readTaskFile(taskDir, fileName)
+      : compactArtifact(taskDir, fileName, 'standard', []),
+  ]));
+}
+
+function compactArtifact(taskDir, fileName, mode, sectionNames) {
+  const content = readTaskFile(taskDir, fileName);
+  if (!content.trim()) {
+    return '';
+  }
+  const maxChars = charLimitForMode(mode, 2500, 7000);
+  const compacted = compactMarkdownSections(content, sectionNames, maxChars);
+  return markCompacted(fileName, content, compacted);
+}
+
+function compactMarkdownSections(content, sectionNames, maxChars) {
+  const sections = parseMarkdownSections(content);
+  if (sections.size === 0 || sectionNames.length === 0) {
+    return truncateMiddle(content, maxChars);
+  }
+
+  const wanted = expandSectionAliases(sectionNames);
+  const included = [];
+  const title = content.split('\n').find((line) => /^#\s+/.test(line)) || '';
+  if (title) {
+    included.push(title);
+  }
+
+  for (const [sectionTitle, body] of sections.entries()) {
+    const normalized = normalizeHeading(sectionTitle);
+    const shouldInclude = wanted.has(normalized);
+    if (shouldInclude) {
+      included.push(compactSection(sectionTitle, body, maxChars));
+    }
+  }
+
+  if (included.length <= (title ? 1 : 0)) {
+    return truncateMiddle(content, maxChars);
+  }
+  return limitSectionsByPriority(included, maxChars);
+}
+
+function compactStatus(status) {
+  const sections = parseMarkdownSections(status || '');
+  const wanted = [
+    'текущий этап',
+    'current stage',
+    'текущий owner',
+    'latest routing decision',
+    'latest check verdict',
+    'latest check result',
+    'latest check resolution',
+    'human gate summary',
+    'последнее действие supervisor',
+    'следующий шаг',
+    'нужен ли сейчас human approval',
+  ].map(normalizeHeading);
+  const result = [];
+  for (const [title, body] of sections.entries()) {
+    if (wanted.includes(normalizeHeading(title))) {
+      result.push(`## ${title}\n${body.trim()}`);
+    }
+  }
+  return markCompacted('status.md', status, result.join('\n\n') || truncateMiddle(status, 1500));
+}
+
+function compactCheckMarkdown({ checkMarkdown, checkResult, mode }) {
+  const findings = Array.isArray(checkResult?.findings) ? checkResult.findings : [];
+  const lines = [
+    '# Check compact excerpt',
+    '',
+    `Verdict: ${checkResult?.verdict || 'unknown'}`,
+    `Findings: ${findings.length}`,
+    '',
+    compactMarkdownSections(checkMarkdown || '', ['итоговая оценка', 'summary'], charLimitForMode(mode, 800, 1200)),
+    '',
+    ...findings.map((finding) => [
+      `## ${finding.id || 'finding'}`,
+      `- Severity: ${finding.severity || 'unknown'}`,
+      `- Category: ${finding.claimCategory || 'unknown'}`,
+      `- Affected artifacts: ${truncateEnd(JSON.stringify(finding.affectedArtifacts || finding.affectedPlanSections || []), 250)}`,
+      '- Evidence refs:',
+      ...formatRefs(finding.evidenceRefs || [], 220),
+      `- Claim: ${truncateEnd(finding.claim || '', 700)}`,
+      `- Expected correction: ${truncateEnd(finding.expectedCorrection || '', 700)}`,
+    ].join('\n')),
+  ];
+  const compacted = lines.join('\n').trim() || truncateMiddle(checkMarkdown, charLimitForMode(mode, 1200, 3000));
+  return markCompacted('check.md', checkMarkdown, compacted);
+}
+
+function compactOrchestrationLog(log, mode) {
+  if (!log.trim()) {
+    return '';
+  }
+  const lines = log.split('\n').filter(Boolean);
+  const eventLines = lines.filter((line) => /^-\s+`/.test(line));
+  const lastCount = mode === 'fast' ? 20 : 40;
+  const counters = {
+    returnToPlan: countMatches(log, /return_to_plan/g),
+    returnToExecute: countMatches(log, /return_to_execute/g),
+    contextInsufficient: countMatches(log, /context_insufficient/g),
+    deterministicPreverify: countMatches(log, /deterministic pre-verify/gi),
+    checkerFailed: countMatches(log, /checker_failed/g),
+    verifierFailed: countMatches(log, /verifier_failed/g),
+  };
+  const compacted = [
+    '# Orchestration Log Compact',
+    '',
+    '## Counters',
+    '',
+    ...Object.entries(counters).map(([key, value]) => `- ${key}: ${value}`),
+    '',
+    `## Last ${lastCount} Events`,
+    '',
+    ...eventLines.slice(-lastCount),
+  ].join('\n');
+  return markCompacted('orchestration-log.md', log, compacted);
+}
+
+function compactProjectMemory(projectMemory, mode) {
+  if (mode === 'strict') {
+    return projectMemory;
+  }
+  const maxChars = MEMORY_MAX_CHARS[mode] ?? MEMORY_MAX_CHARS.standard;
+  let used = 0;
+  const compacted = [];
+  for (const item of projectMemory || []) {
+    const budgetLeft = maxChars - used;
+    if (budgetLeft <= 0) {
+      break;
+    }
+    const content = truncateEnd(item.content || '', Math.min(budgetLeft, mode === 'fast' ? 800 : 1400));
+    used += content.length;
+    compacted.push({
+      ...item,
+      content,
+      compacted: content !== item.content,
+    });
+  }
+  return compacted;
+}
+
+function compactGeneratedMarkdown(fileName, content, mode, limits) {
+  if (mode === 'strict' || !content) {
+    return content;
+  }
+  const limit = mode === 'fast' ? limits.fast : limits.standard;
+  return markCompacted(fileName, content, truncateMiddle(content, limit));
+}
+
+function compactCheckContext(checkContext, mode) {
+  const referencedLimit = mode === 'fast' ? 8 : 16;
+  return {
+    taskId: checkContext.taskId,
+    stage: checkContext.stage,
+    planSha: checkContext.planSha,
+    planFingerprintVersion: checkContext.planFingerprintVersion,
+    memorySha: checkContext.memorySha,
+    riskProfile: checkContext.riskProfile,
+    riskTriggers: checkContext.riskTriggers,
+    checkerContextPackFile: checkContext.checkerContextPackFile,
+    checkerContextPackSha: checkContext.checkerContextPackSha,
+    evidenceFile: checkContext.evidenceFile,
+    referencedFiles: (checkContext.referencedFiles || []).slice(0, referencedLimit),
+    contextBudgetTokens: checkContext.contextBudgetTokens,
+    maxRepoReads: checkContext.maxRepoReads,
+  };
+}
+
+function markCompacted(fileName, original, compacted) {
+  if (!original || original === compacted) {
+    return compacted;
+  }
+  return [
+    `<!-- compacted:${fileName} originalBytes=${Buffer.byteLength(original, 'utf8')} compactBytes=${Buffer.byteLength(compacted, 'utf8')} -->`,
+    compacted,
+  ].join('\n');
+}
+
+function isCompactedArtifact(value) {
+  return typeof value === 'string' && value.startsWith('<!-- compacted:');
+}
+
+function truncateMiddle(value, maxChars) {
+  const text = String(value || '').trim();
+  if (text.length <= maxChars) {
+    return text;
+  }
+  const head = Math.floor(maxChars * 0.65);
+  const tail = Math.max(0, maxChars - head - 120);
+  return [
+    text.slice(0, head).trimEnd(),
+    '',
+    `<!-- truncated ${text.length - head - tail} chars from middle for token budget -->`,
+    '',
+    text.slice(text.length - tail).trimStart(),
+  ].join('\n');
+}
+
+function truncateEnd(value, maxChars) {
+  const text = String(value || '').trim();
+  if (text.length <= maxChars) {
+    return text;
+  }
+  return `${text.slice(0, Math.max(0, maxChars - 40)).trimEnd()} ... [truncated]`;
+}
+
+function expandSectionAliases(sectionNames) {
+  const wanted = new Set();
+  for (const name of sectionNames) {
+    const normalized = normalizeHeading(name);
+    wanted.add(normalized);
+    for (const alias of SECTION_ALIASES.get(normalized) || []) {
+      wanted.add(normalizeHeading(alias));
+    }
+  }
+  return wanted;
+}
+
+function compactSection(sectionTitle, body, maxChars) {
+  const header = `## ${sectionTitle}`;
+  const trimmed = String(body || '').trim();
+  const sectionBudget = isProtectedSection(sectionTitle)
+    ? Math.max(1400, Math.floor(maxChars * 0.65))
+    : Math.min(Math.max(1200, Math.floor(maxChars / 2)), maxChars);
+  return `${header}\n${truncateEnd(trimmed, sectionBudget)}`;
+}
+
+function limitSectionsByPriority(sections, maxChars) {
+  const joined = sections.join('\n\n');
+  if (joined.length <= maxChars) {
+    return joined;
+  }
+  const protectedSections = sections.filter((section) => isProtectedSection(section));
+  const regularSections = sections.filter((section) => !isProtectedSection(section));
+  const kept = [];
+  const droppedProtected = [];
+  let used = 0;
+  for (const section of [...protectedSections, ...regularSections]) {
+    const nextSize = section.length + (kept.length ? 2 : 0);
+    if (used + nextSize <= maxChars) {
+      kept.push(section);
+      used += nextSize;
+    } else if (isProtectedSection(section)) {
+      droppedProtected.push(extractSectionTitle(section));
+    }
+  }
+  const droppedMarkers = droppedProtected.map((title) => `<!-- dropped-protected:${title} -->`);
+  const result = [...droppedMarkers, ...kept].join('\n\n');
+  if (result.length <= maxChars) {
+    return result;
+  }
+  return truncateEnd(result, maxChars);
+}
+
+function extractSectionTitle(section) {
+  const match = /^##\s+(.+?)\s*$/m.exec(String(section || ''));
+  return match ? normalizeHeading(match[1]) : 'unknown';
+}
+
+function formatRefs(refs, maxChars) {
+  if (!Array.isArray(refs) || refs.length === 0) {
+    return ['  - none'];
+  }
+  return refs.map((ref) => `  - ${truncateEnd(JSON.stringify(ref), maxChars)}`);
+}
+
+function isProtectedSection(value) {
+  const normalized = extractSectionTitle(value);
+  return PROTECTED_SECTIONS.has(normalized);
+}
+
+function charLimitForMode(mode, fastChars, standardChars) {
+  return mode === 'fast' ? fastChars : standardChars;
+}
+
+function readOptionalJson(taskDir, fileName) {
+  const filePath = path.join(taskDir, fileName);
+  try {
+    return readJsonFile(filePath);
+  } catch {
+    return null;
+  }
+}
+
+function countMatches(value, pattern) {
+  return (String(value || '').match(pattern) || []).length;
+}