yadflow 2.12.0 → 2.14.0

package/cli/setup.mjs

@@ -3,7 +3,7 @@ import path from 'node:path';
 import fs from 'node:fs';
 import os from 'node:os';
 import {
-  c, log, step, ok, info, warn, hand, fail, ask, askYesNo, run, has,
+  c, log, step, guide, ok, info, warn, hand, fail, ask, askYesNo, run, has,
   exists, readJSON, writeJSON,
 } from './lib.mjs';
 import { VERSION, IDE_FOLDER_TARGETS, PROJECT_FILES, DESIGN_TOOLS, DESIGN_PRIMARY, TESTING_TOOLS, TESTING_PRIMARY, LEARNING_TOOLS, LEARNING_PRIMARY } from './manifest.mjs';
@@ -176,7 +176,7 @@ export function reconcileRepoRoles(root, name, repo, current = [], want = []) {
   ok(`    ${repo}: ${want.length ? want.join(', ') : 'cleared'}`);
 }
 
-export function registerRepo(root, registry, { name, rpath, platform, domain_owner = '', domain_owners = null, default_branch = 'main', today = null }) {
+export function registerRepo(root, registry, { name, rpath, platform, domain_owner = '', domain_owners = null, default_branch = 'main', today = null, pack = true }) {
   if (!insideRoot(root, rpath)) {
     warn(`${rpath} resolves outside the project root — skipped`);
     return null;
@@ -198,7 +198,10 @@ export function registerRepo(root, registry, { name, rpath, platform, domain_own
     name, path: rpath, git_url: (remote.ok && remote.stdout) || null, platform: plat,
     domain_owner: owners[0] || '', domain_owners: owners, default_branch,
     connectedAt: today, lastSyncedAt: today,
-    syncedHead: head,
+    // Only claim a synced HEAD when a pack is actually produced. The greenfield path skips packing
+    // (pack:false), so leave syncedHead null — the repo then reads as "needs an initial pack" in
+    // `yad repo list` / `yad doctor` instead of falsely "fresh".
+    syncedHead: pack ? head : null,
     contextPack: `.sdlc/code-context/${name}/pack.md`,
     codeMap: `.sdlc/code-context/${name}/code-map.md`,
     source: 'repomix',
@@ -305,13 +308,70 @@ function applyActions(actions, { force = false } = {}) {
   return changed;
 }
 
+// Step 0 — resolve the setup profile that branches the rest of the wizard. Flags pre-answer each
+// question (CI/scripts); an existing hub.json carries prior answers forward (idempotent re-run);
+// otherwise we prompt with a default. Pure of side effects — it only reads. Returns
+// { solo, team_size, codebase, repo_layout, configureTools }.
+export async function resolveProfile(root, opts = {}) {
+  const hub = readJSON(path.join(root, PROJECT_FILES.hubConfig), null);
+  const prev = (hub && hub.profile) || {};
+
+  // 1. Solo or team (+ size). --solo / --team <n> win; else carry hub.solo forward; else ask.
+  let solo, team_size;
+  if (opts.solo) { solo = true; team_size = 1; }
+  else if (opts.team != null) { team_size = Math.max(1, parseInt(opts.team, 10) || 1); solo = team_size <= 1; }
+  else if (typeof hub?.solo === 'boolean') { solo = hub.solo; team_size = prev.team_size ?? (solo ? 1 : 2); }
+  else {
+    // Default from any existing roster: a hub already carrying reviewers is a team; otherwise solo.
+    const rosterN = Array.isArray(hub?.roster) ? hub.roster.length : 0;
+    solo = !(await ask('Solo or team?', rosterN > 1 ? 'team' : 'solo')).toLowerCase().startsWith('t');
+    team_size = solo ? 1 : Math.max(2, parseInt(await ask('  how many team members?', String(rosterN || 2)), 10) || 2);
+  }
+
+  // 2. Greenfield (new code) or brownfield (existing code).
+  let codebase;
+  if (opts.greenfield) codebase = 'greenfield';
+  else if (opts.brownfield) codebase = 'brownfield';
+  else if (prev.codebase) codebase = prev.codebase;
+  else codebase = (await ask('Greenfield (new code) or brownfield (existing code)?', 'greenfield')).toLowerCase().startsWith('b') ? 'brownfield' : 'greenfield';
+
+  // 3. Monorepo (one repo) or separate repos.
+  let repo_layout;
+  if (opts.monorepo) repo_layout = 'monorepo';
+  else if (opts.separate) repo_layout = 'separate';
+  else if (prev.repo_layout) repo_layout = prev.repo_layout;
+  else repo_layout = (await ask('Monorepo (one repo) or separate repos?', 'monorepo')).toLowerCase().startsWith('s') ? 'separate' : 'monorepo';
+
+  // 4. Configure the optional tools now, or defer (records them as none, connect later).
+  const configureTools = opts.tools === true ? true
+    : process.env.SDLC_NONINTERACTIVE ? false
+      : await askYesNo('Configure design/testing/learning tools now? (else connect them later)', false);
+
+  return { solo, team_size, codebase, repo_layout, configureTools };
+}
+
+// The guided, idempotent first-run wizard: a Step 0 profile interview (resolveProfile) that branches
+// the remaining steps — install, hub + roster, optional tools, repos, wiring — and persists the profile.
 export async function runSetup(root, opts = {}) {
-  const total = 10;
   log(c.bold(`\nSDLC Workflow setup  ${c.dim('v' + VERSION)}`));
   log(c.dim(`target: ${root}`));
 
-  // 1. Preflight
-  step(1, total, 'Preflight');
+  // 0. Profile interview — branch the wizard to the user's situation (solo/team, code, repo layout).
+  const { solo, team_size, codebase, repo_layout, configureTools } = await resolveProfile(root, opts);
+  // Steps: interview, preflight, install, hub, tools (1 if deferred else 3), repos, wire, coderabbit, done.
+  const total = 8 + (configureTools ? 3 : 1);
+  let _n = 0;
+  const S = (title) => step(++_n, total, title);
+
+  S('Profile');
+  guide([
+    'How you answer here shapes the rest of setup — fewer prompts, the right path.',
+    `solo: ${solo ? 'yes — you review by merging your own PR (approval waived)' : `no — team of ${team_size}`}`,
+    `code: ${codebase}  •  repos: ${repo_layout}  •  optional tools: ${configureTools ? 'configure now' : 'deferred (connect later)'}`,
+  ]);
+
+  // Preflight
+  S('Preflight');
   if (!exists(path.join(root, '.git'))) {
     if (await askYesNo('Not a git repo. Run `git init` here?', true)) {
       run('git', ['init'], { cwd: root });
@@ -321,8 +381,12 @@ export async function runSetup(root, opts = {}) {
   for (const tool of ['git', 'node']) has(tool) ? ok(`${tool} present`) : warn(`${tool} not found on PATH`);
   if (!has('npx')) warn('npx not found — repomix packing will be skipped');
 
-  // 2. Install the module
-  step(2, total, 'Install the module (skills + _bmad registration)');
+  // Install the module
+  S('Install the module (skills + _bmad registration)');
+  guide([
+    'Copies the yad-* skills into your AI tool(s) so they appear in Claude Code / agents / opencode.',
+    'Enter the IDE folders to install into, comma-separated; default = whatever is already present.',
+  ]);
   let ideTargets = opts.ideTargets;
   if (!ideTargets) {
     const present = ALL_IDES.filter((d) => exists(path.join(root, d)));
@@ -352,8 +416,18 @@ export async function runSetup(root, opts = {}) {
     }
   }
 
-  // 3. Detect hub platform + roster
-  step(3, total, 'Hub platform & reviewer roster');
+  // Detect hub platform + roster
+  S(solo ? 'Hub platform (solo — no roster)' : 'Hub platform & reviewer roster');
+  guide(solo
+    ? [
+      'Your hub is this repo on GitHub/GitLab (or none for a file-only gate).',
+      'Solo: no roster needed — you review by merging your own PR (approval waived).',
+    ]
+    : [
+      'Your hub is this repo on GitHub/GitLab; reviewers approve artifacts there.',
+      `Add your ${team_size}-person roster: platform login → yad name → hub role (owner/reviewer).`,
+      'An owner + 1 reviewer is required to pass a gate; skip now and add later with `yad roster add`.',
+    ]);
   const hubPath = path.join(root, PROJECT_FILES.hubConfig);
   if (exists(hubPath) && !(await askYesNo('hub.json exists — reconfigure?', false))) {
     info('keeping existing .sdlc/hub.json');
@@ -367,7 +441,8 @@ export async function runSetup(root, opts = {}) {
       platform = 'none';
     }
     const roster = [];
-    if (await askYesNo('Add reviewers to the roster now?', true)) {
+    // Solo mode needs no roster — the lone developer is owner and reviewer-by-merge.
+    if (!solo && await askYesNo('Add reviewers to the roster now?', true)) {
       for (;;) {
         const login = await ask('  reviewer platform login (blank to finish)', '');
         if (!login) break;
@@ -392,68 +467,113 @@ export async function runSetup(root, opts = {}) {
     // `bridge_enabled` is the canonical flag (hub-config schema); keep the legacy `bridge` spelling
     // for anything that still reads it.
     const enabled = platform !== 'none';
-    writeJSON(hubPath, { platform: enabled ? platform : null, bridge_enabled: enabled, bridge: enabled, default_branch, roster });
-    ok(`wrote ${PROJECT_FILES.hubConfig} (${roster.length} reviewer(s))`);
+    writeJSON(hubPath, { platform: enabled ? platform : null, bridge_enabled: enabled, bridge: enabled, default_branch, roster, solo, profile: { codebase, repo_layout, team_size } });
+    ok(`wrote ${PROJECT_FILES.hubConfig} (${roster.length} reviewer(s)${solo ? ', solo mode' : ''})`);
   }
-
-  // 4. Connect a design tool (Figma-first, pluggable; the UI step materializes the design here)
-  step(4, total, 'Connect a design tool (Figma / pencil / none)');
-  const designPath = path.join(root, PROJECT_FILES.designConfig);
-  if (exists(designPath) && !(await askYesNo('design.json exists — reconfigure?', false))) {
-    info('keeping existing .sdlc/design.json');
-  } else {
-    let tool = (await ask(`Design tool (${DESIGN_TOOLS.join('/')}/none)`, DESIGN_PRIMARY)).toLowerCase();
-    if (![...DESIGN_TOOLS, 'none'].includes(tool)) {
-      warn(`unknown design tool '${tool}' — using ${DESIGN_PRIMARY}`);
-      tool = DESIGN_PRIMARY;
+  // Persist the profile + solo flag even on the "keeping existing" path, so re-running setup with new
+  // flags (e.g. `yad setup --solo`) updates the mode without a full reconfigure. Merge, never clobber.
+  if (exists(hubPath)) {
+    const cur = readJSON(hubPath, {}) || {};
+    if (cur.solo !== solo || JSON.stringify(cur.profile || {}) !== JSON.stringify({ codebase, repo_layout, team_size })) {
+      writeJSON(hubPath, { ...cur, solo, profile: { codebase, repo_layout, team_size } });
+      info(`recorded profile: ${solo ? 'solo' : `team(${team_size})`}, ${codebase}, ${repo_layout}`);
     }
-    const project_url = tool === 'none' ? null : (await ask('  project/file URL (blank to set later)', '')) || null;
-    registerDesign(root, { tool, project_url, today: opts.today ?? null });
-    ok(tool === 'none'
-      ? `wrote ${PROJECT_FILES.designConfig} (markdown-only)`
-      : `wrote ${PROJECT_FILES.designConfig} (${tool})`);
   }
 
-  // 5. Connect a testing tool (Playwright-first, pluggable; the test-cases step implements automation here)
-  step(5, total, 'Connect a testing tool (playwright / cypress / pytest / none)');
+  // Optional tools (design / testing / learning). Paths are declared here so the final summary can
+  // read them whether or not we configured the tools this run.
+  const designPath = path.join(root, PROJECT_FILES.designConfig);
   const testingPath = path.join(root, PROJECT_FILES.testingConfig);
-  if (exists(testingPath) && !(await askYesNo('testing.json exists — reconfigure?', false))) {
-    info('keeping existing .sdlc/testing.json');
-  } else {
-    let tool = (await ask(`Testing tool (${TESTING_TOOLS.join('/')}/none)`, TESTING_PRIMARY)).toLowerCase();
-    if (![...TESTING_TOOLS, 'none'].includes(tool)) {
-      warn(`unknown testing tool '${tool}' — using ${TESTING_PRIMARY}`);
-      tool = TESTING_PRIMARY;
+  const learningPath = path.join(root, PROJECT_FILES.learningConfig);
+  if (configureTools) {
+    // Connect a design tool (Figma-first, pluggable; the UI step materializes the design here)
+    S('Connect a design tool (Figma / pencil / none)');
+    guide([
+      'Where yad-ui materializes real screens. figma (confirm the MCP later) or none for markdown-only.',
+      'Skipping is safe — the UI step degrades to ui-design.md.',
+    ]);
+    if (exists(designPath) && !(await askYesNo('design.json exists — reconfigure?', false))) {
+      info('keeping existing .sdlc/design.json');
+    } else {
+      let tool = (await ask(`Design tool (${DESIGN_TOOLS.join('/')}/none)`, DESIGN_PRIMARY)).toLowerCase();
+      if (![...DESIGN_TOOLS, 'none'].includes(tool)) {
+        warn(`unknown design tool '${tool}' — using ${DESIGN_PRIMARY}`);
+        tool = DESIGN_PRIMARY;
+      }
+      const project_url = tool === 'none' ? null : (await ask('  project/file URL (blank to set later)', '')) || null;
+      registerDesign(root, { tool, project_url, today: opts.today ?? null });
+      ok(tool === 'none'
+        ? `wrote ${PROJECT_FILES.designConfig} (markdown-only)`
+        : `wrote ${PROJECT_FILES.designConfig} (${tool})`);
     }
-    const project_url = tool === 'none' ? null : (await ask('  project/config reference (blank to set later)', '')) || null;
-    registerTesting(root, { tool, project_url, today: opts.today ?? null });
-    ok(tool === 'none'
-      ? `wrote ${PROJECT_FILES.testingConfig} (artifacts-only)`
-      : `wrote ${PROJECT_FILES.testingConfig} (${tool})`);
-  }
 
-  // 6. Connect a learning tool (DeepTutor-first, pluggable; the learning layer tutors team members here)
-  step(6, total, 'Connect a learning tool (deeptutor / none)');
-  const learningPath = path.join(root, PROJECT_FILES.learningConfig);
-  if (exists(learningPath) && !(await askYesNo('learning.json exists — reconfigure?', false))) {
-    info('keeping existing .sdlc/learning.json');
-  } else {
-    let tool = (await ask(`Learning tool (${LEARNING_TOOLS.join('/')}/none)`, LEARNING_PRIMARY)).toLowerCase();
-    if (![...LEARNING_TOOLS, 'none'].includes(tool)) {
-      warn(`unknown learning tool '${tool}' — using ${LEARNING_PRIMARY}`);
-      tool = LEARNING_PRIMARY;
+    // Connect a testing tool (Playwright-first, pluggable; the test-cases step implements automation here)
+    S('Connect a testing tool (playwright / cypress / pytest / none)');
+    guide([
+      'Where yad-test-cases generates automation. playwright/cypress/pytest, or none for artifacts-only.',
+      'Skipping is safe — test-cases authors test-cases.md only.',
+    ]);
+    if (exists(testingPath) && !(await askYesNo('testing.json exists — reconfigure?', false))) {
+      info('keeping existing .sdlc/testing.json');
+    } else {
+      let tool = (await ask(`Testing tool (${TESTING_TOOLS.join('/')}/none)`, TESTING_PRIMARY)).toLowerCase();
+      if (![...TESTING_TOOLS, 'none'].includes(tool)) {
+        warn(`unknown testing tool '${tool}' — using ${TESTING_PRIMARY}`);
+        tool = TESTING_PRIMARY;
+      }
+      const project_url = tool === 'none' ? null : (await ask('  project/config reference (blank to set later)', '')) || null;
+      registerTesting(root, { tool, project_url, today: opts.today ?? null });
+      ok(tool === 'none'
+        ? `wrote ${PROJECT_FILES.testingConfig} (artifacts-only)`
+        : `wrote ${PROJECT_FILES.testingConfig} (${tool})`);
+    }
+
+    // Connect a learning tool (DeepTutor-first, pluggable; the learning layer tutors team members here)
+    S('Connect a learning tool (deeptutor / none)');
+    guide([
+      'Lets any team member invoke yad-learn to be tutored in-context. deeptutor (a CLI), or none.',
+      'Skipping is safe — yad-learn tutors via the harness model (harness-native).',
+    ]);
+    if (exists(learningPath) && !(await askYesNo('learning.json exists — reconfigure?', false))) {
+      info('keeping existing .sdlc/learning.json');
+    } else {
+      let tool = (await ask(`Learning tool (${LEARNING_TOOLS.join('/')}/none)`, LEARNING_PRIMARY)).toLowerCase();
+      if (![...LEARNING_TOOLS, 'none'].includes(tool)) {
+        warn(`unknown learning tool '${tool}' — using ${LEARNING_PRIMARY}`);
+        tool = LEARNING_PRIMARY;
+      }
+      registerLearning(root, { tool, today: opts.today ?? null });
+      ok(tool === 'none'
+        ? `wrote ${PROJECT_FILES.learningConfig} (harness-native)`
+        : `wrote ${PROJECT_FILES.learningConfig} (${tool})`);
     }
-    registerLearning(root, { tool, today: opts.today ?? null });
-    ok(tool === 'none'
-      ? `wrote ${PROJECT_FILES.learningConfig} (harness-native)`
-      : `wrote ${PROJECT_FILES.learningConfig} (${tool})`);
+  } else {
+    // Deferred: record any not-yet-present tool as none (degrades gracefully). Existing connections kept.
+    S('Optional tools (design / testing / learning) — deferred');
+    guide(['Recorded as none; connect any later with the yad-connect-* skills. Existing connections are kept.']);
+    if (!exists(designPath)) registerDesign(root, { tool: 'none', project_url: null, today: opts.today ?? null });
+    if (!exists(testingPath)) registerTesting(root, { tool: 'none', project_url: null, today: opts.today ?? null });
+    if (!exists(learningPath)) registerLearning(root, { tool: 'none', today: opts.today ?? null });
+    info('design / testing / learning recorded as none (connect later)');
   }
 
-  // 7. Connect code repos
-  step(7, total, 'Connect code repos');
+  // Connect code repos
+  S(repo_layout === 'monorepo' ? 'Connect your code repo (monorepo)' : 'Connect code repos');
+  guide(repo_layout === 'monorepo'
+    ? [
+      'One repo holds all the code; the contract lives in the hub and stories tag this single repo.',
+      codebase === 'greenfield' ? 'Greenfield: no code yet — the repomix code-pack step is skipped.' : 'Brownfield: the repo is packed so the front phases see what already exists.',
+    ]
+    : [
+      'Register each code repo the feature touches; stories get tagged with the repos that implement them.',
+      'Per repo: name → path (inside this project) → platform → domain owner(s).',
+      codebase === 'greenfield' ? 'Greenfield: no code yet — the repomix code-pack step is skipped.' : 'Brownfield: each repo is packed so the front phases see what already exists.',
+    ]);
   const regPath = path.join(root, PROJECT_FILES.reposRegistry);
   const registry = readJSON(regPath, { repos: [] });
   const known = new Set(registry.repos.map((r) => r.name));
+  const greenfield = codebase === 'greenfield';
+  const mono = repo_layout === 'monorepo';
   if (await askYesNo(`Connect a code repo? ${c.dim(`(${registry.repos.length} already registered)`)}`, registry.repos.length === 0)) {
     for (;;) {
       const name = await ask('  repo name (blank to finish)', '');
@@ -463,26 +583,28 @@ export async function runSetup(root, opts = {}) {
       if (!insideRoot(root, rpath)) { warn(`${rpath} resolves outside the project root — skipped`); continue; }
       const detected = run('git', ['remote', 'get-url', 'origin'], { cwd: path.resolve(root, rpath) });
       const platform = (await ask('    platform (github/gitlab)', detectPlatform(detected.ok ? detected.stdout : '') || 'github')).toLowerCase();
-      // A repo can have one or more domain owners; reviewers/owners can also be scoped to it. Names
-      // refer to roster `name`s; each grant is written into that person's per-scope roles map.
-      const domain_owners = parseList(await ask('    domain owner(s) (yad names, space-separated)', ''));
-      const repoReviewers = parseList(await ask('    repo reviewer(s) (yad names, space-separated; blank to skip)', ''));
-      const repoOwners = parseList(await ask('    repo owner(s) (yad names, space-separated; blank to skip)', ''));
+      // Domain owners route the per-repo review. Solo (no roster) and monorepo (one repo = one owner)
+      // skip these prompts — there is no second person to route to.
+      const domain_owners = solo || mono ? [] : parseList(await ask('    domain owner(s) (yad names, space-separated)', ''));
+      const repoReviewers = solo || mono ? [] : parseList(await ask('    repo reviewer(s) (yad names, space-separated; blank to skip)', ''));
+      const repoOwners = solo || mono ? [] : parseList(await ask('    repo owner(s) (yad names, space-separated; blank to skip)', ''));
       const default_branch = await ask('    default branch', 'main');
-      const repo = registerRepo(root, registry, { name, rpath, platform, domain_owners, default_branch, today: opts.today ?? null });
+      const repo = registerRepo(root, registry, { name, rpath, platform, domain_owners, default_branch, today: opts.today ?? null, pack: !greenfield });
       if (!repo) continue;
       addRepoRoles(root, name, { 'domain-owner': domain_owners, reviewer: repoReviewers, owner: repoOwners });
       known.add(name);
       ok(`registered ${name}`);
-      packRepo(root, repo);
+      if (greenfield) info(`${name}: greenfield — skipped repomix pack (run \`yad repo refresh ${name}\` once it has code)`);
+      else packRepo(root, repo);
+      if (mono) { info('monorepo — one repo connected; stop here'); break; }
     }
   }
 
-  // 7b. Assign/update roles for ALREADY-connected repos. The connect loop above only prompts for the
-  // repos you add now; this closes the gap so a member's domain-owner/reviewer/owner role on a repo
-  // connected in an earlier run can be set without reconnecting. Mirrors `yad roster` (repo-driven).
+  // Assign/update roles for ALREADY-connected repos. Skipped in solo mode (no roster). The connect loop
+  // above only prompts for repos you add now; this closes the gap so a member's role on a repo connected
+  // in an earlier run can be set without reconnecting. Mirrors `yad roster` (repo-driven).
   const hub7 = readJSON(hubPath, null);
-  if (registry.repos.length && hub7 && Array.isArray(hub7.roster) && hub7.roster.length
+  if (!solo && registry.repos.length && hub7 && Array.isArray(hub7.roster) && hub7.roster.length
       && await askYesNo('Assign/update roles for connected repos?', false)) {
     for (const member of hub7.roster) {
       if (!(await askYesNo(`  edit ${member.name}'s repo roles?`, false))) continue;
@@ -496,8 +618,9 @@ export async function runSetup(root, opts = {}) {
     }
   }
 
-  // 8. Wire each connected repo + the hub itself
-  step(8, total, 'Wire connected repos + the hub (CI gates, PR template, comment scaffold, gate-sync)');
+  // Wire each connected repo + the hub itself
+  S('Wire connected repos + the hub (CI gates, PR template, comment scaffold, gate-sync)');
+  guide(['Installs the CI safety gates, PR/MR template, and gate-sync — automatic, no input needed.']);
   if (registry.repos.length === 0) info('no repos to wire');
   for (const repo of registry.repos) {
     log(`  ${c.bold(repo.name)} ${c.dim(`(${repo.platform})`)}`);
@@ -516,8 +639,9 @@ export async function runSetup(root, opts = {}) {
   // author allowlists for the verified-commits gate (hub + every repo), from the roster emails
   applyActions(authorsActions(root, registry.repos), { force: true });
 
-  // 9. Optional CodeRabbit
-  step(9, total, 'AI review (CodeRabbit)');
+  // Optional CodeRabbit
+  S('AI review (CodeRabbit)');
+  guide(['Advisory AI first-pass on PRs — never the authority. Opt in per repo; safe to skip.']);
   for (const repo of registry.repos) {
     const cr = path.join(path.resolve(root, repo.path), '.coderabbit.yaml');
     if (exists(cr)) { info(`${repo.name}: .coderabbit.yaml present`); continue; }
@@ -527,13 +651,25 @@ export async function runSetup(root, opts = {}) {
     }
   }
 
-  // 10. Summary + version stamp
-  step(10, total, 'Done');
+  // Summary + version stamp
+  S('Done');
   writeJSON(path.join(root, PROJECT_FILES.version), { version: VERSION, ideTargets, updatedAt: opts.today ?? null });
   ok(`stamped ${PROJECT_FILES.version} (v${VERSION})`);
   log('');
-  log(c.bold('Next — AI-only steps (run in Claude Code):'));
-  hand('generate code-maps: run `yad-connect-repos` for each connected repo');
+  // Tailored fastest path to the first epic, by profile.
+  log(c.bold('Next:'));
+  if (codebase === 'brownfield' && registry.repos.length) {
+    hand('capture what already exists first: run `yad-backfill`, then your first epic with `yad-epic`');
+  } else {
+    hand('author your first epic: run `yad-epic`');
+  }
+  hand('your single next action, anytime: `yad next`');
+  if (!solo && !(readJSON(hubPath, null)?.roster || []).length) {
+    hand('add reviewers when ready: `yad roster add <login>` (an owner + 1 reviewer passes a gate)');
+  }
+  log('');
+  log(c.bold('Then — AI-only steps (run in Claude Code):'));
+  if (registry.repos.length) hand('generate code-maps: run `yad-connect-repos` for each connected repo');
   const design = readJSON(designPath, null);
   if (design && design.tool && design.tool !== 'none') {
     hand(`confirm the design tool: run \`yad-connect-design\` to detect the ${design.tool} MCP (or it degrades to markdown-only)`);
@@ -546,7 +682,6 @@ export async function runSetup(root, opts = {}) {
   if (learning && learning.tool && learning.tool !== 'none') {
     hand(`confirm the learning tool: run \`yad-connect-learning\` to detect the ${learning.tool} CLI (or it degrades to harness-native)`);
   }
-  hand('author your first epic: run `yad-epic`');
   log('');
   log(c.dim('Re-run anytime: `yad check` (report) / `yad check --fix` (reconcile).'));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yadflow",
-  "version": "2.12.0",
+  "version": "2.14.0",
   "description": "Yadflow — the gated, team, multi-repo SDLC: author → review → build with a PR-driven review gate and a zero-dependency `yad` CLI (setup, gate, commit, open-pr, ship, repo). A BMAD module + 30 yad-* skills.",
   "type": "module",
   "author": "AbdelRahman Nasr",

package/skills/sdlc/config.yaml

@@ -31,6 +31,14 @@ defaults:
 # Team review gate defaults (build plan §3 piece 2, §4).
 review_gate:
   default_reviewers: 1          # non-owner reviewers required (in addition to 1 owner) => owner + 1 reviewer
+  # Solo mode (a lone developer): a relaxed, opt-in safety guarantee, recorded per-project in
+  # .sdlc/hub.json (`solo: true`). On GitHub you CANNOT approve your own PR, so requiring an approval
+  # would deadlock a solo user. Solo waives the APPROVAL requirement only — the review PR/MR and its
+  # MERGE stay (CI still runs on the PR, and the merge is what advances the step). Net: the gate passes
+  # on `merged + all comment threads resolved`, no approval needed. NOT a default; team gates are
+  # unchanged. (Branch protection must not "require approvals", or the solo dev's own merge is blocked —
+  # `yad doctor` warns when it does.)
+  solo: false
   escalate_when: [contract, auth, payments]   # escalate to domain owners
   # PR-driven automation (the `yad gate` CLI). With a hub platform, the review rides the per-step
   # PR/MR: `yad gate sync` maps platform reviews/threads into the file ledger and the step

package/skills/yad-analysis/SKILL.md

@@ -26,9 +26,12 @@ engine (never typed by hand); front steps are locked to `human_approve`.
 ## On Activation
 
 ### Step 1 — Get the idea
-Ask the user for a one-line feature idea if not provided. If `.sdlc/state.json` already exists for the
-target epic, analysis was already seeded (or the epic is past it) — stop and point the user at
-`yad-status`. The entry point seeds state exactly once.
+Ask the user for a one-line feature idea if not provided.
+
+**Precondition gate (rail):** analysis is the optional first entry point and seeds state exactly once.
+If `.sdlc/state.json` already exists for the target epic, run `yad next EP-<slug> --check analysis`; if it
+exits non-zero, **STOP** and point the user at `yad next EP-<slug>` (the epic is past analysis). If it
+exits zero, resume analysis for that epic. When no `state.json` exists yet, proceed and seed state.
 
 ### Step 2 — Shape the idea (assist: analyst)
 Adopt the **analyst** lens (`bmad-agent-analyst`, Mary) to pressure-test the idea in depth: who is the

package/skills/yad-architecture/SKILL.md

@@ -23,9 +23,14 @@ shared cross-repo surface at charter altitude; front steps stay locked to `human
 ## On Activation
 
 ### Step 1 — Resolve the epic and check the gate
-Resolve the `EP-<slug>` (ask if not provided). Read `{project-root}/epics/EP-<slug>/.sdlc/state.json`.
-Only proceed when `currentStep == "architecture"` and that step's `status == "in_progress"` (the epic
-review must already have passed). If not, stop and point the user at `yad-status` / the gate.
+Resolve the `EP-<slug>` (ask if not provided).
+
+**Precondition gate (rail):** run `yad next EP-<slug> --check architecture` first. If it exits non-zero,
+**STOP** — surface the blocker it prints and point the user at `yad next EP-<slug>`. Do not author until
+it passes. (The check is the authoritative rail; the description below explains what it enforces.)
+
+This passes when `architecture` is the next runnable step per the state sequence — every prior step
+(through the epic review) is `done` and `architecture` is not already `done`.
 
 ### Step 1b — Open the authoring branch
 Open the architecture authoring branch `architecture/EP-<slug>` per the shared procedure

package/skills/yad-docs-overview/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yad-docs-overview
-description: 'Generates the project-level SDLC-overview interactive site — the same React/Vite/Tailwind shell as the per-epic docs — showing every yadflow stage from setup → ship: the pipeline as a flow canvas, each skill/gate as a flow step, the durable .sdlc state objects as system components, and the lenses as stakeholder roles. Themed with yadflow''s own brand palette for continuity, built from config.yaml + module-help.csv + the overview diagram. Folds the legacy hand-maintained docs/index.html report into the site as report.html (linked from the nav) and deploys via `yad docs deploy --overview`. This is project documentation, not a gated state — it never touches any epic''s state or approvals. Use when the user says "generate the overview site", "build the SDLC overview docs", or after the pipeline (module-help.csv / config.yaml / skill count) changes.'
+description: 'Generates the project-level SDLC-overview interactive site — the same React/Vite/Tailwind shell as the per-epic docs — showing every yadflow stage from setup → ship: the pipeline as a flow canvas, each skill/gate as a flow step, the durable .sdlc state objects as system components, and the lenses as stakeholder roles. Themed with yadflow''s own brand palette for continuity, built from config.yaml + module-help.csv + the overview diagram. The hand-maintained report is the MAIN documentation at the Pages root (report.html, also served as index.html); the interactive SPA mounts under `app/` and is reached from it (and links back). Deploys via `yad docs deploy --overview`. This is project documentation, not a gated state — it never touches any epic''s state or approvals. Use when the user says "generate the overview site", "build the SDLC overview docs", or after the pipeline (module-help.csv / config.yaml / skill count) changes.'
 ---
 
 # SDLC — Author the Overview Site (project-level, the pipeline as a living map)
@@ -8,8 +8,10 @@ description: 'Generates the project-level SDLC-overview interactive site — the
 **Goal:** Render the **whole yadflow pipeline** — every stage from setup → ship — as an interactive site,
 reusing the same shell as the per-epic docs (`skills/yad-docs/templates/app/`). Where `yad-docs`
 animates one epic's flows, this animates the **workflow itself**: the front gates, the build half, the
-automation dial, the setup connectors. It is the regenerable successor to the hand-maintained
-overview report, which is folded into this site as `public/report.html`.
+automation dial, the setup connectors. The hand-maintained overview report stays the **main
+documentation at the Pages root** (`<base>/`, served from `public/report.html` and `public/index.html`);
+this interactive SPA mounts under `<base>/app/` and is reached from the report — the report links
+forward to `app/`, the app links back to the report root.
 
 This is **project documentation, not a gated state** — there is no epic, no `state.json`, no approvals.
 It only reads the pipeline definition and writes a project-level site. When a docs target is connected
@@ -70,7 +72,8 @@ determinism rules as `yad-docs`: stable-ID sort by skill pipeline order / phase,
 timestamps in the data files), theme the `:root` of `index.css` from **yadflow's brand palette** — the
 the legacy report's `:root`: `--accent: #2471a3` and the node colors (`--artifact-*`, `--gate-*`,
 `--earns-*`, `--locked-*`, `--sentinel-*`) — and substitute the Vite base from `.sdlc/docs.json`
-`basePath` (the overview sits at the base root, e.g. `/<repo>/`).
+`basePath` **with `app/` appended** (the SPA mounts under `<base>/app/`, e.g. `/<repo>/app/`, so the
+report can own the root). `siteBasePath(docs, { overview: true })` in `cli/docs.mjs` computes this.
 
 ### Step 4 — Write the overview build manifest (the staleness baseline)
 Write `docs/sdlc-site/.docs-build.json` — `yad-docs-sync` compares against it:
@@ -91,13 +94,16 @@ doc-shell upgrade triggers a rebuild). `skillCount` rides along in the manifest
 — it is **not** a separate hash input, since `module-help.csv` already moves whenever the skill set does.
 Not per-epic artifacts/repo heads.
 
-### Step 5 — Fold the legacy report into the site
-Relocate the hand-maintained static report into the generated site as `docs/sdlc-site/public/report.html`
-(Vite copies `public/` verbatim into `dist/`, so it publishes alongside the app at `<base>/report.html`),
-and link it from the app nav (a "Full report" link in `TopNavBar`). The interactive overview becomes the
-primary documentation and the legacy report rides along as its detailed companion — no orphaned
-`docs/index.html` at the repo root. This generalizes the standing rule that feature work hand-updates the
-report: the overview site now **regenerates** instead.
+### Step 5 — The report is the main documentation; the SPA is reached from it
+The hand-maintained static report lives at `docs/sdlc-site/public/report.html` and is the **primary
+documentation at the Pages root**. The deploy (`BUILD_PUBLIC` in `cli/docs.mjs`, mirrored by the Pages CI
+workflow) copies it to **both** `public/index.html` (the landing `<base>/`) and `public/report.html`
+(so the `<base>/report.html` URL keeps working), and copies the built SPA into `public/app/`. Wire the
+two cross-links: the report links **forward** to the interactive map with a relative `app/` href (its
+hero CTA); the app's `TopNavBar` "Full report" link points **back** to the report root
+(`import.meta.env.BASE_URL` with the trailing `app/` stripped). No orphaned `docs/index.html` at the repo
+root. This generalizes the standing rule that feature work hand-updates the report: the overview SPA now
+**regenerates** instead, while the report stays the front door.
 
 ### Step 6 — Build / deploy (`action`)
 - `action: generate` (default) — generate source + manifest; stop.
@@ -106,8 +112,9 @@ report: the overview site now **regenerates** instead.
 
 ### Step 7 — Stop. Report (no gate, no epic)
 Report: the site path (`docs/sdlc-site/`), the data files produced, that the theme is the yadflow brand
-palette, the deploy URL or "build-only", the staleness baseline, and that the legacy report is folded in
-at `public/report.html` (linked from the nav). Never touches any epic state.
+palette, the deploy URL or "build-only", the staleness baseline, and that the report is the main
+documentation at `<base>/` (`public/index.html` + `public/report.html`) with the interactive SPA mounted
+under `<base>/app/` and cross-linked. Never touches any epic state.
 
 ## Hard rules
 

package/skills/yad-epic/SKILL.md

@@ -40,7 +40,10 @@ exists for the idea.
 
 Either mode runs Step 3b (branch), Step 4 (write the epic), and Step 6 (stop at the gate).
 
-If `state.json` exists but `currentStep != "epic"`, stop and point the user at `yad-status` / the gate.
+**Precondition gate (rail):** if `state.json` already exists (analysis-ran or re-entry), run
+`yad next EP-<slug> --check epic` — if it exits non-zero, **STOP** and surface the blocker, pointing the
+user at `yad next EP-<slug>`. When no `state.json` exists yet, this is the greenfield entry point — the
+check is not applicable, so proceed and seed state.
 
 ### Step 2 — Shape the idea (assist: analyst) — or read the analysis
 - **Analysis skipped:** ask the user for a one-line feature idea if not provided, then adopt the

package/skills/yad-stories/SKILL.md

@@ -24,9 +24,14 @@ There is **no `sm` agent** (Phase 0 Deviation 1): the `pm` lens breaks down the
 ## On Activation
 
 ### Step 1 — Resolve the epic and check the gate
-Resolve the `EP-<slug>` (ask if not provided). Read `.sdlc/state.json`. Only proceed when
-`currentStep == "stories"` and that step's `status == "in_progress"` (the UI review must already have
-passed). If not, stop and point the user at `yad-status` / the gate.
+Resolve the `EP-<slug>` (ask if not provided).
+
+**Precondition gate (rail):** run `yad next EP-<slug> --check stories` first. If it exits non-zero,
+**STOP** — surface the blocker it prints and point the user at `yad next EP-<slug>`. Do not author until
+it passes.
+
+This passes when `stories` is the next runnable step per the state sequence — every prior step
+(through the UI review) is `done` and `stories` is not already `done`.
 
 ### Step 1b — Open the authoring branch
 Open the stories authoring branch `stories/EP-<slug>` per the shared procedure

package/skills/yad-test-cases/SKILL.md

@@ -36,11 +36,16 @@ the Markdown artifact only — the testing tool is additive, exactly like the de
 ## On Activation
 
 ### Step 1 — Resolve the epic and check the track
-Resolve the `EP-<slug>` (ask if not provided). Read `.sdlc/state.json`. Only proceed when the
-**`test-cases` step's `status == "in_progress"`** — it opens when `stories-review` passes (the epic is
-already `ready-for-build` by then; `currentStep` stays there because this is a parallel track, so do
-**not** gate on `currentStep`). If `test-cases` is still `blocked`, the stories review has not passed —
-stop and point the user at `yad-status` / the gate.
+Resolve the `EP-<slug>` (ask if not provided).
+
+**Precondition gate (rail):** run `yad next EP-<slug> --check test-cases` first. If it exits non-zero,
+**STOP** — surface the blocker it prints and point the user at `yad next EP-<slug>`. Do not author until
+it passes. The check is track-aware: it keys off the `test-cases` step's predecessors, **not**
+`currentStep` (this is a parallel track — `currentStep` stays at `ready-for-build`).
+
+This passes once the `test-cases` step is runnable — its predecessor `stories-review` is `done` (so the
+step has opened to `in_progress`) and `test-cases` is not already `done`. While it is still `blocked`,
+the stories review has not passed.
 
 ### Step 1b — Open the authoring branch
 Open the test-cases authoring branch `test-cases/EP-<slug>` per the shared procedure