mandrel 2.54.0 → 2.56.0

package/.agents/scripts/file-ci-gap.js

@@ -0,0 +1,306 @@
+#!/usr/bin/env node
+/**
+ * file-ci-gap.js — the CI-remediation Option-2 filing command.
+ *
+ * `rules/ci-remediation.md` sends three verdicts here — `pre-existing`,
+ * `capacity`, `unreproducible-tier` — each meaning "this red check is real,
+ * and fixing it is not this delivery's job". The rule used to say "file a
+ * `meta::framework-gap` issue" and stop, leaving the agent to hand-run
+ * `gh issue create` wherever it was standing. This is the mechanism behind
+ * that sentence: evidence from the CI digest, ownership routing, fingerprint
+ * dedup, the `friction` comment, and the `agent::blocked` flip in one call.
+ *
+ * It files an **intake** issue, never a Story: `/mandrel-plan <id>` graduates
+ * it on the next planning pass. Delivery never blocks on planning — see
+ * `lib/orchestration/ci-gap-intake.js` for why that split is load-bearing.
+ */
+
+import { parseArgs } from 'node:util';
+
+import { runAsCli } from './lib/cli-utils.js';
+import { resolveConfig } from './lib/config-resolver.js';
+import {
+  createFollowUpIssue,
+  ensureIssueLabels,
+  updateFollowUpIssue,
+} from './lib/feedback-loop/graduator-core.js';
+import { issueNumberFromUrl } from './lib/feedback-loop/retro-proposals-graduator.js';
+import {
+  resolveOwnershipRepos,
+  routeOwnership,
+} from './lib/github/framework-repo.js';
+import { Logger } from './lib/Logger.js';
+import {
+  fileCiGapIntake,
+  INTAKE_VERDICTS,
+  REFUSED_VERDICT,
+} from './lib/orchestration/ci-gap-intake.js';
+import { readCiDigest } from './lib/orchestration/ci-rerun-guard.js';
+import {
+  STATE_LABELS,
+  transitionTicketState,
+  upsertStructuredComment,
+} from './lib/orchestration/ticketing.js';
+import { createProvider } from './lib/provider-factory.js';
+
+const USAGE = {
+  invocation:
+    'node .agents/scripts/file-ci-gap.js --story <id> --verdict <verdict> --owner <bucket> [--evidence "<proof reading>"] [--pr <n>] [--block] [--dry-run]',
+  summary:
+    'File (or update) the CI-gap intake issue for an Option-2 verdict in .agents/rules/ci-remediation.md, routed to the repository that owns the fault and deduped by failure signature.',
+  flags: [
+    [
+      '--story <id>',
+      'Story the red check blocked (required — keys the CI digest).',
+    ],
+    [
+      '--verdict <verdict>',
+      `One of ${INTAKE_VERDICTS.join(' | ')}. "${REFUSED_VERDICT}" is refused: it routes to Option 1, fix at source.`,
+    ],
+    [
+      '--owner <bucket>',
+      'Who owns the fault: consumer | framework | platform. Resolves through github.followUpRepos.*.',
+    ],
+    [
+      '--evidence <text>',
+      "The verdict's proof reading (the exhausted-limit log line, the failed attach). Recorded in the body.",
+    ],
+    ['--pr <n>', 'PR number the red check ran on; recorded as an occurrence.'],
+    [
+      '--block',
+      'Also flip the Story to agent::blocked. Without it the friction comment is posted but the Story is left where it is.',
+    ],
+    ['--dry-run', 'Compose the filing and print it; write nothing.'],
+  ],
+  notes: [
+    'Requires a CI digest at temp/story-<id>-ci-digest.json — pr-watch-with-update.js --story <id> writes it on the first red.',
+    'A repeat occurrence of a known signature UPDATES the existing intake issue rather than opening a second one.',
+    'The issue it files is intake, not an executable Story: graduate it with /mandrel-plan <issue number>.',
+  ],
+};
+
+/**
+ * Wire the live GitHub ports the intake filer writes through.
+ *
+ * `gh` is the transport rather than the provider facade because a filing can
+ * target a repository other than the configured one, and `gh issue create
+ * --repo` is the surface that already does that (the graduators file
+ * cross-repo the same way).
+ *
+ * @param {object} opts
+ * @returns {object} ports for `fileCiGapIntake`
+ */
+function liveIntakePorts({ provider, searchRepo, cwd, logger }) {
+  const labelCache = new Map();
+  return {
+    searchIssues: (query) =>
+      provider.searchIssues({
+        query,
+        owner: searchRepo.owner,
+        repo: searchRepo.repo,
+      }),
+    createIssue: async ({ owner, repo, title, body, labels }) => {
+      // `gh issue create --label <absent>` fails outright, so a brand-new
+      // routing label (meta::platform-gap, friction::unreproducible-tier)
+      // has to exist before the create — not after it errors.
+      const ensured = await ensureIssueLabels({
+        owner,
+        repo,
+        labels,
+        labelCache,
+        cwd,
+      });
+      for (const err of ensured.errors) logger?.warn?.(`[file-ci-gap] ${err}`);
+      const created = await createFollowUpIssue({
+        owner,
+        repo,
+        title,
+        body,
+        labels,
+        ghPath: 'gh',
+        cwd,
+      });
+      return {
+        url: created.url,
+        number: created.url ? issueNumberFromUrl(created.url) : null,
+        error: created.error,
+      };
+    },
+    updateIssue: ({ owner, repo, number, body }) =>
+      updateFollowUpIssue({ owner, repo, number, body, ghPath: 'gh', cwd }),
+  };
+}
+
+/**
+ * Render the `friction` comment the Story carries so the blocker is legible
+ * on the ticket itself, not only in the intake issue.
+ *
+ * @param {object} opts
+ * @returns {string}
+ */
+export function renderFrictionComment({ verdict, result, digest }) {
+  const target = result.issue?.url ?? result.issue?.number ?? '(not filed)';
+  const lines = [
+    `### CI gap filed — verdict \`${verdict}\``,
+    '',
+    `- **Failing check:** \`${digest?.failingCheck ?? 'unknown'}\``,
+    `- **Run:** ${digest?.runUrl ?? `run id ${digest?.runId ?? 'unresolved'}`}`,
+    `- **Intake issue:** ${target} (${result.decision})`,
+    `- **Owner:** \`${result.routing.bucket}\` → \`${result.routing.routedRepo.owner}/${result.routing.routedRepo.repo}\``,
+  ];
+  if (!result.routing.routable) {
+    lines.push(
+      `- **Routing:** \`unroutable\` — \`${result.routing.missingKey}\` is unset, so the intake issue was filed locally.`,
+    );
+  }
+  if (result.routing.deferredFrom) {
+    lines.push(
+      `- **Routing:** deferred from \`${result.routing.deferredFrom}\` (${result.routing.deferralReason}) — filed locally instead.`,
+    );
+  }
+  lines.push(
+    '',
+    'This verdict does **not** license a re-run of the failed job. Graduate the',
+    'intake issue with `/mandrel-plan <issue number>` to turn it into a Story.',
+  );
+  return lines.join('\n');
+}
+
+/**
+ * File the CI-gap intake issue for one Story, post the `friction` comment,
+ * and optionally flip the Story to `agent::blocked`.
+ *
+ * Every port is injectable so the unit tests exercise the whole command with
+ * no network and no live tracker.
+ *
+ * @param {object} opts
+ * @returns {Promise<object>} the intake result, plus what the command did.
+ */
+export async function runFileCiGap({
+  storyId,
+  verdict,
+  owner: bucket,
+  evidence = '',
+  prNumber = null,
+  dryRun = false,
+  block = false,
+  config,
+  provider,
+  ports,
+  digest,
+  tempRoot,
+  cwd = process.cwd(),
+  logger = Logger,
+  now,
+} = {}) {
+  const sid = Number(storyId);
+  if (!Number.isInteger(sid) || sid <= 0) {
+    throw new Error('--story <id> is required (a positive issue number).');
+  }
+  const resolved = config ?? resolveConfig();
+  const ciDigest = digest ?? readCiDigest({ storyId: sid, tempRoot, cwd });
+  if (!ciDigest) {
+    throw new Error(
+      `no CI digest for Story #${sid}. The digest is written by \`pr-watch-with-update.js --story ${sid}\` on the first red; without it there is no run link or failure signature to file.`,
+    );
+  }
+
+  const repos = resolveOwnershipRepos(resolved);
+  const currentRepo = repos.consumer ?? { owner: 'unknown', repo: 'unknown' };
+  // Dedup searches the repository the filing will land in — routing is a pure
+  // function, so computing it here and inside the filer cannot disagree.
+  const routed = routeOwnership({ bucket, repos, currentRepo });
+  const searchRepo = routed.routable ? routed.routedRepo : currentRepo;
+
+  const ticketing =
+    provider ?? (dryRun ? null : (createProvider(resolved) ?? null));
+  const livePorts =
+    ports ??
+    liveIntakePorts({
+      provider: ticketing ?? createProvider(resolved),
+      searchRepo,
+      cwd,
+      logger,
+    });
+
+  const result = await fileCiGapIntake({
+    digest: ciDigest,
+    verdict,
+    bucket,
+    evidence,
+    repos,
+    currentRepo,
+    prNumber,
+    dryRun,
+    ports: livePorts,
+    logger,
+    now,
+  });
+
+  const actions = { commented: false, blocked: false };
+  if (!dryRun && ticketing) {
+    const body = renderFrictionComment({ verdict, result, digest: ciDigest });
+    try {
+      await upsertStructuredComment(ticketing, sid, 'friction', body);
+      actions.commented = true;
+    } catch (err) {
+      result.errors.push(`friction comment failed: ${err?.message ?? err}`);
+    }
+    if (block) {
+      try {
+        await transitionTicketState(ticketing, sid, STATE_LABELS.BLOCKED, {});
+        actions.blocked = true;
+      } catch (err) {
+        result.errors.push(
+          `agent::blocked transition failed: ${err?.message ?? err}`,
+        );
+      }
+    }
+  }
+
+  return { storyId: sid, verdict, ...result, actions };
+}
+
+/**
+ * CLI entrypoint.
+ *
+ * @returns {Promise<void>}
+ */
+async function main() {
+  const { values } = parseArgs({
+    args: process.argv.slice(2),
+    options: {
+      story: { type: 'string' },
+      verdict: { type: 'string' },
+      owner: { type: 'string' },
+      evidence: { type: 'string' },
+      pr: { type: 'string' },
+      block: { type: 'boolean', default: false },
+      'dry-run': { type: 'boolean', default: false },
+    },
+  });
+
+  const result = await runFileCiGap({
+    storyId: values.story,
+    verdict: values.verdict,
+    owner: values.owner,
+    evidence: values.evidence ?? '',
+    prNumber: values.pr ? Number(values.pr) : null,
+    dryRun: values['dry-run'],
+    block: values.block,
+  });
+
+  // Single-line JSON per the script-output contract — an orchestrator parses
+  // this, and a pretty dump is noise in a delivery transcript.
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+  for (const err of result.errors) {
+    Logger.error(`[file-ci-gap] ${err}`);
+  }
+  if (result.errors.length > 0) process.exitCode = 1;
+}
+
+runAsCli(import.meta.url, main, {
+  source: 'file-ci-gap',
+  errorPrefix: '[file-ci-gap]',
+  usage: USAGE,
+});

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

@@ -22,6 +22,8 @@
  *                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
@@ -39,8 +41,43 @@ import { buildCatalog, buildLoopCatalog } from './lib/mandrel-catalog.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const PROJECT_ROOT = path.resolve(__dirname, '..', '..');
-const WORKFLOWS_DIR = path.join(PROJECT_ROOT, '.agents', 'workflows');
-const DOC_PATH = path.join(PROJECT_ROOT, '.agents', 'docs', 'workflows.md');
+
+/**
+ * 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.
+ * @returns {{ root: string, workflowsDir: string, docPath: string }}
+ */
+export function resolveTargets(root) {
+  const resolved = root ? path.resolve(root) : PROJECT_ROOT;
+  return {
+    root: resolved,
+    workflowsDir: path.join(resolved, '.agents', 'workflows'),
+    docPath: path.join(resolved, '.agents', 'docs', 'workflows.md'),
+  };
+}
+
+/** 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.
@@ -149,16 +186,24 @@ export function renderWorkflowsDoc(catalog, loopCatalog = []) {
 /**
  * Build the canonical generated content and read the on-disk file (if any).
  *
- * @returns {{ generated: string, original: string | null }}
+ * @param {string} [root] Repository root to render against; see
+ *   {@link resolveTargets}.
+ * @returns {{
+ *   generated: string,
+ *   original: string | null,
+ *   root: string,
+ *   docPath: string,
+ * }}
  */
-export function buildExpected() {
-  const catalog = buildCatalog(WORKFLOWS_DIR);
-  const loopCatalog = buildLoopCatalog(WORKFLOWS_DIR);
+export function buildExpected(root) {
+  const { root: resolvedRoot, workflowsDir, docPath } = resolveTargets(root);
+  const catalog = buildCatalog(workflowsDir);
+  const loopCatalog = buildLoopCatalog(workflowsDir);
   const generated = renderWorkflowsDoc(catalog, loopCatalog);
-  const original = fs.existsSync(DOC_PATH)
-    ? fs.readFileSync(DOC_PATH, 'utf8')
+  const original = fs.existsSync(docPath)
+    ? fs.readFileSync(docPath, 'utf8')
     : null;
-  return { generated, original };
+  return { generated, original, root: resolvedRoot, docPath };
 }
 
 /**
@@ -169,12 +214,13 @@ async function main(argv = process.argv.slice(2)) {
     args: argv,
     options: {
       check: { type: 'boolean', default: false },
+      root: { type: 'string' },
     },
     allowPositionals: false,
   });
 
-  const { generated, original } = buildExpected();
-  const rel = path.relative(PROJECT_ROOT, DOC_PATH).split(path.sep).join('/');
+  const { generated, original, root, docPath } = buildExpected(values.root);
+  const rel = path.relative(root, docPath).split(path.sep).join('/');
 
   if (values.check) {
     if (original === generated) {
@@ -191,8 +237,8 @@ async function main(argv = process.argv.slice(2)) {
     Logger.info(`generate-workflows-doc: ${rel} already current — no write.`);
     return;
   }
-  fs.mkdirSync(path.dirname(DOC_PATH), { recursive: true });
-  fs.writeFileSync(DOC_PATH, generated, 'utf8');
+  fs.mkdirSync(path.dirname(docPath), { recursive: true });
+  fs.writeFileSync(docPath, generated, 'utf8');
   Logger.info(`generate-workflows-doc: wrote ${rel}.`);
 }
 
@@ -201,7 +247,8 @@ export { DOC_PATH, WORKFLOWS_DIR };
 runAsCli(import.meta.url, main, {
   source: 'generate-workflows-doc',
   usage: {
-    invocation: 'node .agents/scripts/generate-workflows-doc.js [--check]',
+    invocation:
+      'node .agents/scripts/generate-workflows-doc.js [--check] [--root <dir>]',
     summary:
       'Regenerate the workflow catalog from .agents/workflows/. Writes only when the generated content differs.',
     flags: [
@@ -209,6 +256,10 @@ runAsCli(import.meta.url, main, {
         '--check',
         'Verify the doc is current and fail if stale; write nothing.',
       ],
+      [
+        '--root <dir>',
+        "Render against another checkout's .agents/ tree instead of this one (test seam).",
+      ],
     ],
   },
 });

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

@@ -157,6 +157,10 @@ runAsCli(import.meta.url, main, {
         'Never consider branches matching the glob (repeatable).',
       ],
       ['--drop-stashes <ref>', 'Stash ref approved for dropping (repeatable).'],
+      [
+        '--include-content-merged',
+        'Under --yes, also delete remote refs detected only by content-equivalence.',
+      ],
       ['--base <branch>', 'Base branch (default: project.baseBranch).'],
       ['--cwd <path>', 'Repository root (default: process cwd).'],
     ],

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

@@ -98,6 +98,84 @@ export class ITicketingProvider {
     // Intentional no-op. Concrete providers that maintain a cache override.
   }
 
+  /**
+   * List every ticket carrying `labels`, in the **mapped** ticket shape.
+   *
+   * This is the declared read for a label scan, and the only one callers
+   * should reach for. Implementations MUST map every issue the way every
+   * other read on this interface does — in particular `id` is the **issue
+   * number**, not the backend's internal database id.
+   *
+   * That single rule is the whole reason the method exists. The raw REST
+   * payload names the issue number `number` and the database id `id`, so a
+   * consumer handed either shape wrote `number ?? id` and appeared to cope —
+   * while silently addressing issues by database id on the mapped shape,
+   * because there `id` is already the number and the fallback never fires.
+   * A declared shape removes the choice rather than documenting it.
+   *
+   * `state` selects `open` (default), `closed` or `all`. Implementations MUST
+   * honour it: a caller asking for `all` is asking a question — "did this
+   * child reopen?" — that an open-only listing answers wrongly rather than
+   * partially.
+   *
+   * @param {{ state?: 'open'|'closed'|'all', labels?: string }} [_opts]
+   * @returns {Promise<Array<{
+   *   id: number,
+   *   title: string,
+   *   body: string,
+   *   labels: string[],
+   *   assignees: string[],
+   *   state: string,
+   *   url?: string|null,
+   * }>>}
+   */
+  async listTicketsByLabel(_opts = {}) {
+    throw new Error('Not implemented: listTicketsByLabel');
+  }
+
+  /**
+   * Read a parent's native sub-issue children as issue numbers.
+   *
+   * Takes **both** identifiers because they address different things: the
+   * backend's child edge is keyed by the parent's opaque node id, while
+   * `number` exists only so a degraded read can name the parent it failed on.
+   * Passing the number where the node id belongs is not a type error — it is
+   * a successful call about the wrong issue — which is why the parameter
+   * order is fixed here rather than left to each call site.
+   *
+   * Implementations MUST return `[]` rather than throw when the sub-issue
+   * feature is unavailable on the backend: absence of the feature is not a
+   * failed read, and callers union this with a body checklist that still
+   * answers the question.
+   *
+   * @param {string} _nodeId Opaque node id of the parent.
+   * @param {number} _number Parent's issue number, for diagnostics only.
+   * @returns {Promise<number[]>}
+   */
+  async getNativeSubIssues(_nodeId, _number) {
+    throw new Error('Not implemented: getNativeSubIssues');
+  }
+
+  /**
+   * Resolve a ticket's container parent in **one** call.
+   *
+   * Exists so a child→parent lookup is a read, not a search. Without it the
+   * only way to find a container was to list every candidate parent and read
+   * each one's children — O(containers) requests to answer what the backend
+   * knows directly.
+   *
+   * Returns `null` when the ticket has no parent, and `null` rather than
+   * throwing when the backend cannot answer. Callers treat a null as "no
+   * parent resolved *here*" and may fall back to a body-declared link; an
+   * exception would turn a degraded lookup into a failed lifecycle edge.
+   *
+   * @param {number} _number Issue number whose parent to resolve.
+   * @returns {Promise<object|null>} Mapped parent ticket, or null.
+   */
+  async getParentIssue(_number) {
+    throw new Error('Not implemented: getParentIssue');
+  }
+
   /**
    * Return the dependency graph edges for a ticket.
    * Parses `blocked by #NNN` patterns from the ticket body.