yadflow 2.18.1 → 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

@@ -8,11 +8,11 @@ import {
 import { VERSION, PROJECT_FILES } from './manifest.mjs';
 import {
   moduleActions, repoActions, hubActions, authorsActions,
-  legacyModuleActions, legacyRepoActions, legacyHubActions,
+  legacyModuleActions, removedModuleActions, legacyRepoActions, legacyHubActions,
 } 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'), 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)}`));
@@ -26,9 +26,10 @@ export async function reconcile(root, { fix = false, scope = 'all', force = fals
   if (!exists(path.join(root, PROJECT_FILES.reposRegistry))) gaps.push('no repos registered (.sdlc/repos.json absent)');
 
   // --- deterministic file actions (module + hub CI + author allowlists + every registered repo),
-  //     plus pre-2.0 sdlc-* -> yad-* migrations ('legacy': old name installed; rename in place) ---
+  //     plus pre-2.0 sdlc-* -> yad-* migrations ('legacy': old name installed; rename in place)
+  //     and purge of skills removed in a later release ('removed': delete the lingering install) ---
   const actions = [
-    ...moduleActions(root), ...legacyModuleActions(root),
+    ...moduleActions(root), ...legacyModuleActions(root), ...removedModuleActions(root),
     ...hubActions(root), ...legacyHubActions(root),
     ...authorsActions(root, registry.repos),
   ];
@@ -50,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, 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]++);
@@ -64,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.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/cli/setup.mjs

@@ -9,7 +9,7 @@ import {
 import { VERSION, IDE_FOLDER_TARGETS, PROJECT_FILES, DESIGN_TOOLS, DESIGN_PRIMARY, TESTING_TOOLS, TESTING_PRIMARY, LEARNING_TOOLS, LEARNING_PRIMARY } from './manifest.mjs';
 import {
   moduleActions, repoActions, hubActions, authorsActions,
-  legacyModuleActions, legacyRepoActions, legacyHubActions,
+  legacyModuleActions, removedModuleActions, legacyRepoActions, legacyHubActions,
 } from './plan.mjs';
 import { validateLogin, rolesForScope } from './platform.mjs';
 
@@ -399,6 +399,9 @@ export async function runSetup(root, opts = {}) {
   // IDE targets and install their yad-* renames. Without this, setup only ADDED yad-* and left
   // stale sdlc-* sitting next to them (the rename only ran under `yad update` / `yad check --fix`).
   applyActions(legacyModuleActions(root, ideTargets), { force: true });
+  // Purge any skill removed in a later release (REMOVED_SKILLS) that a prior install left behind —
+  // setup only ADDS current skills, so without this a breaking removal would linger next to them.
+  applyActions(removedModuleActions(root, ideTargets), { force: true });
   ok(`module installed into: ${ideTargets.join(', ')}`);
 
   // Global leftovers: a pre-2.0 install may have put sdlc-* skills in the user's global
@@ -416,6 +419,18 @@ export async function runSetup(root, opts = {}) {
     }
   }
 
+  // Same opt-in pass for skills removed in a later release (REMOVED_SKILLS) that linger in the
+  // global ~/.claude/skills — purge them so a global install also drops the dead command.
+  const globalRemoved = process.env.SDLC_NONINTERACTIVE ? [] : removedModuleActions(os.homedir(), ['.claude']);
+  if (globalRemoved.length) {
+    if (await askYesNo(`Found ${globalRemoved.length} removed skill(s) in your global ~/.claude/skills. Delete them?`, true)) {
+      applyActions(globalRemoved, { force: true });
+      ok('purged removed skill(s) from global ~/.claude/skills');
+    } else {
+      info('left global ~/.claude/skills untouched — re-run `yad setup` or purge later with `yad update`');
+    }
+  }
+
   // Detect hub platform + roster
   S(solo ? 'Hub platform (solo — no roster)' : 'Hub platform & reviewer roster');
   guide(solo
@@ -619,7 +634,7 @@ export async function runSetup(root, opts = {}) {
   }
 
   // Wire each connected repo + the hub itself
-  S('Wire connected repos + the hub (CI gates, PR template, comment scaffold, gate-sync)');
+  S('Wire connected repos + the hub (CI gates, PR template, gate-sync)');
   guide(['Installs the CI safety gates, PR/MR template, and gate-sync — automatic, no input needed.']);
   if (registry.repos.length === 0) info('no repos to wire');
   for (const repo of registry.repos) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "yadflow",
-  "version": "2.18.1",
-  "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 + 35 yad-* skills.",
+  "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",
   "license": "MIT",

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/install.sh

@@ -11,10 +11,27 @@ 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-review-comments 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-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
+# (current name + any pre-rename alias) so the breaking removal takes effect for existing installs.
+# Mirrors the CLI's REMOVED_SKILLS purge in `yad update`.
+REMOVED_SKILLS=(yad-review-comments sdlc-review-comments)
 
 echo "Installing sdlc module from $ROOT/skills ..."
 
+for ide in .claude .agents .zencoder; do
+  for s in "${REMOVED_SKILLS[@]}"; do
+    rm -rf "$ide/skills/$s"
+  done
+done
+if [ -d ".opencode/commands" ]; then
+  for s in "${REMOVED_SKILLS[@]}"; do
+    rm -f ".opencode/commands/$s.md"
+  done
+fi
+
 # 1. Folder-per-skill IDEs: .claude, .agents, .zencoder
 for ide in .claude .agents .zencoder; do
   for s in "${SKILLS[@]}"; do

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
@@ -20,7 +21,6 @@ SDLC Workflow,yad-pr-template,PR/MR Template,PT,"Build-half Step D: detect a cod
 SDLC Workflow,yad-commit,Commit by Convention,CM,"Build-half helper: commit ONE staged atomic change by the conventions — a Conventional-Commits subject, the fixed trailer block (Task -> Contract-Change -> Co-Authored-By), and the <=3-file atomic guard. The human git author owns the commit; an assisting AI is recorded only as a Co-Authored-By footer chosen per-commit with --ai (claude|copilot|cursor|coderabbit|none, default none). Drives the yad commit CLI. Never auto-advances.",,{type: feat|fix|...} {message: subject} {ai: <tool|none>} {task: <id>} {contract-change: true|false},3-build,yad-implement,,false,<repo>/,one commit
 SDLC Workflow,yad-open-pr,Open PR/MR,OP,"Build-half helper: open a code-repo task PR/MR from the committed platform template — detect GitHub/GitLab, push the task branch, create the PR/MR with the body prefilled (Summary / Story-task / Impact & Risk) and the title defaulting to the commit subject. Auto-assigns from the hub roster (assignee = committer, reviewers = repo reviewers + domain-owners); high risk / contract surface routes to domain owners (risk-route.sh). Drives the yad open-pr CLI. Never merges; never auto-advances.",,{repo: <name>} {risk: low|medium|high} {contract-change: true|false},3-build,yad-commit,,false,<repo>/,one PR/MR
 SDLC Workflow,yad-ship,Commit + Open PR/MR,SP2,"Build-half helper: commit AND open the task PR/MR in one step — a thin orchestration over yad-commit then yad-open-pr. Commits the staged atomic change by the conventions, then pushes the branch and opens the PR/MR from the committed template with the roster auto-assigned. The PR step runs ONLY if the commit lands (a failed commit, tripped guard, or --dry-run stops before pushing). Drives the yad ship CLI. Never merges; never auto-advances.",,{type: feat|fix|...} {message: subject} {ai: <tool|none>} {repo: <name>} {risk: low|medium|high} {contract-change: true|false},3-build,yad-pr-template,,false,<repo>/,one commit + one PR/MR
-SDLC Workflow,yad-review-comments,Review Comment Templates,RC,"Install platform-matched PR/MR review-comment scaffolds (committed REVIEW_COMMENTS.md) into a code repo or the product hub, so reviewers leave structured, attributable feedback whose **name (role)** headers map cleanly into the SDLC file ledger. GitHub Saved Replies / GitLab comment templates are per-user, so a committed doc is the repo-level mechanism. Never auto-advances.",,{repo: <one of an epic's repos | hub>} {action: wire},3-build,,,false,<repo>/.github|.gitlab/,REVIEW_COMMENTS.md
 SDLC Workflow,yad-hub-bridge,Hub Review Bridge,HB,"The templated PR/MR bridge for the front-half review gate: when the product hub has a platform (.sdlc/hub.json), open a review PR/MR on the hub for an authored artifact, set required reviewers/labels from the routing rule, and provide the read-only gh/glab recipes yad-review-gate's sync uses to pull platform comments + approvals into the file ledger. Local-user auth, no stored tokens; file ledger stays the source of truth; degrades to file-only when no platform/CLI. Never auto-advances.",,{epic: EP-<slug>} {artifact: epic.md|architecture.md|ui-design.md|stories/} {action: open|route},1-front,yad-review-gate,yad-review-gate,false,epics/EP-<slug>/.sdlc/,hub-prs.json
 SDLC Workflow,yad-engineer-review,Engineer Review & Merge,ER,"Build-half Step E: wire an advisory AI first-pass (CodeRabbit) on the PR, record the human engineer review with the same human_approve discipline as the front gates (owner + 1 reviewer, escalating to domain owners on high risk / contract / auth / payments), and on merge record the ship in epics/<epic>/.sdlc/build-log.json and update the story state. AI review is advisory, never the authority; the human owns the merge. Never auto-advances.",,{epic: EP-<slug>} {story: EP-<slug>-S0N} {task: T0N} {repo: <repo>} {action: ai-review|approve|ship},3-build,yad-ship,,false,epics/EP-<slug>/.sdlc/,build-log.json story-status
 SDLC Workflow,yad-backfill,Backfill Specs,BF,"Build-half Step G: generate specs for already-built features in an existing repo. Confirm Repomix (npx repomix CLI), pack ONE feature (compress + git logs, secret-scan), feed to AI with a 'describe what exists, do not invent' prompt, write a DRAFT spec marked verified: false. Human approval (reuse yad-review-gate) makes it real. Boundary auto-proposed and human-confirmed. A change is blocked only until the features it touches have approved specs. Never auto-advances.",,{repo: <repo>} {feature: <name + globs>} {action: pack|draft|approve|gate},3-build,,,false,demo-repos/<repo>/specs/backfill/<feature>/,spec.md backfill-check.sh

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,8 +56,8 @@ 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` |
-| `yad-review-comments` | comment scaffolds | repo comment templates |
 
 ### Path: Build half (`phase: 3-build`)
 Per-story, per-repo: `spec → tasks → implement → checks → engineer-review`, plus the commit/PR helpers.