yadflow 2.13.0 → 2.15.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.13.0",
+  "version": "2.15.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-checks/SKILL.md

@@ -38,6 +38,13 @@ and GitLab CI. This step is **by hand** in Phase 3 — run the gates with the sk
 - Canonical gate sources live in this skill's `templates/` (the source of truth that gets installed
   into each code repo):
   - `templates/checks/{spec-link,contract-check,build-test-lint,verified-commits}.sh`
+  - `templates/checks/ledger-guard.sh` → **hub-only** gate, active **only in bridge mode** (a no-op
+    when humans legitimately own the ledger). On review PRs it FAILs any commit that touches the
+    CI-owned gate ledger (`.sdlc/{state,approvals,comments,hub-prs}.json`, `reviews/*.md`) unless it
+    is a **verified gate-bot commit** — bot-authored AND platform-Verified, since author text alone is
+    spoofable. `.sdlc/contract-lock.json` is artifact-side and exempt. Runs in `yad-hub-checks`
+    alongside `verified-commits` (which waives the allowlist for the bot but still requires its
+    signature). See `yad-hub-bridge`.
   - `templates/github/yad-verified-commits.yml` + `templates/gitlab/yad-verified-commits.gitlab-ci.yml`
     → the standalone hub-side verified-commits CI (installed by `yad check --fix` with the hub wiring)
   - `templates/github/yad-checks.yml` → installs to `.github/workflows/yad-checks.yml` (marked `# yad-managed: yad-checks`)

package/skills/yad-checks/templates/checks/ledger-guard.sh

@@ -0,0 +1,117 @@
+#!/usr/bin/env bash
+# ledger-guard gate.
+# In BRIDGE mode the gate ledger is CI-owned: only the yad gate-sync bot may change the
+# machine-written gate-state files. A commit on a review PR by anyone else that modifies them is
+# rejected — the human keeps the artifact, CI keeps the ledger. This makes "CI is the sole writer of
+# the ledger" a mechanical guarantee instead of a convention.
+#
+# Protected (gate-state, machine-written):
+#   epics/*/.sdlc/state.json, approvals.json, comments.json, hub-prs.json
+#   epics/*/reviews/*.md
+# NOT protected:
+#   epics/*/.sdlc/contract-lock.json — artifact-side: the architect locks the contract surface in
+#   `gate open`, so a human legitimately commits it alongside the architecture artifact.
+#
+# A "bot commit" must be BOTH authored by the gate bot (name/email contains yad-gate-sync) AND
+# platform-VERIFIED — author/committer text alone is user-controlled and spoofable, so the platform
+# Verified signature (a key the contributor cannot forge under the bot identity) is what actually
+# distinguishes CI-generated commits. A spoofed-author commit that is not Verified is treated as a
+# human edit and rejected.
+#
+# Scope: enforced ONLY when the bridge is enabled (a platform + gate-sync CI). Without the bridge
+# (file-only / non-bridge) humans legitimately write the ledger locally, so the gate is a no-op.
+#
+# Degradation: a base ref that cannot be resolved FAILs closed; no platform (cannot read the Verified
+# badge) WARNs and waives the signature half — the same stance verified-commits takes.
+set -euo pipefail
+
+# ---- bridge gate: only CI-owned ledgers are guarded -------------------------------------------
+HUB="${SDLC_HUB_CONFIG:-.sdlc/hub.json}"
+if [ ! -f "$HUB" ] || ! grep -Eq '"(bridge_enabled|bridge)"[[:space:]]*:[[:space:]]*true' "$HUB"; then
+  echo "PASS [ledger-guard]: bridge not enabled — the ledger is locally owned, nothing to guard."
+  exit 0
+fi
+
+BASE="${1:-${SDLC_BASE:-origin/main}}"
+if ! git rev-parse --verify --quiet "${BASE}^{commit}" >/dev/null; then
+  echo "FAIL [ledger-guard]: base ref '${BASE}' not found — fetch full history / check the base branch."
+  exit 1
+fi
+RANGE="${BASE}..HEAD"
+
+commits="$(git rev-list "$RANGE")"
+if [ -z "$commits" ]; then
+  echo "PASS [ledger-guard]: no commits in ${RANGE}"
+  exit 0
+fi
+
+# ---- platform for the signature check (mirrors verified-commits) ------------------------------
+remote="$(git remote get-url origin 2>/dev/null || true)"
+platform=""
+case "$remote" in
+  *github*) platform=github ;;
+  *gitlab*) platform=gitlab ;;
+esac
+platform="${SDLC_PLATFORM:-$platform}"
+case "$platform" in
+  github|gitlab) ;;
+  ""|none) platform=""; echo "WARN [ledger-guard]: no GitHub/GitLab remote — bot signature NOT verified (the Verified badge is a platform concept)." ;;
+  *) echo "FAIL [ledger-guard]: unknown platform '${platform}' (SDLC_PLATFORM must be github|gitlab|none)."; exit 1 ;;
+esac
+
+# 0 when the platform marks the commit's signature verified.
+signature_verified() {
+  local sha v body
+  sha="$1"
+  case "$platform" in
+    github)
+      v="$(gh api "repos/{owner}/{repo}/commits/${sha}" --jq '.commit.verification.verified' 2>/dev/null || echo api-error)"
+      [ "$v" = "true" ]
+      ;;
+    gitlab)
+      if [ -n "${CI_API_V4_URL:-}" ] && [ -n "${CI_PROJECT_ID:-}" ]; then
+        body="$(curl -fsS --header "PRIVATE-TOKEN: ${GITLAB_TOKEN:-${SDLC_API_TOKEN:-}}" \
+          "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/repository/commits/${sha}/signature" 2>/dev/null || true)"
+      else
+        body="$(glab api "projects/:id/repository/commits/${sha}/signature" 2>/dev/null || true)"
+      fi
+      printf '%s' "$body" | grep -qE '"verification_status"[[:space:]]*:[[:space:]]*"verified"'
+      ;;
+    *) return 1 ;;
+  esac
+}
+
+# A trusted bot commit = bot-attributed AND (platform-Verified, or no platform to check against).
+trusted_bot() {
+  case "$(git show -s --format='%an|%ae' "$1")" in
+    *yad-gate-sync*) ;;
+    *) return 1 ;;
+  esac
+  [ -z "$platform" ] && return 0          # degraded: cannot read the Verified badge — waive (warned above)
+  signature_verified "$1"
+}
+
+violations=0
+for sha in $commits; do
+  touches_ledger=0
+  while IFS= read -r f; do
+    [ -n "$f" ] || continue
+    case "$f" in
+      epics/*/.sdlc/contract-lock.json) ;; # artifact-side — allowed
+      epics/*/.sdlc/state.json|epics/*/.sdlc/approvals.json|epics/*/.sdlc/comments.json|epics/*/.sdlc/hub-prs.json|epics/*/reviews/*.md)
+        touches_ledger=1
+        echo "  ${sha} (author $(git show -s --format='%an' "$sha")) → $f"
+        ;;
+    esac
+  done < <(git diff-tree --no-commit-id --name-only -r "$sha")
+  if [ "$touches_ledger" = 1 ] && ! trusted_bot "$sha"; then
+    violations=$((violations + 1))
+  fi
+done
+
+if [ "$violations" -gt 0 ]; then
+  echo "FAIL [ledger-guard]: ${violations} commit(s) change CI-owned gate files without a verified gate-bot signature. The ledger is CI-owned — let CI sync the gate; do not commit .sdlc/*.json or reviews/*.md yourself."
+  exit 1
+fi
+echo "PASS [ledger-guard]: every CI-owned gate change in ${RANGE} is a verified gate-bot commit."
+exit 0

package/skills/yad-checks/templates/checks/verified-commits.sh

@@ -93,8 +93,14 @@ while IFS= read -r sha; do
   [ -z "$sha" ] && continue
   short="$(git log -1 --format=%h "$sha")"
   author="$(git log -1 --format=%ae "$sha" | tr '[:upper:]' '[:lower:]')"
+  # The gate-sync bot is a machine identity, not a roster human — waive the allowlist for it. Its
+  # commits are still held to the SIGNATURE check below, so a contributor cannot spoof the bot author
+  # to dodge the allowlist (a forged-author commit is not platform-Verified). Mirrors how the
+  # platform-committer merge commits are allowlist-exempt but signature-covered.
+  is_bot=0
+  case "${author}|$(git log -1 --format=%an "$sha" | tr '[:upper:]' '[:lower:]')" in *yad-gate-sync*) is_bot=1 ;; esac
 
-  if [ "$authors_on" = 1 ]; then
+  if [ "$authors_on" = 1 ] && [ "$is_bot" = 0 ]; then
     # tolerate CRLF / stray surrounding whitespace in a hand-edited allowlist
     if grep -vE '^[[:space:]]*(#|$)' "$ALLOWLIST" | tr -d '\r' | sed 's/^[[:space:]]*//;s/[[:space:]]*$//' \
         | tr '[:upper:]' '[:lower:]' | grep -qxF "$author"; then
@@ -103,6 +109,8 @@ while IFS= read -r sha; do
       echo "FAIL [verified-commits]: ${short} author <${author}> is not in ${ALLOWLIST} — unverified user."
       rc=1
     fi
+  elif [ "$is_bot" = 1 ]; then
+    echo "PASS [verified-commits]: ${short} gate-sync bot — allowlist waived (signature still required)"
   fi
 
   if [ -n "$platform" ]; then