yadflow 4.0.0-next.1 → 4.0.0-next.4

package/bin/yad.mjs

@@ -1,14 +1,28 @@
 #!/usr/bin/env node
 // `yad` — setup/maintenance + the PR-driven review gate + build helpers for the SDLC module.
+import fs from 'node:fs';
+import path from 'node:path';
 import { VERSION } from '../cli/manifest.mjs';
 import { c, log, warn, closePrompts, askYesNo, refuse, beginJSON, inJSON, emitJSON, jsonEmitted, jsonFailure, stripAnsi, isPlainObject, ENVELOPE_KEYS } from '../cli/lib.mjs';
-import { runLedgerGuardHook } from '../cli/hook.mjs';
+import { runLedgerGuardHook, runStagedLedgerGuard } from '../cli/hook.mjs';
 
 const helpText = (profiles) => `${c.bold('yad')} — setup, review-gate & build helpers for the SDLC Workflow module  ${c.dim('v' + VERSION)}
 
 ${c.dim('Every command but `yad hook` takes --json: one JSON object on stdout, every other line on stderr')}
 ${c.dim('(docs/CLI.md, "--json on every command").')}
 
+${c.bold('Start a workspace')} ${c.dim('(the folder holding product/ and the code repos side by side)')}
+  ${c.dim('--dir: for init, the workspace; for new and join, the folder the workspace is made in')}
+  yad new <name>       Greenfield: make <name>/product/, git init it, run setup inside it. Creates
+                       no remote — prints the gh/glab line to run yourself. Takes the setup flags
+  yad init             Brownfield, in the folder that already holds your repos: make product/ (or
+                       use the one there; --path <folder> names it), run setup, offer each repo found
+  yad join <url> [folder]
+                       Clone the Product into [folder]/product/ (default: the URL's last name) and
+                       every repo it registers; a failed repo clone is reported, never fatal. Then
+                       only per-machine steps: git-ignored skill copies + the git pre-commit hook.
+                       Never commits, pushes, or changes a shared file
+
 ${c.bold('Setup & maintenance')}
   yad setup            Guided first-run setup (profile interview, install, connect & wire repos)
                        profile flags: --solo | --team <n>, --greenfield | --brownfield,
@@ -29,11 +43,13 @@ ${c.bold('Setup & maintenance')}
                        'yad check --fix --push'; --allow-branch permits a non-default branch
   yad doctor [--json]  Environment + state health: tools/auth, config files,
                        repo paths, epic ledgers (exit 1 on any failure)
-  yad migrate [--apply] [--json]   Move this project's state files onto the shape
+  yad migrate [--apply] [--keep product|hub] [--json]   Move this project's state files onto the shape
                        this yadflow expects. Prints what WOULD change and writes
                        nothing until --apply, which copies each file it rewrites to
                        <file>.yad-orig first. Safe to run twice — the second run
-                       reports there is nothing to do
+                       reports there is nothing to do. When .sdlc/product.json and
+                       .sdlc/hub.json (or an epic's product-prs.json and hub-prs.json)
+                       disagree, --apply asks which copy to keep; --keep answers it
   yad sync-status [epic]   Update artifact frontmatter status (draft/in-review/approved)
                        from .sdlc/state.json — all epics if omitted (--dry-run to preview)
   yad report [-m <text>]   File a bug in the yadflow repo with auto-scrubbed diagnostics
@@ -46,7 +62,10 @@ ${c.bold('Setup & maintenance')}
                        --format cursor the verdict is JSON on stdout instead, for a harness
                        whose pre-edit hook asks for permission rather than reading an exit
                        code. Wired into .claude/settings.json and .cursor/hooks.json by
-                       setup / check --fix. YAD_HOOK_DISABLE=1 skips.
+                       setup / check --fix. With --staged it judges the files a commit is
+                       about to record instead — the git pre-commit hook check --fix
+                       installs in this clone refuses a person's hand commit to the ledger.
+                       YAD_HOOK_DISABLE=1 skips.
 
 ${c.bold('Team usage (EM adoption & behavior report)')}
   yad usage                            Build a per-member report (HTML) from git + the SDLC ledgers
@@ -151,6 +170,12 @@ ${c.bold('Review gate (Shape)')}
                                        in verified mode — there, recover with 'yad gate ci' below
   yad gate comments <epic> [artifact]  Fetch unresolved review comments to address
   yad gate status <epic>               Show each review step + approvals
+  yad gate approve <epic> <artifact> --by <name> [--engagement verified|none]
+                                       No platform only: record an approval, bound to the artifact's
+                                       content (an edit revokes it). Reports the verdict; never advances
+  yad gate comment <epic> <artifact> --by <name> [--count <n>] [--new-round]
+                                       No platform only: record who commented, and how often, this round
+  yad gate advance <epic> <artifact>   No platform only: pass the gate when its approvals hold
   yad gate repair <epic> [--push]      Close an author step stranded behind a passed review gate
                                        (YAD-STATE-005); --push commits state.json to the default branch
   yad gate review <epic> [artifact]    Print the grounding bundle for the review companion
@@ -164,26 +189,47 @@ ${c.bold('Review gate (Shape)')}
                         --merged advances the step + flips artifact status on the default branch
 
 ${c.bold('Build helpers')}
-  yad commit --type <t> -m <subject>   Commit by convention (trailers, atomic guard)
-  yad open-pr [--repo <name>]          Open a task PR/MR against the repo's DEFAULT branch (never a
+  yad commit --type <t> -m <subject> [--manual --reason <why>]
+                                       Commit by convention (trailers, atomic guard); --manual is
+                                       the door past the Product's ledger hook, reason recorded
+  yad open-pr [--repo <name>] [--title <text>]
+                                       Open a task PR/MR against the repo's DEFAULT branch (never a
                                        hardcoded main; --base overrides) — stage-aware on the Product: a
                                        review/EP-* branch opens the Shape artifact-review PR
                                        (delegates to gate open), any other Product branch uses the
-                                       code-task template
-  yad ship --type <t> -m <subject>     Commit AND open the task PR/MR in one step (stage-aware)
+                                       code-task template. --title sets the PR/MR title (default: -m,
+                                       else the last commit's subject)
+  yad ship --type <t> -m <subject> [--title <text>]
+                                       Commit AND open the task PR/MR in one step (stage-aware).
+                                       --title sets the PR/MR title (default: the commit subject)
   yad checkpoint [--push]              Commit the machine-written Build state on the Product
                                        (trust-log/build-log/build-state) — plus any story
                                        status: flip (→ in-build/shipped) backed by a build-log
-                                       ship — as one audit-trail chore(hub) commit; default
+                                       ship — as one audit-trail chore(product) commit; default
                                        branch only (--allow-branch to override); no-op when clean
   yad checkpoint --retro-ship <epic>/<story> --repo <r>
                                        Record a retroactive build-log ship for a PRE-TRACKING story
                                        (merged before ledger tracking), then carry its status: shipped
                                        flip in the same commit (--merge-commit <sha>, --task <t> opt.);
                                        one repo per run — re-run per --repo for a multi-repo story
+  yad capture [--no-push]              Snapshot every changed Shape artifact onto your private
+                                       yad/wip/<you>/<epic> branches — never your checkout; pushes them
+                                       (a harness hook runs it after each agent edit, with --hook)
+  yad claims [<epic>] [--no-fetch]     Who else is editing which artifact: read from everyone's
+                                       capture branches (fetched first) — advice, not a lock; a claim
+                                       ends 4 hours after the last save, or once the file is merged
+  yad assign <epic> <step> [--to <name>] [--force]
+                                       Assign an authoring step to one person (you, or their git
+                                       name) — advice, not a lock: the capture hook warns anyone
+                                       else who edits its files; --force replaces another owner
+  yad unassign <epic> <step> [--force] Remove an assignment (someone else's needs --force)
+  yad owners [<epic>]                  List every step assignment, and whether it is live
+  yad fold <epic> <step>               End an authoring step: commit ITS artifacts as one commit,
+                                       docs(<epic>): author <step> (signed if git signs) — the drafts
+                                       stay on yad/wip/…; with ledger: local the epic's ledger rides along
   yad tidy up [<epic>] [--push]        Fold FINISHED Build shards (a shipped story's
                                        trust-log/build-log entries) back into the single folded
-                                       ledger, as one chore(hub) commit — the manual "pack it up"
+                                       ledger, as one chore(product) commit — the manual "pack it up"
                                        for the shard files; a no-op when nothing is foldable
   yad index [--json]                   Rebuild .sdlc/index.json — one summary line per work item,
                                        derived from their own files; the default branch only, with no
@@ -203,9 +249,14 @@ ${c.bold('Build helpers')}
                                                           pair-review walkthrough (yad-pair-review)
   yad review nudge --repo <r> --pr <n>                    Friendly @-mention on a bare code-PR approve
   yad review reconcile --epic <id> --repo <r> --pr <n>    Bridge: stamp engagement onto the build-log ship
-  yad repo list                        Show connected repos (fresh / stale)
+  yad repo list                        Show connected repos (fresh / stale / not cloned here)
+  yad repo clone [name]                Clone every registered repo missing on this machine, at its
+                                       recorded path (the clone step of \`yad join\`). Never touches a
+                                       repo already there; exits 1 when one could not be cloned
+  yad repo sync [name]                 Switch each connected repo to its default branch and
+                                       fast-forward it from origin; dirty repos are skipped
   yad repo refresh [name] [--push]     Re-pack a stale repo (a human decision). --push commits the
-                       refreshed code-maps + registry as a chore(hub): sync code-context … [skip ci]
+                       refreshed code-maps + registry as a chore(product): sync code-context … [skip ci]
                        audit commit and pushes it to the Product default branch (--allow-branch to override)
   yad risk-map check [repo] [--json]   Warn where a code repo's .sdlc/risk-map (a risk level per
                                        directory, no names) has gone stale — advisory, never blocks
@@ -231,16 +282,23 @@ ${c.bold('Interactive docs (generated sites)')}
   yad docs sync [--check|--refresh|--wire]   Staleness sweep; --wire installs the Pages CI
 
 ${c.bold('Options')}
-  --dir <path>          Target project root (default: cwd)
+  --dir <path>          Target project root. Without it, a Product command finds the Product from
+                        where you are — any folder inside it, or inside a repo it registers
+                        (via .yad-workspace.json) — and says so on stderr; a code-repo command
+                        (commit, open-pr, ship, review) works on the repo you are in
   --type <t>            commit: feat|fix|docs|refactor|test|perf|build|ci|chore|revert
   -m, --message <s>     commit: subject / PR title
-  --task <id>           commit: Task trailer, a <story>-T<NN> id (else derived from the branch)
+  --task <id>           commit: Task trailer, EP-<slug>-S<n>-T<NN> (else derived from the branch)
   --ai <id>             commit: co-author — claude|copilot|cursor|coderabbit|none (default none)
   --contract-change     commit/open-pr: mark the contract surface touched
+  --manual              commit: on a verified Product, commit past the local ledger hook; needs
+                        --reason, recorded as a Ledger-Override trailer. The ledger-guard check
+                        on the pull request still judges the commit, and quotes the reason
   --risk <level>        open-pr: low|medium|high (default low)
   --repo <name>         open-pr: target a registered repo by name
+  --title <text>        open-pr/ship: the PR/MR title (ignored on the Product's review/EP-* branch)
   --base <branch>       open-pr: override the PR/MR base — default is the repo's own default
-                        branch (repos.json default_branch, else hub.json default_branch for a PR
+                        branch (repos.json default_branch, else product.json default_branch for a PR
                         on the Product itself, else the platform, else origin/HEAD, else main); a
                         non-default base loses the AI first pass (warns, never blocks)
   --epic <id>           docs: target one epic's site (EP-<slug>)
@@ -264,7 +322,7 @@ ${c.bold('Environment')}
   YAD_NO_REPORT=1            Never offer to file a bug report after a failure
   YAD_PLATFORM_LOGIN=0       Name a record's author by git user.name; never ask gh/glab who is logged in`;
 
-const VALUE_FLAGS = new Set(['--dir', '--type', '--message', '--task', '--ai', '--risk', '--repo', '--platform', '--base', '--title', '--scope', '--branch', '--pr', '--epic', '--team', '--body', '--out', '--since', '--until', '--member', '--format', '--reason', '--profile', '--parent', '--inherits', '--to', '--retro-ship', '--merge-commit', '--path', '--ide-targets', '--theme', '--thread']);
+const VALUE_FLAGS = new Set(['--dir', '--type', '--message', '--task', '--ai', '--risk', '--repo', '--platform', '--base', '--title', '--scope', '--branch', '--pr', '--epic', '--team', '--body', '--out', '--since', '--until', '--member', '--format', '--reason', '--profile', '--parent', '--inherits', '--to', '--retro-ship', '--merge-commit', '--path', '--ide-targets', '--theme', '--thread', '--by', '--count', '--engagement', '--keep']);
 
 function parseArgs(argv) {
   const o = { _: [], dir: process.cwd(), fix: false, force: false, scope: 'all' };
@@ -274,7 +332,9 @@ function parseArgs(argv) {
     if (a === '--fix') o.fix = true;
     else if (a === '--force') o.force = true;
     else if (a === '--contract-change') o.contractChange = true;
+    else if (a === '--manual') o.manual = true;
     else if (a === '--no-push') o.noPush = true;
+    else if (a === '--no-fetch') o.noFetch = true;
     else if (a === '--push') o.push = true;
     else if (a === '--allow-branch') o.allowBranch = true;
     else if (a === '--overwrite-local') o.overwriteLocal = true;
@@ -290,6 +350,9 @@ function parseArgs(argv) {
     else if (a === '--done') o.done = true;
     else if (a === '--undo') o.undo = true;
     else if (a === '--debt') o.debt = true;
+    else if (a === '--new-round') o.newRound = true;
+    else if (a === '--hook') o.hook = true;
+    else if (a === '--staged') o.staged = true;
     else if (a === '--stub') o.stub = true;
     // setup profile flags (pre-answer the Step 0 interview, for CI/scripts)
     else if (a === '--solo') o.solo = true;
@@ -345,17 +408,50 @@ const ACTIONS = {
   epic: { known: ['new'] },
   foundation: { known: ['new', 'status'] },
   skill: { known: ['list', 'bind', 'unbind'], default: 'list' },
-  gate: { known: ['open', 'sync', 'comments', 'status', 'repair', 'review', 'walkthrough', 'trailer', 'ci'] },
+  gate: { known: ['open', 'sync', 'comments', 'status', 'repair', 'review', 'walkthrough', 'trailer', 'ci', 'approve', 'comment', 'advance'] },
   review: { known: ['trailer', 'context', 'chat', 'cards', 'walkthrough', 'nudge', 'reconcile'] },
   tidy: { known: ['up'] },
   history: { known: ['list', 'show', 'search'], default: 'list' },
-  repo: { known: ['list', 'refresh', 'sync'], default: 'list' },
+  repo: { known: ['list', 'refresh', 'sync', 'clone'], default: 'list' },
   'risk-map': { known: ['check', 'draft'], default: 'check' },
   codeowners: { known: ['check'], default: 'check' },
   docs: { known: ['list', 'build', 'deploy', 'sync'], default: 'list' },
   reconcile: { known: ['check', 'refresh', 'wire'] },
   hook: { known: ['ledger-guard'] },
 };
+// E80 — how each command finds its folder. A PRODUCT command works on the Product; a REPO command works
+// on the code repo it runs in and reads the Product beside it. The rest take their folder as given:
+// `setup` and `new`/`init`/`join` make one, `report` and `hook` read what is there.
+const PRODUCT_CMDS = new Set([
+  'check', 'update', 'doctor', 'migrate', 'usage', 'sync-status', 'epic', 'foundation', 'skill', 'next',
+  'skip', 'unskip', 'defer', 'undefer', 'dial', 'mode', 'kill', 'unkill', 'unblock', 'gate', 'checkpoint',
+  'capture', 'claims', 'assign', 'unassign', 'owners', 'fold', 'tidy', 'index', 'history', 'repo',
+  'risk-map', 'codeowners', 'docs', 'thread', 'reconcile',
+]);
+const REPO_CMDS = new Set(['commit', 'open-pr', 'ship', 'review']);
+// The Product commands that WRITE its files without first checking it is one. Run from a code repo they
+// wrote an epic, a dial or the module into it; they refuse instead (E80). The rest either only read, or
+// already refuse a folder that is not a Product.
+function writesProduct(cmd, o) {
+  const action = o._[1];
+  if (cmd === 'update' || cmd === 'kill' || cmd === 'unkill') return true;
+  if (cmd === 'check') return !!o.fix;
+  if (cmd === 'epic' || cmd === 'foundation') return action === 'new';
+  if (cmd === 'skill') return action === 'bind' || action === 'unbind';
+  if (cmd === 'dial') return o.to !== undefined;
+  // `--wire` writes a CI workflow; `--refresh` only rebuilds sites the folder already holds.
+  if (cmd === 'docs') return action === 'sync' && !!o.wire;
+  return false;
+}
+
+// Where the person IS, as their shell says it: a repo reached through a link (`ws/backend -> /src/backend`)
+// is inside the workspace by the path they typed, and not by the one the disk resolves to.
+function shellCwd() {
+  const pwd = process.env.PWD;
+  try { if (pwd && path.isAbsolute(pwd) && fs.realpathSync(pwd) === fs.realpathSync(process.cwd())) return pwd; } catch { /* the disk's path, then */ }
+  return process.cwd();
+}
+
 const ALWAYS_JSON = new Set(['gate review', 'gate walkthrough', 'review context', 'review chat', 'review cards', 'review walkthrough']);
 export function commandName(words) {
   const [cmd, action] = words;
@@ -399,26 +495,85 @@ async function main() {
     // so it takes no --json (E1).
     if (inJSON()) return refuse('yad hook takes no --json — its output is the protocol the agent reads', 'run it without --json');
     if (action !== 'ledger-guard') return refuse(`unknown hook: ${action ?? '(none)'} (ledger-guard)`);
+    // `--staged` is the git pre-commit half (E48): the files come from the index, never from stdin.
+    if (o.staged) { runStagedLedgerGuard(); return; }
     runLedgerGuardHook({ paths: o.path ? [o.path] : [], format: o.format });
     return;
   }
 
+  // The same hot path for the post-edit capture hook (E43): it runs after every agent edit, never fails,
+  // and needs `cli/capture.mjs` alone.
+  if (cmd === 'capture' && o.hook) {
+    const { runCapture } = await import('../cli/capture.mjs');
+    try { await runCapture(o.dir, { hook: true, noPush: !!o.noPush, format: o.format || null }); } catch (e) { process.stderr.write(`  • yad capture: ${e.message}\n`); }
+    process.exitCode = 0;
+    return;
+  }
+
   // Every other command. One await, once, for a process that is about to do real work anyway.
   const commands = await import('./commands.mjs');
   if (o.help || !cmd) {
     const text = helpText(commands.seedableProfiles());
     return inJSON() ? emitJSON({ help: stripAnsi(text) }) : log(text);
   }
+  // E80: find the Product from wherever yad runs. `--dir` always wins. Otherwise a Product command runs
+  // against the Product found by walking up — from any subfolder of the Product, or from inside a repo it
+  // registers (through `.yad-workspace.json`) — and says where, on stderr. A code-repo command keeps acting
+  // on the repo it runs in, and is handed the Product to read (its registry: name, platform, branch).
+  const dirGiven = process.argv.slice(2).some((a) => a === '--dir' || a.startsWith('--dir='));
+  if (PRODUCT_CMDS.has(cmd) || REPO_CMDS.has(cmd)) {
+    const found = commands.findProduct(dirGiven ? o.dir : shellCwd());
+    const shown = (p) => path.relative(process.cwd(), p) || '.';
+    if (found?.problem) warn(`${found.problem} — using ${o.dir}`);
+    else if (found?.elsewhere) {
+      // The workspace folder itself, or a repo the Product does not register: no Product here, but the
+      // person is one `cd` away from it — say so, rather than let "run yad setup" make a second one.
+      if (PRODUCT_CMDS.has(cmd)) warn(`this folder is not in a repo the Product registers — the Product is ${shown(found.elsewhere)}: cd there, or pass --dir ${shown(found.elsewhere)}`);
+    } else if (found?.root && REPO_CMDS.has(cmd)) o.product = found.root;
+    else if (found?.root && !dirGiven && found.via !== 'here') {
+      o.dir = found.root;
+      process.stderr.write(c.dim(`Product: ${shown(found.root)} (${found.via === 'workspace' ? `from ${commands.WORKSPACE_FILE}` : 'above this folder'})\n`));
+      // Run from inside one code repo, the per-repo commands work on THAT repo, not on every one the
+      // Product registers (they take the repo's name as their second word).
+      // The CHECKOUT must be the registered repo (a worktree or nested repo inside it is another one).
+      if ((cmd === 'risk-map' || cmd === 'codeowners') && o._[2] === undefined) {
+        const hit = commands.registryEntryFor(found.root, dirGiven ? o.dir : shellCwd());
+        if (typeof hit?.meta?.name === 'string') o._[2] = hit.meta.name;
+      }
+    }
+  }
+  // A command that WRITES the Product never writes into a folder that is not one (a code repo, say).
+  // Asked by each such command AFTER its own usage checks, so a mistyped command still hears what is
+  // wrong with it first.
+  const noProduct = () => {
+    if (!writesProduct(cmd, o) || commands.hasProduct(o.dir)) return false;
+    refuse(`no Product here (${o.dir}) — yad ${cmd} writes the Product's files`, 'run it from the Product, from inside a repo it registers, or pass --dir <the Product>; `yad new` / `yad init` start one');
+    return true;
+  };
   // A project written by a newer yadflow is warned about before any command reads it (docs/migrations/
   // shape-8.md). Not on `hook` — its stderr is the channel a block reason reaches a model on — and not
   // where the command reports the same thing itself (doctor, migrate) or runs before a project exists.
-  if (!['hook', 'doctor', 'migrate', 'setup', 'report'].includes(cmd)) commands.warnIfProjectAhead(o.dir || process.cwd());
+  if (!['hook', 'doctor', 'migrate', 'setup', 'report', 'new', 'init', 'join'].includes(cmd)) commands.warnIfProjectAhead(o.dir || process.cwd());
+  // E122: the Product's settings (or an epic's PR ledger) under two names that say different things.
+  // Every command refuses rather than pick one — whichever it picked, somebody's edit would be silently
+  // ignored. Not `doctor` (it reports the drift), `migrate` (it ends it) or `report` (it files a bug
+  // about a broken flow, and reads nothing it could get wrong). `hook` returned above: it guards.
+  if (!['doctor', 'migrate', 'report'].includes(cmd)) {
+    // Both the folder the command runs on and, for a code-repo command, the Product it reads.
+    for (const root of new Set([o.dir || process.cwd(), o.product].filter(Boolean))) {
+      const drift = commands.productDriftError(root);
+      if (drift) throw drift;
+    }
+  }
 
   const today = new Date().toISOString().slice(0, 10);
   // What the command returned: under --json, a command that did not answer itself answers with it.
   let result;
   switch (cmd) {
     case 'setup':
+      // A workspace folder holds a Product; it never becomes a second one (E80 review 2 — following
+      // "run yad setup" from the workspace folder did exactly that, and hid the real one from its repos).
+      if (commands.workspaceProduct(o.dir)) { refuse(`this folder is a workspace — its Product is ${path.relative(process.cwd(), commands.workspaceProduct(o.dir)) || '.'}`, 'run `yad setup` there, or `yad next` from inside it'); break; }
       result = await commands.runSetup(o.dir, {
         today, force: o.force,
         solo: o.solo, team: o.team, greenfield: o.greenfield, brownfield: o.brownfield,
@@ -433,17 +588,36 @@ async function main() {
         ideTargets: o['ide-targets'] === undefined ? undefined : String(o['ide-targets']).split(',').map((t) => t.trim()).filter(Boolean),
       });
       break;
+    // E79: the workspace verbs. `--dir` is never the Product here: for `init` it is the WORKSPACE (the
+    // folder that holds product/ and the code repos); for `new` and `join` it is the folder the workspace
+    // is made IN. The setup flags pass through.
+    case 'new':
+    case 'init':
+    case 'join': {
+      const setupFlags = {
+        today, force: o.force,
+        solo: o.solo, team: o.team, greenfield: o.greenfield, brownfield: o.brownfield,
+        monorepo: o.monorepo, separate: o.separate, tools: o.tools,
+        ideTargets: o['ide-targets'] === undefined ? undefined : String(o['ide-targets']).split(',').map((t) => t.trim()).filter(Boolean),
+      };
+      if (cmd === 'new') result = await commands.runNew(o.dir, o._[1], setupFlags);
+      else if (cmd === 'init') result = await commands.runInit(o.dir, { ...setupFlags, path: o.path });
+      else result = await commands.runJoin(o.dir, o._[1], o._[2], { ideTargets: setupFlags.ideTargets });
+      break;
+    }
     case 'check':
+      if (noProduct()) break;
       result = await commands.reconcile(o.dir, { fix: o.fix, scope: o.scope, force: o.force, push: o.push, allowBranch: o.allowBranch, overwriteLocal: o.overwriteLocal, today });
       break;
     case 'update':
+      if (noProduct()) break;
       result = await commands.reconcile(o.dir, { fix: true, scope: 'changed', force: o.force, push: o.push, allowBranch: o.allowBranch, overwriteLocal: o.overwriteLocal, today });
       break;
     case 'doctor':
       result = await commands.runDoctor(o.dir, { json: o.json });
       break;
     case 'migrate':
-      result = await commands.runMigrate(o.dir, { apply: o.apply, json: o.json });
+      result = await commands.runMigrate(o.dir, { apply: o.apply, json: o.json, keep: o.keep ?? null });
       break;
     case 'report':
       result = await commands.runReport(o.dir, { message: o.message });
@@ -471,6 +645,7 @@ async function main() {
         refuse(`unknown epic action: ${action ?? '(none)'} (new)`, `usage: yad epic new <slug> [--type feature|chore|change|defect|hotfix] [--profile ${commands.seedableProfiles().join('|')}] [--parent EP-<slug> --inherits <bases>]`);
         break;
       }
+      if (noProduct()) break;
       result = await commands.runEpicNew(o.dir, { slug, type: o.type, profile: o.profile, stub: o.stub, parent: o.parent, inherits: o.inherits, today, json: o.json });
       break;
     }
@@ -481,12 +656,14 @@ async function main() {
         refuse(`unknown foundation action: ${action ?? '(none)'} (new, status)`, 'usage: yad foundation new [--json] | yad foundation status [--json]');
         break;
       }
+      if (noProduct()) break;
       result = await commands.runFoundationNew(o.dir, { today, json: o.json });
       break;
     }
     case 'skill': {
       const [, action, step, ...rest] = o._;
       if (action === 'list' || action === undefined) { result = commands.runSkillList(o.dir, { json: o.json }); break; }
+      if ((action === 'bind' || action === 'unbind') && noProduct()) break;
       if (action === 'bind') { result = commands.runSkillBind(o.dir, { step, skills: rest }); break; }
       if (action === 'unbind') { result = commands.runSkillUnbind(o.dir, { step }); break; }
       refuse(`unknown skill action: ${action} (list, bind, unbind)`, 'usage: yad skill list [--json] | yad skill bind <step> <skill> [<skill> ...] | yad skill unbind <step>');
@@ -525,9 +702,11 @@ async function main() {
       // One word names a Shape author step (project-wide). Three name a Build lane step: epic, story, step.
       const args = o._.slice(1);
       if (args.length === 1) {
+        if (noProduct()) break;
         result = await commands.runDial(o.dir, { step: args[0], to: o.to, json: o.json });
       } else if (args.length === 3) {
         if (!commands.isValidEpicId(args[0])) { refuse(`invalid epic id: ${args[0]} (expected EP-<slug>, [a-z0-9-] only)`); break; }
+        if (noProduct()) break;
         result = await commands.runDial(o.dir, { epic: args[0], story: args[1], step: args[2], repo: o.repo, to: o.to, json: o.json });
       } else {
         refuse('usage: yad dial <step> [--to auto|human]   |   yad dial <epic> <story> --repo <name> <step> [--to auto|human]');
@@ -542,6 +721,7 @@ async function main() {
     case 'kill':
     case 'unkill': {
       if (o._.length > 1) { refuse(`unexpected argument(s): ${o._.slice(1).join(' ')}`); break; }
+      if (noProduct()) break;
       result = await commands.runKill(o.dir, { on: o._[0] === 'kill', reason: o.reason, json: o.json, today });
       break;
     }
@@ -555,7 +735,7 @@ async function main() {
       const [, action, epic, artifact] = o._;
       // `gate ci` takes no positionals — epic/artifact come from --branch (or a sweep of all PRs).
       if (action === 'ci') { result = await commands.gateCi(o.dir, { branch: o.branch, pr: o.pr, merged: o.merged, push: !o.noPush, today }); break; }
-      if (!epic) { refuse('usage: yad gate <open|sync|comments|status|repair|review|walkthrough|trailer|ci> <epic> [artifact]'); break; }
+      if (!epic) { refuse('usage: yad gate <open|sync|comments|status|repair|review|walkthrough|trailer|ci|approve|comment|advance> <epic> [artifact]'); break; }
       // The epic id becomes a path segment under epics/ — reject anything but EP-<slug> outright.
       if (!commands.isValidEpicId(epic)) { refuse(`invalid epic id: ${epic} (expected EP-<slug>, [a-z0-9-] only)`); break; }
       // In verified mode CI is the sole ledger writer: `open` only opens the PR, and local `sync` is
@@ -569,31 +749,38 @@ async function main() {
       else if (action === 'review') result = await commands.gateReview(o.dir, { epic, artifact });
       else if (action === 'walkthrough') result = await commands.gateWalkthrough(o.dir, { epic, artifact });
       else if (action === 'trailer') result = await commands.gateTrailer(o.dir, { epic, artifact, body: o.body || o.message, number: o.pr });
-      else { refuse(`unknown gate action: ${action} (open|sync|comments|status|repair|review|walkthrough|trailer|ci)`); }
+      // E112 — the gate on a Product with no platform: record an approval, record a comment round, advance.
+      else if (action === 'approve') result = await commands.gateApprove(o.dir, { epic, artifact, by: o.by, engagement: o.engagement ?? null, today });
+      else if (action === 'comment') result = await commands.gateComment(o.dir, { epic, artifact, by: o.by, count: o.count ?? null, newRound: !!o.newRound, today });
+      else if (action === 'advance') result = await commands.gateAdvance(o.dir, { epic, artifact, today });
+      else { refuse(`unknown gate action: ${action} (open|sync|comments|status|repair|review|walkthrough|trailer|ci|approve|comment|advance)`); }
       break;
     }
     case 'review': {
       const [, action] = o._;
-      if (action === 'trailer') result = await commands.reviewTrailer(o.dir, { repo: o.repo, pr: o.pr, body: o.body || o.message });
-      else if (action === 'context' || action === 'chat' || action === 'cards') result = await commands.reviewContext(o.dir, { repo: o.repo, pr: o.pr });
-      else if (action === 'walkthrough') result = await commands.reviewWalkthrough(o.dir, { repo: o.repo, pr: o.pr });
-      else if (action === 'nudge') result = await commands.reviewNudge(o.dir, { repo: o.repo, pr: o.pr });
+      if (action === 'trailer') result = await commands.reviewTrailer(o.dir, { repo: o.repo, product: o.product, pr: o.pr, body: o.body || o.message });
+      else if (action === 'context' || action === 'chat' || action === 'cards') result = await commands.reviewContext(o.dir, { repo: o.repo, product: o.product, pr: o.pr });
+      else if (action === 'walkthrough') result = await commands.reviewWalkthrough(o.dir, { repo: o.repo, product: o.product, pr: o.pr });
+      else if (action === 'nudge') result = await commands.reviewNudge(o.dir, { repo: o.repo, product: o.product, pr: o.pr });
       else if (action === 'reconcile') {
         // The epic becomes a path segment under epics/ — reject anything but EP-<slug> (no `../` escape).
         if (!o.epic || !commands.isValidEpicId(o.epic)) { refuse(`invalid or missing --epic: ${o.epic ?? '(none)'} (expected EP-<slug>, [a-z0-9-] only)`); break; }
-        result = await commands.reviewReconcile(o.dir, { epic: o.epic, repo: o.repo, pr: o.pr });
+        result = await commands.reviewReconcile(o.dir, { epic: o.epic, repo: o.repo, product: o.product, pr: o.pr });
       }
       else { refuse('usage: yad review <trailer|context|walkthrough|nudge|reconcile> --repo <name> --pr <n> [--epic <id>] [--body <text>]'); }
       break;
     }
     case 'commit':
-      result = await commands.runCommit(o.dir, { type: o.type, message: o.message, task: o.task, ai: o.ai, contractChange: o.contractChange, dryRun: o.dryRun, force: o.force });
+      result = await commands.runCommit(o.dir, { type: o.type, message: o.message, task: o.task, ai: o.ai, contractChange: o.contractChange, dryRun: o.dryRun, force: o.force, manual: o.manual, reason: o.reason });
       break;
     case 'open-pr':
-      result = await commands.runOpenPr(o.dir, { repo: o.repo, platform: o.platform, base: o.base, title: o.title || o.message, task: o.task, risk: o.risk, contractChange: o.contractChange });
+      result = await commands.runOpenPr(o.dir, { repo: o.repo, product: o.product, platform: o.platform, base: o.base, title: o.title || o.message, task: o.task, risk: o.risk, contractChange: o.contractChange });
       break;
     case 'ship':
-      result = await commands.runShip(o.dir, { type: o.type, message: o.message, task: o.task, ai: o.ai, contractChange: o.contractChange, dryRun: o.dryRun, force: o.force, repo: o.repo, platform: o.platform, base: o.base, title: o.title, risk: o.risk });
+      // The ledger override is its own act (E49): recorded in its own commit, never folded into a
+      // commit-and-open-PR run. Refused, never ignored.
+      if (o.manual || o.reason !== undefined) { refuse('yad ship takes no --manual/--reason: commit with `yad commit --manual --reason "<why>" …`, then `yad open-pr`'); break; }
+      result = await commands.runShip(o.dir, { type: o.type, message: o.message, task: o.task, ai: o.ai, contractChange: o.contractChange, dryRun: o.dryRun, force: o.force, repo: o.repo, product: o.product, platform: o.platform, base: o.base, title: o.title, risk: o.risk });
       break;
     case 'checkpoint': {
       let retroShip;
@@ -609,6 +796,45 @@ async function main() {
       result = await commands.runCheckpoint(o.dir, { push: o.push, allowBranch: o.allowBranch, dryRun: o.dryRun, retroShip });
       break;
     }
+    case 'capture': {
+      // E43. `--hook` is the harness's post-edit command: it never fails and never prints to stdout.
+      if (o._[1]) { refuse(`yad capture takes no word (got ${o._[1]})`, 'usage: yad capture [--no-push]'); break; }
+      result = await commands.runCapture(o.dir, { hook: !!o.hook, noPush: !!o.noPush });
+      if (o.hook) process.exitCode = 0;
+      break;
+    }
+    case 'claims': {
+      // E46. Read from the capture branches; nothing is recorded here.
+      const [, epic, extra] = o._;
+      if (extra) { refuse(`yad claims takes at most an epic (got an extra word: ${extra})`, 'usage: yad claims [<epic>] [--no-fetch]'); break; }
+      result = await commands.runClaims(o.dir, { epic, noFetch: !!o.noFetch });
+      break;
+    }
+    case 'assign':
+    case 'unassign': {
+      // E47. A file per step; nothing is committed and nothing is blocked.
+      const [verb, epic, step, extra] = o._;
+      const usage = verb === 'assign' ? 'usage: yad assign <epic> <step> [--to <git name>] [--force]' : 'usage: yad unassign <epic> <step> [--force]';
+      if (extra) { refuse(`yad ${verb} takes an epic and a step (got an extra word: ${extra})`, usage); break; }
+      if (verb === 'unassign' && o.to != null) { refuse('yad unassign takes no --to: it removes whoever is assigned', usage); break; }
+      result = verb === 'assign'
+        ? await commands.runAssign(o.dir, { epic, step, to: o.to ?? null, force: !!o.force, today })
+        : await commands.runUnassign(o.dir, { epic, step, force: !!o.force });
+      break;
+    }
+    case 'owners': {
+      const [, epic, extra] = o._;
+      if (extra) { refuse(`yad owners takes at most an epic (got an extra word: ${extra})`, 'usage: yad owners [<epic>]'); break; }
+      result = await commands.runOwners(o.dir, { epic });
+      break;
+    }
+    case 'fold': {
+      // E44. The step-boundary commit; the authoring skills run it where they used to say "commit".
+      const [, epic, step, extra] = o._;
+      if (extra) { refuse(`yad fold takes an epic and a step (got an extra word: ${extra})`, 'usage: yad fold <epic> <step>'); break; }
+      result = await commands.runFold(o.dir, { epic, step });
+      break;
+    }
     case 'tidy': {
       const [, action, epic] = o._;
       if (action !== 'up') {
@@ -663,13 +889,14 @@ async function main() {
       // instead of "unknown command".
       refuse('yad roster was removed — yadflow keeps no list of people',
         'A gate needs one approval (not the author\'s own) from anyone with access to the repo; the platform records who approved. '
-        + 'Request reviewers on the PR itself. Keep an existing `roster` in hub.json until every review with older approvals is closed: '
+        + 'Request reviewers on the PR itself. Keep an existing `roster` in the Product settings until every review with older approvals is closed: '
         + 'it decides nothing, but the first sync uses its name → login pairs to recognise those approvals.');
       break;
     case 'docs': {
       const [, action] = o._;
       if (o.epic && !commands.isValidEpicId(o.epic)) { refuse(`invalid epic id: ${o.epic} (expected EP-<slug>, [a-z0-9-] only)`); break; }
       const sync = o.wire ? 'wire' : o.refresh ? 'refresh' : 'check';
+      if (noProduct()) break;
       result = await commands.runDocs(o.dir, { action: action || 'list', epic: o.epic, overview: o.overview, sync, today });
       break;
     }
@@ -739,7 +966,10 @@ main()
     // Require a TTY on BOTH ends: stdout for the message, stdin so the y/N prompt can be answered
     // (a TTY stdout with piped/closed stdin would otherwise hang on readline).
     const offerReport = !inJSON() && process.stdin.isTTY && process.stdout.isTTY && !process.env.SDLC_NONINTERACTIVE
-      && !process.env.YAD_NO_REPORT && process.argv[2] !== 'report';
+      && !process.env.YAD_NO_REPORT && process.argv[2] !== 'report'
+      // Two copies of the project's own settings that disagree (E122) are the project's state, not a
+      // yadflow bug: the refusal already names the one command that ends it.
+      && err?.code !== 'YAD-STATE-008';
     if (offerReport) {
       try {
         if (await askYesNo('\nReport this failure to the yadflow team?', false)) {