yadflow 3.18.1 → 4.0.0-next.1

package/bin/yad.mjs

@@ -1,32 +1,13 @@
 #!/usr/bin/env node
 // `yad` — setup/maintenance + the PR-driven review gate + build helpers for the SDLC module.
 import { VERSION } from '../cli/manifest.mjs';
-import { c, log, closePrompts, askYesNo } from '../cli/lib.mjs';
-import { runSetup } from '../cli/setup.mjs';
-import { reconcile } from '../cli/reconcile.mjs';
-import { gateOpen, gateSync, gateComments, gateStatus, gateCi, gateReview, gateTrailer, gateWalkthrough, gateRepair } from '../cli/gate.mjs';
-import { isValidEpicId } from '../cli/epic-state.mjs';
-import { runCommit } from '../cli/commit.mjs';
-import { runOpenPr } from '../cli/openpr.mjs';
-import { reviewTrailer, reviewContext, reviewNudge, reviewReconcile, reviewWalkthrough } from '../cli/review.mjs';
-import { runShip } from '../cli/ship.mjs';
-import { runCheckpoint } from '../cli/checkpoint.mjs';
-import { runTidy } from '../cli/tidy.mjs';
-import { runRepo } from '../cli/repo.mjs';
-import { runRoster } from '../cli/roster.mjs';
-import { runDocs } from '../cli/docs.mjs';
-import { runDoctor } from '../cli/doctor.mjs';
-import { runMigrate } from '../cli/migrate.mjs';
-import { runNext } from '../cli/next.mjs';
-import { runSkip } from '../cli/skip.mjs';
-import { syncStatuses } from '../cli/artifact-status.mjs';
-import { runThread, runReconcile } from '../cli/thread.mjs';
-import { runReport } from '../cli/report.mjs';
-import { runUsage } from '../cli/usage.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 { maybeNotifyUpdate } from '../cli/update-notice.mjs';
 
-const HELP = `${c.bold('yad')} — setup, review-gate & build helpers for the SDLC Workflow module  ${c.dim('v' + VERSION)}
+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('Setup & maintenance')}
   yad setup            Guided first-run setup (profile interview, install, connect & wire repos)
@@ -42,7 +23,7 @@ ${c.bold('Setup & maintenance')}
                        it. Anything else it cannot account for is replaced only after
                        a <file>.yad-orig backup
   yad update --push    Also commit each repo's applied changes and push them straight to the
-                       default branch of the hub + every connected repo (a chore(yad-update)
+                       default branch of the Product + every connected repo (a chore(yad-update)
                        commit; no PR — the push-on-main yad-update-guard runs verified-commits
                        + commit-message). Announce the team & pause merges first. Also works as
                        'yad check --fix --push'; --allow-branch permits a non-default branch
@@ -59,18 +40,13 @@ ${c.bold('Setup & maintenance')}
                        (no paths/hosts/repo names/logins/flag values). Also offered
                        automatically after an unexpected failure. YAD_NO_REPORT=1 disables.
   yad hook ledger-guard    ${c.dim('harness-invoked, not typed')} — refuse an agent's edit to the
-                       CI-owned gate ledger in bridge mode and name the command that owns
+                       CI-owned gate ledger in verified mode and name the command that owns
                        the transition. Reads a tool-call payload on stdin (or --path <p>);
-                       exit 0 allows, exit 2 denies with the reason on stderr. Wired into
-                       .claude/settings.json by setup / check --fix. YAD_HOOK_DISABLE=1 skips.
-
-${c.bold('Reviewer roster')}
-  yad roster list                      Show every member + their roles per scope (hub + each repo)
-  yad roster add <login>               Add/edit a member, then walk the connected repos for their roles
-                                       (--name, --email, --roles "hub=owner,reviewer backend=domain-owner")
-  yad roster grant <name> <repo> <role...>   Grant role(s) for a connected repo (domain-owner|reviewer|owner)
-  yad roster revoke <name> <repo> <role...>  Remove role(s) for a repo
-  yad roster remove <login>            Delete a member from the roster
+                       exit 0 allows, exit 2 denies with the reason on stderr. With
+                       --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.
 
 ${c.bold('Team usage (EM adoption & behavior report)')}
   yad usage                            Build a per-member report (HTML) from git + the SDLC ledgers
@@ -80,25 +56,99 @@ ${c.bold('Team usage (EM adoption & behavior report)')}
                                        --member <name>, --format html|json|md, --repos (code commits)
 
 ${c.bold('Where am I / what next')}
+  yad epic new <slug> [--type <t>] [--profile <p>] [--stub] [--parent <epic> --inherits <bases>] [--json]
+                                       Seed a new epic's lifecycle: writes its step chain from a
+                                       profile, plus empty approval/comment ledgers and reviews/.
+                                       --type feature|chore (default feature). A change/defect/
+                                       hotfix needs --parent: it takes the parent's route, and
+                                       --inherits epic,architecture,contract,ui-design carries
+                                       those steps by reference (satisfied, bound to the owner's
+                                       hash). Carrying the contract writes a pointer-lock instead
+                                       of a second contract (E42). The yad-change skill triages.
+                                       --profile ${profiles.join('|')} (default classic).
+                                       classic and analysis-first are the full chains; chore and
+                                       spike are E40's short lanes — epic + stories, with the
+                                       analyst's brief in front for a spike. Neither carries an
+                                       architecture gate, so neither may move the contract surface.
+                                       --stub seeds a brownfield anchor instead: the same chain
+                                       with every step blocked behind backfill-pending, so a
+                                       defect can thread off a feature that shipped before the
+                                       Product existed (yad-backfill promote wakes it).
+                                       Writes no epic.md, no branch and no commit: run the skill
+                                       the chain names next. Refuses an epic that already has one
+  yad foundation new [--json]          Seed the Product level (E75): the Foundation's two-step chain
+                                       in foundation/.sdlc/, plus empty ledgers and reviews/. Run once
+                                       per product, before any epic — then the yad-discovery skill
+                                       authors its sections. Refuses a second one, and a product still
+                                       on the old epics/EP-discovery/ (yad migrate converts that)
+  yad foundation status [--json]       Which roadmap features are started: reads each proposed epic id
+                                       in roadmap.md and reports planned / in-shape / in-build /
+                                       shipped from the epic ledgers. Read-only — the roadmap's Status
+                                       column is no longer kept by hand
   yad next                             Project-wide: the one next action to take (or run setup)
   yad next <epic>                      The single next action for one epic (skill or yad command)
   yad next <epic> --check <step>       Exit 0 if <step> is runnable now, else 1 (precondition guard)
   yad next --all                       Every active epic's next action at once
   yad next [<epic>] --json             The same answer as a machine-readable action object (for
                                        agents/CI) — always every epic, so --all is implied
-  yad skip <epic> ui-design --reason <text>   Mark an optional step N/A for this epic (only
-                                       ui-design today) — a backend/API/data epic with no UI.
-                                       Stays visible & auditable (pre-done, gate short-circuited);
-                                       --undo reverses it until the stories review opens
+  yad skill list [--json]              Which skill runs which step, and whether that is this
+                                       project's choice or the engine's default
+  yad skill bind <step> <skill> [<skill> ...]
+                                       Bind a step to a skill of your own. Several skills run in
+                                       the order given, one after another — each costs tokens
+  yad skill unbind <step>              Drop the binding; the step goes back to the engine's default
+  yad skip <epic> <step> --reason <text>   Mark an optional step N/A for this epic. Which steps
+                                       those are comes from the epic's lifecycle route — on classic
+                                       and analysis-first, ui-design: a backend/API/data epic with no
+                                       UI. Stays visible & auditable (reason recorded, gate
+                                       short-circuited); refused once any later step has started
+  yad unskip <epic> <step>             Put a skipped step back in the chain (\`skip --undo\` does the
+                                       same), until the step that follows it is finished or work
+                                       past it starts — on classic, until stories are done
+  yad skip <epic> <story> --repo <name> --reason <text>
+                                       Skip a whole Build lane: this story needs no change in this
+                                       repo (E39). Written to build-state/<story>.json; commit it with
+                                       yad checkpoint --push. Refused before the stories review passes
+                                       (edit the story's repos: instead), for a repo the story does not
+                                       declare, once work started or a ship is recorded, and for the
+                                       story's last lane. No single Build step can be skipped
+  yad unskip <epic> <story> --repo <name>
+                                       Put a skipped Build lane back; yad-run adds it on its next run
+  yad defer <epic> <step> --reason <text> [--debt]
+                                       Set an optional step aside to do LATER: marks it deferred.
+                                       Say who is waiting for it in the reason. Same steps and same
+                                       refusals as skip; the chain goes on, its review is still owed.
+                                       --debt marks it owed back: yad next and yad doctor remind
+                                       you until its review passes
+  yad undefer <epic> <step>            Put a deferred step back, at any time. After later work has
+                                       finished, the step re-opens beside that work, which stays done
+  yad unblock <epic> <step>            Clear a recorded blocker once the wait is over: moves the
+                                       step off blocked and removes its record in one write
+  yad dial <step> [--to auto|human] [--json]
+                                       A Shape author step's advance dial, for the whole project (E34),
+                                       kept in .sdlc/automation.json. No --to shows it. A review gate is
+                                       always human. Recorded only for now: nothing drives a Shape step
+                                       on its own until the engine runs agents
+  yad dial <epic> <story> --repo <name> <step> [--to auto|human] [--json]
+                                       A Build lane step's dial (spec, tasks, implement, checks), in
+                                       build-state; on auto the yad-run skill moves past it after a clean
+                                       run. Shows the step's run record as advice, never as a rule
+  yad kill --reason <text>             Kill switch: hold every step at advance: human. Recorded in
+                                       .sdlc/automation.json — who, when and why
+  yad unkill [--reason <text>]         Turn the kill switch off; each step follows its own dial again
+  yad mode [solo --reason <text> | team [--reason <text>]] [--json]
+                                       Who must approve. Solo waives approvals on every review gate (the
+                                       merge still decides); team counts them. Records who, when and why.
+                                       No word reads the mode. Open reviews follow it from their next sync
 
-${c.bold('Review gate (front half)')}
+${c.bold('Review gate (Shape)')}
   yad gate open <epic> <artifact>      Open the review PR/MR; mark the step in_review. The review
                                        branch must already be on origin (it is never created here)
   yad gate sync <epic> [artifact] [--pr <n>]
                                        Pull PR state -> ledger; advance on approved+resolved+merged.
                                        With no recorded PR, resolves it from the review branch; --pr
                                        names one (and overrides a stale recorded pointer). Advisory
-                                       in bridge mode — there, recover with 'yad gate ci' below
+                                       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 repair <epic> [--push]      Close an author step stranded behind a passed review gate
@@ -110,18 +160,18 @@ ${c.bold('Review gate (front half)')}
   yad gate trailer <epic> [artifact] --body <text> [--pr <n>]
                                        Upsert the companion's 60-sec briefing into the PR/MR description
   yad gate ci [--branch <head>] [--pr <n>] [--merged]
-                        CI entry (hub workflow): pre-merge is read-only (nothing pushed);
+                        CI entry (Product workflow): pre-merge is read-only (nothing pushed);
                         --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
-                                       hardcoded main; --base overrides) — stage-aware on the hub: a
-                                       review/EP-* branch opens the front-half artifact-review PR
-                                       (delegates to gate open), any other hub branch uses the
+                                       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)
-  yad checkpoint [--push]              Commit the machine-written back-half hub state
+  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
@@ -131,10 +181,22 @@ ${c.bold('Build helpers')}
                                        (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 tidy up [<epic>] [--push]        Fold FINISHED back-half shards (a shipped story's
+  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"
                                        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
+                                       override; on a verified Product CI writes it.
+                                       --json prints it, built live, and writes nothing
+  yad history [list] [--type t] [--theme x] [--thread EP-…] [--open|--done] [--json]
+                                       Every work item, open and shape-done (Build is not counted),
+                                       newest first — built live from their own files; writes nothing
+  yad history show <id> [--json]       One work item: every step with its state and closing record,
+                                       and the approvals recorded for each review step
+  yad history search <text> [filters] [--json]
+                                       Match text in ids, titles, themes, types, repos, and in who
+                                       closed or merged a step, its PR and its commit
   yad review trailer --repo <r> --pr <n> --body <text>   Post the companion's 60-sec briefing to a code PR/MR
   yad review context --repo <r> --pr <n>                  Print the grounding bundle for cards/chat
   yad review walkthrough --repo <r> --pr <n>              Bundle + ordered risk-tagged stops for the
@@ -144,7 +206,17 @@ ${c.bold('Build helpers')}
   yad repo list                        Show connected repos (fresh / stale)
   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]
-                       audit commit and pushes it to the hub default branch (--allow-branch to override)
+                       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
+  yad risk-map draft [repo]            Add an 'unset' line for every directory the map does not cover
+                                       (--dry-run prints it);
+                                       never changes a line (the yad-connect-repos skill classifies them)
+  yad codeowners check [repo] [--json] [--platform github|gitlab]
+                                       Warn where a code repo's CODEOWNERS looks stale: a line that
+                                       matches no file, a file the platform never reads or will not load,
+                                       a line yad cannot read; plus a hint about @logins with no recent
+                                       commit — advisory, never blocks, never writes the file
 
 ${c.bold('Feature threads (post-lock change management)')}
   yad thread                           List every feature thread (genesis → changes → defects)
@@ -169,7 +241,7 @@ ${c.bold('Options')}
   --repo <name>         open-pr: target a registered repo by name
   --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
-                        on the hub itself, else the platform, else origin/HEAD, else main); a
+                        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>)
   --overview            docs: target the project SDLC-overview site
@@ -189,12 +261,14 @@ ${c.bold('Options')}
 
 ${c.bold('Environment')}
   YAD_NO_UPDATE_NOTIFIER=1   Silence the "update available" notice (also off in CI)
-  YAD_NO_REPORT=1            Never offer to file a bug report after a failure`;
+  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', '--name', '--email', '--roles', '--team', '--body', '--out', '--since', '--until', '--member', '--format', '--reason', '--retro-ship', '--merge-commit', '--path']);
+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']);
 
 function parseArgs(argv) {
   const o = { _: [], dir: process.cwd(), fix: false, force: false, scope: 'all' };
+  try {
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--fix') o.fix = true;
@@ -212,7 +286,11 @@ function parseArgs(argv) {
     // positional. `o._[0]` is the command, already pushed by the time `--check` is seen in normal use.
     else if (a === '--check') { const v = argv[i + 1]; o.check = (o._[0] === 'next' && v !== undefined && !v.startsWith('-')) ? argv[++i] : true; }
     else if (a === '--all') o.all = true;
+    else if (a === '--open') o.open = true;
+    else if (a === '--done') o.done = true;
     else if (a === '--undo') o.undo = true;
+    else if (a === '--debt') o.debt = 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;
     else if (a === '--greenfield') o.greenfield = true;
@@ -234,11 +312,60 @@ function parseArgs(argv) {
     else if (a.startsWith('--scope=')) o.scope = a.slice('--scope='.length);
     else if (a === '-m' || a === '--message') o.message = takeValue(argv, ++i, a);
     else if (VALUE_FLAGS.has(a)) o[a.replace(/^--/, '')] = takeValue(argv, ++i, a);
-    else o._.push(a);
+    // `--flag=value` for the same flags. Without it the token matched nothing and fell through to the
+    // positionals, where it was silently ignored — and for `yad hook ledger-guard --format=cursor`
+    // that is not a cosmetic miss: the format goes undefined, the exit protocol is selected, and under
+    // Cursor an empty stdout on an allow BLOCKS every file write. A flag spelling that silently
+    // inverts a guard is worth accepting rather than quietly dropping.
+    else if (a.startsWith('--') && a.includes('=') && VALUE_FLAGS.has(a.slice(0, a.indexOf('=')))) {
+      const eq = a.indexOf('=');
+      const value = a.slice(eq + 1);
+      if (!value) throw new Error(`${a.slice(0, eq)} expects a value`);
+      o[a.slice(2, eq)] = value;
+    } else o._.push(a);
+  }
+  } catch (e) {
+    // The command read so far, so the error handler knows WHICH command failed — the parse did not finish.
+    e.parsedCmd = o._[0] ?? null;
+    // The words read so far, so a refusal names `history show`, not the default action (E1 review).
+    e.parsedWords = o._.slice(0, 2);
+    throw e;
   }
   return o;
 }
 
+// The command `main` is running, for the error handler (set once the arguments are read).
+let runningCmd = null;
+
+// The `command` a --json answer names: the command word, plus its action where it has one, as the
+// user would type it (`gate status`, `history show`). An action left out is the one that ran
+// (`yad skill` is `skill list`); a word that is not one of the command's actions is not added, so a
+// refusal of `yad gate frobnicate` names `gate`, not a command that does not exist.
+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'] },
+  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' },
+  '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'] },
+};
+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;
+  if (!cmd) return null;
+  const a = ACTIONS[cmd];
+  if (!a) return cmd;
+  if (action === undefined) return a.default ? `${cmd} ${a.default}` : cmd;
+  return a.known.includes(action) ? `${cmd} ${action}` : cmd;
+}
+
 // A value flag must be followed by a token; erroring beats silently passing `undefined` downstream.
 function takeValue(argv, i, flag) {
   const v = argv[i];
@@ -247,179 +374,361 @@ function takeValue(argv, i, flag) {
 }
 
 async function main() {
+  // `--json` is read from the raw arguments too, so a refusal from the parser itself (a flag with no
+  // value) still answers as one object.
+  if (process.argv.slice(2).includes('--json')) beginJSON(null);
   const o = parseArgs(process.argv.slice(2));
   const cmd = o._[0];
-  if (o.version) return log(VERSION);
-  if (o.help || !cmd) return log(HELP);
+  runningCmd = cmd ?? null;
+  // The grounding bundles a skill parses are JSON with or without the flag, so they are always a
+  // --json run: one object on stdout, a refusal included, and every other line on stderr.
+  if (o.json || ALWAYS_JSON.has(commandName(o._))) beginJSON(commandName(o._));
+  if (o.version) return inJSON() ? emitJSON({}) : log(VERSION);
+
+  // THE HOT PATH, handled before anything heavy is loaded. `yad hook ledger-guard` runs inside the
+  // agent's tool loop on every file-editing call, and it needs `cli/hook.mjs` alone. Everything else
+  // lives behind the single dynamic import below, so the hook no longer pays for 29 modules it does
+  // not use — measured at ~30ms of module loading against ~14ms for what it actually needs.
+  //
+  // It sits above the help and the newer-shape warning deliberately: `--help` is not a hook call, and
+  // the warning is already excluded for `hook` below because its stderr is the channel a block reason
+  // reaches the model on.
+  if (cmd === 'hook') {
+    const [, action] = o._;
+    // Its stdout is already a protocol (Claude Code reads the exit code, Cursor a permission object),
+    // 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)`);
+    runLedgerGuardHook({ paths: o.path ? [o.path] : [], format: o.format });
+    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);
+  }
+  // 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());
 
   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':
-      await runSetup(o.dir, {
+      result = await commands.runSetup(o.dir, {
         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,
+        // The agent directories to install into, as a pre-answer for CI/scripts exactly like `--solo`
+        // above (E11). Until this flag existed, `ideTargets` was reachable only programmatically: a
+        // non-interactive run took `ask`'s default and had NO way to choose. That was survivable while
+        // the default was one directory; it stopped being survivable when the default became two,
+        // because a scripted setup would write a second full copy of the skills with no way to say no.
+        // `o['ide-targets']`, not `o.ideTargets`: VALUE_FLAGS strips the leading `--` and nothing else,
+        // so a hyphenated flag keeps its hyphen as the key (`--retro-ship` is read the same way below).
+        ideTargets: o['ide-targets'] === undefined ? undefined : String(o['ide-targets']).split(',').map((t) => t.trim()).filter(Boolean),
       });
       break;
     case 'check':
-      await reconcile(o.dir, { fix: o.fix, scope: o.scope, force: o.force, push: o.push, allowBranch: o.allowBranch, overwriteLocal: o.overwriteLocal, today });
+      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':
-      await reconcile(o.dir, { fix: true, scope: 'changed', force: o.force, push: o.push, allowBranch: o.allowBranch, overwriteLocal: o.overwriteLocal, today });
+      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':
-      await runDoctor(o.dir, { json: o.json });
+      result = await commands.runDoctor(o.dir, { json: o.json });
       break;
     case 'migrate':
-      await runMigrate(o.dir, { apply: o.apply, json: o.json });
-      break;
-    // Harness-invoked, not typed by a human: a tool-call payload arrives on stdin and the exit code
-    // is the verdict (0 allow, 2 deny). See cli/hook.mjs for the contract.
-    case 'hook': {
-      const [, action] = o._;
-      if (action !== 'ledger-guard') {
-        log(c.red(`unknown hook: ${action ?? '(none)'} (ledger-guard)`));
-        process.exitCode = 1;
-        break;
-      }
-      runLedgerGuardHook({ paths: o.path ? [o.path] : [] });
+      result = await commands.runMigrate(o.dir, { apply: o.apply, json: o.json });
       break;
-    }
     case 'report':
-      await runReport(o.dir, { message: o.message });
+      result = await commands.runReport(o.dir, { message: o.message });
       break;
     case 'usage':
-      runUsage(o.dir, {
+      result = commands.runUsage(o.dir, {
         out: o.out, since: o.since, until: o.until, all: o.all, member: o.member,
         format: o.format, repos: o.repos, json: o.json, today,
       });
       break;
     case 'sync-status': {
       const [, epic] = o._;
-      if (epic && !isValidEpicId(epic)) { log(c.red(`invalid epic id: ${epic} (expected EP-<slug>, [a-z0-9-] only)`)); process.exitCode = 1; break; }
-      await syncStatuses(o.dir, { epic, dryRun: o.dryRun });
+      if (epic && !commands.isValidEpicId(epic)) { refuse(`invalid epic id: ${epic} (expected EP-<slug>, [a-z0-9-] only)`); break; }
+      result = await commands.syncStatuses(o.dir, { epic, dryRun: o.dryRun });
+      break;
+    }
+    case 'epic': {
+      const [, action, slug, ...extra] = o._;
+      // A stray word is refused rather than dropped: `--inherits epic architecture` takes only `epic` as
+      // the value, and silently seeding without `architecture` would carry less than the author asked.
+      if (action === 'new' && extra.length) {
+        refuse(`unexpected argument(s): ${extra.join(' ')} — a list takes commas, e.g. --inherits epic,architecture`); break;
+      }
+      if (action !== 'new') {
+        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;
+      }
+      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;
+    }
+    case 'foundation': {
+      const [, action] = o._;
+      if (action === 'status') { result = await commands.runFoundationStatus(o.dir, { json: o.json }); break; }
+      if (action !== 'new') {
+        refuse(`unknown foundation action: ${action ?? '(none)'} (new, status)`, 'usage: yad foundation new [--json] | yad foundation status [--json]');
+        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') { 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>');
       break;
     }
     case 'next': {
       const [, epic] = o._;
       // `--check` with no step is a malformed guard call — fail loudly rather than silently print.
-      if (o.check === true) { log(c.red('usage: yad next <epic> --check <step>')); process.exitCode = 1; break; }
-      await runNext(o.dir, { epic, check: typeof o.check === 'string' ? o.check : undefined, all: o.all, json: o.json });
+      if (o.check === true) { refuse('usage: yad next <epic> --check <step>'); break; }
+      result = await commands.runNext(o.dir, { epic, check: typeof o.check === 'string' ? o.check : undefined, all: o.all, json: o.json });
       break;
     }
-    case 'skip': {
+    case 'skip':
+    case 'unskip':
+    case 'defer':
+    case 'undefer': {
+      const [verb, epic, step] = o._;
+      if (!epic || !commands.isValidEpicId(epic)) { refuse(`invalid or missing epic id: ${epic ?? '(none)'} (expected EP-<slug>, [a-z0-9-] only)`); break; }
+      // A STORY id where the step goes names a whole Build lane (E39), with --repo naming the repo. No Shape
+      // step id ends in -S<n>, so the two never overlap. A lane is skipped, never deferred.
+      if (step && /-S\d+$/i.test(step)) {
+        if (verb === 'defer' || verb === 'undefer') {
+          refuse(`a Build lane is skipped whole, never deferred: yad skip ${epic} ${step} --repo <name> --reason "<why>"`); break;
+        }
+        if (o.debt) warn('--debt is not used on a Build lane: a lane is skipped whole, never owed back');
+        result = await commands.runLaneSkip(o.dir, { epic, story: step, repo: o.repo, reason: o.reason, undo: verb === 'unskip' || o.undo, today });
+        break;
+      }
+      if (o.repo) warn(`--repo is only for a Build lane (yad ${verb} ${epic} <story> --repo <name>) — ignored for a Shape step`);
+      // `unskip` / `undefer` are the verbs E36 / E37 named; `--undo` is the spelling that shipped first and stays.
+      const runVerb = verb === 'defer' || verb === 'undefer' ? commands.runDefer : commands.runSkip;
+      result = await runVerb(o.dir, { epic, step, reason: o.reason, debt: o.debt, undo: verb.startsWith('un') || o.undo, today });
+      break;
+    }
+    case 'dial': {
+      // 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) {
+        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; }
+        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]');
+      }
+      break;
+    }
+    case 'mode': {
+      if (o._.length > 2) { refuse(`unexpected argument(s): ${o._.slice(2).join(' ')}`); break; }
+      result = await commands.runMode(o.dir, { to: o._[1] ?? null, reason: o.reason, json: o.json, today });
+      break;
+    }
+    case 'kill':
+    case 'unkill': {
+      if (o._.length > 1) { refuse(`unexpected argument(s): ${o._.slice(1).join(' ')}`); break; }
+      result = await commands.runKill(o.dir, { on: o._[0] === 'kill', reason: o.reason, json: o.json, today });
+      break;
+    }
+    case 'unblock': {
       const [, epic, step] = o._;
-      if (!epic || !isValidEpicId(epic)) { log(c.red(`invalid or missing epic id: ${epic ?? '(none)'} (expected EP-<slug>, [a-z0-9-] only)`)); process.exitCode = 1; break; }
-      await runSkip(o.dir, { epic, step, reason: o.reason, undo: o.undo, today });
+      if (!epic || !commands.isValidEpicId(epic)) { refuse(`invalid or missing epic id: ${epic ?? '(none)'} (expected EP-<slug>, [a-z0-9-] only)`); break; }
+      result = await commands.runUnblock(o.dir, { epic, step });
       break;
     }
     case 'gate': {
       const [, action, epic, artifact] = o._;
       // `gate ci` takes no positionals — epic/artifact come from --branch (or a sweep of all PRs).
-      if (action === 'ci') { await gateCi(o.dir, { branch: o.branch, pr: o.pr, merged: o.merged, push: !o.noPush, today }); break; }
-      if (!epic) { log(c.red('usage: yad gate <open|sync|comments|status|repair|review|walkthrough|trailer|ci> <epic> [artifact]')); process.exitCode = 1; break; }
+      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; }
       // The epic id becomes a path segment under epics/ — reject anything but EP-<slug> outright.
-      if (!isValidEpicId(epic)) { log(c.red(`invalid epic id: ${epic} (expected EP-<slug>, [a-z0-9-] only)`)); process.exitCode = 1; break; }
-      // In bridge mode CI is the sole ledger writer: `open` only opens the PR, and local `sync` is
+      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
       // advisory (reads the platform, prints status, writes nothing). The artifact status flip is
-      // CI's job at merge — never wired into the local gate. File-only mode keeps local writes.
-      if (action === 'open') await gateOpen(o.dir, { epic, artifact });
-      else if (action === 'sync') await gateSync(o.dir, { epic, artifact, today, number: o.pr, local: true });
-      else if (action === 'comments') await gateComments(o.dir, { epic, artifact, today });
-      else if (action === 'status') await gateStatus(o.dir, { epic });
-      else if (action === 'repair') await gateRepair(o.dir, { epic, push: o.push, allowBranch: o.allowBranch, dryRun: o.dryRun });
-      else if (action === 'review') await gateReview(o.dir, { epic, artifact });
-      else if (action === 'walkthrough') await gateWalkthrough(o.dir, { epic, artifact });
-      else if (action === 'trailer') await gateTrailer(o.dir, { epic, artifact, body: o.body || o.message, number: o.pr });
-      else { log(c.red(`unknown gate action: ${action} (open|sync|comments|status|repair|review|walkthrough|trailer|ci)`)); process.exitCode = 1; }
+      // CI's job at merge — never wired into the local gate. Local mode keeps local writes.
+      if (action === 'open') result = await commands.gateOpen(o.dir, { epic, artifact, today });
+      else if (action === 'sync') result = await commands.gateSync(o.dir, { epic, artifact, today, number: o.pr, local: true });
+      else if (action === 'comments') result = await commands.gateComments(o.dir, { epic, artifact, today });
+      else if (action === 'status') result = await commands.gateStatus(o.dir, { epic });
+      else if (action === 'repair') result = await commands.gateRepair(o.dir, { epic, push: o.push, allowBranch: o.allowBranch, dryRun: o.dryRun, today });
+      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)`); }
       break;
     }
     case 'review': {
       const [, action] = o._;
-      if (action === 'trailer') await reviewTrailer(o.dir, { repo: o.repo, pr: o.pr, body: o.body || o.message });
-      else if (action === 'context' || action === 'chat' || action === 'cards') await reviewContext(o.dir, { repo: o.repo, pr: o.pr });
-      else if (action === 'walkthrough') await reviewWalkthrough(o.dir, { repo: o.repo, pr: o.pr });
-      else if (action === 'nudge') await reviewNudge(o.dir, { repo: o.repo, pr: o.pr });
+      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 });
       else if (action === 'reconcile') {
         // The epic becomes a path segment under epics/ — reject anything but EP-<slug> (no `../` escape).
-        if (!o.epic || !isValidEpicId(o.epic)) { log(c.red(`invalid or missing --epic: ${o.epic ?? '(none)'} (expected EP-<slug>, [a-z0-9-] only)`)); process.exitCode = 1; break; }
-        await reviewReconcile(o.dir, { epic: o.epic, repo: o.repo, pr: o.pr });
+        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 });
       }
-      else { log(c.red('usage: yad review <trailer|context|walkthrough|nudge|reconcile> --repo <name> --pr <n> [--epic <id>] [--body <text>]')); process.exitCode = 1; }
+      else { refuse('usage: yad review <trailer|context|walkthrough|nudge|reconcile> --repo <name> --pr <n> [--epic <id>] [--body <text>]'); }
       break;
     }
     case 'commit':
-      await 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 });
       break;
     case 'open-pr':
-      await 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, platform: o.platform, base: o.base, title: o.title || o.message, task: o.task, risk: o.risk, contractChange: o.contractChange });
       break;
     case 'ship':
-      await 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 });
+      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 });
       break;
     case 'checkpoint': {
       let retroShip;
       if (o['retro-ship']) {
         const [epic, story] = String(o['retro-ship']).split('/');
-        if (!epic || !isValidEpicId(epic)) { log(c.red(`invalid --retro-ship: expected <epic>/<story> with epic EP-<slug> (got ${o['retro-ship']})`)); process.exitCode = 1; break; }
+        if (!epic || !commands.isValidEpicId(epic)) { refuse(`invalid --retro-ship: expected <epic>/<story> with epic EP-<slug> (got ${o['retro-ship']})`); break; }
         // The story id becomes a path element (stories/<story>.md) — pin it to the id shape (and to its
         // own epic) so a `..` or a slash can never traverse out of the epic's stories dir, and a typo'd
         // cross-epic id is caught here rather than failing obscurely later.
-        if (!story || !/^EP-[a-z0-9-]+-S\d+$/.test(story) || !story.startsWith(`${epic}-S`)) { log(c.red(`invalid --retro-ship: expected <epic>/<story> with story <epic>-S<NN> (got ${o['retro-ship']})`)); process.exitCode = 1; break; }
+        if (!story || !/^EP-[a-z0-9-]+-S\d+$/.test(story) || !story.startsWith(`${epic}-S`)) { refuse(`invalid --retro-ship: expected <epic>/<story> with story <epic>-S<NN> (got ${o['retro-ship']})`); break; }
         retroShip = { epic, story, repo: o.repo, task: o.task, mergeCommit: o['merge-commit'], today };
       }
-      await runCheckpoint(o.dir, { push: o.push, allowBranch: o.allowBranch, dryRun: o.dryRun, retroShip });
+      result = await commands.runCheckpoint(o.dir, { push: o.push, allowBranch: o.allowBranch, dryRun: o.dryRun, retroShip });
       break;
     }
     case 'tidy': {
       const [, action, epic] = o._;
-      if (action !== 'up') { log(`usage: yad tidy up [<epic>] [--push] [--dry-run]`); process.exitCode = action ? 1 : 0; break; }
-      await runTidy(o.dir, { epic: epic || o.epic, push: o.push, allowBranch: o.allowBranch, dryRun: o.dryRun });
+      if (action !== 'up') {
+        // A bare `yad tidy` is a request for the usage, not a mistake: exit 0.
+        if (action) refuse(`unknown tidy action: ${action} (up)`, 'usage: yad tidy up [<epic>] [--push] [--dry-run]');
+        else if (inJSON()) emitJSON({ usage: 'yad tidy up [<epic>] [--push] [--dry-run]' });
+        else log(`usage: yad tidy up [<epic>] [--push] [--dry-run]`);
+        break;
+      }
+      result = await commands.runTidy(o.dir, { epic: epic || o.epic, push: o.push, allowBranch: o.allowBranch, dryRun: o.dryRun });
+      break;
+    }
+    case 'index':
+      result = await commands.runIndex(o.dir, { json: o.json });
+      break;
+    case 'history': {
+      const [, action, ...args] = o._;
+      // Every flag that is not history's own is refused, not ignored: an ignored `--since` would read as
+      // a filter that was applied. Read from the RAW arguments, as typed — `parseArgs` turns a flag it
+      // does not know (`--limit`, a typo) into a plain word, which `search` would take as text, and it
+      // stores `--preview` under another name. A word that starts with `--`, or a one-letter flag such
+      // as `-m`, is a flag; a value (`--type chore`) never starts with `-`, because `parseArgs` refuses it.
+      const HISTORY_OWN = new Set(commands.HISTORY_FLAGS);
+      const unknownFlags = [...new Set(process.argv.slice(2)
+        .filter((t) => /^--./.test(t) || /^-[A-Za-z]$/.test(t))
+        .map((t) => t.split('=')[0])
+        .filter((f) => !HISTORY_OWN.has(f)))];
+      result = await commands.runHistory(o.dir, {
+        action: action || 'list', args, json: !!o.json, unknownFlags,
+        type: o.type ?? null, theme: o.theme ?? null, thread: o.thread ?? null, open: !!o.open, done: !!o.done,
+      });
       break;
     }
     case 'repo': {
       const [, action, name] = o._;
-      await runRepo(o.dir, { action: action || 'list', name, today, push: o.push, allowBranch: o.allowBranch });
+      result = await commands.runRepo(o.dir, { action: action || 'list', name, today, push: o.push, allowBranch: o.allowBranch });
       break;
     }
-    case 'roster': {
-      const [, action, ...rest] = o._;
-      await runRoster(o.dir, { action: action || 'list', args: rest, name: o.name, email: o.email, roles: o.roles, today });
+    case 'risk-map': {
+      const [, action, name] = o._;
+      result = await commands.runRiskMap(o.dir, { action: action || 'check', name, json: o.json, dryRun: o.dryRun });
       break;
     }
+    case 'codeowners': {
+      const [, action, name] = o._;
+      // `--write` was dropped (E69); wherever it is typed, it is refused with the reason — never ignored.
+      result = await commands.runCodeowners(o.dir, { action: action || 'check', name, json: o.json, platform: o.platform, write: o._.some((a) => a === '--write' || a.startsWith('--write=')) });
+      break;
+    }
+    case 'roster':
+      // Removed in E62. Kept as a word for one major so a script or a habit gets told where it went
+      // 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: '
+        + '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 && !isValidEpicId(o.epic)) { log(c.red(`invalid epic id: ${o.epic} (expected EP-<slug>, [a-z0-9-] only)`)); process.exitCode = 1; break; }
+      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';
-      await runDocs(o.dir, { action: action || 'list', epic: o.epic, overview: o.overview, sync, today });
+      result = await commands.runDocs(o.dir, { action: action || 'list', epic: o.epic, overview: o.overview, sync, today });
       break;
     }
     case 'thread': {
       const [, epic] = o._;
-      if (epic && !isValidEpicId(epic)) { log(c.red(`invalid epic id: ${epic} (expected EP-<slug>, [a-z0-9-] only)`)); process.exitCode = 1; break; }
-      await runThread(o.dir, { epic, json: o.json });
+      if (epic && !commands.isValidEpicId(epic)) { refuse(`invalid epic id: ${epic} (expected EP-<slug>, [a-z0-9-] only)`); break; }
+      result = await commands.runThread(o.dir, { epic, json: o.json });
       break;
     }
     case 'reconcile': {
       const [, action] = o._;
       const thread = o.epic || o.thread || null;
-      if (thread && !isValidEpicId(thread)) { log(c.red(`invalid epic id: ${thread} (expected EP-<slug>, [a-z0-9-] only)`)); process.exitCode = 1; break; }
+      if (thread && !commands.isValidEpicId(thread)) { refuse(`invalid epic id: ${thread} (expected EP-<slug>, [a-z0-9-] only)`); break; }
       const act = action || (o.wire ? 'wire' : o.refresh ? 'refresh' : 'check');
       if (!['check', 'refresh', 'wire'].includes(act)) {
-        log(c.red(`unknown reconcile action: ${act} (check|refresh|wire)`)); process.exitCode = 1; break;
+        refuse(`unknown reconcile action: ${act} (check|refresh|wire)`); break;
       }
-      await runReconcile(o.dir, { action: act, thread });
+      result = await commands.runReconcile(o.dir, { action: act, thread });
       break;
     }
     default:
+      if (inJSON()) { refuse(`unknown command: ${cmd}`, '`yad --help` lists the commands'); break; }
       log(c.red(`unknown command: ${cmd}`));
-      log(HELP);
+      log(helpText(commands.seedableProfiles()));
       process.exitCode = 1;
   }
+  return result;
 }
 
 main()
+  // A command that finished a --json run without answering is a yadflow bug. Stdout still gets one
+  // object saying so, never an empty stream a parser chokes on — and never a guessed `ok: true`.
+  .then((result) => {
+    if (!inJSON() || jsonEmitted()) return;
+    // A refusal said in prose (`fail` + its `hint`) becomes the JSON refusal.
+    // What the command DID rides along: a push that failed after the commit landed must not read as
+    // "nothing happened" (E1 review) — `ship` answers `committed: true` beside the refusal.
+    const said = process.exitCode ? jsonFailure() : null;
+    if (said) {
+      // Never a key the envelope or the refusal owns: a clash would throw inside the answer and lose the
+      // real refusal, and a `json` key is an option of `refuse`, not data.
+      const owned = new Set([...ENVELOPE_KEYS, 'ok', 'error', 'code', 'hint', 'warnings', 'json']);
+      const did = Object.fromEntries(Object.entries(isPlainObject(result) ? result : {}).filter(([k]) => !owned.has(k)));
+      return refuse(said.error, said.hint, { code: said.code, ...did });
+    }
+    // Otherwise the command's result object IS the answer — `ok` follows the exit code, as everywhere.
+    if (isPlainObject(result)) return emitJSON({ ...result, ok: !process.exitCode });
+    refuse(`yad ${runningCmd ?? ''} gave no JSON answer — this is a yadflow bug`.replace('  ', ' '), 'run it without --json to see what it printed, and report it with `yad report`');
+  })
   .catch(async (err) => {
+    // Under --json every failure is still one object on stdout (E1) — a refusal from the parser, a
+    // thrown YadError, a bug. The `code` is the `YAD-` code README "Troubleshooting" is keyed on.
+    // If the command had already answered, stdout holds its object, and the failure goes to stderr.
+    if (inJSON() && !jsonEmitted()) {
+      if (err?.parsedCmd !== undefined && runningCmd === null) beginJSON(commandName(err.parsedWords ?? []));
+      const hint = err?.hint || (/expects a value$/.test(String(err?.message)) ? '`yad --help` lists the flags of each command' : null);
+      refuse(String(err?.message || err), hint, { code: err?.code && /^YAD-/.test(err.code) ? err.code : null });
+      return;
+    }
     const code = err?.code && /^YAD-/.test(err.code) ? ` [${err.code}]` : '';
     log(c.red(`\nyad failed${code}: ${err?.message || err}`));
     if (err?.hint) log(c.yellow(`  → ${err.hint}`));
@@ -429,11 +738,12 @@ main()
     // YAD_NO_REPORT. `report` failing on its own would land here, so never re-offer for it.
     // 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 = process.stdin.isTTY && process.stdout.isTTY && !process.env.SDLC_NONINTERACTIVE
+    const offerReport = !inJSON() && process.stdin.isTTY && process.stdout.isTTY && !process.env.SDLC_NONINTERACTIVE
       && !process.env.YAD_NO_REPORT && process.argv[2] !== 'report';
     if (offerReport) {
       try {
         if (await askYesNo('\nReport this failure to the yadflow team?', false)) {
+          const { runReport } = await import('./commands.mjs');
           await runReport(process.cwd(), { error: err });
         }
       } catch { /* reporting is best-effort — never mask the original failure */ }
@@ -450,7 +760,10 @@ main()
       // block reason travels on — an update banner there would land in front of a model.
       // Resolved the way main() resolves it, NOT from argv[2]: that is the first raw argument, so
       // `yad --dir <path> hook ledger-guard` puts `--dir` there and the banner slips through.
-      if (parseArgs(process.argv.slice(2))._[0] !== 'hook') await maybeNotifyUpdate();
+      if (parseArgs(process.argv.slice(2))._[0] !== 'hook') {
+        const { maybeNotifyUpdate } = await import('./commands.mjs');
+        await maybeNotifyUpdate();
+      }
     } catch { /* the notice is never worth failing or hanging a command over */ } finally {
       closePrompts();
     }