yadflow 3.13.1 → 3.14.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [3.14.0](https://github.com/abdelrahmannasr/yadflow/compare/v3.13.2...v3.14.0) (2026-08-10)
+
+
+### Features
+
+* **next:** emit the action object with --json ([40d34dd](https://github.com/abdelrahmannasr/yadflow/commit/40d34ddba2492821700c7a877de28938faa74f3e))
+
+## [3.13.2](https://github.com/abdelrahmannasr/yadflow/compare/v3.13.1...v3.13.2) (2026-08-10)
+
+
+### Bug Fixes
+
+* **doctor:** fail a done review gate that holds no approval ([b1b23df](https://github.com/abdelrahmannasr/yadflow/commit/b1b23df5426e8523cdb1d95221cb2291200c6249))
+
 ## [3.13.1](https://github.com/abdelrahmannasr/yadflow/compare/v3.13.0...v3.13.1) (2026-07-29)
 
 

package/bin/yad.mjs

@@ -68,6 +68,8 @@ ${c.bold('Where am I / what next')}
   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
+  yad next [<epic>] --json             The same answer as a machine-readable action object (for
+                                       agents/CI) — always every epic, so --all is implied
   yad skip <epic> ui-design --reason <text>   Mark an optional step N/A for this epic (only
                                        ui-design today) — a backend/API/data epic with no UI.
                                        Stays visible & auditable (pre-done, gate short-circuited);
@@ -257,7 +259,7 @@ async function main() {
       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 });
+      await runNext(o.dir, { epic, check: typeof o.check === 'string' ? o.check : undefined, all: o.all, json: o.json });
       break;
     }
     case 'skip': {

package/cli/doctor.mjs

@@ -368,20 +368,40 @@ function contractLockCheck(checks, root, epic, ledger) {
   check(checks, id, 'epics', 'ok', `${epic}: contract surface matches its lock (${short(stored)})`);
 }
 
-// A review step that is `done` but whose approvals no longer bind to the artifact as it stands today.
-// The gate is deliberately one-way — nothing pulls a chain backward once work is built on it — so the
-// only way this surfaces is if something reports it. `gate sync` records the gap on the step it is
-// syncing; this reports it for the whole epic, so a re-locked surface that was never re-approved is
-// visible in the one command people run when something looks wrong. WARN, not FAIL: the state is a
-// fact about history, and the fix (re-open the review) is a human decision.
-function staleGateCheck(checks, root, epic, ledger) {
+// Two findings on a review step that is already `done`, both about the approval record behind it.
+//
+//   FAIL — it holds NO qualifying approval at all (outside solo mode). This is the state the gate
+//   exists to prevent: the step advanced without the record that justifies it. `gatePredicate` counts
+//   exactly the same thing (`status === 'approved'`, with `inherited`/`skipped` steps short-circuited
+//   before it), so a step doctor reports here is one the gate itself would refuse today.
+//
+//   WARN — it holds approvals, but none still bind to the artifact as it stands. The gate is
+//   deliberately one-way — nothing pulls a chain backward once work is built on it — so the only way
+//   this surfaces is if something reports it. `gate sync` records the gap on the step it is syncing;
+//   this reports it for the whole epic, so a re-locked surface that was never re-approved is visible
+//   in the one command people run when something looks wrong. A warning, because the state is a fact
+//   about history and the fix (re-open the review) is a human decision.
+function staleGateCheck(checks, root, epic, ledger, { solo = false } = {}) {
   const epicDir = epicRoot(root, epic);
   for (const s of ledger.state.steps) {
     if (s.type !== 'review+approve' || s.status !== 'done' || s.inherited || s.skipped) continue;
+    const forStep = ledger.approvals.filter((a) => a.step === s.id && a.status === 'approved');
+    // Checked BEFORE the artifact hash below: "done holding no approval" is a claim about the ledger,
+    // not about content, so it must not depend on there being something to hash. Gating it behind the
+    // hash would keep hiding it on every epic with no locked surface.
+    if (!forStep.length) {
+      // Solo mode waives the approval requirement outright (you cannot approve your own PR) — the
+      // merge + resolved threads are what advance the step, so an empty record is the documented
+      // shape there, not a finding. Everywhere else it is the gate being silently defeated.
+      if (solo) continue;
+      const records = ledger.approvals.filter((a) => a.step === s.id).length;
+      check(checks, `epic:${epic}:${s.id}:unapproved`, 'epics', 'fail',
+        `${epic}: ${s.id} is done but holds no approval${records ? ` (${records} record(s), none of them live)` : ''}`,
+        'the step advanced without the record the gate exists to keep — re-open the review (a fresh PR/MR) and re-approve, or run `yad gate sync` if the approvals are on the PR but never reached the ledger');
+      continue;
+    }
     const cur = artifactHash(epicDir, s.artifact);
     if (!cur) continue; // nothing to bind to (no locked surface / incomplete set) — not a staleness claim
-    const forStep = ledger.approvals.filter((a) => a.step === s.id && a.status === 'approved');
-    if (!forStep.length) continue; // solo mode waives approvals entirely; absence is not staleness
     const live = forStep.filter((a) => !a.artifactHash || a.artifactHash === cur);
     if (live.length) continue;
     check(checks, `epic:${epic}:${s.id}:stale`, 'epics', 'warn',
@@ -393,6 +413,8 @@ function staleGateCheck(checks, root, epic, ledger) {
 export function epicChecks(checks, root) {
   const epicsDir = path.join(root, 'epics');
   if (!exists(epicsDir)) return;
+  // Read once for the whole sweep: whether approval is waived is a project fact, not a per-epic one.
+  const solo = isSolo(readJSON(path.join(root, PROJECT_FILES.hubConfig), null));
   for (const e of fs.readdirSync(epicsDir).sort()) {
     if (!fs.statSync(path.join(epicsDir, e)).isDirectory()) continue;
     try {
@@ -419,7 +441,7 @@ export function epicChecks(checks, root) {
           `${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');
         contractLockCheck(checks, root, e, ledger);
-        staleGateCheck(checks, root, e, ledger);
+        staleGateCheck(checks, root, e, ledger, { solo });
       }
     } 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/next.mjs

@@ -9,10 +9,11 @@
 //   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
+//   yad next [<epic>] --json  the same answer as an action object, for an agent or CI
 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 { PROJECT_FILES, VERSION } from './manifest.mjs';
 import { epicRoot, loadLedger, nextAction, preconditionsMet, isValidEpicId, epicLineage, kindNoun, DISCOVERY_EPIC } from './epic-state.mjs';
 
 // Is solo mode on? Persisted in hub.json by setup (Phase C/D); default false. Read defensively so a
@@ -37,6 +38,14 @@ function listEpics(root) {
     .sort();
 }
 
+// The action object for ONE epic, with its lineage kind attached. The single shape both surfaces
+// consume — `printAction` renders it, `--json` emits it verbatim — so the prose and the machine
+// answer can never drift apart.
+const actionFor = (root, id) => ({
+  ...nextAction(loadLedger(epicRoot(root, id)), { epic: id }),
+  lineageKind: epicLineage(root, id).kind,
+});
+
 // EP-istifta-inquiries-S03 → S03 (the compact lane label for the roll-up). Falls back to the full id.
 const shortStory = (s) => (s && s.match(/S\d+$/i)?.[0]) || s || '(story)';
 
@@ -128,9 +137,7 @@ function generalNext(root, { all } = {}) {
   const allEpics = listEpics(root);
   const hasDiscovery = allEpics.includes(DISCOVERY_EPIC);
   const featureEpics = allEpics.filter((id) => id !== DISCOVERY_EPIC);
-  const discoveryAction = hasDiscovery
-    ? nextAction(loadLedger(epicRoot(root, DISCOVERY_EPIC)), { epic: DISCOVERY_EPIC })
-    : null;
+  const discoveryAction = hasDiscovery ? actionFor(root, DISCOVERY_EPIC) : null;
   const discoveryOpen = !!discoveryAction && discoveryAction.kind !== 'discovery-done';
 
   if (!featureEpics.length) {
@@ -142,10 +149,7 @@ function generalNext(root, { all } = {}) {
     return;
   }
 
-  const actions = featureEpics.map((id) => ({
-    ...nextAction(loadLedger(epicRoot(root, id)), { epic: id }),
-    lineageKind: epicLineage(root, id).kind,
-  }));
+  const actions = featureEpics.map((id) => actionFor(root, id));
   if (discoveryOpen) printAction(discoveryAction, { solo });   // an unfinished discovery comes first
 
   if (featureEpics.length === 1 || all) {
@@ -171,14 +175,59 @@ function checkPrecondition(root, epic, stepId) {
   process.exitCode = 1;
 }
 
+// ---- machine-readable output (`--json`) --------------------------------------------------------
+// `nextAction` already computes exactly what a caller needs; until now the ANSI prose renderer was
+// its only consumer, so anything driving yadflow had to regex coloured English. This emits the SAME
+// objects, unrendered. One envelope for every route, so a caller never has to branch on the shape:
+//
+//   { version, ok: true,  actions: [ <action>, … ] }        next / next <epic>
+//   { version, ok,        check: { epic, step, ok, reason } } next <epic> --check <step>
+//   { version, ok: true,  setUp: false, actions: [] }        the project has no `yad setup` yet
+//   { version, ok: false, error }                            bad epic id / no state.json
+//
+// Exit codes are unchanged from the prose path — only the rendering differs.
+const emitJSON = (payload) => log(JSON.stringify({ version: VERSION, ...payload }, null, 2));
+
+// A JSON error still leaves stdout parseable: a caller that pipes us into a parser gets an object
+// explaining the failure, never half a document or a bare ANSI line.
+function jsonError(message) {
+  emitJSON({ ok: false, error: message });
+  process.exitCode = 1;
+}
+
+// `--json` counterpart of runNext's three routes. Kept in one function so the routing reads next to
+// the prose routing it mirrors.
+function jsonNext(root, { epic, check }) {
+  if (epic && check) {
+    const res = preconditionsMet(loadLedger(epicRoot(root, epic)).state, check);
+    emitJSON({ ok: !!res.ok, check: { epic, step: check, ok: !!res.ok, ...(res.reason ? { reason: res.reason } : {}) } });
+    if (!res.ok) process.exitCode = 1;
+    return;
+  }
+  if (epic) {
+    if (!exists(path.join(epicRoot(root, epic), '.sdlc', 'state.json'))) {
+      return jsonError(`no epic state at epics/${epic}/.sdlc/state.json`);
+    }
+    return emitJSON({ ok: true, actions: [actionFor(root, epic)] });
+  }
+  if (!isSetUp(root)) return emitJSON({ ok: true, setUp: false, actions: [] });
+  // Every epic that HAS a ledger, discovery included — its `kind` already says whether it is open
+  // (`discovery-*`) or finished, so filtering it out would hide a fact rather than clarify one.
+  // `--all` is implied: an array always carries everything, so there is nothing left to expand.
+  return emitJSON({ ok: true, actions: listEpics(root).map((id) => actionFor(root, id)) });
+}
+
 // 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 } = {}) {
+export async function runNext(root, { epic, check, all, json } = {}) {
   if (epic && !isValidEpicId(epic)) {
-    fail(`invalid epic id: ${epic} (expected EP-<slug>, [a-z0-9-] only)`);
+    const message = `invalid epic id: ${epic} (expected EP-<slug>, [a-z0-9-] only)`;
+    if (json) return jsonError(message);
+    fail(message);
     process.exitCode = 1;
     return;
   }
+  if (json) return jsonNext(root, { epic, check });
   if (epic && check) return checkPrecondition(root, epic, check);
   if (!epic) return generalNext(root, { all });
 
@@ -189,8 +238,5 @@ export async function runNext(root, { epic, check, all } = {}) {
     process.exitCode = 1;
     return;
   }
-  printAction(
-    { ...nextAction(loadLedger(epicDir), { epic }), lineageKind: epicLineage(root, epic).kind },
-    { solo: isSolo(root) },
-  );
+  printAction(actionFor(root, epic), { solo: isSolo(root) });
 }

package/package.json

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