mandrel 1.94.0 → 2.1.0

package/.agents/scripts/lib/orchestration/lifecycle/listeners/notify-dispatcher.js

@@ -1,174 +0,0 @@
-// .agents/scripts/lib/orchestration/lifecycle/listeners/notify-dispatcher.js
-/**
- * NotifyDispatcher — lifecycle listener that fans out the curated
- * webhook event subset (Story #2239 Task #2244).
- *
- * The framework's notification surface is the operator-supplied
- * `notifications.webhookEvents` allowlist (see
- * `.agents/scripts/lib/config/github.js NOTIFICATIONS_DEFAULTS`). Each
- * allowlisted name maps to one lifecycle event the bus emits — this
- * listener subscribes to those events and dispatches via the injected
- * `notify` function.
- *
- * Mapping (Tech Spec § curated webhooks):
- *
- *   webhookEvents entry    lifecycle event
- *   --------------------   ---------------------
- *   `epic-started`         (emitted at /deliver kickoff;
- *                          this listener handles `epic.snapshot.start`)
- *   `epic-blocked`         `epic.blocked`
- *   `epic-complete`        `epic.complete`
- *
- * The `epic-progress` and `epic-unblocked` webhook events are NOT mapped
- * here: their former dotted lifecycle triggers (`wave.end` /
- * `epic.unblocked`) belonged to the in-process runner stratum deleted in
- * Story #3908. The production wave loop fires those curated webhooks
- * directly through `progress-reporter/transport.js`
- * (`wave-record-notifications.js`), so the webhook names stay valid in
- * `NOTIFICATIONS_DEFAULTS` — only the redundant lifecycle-bus subscription
- * is gone.
- *
- * Why per-event subscriptions instead of a wildcard listener? The
- * wildcard would receive every event the bus carries, forcing the
- * dispatcher to re-check membership on every emit. Per-event
- * subscription gives the bus's mediator the routing decision once at
- * registration time and keeps the side-effect surface auditable.
- *
- * Idempotency: `(event, seqId)` guard short-circuits replays. The
- * `notify` function itself is fire-and-forget per `notify.js`
- * (failures are swallowed); the listener wraps in try/catch defense.
- *
- * Trace emit (Tech Spec § observability): for every event the
- * dispatcher handles, it appends a `notification.emitted` row to the
- * epic-level signals NDJSON via the injected `appendEpicSignal`. This
- * gives operators a single place to confirm that a webhook actually
- * fired (the `notify` function's success is silent). The trace row
- * also carries `seqId` so the resume test can prove
- * notifications survive a crash window without duplicating.
- */
-
-/**
- * Static map: lifecycle event → curated webhook event name. Keys are
- * the bus event names this listener subscribes to.
- */
-export const LIFECYCLE_TO_WEBHOOK_EVENT = Object.freeze({
-  'epic.snapshot.start': 'epic-started',
-  'epic.blocked': 'epic-blocked',
-  'epic.complete': 'epic-complete',
-});
-
-/**
- * Compute the set of webhook event names this listener can emit.
- * Exposed so the listener-notify test can assert subset equality
- * against `notifications.webhookEvents` from `.agentrc.json`.
- */
-export function webhookEventNames() {
-  return new Set(Object.values(LIFECYCLE_TO_WEBHOOK_EVENT));
-}
-
-export class NotifyDispatcher {
-  /**
-   * @param {object} opts
-   * @param {number} opts.epicId
-   * @param {(ticketId: number, payload: object, opts?: object) => Promise<unknown>} opts.notify
-   * @param {(args: object) => Promise<boolean>} [opts.appendEpicSignal]
-   *   Optional trace writer; when omitted, trace emits are skipped.
-   * @param {object} [opts.config] Resolved framework config (forwarded
-   *   to `appendEpicSignal`).
-   * @param {() => number} [opts.now]
-   * @param {{ warn?: Function, debug?: Function }} [opts.logger]
-   */
-  constructor(opts = {}) {
-    if (!Number.isInteger(opts.epicId) || opts.epicId < 1) {
-      throw new TypeError('NotifyDispatcher requires a numeric epicId');
-    }
-    if (typeof opts.notify !== 'function') {
-      throw new TypeError('NotifyDispatcher requires a notify function');
-    }
-    this.epicId = opts.epicId;
-    this._notify = opts.notify;
-    this._appendEpicSignal = opts.appendEpicSignal ?? null;
-    this._config = opts.config;
-    this._now = typeof opts.now === 'function' ? opts.now : Date.now;
-    this.logger = opts.logger ?? console;
-    this._seen = new Set();
-    this.events = Object.freeze(Object.keys(LIFECYCLE_TO_WEBHOOK_EVENT));
-  }
-
-  register(bus) {
-    if (!bus || typeof bus.on !== 'function') {
-      throw new TypeError('NotifyDispatcher.register requires a bus with on()');
-    }
-    return this.events.map((event) =>
-      bus.on(event, async (ctx) => this.handle(ctx)),
-    );
-  }
-
-  async handle({ event, seqId, payload }) {
-    const key = `${event}:${seqId}`;
-    if (this._seen.has(key)) {
-      this.logger.debug?.(
-        `[NotifyDispatcher] skip duplicate ${key} (idempotent)`,
-      );
-      return;
-    }
-    this._seen.add(key);
-
-    const webhookEvent = LIFECYCLE_TO_WEBHOOK_EVENT[event];
-    if (!webhookEvent) return;
-
-    // notify() is fire-and-forget by contract; wrap in try/catch as a
-    // defense layer so even a thrown notify error never propagates
-    // back to the bus.
-    try {
-      await this._notify(
-        this.epicId,
-        {
-          event: webhookEvent,
-          level: 'epic',
-          epicId: this.epicId,
-          payload: { ...payload },
-        },
-        { skipComment: true },
-      );
-    } catch (err) {
-      this.logger.warn?.(
-        `[NotifyDispatcher] notify ${webhookEvent} failed: ${err?.message ?? err}`,
-      );
-    }
-
-    // Self-emit `notification.emitted` for trace — but NOT through the
-    // bus (the mediator forbids re-entry from inside a listener
-    // body). Instead we append a row to the epic-level signals NDJSON
-    // so the resume test can prove the dispatch survived a crash
-    // window without duplicating.
-    if (this._appendEpicSignal) {
-      const signal = {
-        kind: 'notification.emitted',
-        seqId,
-        ts: new Date(this._now()).toISOString(),
-        // The common signal envelope requires `epicId` on the record
-        // itself — `hasCommonEnvelope` (lib/signals/schema.js) rejects
-        // rows without it and the read side silently drops them, so
-        // without this field the record was write-only (invisible to
-        // signals-view.js and every other reader).
-        epicId: this.epicId,
-        sourceEvent: event,
-        webhookEvent,
-      };
-      try {
-        await this._appendEpicSignal({
-          epicId: this.epicId,
-          signal,
-          config: this._config,
-        });
-      } catch {
-        // already best-effort; swallow.
-      }
-    }
-  }
-
-  resetSeen() {
-    this._seen.clear();
-  }
-}

package/.agents/scripts/lib/orchestration/manifest-builder.js

@@ -1,222 +0,0 @@
-/**
- * lib/orchestration/manifest-builder.js — Manifest Building Logic
- *
- * 2-tier-only producer. Reads Story tickets from `allTickets` directly,
- * computes Story-scoped waves, and emits the `waves[].stories[]` /
- * Story-only `storyManifest` shape. The pre-Epic-#3163 Task-tier branch
- * has been removed; the framework no longer carries a Task-tier
- * producer path.
- */
-
-import { parseBlockedBy } from '../dependency-parser.js';
-import { getStoryBranch, slugify } from '../git-utils.js';
-import { TYPE_LABELS } from '../label-constants.js';
-import { computeStoryWaves } from './dependency-analyzer.js';
-import { STATE_LABELS } from './ticketing.js';
-
-/**
- * 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 — the same set the schema expects to round-trip
- * verbatim per the manifest dispatch-manifest contract.
- *
- * @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;
-}
-
-/**
- * Project a Story ticket into the inline-acceptance/verify shape required by
- * the 2-tier waves[].stories[] schema. Reads `## Acceptance` /
- * `## Acceptance Criteria` and `## Verify` sections from the body.
- *
- * @param {object} story
- * @param {number} epicId
- * @returns {object}
- */
-function projectStoryForWave(story, epicId) {
-  const body = story.body ?? '';
-  const acceptanceCriteria = extractSectionList(body, 'Acceptance Criteria');
-  const acceptanceItems =
-    acceptanceCriteria.length > 0
-      ? acceptanceCriteria
-      : extractSectionList(body, 'Acceptance');
-  const verifyItems = extractSectionList(body, 'Verify');
-  const fromBody = parseBlockedBy(body);
-  const fromField = Array.isArray(story.dependencies)
-    ? story.dependencies.map(Number)
-    : [];
-  const dependsOn = [...new Set([...fromBody, ...fromField])].filter((id) =>
-    Number.isInteger(id),
-  );
-  const labels = story.labels ?? [];
-  const personaLabel = labels.find((l) => l.startsWith('persona::'));
-  const persona =
-    story.persona ??
-    (personaLabel ? personaLabel.replace('persona::', '') : 'engineer');
-  const status =
-    story.status ??
-    labels.find((l) => l.startsWith('agent::')) ??
-    'agent::ready';
-
-  return {
-    storyId: story.id,
-    title: story.title ?? '',
-    status,
-    branch: getStoryBranch(epicId, story.id),
-    persona,
-    acceptance: acceptanceItems,
-    verify: verifyItems,
-    dependsOn,
-  };
-}
-
-const AGENT_DONE_LABEL = STATE_LABELS.DONE;
-
-/**
- * Build the Story-only manifest array used by the 2-tier hierarchy path.
- * Reads Story tickets directly from `allTickets`; there is no Task tier
- * to walk. Each entry exposes an empty `tasks: []` to keep downstream
- * consumers (renderers, dispatch helpers) on a single per-Story shape
- * until Category 4 of Epic #3163 rewrites them.
- *
- * @param {object[]} stories  Story tickets (each with `id`, `title`,
- *                            `body`, `labels`, optional `dependencies`).
- * @param {number}   epicId
- * @returns {object[]}
- */
-function buildStoryOnlyManifest(stories, epicId) {
-  const storyById = new Map(stories.map((s) => [s.id, s]));
-  const explicitStoryDeps = new Map();
-  for (const story of stories) {
-    const fromBody = parseBlockedBy(story.body ?? '');
-    const fromField = Array.isArray(story.dependencies)
-      ? story.dependencies.map(Number)
-      : [];
-    const merged = [...new Set([...fromBody, ...fromField])].filter(
-      (id) => Number.isInteger(id) && id !== story.id && storyById.has(id),
-    );
-    if (merged.length > 0) explicitStoryDeps.set(story.id, merged);
-  }
-
-  // Reuse `computeStoryWaves` by adapting Stories to its `storyGroups`
-  // input shape: a Map keyed by storyId whose values look like grouper
-  // output. With no Tasks, every group's `tasks: []` collapses the
-  // task-level wave inference to a no-op; only `explicitDeps` drives
-  // ordering.
-  const storyGroups = new Map(
-    stories.map((s) => [s.id, { storyId: s.id, tasks: [] }]),
-  );
-  const storyWaves = computeStoryWaves(storyGroups, explicitStoryDeps);
-
-  return stories.map((story) => {
-    const earliestWave = storyWaves.get(story.id) ?? -1;
-    return {
-      storyId: story.id,
-      storyTitle: story.title ?? '',
-      storySlug: slugify(story.title ?? `story-${story.id}`),
-      type: 'story',
-      branchName: getStoryBranch(epicId, story.id),
-      earliestWave,
-      // Carry the resolved cross-Story dependency edges on the entry so the
-      // presentation layer can derive grouping depth at render time via
-      // `assignLayers` (Story #4157) instead of trusting the persisted
-      // `earliestWave`. This is the same `explicitStoryDeps` set the wave
-      // computation consumed, already closed over the scheduled Story set.
-      dependsOn: explicitStoryDeps.get(story.id) ?? [],
-      tasks: [],
-    };
-  });
-}
-
-/**
- * Build the wave records for a 2-tier manifest. Each wave entry exposes a
- * `stories[]` projection (instead of the legacy `tasks[]`) so dispatch
- * consumers can fan Story execution out wave-by-wave without ever seeing
- * a `type::task` ticket.
- *
- * @param {object[][]} waves   Story waves (array of Story-ticket arrays).
- * @param {number}     epicId
- * @returns {object[]}
- */
-function buildStoryWaves(waves, epicId) {
-  return waves.map((wave, i) => ({
-    waveIndex: i,
-    stories: wave.map((s) => projectStoryForWave(s, epicId)),
-  }));
-}
-
-/**
- * Build the full Dispatch Manifest object.
- *
- * Epic #3163, Category 2 deleted the legacy Task-tier
- * `waves[].tasks[]` branch and the Task-grouping import this module
- * used to pull from the removed helper. The producer is now
- * Story-only: it filters `allTickets` to the Story tier, computes
- * Story-scoped waves, and emits `waves[].stories[]` plus a Story-only
- * `storyManifest`.
- *
- * @param {object} params
- * @returns {object}
- */
-export function buildManifest({
-  epicId,
-  epic,
-  allTickets,
-  waves,
-  dispatched,
-  dryRun,
-  agentTelemetry = null,
-}) {
-  const stories = (allTickets ?? []).filter((t) =>
-    (t.labelSet ?? new Set(t.labels ?? [])).has(TYPE_LABELS.STORY),
-  );
-  const totalStories = stories.length;
-  const doneStories = stories.filter((s) =>
-    (s.labelSet ?? new Set(s.labels ?? [])).has(AGENT_DONE_LABEL),
-  ).length;
-  const progress =
-    totalStories > 0 ? Math.round((doneStories / totalStories) * 100) : 0;
-
-  return {
-    schemaVersion: '1.0.0',
-    generatedAt: new Date().toISOString(),
-    epicId,
-    epicTitle: epic?.title ?? '',
-    executor: 'claude-code',
-    dryRun,
-    hierarchy: '2-tier',
-    summary: {
-      totalStories,
-      doneStories,
-      progressPercent: progress,
-      totalWaves: waves.length,
-      dispatched: dispatched.length,
-    },
-    waves: buildStoryWaves(waves, epicId),
-    storyManifest: buildStoryOnlyManifest(stories, epicId),
-    dispatched,
-    agentTelemetry,
-  };
-}