yadflow 3.1.0 → 3.3.0

package/CHANGELOG.md

@@ -1,18 +1,9 @@
-# [3.1.0](https://github.com/abdelrahmannasr/yadflow/compare/v3.0.0...v3.1.0) (2026-06-30)
-
-
-### Bug Fixes
-
-* **bridge:** harden reviewer routing on GitHub + GitLab ([8d9cf24](https://github.com/abdelrahmannasr/yadflow/commit/8d9cf24c10adf1403959fa44a30fd13f7b362fb9))
-* **review:** address PR [#89](https://github.com/abdelrahmannasr/yadflow/issues/89) code review (bridge/companion robustness) ([4864fae](https://github.com/abdelrahmannasr/yadflow/commit/4864fae0cb7131948509dc6786eae9eb18c80497)), closes [#15](https://github.com/abdelrahmannasr/yadflow/issues/15)
+# [3.3.0](https://github.com/abdelrahmannasr/yadflow/compare/v3.2.0...v3.3.0) (2026-06-30)
 
 
 ### Features
 
-* **cli:** install newly-added skills on `yad update` ([872b92c](https://github.com/abdelrahmannasr/yadflow/commit/872b92ce1ce2ff5e8154add48b6ebdfef0d87cd4))
-* **review:** add the Review Companion (front half) ([d45bf23](https://github.com/abdelrahmannasr/yadflow/commit/d45bf239fa27a7b84cba409a7fdc23f64f99753d))
-* **review:** config switch, pr-template tolerance, and docs for the companion ([13aafcd](https://github.com/abdelrahmannasr/yadflow/commit/13aafcd6f359d6a0c7c39c53f01fd75357ba6aeb))
-* **review:** extend the companion + bridge to the back half (code PRs) ([1711ca9](https://github.com/abdelrahmannasr/yadflow/commit/1711ca9753f5eb67fad3fa5c828733e45ca9686f))
+* **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/README.md

@@ -66,6 +66,19 @@ Every step stops at a gate until a human approves. New here? **Walk it lesson-by
 - **Everything is files.** State, approvals, the contract lock, the build log — all plain files under
   `epics/EP-<slug>/`. No database. The audit trail *is* the repo.
 
+## Review, made a pairing — and a lesson
+
+Reviewing AI-generated code is where governance lives or dies, so Yadflow makes the honest review the
+*easiest* path — and, optionally, a **teaching** one. The **Review Companion** turns a PR/MR into a
+60-second trailer, swipe-through cards, and a grounded chat. On top of it, **Pair Review**
+(`yad pair-review`) runs a guided, two-way walkthrough: the AI walks the engineer through the change
+**one risk-ordered stop at a time**, explains each change in depth, then **asks them about it**; the
+engineer answers and asks back, until **both are satisfied**. The session doubles as a lesson — it
+demonstrates a transferable review method, scores the engineer against it, and records their review-skill
+growth in a **private, local-only** learning log (`yad status` rolls it up). It's **soft and additive**:
+it never blocks a merge, it rides the same `engagement: verified` signal, and any genuine concern it
+surfaces blocks like a normal review comment.
+
 ## Who it's for
 
 Tech leads and engineering managers who want their team to move fast with AI **without** giving up
@@ -78,7 +91,7 @@ development, not another code generator.
 - **[Terminology & workflow report](https://abdelrahmannasr.github.io/yadflow/)** — every term, artifact, gate, and skill on one illustrated page.
 - **[TEAM-GUIDE.md](TEAM-GUIDE.md)** — the short, plain-language version for a developer team.
 - **[docs/CLI.md](docs/CLI.md)** — the full `yad` command reference, the PR-driven gate, and `yad doctor` codes.
-- **[docs/SKILLS.md](docs/SKILLS.md)** — the catalogue of all 34 agent skills.
+- **[docs/SKILLS.md](docs/SKILLS.md)** — the catalogue of all 36 agent skills.
 - **[docs/WALKTHROUGH.md](docs/WALKTHROUGH.md)** — the by-hand, end-to-end path through every phase.
 - **[CONTRIBUTING.md](CONTRIBUTING.md)** · **[RESEARCH-NOTES.md](RESEARCH-NOTES.md)** · **[RELEASING.md](RELEASING.md)**
 

package/bin/yad.mjs

@@ -4,11 +4,11 @@ import { VERSION } from '../cli/manifest.mjs';
 import { c, log, closePrompts } from '../cli/lib.mjs';
 import { runSetup } from '../cli/setup.mjs';
 import { reconcile } from '../cli/reconcile.mjs';
-import { gateOpen, gateSync, gateComments, gateStatus, gateCi, gateReview, gateTrailer } from '../cli/gate.mjs';
+import { gateOpen, gateSync, gateComments, gateStatus, gateCi, gateReview, gateTrailer, gateWalkthrough } from '../cli/gate.mjs';
 import { isValidEpicId } from '../cli/epic-state.mjs';
 import { runCommit } from '../cli/commit.mjs';
 import { runOpenPr } from '../cli/openpr.mjs';
-import { reviewTrailer, reviewContext, reviewNudge, reviewReconcile } from '../cli/review.mjs';
+import { reviewTrailer, reviewContext, reviewNudge, reviewReconcile, reviewWalkthrough } from '../cli/review.mjs';
 import { runShip } from '../cli/ship.mjs';
 import { runRepo } from '../cli/repo.mjs';
 import { runRoster } from '../cli/roster.mjs';
@@ -55,6 +55,8 @@ ${c.bold('Review gate (front half)')}
   yad gate status <epic>               Show each review step + approvals
   yad gate review <epic> [artifact]    Print the grounding bundle for the review companion
                                        (artifact + risk + contract + PR + code-maps) — fun, easy review
+  yad gate walkthrough <epic> [artifact]  Grounding bundle + ordered risk-tagged stops for the
+                                       pair-review walkthrough (yad-pair-review) — guided, teaching review
   yad gate trailer <epic> [artifact] --body <text> [--pr <n>]
                                        Upsert the companion's 60-sec briefing into the PR/MR description
   yad gate ci [--branch <head>] [--pr <n>] [--merged]
@@ -69,6 +71,8 @@ ${c.bold('Build helpers')}
   yad ship --type <t> -m <subject>     Commit AND open the task PR/MR in one step (stage-aware)
   yad review trailer --repo <r> --pr <n> --body <text>   Post the companion's 60-sec briefing to a code PR/MR
   yad review context --repo <r> --pr <n>                  Print the grounding bundle for cards/chat
+  yad review walkthrough --repo <r> --pr <n>              Bundle + ordered risk-tagged stops for the
+                                                          pair-review walkthrough (yad-pair-review)
   yad review nudge --repo <r> --pr <n>                    Friendly @-mention on a bare code-PR approve
   yad review reconcile --epic <id> --repo <r> --pr <n>    Bridge: stamp engagement onto the build-log ship
   yad repo list                        Show connected repos (fresh / stale)
@@ -194,7 +198,7 @@ async function main() {
       const [, action, epic, artifact] = o._;
       // `gate ci` takes no positionals — epic/artifact come from --branch (or a sweep of all PRs).
       if (action === 'ci') { await gateCi(o.dir, { branch: o.branch, pr: o.pr, merged: o.merged, push: !o.noPush, today }); break; }
-      if (!epic) { log(c.red('usage: yad gate <open|sync|comments|status|review|trailer|ci> <epic> [artifact]')); process.exitCode = 1; break; }
+      if (!epic) { log(c.red('usage: yad gate <open|sync|comments|status|review|walkthrough|trailer|ci> <epic> [artifact]')); process.exitCode = 1; break; }
       // The epic id becomes a path segment under epics/ — reject anything but EP-<slug> outright.
       if (!isValidEpicId(epic)) { log(c.red(`invalid epic id: ${epic} (expected EP-<slug>, [a-z0-9-] only)`)); process.exitCode = 1; break; }
       // In bridge mode CI is the sole ledger writer: `open` only opens the PR, and local `sync` is
@@ -205,21 +209,23 @@ async function main() {
       else if (action === 'comments') await gateComments(o.dir, { epic, artifact, today });
       else if (action === 'status') await gateStatus(o.dir, { epic });
       else if (action === 'review') await gateReview(o.dir, { epic, artifact });
+      else if (action === 'walkthrough') await gateWalkthrough(o.dir, { epic, artifact });
       else if (action === 'trailer') await gateTrailer(o.dir, { epic, artifact, body: o.body || o.message, number: o.pr });
-      else { log(c.red(`unknown gate action: ${action} (open|sync|comments|status|review|trailer|ci)`)); process.exitCode = 1; }
+      else { log(c.red(`unknown gate action: ${action} (open|sync|comments|status|review|walkthrough|trailer|ci)`)); process.exitCode = 1; }
       break;
     }
     case 'review': {
       const [, action] = o._;
       if (action === 'trailer') await reviewTrailer(o.dir, { repo: o.repo, pr: o.pr, body: o.body || o.message });
       else if (action === 'context' || action === 'chat' || action === 'cards') await reviewContext(o.dir, { repo: o.repo, pr: o.pr });
+      else if (action === 'walkthrough') await reviewWalkthrough(o.dir, { repo: o.repo, pr: o.pr });
       else if (action === 'nudge') await reviewNudge(o.dir, { repo: o.repo, pr: o.pr });
       else if (action === 'reconcile') {
         // The epic becomes a path segment under epics/ — reject anything but EP-<slug> (no `../` escape).
         if (!o.epic || !isValidEpicId(o.epic)) { log(c.red(`invalid or missing --epic: ${o.epic ?? '(none)'} (expected EP-<slug>, [a-z0-9-] only)`)); process.exitCode = 1; break; }
         await reviewReconcile(o.dir, { epic: o.epic, repo: o.repo, pr: o.pr });
       }
-      else { log(c.red('usage: yad review <trailer|context|nudge|reconcile> --repo <name> --pr <n> [--epic <id>] [--body <text>]')); process.exitCode = 1; }
+      else { log(c.red('usage: yad review <trailer|context|walkthrough|nudge|reconcile> --repo <name> --pr <n> [--epic <id>] [--body <text>]')); process.exitCode = 1; }
       break;
     }
     case 'commit':

package/cli/companion.mjs

@@ -59,3 +59,32 @@ export function nudgeMessage(login, cmd = 'yad gate review') {
   const who = login ? `@${login}` : 'there';
   return noBlock(`Thanks ${who} for the quick approval 🙏 — mind running \`${cmd}\`? It won't take long, and a real read has way more impact than the few minutes it costs 💛`);
 }
+
+// ---- pair review (yad-pair-review) --------------------------------------------------------------
+// The pair-review walkthrough records its session as a PERMANENT PR/MR comment: the transcript summary,
+// the review-skill scorecard, and BOTH sign-offs. It carries this marker so a recorded pair session is
+// IDENTIFIABLE in platform history (the skill / `yad status` can recognise + count paired reviews for the
+// 🏆 roll-up), AND the noblock marker so the session thread never holds the gate. The human's actual
+// approval still rides the existing `<!-- yad:engagement verified -->` mark — the session comment NEVER
+// carries an engagement marker (it is history, not the approval). `isPair` is the marker's public reader,
+// symmetrical with `isNoBlock`; the engagement roll-up itself lives in the local yad-learn ledger.
+export const PAIR_MARK = '<!-- yad:pair -->';
+
+// True when a comment is a recorded pair-review session (countable, but never blocking).
+export function isPair(body) {
+  return typeof body === 'string' && body.includes(PAIR_MARK);
+}
+
+// Render the pair-review session-record comment. The skill generates each prose section; this composes
+// them into one comment carrying both the pair marker (countable) and the noblock marker (never blocks).
+export function pairSessionBody({ summary = '', scorecard = '', verdict = '', humanSignoff = '', aiSignoff = '' } = {}) {
+  const parts = [
+    PAIR_MARK,
+    '## 🤝 Pair review session',
+    summary && summary.trim(),
+    scorecard && `### Review-skill scorecard\n${scorecard.trim()}`,
+    verdict && `### AI verdict\n${verdict.trim()}`,
+    (humanSignoff || aiSignoff) && `### Sign-off\n- 🧑 Human: ${humanSignoff || '—'}\n- 🤖 AI: ${aiSignoff || '—'}`,
+  ].filter(Boolean);
+  return noBlock(parts.join('\n\n'));
+}

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

@@ -5,7 +5,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import {
-  c, log, ok, info, warn, hand, fail, readJSONStrict, writeJSON, run,
+  c, log, ok, info, warn, hand, fail, note, readJSONStrict, writeJSON, run,
 } from './lib.mjs';
 import { PROJECT_FILES } from './manifest.mjs';
 import {
@@ -18,6 +18,7 @@ import {
   getPrBody, editPrBody, postComment,
 } from './platform.mjs';
 import { isNoBlock, upsertTrailerBlock, nudgeMessage, parseEngagement } from './companion.mjs';
+import { sequenceDiff } from './walkthrough.mjs';
 import { syncStatuses } from './artifact-status.mjs';
 import { err } from './errors.mjs';
 
@@ -556,11 +557,14 @@ export async function gateOpen(root, { epic, artifact, head, creator = createPr
 // to generate the 60-sec trailer / swipe cards and to run the grounded chat (artifact + risk tags +
 // contract + PR + repo code-maps). The CLI never calls an LLM; the skill (yad-review-companion)
 // consumes this JSON, generates, and posts back via the platform (trailer/comments/approval).
-export async function gateReview(root, { epic, artifact } = {}) {
+// Build (but don't print) the front-half grounding bundle. Shared by `review` and `walkthrough` so the
+// pair walkthrough adds an ordered stop-list on top of the exact same grounding the companion uses.
+// Returns { error } when there is no epic state, else { bundle, epicDir, hub }.
+function reviewBundle(root, { epic, artifact } = {}) {
   const { hub, repos } = loadHub(root);
   const epicDir = epicRoot(root, epic);
   const ledger = loadLedger(epicDir);
-  if (!ledger.state) { fail(`no epic state at ${epicDir}`); process.exitCode = 1; return; }
+  if (!ledger.state) return { error: `no epic state at ${epicDir}` };
   const pr = (ledger.hubPrs || []).find((p) => !artifact || p.artifact === artifact) || null;
   const art = artifact || pr?.artifact || null;
   const step = art ? findReviewStep(ledger.state, art) : null;
@@ -578,10 +582,44 @@ export async function gateReview(root, { epic, artifact } = {}) {
       codeMap: r.name ? path.join(root, '.sdlc/code-context', r.name, 'code-map.md') : null,
     })),
     requireEngagement: requireEngagement(hub),
-    markers: { trailerBegin: '<!-- yad:trailer -->', noblock: '<!-- yad:noblock -->', engagementVerified: '<!-- yad:engagement verified -->' },
+    markers: {
+      trailerBegin: '<!-- yad:trailer -->', noblock: '<!-- yad:noblock -->',
+      engagementVerified: '<!-- yad:engagement verified -->', pair: '<!-- yad:pair -->',
+    },
   };
-  log(JSON.stringify(bundle, null, 2));
-  return bundle;
+  return { bundle, epicDir, hub };
+}
+
+export async function gateReview(root, { epic, artifact } = {}) {
+  const r = reviewBundle(root, { epic, artifact });
+  if (r.error) { fail(r.error); process.exitCode = 1; return; }
+  log(JSON.stringify(r.bundle, null, 2));
+  return r.bundle;
+}
+
+// `yad gate walkthrough <epic> [artifact]` — the front-half pair-review grounding: the same bundle PLUS
+// an ordered `stops[]` from the artifact's review diff (highest-risk first). The skill (yad-pair-review)
+// walks the stops and runs the two-way teaching session. Deterministic sequencing only — no LLM here.
+export async function gateWalkthrough(root, { epic, artifact, runner = run } = {}) {
+  const r = reviewBundle(root, { epic, artifact });
+  if (r.error) { fail(r.error); process.exitCode = 1; return; }
+  const { bundle, hub } = r;
+  const defaultBranch = hub?.default_branch || 'main';
+  let stops = [];
+  if (bundle.artifactPath) {
+    const rel = path.relative(root, bundle.artifactPath) || bundle.artifact;
+    const diff = runner('git', ['-C', root, 'diff', `${defaultBranch}...HEAD`, '--', rel]);
+    if (diff.ok && diff.stdout.trim()) {
+      stops = sequenceDiff(diff.stdout, { contractPath: bundle.contractPath });
+    } else if (!diff.ok) {
+      note(`could not read the artifact diff (${defaultBranch}...HEAD) in ${root} — is the review branch checked out and the base correct?`);
+    }
+  }
+  const out = { ...bundle, stops };
+  log(JSON.stringify(out, null, 2));
+  // Diagnostics to STDERR so STDOUT stays pure JSON (the skill / e2e parse it).
+  if (!stops.length) note('no stops from the artifact diff — walk the artifact by section (see yad-pair-review)');
+  return out;
 }
 
 // `yad gate trailer <epic> [artifact] --body <text> [--pr <n>]` — the skill generates the 60-second

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}`);
+// Like `info`, but to STDERR — for diagnostics emitted by commands whose STDOUT must stay pure (e.g. a
+// JSON bundle a tool parses). Keeps the human hint visible without corrupting machine-readable output.
+export const note = (s) => console.error(`  ${c.dim('•')} ${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)}`); };

package/cli/manifest.mjs

@@ -42,6 +42,7 @@ export const SKILLS = [
   'yad-run',
   'yad-review-gate',
   'yad-review-companion',
+  'yad-pair-review',
   'yad-status',
   'yad-change',
   'yad-timeline',
@@ -169,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/cli/review.mjs

@@ -6,13 +6,14 @@
 // The CLI never calls an LLM: the skill (yad-review-companion / yad-engineer-review) generates the
 // trailer/cards/chat text and posts it via these primitives, all to the PLATFORM (never a ledger file).
 import path from 'node:path';
-import { log, ok, info, warn, fail, run, readJSON, writeJSON } from './lib.mjs';
+import { log, ok, info, warn, fail, note, run, readJSON, writeJSON } from './lib.mjs';
 import { PROJECT_FILES, epicFiles } from './manifest.mjs';
 import { epicRoot } from './epic-state.mjs';
 import {
   detectPlatform, readPr, mapApprovers, getPrBody, editPrBody, postComment, prNumberFromUrl,
 } from './platform.mjs';
 import { upsertTrailerBlock, nudgeMessage, parseEngagement } from './companion.mjs';
+import { sequenceDiff } from './walkthrough.mjs';
 
 const NUDGE_CMD = 'yad review chat';
 
@@ -35,11 +36,12 @@ function platformOf(root, repoRoot, meta) {
   return detectPlatform(remote) || readJSON(path.join(root, PROJECT_FILES.hubConfig), {}).platform || null;
 }
 
-// `yad review context --repo <r> --pr <n>` — print the grounding bundle the companion uses to generate
-// the trailer / cards and run the chat over the CODE diff (grounded in the repo code-map + the PR).
-export async function reviewContext(root, { repo, dir, pr } = {}) {
+// Build (but don't print) the back-half grounding bundle. Shared by `context` and `walkthrough` so the
+// pair walkthrough adds an ordered stop-list on top of the exact same grounding the companion uses.
+// Returns { error } on a bad --repo, else { bundle, repoRoot, base }.
+function contextBundle(root, { repo, dir, pr } = {}) {
   const rr = resolveRepo(root, { repo, dir });
-  if (rr.error) { fail(rr.error); process.exitCode = 1; return; }
+  if (rr.error) return { error: rr.error };
   const { repoRoot, meta } = rr;
   const platform = platformOf(root, repoRoot, meta);
   const base = meta?.default_branch || 'main';
@@ -52,10 +54,41 @@ export async function reviewContext(root, { repo, dir, pr } = {}) {
     diffCmd: `git -C ${repoRoot} diff ${base}...HEAD`,
     codeMap: meta?.name ? path.join(root, '.sdlc/code-context', meta.name, 'code-map.md') : null,
     pack: meta?.name ? path.join(root, '.sdlc/code-context', meta.name, 'pack.md') : null,
-    markers: { trailerBegin: '<!-- yad:trailer -->', noblock: '<!-- yad:noblock -->', engagementVerified: '<!-- yad:engagement verified -->' },
+    contract: meta?.contract || null,
+    markers: {
+      trailerBegin: '<!-- yad:trailer -->', noblock: '<!-- yad:noblock -->',
+      engagementVerified: '<!-- yad:engagement verified -->', pair: '<!-- yad:pair -->',
+    },
   };
-  log(JSON.stringify(bundle, null, 2));
-  return bundle;
+  return { bundle, repoRoot, base };
+}
+
+// `yad review context --repo <r> --pr <n>` — print the grounding bundle the companion uses to generate
+// the trailer / cards and run the chat over the CODE diff (grounded in the repo code-map + the PR).
+export async function reviewContext(root, { repo, dir, pr } = {}) {
+  const r = contextBundle(root, { repo, dir, pr });
+  if (r.error) { fail(r.error); process.exitCode = 1; return; }
+  log(JSON.stringify(r.bundle, null, 2));
+  return r.bundle;
+}
+
+// `yad review walkthrough --repo <r> --pr <n>` — the pair-review grounding: the same bundle PLUS an
+// ordered `stops[]` (the code diff parsed into hunk-anchored, risk-tagged review stops, highest-risk
+// first). The CLI sequences deterministically; the skill (yad-pair-review) walks the stops, generates
+// the per-stop briefing + Socratic question, and runs the two-way session. No LLM here, no ledger write.
+export async function reviewWalkthrough(root, { repo, dir, pr, runner = run } = {}) {
+  const r = contextBundle(root, { repo, dir, pr });
+  if (r.error) { fail(r.error); process.exitCode = 1; return; }
+  const { bundle, repoRoot, base } = r;
+  const diff = runner('git', ['-C', repoRoot, 'diff', `${base}...HEAD`]);
+  // Diagnostics go to STDERR so STDOUT stays pure JSON (the skill / e2e parse it). The empty `stops: []`
+  // in the bundle already signals "nothing to walk".
+  if (!diff.ok) note(`could not read the diff (${base}...HEAD) in ${repoRoot} — is the branch pushed and the base correct?`);
+  const stops = sequenceDiff(diff.ok ? diff.stdout : '', { contractPath: bundle.contract });
+  const out = { ...bundle, stops };
+  log(JSON.stringify(out, null, 2));
+  if (!stops.length) note('no stops — the diff is empty (nothing to walk through)');
+  return out;
 }
 
 // `yad review trailer --repo <r> --pr <n> --body <text>` — idempotently upsert the 60-sec briefing into

package/cli/walkthrough.mjs

@@ -0,0 +1,115 @@
+// cli/walkthrough.mjs — the deterministic diff SEQUENCER for the pair-review walkthrough
+// (yad-pair-review). Pure, no I/O, no LLM: it parses a unified `git diff` into ordered, hunk-anchored,
+// risk-tagged "stops" so the skill walks the change one stop at a time, highest-risk first, the same way
+// every time. The harness generates the prose for each stop; this only decides WHAT and IN WHICH ORDER.
+//
+// Risk tags reuse the same vocabulary as the review gate's escalation (contract / auth / payments — see
+// cli/epic-state.mjs isEscalated), plus a `tests` tag so the walkthrough can check that tests cover the
+// change (rubric step 5). The signal is a heuristic over file paths + hunk size — advisory, never a gate.
+
+// Path heuristics for the escalation domains + tests. Order matters only for readability; a path can
+// carry several tags.
+const RISK_PATTERNS = [
+  ['auth', /(^|[/_.-])(auth|authn|authz|login|logout|session|token|jwt|oauth|saml|password|passwd|credential|secret|permission|rbac|acl)([/_.-]|$)/i],
+  ['payments', /(^|[/_.-])(pay|payment|payout|billing|invoice|charge|stripe|paypal|checkout|wallet|refund|subscription|price|pricing|ledger)([/_.-]|$)/i],
+  ['contract', /(^|[/_.-])(contract|openapi|swagger|proto|graphql|schema|migration|migrations)([/_.-]|$)|\.(proto|sql|graphql|gql)$|(^|[/])(api|contracts?)[/]/i],
+  ['tests', /(^|[/_.-])(test|tests|spec|specs|__tests__|e2e|fixtures?)([/_.-]|$)|\.(test|spec)\.[a-z]+$/i],
+];
+
+// Relative weight used to order stops — the higher, the earlier it is walked. `tests` is intentionally
+// weightless (it's informative, not risky on its own).
+const RISK_WEIGHT = { contract: 4, auth: 3, payments: 3, tests: 0 };
+
+// The risk tags a file path carries. `contractPath` (when known) force-tags the locked contract surface
+// even if its path doesn't match the generic heuristics.
+export function riskTagsForPath(file, { contractPath } = {}) {
+  const f = String(file || '');
+  const tags = [];
+  for (const [tag, re] of RISK_PATTERNS) {
+    if (re.test(f)) tags.push(tag);
+  }
+  if (contractPath && (f === contractPath || f.endsWith(`/${contractPath}`) || contractPath.endsWith(`/${f}`))) {
+    if (!tags.includes('contract')) tags.unshift('contract');
+  }
+  return tags;
+}
+
+// The maximum risk weight across a stop's tags (0 when none) — the primary sort key.
+function weightOf(tags) {
+  return (tags || []).reduce((m, t) => Math.max(m, RISK_WEIGHT[t] || 0), 0);
+}
+
+// Parse the `+c,d` side of a hunk header `@@ -a,b +c,d @@`. `d` defaults to 1 when omitted (a one-line
+// hunk). Returns { startLine, endLine } in the NEW file, or null when the header doesn't parse.
+function parseHunkRange(header) {
+  const m = /@@\s+-\d+(?:,\d+)?\s+\+(\d+)(?:,(\d+))?\s+@@/.exec(header || '');
+  if (!m) return null;
+  const start = Number(m[1]);
+  const count = m[2] == null ? 1 : Number(m[2]);
+  return { startLine: start, endLine: count > 0 ? start + count - 1 : start };
+}
+
+// The file a `diff --git a/x b/y` line names. Use the new-side path (`b/`) so a rename is anchored to its
+// destination; fall back to the old side for a pure deletion.
+function fileFromDiffHeader(line) {
+  const m = /^diff --git a\/(.+?) b\/(.+)$/.exec(line);
+  if (!m) return null;
+  return m[2] || m[1];
+}
+
+// sequenceDiff(diffText, { contractPath }) -> ordered stops[].
+// Each stop: { file, hunkHeader, startLine, endLine, added, removed, riskTags[], order }.
+// A file with no hunks (binary, pure rename, mode-only change) still yields ONE stop so it's never
+// skipped silently. `order` is the 1-based position AFTER sorting (high-risk, then larger, first).
+export function sequenceDiff(diffText, { contractPath } = {}) {
+  const lines = String(diffText || '').split('\n');
+  const files = [];        // { file, hunks: [{ header, startLine, endLine, added, removed }] }
+  let cur = null;
+  let hunk = null;
+
+  const closeHunk = () => { if (cur && hunk) cur.hunks.push(hunk); hunk = null; };
+
+  for (const line of lines) {
+    if (line.startsWith('diff --git ')) {
+      closeHunk();
+      const file = fileFromDiffHeader(line);
+      cur = { file: file || '(unknown)', hunks: [] };
+      files.push(cur);
+      continue;
+    }
+    if (!cur) continue;                       // preamble before the first file header
+    if (line.startsWith('@@')) {
+      closeHunk();
+      const range = parseHunkRange(line) || { startLine: null, endLine: null };
+      hunk = { header: line.trim(), startLine: range.startLine, endLine: range.endLine, added: 0, removed: 0 };
+      continue;
+    }
+    if (!hunk) continue;                       // ---/+++/index/rename lines between header and first @@
+    // Inside a hunk every +/- line is CONTENT — the `+++ b/file` / `--- a/file` headers appear before
+    // the first @@ and are already skipped by the !hunk guard, so count on the marker char alone (a
+    // content line like `--flag` or `++i` must not be dropped).
+    if (line[0] === '+') hunk.added++;
+    else if (line[0] === '-') hunk.removed++;
+  }
+  closeHunk();
+
+  // Flatten to stops; a file with zero hunks becomes one zero-size stop.
+  const stops = [];
+  for (const f of files) {
+    const tags = riskTagsForPath(f.file, { contractPath });
+    if (f.hunks.length === 0) {
+      stops.push({ file: f.file, hunkHeader: null, startLine: null, endLine: null, added: 0, removed: 0, riskTags: tags });
+      continue;
+    }
+    for (const h of f.hunks) {
+      stops.push({ file: f.file, hunkHeader: h.header, startLine: h.startLine, endLine: h.endLine, added: h.added, removed: h.removed, riskTags: tags });
+    }
+  }
+
+  // Stable sort: highest risk weight first, then the larger change, then original order (index) so the
+  // result is deterministic for identical input.
+  return stops
+    .map((s, i) => ({ s, i, w: weightOf(s.riskTags), size: s.added + s.removed }))
+    .sort((a, b) => (b.w - a.w) || (b.size - a.size) || (a.i - b.i))
+    .map(({ s }, idx) => ({ ...s, order: idx + 1 }));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yadflow",
-  "version": "3.1.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/sdlc/config.yaml

@@ -71,6 +71,18 @@ review_gate:
   # stamp, it does not prove a human read the artifact). Persisted per-project in hub.json as
   # `review.requireEngagement`; companion comments carry `<!-- yad:noblock -->` so they never block.
   require_engagement: false
+  # Pair Review (yad-pair-review) — the guided, two-way, TEACHING walkthrough; the AI-driven 5th
+  # companion face. The AI walks the human through the change one risk-ordered stop at a time, asks
+  # Socratic questions, and both sign off when satisfied; the session doubles as a learning session and
+  # records the engineer's review-skill growth in the local-only yad-learn ledger. SOFT and additive —
+  # it NEVER blocks a merge or gate (no strict switch); it rides the same `engagement: verified` signal
+  # as the companion and surfaces genuine concerns as normal blocking comments. `mode: optional` is the
+  # default posture (offered, never required). The quiz/comprehension signal reuses learning.capabilities.
+  pair_review:
+    enabled: true
+    mode: optional              # optional | encouraged — never `required` (it can never gate)
+    never_blocks: true          # invariant: a pair session is advisory; the gate predicate is untouched
+    rubric: review-rubric.md    # the transferable review method (skills/yad-pair-review/references/)
 
 # Build half (Phase 3). Code repos are SEPARATE git repos (one .git each), not subfolders
 # of the product repo — faithful to "per-repo specs in each code repo, contract singular in the

package/skills/sdlc/install.sh

@@ -11,7 +11,7 @@ set -euo pipefail
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
 cd "$ROOT"
 
-SKILLS=(yad-discovery yad-analysis yad-epic yad-architecture yad-ui yad-stories yad-test-cases yad-connect-repos yad-sync-repos yad-connect-design yad-connect-testing yad-connect-learning yad-connect-docs yad-docs yad-docs-overview yad-docs-sync yad-learn yad-spec yad-implement yad-checks yad-pr-template yad-hub-bridge yad-commit yad-open-pr yad-ship yad-engineer-review yad-backfill yad-run yad-review-gate yad-status yad-change yad-timeline yad-defects yad-reconcile)
+SKILLS=(yad-discovery yad-analysis yad-epic yad-architecture yad-ui yad-stories yad-test-cases yad-connect-repos yad-sync-repos yad-connect-design yad-connect-testing yad-connect-learning yad-connect-docs yad-docs yad-docs-overview yad-docs-sync yad-learn yad-spec yad-implement yad-checks yad-pr-template yad-hub-bridge yad-commit yad-open-pr yad-ship yad-engineer-review yad-backfill yad-run yad-review-gate yad-review-companion yad-pair-review yad-status yad-change yad-timeline yad-defects yad-reconcile)
 
 # Skills removed in a later release: this installer only refreshes names still in SKILLS, so a
 # rerun would otherwise leave a dropped skill sitting in the IDE dirs. Purge any lingering copy

package/skills/sdlc/module-help.csv

@@ -4,6 +4,7 @@ SDLC Workflow,yad-analysis,Author Analysis,AN,"Optional front state: with the an
 SDLC Workflow,yad-epic,Author Epic,AE,"Front state 1: shape an idea with analyst then pm into epic.md; assign EP-<slug> ID and seed .sdlc state. Never auto-advances.",,{idea: one-line feature idea},1-front,,yad-review-gate,true,epics/EP-<slug>/,epic.md state.json
 SDLC Workflow,yad-review-gate,Team Review Gate,RG,"Reusable review+approve gate for all five reviews. Shares an artifact for review, records comments and approvals as files, enforces owner + 1 reviewer (escalates on contract/auth/payments; per-repo routing for stories), advances state only when approved.",,{artifact: file under the epic} {action: open|comment|approve|advance},1-front,,,true,epics/EP-<slug>/reviews/,reviews/*.md approvals.json state.json
 SDLC Workflow,yad-review-companion,Review Companion,RC,"Fun, easy, transparent review companion for the review gates (front gate AND back-half code PR). Generates a 60-sec AI trailer of what changed and where the risk is, deals swipe-through review cards, and runs a grounded chat where a reviewer's questions become the review record — then records an engagement signal on the approval (verified vs none) and posts a friendly public @-mention nudge on a bare rubber-stamp. Companion comments carry a noblock marker so they never hold the gate. Soft by default (visible, not impossible); gates only when hub.review.requireEngagement. Never auto-advances.",,{epic: EP-<slug>} {artifact} | {repo} {pr} {action: trailer|cards|chat|nudge},1-front,,,false,epics/EP-<slug>/reviews/ | code PR,trailer/cards/chat (platform) approvals.json engagement
+SDLC Workflow,yad-pair-review,Pair Review,PV,"The guided, two-way, teaching pair-review walkthrough — the AI-driven 5th companion face (front gate AND back-half code PR). The human opens a PR/MR with an AI session and the AI walks them through the change one stop at a time (highest-risk first), gives comprehensive context per change, then asks a Socratic question; the human answers and asks back until BOTH declare satisfied. Doubles as a learning session: demonstrates a transferable review method, scores the engineer, and records review-skill growth in the local-only yad-learn ledger (rolled up by yad status). Soft and additive — NEVER blocks; rides the engagement signal and surfaces genuine concerns as normal blocking comments. Never auto-advances.",,{epic: EP-<slug>} {artifact} | {repo} {pr} {member} {action: walkthrough|record|rubric},3-build,yad-review-companion,,false,epics/EP-<slug>/reviews/ | code PR | epics/EP-<slug>/learning/ (local-only),pair session (platform) learning-records.json learning/<member>--review-<pr>.md
 SDLC Workflow,yad-architecture,Author Architecture,AA,"Front state 3: with the architect author architecture.md and the locked contract.md; hash-lock the contract surface. Never auto-advances.",,{epic: EP-<slug>},1-front,yad-review-gate,yad-review-gate,true,epics/EP-<slug>/,architecture.md contract.md contract-lock.json state.json
 SDLC Workflow,yad-ui,Author UI Design,AU,"Front state 5: with the ux-designer author ui-design.md and DESIGN.md, driving Impeccable slash-commands when installed. Never auto-advances.",,{epic: EP-<slug>},1-front,yad-review-gate,yad-review-gate,true,epics/EP-<slug>/,ui-design.md DESIGN.md state.json
 SDLC Workflow,yad-stories,Author Stories,AS,"Front state 7: with the pm break the epic into repo-tagged stories with stable EP-<slug>-S0N IDs, one file each under stories/. Never auto-advances.",,{epic: EP-<slug>},1-front,yad-review-gate,yad-review-gate,true,epics/EP-<slug>/stories/,stories/EP-<slug>-S0N.md state.json

package/skills/yad-engineer-review/SKILL.md

@@ -45,6 +45,13 @@ chat from the bundle (`yad review context --repo <r> --pr <n>` → [yad-review-c
 Companion comments carry `<!-- yad:noblock -->` (history-only, never block); genuine concerns are posted
 unflagged and block normally.
 
+For a **deep, teaching** review instead of a skim, offer the **Pair Review** walkthrough
+([yad-pair-review](../yad-pair-review/SKILL.md)): `yad review walkthrough --repo <r> --pr <n>` deals an
+ordered, risk-tagged stop-list, and the AI walks the engineer through the change one stop at a time —
+asking questions, answering theirs, until both are satisfied — then records the engineer's review-skill
+growth in the local-only learning log. Still soft: it rides the same `engagement: verified` signal and
+never gates. When a pair session backs the approve, you may set `companion.pair: true` on the ship record.
+
 ### Step 2 — `approve` (the engineer review — the human gate)
 A human engineer reads the diff **against the spec** (`specs/<story>/`) and the acceptance criteria,
 and records an approval. Determine the rule from the PR's Impact & Risk block (run

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-pair-review/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: yad-pair-review
+description: 'The guided, two-way, teaching pair-review walkthrough for the SDLC review gates — the AI-driven companion face. The human opens a PR/MR with an AI session and the AI walks them through the change ONE STOP AT A TIME (highest-risk first), giving comprehensive context per change, then asking the human a Socratic question about it; the human answers and asks back, and both keep going until BOTH declare satisfied. The session doubles as a learning session: it demonstrates a transferable review method, scores the engineer against it, and records their review-skill growth in the local-only yad-learn ledger (rolled up by yad status). Works on the back-half code PR/MR (yad review) and the front-half artifact-review PR/MR (yad gate). Soft and additive — it NEVER blocks a merge or gate; it rides the existing engagement signal and surfaces genuine concerns as normal blocking comments. Use when the user says "pair review this", "walk me through the PR/MR", "review with me", "co-review", or "teach me to review".'
+---
+
+# SDLC — Pair Review (the guided, two-way, teaching walkthrough)
+
+**Goal:** turn a review from a solo skim into a **paired session** where the AI is the senior reviewer
+sitting beside a junior engineer. The AI **drives** the review change-by-change, explains each change in
+depth, then **asks the human about it** (flipping the companion's chat direction); the human answers and
+asks back; both keep answering **until both are satisfied**. The PR is the textbook, the walkthrough is
+the lesson — and the engineer walks away having *learned how to review a PR efficiently*, with that
+growth recorded in their personal learning log.
+
+This is the **fifth face** of the Review Companion — the AI-driven, bidirectional, teaching layer on top
+of [`yad-review-companion`](../yad-review-companion/SKILL.md) (Trailer / Cards / Chat / Social). The
+**gate still owns the predicate and advancement**; this skill only enriches the *input* and records the
+*engagement* + *learning* signals. Like the companion, **the CLI never calls an LLM — you (this skill)
+generate every briefing, question, and answer, grounded only in real material, and post via the
+platform.**
+
+> **Philosophy — "the review is the lesson, and laziness stays visible, not blocked."** Every signal here
+> is soft and gameable by design (same as the companion + learning layers). A pair session never proves a
+> human understood anything and never holds the gate; it makes a real review the *easiest, most useful*
+> path and turns it into mentorship. Say this openly — do not oversell it.
+
+## Conventions
+
+- `{project-root}` resolves from the project working directory — the **product hub**.
+- Back half (code PR/MR): grounded by `yad review walkthrough --repo <r> --pr <n>`.
+- Front half (artifact-review PR/MR): grounded by `yad gate walkthrough <epic> [artifact]`.
+- The transferable review method + scorecard live in `references/review-rubric.md`.
+- The session-record comment shape, the dual sign-off, and the learning record this writes live in
+  `references/session-state.md` (it reuses [`yad-learn`](../yad-learn/SKILL.md)'s ledger + gitignore
+  discipline **verbatim** — the learning output is **local-only, never committed or pushed**).
+- Speak in the configured `communication_language`; write any rendered tutorial in
+  `document_output_language`.
+
+## Inputs
+
+- Back half: `repo` + `pr`. Front half: `epic` + `artifact`.
+- `member` — the learner being paired with (default: the invoking user). Used for the learning record.
+- `action` — `walkthrough` (the full session, default) | `record` (just write the session comment +
+  learning record from an already-finished session) | `rubric` (print the review method and stop).
+
+## On Activation (`action: walkthrough`)
+
+### Step 1 — Get the ordered stops (the grounding)
+Run the walkthrough grounding for the half you're on:
+- Back half: `yad review walkthrough --repo <r> --pr <n>` → prints the grounding bundle **plus an ordered
+  `stops[]`** (the code diff parsed into hunk-anchored, risk-tagged review stops, highest-risk first).
+- Front half: `yad gate walkthrough <epic> [artifact]` → the same, over the artifact's review diff.
+
+**Read the real material yourself** — run the bundle's `diffCmd`, and read the named `codeMap` / `pack` /
+`contract` / `artifactPath` / `specs/<story>/` files. Never invent content. If a stop's material isn't
+available, say so at that stop (a gap is a finding — see Hard rules).
+
+### Step 2 — Set the frame (teach the method first)
+Briefly state the **review method** you'll both follow (from `references/review-rubric.md`): spec-first →
+contract-surface → high-risk hunks first → per-change correctness · tests · edge cases · security/auth/
+payments → tests-cover-the-change → decide. Tell the human you'll walk the change in that order and ask
+them to apply each step with you. This framing is the lesson scaffold.
+
+### Step 3 — Walk the stops, one at a time (the two-way loop)
+For **each stop in `stops[]` order** (highest-risk first):
+1. **Comprehensive briefing.** Explain *what* changed in this hunk, *why* (tie it to the spec / epic /
+   contract), *how it fits* the surrounding code (use the code-map), and *where the risk is* (call out the
+   stop's `riskTags` — `contract`/`auth`/`payments`/`tests`). Cite real file + line ranges.
+2. **Socratic question.** Ask the human ONE focused question that applies a rubric step to *this* change —
+   e.g. "this touches the `auth` surface — what could a malicious caller do here, and does the change
+   guard it?" or "which test covers this branch, and what edge case is still uncovered?"
+3. **Two-way until satisfied with the stop.** The human answers and may ask their own questions; you
+   answer **only from real material**, citing lines. Coach — if they miss a rubric angle, surface it and
+   explain *how* an efficient reviewer would have caught it. The stop closes when **both** of you are
+   satisfied with it (no open concern, the human has engaged the change).
+4. **Capture the moment** for the scorecard: which rubric step this stop exercised, and whether the human
+   nailed it, needed a nudge, or missed it (feeds the learning `comprehension` signal).
+
+A **genuine concern** found at any stop (a real bug, a missing test, an unguarded surface) is posted as a
+**normal, unflagged** PR/MR comment so it **blocks** like any reviewer's note — exactly the companion
+rule. Do not bury a real finding inside the session log.
+
+### Step 4 — Dual sign-off (both satisfied)
+After the last stop:
+- **AI sign-off (your verdict).** State plainly: did the human demonstrate understanding across the
+  rubric? Are there any unresolved blocking concerns? "Satisfied" from you means *no unresolved blocking
+  concern remains*.
+- **Human sign-off.** The human decides: **approve** or **request changes**. When they approve through
+  this session, submit the approval carrying the engagement marker so the gate records
+  `engagement: verified` — back half: `gh pr review <n> --approve --body "<note>\n\n<!-- yad:engagement verified -->"`
+  (GitLab: `glab mr approve <n>` then a note with the marker); front half: the human approves via
+  [`yad-review-gate`](../yad-review-gate/SKILL.md) the normal way.
+
+"**Both satisfied**" = the human approved **and** your verdict holds no unresolved blocking concern. If
+either is not satisfied, the loop continues (more stops, or the human requests changes and the owner
+addresses them) — nothing advances on a half-finished session.
+
+### Step 5 — Record the session (twice) — see `references/session-state.md`
+1. **Session comment (PR/MR history).** Post one comment built by the CLI helper `pairSessionBody`
+   (carries `<!-- yad:pair -->` so `yad status` can count paired reviews, and `<!-- yad:noblock -->` so it
+   never holds the gate): the transcript summary, the **review-skill scorecard**, your AI verdict, and
+   both sign-offs. Post it with the platform CLI (`gh pr comment` / `glab mr note`).
+2. **Learning record (local-only).** Append a `yad-learn` record for the `member`: `concept` =
+   `review <repo> PR #<n> — <title>` (front half: `review <artifact> (<epic>)`), `stage` =
+   `engineer-review` (back) / `<artifact>-review` (front), `mode` = `deep` (or `quiz` when you scored
+   comprehension), `comprehension` = the scorecard roll-up, `tutorial` = a rendered
+   `learning/<member>--review-<pr>.md` capturing the method as applied to this PR + the engineer's gaps.
+   **First ensure the hub `.gitignore` covers the learning paths** (reuse yad-learn's guard), then write —
+   these are personal, gitignored, **never committed or pushed**. The growth rolls up under `yad status`
+   "My skills".
+
+## Hard rules
+
+- **Never a gate.** This skill never moves `currentStep`, never records an approval on the human's
+  behalf, and never merges. It enriches the input and rides the existing soft `engagement` signal only.
+  Strict mode (`hub.review.requireEngagement`) is the gate's switch, not this skill's.
+- **The CLI never calls an LLM.** The sequencer (`stops[]`) and the markers are deterministic; *you*
+  generate every briefing, question, and answer. Same split as the companion.
+- **Grounded only in real material.** Briefings/answers come from the diff + artifact + contract +
+  code-map/pack + specs. If the material can't answer something, **say so — that gap is itself a finding**
+  and is posted as a genuine, blocking comment, not fabricated over.
+- **Real concerns block; the session log never does.** Genuine findings are posted **unflagged**; the
+  session comment carries `<!-- yad:pair -->` + `<!-- yad:noblock -->` and is permanent history only.
+- **The learning output is local-only.** Reuse yad-learn's gitignore guard before writing; never commit
+  or push the records/tutorials, and never write them into a code repo.
+- **You never approve for the human and never merge.** You pair and teach; the human acts.
+
+## File-only mode (no platform)
+
+With no hub platform there is no PR to post to: write the session record to
+`reviews/<base>--<date>--pair-session.md` alongside the existing `reviews/*.md`, and the human records
+approval the manual way via [`yad-review-gate`](../yad-review-gate/SKILL.md). The learning record is
+written exactly the same (it is local-only regardless of platform). The session logic is unchanged; only
+the posting surface differs.
+
+## Reference
+
+- The transferable review method + scorecard schema: `references/review-rubric.md`.
+- The session comment shape, dual sign-off, and learning record: `references/session-state.md`.
+- The four skim faces this complements: [`yad-review-companion`](../yad-review-companion/SKILL.md).
+- The back-half merge gate it enriches: [`yad-engineer-review`](../yad-engineer-review/SKILL.md).
+- The front-half gate it enriches: [`yad-review-gate`](../yad-review-gate/SKILL.md).
+- The learning layer it records into: [`yad-learn`](../yad-learn/SKILL.md) and its
+  `references/learning-state.md`.

package/skills/yad-pair-review/references/review-rubric.md

@@ -0,0 +1,56 @@
+# The review method + scorecard (the transferable skill)
+
+This is the repeatable, efficient PR/MR review method the pair walkthrough demonstrates on the real
+change and scores the engineer against. It is **transferable** — the point is that after a few paired
+sessions the engineer reviews this way on their own. `action: rubric` prints this method and stops.
+
+## The method (the order the walkthrough follows)
+
+1. **Spec first — know what it should do.** Read the acceptance criteria / story / `specs/<story>/`
+   before the diff. You can't judge a change you can't measure against its intent.
+2. **Contract surface — did it move the locked surface?** Map the diff against the locked contract
+   (`contract.md` / `contract-lock.json`). A change to the surface without a `Contract-Change` is a
+   routing problem, not just a code problem (it must go back to the architecture gate).
+3. **Risk first — walk the dangerous hunks first.** The grounding orders stops highest-risk first
+   (`contract` > `auth`/`payments` > everything; larger hunks before smaller). Spend your attention where
+   a mistake costs the most; don't read top-to-bottom.
+4. **Per change — the four lenses.** For each hunk ask: **correctness** (does it do what the spec says,
+   including the unhappy path?), **tests** (is the new behaviour covered?), **edge cases** (nulls, empty,
+   concurrency, large input, failure/rollback), **security** (auth/authz, injection, secrets, payments
+   integrity) — weight the last two hard on `auth`/`payments`/`contract` stops.
+5. **Tests cover the change.** A `tests`-tagged stop should map to the behaviour stops. Behaviour with no
+   test is a finding; a test that doesn't exercise the new branch is a finding.
+6. **Decide — approve or request changes.** A clear verdict with the *why*. "Looks good" is not a review;
+   name what you checked and what convinced you.
+
+## The scorecard (feeds the learning signal)
+
+At each stop, capture which rubric step it exercised and how the engineer did. Roll the stops up into a
+compact scorecard for the session comment and the `comprehension` field of the learning record.
+
+Per-step grade (one of):
+
+| grade | meaning |
+|-------|---------|
+| ✅ nailed | the engineer applied the step correctly unprompted |
+| 💡 nudged | they got there after a Socratic hint — a learning moment |
+| ⚠️ missed | they didn't catch it; the AI surfaced it and explained how to next time |
+| — n/a | the step didn't apply to this change |
+
+`comprehension` for the learning record is a short roll-up, e.g. `4/6 steps nailed, 2 nudged
+(contract-surface, edge-cases)` — honest about where the engineer is still growing. It is a soft,
+gameable signal (a learning aid), never a gate — say so.
+
+## Example scorecard block (rendered into the session comment)
+
+```
+| Rubric step            | Grade   | Note                                                |
+|------------------------|---------|-----------------------------------------------------|
+| 1 Spec first           | ✅ nailed | read the AC before the diff                         |
+| 2 Contract surface     | 💡 nudged | spotted the surface change after a hint             |
+| 3 Risk first           | ✅ nailed | started on the auth hunk                            |
+| 4 Four lenses          | ⚠️ missed | missed the missing authz check on the new endpoint  |
+| 5 Tests cover          | ✅ nailed | flagged the uncovered error branch                  |
+| 6 Decide               | ✅ nailed | clear request-changes with the why                  |
+Comprehension: 4/6 nailed, 1 nudged, 1 missed (four-lenses/security)
+```

package/skills/yad-pair-review/references/session-state.md

@@ -0,0 +1,82 @@
+# The session record, the dual sign-off, and the learning record
+
+The pair walkthrough writes its outcome to **two** places, neither of which is a gate ledger and neither
+of which ever blocks the gate. The gate's predicate (approvals + resolved threads + merge) is untouched.
+
+## 1. The session comment (PR/MR platform history)
+
+Built by the CLI helper `pairSessionBody({ summary, scorecard, verdict, humanSignoff, aiSignoff })` in
+`cli/companion.mjs`. It carries **both** markers:
+
+- `<!-- yad:pair -->` — so this is countable as a *paired review* in the `yad status` 🏆 roll-up.
+- `<!-- yad:noblock -->` — so the thread is excluded from the gate's blocking check and persists as
+  permanent history (a deliberate, unresolved trail), exactly like the companion's card/chat threads.
+
+It **never** carries an engagement marker — the session comment is *history*, not the approval. The
+approval is a separate act (Step 4) and carries `<!-- yad:engagement verified -->` on its own.
+
+Sections (you generate the prose; the helper composes them):
+- **summary** — what was walked, how many stops, where the risk was, what the human engaged with.
+- **scorecard** — the rubric table + comprehension roll-up from `references/review-rubric.md`.
+- **verdict** — the AI sign-off: understanding demonstrated? any unresolved blocking concern?
+- **humanSignoff / aiSignoff** — the two satisfaction statements ("both satisfied").
+
+Post it with the platform CLI (`gh pr comment <n> -b "<body>"` / `glab mr note <n> -m "<body>"`). In
+file-only mode write it to `reviews/<base>--<date>--pair-session.md` instead.
+
+## 2. The learning record (local-only, reuses yad-learn)
+
+This is the "review **is** the lesson" half. It reuses [`yad-learn`](../../yad-learn/SKILL.md)'s ledger
+schema and gitignore discipline **verbatim** — see `yad-learn/references/learning-state.md`. Do not
+invent a new store.
+
+**Before writing anything**, ensure the **product hub's** `.gitignore` covers the learning paths
+(idempotent — append only if absent), the same block yad-learn uses:
+
+```
+# yadflow learning layer — personal, local-only (never commit or push)
+.sdlc/learning-records.json
+.sdlc/learning/
+epics/*/.sdlc/learning-records.json
+epics/*/learning/
+```
+
+Then append one record to `epics/EP-<slug>/.sdlc/learning-records.json` (or `.sdlc/learning-records.json`
+cross-project), using yad-learn's exact field shape:
+
+```json
+{
+  "member": "alice",
+  "concept": "review backend PR #42 — add refund endpoint",
+  "context": "pair-review walkthrough; risk: payments, contract",
+  "stage": "engineer-review",
+  "mode": "quiz",
+  "tool": "harness-native",
+  "sessionId": null,
+  "tutorial": "learning/alice--review-42.md",
+  "comprehension": "4/6 nailed, 1 nudged, 1 missed (four-lenses/security)",
+  "status": "learned",
+  "requestedAt": "<YYYY-MM-DD>",
+  "completedAt": "<YYYY-MM-DD>"
+}
+```
+
+Field notes:
+- `stage` = `engineer-review` (back half) or `<artifact>-review` (front half, e.g. `architecture-review`).
+- `mode` = `deep` for a walkthrough that didn't score, `quiz` when you captured a comprehension roll-up.
+- `comprehension` = the scorecard roll-up string (null when `mode: deep`).
+- `tool` = `harness-native` (or `deeptutor` if a DeepTutor session backed the tutoring).
+- `status` = `learned` once the session completed (set `completedAt`); `in-progress` if paused.
+
+Also render the tutorial artifact `epics/EP-<slug>/learning/<member>--review-<pr>.md` (front-matter:
+`member`, `concept`, `stage`, `tool`, `requestedAt`) — the review method as applied to *this* PR plus the
+engineer's specific gaps and how to close them. Both files are **local-only, gitignored, never committed
+or pushed, and never written into a code repo** — they are a private personal skills log. `yad status`
+rolls them up by stage (e.g. "engineer-review: 3").
+
+## Optional: stamp the build-log (back half)
+
+When the task later ships, [`yad-engineer-review`](../../yad-engineer-review/SKILL.md) may record on the
+ship record's `companion` block that a pair session ran: `"companion": { "trailer": true, "cards": false,
+"chat": false, "pair": true }`. This is informational only — it never changes whether the ship is
+allowed.

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