yadflow 2.12.0 → 2.14.0

package/CHANGELOG.md

@@ -1,14 +1,9 @@
-# [2.12.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.11.1...v2.12.0) (2026-06-16)
-
-
-### Bug Fixes
-
-* **checks:** harden spec-link + gitlab gate templates ([#69](https://github.com/abdelrahmannasr/yadflow/issues/69)) ([42f3949](https://github.com/abdelrahmannasr/yadflow/commit/42f3949841095624db03cb17f85db3138be8b93b))
+# [2.14.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.13.0...v2.14.0) (2026-06-21)
 
 
 ### Features
 
-* **docs:** pipeline-shaped overview canvas + collapsible panels + content refresh ([#70](https://github.com/abdelrahmannasr/yadflow/issues/70)) ([da47b80](https://github.com/abdelrahmannasr/yadflow/commit/da47b8050ccd7aa1919bf4b364298a90cdd56012))
+* yad next driver, precondition guards, solo mode, and guided setup interview ([#72](https://github.com/abdelrahmannasr/yadflow/issues/72)) ([7125c9d](https://github.com/abdelrahmannasr/yadflow/commit/7125c9d80043cb282a7be4f08dfaa95ddf94594a))
 
 # [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,11 +13,14 @@ 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';
 
 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);
@@ -33,6 +36,12 @@ ${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
@@ -75,7 +84,7 @@ ${c.bold('Options')}
   -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' };
@@ -86,7 +95,19 @@ function parseArgs(argv) {
     else if (a === '--contract-change') o.contractChange = true;
     else if (a === '--no-push') o.noPush = 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 +138,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,6 +153,13 @@ async function main() {
     case 'doctor':
       await runDoctor(o.dir, { json: o.json });
       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).

package/cli/docs.mjs

@@ -43,11 +43,12 @@ export function deployTargetFromHub(hub = {}) {
 }
 
 // The Vite `base` for one site: join the project base path (from docs.json) with the per-site
-// subpath. Per-epic sites nest under epics/<id>/; the overview is the Pages root. Always a
+// subpath. The overview SPA mounts under `app/` so the hand-maintained report.html can own the
+// Pages root (`<base>/`) as the main documentation; per-epic sites nest under epics/<id>/. Always a
 // leading+trailing slash so it works as a Vite base and a router basename.
 export function siteBasePath(docs = {}, { epic, overview } = {}) {
   const root = (docs.basePath || '/').replace(/\/+$/, '') || '';
-  const sub = overview ? '' : epic ? `/epics/${epic}` : '';
+  const sub = overview ? '/app' : epic ? `/epics/${epic}` : '';
   const joined = `${root}${sub}`.replace(/\/+/g, '/');
   return joined ? `${joined.replace(/\/$/, '')}/` : '/';
 }
@@ -113,12 +114,13 @@ export function docsStale(manifest, { artifactHash, repoHeads = {}, templateVers
 
 // ---- pure: the Pages CI workflow (committed by `yad docs sync --wire`) ---------------------------
 // GitHub Actions deploy-pages, or a GitLab `pages` job. Both assemble a single `public/` tree: the
-// overview at the root and every per-epic site under `epics/<id>/` — matching siteBasePath's nesting
-// (overview at `<base>/`, epics at `<base>/epics/EP-<slug>/`). A concurrency group prevents the
+// hand-maintained report.html owns the root (`<base>/` — the main documentation), the overview SPA
+// mounts under `app/`, and every per-epic site nests under `epics/<id>/` — matching siteBasePath
+// (overview at `<base>/app/`, epics at `<base>/epics/EP-<slug>/`). A concurrency group prevents the
 // deploy from retriggering. The shared shell script keeps the two platforms byte-for-byte aligned.
 const BUILD_PUBLIC = [
   'mkdir -p public',
-  'if [ -d docs/sdlc-site ]; then (cd docs/sdlc-site && npm ci && npm run build) && cp -r docs/sdlc-site/dist/. public/; fi',
+  'if [ -d docs/sdlc-site ]; then (cd docs/sdlc-site && npm ci && npm run build) && mkdir -p public/app && cp -r docs/sdlc-site/dist/. public/app/ && cp docs/sdlc-site/public/report.html public/index.html && cp docs/sdlc-site/public/report.html public/report.html; fi',
   'for d in epics/*/docs-site; do [ -d "$d" ] || continue; id=$(basename "$(dirname "$d")"); (cd "$d" && npm ci && npm run build) && mkdir -p "public/epics/$id" && cp -r "$d/dist/." "public/epics/$id/"; done',
 ];
 export function pagesWorkflow(platform) {

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');

package/cli/epic-state.mjs

@@ -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 };

package/cli/gate.mjs

@@ -85,6 +85,11 @@ function loadHub(root) {
   return { hub, repos: registry.repos };
 }
 
+// Solo mode (a lone developer): waive the approval requirement — on GitHub you cannot approve your own
+// PR, so an approval gate would deadlock. The review PR/MR and its merge stay (CI runs on the PR; the
+// merge advances the step). Recorded per-project in hub.json by `yad setup`.
+const isSolo = (hub) => !!(hub && (hub.solo === true || hub.review_gate?.solo === true));
+
 // Re-add this step's bridge approvals from the current platform state (drop+re-add => dismissals and
 // revocations vanish idempotently; manual approvals are never touched). Preserve the artifactHash a
 // reviewer first approved against unless their review is newer (a genuine re-approval) — that is what
@@ -159,6 +164,7 @@ export async function gateSync(root, { epic, artifact, today, reader = readPr }
   const platform = hub.platform;
   const roster = hub.roster || [];
   const defaultReviewers = 1;
+  const solo = isSolo(hub);
   const epicDir = epicRoot(root, epic);
   const ledger = loadLedger(epicDir);
   if (!ledger.state) { fail(`no epic state at ${epicDir}/.sdlc/state.json`); process.exitCode = 1; return { synced: 0 }; }
@@ -195,7 +201,7 @@ export async function gateSync(root, { epic, artifact, today, reader = readPr }
 
     const pred = gatePredicate({
       step, approvals, currentHash: curHash, touchedDomains: domains,
-      defaultReviewers, threadsResolved, merged: pull.merged,
+      defaultReviewers, threadsResolved, merged: pull.merged, solo,
     });
 
     log(`  ${c.bold(pr.artifact)} ${c.dim(`(PR #${pr.number}, rule: ${pred.rule})`)}`);
@@ -382,7 +388,8 @@ export async function gateStatus(root, { epic } = {}) {
   const epicDir = epicRoot(root, epic);
   const ledger = loadLedger(epicDir);
   if (!ledger.state) { fail(`no epic state at ${epicDir}`); process.exitCode = 1; return; }
-  log(`\n  ${c.bold(epic)}  ${c.dim(`currentStep: ${ledger.state.currentStep}`)}`);
+  const solo = isSolo(loadHub(root).hub);
+  log(`\n  ${c.bold(epic)}  ${c.dim(`currentStep: ${ledger.state.currentStep}${solo ? ' — solo mode (approval waived; merge still required)' : ''}`)}`);
   for (const s of ledger.state.steps.filter((x) => x.type === 'review+approve')) {
     const cur = artifactHash(epicDir, s.artifact);
     const live = ledger.approvals.filter((a) => a.step === s.id && a.status === 'approved' && !(a.artifactHash && cur && a.artifactHash !== cur));

package/cli/lib.mjs

@@ -30,6 +30,9 @@ export const info = (s) => log(`  ${c.dim('•')} ${s}`);
 export const warn = (s) => log(`  ${c.yellow('!')} ${s}`);
 export const fail = (s) => log(`  ${c.red('✗')} ${s}`);
 export const hand = (s) => log(`  ${c.yellow('→')} ${s}`);
+// Dimmed, indented guidance under a step — what it does / why / what to enter / what skipping means.
+// Accepts a string or an array of lines so a knowledgeable user can skim past it.
+export const guide = (lines) => { for (const l of (Array.isArray(lines) ? lines : [lines])) log(`    ${c.dim(l)}`); };
 
 // ---- prompts ------------------------------------------------------------
 let rl;

package/cli/next.mjs

@@ -0,0 +1,123 @@
+// `yad next` — the unified next-step driver. Read-only: it never writes state or acts. It reads the
+// file ledger and prints the ONE concrete, copy-pasteable next action (and a one-line why), so a user
+// never has to remember which of the 30 skills / gate commands comes next. "Guide, don't act" — the
+// front half still never auto-advances.
+//
+//   yad next                  general orientation across the whole project
+//   yad next <epic>           the single next action for one epic
+//   yad next <epic> --check <step>   exit 0 if <step> is runnable now, else 1 (the precondition guard)
+//   yad next --all            every active epic's next action at once
+import fs from 'node:fs';
+import path from 'node:path';
+import { c, log, ok, info, warn, hand, fail, readJSON, exists } from './lib.mjs';
+import { PROJECT_FILES } from './manifest.mjs';
+import { epicRoot, loadLedger, nextAction, preconditionsMet, isValidEpicId } from './epic-state.mjs';
+
+// Is solo mode on? Persisted in hub.json by setup (Phase C/D); default false. Read defensively so a
+// missing/old hub.json never breaks the driver.
+function isSolo(root) {
+  const hub = readJSON(path.join(root, PROJECT_FILES.hubConfig), null);
+  return !!(hub && (hub.solo === true || hub.review_gate?.solo === true));
+}
+// The setup profile recorded by `yad setup` (codebase / repo_layout / team_size), or null.
+const profileOf = (root) => readJSON(path.join(root, PROJECT_FILES.hubConfig), null)?.profile || null;
+// Has `yad setup` run here? True once the version stamp or hub config exists.
+const isSetUp = (root) => exists(path.join(root, PROJECT_FILES.version)) || exists(path.join(root, PROJECT_FILES.hubConfig));
+
+// Every epic that has a state ledger, in directory order.
+function listEpics(root) {
+  const dir = path.join(root, 'epics');
+  if (!exists(dir)) return [];
+  return fs.readdirSync(dir, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && isValidEpicId(e.name))
+    .map((e) => e.name)
+    .filter((id) => exists(path.join(dir, id, '.sdlc', 'state.json')))
+    .sort();
+}
+
+// A short, copy-pasteable line for one action — the `▸` line a user can act on directly.
+function actionLine(a, { solo } = {}) {
+  switch (a.kind) {
+    case 'new':
+      return `invoke the ${c.bold(a.skill)} skill ${c.dim('(author the epic)')}`;
+    case 'author':
+      return `invoke the ${c.bold(a.skill || ('yad-' + a.step))} skill ${c.dim(`(author ${a.artifact})`)}`;
+    case 'review-open':
+    case 'review-sync':
+      return `${c.bold(a.command)}${solo ? c.dim('   (solo: no approval needed — just merge your own PR)') : ''}`;
+    case 'build':
+      return `${c.bold('yad-run')} ${c.dim('(or per story: yad-spec → yad-implement → yad ship → yad-engineer-review)')}`;
+    default:
+      return c.dim('nothing to do');
+  }
+}
+
+// Full, friendly printout for a single epic.
+function printAction(a, { solo } = {}) {
+  log(`\n  ${c.bold(a.epicId || '(epic)')} ${c.dim(`— ${a.why}`)}`);
+  hand(actionLine(a, { solo }));
+  if (a.kind === 'review-sync') info(c.dim(`unresolved comments? ${c.bold(`yad gate comments ${a.epicId} ${a.artifact}`)}`));
+  if (a.parallel) hand(`parallel track: invoke the ${c.bold(a.parallel.skill)} skill ${c.dim(`(author ${a.parallel.artifact})`)}`);
+}
+
+// `yad next` with no epic: orient across the whole project, always ending on ONE thing to do.
+function generalNext(root, { all } = {}) {
+  if (!isSetUp(root)) {
+    log(`\n  ${c.bold('Project not set up yet.')}`);
+    hand(`run ${c.bold('yad setup')} ${c.dim('(then come back to `yad next`)')}`);
+    return;
+  }
+  const epics = listEpics(root);
+  if (!epics.length) {
+    const brownfield = profileOf(root)?.codebase === 'brownfield';
+    log(`\n  ${c.bold('Set up — no epics yet.')}`);
+    if (brownfield) hand(`capture what already exists first: invoke the ${c.bold('yad-backfill')} skill`);
+    hand(`start your first epic: invoke the ${c.bold('yad-epic')} skill`);
+    return;
+  }
+  const solo = isSolo(root);
+  const actions = epics.map((id) => nextAction(loadLedger(epicRoot(root, id)), { epic: id }));
+
+  if (epics.length === 1 || all) {
+    for (const a of actions) printAction(a, { solo });
+    return;
+  }
+  // Several epics — list each with a one-liner, then point at the per-epic / --all views.
+  log(`\n  ${c.bold(`${epics.length} epics`)} ${c.dim('— next action each:')}`);
+  for (const a of actions) log(`    ${c.cyan(a.epicId)}  ${actionLine(a, { solo })}`);
+  info(c.dim(`detail: ${c.bold('yad next <epic>')}  •  all at once: ${c.bold('yad next --all')}`));
+}
+
+// `yad next <epic> --check <step>`: the precondition guard. Exit 0 if runnable now, 1 otherwise.
+function checkPrecondition(root, epic, stepId) {
+  const ledger = loadLedger(epicRoot(root, epic));
+  const res = preconditionsMet(ledger.state, stepId);
+  if (res.ok) {
+    ok(`${epic}: ${stepId} is ready to run`);
+    return;
+  }
+  fail(`${epic}: ${stepId} is blocked — ${res.reason}`);
+  hand(`see what to do now: ${c.bold(`yad next ${epic}`)}`);
+  process.exitCode = 1;
+}
+
+// Entry point for the `next` command: route to the precondition check, a single epic's action, or the
+// project-wide general view. Validates the epic id first.
+export async function runNext(root, { epic, check, all } = {}) {
+  if (epic && !isValidEpicId(epic)) {
+    fail(`invalid epic id: ${epic} (expected EP-<slug>, [a-z0-9-] only)`);
+    process.exitCode = 1;
+    return;
+  }
+  if (epic && check) return checkPrecondition(root, epic, check);
+  if (!epic) return generalNext(root, { all });
+
+  const epicDir = epicRoot(root, epic);
+  if (!exists(path.join(epicDir, '.sdlc', 'state.json'))) {
+    warn(`no epic state at ${epicDir}/.sdlc/state.json`);
+    hand(`is the id right? list project status with ${c.bold('yad next')}`);
+    process.exitCode = 1;
+    return;
+  }
+  printAction(nextAction(loadLedger(epicDir), { epic }), { solo: isSolo(root) });
+}

package/cli/repo.mjs

@@ -13,11 +13,14 @@ function load(root) {
   return { regPath, registry: readJSON(regPath, { repos: [] }) };
 }
 
-// HEAD != syncedHead => stale (config.yaml code_context.staleness: head-sha).
+// HEAD != syncedHead => stale (config.yaml code_context.staleness: head-sha). A repo that has a HEAD but
+// no syncedHead was registered without a pack (the greenfield path) — it needs an initial pack, which is
+// also a "run `yad repo refresh`" state, kept distinct from HEAD-moved staleness.
 function staleness(root, repo) {
   const head = gitHead(path.resolve(root, repo.path));
+  const neverPacked = !!head && !repo.syncedHead;
   const stale = head && repo.syncedHead && head !== repo.syncedHead;
-  return { head, stale: !!stale, unknown: !head };
+  return { head, stale: !!stale, unknown: !head, neverPacked };
 }
 
 // ---- git helpers for `sync` (local-user auth only — never embed credentials) ----
@@ -40,9 +43,10 @@ export async function runRepo(root, { action = 'list', name, today } = {}) {
     log(c.bold('\nconnected repos'));
     let staleCount = 0;
     for (const repo of registry.repos) {
-      const { stale, unknown } = staleness(root, repo);
+      const { stale, unknown, neverPacked } = staleness(root, repo);
       if (unknown) { warn(`${repo.name} ${c.dim(`(${repo.path})`)} — HEAD unreadable`); continue; }
-      if (stale) { staleCount++; warn(`${repo.name} ${c.dim(`(${repo.path})`)} — ${c.yellow('stale')} (HEAD moved since last pack)`); }
+      if (neverPacked) { staleCount++; warn(`${repo.name} ${c.dim(`(${repo.path})`)} — ${c.yellow('no code-context pack yet')} (registered without one)`); }
+      else if (stale) { staleCount++; warn(`${repo.name} ${c.dim(`(${repo.path})`)} — ${c.yellow('stale')} (HEAD moved since last pack)`); }
       else ok(`${repo.name} ${c.dim('— fresh')}`);
     }
     if (staleCount) hand(`refresh with \`yad repo refresh${registry.repos.length > 1 ? ' <name>' : ''}\` (or \`yad repo refresh\` for all)`);