mandrel 2.59.0 → 2.61.0

package/.agents/scripts/generate-skills-index.js

@@ -1,43 +1,10 @@
 #!/usr/bin/env node
-// .agents/scripts/generate-skills-index.js
-//
-// Walk `.agents/skills/{core,stack}/**/SKILL.md` via the shared parser
-// helper, project each parsed result into an index entry, and write the
-// aggregated manifest to `.agents/skills/skills.index.json`. Supports a
-// `--check` mode that compares the on-disk manifest against fresh
-// generator output (ignoring the volatile `generatedAt` field) and exits
-// non-zero with a diff-style message if they diverge.
-//
-// Two indexes, never one (Story #5135). The shipped manifest above is a
-// committed payload file that `mandrel doctor` / `mandrel sync-agents`
-// compare byte-for-byte against the installed package, so consumer-authored
-// skills under the `.agents/local/skills/` zone MUST NOT be folded into it —
-// a merged index would read as payload drift in every consumer that authored
-// a skill, and those commands would refuse. Local skills are therefore
-// indexed into their own `.agents/local/skills/skills.index.json`, inside
-// the zone sync never prunes and drift never walks.
-//
-// CLI surface:
-//
-//   node generate-skills-index.js [--check] [--root <dir>] [--out <file>]
-//
-//   --check        Read the on-disk manifest, compare to generator output
-//                  modulo `generatedAt`. Exit 0 on match, non-zero on
-//                  drift. Does not write.
-//   --root <dir>   Use <dir> as the repo root (defaults to the project
-//                  root containing `.agents/skills`). Useful for tests
-//                  staging fixture trees outside the real repo.
-//   --out <file>   Override the manifest output path (defaults to
-//                  `<root>/.agents/skills/skills.index.json`).
-//
-// Written output is passed through the project formatter (Biome) so that
-// regenerating on a clean tree leaves no format drift behind; the step is
-// best-effort and degrades to plain `JSON.stringify` output where Biome is
-// not installed. See `lib/format-generated-json.js`.
-//
-// Honors AGENT_LOG_LEVEL via the shared `Logger`. Stdout is reserved for
-// the diff text in --check failure mode; informational progress goes to
-// stderr.
+// Writes `.agents/skills/skills.index.json` from every payload SKILL.md;
+// `--check` compares modulo `generatedAt`. Consumer skills under
+// `.agents/local/skills/` get their own index and must never be merged into
+// the payload one: doctor/sync-agents compare it byte-for-byte against the
+// package and would read a merged index as drift. Stdout is reserved for the
+// `--check` diff; progress goes to stderr.
 
 import fs from 'node:fs';
 import path from 'node:path';
@@ -72,11 +39,7 @@ function defaultRepoRoot() {
   return path.resolve(here, '..', '..');
 }
 
-/**
- * Parse CLI flags. Returns `{ check, root, out }`. Unknown flags trigger
- * a thrown Error (from the shared parser) so the runAsCli boundary can
- * surface a clean message.
- */
+/** Unknown flags throw, for runAsCli to surface. */
 export function parseArgs(argv) {
   if (argv.some((t) => t === '--help' || t === '-h')) {
     return { check: false, root: null, out: null, help: true };
@@ -92,15 +55,7 @@ export function parseArgs(argv) {
   return { check: values.check, root: values.root, out: values.out };
 }
 
-/**
- * Project a parseSkill result into an index entry shaped by
- * `.agents/schemas/skills-index.schema.json`.
- *
- * Post-Wave-2 every SKILL.md carries a 5–12-bullet Policy Capsule.
- * `policyCapsuleBullets` records that count for the manifest entry.
- * A value of `0` means the parser did not find the capsule section and
- * is a validator-rejected condition (see validate-skills.js).
- */
+/** `policyCapsuleBullets: 0` means no capsule was found (validator-rejected). */
 function projectEntry(parsed) {
   return {
     name: parsed.name,
@@ -119,10 +74,6 @@ function projectEntry(parsed) {
   };
 }
 
-/**
- * Build the manifest object (without `generatedAt`) by walking the tree
- * and projecting each parsed SKILL.md into an index entry.
- */
 export function buildManifestBody(repoRoot, collect = collectSkillFiles) {
   const skillFiles = collect(repoRoot);
   const skills = skillFiles.map((absPath) =>
@@ -134,10 +85,6 @@ export function buildManifestBody(repoRoot, collect = collectSkillFiles) {
   };
 }
 
-/**
- * Build the full manifest with `generatedAt`. `nowIso` is injected so
- * tests can pin the timestamp deterministically.
- */
 export function buildManifest(repoRoot, { nowIso, collect } = {}) {
   const body = buildManifestBody(repoRoot, collect);
   return {
@@ -148,44 +95,24 @@ export function buildManifest(repoRoot, { nowIso, collect } = {}) {
 }
 
 /**
- * Serialize a manifest object as canonical JSON: 2-space indent,
- * trailing newline. Two runs against an unchanged corpus produce
- * byte-identical output modulo `generatedAt`.
- *
- * This is the *pre-format* shape. `JSON.stringify` expands every array
- * across multiple lines, while Biome collapses short ones that fit
- * inside `lineWidth` (`"allowedTools": ["Read", "Bash"]`). Writing this
- * text verbatim therefore leaves the tree format-dirty on every run —
- * see `lib/format-generated-json.js`, which reconciles the two.
+ * Pre-format shape: Biome collapses short arrays this expands, so writes go
+ * through `formatGeneratedJson` or the tree is format-dirty on every run.
  */
 export function serializeManifest(manifest) {
   return `${JSON.stringify(manifest, null, 2)}\n`;
 }
 
-/**
- * Resolve the manifest output path given (root, optional explicit
- * override).
- */
 function resolveOutPath(root, override) {
   return override
     ? path.resolve(override)
     : indexPathFor(root, PAYLOAD_SKILLS_SEGMENTS);
 }
 
-/**
- * Resolve the local-zone manifest path. Deliberately NOT overridable by
- * `--out`: that flag redirects the payload manifest (tests stage fixture
- * trees with it), and letting it also move the local manifest would let one
- * invocation write both indexes to the same file.
- */
+/** Not overridable by `--out`, or one run could write both indexes to one file. */
 function resolveLocalOutPath(root) {
   return indexPathFor(root, LOCAL_SKILLS_SEGMENTS);
 }
 
-/**
- * Write one manifest through the project formatter so a regeneration on a
- * clean tree leaves no format drift behind.
- */
 function writeManifest(manifest, outPath, root) {
   const serialized = serializeManifest(manifest);
   const opts = { cwd: root, filename: INDEX_FILENAME };
@@ -196,12 +123,7 @@ function writeManifest(manifest, outPath, root) {
   );
 }
 
-/**
- * Write (or reap) the local-zone manifest. A consumer who deletes their last
- * local skill would otherwise be left with a stale index reporting skills
- * that no longer exist, so an emptied zone removes the artifact rather than
- * leaving it behind.
- */
+/** An emptied local zone removes its index rather than leave a stale one. */
 function writeLocalManifest(localFresh, localOutPath, root) {
   const rel = path.relative(root, localOutPath).split(path.sep).join('/');
   if (localFresh === null) {
@@ -215,11 +137,6 @@ function writeLocalManifest(localFresh, localOutPath, root) {
   Logger.info(`wrote ${rel} (${localFresh.skills.length} entries)`);
 }
 
-/**
- * Compare the local-zone manifest against fresh generator output. Returns
- * null when in sync (including the common case of no local skills and no
- * artifact), or a diff-style message.
- */
 function checkLocalManifest(localFresh, localOutPath) {
   const exists = fs.existsSync(localOutPath);
   if (localFresh === null) {
@@ -240,13 +157,7 @@ function checkLocalManifest(localFresh, localOutPath) {
 }
 
 /**
- * Build the local zone's manifest plan for this invocation: its output path,
- * and a fresh manifest when the consumer has authored any local skill (null
- * otherwise, which is the signal to reap a stale artifact).
- *
- * Split out of `run` so the payload path and the local path each read as one
- * step there rather than interleaving.
- *
+ * A null `localFresh` signals reaping a stale artifact.
  * @param {string} root
  * @param {Date} now
  * @returns {{ localFresh: object | null, localOutPath: string }}
@@ -264,9 +175,6 @@ function buildLocalPlan(root, now) {
 }
 
 /**
- * Render the freshness line's entry counts, naming the local zone only when
- * one exists.
- *
  * @param {object} fresh
  * @param {object | null} localFresh
  * @returns {string}
@@ -279,13 +187,7 @@ function describeCounts(fresh, localFresh) {
 }
 
 /**
- * `--check` mode: compare both manifests against fresh generator output and
- * report the first drift found, payload first.
- *
- * Lives outside `run` so the entry point reads as "resolve inputs, then check
- * or write" — and so the check path's branches are not charged to a function
- * that also owns argument resolution.
- *
+ * Reports the first drift found, payload first.
  * @param {{ outPath: string, fresh: object, localOutPath: string, localFresh: object | null }} plan
  * @returns {{ status: number, output: string }}
  */

package/.agents/scripts/generate-workflows-doc.js

@@ -1,33 +1,8 @@
 #!/usr/bin/env node
 /**
- * .agents/scripts/generate-workflows-doc.js — Catalog-backed workflows index
- *
- * Renders the consumer-shipped slash-command catalog at
- * `.agents/docs/workflows.md` from the on-disk workflow set under
- * `.agents/workflows/*.md` (top-level only — `helpers/` are path-included
- * modules, not runnable slash commands). The catalog logic is shared with
- * the in-process backend in `lib/mandrel-catalog.js`, so the generated doc
- * and any programmatic catalog reader never drift from one another.
- *
- * Why generated (Story #3708): `workflows.md` used to be hand-maintained and
- * was *not* drift-gated, so it could silently fall out of sync with the
- * actual workflow set. The retired `/mandrel` discoverability command was
- * always accurate because it rendered the catalog live. Rather than keep the
- * drift-prone hand-authored doc and the accurate-but-ephemeral command, this
- * generator makes the doc itself a rendering of the same catalog, gates it via
- * `--check`, and ships it to consumers under `.agents/docs/`.
- *
- * Modes:
- *   (default)  — rewrites `.agents/docs/workflows.md` in full from the
- *                current workflow set.
- *   --check    — exits 0 when the on-disk file matches the freshly generated
- *                content, throws (→ exit 1) with a regeneration hint otherwise.
- *   --root     — read and write under another checkout's `.agents/` tree.
- *                See {@link resolveTargets} for why this seam exists.
- *
- * Per `.agents/rules/orchestration-error-handling.md`, unrecoverable failures
- * surface via `throw new Error(...)` so `runAsCli` maps the throw to
- * `process.exit(1)` deterministically (no `Logger.fatal`).
+ * Renders `.agents/docs/workflows.md` from the top-level workflow set via the
+ * shared `lib/mandrel-catalog.js`, so the doc and programmatic readers cannot
+ * drift; `--check` gates it.
  */
 
 import fs from 'node:fs';
@@ -43,28 +18,9 @@ const __dirname = path.dirname(__filename);
 const PROJECT_ROOT = path.resolve(__dirname, '..', '..');
 
 /**
- * Resolve the workflow source directory and the generated doc for one
- * repository root.
- *
- * The `--root` seam this backs exists for the drift gate's own test. That
- * test used to prove the gate by editing the *real*
- * `.agents/workflows/mandrel-deliver.md`, running `--check`, and restoring
- * the file in `afterEach`. The proof was sound; the blast radius was not.
- * `node --test` runs test files in parallel against one shared checkout, so
- * for the ~1s the real file sat mutated, every other test file observed a
- * dirty tree — and `tests/enforcement/workflow-script-help.test.js`, whose
- * final assertion is a repo-wide `git status --porcelain`, reported it as
- * "`--help` mutated the working tree" on the Windows Smoke job, where the
- * wider process-spawn cost stretches that window far enough to collide.
- *
- * A generator that can only ever be pointed at its own checkout forces that
- * choice. Pointing it at a fixture root removes it.
- *
- * The `--root` default is applied here rather than at the call site so the
- * one branch it costs lives with the resolution it belongs to.
- *
- * @param {string} [root] Repository root to render against; defaults to this
- *   checkout. A relative path is resolved against the process cwd.
+ * The `--root` seam lets the drift gate's test use a fixture root: mutating
+ * the real workflow file dirties the shared checkout for parallel test files.
+ * @param {string} [root]
  * @returns {{ root: string, workflowsDir: string, docPath: string }}
  */
 export function resolveTargets(root) {
@@ -76,21 +32,11 @@ export function resolveTargets(root) {
   };
 }
 
-/** This checkout's own targets — the default when `--root` is absent. */
 const { workflowsDir: WORKFLOWS_DIR, docPath: DOC_PATH } = resolveTargets();
 
 /**
- * Collapse a catalog description to a single Markdown table-cell-safe line.
- * The catalog already normalizes whitespace; this neutralizes:
- *   - pipe characters (`|`) so a description can never break the table grid;
- *   - stray newlines;
- *   - bare emphasis markers (`*`, `_`) so a glob like `audit-*` in a
- *     description is rendered literally instead of being parsed as emphasis
- *     (which trips markdownlint MD037 in the generated doc).
- *
- * Framework workflow descriptions do not embed `*`/`_` inside inline code
- * spans, so a global escape is safe and keeps the generator pure.
- *
+ * Escapes `*`/`_` so a glob like `audit-*` is not parsed as emphasis (MD037);
+ * safe globally because descriptions put neither inside code spans.
  * @param {string | null} description
  * @returns {string}
  */
@@ -103,9 +49,6 @@ function cellEscape(description) {
 }
 
 /**
- * Render the full generated `workflows.md` content from the flat command
- * catalog and the loop-unit catalog.
- *
  * @param {Array<{ name: string, description: string | null, vague: boolean }>} catalog
  * @param {Array<{ name: string, description: string | null, vague: boolean }>} [loopCatalog]
  * @returns {string}
@@ -124,7 +67,7 @@ export function renderWorkflowsDoc(catalog, loopCatalog = []) {
     'This is an **auto-generated reference index** of every slash command shipped',
     'under `.agents/workflows/` (top-level only — `helpers/` are path-included',
     'modules, not runnable commands). The canonical workflow narrative lives in',
-    '[`SDLC.md`](SDLC.md) — read that first to understand how the commands',
+    '[`SDLC.md`](https://github.com/dsj1984/mandrel/blob/main/docs/SDLC.md) — read that first to understand how the commands',
     'compose. This file is only for "which command does X?" lookups.',
     '',
     'Every command file lives at `.agents/workflows/<name>.md` and is projected',
@@ -184,10 +127,7 @@ export function renderWorkflowsDoc(catalog, loopCatalog = []) {
 }
 
 /**
- * Build the canonical generated content and read the on-disk file (if any).
- *
- * @param {string} [root] Repository root to render against; see
- *   {@link resolveTargets}.
+ * @param {string} [root]
  * @returns {{
  *   generated: string,
  *   original: string | null,

package/.agents/scripts/git-cleanup.js

@@ -2,41 +2,9 @@
 /* node:coverage ignore file -- multi-phase repo-cleanup CLI; thin shell over `git` + `gh` */
 
 /**
- * git-cleanup.js — Story #2466 thin CLI shell over the multi-phase
- * cleanup pipeline.
+ * Thin CLI shell over the `lib/orchestration/git-cleanup/phases/` pipeline.
  *
- * The pipeline lives under `lib/orchestration/git-cleanup/phases/`:
- *
- *   1. parse-args   — argv → normalized opts bag (`parseCleanupArgs`).
- *   2. filters      — pure glob + protected-branch helpers.
- *   3. git-probes   — every `gitSpawn` / `gh` subprocess wrapper plus
- *                     small parsers (`probeMergedPr`, etc).
- *   4. branches     — merged-branch reap (`planCleanup`,
- *                     `executeCleanup`).
- *   5. fast-forward — fast-forward-main phase.
- *   6. prune        — prune-remotes phase + `parsePrunedRefs`.
- *   7. stashes      — stash triage (`parseStashList`, `planStashes`,
- *                     `executeStashes`, `stashRefIndex`,
- *                     `buildAllowlistDecider`).
- *   8. render       — operator-facing renderers + `buildJsonEnvelope`,
- *                     `computeExitCode`.
- *   9. cli          — interactive prompts + per-phase drivers + `main`.
- *
- * Public CLI surface, named exports, and exit codes are byte-identical
- * to the pre-refactor implementation. See the original module docstring
- * (preserved below) for the operator-facing flag + phase contract.
- *
- * Phases (selectable, run sequentially when no narrowing flag set):
- *   1. fast-forward-main — `git fetch origin <base>` → `git merge --ff-only`.
- *   2. prune-remotes     — `git fetch --prune <remote>`.
- *   3. branches          — enumerate merged local branches via `gh pr list`
- *                          + `git branch --merged <base>` and reap.
- *   4. stashes           — `git stash list` → optional per-stash drops.
- *
- * Exit codes:
- *   0 — clean (dry-run preview, or every active phase succeeded).
- *   1 — at least one phase reported a failure.
- *   2 — every active phase produced nothing to do (informational).
+ * Exit codes: 0 clean or dry-run, 1 a phase failed, 2 nothing to do.
  */
 
 import { runAsCli } from './lib/cli-utils.js';

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++) {