yadflow 3.2.0 → 3.3.0

package/CHANGELOG.md

@@ -1,14 +1,9 @@
-# [3.2.0](https://github.com/abdelrahmannasr/yadflow/compare/v3.1.0...v3.2.0) (2026-06-30)
-
-
-### Bug Fixes
-
-* **review:** keep walkthrough STDOUT pure JSON (diagnostics to stderr) ([0d46455](https://github.com/abdelrahmannasr/yadflow/commit/0d46455919997ebcaa9b1f9929f5265023d05c5a))
+# [3.3.0](https://github.com/abdelrahmannasr/yadflow/compare/v3.2.0...v3.3.0) (2026-06-30)
 
 
 ### Features
 
-* **review:** add yad-pair-review — guided two-way teaching walkthrough ([337cf9a](https://github.com/abdelrahmannasr/yadflow/commit/337cf9a0814f79f411db13a59af9afbdb64cf57d))
+* **next:** surface build-half sub-steps in yad next ([603b129](https://github.com/abdelrahmannasr/yadflow/commit/603b1294194e436c35de842bc687ccb4f51c2075))
 
 # [2.2.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.1.0...v2.2.0) (2026-06-14)
 

package/cli/epic-state.mjs

@@ -4,7 +4,7 @@
 import path from 'node:path';
 import { createHash } from 'node:crypto';
 import fs from 'node:fs';
-import { readJSONStrict, writeJSON, fileSha } from './lib.mjs';
+import { readJSON, readJSONStrict, writeJSON, fileSha } from './lib.mjs';
 import { err } from './errors.mjs';
 import { epicFiles } from './manifest.mjs';
 
@@ -147,6 +147,18 @@ function validateState(state, file) {
   return state;
 }
 
+// Every build-state/<story>.json under the epic, story-sorted. Missing dir = the build half hasn't
+// started yet, a normal state → []. The per-story files drive `yad next`'s build sub-step guidance —
+// advisory, read-only hints, NOT a source-of-truth ledger. So a corrupt file is skipped (non-throwing
+// `readJSON`), not fatal: `yad next` (and especially the all-epics roll-up) must still orient the user
+// even if one story's hint file is broken, rather than aborting the whole command.
+function loadBuildStates(dir) {
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir).filter((f) => f.endsWith('.json')).sort()
+    .map((f) => readJSON(path.join(dir, f), null))
+    .filter((bs) => bs && typeof bs === 'object' && !Array.isArray(bs));
+}
+
 export function loadLedger(epicDir) {
   const f = epicFiles(epicDir);
   return {
@@ -156,6 +168,7 @@ export function loadLedger(epicDir) {
     comments: requireArray(readJSONStrict(f.comments, []), f.comments),
     hubPrs: requireArray(readJSONStrict(f.hubPrs, []), f.hubPrs),
     contractLock: readJSONStrict(f.contractLock, null),
+    buildStates: loadBuildStates(f.buildStateDir),
   };
 }
 
@@ -315,6 +328,74 @@ export const STEP_SKILL = {
   'test-cases': 'yad-test-cases',
 };
 
+// The skill that runs each BACK-half (build) step — the build-state analogue of STEP_SKILL. `spec`
+// and `tasks` are the two legs of the SAME yad-spec ceremony (run-loop.md), so both map to yad-spec;
+// the chain renderer collapses the consecutive duplicate. `engineer-review` is the human merge gate.
+export const BUILD_STEP_SKILL = {
+  spec: 'yad-spec',
+  tasks: 'yad-spec',
+  implement: 'yad-implement',
+  checks: 'yad-checks',
+  'engineer-review': 'yad-engineer-review',
+};
+
+// The fixed back-half order. Used to derive the "remaining chain" from the active step onward even if a
+// repo's `steps` array is partial or out of order.
+const BUILD_STEP_ORDER = ['spec', 'tasks', 'implement', 'checks', 'engineer-review'];
+
+// Collapse consecutive identical skills (spec+tasks → one yad-spec) so the rendered chain reads
+// yad-spec → yad-implement → yad-checks → yad-engineer-review, matching the build-half mental model.
+// Folds against the last KEPT element (not the raw neighbor) so a dropped null between duplicates can't
+// reintroduce one.
+function dedupeConsecutive(skills) {
+  const out = [];
+  for (const s of skills) if (s && s !== out[out.length - 1]) out.push(s);
+  return out;
+}
+
+// PURE: given ONE repo's build-state ({ currentStep, steps }), resolve the next build sub-step and the
+// remaining chain. The active step is `currentStep`'s entry, or the first step not yet `done`. Returns
+// `shipped: true` only when there ARE steps and every one is `done`; an empty/missing steps array is
+// `unknown` (not-started), NEVER shipped — otherwise a half-seeded file would render a false "shipped ✓".
+export function buildNextForRepo(repoState = {}) {
+  const steps = Array.isArray(repoState.steps) ? repoState.steps : [];
+  const byId = new Map(steps.map((s) => [s.id, s]));
+  // Empty/half-seeded file ⇒ unknown (not-started), NEVER shipped. Every step done ⇒ shipped.
+  if (!steps.length) {
+    return { step: null, status: 'unknown', shipped: false, skill: null, automation: null, locked: false, chain: [] };
+  }
+  if (steps.every((s) => s.status === 'done')) {
+    return { step: null, status: 'done', shipped: true, skill: null, automation: null, locked: false, chain: [] };
+  }
+  // Active = the orchestrator's currentStep when it isn't already done, else the first not-done step
+  // (guaranteed to exist here — not every step is done). currentStep authority, with a done-step skip.
+  const cur = byId.get(repoState.currentStep);
+  const active = cur && cur.status !== 'done' ? cur : steps.find((s) => s.status !== 'done');
+  // The remaining chain: the active step + every later step in the canonical order, mapped to skills.
+  const from = BUILD_STEP_ORDER.indexOf(active.id);
+  const tail = from === -1 ? [active.id] : BUILD_STEP_ORDER.slice(from);
+  const chain = dedupeConsecutive(tail.map((id) => BUILD_STEP_SKILL[id] || null));
+  return {
+    step: active.id,
+    status: active.status || 'blocked',
+    automation: active.automation || 'human_approve',
+    locked: !!active.locked,
+    skill: BUILD_STEP_SKILL[active.id] || null,
+    shipped: false,
+    chain,
+  };
+}
+
+// PURE: map every parsed build-state object → its per-repo next sub-steps. `buildStates` is the array
+// `loadLedger` reads from build-state/*.json. Repos are sorted for a stable, machine-independent order.
+export function buildNextActions(buildStates = []) {
+  return buildStates.map((bs) => ({
+    story: bs.story || null,
+    repos: Object.keys(bs.repos || {}).sort()
+      .map((repo) => ({ repo, ...buildNextForRepo(bs.repos[repo]) })),
+  }));
+}
+
 // 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`
@@ -374,13 +455,29 @@ export function nextAction(ledger, { epic } = {}) {
   const parallel = tcOpen ? { step: 'test-cases', skill: STEP_SKILL['test-cases'], artifact: tc.artifact } : null;
 
   if (state.currentStep === 'ready-for-build') {
+    // Once stories enter the build half, surface each story/repo's CONCRETE next sub-step (spec →
+    // implement → checks → engineer-review) from build-state, not one static "run the build half" hint.
+    const builds = buildNextActions(ledger?.buildStates || []);
+    const lanes = builds.flatMap((b) => b.repos);
+    const open = lanes.filter((r) => !r.shipped);
+    if (builds.length) {
+      let why;
+      if (!lanes.length) why = 'build half started — no repo lanes recorded yet';
+      else if (!open.length) why = 'build half — every story/repo lane is shipped';
+      else why = `build half in progress — ${open.length} story/repo lane(s) still moving`;
+      return { epicId, kind: 'build', step: 'ready-for-build', status: 'ready-for-build', parallel, builds, why };
+    }
     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) {
+    const builds = buildNextActions(ledger?.buildStates || []);
+    return { epicId, kind: 'build', step: 'ready-for-build', parallel,
+      builds: builds.length ? builds : undefined, why: 'all front steps are done' };
+  }
 
   if (step.type === 'author') {
     return { epicId, kind: 'author', step: step.id, status: step.status, parallel,

package/cli/manifest.mjs

@@ -170,6 +170,8 @@ export const epicFiles = (epicRoot) => ({
   hubPrs: `${epicRoot}/.sdlc/hub-prs.json`,
   contractLock: `${epicRoot}/.sdlc/contract-lock.json`,
   buildLog: `${epicRoot}/.sdlc/build-log.json`,
+  buildStateDir: `${epicRoot}/.sdlc/build-state`,       // Phase 4 — per-story, per-repo back-half state
+
   change: `${epicRoot}/.sdlc/change.json`,             // Phase 6 — change/defect intake + triage
   reconcileDebt: `${epicRoot}/.sdlc/reconcile-debt.json`, // Phase 6 — hotfix ship-first debt
 });

package/cli/next.mjs

@@ -1,7 +1,9 @@
 // `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 31 skills / gate commands comes next. "Guide, don't act" — the
-// front half still never auto-advances.
+// front half still never auto-advances. Once an epic is `ready-for-build`, it reads each story's
+// build-state and prints the next BUILD sub-step per repo (spec → tasks → implement → checks → engineer-review)
+// plus the remaining chain — so the build half is guided too, not just hinted at.
 //
 //   yad next                  general orientation across the whole project
 //   yad next <epic>           the single next action for one epic
@@ -35,6 +37,36 @@ function listEpics(root) {
     .sort();
 }
 
+// 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)';
+
+// Every per-repo lane across the build, flattened with its story id attached.
+const buildLanes = (builds = []) => builds.flatMap((b) => b.repos.map((r) => ({ ...r, story: b.story })));
+
+// The dial note for a build lane: a machine_advance lane is driven by yad-run; everything else stops
+// for a human (the locked engineer-review always does).
+function dialNote(r) {
+  if (r.locked) return c.dim('human merge gate');
+  return r.automation === 'machine_advance'
+    ? c.dim('machine_advance — yad-run auto-drives')
+    : c.dim('human_approve');
+}
+
+// The detailed per-story/per-repo build lanes for `printAction`. Each open lane is a 2-line block:
+// a header naming the active step + dial, then the actionable `▸` skill line with the remaining chain.
+function printBuildLanes(builds) {
+  for (const lane of buildLanes(builds)) {
+    const where = `${c.cyan(lane.story || '(story)')} / ${c.bold(lane.repo)}`;
+    if (lane.shipped) { log(`    ${where} ${c.green('— shipped ✓')}`); continue; }
+    // No resolvable next skill (an empty/half-seeded build-state file): show it as not-started, no ▸.
+    if (!lane.skill) { log(`    ${where} ${c.dim('— not started yet (no build steps recorded)')}`); continue; }
+    log(`    ${where} ${c.dim('—')} ${c.bold(lane.step)}  (${dialNote(lane)})`);
+    const rest = (lane.chain || []).slice(1);
+    const then = rest.length ? `   ${c.dim(`then → ${rest.join(' → ')}`)}` : '';
+    hand(`invoke the ${c.bold(lane.skill)} skill${then}`);
+  }
+}
+
 // A short, copy-pasteable line for one action — the `▸` line a user can act on directly.
 function actionLine(a, { solo } = {}) {
   switch (a.kind) {
@@ -45,8 +77,18 @@ function actionLine(a, { solo } = {}) {
     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':
+    case 'build': {
+      // In the build half: compact the lanes to "N lane(s) in build — next: <skill> @ <story>/<repo>".
+      if (a.builds?.length) {
+        const open = buildLanes(a.builds).filter((r) => !r.shipped);
+        if (!open.length) return c.dim('build half — every lane shipped');
+        // Headline the first lane with a resolvable next skill; if none, the half is started but unspecced.
+        const first = open.find((r) => r.skill);
+        if (!first) return c.dim(`${open.length} lane(s) in build — not specced yet`);
+        return `${c.dim(`${open.length} lane(s) in build — next:`)} ${c.bold(first.skill)} ${c.dim(`@ ${shortStory(first.story)}/${first.repo}`)}`;
+      }
       return `${c.bold('yad-run')} ${c.dim('(or per story: yad-spec → yad-implement → yad ship → yad-engineer-review)')}`;
+    }
     case 'discovery-done':
       return `invoke the ${c.bold('yad-epic')} skill ${c.dim('(seed a feature epic from roadmap.md)')}`;
     default:
@@ -57,7 +99,10 @@ function actionLine(a, { solo } = {}) {
 // 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 }));
+  // In the build half with live lanes, print each story/repo's next sub-step + remaining chain instead
+  // of the single static hint; otherwise the one actionable line.
+  if (a.kind === 'build' && a.builds?.length) printBuildLanes(a.builds);
+  else 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})`)}`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yadflow",
-  "version": "3.2.0",
+  "version": "3.3.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 + 34 yad-* skills.",
   "type": "module",
   "author": "AbdelRahman Nasr",

package/skills/yad-epic/references/state-schema.md

@@ -184,6 +184,11 @@ Each `steps[]` entry:
 created when a story enters the build half; all dials start `human_approve` (the `config.yaml`
 `automation.default`).
 
+`yad next` reads these files too: once an epic is `ready-for-build`, `yad next <epic>` resolves each
+story/repo's `currentStep` into the next build sub-step (`spec`/`tasks` → `yad-spec`, `implement` →
+`yad-implement`, `checks` → `yad-checks`, `engineer-review` → `yad-engineer-review`) and prints it with
+the remaining chain and the step's automation dial — so the build half is guided, not just hinted at.
+
 ## `trust-log.json`
 Append-only ledger (an array), the back-half analogue of `approvals.json`. **This is the evidence
 base** that decides when a step is safe to automate (build plan Step A). One entry per step run:

package/skills/yad-run/SKILL.md

@@ -35,6 +35,9 @@ signal to seed them from, so they are earned only on real runs.
   `../yad-epic/references/state-schema.md`.
 - The orchestrator **calls the existing step skills unchanged** — `yad-spec` (A), `yad-implement`
   (B), `yad-checks` (C). It owns only the *advance decision*, never what a step does.
+- To see (read-only, without driving the loop) the next build sub-step per story/repo, use
+  `yad next <epic>` — it reads the same `build-state/<story-id>.json` and prints the next sub-step plus
+  the remaining chain and the automation dial.
 
 ## Inputs
 

package/skills/yad-status/SKILL.md

@@ -67,7 +67,9 @@ Print, in this order:
    each such story and each of its repos print the back-half chain
    `spec → tasks → implement → checks → engineer-review`, marking each step's `status`, its
    `automation` dial, and `locked`. Mark that repo's `currentStep` with `→`. This shows, at a glance,
-   which back steps are automated and where a run is waiting.
+   which back steps are automated and where a run is waiting. (For the single *next* build sub-step to
+   take per story/repo — rather than this full status view — point the user at `yad next <epic>`, which
+   reads the same `build-state` files.)
 8. **Automation & trust** — print the system-wide **kill switch** state from `config.yaml`
    `automation.kill_switch` (when `on`, note that every step is forced to `human_approve`). Then, for
    each back-half step that has entries in `.sdlc/trust-log.json`, print its **trust record**: number