yadflow 2.13.0 → 2.15.0

package/CHANGELOG.md

@@ -1,9 +1,9 @@
-# [2.13.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.12.0...v2.13.0) (2026-06-16)
+# [2.15.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.14.0...v2.15.0) (2026-06-24)
 
 
 ### Features
 
-* **docs:** make the report the main documentation, mount the SPA under /app/ ([#71](https://github.com/abdelrahmannasr/yadflow/issues/71)) ([1993e4d](https://github.com/abdelrahmannasr/yadflow/commit/1993e4dc282df281474ca1923acd52dbd1262dcb))
+* merge-driven review gate (Path B) — CI never pushes the review branch ([#78](https://github.com/abdelrahmannasr/yadflow/issues/78)) ([d4d983a](https://github.com/abdelrahmannasr/yadflow/commit/d4d983ab4efddb4e6ec259bb940b393e9237f9cf)), closes [#76](https://github.com/abdelrahmannasr/yadflow/issues/76)
 
 # [2.2.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.1.0...v2.2.0) (2026-06-14)
 

package/README.md

@@ -85,7 +85,8 @@ with `npx` from your **product hub** repo — no clone needed.
 
 | Command | What it does |
 |---------|--------------|
-| `npx yadflow setup` | Guided first-run wizard (the steps below). |
+| `npx yadflow setup` | Guided first-run wizard — a short **profile interview** (solo/team, greenfield/brownfield, monorepo/separate) then the branched steps below. Pre-answer for CI/scripts with `--solo`/`--team <n>`, `--greenfield`/`--brownfield`, `--monorepo`/`--separate`, `--tools`. |
+| `yad next [<epic>]` | **Where am I / what next.** With no epic: project-wide orientation — the one next action (run setup, start an epic, or the single active epic's step). With an epic: that epic's exact next action (a skill to invoke or a `yad` command to run). `yad next <epic> --check <step>` exits non-zero when a step is run out of order (the precondition guard); `yad next --all` lists every epic's next action. |
 | `npx yadflow check` | Read-only report: what is **missing** / **outdated** (drifted) / **stale** (code-context) / **legacy** (pre-2.0 `sdlc-*` names) vs the bundled manifest. |
 | `npx yadflow check --fix` | Reconcile: fill what is missing **and** update what changed — touches nothing already correct. |
 | `npx yadflow update` | Apply drift only (alias for `check --fix --scope=changed`). Also migrates a pre-2.0 install in place: `sdlc-*` skill copies and marker-owned `sdlc-*.yml` CI files are replaced by their `yad-*` names (a same-named file *you* authored is never touched). |
@@ -120,6 +121,13 @@ The merge click is the human approval act, so front steps still never `machine_a
 **revoked when the reviewed artifact actually changes** (re-hash), giving reviewers a fresh pass. With no
 hub platform / no `gh`/`glab`, the gate degrades to file-only with no error.
 
+**Solo mode.** A lone developer can't approve their own PR on GitHub, so an approval requirement would
+deadlock them. Opt in (`yad setup --solo`, recorded as `solo: true` in `.sdlc/hub.json`) and the gate
+**waives the approval requirement only** — the review PR/MR and its merge stay, so CI still runs on the
+PR and the **merge** advances the step. Net: the gate passes on *merged + all threads resolved*. It's a
+documented, reversible relaxation; `yad doctor` warns if branch protection still "requires approvals"
+(which would block the solo dev's own merge).
+
 **Event-driven sync.** Wire the hub once (`yad check --fix` installs `.github/workflows/yad-gate-sync.yml`,
 or the GitLab fragment + schedule) and every **approval, change request, and merge** on a review PR/MR
 triggers `yad gate ci` in the hub's own CI: the ledger updates land directly on the hub's default branch
@@ -132,29 +140,33 @@ a manual `yad gate sync` racing CI, or GitLab pipelines — two simultaneous syn
 *commits* via the rebase retry but each works from the state it read at start, so the rarer of two
 simultaneous advancements can be lost; the next event or scheduled sweep re-syncs and converges.
 
-### What `setup` walks you through (10 steps)
+### What `setup` walks you through (a guided, branching interview)
+
+Setup opens with a short **profile interview** — *solo or team (how many)? greenfield or brownfield?
+monorepo or separate repos?* — and the answers (recorded in `.sdlc/hub.json` as `solo` + `profile`)
+branch the rest so you only answer what your situation needs. Each step prints inline guidance (what it
+does / why / what to enter / what skipping means), and the step count adapts.
 
+0. **Profile** — the three questions above, plus "configure optional tools now?". Pre-answer for
+   CI/scripts with `--solo`/`--team <n>`, `--greenfield`/`--brownfield`, `--monorepo`/`--separate`, `--tools`.
 1. **Preflight** — confirm the hub is a git repo (offers `git init`); check `git`/`node`/`npx`.
 2. **Install the module** — copy all 30 `yad-*` skills into the IDE skill dirs you pick
    (`.claude/`, `.agents/`, `.zencoder/`, `.opencode/`) and register `_bmad/sdlc/`.
 3. **Hub platform & roster** — detect GitHub/GitLab from the remote; record reviewers → `.sdlc/hub.json`.
-   Edit the roster any time afterwards with `yad roster` (no need to re-run the whole wizard).
-4. **Connect a design tool** — record the design tool (Figma / pencil / none) → `.sdlc/design.json` so
-   the UI step can materialize the design; the MCP itself is confirmed later by `yad-connect-design`.
-5. **Connect a testing tool** — record the testing tool (Playwright / cypress / pytest / none) →
-   `.sdlc/testing.json` so the test-cases step can implement the automation; the MCP itself is confirmed
-   later by `yad-connect-testing`.
-6. **Connect a learning tool** — record the learning tool (DeepTutor / none) → `.sdlc/learning.json` so
-   the learning layer can tutor the team; the CLI + knowledge base are confirmed later by
-   `yad-connect-learning`.
-7. **Connect code repos** — register each repo into `.sdlc/repos.json` and cache a Repomix pack.
-8. **Wire each repo** — CI gates, PR/MR template, and review-comment scaffold.
-9. **AI review** — optionally write `.coderabbit.yaml`.
-10. **Done** — stamp `.sdlc/cli-version.json` and hand off the AI-only steps (code-maps; first epic).
+   **Solo skips the roster** (you review by merging your own PR). Edit the roster any time with `yad roster`.
+4. **Optional tools** — design (Figma/pencil), testing (Playwright/cypress/pytest), learning (DeepTutor).
+   Configure now, or **defer with one prompt** → all recorded as `none` (connect later with the
+   `yad-connect-*` skills; the MCPs/CLIs are confirmed there).
+5. **Connect code repos** — register repos into `.sdlc/repos.json`. **Monorepo** connects one repo and
+   skips domain-owner prompts; **greenfield** skips the Repomix pack (run `yad repo refresh` once it has code).
+6. **Wire each repo** — CI gates, PR/MR template, and review-comment scaffold.
+7. **AI review** — optionally write `.coderabbit.yaml`.
+8. **Done** — stamp `.sdlc/cli-version.json` and print a **profile-tailored next step** (brownfield →
+   `yad-backfill` first; everyone → `yad next` and your first epic via `yad-epic`).
 
 The deterministic file work runs automatically; the AI-only steps are handed to the Claude Code skills
 with a printed next-action. Re-run `… check --fix` any time the workflow updates — it never re-asks for
-input you already gave.
+input you already gave; re-running `setup` carries your profile forward.
 
 **Releases:** automated via semantic-release on merge to `main` (Conventional Commits → npm, with
 provenance). See [`RELEASING.md`](RELEASING.md).

package/bin/yad.mjs

@@ -13,17 +13,23 @@ import { runRepo } from '../cli/repo.mjs';
 import { runRoster } from '../cli/roster.mjs';
 import { runDocs } from '../cli/docs.mjs';
 import { runDoctor } from '../cli/doctor.mjs';
+import { runNext } from '../cli/next.mjs';
+import { syncStatuses } from '../cli/artifact-status.mjs';
 
 const HELP = `${c.bold('yad')} — setup, review-gate & build helpers for the SDLC Workflow module  ${c.dim('v' + VERSION)}
 
 ${c.bold('Setup & maintenance')}
-  yad setup            Guided first-run setup (install module, connect & wire repos)
+  yad setup            Guided first-run setup (profile interview, install, connect & wire repos)
+                       profile flags: --solo | --team <n>, --greenfield | --brownfield,
+                       --monorepo | --separate, --tools (configure design/testing/learning now)
   yad check            Report what is missing / drifted / stale / legacy (read-only)
   yad check --fix      Reconcile: fill what is missing, update what changed
   yad update           Apply drift only (alias for: check --fix --scope=changed);
                        also migrates pre-2.0 sdlc-* installs to the yad-* names
   yad doctor [--json]  Environment + state health: tools/auth, config files,
                        repo paths, epic ledgers (exit 1 on any failure)
+  yad sync-status [epic]   Update artifact frontmatter status (draft/in-review/approved)
+                       from .sdlc/state.json — all epics if omitted (--dry-run to preview)
 
 ${c.bold('Reviewer roster')}
   yad roster list                      Show every member + their roles per scope (hub + each repo)
@@ -33,14 +39,20 @@ ${c.bold('Reviewer roster')}
   yad roster revoke <name> <repo> <role...>  Remove role(s) for a repo
   yad roster remove <login>            Delete a member from the roster
 
+${c.bold('Where am I / what next')}
+  yad next                             Project-wide: the one next action to take (or run setup)
+  yad next <epic>                      The single next action for one epic (skill or yad command)
+  yad next <epic> --check <step>       Exit 0 if <step> is runnable now, else 1 (precondition guard)
+  yad next --all                       Every active epic's next action at once
+
 ${c.bold('Review gate (front half)')}
   yad gate open <epic> <artifact>      Open the review PR/MR; mark the step in_review
   yad gate sync <epic> [artifact]      Pull PR state -> ledger; advance on approved+resolved+merged
   yad gate comments <epic> [artifact]  Fetch unresolved review comments to address
   yad gate status <epic>               Show each review step + approvals
-  yad gate ci [--branch <head>] [--pr <n>]
-                        CI entry (hub workflow): derive epic/artifact from the review branch,
-                        sync, commit the ledger to the default branch (sweep all PRs if no --branch)
+  yad gate ci [--branch <head>] [--pr <n>] [--merged]
+                        CI entry (hub workflow): pre-merge is read-only (nothing pushed);
+                        --merged advances the step + flips artifact status on the default branch
 
 ${c.bold('Build helpers')}
   yad commit --type <t> -m <subject>   Commit by convention (trailers, atomic guard)
@@ -71,11 +83,12 @@ ${c.bold('Options')}
   --force               commit: bypass the atomic-file guard / re-copy unchanged files
   --branch <head>       gate ci: the review PR/MR head branch (review/EP-<slug>/<artifact>)
   --pr <n>              gate ci: the PR/MR number from the CI event
+  --merged              gate ci: merge phase — advance the step on the default branch
   --no-push             gate ci: commit the ledger but do not push
   -h, --help            Show this help
   -v, --version         Print version`;
 
-const VALUE_FLAGS = new Set(['--dir', '--type', '--message', '--task', '--ai', '--risk', '--repo', '--platform', '--base', '--title', '--scope', '--branch', '--pr', '--epic', '--name', '--email', '--roles']);
+const VALUE_FLAGS = new Set(['--dir', '--type', '--message', '--task', '--ai', '--risk', '--repo', '--platform', '--base', '--title', '--scope', '--branch', '--pr', '--epic', '--name', '--email', '--roles', '--team']);
 
 function parseArgs(argv) {
   const o = { _: [], dir: process.cwd(), fix: false, force: false, scope: 'all' };
@@ -85,8 +98,21 @@ function parseArgs(argv) {
     else if (a === '--force') o.force = true;
     else if (a === '--contract-change') o.contractChange = true;
     else if (a === '--no-push') o.noPush = true;
+    else if (a === '--merged') o.merged = true;
     else if (a === '--overview') o.overview = true;
-    else if (a === '--check') o.check = true;
+    // `--check` is a bare boolean for `docs sync --check`, but takes a value for
+    // `next <epic> --check <step>`. Only the `next` command consumes the following token as a value —
+    // scoping it to `next` keeps `docs sync --check overview` (and any other command) from swallowing a
+    // positional. `o._[0]` is the command, already pushed by the time `--check` is seen in normal use.
+    else if (a === '--check') { const v = argv[i + 1]; o.check = (o._[0] === 'next' && v !== undefined && !v.startsWith('-')) ? argv[++i] : true; }
+    else if (a === '--all') o.all = true;
+    // setup profile flags (pre-answer the Step 0 interview, for CI/scripts)
+    else if (a === '--solo') o.solo = true;
+    else if (a === '--greenfield') o.greenfield = true;
+    else if (a === '--brownfield') o.brownfield = true;
+    else if (a === '--monorepo') o.monorepo = true;
+    else if (a === '--separate') o.separate = true;
+    else if (a === '--tools') o.tools = true;
     else if (a === '--refresh') o.refresh = true;
     else if (a === '--wire') o.wire = true;
     else if (a === '--dry-run') o.dryRun = true;
@@ -117,7 +143,11 @@ async function main() {
   const today = new Date().toISOString().slice(0, 10);
   switch (cmd) {
     case 'setup':
-      await runSetup(o.dir, { today, force: o.force });
+      await runSetup(o.dir, {
+        today, force: o.force,
+        solo: o.solo, team: o.team, greenfield: o.greenfield, brownfield: o.brownfield,
+        monorepo: o.monorepo, separate: o.separate, tools: o.tools,
+      });
       break;
     case 'check':
       await reconcile(o.dir, { fix: o.fix, scope: o.scope, force: o.force, today });
@@ -128,15 +158,31 @@ async function main() {
     case 'doctor':
       await runDoctor(o.dir, { json: o.json });
       break;
+    case 'sync-status': {
+      const [, epic] = o._;
+      if (epic && !isValidEpicId(epic)) { log(c.red(`invalid epic id: ${epic} (expected EP-<slug>, [a-z0-9-] only)`)); process.exitCode = 1; break; }
+      await syncStatuses(o.dir, { epic, dryRun: o.dryRun });
+      break;
+    }
+    case 'next': {
+      const [, epic] = o._;
+      // `--check` with no step is a malformed guard call — fail loudly rather than silently print.
+      if (o.check === true) { log(c.red('usage: yad next <epic> --check <step>')); process.exitCode = 1; break; }
+      await runNext(o.dir, { epic, check: typeof o.check === 'string' ? o.check : undefined, all: o.all });
+      break;
+    }
     case 'gate': {
       const [, action, epic, artifact] = o._;
       // `gate ci` takes no positionals — epic/artifact come from --branch (or a sweep of all PRs).
-      if (action === 'ci') { await gateCi(o.dir, { branch: o.branch, pr: o.pr, push: !o.noPush, today }); break; }
+      if (action === 'ci') { await gateCi(o.dir, { branch: o.branch, pr: o.pr, merged: o.merged, push: !o.noPush, today }); break; }
       if (!epic) { log(c.red('usage: yad gate <open|sync|comments|status|ci> <epic> [artifact]')); process.exitCode = 1; break; }
       // The epic id becomes a path segment under epics/ — reject anything but EP-<slug> outright.
       if (!isValidEpicId(epic)) { log(c.red(`invalid epic id: ${epic} (expected EP-<slug>, [a-z0-9-] only)`)); process.exitCode = 1; break; }
+      // In bridge mode CI is the sole ledger writer: `open` only opens the PR, and local `sync` is
+      // advisory (reads the platform, prints status, writes nothing). The artifact status flip is
+      // CI's job at merge — never wired into the local gate. File-only mode keeps local writes.
       if (action === 'open') await gateOpen(o.dir, { epic, artifact, today });
-      else if (action === 'sync') await gateSync(o.dir, { epic, artifact, today });
+      else if (action === 'sync') await gateSync(o.dir, { epic, artifact, today, local: true });
       else if (action === 'comments') await gateComments(o.dir, { epic, artifact, today });
       else if (action === 'status') await gateStatus(o.dir, { epic });
       else { log(c.red(`unknown gate action: ${action} (open|sync|comments|status|ci)`)); process.exitCode = 1; }

package/cli/artifact-status.mjs

@@ -0,0 +1,102 @@
+// `yad sync-status [epic]` — reconcile each artifact's frontmatter `status:` with the real
+// source of truth, the per-epic state machine in .sdlc/state.json. The authoring skills hard-code
+// `status: draft` at creation and never update it, so artifacts read as "draft" long after their
+// gate has passed. This derives draft / in-review / approved from the step statuses and rewrites
+// only the `status:` line — advance-only, and never touching build-owned values.
+import fs from 'node:fs';
+import path from 'node:path';
+import { c, log, ok, info, readJSONStrict } from './lib.mjs';
+import { epicRoot, artifactBase, artifactFromBase, findReviewStep } from './epic-state.mjs';
+import { epicFiles } from './manifest.mjs';
+
+// The front-gate lifecycle this command manages. Forward-only: a status is only ever moved UP this
+// ladder, so a re-run never regresses anything.
+const RANK = { draft: 0, 'in-review': 1, approved: 2 };
+
+// Values owned by other parts of the workflow — left untouched. `locked` is the contract surface;
+// `in-build` / `shipped` are set by the build half (engineer-review) per story; `ready-for-build`,
+// `done`, `blocked` are roll-ups/states we must not overwrite from the front-gate view.
+const PRESERVE = new Set(['locked', 'in-build', 'shipped', 'ready-for-build', 'done', 'blocked']);
+
+// The per-epic artifact files this command considers (bases). Story files are handled separately
+// because they live under stories/ and all map to the single stories / stories-review step pair.
+const ARTIFACT_FILES = ['analysis.md', 'epic.md', 'architecture.md', 'contract.md', 'ui-design.md', 'test-cases.md'];
+
+// The desired front-gate status for an artifact base, derived purely from state.json. Returns null
+// when the chain has no steps for this base (nothing to manage) — e.g. contract has no own step.
+export function desiredStatus(state, base) {
+  if (!state?.steps) return null;
+  const review = findReviewStep(state, artifactFromBase(base));
+  const author = state.steps.find((s) => s.type === 'author' && artifactBase(s.artifact) === base);
+  if (!review && !author) return null;
+  if (review?.status === 'done') return 'approved';
+  if (review?.status === 'in_review' || author?.status === 'done') return 'in-review';
+  return 'draft';
+}
+
+// Rewrite ONLY the `status:` line inside the first `---\n...\n---` frontmatter block, preserving
+// everything else. Returns the prior status when a change was written, or null for a no-op (no
+// frontmatter, no status line, preserved value, or not an advance). Mirrors the frontmatter regex
+// in gate.mjs.
+export function setFrontmatterStatus(file, status) {
+  if (!fs.existsSync(file)) return null;
+  const text = fs.readFileSync(file, 'utf8');
+  const fm = text.match(/^---\n([\s\S]*?)\n---/);
+  if (!fm) return null;
+  const cur = (fm[1].match(/^status:\s*(.*)$/m) || [])[1]?.trim();
+  if (cur === undefined) return null;
+  // Advance-only within the managed ladder; anything else (build-owned, roll-ups) is left as-is.
+  if (PRESERVE.has(cur)) return null;
+  if (!(cur in RANK) || !(status in RANK) || RANK[status] <= RANK[cur]) return null;
+  const block = fm[1].replace(/^status:\s*.*$/m, `status: ${status}`);
+  fs.writeFileSync(file, text.replace(fm[1], block));
+  return cur;
+}
+
+// Sweep one epic (or every epic under epics/) and reconcile artifact frontmatter with state.json.
+export async function syncStatuses(root, { epic, dryRun = false } = {}) {
+  const epicsDir = path.join(root, 'epics');
+  const epics = epic
+    ? [epic]
+    : (fs.existsSync(epicsDir) ? fs.readdirSync(epicsDir).filter((e) => fs.statSync(path.join(epicsDir, e)).isDirectory()).sort() : []);
+  if (!epics.length) { info('no epics found — nothing to sync'); return { changed: 0 }; }
+
+  let changed = 0;
+  for (const e of epics) {
+    const dir = epicRoot(root, e);
+    const state = readJSONStrict(epicFiles(dir).state, null);
+    if (!state?.steps) { info(`${e}: no state.json — skipping`); continue; }
+
+    // Single-file artifacts + each story file (all keyed to the stories step pair).
+    const files = ARTIFACT_FILES.map((f) => ({ base: artifactBase(f), file: path.join(dir, f) }));
+    const storiesDir = path.join(dir, 'stories');
+    if (fs.existsSync(storiesDir)) {
+      for (const f of fs.readdirSync(storiesDir).filter((x) => x.endsWith('.md'))) {
+        files.push({ base: 'stories', file: path.join(storiesDir, f) });
+      }
+    }
+
+    for (const { base, file } of files) {
+      if (!fs.existsSync(file)) continue;
+      const want = desiredStatus(state, base);
+      if (!want) continue;
+      if (dryRun) {
+        // Peek without writing so --dry-run reports exactly what would change. Scope the match to the
+        // frontmatter block so a `status:` line in the Markdown body can't be mistaken for the value.
+        const text = fs.readFileSync(file, 'utf8');
+        const fm = text.match(/^---\n([\s\S]*?)\n---/);
+        const cur = (fm?.[1].match(/^status:\s*(.*)$/m) || [])[1]?.trim();
+        if (cur && !PRESERVE.has(cur) && cur in RANK && RANK[want] > RANK[cur]) {
+          log(`  ${c.dim('• would update')} ${path.relative(root, file)}: ${cur} → ${want}`);
+          changed++;
+        }
+        continue;
+      }
+      const prev = setFrontmatterStatus(file, want);
+      if (prev) { ok(`${path.relative(root, file)}: ${prev} → ${want}`); changed++; }
+    }
+  }
+  if (!changed) info(dryRun ? 'no status changes needed' : 'all artifact statuses already in sync');
+  else if (!dryRun) ok(`updated ${changed} artifact status(es)`);
+  return { changed };
+}

package/cli/doctor.mjs

@@ -12,6 +12,12 @@ import { cliFor, validateLogin, hostFromGitUrl } from './platform.mjs';
 
 const MIN_NODE = 18;
 
+// Solo mode (a lone developer): approval waived, merge + resolved threads still gate. Persisted in
+// hub.json. Mirrors gate.mjs / next.mjs.
+const isSolo = (hub) => !!(hub && (hub.solo === true || hub.review_gate?.solo === true));
+// owner/repo slug from a git url (https or ssh), for the branch-protection probe.
+const repoSlug = (url) => ((url || '').match(/[:/]([^/:]+\/[^/]+?)(?:\.git)?$/) || [])[1] || null;
+
 // Each check: { id, section, status: 'ok'|'warn'|'fail', message, hint? }
 function check(checks, id, section, status, message, hint = '') {
   checks.push({ id, section, status, message, ...(hint ? { hint } : {}) });
@@ -65,6 +71,7 @@ export function projectChecks(checks, root) {
     else if (hub.roster !== undefined && !Array.isArray(hub.roster)) check(checks, 'hub', 'project', 'fail', `${PROJECT_FILES.hubConfig}: \`roster\` must be an array [YAD-STATE-002]`, 'fix the file or re-run `yad setup`');
     else {
       check(checks, 'hub', 'project', 'ok', `hub: ${hub.platform || 'file-only'}, ${(hub.roster || []).length} reviewer(s)`);
+      if (isSolo(hub)) check(checks, 'solo', 'project', 'ok', 'mode: solo — approval waived; the PR merge + resolved threads gate the step');
       // platform CLI + auth (best-effort; auth probing is the user's own session)
       const cli = cliFor(hub.platform);
       if (cli) {
@@ -86,6 +93,18 @@ export function projectChecks(checks, root) {
           }
           if (bad.length) check(checks, 'roster', 'project', 'warn', `roster login(s) not found on ${hub.platform}: ${bad.join(', ')}`, 'fix the login or re-run `yad setup` (they cannot satisfy a gate)');
           else check(checks, 'roster', 'project', 'ok', `roster: ${(hub.roster || []).length} member(s) validated on ${hub.platform}`);
+          // Solo + GitHub: a branch that "requires approvals" would block the solo dev's own merge
+          // (they can't approve their own PR). Best-effort probe; a 404 (no protection) is fine.
+          if (isSolo(hub) && hub.platform === 'github') {
+            const slug = repoSlug(hub.git_url) || repoSlug(run('git', ['remote', 'get-url', 'origin'], { cwd: root }).stdout);
+            const br = hub.default_branch || 'main';
+            if (slug) {
+              const probe = run('gh', ['api', `repos/${slug}/branches/${br}/protection/required_pull_request_reviews`, '--jq', '.required_approving_review_count']);
+              if (probe.ok && Number(probe.stdout) > 0) {
+                check(checks, 'solo-branch-protection', 'project', 'warn', `solo mode but ${br} requires ${probe.stdout} approval(s) — you cannot approve your own PR, so the merge will be blocked`, `relax "Require approvals" in ${slug} branch protection for ${br}`);
+              }
+            }
+          }
         }
       }
     }
@@ -173,7 +192,8 @@ export function projectChecks(checks, root) {
       if (!exists(repoRoot)) { check(checks, `repo:${repo.name}`, 'project', 'fail', `${repo.name}: path ${repo.path} does not exist [YAD-STATE-003]`, 'fix the path in repos.json or re-connect the repo'); continue; }
       const head = gitHead(repoRoot);
       if (!head) { check(checks, `repo:${repo.name}`, 'project', 'fail', `${repo.name}: ${repo.path} is not a git repository (or has no commits) [YAD-STATE-003]`, 'init/clone the repo, then re-connect it'); continue; }
-      if (repo.syncedHead && head !== repo.syncedHead) check(checks, `repo:${repo.name}`, 'project', 'warn', `${repo.name}: code-context is stale (HEAD moved since last pack)`, 'run `yad repo refresh ' + repo.name + '`');
+      if (!repo.syncedHead) check(checks, `repo:${repo.name}`, 'project', 'warn', `${repo.name}: registered without a code-context pack (greenfield)`, 'run `yad repo refresh ' + repo.name + '` once it has code');
+      else if (head !== repo.syncedHead) check(checks, `repo:${repo.name}`, 'project', 'warn', `${repo.name}: code-context is stale (HEAD moved since last pack)`, 'run `yad repo refresh ' + repo.name + '`');
       else check(checks, `repo:${repo.name}`, 'project', 'ok', `${repo.name}: git repo, context fresh`);
     }
     if (!registry.repos.length) check(checks, 'repos', 'project', 'warn', 'no code repos registered', 'run `yad setup` to connect one');
@@ -224,7 +244,20 @@ export function epicChecks(checks, root) {
     try {
       const ledger = loadLedger(epicRoot(root, e));
       if (!ledger.state) check(checks, `epic:${e}`, 'epics', 'warn', `${e}: no state.json — epic not seeded`, 'author it via yad-epic, or remove the directory');
-      else check(checks, `epic:${e}`, 'epics', 'ok', `${e}: currentStep ${ledger.state.currentStep}`);
+      else {
+        check(checks, `epic:${e}`, 'epics', 'ok', `${e}: currentStep ${ledger.state.currentStep}`);
+        // Migration guard (pre-3.0 model): under the current model CI records the ledger on the
+        // default branch only at merge (when the step is already done), and writes nothing during
+        // review — so an OPEN (non-done) review PR recorded here means it was opened under an older
+        // model. Merge/close it under the version that opened it before relying on the CI flow.
+        const openPr = (ledger.hubPrs || []).find((p) => {
+          const st = (ledger.state.steps.find((s) => s.id === p.step) || {}).status;
+          return st && st !== 'done';
+        });
+        if (openPr) check(checks, `epic:${e}:migration`, 'epics', 'warn',
+          `${e}: an open review PR (${openPr.artifact}${openPr.number ? ` #${openPr.number}` : ''}) is recorded on the default branch`,
+          'opened under a pre-3.0 yadflow? merge/close it before continuing — CI now records the gate ledger on the default branch only at merge');
+      }
     } catch (err) {
       check(checks, `epic:${e}`, 'epics', 'fail', `${e}: ${err.message} [${err.code || 'YAD-STATE-001'}]`, err.hint || 'fix the file or restore it from git');
     }

package/cli/epic-state.mjs

@@ -42,7 +42,7 @@ export function artifactFromBase(base) {
 }
 
 // The files (relative to the epic dir) a review of this artifact covers — what `gate open` commits
-// on the review branch, and what the CI overlay checks out from the head ref (and never commits).
+// on the review branch (the owner's artifact), and what CI re-reads to bind the approval at merge.
 // Architecture mirrors artifactHash(): the approval is bound to the locked contract surface too.
 export function artifactPaths(base) {
   if (base === 'architecture') return ['architecture.md', 'contract.md', '.sdlc/contract-lock.json'];
@@ -158,6 +158,7 @@ export function gatePredicate({
   defaultReviewers = 1,
   threadsResolved = true,
   merged = true,
+  solo = false,
 }) {
   const forStep = approvals.filter((a) => a.step === step.id && a.status === 'approved');
   // Revoke-on-change: an approval bound to a stale content hash no longer counts.
@@ -168,19 +169,24 @@ export function gatePredicate({
   const reviewers = uniqueBy(live.filter((a) => a.role === 'reviewer'), 'approver');
   const domainOwners = live.filter((a) => a.role === 'domain-owner');
 
-  const missing = [];
-  if (owners.length < 1) missing.push('1 owner approval');
-  if (reviewers.length < defaultReviewers) {
-    missing.push(`${defaultReviewers - reviewers.length} reviewer approval(s)`);
-  }
   const escalate = isEscalated(step);
-  if (escalate) {
-    for (const d of touchedDomains) {
-      if (!domainOwners.some((a) => a.domain === d)) missing.push(`domain-owner for ${d}`);
+  const missing = [];
+  // Solo mode waives the APPROVAL requirements entirely (you can't approve your own PR on GitHub) —
+  // merge + resolved threads are what advance the step. Team mode is unchanged.
+  if (!solo) {
+    if (owners.length < 1) missing.push('1 owner approval');
+    if (reviewers.length < defaultReviewers) {
+      missing.push(`${defaultReviewers - reviewers.length} reviewer approval(s)`);
+    }
+    if (escalate) {
+      for (const d of touchedDomains) {
+        if (!domainOwners.some((a) => a.domain === d)) missing.push(`domain-owner for ${d}`);
+      }
     }
   }
   const approvalsSatisfied = missing.length === 0;
-  if (stale.length) missing.unshift(`${stale.length} approval(s) revoked — artifact changed; re-approve`);
+  // A stale approval only matters when approvals are required (team mode); in solo they are moot.
+  if (!solo && stale.length) missing.unshift(`${stale.length} approval(s) revoked — artifact changed; re-approve`);
   if (!threadsResolved) missing.push('unresolved review comments');
   if (!merged) missing.push('review PR/MR not merged');
 
@@ -191,7 +197,7 @@ export function gatePredicate({
     staleDropped: stale.length,
     passed: approvalsSatisfied && threadsResolved && merged,
     missing,
-    rule: escalate ? (step.id === 'stories-review' ? 'per-repo' : 'escalated') : 'base',
+    rule: solo ? 'solo' : escalate ? (step.id === 'stories-review' ? 'per-repo' : 'escalated') : 'base',
   };
 }
 
@@ -235,4 +241,73 @@ export function markInReview(state, step) {
   return state;
 }
 
+// The front authoring step a `yad next` action maps to — the skill the user invokes for that step.
+// Review (review+approve) steps are driven by the `yad gate` CLI, not a skill, so they are not here.
+export const STEP_SKILL = {
+  analysis: 'yad-analysis',
+  epic: 'yad-epic',
+  architecture: 'yad-architecture',
+  'ui-design': 'yad-ui',
+  stories: 'yad-stories',
+  'test-cases': 'yad-test-cases',
+};
+
+// PURE precondition guard. Is `stepId` runnable right now? A step is runnable iff every step BEFORE it
+// in the chain is `done` and the step itself is not already `done`. With no state yet (greenfield), the
+// only runnable steps are the entry authoring steps (analysis | epic). Used by `yad next --check`
+// (the Phase B rail) and by the driver. No FS / network.
+export function preconditionsMet(state, stepId) {
+  if (!state || !Array.isArray(state.steps)) {
+    const ok = stepId === 'epic' || stepId === 'analysis';
+    return { ok, blockedBy: null, reason: ok ? 'entry step (no epic seeded yet)' : `start with yad-epic — no epic state for '${stepId}'` };
+  }
+  const i = state.steps.findIndex((s) => s.id === stepId);
+  if (i === -1) return { ok: false, blockedBy: null, reason: `unknown step '${stepId}'` };
+  if (state.steps[i].status === 'done') return { ok: false, blockedBy: null, reason: `${stepId} is already done` };
+  const blocker = state.steps.slice(0, i).find((s) => s.status !== 'done');
+  if (blocker) return { ok: false, blockedBy: blocker.id, reason: `${blocker.id} has not passed yet` };
+  return { ok: true, blockedBy: null, reason: 'ready' };
+}
+
+// PURE next-action resolver for ONE epic's ledger — what `yad next <epic>` prints. Reads state + the
+// recorded review PRs only. kind:
+//   'new'         — no epic state yet (seed one with yad-epic)
+//   'author'      — invoke a front authoring skill (STEP_SKILL)
+//   'review-open' — open the review PR/MR (`yad gate open`)
+//   'review-sync' — a review PR/MR is open; sync its state (`yad gate sync`)
+//   'build'       — front half approved (ready-for-build); the build half can run
+export function nextAction(ledger, { epic } = {}) {
+  const state = ledger?.state;
+  const epicId = epic || state?.epicId || null;
+  if (!state) return { epicId, kind: 'new', skill: 'yad-epic', why: 'no epic state yet — seed it with yad-epic' };
+
+  // The parallel test-cases track stays workable even once the epic is ready-for-build.
+  const tc = state.steps.find((s) => s.id === 'test-cases');
+  const tcOpen = !!tc && tc.status !== 'done' && tc.status !== 'blocked';
+  const parallel = tcOpen ? { step: 'test-cases', skill: STEP_SKILL['test-cases'], artifact: tc.artifact } : null;
+
+  if (state.currentStep === 'ready-for-build') {
+    return { epicId, kind: 'build', step: 'ready-for-build', status: 'ready-for-build', parallel,
+      why: 'front half approved — the build half can run' };
+  }
+
+  const step = state.steps.find((s) => s.id === state.currentStep)
+    || state.steps.find((s) => s.status !== 'done');
+  if (!step) return { epicId, kind: 'build', step: 'ready-for-build', parallel, why: 'all front steps are done' };
+
+  if (step.type === 'author') {
+    return { epicId, kind: 'author', step: step.id, status: step.status, parallel,
+      skill: STEP_SKILL[step.id] || null, artifact: step.artifact,
+      why: `${step.id} is ${step.status} — author ${step.artifact}` };
+  }
+
+  // review+approve: open the review PR if none is recorded yet, else sync the open one.
+  const pr = (ledger.hubPrs || []).find((p) => artifactBase(p.artifact) === artifactBase(step.artifact));
+  const verb = pr ? 'sync' : 'open';
+  return { epicId, kind: pr ? 'review-sync' : 'review-open', step: step.id, status: step.status,
+    artifact: step.artifact, pr: pr ? pr.number : null, parallel,
+    command: `yad gate ${verb} ${epicId} ${step.artifact}`,
+    why: pr ? `review PR #${pr.number} is open — sync its state to advance` : `${step.id} is open — create the review PR/MR` };
+}
+
 export { writeJSON };