mandrel 2.60.0 → 2.62.0

package/.agents/scripts/lib/Graph.js

@@ -1,13 +1,6 @@
-/**
- * Graph.js
- * Extracted mathematical DAG logic for topological sorting, cycle detection,
- * transitive reduction, and auto-serialization of concurrent task overlaps.
- */
+/** DAG utilities: cycle detection, layering, reduction, topological sort. */
 
-/**
- * Builds an adjacency list from the manifest tasks.
- * Returns { adjacency: Map<id, id[]>, taskMap: Map<id, task> }
- */
+/** Returns { adjacency: Map<id, id[]>, taskMap: Map<id, task> }. */
 export function buildGraph(tasks) {
   const adjacency = new Map();
   const taskMap = new Map();
@@ -20,10 +13,7 @@ export function buildGraph(tasks) {
   return { adjacency, taskMap };
 }
 
-/**
- * Detects cycles using DFS. Returns the first cycle found as an array of ids,
- * or null if the graph is acyclic.
- */
+/** The first cycle found as an array of ids, or null. */
 export function detectCycle(adjacency) {
   const WHITE = 0,
     _GRAY = 1,
@@ -50,7 +40,7 @@ function dfsVisit(u, adjacency, color, parent) {
 
   for (const v of adjacency.get(u) || []) {
     if (color.get(v) === 1) {
-      // Back edge → cycle. Reconstruct.
+      // Back edge: reconstruct the cycle.
       const cycle = [v, u];
       let cur = u;
       while (parent.has(cur) && parent.get(cur) !== v) {
@@ -70,10 +60,7 @@ function dfsVisit(u, adjacency, color, parent) {
   return null;
 }
 
-/**
- * Assigns each task a layer (depth from root). Root tasks (no dependencies)
- * are layer 0. Returns Map<id, layer>.
- */
+/** Depth from root (roots are layer 0) as Map<id, layer>. */
 export function assignLayers(adjacency) {
   const layers = new Map();
   const memo = new Map();
@@ -101,36 +88,18 @@ export function assignLayers(adjacency) {
 }
 
 /**
- * Performs transitive reduction on a DAG.
- *
- * Removes edge (u→v) iff some *other* direct dependency w of u satisfies
- * v ∈ reach(w) — i.e. v is reachable from u via a path of length > 1 that
- * does not use the edge (u→v) itself.
+ * Remove edge (u→v) iff another direct dependency of u already reaches v.
  *
- * Two-arg form (preferred on hot paths): callers that already hold a
- * reachability matrix for the same `adjacency` (e.g. the dispatch
- * pipeline, which also feeds it to `autoSerializeOverlaps`) pass it in
- * via `reachable` so we skip the O(V·(V+E)) re-derivation. The per-edge
- * check is then O(1) (`reach(w).has(v)`), making the overall reduction
- * O(V+E) on top of the (amortized) cost of producing `reachable` once.
- *
- * Single-arg form (back-compat): when `reachable` is omitted we compute
- * it locally via `computeReachability(adjacency)` so the function stays
- * a drop-in replacement for the historical single-argument signature.
- * Output is byte-identical between the two forms.
- *
- * @param {Map<*, *[]>} adjacency  Dependency map (node → deps[]).
- * @param {Map<*, Set<*>>} [reachable]  Optional pre-computed reachability
- *   matrix matching `adjacency`. When supplied it MUST cover every node
- *   in `adjacency` — passing a partial map will silently corrupt output.
- * @returns {Map<*, *[]>}  Reduced adjacency map.
+ * @param {Map<*, *[]>} adjacency node → deps[].
+ * @param {Map<*, Set<*>>} [reachable] Precomputed reachability; when given it
+ *   MUST cover every node, or output is silently corrupt.
+ * @returns {Map<*, *[]>}
  */
 export function transitiveReduction(adjacency, reachable) {
   const reach = reachable ?? computeReachability(adjacency);
   const result = new Map();
 
   for (const [node, deps] of adjacency.entries()) {
-    // Early-return: nodes with zero or one dependency cannot have redundant edges
     if (deps.length <= 1) {
       result.set(node, [...deps]);
       continue;
@@ -138,8 +107,6 @@ export function transitiveReduction(adjacency, reachable) {
 
     const kept = [];
     for (const dep of deps) {
-      // Edge (node → dep) is redundant iff some other direct dep `other`
-      // of `node` already reaches `dep` transitively.
       let isRedundant = false;
       for (const other of deps) {
         if (other === dep) continue;
@@ -156,12 +123,8 @@ export function transitiveReduction(adjacency, reachable) {
   return result;
 }
 
-/**
- * Computes which Chat Sessions each Chat Session depends on.
- * Returns a Map<chatNumber, chatNumber[]>.
- */
+/** Returns a transitively reduced Map<chatNumber, chatNumber[]>. */
 export function computeChatDependencies(chatSessions, _adjacency) {
-  // Build a reverse lookup: taskId → chatNumber
   const taskToChat = new Map();
   for (const session of chatSessions) {
     for (const task of session.tasks) {
@@ -186,22 +149,16 @@ export function computeChatDependencies(chatSessions, _adjacency) {
     );
   }
 
-  // Apply transitive reduction to chat-level dependencies
   return transitiveReduction(chatDeps);
 }
 
-/**
- * Computes the transitive closure (reachability matrix) for the DAG.
- * Returns a Map<id, Set<id>> where each key maps to a set of all tasks it can reach.
- */
+/** Transitive closure as Map<id, Set<id>>, by memoized DFS: O(V·(V+E)). */
 export function computeReachability(adjacency) {
-  // Memoized DFS: each node's reachable set is computed once and cached.
-  // Complexity: O(V·(V+E)) — avoids the O(N³) Floyd-Warshall triple loop.
   const memo = new Map();
 
   function reach(id) {
     if (memo.has(id)) return memo.get(id);
-    // Seed with a placeholder to handle cycles defensively
+    // Placeholder first, so a cycle cannot recurse forever.
     const set = new Set();
     memo.set(id, set);
     for (const neighbour of adjacency.get(id) || []) {
@@ -221,17 +178,14 @@ export function computeReachability(adjacency) {
 }
 
 /**
- * Performs a topological sort on the DAG using Kahn's algorithm.
- * Returns tasks ordered such that all dependencies precede their dependents.
- * Deterministic: ties are broken by task ID (ascending) for stable output.
+ * Kahn's algorithm; ties break by ascending id for stable output.
  *
- * @param {Map<number, number[]>} adjacency - Dependency map (id → blockedBy[]).
- * @param {Map<number, object>} taskMap - Full task objects keyed by id.
- * @returns {object[]} Tasks in topological order.
- * @throws {Error} If a cycle is detected (should be caught before calling this).
+ * @param {Map<number, number[]>} adjacency id → blockedBy[].
+ * @param {Map<number, object>} taskMap
+ * @returns {object[]}
+ * @throws {Error} On a cycle (run `detectCycle` first).
  */
 export function topologicalSort(adjacency, taskMap) {
-  // Pre-compute reverse adjacency and in-degree for O(V+E)
   const inDegree = new Map();
   const reverseAdj = new Map();
 
@@ -250,7 +204,6 @@ export function topologicalSort(adjacency, taskMap) {
     inDegree.set(nodeId, activeDeps);
   }
 
-  // Seed queue with zero-in-degree nodes (tasks with no active dependencies), sorted by id for determinism
   const queue = [...inDegree.entries()]
     .filter(([, deg]) => deg === 0)
     .map(([id]) => id)
@@ -259,17 +212,15 @@ export function topologicalSort(adjacency, taskMap) {
   const sorted = [];
 
   while (queue.length > 0) {
-    // Take smallest ID for determinism (queue is kept sorted)
+    // The queue is kept sorted, so this is the smallest id.
     const id = queue.shift();
     sorted.push(taskMap.get(id));
 
-    // Decrement in-degree for dependents using pre-computed reverse map
     for (const dependent of reverseAdj.get(id) ?? []) {
       const newDeg = (inDegree.get(dependent) ?? 0) - 1;
       inDegree.set(dependent, newDeg);
       if (newDeg === 0) {
-        // Binary insertion to maintain sorted order — O(log N) per insert
-        // instead of re-sorting the entire queue each iteration.
+        // Binary insertion keeps the queue sorted without a re-sort.
         let lo = 0,
           hi = queue.length;
         while (lo < hi) {
@@ -292,18 +243,11 @@ export function topologicalSort(adjacency, taskMap) {
 }
 
 /**
- * Groups tasks into sequential execution waves.
- *
- * A wave contains all tasks whose dependencies are fully satisfied by
- * previously completed waves. Tasks within the same wave can run concurrently
- * (subject to focus-area serialization in the Dispatcher).
- *
- * Uses `assignLayers` to compute depth, then groups by layer value.
- * The returned array is sorted by wave index (wave 0 = roots).
+ * Group tasks by layer; each wave's dependencies are all in earlier waves.
  *
- * @param {Map<number, number[]>} adjacency - Dependency map (id → blockedBy[]).
- * @param {Map<number, object>} taskMap - Full task objects keyed by id.
- * @returns {object[][]} Array of waves, each wave is an array of task objects.
+ * @param {Map<number, number[]>} adjacency id → blockedBy[].
+ * @param {Map<number, object>} taskMap
+ * @returns {object[][]}
  */
 export function computeWaves(adjacency, taskMap) {
   const layers = assignLayers(adjacency);
@@ -314,7 +258,6 @@ export function computeWaves(adjacency, taskMap) {
     waveMap.get(layer).push(taskMap.get(id));
   }
 
-  // Sort waves by layer, sort tasks within each wave by id for determinism
   const maxLayer = Math.max(...waveMap.keys());
   const waves = [];
   for (let i = 0; i <= maxLayer; i++) {

package/.agents/scripts/lib/ITicketingProvider.js

@@ -1,28 +1,14 @@
 /**
- * ITicketingProvider — Abstract Ticketing Provider Interface
- *
- * All ticketing interactions in the v5 Story-centric orchestration are mediated
- * through this interface. Concrete implementations (e.g., `providers/github.js`)
- * extend this class and override every method.
- *
- * Unoverridden methods throw `Error('Not implemented: <method>')` to enforce
- * the contract at runtime rather than silently returning `undefined`.
- *
- * @see docs/architecture.md — Provider Abstraction Layer
- * @see docs/v5-implementation-plan.md Sprint 1A
+ * Abstract ticketing provider. Implementations (e.g. `providers/github.js`)
+ * override every method; unoverridden ones throw rather than return
+ * `undefined`.
  */
 
 export class ITicketingProvider {
-  // ---------------------------------------------------------------------------
-  // Read Operations
-  // ---------------------------------------------------------------------------
+  // Reads
 
   /**
-   * Fetch the Epic issue with its body — the single planning document
-   * (ideation sections plus the folded Tech Spec / Acceptance Table
-   * managed sections, Story #4324).
-   *
-   * @param {number} epicId - GitHub Issue number of the Epic.
+   * @param {number} epicId
    * @returns {Promise<{
    *   id: number,
    *   title: string,
@@ -34,10 +20,8 @@ export class ITicketingProvider {
     throw new Error('Not implemented: getEpic');
   }
   /**
-   * Fetch all child tickets for an Epic, optionally filtered by labels or state.
-   *
-   * @param {number} epicId - GitHub Issue number of the Epic.
-   * @param {{ label?: string, state?: string }} [filters={}] - Filter criteria.
+   * @param {number} epicId
+   * @param {{ label?: string, state?: string }} [filters={}]
    * @returns {Promise<Array<{
    *   id: number,
    *   title: string,
@@ -50,9 +34,7 @@ export class ITicketingProvider {
   }
 
   /**
-   * Fetch all immediate sub-tickets of a given parent ticket.
-   *
-   * @param {number} parentId - GitHub Issue number of the parent.
+   * @param {number} parentId
    * @returns {Promise<Array<{
    *   id: number,
    *   title: string,
@@ -65,9 +47,7 @@ export class ITicketingProvider {
   }
 
   /**
-   * Retrieve a single ticket with full metadata.
-   *
-   * @param {number} ticketId - GitHub Issue number.
+   * @param {number} ticketId
    * @returns {Promise<{
    *   id: number,
    *   title: string,
@@ -82,41 +62,19 @@ export class ITicketingProvider {
   }
 
   /**
-   * Pre-populate the provider's per-instance ticket cache with a batch of
-   * already-hydrated tickets so subsequent `getTicket(id)` calls can be
-   * served from cache instead of issuing a REST round-trip.
-   *
-   * Default no-op: providers without a cache (e.g. the manual adapter or
-   * test stubs) need not override. Call sites can therefore invoke
-   * `provider.primeTicketCache(tickets)` unconditionally without an
-   * `instanceof` / `typeof === 'function'` capability check.
+   * Seed the ticket cache so later `getTicket` calls skip a round-trip. A
+   * no-op by default, so callers need no capability check.
    *
    * @param {Array<{ id: number }>} _tickets
    * @returns {void}
    */
-  primeTicketCache(_tickets) {
-    // Intentional no-op. Concrete providers that maintain a cache override.
-  }
+  primeTicketCache(_tickets) {}
 
   /**
-   * List every ticket carrying `labels`, in the **mapped** ticket shape.
-   *
-   * This is the declared read for a label scan, and the only one callers
-   * should reach for. Implementations MUST map every issue the way every
-   * other read on this interface does — in particular `id` is the **issue
-   * number**, not the backend's internal database id.
-   *
-   * That single rule is the whole reason the method exists. The raw REST
-   * payload names the issue number `number` and the database id `id`, so a
-   * consumer handed either shape wrote `number ?? id` and appeared to cope —
-   * while silently addressing issues by database id on the mapped shape,
-   * because there `id` is already the number and the fallback never fires.
-   * A declared shape removes the choice rather than documenting it.
-   *
-   * `state` selects `open` (default), `closed` or `all`. Implementations MUST
-   * honour it: a caller asking for `all` is asking a question — "did this
-   * child reopen?" — that an open-only listing answers wrongly rather than
-   * partially.
+   * List tickets carrying `labels` in the mapped shape: `id` MUST be the issue
+   * number, never the backend database id (a raw-vs-mapped `number ?? id`
+   * fallback silently addresses the wrong issue). `state` (default `open`)
+   * MUST be honoured.
    *
    * @param {{ state?: 'open'|'closed'|'all', labels?: string }} [_opts]
    * @returns {Promise<Array<{
@@ -134,19 +92,9 @@ export class ITicketingProvider {
   }
 
   /**
-   * Read a parent's native sub-issue children as issue numbers.
-   *
-   * Takes **both** identifiers because they address different things: the
-   * backend's child edge is keyed by the parent's opaque node id, while
-   * `number` exists only so a degraded read can name the parent it failed on.
-   * Passing the number where the node id belongs is not a type error — it is
-   * a successful call about the wrong issue — which is why the parameter
-   * order is fixed here rather than left to each call site.
-   *
-   * Implementations MUST return `[]` rather than throw when the sub-issue
-   * feature is unavailable on the backend: absence of the feature is not a
-   * failed read, and callers union this with a body checklist that still
-   * answers the question.
+   * Native sub-issue children as issue numbers. The edge is keyed by node id;
+   * passing the number there succeeds about the wrong issue. MUST return `[]`
+   * when the backend lacks the feature (callers union a body checklist).
    *
    * @param {string} _nodeId Opaque node id of the parent.
    * @param {number} _number Parent's issue number, for diagnostics only.
@@ -157,30 +105,19 @@ export class ITicketingProvider {
   }
 
   /**
-   * Resolve a ticket's container parent in **one** call.
+   * Resolve a container parent in one call. Returns `null` (never throws) when
+   * there is no parent or the backend cannot answer, so a degraded lookup
+   * never fails a lifecycle edge.
    *
-   * Exists so a child→parent lookup is a read, not a search. Without it the
-   * only way to find a container was to list every candidate parent and read
-   * each one's children — O(containers) requests to answer what the backend
-   * knows directly.
-   *
-   * Returns `null` when the ticket has no parent, and `null` rather than
-   * throwing when the backend cannot answer. Callers treat a null as "no
-   * parent resolved *here*" and may fall back to a body-declared link; an
-   * exception would turn a degraded lookup into a failed lifecycle edge.
-   *
-   * @param {number} _number Issue number whose parent to resolve.
-   * @returns {Promise<object|null>} Mapped parent ticket, or null.
+   * @param {number} _number
+   * @returns {Promise<object|null>}
    */
   async getParentIssue(_number) {
     throw new Error('Not implemented: getParentIssue');
   }
 
   /**
-   * Return the dependency graph edges for a ticket.
-   * Parses `blocked by #NNN` patterns from the ticket body.
-   *
-   * @param {number} ticketId - GitHub Issue number.
+   * @param {number} ticketId
    * @returns {Promise<{
    *   blocks: number[],
    *   blockedBy: number[]
@@ -191,28 +128,22 @@ export class ITicketingProvider {
   }
 
   /**
-   * Fetch all comments for a specific ticket.
-   *
-   * @param {number} ticketId - GitHub Issue number.
-   * @returns {Promise<object[]>} Array of comment objects.
+   * @param {number} ticketId
+   * @returns {Promise<object[]>}
    */
   async getTicketComments(_ticketId) {
     throw new Error('Not implemented: getTicketComments');
   }
 
-  // ---------------------------------------------------------------------------
-  // Write Operations
-  // ---------------------------------------------------------------------------
+  // Writes
 
   /**
-   * Mutate labels, body (tasklist checkboxes), and assignees on a ticket.
-   *
-   * @param {number} ticketId - GitHub Issue number.
+   * @param {number} ticketId
    * @param {{
    *   labels?: { add?: string[], remove?: string[] },
    *   body?: string,
    *   assignees?: string[]
-   * }} mutations - The mutations to apply.
+   * }} mutations
    * @returns {Promise<void>}
    */
   async updateTicket(_ticketId, _mutations) {
@@ -220,13 +151,11 @@ export class ITicketingProvider {
   }
 
   /**
-   * Append a structured comment to a ticket.
-   *
-   * @param {number} ticketId - GitHub Issue number.
+   * @param {number} ticketId
    * @param {{
    *   body: string,
    *   type: 'progress'|'friction'|'notification'
-   * }} payload - The comment content and classification.
+   * }} payload
    * @returns {Promise<{ commentId: number }>}
    */
   async postComment(_ticketId, _payload) {
@@ -234,8 +163,7 @@ export class ITicketingProvider {
   }
 
   /**
-   * Delete an issue comment by its numeric id.
-   * Implementations SHOULD treat "not found" as a no-op.
+   * SHOULD treat "not found" as a no-op.
    *
    * @param {number} _commentId
    * @returns {Promise<void>}
@@ -244,13 +172,9 @@ export class ITicketingProvider {
     throw new Error('Not implemented: deleteComment');
   }
 
-  // ---------------------------------------------------------------------------
-  // Setup Operations (used by bootstrap)
-  // ---------------------------------------------------------------------------
+  // Setup (bootstrap)
 
   /**
-   * Idempotent label creation. Skips labels that already exist.
-   *
    * @param {Array<{ name: string, color: string, description: string }>} labelDefs
    * @returns {Promise<{ created: string[], skipped: string[] }>}
    */
@@ -259,11 +183,8 @@ export class ITicketingProvider {
   }
 
   /**
-   * List the repository's whole label vocabulary.
-   *
-   * Implementations MUST paginate rather than take a fixed page cap: a cap is
-   * silent truncation, and a caller deciding what to delete from a truncated
-   * view is the exact failure Story #5189 exists to stop reproducing.
+   * MUST paginate: a page cap silently truncates, and callers decide
+   * deletions from this list.
    *
    * @returns {Promise<Array<{ name: string, color: string|null, description: string|null }>>}
    */
@@ -272,11 +193,8 @@ export class ITicketingProvider {
   }
 
   /**
-   * Delete one label by name.
-   *
-   * A label that is already gone MUST resolve as a successful no-op
-   * (`{ deleted: false, reason: 'not-found' }`) rather than throwing, so a
-   * re-run of any sweep built on this port is idempotent.
+   * An absent label MUST resolve `{ deleted: false, reason: 'not-found' }`,
+   * never throw, so sweeps are idempotent.
    *
    * @param {string} _name
    * @returns {Promise<{ deleted: boolean, reason: string|null }>}
@@ -286,8 +204,7 @@ export class ITicketingProvider {
   }
 
   /**
-   * Idempotent custom field creation on the Project board.
-   * Only applicable when `projectNumber` is configured.
+   * Idempotent; only applicable when `projectNumber` is configured.
    *
    * @param {Array<{
    *   name: string,
@@ -301,21 +218,17 @@ export class ITicketingProvider {
   }
 
   /**
-   * Execute a GraphQL query/mutation against the ticketing backend.
-   * @param {string} _query - GraphQL query/mutation string.
+   * @param {string} _query
    * @param {object} [_variables={}]
    * @param {object} [_opts={}]
-   * @returns {Promise<object>} The `data` portion of the response.
+   * @returns {Promise<object>} The response's `data`.
    */
   async graphql(_query, _variables = {}, _opts = {}) {
     throw new Error('Not implemented: graphql');
   }
 
   /**
-   * Inspect the branch-protection state of a branch. Returns
-   * `{ enabled: false }` when no protection rule exists (HTTP 404), and
-   * `{ enabled: true, raw }` when one does. Implementations may return a
-   * richer shape; the only contract consumers rely on is the boolean.
+   * `{ enabled: false }` on 404; consumers rely only on the boolean.
    *
    * @param {string} _branch
    * @returns {Promise<{ enabled: boolean, raw?: object }>}
@@ -325,15 +238,9 @@ export class ITicketingProvider {
   }
 
   /**
-   * Create or additively-merge a branch-protection rule on `_branch`. The
-   * `contexts` array names required status-check contexts; existing
-   * contexts are preserved (additive merge). When no rule exists one is
-   * created with sensible defaults and just the supplied contexts.
-   *
-   * Returns a summary `{ created, added, existing }` describing the diff
-   * the bootstrap orchestrator surfaces to the operator. Implementations
-   * MAY ignore other branch-protection knobs (PR review counts, signed
-   * commits, etc.) so operator-tuned settings survive re-runs.
+   * Additively merge required status-check `contexts` (creating the rule if
+   * absent). Other protection knobs are left alone so operator tuning
+   * survives re-runs.
    *
    * @param {string} _branch
    * @param {{ contexts: string[], strict?: boolean }} _opts
@@ -344,9 +251,7 @@ export class ITicketingProvider {
   }
 
   /**
-   * Read the repo's merge-method allowlist + auto-merge / delete-branch
-   * flags. Returns a sparse object containing only the fields the upstream
-   * API exposes (consumers should treat missing keys as "unknown").
+   * Sparse: a missing key means "unknown".
    *
    * @returns {Promise<Partial<{
    *   allow_squash_merge: boolean,
@@ -361,8 +266,7 @@ export class ITicketingProvider {
   }
 
   /**
-   * PATCH the repo with the supplied merge-method settings. Body is sparse —
-   * only the supplied fields are sent / touched.
+   * Sparse PATCH: only supplied fields are touched.
    *
    * @param {Partial<{
    *   allow_squash_merge: boolean,