mandrel 1.58.0 → 1.59.0

package/.agents/scripts/providers/github/tickets.js

@@ -22,6 +22,7 @@
  */
 
 import { parseBlockedBy, parseBlocks } from '../../lib/dependency-parser.js';
+import { Logger } from '../../lib/Logger.js';
 import { addIssueToBoard } from './board-add.js';
 import { createInlineTicketCache } from './cache.js';
 import { withTransientRetry } from './errors.js';
@@ -32,6 +33,14 @@ import {
   parseApiJson,
 } from './request-helpers.js';
 
+/**
+ * GitHub Search API hard ceiling is 1000 results per query; at
+ * `per_page=100` that is 10 pages. An Epic never has anywhere near 1000
+ * children, so hitting this cap means the query is degenerate — we stop
+ * rather than throw (the regex post-filter keeps results correct).
+ */
+const SEARCH_PAGE_CAP = 10;
+
 /**
  * Compose the final markdown body for a created ticket. Under the 3-tier
  * hierarchy (Epic → Feature → Story), `body` is always a string supplied
@@ -100,6 +109,14 @@ export class TicketGateway {
     this.repo = repo;
     this._hooks = hooks;
     this._cache = cache ?? createInlineTicketCache();
+    /**
+     * Per-instance memo of `getTickets(epicId, filters)` results (Story
+     * #3988). The planning-state-manager fetches the same child list twice
+     * per planning pass; without this memo each fetch re-pays the full
+     * search/list round-trip. Invalidated on every write surface.
+     * @type {Map<string, object[]>}
+     */
+    this._listCache = new Map();
   }
 
   /**
@@ -142,29 +159,113 @@ export class TicketGateway {
   }
 
   /**
-   * @field-manifest /repos/{owner}/{repo}/issues?state=...&labels=...:
-   *                 number, body, labels, state, pull_request
+   * Run one Search API query (`/search/issues`) to completion, returning
+   * the raw issue items. Search responses are `{ total_count, items }`
+   * envelopes rather than bare arrays, so this paginates manually instead
+   * of going through `paginateRest`.
+   */
+  async _searchIssues(query) {
+    const items = [];
+    for (let page = 1; page <= SEARCH_PAGE_CAP; page++) {
+      const params = new URLSearchParams({
+        q: query,
+        per_page: '100',
+        page: String(page),
+      });
+      const result = await withTransientRetry(
+        () =>
+          this._gh.api({
+            method: 'GET',
+            endpoint: `/search/issues?${params}`,
+          }),
+        { label: `searchIssues page ${page}`, onRetry: defaultRetryWarn },
+      );
+      const parsed = parseApiJson(result);
+      const batch = Array.isArray(parsed?.items) ? parsed.items : [];
+      items.push(...batch);
+      if (batch.length < 100) break;
+    }
+    return items;
+  }
+
+  /**
+   * Server-side narrowed child lookup (Story #3988): two Search API
+   * queries — `"Epic: #N" in:body` and `"parent: #N" in:body` — deduped
+   * by issue number. Replaces the repo-wide `state=all` pagination that
+   * cost ~1 spawn per 100 repo issues and hard-failed past the
+   * `paginateRest` page cap. Search tokenization can over-match (e.g.
+   * `#10` vs `#100`), so callers MUST keep the word-boundary regex
+   * post-filter.
+   */
+  async _searchEpicChildren(epicId, filters) {
+    const qualifiers = [`repo:${this.owner}/${this.repo}`, 'is:issue'];
+    const state = filters.state ?? 'all';
+    if (state === 'open' || state === 'closed') {
+      qualifiers.push(`state:${state}`);
+    }
+    if (filters.label) qualifiers.push(`label:"${filters.label}"`);
+    const base = qualifiers.join(' ');
+
+    const [epicRefs, parentRefs] = await Promise.all([
+      this._searchIssues(`${base} "Epic: #${epicId}" in:body`),
+      this._searchIssues(`${base} "parent: #${epicId}" in:body`),
+    ]);
+
+    const byNumber = new Map();
+    for (const issue of [...epicRefs, ...parentRefs]) {
+      if (!byNumber.has(issue.number)) byNumber.set(issue.number, issue);
+    }
+    return Array.from(byNumber.values());
+  }
+
+  /**
+   * Repo-wide listing fallback — the pre-#3988 shape. Only used when the
+   * Search API path fails (search outage, search-specific rate limit).
    */
   /* node:coverage ignore next */
-  async getTickets(epicId, filters = {}) {
+  async _listAllIssues(filters) {
     const params = new URLSearchParams({ state: filters.state ?? 'all' });
     if (filters.label) params.set('labels', filters.label);
-
     const endpoint = `/repos/${this.owner}/${this.repo}/issues?${params}`;
-    const issues = await paginateRest(this._gh, endpoint);
+    return paginateRest(this._gh, endpoint);
+  }
+
+  /**
+   * @field-manifest /search/issues?q=...: number, id, node_id, title,
+   *                 body, labels, state, pull_request
+   * @field-manifest /repos/{owner}/{repo}/issues?state=...&labels=...:
+   *                 number, body, labels, state, pull_request
+   */
+  async getTickets(epicId, filters = {}) {
+    const memoKey = `${epicId}|${filters.state ?? 'all'}|${filters.label ?? ''}`;
+    if (this._listCache.has(memoKey)) return this._listCache.get(memoKey);
+
+    let issues;
+    try {
+      issues = await this._searchEpicChildren(epicId, filters);
+    } catch (err) {
+      const msg = typeof err?.message === 'string' ? err.message : String(err);
+      Logger.warn(
+        `[TicketGateway] search-based getTickets(#${epicId}) failed (${msg}); ` +
+          'falling back to repo-wide issue listing',
+      );
+      issues = await this._listAllIssues(filters);
+    }
 
     // Word-boundary regex prevents #1 matching #10, #100, etc.
     const epicRefRe = new RegExp(
       `(?:Epic:\\s*#${epicId}|parent:\\s*#${epicId})(?:\\s|$|[,.)\\]])`,
     );
 
-    return issues
+    const tickets = issues
       .filter((issue) => {
         if (issue.pull_request) return false;
         const body = issue.body ?? '';
         return epicRefRe.test(body);
       })
       .map(issueToListItem);
+    this._listCache.set(memoKey, tickets);
+    return tickets;
   }
 
   /* node:coverage ignore next */
@@ -187,6 +288,7 @@ export class TicketGateway {
 
   invalidateTicket(ticketId) {
     this._cache.invalidate(ticketId);
+    this._listCache.clear();
   }
 
   // ---------------------------------------------------------------------------
@@ -226,6 +328,7 @@ export class TicketGateway {
       },
     });
     const issue = parseApiJson(result);
+    this._listCache.clear();
 
     let subIssueLinked = false;
     let subIssueError = null;
@@ -288,6 +391,7 @@ export class TicketGateway {
       body: { title, body, labels },
     });
     const issue = parseApiJson(result);
+    this._listCache.clear();
 
     const boardAdd = await addIssueToBoard({
       nodeId: issue.node_id,

package/.agents/scripts/run-lint.js

@@ -69,6 +69,15 @@ const tasks = [
     cmd: 'node',
     args: ['.agents/scripts/lint-label-vocabulary.js'],
   },
+  {
+    // Architecture cycle ratchet (Story #3991). Detects directed import
+    // cycles under `.agents/scripts/` and fails on any cycle not in the
+    // committed allowlist (`baselines/arch-cycles.json`). Mirrors the
+    // ratchet-down semantics of `check-dead-exports.js`.
+    name: 'arch-cycles',
+    cmd: 'node',
+    args: ['.agents/scripts/check-arch-cycles.js'],
+  },
 ];
 
 function runTask({ name, cmd, args }) {

package/.agents/scripts/run-tests.js

@@ -84,11 +84,31 @@ export const TEST_RUNNER_FLAGS = Object.freeze([
  * quoting). Budgeting the targets to 8 000 chars keeps every spawn's full
  * command line at roughly a quarter of the ceiling — ample headroom for the
  * exe path and any pass-through `--test-name-pattern` args — while keeping
- * the chunk count (and thus the extra `node` start-ups) low. POSIX limits are
- * far higher, so this only ever splits work that would otherwise fail on
- * Windows.
+ * the chunk count (and thus the extra `node` start-ups) low.
+ *
+ * `MAX_TARGET_CHARS` is the **Windows** budget. On POSIX hosts `ARG_MAX` is
+ * far higher (~256 KB on macOS, ~1 MB on Linux), so applying the Windows
+ * budget there needlessly serializes the quick tier into several sequential
+ * `node --test` spawns — each chunk pays a fresh runner start-up, and cores
+ * idle at every chunk's tail. `POSIX_MAX_TARGET_CHARS` (100 000) lets the
+ * whole quick-tier target list (~33 000 chars today) collapse into a single
+ * spawn on POSIX while staying far below `ARG_MAX`.
+ * `resolveMaxTargetChars` picks the budget per platform; the Windows
+ * semantics of `MAX_TARGET_CHARS` are unchanged.
  */
 export const MAX_TARGET_CHARS = 8000;
+export const POSIX_MAX_TARGET_CHARS = 100_000;
+
+/**
+ * Resolve the per-spawn target-character budget for the host platform.
+ * The `platform` parameter is injected in tests.
+ *
+ * @param {NodeJS.Platform} [platform]
+ * @returns {number}
+ */
+export function resolveMaxTargetChars(platform = process.platform) {
+  return platform === 'win32' ? MAX_TARGET_CHARS : POSIX_MAX_TARGET_CHARS;
+}
 
 /**
  * Partition an ordered list of test-file targets into chunks whose joined
@@ -144,7 +164,7 @@ export function runTestSuite({
   spawn = spawnSync,
   cleanup = cleanupRepoTestTempArtifacts,
   listTargets = listTestFilesForTier,
-  maxTargetChars = MAX_TARGET_CHARS,
+  maxTargetChars = resolveMaxTargetChars(),
 } = {}) {
   const { tier, rest } = parseTierArgv(argv);
   const targets = listTargets(tier, cwd);

package/.agents/scripts/stories-wave-tick.js

@@ -43,6 +43,7 @@ import { runAsCli } from './lib/cli-utils.js';
 import { getRunners, resolveConfig } from './lib/config-resolver.js';
 import { assignLayers, detectCycle } from './lib/Graph.js';
 import { Logger } from './lib/Logger.js';
+import { buildStoryAdjacency } from './lib/story-adjacency.js';
 
 const HELP = `Usage: node .agents/scripts/stories-wave-tick.js --dag '<json>' | --dag-file <path> [--concurrency <n>]
 
@@ -132,15 +133,17 @@ export function parseDag(raw) {
  * Build an adjacency map from parsed DAG nodes.
  * Returns Map<id, id[]> where each id maps to its dependencies.
  *
+ * Delegates to the shared story-level builder
+ * (`lib/story-adjacency.js#buildStoryAdjacency`) with `dropForeign: false`
+ * to preserve the operator-DAG contract: a `dependsOn` id absent from the
+ * input set still deepens the dependent's layer (assignLayers treats the
+ * unknown id as a root).
+ *
  * @param {Array<{id: number, dependsOn: number[]}>} nodes
  * @returns {Map<number, number[]>}
  */
 export function buildAdjacency(nodes) {
-  const adjacency = new Map();
-  for (const node of nodes) {
-    adjacency.set(node.id, [...node.dependsOn]);
-  }
-  return adjacency;
+  return buildStoryAdjacency(nodes, { dropForeign: false });
 }
 
 /**

package/.agents/scripts/story-init.js

@@ -38,8 +38,13 @@ import {
 } from './lib/config-resolver.js';
 import { parseBlockedBy } from './lib/dependency-parser.js';
 import { getEpicBranch, getStoryBranch } from './lib/git-utils.js';
+import { runInstallCommand } from './lib/install-cmd-parser.js';
 import { Logger } from './lib/Logger.js';
 import { setActiveStoryEnv } from './lib/observability/active-story-env.js';
+import {
+  defaultStoryPhases,
+  upsertStoryRunProgress,
+} from './lib/orchestration/epic-runner/story-run-progress-writer.js';
 import { upsertStructuredComment } from './lib/orchestration/ticketing.js';
 import { createProvider } from './lib/provider-factory.js';
 import { validateBlockers } from './lib/story-init/blocker-validator.js';
@@ -330,11 +335,6 @@ export async function runStoryInit({
     hierarchy: hierarchyMode,
   });
 
-  emitStoryInitResult(result, {
-    storyId,
-    dryRun,
-  });
-
   if (!dryRun) {
     await postStoryInitComment({
       provider,
@@ -342,11 +342,153 @@ export async function runStoryInit({
       result,
       logger: stageLogger,
     });
+
+    // Story #4017 — the formerly standalone prepare CLI (which
+    // re-read the story-init structured comment seconds after this process
+    // wrote it) is inlined here: apply the install tri-state and render the
+    // initial Story-phase snapshot in-process, off the result we already
+    // hold.
+    result.prepare = await runStoryInitPrepare({
+      provider,
+      storyId,
+      result,
+      notify: _notifyFn,
+      logger: stageLogger,
+    });
   }
 
+  emitStoryInitResult(result, {
+    storyId,
+    dryRun,
+  });
+
   return { success: true, result };
 }
 
+const VALID_INSTALLED_STATES = new Set(['true', 'false', 'skipped']);
+
+/**
+ * Apply the dependenciesInstalled tri-state to derive the next install
+ * action. Pure helper — exposes the Step 0.5 truth table as data so tests
+ * can pin each branch without spinning up a child process.
+ *
+ * @param {'true' | 'false' | 'skipped'} dependenciesInstalled
+ * @param {{ skipInstall?: boolean }} [options]
+ * @returns {'skip' | 'install'}
+ */
+export function deriveInstallAction(dependenciesInstalled, options = {}) {
+  if (!VALID_INSTALLED_STATES.has(dependenciesInstalled)) {
+    throw new RangeError(
+      `deriveInstallAction: dependenciesInstalled "${dependenciesInstalled}" must be one of: ${[...VALID_INSTALLED_STATES].join(', ')}`,
+    );
+  }
+  if (options.skipInstall) return 'skip';
+  return dependenciesInstalled === 'false' ? 'install' : 'skip';
+}
+
+/**
+ * Resolve the install command to run when `dependenciesInstalled === 'false'`.
+ * `project.commands` does not currently carry a dedicated install key,
+ * so this defaults to `npm ci`. Operators can override per-invocation via
+ * the `installCmd` option.
+ *
+ * @param {{ override?: string }} [options]
+ * @returns {string}
+ */
+export function resolveInstallCommand(options = {}) {
+  const trimmed = options.override?.trim();
+  if (trimmed) {
+    return trimmed;
+  }
+  return 'npm ci';
+}
+
+/**
+ * Post-init prepare step (Story #4017 — formerly a standalone prepare
+ * CLI, now consuming the in-process init result
+ * instead of re-reading the `story-init` structured comment):
+ *
+ *   1. Apply the `dependenciesInstalled` tri-state truth table — `'false'`
+ *      (install attempted and failed) retries the install command in the
+ *      worktree; `'true'` / `'skipped'` proceed.
+ *   2. Render the initial Story-phase snapshot with every phase pinned to
+ *      `pending` and `phase: 'init'` via `upsertStoryRunProgress`
+ *      (render-only since Story #3909 — no comment is posted). The
+ *      `renderedBody` markdown is relayed to chat by the delivery
+ *      workflows so operators see the initial progress block before the
+ *      first commit lands.
+ *
+ * Install failure throws (init exits non-zero); a snapshot-render failure
+ * is non-fatal observability loss and only warns.
+ *
+ * @param {{
+ *   provider: object,
+ *   storyId: number,
+ *   result: { workCwd?: string, dependenciesInstalled?: string, storyBranch?: string },
+ *   notify?: Function | null,
+ *   runInstall?: (cmd: string, cwd: string) => { status: number, stderr?: string },
+ *   skipInstall?: boolean,
+ *   installCmd?: string,
+ *   logger?: object,
+ * }} args
+ * @returns {Promise<{
+ *   installAction: 'skip' | 'install',
+ *   installCmd: string | null,
+ *   installResult: { status: number, stderr?: string } | null,
+ *   snapshot: object | null,
+ *   renderedBody: string | null,
+ * }>}
+ */
+export async function runStoryInitPrepare({
+  provider,
+  storyId,
+  result,
+  notify: notifyFn = null,
+  runInstall = runInstallCommand,
+  skipInstall = false,
+  installCmd: installCmdOverride,
+  logger = stageLogger,
+}) {
+  const dependenciesInstalled = String(
+    result?.dependenciesInstalled ?? 'skipped',
+  );
+  const installAction = deriveInstallAction(dependenciesInstalled, {
+    skipInstall,
+  });
+  let installCmd = null;
+  let installResult = null;
+  if (installAction === 'install') {
+    installCmd = resolveInstallCommand({ override: installCmdOverride });
+    installResult = runInstall(installCmd, result.workCwd);
+    if (installResult.status !== 0) {
+      throw new Error(
+        `runStoryInitPrepare: install command \`${installCmd}\` failed with status ${installResult.status}: ${installResult.stderr ?? ''}`,
+      );
+    }
+  }
+
+  let snapshot = null;
+  let renderedBody = null;
+  try {
+    const { body, payload } = await upsertStoryRunProgress({
+      provider,
+      storyId,
+      branch: result?.storyBranch ?? `story-${storyId}`,
+      phase: 'init',
+      phases: defaultStoryPhases(),
+      notify: notifyFn,
+    });
+    snapshot = payload;
+    renderedBody = body;
+  } catch (err) {
+    logger?.warn?.(
+      `[story-init] ⚠️ Failed to render initial story-run-progress snapshot: ${err?.message ?? err}`,
+    );
+  }
+
+  return { installAction, installCmd, installResult, snapshot, renderedBody };
+}
+
 function buildStoryInitResult({
   storyId,
   epicId,
@@ -458,11 +600,8 @@ export function renderStoryInitCommentBody(result) {
     worktreeCreated: result.worktreeCreated,
     dependenciesInstalled: result.dependenciesInstalled,
     installStatus: result.installStatus,
-    // Embed the canonical task list so `story-deliver-prepare.js` can seed the
-    // initial `story-run-progress` snapshot without re-fetching the task graph.
-    // Without this field, the prepare CLI silently seeded an empty snapshot,
-    // breaking every subsequent phase-writer call (it asserts the
-    // task id is present in the snapshot).
+    // Embed the canonical task list so downstream snapshot consumers can
+    // seed phase-writer calls without re-fetching the task graph.
     tasks: Array.isArray(result.tasks)
       ? result.tasks.map((t) => ({ id: t.id, title: t.title }))
       : [],

package/.agents/scripts/sync-branch-from-base.js

@@ -31,10 +31,10 @@
 import path from 'node:path';
 import { parseArgs } from 'node:util';
 import { runAsCli } from './lib/cli-utils.js';
-import { PROJECT_ROOT } from './lib/config-resolver.js';
 import { syncBranchFromBase } from './lib/git/sync-from-base.js';
 import { gitSpawn, gitSync } from './lib/git-utils.js';
 import { Logger } from './lib/Logger.js';
+import { PROJECT_ROOT } from './lib/project-root.js';
 
 const progress = Logger.createProgress('sync-branch-from-base', {
   stderr: true,

package/.agents/skills/stack/qa/lighthouse-baseline/SKILL.md

@@ -58,7 +58,7 @@ The five pieces every baseline of this shape carries:
 3. **`<name>:check` npm script** — runs the measurement, compares against
    `baselines/<name>.json` with a tolerance, exits non-zero on regression.
    Wired into the close-validation gate chain (see `buildDefaultGates` in
-   `lib/close-validation.js`) and into the PR gate.
+   `lib/close-validation/gates.js`) and into the PR gate.
 4. **`--self-test` flag** — every check script accepts `--self-test`,
    which runs the comparator against synthetic inputs (a known-good and a
    known-regression fixture) and asserts the gate's verdict matches. CI