mandrel 1.69.0 → 1.70.0

package/.agents/README.md

@@ -466,7 +466,7 @@ ticketing provider is GitHub, resolved by `provider-factory.js` from the
 `orchestration.provider` config key. CLI scripts receive provider
 instances from the SDK surface rather than importing provider
 implementations directly. Execution is Claude-Code-in-session — there is
-no separate adapter abstraction; `wave-dispatcher.js` synthesizes the
+no separate adapter abstraction; `manifest-builder.js` synthesizes the
 dispatch record inline and the dispatch manifest (md + structured
 comment) is the cross-runtime contract.
 

package/.agents/docs/workflows.md

@@ -29,7 +29,7 @@ description, edit the workflow file’s front-matter and regenerate.
 
 | Command | Description |
 | --- | --- |
-| `/agents-update` | npm-era upgrade wraparound for a Mandrel consumer. Runs `mandrel update` (resolve newest published version → install → re-materialize `.agents/` → migrate → doctor → surface changelog) as the single mechanical step, then walks the operator through the judgment wraparound the CLI deliberately leaves unowned: reconcile `.agentrc.json`, install the Epic #1386 quality-gate surface, refresh the harness permission allowlist, reconcile the consumer's `AGENTS.md` / runbooks against the surfaced changelog, and stage + commit the staged lockfile bump. |
+| `/agents-update` | npm-era upgrade wraparound for a Mandrel consumer. Runs `npx mandrel update` (resolve newest published version → install → re-materialize `.agents/` → migrate → doctor → surface changelog) as the single mechanical step, then walks the operator through the judgment wraparound the CLI deliberately leaves unowned: reconcile `.agentrc.json`, install the Epic #1386 quality-gate surface, refresh the harness permission allowlist, reconcile the consumer's `AGENTS.md` / runbooks against the surfaced changelog, and stage + commit the staged lockfile bump. |
 | `/audit-architecture` | Audit architectural boundaries, module coupling, and layering violations; emit a structured findings report keyed to High/Medium/Low severity. |
 | `/audit-clean-code` | Audit code smells, dead code, complexity hotspots, and maintainability-index outliers; emit a structured findings report. |
 | `/audit-dependencies` | Audit `package.json` for unused, outdated, and major-version-stale dependencies; surface Node-engine drift and propose upgrade batches. |

package/.agents/scripts/agents-update-preflight.js

@@ -0,0 +1,235 @@
+#!/usr/bin/env node
+
+/**
+ * agents-update-preflight.js — Story #4170
+ * (feat(agents-update): add a first-run preflight before the updater)
+ *
+ * A first-run preflight for the `/agents-update` workflow. The workflow
+ * otherwise jumps straight to `npx mandrel update` with no guard rails;
+ * this preflight catches three day-0 failure modes *before* the version
+ * bump:
+ *
+ *   1. **Wrong project (hard stop).** Running the updater in the framework
+ *      repo itself or in a non-consumer (no `mandrel` dependency in
+ *      `package.json`, or no materialized `.agents/` directory) silently
+ *      does the wrong thing. The consumer-shape check is a BLOCKER: it
+ *      exits non-zero so the workflow halts before bumping anything.
+ *   2. **Dirty git index (warn).** `mandrel update` deliberately leaves the
+ *      lockfile *staged* (see `lib/cli/update.js`); the workflow's commit
+ *      step then `git add`s and commits. If the index already holds
+ *      unrelated staged changes, that step would sweep them into the
+ *      `chore: update mandrel` commit. Warn so the operator can unstage
+ *      first.
+ *   3. **Offline (warn).** The CLI throws a usable error on a failed
+ *      `npm view`, but a one-line up-front reachability check gives a
+ *      friendlier "you're offline" signal before any version probe.
+ *
+ * Severity is consistent with framework preflight conventions
+ * (cf. `story-close.js` runStoryClosePreflight, `epic-deliver-preflight.js`):
+ * the consumer-shape check is a hard stop (blocker), dirty-index and offline
+ * are warn-only and never block the run.
+ *
+ * Out of scope (per the Story): folding these checks into
+ * `lib/cli/update.js` itself — the CLI stays git-free and
+ * side-effect-scoped; this is a workflow-layer concern.
+ *
+ * The detection logic is a pure function (`runAgentsUpdatePreflight`) that
+ * takes injectable probes so it is unit-testable without touching the real
+ * filesystem, git index, or network. The CLI wrapper wires the real probes
+ * and maps a blocker finding to a non-zero exit code.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { runAsCli } from './lib/cli-utils.js';
+import { Logger } from './lib/Logger.js';
+
+/**
+ * @typedef {object} PreflightFinding
+ * @property {string} id        Stable check id.
+ * @property {'blocker'|'warning'} severity
+ * @property {string} summary   One-line human-readable description.
+ * @property {string} [fix]     Copy-pasteable remediation hint.
+ */
+
+/**
+ * Real-world probes. Each is overridable in tests via the `probes` option.
+ *
+ * @param {string} projectRoot Absolute consumer repo root.
+ */
+export function makeProbes(projectRoot) {
+  return {
+    /**
+     * Read + parse `package.json`. Returns the parsed object, or `null`
+     * when the file is missing or unparseable.
+     */
+    readPackageJson() {
+      const pkgPath = path.join(projectRoot, 'package.json');
+      if (!existsSync(pkgPath)) return null;
+      try {
+        return JSON.parse(readFileSync(pkgPath, 'utf8'));
+      } catch {
+        return null;
+      }
+    },
+    /** Does the materialized `.agents/` directory exist? */
+    agentsDirExists() {
+      return existsSync(path.join(projectRoot, '.agents'));
+    },
+    /**
+     * Are there staged (index) changes? Returns true when
+     * `git diff --cached --name-only` is non-empty. Returns false on any
+     * git error (not a repo, git missing) — a missing index is not a
+     * dirty index.
+     */
+    hasStagedChanges() {
+      try {
+        const out = execFileSync('git', ['diff', '--cached', '--name-only'], {
+          cwd: projectRoot,
+          encoding: 'utf8',
+          stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        return out.trim().length > 0;
+      } catch {
+        return false;
+      }
+    },
+    /**
+     * Is the npm registry reachable? Probes `npm ping` (a PM-agnostic
+     * reachability query that does not mutate anything). Returns true when
+     * the ping succeeds, false on any failure (offline / registry down).
+     */
+    registryReachable() {
+      try {
+        execFileSync('npm', ['ping'], {
+          cwd: projectRoot,
+          encoding: 'utf8',
+          stdio: ['ignore', 'ignore', 'ignore'],
+          timeout: 10_000,
+        });
+        return true;
+      } catch {
+        return false;
+      }
+    },
+  };
+}
+
+/**
+ * Pure preflight evaluator. Runs the three checks against the supplied
+ * probes and returns a structured result. Never throws; never performs
+ * I/O directly (all I/O is behind `probes`).
+ *
+ * @param {object} options
+ * @param {ReturnType<typeof makeProbes>} options.probes
+ * @returns {{ ok: boolean, blocked: boolean, findings: PreflightFinding[] }}
+ *   `blocked` is true when any blocker-severity finding fired (the
+ *   consumer-shape hard stop). `ok` is true when there are no findings of
+ *   any severity.
+ */
+export function runAgentsUpdatePreflight({ probes }) {
+  /** @type {PreflightFinding[]} */
+  const findings = [];
+
+  // 1. Consumer-shape check — BLOCKER (hard stop).
+  const pkg = probes.readPackageJson();
+  const deps = pkg
+    ? {
+        ...(pkg.dependencies ?? {}),
+        ...(pkg.devDependencies ?? {}),
+        ...(pkg.optionalDependencies ?? {}),
+      }
+    : {};
+  const hasMandrelDep = Object.hasOwn(deps, 'mandrel');
+  const hasAgentsDir = probes.agentsDirExists();
+
+  if (!pkg || !hasMandrelDep || !hasAgentsDir) {
+    const missing = [];
+    if (!pkg) missing.push('no readable package.json');
+    else if (!hasMandrelDep)
+      missing.push('package.json does not list "mandrel" as a dependency');
+    if (!hasAgentsDir) missing.push('no .agents/ directory');
+    findings.push({
+      id: 'consumer-shape',
+      severity: 'blocker',
+      summary: `Not a Mandrel consumer project (${missing.join('; ')}). Run /agents-update from a consumer repo that depends on "mandrel" and has a materialized .agents/ tree — not the framework repo itself or an unrelated project.`,
+      fix: 'cd into the consumer project root, or run `npm install -D mandrel && npx mandrel sync` to bootstrap one.',
+    });
+  }
+
+  // 2. Dirty-index check — WARN only.
+  if (probes.hasStagedChanges()) {
+    findings.push({
+      id: 'dirty-index',
+      severity: 'warning',
+      summary:
+        "The git index already has staged changes. `mandrel update` leaves the lockfile staged, and the workflow's commit step (Step 5) would sweep these unrelated staged files into the `chore: update mandrel` commit.",
+      fix: 'Unstage unrelated changes first: `git restore --staged <path>` (or `git reset` to clear the whole index), then re-run the preflight.',
+    });
+  }
+
+  // 3. Offline check — WARN only.
+  if (!probes.registryReachable()) {
+    findings.push({
+      id: 'offline',
+      severity: 'warning',
+      summary:
+        'The npm registry is not reachable. `npx mandrel update` resolves the newest published version via the registry and will fail its version probe while offline.',
+      fix: 'Check your network connection (or registry auth/proxy config) before running `npx mandrel update`.',
+    });
+  }
+
+  const blocked = findings.some((f) => f.severity === 'blocker');
+  return { ok: findings.length === 0, blocked, findings };
+}
+
+/**
+ * Render the findings to a logger. Blockers go to `error`, warnings to
+ * `warn`. A clean result logs a single `info` line.
+ *
+ * @param {{ ok: boolean, blocked: boolean, findings: PreflightFinding[] }} result
+ * @param {{ info: Function, warn: Function, error: Function }} logger
+ */
+export function reportPreflight(result, logger) {
+  if (result.ok) {
+    logger.info(
+      '✅ [agents-update-preflight] All checks passed — safe to run `npx mandrel update`.',
+    );
+    return;
+  }
+  for (const f of result.findings) {
+    const line = `[${f.id}] ${f.summary}${f.fix ? `\n  ↳ Fix: ${f.fix}` : ''}`;
+    if (f.severity === 'blocker') {
+      logger.error(`❌ ${line}`);
+    } else {
+      logger.warn(`⚠️  ${line}`);
+    }
+  }
+  if (result.blocked) {
+    logger.error(
+      '[agents-update-preflight] Hard stop: do not run `npx mandrel update` until the blocker above is resolved (exit 2).',
+    );
+  } else {
+    logger.warn(
+      '[agents-update-preflight] Warnings only — review them, then proceed if intentional.',
+    );
+  }
+}
+
+async function main() {
+  const projectRoot = process.cwd();
+  const probes = makeProbes(projectRoot);
+  const result = runAgentsUpdatePreflight({ probes });
+  reportPreflight(result, Logger);
+  // Machine-parsable JSON envelope on stdout for tooling / the workflow to
+  // read. Use process.stdout.write (not console.log) per the no-console
+  // enforcement boundary: human-facing output goes through Logger above.
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+  return result.blocked ? 2 : 0;
+}
+
+runAsCli(import.meta.url, main, {
+  source: 'agents-update-preflight',
+  propagateExitCode: true,
+});

package/.agents/scripts/apply-quality-bootstrap.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+
+/**
+ * apply-quality-bootstrap.js — Story #4171
+ * (refactor(agents-update): extract the quality-bootstrap heredoc into a
+ * tested script)
+ *
+ * Replaces the inline `node -e "Promise.all([...])"` heredoc that Step 3.5 of
+ * the `/agents-update` workflow used to carry. That shape was fragile in three
+ * ways: it broke across shells (PowerShell vs bash quoting / backticks), it
+ * had no test so it silently drifted when the two helper signatures moved, and
+ * it could not be invoked or dry-run independently.
+ *
+ * This script runs the two Epic #1386 quality-gate installs in order against
+ * the consumer repo root:
+ *
+ *   1. `applyQualityBootstrap` — copies the code-quality-guardrails helper,
+ *      installs the `.husky/pre-commit` quality:preview line, backfills the
+ *      `quality:preview` / `quality:watch` npm scripts, and seeds the
+ *      `delivery.quality.{codingGuardrails,autoRefresh}` defaults.
+ *   2. `migrateBaselinesLayout` — relocates per-Epic baseline snapshots into
+ *      the `temp/epic/<id>/baselines/` namespace.
+ *
+ * Both helpers are idempotent by contract — a second run reports `no-change`
+ * on every install path — so this wrapper is safe to re-run. It prints the
+ * **same JSON result shape** the heredoc did: `{ quality, baselines }` to
+ * stdout, so any tooling that parsed the old output keeps working.
+ *
+ * The effectful work is a thin pure function (`applyBootstrapAndMigration`)
+ * that takes the two helpers and the project root, so the test suite can
+ * drive it against a tmp directory without spawning a child process. The CLI
+ * wrapper wires the real helpers and `process.cwd()`.
+ */
+
+import path from 'node:path';
+import { migrateBaselinesLayout } from './lib/bootstrap/baselines-layout-migration.js';
+import { applyQualityBootstrap } from './lib/bootstrap/quality-bootstrap.js';
+import { runAsCli } from './lib/cli-utils.js';
+
+/**
+ * Run the quality-bootstrap install and the baselines-layout migration
+ * against `projectRoot`, returning the combined `{ quality, baselines }`
+ * envelope. Pure relative to its injected helpers: the default helpers touch
+ * the filesystem under `projectRoot`, but tests can pass stubs to exercise
+ * the composition in isolation.
+ *
+ * @param {object} options
+ * @param {string} options.projectRoot Absolute consumer repo root.
+ * @param {typeof applyQualityBootstrap} [options.applyQualityBootstrap]
+ * @param {typeof migrateBaselinesLayout} [options.migrateBaselinesLayout]
+ * @returns {{ quality: object, baselines: object }}
+ */
+export function applyBootstrapAndMigration({
+  projectRoot,
+  applyQualityBootstrap: applyQuality = applyQualityBootstrap,
+  migrateBaselinesLayout: migrateBaselines = migrateBaselinesLayout,
+}) {
+  const quality = applyQuality({ projectRoot });
+  const baselines = migrateBaselines({
+    baselinesDir: path.join(projectRoot, 'baselines'),
+    repoRoot: projectRoot,
+  });
+  return { quality, baselines };
+}
+
+async function main() {
+  const projectRoot = process.cwd();
+  const result = applyBootstrapAndMigration({ projectRoot });
+  // Mirror the retired heredoc's output: pretty-printed `{ quality, baselines }`
+  // to stdout. Use process.stdout.write (not console.log) per the no-console
+  // enforcement boundary.
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  return 0;
+}
+
+runAsCli(import.meta.url, main, {
+  source: 'apply-quality-bootstrap',
+  propagateExitCode: true,
+});

package/.agents/scripts/audit-labels-bootstrap.js

@@ -1,14 +1,21 @@
 /**
- * audit-labels-bootstrap.js — Idempotently create the `audit::<dimension>`
+ * audit-labels-bootstrap.js — Idempotently create the `audit::<lens>`
  * label taxonomy in the configured GitHub repo.
  *
  * Run this once per repo before `/audit-to-stories` opens its first
  * Story. Re-runs are safe — existing labels are skipped, only missing
  * ones are created. Story #2583 acceptance criterion #6.
  *
- * The dimension list mirrors the 12 audit-* workflows in
- * `.agents/workflows/`. Adding a new audit-* workflow should also add a
- * corresponding entry below.
+ * The lens list is the shared SSOT `AUDIT_LENSES`
+ * (`lib/audit-to-stories/audit-lenses.js`), one per `/audit-<lens>` workflow
+ * under `.agents/workflows/`. Sourcing the list from the same module that
+ * `build-story-body.js` derives `audit::<lens>` labels from guarantees the
+ * label producer (this bootstrap) and the label deriver (story-body) cannot
+ * drift — a finding from `audit-documentation-results.md` derives
+ * `audit::documentation`, and this bootstrap creates exactly that label
+ * (Story #4195). The per-lens colour/description metadata lives in
+ * `LENS_META` below; adding a new `audit-*` workflow means adding its lens to
+ * `AUDIT_LENSES` and (optionally) a `LENS_META` entry.
  *
  * Delegates to `gh label create` so the script works without any
  * provider plumbing — `gh auth status` is the only prerequisite. Per
@@ -19,72 +26,87 @@
 import process from 'node:process';
 import { parseArgs } from 'node:util';
 
+import { AUDIT_LENSES } from './lib/audit-to-stories/audit-lenses.js';
 import { runAsCli } from './lib/cli-utils.js';
 import { resolveConfig } from './lib/config-resolver.js';
 import { gh as defaultGh, GhExecError } from './lib/gh-exec.js';
 
-const DIMENSIONS = Object.freeze([
-  {
-    name: 'architecture',
+/**
+ * Per-lens label presentation. Keyed by canonical lens name. A lens absent
+ * from this map falls back to {@link DEFAULT_LENS_META} so a newly-added
+ * `AUDIT_LENSES` entry still gets a label without a hard requirement to
+ * register colour/description here first.
+ */
+const LENS_META = Object.freeze({
+  architecture: {
     color: '6f42c1',
     description: 'Audit-sourced finding: architectural concerns',
   },
-  {
-    name: 'clean-code',
+  'clean-code': {
     color: '0e8a16',
     description: 'Audit-sourced finding: clean-code / maintainability',
   },
-  {
-    name: 'dependencies',
+  dependencies: {
     color: 'd4c5f9',
     description: 'Audit-sourced finding: dependencies / supply chain',
   },
-  {
-    name: 'devops',
+  devops: {
     color: 'fbca04',
     description: 'Audit-sourced finding: DevOps / CI / CD',
   },
-  {
-    name: 'lighthouse',
+  documentation: {
+    color: '1d76db',
+    description: 'Audit-sourced finding: documentation staleness / gaps',
+  },
+  lighthouse: {
     color: 'c5def5',
     description: 'Audit-sourced finding: Lighthouse score regressions',
   },
-  {
-    name: 'performance',
+  navigability: {
+    color: 'bfdadc',
+    description: 'Audit-sourced finding: route / nav reachability',
+  },
+  performance: {
     color: 'b60205',
     description: 'Audit-sourced finding: performance / latency',
   },
-  {
-    name: 'privacy',
+  privacy: {
     color: 'fef2c0',
     description: 'Audit-sourced finding: privacy / data handling',
   },
-  {
-    name: 'quality',
+  quality: {
     color: '0052cc',
     description: 'Audit-sourced finding: test quality / coverage gaps',
   },
-  {
-    name: 'security',
+  security: {
     color: 'b60205',
     description: 'Audit-sourced finding: security / OWASP',
   },
-  {
-    name: 'seo',
+  seo: {
     color: 'fbca04',
     description: 'Audit-sourced finding: SEO / discoverability',
   },
-  {
-    name: 'sre',
+  sre: {
     color: '0052cc',
     description: 'Audit-sourced finding: SRE / observability / reliability',
   },
-  {
-    name: 'ux-ui',
+  'ux-ui': {
     color: 'd4c5f9',
     description: 'Audit-sourced finding: UX / UI concerns',
   },
-]);
+});
+
+const DEFAULT_LENS_META = Object.freeze({
+  color: 'ededed',
+  description: 'Audit-sourced finding',
+});
+
+const DIMENSIONS = Object.freeze(
+  AUDIT_LENSES.map((name) => ({
+    name,
+    ...(LENS_META[name] ?? DEFAULT_LENS_META),
+  })),
+);
 
 async function labelExists(gh, owner, repo, name) {
   try {

package/.agents/scripts/audit-to-stories.js

@@ -39,6 +39,7 @@ import { groupFindings } from './lib/audit-to-stories/group-findings.js';
 import { parseAuditReports } from './lib/audit-to-stories/parse-audit-md.js';
 import { buildEpicSeedMarkdown } from './lib/audit-to-stories/seed-epic-from-findings.js';
 import { runAsCli } from './lib/cli-utils.js';
+import { Logger } from './lib/Logger.js';
 
 const SEVERITY_RANK = { critical: 4, high: 3, medium: 2, low: 1 };
 const DEFAULT_GLOB = 'temp/audits/audit-*-results.md';
@@ -109,6 +110,44 @@ async function loadProvider() {
   }
 }
 
+/**
+ * Render the loud, operator-visible warning emitted when the Phase 6 dedup
+ * does NOT run against real GitHub issues. Two distinct reasons:
+ *
+ *   - `'no-provider-port'` — the configured provider resolved but exposes no
+ *     `searchIssues` port (or `loadProvider()` threw). This is the
+ *     silent-no-op the workflow's "Never open a duplicate Issue" contract
+ *     was failing on: every group classifies `create` and the operator gets
+ *     zero automated dedup signal. Surfacing it loudly is the whole point.
+ *   - `'disabled'` — the operator passed `--no-provider`, intentionally
+ *     skipping dedup. Still warned (so a re-run that opens duplicates is
+ *     never a surprise), but framed as a deliberate choice.
+ *
+ * Pure: returns the message string so `buildPlan` owns the single
+ * `Logger.warn` write site and the text stays unit-testable.
+ *
+ * @param {'no-provider-port'|'disabled'} reason
+ * @returns {string}
+ */
+function dedupSkippedWarning(reason) {
+  if (reason === 'disabled') {
+    return (
+      'dedup skipped (--no-provider): every group is classified "create" ' +
+      'without checking GitHub for existing issues. A re-run may open ' +
+      'duplicates of already-tracked or already-closed findings. Drop ' +
+      '--no-provider to enable fingerprint dedup against real issues.'
+    );
+  }
+  return (
+    'dedup skipped (no provider port): the configured provider exposes no ' +
+    'searchIssues() port, so Phase 6 dedup did NOT run. Every group is ' +
+    'classified "create" and existing/closed issues are NOT checked — a run ' +
+    'that creates Stories from this plan WILL open duplicates of ' +
+    'already-tracked work. Verify `gh auth status` and the github.{owner,repo} ' +
+    'config so a real provider resolves.'
+  );
+}
+
 async function buildPlan({ glob: pattern, severity, useProvider }) {
   const reportPaths = await collectReportPaths(pattern ?? DEFAULT_GLOB);
   if (reportPaths.length === 0) {
@@ -143,6 +182,7 @@ async function buildPlan({ glob: pattern, severity, useProvider }) {
     matchedFingerprints: [],
   }));
   let summary = { create: groups.length, skipOpen: 0, skipReoccurring: 0 };
+  let dedupApplied = false;
 
   if (useProvider) {
     const provider = await loadProvider();
@@ -150,7 +190,18 @@ async function buildPlan({ glob: pattern, severity, useProvider }) {
       const result = await classifyGroupsAgainstGitHub({ groups, provider });
       classifications = result.classifications;
       summary = result.summary;
+      dedupApplied = true;
+    } else {
+      // The provider could not resolve a searchIssues port — the dedup gate
+      // is silently a no-op without this. Surface it loudly (stderr, so the
+      // --scan JSON on stdout stays clean) so the operator does not read a
+      // create-only plan as "no duplicates found".
+      Logger.warn(dedupSkippedWarning('no-provider-port'));
     }
+  } else {
+    // Operator explicitly opted out via --no-provider. Still warn so a
+    // duplicate-opening re-run is never a surprise.
+    Logger.warn(dedupSkippedWarning('disabled'));
   }
 
   return {
@@ -165,6 +216,7 @@ async function buildPlan({ glob: pattern, severity, useProvider }) {
       totalFindings: allFindings.length,
       filtered: filtered.length,
       tally: tallyBySeverity(filtered),
+      dedupApplied,
       ...summary,
     },
   };
@@ -188,6 +240,8 @@ export const __testing = {
   meetsSeverity,
   collectReportPaths,
   buildPlan,
+  loadProvider,
+  dedupSkippedWarning,
 };
 
 async function main() {

package/.agents/scripts/bootstrap.js

@@ -534,6 +534,13 @@ export function buildQuestions(defaults, flags, env = process.env, lists = {}) {
   const reposList = lists.reposList;
   const projectsList = lists.projectsList;
   const pickerOwner = (answers) => answers?.owner || owner;
+  // `owner` / `repo` are GitHub-side answers. When `--skip-github` suppresses
+  // the entire GitHub bootstrap, they are not required — this lets a
+  // non-interactive `--assume-yes --skip-github` run materialize and configure
+  // a fresh non-git directory (no inferable remote) without hard-failing on
+  // `missing required answers: owner, repo`. With GitHub bootstrap active they
+  // remain required (the target repo must be resolvable).
+  const skipGithub = Boolean(flags?.['skip-github']);
   return [
     {
       key: 'owner',
@@ -541,7 +548,7 @@ export function buildQuestions(defaults, flags, env = process.env, lists = {}) {
       env: 'GH_OWNER',
       message: '\n\nGitHub repo owner',
       default: defaults.owner,
-      required: true,
+      required: !skipGithub,
       validate: (v) =>
         /^[A-Za-z0-9][A-Za-z0-9-]*$/.test(v) ? null : 'Invalid GitHub owner',
     },
@@ -567,7 +574,7 @@ export function buildQuestions(defaults, flags, env = process.env, lists = {}) {
       pickerMessage:
         'GitHub repo name  - Select existing or press ENTER to create',
       default: defaults.repo,
-      required: true,
+      required: !skipGithub,
       picker: {
         list: (answers) => {
           if (Array.isArray(reposList) && reposList.length > 0)
@@ -957,7 +964,10 @@ export async function collectAndConfirm(state) {
     });
     if (missing.length > 0) {
       Logger.error(
-        `[Bootstrap] missing required answers: ${missing.join(', ')}`,
+        `[Bootstrap] missing required answers: ${missing.join(', ')}. ` +
+          'Pass them as flags (e.g. `--owner <name> --repo <name>`), or run ' +
+          'with `--skip-github` to configure the files/local setup only and ' +
+          'wire GitHub later.',
       );
       return { ok: false, exit: 1 };
     }