mandrel 2.31.0 → 2.32.0

package/.agents/scripts/providers/github/sub-issues.js

@@ -1,21 +1,19 @@
 /**
  * GitHub Provider — SubIssueGateway.
  *
- * Owns the native GitHub Sub-Issues link surface (the GraphQL `subIssues`
- * field on an Issue, plus the add/remove mutations) along with the
- * `reconcileSubIssueLinks` walker that backfills missing parent/child
- * links across an Epic's child set.
+ * Owns the **read** side of the native GitHub Sub-Issues surface: the
+ * GraphQL `subIssues` field on an Issue, paginated into a child-number
+ * list. Story #5008 removed the write side (`addSubIssue`,
+ * `removeSubIssue`) and the `reconcileSubIssueLinks` walker along with the
+ * rest of the Epic-hierarchy provider surface — v2 delivery is Story-only,
+ * so nothing establishes or repairs parent/child links any more.
  *
- * Extracted from `../github.js` in Story #2462 / Task #2480. Public
- * surface on `GitHubProvider` is unchanged — `addSubIssue`,
- * `removeSubIssue`, and `reconcileSubIssueLinks` all delegate here.
+ * Extracted from `../github.js` in Story #2462 / Task #2480. The read path
+ * still reaches `GitHubProvider` as `_getNativeSubIssues`, and
+ * `IssuesGateway` calls it directly through its `getNativeSubIssues` hook.
  *
- * Constructed with `{ ghGraphql, hooks, classifyGithubError, cache, queries }`:
+ * Constructed with `{ ghGraphql, cache, classifyGithubError }`:
  *   - `ghGraphql(query, variables, opts)`    — bound `_ghGraphql` from the parent.
- *   - `hooks.getTicket(id, opts)`            — bound to the TicketGateway.
- *   - `hooks.getTickets(parentId)`           — bound to the TicketGateway (for the reconciler).
- *   - `hooks.primeTicketCache(tickets)`      — bound to the TicketGateway (reconciler priming).
- *   - `hooks.invalidateTicket(id)`           — bound to the TicketGateway (post-mutation invalidate).
  *   - `cache.primeIfAbsent(ticket)`          — bound to the shared cache (native-walk priming).
  *
  * The gateway holds **no** transport state of its own — every call goes
@@ -26,25 +24,14 @@
  */
 
 import { Logger } from '../../lib/Logger.js';
-import { concurrentMap } from '../../lib/util/concurrent-map.js';
 import {
-  ADD_SUB_ISSUE_MUTATION,
   classifyGithubError as defaultClassifyGithubError,
-  REMOVE_SUB_ISSUE_MUTATION,
   SUB_ISSUES_QUERY,
   withTransientRetry,
 } from './errors.js';
 import { subIssueNodeToTicket } from './mappers.js';
 import { defaultRetryWarn } from './request-helpers.js';
 
-// Concurrency + retry budgets — preserved from `../github.js` so dispatch
-// fan-out and sub-issue reconciliation keep their established shapes.
-const SUB_ISSUE_RECONCILE_CONCURRENCY = 4;
-const SUB_ISSUE_RETRY_MAX_ATTEMPTS = 6;
-const SUB_ISSUE_RETRY_BASE_DELAY_MS = 1000;
-const SUB_ISSUE_RETRY_MAX_DELAY_MS = 30000;
-const SUB_ISSUE_RETRY_JITTER_MS = 500;
-
 // Story #2852: cap the native sub-issue cursor walk so a runaway pagination
 // (e.g. an upstream API regression that never sets `hasNextPage = false`)
 // fails fast instead of looping forever. 50 cursor pages × 100 nodes per
@@ -55,24 +42,16 @@ export class SubIssueGateway {
   /**
    * @param {{
    *   ghGraphql: (query: string, variables?: object, opts?: object) => Promise<object>,
-   *   hooks?: {
-   *     getTicket?: (id: number, opts?: object) => Promise<object>,
-   *     getTickets?: (parentId: number) => Promise<object[]>,
-   *     primeTicketCache?: (tickets: object[]) => void,
-   *     invalidateTicket?: (id: number) => void,
-   *   },
    *   cache?: { primeIfAbsent: (ticket: object) => void },
    *   classifyGithubError?: (err: unknown) => string,
    * }} deps
    */
   constructor({
     ghGraphql,
-    hooks = {},
     cache,
     classifyGithubError = defaultClassifyGithubError,
   } = {}) {
     this._ghGraphql = ghGraphql;
-    this._hooks = hooks;
     this._cache = cache;
     this._classify = classifyGithubError;
   }
@@ -132,191 +111,4 @@ export class SubIssueGateway {
     }
     return childIds;
   }
-
-  /**
-   * Establish the native sub-issue link between `parentNumber` and the
-   * child identified by `childNodeId`. Retries on transient errors with
-   * jittered exponential backoff before re-throwing.
-   */
-  async addSubIssue(
-    parentNumber,
-    childNodeId,
-    opts = { replaceParent: false },
-  ) {
-    const getTicket = this._hooks.getTicket;
-    if (typeof getTicket !== 'function') {
-      throw new Error(
-        '[SubIssueGateway] addSubIssue requires a getTicket hook',
-      );
-    }
-    const parentTicket = await getTicket(parentNumber);
-    let lastErr;
-    for (let attempt = 0; attempt < SUB_ISSUE_RETRY_MAX_ATTEMPTS; attempt++) {
-      try {
-        const result = await this._ghGraphql(
-          ADD_SUB_ISSUE_MUTATION,
-          {
-            parentId: parentTicket.nodeId,
-            subIssueId: childNodeId,
-            replaceParent: opts.replaceParent,
-          },
-          { headers: { 'GraphQL-Features': 'sub_issues' } },
-        );
-        // Sub-issue link mutates the parent's sub-issue list. Invalidate so
-        // the next `getTicket(parentNumber)` re-fetches a coherent view.
-        if (typeof this._hooks.invalidateTicket === 'function') {
-          this._hooks.invalidateTicket(parentNumber);
-        }
-        return result;
-      } catch (err) {
-        lastErr = err;
-        const category = this._classify(err);
-        const isFinalAttempt = attempt === SUB_ISSUE_RETRY_MAX_ATTEMPTS - 1;
-        if (category !== 'transient' || isFinalAttempt) throw err;
-        const base = Math.min(
-          SUB_ISSUE_RETRY_MAX_DELAY_MS,
-          SUB_ISSUE_RETRY_BASE_DELAY_MS * 2 ** attempt,
-        );
-        const delay =
-          base + Math.floor(Math.random() * SUB_ISSUE_RETRY_JITTER_MS);
-        Logger.warn(
-          `[GitHubProvider] sub-issue link transient error for parent #${parentNumber} (attempt ${attempt + 1}/${SUB_ISSUE_RETRY_MAX_ATTEMPTS}); retrying in ${delay}ms: ${err.message}`,
-        );
-        await new Promise((r) => setTimeout(r, delay));
-      }
-    }
-    throw lastErr;
-  }
-
-  async removeSubIssue(parentNumber, subIssueNumber) {
-    const getTicket = this._hooks.getTicket;
-    if (typeof getTicket !== 'function') {
-      throw new Error(
-        '[SubIssueGateway] removeSubIssue requires a getTicket hook',
-      );
-    }
-    const parentTicket = await getTicket(parentNumber);
-    const childTicket = await getTicket(subIssueNumber);
-    const result = await this._ghGraphql(
-      REMOVE_SUB_ISSUE_MUTATION,
-      { parentId: parentTicket.nodeId, subIssueId: childTicket.nodeId },
-      { headers: { 'GraphQL-Features': 'sub_issues' } },
-    );
-    if (typeof this._hooks.invalidateTicket === 'function') {
-      this._hooks.invalidateTicket(parentNumber);
-      this._hooks.invalidateTicket(subIssueNumber);
-    }
-    return result;
-  }
-
-  /**
-   * Walk every child of `epicId` whose body footer carries `parent: #N` and
-   * verify the native sub-issue link is present. Re-establish missing links
-   * via `addSubIssue` (which retries internally). Idempotent.
-   */
-  async reconcileSubIssueLinks(epicId) {
-    const PARENT_RE = /(?:^|\n)parent:\s*#(\d+)/;
-    const getTicket = this._hooks.getTicket;
-    const getTickets = this._hooks.getTickets;
-    if (typeof getTicket !== 'function' || typeof getTickets !== 'function') {
-      throw new Error(
-        '[SubIssueGateway] reconcileSubIssueLinks requires getTicket + getTickets hooks',
-      );
-    }
-    const allChildren = await getTickets(epicId);
-    const parentByChild = new Map();
-    for (const child of allChildren) {
-      const match = (child.body ?? '').match(PARENT_RE);
-      if (!match) continue;
-      parentByChild.set(child.id, Number.parseInt(match[1], 10));
-    }
-
-    const childrenByParent = new Map();
-    for (const [childId, parentId] of parentByChild) {
-      if (!childrenByParent.has(parentId)) childrenByParent.set(parentId, []);
-      childrenByParent.get(parentId).push(childId);
-    }
-
-    let alreadyLinked = 0;
-    let reconciled = 0;
-    let failed = 0;
-    const failures = [];
-
-    const parentEntries = Array.from(childrenByParent.entries());
-
-    await concurrentMap(
-      parentEntries,
-      async ([parentId, childIds]) => {
-        let parent;
-        try {
-          parent = await getTicket(parentId);
-        } catch (err) {
-          for (const childId of childIds) {
-            failures.push({ parentId, childId, reason: err.message });
-          }
-          failed += childIds.length;
-          return;
-        }
-        if (!parent?.nodeId) {
-          for (const childId of childIds) {
-            failures.push({
-              parentId,
-              childId,
-              reason: 'parent missing nodeId',
-            });
-          }
-          failed += childIds.length;
-          return;
-        }
-
-        const linked = new Set(
-          await this.getNativeSubIssues(parent.nodeId, parentId),
-        );
-
-        await concurrentMap(
-          childIds,
-          async (childId) => {
-            if (linked.has(childId)) {
-              alreadyLinked++;
-              return;
-            }
-            let childTicket;
-            try {
-              childTicket = await getTicket(childId);
-            } catch (err) {
-              failures.push({ parentId, childId, reason: err.message });
-              failed++;
-              return;
-            }
-            if (!childTicket?.nodeId) {
-              failures.push({
-                parentId,
-                childId,
-                reason: 'child missing nodeId',
-              });
-              failed++;
-              return;
-            }
-            try {
-              await this.addSubIssue(parentId, childTicket.nodeId);
-              reconciled++;
-            } catch (err) {
-              failures.push({ parentId, childId, reason: err.message });
-              failed++;
-            }
-          },
-          { concurrency: SUB_ISSUE_RECONCILE_CONCURRENCY },
-        );
-      },
-      { concurrency: SUB_ISSUE_RECONCILE_CONCURRENCY },
-    );
-
-    return {
-      totalExpected: parentByChild.size,
-      alreadyLinked,
-      reconciled,
-      failed,
-      failures,
-    };
-  }
 }

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

@@ -19,8 +19,10 @@
  * module.
  *
  * Gateway map: tickets, sub-issues, comments, labels, branch-protection,
- * merge-methods, prs, project-board, issues (epics + sub-tickets +
- * branch probe + raw GraphQL).
+ * merge-methods, project-board, issues (epics + sub-tickets + branch probe
+ * + raw GraphQL). Story #5008 retired the `prs` gateway — `single-story-close`
+ * drives `gh pr create` directly — along with the sub-issue write surface and
+ * the repo-wide recent-comments feed.
  */
 
 import { createGh, gh as defaultGh } from '../lib/gh-exec.js';
@@ -125,16 +127,11 @@ const DELEGATIONS = [
   ['updateTicket', 'tickets.updateTicket'],
   ['_applyLabelMutations', 'tickets._applyLabelMutations'],
   ['_getNativeSubIssues', 'subIssues.getNativeSubIssues'],
-  ['addSubIssue', 'subIssues.addSubIssue'],
-  ['removeSubIssue', 'subIssues.removeSubIssue'],
-  ['reconcileSubIssueLinks', 'subIssues.reconcileSubIssueLinks'],
-  ['getRecentComments', 'comments.getRecentComments'],
   ['getTicketComments', 'comments.getTicketComments'],
   ['deleteComment', 'comments.deleteComment'],
   ['postComment', 'comments.postComment'],
   ['getBranchProtection', 'branchProtection.getBranchProtection'],
   ['setBranchProtection', 'branchProtection.setBranchProtection'],
-  ['createPullRequest', 'pullRequests.createPullRequest'],
   ['ensureLabels', 'labels.ensureLabels'],
   ['_reconcileLabelsPresence', 'labels._reconcileLabelsPresence'],
   ['getMergeMethods', 'mergeMethods.getMergeMethods'],

package/.agents/scripts/prune-baseline-orphans.js

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+
+// .agents/scripts/prune-baseline-orphans.js — Story #5012.
+//
+// Delete the baseline rows that are provably inert, and nothing else.
+//
+// This is the cheap remedy that makes `check-baseline-scope.js` fair. A gate
+// that hard-fails on a stale row is only defensible while clearing one costs a
+// command rather than a full re-score: the honest alternative — re-derive the
+// whole baseline — spends a coverage run or a full-tree MI pass to express a
+// deletion, which is why stale rows accumulate instead.
+//
+// Two row classes qualify, both decidable without measuring anything:
+//
+//   - `absent`       — the row's file is gone from disk.
+//   - `out-of-scope` — the file is still there, but the gate's own
+//                      `targetDirs` / `ignoreGlobs` no longer match it.
+//
+// The pruner never adds a row, never restamps `generatedAt` (a fresh stamp
+// over unmeasured rows is the exact failure an age check exists to catch), and
+// recomputes `rollup` through the kind's own arithmetic so the pruned envelope
+// still validates against its schema. An unreadable scope config degrades to
+// orphan-only pruning rather than treating unknown scope as empty scope.
+//
+// Exit codes:
+//   0  nothing to prune (or, without `--check`, the prune was written)
+//   1  `--check` found rows that would be pruned
+//   2  the pruner could not run
+
+// Fail-fast if the framework's runtime deps are not installed — must be the
+// first import so the check runs before any third-party-importing sibling
+// module is evaluated (Story #3432).
+import './lib/runtime-deps/ensure-installed.js';
+import { PRUNABLE_KINDS, runPrune } from './lib/baselines/orphan-pruner.js';
+import { runAsCli } from './lib/cli-utils.js';
+import { getQuality } from './lib/config/quality.js';
+import { resolveConfig } from './lib/config-resolver.js';
+
+const EXIT_CLEAN = 0;
+const EXIT_WOULD_PRUNE = 1;
+const EXIT_CANNOT_RUN = 2;
+
+const HELP = {
+  invocation:
+    'node .agents/scripts/prune-baseline-orphans.js [--check] [--kind <kind>] [--json]',
+  summary:
+    "Remove baseline rows whose file is gone from disk or has left the gate's scope. Never adds a row, never restamps generatedAt, never re-scores.",
+  flags: [
+    ['--check', 'Report what would be pruned, write nothing, exit 1 if any.'],
+    ['--kind <kind>', 'Prune one kind only (repeatable). Default: all.'],
+    ['--json', 'Emit the report as JSON instead of text.'],
+    ['--cwd <dir>', 'Repository root to prune. Default: process.cwd().'],
+  ],
+  notes: [
+    'Exit codes:\n  0  clean, or pruned\n  1  --check found prunable rows\n  2  the pruner could not run',
+  ],
+};
+
+/**
+ * Parse argv into an options bag. An unknown flag is an error, never a silent
+ * no-op — a typo'd `--dry-run` must not read as "write the files".
+ *
+ * @param {string[]} argv
+ * @returns {{ kinds: string[], check: boolean, json: boolean, cwd: string }}
+ */
+export function parseArgs(argv = []) {
+  const out = { kinds: [], check: false, json: false, cwd: null };
+  let i = 0;
+  while (i < argv.length) {
+    const arg = argv[i];
+    const value = argv[i + 1];
+    i += 1;
+    if (arg === '--check') out.check = true;
+    else if (arg === '--json') out.json = true;
+    else if (arg === '--kind') {
+      out.kinds.push(value);
+      i += 1;
+    } else if (arg === '--cwd') {
+      out.cwd = value;
+      i += 1;
+    } else throw new Error(`unknown flag "${arg}" (try --help)`);
+  }
+  const unknown = out.kinds.filter((k) => !PRUNABLE_KINDS.includes(k));
+  if (unknown.length > 0) {
+    throw new Error(
+      `unknown --kind ${unknown.join(', ')}; expected one of ${PRUNABLE_KINDS.join(', ')}`,
+    );
+  }
+  if (out.kinds.length === 0) out.kinds = [...PRUNABLE_KINDS];
+  out.cwd = out.cwd ?? process.cwd();
+  return out;
+}
+
+/**
+ * Render one kind's outcome as indented text lines.
+ *
+ * @param {object} entry
+ * @param {boolean} check
+ * @returns {string[]}
+ */
+function renderKind(entry, check) {
+  if (!entry.present) return [];
+  if (entry.skipped)
+    return [`  - ${entry.kind}: skipped (${entry.skipReason})`];
+  const suffix = entry.degraded
+    ? ` [orphan-only: ${entry.degradedReason}]`
+    : '';
+  if (entry.removed.length === 0) {
+    return [`  - ${entry.kind}: clean${suffix}`];
+  }
+  const verb = check ? 'would prune' : 'pruned';
+  return [
+    `  - ${entry.kind}: ${verb} ${entry.removed.length} row(s)${suffix}`,
+    ...entry.removed.map((row) => `      · ${row.reason}: ${row.path}`),
+  ];
+}
+
+/**
+ * Render the whole report as text.
+ *
+ * @param {object} report
+ * @returns {string}
+ */
+export function formatReport(report) {
+  const verb = report.check ? 'would prune' : 'pruned';
+  const lines = [
+    `[prune-baseline-orphans] ${verb} ${report.removedCount} row(s) across ` +
+      `${report.writtenCount} file(s)`,
+    ...report.kinds.flatMap((entry) => renderKind(entry, report.check)),
+  ];
+  if (report.check && report.removedCount > 0) {
+    lines.push(
+      '',
+      'Run without --check to write the prune:',
+      '  node .agents/scripts/prune-baseline-orphans.js',
+    );
+  }
+  return lines.join('\n');
+}
+
+/**
+ * CLI entry point. Returns its exit code rather than calling `process.exit()`,
+ * so `runAsCli`'s `propagateExitCode` path settles it through `flushStdio` and
+ * an unbounded report is not truncated at a pipe boundary (Story #4783).
+ *
+ * @returns {Promise<number>}
+ */
+async function main() {
+  let opts;
+  let report;
+  try {
+    opts = parseArgs(process.argv.slice(2));
+    const config = resolveConfig({ cwd: opts.cwd });
+    report = runPrune({
+      cwd: opts.cwd,
+      kinds: opts.kinds,
+      check: opts.check,
+      quality: getQuality(config) ?? { gates: {} },
+    });
+  } catch (err) {
+    const message = err?.message ?? String(err);
+    process.stdout.write(
+      `${JSON.stringify({ schemaVersion: '1', error: message }, null, 2)}\n`,
+    );
+    return EXIT_CANNOT_RUN;
+  }
+  process.stdout.write(
+    opts.json
+      ? `${JSON.stringify(report, null, 2)}\n`
+      : `${formatReport(report)}\n`,
+  );
+  return report.check && report.removedCount > 0
+    ? EXIT_WOULD_PRUNE
+    : EXIT_CLEAN;
+}
+
+runAsCli(import.meta.url, main, {
+  source: 'prune-baseline-orphans',
+  usage: HELP,
+  propagateExitCode: true,
+});

package/.agents/scripts/resolve-stories.js

@@ -197,7 +197,6 @@ export async function runResolveStories(
     stories,
     nativeEdges,
     warn: (m) => Logger.warn(m),
-    config,
   });
   const foreignDone = await resolveForeignDone({
     provider,
@@ -209,7 +208,6 @@ export async function runResolveStories(
     nativeEdges,
     foreignDone,
     warn: () => {},
-    config,
   });
 
   stdout.write(

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

@@ -21,6 +21,32 @@ import process from 'node:process';
 // can spawn directly.
 const useShell = process.platform === 'win32';
 
+/**
+ * A Node gate spelled `node .agents/scripts/<script>` — the shape six of the
+ * eight tasks share. Spelling it once keeps this list readable as what it
+ * actually is (a fan-out roster) instead of a wall of spawn tuples, and keeps
+ * adding a gate from costing the module a maintainability regression for the
+ * boilerplate rather than the behaviour. Mirrors `run-verify.js`'s `gate()`.
+ *
+ * Use bare `node` (PATH-resolved) rather than `process.execPath`:
+ * `process.execPath` on Windows often expands to `C:\Program
+ * Files\nodejs\node.exe`, and spawn(..., { shell: true }) does not quote the
+ * executable, so the space breaks invocation.
+ *
+ * The path is passed WHOLE rather than assembled from a basename. Composing
+ * it (`` `.agents/scripts/${script}` ``) reads better and is wrong:
+ * `check-knip-entries.js` derives which CLIs something actually invokes by
+ * scanning this file's source text for literal script paths, and four of the
+ * gates below are invoked from nowhere else. Interpolating the path made them
+ * invisible to that derivation, so knip called them dead and the ratchet
+ * offered to record live gates as expected-dead — the Story #5012 trap.
+ *
+ * @param {string} name reported in this driver's own error prefix
+ * @param {string} script repo-relative path, spelled as one literal
+ * @returns {{ name: string, cmd: string, args: string[] }}
+ */
+const nodeGate = (name, script) => ({ name, cmd: 'node', args: [script] });
+
 const tasks = [
   {
     name: 'biome',
@@ -47,67 +73,41 @@ const tasks = [
       '!.worktrees/**',
     ],
   },
-  {
-    // Custom Node-based lint for the lifecycle bus surface (Story #2227).
-    // Enforces:
-    //   1. No `Promise.all` over listener arrays under
-    //      `.agents/scripts/lib/orchestration/lifecycle/**`.
-    //   2. Wildcard-observer firewall: no state-mutating imports in
-    //      listener modules that register on `'*'`.
-    // Both rules are mandated by Tech Spec #2189 and have no biome
-    // equivalent.
-    //
-    // Use bare `node` (PATH-resolved) rather than `process.execPath`:
-    // `process.execPath` on Windows often expands to `C:\Program
-    // Files\nodejs\node.exe`, and spawn(..., { shell: true }) does not
-    // quote the executable, so the space breaks invocation.
-    name: 'lifecycle-lint',
-    cmd: 'node',
-    args: ['.agents/scripts/check-lifecycle-lint.js'],
-  },
-  {
-    // Custom Node-based lint for the workflow prose surface (Epic #4474
-    // PR5). Enforces: no workflow may instruct calling an exported
-    // library function that has no CLI entrypoint — the measured
-    // shim-writing failure mode the /plan collapse killed. See
-    // check-workflow-cli-lint.js for the paragraph-level heuristic.
-    name: 'workflow-cli-lint',
-    cmd: 'node',
-    args: ['.agents/scripts/check-workflow-cli-lint.js'],
-  },
-  {
-    // Custom Node-based lint for label-vocabulary citations in
-    // `.agents/docs/SDLC.md` and `.agents/workflows/**/*.md` (Story #2892,
-    // Tech Spec F9 under Epic #2880). Greps inline backtick code
-    // spans for axis-shaped tokens (`type/epic`, etc.) and asserts
-    // only the canonical `<axis>::<value>` separator from
-    // `lib/label-constants.js` appears. Closes the drift gap that
-    // let the original `type/epic` typo land in a since-retired
-    // planning workflow helper.
-    name: 'label-vocabulary',
-    cmd: 'node',
-    args: ['.agents/scripts/lint-label-vocabulary.js'],
-  },
-  {
-    // GitHub Actions job-timeout gate (Story #4936). Enumerates every
-    // `jobs.<id>` key across `.github/workflows/*.yml` and fails when one
-    // sets no `timeout-minutes` (inheriting GitHub's 360-minute default) or
-    // sets one above the ceiling. A deadlocked Windows job burned 44 minutes
-    // of a runner and withheld the failing required check's logs for the
-    // whole time; nothing but this check would have caught the gap.
-    name: 'workflow-timeouts',
-    cmd: 'node',
-    args: ['.agents/scripts/check-workflow-timeouts.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'],
-  },
+  // Lifecycle surface (Story #2227). Enforces (1) no `Promise.all` under
+  // `.agents/scripts/lib/orchestration/lifecycle/**` — the ledger is
+  // append-only and a parallel write interleaves records; and (2) the
+  // auto-merge lockout: the `gh pr merge` literal appears only in
+  // `single-story-close/phases/auto-merge.js`. Neither has a biome
+  // equivalent. Story #5024 dropped the third rule (the wildcard-observer
+  // firewall) with the bus and the `listeners/` directory its predicate
+  // required.
+  nodeGate('lifecycle-lint', '.agents/scripts/check-lifecycle-lint.js'),
+  // Workflow prose surface (Epic #4474 PR5). No workflow may instruct calling
+  // an exported library function that has no CLI entrypoint — the measured
+  // shim-writing failure mode the /plan collapse killed. See
+  // check-workflow-cli-lint.js for the paragraph-level heuristic.
+  nodeGate('workflow-cli-lint', '.agents/scripts/check-workflow-cli-lint.js'),
+  // Label-vocabulary citations in `.agents/docs/SDLC.md` and
+  // `.agents/workflows/**/*.md` (Story #2892). Greps inline backtick code
+  // spans for axis-shaped tokens (`type/epic`, etc.) and asserts only the
+  // canonical `<axis>::<value>` separator from `lib/label-constants.js`
+  // appears. Closes the drift gap that let the original `type/epic` typo land.
+  nodeGate('label-vocabulary', '.agents/scripts/lint-label-vocabulary.js'),
+  // GitHub Actions job-timeout gate (Story #4936). Fails a `jobs.<id>` that
+  // sets no `timeout-minutes` (inheriting GitHub's 360-minute default) or sets
+  // one above the ceiling. A deadlocked Windows job burned 44 minutes of a
+  // runner and withheld the failing required check's logs for the whole time.
+  nodeGate('workflow-timeouts', '.agents/scripts/check-workflow-timeouts.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`).
+  nodeGate('arch-cycles', '.agents/scripts/check-arch-cycles.js'),
+  // Static Gherkin corpus gate (Story #5013): must-compile with the real
+  // parser, then must-bind scoped per step root. Opt-in behind
+  // `qa.gherkinLint`, so it exits 0 as "not configured" in this repo. Here
+  // rather than in run-verify.js so it reaches CI through the same `lint`
+  // required check as arch-cycles; listing it in both would double-pay it.
+  nodeGate('gherkin-corpus', '.agents/scripts/check-gherkin-corpus.js'),
 ];
 
 function runTask({ name, cmd, args }) {