yadflow 4.0.0-next.3 → 4.0.0

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
@@ -170,17 +189,23 @@ ${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
@@ -204,7 +229,7 @@ ${c.bold('Build helpers')}
                                        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
@@ -224,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
@@ -252,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>)
@@ -285,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', '--by', '--count', '--engagement']);
+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' };
@@ -295,6 +332,7 @@ 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;
@@ -314,6 +352,7 @@ function parseArgs(argv) {
     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;
@@ -373,13 +412,46 @@ const ACTIONS = {
   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;
@@ -423,6 +495,8 @@ 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;
   }
@@ -442,16 +516,64 @@ async function main() {
     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,
@@ -466,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 });
@@ -504,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;
     }
@@ -514,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>');
@@ -558,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]');
@@ -575,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;
     }
@@ -611,26 +758,29 @@ async function main() {
     }
     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;
@@ -739,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;
     }
@@ -815,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)) {

package/cli/capture.mjs

@@ -255,12 +255,14 @@ function push(root, git, name, { hook, now, spawner, env }) {
     const last = Number(state.lastPushAt) || 0;
     if (now - last < PUSH_EVERY_MS) return { pushed: 'later', why: `the last push started under ${PUSH_EVERY_MS / 60000} minutes ago` };
     // Recorded BEFORE the push starts, so two hooks a moment apart cannot both start one.
+    // `windowsHide` below (E113): on Windows a detached console program gets a console window of its own,
+    // so without it every background push would flash one up in front of the person.
     if (stateFile) writeJSON(stateFile, { ...state, lastPushAt: now });
     try {
-      spawner('git', pushArgs(name), { cwd: root, env: { ...env, ...pushEnv(env) }, detached: true, stdio: 'ignore' }).unref();
+      spawner('git', pushArgs(name), { cwd: root, env: { ...env, ...pushEnv(env) }, detached: true, stdio: 'ignore', windowsHide: true }).unref();
       // E46: fetch everyone's capture branches in the same window, so the claim check at the next edit reads
       // minutes-old claims, not hours-old ones. Detached too: an edit never waits on it, and a failure is silent.
-      try { spawner('git', fetchAllArgs(), { cwd: root, env: { ...env, ...pushEnv(env) }, detached: true, stdio: 'ignore' }).unref(); } catch { /* claims read what was last fetched */ }
+      try { spawner('git', fetchAllArgs(), { cwd: root, env: { ...env, ...pushEnv(env) }, detached: true, stdio: 'ignore', windowsHide: true }).unref(); } catch { /* claims read what was last fetched */ }
       return { pushed: 'started' };
     } catch (e) {
       return { pushed: 'failed', why: e.message };

package/cli/checkpoint.mjs

@@ -2,7 +2,7 @@
 // build-state) as one audit-trail commit. This is the Build analogue of the Shape gate sync
 // (cli/gate.mjs): the SDLC's Build part (yad-run, yad-engineer-review) WRITES these ledgers into the
 // working tree but never commits them, so teammates/CI/`yad status` on other machines see stale trust
-// evidence. checkpoint lands them with a `chore(hub): ...` message.
+// evidence. checkpoint lands them with a `chore(product): ...` message.
 //
 // It also carries the Build story `status:` flip (approved → in-build/shipped) that
 // yad-engineer-review writes into stories/<id>.md but no command committed — the #112 drift where
@@ -26,7 +26,7 @@ import { c, log, ok, info, fail, hand, exists, readJSON, readJSONStrict, pushWit
 import { PROJECT_FILES , productConfigPath } from './manifest.mjs';
 import { loadProduct } from './gate.mjs';
 import { platformLogin } from './platform.mjs';
-import { productGit, resolveDefaultBranch, guardDefaultBranch } from './hubcommit.mjs';
+import { productGit, resolveDefaultBranch, guardDefaultBranch } from './productcommit.mjs';
 import { readShips, writeRetroShip } from './ledger.mjs';
 import { readFrontmatter, declaredRepos } from './epic-state.mjs';
 
@@ -68,7 +68,7 @@ const BACK_HALF_STATUSES = new Set(['in-build', 'shipped']);
 //   2. its current frontmatter `status:` is a Build value (in-build | shipped).
 // A candidate is only actually carried when its staged diff is the `status:` line ALONE — runCheckpoint
 // drops any candidate whose working tree also changed prose/other frontmatter (stagedStoryIsStatusOnly),
-// so an unrelated edit can never ride into a `chore(hub) … [skip ci]` commit that bypasses review.
+// so an unrelated edit can never ride into a `chore(product) … [skip ci]` commit that bypasses review.
 // The shared `git add`/`diff --cached` machinery then commits ONLY the ones that actually differ from
 // HEAD (so a story already committed at shipped is a no-op).
 //
@@ -139,11 +139,11 @@ export function checkpointAuthor(login, name) {
 }
 
 // PURE — the audit-trail commit message. The subject passes the Product commit-message gate (valid type
-// `chore`, optional scope `hub`, non-empty description, no trailing period). No Task trailer and no
+// `chore`, optional scope `product`, non-empty description, no trailing period). No Task trailer and no
 // Co-Authored-By footer: this is human-owned machine state, not an authored code change. `label` and
 // `author` are collapsed to one line so nothing can split the subject or forge a trailer.
 export function buildCheckpointMessage({ label, author, basenames = [] }) {
-  const subject = `chore(hub): sync Build state — ${oneLine(label)} by ${oneLine(author)} [skip ci]`;
+  const subject = `chore(product): sync Build state — ${oneLine(label)} by ${oneLine(author)} [skip ci]`;
   const body = basenames.length ? `Updated: ${basenames.join(', ')}` : '';
   return body ? `${subject}\n\n${body}` : subject;
 }
@@ -307,18 +307,18 @@ export async function runCheckpoint(root, opts = {}) {
   log(c.bold('\nyad checkpoint'));
   if (!exists(path.join(root, '.git'))) { fail('not a git repo'); process.exitCode = 1; return; }
   if (!exists(productConfigPath(root))) {
-    fail('no .sdlc/hub.json — checkpoint commits the Product Build ledger; run it from the Product');
+    fail('no .sdlc/product.json — checkpoint commits the Product Build ledger; run it from the Product');
     process.exitCode = 1;
     return;
   }
 
-  const { hub } = loadProduct(root);
+  const { productConfig } = loadProduct(root);
   const git = productGit(root);
   const branch = git('rev-parse', '--abbrev-ref', 'HEAD').stdout;
-  const defaultBranch = resolveDefaultBranch(git, hub);
+  const defaultBranch = resolveDefaultBranch(git, productConfig);
 
   // Default-branch guard (invariant 2) — shared with `yad tidy up`.
-  if (!guardDefaultBranch(branch, defaultBranch, { allowBranch: opts.allowBranch, cmd: 'yad checkpoint' })) return;
+  if (!guardDefaultBranch(branch, defaultBranch, { allowBranch: opts.allowBranch, cmd: 'yad checkpoint', root })) return;
 
   // --retro-ship (#142): record a retroactive build-log ship for a PRE-TRACKING story (merged before
   // the Build ledger existed, so it has no ship and its `status:` flip can't be carried). Done
@@ -377,7 +377,7 @@ export async function runCheckpoint(root, opts = {}) {
   const staged = git('diff', '--cached', '--name-only', '--', ...pathspecs).stdout.split('\n').filter(Boolean);
 
   const { label, basenames } = summarizeStaged(staged);
-  const author = checkpointAuthor(platformLogin(root, hub?.platform), git('config', 'user.name').stdout);
+  const author = checkpointAuthor(platformLogin(root, productConfig?.platform), git('config', 'user.name').stdout);
   const message = buildCheckpointMessage({ label, author, basenames });
 
   if (opts.dryRun) {

package/cli/claims.mjs

@@ -29,15 +29,15 @@ import fs from 'node:fs';
 import { ok, info, warn, fail, hand, readJSON, writeJSON } from './lib.mjs';
 import { productConfigPath } from './manifest.mjs';
 import { capturedEpic, gitIn, isOwnerPath, pushEnv, wipName, WIP_PREFIX, fetchAllArgs } from './capture.mjs';
-import { resolveDefaultBranch } from './hubcommit.mjs';
+import { resolveDefaultBranch } from './productcommit.mjs';
 
 export const CLAIM_HOURS = 4;
 const CLAIM_MS = CLAIM_HOURS * 60 * 60 * 1000;
 
 // The default branch as a ref this clone holds — origin's copy first, then a local branch — or null.
 function defaultRef(root, git) {
-  const hub = readJSON(productConfigPath(root), {}) || {};
-  const def = resolveDefaultBranch((...a) => { const r = git(a); return { ok: r.ok, stdout: r.out.trim() }; }, hub);
+  const productConfig = readJSON(productConfigPath(root), {}) || {};
+  const def = resolveDefaultBranch((...a) => { const r = git(a); return { ok: r.ok, stdout: r.out.trim() }; }, productConfig);
   for (const ref of [`refs/remotes/origin/${def}`, `refs/heads/${def}`]) if (git(['rev-parse', '--verify', '-q', `${ref}^{commit}`]).ok) return { ref, name: def };
   return { ref: null, name: def };
 }
@@ -149,7 +149,7 @@ export async function runClaims(root, { epic = null, noFetch = false, env = proc
       const opts = { cwd: root, encoding: 'utf8', timeout: 30_000, env: { ...env, ...pushEnv(env) } };
       const r = spawnSync('git', fetchAllArgs({ prune: true }), opts);
       fetched = r.status === 0 ? 'done' : 'failed';
-      // The default branch, for the "landed" rule — on its own: a name guessed wrong (no hub default, no
+      // The default branch, for the "landed" rule — on its own: a name guessed wrong (no Product default, no
       // origin/HEAD) must not stop the capture branches from arriving. Its failure changes nothing.
       const def = defaultRef(root, git).name;
       if (fetched === 'done') spawnSync('git', ['-c', 'http.lowSpeedLimit=1000', '-c', 'http.lowSpeedTime=20', 'fetch', '--quiet', '--no-tags', 'origin', `+refs/heads/${def}:refs/remotes/origin/${def}`], opts);