yadflow 3.0.0 → 3.2.0

package/cli/platform.mjs

@@ -3,6 +3,7 @@
 // no tokens are stored. Pure mapping fns (resolveLogin/mapApprovers) are exported for unit tests;
 // readPr is injectable so the gate can be tested with a fake.
 import { run, has } from './lib.mjs';
+import { parseEngagement } from './companion.mjs';
 
 // github | gitlab | null, from a repo/remote.
 export function detectPlatform(remoteUrl = '') {
@@ -68,11 +69,22 @@ export function hasAnyRole(entry, scopes = [], wanted = []) {
 
 // Platform logins to auto-request as reviewers for the given scopes: everyone holding a `reviewer`
 // or `domain-owner` role in any scope, minus `excludeLogin` (you don't review your own PR), deduped.
-export function reviewersForScopes(roster = [], scopes = [], { excludeLogin = null } = {}) {
+// `repos` (the registry) is consulted so a repo whose domain ownership lives ONLY in the legacy
+// `repos.json` `domain_owner`/`domain_owners` field — not the roster roles map — is still requested
+// as a reviewer for any scope that is its repo name. Without this the read side credits that login as
+// a domain-owner (resolveLogin's legacy fallback) but the open side never asks them, so an escalated
+// gate becomes structurally unsatisfiable through platform routing (BUG-1).
+export function reviewersForScopes(roster = [], scopes = [], { excludeLogin = null, repos = [] } = {}) {
   const out = [];
+  const add = (login) => { if (login && login !== excludeLogin && !out.includes(login)) out.push(login); };
   for (const entry of roster) {
-    if (!entry.login || entry.login === excludeLogin) continue;
-    if (hasAnyRole(entry, scopes, ['reviewer', 'domain-owner']) && !out.includes(entry.login)) out.push(entry.login);
+    if (hasAnyRole(entry, scopes, ['reviewer', 'domain-owner'])) add(entry.login);
+  }
+  for (const scope of scopes) {
+    const repo = repos.find((r) => r.name === scope);
+    if (!repo) continue;
+    const names = repo.domain_owners || (repo.domain_owner ? [repo.domain_owner] : []);
+    for (const name of names) add(roster.find((r) => r.name === name)?.login);
   }
   return out;
 }
@@ -127,8 +139,11 @@ export function resolveLogin(login, roster = [], repos = [], touchedDomains = []
     for (const role of rolesForScope(entry, d)) {
       push(role === 'domain-owner' ? { name: entry.name, role, domain: d } : { name: entry.name, role });
     }
-    // Legacy fallback: a repo whose domain_owner is this name confers domain-owner for that domain.
-    const legacy = repos.find((repo) => repo.name === d && repo.domain_owner === entry.name);
+    // Legacy fallback: a repo whose domain_owner / domain_owners[] includes this name confers
+    // domain-owner for that domain. Both spellings are honored — symmetric with reviewersForScopes,
+    // which REQUESTS from both, so a person routed as a domain owner is also credited as one.
+    const legacy = repos.find((repo) => repo.name === d
+      && (repo.domain_owner === entry.name || (Array.isArray(repo.domain_owners) && repo.domain_owners.includes(entry.name))));
     if (legacy) push({ name: entry.name, role: 'domain-owner', domain: d });
   }
   // An identity-only entry (no roles map and no legacy `role`) still contributes a base reviewer
@@ -156,8 +171,11 @@ export function mapApprovers(reviews = [], { roster, repos, touchedDomains, head
     //                               commits" setting.
     if (r.commit === null) continue;
     if (headOid && r.commit !== undefined && r.commit !== headOid) continue;
+    // engagement rides in the APPROVE review body (`<!-- yad:engagement verified -->`); a bare UI
+    // click has no marker → 'none'. Gameable by design (it makes review quality visible, not provable).
+    const engagement = parseEngagement(r.body);
     for (const rec of resolveLogin(r.login, roster, repos, touchedDomains)) {
-      out.push({ ...rec, submittedAt: r.submittedAt || null });
+      out.push({ ...rec, submittedAt: r.submittedAt || null, engagement });
     }
   }
   return out;
@@ -182,7 +200,7 @@ function readPrGitHub(n, { cwd } = {}) {
     // latestReviews` does not expose the commit, so read it via GraphQL. Paginate so a PR with >100
     // reviewers never silently omits one; any page failure aborts to the commitless fallback below,
     // which fails closed rather than advancing on a partial read.
-    const rq = `query($o:String!,$r:String!,$n:Int!,$c:String){repository(owner:$o,name:$r){pullRequest(number:$n){latestReviews(first:100,after:$c){pageInfo{hasNextPage endCursor} nodes{author{login} state submittedAt commit{oid}}}}}}`;
+    const rq = `query($o:String!,$r:String!,$n:Int!,$c:String){repository(owner:$o,name:$r){pullRequest(number:$n){latestReviews(first:100,after:$c){pageInfo{hasNextPage endCursor} nodes{author{login} state submittedAt body commit{oid}}}}}}`;
     let rcursor = null;
     reviewsOk = true;
     for (let guard = 0; guard < 50; guard++) {
@@ -192,7 +210,7 @@ function readPrGitHub(n, { cwd } = {}) {
       if (!rg.ok) { reviewsOk = false; reviews = []; break; }
       const conn = JSON.parse(rg.stdout)?.data?.repository?.pullRequest?.latestReviews;
       for (const x of conn?.nodes || []) {
-        reviews.push({ login: x.author?.login, state: x.state, submittedAt: x.submittedAt, commit: x.commit?.oid || null });
+        reviews.push({ login: x.author?.login, state: x.state, submittedAt: x.submittedAt, body: x.body, commit: x.commit?.oid || null });
       }
       if (!conn?.pageInfo?.hasNextPage) break;
       rcursor = conn.pageInfo.endCursor;
@@ -224,7 +242,7 @@ function readPrGitHub(n, { cwd } = {}) {
   if (!reviewsOk) {
     const rev = run('gh', ['pr', 'view', String(n), '--json', 'latestReviews'], { cwd });
     if (rev.ok) reviews = (JSON.parse(rev.stdout).latestReviews || [])
-      .map((x) => ({ login: x.author?.login, state: x.state, submittedAt: x.submittedAt, commit: null }));
+      .map((x) => ({ login: x.author?.login, state: x.state, submittedAt: x.submittedAt, body: x.body, commit: null }));
   }
   return {
     ok: true,
@@ -243,19 +261,26 @@ function readPrGitLab(n, { cwd } = {}) {
   const mr = JSON.parse(view.stdout);
   const approvals = run('glab', ['api', `projects/:id/merge_requests/${mr.iid}/approvals`], { cwd });
   const approvedBy = approvals.ok ? (JSON.parse(approvals.stdout).approved_by || []) : [];
-  const reviews = approvedBy.map((a) => ({ login: a.user?.username, state: 'APPROVED' }));
   const disc = run('glab', ['api', `projects/:id/merge_requests/${mr.iid}/discussions`], { cwd });
-  let threads = [];
-  if (disc.ok) {
-    threads = (JSON.parse(disc.stdout) || [])
-      .filter((d) => d.notes?.some((nt) => nt.resolvable))
-      .map((d, i) => ({
-        id: d.id || `disc-${i}`,
-        resolved: !!d.notes.find((nt) => nt.resolvable)?.resolved,
-        login: d.notes[0]?.author?.username,
-        body: d.notes[0]?.body,
-      }));
+  const discussions = disc.ok ? (JSON.parse(disc.stdout) || []) : [];
+  // A GitLab approval carries no body, so the companion's engagement marker rides in a NOTE the
+  // reviewer posts; attach the latest engagement-bearing note per username to their approval so
+  // mapApprovers reads engagement uniformly with GitHub.
+  const engagementByUser = new Map();
+  for (const d of discussions) {
+    for (const nt of d.notes || []) {
+      if (/<!--\s*yad:engagement\s+\w+\s*-->/i.test(nt.body || '')) engagementByUser.set(nt.author?.username, nt.body);
+    }
   }
+  const reviews = approvedBy.map((a) => ({ login: a.user?.username, state: 'APPROVED', body: engagementByUser.get(a.user?.username) }));
+  const threads = discussions
+    .filter((d) => d.notes?.some((nt) => nt.resolvable))
+    .map((d, i) => ({
+      id: d.id || `disc-${i}`,
+      resolved: !!d.notes.find((nt) => nt.resolvable)?.resolved,
+      login: d.notes[0]?.author?.username,
+      body: d.notes[0]?.body,
+    }));
   return {
     ok: true,
     state: mr.state,
@@ -281,7 +306,9 @@ export function readPr(platform, n, opts = {}) {
 export function buildPrArgs(platform, { title, body, base, head, reviewers = [], labels = [], assignees = [] } = {}) {
   if (platform === 'gitlab') {
     const args = ['mr', 'create', '--title', title, '--description', body, '--target-branch', base, '--source-branch', head, '--yes'];
-    if (reviewers.length) args.push('--reviewer', reviewers.join(','));
+    // A Free/Core GitLab MR carries a SINGLE reviewer field (multiple reviewers is a Premium feature),
+    // so only the first reviewer goes in the field; createPr @-mentions the rest in a note (BUG-2).
+    if (reviewers.length) args.push('--reviewer', reviewers[0]);
     if (assignees.length) args.push('--assignee', assignees.join(','));
     if (labels.length) args.push('--label', labels.join(','));
     return args;
@@ -293,8 +320,107 @@ export function buildPrArgs(platform, { title, body, base, head, reviewers = [],
   return args;
 }
 
+// Number/IID from a PR/MR URL (…/pull/123, …/pulls/123, …/-/merge_requests/45). Anchored to the
+// PR/MR path segment so a numeric group/org/repo earlier in the URL is never mistaken for it; falls
+// back to a trailing number for non-standard URLs. null when unparsable.
+export function prNumberFromUrl(url = '') {
+  const s = String(url);
+  const m = s.match(/\/(?:pull|pulls|merge_requests)\/(\d+)/);
+  if (m) return m[1];
+  const tail = s.match(/\/(\d+)(?:[/?#]|$)/);
+  return tail ? tail[1] : null;
+}
+
+// Create a PR/MR and route the required reviewers, resiliently, on both platforms:
+//   GitHub — create WITHOUT reviewers, then add each via `gh pr edit --add-reviewer`. A bad/
+//            non-collaborator login then WARNS (dropped) instead of aborting the whole create (BUG-4).
+//   GitLab — assign the first reviewer to the MR field; @-mention the remaining required reviewers in
+//            an MR note so they are still notified/routed despite the single-reviewer-field cap (BUG-2).
+// Returns { ok, url, reviewers (assigned), mentioned, dropped }.
+// ---- post back to the platform (companion write helpers) ----------------------------------------
+// The reviewer/companion writes to the PLATFORM (PR/MR body + comments + approval), never the ledger —
+// so the ledger-guard check is never tripped. Each returns { ok, ... } and never throws.
+
+// Current PR/MR description (for idempotent trailer-block upsert). null when unreadable.
+export function getPrBody(platform, n, { cwd } = {}) {
+  if (!platformReady(platform)) return { ok: false, reason: `${cliFor(platform) || 'platform CLI'} not available` };
+  if (platform === 'github') {
+    const r = run('gh', ['pr', 'view', String(n), '--json', 'body', '-q', '.body'], { cwd });
+    return { ok: r.ok, body: r.ok ? r.stdout : '', reason: r.stderr };
+  }
+  const r = run('glab', ['mr', 'view', String(n), '-F', 'json'], { cwd });
+  if (!r.ok) return { ok: false, body: '', reason: r.stderr };
+  try { return { ok: true, body: JSON.parse(r.stdout).description || '' }; } catch { return { ok: false, body: '', reason: 'unparseable mr json' }; }
+}
+
+// Replace the PR/MR description (used to upsert the trailer block).
+export function editPrBody(platform, n, body, { cwd } = {}) {
+  if (!platformReady(platform)) return { ok: false, reason: `${cliFor(platform) || 'platform CLI'} not available` };
+  const r = platform === 'github'
+    ? run('gh', ['pr', 'edit', String(n), '--body', body], { cwd })
+    : run('glab', ['mr', 'update', String(n), '--description', body], { cwd });
+  return { ok: r.ok, reason: r.stderr };
+}
+
+// Post a top-level comment/note (companion card deck, chat log, nudge — pass a noBlock()-tagged body).
+export function postComment(platform, n, body, { cwd } = {}) {
+  if (!platformReady(platform)) return { ok: false, reason: `${cliFor(platform) || 'platform CLI'} not available` };
+  const r = platform === 'github'
+    ? run('gh', ['pr', 'comment', String(n), '--body', body], { cwd })
+    : run('glab', ['mr', 'note', String(n), '-m', body], { cwd });
+  return { ok: r.ok, reason: r.stderr };
+}
+
+// Submit an APPROVE carrying the engagement marker. On GitLab an approval has no body, so the marker
+// is posted as a note (readPrGitLab attaches it to the approval); on GitHub it rides in the review body.
+export function submitApproval(platform, n, body = '', { cwd } = {}) {
+  if (!platformReady(platform)) return { ok: false, reason: `${cliFor(platform) || 'platform CLI'} not available` };
+  if (platform === 'github') {
+    const r = run('gh', ['pr', 'review', String(n), '--approve', '--body', body], { cwd });
+    return { ok: r.ok, reason: r.stderr };
+  }
+  const a = run('glab', ['mr', 'approve', String(n)], { cwd });
+  if (!a.ok) return { ok: false, reason: a.stderr };
+  if (body) {
+    // The engagement marker rides in this note (GitLab approvals carry no body). If it fails to post,
+    // the approval landed but the engagement signal is lost — report failure so the caller can retry.
+    const note = run('glab', ['mr', 'note', String(n), '-m', body], { cwd });
+    if (!note.ok) return { ok: false, reason: `approved, but failed to post the engagement note: ${note.stderr || 'unknown'}` };
+  }
+  return { ok: true };
+}
+
 export function createPr(platform, opts = {}) {
   if (!platformReady(platform)) return { ok: false, reason: `${cliFor(platform) || 'platform CLI'} not available` };
-  const r = run(cliFor(platform), buildPrArgs(platform, opts), { cwd: opts.cwd });
-  return { ok: r.ok, url: r.stdout.split('\n').pop(), reason: r.stderr };
+  const reviewers = opts.reviewers || [];
+  if (platform === 'github') {
+    const r = run('gh', buildPrArgs('github', { ...opts, reviewers: [] }), { cwd: opts.cwd });
+    if (!r.ok) return { ok: false, reason: r.stderr };
+    const url = r.stdout.split('\n').pop();
+    const number = prNumberFromUrl(url);
+    const added = []; const dropped = [];
+    if (number) {
+      for (const rv of reviewers) {
+        (run('gh', ['pr', 'edit', number, '--add-reviewer', rv], { cwd: opts.cwd }).ok ? added : dropped).push(rv);
+      }
+    }
+    return { ok: true, url, reviewers: added, mentioned: [], dropped };
+  }
+  // gitlab
+  const r = run('glab', buildPrArgs('gitlab', opts), { cwd: opts.cwd });
+  if (!r.ok) return { ok: false, reason: r.stderr };
+  const url = r.stdout.split('\n').pop();
+  const iid = prNumberFromUrl(url);
+  const rest = reviewers.slice(1);
+  // Only report a reviewer as `mentioned` if the @-mention note actually posted; otherwise they were
+  // neither assigned (single-field cap) nor notified — surface them as `dropped` so the caller warns.
+  let mentioned = []; let dropped = [];
+  if (rest.length && iid) {
+    const ats = rest.map((m) => `@${m}`).join(' ');
+    const note = run('glab', ['mr', 'note', iid, '-m', `Review requested (owner + reviewer rule): ${ats} — please review and approve/comment on this MR (this drives the gate).`], { cwd: opts.cwd });
+    if (note.ok) mentioned = rest; else dropped = rest;
+  } else if (rest.length) {
+    dropped = rest; // could not parse the IID to post the note
+  }
+  return { ok: true, url, reviewers: reviewers.slice(0, 1), mentioned, dropped };
 }

package/cli/reconcile.mjs

@@ -12,7 +12,7 @@ import {
 } from './plan.mjs';
 import { gitHead, packRepo } from './setup.mjs';
 
-const MARK = { missing: c.red('missing'), outdated: c.yellow('outdated'), stale: c.yellow('stale'), legacy: c.yellow('legacy'), removed: c.yellow('removed'), ok: c.green('ok') };
+const MARK = { missing: c.red('missing'), new: c.cyan('new'), outdated: c.yellow('outdated'), stale: c.yellow('stale'), legacy: c.yellow('legacy'), removed: c.yellow('removed'), ok: c.green('ok') };
 
 export async function reconcile(root, { fix = false, scope = 'all', force = false } = {}) {
   log(c.bold(`\nSDLC reconcile  ${c.dim('v' + VERSION)}`));
@@ -51,7 +51,7 @@ export async function reconcile(root, { fix = false, scope = 'all', force = fals
     if (!byScope.has(a.scope)) byScope.set(a.scope, []);
     byScope.get(a.scope).push(a);
   }
-  const counts = { missing: 0, outdated: 0, stale: 0, legacy: 0, removed: 0, ok: 0 };
+  const counts = { missing: 0, new: 0, outdated: 0, stale: 0, legacy: 0, removed: 0, ok: 0 };
   for (const [scopeName, items] of byScope) {
     const notOk = items.filter((i) => i.status !== 'ok');
     items.forEach((i) => counts[i.status]++);
@@ -65,7 +65,7 @@ export async function reconcile(root, { fix = false, scope = 'all', force = fals
     a.status !== 'ok' && (scope === 'all' ? true : a.status !== 'missing'),
   );
   log('');
-  log(c.dim(`summary: ${counts.missing} missing, ${counts.outdated} outdated, ${counts.stale} stale, ${counts.legacy} legacy, ${counts.removed} removed, ${counts.ok} ok`));
+  log(c.dim(`summary: ${counts.missing} missing, ${counts.new} new, ${counts.outdated} outdated, ${counts.stale} stale, ${counts.legacy} legacy, ${counts.removed} removed, ${counts.ok} ok`));
 
   if (!fix) {
     if (fixable.length || gaps.length) hand('run `yad check --fix` to reconcile (or `yad setup` for missing one-time setup).');

package/cli/review.mjs

@@ -0,0 +1,178 @@
+// `yad review trailer|context|nudge|reconcile` — the BACK-HALF Review Companion + bridge for code
+// PR/MRs (the analogue of `yad gate …` for the front half). The fun process (trailer/cards/chat/nudge)
+// makes the engineer review easy and visible; the bridge process (reconcile) maps the code PR's review
+// state — including the engagement signal — into the build ledger (build-log.json) at merge.
+//
+// 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, 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';
+
+// Resolve the target code repo: --repo <name> from the registry (platform + path + roles), else cwd.
+// An explicit --repo that is NOT in the registry is an error — never silently fall through to cwd (that
+// would operate on the wrong repo). Returns { error } in that case for the caller to surface.
+function resolveRepo(root, { repo, dir }) {
+  if (repo) {
+    const reg = readJSON(path.join(root, PROJECT_FILES.reposRegistry), { repos: [] });
+    const found = (reg.repos || []).find((r) => r.name === repo);
+    if (!found) return { error: `repo '${repo}' is not in .sdlc/repos.json — connect it first (yad-connect-repos)` };
+    return { repoRoot: path.resolve(root, found.path), meta: found };
+  }
+  return { repoRoot: path.resolve(root, dir || '.'), meta: null };
+}
+
+function platformOf(root, repoRoot, meta) {
+  if (meta?.platform) return meta.platform;
+  const remote = run('git', ['remote', 'get-url', 'origin'], { cwd: repoRoot }).stdout;
+  return detectPlatform(remote) || readJSON(path.join(root, PROJECT_FILES.hubConfig), {}).platform || null;
+}
+
+// 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) return { error: rr.error };
+  const { repoRoot, meta } = rr;
+  const platform = platformOf(root, repoRoot, meta);
+  const base = meta?.default_branch || 'main';
+  const bundle = {
+    repo: meta?.name || null,
+    repoRoot,
+    platform,
+    pr: pr || null,
+    base,
+    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,
+    contract: meta?.contract || null,
+    markers: {
+      trailerBegin: '<!-- yad:trailer -->', noblock: '<!-- yad:noblock -->',
+      engagementVerified: '<!-- yad:engagement verified -->', pair: '<!-- yad:pair -->',
+    },
+  };
+  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
+// the code PR/MR description (delimited block; safe to re-run after a push).
+export async function reviewTrailer(root, { repo, dir, pr, body, getBody = getPrBody, editBody = editPrBody } = {}) {
+  if (!pr) { fail('--pr <n> is required'); process.exitCode = 1; return; }
+  if (!body || !String(body).trim()) { fail('trailer body is required: `yad review trailer --repo <r> --pr <n> --body <text>`'); process.exitCode = 1; return; }
+  const rr = resolveRepo(root, { repo, dir });
+  if (rr.error) { fail(rr.error); process.exitCode = 1; return; }
+  const { repoRoot, meta } = rr;
+  const platform = platformOf(root, repoRoot, meta);
+  if (!platform) { fail('could not detect platform (github/gitlab)'); process.exitCode = 1; return; }
+  const cur = getBody(platform, pr, { cwd: repoRoot });
+  if (!cur.ok) { fail(`could not read PR #${pr}: ${cur.reason || 'unknown'}`); process.exitCode = 1; return; }
+  const r = editBody(platform, pr, upsertTrailerBlock(cur.body, String(body).trim()), { cwd: repoRoot });
+  if (!r.ok) { fail(`could not update PR #${pr}: ${r.reason || 'unknown'}`); process.exitCode = 1; return; }
+  ok(`trailer posted to ${platform === 'gitlab' ? 'MR' : 'PR'} #${pr}`);
+  return { number: pr };
+}
+
+// `yad review nudge --repo <r> --pr <n>` — friendly public @-mention on a bare approve (engagement none)
+// of a code PR. A platform comment (carries the noblock marker so it never blocks); call once per PR.
+export async function reviewNudge(root, { repo, dir, pr, reader = readPr, poster = postComment } = {}) {
+  if (!pr) { fail('--pr <n> is required'); process.exitCode = 1; return; }
+  const rr = resolveRepo(root, { repo, dir });
+  if (rr.error) { fail(rr.error); process.exitCode = 1; return; }
+  const { repoRoot, meta } = rr;
+  const platform = platformOf(root, repoRoot, meta);
+  if (!platform) { fail('could not detect platform (github/gitlab)'); process.exitCode = 1; return; }
+  const pull = reader(platform, pr, { cwd: repoRoot });
+  if (!pull.ok) { warn(`could not read PR #${pr}: ${pull.reason}`); process.exitCode = 1; return; }
+  let nudged = 0;
+  for (const rv of pull.reviews) {
+    if (rv.state !== 'APPROVED' || parseEngagement(rv.body) === 'verified' || !rv.login) continue;
+    if (poster(platform, pr, nudgeMessage(rv.login, NUDGE_CMD), { cwd: repoRoot }).ok) nudged++;
+  }
+  if (nudged) info(`nudged ${nudged} bare approval(s) — invited to run \`${NUDGE_CMD}\``);
+  else ok('no un-engaged approvals to nudge');
+  return { nudged };
+}
+
+// `yad review reconcile --epic <id> --repo <r> --pr <n>` — the back-half BRIDGE: read the code PR's
+// approvals (with the engagement signal) and stamp them onto the matching build-log.json ship record,
+// so the build ledger reflects who actually engaged. The first CLI to write build-log.json. Matches the
+// ship record by its `pr` field (url or number); if none exists yet, prints the engineer_review block
+// for the engineer/CI to attach at ship time (we never fabricate a story/task).
+export async function reviewReconcile(root, { epic, repo, dir, pr, reader = readPr } = {}) {
+  if (!epic) { fail('--epic <id> is required'); process.exitCode = 1; return; }
+  if (!pr) { fail('--pr <n> is required'); process.exitCode = 1; return; }
+  const rr = resolveRepo(root, { repo, dir });
+  if (rr.error) { fail(rr.error); process.exitCode = 1; return; }
+  const { repoRoot, meta } = rr;
+  const platform = platformOf(root, repoRoot, meta);
+  if (!platform) { fail('could not detect platform (github/gitlab)'); process.exitCode = 1; return; }
+  const hub = readJSON(path.join(root, PROJECT_FILES.hubConfig), { roster: [] });
+  const registry = readJSON(path.join(root, PROJECT_FILES.reposRegistry), { repos: [] });
+  const domain = meta?.name ? [meta.name] : [];
+  const pull = reader(platform, pr, { cwd: repoRoot });
+  if (!pull.ok) { fail(`could not read PR #${pr}: ${pull.reason}`); process.exitCode = 1; return; }
+
+  // Map platform approvals → engineer_review entries, deduped by (approver, role, domain), carrying the
+  // engagement signal read from the approve body/note.
+  const recs = mapApprovers(pull.reviews, { roster: hub.roster || [], repos: registry.repos || [], touchedDomains: domain, headOid: pull.headOid });
+  const seen = new Set();
+  const engineerReview = [];
+  for (const r of recs) {
+    const key = `${r.name}|${r.role}|${r.domain || ''}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    engineerReview.push({ approver: r.name, role: r.role, ...(r.domain ? { domain: r.domain } : {}), engagement: r.engagement === 'verified' ? 'verified' : 'none' });
+  }
+
+  const file = epicFiles(epicRoot(root, epic)).buildLog;
+  const ledger = readJSON(file, null);
+  // Match by exact PR number — never substring (`--pr 5` must not match a ship recorded against #15).
+  const ship = ledger?.ships?.find((s) => s.pr != null
+    && (String(s.pr) === String(pr) || prNumberFromUrl(s.pr) === String(pr)));
+  if (!ship) {
+    warn(`no build-log ship record matches PR #${pr} in ${epic} — attach this at ship time:`);
+    log(JSON.stringify({ engineer_review: engineerReview }, null, 2));
+    return { engineerReview, written: false };
+  }
+  ship.engineer_review = engineerReview;
+  writeJSON(file, ledger);
+  ok(`stamped engagement onto ${epic} ship ${ship.story || ''}${ship.task ? '/' + ship.task : ''} (PR #${pr})`);
+  return { engineerReview, written: true };
+}

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.0.0",
+  "version": "3.2.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

@@ -63,6 +63,26 @@ review_gate:
   revoke_on: artifact-change    # re-hash the artifact (contract surface for architecture); a changed
                                 # hash drops the bound approvals so reviewers re-approve. NOT per-commit.
   block_on_unresolved_comments: true   # any unresolved thread / CHANGES_REQUESTED holds it in_review
+  # Review Companion engagement (yad-review-companion). Each approval records engagement: verified|none
+  # — verified when reviewed through the companion (trailer/cards/chat), none for a bare click. SOFT by
+  # default: both count, a bare approve still passes but draws a friendly public @-mention nudge so
+  # review quality is VISIBLE without blocking anyone ("visible, not impossible"). Flip to true to make
+  # only verified approvals count (the signal is gameable by design — it raises the cost of a rubber-
+  # 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

@@ -3,6 +3,8 @@ SDLC Workflow,yad-discovery,Project Discovery,DI,"Optional front-zero (once per
 SDLC Workflow,yad-analysis,Author Analysis,AN,"Optional front state: with the analyst pressure-test a feature idea and write the discovery brief into analysis.md. Assigns the EP-<slug> ID and seeds .sdlc state (the chain that puts analysis before epic). If skipped, the epic step does this shaping inline. Never auto-advances.",,{idea: one-line feature idea},1-front,,yad-review-gate,false,epics/EP-<slug>/,analysis.md state.json
 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