yadflow 4.7.0 → 4.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (96) hide show
  1. package/CHANGELOG.md +116 -0
  2. package/README.md +43 -4
  3. package/bin/commands.mjs +5 -1
  4. package/bin/yad.mjs +169 -22
  5. package/cli/agent-guard.mjs +511 -0
  6. package/cli/agent-guide.mjs +83 -0
  7. package/cli/agent-rules.mjs +388 -0
  8. package/cli/argv-flags.mjs +7 -0
  9. package/cli/build.mjs +1 -1
  10. package/cli/ci-check.mjs +492 -0
  11. package/cli/docs.mjs +1 -1
  12. package/cli/doctor.mjs +148 -7
  13. package/cli/epic-state.mjs +3 -3
  14. package/cli/errors.mjs +1 -0
  15. package/cli/guide.mjs +549 -0
  16. package/cli/hook.mjs +32 -3
  17. package/cli/lib.mjs +46 -0
  18. package/cli/lifecycle/defaults/2.json +124 -0
  19. package/cli/lifecycle/lifecycle.schema.json +5 -2
  20. package/cli/lifecycle.mjs +16 -3
  21. package/cli/machine.mjs +141 -0
  22. package/cli/manifest.mjs +75 -0
  23. package/cli/marked-block.mjs +48 -0
  24. package/cli/members.mjs +19 -5
  25. package/cli/migrate.mjs +17 -19
  26. package/cli/next.mjs +1 -1
  27. package/cli/openpr.mjs +46 -6
  28. package/cli/plan.mjs +326 -22
  29. package/cli/preview.mjs +253 -0
  30. package/cli/protection.mjs +50 -0
  31. package/cli/reconcile.mjs +187 -26
  32. package/cli/repo.mjs +64 -3
  33. package/cli/report.mjs +62 -14
  34. package/cli/review.mjs +4 -0
  35. package/cli/setup.mjs +244 -25
  36. package/cli/signing.mjs +377 -0
  37. package/cli/story-frames.mjs +296 -0
  38. package/cli/test-agents-file.mjs +993 -0
  39. package/cli/test-ci-check.mjs +616 -0
  40. package/cli/test-guide.mjs +1267 -0
  41. package/cli/test-machine.mjs +140 -0
  42. package/cli/test-node.mjs +129 -0
  43. package/cli/test-preview.mjs +511 -0
  44. package/cli/test-setup-agent.mjs +352 -0
  45. package/cli/test-signing.mjs +524 -0
  46. package/cli/test-story-frames.mjs +339 -0
  47. package/cli/toolbox.mjs +35 -1
  48. package/cli/update-commit.mjs +313 -11
  49. package/cli/workspace.mjs +37 -12
  50. package/package.json +6 -4
  51. package/skills/sdlc/config.yaml +4 -4
  52. package/skills/sdlc/module-help.csv +1 -0
  53. package/skills/yad-change/SKILL.md +3 -2
  54. package/skills/yad-checks/SKILL.md +29 -9
  55. package/skills/yad-checks/references/check-gates.md +9 -4
  56. package/skills/yad-checks/templates/checks/package-manager.sh +1 -1
  57. package/skills/yad-checks/templates/github/yad-checks.yml +1 -1
  58. package/skills/yad-checks/templates/gitlab/.gitlab-ci.yml +1 -1
  59. package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml +1 -1
  60. package/skills/yad-checks/templates/gitlab/yad-product-checks.gitlab-ci.yml +1 -1
  61. package/skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml +1 -1
  62. package/skills/yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml +1 -1
  63. package/skills/yad-checks/templates/hooks/agent-guard.mjs +116 -0
  64. package/skills/yad-commit/SKILL.md +4 -3
  65. package/skills/yad-connect-design/SKILL.md +7 -4
  66. package/skills/yad-connect-design/references/design-context.md +23 -0
  67. package/skills/yad-connect-design/references/design-registry.md +3 -3
  68. package/skills/yad-connect-repos/SKILL.md +13 -3
  69. package/skills/yad-connect-repos/references/code-context.md +2 -1
  70. package/skills/yad-connect-repos/references/repos-registry.md +2 -1
  71. package/skills/yad-docs-overview/references/pipeline-model.md +2 -2
  72. package/skills/yad-engineer-review/SKILL.md +25 -7
  73. package/skills/yad-engineer-review/references/ship-and-record.md +7 -4
  74. package/skills/yad-epic/SKILL.md +2 -1
  75. package/skills/yad-epic/references/state-schema.md +7 -1
  76. package/skills/yad-guide/SKILL.md +192 -0
  77. package/skills/yad-implement/SKILL.md +14 -0
  78. package/skills/yad-open-pr/SKILL.md +5 -2
  79. package/skills/yad-pair-review/SKILL.md +19 -5
  80. package/skills/yad-pr-template/templates/github/pull_request_template.md +1 -0
  81. package/skills/yad-pr-template/templates/gitlab/merge_request_templates/Default.md +1 -0
  82. package/skills/yad-product-bridge/SKILL.md +32 -13
  83. package/skills/yad-product-bridge/references/bridge.md +6 -3
  84. package/skills/yad-product-bridge/templates/github/yad-gate-sync.yml +2 -2
  85. package/skills/yad-product-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml +1 -1
  86. package/skills/yad-report/SKILL.md +15 -0
  87. package/skills/yad-review-companion/SKILL.md +9 -4
  88. package/skills/yad-review-gate/SKILL.md +13 -9
  89. package/skills/yad-review-gate/references/gating.md +1 -1
  90. package/skills/yad-run/SKILL.md +10 -6
  91. package/skills/yad-run/references/run-loop.md +2 -1
  92. package/skills/yad-spec/SKILL.md +21 -0
  93. package/skills/yad-stories/SKILL.md +22 -0
  94. package/skills/yad-stories/references/story-schema.md +1 -0
  95. package/skills/yad-sync-repos/SKILL.md +2 -1
  96. package/skills/yad-ui/SKILL.md +7 -2
package/bin/yad.mjs CHANGED
@@ -3,8 +3,9 @@
3
3
  import fs from 'node:fs';
4
4
  import path from 'node:path';
5
5
  import { VERSION } from '../cli/manifest.mjs';
6
- import { c, log, warn, closePrompts, askYesNo, refuse, beginJSON, inJSON, emitJSON, jsonEmitted, jsonFailure, stripAnsi, isPlainObject, ENVELOPE_KEYS } from '../cli/lib.mjs';
7
- import { runLedgerGuardHook, runStagedLedgerGuard } from '../cli/hook.mjs';
6
+ import { c, log, warn, closePrompts, askYesNo, refuse, beginJSON, inJSON, emitJSON, jsonEmitted, jsonFailure, stripAnsi, isPlainObject, forTerminal, nodeSupport, nodeEndOfLife, ENVELOPE_KEYS } from '../cli/lib.mjs';
7
+ import { runLedgerGuardHook, runStagedLedgerGuard, runAgentGuardHook } from '../cli/hook.mjs';
8
+ import { VALUE_FLAGS, LIST_FLAGS } from '../cli/argv-flags.mjs';
8
9
 
9
10
  const helpText = (profiles) => `${c.bold('yad')} — setup, review-gate & build helpers for the SDLC Workflow module ${c.dim('v' + VERSION)}
10
11
 
@@ -22,13 +23,22 @@ ${c.bold('Start a workspace')} ${c.dim('(the folder holding product/ and the cod
22
23
  every repo it registers; a failed repo clone is reported, never fatal. Then
23
24
  only per-machine steps: git-ignored skill copies + the git pre-commit hook.
24
25
  Last, \`yad member add\` (below): your member file, on a branch with its own
25
- PR/MR — the only shared change join makes. A problem there never fails join
26
+ PR/MR — the only shared change join makes. A problem there never fails join.
27
+ --ide-targets <a,b> picks the AI tools; under --json it is required (asked
28
+ before the clone), and a missing platform login comes back as your step (E159)
26
29
 
27
30
  ${c.bold('Setup & maintenance')}
28
31
  yad setup Guided first-run setup (profile interview, install, connect & wire repos,
29
32
  then the tools this project uses that are missing — offered, never installed)
30
33
  profile flags: --solo | --team <n>, --greenfield | --brownfield,
31
- --monorepo | --separate, --tools (configure design/testing/learning now)
34
+ --monorepo | --separate, --tools | --no-tools (configure design/testing/learning now)
35
+ every other answer: --ide-targets <a,b>, --platform <github|gitlab|none>,
36
+ --default-branch <name>, --design|--testing|--learning <tool|none>
37
+ (--design-url, --testing-url), --reconfigure | --no-reconfigure,
38
+ --git-init | --no-git-init, --connect <all|none|names>,
39
+ --add-repo <name>=<path>[,<platform>[,<branch>]] (repeat it),
40
+ --coderabbit <all|none|names>. Under --json a missing answer is refused before
41
+ anything is written, with the questions to ask (E159)
32
42
  yad check Report what is missing / drifted / modified / stale / legacy (read-only)
33
43
  yad check --fix Reconcile: fill what is missing, update what changed
34
44
  yad update Apply drift only (alias for: check --fix --scope=changed);
@@ -43,8 +53,23 @@ ${c.bold('Setup & maintenance')}
43
53
  commit; no PR — the push-on-main yad-update-guard runs verified-commits
44
54
  + commit-message). Announce the team & pause merges first. Also works as
45
55
  'yad check --fix --push'; --allow-branch permits a non-default branch
56
+ yad update --open-pr Instead of --push: commit each repo's changes on its own branch
57
+ (chore/yad-update-v<version>), push it, and open a PR/MR into the
58
+ default branch, so the checks run and a person merges it. Works on a
59
+ protected branch. Each repo must be on its default branch; it is left
60
+ there. Also 'yad check --fix --open-pr'
46
61
  yad doctor [--json] Environment + state health: tools/auth, config files,
47
62
  repo paths, epic ledgers (exit 1 on any failure)
63
+ yad signing check [--json]
64
+ Will your commits be signed and marked Verified? Reads this folder's git
65
+ config, the key it names, and your account on the Product's platform (the
66
+ key listed for signing, a verified email). Read-only; exit 1 on a gap (E160)
67
+ yad ci check [--repo <name> | --all] [--json] [--dir <Product>]
68
+ Will yad's checks hold a merge? For the Product and each registered repo
69
+ (from inside one repo: that repo; --repo picks one code repo, --all every
70
+ one — not both): yad's CI files, the default branch's protection, the
71
+ checks required before a merge, force pushes, deletion. Read-only; each
72
+ gap names the settings page or the yad command; exit 1 on a gap (E160)
48
73
  yad migrate [--apply] [--keep product|hub] [--json] Move this project's state files onto the shape
49
74
  this yadflow expects. Prints what WOULD change and writes
50
75
  nothing until --apply, which copies each file it rewrites to
@@ -57,6 +82,10 @@ ${c.bold('Setup & maintenance')}
57
82
  yad report [-m <text>] File a bug in the yadflow repo with auto-scrubbed diagnostics
58
83
  (no paths/hosts/repo names/logins/flag values). Also offered
59
84
  automatically after an unexpected failure. YAD_NO_REPORT=1 disables.
85
+ --kind enhancement files an idea instead of a bug. --json previews
86
+ (never posts) and gives a \`confirm\` value; --post --confirm <value>
87
+ then posts that exact text with no prompt — for an AI agent, after
88
+ the person said yes to the preview.
60
89
  yad hook ledger-guard ${c.dim('harness-invoked, not typed')} — refuse an agent's edit to the
61
90
  CI-owned gate ledger in verified mode and name the command that owns
62
91
  the transition. Reads a tool-call payload on stdin (or --path <p>);
@@ -67,7 +96,15 @@ ${c.bold('Setup & maintenance')}
67
96
  setup / check --fix. With --staged it judges the files a commit is
68
97
  about to record instead — the git pre-commit hook check --fix
69
98
  installs in this clone refuses a person's hand commit to the ledger.
70
- YAD_HOOK_DISABLE=1 skips.
99
+ yad hook agent-guard ${c.dim('harness-invoked, not typed')} — before an agent's shell command:
100
+ refuse a yad command only the person runs (gate approve, comment,
101
+ advance, reopen; commit --manual), a PR/MR approval or merge (gh,
102
+ glab, their api), skipping the git hooks (--no-verify or -n,
103
+ YAD_HOOK_DISABLE, core.hooksPath), or a force push, and say
104
+ what to do instead. Reads the shell payload on stdin; answers in the
105
+ protocol the payload names (Cursor: JSON; Claude Code: exit 2).
106
+ A speed bump, not proof. Wired on every Product by setup / check --fix.
107
+ A person's YAD_HOOK_DISABLE=1 skips it.
71
108
 
72
109
  ${c.bold('Parallel agents')} ${c.dim('(one git worktree per epic — #115)')}
73
110
  yad worktree add <epic> [--repo <name>|--all] [--dry-run]
@@ -85,7 +122,8 @@ ${c.bold('Parallel agents')} ${c.dim('(one git worktree per epic — #115)')}
85
122
 
86
123
  ${c.bold('Team members')} ${c.dim('(identity only — no roles, no reviewers, no allowlist)')}
87
124
  yad member add [--no-push] Prove who you are and write .sdlc/members/<platform>-<login>.json:
88
- your account on the Product's platform (logs you in if needed),
125
+ your account on the Product's platform (logs you in if needed;
126
+ under --json it never does: the login is the person's step),
89
127
  your other GitHub/GitLab accounts and git emails that the platform
90
128
  says are VERIFIED (stored hashed). One commit per email on
91
129
  yad/member/<login>, pushed, with a PR/MR. Never your checkout
@@ -151,6 +189,12 @@ ${c.bold('Where am I / what next')}
151
189
  yad next --all Every active epic's next action at once
152
190
  yad next [<epic>] --json The same answer as a machine-readable action object (for
153
191
  agents/CI) — always every epic, so --all is implied
192
+ yad guide [<epic>] [--json] The brief an AI agent reads before each step (E157): what the
193
+ step is for, mandatory or skippable, who does it, the skills
194
+ that fit, what the agent runs, and what only the person can do
195
+ (with the exact steps and the command that confirms it). With
196
+ no Product yet, the command to start one and the questions it
197
+ asks, each with its flag (E159). Read-only
154
198
  yad status [--brief] [--no-fetch] [--json]
155
199
  Where the work stands in ~20 lines, for after a context reset:
156
200
  this checkout's task and its Build step, each open epic and its
@@ -275,6 +319,9 @@ ${c.bold('Build helpers')}
275
319
  Commit by convention (trailers, atomic guard); --body adds a
276
320
  body above the trailers; --manual is
277
321
  the door past the Product's ledger hook, reason recorded
322
+ yad story frames <story> [--json] Show the design frames a story records (its design-frames
323
+ list), with each frame's name, platform and link from the
324
+ epic's design-links.json; warns on an ID it cannot find
278
325
  yad build start <story> --repo <r> ${c.dim('(on the Product)')} Begin a story's Build lane in one repo
279
326
  yad build step <story> --repo <r> <step> in_progress|in_review|done|blocked [--reason <text>] [--run <uid>] [--via auto|human] [--task <T>]
280
327
  Move the lane's current step; done records how it closed.
@@ -377,6 +424,10 @@ ${c.bold('Build helpers')}
377
424
  yad repo refresh [name] [--push] Re-pack a stale repo (a human decision). --push commits the
378
425
  refreshed code-maps + registry as a chore(product): sync code-context … [skip ci]
379
426
  audit commit and pushes it to the Product default branch (--allow-branch to override)
427
+ yad repo preview <name> [<pattern>] [--clear]
428
+ Show, set or clear a repo's preview address pattern (#359), e.g.
429
+ 'https://pr-{pr}.myapp.dev' ({pr} {branch} {repo}). Review steps
430
+ check the live page there; with none, they say "locally only"
380
431
  yad risk-map check [repo] [--json] Warn where a code repo's .sdlc/risk-map (a risk level per
381
432
  directory, no names) has gone stale — advisory, never blocks
382
433
  yad risk-map draft [repo] Add an 'unset' line for every directory the map does not cover
@@ -442,10 +493,9 @@ ${c.bold('Environment')}
442
493
  YAD_NO_REPORT=1 Never offer to file a bug report after a failure
443
494
  YAD_PLATFORM_LOGIN=0 Name a record's author by git user.name; never ask gh/glab who is logged in`;
444
495
 
496
+ const REPORT_USAGE = 'usage: yad report [-m <text>] [--kind bug|enhancement] [--json] | yad report -m <text> [--kind …] --post --confirm <value>';
445
497
  const STANDUP_USAGE = 'usage: yad standup [--since <YYYY-MM-DD>|<N>h|<N>d] [--tz <zone>] [--member <login>|--me] [--format md|html] [--out <file>] [--json]';
446
498
 
447
- 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', '--role', '--fallback', '--detect', '--install', '--source', '--tz', '--verdict', '--ran-by', '--note', '--uid', '--run', '--via']);
448
- const LIST_FLAGS = new Set(['--signal', '--approver']);
449
499
 
450
500
  function parseArgs(argv) {
451
501
  const o = { _: [], dir: process.cwd(), fix: false, force: false, scope: 'all' };
@@ -461,7 +511,10 @@ function parseArgs(argv) {
461
511
  else if (a === '--no-fetch') o.noFetch = true;
462
512
  else if (a === '--no-build') o.noBuild = true;
463
513
  else if (a === '--push') o.push = true;
514
+ else if (a === '--open-pr') o.openPr = true;
515
+ else if (a === '--post') o.post = true;
464
516
  else if (a === '--allow-branch') o.allowBranch = true;
517
+ else if (a === '--clear') o.clear = true;
465
518
  else if (a === '--overwrite-local') o.overwriteLocal = true;
466
519
  else if (a === '--merged') o.merged = true;
467
520
  else if (a === '--ship') o.ship = true;
@@ -489,6 +542,12 @@ function parseArgs(argv) {
489
542
  else if (a === '--monorepo') o.monorepo = true;
490
543
  else if (a === '--separate') o.separate = true;
491
544
  else if (a === '--tools') o.tools = true;
545
+ // E159: the yes/no setup answers, both ways, so an agent can pass what the person said.
546
+ else if (a === '--no-tools') o.noTools = true;
547
+ else if (a === '--reconfigure') o.reconfigure = true;
548
+ else if (a === '--no-reconfigure') o.reconfigure = false;
549
+ else if (a === '--git-init') o.gitInit = true;
550
+ else if (a === '--no-git-init') o.gitInit = false;
492
551
  else if (a === '--refresh') o.refresh = true;
493
552
  else if (a === '--repos') o.repos = true;
494
553
  else if (a === '--wire') o.wire = true;
@@ -533,6 +592,16 @@ function parseArgs(argv) {
533
592
  return o;
534
593
  }
535
594
 
595
+ // E159: the setup answers beyond the profile flags, as `runSetup` reads them.
596
+ const setupAnswers = (o) => ({
597
+ noTools: o.noTools, reconfigure: o.reconfigure, gitInit: o.gitInit,
598
+ platform: o.platform === undefined ? undefined : String(o.platform).toLowerCase(),
599
+ defaultBranch: o['default-branch'], designUrl: o['design-url'], testingUrl: o['testing-url'],
600
+ // The tool names are read as setup reads a typed answer: in lower case.
601
+ ...Object.fromEntries(['design', 'testing', 'learning'].map((k) => [k, o[k] === undefined ? undefined : String(o[k]).toLowerCase()])),
602
+ connect: o.connect, addRepo: o['add-repo'], coderabbit: o.coderabbit,
603
+ });
604
+
536
605
  // The command `main` is running, for the error handler (set once the arguments are read).
537
606
  let runningCmd = null;
538
607
 
@@ -548,13 +617,16 @@ const ACTIONS = {
548
617
  review: { known: ['trailer', 'context', 'chat', 'cards', 'walkthrough', 'nudge', 'reconcile'] },
549
618
  tidy: { known: ['up'] },
550
619
  history: { known: ['list', 'show', 'search'], default: 'list' },
551
- repo: { known: ['list', 'refresh', 'sync', 'clone'], default: 'list' },
620
+ repo: { known: ['list', 'refresh', 'sync', 'clone', 'preview'], default: 'list' },
552
621
  'risk-map': { known: ['check', 'draft'], default: 'check' },
553
622
  codeowners: { known: ['check'], default: 'check' },
623
+ story: { known: ['frames'] },
554
624
  docs: { known: ['list', 'build', 'deploy', 'sync'], default: 'list' },
555
625
  reconcile: { known: ['check', 'refresh', 'wire'] },
556
- hook: { known: ['ledger-guard'] },
626
+ hook: { known: ['ledger-guard', 'agent-guard'] },
557
627
  toolbox: { known: ['list', 'check', 'add', 'remove'], default: 'list' },
628
+ signing: { known: ['check'], default: 'check' },
629
+ ci: { known: ['check'], default: 'check' },
558
630
  member: { known: ['add', 'list', 'remove'], default: 'list' },
559
631
  worktree: { known: ['add', 'list', 'remove'], default: 'list' },
560
632
  run: { known: ['checks'] },
@@ -567,10 +639,11 @@ const PRODUCT_CMDS = new Set([
567
639
  'check', 'update', 'doctor', 'migrate', 'usage', 'sync-status', 'epic', 'foundation', 'skill', 'next',
568
640
  'skip', 'unskip', 'defer', 'undefer', 'dial', 'mode', 'kill', 'unkill', 'unblock', 'gate', 'checkpoint',
569
641
  'capture', 'claims', 'assign', 'unassign', 'owners', 'fold', 'tidy', 'index', 'history', 'repo',
570
- 'risk-map', 'codeowners', 'docs', 'thread', 'reconcile', 'member', 'standup', 'build', 'worktree',
642
+ 'risk-map', 'codeowners', 'docs', 'thread', 'reconcile', 'member', 'standup', 'build', 'worktree', 'ci',
643
+ 'story',
571
644
  ]);
572
645
  // `status` reads the Product but must keep the folder it ran in: "here" is that checkout's task branch (#349).
573
- const REPO_CMDS = new Set(['commit', 'open-pr', 'ship', 'review', 'run', 'status']);
646
+ const REPO_CMDS = new Set(['commit', 'open-pr', 'ship', 'review', 'run', 'status', 'guide']);
574
647
  // The Product commands that WRITE its files without first checking it is one. Run from a code repo they
575
648
  // wrote an epic, a dial or the module into it; they refuse instead (E80). The rest either only read, or
576
649
  // already refuse a folder that is not a Product.
@@ -640,7 +713,9 @@ async function main() {
640
713
  // Its stdout is already a protocol (Claude Code reads the exit code, Cursor a permission object),
641
714
  // so it takes no --json (E1).
642
715
  if (inJSON()) return refuse('yad hook takes no --json — its output is the protocol the agent reads', 'run it without --json');
643
- if (action !== 'ledger-guard') return refuse(`unknown hook: ${action ?? '(none)'} (ledger-guard)`);
716
+ // E158: the agent guard, before an agent's shell command.
717
+ if (action === 'agent-guard') { runAgentGuardHook({ format: o.format ?? null }); return; }
718
+ if (action !== 'ledger-guard') return refuse(`unknown hook: ${action ?? '(none)'} (ledger-guard, agent-guard)`);
644
719
  // `--staged` is the git pre-commit half (E48): the files come from the index, never from stdin.
645
720
  if (o.staged) { runStagedLedgerGuard(); return; }
646
721
  runLedgerGuardHook({ paths: o.path ? [o.path] : [], format: o.format });
@@ -679,7 +754,7 @@ async function main() {
679
754
  // The workspace folder itself, or a repo the Product does not register: no Product here, but the
680
755
  // person is one `cd` away from it — say so, rather than let "run yad setup" make a second one.
681
756
  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)}`);
682
- else if (cmd === 'status') o.productElsewhere = shown(found.elsewhere);
757
+ else if (cmd === 'status' || cmd === 'guide') o.productElsewhere = shown(found.elsewhere);
683
758
  } else if (found?.root && REPO_CMDS.has(cmd)) o.product = found.root;
684
759
  else if (found?.root && !dirGiven && found.via !== 'here') {
685
760
  o.dir = found.root;
@@ -691,6 +766,11 @@ async function main() {
691
766
  const hit = commands.registryEntryFor(found.root, dirGiven ? o.dir : shellCwd());
692
767
  if (typeof hit?.meta?.name === 'string') o._[2] = hit.meta.name;
693
768
  }
769
+ // `yad ci check` the same way: that repo, unless --repo or --all says otherwise.
770
+ if (cmd === 'ci' && o.repo === undefined && !o.all) {
771
+ const hit = commands.registryEntryFor(found.root, dirGiven ? o.dir : shellCwd());
772
+ if (typeof hit?.meta?.name === 'string') o.repo = hit.meta.name;
773
+ }
694
774
  }
695
775
  }
696
776
  // A command that WRITES the Product never writes into a folder that is not one (a code repo, say).
@@ -705,6 +785,11 @@ async function main() {
705
785
  // shape-8.md). Not on `hook` — its stderr is the channel a block reason reaches a model on — and not
706
786
  // where the command reports the same thing itself (doctor, migrate) or runs before a project exists.
707
787
  if (!['hook', 'doctor', 'migrate', 'setup', 'report', 'detect', 'toolbox', 'new', 'init', 'join'].includes(cmd)) commands.warnIfProjectAhead(o.dir || process.cwd());
788
+ // E161: an end-of-life Node, once per run, on stderr (so --json stays clean). `hook` has returned above
789
+ // (its stderr is the channel a block reason reaches a model on); `doctor` says it in its own node row.
790
+ // YAD_TEST_NODE_VERSION stands in for the running version in tests only.
791
+ const nodeNow = process.env.YAD_TEST_NODE_VERSION || process.versions.node;
792
+ if (!['hook', 'doctor'].includes(cmd) && nodeSupport(nodeNow) === 'end-of-life') process.stderr.write(`${c.yellow(`! ${nodeEndOfLife(nodeNow)}`)}\n`);
708
793
  // E122: the Product's settings (or an epic's PR ledger) under two names that say different things.
709
794
  // Every command refuses rather than pick one — whichever it picked, somebody's edit would be silently
710
795
  // ignored. Not `doctor` (it reports the drift), `migrate` (it ends it) or `report` (it files a bug
@@ -729,6 +814,7 @@ async function main() {
729
814
  today, force: o.force,
730
815
  solo: o.solo, team: o.team, greenfield: o.greenfield, brownfield: o.brownfield,
731
816
  monorepo: o.monorepo, separate: o.separate, tools: o.tools,
817
+ ...setupAnswers(o),
732
818
  // The agent directories to install into, as a pre-answer for CI/scripts exactly like `--solo`
733
819
  // above (E11). Until this flag existed, `ideTargets` was reachable only programmatically: a
734
820
  // non-interactive run took `ask`'s default and had NO way to choose. That was survivable while
@@ -749,20 +835,25 @@ async function main() {
749
835
  today, force: o.force,
750
836
  solo: o.solo, team: o.team, greenfield: o.greenfield, brownfield: o.brownfield,
751
837
  monorepo: o.monorepo, separate: o.separate, tools: o.tools,
838
+ ...setupAnswers(o),
752
839
  ideTargets: o['ide-targets'] === undefined ? undefined : String(o['ide-targets']).split(',').map((t) => t.trim()).filter(Boolean),
753
840
  };
754
841
  if (cmd === 'new') result = await commands.runNew(o.dir, o._[1], setupFlags);
755
842
  else if (cmd === 'init') result = await commands.runInit(o.dir, { ...setupFlags, path: o.path });
756
- else result = await commands.runJoin(o.dir, o._[1], o._[2], { ideTargets: setupFlags.ideTargets });
843
+ else result = await commands.runJoin(o.dir, o._[1], o._[2], { ideTargets: setupFlags.ideTargets, noPush: !!o.noPush });
757
844
  break;
758
845
  }
759
846
  case 'check':
760
847
  if (noProduct()) break;
761
- 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, toolbox: toolboxAt });
848
+ if (o.push && o.openPr) { refuse('--push and --open-pr publish the update two different ways — pick one', 'use --open-pr for a branch and a PR/MR per repo, or --push to push straight to each default branch'); break; }
849
+ if (o.openPr && o.allowBranch) { refuse('--allow-branch does not apply to --open-pr: the update branch is cut from each repo\'s default branch', 'switch each repo to its default branch, then run it again'); break; }
850
+ result = await commands.reconcile(o.dir, { fix: o.fix, scope: o.scope, force: o.force, push: o.push, openPr: o.openPr, allowBranch: o.allowBranch, overwriteLocal: o.overwriteLocal, today, toolbox: toolboxAt });
762
851
  break;
763
852
  case 'update':
764
853
  if (noProduct()) break;
765
- result = await commands.reconcile(o.dir, { fix: true, scope: 'changed', force: o.force, push: o.push, allowBranch: o.allowBranch, overwriteLocal: o.overwriteLocal, today, toolbox: toolboxAt });
854
+ if (o.push && o.openPr) { refuse('--push and --open-pr publish the update two different ways — pick one', 'use --open-pr for a branch and a PR/MR per repo, or --push to push straight to each default branch'); break; }
855
+ if (o.openPr && o.allowBranch) { refuse('--allow-branch does not apply to --open-pr: the update branch is cut from each repo\'s default branch', 'switch each repo to its default branch, then run it again'); break; }
856
+ result = await commands.reconcile(o.dir, { fix: true, scope: 'changed', force: o.force, push: o.push, openPr: o.openPr, allowBranch: o.allowBranch, overwriteLocal: o.overwriteLocal, today, toolbox: toolboxAt });
766
857
  break;
767
858
  case 'doctor':
768
859
  result = await commands.runDoctor(o.dir, { json: o.json });
@@ -770,6 +861,33 @@ async function main() {
770
861
  case 'migrate':
771
862
  result = await commands.runMigrate(o.dir, { apply: o.apply, json: o.json, keep: o.keep ?? null });
772
863
  break;
864
+ case 'signing': {
865
+ // E160a. Read-only: the git config in this folder, the key it names, and the account on the Product's
866
+ // platform (found as every Product command finds it, from this folder or a repo the Product registers).
867
+ const [, action = 'check', extra] = o._;
868
+ if (action !== 'check' || extra) { refuse(`unknown signing action: ${[action, extra].filter(Boolean).join(' ')}`, 'usage: yad signing check [--json] [--dir <folder>]'); break; }
869
+ const found = commands.findProduct(dirGiven ? o.dir : shellCwd());
870
+ // Why no Product was found is said, as every Product command says it: the account is then not checked.
871
+ if (found?.problem) warn(`${found.problem} — your account is not checked`);
872
+ else if (found?.elsewhere) warn(`this folder is not in a repo the Product registers (the Product is ${path.relative(process.cwd(), found.elsewhere) || '.'}) — your account is not checked; run it from there, or pass --dir`);
873
+ result = commands.runSigningCheck(dirGiven ? o.dir : shellCwd(), { root: found?.problem || found?.elsewhere ? null : found?.root ?? null, json: o.json });
874
+ break;
875
+ }
876
+ case 'ci': {
877
+ // E160b. Read-only: yad's CI files on disk, and the platform's rules on each default branch.
878
+ const [, action = 'check', extra] = o._;
879
+ const usage = 'usage: yad ci check [--repo <name> | --all] [--json] [--dir <folder>]';
880
+ if (action !== 'check' || extra) { refuse(`unknown ci action: ${[action, extra].filter(Boolean).join(' ')}`, usage); break; }
881
+ if (o.repo !== undefined && o.all) { refuse('--repo and --all name different repos: pass one of them', usage); break; }
882
+ if (!commands.hasProduct(o.dir)) { refuse(`no Product here (${o.dir}) — yad ci check reads the repos a Product registers`, 'run it from the Product, from inside a repo it registers, or pass --dir <the Product> (with --repo <name> for one repo)'); break; }
883
+ result = commands.runCiCheck(o.dir, { repo: o.all ? null : o.repo ?? null, json: o.json });
884
+ if (result?.unknownRepo !== undefined) {
885
+ const names = result.names.map(forTerminal);
886
+ refuse(`no repo named ${forTerminal(result.unknownRepo)} is registered`, names.length ? `the registered repos: ${names.join(', ')} (or --all)` : 'this Product registers no code repos');
887
+ result = undefined;
888
+ }
889
+ break;
890
+ }
773
891
  case 'toolbox': {
774
892
  // E84 + E86. Finding a tool reads the folder yad runs in (a code repo's own skills count); the
775
893
  // team's choices are the Product's `.sdlc/toolbox.json`, found the way every Product command finds
@@ -820,9 +938,16 @@ async function main() {
820
938
  result = commands.runDetect(o.dir || process.cwd(), { json: o.json });
821
939
  break;
822
940
  }
823
- case 'report':
824
- result = await commands.runReport(o.dir, { message: o.message });
941
+ case 'report': {
942
+ // E158: an agent previews with --json, shows the person, and on their yes posts with --post --confirm.
943
+ const kind = o.kind ?? 'bug';
944
+ if (!commands.REPORT_KINDS.includes(kind)) { refuse(`yad report --kind takes ${commands.REPORT_KINDS.join(' or ')} (got: ${kind})`, REPORT_USAGE); break; }
945
+ if (o.post && !o.confirm) { refuse('yad report --post needs --confirm <value>: the `confirm` its --json preview gave, after the person said yes to that text', REPORT_USAGE); break; }
946
+ if (o.confirm && !o.post) { refuse('yad report --confirm is for --post', REPORT_USAGE); break; }
947
+ result = await commands.runReport(o.dir, { message: o.message, kind, post: !!o.post, confirm: o.confirm ?? null });
948
+ if (result?.refused) process.exitCode = 1;
825
949
  break;
950
+ }
826
951
  case 'usage':
827
952
  result = commands.runUsage(o.dir, {
828
953
  out: o.out, since: o.since, until: o.until, all: o.all, member: o.member,
@@ -883,6 +1008,17 @@ async function main() {
883
1008
  result = await commands.runStatus(root, { cwd: o.dir, json: o.json, fetch: !o.noFetch });
884
1009
  break;
885
1010
  }
1011
+ case 'guide': {
1012
+ // Like `status`, it keeps the folder it ran in ("here" is that checkout). Unlike `status`, no Product
1013
+ // is an answer, not a refusal: it says how to start one (the first start, E157).
1014
+ const [, epic] = o._;
1015
+ if (o._[2] !== undefined) { refuse(`yad guide takes one epic id, not ${o._[2]}`, 'usage: yad guide [<epic>] [--json]'); break; }
1016
+ if (epic !== undefined && !commands.isValidEpicId(epic)) { refuse(`invalid epic id: ${epic} (expected EP-<slug>, [a-z0-9-] only)`, 'usage: yad guide [<epic>] [--json]'); break; }
1017
+ const root = o.product || (commands.hasProduct(o.dir) ? o.dir : null);
1018
+ // A Product one `cd` away is said in the answer too, so an agent never starts a second one (E80).
1019
+ result = await commands.runGuide(root, { epic: epic ?? null, cwd: o.dir, json: o.json, productElsewhere: root ? null : o.productElsewhere ?? null });
1020
+ break;
1021
+ }
886
1022
  case 'next': {
887
1023
  const [, epic] = o._;
888
1024
  // `--check` with no step is a malformed guard call — fail loudly rather than silently print.
@@ -1027,7 +1163,7 @@ async function main() {
1027
1163
  case 'ship':
1028
1164
  // The ledger override is its own act (E49): recorded in its own commit, never folded into a
1029
1165
  // commit-and-open-PR run. Refused, never ignored.
1030
- 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; }
1166
+ if (o.manual || o.reason !== undefined) { refuse('yad ship takes no --manual/--reason: the person commits with `yad commit --manual --reason "<why>" …` (an AI agent hands it to them, `!` in front in Claude Code), then `yad open-pr`'); break; }
1031
1167
  // Opening on the standing approval follows the checks, not the commit (#356): its own command.
1032
1168
  if (o.via !== undefined) { refuse('yad ship takes no --via: commit, run the checks, then `yad open-pr --via auto`'); break; }
1033
1169
  // A commit body (#357: the Decisions: paragraph) is written by `yad commit`; ship never drops it unseen.
@@ -1165,7 +1301,11 @@ async function main() {
1165
1301
  }
1166
1302
  case 'repo': {
1167
1303
  const [, action, name] = o._;
1168
- result = await commands.runRepo(o.dir, { action: action || 'list', name, today, push: o.push, allowBranch: o.allowBranch });
1304
+ // `yad repo preview <name> [<pattern>]` (#359): the one action with a third word.
1305
+ const pattern = action === 'preview' ? o._[3] : undefined;
1306
+ if (action === 'preview' && o._.length > 4) { refuse(`unexpected argument(s): ${o._.slice(4).join(' ')}`, 'use: yad repo preview <name> [<pattern>] [--clear] — quote the pattern'); break; }
1307
+ result = await commands.runRepo(o.dir, { action: action || 'list', name, pattern, clear: !!o.clear, today,
1308
+ push: o.push, allowBranch: o.allowBranch });
1169
1309
  break;
1170
1310
  }
1171
1311
  case 'risk-map': {
@@ -1179,6 +1319,12 @@ async function main() {
1179
1319
  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=')) });
1180
1320
  break;
1181
1321
  }
1322
+ case 'story': {
1323
+ if (o._.length > 3) { refuse(`unexpected argument(s): ${o._.slice(3).join(' ')}`, 'use: yad story frames <story-id> — one story at a time'); break; }
1324
+ const [, action, story] = o._;
1325
+ result = await commands.runStory(o.dir, { action, story, json: o.json });
1326
+ break;
1327
+ }
1182
1328
  case 'roster':
1183
1329
  // Removed in E62. Kept as a word for one major so a script or a habit gets told where it went
1184
1330
  // instead of "unknown command".
@@ -1248,7 +1394,8 @@ main()
1248
1394
  if (inJSON() && !jsonEmitted()) {
1249
1395
  if (err?.parsedCmd !== undefined && runningCmd === null) beginJSON(commandName(err.parsedWords ?? []));
1250
1396
  const hint = err?.hint || (/expects a value$/.test(String(err?.message)) ? '`yad --help` lists the flags of each command' : null);
1251
- refuse(String(err?.message || err), hint, { code: err?.code && /^YAD-/.test(err.code) ? err.code : null });
1397
+ // E159: a setup refused for unanswered questions lists them, so an agent can ask the person.
1398
+ refuse(String(err?.message || err), hint, { code: err?.code && /^YAD-/.test(err.code) ? err.code : null, ...(Array.isArray(err?.questions) ? { questions: err.questions } : {}) });
1252
1399
  return;
1253
1400
  }
1254
1401
  const code = err?.code && /^YAD-/.test(err.code) ? ` [${err.code}]` : '';