yadflow 2.13.0 → 2.15.0

package/cli/gate.mjs

@@ -11,9 +11,10 @@ import { PROJECT_FILES } from './manifest.mjs';
 import {
   epicRoot, loadLedger, findReviewStep, artifactBase, artifactHash, gatePredicate,
   advanceState, markInReview, isEscalated, parseReviewBranch, artifactFromBase,
-  artifactPaths, upsertHubPr,
+  upsertHubPr,
 } from './epic-state.mjs';
 import { readPr, mapApprovers, createPr, reviewersForScopes, resolveCommitterLogin } from './platform.mjs';
+import { syncStatuses } from './artifact-status.mjs';
 import { err } from './errors.mjs';
 
 // ---- tiny frontmatter reader (key: value, and `repos: [a, b]`) ----------------------------------
@@ -85,6 +86,17 @@ 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));
+
+// Bridge mode: a platform AND the gate-sync CI explicitly enabled (the canonical `bridge_enabled`,
+// or the older `bridge`). ONLY then is CI the sole ledger writer — so `gate open`/`sync` stay
+// hands-off. A platform without the bridge (no gate-sync CI installed) keeps the local write path,
+// or reviews could never advance. Mirrors plan.mjs hubActions.
+const isBridge = (hub) => !!(hub?.platform && (hub.bridge_enabled === true || hub.bridge === 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
@@ -153,12 +165,19 @@ function recordComments(comments, { artifact, stepId, today, roster, blocking })
 
 // ---- actions ------------------------------------------------------------------------------------
 
-export async function gateSync(root, { epic, artifact, today, reader = readPr } = {}) {
+export async function gateSync(root, { epic, artifact, today, reader = readPr, local = false, dryRun = false } = {}) {
   const { hub, repos } = loadHub(root);
   if (!hub?.platform) { warn('no hub platform configured (.sdlc/hub.json) — file-only gate, nothing to sync'); return { synced: 0 }; }
   const platform = hub.platform;
   const roster = hub.roster || [];
   const defaultReviewers = 1;
+  const solo = isSolo(hub);
+  // Local invocation in bridge mode is ADVISORY: CI is the sole ledger writer, so a human run reads
+  // the platform and prints the predicate but writes nothing. CI calls gateSync with local=false.
+  // Without the bridge (platform but no gate-sync CI) the local command stays the writer.
+  // dryRun forces the same read-only behavior regardless of bridge — used for the Path B pre-merge
+  // evaluation, which must persist nothing (gateCi passes dryRun for a held branch event).
+  const readOnly = (local && isBridge(hub)) || dryRun;
   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 }; }
@@ -168,6 +187,7 @@ export async function gateSync(root, { epic, artifact, today, reader = readPr }
   if (!targets.length) { warn(`no open review PR recorded for ${epic}${artifact ? ` / ${artifact}` : ''} (run \`yad gate open\` first)`); return { synced: 0 }; }
 
   let synced = 0;
+  let advanced = 0;
   for (const pr of targets) {
     const step = findReviewStep(state, pr.artifact);
     if (!step) { warn(`no review step for ${pr.artifact}`); continue; }
@@ -176,11 +196,13 @@ export async function gateSync(root, { epic, artifact, today, reader = readPr }
     if (step.status === 'done') { info(`${pr.artifact}: ${step.id} already done — skipping`); continue; }
     const domains = touchedDomains(epicDir, step);
     const pull = reader(platform, pr.number, { cwd: root });
-    if (!pull.ok) { warn(`${pr.artifact}: ${pull.reason} — skipping (file-only)`); continue; }
+    // A failed platform read must not pass as a green no-op: flag the run non-zero so CI surfaces it
+    // (the wired workflow's reconcile/sweep aggregates this exit) instead of silently not advancing.
+    if (!pull.ok) { warn(`${pr.artifact}: ${pull.reason} — skipping (file-only)`); process.exitCode = 1; continue; }
 
     const curHash = artifactHash(epicDir, pr.artifact);
     warnUnlockedContract(epicDir, pr.artifact);
-    const recs = mapApprovers(pull.reviews, { roster, repos, touchedDomains: domains });
+    const recs = mapApprovers(pull.reviews, { roster, repos, touchedDomains: domains, headOid: pull.headOid });
     approvals = upsertBridge(approvals, recs, { stepId: step.id, artifact: pr.artifact, curHash, today });
 
     const changeRequested = pull.reviews.filter((r) => r.state === 'CHANGES_REQUESTED');
@@ -190,17 +212,19 @@ export async function gateSync(root, { epic, artifact, today, reader = readPr }
       ...changeRequested.map((r) => ({ login: r.login, changesRequested: true })),
       ...unresolved,
     ];
-    writeComments(epicDir, base(pr.artifact), today, blocking);
+    // Advisory (read-only) sync must not touch the working tree — defer the reviews/*.md write.
+    if (!readOnly) writeComments(epicDir, base(pr.artifact), today, blocking);
     comments = recordComments(comments, { artifact: pr.artifact, stepId: step.id, today, roster, repos, blocking });
 
     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})`)}`);
     if (pred.passed) {
       state = advanceState(state, step);
+      advanced++;
       ok(`gate PASSED — ${step.id} → done; next: ${state.currentStep}`);
     } else {
       state = markInReview(state, step);
@@ -210,29 +234,42 @@ export async function gateSync(root, { epic, artifact, today, reader = readPr }
     synced++;
   }
 
+  if (readOnly) {
+    info('bridge mode: advisory view — CI owns the ledger, nothing written locally');
+    return { synced, advanced };
+  }
   writeJSON(ledger.files.approvals, approvals);
   writeJSON(ledger.files.comments, comments);
   writeJSON(ledger.files.hubPrs, hubPrs);
   writeJSON(ledger.files.state, state);
   refreshRoster(epicDir, targets, approvals, today);
-  return { synced };
+  return { synced, advanced };
 }
 
-// `yad gate ci` — the self-sufficient entry point hub CI calls on platform events (review
-// submitted/dismissed, PR synchronize, PR merged) and on the GitLab schedule. Event mode derives
-// epic/artifact from the `review/EP-<slug>/<base>` head branch (so it works even when the author
-// never committed hub-prs.json); sweep mode (no --branch) re-syncs every open review PR. Either way
-// it runs the unchanged gateSync, then commits ONLY the ledger files to the hub default branch —
-// the artifact itself lands on main via the human merge, never via CI.
-export async function gateCi(root, { branch, pr, today, push = true, reader = readPr } = {}) {
+// `yad gate ci` — the self-sufficient entry point hub CI calls on platform events. Path B: CI
+// never writes the ledger to the review branch — during review the platform PR/MR is the source of
+// truth, and the ledger is reconciled onto the default branch at merge.
+//
+//   PRE-MERGE (a held step, no --merged and nothing advanced): READ-ONLY. The predicate is
+//   evaluated for visibility, but nothing is committed or pushed — so an in-flight approval is never
+//   dismissed and the PR's required checks never strand on a CI commit.
+//
+//   MERGE (--merged, PR/MR closed+merged): the artifact reached the default branch via the human
+//   merge; the workflow checks out the default branch. CI runs the sync — the PR reads merged=true,
+//   so the predicate ADVANCES the step, flips the artifact `status:` to approved (syncStatuses), and
+//   commits the advance to the default branch. CI re-reads approvals fresh from the platform, so it
+//   needs no ledger pre-seeded on the branch.
+//
+// CI is the SOLE writer of the ledger and only ever commits to the default branch; humans never
+// commit gate-state files (enforced by the ledger-guard check). Sweep mode (no --branch) advances
+// merged-but-stuck reviews found in the locally checked-out default-branch ledgers.
+export async function gateCi(root, { branch, pr, merged = false, today, push = true, reader = readPr } = {}) {
   const { hub } = loadHub(root);
   if (!hub?.platform) { warn('no hub platform configured (.sdlc/hub.json) — nothing to sync'); return { synced: 0 }; }
   const git = (...args) => run('git', args, { cwd: root });
-  // Push target: an explicit hub.default_branch wins; else the branch CI actually checked out (the
-  // workflow checks out the PR base / $CI_DEFAULT_BRANCH — hub.json from `yad setup` has no
-  // default_branch field, so the checkout is the truth); 'main' only as the last resort.
-  const head = git('rev-parse', '--abbrev-ref', 'HEAD').stdout;
-  const target = hub.default_branch || (head && head !== 'HEAD' ? head : 'main');
+  const defaultBranch = hub.default_branch || (() => { const h = git('rev-parse', '--abbrev-ref', 'HEAD').stdout; return h && h !== 'HEAD' ? h : 'main'; })();
+  // Push is decided AFTER the sync, once we know whether any step advanced: a held step (no advance,
+  // not merged) is read-only and pushes nothing; an advance lands on the default branch (see below).
 
   // Build the work list: one job per (epic, artifact) — from the event branch, or a full sweep.
   const jobs = [];
@@ -265,6 +302,7 @@ export async function gateCi(root, { branch, pr, today, push = true, reader = re
 
   let synced = 0;
   const touched = new Set();
+  const advancedEpics = new Set(); // epics whose step actually passed this run (merge OR a swept merge)
   for (const job of jobs) {
     const epicDir = epicRoot(root, job.epic);
     // Event mode (--branch) targets a single epic: fail loudly. Sweep mode skips the bad epic.
@@ -278,14 +316,14 @@ export async function gateCi(root, { branch, pr, today, push = true, reader = re
       continue;
     }
     if (!ledger.state) {
-      warn(`${job.epic}: no epic state on ${target} — commit epics/${job.epic}/.sdlc to ${target} first`);
+      warn(`${job.epic}: no epic state on the checked-out branch — the review branch is cut from the default branch, so it should carry it`);
       continue;
     }
     const step = findReviewStep(ledger.state, job.artifact);
     if (!step) { warn(`${job.epic}: no review step for ${job.artifact} — skipping`); continue; }
 
-    // The event may fire before the author ever committed hub-prs.json — build the entry from the
-    // event itself, so the first CI commit lands it on the default branch and the views converge.
+    // The merge event may fire before any hub-prs record exists (Path B never wrote one pre-merge) —
+    // build the entry from the event itself so the advance commit carries it onto the default branch.
     const existing = (ledger.hubPrs || []).find((x) => x.artifact === job.artifact);
     const number = Number(job.pr) || existing?.number || null;
     if (!existing || existing.number !== number || existing.branch !== job.branch) {
@@ -296,60 +334,78 @@ export async function gateCi(root, { branch, pr, today, push = true, reader = re
       writeJSON(ledger.files.hubPrs, ledger.hubPrs);
     }
 
-    // Overlay the artifact from the review branch so artifactHash binds approvals to what the
-    // reviewers actually approved (pre-merge, the default branch does not have it yet). A failed
-    // fetch (branch deleted after merge) is fine — the artifact already landed via the merge.
-    const overlay = artifactPaths(job.base).map((p) => path.join('epics', job.epic, p));
-    const fetched = job.branch ? git('fetch', 'origin', job.branch).ok : false;
-    if (fetched) for (const p of overlay) git('checkout', 'FETCH_HEAD', '--', p);
-
+    // No overlay: at merge the artifact is on the default branch CI checked out, so artifactHash
+    // binds to the reviewed content directly when CI re-reads the platform.
     let failed = false;
     try {
-      const r = await gateSync(root, { epic: job.epic, artifact: job.artifact, today, reader });
+      // A branch event that is not a merge can never advance (the predicate requires merged), so it
+      // is read-only under Path B — run it as a dry sync that persists nothing to the working tree.
+      const r = await gateSync(root, { epic: job.epic, artifact: job.artifact, today, reader, dryRun: !!branch && !merged });
       synced += r.synced;
+      // When the step actually ADVANCED (the merge phase, or a swept merge the schedule observed),
+      // reflect it in the artifact frontmatter (draft → approved). Keyed off the advance, not the
+      // --merged flag, so the GitLab scheduled sweep also flips status on a merge it catches. Never
+      // on a held step: CI must not touch the artifact while the owner is editing it pre-merge.
+      if (r.advanced > 0) { advancedEpics.add(job.epic); await syncStatuses(root, { epic: job.epic }); }
     } catch (err) {
       if (branch) throw err; // event mode: one epic — surface the failure
       warn(`${job.epic}: sync failed — ${err.message} — skipping this epic`);
       process.exitCode = 1;
       failed = true;
-    } finally {
-      // Drop the overlay — even when sync throws: only the ledger may reach the default branch via CI.
-      if (fetched) {
-        for (const p of overlay) {
-          git('checkout', 'HEAD', '--', p); // tracked files back to HEAD (no-op fail if not in HEAD)
-          git('clean', '-fd', '--', p);     // files new on the branch: remove
-        }
-      }
     }
     if (failed) continue; // a failed epic's partial state must not be committed by this run
     touched.add(job.epic);
   }
   if (!touched.size) return { synced };
 
-  // Commit the ledger only, then push with a rebase-retry (ledger commits across epics touch
-  // disjoint files; same-repo runs are serialized by the CI concurrency group).
+  // Path B: CI never writes the ledger to the review branch. A held step that did not advance is
+  // read-only here — during review the platform PR/MR is the source of truth (native approvals/
+  // threads); the ledger is reconciled onto the default branch at merge. Keeping CI off the PR head
+  // is what stops an approval from being dismissed and required checks from stranding. Correctness is
+  // unaffected: the merge phase re-reads approvals fresh from the platform (readPr).
+  const advancedAny = advancedEpics.size > 0;
+  if (!merged && !advancedAny) {
+    // Pre-merge is read-only (Path B): the gate was evaluated with a dry sync that persists nothing.
+    // The one working-tree write is the hub-prs.json seed above (so the dry sync could find the PR);
+    // restore exactly that file per epic so the checkout stays clean — never touching anything else,
+    // so a local `yad gate ci --branch` cannot disturb unrelated files.
+    for (const e of touched) {
+      const hp = path.join('epics', e, '.sdlc', 'hub-prs.json');
+      git('checkout', '-q', '--', hp); // restore it if it was tracked
+      git('clean', '-fq', '--', hp);   // remove it if the event first-seeded it (untracked)
+    }
+    info('pre-merge: gate evaluated; the ledger reconciles on the default branch at merge — nothing pushed');
+    return { synced };
+  }
+  const target = defaultBranch; // CI only ever commits the ledger to the default branch
+
+  // Stage what this merge-phase run owns, per epic (everything lands on the default branch):
+  //  - advanced → the whole epic (ledger advance + the status flip syncStatuses wrote into the .md).
+  //  - merged but not advanced (merged before the rule passed) → the ledger (.sdlc) + the generated
+  //    reviews/ summaries only; the artifact is the owner's, left untouched.
   for (const e of touched) {
-    // Separate adds: a pathspec with no match (reviews/ not created yet) must not abort the other.
-    git('add', '-A', '--', path.join('epics', e, '.sdlc'));
-    git('add', '-A', '--', path.join('epics', e, 'reviews'));
+    if (advancedEpics.has(e)) git('add', '-A', '--', path.join('epics', e));
+    else { git('add', '-A', '--', path.join('epics', e, '.sdlc')); git('add', '-A', '--', path.join('epics', e, 'reviews')); }
   }
   if (git('diff', '--cached', '--quiet').ok) { info('ledger unchanged — nothing to commit'); return { synced }; }
-  const subject = branch
-    ? `chore(gate): sync ${jobs[0].epic}/${jobs[0].base} via CI [skip ci]`
-    : 'chore(gate): scheduled gate sync [skip ci]';
+  // [skip ci]: the advance lands on the default branch (no PR trigger) but keeps the marker to guard
+  // sibling workflows. CI never pushes the review branch (Path B), so there is no synchronize loop.
+  const subject = !branch
+    ? 'chore(gate): scheduled gate sync [skip ci]' // sweep is a batch; one subject for the run
+    : `chore(gate): advance ${jobs[0].epic}/${jobs[0].base} on merge [skip ci]`;
   const cm = git('commit', '-m', subject);
   if (!cm.ok) { fail(`commit failed: ${cm.stderr || cm.stdout}`); process.exitCode = 1; return { synced }; }
-  ok(`committed ledger update: ${c.dim(subject)}`);
+  ok(`committed gate update: ${c.dim(subject)}`);
   if (!push) return { synced };
 
   for (let attempt = 1; attempt <= 3; attempt++) {
-    if (git('push', 'origin', `HEAD:${target}`).ok) { ok(`pushed ledger to origin/${target}`); return { synced }; }
+    if (git('push', 'origin', `HEAD:${target}`).ok) { ok(`pushed to origin/${target}`); return { synced }; }
     if (attempt < 3) {
       info(`push rejected — rebasing onto origin/${target} and retrying (${attempt}/3)`);
       if (!git('pull', '--rebase', 'origin', target).ok) git('rebase', '--abort'); // never leave a wedged rebase
     }
   }
-  fail(`could not push the ledger to origin/${target} — protected branch? allow the CI actor to push (see yad-hub-bridge references/bridge.md) or run \`yad gate sync\` locally`);
+  fail(`could not push to origin/${target}${merged ? ' — protected default branch? allow the gate bot to push the merge advance (see yad-hub-bridge references/bridge.md)' : ''} — or run \`yad gate sync\` locally`);
   process.exitCode = 1;
   return { synced };
 }
@@ -382,7 +438,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));
@@ -405,12 +462,22 @@ export async function gateOpen(root, { epic, artifact } = {}) {
   const domains = touchedDomains(epicDir, step);
   warnUnlockedContract(epicDir, artifact);
 
-  // Mark in-review in the ledger regardless of platform (file-only still works).
-  ledger.state = markInReview(ledger.state, step);
-  writeJSON(ledger.files.state, ledger.state);
-
-  if (!hub?.platform) { warn('no hub platform — marked in_review file-only (no PR opened)'); ok(`${step.id} → in_review`); return; }
+  const bridge = isBridge(hub);
+  // Outside bridge mode (file-only, OR a platform with no gate-sync CI) there is no CI to write the
+  // ledger, so the local command marks the step in_review. In bridge mode CI is the sole writer.
+  if (!bridge) {
+    ledger.state = markInReview(ledger.state, step);
+    writeJSON(ledger.files.state, ledger.state);
+  }
+  if (!hub?.platform) {
+    warn('no hub platform — marked in_review file-only (no PR opened)');
+    ok(`${step.id} → in_review`);
+    return;
+  }
 
+  // Open the PR. In bridge mode CI records the hub-prs entry (and advances) on the default branch at
+  // merge — `yad gate open` never commits gate-state files (the ledger-guard check enforces that), and
+  // CI writes nothing pre-merge. Without the bridge, the local command records the PR itself (no CI will).
   const body = fillHubTemplate({ epic, artifact, step, owner: ownerOf(epicDir), domains });
   // Assignee = whoever opens the review PR (the committer); reviewers = the hub's reviewers +
   // domain-owners of the touched repos, minus the committer (the owner/author is recorded, not asked
@@ -421,13 +488,16 @@ export async function gateOpen(root, { epic, artifact } = {}) {
   const labels = isEscalated(step) ? domains.map((d) => `domain:${d}`) : [];
   info(`opening review ${hub.platform === 'gitlab' ? 'MR' : 'PR'} on branch ${branch} …`);
   const r = createPr(hub.platform, { title: `review: ${artifact} (${epic})`, body, base: hub.default_branch || 'main', head: branch, reviewers, assignees, labels, cwd: root });
-  if (!r.ok) { warn(`could not open PR (${r.reason || 'unknown'}); step is in_review file-only`); return; }
+  if (!r.ok) { warn(`could not open PR (${r.reason || 'unknown'})${bridge ? ' — open it manually; CI records the gate on merge' : '; step is in_review file-only'}`); return; }
 
-  const number = Number((r.url.match(/\/(\d+)(?:[/?#]|$)/) || [])[1]) || null;
-  ledger.hubPrs = upsertHubPr(ledger.hubPrs, { step: step.id, artifact, platform: hub.platform, number, url: r.url, branch, lastSyncedAt: null });
-  writeJSON(ledger.files.hubPrs, ledger.hubPrs);
+  if (!bridge) {
+    ledger.hubPrs = upsertHubPr(ledger.hubPrs, { step: step.id, artifact, platform: hub.platform, number: Number((r.url.match(/\/(\d+)(?:[/?#]|$)/) || [])[1]) || null, url: r.url, branch, lastSyncedAt: null });
+    writeJSON(ledger.files.hubPrs, ledger.hubPrs);
+  }
   ok(`opened ${r.url}`);
-  hand(`reviewers approve/comment there; then run \`yad gate sync ${epic} ${artifact}\``);
+  hand(bridge
+    ? 'reviewers approve/comment there; CI advances the gate on the default branch when it is merged'
+    : `reviewers approve/comment there; then run \`yad gate sync ${epic} ${artifact}\``);
 }
 
 // ---- helpers ------------------------------------------------------------------------------------

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/manifest.mjs

@@ -195,6 +195,8 @@ export const wiringFor = (platform) => [
 export const HUB_WIRING = {
   common: [
     { src: 'skills/yad-checks/templates/checks/verified-commits.sh', dest: 'checks/verified-commits.sh', exec: true },
+    // The ledger is CI-owned: block non-bot commits to gate-state files on hub review PRs.
+    { src: 'skills/yad-checks/templates/checks/ledger-guard.sh', dest: 'checks/ledger-guard.sh', exec: true },
     // Pattern gates run on the hub too (profile: hub) — commit subject + PR title + PR body.
     { src: 'skills/yad-checks/templates/checks/commit-message.sh', dest: 'checks/commit-message.sh', exec: true },
     { src: 'skills/yad-pr-template/templates/checks/pr-title.sh', dest: 'checks/pr-title.sh', exec: true },

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/platform.mjs

@@ -141,10 +141,21 @@ export function resolveLogin(login, roster = [], repos = [], touchedDomains = []
 
 // Normalized PR reviews -> approval records (only APPROVED states count). `submittedAt` rides along
 // so the gate can tell a fresh re-approval from a stale one (revoke-on-change).
-export function mapApprovers(reviews = [], { roster, repos, touchedDomains }) {
+export function mapApprovers(reviews = [], { roster, repos, touchedDomains, headOid } = {}) {
   const out = [];
   for (const r of reviews) {
     if (r.state !== 'APPROVED') continue;
+    // Revoke-on-change, enforced in code where the platform binds an approval to a commit. The reader
+    // sets `commit` to the review's SHA (GitHub), to `null` when that read DEGRADED, or leaves it
+    // ABSENT when the platform exposes no per-approval SHA (GitLab):
+    //   - `null` (degraded read)  → FAIL CLOSED → drop, independently of headOid: we cannot prove the
+    //                               approval is for the merged content, so a transient failure holds
+    //                               the gate rather than advancing on unverifiable approvals;
+    //   - a known SHA ≠ head      → the approval is stale (artifact moved) → drop;
+    //   - absent (GitLab)         → keep: revoke-on-change is the platform's "remove approvals on new
+    //                               commits" setting.
+    if (r.commit === null) continue;
+    if (headOid && r.commit !== undefined && r.commit !== headOid) continue;
     for (const rec of resolveLogin(r.login, roster, repos, touchedDomains)) {
       out.push({ ...rec, submittedAt: r.submittedAt || null });
     }
@@ -157,17 +168,35 @@ function readPrGitHub(n, { cwd } = {}) {
   const view = run('gh', ['pr', 'view', String(n), '--json', 'state,mergedAt,headRefOid'], { cwd });
   if (!view.ok) return { ok: false, reason: view.stderr || 'gh pr view failed' };
   const meta = JSON.parse(view.stdout);
-  // latestReviews collapses a reviewer's superseded reviews to their current one.
-  const rev = run('gh', ['pr', 'view', String(n), '--json', 'latestReviews'], { cwd });
-  const reviews = rev.ok
-    ? (JSON.parse(rev.stdout).latestReviews || []).map((x) => ({ login: x.author?.login, state: x.state, submittedAt: x.submittedAt }))
-    : [];
+  let reviews = [];
+  let reviewsOk = false;
   // Review-thread resolution via GraphQL (REST does not expose isResolved). Paginate so a PR with
   // >100 threads is not mistakenly read as "all resolved".
   let threads = [];
   const nwo = run('gh', ['repo', 'view', '--json', 'owner,name'], { cwd });
   if (nwo.ok) {
     const { owner, name } = JSON.parse(nwo.stdout);
+    // latestReviews collapses a reviewer's superseded reviews to their current one; commit.oid binds
+    // each approval to the revision it was made on, so an approval on an older commit than the merged
+    // head is dropped as stale (revoke-on-change in code — see mapApprovers). `gh pr view --json
+    // latestReviews` does not expose the commit, so read it via GraphQL. Paginate so a PR with >100
+    // reviewers never silently omits one; any page failure aborts to the commitless fallback below,
+    // which fails closed rather than advancing on a partial read.
+    const rq = `query($o:String!,$r:String!,$n:Int!,$c:String){repository(owner:$o,name:$r){pullRequest(number:$n){latestReviews(first:100,after:$c){pageInfo{hasNextPage endCursor} nodes{author{login} state submittedAt commit{oid}}}}}}`;
+    let rcursor = null;
+    reviewsOk = true;
+    for (let guard = 0; guard < 50; guard++) {
+      const args = ['api', 'graphql', '-f', `query=${rq}`, '-F', `o=${owner.login}`, '-F', `r=${name}`, '-F', `n=${n}`];
+      if (rcursor) args.push('-F', `c=${rcursor}`);
+      const rg = run('gh', args, { cwd });
+      if (!rg.ok) { reviewsOk = false; reviews = []; break; }
+      const conn = JSON.parse(rg.stdout)?.data?.repository?.pullRequest?.latestReviews;
+      for (const x of conn?.nodes || []) {
+        reviews.push({ login: x.author?.login, state: x.state, submittedAt: x.submittedAt, commit: x.commit?.oid || null });
+      }
+      if (!conn?.pageInfo?.hasNextPage) break;
+      rcursor = conn.pageInfo.endCursor;
+    }
     const q = `query($o:String!,$r:String!,$n:Int!,$c:String){repository(owner:$o,name:$r){pullRequest(number:$n){reviewThreads(first:100,after:$c){pageInfo{hasNextPage endCursor} nodes{isResolved comments(first:1){nodes{author{login} body}}}}}}}`;
     let cursor = null;
     for (let guard = 0; guard < 50; guard++) {
@@ -188,6 +217,15 @@ function readPrGitHub(n, { cwd } = {}) {
       cursor = page.pageInfo.endCursor;
     }
   }
+  // Fallback if the GraphQL reviews read failed (no nwo / API hiccup): take the plain JSON view with
+  // commit=null. Approvals then FAIL CLOSED in mapApprovers (a degraded read cannot prove an approval
+  // is for the merged content), while CHANGES_REQUESTED is still honored — so a transient failure
+  // holds the gate, never advances it.
+  if (!reviewsOk) {
+    const rev = run('gh', ['pr', 'view', String(n), '--json', 'latestReviews'], { cwd });
+    if (rev.ok) reviews = (JSON.parse(rev.stdout).latestReviews || [])
+      .map((x) => ({ login: x.author?.login, state: x.state, submittedAt: x.submittedAt, commit: null }));
+  }
   return {
     ok: true,
     state: meta.state,

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