yadflow 3.0.0 → 3.1.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,145 @@
+// `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, 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';
+
+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;
+}
+
+// `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 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);
+  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,
+    markers: { trailerBegin: '<!-- yad:trailer -->', noblock: '<!-- yad:noblock -->', engagementVerified: '<!-- yad:engagement verified -->' },
+  };
+  log(JSON.stringify(bundle, null, 2));
+  return bundle;
+}
+
+// `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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yadflow",
-  "version": "3.0.0",
+  "version": "3.1.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,14 @@ 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
 
 # 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/module-help.csv

@@ -3,6 +3,7 @@ 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-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-connect-repos/references/hub-config.md

@@ -19,6 +19,7 @@ login to an SDLC name + role. It is a single object for the hub itself — the s
   "git_url": "https://github.com/abdelrahmannasr/yadflow.git",
   "default_branch": "main",
   "bridge_enabled": true,                                     // open review PRs/MRs on the hub for front-half reviews
+  "review": { "requireEngagement": false },                   // Review Companion: false (soft) counts bare approves but nudges; true counts only verified-engagement approvals
   "detectedAt": "2026-06-08",                                 // last detect-hub run (YYYY-MM-DD)
   "roster": [
     { "login": "abdelrahmannasr", "name": "alice", "email": "alice@example.com",
@@ -76,6 +77,15 @@ as the registry). `detect-hub` upserts `hub.json` in place — it is idempotent
   existing **file-only** flow with no error. The file ledger is the source of truth in both modes.
 - The master switch `config.yaml` `hub.bridge: false` disables the bridge globally regardless of `hub.json`.
 
+## Review Companion engagement (`review.requireEngagement`)
+
+`review.requireEngagement` (default `false`) controls the [Review Companion](../../yad-review-companion/SKILL.md)
+engagement gate. Each approval records `engagement: verified | none`. **Soft (`false`):** both count — a
+bare approve still passes but draws a friendly public nudge, so review *quality* is visible without
+blocking. **Strict (`true`):** the predicate counts only `verified` approvals. The signal is gameable by
+design ("visible, not impossible") — it raises the cost of a rubber-stamp, it does not prove a human
+read the artifact. Applies to both the front gate and the back-half engineer review.
+
 ## Git tracking
 
 Commit `hub.json` — it is small, reviewable, and carries no secrets (logins and names only, never tokens).

package/skills/yad-docs-overview/references/pipeline-model.md

@@ -56,6 +56,7 @@ The gated authoring chain + the reusable review gate (10 steps, or 12 with the o
 | `yad-stories` | → `stories-review` (per-repo routing) | `stories/EP-<slug>-S0N.md` |
 | `yad-test-cases` | → `test-cases-review` (parallel, non-blocking) | `test-cases.md`, `test-links.json` |
 | `yad-review-gate` | the shared gate | `reviews/*.md`, `approvals.json`, `comments.json` |
+| `yad-review-companion` | the fun/visible review layer (trailer/cards/chat + engagement) | `approvals.json` `engagement`, platform trailer/cards |
 | `yad-hub-bridge` | the platform PR/MR bridge | `hub-prs.json` |
 
 ### Path: Build half (`phase: 3-build`)

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

@@ -39,11 +39,22 @@ a **second set of eyes, never the authority**: it cannot approve or merge. Where
 (no remote), run an equivalent AI first-pass by hand and capture its notes. Record that the AI review
 ran; surface its findings to the engineer. Do **not** treat AI approval as a gate.
 
+Also run the **Review Companion** so the human review is easy and fun: post the 60-sec trailer
+(`yad review trailer --repo <r> --pr <n> --body "<text>"`) and deal the swipe cards / open the grounded
+chat from the bundle (`yad review context --repo <r> --pr <n>` → [yad-review-companion](../yad-review-companion/SKILL.md)).
+Companion comments carry `<!-- yad:noblock -->` (history-only, never block); genuine concerns are posted
+unflagged and block normally.
+
 ### 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
 `../yad-pr-template/templates/checks/risk-route.sh` on the PR body): base, or escalated to a
 domain-owner per touched domain. Record each approval; re-evaluate whether the rule is satisfied.
+Record `engagement: verified` when the engineer reviewed through the companion (else `none` for a bare
+approve); `yad review reconcile --epic <id> --repo <r> --pr <n>` stamps it onto the ship record from the
+platform. Soft by default (both count; a bare approve draws `yad review nudge`); only gates when
+`hub.review.requireEngagement: true`. The signal is gameable by design and sits **beside** the CI gates,
+never above them.
 Recording an approval does **not** ship — shipping is a separate, explicit step. Front-half discipline:
 the gate talks only through files; refuse to treat AI review as a human approval.
 
@@ -55,8 +66,8 @@ engineer-review rule is satisfied (Step 2). Then:
   ```json
   { "story": "<story>", "task": "<task>", "repo": "<repo>", "branch": "feat/<story>-<task>-…",
     "pr": "<url|#>", "mergeCommit": "<sha>", "gates": ["spec-link","contract-check","build-test-lint"],
-    "ai_review": "coderabbit (advisory)", "engineer_review": [{"approver":"<name>","role":"<role>","domain":"<opt>"}],
-    "risk": "<low|medium|high>", "shippedAt": "<YYYY-MM-DD>" }
+    "ai_review": "coderabbit (advisory)", "engineer_review": [{"approver":"<name>","role":"<role>","domain":"<opt>","engagement":"<verified|none>"}],
+    "companion": {"trailer":true,"cards":true,"chat":false}, "risk": "<low|medium|high>", "shippedAt": "<YYYY-MM-DD>" }
   ```
 - **Update the story state** — when **every** task in `specs/<story>/tasks.md` has a ship record, set
   the story frontmatter `status: shipped`; otherwise `status: in-build`. The chain

package/skills/yad-engineer-review/references/ship-and-record.md

@@ -33,9 +33,10 @@ Append-only. One record per shipped task:
       "gates": ["spec-link", "contract-check", "build-test-lint"],
       "ai_review": "coderabbit (advisory)",
       "engineer_review": [
-        { "approver": "amelia", "role": "owner" },
-        { "approver": "carol", "role": "reviewer" }
+        { "approver": "amelia", "role": "owner", "engagement": "verified" },
+        { "approver": "carol", "role": "reviewer", "engagement": "none" }
       ],
+      "companion": { "trailer": true, "cards": true, "chat": false },
       "risk": "low",
       "shippedAt": "2026-06-06"
     }
@@ -46,6 +47,18 @@ Append-only. One record per shipped task:
 This is the back-half analogue of the front half's `approvals.json` — files only, no hidden state, so a
 future service can drive ship by writing the same records.
 
+**Engagement (the Review Companion).** Each `engineer_review` entry carries `engagement: verified | none`
+— `verified` when the engineer reviewed through the [companion](../../yad-review-companion/SKILL.md)
+(`yad review trailer/context/nudge`, a real trailer/cards/chat session over the diff), `none` for a bare
+approve. The optional `companion` block records which faces ran. It is **soft by default** (both count;
+a bare approve draws a friendly `yad review nudge`); it only gates ship when
+`hub.review.requireEngagement: true`. `yad review reconcile --epic <id> --repo <r> --pr <n>` reads the
+code PR's approvals (with the engagement signal) and stamps them onto the matching ship record — the
+back-half **bridge**, the analogue of `yad gate sync`. The signal is gameable by design ("visible, not
+impossible"): it makes engineer-review quality visible, it does not prove a human read the diff. It sits
+**beside** the CI gates (build/test/lint/contract/verified-commits) — never above them; CI still
+decides machine safety, the merge is still the human act.
+
 ## Story state
 
 The story frontmatter `status` reflects build progress:

package/skills/yad-hub-bridge/references/bridge.md

@@ -35,6 +35,40 @@ glab api projects/:id/merge_requests/:iid/notes          # discussion notes (com
 All commands run as the **local user**; the bridge stores no tokens. If the CLI is missing/unauthenticated
 or the remote is unreachable, the bridge stops and the gate falls back to file-only (no error).
 
+> **GitLab read parity (GAP-6).** `readPrGitLab` reads approvals (`approved_by[]`) and discussions but
+> does **not** map a "Request changes" reviewer state to `CHANGES_REQUESTED` — on GitLab the blocking
+> signal is an **unresolved discussion**. So on GitLab the gate is held by unresolved threads, not by a
+> reviewer state. (GitHub maps both.) If you need GitLab "Request changes" honored, read
+> `reviewers[].state` from the MR and map it to `CHANGES_REQUESTED`.
+
+## Open recipes (request the reviewers — used by `yad gate open` / `yad open-pr`)
+
+Opening the review PR/MR must **request the required reviewers**, or an escalated gate is opened with
+nobody asked. The CLI (`createPr` in `cli/platform.mjs`) does this; an agent opening a PR by hand uses:
+
+**GitHub** — create, then add each reviewer (a bad/non-collaborator login WARNS instead of aborting the
+whole create):
+```bash
+gh pr create --title "review: <artifact> (<epic>)" --body <body> --base <default> --head <branch> \
+  --assignee @me --label domain:<repo>
+gh pr edit <n> --add-reviewer <login>      # once per required reviewer
+```
+
+**GitLab** — a Free/Core MR carries a **single** reviewer field (multiple reviewers is Premium), so
+assign the first required reviewer and **@-mention the rest in a note** so they are still notified/routed:
+```bash
+glab mr create --title "review: <artifact> (<epic>)" --description <body> \
+  --target-branch <default> --source-branch <branch> --reviewer <first-login> --label domain:<repo> --yes
+glab mr note <iid> -m "Review requested (owner + reviewer rule): @<l2> @<l3> — please review and approve/comment on this MR (this drives the gate)."
+```
+The read side counts a mentioned reviewer normally: their eventual **approval** still appears in
+`…/approvals → approved_by[]`, and their **note** in `…/discussions` — so the single-reviewer-field cap
+loses only the native "Reviewers" UI chip, not the gate routing.
+
+Required reviewers = the hub's `reviewer`/`domain-owner` roster logins for the touched scopes, PLUS any
+repo whose ownership lives only in `repos.json` `domain_owner`/`domain_owners` (those are resolved to a
+login and requested too — otherwise an escalated step is structurally unsatisfiable through routing).
+
 ## Login → role resolution (order)
 
 1. Roster (`.sdlc/hub.json`) maps `login` → `name` + base `role` (owner/reviewer).

package/skills/yad-open-pr/SKILL.md

@@ -62,6 +62,16 @@ PR/MR with the auto-assigned assignee + reviewers.
 On `high` risk or a contract touch, run `bash checks/risk-route.sh <pr-body>` to print the required
 domain-owner reviewers — the same escalation `yad-engineer-review` enforces.
 
+### Step 3b — Post the review trailer (optional, recommended)
+Make the reviewer's job easy: generate the 60-sec briefing and post it to the new PR/MR so it greets
+every reviewer in the UI (idempotent; safe to re-run after a push):
+```bash
+yad review trailer --repo <name> --pr <n> --body "<companion-generated briefing>"
+```
+The full fun-review flow (cards + grounded chat + engagement) is driven by the
+[Review Companion](../yad-review-companion/SKILL.md) during `yad-engineer-review`. Non-blocking by
+design — companion comments carry `<!-- yad:noblock -->`.
+
 ### Step 4 — Stop (no merge)
 Report the PR/MR URL and the requested reviewers. The PR now runs the check gates (Step C); the human
 engineer review and merge happen in `yad-engineer-review` (Step E).