yadflow 4.6.0 → 4.8.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 (136) hide show
  1. package/CHANGELOG.md +259 -0
  2. package/README.md +46 -4
  3. package/bin/commands.mjs +9 -2
  4. package/bin/yad.mjs +309 -30
  5. package/cli/agent-guard.mjs +511 -0
  6. package/cli/agent-guide.mjs +83 -0
  7. package/cli/agent-rules.mjs +381 -0
  8. package/cli/argv-flags.mjs +7 -0
  9. package/cli/artifact-status.mjs +88 -20
  10. package/cli/build.mjs +1372 -0
  11. package/cli/checkpoint.mjs +2 -2
  12. package/cli/ci-check.mjs +492 -0
  13. package/cli/commit.mjs +1 -0
  14. package/cli/dial.mjs +21 -1
  15. package/cli/docs.mjs +7 -2
  16. package/cli/doctor.mjs +176 -33
  17. package/cli/epic-state.mjs +360 -12
  18. package/cli/errors.mjs +3 -0
  19. package/cli/find-product.mjs +36 -2
  20. package/cli/fold.mjs +9 -5
  21. package/cli/gate-local.mjs +9 -1
  22. package/cli/gate.mjs +364 -22
  23. package/cli/guide.mjs +549 -0
  24. package/cli/history.mjs +22 -2
  25. package/cli/hook.mjs +35 -4
  26. package/cli/index-command.mjs +2 -2
  27. package/cli/ledger.mjs +60 -0
  28. package/cli/lib.mjs +46 -0
  29. package/cli/lifecycle/defaults/2.json +124 -0
  30. package/cli/lifecycle/lifecycle.schema.json +5 -2
  31. package/cli/lifecycle.mjs +16 -3
  32. package/cli/manifest.mjs +75 -0
  33. package/cli/marked-block.mjs +48 -0
  34. package/cli/members.mjs +19 -5
  35. package/cli/migrate.mjs +17 -19
  36. package/cli/next.mjs +35 -12
  37. package/cli/openpr.mjs +81 -5
  38. package/cli/plan.mjs +326 -22
  39. package/cli/platform.mjs +21 -0
  40. package/cli/pr-list.mjs +5 -3
  41. package/cli/product-index.mjs +6 -3
  42. package/cli/product-token.mjs +186 -0
  43. package/cli/productcommit.mjs +33 -0
  44. package/cli/protection.mjs +50 -0
  45. package/cli/recommend.mjs +3 -1
  46. package/cli/reconcile.mjs +187 -26
  47. package/cli/repo-publish.mjs +2 -2
  48. package/cli/report.mjs +62 -14
  49. package/cli/run-checks.mjs +586 -0
  50. package/cli/setup.mjs +244 -25
  51. package/cli/ship-drift.mjs +49 -18
  52. package/cli/signing.mjs +377 -0
  53. package/cli/standup.mjs +1 -1
  54. package/cli/status.mjs +282 -0
  55. package/cli/test-agents-file.mjs +993 -0
  56. package/cli/test-build.mjs +1559 -0
  57. package/cli/test-ci-check.mjs +616 -0
  58. package/cli/test-guide.mjs +1267 -0
  59. package/cli/test-node.mjs +129 -0
  60. package/cli/test-run-checks.mjs +603 -0
  61. package/cli/test-setup-agent.mjs +352 -0
  62. package/cli/test-signing.mjs +524 -0
  63. package/cli/test-worktree.mjs +520 -0
  64. package/cli/thread.mjs +4 -0
  65. package/cli/tidy.mjs +2 -2
  66. package/cli/toolbox.mjs +37 -6
  67. package/cli/update-commit.mjs +313 -11
  68. package/cli/workspace.mjs +38 -10
  69. package/cli/worktree-record.mjs +53 -0
  70. package/cli/worktree.mjs +379 -0
  71. package/package.json +6 -4
  72. package/skills/sdlc/config.yaml +5 -5
  73. package/skills/sdlc/module-help.csv +2 -1
  74. package/skills/yad-backfill/templates/checks/backfill-check.sh +9 -9
  75. package/skills/yad-change/SKILL.md +5 -1
  76. package/skills/yad-checks/SKILL.md +61 -12
  77. package/skills/yad-checks/references/check-gates.md +78 -14
  78. package/skills/yad-checks/templates/checks/build-test-lint.sh +22 -3
  79. package/skills/yad-checks/templates/checks/commit-message.sh +8 -2
  80. package/skills/yad-checks/templates/checks/contract-check.sh +61 -33
  81. package/skills/yad-checks/templates/checks/epic-open.sh +87 -14
  82. package/skills/yad-checks/templates/checks/ledger-guard.sh +3 -3
  83. package/skills/yad-checks/templates/checks/lineage-check.sh +88 -15
  84. package/skills/yad-checks/templates/checks/member-check.mjs +206 -35
  85. package/skills/yad-checks/templates/checks/package-manager.sh +42 -5
  86. package/skills/yad-checks/templates/checks/product-checkout.sh +161 -13
  87. package/skills/yad-checks/templates/checks/reconcile-debt-check.sh +94 -15
  88. package/skills/yad-checks/templates/checks/risk-map-check.sh +2 -2
  89. package/skills/yad-checks/templates/checks/spec-link.sh +63 -4
  90. package/skills/yad-checks/templates/checks/verified-commits.sh +23 -5
  91. package/skills/yad-checks/templates/github/yad-checks.yml +9 -9
  92. package/skills/yad-checks/templates/gitlab/.gitlab-ci.yml +4 -1
  93. package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml +5 -5
  94. package/skills/yad-checks/templates/gitlab/yad-product-checks.gitlab-ci.yml +16 -3
  95. package/skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml +5 -1
  96. package/skills/yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml +5 -1
  97. package/skills/yad-checks/templates/hooks/agent-guard.mjs +116 -0
  98. package/skills/yad-commit/SKILL.md +8 -5
  99. package/skills/yad-connect-repos/SKILL.md +5 -3
  100. package/skills/yad-connect-repos/references/code-context.md +2 -1
  101. package/skills/yad-connect-repos/references/repos-registry.md +2 -1
  102. package/skills/yad-docs/templates/app/package-lock.json +395 -106
  103. package/skills/yad-docs/templates/app/package.json +2 -2
  104. package/skills/yad-docs-overview/references/pipeline-model.md +2 -2
  105. package/skills/yad-engineer-review/SKILL.md +55 -25
  106. package/skills/yad-engineer-review/references/ship-and-record.md +49 -12
  107. package/skills/yad-epic/SKILL.md +2 -1
  108. package/skills/yad-epic/references/state-schema.md +76 -17
  109. package/skills/yad-guide/SKILL.md +192 -0
  110. package/skills/yad-implement/SKILL.md +75 -13
  111. package/skills/yad-implement/references/implement-conventions.md +8 -1
  112. package/skills/yad-implement/templates/.gitmessage +3 -0
  113. package/skills/yad-open-pr/SKILL.md +21 -0
  114. package/skills/yad-pair-review/SKILL.md +14 -5
  115. package/skills/yad-pr-template/SKILL.md +6 -2
  116. package/skills/yad-pr-template/templates/checks/pr-template.sh +85 -4
  117. package/skills/yad-pr-template/templates/checks/pr-title.sh +1 -1
  118. package/skills/yad-pr-template/templates/github/pull_request_template.md +1 -1
  119. package/skills/yad-pr-template/templates/gitlab/merge_request_templates/Default.md +1 -1
  120. package/skills/yad-product-bridge/SKILL.md +44 -12
  121. package/skills/yad-product-bridge/references/bridge.md +11 -5
  122. package/skills/yad-product-bridge/templates/github/yad-gate-sync.yml +2 -2
  123. package/skills/yad-product-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml +9 -4
  124. package/skills/yad-reconcile/SKILL.md +9 -3
  125. package/skills/yad-report/SKILL.md +15 -0
  126. package/skills/yad-review-companion/SKILL.md +5 -3
  127. package/skills/yad-review-gate/SKILL.md +16 -8
  128. package/skills/yad-review-gate/references/gating.md +26 -1
  129. package/skills/yad-run/SKILL.md +61 -33
  130. package/skills/yad-run/references/run-loop.md +44 -22
  131. package/skills/yad-spec/SKILL.md +137 -16
  132. package/skills/yad-spec/references/spec-handoff.md +50 -3
  133. package/skills/yad-status/SKILL.md +7 -0
  134. package/skills/yad-stories/references/story-schema.md +1 -1
  135. package/skills/yad-sync-repos/SKILL.md +2 -1
  136. package/skills/yad-ui/SKILL.md +2 -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,11 +96,34 @@ ${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.
108
+
109
+ ${c.bold('Parallel agents')} ${c.dim('(one git worktree per epic — #115)')}
110
+ yad worktree add <epic> [--repo <name>|--all] [--dry-run]
111
+ Make the epic's own worktree beside the Product (or beside a code
112
+ repo with --repo; the Product and every repo the epic names with
113
+ --all), detached at origin/<default>. A code repo's ignored
114
+ node_modules are linked, not reinstalled. Open the agent's session
115
+ in that folder, and make the step's usual branch there
116
+ yad worktree list [<epic>] [--json] The yad worktrees of the Product and every repo: branch, changes,
117
+ commits on no remote, locked, folder gone
118
+ yad worktree remove <epic> [--repo <name>|--all]
119
+ Remove them — refused, removing nothing, while one holds
120
+ uncommitted or untracked files, commits on no remote, a lock or an
121
+ operation half done, or you are inside it. No override
71
122
 
72
123
  ${c.bold('Team members')} ${c.dim('(identity only — no roles, no reviewers, no allowlist)')}
73
124
  yad member add [--no-push] Prove who you are and write .sdlc/members/<platform>-<login>.json:
74
- 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),
75
127
  your other GitHub/GitLab accounts and git emails that the platform
76
128
  says are VERIFIED (stored hashed). One commit per email on
77
129
  yad/member/<login>, pushed, with a PR/MR. Never your checkout
@@ -137,6 +189,18 @@ ${c.bold('Where am I / what next')}
137
189
  yad next --all Every active epic's next action at once
138
190
  yad next [<epic>] --json The same answer as a machine-readable action object (for
139
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
198
+ yad status [--brief] [--no-fetch] [--json]
199
+ Where the work stands in ~20 lines, for after a context reset:
200
+ this checkout's task and its Build step, each open epic and its
201
+ next action, your open PRs/MRs, and what is owed (debt, blockers,
202
+ hotfix debt, follow-up PRs). --brief is the only form today;
203
+ --no-fetch asks no platform
140
204
  yad skill list [--profile <p> | --epic <id>] [--json]
141
205
  Which skill runs which step, whether that is one route's
142
206
  choice, the project's or the engine's default, and whether
@@ -155,7 +219,7 @@ ${c.bold('Where am I / what next')}
155
219
  command (pool skill first, yadflow's skill last). Binds nothing
156
220
  yad toolbox list [--json] [--dir <folder>]
157
221
  The external tools yadflow can use — core (offered at setup),
158
- recommended pools, the design/testing/learning connectors and
222
+ recommended (skill pools, Docker MCP), the connectors and
159
223
  this project's own — whether each is found here, whether this
160
224
  project uses it, and what yadflow does without it. Installs nothing
161
225
  yad toolbox check [--json] The tools this project uses that are not ready here, each with
@@ -201,6 +265,10 @@ ${c.bold('Where am I / what next')}
201
265
  kept in .sdlc/automation.json. No --to shows it. A review gate is
202
266
  always human. Recorded only for now: nothing drives a Shape step
203
267
  on its own until the engine runs agents
268
+ yad dial open-pr [--to auto|human] [--json]
269
+ The standing approval to open a task's PR/MR once its checks
270
+ pass (\`yad open-pr --via auto\`), for the whole project. The
271
+ merge is always a person's; the kill switch holds it at human
204
272
  yad dial <epic> <story> --repo <name> <step> [--to auto|human] [--json]
205
273
  A Build lane step's dial (spec, tasks, implement, checks), in
206
274
  build-state; on auto the yad-run skill moves past it after a clean
@@ -230,6 +298,11 @@ ${c.bold('Review gate (Shape)')}
230
298
  No platform only: record who commented, and how often, this round
231
299
  yad gate advance <epic> <artifact> No platform only: pass the gate when its approvals hold
232
300
  yad gate repair <epic> [--push] Close an author step stranded behind a passed review gate
301
+ yad gate reopen <epic> <step> --reason <why> [--push] [--dry-run]
302
+ Reopen an approved Shape step before Build starts: it and every
303
+ later step go back, their approvals are revoked (kept in
304
+ state.json reopens[]), and every gate from it is required again.
305
+ --push commits it to the default branch (needed when verified)
233
306
  (YAD-STATE-005); --push commits state.json to the default branch
234
307
  yad gate review <epic> [artifact] Print the grounding bundle for the review companion
235
308
  (artifact + risk + contract + PR + code-maps) — fun, easy review
@@ -242,16 +315,53 @@ ${c.bold('Review gate (Shape)')}
242
315
  --merged advances the step + flips artifact status on the default branch
243
316
 
244
317
  ${c.bold('Build helpers')}
245
- yad commit --type <t> -m <subject> [--manual --reason <why>]
246
- Commit by convention (trailers, atomic guard); --manual is
318
+ yad commit --type <t> -m <subject> [--body <text>] [--manual --reason <why>]
319
+ Commit by convention (trailers, atomic guard); --body adds a
320
+ body above the trailers; --manual is
247
321
  the door past the Product's ledger hook, reason recorded
248
- yad open-pr [--repo <name>] [--title <text>]
322
+ yad build start <story> --repo <r> ${c.dim('(on the Product)')} Begin a story's Build lane in one repo
323
+ yad build step <story> --repo <r> <step> in_progress|in_review|done|blocked [--reason <text>] [--run <uid>] [--via auto|human] [--task <T>]
324
+ Move the lane's current step; done records how it closed.
325
+ --task <T> reopens implement/checks for the next task
326
+ yad build trust <story> --repo <r> <step> --verdict <v> [--signal k=v] [--ran-by machine|human] [--note] [--task <T>]
327
+ Record a step run's trust entry (prints its uid); --uid <uid>
328
+ --verdict <v> finalizes one already recorded
329
+ yad build ship <story> --task <T> --repo <r> --pr <n> [--follow-up]
330
+ Record a ship from the MERGED PR/MR (merge commit, checks,
331
+ approvers); not \`yad ship\`, which commits and opens the PR.
332
+ Merged with no PR/MR: --merge-commit <sha> (no --pr) — the
333
+ platform is asked which PR merged it. [--no-fetch]
334
+ No platform to read: --merge-commit <sha> [--approver <login>]…
335
+ --follow-up: a merged fix/<story>-<task>-followup-<words> PR,
336
+ added to the task's ship (its followUps)
337
+ yad build merged <story> --task <T> --repo <r> [--pr <n>] [--ship] [--follow-up] [--no-fetch]
338
+ Ask the platform whether the task's PR/MR merged (found by
339
+ its branch): shipped | merged | open | closed | none. One
340
+ check, nothing waits; --ship records the ship once merged.
341
+ --follow-up asks about the task's follow-up PRs instead
342
+ yad build sync [<epic>] [--dry-run] [--no-fetch]
343
+ Record every ship the code repos already show (what yad
344
+ reconcile check finds merged with no ship), through yad build
345
+ ship, then yad build done for each story now fully shipped;
346
+ what it cannot record is listed with the command to run
347
+ yad build done <story> [--no-fetch] Every task shipped: status shipped, review step closed
348
+ yad run checks [--title <text>] [--body <file>] [--base <ref>] [--no-build] [--no-fetch]
349
+ Run every PR/MR gate here before you push, as CI would: this
350
+ repo's own checks/ scripts against origin/<default>, with the
351
+ Product's default branch written where CI checks it out (and
352
+ removed after). Signatures are checked with git; the platform's
353
+ Verified badge is judged in CI. install-deps runs npm ci (it
354
+ replaces node_modules); --no-build skips it and build/test/lint.
355
+ Exit 1 on any FAIL, 130 when stopped with Ctrl-C
356
+ yad open-pr [--repo <name>] [--title <text>] [--via auto]
249
357
  Open a task PR/MR against the repo's DEFAULT branch (never a
250
358
  hardcoded main; --base overrides) — stage-aware on the Product: a
251
359
  review/EP-* branch opens the Shape artifact-review PR
252
360
  (delegates to gate open), any other Product branch uses the
253
361
  code-task template. --title sets the PR/MR title (default: -m,
254
- else the last commit's subject)
362
+ else the last commit's subject). --via auto: opened on the
363
+ standing approval (yad dial open-pr) once this task's checks
364
+ passed, and recorded on its lane
255
365
  yad ship --type <t> -m <subject> [--title <text>]
256
366
  Commit AND open the task PR/MR in one step (stage-aware).
257
367
  --title sets the PR/MR title (default: the commit subject)
@@ -278,7 +388,7 @@ ${c.bold('Build helpers')}
278
388
  yad unassign <epic> <step> [--force] Remove an assignment (someone else's needs --force)
279
389
  yad owners [<epic>] List every step assignment, and whether it is live
280
390
  yad fold <epic> <step> End an authoring step: commit ITS artifacts as one commit,
281
- docs(<epic>): author <step> (signed if git signs) — the drafts
391
+ docs(<epic, lowercase>): author <step> (signed if git signs) — drafts
282
392
  stay on yad/wip/…; with ledger: local the epic's ledger rides along
283
393
  yad tidy up [<epic>] [--push] Fold FINISHED Build shards (a shipped story's
284
394
  trust-log/build-log entries) back into the single folded
@@ -376,9 +486,9 @@ ${c.bold('Environment')}
376
486
  YAD_NO_REPORT=1 Never offer to file a bug report after a failure
377
487
  YAD_PLATFORM_LOGIN=0 Name a record's author by git user.name; never ask gh/glab who is logged in`;
378
488
 
489
+ const REPORT_USAGE = 'usage: yad report [-m <text>] [--kind bug|enhancement] [--json] | yad report -m <text> [--kind …] --post --confirm <value>';
379
490
  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]';
380
491
 
381
- 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']);
382
492
 
383
493
  function parseArgs(argv) {
384
494
  const o = { _: [], dir: process.cwd(), fix: false, force: false, scope: 'all' };
@@ -392,10 +502,15 @@ function parseArgs(argv) {
392
502
  else if (a === '--me') o.me = true;
393
503
  else if (a === '--no-push') o.noPush = true;
394
504
  else if (a === '--no-fetch') o.noFetch = true;
505
+ else if (a === '--no-build') o.noBuild = true;
395
506
  else if (a === '--push') o.push = true;
507
+ else if (a === '--open-pr') o.openPr = true;
508
+ else if (a === '--post') o.post = true;
396
509
  else if (a === '--allow-branch') o.allowBranch = true;
397
510
  else if (a === '--overwrite-local') o.overwriteLocal = true;
398
511
  else if (a === '--merged') o.merged = true;
512
+ else if (a === '--ship') o.ship = true;
513
+ else if (a === '--follow-up') o.followUp = true;
399
514
  else if (a === '--overview') o.overview = true;
400
515
  // `--check` is a bare boolean for `docs sync --check`, but takes a value for
401
516
  // `next <epic> --check <step>`. Only the `next` command consumes the following token as a value —
@@ -403,6 +518,7 @@ function parseArgs(argv) {
403
518
  // positional. `o._[0]` is the command, already pushed by the time `--check` is seen in normal use.
404
519
  else if (a === '--check') { const v = argv[i + 1]; o.check = (o._[0] === 'next' && v !== undefined && !v.startsWith('-')) ? argv[++i] : true; }
405
520
  else if (a === '--all') o.all = true;
521
+ else if (a === '--brief') o.brief = true;
406
522
  else if (a === '--open') o.open = true;
407
523
  else if (a === '--done') o.done = true;
408
524
  else if (a === '--undo') o.undo = true;
@@ -418,6 +534,12 @@ function parseArgs(argv) {
418
534
  else if (a === '--monorepo') o.monorepo = true;
419
535
  else if (a === '--separate') o.separate = true;
420
536
  else if (a === '--tools') o.tools = true;
537
+ // E159: the yes/no setup answers, both ways, so an agent can pass what the person said.
538
+ else if (a === '--no-tools') o.noTools = true;
539
+ else if (a === '--reconfigure') o.reconfigure = true;
540
+ else if (a === '--no-reconfigure') o.reconfigure = false;
541
+ else if (a === '--git-init') o.gitInit = true;
542
+ else if (a === '--no-git-init') o.gitInit = false;
421
543
  else if (a === '--refresh') o.refresh = true;
422
544
  else if (a === '--repos') o.repos = true;
423
545
  else if (a === '--wire') o.wire = true;
@@ -432,6 +554,13 @@ function parseArgs(argv) {
432
554
  else if (a === '-v' || a === '--version') o.version = true;
433
555
  else if (a.startsWith('--scope=')) o.scope = a.slice('--scope='.length);
434
556
  else if (a === '-m' || a === '--message') o.message = takeValue(argv, ++i, a);
557
+ // Repeatable (`yad build trust … --signal a=true --signal b=false`, `yad build ship … --approver x --approver y`).
558
+ else if (LIST_FLAGS.has(a)) (o[a.slice(2)] ||= []).push(takeValue(argv, ++i, a));
559
+ else if (a.startsWith('--') && a.includes('=') && LIST_FLAGS.has(a.slice(0, a.indexOf('=')))) {
560
+ const value = a.slice(a.indexOf('=') + 1);
561
+ if (!value) throw new Error(`${a.slice(0, a.indexOf('='))} expects a value`);
562
+ (o[a.slice(2, a.indexOf('='))] ||= []).push(value);
563
+ }
435
564
  else if (VALUE_FLAGS.has(a)) o[a.replace(/^--/, '')] = takeValue(argv, ++i, a);
436
565
  // `--flag=value` for the same flags. Without it the token matched nothing and fell through to the
437
566
  // positionals, where it was silently ignored — and for `yad hook ledger-guard --format=cursor`
@@ -455,6 +584,16 @@ function parseArgs(argv) {
455
584
  return o;
456
585
  }
457
586
 
587
+ // E159: the setup answers beyond the profile flags, as `runSetup` reads them.
588
+ const setupAnswers = (o) => ({
589
+ noTools: o.noTools, reconfigure: o.reconfigure, gitInit: o.gitInit,
590
+ platform: o.platform === undefined ? undefined : String(o.platform).toLowerCase(),
591
+ defaultBranch: o['default-branch'], designUrl: o['design-url'], testingUrl: o['testing-url'],
592
+ // The tool names are read as setup reads a typed answer: in lower case.
593
+ ...Object.fromEntries(['design', 'testing', 'learning'].map((k) => [k, o[k] === undefined ? undefined : String(o[k]).toLowerCase()])),
594
+ connect: o.connect, addRepo: o['add-repo'], coderabbit: o.coderabbit,
595
+ });
596
+
458
597
  // The command `main` is running, for the error handler (set once the arguments are read).
459
598
  let runningCmd = null;
460
599
 
@@ -466,7 +605,7 @@ const ACTIONS = {
466
605
  epic: { known: ['new'] },
467
606
  foundation: { known: ['new', 'status'] },
468
607
  skill: { known: ['list', 'bind', 'unbind', 'recommend'], default: 'list' },
469
- gate: { known: ['open', 'sync', 'comments', 'status', 'repair', 'review', 'walkthrough', 'trailer', 'ci', 'approve', 'comment', 'advance'] },
608
+ gate: { known: ['open', 'sync', 'comments', 'status', 'repair', 'reopen', 'review', 'walkthrough', 'trailer', 'ci', 'approve', 'comment', 'advance'] },
470
609
  review: { known: ['trailer', 'context', 'chat', 'cards', 'walkthrough', 'nudge', 'reconcile'] },
471
610
  tidy: { known: ['up'] },
472
611
  history: { known: ['list', 'show', 'search'], default: 'list' },
@@ -475,9 +614,14 @@ const ACTIONS = {
475
614
  codeowners: { known: ['check'], default: 'check' },
476
615
  docs: { known: ['list', 'build', 'deploy', 'sync'], default: 'list' },
477
616
  reconcile: { known: ['check', 'refresh', 'wire'] },
478
- hook: { known: ['ledger-guard'] },
617
+ hook: { known: ['ledger-guard', 'agent-guard'] },
479
618
  toolbox: { known: ['list', 'check', 'add', 'remove'], default: 'list' },
619
+ signing: { known: ['check'], default: 'check' },
620
+ ci: { known: ['check'], default: 'check' },
480
621
  member: { known: ['add', 'list', 'remove'], default: 'list' },
622
+ worktree: { known: ['add', 'list', 'remove'], default: 'list' },
623
+ run: { known: ['checks'] },
624
+ build: { known: ['start', 'step', 'trust', 'ship', 'merged', 'done', 'sync'] },
481
625
  };
482
626
  // E80 — how each command finds its folder. A PRODUCT command works on the Product; a REPO command works
483
627
  // on the code repo it runs in and reads the Product beside it. The rest take their folder as given:
@@ -486,20 +630,24 @@ const PRODUCT_CMDS = new Set([
486
630
  'check', 'update', 'doctor', 'migrate', 'usage', 'sync-status', 'epic', 'foundation', 'skill', 'next',
487
631
  'skip', 'unskip', 'defer', 'undefer', 'dial', 'mode', 'kill', 'unkill', 'unblock', 'gate', 'checkpoint',
488
632
  'capture', 'claims', 'assign', 'unassign', 'owners', 'fold', 'tidy', 'index', 'history', 'repo',
489
- 'risk-map', 'codeowners', 'docs', 'thread', 'reconcile', 'member', 'standup',
633
+ 'risk-map', 'codeowners', 'docs', 'thread', 'reconcile', 'member', 'standup', 'build', 'worktree', 'ci',
490
634
  ]);
491
- const REPO_CMDS = new Set(['commit', 'open-pr', 'ship', 'review']);
635
+ // `status` reads the Product but must keep the folder it ran in: "here" is that checkout's task branch (#349).
636
+ const REPO_CMDS = new Set(['commit', 'open-pr', 'ship', 'review', 'run', 'status', 'guide']);
492
637
  // The Product commands that WRITE its files without first checking it is one. Run from a code repo they
493
638
  // wrote an epic, a dial or the module into it; they refuse instead (E80). The rest either only read, or
494
639
  // already refuse a folder that is not a Product.
495
640
  function writesProduct(cmd, o) {
496
641
  const action = o._[1];
497
642
  if (cmd === 'update' || cmd === 'kill' || cmd === 'unkill') return true;
643
+ // `build merged` only asks the platform, unless --ship records what it found.
644
+ if (cmd === 'build') return action === 'sync' ? !o.dryRun : action !== 'merged' || !!o.ship;
498
645
  if (cmd === 'check') return !!o.fix;
499
646
  if (cmd === 'epic' || cmd === 'foundation') return action === 'new';
500
647
  if (cmd === 'skill') return action === 'bind' || action === 'unbind';
501
648
  if (cmd === 'dial') return o.to !== undefined;
502
649
  if (cmd === 'member') return o._[1] === 'add' || o._[1] === 'remove';
650
+ if (cmd === 'worktree') return o._[1] === 'add' || o._[1] === 'remove';
503
651
  // `--wire` writes a CI workflow; `--refresh` only rebuilds sites the folder already holds.
504
652
  if (cmd === 'docs') return action === 'sync' && !!o.wire;
505
653
  return false;
@@ -555,7 +703,9 @@ async function main() {
555
703
  // Its stdout is already a protocol (Claude Code reads the exit code, Cursor a permission object),
556
704
  // so it takes no --json (E1).
557
705
  if (inJSON()) return refuse('yad hook takes no --json — its output is the protocol the agent reads', 'run it without --json');
558
- if (action !== 'ledger-guard') return refuse(`unknown hook: ${action ?? '(none)'} (ledger-guard)`);
706
+ // E158: the agent guard, before an agent's shell command.
707
+ if (action === 'agent-guard') { runAgentGuardHook({ format: o.format ?? null }); return; }
708
+ if (action !== 'ledger-guard') return refuse(`unknown hook: ${action ?? '(none)'} (ledger-guard, agent-guard)`);
559
709
  // `--staged` is the git pre-commit half (E48): the files come from the index, never from stdin.
560
710
  if (o.staged) { runStagedLedgerGuard(); return; }
561
711
  runLedgerGuardHook({ paths: o.path ? [o.path] : [], format: o.format });
@@ -594,10 +744,11 @@ async function main() {
594
744
  // The workspace folder itself, or a repo the Product does not register: no Product here, but the
595
745
  // person is one `cd` away from it — say so, rather than let "run yad setup" make a second one.
596
746
  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)}`);
747
+ else if (cmd === 'status' || cmd === 'guide') o.productElsewhere = shown(found.elsewhere);
597
748
  } else if (found?.root && REPO_CMDS.has(cmd)) o.product = found.root;
598
749
  else if (found?.root && !dirGiven && found.via !== 'here') {
599
750
  o.dir = found.root;
600
- process.stderr.write(c.dim(`Product: ${shown(found.root)} (${found.via === 'workspace' ? `from ${commands.WORKSPACE_FILE}` : 'above this folder'})\n`));
751
+ process.stderr.write(c.dim(`Product: ${shown(found.root)} (${found.worktree ? `${found.worktree}'s worktree` : found.via === 'workspace' ? `from ${commands.WORKSPACE_FILE}` : 'above this folder'})\n`));
601
752
  // Run from inside one code repo, the per-repo commands work on THAT repo, not on every one the
602
753
  // Product registers (they take the repo's name as their second word).
603
754
  // The CHECKOUT must be the registered repo (a worktree or nested repo inside it is another one).
@@ -605,6 +756,11 @@ async function main() {
605
756
  const hit = commands.registryEntryFor(found.root, dirGiven ? o.dir : shellCwd());
606
757
  if (typeof hit?.meta?.name === 'string') o._[2] = hit.meta.name;
607
758
  }
759
+ // `yad ci check` the same way: that repo, unless --repo or --all says otherwise.
760
+ if (cmd === 'ci' && o.repo === undefined && !o.all) {
761
+ const hit = commands.registryEntryFor(found.root, dirGiven ? o.dir : shellCwd());
762
+ if (typeof hit?.meta?.name === 'string') o.repo = hit.meta.name;
763
+ }
608
764
  }
609
765
  }
610
766
  // A command that WRITES the Product never writes into a folder that is not one (a code repo, say).
@@ -619,6 +775,11 @@ async function main() {
619
775
  // shape-8.md). Not on `hook` — its stderr is the channel a block reason reaches a model on — and not
620
776
  // where the command reports the same thing itself (doctor, migrate) or runs before a project exists.
621
777
  if (!['hook', 'doctor', 'migrate', 'setup', 'report', 'detect', 'toolbox', 'new', 'init', 'join'].includes(cmd)) commands.warnIfProjectAhead(o.dir || process.cwd());
778
+ // E161: an end-of-life Node, once per run, on stderr (so --json stays clean). `hook` has returned above
779
+ // (its stderr is the channel a block reason reaches a model on); `doctor` says it in its own node row.
780
+ // YAD_TEST_NODE_VERSION stands in for the running version in tests only.
781
+ const nodeNow = process.env.YAD_TEST_NODE_VERSION || process.versions.node;
782
+ if (!['hook', 'doctor'].includes(cmd) && nodeSupport(nodeNow) === 'end-of-life') process.stderr.write(`${c.yellow(`! ${nodeEndOfLife(nodeNow)}`)}\n`);
622
783
  // E122: the Product's settings (or an epic's PR ledger) under two names that say different things.
623
784
  // Every command refuses rather than pick one — whichever it picked, somebody's edit would be silently
624
785
  // ignored. Not `doctor` (it reports the drift), `migrate` (it ends it) or `report` (it files a bug
@@ -643,6 +804,7 @@ async function main() {
643
804
  today, force: o.force,
644
805
  solo: o.solo, team: o.team, greenfield: o.greenfield, brownfield: o.brownfield,
645
806
  monorepo: o.monorepo, separate: o.separate, tools: o.tools,
807
+ ...setupAnswers(o),
646
808
  // The agent directories to install into, as a pre-answer for CI/scripts exactly like `--solo`
647
809
  // above (E11). Until this flag existed, `ideTargets` was reachable only programmatically: a
648
810
  // non-interactive run took `ask`'s default and had NO way to choose. That was survivable while
@@ -663,20 +825,25 @@ async function main() {
663
825
  today, force: o.force,
664
826
  solo: o.solo, team: o.team, greenfield: o.greenfield, brownfield: o.brownfield,
665
827
  monorepo: o.monorepo, separate: o.separate, tools: o.tools,
828
+ ...setupAnswers(o),
666
829
  ideTargets: o['ide-targets'] === undefined ? undefined : String(o['ide-targets']).split(',').map((t) => t.trim()).filter(Boolean),
667
830
  };
668
831
  if (cmd === 'new') result = await commands.runNew(o.dir, o._[1], setupFlags);
669
832
  else if (cmd === 'init') result = await commands.runInit(o.dir, { ...setupFlags, path: o.path });
670
- else result = await commands.runJoin(o.dir, o._[1], o._[2], { ideTargets: setupFlags.ideTargets });
833
+ else result = await commands.runJoin(o.dir, o._[1], o._[2], { ideTargets: setupFlags.ideTargets, noPush: !!o.noPush });
671
834
  break;
672
835
  }
673
836
  case 'check':
674
837
  if (noProduct()) break;
675
- 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 });
838
+ 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; }
839
+ 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; }
840
+ 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 });
676
841
  break;
677
842
  case 'update':
678
843
  if (noProduct()) break;
679
- 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 });
844
+ 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; }
845
+ 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; }
846
+ 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 });
680
847
  break;
681
848
  case 'doctor':
682
849
  result = await commands.runDoctor(o.dir, { json: o.json });
@@ -684,6 +851,33 @@ async function main() {
684
851
  case 'migrate':
685
852
  result = await commands.runMigrate(o.dir, { apply: o.apply, json: o.json, keep: o.keep ?? null });
686
853
  break;
854
+ case 'signing': {
855
+ // E160a. Read-only: the git config in this folder, the key it names, and the account on the Product's
856
+ // platform (found as every Product command finds it, from this folder or a repo the Product registers).
857
+ const [, action = 'check', extra] = o._;
858
+ if (action !== 'check' || extra) { refuse(`unknown signing action: ${[action, extra].filter(Boolean).join(' ')}`, 'usage: yad signing check [--json] [--dir <folder>]'); break; }
859
+ const found = commands.findProduct(dirGiven ? o.dir : shellCwd());
860
+ // Why no Product was found is said, as every Product command says it: the account is then not checked.
861
+ if (found?.problem) warn(`${found.problem} — your account is not checked`);
862
+ 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`);
863
+ result = commands.runSigningCheck(dirGiven ? o.dir : shellCwd(), { root: found?.problem || found?.elsewhere ? null : found?.root ?? null, json: o.json });
864
+ break;
865
+ }
866
+ case 'ci': {
867
+ // E160b. Read-only: yad's CI files on disk, and the platform's rules on each default branch.
868
+ const [, action = 'check', extra] = o._;
869
+ const usage = 'usage: yad ci check [--repo <name> | --all] [--json] [--dir <folder>]';
870
+ if (action !== 'check' || extra) { refuse(`unknown ci action: ${[action, extra].filter(Boolean).join(' ')}`, usage); break; }
871
+ if (o.repo !== undefined && o.all) { refuse('--repo and --all name different repos: pass one of them', usage); break; }
872
+ 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; }
873
+ result = commands.runCiCheck(o.dir, { repo: o.all ? null : o.repo ?? null, json: o.json });
874
+ if (result?.unknownRepo !== undefined) {
875
+ const names = result.names.map(forTerminal);
876
+ refuse(`no repo named ${forTerminal(result.unknownRepo)} is registered`, names.length ? `the registered repos: ${names.join(', ')} (or --all)` : 'this Product registers no code repos');
877
+ result = undefined;
878
+ }
879
+ break;
880
+ }
687
881
  case 'toolbox': {
688
882
  // E84 + E86. Finding a tool reads the folder yad runs in (a code repo's own skills count); the
689
883
  // team's choices are the Product's `.sdlc/toolbox.json`, found the way every Product command finds
@@ -734,9 +928,16 @@ async function main() {
734
928
  result = commands.runDetect(o.dir || process.cwd(), { json: o.json });
735
929
  break;
736
930
  }
737
- case 'report':
738
- result = await commands.runReport(o.dir, { message: o.message });
931
+ case 'report': {
932
+ // E158: an agent previews with --json, shows the person, and on their yes posts with --post --confirm.
933
+ const kind = o.kind ?? 'bug';
934
+ if (!commands.REPORT_KINDS.includes(kind)) { refuse(`yad report --kind takes ${commands.REPORT_KINDS.join(' or ')} (got: ${kind})`, REPORT_USAGE); break; }
935
+ 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; }
936
+ if (o.confirm && !o.post) { refuse('yad report --confirm is for --post', REPORT_USAGE); break; }
937
+ result = await commands.runReport(o.dir, { message: o.message, kind, post: !!o.post, confirm: o.confirm ?? null });
938
+ if (result?.refused) process.exitCode = 1;
739
939
  break;
940
+ }
740
941
  case 'usage':
741
942
  result = commands.runUsage(o.dir, {
742
943
  out: o.out, since: o.since, until: o.until, all: o.all, member: o.member,
@@ -785,6 +986,29 @@ async function main() {
785
986
  refuse(`unknown skill action: ${action} (list, bind, unbind, recommend)`, 'usage: yad skill list [--profile <p> | --epic <id>] [--json] | yad skill bind <step> <skill> [<skill> ...] [--profile <p>] | yad skill unbind <step> [--profile <p>] | yad skill recommend [<step>] [--profile <p> | --epic <id>] [--json]');
786
987
  break;
787
988
  }
989
+ case 'status': {
990
+ if (o._[1] !== undefined) { refuse(`yad status takes no ${o._[1]}`, 'usage: yad status [--brief] [--no-fetch] [--json]'); break; }
991
+ const root = o.product || (commands.hasProduct(o.dir) ? o.dir : null);
992
+ if (!root) {
993
+ refuse(`no Product here (${o.dir}) — yad status reads the Product`, o.productElsewhere
994
+ ? `this folder is not in a repo the Product registers — the Product is ${o.productElsewhere}: cd there, or pass --dir ${o.productElsewhere}`
995
+ : 'run it from the Product, from inside a repo it registers, or pass --dir <the Product>; `yad new` / `yad init` start one');
996
+ break;
997
+ }
998
+ result = await commands.runStatus(root, { cwd: o.dir, json: o.json, fetch: !o.noFetch });
999
+ break;
1000
+ }
1001
+ case 'guide': {
1002
+ // Like `status`, it keeps the folder it ran in ("here" is that checkout). Unlike `status`, no Product
1003
+ // is an answer, not a refusal: it says how to start one (the first start, E157).
1004
+ const [, epic] = o._;
1005
+ if (o._[2] !== undefined) { refuse(`yad guide takes one epic id, not ${o._[2]}`, 'usage: yad guide [<epic>] [--json]'); break; }
1006
+ if (epic !== undefined && !commands.isValidEpicId(epic)) { refuse(`invalid epic id: ${epic} (expected EP-<slug>, [a-z0-9-] only)`, 'usage: yad guide [<epic>] [--json]'); break; }
1007
+ const root = o.product || (commands.hasProduct(o.dir) ? o.dir : null);
1008
+ // A Product one `cd` away is said in the answer too, so an agent never starts a second one (E80).
1009
+ result = await commands.runGuide(root, { epic: epic ?? null, cwd: o.dir, json: o.json, productElsewhere: root ? null : o.productElsewhere ?? null });
1010
+ break;
1011
+ }
788
1012
  case 'next': {
789
1013
  const [, epic] = o._;
790
1014
  // `--check` with no step is a malformed guard call — fail loudly rather than silently print.
@@ -851,7 +1075,7 @@ async function main() {
851
1075
  const [, action, epic, artifact] = o._;
852
1076
  // `gate ci` takes no positionals — epic/artifact come from --branch (or a sweep of all PRs).
853
1077
  if (action === 'ci') { result = await commands.gateCi(o.dir, { branch: o.branch, pr: o.pr, merged: o.merged, push: !o.noPush, today }); break; }
854
- if (!epic) { refuse('usage: yad gate <open|sync|comments|status|repair|review|walkthrough|trailer|ci|approve|comment|advance> <epic> [artifact]'); break; }
1078
+ if (!epic) { refuse('usage: yad gate <open|sync|comments|status|repair|reopen|review|walkthrough|trailer|ci|approve|comment|advance> <epic> [artifact]'); break; }
855
1079
  // The epic id becomes a path segment under epics/ — reject anything but EP-<slug> outright.
856
1080
  if (!commands.isValidEpicId(epic)) { refuse(`invalid epic id: ${epic} (expected EP-<slug>, [a-z0-9-] only)`); break; }
857
1081
  // In verified mode CI is the sole ledger writer: `open` only opens the PR, and local `sync` is
@@ -862,6 +1086,8 @@ async function main() {
862
1086
  else if (action === 'comments') result = await commands.gateComments(o.dir, { epic, artifact, today });
863
1087
  else if (action === 'status') result = await commands.gateStatus(o.dir, { epic });
864
1088
  else if (action === 'repair') result = await commands.gateRepair(o.dir, { epic, push: o.push, allowBranch: o.allowBranch, dryRun: o.dryRun, today });
1089
+ // The third word is a STEP here (`architecture`), not an artifact file.
1090
+ else if (action === 'reopen') result = await commands.gateReopen(o.dir, { epic, step: artifact, reason: o.reason, push: o.push, allowBranch: o.allowBranch, dryRun: o.dryRun, today });
865
1091
  else if (action === 'review') result = await commands.gateReview(o.dir, { epic, artifact });
866
1092
  else if (action === 'walkthrough') result = await commands.gateWalkthrough(o.dir, { epic, artifact });
867
1093
  else if (action === 'trailer') result = await commands.gateTrailer(o.dir, { epic, artifact, body: o.body || o.message, number: o.pr });
@@ -869,7 +1095,7 @@ async function main() {
869
1095
  else if (action === 'approve') result = await commands.gateApprove(o.dir, { epic, artifact, by: o.by, engagement: o.engagement ?? null, today });
870
1096
  else if (action === 'comment') result = await commands.gateComment(o.dir, { epic, artifact, by: o.by, count: o.count ?? null, newRound: !!o.newRound, today });
871
1097
  else if (action === 'advance') result = await commands.gateAdvance(o.dir, { epic, artifact, today });
872
- else { refuse(`unknown gate action: ${action} (open|sync|comments|status|repair|review|walkthrough|trailer|ci|approve|comment|advance)`); }
1098
+ else { refuse(`unknown gate action: ${action} (open|sync|comments|status|repair|reopen|review|walkthrough|trailer|ci|approve|comment|advance)`); }
873
1099
  break;
874
1100
  }
875
1101
  case 'review': {
@@ -887,15 +1113,51 @@ async function main() {
887
1113
  break;
888
1114
  }
889
1115
  case 'commit':
890
- result = await commands.runCommit(o.dir, { type: o.type, message: o.message, task: o.task, ai: o.ai, contractChange: o.contractChange, dryRun: o.dryRun, force: o.force, manual: o.manual, reason: o.reason });
1116
+ result = await commands.runCommit(o.dir, { type: o.type, message: o.message, task: o.task, ai: o.ai, contractChange: o.contractChange, dryRun: o.dryRun, force: o.force, manual: o.manual, reason: o.reason, body: o.body });
1117
+ break;
1118
+ case 'build': {
1119
+ const [, action, story, a3, a4] = o._;
1120
+ const known = ACTIONS.build.known;
1121
+ if (!known.includes(action)) { refuse(`unknown build action: ${action ?? '(none)'} (${known.join('|')})`, '`yad build start <story> --repo <name>` begins a story\'s lane'); break; }
1122
+ // `sync` takes an optional epic, not a story.
1123
+ if (action === 'sync') {
1124
+ if (a3 !== undefined) { refuse(`yad build sync takes one epic at most (got ${o._.slice(2).join(' ')})`, 'yad build sync [<epic>]'); break; }
1125
+ if (noProduct()) break;
1126
+ result = await commands.buildSync(o.dir, { epic: story || null, dryRun: !!o.dryRun, today, fetch: !o.noFetch });
1127
+ break;
1128
+ }
1129
+ if (!story) { refuse(`usage: yad build ${action} <story> …`, 'the story id, such as EP-checkout-S01'); break; }
1130
+ if (noProduct()) break;
1131
+ // Every --signal is name=value.
1132
+ const signals = {};
1133
+ const badSignal = (o.signal || []).find((sgl) => sgl.indexOf('=') < 1);
1134
+ if (badSignal) { refuse(`--signal ${badSignal}: expected name=value`, '--signal checks=pass'); break; }
1135
+ for (const sgl of o.signal || []) signals[sgl.slice(0, sgl.indexOf('='))] = sgl.slice(sgl.indexOf('=') + 1);
1136
+ if (action === 'start') result = await commands.buildStart(o.dir, { story, repo: o.repo, today });
1137
+ else if (action === 'step') result = await commands.buildStep(o.dir, { story, repo: o.repo, step: a3, to: a4, reason: o.reason, via: o.via || 'human', run: o.run || null, task: o.task || null, today });
1138
+ else if (action === 'trust') result = await commands.buildTrust(o.dir, { story, repo: o.repo, step: a3, verdict: o.verdict, signals, ranBy: o['ran-by'] || 'human', note: o.note || null, uid: o.uid || null, task: o.task || null, today });
1139
+ else if (action === 'ship') result = await commands.buildShip(o.dir, { story, task: o.task, repo: o.repo, pr: o.pr, mergeCommit: o['merge-commit'] || null, approvers: o.approver || [], followUp: !!o.followUp, today, fetch: !o.noFetch });
1140
+ else if (action === 'merged') result = await commands.buildMerged(o.dir, { story, task: o.task, repo: o.repo, pr: o.pr || null, ship: !!o.ship, followUp: !!o.followUp, today, fetch: !o.noFetch });
1141
+ else result = await commands.buildDone(o.dir, { story, today, fetch: !o.noFetch });
891
1142
  break;
1143
+ }
1144
+ case 'run': {
1145
+ const [, action] = o._;
1146
+ if (action !== 'checks') { refuse(`unknown run action: ${action ?? '(none)'} (checks)`, '`yad run checks` runs every pull request gate here before you push'); break; }
1147
+ result = await commands.runChecks(o.dir, { product: o.product, base: o.base, title: o.title, body: o.body, build: !o.noBuild, fetch: !o.noFetch });
1148
+ break;
1149
+ }
892
1150
  case 'open-pr':
893
- result = await commands.runOpenPr(o.dir, { repo: o.repo, product: o.product, platform: o.platform, base: o.base, title: o.title || o.message, task: o.task, risk: o.risk, contractChange: o.contractChange });
1151
+ result = await commands.runOpenPr(o.dir, { repo: o.repo, product: o.product, platform: o.platform, base: o.base, title: o.title || o.message, task: o.task, risk: o.risk, contractChange: o.contractChange, via: o.via, today });
894
1152
  break;
895
1153
  case 'ship':
896
1154
  // The ledger override is its own act (E49): recorded in its own commit, never folded into a
897
1155
  // commit-and-open-PR run. Refused, never ignored.
898
- 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; }
1156
+ 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; }
1157
+ // Opening on the standing approval follows the checks, not the commit (#356): its own command.
1158
+ if (o.via !== undefined) { refuse('yad ship takes no --via: commit, run the checks, then `yad open-pr --via auto`'); break; }
1159
+ // A commit body (#357: the Decisions: paragraph) is written by `yad commit`; ship never drops it unseen.
1160
+ if (o.body !== undefined) { refuse('yad ship takes no --body: commit with `yad commit --body "<text>" …`, then `yad open-pr`'); break; }
899
1161
  result = await commands.runShip(o.dir, { type: o.type, message: o.message, task: o.task, ai: o.ai, contractChange: o.contractChange, dryRun: o.dryRun, force: o.force, repo: o.repo, product: o.product, platform: o.platform, base: o.base, title: o.title, risk: o.risk });
900
1162
  break;
901
1163
  case 'checkpoint': {
@@ -934,6 +1196,22 @@ async function main() {
934
1196
  else result = await commands.runMemberRemove(o.dir, { login: who ?? null, reason: o.reason ?? null });
935
1197
  break;
936
1198
  }
1199
+ case 'worktree': {
1200
+ // #115. One git worktree per epic, beside the Product and each code repo.
1201
+ const [, action = 'list', epic, extra] = o._;
1202
+ const usage = 'usage: yad worktree add <epic> [--repo <name>|--all] [--dry-run] | yad worktree list [<epic>] [--json] | yad worktree remove <epic> [--repo <name>|--all]';
1203
+ if (!['add', 'list', 'remove'].includes(action)) { refuse(`unknown worktree action: ${action} (add, list, remove)`, usage); break; }
1204
+ if (extra) { refuse(`unexpected word: ${extra}`, usage); break; }
1205
+ if (action !== 'list' && !epic) { refuse(`yad worktree ${action} needs an epic`, usage); break; }
1206
+ if (o.repo !== undefined && o.all) { refuse('--repo and --all name different targets — pass one', usage); break; }
1207
+ if (o.repo === true || o.repo === '') { refuse('--repo needs a repo name', usage); break; }
1208
+ if (action === 'list' && (o.repo !== undefined || o.all)) { refuse('yad worktree list lists every repo; it takes no --repo or --all', usage); break; }
1209
+ if (noProduct()) break;
1210
+ if (action === 'add') result = await commands.runWorktreeAdd(o.dir, { epic, repo: o.repo ?? null, all: !!o.all, dryRun: !!o.dryRun, today });
1211
+ else if (action === 'list') result = await commands.runWorktreeList(o.dir, { epic: epic ?? null });
1212
+ else result = await commands.runWorktreeRemove(o.dir, { epic, repo: o.repo ?? null, all: !!o.all, cwd: shellCwd() });
1213
+ break;
1214
+ }
937
1215
  case 'standup': {
938
1216
  // E132. Read-only; every flag that is not standup's own is refused, as history refuses them.
939
1217
  const foreign = commands.standupForeignFlags(process.argv.slice(2));
@@ -1096,7 +1374,8 @@ main()
1096
1374
  if (inJSON() && !jsonEmitted()) {
1097
1375
  if (err?.parsedCmd !== undefined && runningCmd === null) beginJSON(commandName(err.parsedWords ?? []));
1098
1376
  const hint = err?.hint || (/expects a value$/.test(String(err?.message)) ? '`yad --help` lists the flags of each command' : null);
1099
- refuse(String(err?.message || err), hint, { code: err?.code && /^YAD-/.test(err.code) ? err.code : null });
1377
+ // E159: a setup refused for unanswered questions lists them, so an agent can ask the person.
1378
+ refuse(String(err?.message || err), hint, { code: err?.code && /^YAD-/.test(err.code) ? err.code : null, ...(Array.isArray(err?.questions) ? { questions: err.questions } : {}) });
1100
1379
  return;
1101
1380
  }
1102
1381
  const code = err?.code && /^YAD-/.test(err.code) ? ` [${err.code}]` : '';