yadflow 3.0.0 → 3.2.0

package/CHANGELOG.md

@@ -1,18 +1,14 @@
-# [3.0.0](https://github.com/abdelrahmannasr/yadflow/compare/v2.18.1...v3.0.0) (2026-06-29)
+# [3.2.0](https://github.com/abdelrahmannasr/yadflow/compare/v3.1.0...v3.2.0) (2026-06-30)
 
 
-* feat!: remove unused yad-review-comments skill ([da6ad60](https://github.com/abdelrahmannasr/yadflow/commit/da6ad608bedf86a58ad09c2aefbf5e6367a41ae4))
-
-
-### Features
+### Bug Fixes
 
-* **cli:** purge removed skills from existing installs ([8887d6d](https://github.com/abdelrahmannasr/yadflow/commit/8887d6d5598775986729c77f1500ac6773e4591e))
+* **review:** keep walkthrough STDOUT pure JSON (diagnostics to stderr) ([0d46455](https://github.com/abdelrahmannasr/yadflow/commit/0d46455919997ebcaa9b1f9929f5265023d05c5a))
 
 
-### BREAKING CHANGES
+### Features
 
-* the yad-review-comments skill and its REVIEW_COMMENTS.md repo
-wiring are removed; `npx yadflow setup` now installs 34 skills instead of 35.
+* **review:** add yad-pair-review — guided two-way teaching walkthrough ([337cf9a](https://github.com/abdelrahmannasr/yadflow/commit/337cf9a0814f79f411db13a59af9afbdb64cf57d))
 
 # [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,10 +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 } 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, reviewWalkthrough } from '../cli/review.mjs';
 import { runShip } from '../cli/ship.mjs';
 import { runRepo } from '../cli/repo.mjs';
 import { runRoster } from '../cli/roster.mjs';
@@ -26,7 +27,8 @@ ${c.bold('Setup & maintenance')}
   yad check            Report what is missing / drifted / stale / legacy (read-only)
   yad check --fix      Reconcile: fill what is missing, update what changed
   yad update           Apply drift only (alias for: check --fix --scope=changed);
-                       also migrates pre-2.0 sdlc-* installs to the yad-* names
+                       installs newly-added skills, updates changed skills + gate scripts,
+                       and migrates pre-2.0 sdlc-* installs to the yad-* names
   yad doctor [--json]  Environment + state health: tools/auth, config files,
                        repo paths, epic ledgers (exit 1 on any failure)
   yad sync-status [epic]   Update artifact frontmatter status (draft/in-review/approved)
@@ -51,6 +53,12 @@ ${c.bold('Review gate (front half)')}
   yad gate sync <epic> [artifact]      Pull PR state -> ledger; advance on approved+resolved+merged
   yad gate comments <epic> [artifact]  Fetch unresolved review comments to address
   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]
                         CI entry (hub workflow): pre-merge is read-only (nothing pushed);
                         --merged advances the step + flips artifact status on the default branch
@@ -61,6 +69,12 @@ ${c.bold('Build helpers')}
                                        branch opens the front-half artifact-review PR (delegates to
                                        gate open), any other hub branch uses the code-task template
   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)
   yad repo refresh [name]              Re-pack a stale repo (a human decision)
 
@@ -97,7 +111,7 @@ ${c.bold('Options')}
   -h, --help            Show this help
   -v, --version         Print version`;
 
-const VALUE_FLAGS = new Set(['--dir', '--type', '--message', '--task', '--ai', '--risk', '--repo', '--platform', '--base', '--title', '--scope', '--branch', '--pr', '--epic', '--name', '--email', '--roles', '--team']);
+const VALUE_FLAGS = new Set(['--dir', '--type', '--message', '--task', '--ai', '--risk', '--repo', '--platform', '--base', '--title', '--scope', '--branch', '--pr', '--epic', '--name', '--email', '--roles', '--team', '--body']);
 
 function parseArgs(argv) {
   const o = { _: [], dir: process.cwd(), fix: false, force: false, scope: 'all' };
@@ -184,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|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
@@ -194,7 +208,24 @@ async function main() {
       else if (action === 'sync') await gateSync(o.dir, { epic, artifact, today, local: true });
       else if (action === 'comments') await gateComments(o.dir, { epic, artifact, today });
       else if (action === 'status') await gateStatus(o.dir, { epic });
-      else { log(c.red(`unknown gate action: ${action} (open|sync|comments|status|ci)`)); process.exitCode = 1; }
+      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|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|walkthrough|nudge|reconcile> --repo <name> --pr <n> [--epic <id>] [--body <text>]')); process.exitCode = 1; }
       break;
     }
     case 'commit':

package/cli/companion.mjs

@@ -0,0 +1,90 @@
+// cli/companion.mjs — pure, perspective-neutral helpers for the Review Companion, shared by the front
+// half (yad gate …) and the back half (yad review …). The CLI never calls an LLM — generation happens
+// in the skill/harness layer (like yad-learn/yad-docs). This module owns the platform MARKERS, the
+// engagement parsing, the trailer-block upsert, and the message text the skill and the gate share.
+//
+// Design philosophy ("visible, not impossible"): the engagement signal is GAMEABLE by design. It makes
+// review quality VISIBLE (verified vs none + a friendly public nudge); it never claims to prove a human
+// read anything. All markers ride in PLATFORM data (PR/MR bodies + comment threads), never in a ledger
+// file — so the ledger-guard check never sees them and the reviewer never writes the ledger.
+
+export const TRAILER_BEGIN = '<!-- yad:trailer -->';
+export const TRAILER_END = '<!-- /yad:trailer -->';
+// A companion- or nudge-posted comment carries this so the gate EXCLUDES it from the thread-resolution
+// blocking check. Such threads are deliberately left unresolved as a permanent PR/MR history trail.
+export const NOBLOCK_MARK = '<!-- yad:noblock -->';
+const ENGAGEMENT_RE = /<!--\s*yad:engagement\s+(verified|none)\s*-->/i;
+
+// True when a comment/thread body is companion scaffolding (card deck, chat log, nudge) — never blocks.
+export function isNoBlock(body) {
+  return typeof body === 'string' && body.includes(NOBLOCK_MARK);
+}
+
+// The engagement signal a reviewer's APPROVE carries in its review body: a companion-driven approve
+// embeds `<!-- yad:engagement verified -->`; a bare UI click has no marker → 'none'.
+export function parseEngagement(body) {
+  const m = ENGAGEMENT_RE.exec(typeof body === 'string' ? body : '');
+  return m ? m[1].toLowerCase() : 'none';
+}
+
+// Body for a companion approval review — embeds the engagement marker the gate reads back.
+export function engagementBody(kind = 'verified', note = '') {
+  const k = kind === 'verified' ? 'verified' : 'none';
+  return `${note ? note + '\n\n' : ''}<!-- yad:engagement ${k} -->`;
+}
+
+// Tag a companion comment so the gate never blocks on it (and it persists as PR/MR history).
+export function noBlock(body = '') {
+  return `${body}\n\n${NOBLOCK_MARK}`;
+}
+
+// Idempotently insert/replace the trailer block in a PR/MR description. String-based (no regex over the
+// markers) so regenerating on every artifact change never duplicates or mangles the block.
+export function upsertTrailerBlock(description = '', trailer = '') {
+  const desc = typeof description === 'string' ? description : '';
+  const block = `${TRAILER_BEGIN}\n${trailer}\n${TRAILER_END}`;
+  const s = desc.indexOf(TRAILER_BEGIN);
+  // Find the END marker AFTER the BEGIN, so an earlier quoted `<!-- /yad:trailer -->` in the body
+  // can't break idempotency (otherwise a second block gets prepended instead of replacing).
+  const e = s === -1 ? -1 : desc.indexOf(TRAILER_END, s + TRAILER_BEGIN.length);
+  if (s !== -1 && e !== -1 && e > s) {
+    return desc.slice(0, s) + block + desc.slice(e + TRAILER_END.length);
+  }
+  return desc ? `${block}\n\n${desc}` : block;
+}
+
+// The friendly, public nudge for a bare approve (engagement: none). Warm, short, names the reviewer,
+// and carries the noblock marker so it never holds the gate.
+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/doctor.mjs

@@ -94,6 +94,17 @@ export function projectChecks(checks, root) {
           }
           if (bad.length) check(checks, 'roster', 'project', 'warn', `roster login(s) not found on ${hub.platform}: ${bad.join(', ')}`, 'fix the login or re-run `yad setup` (they cannot satisfy a gate)');
           else check(checks, 'roster', 'project', 'ok', `roster: ${(hub.roster || []).length} member(s) validated on ${hub.platform}`);
+          // GitLab API reachability: the gate reads MR state via `glab api …` (approvals, discussions).
+          // A present+authenticated glab whose token lacks api scope would still break readPrGitLab, so
+          // probe a cheap api call (warn-only) to surface it before a sync silently holds the gate.
+          if (hub.platform === 'gitlab') {
+            // Scope the probe to the hub's own host (like the auth check above) so a multi-instance
+            // setup doesn't hit the wrong GitLab and emit a misleading warning.
+            const apiArgs = host ? ['api', 'version', '--hostname', host] : ['api', 'version'];
+            if (!run('glab', apiArgs).ok) {
+              check(checks, 'gitlab-api', 'project', 'warn', `glab is authenticated but \`glab api\` failed${host ? ` for ${host}` : ''} [YAD-ENV-002]`, 'ensure the token has `api` scope — the gate reads MR approvals/discussions via the API');
+            }
+          }
           // Solo + GitHub: a branch that "requires approvals" would block the solo dev's own merge
           // (they can't approve their own PR). Best-effort probe; a 404 (no protection) is fine.
           if (isSolo(hub) && hub.platform === 'github') {

package/cli/epic-state.mjs

@@ -189,6 +189,7 @@ export function gatePredicate({
   threadsResolved = true,
   merged = true,
   solo = false,
+  requireEngagement = false,
 }) {
   // Phase 6: an INHERITED step (a change-epic carrying a parent artifact by reference) is satisfied
   // without re-review — its approval lives upstream in the thread, recorded as an `inherited` provenance
@@ -210,9 +211,14 @@ export function gatePredicate({
   const stale = forStep.filter((a) => a.artifactHash && currentHash && a.artifactHash !== currentHash);
   const live = forStep.filter((a) => !stale.includes(a));
 
-  const owners = uniqueBy(live.filter((a) => a.role === 'owner'), 'approver');
-  const reviewers = uniqueBy(live.filter((a) => a.role === 'reviewer'), 'approver');
-  const domainOwners = live.filter((a) => a.role === 'domain-owner');
+  // requireEngagement (config `hub.review.requireEngagement`, soft-off by default): only an approval
+  // carrying a verified engagement signal counts. The signal is gameable by design — this raises the
+  // cost of a bare rubber-stamp, it does not claim to prove a human read the artifact.
+  const counted = requireEngagement ? live.filter((a) => a.engagement === 'verified') : live;
+  const unengaged = requireEngagement ? live.filter((a) => a.engagement !== 'verified').length : 0;
+  const owners = uniqueBy(counted.filter((a) => a.role === 'owner'), 'approver');
+  const reviewers = uniqueBy(counted.filter((a) => a.role === 'reviewer'), 'approver');
+  const domainOwners = counted.filter((a) => a.role === 'domain-owner');
 
   const escalate = isEscalated(step);
   const missing = [];
@@ -230,6 +236,10 @@ export function gatePredicate({
     }
   }
   const approvalsSatisfied = missing.length === 0;
+  // Surface engagement-gated approvals that did not count (only when requireEngagement holds the gate).
+  if (!solo && requireEngagement && !approvalsSatisfied && unengaged) {
+    missing.push(`${unengaged} approval(s) without verified engagement — run \`yad gate review\` so they count`);
+  }
   // A stale approval only matters when approvals are required (team mode); in solo they are moot.
   if (!solo && stale.length) missing.unshift(`${stale.length} approval(s) revoked — artifact changed; re-approve`);
   if (!threadsResolved) missing.push('unresolved review comments');

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 {
@@ -13,7 +13,12 @@ import {
   advanceState, markInReview, isEscalated, parseReviewBranch, artifactFromBase,
   upsertHubPr, DISCOVERY_FILES,
 } from './epic-state.mjs';
-import { readPr, mapApprovers, createPr, reviewersForScopes, resolveCommitterLogin } from './platform.mjs';
+import {
+  readPr, mapApprovers, createPr, reviewersForScopes, resolveCommitterLogin,
+  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';
 
@@ -112,6 +117,11 @@ const isSolo = (hub) => !!(hub && (hub.solo === true || hub.review_gate?.solo ==
 // or reviews could never advance. Mirrors plan.mjs hubActions.
 const isBridge = (hub) => !!(hub?.platform && (hub.bridge_enabled === true || hub.bridge === true));
 
+// requireEngagement (config `hub.review.requireEngagement`): when on, the predicate counts only
+// approvals carrying a verified engagement signal. Soft-off by default — a bare approve still counts
+// but is recorded `engagement: none` and draws the friendly nudge.
+const requireEngagement = (hub) => !!(hub && (hub.review?.requireEngagement === true));
+
 // Re-add this step's bridge approvals from the current platform state (drop+re-add => dismissals and
 // revocations vanish idempotently; manual approvals are never touched). Preserve the artifactHash a
 // reviewer first approved against unless their review is newer (a genuine re-approval) — that is what
@@ -142,6 +152,7 @@ function upsertBridge(approvals, recs, { stepId, artifact, curHash, today }) {
       ...(r.domain ? { domain: r.domain } : {}),
       status: 'approved', date: today, source: 'bridge',
       artifactHash: artHash, approvedAt,
+      engagement: r.engagement === 'verified' ? 'verified' : 'none',
       ...(r.unverified ? { unverified: true } : {}),
     });
   }
@@ -187,6 +198,7 @@ export async function gateSync(root, { epic, artifact, today, reader = readPr, l
   const roster = hub.roster || [];
   const defaultReviewers = 1;
   const solo = isSolo(hub);
+  const reqEng = requireEngagement(hub);
   // Local invocation in bridge mode is ADVISORY: CI is the sole ledger writer, so a human run reads
   // the platform and prints the predicate but writes nothing. CI calls gateSync with local=false.
   // Without the bridge (platform but no gate-sync CI) the local command stays the writer.
@@ -222,7 +234,10 @@ export async function gateSync(root, { epic, artifact, today, reader = readPr, l
     approvals = upsertBridge(approvals, recs, { stepId: step.id, artifact: pr.artifact, curHash, today });
 
     const changeRequested = pull.reviews.filter((r) => r.state === 'CHANGES_REQUESTED');
-    const unresolved = (pull.threads || []).filter((t) => !t.resolved);
+    // 2f: companion scaffolding + nudge threads carry the noblock marker and are EXCLUDED from the
+    // blocking check — they stay unresolved as a permanent PR/MR history trail but never hold the gate.
+    // Only genuine (unflagged) unresolved threads block.
+    const unresolved = (pull.threads || []).filter((t) => !t.resolved && !isNoBlock(t.body));
     const threadsResolved = unresolved.length === 0 && changeRequested.length === 0;
     const blocking = [
       ...changeRequested.map((r) => ({ login: r.login, changesRequested: true })),
@@ -232,9 +247,21 @@ export async function gateSync(root, { epic, artifact, today, reader = readPr, l
     if (!readOnly) writeComments(epicDir, base(pr.artifact), today, blocking);
     comments = recordComments(comments, { artifact: pr.artifact, stepId: step.id, today, roster, repos, blocking });
 
+    // Social nudge: a bare APPROVE (no verified engagement) still counts (soft default), but the bot
+    // posts a friendly public @-mention inviting the reviewer to run the companion. Idempotent via
+    // pr.nudged; only on the writer path (a platform comment, not a ledger write).
+    if (!readOnly) {
+      const nudged = new Set(pr.nudged || []);
+      for (const rv of pull.reviews) {
+        if (rv.state !== 'APPROVED' || parseEngagement(rv.body) === 'verified' || !rv.login || nudged.has(rv.login)) continue;
+        if (postComment(platform, pr.number, nudgeMessage(rv.login), { cwd: root }).ok) nudged.add(rv.login);
+      }
+      pr.nudged = [...nudged];
+    }
+
     const pred = gatePredicate({
       step, approvals, currentHash: curHash, touchedDomains: domains,
-      defaultReviewers, threadsResolved, merged: pull.merged, solo,
+      defaultReviewers, threadsResolved, merged: pull.merged, solo, requireEngagement: reqEng,
     });
 
     log(`  ${c.bold(pr.artifact)} ${c.dim(`(PR #${pr.number}, rule: ${pred.rule})`)}`);
@@ -470,7 +497,7 @@ export async function gateStatus(root, { epic } = {}) {
 // the branch this would otherwise recompute (artifactFromBase collapses stories-S01 → stories/). Pass
 // the real pushed head so the PR targets a branch that exists. `creator` is injected in tests.
 export async function gateOpen(root, { epic, artifact, head, creator = createPr } = {}) {
-  const { hub } = loadHub(root);
+  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; }
@@ -504,12 +531,16 @@ export async function gateOpen(root, { epic, artifact, head, creator = createPr
   // domain-owners of the touched repos, minus the committer (the owner/author is recorded, not asked
   // to review their own artifact). Scope is the hub plus every touched domain.
   const committer = resolveCommitterLogin(root, hub.roster || []);
-  const reviewers = reviewersForScopes(hub.roster || [], ['hub', ...domains], { excludeLogin: committer });
+  const reviewers = reviewersForScopes(hub.roster || [], ['hub', ...domains], { excludeLogin: committer, repos });
   const assignees = committer ? [committer] : [];
   const labels = isEscalated(step) ? domains.map((d) => `domain:${d}`) : [];
   info(`opening review ${hub.platform === 'gitlab' ? 'MR' : 'PR'} on branch ${branch} …`);
   const r = creator(hub.platform, { title: `review: ${artifact} (${epic})`, body, base: hub.default_branch || 'main', head: branch, reviewers, assignees, labels, cwd: root });
   if (!r.ok) { warn(`could not open PR (${r.reason || 'unknown'})${bridge ? ' — open it manually; CI records the gate on merge' : '; step is in_review file-only'}`); return; }
+  // Surface routing: who was assigned as a reviewer, who was @-mentioned (GitLab field cap), and any
+  // login the platform could not add (dropped) so a partial roster is visible, not silent.
+  if (r.mentioned?.length) info(`@-mentioned (GitLab single-reviewer field): ${r.mentioned.join(', ')}`);
+  if (r.dropped?.length) warn(`could not request as reviewer (unknown/non-collaborator login): ${r.dropped.join(', ')}`);
 
   if (!bridge) {
     ledger.hubPrs = upsertHubPr(ledger.hubPrs, { step: step.id, artifact, platform: hub.platform, number: Number((r.url.match(/\/(\d+)(?:[/?#]|$)/) || [])[1]) || null, url: r.url, branch, lastSyncedAt: null });
@@ -522,6 +553,95 @@ export async function gateOpen(root, { epic, artifact, head, creator = createPr
   return { url: r.url };
 }
 
+// `yad gate review <epic> [artifact]` — assemble + print the grounding bundle the companion skill uses
+// 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).
+// 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) 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;
+  const bundle = {
+    epic,
+    artifact: art,
+    platform: hub?.platform || null,
+    pr: pr ? { number: pr.number, url: pr.url } : null,
+    step: step ? { id: step.id, riskTags: step.risk_tags || [], escalated: isEscalated(step) } : null,
+    artifactPath: art ? path.join(epicDir, art) : null,
+    contractPath: art && base(art) === 'architecture' ? path.join(epicDir, 'contract.md') : null,
+    touchedDomains: step ? touchedDomains(epicDir, step) : [],
+    repos: (repos || []).map((r) => ({
+      name: r.name,
+      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 -->', pair: '<!-- yad:pair -->',
+    },
+  };
+  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
+// briefing text and passes it here; this upserts it idempotently into the review PR/MR description as a
+// delimited block, so regenerating on every artifact change never duplicates it. A platform write only.
+export async function gateTrailer(root, { epic, artifact, body, number, getBody = getPrBody, editBody = editPrBody } = {}) {
+  const { hub } = loadHub(root);
+  if (!hub?.platform) { warn('no hub platform configured — the trailer posts to the PR/MR (file-only has none)'); return; }
+  if (!body || !String(body).trim()) { fail('trailer body is required: `yad gate trailer <epic> <artifact> --body <text>` (the companion generates it)'); process.exitCode = 1; return; }
+  const epicDir = epicRoot(root, epic);
+  const ledger = loadLedger(epicDir);
+  const pr = (ledger.hubPrs || []).find((p) => !artifact || p.artifact === artifact) || null;
+  const n = number || pr?.number;
+  if (!n) { warn('no PR number — pass `--pr <n>` (in bridge mode the PR is recorded in the ledger only at merge)'); return; }
+  const cur = getBody(hub.platform, n, { cwd: root });
+  if (!cur.ok) { fail(`could not read PR #${n} description: ${cur.reason || 'unknown'}`); process.exitCode = 1; return; }
+  const r = editBody(hub.platform, n, upsertTrailerBlock(cur.body, String(body).trim()), { cwd: root });
+  if (!r.ok) { fail(`could not update PR #${n}: ${r.reason || 'unknown'}`); process.exitCode = 1; return; }
+  ok(`trailer posted to PR #${n}`);
+  return { number: n };
+}
+
 // ---- helpers ------------------------------------------------------------------------------------
 const base = (artifact) => artifactBase(artifact);
 

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

@@ -41,6 +41,8 @@ export const SKILLS = [
   'yad-backfill',
   'yad-run',
   'yad-review-gate',
+  'yad-review-companion',
+  'yad-pair-review',
   'yad-status',
   'yad-change',
   'yad-timeline',

package/cli/openpr.mjs

@@ -136,12 +136,16 @@ export async function runOpenPr(root, opts = {}) {
   const roster = hub.roster || [];
   const committer = resolveCommitterLogin(repoRoot, roster);
   const scope = meta?.name ? [meta.name] : [];
-  const reviewers = reviewersForScopes(roster, scope, { excludeLogin: committer });
+  // Pass the repo registry entry so a domain owner declared only in repos.json (not the roster roles
+  // map) is still requested as a reviewer (BUG-1).
+  const reviewers = reviewersForScopes(roster, scope, { excludeLogin: committer, repos: meta ? [meta] : [] });
   const assignees = committer ? [committer] : [];
 
   const r = createPr(platform, { title, body, base: baseBranch, head: branch, reviewers, assignees, cwd: repoRoot });
   if (!r.ok) { fail(`could not open PR/MR — ${r.reason || 'unknown'}`); process.exitCode = 1; return; }
   ok(`opened ${r.url}`);
+  if (r.mentioned?.length) info(`@-mentioned (GitLab single-reviewer field): ${r.mentioned.join(', ')}`);
+  if (r.dropped?.length) hand(`could not request as reviewer (unknown/non-collaborator login): ${r.dropped.join(', ')}`);
   if (opts.risk === 'high' || opts.contractChange) hand('high risk / contract surface — run `bash checks/risk-route.sh "<pr body>"` for required reviewers');
   return { url: r.url };
 }

package/cli/plan.mjs

@@ -34,25 +34,31 @@ export function ideTargetsFor(root) {
   return present.length ? present : ['.claude'];
 }
 
+// A brand-new first-party skill is `missing` on every existing install. Relabel that to status `'new'`
+// so it rides `yad update` (--scope=changed) — like 'legacy'/'removed', the `changed` filter only
+// excludes literal 'missing', so 'new' survives. Scoped to SKILL installs ONLY: repo/hub wiring and
+// _bmad files stay 'missing' (excluded from update), so `update` never does one-time setup.
+const asNewSkill = (a) => (a.status === 'missing' ? { ...a, status: 'new' } : a);
+
 // Module = skills installed into each IDE target + the _bmad/sdlc registration.
 export function moduleActions(root, ideTargets = ideTargetsFor(root)) {
   const actions = [];
   for (const ide of ideTargets) {
     if (ide === '.opencode') {
       for (const s of SKILLS) {
-        actions.push(fileAction(
+        actions.push(asNewSkill(fileAction(
           ide, s,
           asset('skills', s, 'SKILL.md'),
           path.join(root, IDE_OPENCODE_DIR, `${s}.md`),
-        ));
+        )));
       }
     } else {
       for (const s of SKILLS) {
-        actions.push(dirAction(
+        actions.push(asNewSkill(dirAction(
           ide, s,
           asset('skills', s),
           path.join(root, ide, 'skills', s),
-        ));
+        )));
       }
     }
   }