mandrel 2.31.0 → 2.33.0

package/.agents/scripts/install-matrix-assert.js

@@ -67,7 +67,6 @@ const FRAMEWORK_RUNTIME_DEPS = [
   'js-yaml',
   'minimatch',
   'picomatch',
-  'string-argv',
   'typhonjs-escomplex',
 ];
 

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

@@ -112,17 +112,6 @@ export class ITicketingProvider {
     throw new Error('Not implemented: getTicketDependencies');
   }
 
-  /**
-   * Fetch recent comments across the repository.
-   * Useful for auditing and visualization of agent telemetry.
-   *
-   * @param {number} [limit=100]
-   * @returns {Promise<object[]>}
-   */
-  async getRecentComments(_limit = 100) {
-    throw new Error('Not implemented: getRecentComments');
-  }
-
   /**
    * Fetch all comments for a specific ticket.
    *
@@ -137,42 +126,6 @@ export class ITicketingProvider {
   // Write Operations
   // ---------------------------------------------------------------------------
 
-  /**
-   * Create a child ticket within an Epic's structural hierarchy.
-   *
-   * @param {number} parentId - GitHub Issue number of the immediate structural parent (e.g. Epic or Story).
-   * @param {{
-   *   epicId: number,
-   *   title: string,
-   *   body: string,
-   *   labels: string[],
-   *   dependencies: number[]
-   * }} ticketData - The ticket content and metadata.
-   * @returns {Promise<{ id: number, url: string }>}
-   */
-
-  /**
-   * Link an existing issue as a sub-issue of a parent.
-   *
-   * @param {number} parentId - GitHub Issue number of the parent.
-   * @param {number} childId - GitHub internal database ID of the sub-issue.
-   * @returns {Promise<void>}
-   */
-  async addSubIssue(_parentId, _childId) {
-    throw new Error('Not implemented: addSubIssue');
-  }
-
-  /**
-   * Remove a sub-issue link from a parent.
-   *
-   * @param {number} parentId - GitHub Issue number of the parent.
-   * @param {number} childId - GitHub internal database ID of the sub-issue.
-   * @returns {Promise<void>}
-   */
-  async removeSubIssue(_parentId, _childId) {
-    throw new Error('Not implemented: removeSubIssue');
-  }
-
   /**
    * Mutate labels, body (tasklist checkboxes), and assignees on a ticket.
    *
@@ -213,17 +166,6 @@ export class ITicketingProvider {
     throw new Error('Not implemented: deleteComment');
   }
 
-  /**
-   * Open a Pull Request linking the specified ticket.
-   *
-   * @param {string} branchName - The source branch for the PR.
-   * @param {number} ticketId - GitHub Issue number to link.
-   * @returns {Promise<{ number: number, url: string, htmlUrl: string }>}
-   */
-  async createPullRequest(_branchName, _ticketId) {
-    throw new Error('Not implemented: createPullRequest');
-  }
-
   // ---------------------------------------------------------------------------
   // Setup Operations (used by bootstrap)
   // ---------------------------------------------------------------------------

package/.agents/scripts/lib/audit-baselines/staleness.js

@@ -16,25 +16,25 @@
  * @module lib/audit-baselines/staleness
  */
 
-import { execFileSync } from 'node:child_process';
+import { execFileCapture } from '../child-exec.js';
 import { KIND_SPECS } from './kinds.js';
 import { ageInDays } from './read.js';
 
 /**
  * Run a git command under `cwd`, returning trimmed stdout, or `null` on any
- * failure or empty result.
+ * failure or empty result. Buffer and shell policy come from the shared
+ * child-process surface ([`child-exec.js`](../child-exec.js)).
  *
  * @param {string[]} args
  * @param {{ cwd: string, run?: Function }} io
  * @returns {string | null}
  */
-function git(args, { cwd, run = execFileSync }) {
+function git(args, { cwd, run }) {
   try {
     const stdout = String(
-      run('git', args, {
+      execFileCapture('git', args, {
+        run,
         cwd,
-        encoding: 'utf8',
-        maxBuffer: 16 * 1024 * 1024,
         stdio: ['ignore', 'pipe', 'ignore'],
       }),
     ).trim();

package/.agents/scripts/lib/audit-baselines/trend.js

@@ -16,7 +16,7 @@
  * @module lib/audit-baselines/trend
  */
 
-import { execFileSync } from 'node:child_process';
+import { execFileCapture } from '../child-exec.js';
 import { trendRollupOf } from './kinds.js';
 
 /**
@@ -25,13 +25,13 @@ import { trendRollupOf } from './kinds.js';
  * @param {{ cwd: string, relPath: string, limit: number, run?: Function }} args
  * @returns {Array<{ sha: string, committedAt: string }>}
  */
-function listCommits({ cwd, relPath, limit, run = execFileSync }) {
+function listCommits({ cwd, relPath, limit, run }) {
   let stdout;
   try {
-    stdout = run(
+    stdout = execFileCapture(
       'git',
       ['log', `-n${limit}`, '--format=%H %cI', '--', relPath],
-      { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] },
+      { run, cwd, stdio: ['ignore', 'pipe', 'ignore'] },
     );
   } catch {
     return [];
@@ -52,13 +52,12 @@ function listCommits({ cwd, relPath, limit, run = execFileSync }) {
  * @param {{ cwd: string, kind: string, sha: string, relPath: string, run?: Function }} args
  * @returns {object | null}
  */
-function rollupAt({ cwd, kind, sha, relPath, run = execFileSync }) {
+function rollupAt({ cwd, kind, sha, relPath, run }) {
   let stdout;
   try {
-    stdout = run('git', ['show', `${sha}:${relPath}`], {
+    stdout = execFileCapture('git', ['show', `${sha}:${relPath}`], {
+      run,
       cwd,
-      encoding: 'utf8',
-      maxBuffer: 64 * 1024 * 1024,
       stdio: ['ignore', 'pipe', 'ignore'],
     });
   } catch {

package/.agents/scripts/lib/audit-baselines/weights.js

@@ -16,9 +16,9 @@
  * @module lib/audit-baselines/weights
  */
 
-import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
+import { execFileCapture } from '../child-exec.js';
 import { computeInDegree, resolveRepoGraph } from '../import-graph.js';
 
 /** Neutral multiplier every degraded weight collapses to. */
@@ -47,10 +47,10 @@ function saturate(count, half) {
  *   `degraded` is true when git could not answer at all — not a git work
  *   tree, no commits yet, or the binary is unavailable.
  */
-export function readChurn({ cwd, windowDays = 180, run = execFileSync }) {
+export function readChurn({ cwd, windowDays = 180, run }) {
   let stdout;
   try {
-    stdout = run(
+    stdout = execFileCapture(
       'git',
       [
         'log',
@@ -60,9 +60,8 @@ export function readChurn({ cwd, windowDays = 180, run = execFileSync }) {
         '--no-renames',
       ],
       {
+        run,
         cwd,
-        encoding: 'utf8',
-        maxBuffer: 64 * 1024 * 1024,
         // git narrates "not a git repository" on stderr; the degradation is
         // reported in the envelope, not shouted at the operator.
         stdio: ['ignore', 'pipe', 'ignore'],

package/.agents/scripts/lib/audit-suite/checklist-threading.js

@@ -41,7 +41,7 @@ import path from 'node:path';
 import { AUDIT_LENSES } from '../audit-to-stories/audit-lenses.js';
 import { getPaths, PROJECT_ROOT, resolveConfig } from '../config-resolver.js';
 import { Logger } from '../Logger.js';
-import { estimateTokens } from '../orchestration/context-envelope.js';
+import { estimateTokens } from '../orchestration/spec-spill.js';
 import {
   changeSetLacksSiblingTest,
   matchesAnyFilePattern,

package/.agents/scripts/lib/audit-to-stories/build-story-body.js

@@ -22,6 +22,7 @@
  * structured contract.
  */
 
+import path from 'node:path';
 import { AGENT_LABELS, RISK_LABELS, TYPE_LABELS } from '../label-constants.js';
 import { serialize } from '../story-body/story-body.js';
 import { definesAuditLabel } from './audit-label-taxonomy.js';
@@ -116,10 +117,7 @@ function acceptanceCriteriaFromGroup(group) {
 
 /**
  * Resolve the `edges[]` sequencing anchored on this group. Each edge whose
- * `fromGroupKey` matches this group's key contributes its `toGroupKey`. Group
- * keys are the only stable identifier available at emit time — issues are not
- * numbered yet — so the relationship is preserved as machine-readable keys the
- * operator can resolve.
+ * `fromGroupKey` matches this group's key contributes its `toGroupKey`.
  *
  * @param {object} group
  * @param {Array<{ fromGroupKey: string, toGroupKey: string }>} edges
@@ -135,22 +133,38 @@ function sequencingDepsForGroup(group, edges) {
 }
 
 /**
- * Render the carried-through `edges[]` sequencing as a dedicated extended
- * markdown block. The canonical `depends_on[]` footer only round-trips `#N`
- * issue refs (`blocked by #123`), which do not exist before the issues are
- * opened; rendering the group-key sequencing as its own informational section
- * keeps the signal in the body (not discarded — Story #4270) and survives
- * `parse()` / `serialize()` round-tripping (it is preamble/extended content,
- * not a structured section). Returns the empty string when there is no
- * sequencing to surface.
+ * Resolve this group's sequencing to canonical `#N` issue refs, or `[]` when
+ * the caller has no issue numbers yet (Story #5044).
  *
- * @param {string[]} deps
- * @returns {string}
+ * Group keys are the only identifier that exists at *emit* time — the issues
+ * are not numbered — which is why this used to render as a prose
+ * `## Sequencing` block that nothing could act on. Standalone audit Stories
+ * therefore hardcoded `depends_on: []`, and their only actual serializer was
+ * an accident: their shared provenance footers collided under the delivery
+ * footprint guard. Narrowing that scrape removes the accident, so the ordering
+ * has to become real in the same change.
+ *
+ * The resolution is the two-pass shape `plan-persist` already uses: create every
+ * issue first, then re-render each body with the now-known numbers and mirror
+ * the same edges as native `blocked_by` relations. An edge whose target was not
+ * created (deduped against an existing Issue, suppressed by the ledger) simply
+ * drops — a `blocked by #undefined` would be worse than an absent edge.
+ *
+ * A **plain object**, deliberately, not a `Map`: the same map is handed to
+ * `applyBlockedByDependencies`, which indexes it with property access, so a
+ * `Map` there would silently resolve every lookup to `undefined`, skip every
+ * edge, and report success having written nothing. One shape, both halves.
+ *
+ * @param {string[]} deps                     Group keys this group depends on.
+ * @param {Record<string, number>|null} issueByGroupKey
+ * @returns {string[]} `#N` refs, in `deps` order.
  */
-function sequencingSection(deps) {
-  if (deps.length === 0) return '';
-  const lines = deps.map((k) => `- depends on group \`${k}\``);
-  return ['## Sequencing', '', lines.join('\n'), ''].join('\n');
+function dependencyRefs(deps, issueByGroupKey) {
+  if (!issueByGroupKey) return [];
+  return deps
+    .map((key) => issueByGroupKey[key])
+    .filter((n) => Number.isInteger(n) && n > 0)
+    .map((n) => `#${n}`);
 }
 
 function agentPromptsSection(group) {
@@ -162,6 +176,21 @@ function agentPromptsSection(group) {
   return blocks.join('\n\n') || '_(no copy-pasteable prompts captured)_';
 }
 
+/**
+ * Link each source audit report **once**.
+ *
+ * This used to render `- [\`path\`](path)` — the same
+ * `temp/audits/audit-<lens>-results.md` in the link text and again in the URL,
+ * byte-identical across every Story of a same-lens sweep. That doubled a token
+ * the delivery footprint guard scraped as edit intent, so a lens's whole cohort
+ * serialized on a report none of them would ever write to (Story #5044). The
+ * guard now ignores markdown-link URLs and temp-root paths, but rendering the
+ * path twice was never useful to a reader either: the file name is the label,
+ * the path is the target.
+ *
+ * @param {object} group
+ * @returns {string}
+ */
 function contextLinksFromGroup(group) {
   const reports = uniq(
     (group.findings ?? [])
@@ -169,7 +198,11 @@ function contextLinksFromGroup(group) {
       .filter((s) => typeof s === 'string'),
   );
   if (reports.length === 0) return '_(no source audit reports captured)_';
-  return reports.map((r) => `- [\`${r}\`](${r})`).join('\n');
+  // `path.basename` rather than `split('/')`: on win32 it splits on both
+  // separators, so an absolute Windows path yields the file name instead of
+  // the whole path — which would render the path twice in one link and
+  // re-create the very duplication this function exists to remove.
+  return reports.map((r) => `- [${path.basename(r)}](${r})`).join('\n');
 }
 
 function labelsForGroup(group) {
@@ -226,20 +259,27 @@ function assertLabelsInTaxonomy(labels) {
  *   — the dependency `edges[]` emitted by `groupFindings`. Edges anchored on
  *   this group are carried through to `depends_on[]`; omit when no sequencing
  *   is known.
- * @returns {{ title: string, body: string, labels: string[] }}
+ * @param {Record<string, number>|null} [params.issueByGroupKey]
+ *   — group key → opened issue number. Supplied on the **second** pass, once
+ *   the issues exist, so this group's edges render as canonical
+ *   `blocked by #N` footers (Story #5044). Omit on the first pass.
+ * @returns {{ title: string, body: string, labels: string[], groupKey: string, dependsOn: string[] }}
+ *   `groupKey` and `dependsOn` are the caller's handle on the second pass:
+ *   they name this Story and the groups it must follow, so the caller can map
+ *   both onto issue numbers without re-deriving the grouping.
  */
-export function buildStoryBody({ group, edges = [] }) {
+export function buildStoryBody({ group, edges = [], issueByGroupKey = null }) {
   if (!group || !Array.isArray(group.findings)) {
     throw new Error('buildStoryBody: group with findings[] is required');
   }
   const title = group.title;
+  const dependsOn = sequencingDepsForGroup(group, edges);
 
   // Build the canonical StoryBody object from the audit group data. The
   // acceptance + verify arrays are populated so the body clears the
-  // inline-contract bar; changes[] carries the file footprint. The edges[]
-  // sequencing is carried through as an extended `## Sequencing` block (see
-  // sequencingSection) — group keys are not `#N` refs, so they cannot ride the
-  // canonical depends_on footer.
+  // inline-contract bar; changes[] carries the file footprint. `depends_on`
+  // is empty on the first pass (the blockers have no issue numbers yet) and
+  // carries real `#N` refs on the second — see dependencyRefs.
   const storyBody = {
     goal: goalFromGroup(group),
     changes: changesFromGroup(group),
@@ -248,21 +288,21 @@ export function buildStoryBody({ group, edges = [] }) {
     references: [],
     wide: null,
     reason_to_exist: null,
-    depends_on: [],
-    estimated_test_files: null,
+    depends_on: dependencyRefs(dependsOn, issueByGroupKey),
   };
 
-  // Serialize via the canonical serializer (no footer — depends_on is empty).
-  const canonicalSections = serialize(storyBody);
-  const sequencing = sequencingSection(sequencingDepsForGroup(group, edges));
+  // The `---` / `blocked by #N` footer is the canonical serializer's own, so
+  // the body round-trips through `parse()` and `/deliver`'s resolver reads the
+  // ordering from the same place it reads every other Story's.
+  const canonicalSections = serialize(storyBody, {
+    includeFooter: storyBody.depends_on.length > 0,
+  });
 
-  // Append audit-specific extended sections (sequencing, agent prompts,
-  // context links, fingerprint footer) that are not part of the canonical
-  // shape.
+  // Append audit-specific extended sections (agent prompts, context links,
+  // provenance footers) that are not part of the canonical shape.
   const body = [
     canonicalSections,
     '',
-    ...(sequencing ? [sequencing] : []),
     '## Agent Prompts',
     '',
     agentPromptsSection(group),
@@ -277,5 +317,11 @@ export function buildStoryBody({ group, edges = [] }) {
     renderSemanticKeyFooter(group.findings),
   ].join('\n');
 
-  return { title, body, labels: labelsForGroup(group) };
+  return {
+    title,
+    body,
+    labels: labelsForGroup(group),
+    groupKey: group.groupKey,
+    dependsOn,
+  };
 }

package/.agents/scripts/lib/audit-to-stories/wire-dependencies.js

@@ -0,0 +1,185 @@
+/**
+ * lib/audit-to-stories/wire-dependencies.js — turn a standalone audit cohort's
+ * detected group edges into declared ordering, once the issues exist.
+ *
+ * `groupFindings` detects `edges[]` between finding groups, but at emit time
+ * the groups have no issue numbers, so the ordering could only be rendered as
+ * prose. Every standalone audit Story therefore shipped with `depends_on: []`,
+ * and what actually kept a cohort from being co-dispatched onto colliding
+ * branches was an **accident**: siblings shared the sweep-wide audit provenance
+ * footers `plan-persist` stamps, and the delivery footprint guard scraped
+ * path-shaped tokens out of them. Story #5044 narrows that scrape, which is why
+ * this module lands with it — removing the accidental serializer without giving
+ * the cohort a real one would leave it less ordered than before.
+ *
+ * The shape is `plan-persist`'s two-pass crossing (`plan-persist/story-ops.js`),
+ * because it is the same problem: **create every issue first, then mirror the
+ * edges**. Both halves are written:
+ *
+ *   1. The **body footer** (`---` / `blocked by #N`) — canonical, parsed by
+ *      `/deliver`'s resolver, and the fallback when the dependencies API is
+ *      unavailable.
+ *   2. The **native `blocked_by` relation** — visible in the GitHub UI,
+ *      readable without parsing markdown, and settable by an operator later.
+ *
+ * Native mirroring is **non-fatal by design**, matching `plan-persist`: the
+ * footer has already been written by the time it runs, so a dependencies API
+ * that says no costs visibility, not ordering.
+ *
+ * @module lib/audit-to-stories/wire-dependencies
+ */
+
+import { applyBlockedByDependencies } from '../../providers/github/blocked-by-add.js';
+import { Logger } from '../Logger.js';
+import { buildStoryBody } from './build-story-body.js';
+
+/**
+ * Re-render each created Story's body with its blockers resolved to `#N`, and
+ * mirror the same edges as native `blocked_by` relations.
+ *
+ * Groups whose issue was not created — deduped against an existing Issue,
+ * suppressed by the ledger, or simply not in `issueByGroupKey` — are skipped
+ * rather than guessed at, and an edge pointing at one drops with them
+ * (`dependencyRefs` filters it). A `blocked by #undefined` would gate a Story
+ * on nothing forever, which is strictly worse than the un-ordered cohort this
+ * replaces.
+ *
+ * @param {object} args
+ * @param {Array<object>} args.groups          The `create`-eligible groups, in
+ *   the order their issues were opened.
+ * @param {Array<{ fromGroupKey: string, toGroupKey: string }>} [args.edges]
+ * @param {Record<string, number>} args.issueByGroupKey  Group key → issue number.
+ * @param {(issueNumber: number, body: string) => Promise<unknown>} args.updateBody
+ *   Persist a re-rendered body. Injected so the caller owns the provider call.
+ * @param {object|null} [args.provider] Provider for native edge mirroring.
+ *   Omit (or pass one without the dependency ports) to write footers only.
+ * @returns {Promise<{
+ *   storiesWired: number,
+ *   bodiesUpdated: number,
+ *   edgesDeclared: number,
+ *   native: { edgesAdded: number, edgesSkipped: number, edgesFailed: number }|null
+ * }>}
+ */
+export async function wireAuditStoryEdges({
+  groups,
+  edges = [],
+  issueByGroupKey,
+  updateBody,
+  provider = null,
+}) {
+  const wired = collectWiredStories({ groups, edges, issueByGroupKey });
+  if (wired.length === 0) {
+    return {
+      storiesWired: 0,
+      bodiesUpdated: 0,
+      edgesDeclared: 0,
+      native: null,
+    };
+  }
+
+  let bodiesUpdated = 0;
+  for (const story of wired) {
+    await updateBody(story.issueNumber, story.body);
+    bodiesUpdated++;
+  }
+
+  return {
+    storiesWired: wired.length,
+    bodiesUpdated,
+    edgesDeclared: wired.reduce((n, s) => n + s.blockerKeys.length, 0),
+    native: await mirrorNativeEdges({ provider, wired, issueByGroupKey }),
+  };
+}
+
+/**
+ * Re-render every group that both has an issue **and** has at least one blocker
+ * whose issue also exists.
+ *
+ * A group with no resolvable blocker is deliberately left alone rather than
+ * rewritten to an identical body: an issue-body update is a mutation and a
+ * notification, and doing it for a no-op edit is noise on every Story of every
+ * sweep.
+ *
+ * @param {object} args
+ * @returns {Array<{ groupKey: string, issueNumber: number, body: string, blockerKeys: string[] }>}
+ */
+function collectWiredStories({ groups, edges, issueByGroupKey }) {
+  const wired = [];
+  for (const group of groups ?? []) {
+    const issueNumber = issueByGroupKey?.[group?.groupKey];
+    if (!Number.isInteger(issueNumber)) continue;
+    const rendered = buildStoryBody({ group, edges, issueByGroupKey });
+    const blockerKeys = rendered.dependsOn.filter((key) =>
+      Number.isInteger(issueByGroupKey[key]),
+    );
+    if (blockerKeys.length === 0) continue;
+    wired.push({
+      groupKey: rendered.groupKey,
+      issueNumber,
+      body: rendered.body,
+      blockerKeys,
+    });
+  }
+  return wired;
+}
+
+/**
+ * Mirror the declared edges as native GitHub `blocked_by` relations.
+ *
+ * Two shape hazards this crossing inherits from `plan-persist`, both silent if
+ * missed: `applyBlockedByDependencies` indexes `slugToIssueNumber` with plain
+ * property access (so it must be a plain object, never a `Map` — a `Map` yields
+ * `undefined` for every lookup, skips every edge, and reports success having
+ * written nothing), and it reads `dependsOn`, not `depends_on`.
+ *
+ * @param {object} args
+ * @returns {Promise<{ edgesAdded: number, edgesSkipped: number, edgesFailed: number }|null>}
+ *   `null` when there is no interface to mirror through.
+ */
+async function mirrorNativeEdges({ provider, wired, issueByGroupKey }) {
+  if (
+    typeof provider?.getDependencyWriteContext !== 'function' ||
+    typeof provider?.getTicket !== 'function'
+  ) {
+    Logger.warn(
+      '[audit-to-stories] provider exposes no getDependencyWriteContext/getTicket — ' +
+        'skipping native blocked_by edges. Ordering survives in the ' +
+        '`blocked by #N` body footers just written.',
+    );
+    return null;
+  }
+  try {
+    const { gh, owner, repo } = provider.getDependencyWriteContext();
+    const summary = await applyBlockedByDependencies({
+      // The group key IS the slug here — it is the stable identifier both
+      // sides of an edge are keyed by — so `issueByGroupKey` is already the
+      // slug→number map the helper wants.
+      stories: wired.map((s) => ({
+        slug: s.groupKey,
+        dependsOn: s.blockerKeys,
+      })),
+      slugToIssueNumber: issueByGroupKey,
+      getTicket: (issueNumber) => provider.getTicket(issueNumber),
+      owner,
+      repo,
+      gh,
+    });
+    if (summary.edgesFailed > 0) {
+      Logger.warn(
+        `[audit-to-stories] ${summary.edgesFailed} native blocked_by edge(s) could ` +
+          'not be written. Ordering survives in the `blocked by #N` body footers.',
+      );
+    }
+    return {
+      edgesAdded: summary.edgesAdded,
+      edgesSkipped: summary.edgesSkipped,
+      edgesFailed: summary.edgesFailed,
+    };
+  } catch (err) {
+    Logger.warn(
+      `[audit-to-stories] native blocked_by mirroring failed (${err.message}) — ` +
+        'ordering survives in the `blocked by #N` body footers.',
+    );
+    return null;
+  }
+}