yadflow 4.0.0-next.3 → 4.0.0

package/cli/repo.mjs

@@ -1,17 +1,31 @@
-// `yad repo list|refresh|sync` — connected-repo maintenance as explicit HUMAN decisions.
+// `yad repo list|refresh|sync|clone` — connected-repo maintenance as explicit HUMAN decisions.
 // list/refresh: staleness of the cached code-context pack (HEAD != syncedHead). Skill steps no longer
 // silently repack a stale repo; they flag it and point here. (`yad check --fix` refreshes too — also
 // human-invoked.) sync: switch every connected repo to its registry default_branch and fast-forward
 // it to origin — a working-tree-only op (it never writes the registry; a dirty tree is skipped).
+// clone (E81): clone every registered repo that is missing on this machine — `yad join`'s clone step,
+// for the repo a teammate registered after you joined. It never runs git in a repo already there.
+import fs from 'node:fs';
 import path from 'node:path';
-import { c, log, ok, info, warn, hand, fail, readJSON, writeJSON, run } from './lib.mjs';
+import { c, log, ok, info, warn, hand, fail, writeJSON, run } from './lib.mjs';
 import { PROJECT_FILES } from './manifest.mjs';
+import { judgeRepo, cloneMissingRepos, reportClones, readRegistry, codeContextPathOk, CODE_CONTEXT_DIR, runnable, shown } from './workspace.mjs';
 import { gitHead, packRepo } from './setup.mjs';
-import { publishCodeContext } from './repo-publish.mjs';
+import { publishCodeContext, packOf, codeMapOf } from './repo-publish.mjs';
 
+// Why `refresh` will not pack this entry, or null when it will (E81): see the loop in `runRepo`.
+function notPackable(root, repo, j) {
+  if (j.state === 'missing') return 'not cloned on this machine (`yad repo clone`)';
+  if (j.state === 'refused') return j.reason;
+  if (j.linked) return 'a folder on its path, inside a repo, is a link, so the checkout is not where the path says';
+  if (!codeContextPathOk(root, packOf(repo)) || !codeContextPathOk(root, codeMapOf(repo))) return `its contextPack or codeMap is not a path under ${CODE_CONTEXT_DIR}/ in the Product`;
+  return null;
+}
+
+// Strict (E81): a registry that does not parse is said, not read as "no repos" — and `refresh` writes it
+// back, so a lenient read would replace a broken file (and every entry in it) with an empty list.
 function load(root) {
-  const regPath = path.join(root, PROJECT_FILES.reposRegistry);
-  return { regPath, registry: readJSON(regPath, { repos: [] }) };
+  return { regPath: path.join(root, PROJECT_FILES.reposRegistry), ...readRegistry(root) };
 }
 
 // HEAD != syncedHead => stale (config.yaml code_context.staleness: head-sha). A repo that has a HEAD but
@@ -29,45 +43,83 @@ const git = (cwd, ...args) => run('git', args, { cwd });
 const hasRemote = (cwd, remote = 'origin') => git(cwd, 'remote', 'get-url', remote).ok;
 const isDirty = (cwd) => { const r = git(cwd, 'status', '--porcelain'); return r.ok && r.stdout.length > 0; };
 const currentBranch = (cwd) => { const r = git(cwd, 'rev-parse', '--abbrev-ref', 'HEAD'); return r.ok ? r.stdout : null; };
-// Registry default_branch wins; else origin/HEAD; else 'main'.
+// Registry default_branch wins; else origin/HEAD; else 'main'. The registry is shared content, and the
+// name is handed to `git fetch` and `git checkout`: `--upload-pack=<command>` would run a command. So a
+// recorded name must be a valid `refs/heads/<name>` (which also rules out `@{-1}`) and must not start
+// with `-` or `+` (a forced refspec); anything else is null.
 function defaultBranch(cwd, repo) {
-  if (repo.default_branch) return repo.default_branch;
+  if (repo.default_branch != null && repo.default_branch !== '') {
+    const b = repo.default_branch;
+    return typeof b === 'string' && !/^[-+]/.test(b) && git(cwd, 'check-ref-format', `refs/heads/${b}`).ok ? b : null;
+  }
+  // origin/HEAD is what the remote says — the remote the registry chose — so it passes the same test.
   const r = git(cwd, 'symbolic-ref', '--short', 'refs/remotes/origin/HEAD');
-  return r.ok && r.stdout ? r.stdout.replace(/^origin\//, '') : 'main';
+  if (!r.ok || !r.stdout) return 'main';
+  const b = r.stdout.replace(/^origin\//, '');
+  return !/^[-+]/.test(b) && git(cwd, 'check-ref-format', `refs/heads/${b}`).ok ? b : null;
 }
 
 export async function runRepo(root, { action = 'list', name, today, push = false, allowBranch = false } = {}) {
-  const { regPath, registry } = load(root);
+  const { regPath, registry, problem } = load(root);
+  if (problem) { fail(`${problem} — fix it in the Product and re-run`); process.exitCode = 1; return { action, repos: [] }; }
   if (!registry.repos.length) { warn('no repos registered (.sdlc/repos.json) — run `yad setup`'); return { action, repos: [] }; }
+  // An entry that is not an object (`null`, `5`) is named where it would be acted on, never dereferenced.
+  const isEntry = (r) => !!r && typeof r === 'object' && !Array.isArray(r);
+  const odd = registry.repos.filter((r) => !isEntry(r)).length;
+  if (odd) warn(`${odd} entr${odd > 1 ? 'ies' : 'y'} in ${PROJECT_FILES.reposRegistry} ${odd > 1 ? 'are' : 'is'} not an object — skipped; fix ${odd > 1 ? 'them' : 'it'} in the Product`);
+  const entries = registry.repos.filter(isEntry);
 
   if (action === 'list') {
     log(c.bold('\nconnected repos'));
     let staleCount = 0;
     const rows = [];   // the --json answer (E1): each repo, as the list reads it
-    for (const repo of registry.repos) {
+    let missing = 0;
+    for (const repo of entries) {
+      // Judged before git runs (E81): only a checkout that is there is read. A missing repo says so and
+      // names the command that clones it; a refused entry says why — git is never run in it.
+      const j = judgeRepo(root, repo);
+      // A checkout behind a link inside a repo's tree is not read either, as `sync` and `refresh` skip it.
+      if (j.linked) Object.assign(j, { state: 'refused', reason: 'a folder on its path, inside a repo, is a link, so the checkout is not where the path says' });
+      if (j.state === 'missing' || j.state === 'refused') {
+        rows.push({ name: repo.name ?? null, path: repo.path ?? null, head: null, syncedHead: repo.syncedHead ?? null, state: j.state === 'missing' ? 'missing' : 'refused', ...(j.reason ? { reason: j.reason } : {}) });
+        if (j.state === 'missing') { missing++; warn(`${j.name} ${c.dim(`(${j.path})`)} — ${c.yellow('not cloned on this machine')}`); }
+        else warn(`${j.name} ${c.dim(`(${j.path})`)} — ${j.reason}`);
+        continue;
+      }
       const { head, stale, unknown, neverPacked } = staleness(root, repo);
       rows.push({ name: repo.name ?? null, path: repo.path ?? null, head: head || null, syncedHead: repo.syncedHead ?? null,
         state: unknown ? 'unreadable' : neverPacked ? 'no-pack' : stale ? 'stale' : 'fresh' });
-      if (unknown) { warn(`${repo.name} ${c.dim(`(${repo.path})`)} — HEAD unreadable`); continue; }
-      if (neverPacked) { staleCount++; warn(`${repo.name} ${c.dim(`(${repo.path})`)} — ${c.yellow('no code-context pack yet')} (registered without one)`); }
-      else if (stale) { staleCount++; warn(`${repo.name} ${c.dim(`(${repo.path})`)} — ${c.yellow('stale')} (HEAD moved since last pack)`); }
-      else ok(`${repo.name} ${c.dim('— fresh')}`);
+      if (unknown) { warn(`${j.name} ${c.dim(`(${j.path})`)} — HEAD unreadable`); continue; }
+      if (neverPacked) { staleCount++; warn(`${j.name} ${c.dim(`(${j.path})`)} — ${c.yellow('no code-context pack yet')} (registered without one)`); }
+      else if (stale) { staleCount++; warn(`${j.name} ${c.dim(`(${j.path})`)} — ${c.yellow('stale')} (HEAD moved since last pack)`); }
+      else ok(`${j.name} ${c.dim('— fresh')}`);
     }
-    if (staleCount) hand(`refresh with \`yad repo refresh${registry.repos.length > 1 ? ' <name>' : ''}\` (or \`yad repo refresh\` for all)`);
-    return { action, repos: rows, stale: staleCount };
+    if (missing) hand('clone the missing repo(s) with `yad repo clone`');
+    if (staleCount) hand(`refresh with \`yad repo refresh${entries.length > 1 ? ' <name>' : ''}\` (or \`yad repo refresh\` for all)`);
+    return { action, repos: rows, stale: staleCount, missing };
   }
 
   if (action === 'refresh') {
-    const targets = name ? registry.repos.filter((r) => r.name === name) : registry.repos;
-    if (name && !targets.length) { fail(`unknown repo: ${name}`); process.exitCode = 1; return { action, refreshed: 0, repos: [], published: null }; }
+    const targets = name ? entries.filter((r) => r.name === name) : entries;
+    if (name && !targets.length) { fail(`unknown repo: ${shown(name)}`); process.exitCode = 1; return { action, refreshed: 0, repos: [], published: null }; }
     let refreshed = 0;
     let published = null;
     const rows = [];
     for (const repo of targets) {
+      // Judged before git runs (E81), as `sync` judges it: only a checkout that is there is packed, never
+      // one reached through a link inside a repo's tree (repomix would pack wherever the link points,
+      // git logs included). And the pack is written only where the Product keeps code context.
+      const j = judgeRepo(root, repo);
+      const why = notPackable(root, repo, j);
+      if (why) {
+        warn(`${j.name}: ${why} — skipped`);
+        rows.push({ name: repo.name ?? null, refreshed: false, head: null });
+        continue;
+      }
       const { head, unknown } = staleness(root, repo);
-      if (unknown) { warn(`${repo.name}: HEAD unreadable — skipped`); rows.push({ name: repo.name ?? null, refreshed: false, head: null }); continue; }
-      log(`  ${c.bold(repo.name)}`);
-      const packed = !!packRepo(root, repo);
+      if (unknown) { warn(`${j.name}: HEAD unreadable — skipped`); rows.push({ name: repo.name ?? null, refreshed: false, head: null }); continue; }
+      log(`  ${c.bold(j.name)}`);
+      const packed = !!packRepo(root, { ...repo, contextPack: packOf(repo) });
       if (packed) {
         repo.syncedHead = head;
         if (today) repo.lastSyncedAt = today;   // always stamp when a date is supplied (the CLI passes today)
@@ -75,6 +127,16 @@ export async function runRepo(root, { action = 'list', name, today, push = false
       }
       rows.push({ name: repo.name ?? null, refreshed: packed, head: head || null });
     }
+    // Never through a `.sdlc` the Product commits as a link: the rename would land in the folder it names
+    // (E81 review 17).
+    let sdlcLinked = false;
+    try { sdlcLinked = fs.lstatSync(path.dirname(regPath)).isSymbolicLink(); } catch { /* not there */ }
+    if (sdlcLinked) {
+      // A refusal stops here, `--push` included (E81 review 18): nothing is published after it.
+      fail(`${path.dirname(PROJECT_FILES.reposRegistry)} in the Product is a link — ${PROJECT_FILES.reposRegistry} was not written`);
+      process.exitCode = 1;
+      return { action, refreshed, repos: rows, published: null };
+    }
     writeJSON(regPath, registry);
     refreshed ? ok(`refreshed ${refreshed} repo(s)`) : info('nothing refreshed');
     if (push) {
@@ -94,43 +156,76 @@ export async function runRepo(root, { action = 'list', name, today, push = false
   }
 
   if (action === 'sync') {
-    const targets = name ? registry.repos.filter((r) => r.name === name) : registry.repos;
-    if (name && !targets.length) { fail(`unknown repo: ${name}`); process.exitCode = 1; return { action, synced: 0, skipped: 0, repos: [] }; }
+    const targets = name ? entries.filter((r) => r.name === name) : entries;
+    if (name && !targets.length) { fail(`unknown repo: ${shown(name)}`); process.exitCode = 1; return { action, synced: 0, skipped: 0, repos: [] }; }
     log(c.bold('\nsync connected repos'));
     let synced = 0, skipped = 0;
     for (const repo of targets) {
-      const repoRoot = path.resolve(root, repo.path);
-      const tag = `${repo.name} ${c.dim(`(${repo.path})`)}`;
+      // The registry is shared content, and sync runs git in each path (E81): the same judgement the
+      // clone step makes comes first. A path outside the workspace or through `.git` is refused; so is a
+      // folder with no `.git` (a committed folder shaped like a bare repo would have git read its
+      // `config`), and a checkout reached through a link inside a repo's tree (the Product's
+      // `evil -> ../../..`). A link of the person's own, directly in the workspace folder, is followed.
+      const j = judgeRepo(root, repo);
+      const tag = `${j.name} ${c.dim(`(${j.path})`)}`;
+      if (j.state === 'missing') { warn(`${tag} — not cloned on this machine — skipped (\`yad repo clone\`)`); skipped++; continue; }
+      if (j.state === 'refused') { warn(`${tag} — ${j.reason} — skipped`); skipped++; continue; }
+      if (j.linked) { warn(`${tag} — a folder on its path, inside a repo, is a link, so the checkout is not where the path says — skipped`); skipped++; continue; }
+      // A folder inside another checkout (a monorepo's `apps/web`): switching "its" branch would switch
+      // the whole checkout, on this entry's say-so. Sync the checkout it belongs to instead.
+      if (j.inside) { info(`${tag} — a folder inside the checkout ${shown(path.relative(root, j.inside) || '.')}, not a repo of its own — skipped (sync that checkout)`); skipped++; continue; }
+      const repoRoot = j.target || path.resolve(root, repo.path);
       if (!gitHead(repoRoot)) { warn(`${tag} — not a git repo / HEAD unreadable — skipped`); skipped++; continue; }
-      if (isDirty(repoRoot)) { warn(`${repo.name} — ${c.yellow('dirty')} → SKIPPED (commit/stash first)`); skipped++; continue; }
+      if (isDirty(repoRoot)) { warn(`${j.name} — ${c.yellow('dirty')} → SKIPPED (commit/stash first)`); skipped++; continue; }
       const branch = defaultBranch(repoRoot, repo);
+      if (!branch) { warn(`${tag} — its default branch (recorded, or origin/HEAD) is not a plain branch name git accepts — skipped (fix default_branch in ${PROJECT_FILES.reposRegistry})`); skipped++; continue; }
       const remote = hasRemote(repoRoot);
+      // Printed through `shown` (E81 review 9): git accepts bytes above 0x7f in a branch name, and the
+      // remote a registered clone fetches from was chosen by the shared registry, so both can carry text
+      // a terminal obeys.
+      const b = shown(branch);
+      const firstLine = (s) => shown(String(s || '').split('\n')[0]);
       if (remote) {
         const f = git(repoRoot, 'fetch', 'origin', branch, '--prune');
-        if (!f.ok) { warn(`${repo.name} — fetch failed (${(f.stderr.split('\n')[0]) || 'auth?'}) — skipped`); skipped++; continue; }
+        if (!f.ok) { warn(`${j.name} — fetch failed (${firstLine(f.stderr) || 'auth?'}) — skipped`); skipped++; continue; }
       }
       if (currentBranch(repoRoot) !== branch) {
         const co = git(repoRoot, 'checkout', branch);
-        if (!co.ok) { warn(`${repo.name} — cannot switch to ${branch} (${co.stderr.split('\n')[0] || 'no such branch'}) — skipped`); skipped++; continue; }
+        if (!co.ok) { warn(`${j.name} — cannot switch to ${b} (${firstLine(co.stderr) || 'no such branch'}) — skipped`); skipped++; continue; }
       }
       if (remote) {
         const before = gitHead(repoRoot);
         const m = git(repoRoot, 'merge', '--ff-only', `origin/${branch}`);
-        if (!m.ok) { warn(`${repo.name} — ${c.yellow('diverged')} on ${branch} → not fast-forwarded (resolve manually)`); skipped++; continue; }
-        ok(`${repo.name} ${c.dim('—')} ${before === gitHead(repoRoot) ? `already current on ${branch}` : `switched to ${branch}, pulled (ff)`}`);
+        if (!m.ok) { warn(`${j.name} — ${c.yellow('diverged')} on ${b} → not fast-forwarded (resolve manually)`); skipped++; continue; }
+        ok(`${j.name} ${c.dim('—')} ${before === gitHead(repoRoot) ? `already current on ${b}` : `switched to ${b}, pulled (ff)`}`);
       } else {
-        ok(`${repo.name} ${c.dim('—')} on ${branch} (local-only, no remote)`);
+        ok(`${j.name} ${c.dim('—')} on ${b} (local-only, no remote)`);
       }
       synced++;
     }
     // A pulled repo's HEAD moves, so its cached code-context pack goes stale — point the human at refresh.
-    const staleCount = registry.repos.filter((r) => staleness(root, r).stale).length;
+    // Only the checkouts the loop would run git in (E81) — never a refused or linked entry.
+    const staleCount = entries.filter((r) => runnable(judgeRepo(root, r)) && staleness(root, r).stale).length;
     info(`synced ${synced}, skipped ${skipped}`);
     if (staleCount) hand(`${staleCount} repo(s) now have a stale code-context pack — \`yad repo refresh\` to repack`);
     return { action, synced, skipped, stale: staleCount };
   }
 
-  fail(`unknown repo action: ${action} (list | refresh | sync)`);
+  if (action === 'clone') {
+    const targets = name ? entries.filter((r) => r.name === name) : entries;
+    if (name && !targets.length) { fail(`unknown repo: ${shown(name)}`); process.exitCode = 1; return { action, cloned: [], present: [], failed: [] }; }
+    log(c.bold('\nclone missing repos'));
+    const repos = cloneMissingRepos(root, { repos: targets });
+    reportClones(repos);
+    if (!repos.cloned.length && !repos.failed.length) info(name ? `${shown(name)} is already on this machine` : 'nothing missing — every registered repo is on this machine');
+    // Unlike `join` (whose other steps still matter), cloning is this command's only job: a repo it could
+    // not clone fails it, so a script sees it.
+    if (repos.failed.length) { hand(`${repos.failed.length} repo(s) not cloned — fix what is named above and re-run \`yad repo clone\``); process.exitCode = 1; }
+    if (repos.cloned.length) hand('build the cloned repos\' code-context pack with `yad repo refresh <name>` when you need it');
+    return { action, ...repos };
+  }
+
+  fail(`unknown repo action: ${action} (list | refresh | sync | clone)`);
   process.exitCode = 1;
   return { action };
 }

package/cli/report.mjs

@@ -52,6 +52,8 @@ const SAFE_VERBS = new Set([
   'approve', 'advance', 'comment',
   // E43: the background capture of Shape artifacts.
   'capture',
+  // E79: the workspace verbs (`new` is also `epic new`'s action).
+  'new', 'init', 'join',
 ]);
 
 // Reduce an argv to a safe command line: the leading verb chain (at most `command subcommand`, and
@@ -78,8 +80,8 @@ export function sanitizeArgv(argv = []) {
 // Build the safe, postable context — the ONLY data that can reach the issue. Reads doctor for tool
 // state but keeps just the booleans, never the raw checks (which carry names + paths).
 export function sanitizeContext(dir, { error = null, argv = process.argv.slice(2) } = {}) {
-  const hub = readJSON(productConfigPath(dir), null);
-  const platform = hub && ['github', 'gitlab'].includes(hub.platform) ? hub.platform : 'local';
+  const productConfig = readJSON(productConfigPath(dir), null);
+  const platform = productConfig && ['github', 'gitlab'].includes(productConfig.platform) ? productConfig.platform : 'local';
   // Derive tool auth from doctor's checks without keeping any check text.
   const toolState = (cli, p) => (has(cli) ? (platformAuthed(p) ? 'present + authenticated' : 'present, not authenticated') : 'not installed');
   const ctx = {

package/cli/review.mjs

@@ -10,6 +10,7 @@ import { log, ok, info, warn, fail, note, run, readJSON, emitJSON, refuse, inJSO
 import { PROJECT_FILES , productConfigPath } from './manifest.mjs';
 import { updateShip } from './ledger.mjs';
 import { epicRoot } from './epic-state.mjs';
+import { registryEntryFor } from './find-product.mjs';
 import {
   detectPlatform, readPr, mapApprovers, getPrBody, editPrBody, postComment, prNumberFromUrl,
   resolveBaseBranch,
@@ -22,14 +23,20 @@ const NUDGE_CMD = 'yad review chat';
 // Resolve the target code repo: --repo <name> from the registry (platform + path), 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 }) {
+//
+// `product` (E80) is the Product found from a code repo beside it: the registry, the code map and the
+// epics are read there, and a repo run without --repo is looked up in the registry by its path.
+function resolveRepo(root, { repo, dir, product }) {
+  const productRoot = product || root;
   if (repo) {
-    const reg = readJSON(path.join(root, PROJECT_FILES.reposRegistry), { repos: [] });
+    const reg = readJSON(path.join(productRoot, 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(productRoot, found.path), meta: found, productRoot };
   }
-  return { repoRoot: path.resolve(root, dir || '.'), meta: null };
+  const here = path.resolve(root, dir || '.');
+  const hit = registryEntryFor(product, here);
+  return { repoRoot: hit ? hit.top : here, meta: hit ? hit.meta : null, productRoot };
 }
 
 function platformOf(root, repoRoot, meta) {
@@ -41,8 +48,8 @@ function platformOf(root, repoRoot, meta) {
 // Assemble (but don't print) the Build 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, runner = run } = {}) {
-  const rr = resolveRepo(root, { repo, dir });
+function contextBundle(root, { repo, dir, product, pr, runner = run } = {}) {
+  const rr = resolveRepo(root, { repo, dir, product });
   if (rr.error) return { error: rr.error };
   const { repoRoot, meta } = rr;
   const platform = platformOf(root, repoRoot, meta);
@@ -58,8 +65,8 @@ function contextBundle(root, { repo, dir, pr, runner = run } = {}) {
     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,
+    codeMap: meta?.name ? path.join(rr.productRoot, '.sdlc/code-context', meta.name, 'code-map.md') : null,
+    pack: meta?.name ? path.join(rr.productRoot, '.sdlc/code-context', meta.name, 'pack.md') : null,
     contract: meta?.contract || null,
     markers: {
       trailerBegin: '<!-- yad:trailer -->', noblock: '<!-- yad:noblock -->',
@@ -71,8 +78,8 @@ function contextBundle(root, { repo, dir, pr, runner = run } = {}) {
 
 // `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, runner = run } = {}) {
-  const r = contextBundle(root, { repo, dir, pr, runner });
+export async function reviewContext(root, { repo, dir, product, pr, runner = run } = {}) {
+  const r = contextBundle(root, { repo, dir, product, pr, runner });
   if (r.error) { refuse(r.error, null, { json: true }); return; }
   emitJSON(r.bundle);
   return r.bundle;
@@ -82,8 +89,8 @@ export async function reviewContext(root, { repo, dir, pr, runner = run } = {})
 // 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, runner });
+export async function reviewWalkthrough(root, { repo, dir, product, pr, runner = run } = {}) {
+  const r = contextBundle(root, { repo, dir, product, pr, runner });
   if (r.error) { refuse(r.error, null, { json: true }); return; }
   const { bundle, repoRoot, base } = r;
   const diff = runner('git', ['-C', repoRoot, 'diff', `${base}...HEAD`]);
@@ -99,10 +106,10 @@ export async function reviewWalkthrough(root, { repo, dir, pr, runner = run } =
 
 // `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 } = {}) {
+export async function reviewTrailer(root, { repo, dir, product, 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 });
+  const rr = resolveRepo(root, { repo, dir, product });
   if (rr.error) { fail(rr.error); process.exitCode = 1; return; }
   const { repoRoot, meta } = rr;
   const platform = platformOf(root, repoRoot, meta);
@@ -117,9 +124,9 @@ export async function reviewTrailer(root, { repo, dir, pr, body, getBody = getPr
 
 // `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 } = {}) {
+export async function reviewNudge(root, { repo, dir, product, pr, reader = readPr, poster = postComment } = {}) {
   if (!pr) { fail('--pr <n> is required'); process.exitCode = 1; return; }
-  const rr = resolveRepo(root, { repo, dir });
+  const rr = resolveRepo(root, { repo, dir, product });
   if (rr.error) { fail(rr.error); process.exitCode = 1; return; }
   const { repoRoot, meta } = rr;
   const platform = platformOf(root, repoRoot, meta);
@@ -141,10 +148,10 @@ export async function reviewNudge(root, { repo, dir, pr, reader = readPr, poster
 // 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 } = {}) {
+export async function reviewReconcile(root, { epic, repo, dir, product, 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 });
+  const rr = resolveRepo(root, { repo, dir, product });
   if (rr.error) { fail(rr.error); process.exitCode = 1; return; }
   const { repoRoot, meta } = rr;
   const platform = platformOf(root, repoRoot, meta);
@@ -167,7 +174,7 @@ export async function reviewReconcile(root, { epic, repo, dir, pr, reader = read
   // build-log is shard-then-fold now: updateShip mutates the ship's own loose shard (authoritative
   // until `yad tidy up` folds it), or the folded file if already folded — never both.
   const res = updateShip(
-    epicRoot(root, epic),
+    epicRoot(rr.productRoot, epic),
     (s) => s.pr != null && (String(s.pr) === String(pr) || prNumberFromUrl(s.pr) === String(pr)),
     (s) => { s.engineer_review = engineerReview; },
   );