mandrel 2.31.0 → 2.33.0

package/.agents/scripts/lib/orchestration/context-envelope.js

@@ -1,277 +0,0 @@
-/**
- * context-envelope.js — typed ContextEnvelope SDK for the hydration pipeline
- * (Epic #2648, Story #2762).
- *
- * Pure functions with no I/O. Downstream Stories assemble sections from ticket
- * fetches and file reads, then serialize via {@link envelopeToPrompt}.
- *
- * @module lib/orchestration/context-envelope
- */
-
-/** @typedef {'protocolPolicy' | 'skillCapsules' | 'hierarchy' | 'acceptanceCriteria' | 'verificationCommands' | 'taskInstructions'} SectionName */
-
-/**
- * @typedef {object} SectionSource
- * @property {'file' | 'ticket' | 'derived'} kind
- * @property {string} ref
- */
-
-/**
- * @typedef {object} Section
- * @property {SectionName} name
- * @property {number} priority Lower numbers are elided first.
- * @property {'drop' | 'summarize'} elideWhenOverBudget
- * @property {string} content
- * @property {number} estimatedTokens
- * @property {SectionSource} [source]
- */
-
-/**
- * @typedef {object} TicketSnapshot
- * @property {number} id
- * @property {string} version ISO 8601 ticket updatedAt
- * @property {string} hash sha256(body) truncated to 12 hex chars
- * @property {string} retrievedAt ISO 8601 at fetch time
- */
-
-/**
- * @typedef {object} ContextEnvelope
- * @property {'1'} schemaVersion
- * @property {{ id: number, title: string, skills?: string[], protocolVersion?: string }} task
- * @property {Section[]} sections
- * @property {TicketSnapshot[]} provenance
- * @property {{ maxTokens: number, used: number, elided: string[] }} budget
- * @property {string[]} warnings
- */
-
-/** Separator between rendered sections — matches legacy hydrateContext join. */
-export const PROMPT_SECTION_SEPARATOR =
-  '\n\n========================================================================\n\n';
-
-/** Rendering order for {@link envelopeToPrompt} (not elision priority). */
-export const SECTION_RENDER_ORDER = Object.freeze([
-  'protocolPolicy',
-  'skillCapsules',
-  'hierarchy',
-  'acceptanceCriteria',
-  'verificationCommands',
-  'taskInstructions',
-]);
-
-/** Default elision priority per section name (lower drops first). */
-export const DEFAULT_SECTION_PRIORITIES = Object.freeze({
-  skillCapsules: 10,
-  hierarchy: 20,
-  acceptanceCriteria: 30,
-  verificationCommands: 40,
-  protocolPolicy: 80,
-  taskInstructions: 100,
-});
-
-/** Default elide policy per section name. */
-export const DEFAULT_ELIDE_POLICIES = Object.freeze({
-  skillCapsules: 'summarize',
-  hierarchy: 'summarize',
-  acceptanceCriteria: 'summarize',
-  verificationCommands: 'drop',
-  protocolPolicy: 'drop',
-  taskInstructions: 'drop',
-});
-
-const SUMMARIZE_HEAD_CHARS = 200;
-const TASK_INSTRUCTIONS = 'taskInstructions';
-
-/**
- * Rough token estimate matching legacy {@link truncateToTokenBudget}.
- *
- * @param {string} text
- * @returns {number}
- */
-export function estimateTokens(text) {
-  return Math.ceil(String(text ?? '').length / 4);
-}
-
-/**
- * Normalize a section: stamp estimatedTokens when absent.
- *
- * @param {Section} section
- * @returns {Section}
- */
-function normalizeSection(section) {
-  const content = String(section.content ?? '');
-  return {
-    ...section,
-    content,
-    estimatedTokens:
-      typeof section.estimatedTokens === 'number'
-        ? section.estimatedTokens
-        : estimateTokens(content),
-  };
-}
-
-/**
- * Sum estimatedTokens across sections.
- *
- * @param {Section[]} sections
- * @returns {number}
- */
-function totalSectionTokens(sections) {
-  return sections.reduce((sum, s) => sum + s.estimatedTokens, 0);
-}
-
-/**
- * Build a {@link ContextEnvelope} from assembled parts.
- *
- * @param {{
- *   task: ContextEnvelope['task'],
- *   sections: Section[],
- *   provenance?: TicketSnapshot[],
- *   warnings?: string[],
- *   maxTokens?: number,
- * }} parts
- * @returns {ContextEnvelope}
- */
-export function buildEnvelope(parts) {
-  const sections = (parts.sections ?? []).map(normalizeSection);
-  const used = totalSectionTokens(sections);
-
-  return {
-    schemaVersion: '1',
-    task: parts.task,
-    sections,
-    provenance: parts.provenance ?? [],
-    budget: {
-      maxTokens: parts.maxTokens ?? used,
-      used,
-      elided: [],
-    },
-    warnings: parts.warnings ?? [],
-  };
-}
-
-/**
- * Deterministic summary for over-budget sections.
- *
- * @param {string} content
- * @returns {{ content: string, estimatedTokens: number, droppedTokens: number }}
- */
-function summarizeSectionContent(content) {
-  const originalTokens = estimateTokens(content);
-  if (content.length <= SUMMARIZE_HEAD_CHARS) {
-    return { content, estimatedTokens: originalTokens, droppedTokens: 0 };
-  }
-  const head = content.slice(0, SUMMARIZE_HEAD_CHARS);
-  const droppedTokens = originalTokens - estimateTokens(head);
-  const summary = `${head}…[elided, ${droppedTokens} tokens dropped]`;
-  return {
-    content: summary,
-    estimatedTokens: estimateTokens(summary),
-    droppedTokens,
-  };
-}
-
-/**
- * Apply section-aware elision against a token budget.
- *
- * Sections iterate in ascending priority order. `taskInstructions` is never
- * dropped or summarized. When still over budget after all eligible sections
- * are elided, a warning is appended and task instructions remain intact.
- *
- * @param {ContextEnvelope} envelope
- * @param {number} maxTokens
- * @returns {ContextEnvelope}
- */
-export function elideEnvelope(envelope, maxTokens) {
-  const sections = envelope.sections.map((s) => ({ ...s }));
-  let used = totalSectionTokens(sections);
-
-  if (used <= maxTokens) {
-    return {
-      ...envelope,
-      budget: { maxTokens, used, elided: [] },
-    };
-  }
-
-  const elided = [];
-  const byPriority = [...sections].sort((a, b) => a.priority - b.priority);
-
-  for (const template of byPriority) {
-    if (used <= maxTokens) break;
-    if (template.name === TASK_INSTRUCTIONS) continue;
-
-    const idx = sections.findIndex((s) => s.name === template.name);
-    if (idx === -1) continue;
-
-    const current = sections[idx];
-    if (!current.content) continue;
-
-    if (current.elideWhenOverBudget === 'summarize') {
-      const { content, estimatedTokens } = summarizeSectionContent(
-        current.content,
-      );
-      sections[idx] = { ...current, content, estimatedTokens };
-    } else {
-      sections[idx] = { ...current, content: '', estimatedTokens: 0 };
-    }
-
-    if (!elided.includes(template.name)) {
-      elided.push(template.name);
-    }
-    used = totalSectionTokens(sections);
-  }
-
-  const warnings = [...envelope.warnings];
-  if (used > maxTokens) {
-    warnings.push(
-      `⚠️ Context envelope still over token budget after elision (${used}/${maxTokens} tokens). Task instructions preserved intact.`,
-    );
-  }
-
-  return {
-    ...envelope,
-    sections,
-    warnings,
-    budget: { maxTokens, used, elided },
-  };
-}
-
-/**
- * Serialize a {@link ContextEnvelope} to the legacy prose prompt form.
- *
- * Warnings are prepended, then non-empty sections are joined in
- * {@link SECTION_RENDER_ORDER} with {@link PROMPT_SECTION_SEPARATOR}.
- * Identical envelope input yields byte-identical output.
- *
- * @param {ContextEnvelope} envelope
- * @returns {string}
- */
-export function envelopeToPrompt(envelope) {
-  const sectionByName = new Map(
-    envelope.sections.map((section) => [section.name, section]),
-  );
-
-  const parts = [];
-
-  const warningsText = (envelope.warnings ?? [])
-    .map((w) => String(w).trim())
-    .filter(Boolean)
-    .join('\n\n');
-  if (warningsText) {
-    parts.push(warningsText);
-  }
-
-  for (const name of SECTION_RENDER_ORDER) {
-    const section = sectionByName.get(name);
-    if (section?.content) {
-      parts.push(section.content);
-    }
-  }
-
-  for (const section of envelope.sections) {
-    if (!SECTION_RENDER_ORDER.includes(section.name) && section.content) {
-      parts.push(section.content);
-    }
-  }
-
-  return parts.join(PROMPT_SECTION_SEPARATOR);
-}

package/.agents/scripts/lib/orchestration/detectors-phase.js

@@ -1,194 +0,0 @@
-/**
- * detectors-phase.js — pure phase that runs the per-Story signal detectors
- * (rework + retry) over the local NDJSON stream.
- *
- * Story #4545 — this phase has no production caller. Its sequencer
- * (`post-merge-pipeline.js`) went in the v2.0.0 cutover, and the
- * `analyze-execution.js` consumer it fed was deleted with the
- * execution-analysis surface. Kept alive only by its own test — the
- * test-importer blind spot the dead-exports ratchet cannot see.
- *
- * Extracted from `post-merge-pipeline.js` (Story #1770 / Task #1779) to
- * keep the parent sequencer's maintainability score above its baseline
- * after the new wiring layer landed. The phase contract is identical to
- * every other entry in `DEFAULT_POST_MERGE_PHASES`: take a context bag,
- * return a value the runner stitches under a `stateKey`.
- *
- * ### Contract
- *
- * - **Pure detectors.** Both `detectRework` and `detectRetry` are pure
- *   modules under `lib/signals/detectors/` — they read the per-Story
- *   `traces.ndjson` and return SignalEvent arrays. This phase resolves
- *   the operator-tunable thresholds via `getSignals(config)` (Epic
- *   #1720 — `delivery.signals.*`), invokes each detector, and persists
- *   each event through `appendSignal` so the per-Story `signals.ndjson`
- *   stream covers both kinds before the analyzer reads it.
- *
- * - **Failure isolation.** A failing detector or a per-event append
- *   MUST NOT block Task close. Each call is wrapped in try/catch;
- *   failures degrade to a warn and contribute 0 to the offending
- *   detector's count. The phase always resolves with a stable
- *   `{ rework: N, retry: N }` shape.
- *
- * - **One info line per close.** The summary log
- *   (`detectors: rework=N retry=M`) is the only stdout signal — one
- *   line per Story rather than two per detector + N per event.
- *
- * - **2-tier (Storyless) closure (Story #3127).** When `tasks` is
- *   empty (the 2-tier hierarchy shape), `resolveLastTaskId` returns
- *   `null` and both detectors run with `taskId: null`. The detector
- *   modules already accept a nullable `taskId` (see
- *   `lib/signals/detectors/{rework,retry}.js`), so no branching on
- *   hierarchy mode is required here.
- *
- * @module lib/orchestration/detectors-phase
- */
-
-import path from 'node:path';
-import { getSignals } from '../config/limits.js';
-import { storyTempDir } from '../config/temp-paths.js';
-import { Logger } from '../Logger.js';
-import { appendSignal } from '../observability/signals-writer.js';
-import { detectRetry, detectRework } from '../signals/detectors/index.js';
-
-function reapPhaseLogger(progress) {
-  return progress ?? (() => {});
-}
-
-function resolveLastTaskId(tasks) {
-  if (!Array.isArray(tasks) || tasks.length === 0) return null;
-  const last = tasks[tasks.length - 1];
-  const id = Number(last?.id ?? last);
-  return Number.isInteger(id) && id > 0 ? id : null;
-}
-
-async function persistDetectorEvents({
-  events,
-  epicId,
-  storyId,
-  config,
-  appendSignalFn,
-  logger,
-  kind,
-}) {
-  let count = 0;
-  for (const evt of events) {
-    try {
-      await appendSignalFn({ epicId, storyId, signal: evt, config });
-      count += 1;
-    } catch (err) {
-      logger?.warn?.(
-        `[detectors-phase] ${kind} appendSignal failed (${err?.message ?? err})`,
-      );
-    }
-  }
-  return count;
-}
-
-async function runOneDetector({
-  detectorFn,
-  args,
-  epicId,
-  storyId,
-  config,
-  appendSignalFn,
-  logger,
-  kind,
-}) {
-  try {
-    const events = await detectorFn(args);
-    return await persistDetectorEvents({
-      events,
-      epicId,
-      storyId,
-      config,
-      appendSignalFn,
-      logger,
-      kind,
-    });
-  } catch (err) {
-    logger?.warn?.(
-      `[detectors-phase] ${kind} detector threw (${err?.message ?? err})`,
-    );
-    return 0;
-  }
-}
-
-function isValidIdPair(eid, sid) {
-  return Number.isInteger(eid) && eid > 0 && Number.isInteger(sid) && sid > 0;
-}
-
-/**
- * Run the rework + retry detectors for one Story and persist every
- * emission to `temp/run-<id>/stories/story-<sid>/signals.ndjson`.
- *
- * @param {{
- *   epicId: number|string,
- *   storyId: number|string,
- *   tasks?: Array<{ id?: number|string }>,
- *   config?: object,
- *   progress?: Function,
- *   logger?: object,
- *   detectorsImpl?: { detectRework?: typeof detectRework, detectRetry?: typeof detectRetry },
- *   appendSignalFn?: typeof appendSignal,
- * }} ctx
- * @returns {Promise<{ rework: number, retry: number }>}
- */
-export async function detectorsPhase(ctx) {
-  const {
-    epicId,
-    storyId,
-    tasks,
-    config,
-    progress,
-    logger = Logger,
-    detectorsImpl,
-    appendSignalFn = appendSignal,
-  } = ctx;
-  const log = reapPhaseLogger(progress);
-  const eid = Number(epicId);
-  const sid = Number(storyId);
-  if (!isValidIdPair(eid, sid)) {
-    logger?.warn?.(
-      `[detectors-phase] skipped: invalid epicId=${epicId} / storyId=${storyId}`,
-    );
-    return { rework: 0, retry: 0 };
-  }
-
-  let signalsCfg;
-  try {
-    signalsCfg = getSignals(config);
-  } catch (err) {
-    logger?.warn?.(
-      `[detectors-phase] getSignals failed (${err?.message ?? err}); using zero counts`,
-    );
-    return { rework: 0, retry: 0 };
-  }
-
-  const tracesPath = path.join(storyTempDir(eid, sid, config), 'traces.ndjson');
-  const taskId = resolveLastTaskId(tasks);
-  const baseArgs = { tracesPath, epicId: eid, storyId: sid, taskId };
-  const common = {
-    epicId: eid,
-    storyId: sid,
-    config,
-    appendSignalFn,
-    logger,
-  };
-
-  const rework = await runOneDetector({
-    ...common,
-    detectorFn: detectorsImpl?.detectRework ?? detectRework,
-    args: { ...baseArgs, threshold: signalsCfg.rework.editsPerFile },
-    kind: 'rework',
-  });
-  const retry = await runOneDetector({
-    ...common,
-    detectorFn: detectorsImpl?.detectRetry ?? detectRetry,
-    args: { ...baseArgs, threshold: signalsCfg.retry.repeatCount },
-    kind: 'retry',
-  });
-
-  log('DETECTORS', `detectors: rework=${rework} retry=${retry}`);
-  return { rework, retry };
-}