mandrel 1.57.0

package/.agents/scripts/lib/bootstrap/branch-protection.js

@@ -0,0 +1,222 @@
+/**
+ * bootstrap/branch-protection
+ *
+ * Consumer-parity branch-protection writer. The bootstrap applies a
+ * CI-gates-only stance every project in the framework inherits:
+ *
+ *   - `enforce_admins: true` — admins do not bypass the prGate suite.
+ *   - `required_pull_request_reviews.required_approving_review_count: 0` —
+ *     CI is the gate; the operator monitors and iterates the open PR
+ *     to green via `/epic-deliver`'s Phase 7 watch loop.
+ *
+ * Behaviour rules
+ * ---------------
+ * Fresh rule (no existing protection):
+ *   The framework writes the full opinionated payload directly. No HITL
+ *   prompt — there is nothing to diff against.
+ *
+ * Existing rule that already matches the target stance:
+ *   Pure-additive append of any missing prGate.checks contexts. No HITL
+ *   prompt (preserves the today-non-interactive contract for additive
+ *   changes).
+ *
+ * Existing rule that *diverges* on a behavior-shifting field
+ * (enforce_admins flip, approval-count change, strict-checks flip, or any
+ * required-check context dropped):
+ *   Routes the proposed payload through `hitlConfirm`. On rejection or
+ *   non-TTY abort, the call is a no-op and we return
+ *   `{ status: 'skipped', reason: 'hitl-declined' }`. On approval, we
+ *   apply the diverging payload.
+ *
+ * Errors (insufficient scopes, repo permission denied, etc.) are logged
+ * and surfaced as `{ status: 'failed' }` — the rest of the bootstrap is
+ * not aborted. Matches `agents-bootstrap-github.js` failure handling so
+ * the wrapper stays predictable.
+ */
+
+const TARGET_ENFORCE_ADMINS = true;
+const TARGET_APPROVAL_COUNT = 0;
+
+/**
+ * Detect whether `current` (the GitHub API's `raw` protection payload)
+ * diverges from the target stance on any behavior-shifting field. The
+ * return value is a structured diff suitable for `hitlConfirm` so the
+ * operator sees exactly what would flip.
+ */
+export function diffProtection(current, targetContexts) {
+  if (!current) return null; // create-from-scratch path; no diff needed.
+
+  const diff = {};
+  const liveEnforceAdmins = current?.enforce_admins?.enabled ?? false;
+  if (liveEnforceAdmins !== TARGET_ENFORCE_ADMINS) {
+    diff.enforceAdmins = {
+      current: liveEnforceAdmins,
+      proposed: TARGET_ENFORCE_ADMINS,
+    };
+  }
+
+  const liveReviews = current?.required_pull_request_reviews ?? null;
+  // Live `null` means "PR reviews not configured at all". We *do* want to
+  // promote the explicit zero-approval policy in that case, so the diff
+  // reports it as a flip from null → { required_approving_review_count: 0 }.
+  // An explicit zero-count rule blocks any future operator drift back to
+  // 1+, which would re-introduce the approval-theater dependency the
+  // framework deliberately stripped out.
+  const liveApprovalCount = liveReviews?.required_approving_review_count;
+  if (liveApprovalCount !== TARGET_APPROVAL_COUNT) {
+    diff.approvingReviewCount = {
+      current: liveApprovalCount ?? null,
+      proposed: TARGET_APPROVAL_COUNT,
+    };
+  }
+
+  const liveContexts = current?.required_status_checks?.contexts ?? [];
+  const dropped = liveContexts.filter((c) => !targetContexts.includes(c));
+  // We never *drop* operator contexts — the writer is additive on that
+  // axis. So a dropped-on-target list is informational only and never
+  // makes us route through HITL. Only enforce-admins / approval-count
+  // shifts trigger the gate.
+  if (dropped.length > 0) {
+    diff.preservedContexts = dropped;
+  }
+
+  return Object.keys(diff).length > 0 ? diff : null;
+}
+
+function isBehaviorShifting(diff) {
+  if (!diff) return false;
+  return (
+    Object.hasOwn(diff, 'enforceAdmins') ||
+    Object.hasOwn(diff, 'approvingReviewCount')
+  );
+}
+
+/**
+ * Apply the framework's branch-protection stance to `baseBranch`.
+ *
+ * @param {object} args
+ * @param {object} args.provider - Ticketing provider exposing
+ *   `getBranchProtection(branch)` and `setBranchProtection(branch, opts)`.
+ * @param {object} args.settings - The resolved settings bag. Carries
+ *   `baseBranch` (default `main`) and `github.branchProtection.{enforce,
+ *   requiredChecks}` post-reshape.
+ * @param {(args:{summary:string, current:object|null, proposed:object})=>Promise<boolean>}
+ *   [args.hitlConfirm] - HITL gate. Defaults to "abort on diverge"
+ *   (returns false) when omitted — matching the non-TTY contract.
+ * @param {(msg:string)=>void} [args.log] - Logger sink. Defaults to a no-op.
+ */
+export async function applyBranchProtection({
+  provider,
+  settings,
+  hitlConfirm,
+  log = () => {},
+}) {
+  const baseBranch = settings?.baseBranch ?? 'main';
+  // Post-reshape: branch protection lives under `github.branchProtection`.
+  // The legacy `quality.prGate` location is gone from the schema; reading
+  // it here is a transitional fallback only.
+  const branchProtection =
+    settings?.github?.branchProtection ?? settings?.quality?.prGate ?? null;
+  const enforce =
+    branchProtection?.enforce ??
+    branchProtection?.enforceBranchProtection ??
+    true;
+  const requiredChecks =
+    branchProtection?.requiredChecks ?? branchProtection?.checks ?? [];
+
+  if (enforce === false) {
+    log(
+      `[bootstrap] Branch protection on '${baseBranch}': skipped (github.branchProtection.enforce=false).`,
+    );
+    return { status: 'skipped', reason: 'opt-out' };
+  }
+
+  const checkNames = requiredChecks
+    .map((c) => c?.name)
+    .filter((n) => typeof n === 'string' && n.length > 0);
+  if (checkNames.length === 0) {
+    log(
+      `[bootstrap] Branch protection on '${baseBranch}': skipped (no github.branchProtection.requiredChecks configured).`,
+    );
+    return { status: 'skipped', reason: 'no-checks' };
+  }
+
+  // Story #2018 (Bug 3): on a fresh-empty repo with no commits yet, the
+  // base branch hasn't been pushed and the protection PUT would 404 with
+  // a confusing transport error. Probe for existence first so operators
+  // get a clear "no-base-branch" skip rather than discovering the
+  // `enforce: false` opt-out by reading the failure message.
+  if (typeof provider.branchExists === 'function') {
+    let exists = true;
+    try {
+      exists = await provider.branchExists(baseBranch);
+    } catch (err) {
+      log(
+        `[bootstrap] Branch protection on '${baseBranch}': existence probe failed — ${err.message}. Proceeding with the write attempt.`,
+      );
+    }
+    if (!exists) {
+      log(
+        `[bootstrap] Branch protection on '${baseBranch}': skipped (base branch does not exist on the remote — push an initial commit first).`,
+      );
+      return { status: 'skipped', reason: 'no-base-branch' };
+    }
+  }
+
+  let current = null;
+  try {
+    const probe = await provider.getBranchProtection(baseBranch);
+    current = probe?.enabled ? (probe.raw ?? null) : null;
+  } catch (err) {
+    log(
+      `[bootstrap] Branch protection on '${baseBranch}': read failed — ${err.message}. Proceeding as if no rule exists.`,
+    );
+  }
+
+  const diff = diffProtection(current, checkNames);
+  if (isBehaviorShifting(diff)) {
+    const approved =
+      typeof hitlConfirm === 'function'
+        ? await hitlConfirm({
+            summary: `Branch protection on '${baseBranch}' diverges from the framework's CI-gates-only stance (enforce_admins=true, required_approving_review_count=0).`,
+            current: {
+              enforce_admins: current?.enforce_admins?.enabled ?? false,
+              required_approving_review_count:
+                current?.required_pull_request_reviews
+                  ?.required_approving_review_count ?? null,
+            },
+            proposed: {
+              enforce_admins: TARGET_ENFORCE_ADMINS,
+              required_approving_review_count: TARGET_APPROVAL_COUNT,
+            },
+          })
+        : false;
+    if (!approved) {
+      log(
+        `[bootstrap] Branch protection on '${baseBranch}': diverges from framework stance; HITL declined / non-TTY — leaving the operator's rule untouched.`,
+      );
+      return { status: 'skipped', reason: 'hitl-declined', diff };
+    }
+  }
+
+  try {
+    const result = await provider.setBranchProtection(baseBranch, {
+      contexts: checkNames,
+      enforceAdmins: TARGET_ENFORCE_ADMINS,
+      requiredApprovingReviewCount: TARGET_APPROVAL_COUNT,
+    });
+    const verb = result.created ? 'Created' : 'Updated';
+    const addedSuffix = result.added.length
+      ? ` (added: ${result.added.join(', ')})`
+      : ' (all required checks already present)';
+    log(
+      `[bootstrap] Branch protection on '${baseBranch}': ${verb} rule${addedSuffix}.`,
+    );
+    return { status: result.created ? 'created' : 'merged', ...result };
+  } catch (err) {
+    log(
+      `[bootstrap] Branch protection on '${baseBranch}': failed — ${err.message}. Proceeding without it.`,
+    );
+    return { status: 'failed', reason: err.message };
+  }
+}

package/.agents/scripts/lib/bootstrap/ci-workflow-template.js

@@ -0,0 +1,171 @@
+/**
+ * bootstrap/ci-workflow-template — Story #1401 (Epic #1386)
+ *
+ * Renders the stabilized-quality-gates CI workflow YAML that
+ * `/agents-bootstrap-github` writes (or refreshes) on a downstream project's
+ * `.github/workflows/ci.yml`. Two design rules drive the shape:
+ *
+ *   1. **Lean on the diff-scoped default.** Story #1394 flipped both gate
+ *      CLIs (`check-maintainability.js`, `check-crap.js`) to default
+ *      `--changed-since=main`. The template no longer passes `--changed-since`
+ *      explicitly on the per-PR job — the default already produces the right
+ *      diff scope and an explicit re-statement risks drifting from the
+ *      framework default at the next bump. The push-to-main job still passes
+ *      `--full-scope` so a self-diff doesn't degrade to "no files in diff".
+ *
+ *   2. **Pass `--epic-ref` where the firing site is Epic-aware.** Inside
+ *      `/story-deliver` the close-validation chain already threads
+ *      `--epic-ref epic/<id>`; on CI the equivalent surface is the PR's
+ *      base branch. The template wires `--epic-ref ${EPIC_REF}` through an
+ *      env var the workflow computes from `github.head_ref` (story-N
+ *      branches name their Epic in the PR title or via the dispatch
+ *      manifest). When `EPIC_REF` is empty, both gates fall through to the
+ *      `main`-tracked baseline — so the env-var expansion is always safe.
+ *
+ * The renderer is a pure string template so the integration test can assert
+ * on its exact shape without instantiating a YAML parser.
+ *
+ * @module bootstrap/ci-workflow-template
+ */
+
+/**
+ * @typedef {object} CiTemplateOptions
+ * @property {string} [nodeVersion='22'] - Node major to install via setup-node.
+ * @property {string} [baseRef='main'] - Default base ref the gate CLIs diff
+ *   against. Surfaces as the workflow's `BASE_REF` env so the template stays
+ *   tunable per consumer.
+ * @property {boolean} [includeCrap=true] - Whether to render the CRAP step.
+ *   Some downstream projects keep CRAP off until they have coverage wired.
+ */
+
+/**
+ * Render the CI workflow YAML body. The output is deterministic and safe to
+ * write byte-for-byte over an existing template — the bootstrap caller is
+ * responsible for diff-aware merging when an operator has hand-edited
+ * `ci.yml`.
+ *
+ * @param {CiTemplateOptions} [opts]
+ * @returns {string}
+ */
+export function renderCiWorkflow(opts = {}) {
+  const nodeVersion = opts.nodeVersion ?? '22';
+  const baseRef = opts.baseRef ?? 'main';
+  const includeCrap = opts.includeCrap !== false;
+
+  const crapBlock = includeCrap
+    ? `
+      - name: CRAP Check
+        # Diff-scoped via the framework default (Story #1394 flipped
+        # --changed-since to '${baseRef}'). On PRs we let the default win;
+        # on push-to-main we pass --full-scope so a self-diff doesn't
+        # collapse to an empty file set. EPIC_REF is set when the head ref
+        # points at a story branch under an Epic — the gate then reads the
+        # per-Epic baseline snapshot via baseline-loader.readBaselineAtRef.
+        env:
+          EPIC_REF: \${{ env.EPIC_REF }}
+        run: |
+          mkdir -p temp
+          if [[ "\${{ github.event_name }}" == "pull_request" ]]; then
+            if [[ -n "\${EPIC_REF}" ]]; then
+              npm run crap:check -- --epic-ref "\${EPIC_REF}" --json temp/crap-report.json
+            else
+              npm run crap:check -- --json temp/crap-report.json
+            fi
+          else
+            npm run crap:check -- --full-scope --json temp/crap-report.json
+          fi
+
+      - name: Upload CRAP Report
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: crap-report
+          path: temp/crap-report.json
+`
+    : '';
+
+  return `# Generated by agents-bootstrap-github (Epic #1386 / Story #1401).
+# Re-run /agents-bootstrap-github to refresh this file. Hand edits are
+# preserved by the bootstrap helper when it detects operator changes —
+# inspect the diff before accepting an overwrite.
+name: CI
+
+on:
+  push:
+    branches: [${baseRef}]
+  pull_request:
+    branches: [${baseRef}]
+    types: [opened, synchronize, reopened]
+  workflow_dispatch:
+
+concurrency:
+  group: \${{ github.workflow }}-\${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  validate:
+    name: Validate and Test
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    env:
+      # Story #1120: when the PR head ref names an Epic story branch
+      # (story-N or story/epic-<id>/<n>), the gate CLIs read the canonical
+      # main baseline at the Epic branch HEAD via --epic-ref (git show).
+      # Empty when the head ref is not an Epic story branch — both gates
+      # fall through to the working-tree baseline, so the env-var
+      # expansion is always safe. Per-epic ratchet snapshots themselves
+      # live under temp/epic/<id>/baselines/ (Story #1467) — ephemeral
+      # scratch state, never read by this CI gate.
+      EPIC_REF: \${{ github.head_ref && contains(github.head_ref, 'story') && format('epic/{0}', github.event.pull_request.base.ref) || '' }}
+      BASE_REF: ${baseRef}
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '${nodeVersion}'
+          cache: 'npm'
+
+      - name: Install Dependencies
+        run: npm ci --ignore-scripts
+
+      - name: Lint and Format
+        run: |
+          npm run lint
+          npm run format:check
+
+      - name: Maintainability Check
+        # Story #1394 (Epic #1386): the gate CLI defaults --changed-since to
+        # the project's BASE_REF, so PRs no longer pass --changed-since
+        # explicitly. push-to-${baseRef} runs with --full-scope so the
+        # diff-scoped default doesn't degrade to a self-diff (= empty file
+        # set). EPIC_REF carries the per-Epic snapshot when present.
+        env:
+          EPIC_REF: \${{ env.EPIC_REF }}
+        run: |
+          if [[ "\${{ github.event_name }}" == "pull_request" ]]; then
+            if [[ -n "\${EPIC_REF}" ]]; then
+              npm run maintainability:check -- --epic-ref "\${EPIC_REF}"
+            else
+              npm run maintainability:check
+            fi
+          else
+            npm run maintainability:check -- --full-scope
+          fi
+
+      - name: Run Tests
+        run: npm test
+${crapBlock}`;
+}
+
+/**
+ * Default workflow filename emitted by the bootstrap. Surfaced as a constant
+ * so the integration test can assert the bootstrap writes to the canonical
+ * path without re-deriving it.
+ */
+export const CI_WORKFLOW_RELATIVE_PATH = '.github/workflows/ci.yml';

package/.agents/scripts/lib/bootstrap/commit-push.js

@@ -0,0 +1,146 @@
+/**
+ * bootstrap/commit-push — end-of-bootstrap "commit + push the wiring" offer
+ * (Story #3899, Finding A.6).
+ *
+ * After a successful bootstrap the consumer's working tree carries the
+ * framework wiring (`.agents/` tree, `.agentrc.json`, `CLAUDE.md`,
+ * `.claude/settings.json`, `.gitignore`, `package.json`, `.husky/`). Nothing
+ * told the operator to commit and push it — yet Story delivery runs in git
+ * worktrees that check out **tracked files only**, so an uncommitted
+ * `.agents/` means no scripts exist inside any worktree and every Story
+ * sub-agent breaks. This module offers that commit + push at the end of the
+ * run, and prints the exact manual commands when the offer is declined or the
+ * run is non-interactive.
+ *
+ * Security: the stage step uses an explicit **allowlist** of bootstrap-written
+ * paths (`git add -- <path>`), never `git add -A`, and explicitly refuses to
+ * stage known secret files (`.env`, `.mcp.json`, `.agentrc.local.json`). This
+ * keeps the commit safe regardless of whether the secret-safe `.gitignore`
+ * Story (#3894) has landed — secrets are never staged even when un-ignored.
+ *
+ * Every git-touching helper takes an injectable `runGit` seam so the logic is
+ * unit-testable without spawning a real `git`. The seam contract mirrors
+ * `bootstrap.js#runGit`: `({ ok, status, stdout, stderr })`.
+ *
+ * @module bootstrap/commit-push
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * The bootstrap-written, version-controllable paths the commit offer stages.
+ * Project-root-relative POSIX paths. Mirrors the file targets the bootstrap
+ * pipeline writes (see `manifest.js` + `project-bootstrap.js`) plus the
+ * materialized `.agents/` tree and `.husky/` quality hook. `.claude/commands/`
+ * is intentionally absent — it is generated and gitignored.
+ *
+ * @type {readonly string[]}
+ */
+export const BOOTSTRAP_COMMIT_PATHS = Object.freeze([
+  '.agents',
+  '.agentrc.json',
+  'CLAUDE.md',
+  '.claude/settings.json',
+  '.gitignore',
+  'package.json',
+  'package-lock.json',
+  '.husky',
+]);
+
+/**
+ * Paths that MUST NEVER be staged by the commit offer, even when they are not
+ * (yet) gitignored. These carry secrets or per-operator local overrides. This
+ * is the defense-in-depth that lets the offer run safely before the
+ * secret-safe `.gitignore` Story (#3894) lands.
+ *
+ * @type {ReadonlySet<string>}
+ */
+export const NEVER_STAGE_PATHS = Object.freeze(
+  new Set([
+    '.env',
+    '.env.local',
+    '.mcp.json',
+    '.agentrc.local.json',
+    '.agents/instructions.local.md',
+  ]),
+);
+
+/**
+ * The conventional commit subject the offer uses for the wiring commit.
+ *
+ * @type {string}
+ */
+export const COMMIT_SUBJECT = 'chore: wire up Mandrel agent framework';
+
+/**
+ * Resolve the subset of {@link BOOTSTRAP_COMMIT_PATHS} that actually exist on
+ * disk and are not in {@link NEVER_STAGE_PATHS}. Pure (filesystem read only):
+ * the secret-exclusion is applied here so a never-stage path is dropped before
+ * it ever reaches `git add`.
+ *
+ * @param {string} projectRoot
+ * @param {typeof fs} [fsImpl]
+ * @returns {string[]} project-root-relative paths safe to stage
+ */
+export function resolveStagePaths(projectRoot, fsImpl = fs) {
+  return BOOTSTRAP_COMMIT_PATHS.filter((rel) => {
+    if (NEVER_STAGE_PATHS.has(rel)) return false;
+    return fsImpl.existsSync(path.join(projectRoot, rel));
+  });
+}
+
+/**
+ * Build the exact manual commands the operator should run to commit and push
+ * the wiring themselves. Printed when the offer is declined or the run is
+ * non-interactive (`--assume-yes`). The `git add` line stages the resolved
+ * allowlist only — never `git add -A` — so copy-pasting it cannot stage a
+ * secret file.
+ *
+ * @param {object} args
+ * @param {string[]} args.stagePaths — resolved, secret-free paths to stage.
+ * @param {string} args.baseBranch
+ * @returns {string} a multi-line, copy-pasteable command block
+ */
+export function buildManualInstructions({ stagePaths, baseBranch }) {
+  const addArgs = stagePaths.length > 0 ? stagePaths.join(' ') : '.';
+  return [
+    'To commit and push the Mandrel setup yourself, run:',
+    '',
+    `  git add ${addArgs}`,
+    `  git commit -m "${COMMIT_SUBJECT}"`,
+    `  git push -u origin ${baseBranch}`,
+    '',
+    'Story delivery runs in git worktrees that check out tracked files only,',
+    'so the .agents/ wiring MUST be committed before any /story-deliver or',
+    '/epic-deliver run — otherwise the worktree has no scripts and breaks.',
+  ].join('\n');
+}
+
+/**
+ * Stage the resolved allowlist via `git add -- <paths>`. No-op (returns
+ * `{ ok: true, staged: [] }`) when nothing resolves. Returns the git result on
+ * failure so the caller can surface it.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {(args: string[], cwd: string) => { ok: boolean, status?: number,
+ *   stdout?: string, stderr?: string }} args.runGit
+ * @param {typeof fs} [args.fsImpl]
+ * @returns {{ ok: boolean, staged: string[], error?: string }}
+ */
+export function stageBootstrapFiles({ projectRoot, runGit, fsImpl = fs }) {
+  const stagePaths = resolveStagePaths(projectRoot, fsImpl);
+  if (stagePaths.length === 0) {
+    return { ok: true, staged: [] };
+  }
+  const result = runGit(['add', '--', ...stagePaths], projectRoot);
+  if (!result.ok) {
+    return {
+      ok: false,
+      staged: [],
+      error: result.stderr || 'git add failed',
+    };
+  }
+  return { ok: true, staged: stagePaths };
+}

package/.agents/scripts/lib/bootstrap/gh-list.js

@@ -0,0 +1,153 @@
+/**
+ * bootstrap/gh-list — `gh`-backed list providers for live pickers.
+ *
+ * Provides the selection substrate for interactive pickers: thin wrappers
+ * over `gh repo list` / `gh project list` that shell out via the same
+ * `spawnSync('gh', …)` convention used elsewhere in the bootstrap libs
+ * (see `gh-preflight.js`). Both providers return a plain array of string
+ * values and degrade to an **empty array on any non-zero exit** (or spawn
+ * error), so a missing scope, an unauthenticated host, or a `gh` that is
+ * too old never throws here — the caller (the `resolveFromPicker` resolver
+ * in `prompt.js`) treats an empty list as "no picker available" and falls
+ * through to manual entry.
+ *
+ * The `runner` seam mirrors `gh-preflight.js`: it defaults to a real
+ * `spawnSync('gh', …)` but lets tests inject a stub returning the canonical
+ * `{ status, stdout, stderr, error }` shape without spawning a child.
+ */
+
+import { spawnSync } from 'node:child_process';
+
+/**
+ * Default runner: synchronously execs `gh <args>` and returns the canonical
+ * `{ status, stdout, stderr, error }` shape. Extracted so tests can inject a
+ * stub without spawning a real child process.
+ *
+ * @param {string[]} args
+ * @returns {{ status: number|null, stdout: string, stderr: string,
+ *             error?: NodeJS.ErrnoException }}
+ */
+function defaultGhRunner(args) {
+  const result = spawnSync('gh', args, { encoding: 'utf8' });
+  return {
+    status: result.status,
+    stdout: typeof result.stdout === 'string' ? result.stdout : '',
+    stderr: typeof result.stderr === 'string' ? result.stderr : '',
+    error: result.error,
+  };
+}
+
+/**
+ * Parse newline-delimited JSON-array stdout into a flat list of strings via
+ * the supplied `mapItem`. Returns `[]` for empty/whitespace stdout or any
+ * shape that does not parse to an array. Non-string mapped values are
+ * dropped so the picker only ever renders selectable strings.
+ *
+ * @param {string} stdout
+ * @param {(item: unknown) => unknown} mapItem
+ * @returns {string[]}
+ */
+function parseJsonList(stdout, mapItem) {
+  const trimmed = (stdout || '').trim();
+  if (trimmed.length === 0) return [];
+  let parsed;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    return [];
+  }
+  if (!Array.isArray(parsed)) return [];
+  return parsed
+    .map(mapItem)
+    .filter((value) => typeof value === 'string' && value.length > 0);
+}
+
+/**
+ * List repositories for an owner via `gh repo list <owner>`. Returns the
+ * `owner/name` slug for each repo, or `[]` on any non-zero exit / spawn
+ * error / missing owner.
+ *
+ * @param {{ owner?: string, runner?: (args: string[]) => {
+ *   status: number|null, stdout: string, stderr: string,
+ *   error?: NodeJS.ErrnoException
+ * } }} [opts]
+ * @returns {string[]}
+ */
+export function listRepos(opts = {}) {
+  const { owner, runner = defaultGhRunner } = opts;
+  if (typeof owner !== 'string' || owner.length === 0) return [];
+  const result = runner([
+    'repo',
+    'list',
+    owner,
+    '--json',
+    'nameWithOwner',
+    '--limit',
+    '100',
+  ]);
+  if (result.error || result.status !== 0) return [];
+  return parseJsonList(result.stdout, (item) =>
+    item && typeof item === 'object' ? item.nameWithOwner : undefined,
+  );
+}
+
+/**
+ * List projects (Projects v2) for an owner via `gh project list --owner
+ * <owner>`. Returns one `{ label, value }` choice per project — `label` is
+ * the human-readable title (with the number appended) and `value` is the
+ * numeric Projects V2 number as a string — or `[]` on any non-zero exit /
+ * spawn error / missing owner.
+ *
+ * @param {{ owner?: string, runner?: (args: string[]) => {
+ *   status: number|null, stdout: string, stderr: string,
+ *   error?: NodeJS.ErrnoException
+ * } }} [opts]
+ * @returns {{ label: string, value: string }[]}
+ */
+export function listProjects(opts = {}) {
+  const { owner, runner = defaultGhRunner } = opts;
+  if (typeof owner !== 'string' || owner.length === 0) return [];
+  const result = runner([
+    'project',
+    'list',
+    '--owner',
+    owner,
+    '--format',
+    'json',
+  ]);
+  if (result.error || result.status !== 0) return [];
+  // `gh project list --format json` emits `{ "projects": [...] }`, not a
+  // bare array. Unwrap the envelope before mapping titles.
+  const trimmed = (result.stdout || '').trim();
+  if (trimmed.length === 0) return [];
+  let parsed;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    return [];
+  }
+  const projects = Array.isArray(parsed)
+    ? parsed
+    : Array.isArray(parsed?.projects)
+      ? parsed.projects
+      : [];
+  // Return `{ label, value }` choices: the menu shows the human-readable
+  // title, but the resolved value is the numeric Projects V2 number that
+  // the `projectNumber` question's validator (and the downstream GitHub
+  // provider) require. Mapping the title into the numeric field would store
+  // a non-numeric string and break project resolution.
+  return projects
+    .map((item) => {
+      if (!item || typeof item !== 'object') return undefined;
+      const number = item.number;
+      if (typeof number !== 'number' || !Number.isInteger(number)) {
+        return undefined;
+      }
+      const title =
+        typeof item.title === 'string' && item.title.length > 0
+          ? item.title
+          : String(number);
+      return { label: `${title} (#${number})`, value: String(number) };
+    })
+    .filter((choice) => choice !== undefined);
+}