mandrel 1.94.0 → 2.0.0

package/.agents/scripts/lib/orchestration/context-hydration-engine.js

@@ -1,539 +0,0 @@
-/**
- * lib/orchestration/context-hydration-engine.js — Context Hydration Engine (SDK)
- *
- * Stateless, async logic for assembling the full execution prompt for an
- * agent task. Extracted from the CLI entry point to enable reuse across
- * consumers (CLI wrappers, tests).
- *
- * This module is the SDK layer — it has no knowledge of CLI arguments,
- * file I/O decisions, or process.exit(). All I/O choices are delegated
- * to the caller.
- *
- * Consumers import `hydrateContext` from this module directly — the former
- * `hydrate-context.js` CLI wrapper was retired (#4482) with no live consumer.
- *
- * @see .agents/scripts/lib/ITicketingProvider.js
- */
-
-import crypto from 'node:crypto';
-import fs from 'node:fs';
-import path from 'node:path';
-import { getCommands } from '../config/commands.js';
-import {
-  getLimits,
-  getPaths,
-  PROJECT_ROOT,
-  resolveConfig,
-} from '../config-resolver.js';
-import { sliceEpicBodyForDelivery } from '../epic-body-sections.js';
-import { resolveFrameworkVersion } from '../framework-version.js';
-import { Logger } from '../Logger.js';
-import {
-  buildEnvelope,
-  DEFAULT_ELIDE_POLICIES,
-  DEFAULT_SECTION_PRIORITIES,
-  elideEnvelope,
-  envelopeToPrompt,
-} from './context-envelope.js';
-
-// ---------------------------------------------------------------------------
-// File-content cache — the agent-protocol template is read-only during a
-// dispatch run.
-// ---------------------------------------------------------------------------
-
-const _fileCache = new Map();
-
-function readFileCached(absPath) {
-  if (_fileCache.has(absPath)) return _fileCache.get(absPath);
-  const content = fs.readFileSync(absPath, 'utf8');
-  _fileCache.set(absPath, content);
-  return content;
-}
-
-// ---------------------------------------------------------------------------
-// Internal helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Resolve the framework version. Delegates to the shared
- * {@link resolveFrameworkVersion} helper (single owner of the root
- * `package.json` read) so the hydrator and the ticket-body stamp read the same
- * source. Retained as a thin named wrapper so the mismatch-warning call sites
- * below read against a stable local name.
- *
- * @returns {string}
- */
-function getVersion() {
-  return resolveFrameworkVersion();
-}
-
-/**
- * Parse the work-breakdown hierarchy from a Task ticket body.
- *
- * Looks for patterns like: `Epic: #1`, `Story: #3`.
- *
- * @param {string} body
- * @returns {Record<string, number>}
- */
-function parseHierarchy(body) {
-  const result = {};
-  if (!body) return result;
-
-  const matches = [...body.matchAll(/([A-Za-z\s]+):\s*#(\d+)/gi)];
-  for (const match of matches) {
-    const key = match[1].trim().toLowerCase().replace(/\s+/g, '');
-    const val = Number.parseInt(match[2], 10);
-    result[key] = val; // e.g. { epic: 1, story: 3 }
-  }
-  return result;
-}
-
-/**
- * Extract the markdown list items under a `## <heading>` section of a
- * Story body. Returns an empty array when the section is missing or has
- * no list items. Recognises both `- ` (incl. `- [ ]` / `- [x]`) and
- * `* ` bullet markers — matches the parser in `manifest-builder.js`
- * so the inline-acceptance contract round-trips verbatim across the two
- * call sites (manifest projection and context hydration).
- *
- * @param {string} body
- * @param {string} heading
- * @returns {string[]}
- */
-function extractSectionList(body, heading) {
-  if (typeof body !== 'string' || body.length === 0) return [];
-  const pattern = new RegExp(
-    `^##\\s+${heading.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*$`,
-    'mi',
-  );
-  const startMatch = body.match(pattern);
-  if (!startMatch || startMatch.index == null) return [];
-  const startIdx = startMatch.index + startMatch[0].length;
-  const rest = body.slice(startIdx);
-  const nextHeading = rest.search(/^##\s+/m);
-  const block = nextHeading === -1 ? rest : rest.slice(0, nextHeading);
-  const items = [];
-  for (const rawLine of block.split(/\r?\n/)) {
-    const line = rawLine.trim();
-    const m = line.match(/^[-*]\s+(?:\[[ xX]\]\s+)?(.*)$/);
-    if (m && m[1].length > 0) items.push(m[1].trim());
-  }
-  return items;
-}
-
-/**
- * Extract the inline `## Acceptance` / `## Acceptance Criteria` and
- * `## Verify` checklists from a Story body. Used by 2-tier hydration to
- * populate the `acceptanceCriteria` and `verificationCommands` envelope
- * sections directly from the dispatched Story ticket — under 2-tier the
- * Story IS the unit of execution and carries acceptance/verify inline
- * (no child tickets to walk).
- *
- * @param {string} body
- * @returns {{ acceptance: string[], verify: string[] }}
- */
-export function extractStorySections(body) {
-  const canonical = extractSectionList(body, 'Acceptance Criteria');
-  const acceptance =
-    canonical.length > 0 ? canonical : extractSectionList(body, 'Acceptance');
-  const verify = extractSectionList(body, 'Verify');
-  return { acceptance, verify };
-}
-
-/**
- * Remove one `## <heading>` section (heading line through the last line
- * before the next `## ` heading, or EOF) from a Story body. Byte-preserving
- * outside the removed span. No-op when the heading is absent. Case- and
- * whitespace-tolerant to match `extractSectionList`.
- *
- * @param {string} body
- * @param {string} heading
- * @returns {string}
- */
-function stripSection(body, heading) {
-  if (typeof body !== 'string' || body.length === 0) return body ?? '';
-  const pattern = new RegExp(
-    `^##\\s+${heading.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*$`,
-    'mi',
-  );
-  const startMatch = body.match(pattern);
-  if (!startMatch || startMatch.index == null) return body;
-  const start = startMatch.index;
-  const afterHeading = start + startMatch[0].length;
-  const rest = body.slice(afterHeading);
-  const nextHeading = rest.search(/^##\s+/m);
-  const end = nextHeading === -1 ? body.length : afterHeading + nextHeading;
-  const before = body.slice(0, start).replace(/\n+$/, '\n');
-  const after = body.slice(end).replace(/^\n+/, '');
-  return (before + after).replace(/\n{3,}/g, '\n\n').trimEnd();
-}
-
-/**
- * Strip the inline `## Acceptance Criteria` / `## Acceptance` and `## Verify`
- * sections from a Story body. Used to build the `taskInstructions` section
- * when the dedicated `acceptanceCriteria` / `verificationCommands` envelope
- * sections already carry those lists — so the binding acceptance/verify
- * content appears exactly once in the hydrated envelope rather than being
- * duplicated between the dedicated sections and the full task body.
- *
- * Each heading group is stripped only when its own dedicated section was
- * emitted (`acceptance` gates `## Acceptance Criteria` + `## Acceptance`;
- * `verify` gates `## Verify`). This keeps the strip symmetric with what was
- * reproduced elsewhere in the envelope: a `## Verify` section that carried no
- * bullets (so no dedicated `verificationCommands` section fired) is left
- * intact in `taskInstructions` rather than being silently dropped. Both flags
- * default to `true` so a no-argument call preserves the original
- * strip-everything behaviour.
- *
- * @param {string} body
- * @param {{ acceptance?: boolean, verify?: boolean }} [opts]
- * @returns {string}
- */
-export function stripStorySectionsForTaskInstructions(
-  body,
-  { acceptance = true, verify = true } = {},
-) {
-  if (typeof body !== 'string' || body.length === 0) return body ?? '';
-  let out = body;
-  if (acceptance) {
-    out = stripSection(out, 'Acceptance Criteria');
-    out = stripSection(out, 'Acceptance');
-  }
-  if (verify) {
-    out = stripSection(out, 'Verify');
-  }
-  return out;
-}
-
-/**
- * Detect whether the dispatched unit is a 2-tier Story (Story is the
- * leaf, carries inline acceptance/verify) vs. a 4-tier Task (Task is
- * the leaf, Story is one level up). The decision is made off the
- * `type::*` label the dispatcher already stamps on every ticket; it
- * does not depend on `planning.hierarchy`, so this engine
- * stays correct even when a 4-tier Epic ships in a 2-tier-default repo
- * (or vice versa) during the Epic #3078 dual-shape window.
- *
- * @param {object} task
- * @returns {boolean}
- */
-function isTwoTierStoryTask(task) {
-  const labels = task?.labels ?? [];
-  return labels.includes('type::story');
-}
-
-/**
- * Load and substitute placeholders in the agent-protocol template. Extracted
- * from {@link hydrateContext} to keep its complexity manageable.
- *
- * @param {object} args
- * @param {{ templatesRoot: string }} args.paths
- * @param {object} args.settings - resolved config (post-reshape `project.*` / `delivery.*` shape)
- * @param {string} args.currentVersion
- * @param {string} args.taskBranch
- * @param {string} args.epicBranch
- * @param {string|number} args.taskId
- * @returns {string} hydrated template body, or '' on read failure
- */
-function loadProtocolTemplate({
-  paths,
-  settings,
-  currentVersion,
-  taskBranch,
-  epicBranch,
-  taskId,
-}) {
-  try {
-    const pTemplatePath = path.join(
-      PROJECT_ROOT,
-      paths.templatesRoot,
-      'agent-protocol.md',
-    );
-    const tpl = readFileCached(pTemplatePath);
-    const commands = getCommands(settings);
-    const baseBranch = settings?.baseBranch ?? 'main';
-    const protectedBranches = Array.isArray(settings?.git?.protectedBranches)
-      ? settings.git.protectedBranches
-      : [baseBranch];
-    const protectedList = protectedBranches.map((b) => `\`${b}\``).join(', ');
-    return tpl
-      .replace(/\{\{PROTOCOL_VERSION\}\}/g, currentVersion)
-      .replace(/\{\{BRANCH_NAME\}\}/g, taskBranch)
-      .replace(/\{\{EPIC_BRANCH\}\}/g, epicBranch)
-      .replace(/\{\{TASK_ID\}\}/g, taskId)
-      .replace(/\{\{VALIDATE_CMD\}\}/g, commands.validate)
-      .replace(/\{\{TEST_CMD\}\}/g, commands.test)
-      .replace(/\{\{PROTECTED_BRANCHES\}\}/g, protectedList);
-  } catch (err) {
-    Logger.warn(`[Hydrator] Failed to load agent-protocol.md: ${err.message}`);
-    return '';
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Envelope assembly helpers
-// ---------------------------------------------------------------------------
-
-/**
- * @param {object} ticket
- * @param {string} retrievedAt
- * @returns {import('./context-envelope.js').TicketSnapshot}
- */
-function ticketSnapshot(ticket, retrievedAt) {
-  const body = ticket.body ?? '';
-  const id = ticket.id ?? ticket.number;
-  const version =
-    ticket.updatedAt ?? ticket.updated_at ?? ticket.updatedAtISO ?? retrievedAt;
-  const hash = crypto
-    .createHash('sha256')
-    .update(body)
-    .digest('hex')
-    .slice(0, 12);
-  return { id, version: String(version), hash, retrievedAt };
-}
-
-/**
- * @param {object} task
- * @returns {import('./context-envelope.js').ContextEnvelope['task']}
- */
-function envelopeTaskFrom(task) {
-  return {
-    id: task.id,
-    title: task.title,
-    protocolVersion: task.protocolVersion,
-  };
-}
-
-/**
- * @param {object} task
- * @param {import('../ITicketingProvider.js').ITicketingProvider} provider
- * @param {number} epicId
- * @param {object} agentSettings - Legacy-shim settings bag or resolved config.
- * @returns {Promise<{ content: string, provenance: import('./context-envelope.js').TicketSnapshot[] }>}
- */
-async function buildHierarchySections(task, provider, epicId, agentSettings) {
-  const hierarchyKeys = parseHierarchy(task.body);
-  let hierarchyContext = '## Work Breakdown Hierarchy\n\n';
-  const provenance = [];
-  const retrievedAt = new Date().toISOString();
-
-  const depth = agentSettings?.contextDepth ?? 'standard';
-  const idsToFetch = [];
-
-  // Story #4324 — the context-ticket classes are retired: the Epic body IS
-  // the planning document (ideation sections + folded Tech Spec sections).
-  // `full` and `standard` fetch the identical Epic / Story pair; both
-  // branches are kept so the `contextDepth` setting stays a stable API
-  // surface.
-  if (depth === 'full') {
-    idsToFetch.push({ key: 'Epic', id: epicId || hierarchyKeys.epic });
-    idsToFetch.push({ key: 'Story', id: hierarchyKeys.story });
-  } else if (depth === 'standard') {
-    idsToFetch.push({ key: 'Epic', id: epicId || hierarchyKeys.epic });
-    idsToFetch.push({ key: 'Story', id: hierarchyKeys.story });
-  } else if (depth === 'minimal') {
-    idsToFetch.push({ key: 'Story', id: hierarchyKeys.story });
-  }
-
-  const fetchPromises = idsToFetch
-    .filter((item) => item.id)
-    .map(async (item) => {
-      try {
-        const t = await provider.getTicket(item.id);
-        provenance.push(ticketSnapshot(t, retrievedAt));
-        // Hydration section-slicing guardrail (Story #4340): the Epic body
-        // is sliced down to only the sections a delivery story agent acts
-        // on — Goal / Non-Goals / User Stories / Tech Spec (plus any
-        // operator-authored section, fail-open). Ideation / authoring /
-        // close machinery (## Context, ## Scope, ## Acceptance Criteria,
-        // and the ## Acceptance Table managed region) is dropped so
-        // per-story prompt size stays flat versus the pre-fold baseline.
-        const body =
-          item.key === 'Epic' ? sliceEpicBodyForDelivery(t.body ?? '') : t.body;
-        return `### ${item.key}: ${t.title} (#${t.id})\n\n${body}\n`;
-      } catch (err) {
-        const detail = err?.message ? `: ${err.message}` : '';
-        Logger.warn(
-          `[Hydrator] hierarchy fetch failed for ${item.key} #${item.id}${detail}`,
-        );
-        return `### ${item.key}: #${item.id} — ⚠️ unavailable (fetch failed${detail})\n`;
-      }
-    });
-
-  const fetchedHierarchy = await Promise.all(fetchPromises);
-  hierarchyContext += fetchedHierarchy.filter(Boolean).join('\n---\n\n');
-  return { content: hierarchyContext, provenance };
-}
-
-/**
- * @param {object} task
- * @param {{ templatesRoot: string }} paths
- * @param {object} agentSettings - Legacy-shim settings bag or resolved config.
- * @param {string} currentVersion
- * @param {string} taskBranch
- * @param {string} epicBranch
- * @returns {{ warnings: string[], sections: import('./context-envelope.js').Section[] }}
- */
-function buildStaticSections(
-  task,
-  paths,
-  agentSettings,
-  currentVersion,
-  taskBranch,
-  epicBranch,
-) {
-  const warnings = [];
-
-  if (task.protocolVersion && task.protocolVersion !== currentVersion) {
-    warnings.push(
-      `⚠️ WARNING: Protocol version mismatch. Task was planned with v${task.protocolVersion}, but is executing with v${currentVersion}.`,
-    );
-    Logger.warn(
-      `[Hydrator] Protocol version mismatch on Task #${task.id}: planned with v${task.protocolVersion}, executing with v${currentVersion}`,
-    );
-  }
-
-  const sections = [];
-  const protocolTpl = loadProtocolTemplate({
-    paths,
-    settings: agentSettings,
-    currentVersion,
-    taskBranch,
-    epicBranch,
-    taskId: task.id,
-  });
-  if (protocolTpl) {
-    sections.push({
-      name: 'protocolPolicy',
-      priority: DEFAULT_SECTION_PRIORITIES.protocolPolicy,
-      elideWhenOverBudget: DEFAULT_ELIDE_POLICIES.protocolPolicy,
-      content: protocolTpl,
-      source: { kind: 'file', ref: 'templates/agent-protocol.md' },
-    });
-  }
-
-  // Track which dedicated section(s) were emitted so taskInstructions drops
-  // only the inline sections that were actually reproduced elsewhere in the
-  // envelope — keeping each binding acceptance/verify item present exactly
-  // once, without dropping a bulletless section that has no dedicated twin.
-  let acceptanceEmitted = false;
-  let verifyEmitted = false;
-  if (isTwoTierStoryTask(task)) {
-    const { acceptance, verify } = extractStorySections(task.body ?? '');
-    if (acceptance.length > 0) {
-      acceptanceEmitted = true;
-      sections.push({
-        name: 'acceptanceCriteria',
-        priority: DEFAULT_SECTION_PRIORITIES.acceptanceCriteria,
-        elideWhenOverBudget: DEFAULT_ELIDE_POLICIES.acceptanceCriteria,
-        content:
-          `## Acceptance Criteria (Story #${task.id})\n\n` +
-          acceptance.map((item) => `- ${item}`).join('\n'),
-        source: { kind: 'ticket', ref: String(task.id) },
-      });
-    }
-    if (verify.length > 0) {
-      verifyEmitted = true;
-      sections.push({
-        name: 'verificationCommands',
-        priority: DEFAULT_SECTION_PRIORITIES.verificationCommands,
-        elideWhenOverBudget: DEFAULT_ELIDE_POLICIES.verificationCommands,
-        content:
-          `## Verify (Story #${task.id})\n\n` +
-          verify.map((item) => `- ${item}`).join('\n'),
-        source: { kind: 'ticket', ref: String(task.id) },
-      });
-    }
-  }
-
-  // When a dedicated acceptance/verify section carries that list, strip the
-  // matching inline heading(s) from the task body so they are not duplicated
-  // in taskInstructions. Each group is gated on its own section: an inline
-  // section with no dedicated twin (e.g. a bulletless `## Verify`) is left
-  // intact. When neither fired, taskInstructions is byte-identical to the
-  // full body.
-  const taskBody =
-    acceptanceEmitted || verifyEmitted
-      ? stripStorySectionsForTaskInstructions(task.body ?? '', {
-          acceptance: acceptanceEmitted,
-          verify: verifyEmitted,
-        })
-      : task.body;
-  sections.push({
-    name: 'taskInstructions',
-    priority: DEFAULT_SECTION_PRIORITIES.taskInstructions,
-    elideWhenOverBudget: DEFAULT_ELIDE_POLICIES.taskInstructions,
-    content: `## Task Instructions (Issue #${task.id}: ${task.title})\n\n${taskBody}`,
-    source: { kind: 'ticket', ref: String(task.id) },
-  });
-
-  return { warnings, sections };
-}
-
-// ---------------------------------------------------------------------------
-// Public SDK export
-// ---------------------------------------------------------------------------
-
-/**
- * Hydrate the execution context into a {@link ContextEnvelope}.
- *
- * @param {object} task - The normalized task object from the dispatcher
- * @param {import('../ITicketingProvider.js').ITicketingProvider} provider
- * @param {string} epicBranch  - e.g. `epic/71`
- * @param {string} taskBranch  - e.g. `story/epic-71/my-story`
- * @param {number} epicId
- * @returns {Promise<import('./context-envelope.js').ContextEnvelope>}
- */
-export async function hydrateContext(
-  task,
-  provider,
-  epicBranch,
-  taskBranch,
-  epicId,
-) {
-  const { agentSettings } = resolveConfig();
-  const maxTokens = getLimits({
-    agentSettings: agentSettings ?? {},
-  }).maxTokenBudget;
-
-  const paths = getPaths({ agentSettings });
-  const currentVersion = getVersion();
-  const { warnings, sections: staticSections } = buildStaticSections(
-    task,
-    paths,
-    agentSettings,
-    currentVersion,
-    taskBranch,
-    epicBranch,
-  );
-
-  const { content: hierarchyContent, provenance } =
-    await buildHierarchySections(task, provider, epicId, agentSettings);
-
-  const sections = [...staticSections];
-  const hierarchySection = {
-    name: 'hierarchy',
-    priority: DEFAULT_SECTION_PRIORITIES.hierarchy,
-    elideWhenOverBudget: DEFAULT_ELIDE_POLICIES.hierarchy,
-    content: hierarchyContent,
-    source: { kind: 'derived', ref: 'work-breakdown-hierarchy' },
-  };
-  const taskIdx = sections.findIndex((s) => s.name === 'taskInstructions');
-  if (taskIdx >= 0) {
-    sections.splice(taskIdx, 0, hierarchySection);
-  } else {
-    sections.push(hierarchySection);
-  }
-
-  const envelope = buildEnvelope({
-    task: envelopeTaskFrom(task),
-    sections,
-    provenance,
-    warnings,
-    maxTokens,
-  });
-
-  return elideEnvelope(envelope, maxTokens);
-}
-
-export { envelopeToPrompt };