yadflow 4.6.0 → 4.7.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 +170 -0
  2. package/README.md +4 -1
  3. package/bin/commands.mjs +5 -1
  4. package/bin/yad.mjs +167 -15
  5. package/cli/artifact-status.mjs +88 -20
  6. package/cli/build.mjs +1372 -0
  7. package/cli/checkpoint.mjs +2 -2
  8. package/cli/commit.mjs +1 -0
  9. package/cli/dial.mjs +21 -1
  10. package/cli/docs.mjs +6 -1
  11. package/cli/doctor.mjs +133 -26
  12. package/cli/epic-state.mjs +357 -9
  13. package/cli/errors.mjs +2 -0
  14. package/cli/find-product.mjs +36 -2
  15. package/cli/fold.mjs +9 -5
  16. package/cli/gate-local.mjs +9 -1
  17. package/cli/gate.mjs +364 -22
  18. package/cli/history.mjs +22 -2
  19. package/cli/hook.mjs +3 -1
  20. package/cli/index-command.mjs +2 -2
  21. package/cli/ledger.mjs +60 -0
  22. package/cli/next.mjs +34 -11
  23. package/cli/openpr.mjs +81 -5
  24. package/cli/platform.mjs +21 -0
  25. package/cli/pr-list.mjs +5 -3
  26. package/cli/product-index.mjs +6 -3
  27. package/cli/product-token.mjs +186 -0
  28. package/cli/productcommit.mjs +33 -0
  29. package/cli/recommend.mjs +3 -1
  30. package/cli/repo-publish.mjs +2 -2
  31. package/cli/run-checks.mjs +586 -0
  32. package/cli/ship-drift.mjs +49 -18
  33. package/cli/standup.mjs +1 -1
  34. package/cli/status.mjs +282 -0
  35. package/cli/test-build.mjs +1559 -0
  36. package/cli/test-run-checks.mjs +603 -0
  37. package/cli/test-worktree.mjs +520 -0
  38. package/cli/thread.mjs +4 -0
  39. package/cli/tidy.mjs +2 -2
  40. package/cli/toolbox.mjs +36 -5
  41. package/cli/workspace.mjs +4 -1
  42. package/cli/worktree-record.mjs +53 -0
  43. package/cli/worktree.mjs +379 -0
  44. package/package.json +3 -3
  45. package/skills/sdlc/config.yaml +1 -1
  46. package/skills/sdlc/module-help.csv +1 -1
  47. package/skills/yad-backfill/templates/checks/backfill-check.sh +9 -9
  48. package/skills/yad-change/SKILL.md +3 -0
  49. package/skills/yad-checks/SKILL.md +34 -5
  50. package/skills/yad-checks/references/check-gates.md +69 -10
  51. package/skills/yad-checks/templates/checks/build-test-lint.sh +22 -3
  52. package/skills/yad-checks/templates/checks/commit-message.sh +8 -2
  53. package/skills/yad-checks/templates/checks/contract-check.sh +61 -33
  54. package/skills/yad-checks/templates/checks/epic-open.sh +87 -14
  55. package/skills/yad-checks/templates/checks/ledger-guard.sh +3 -3
  56. package/skills/yad-checks/templates/checks/lineage-check.sh +88 -15
  57. package/skills/yad-checks/templates/checks/member-check.mjs +206 -35
  58. package/skills/yad-checks/templates/checks/package-manager.sh +41 -4
  59. package/skills/yad-checks/templates/checks/product-checkout.sh +161 -13
  60. package/skills/yad-checks/templates/checks/reconcile-debt-check.sh +94 -15
  61. package/skills/yad-checks/templates/checks/risk-map-check.sh +2 -2
  62. package/skills/yad-checks/templates/checks/spec-link.sh +63 -4
  63. package/skills/yad-checks/templates/checks/verified-commits.sh +23 -5
  64. package/skills/yad-checks/templates/github/yad-checks.yml +8 -8
  65. package/skills/yad-checks/templates/gitlab/.gitlab-ci.yml +3 -0
  66. package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml +4 -4
  67. package/skills/yad-checks/templates/gitlab/yad-product-checks.gitlab-ci.yml +16 -3
  68. package/skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml +5 -1
  69. package/skills/yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml +5 -1
  70. package/skills/yad-commit/SKILL.md +4 -2
  71. package/skills/yad-docs/templates/app/package-lock.json +395 -106
  72. package/skills/yad-docs/templates/app/package.json +2 -2
  73. package/skills/yad-engineer-review/SKILL.md +45 -20
  74. package/skills/yad-engineer-review/references/ship-and-record.md +42 -8
  75. package/skills/yad-epic/references/state-schema.md +75 -16
  76. package/skills/yad-implement/SKILL.md +75 -13
  77. package/skills/yad-implement/references/implement-conventions.md +8 -1
  78. package/skills/yad-implement/templates/.gitmessage +3 -0
  79. package/skills/yad-open-pr/SKILL.md +21 -0
  80. package/skills/yad-pr-template/SKILL.md +6 -2
  81. package/skills/yad-pr-template/templates/checks/pr-template.sh +85 -4
  82. package/skills/yad-pr-template/templates/checks/pr-title.sh +1 -1
  83. package/skills/yad-pr-template/templates/github/pull_request_template.md +1 -1
  84. package/skills/yad-pr-template/templates/gitlab/merge_request_templates/Default.md +1 -1
  85. package/skills/yad-product-bridge/SKILL.md +14 -1
  86. package/skills/yad-product-bridge/references/bridge.md +5 -2
  87. package/skills/yad-product-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml +9 -4
  88. package/skills/yad-reconcile/SKILL.md +9 -3
  89. package/skills/yad-review-gate/SKILL.md +4 -0
  90. package/skills/yad-review-gate/references/gating.md +26 -1
  91. package/skills/yad-run/SKILL.md +52 -28
  92. package/skills/yad-run/references/run-loop.md +42 -21
  93. package/skills/yad-spec/SKILL.md +137 -16
  94. package/skills/yad-spec/references/spec-handoff.md +50 -3
  95. package/skills/yad-status/SKILL.md +7 -0
  96. package/skills/yad-stories/references/story-schema.md +1 -1
package/bin/yad.mjs CHANGED
@@ -69,6 +69,20 @@ ${c.bold('Setup & maintenance')}
69
69
  installs in this clone refuses a person's hand commit to the ledger.
70
70
  YAD_HOOK_DISABLE=1 skips.
71
71
 
72
+ ${c.bold('Parallel agents')} ${c.dim('(one git worktree per epic — #115)')}
73
+ yad worktree add <epic> [--repo <name>|--all] [--dry-run]
74
+ Make the epic's own worktree beside the Product (or beside a code
75
+ repo with --repo; the Product and every repo the epic names with
76
+ --all), detached at origin/<default>. A code repo's ignored
77
+ node_modules are linked, not reinstalled. Open the agent's session
78
+ in that folder, and make the step's usual branch there
79
+ yad worktree list [<epic>] [--json] The yad worktrees of the Product and every repo: branch, changes,
80
+ commits on no remote, locked, folder gone
81
+ yad worktree remove <epic> [--repo <name>|--all]
82
+ Remove them — refused, removing nothing, while one holds
83
+ uncommitted or untracked files, commits on no remote, a lock or an
84
+ operation half done, or you are inside it. No override
85
+
72
86
  ${c.bold('Team members')} ${c.dim('(identity only — no roles, no reviewers, no allowlist)')}
73
87
  yad member add [--no-push] Prove who you are and write .sdlc/members/<platform>-<login>.json:
74
88
  your account on the Product's platform (logs you in if needed),
@@ -137,6 +151,12 @@ ${c.bold('Where am I / what next')}
137
151
  yad next --all Every active epic's next action at once
138
152
  yad next [<epic>] --json The same answer as a machine-readable action object (for
139
153
  agents/CI) — always every epic, so --all is implied
154
+ yad status [--brief] [--no-fetch] [--json]
155
+ Where the work stands in ~20 lines, for after a context reset:
156
+ this checkout's task and its Build step, each open epic and its
157
+ next action, your open PRs/MRs, and what is owed (debt, blockers,
158
+ hotfix debt, follow-up PRs). --brief is the only form today;
159
+ --no-fetch asks no platform
140
160
  yad skill list [--profile <p> | --epic <id>] [--json]
141
161
  Which skill runs which step, whether that is one route's
142
162
  choice, the project's or the engine's default, and whether
@@ -155,7 +175,7 @@ ${c.bold('Where am I / what next')}
155
175
  command (pool skill first, yadflow's skill last). Binds nothing
156
176
  yad toolbox list [--json] [--dir <folder>]
157
177
  The external tools yadflow can use — core (offered at setup),
158
- recommended pools, the design/testing/learning connectors and
178
+ recommended (skill pools, Docker MCP), the connectors and
159
179
  this project's own — whether each is found here, whether this
160
180
  project uses it, and what yadflow does without it. Installs nothing
161
181
  yad toolbox check [--json] The tools this project uses that are not ready here, each with
@@ -201,6 +221,10 @@ ${c.bold('Where am I / what next')}
201
221
  kept in .sdlc/automation.json. No --to shows it. A review gate is
202
222
  always human. Recorded only for now: nothing drives a Shape step
203
223
  on its own until the engine runs agents
224
+ yad dial open-pr [--to auto|human] [--json]
225
+ The standing approval to open a task's PR/MR once its checks
226
+ pass (\`yad open-pr --via auto\`), for the whole project. The
227
+ merge is always a person's; the kill switch holds it at human
204
228
  yad dial <epic> <story> --repo <name> <step> [--to auto|human] [--json]
205
229
  A Build lane step's dial (spec, tasks, implement, checks), in
206
230
  build-state; on auto the yad-run skill moves past it after a clean
@@ -230,6 +254,11 @@ ${c.bold('Review gate (Shape)')}
230
254
  No platform only: record who commented, and how often, this round
231
255
  yad gate advance <epic> <artifact> No platform only: pass the gate when its approvals hold
232
256
  yad gate repair <epic> [--push] Close an author step stranded behind a passed review gate
257
+ yad gate reopen <epic> <step> --reason <why> [--push] [--dry-run]
258
+ Reopen an approved Shape step before Build starts: it and every
259
+ later step go back, their approvals are revoked (kept in
260
+ state.json reopens[]), and every gate from it is required again.
261
+ --push commits it to the default branch (needed when verified)
233
262
  (YAD-STATE-005); --push commits state.json to the default branch
234
263
  yad gate review <epic> [artifact] Print the grounding bundle for the review companion
235
264
  (artifact + risk + contract + PR + code-maps) — fun, easy review
@@ -242,16 +271,53 @@ ${c.bold('Review gate (Shape)')}
242
271
  --merged advances the step + flips artifact status on the default branch
243
272
 
244
273
  ${c.bold('Build helpers')}
245
- yad commit --type <t> -m <subject> [--manual --reason <why>]
246
- Commit by convention (trailers, atomic guard); --manual is
274
+ yad commit --type <t> -m <subject> [--body <text>] [--manual --reason <why>]
275
+ Commit by convention (trailers, atomic guard); --body adds a
276
+ body above the trailers; --manual is
247
277
  the door past the Product's ledger hook, reason recorded
248
- yad open-pr [--repo <name>] [--title <text>]
278
+ yad build start <story> --repo <r> ${c.dim('(on the Product)')} Begin a story's Build lane in one repo
279
+ yad build step <story> --repo <r> <step> in_progress|in_review|done|blocked [--reason <text>] [--run <uid>] [--via auto|human] [--task <T>]
280
+ Move the lane's current step; done records how it closed.
281
+ --task <T> reopens implement/checks for the next task
282
+ yad build trust <story> --repo <r> <step> --verdict <v> [--signal k=v] [--ran-by machine|human] [--note] [--task <T>]
283
+ Record a step run's trust entry (prints its uid); --uid <uid>
284
+ --verdict <v> finalizes one already recorded
285
+ yad build ship <story> --task <T> --repo <r> --pr <n> [--follow-up]
286
+ Record a ship from the MERGED PR/MR (merge commit, checks,
287
+ approvers); not \`yad ship\`, which commits and opens the PR.
288
+ Merged with no PR/MR: --merge-commit <sha> (no --pr) — the
289
+ platform is asked which PR merged it. [--no-fetch]
290
+ No platform to read: --merge-commit <sha> [--approver <login>]…
291
+ --follow-up: a merged fix/<story>-<task>-followup-<words> PR,
292
+ added to the task's ship (its followUps)
293
+ yad build merged <story> --task <T> --repo <r> [--pr <n>] [--ship] [--follow-up] [--no-fetch]
294
+ Ask the platform whether the task's PR/MR merged (found by
295
+ its branch): shipped | merged | open | closed | none. One
296
+ check, nothing waits; --ship records the ship once merged.
297
+ --follow-up asks about the task's follow-up PRs instead
298
+ yad build sync [<epic>] [--dry-run] [--no-fetch]
299
+ Record every ship the code repos already show (what yad
300
+ reconcile check finds merged with no ship), through yad build
301
+ ship, then yad build done for each story now fully shipped;
302
+ what it cannot record is listed with the command to run
303
+ yad build done <story> [--no-fetch] Every task shipped: status shipped, review step closed
304
+ yad run checks [--title <text>] [--body <file>] [--base <ref>] [--no-build] [--no-fetch]
305
+ Run every PR/MR gate here before you push, as CI would: this
306
+ repo's own checks/ scripts against origin/<default>, with the
307
+ Product's default branch written where CI checks it out (and
308
+ removed after). Signatures are checked with git; the platform's
309
+ Verified badge is judged in CI. install-deps runs npm ci (it
310
+ replaces node_modules); --no-build skips it and build/test/lint.
311
+ Exit 1 on any FAIL, 130 when stopped with Ctrl-C
312
+ yad open-pr [--repo <name>] [--title <text>] [--via auto]
249
313
  Open a task PR/MR against the repo's DEFAULT branch (never a
250
314
  hardcoded main; --base overrides) — stage-aware on the Product: a
251
315
  review/EP-* branch opens the Shape artifact-review PR
252
316
  (delegates to gate open), any other Product branch uses the
253
317
  code-task template. --title sets the PR/MR title (default: -m,
254
- else the last commit's subject)
318
+ else the last commit's subject). --via auto: opened on the
319
+ standing approval (yad dial open-pr) once this task's checks
320
+ passed, and recorded on its lane
255
321
  yad ship --type <t> -m <subject> [--title <text>]
256
322
  Commit AND open the task PR/MR in one step (stage-aware).
257
323
  --title sets the PR/MR title (default: the commit subject)
@@ -278,7 +344,7 @@ ${c.bold('Build helpers')}
278
344
  yad unassign <epic> <step> [--force] Remove an assignment (someone else's needs --force)
279
345
  yad owners [<epic>] List every step assignment, and whether it is live
280
346
  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
347
+ docs(<epic, lowercase>): author <step> (signed if git signs) — drafts
282
348
  stay on yad/wip/…; with ledger: local the epic's ledger rides along
283
349
  yad tidy up [<epic>] [--push] Fold FINISHED Build shards (a shipped story's
284
350
  trust-log/build-log entries) back into the single folded
@@ -378,7 +444,8 @@ ${c.bold('Environment')}
378
444
 
379
445
  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
446
 
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']);
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']);
382
449
 
383
450
  function parseArgs(argv) {
384
451
  const o = { _: [], dir: process.cwd(), fix: false, force: false, scope: 'all' };
@@ -392,10 +459,13 @@ function parseArgs(argv) {
392
459
  else if (a === '--me') o.me = true;
393
460
  else if (a === '--no-push') o.noPush = true;
394
461
  else if (a === '--no-fetch') o.noFetch = true;
462
+ else if (a === '--no-build') o.noBuild = true;
395
463
  else if (a === '--push') o.push = true;
396
464
  else if (a === '--allow-branch') o.allowBranch = true;
397
465
  else if (a === '--overwrite-local') o.overwriteLocal = true;
398
466
  else if (a === '--merged') o.merged = true;
467
+ else if (a === '--ship') o.ship = true;
468
+ else if (a === '--follow-up') o.followUp = true;
399
469
  else if (a === '--overview') o.overview = true;
400
470
  // `--check` is a bare boolean for `docs sync --check`, but takes a value for
401
471
  // `next <epic> --check <step>`. Only the `next` command consumes the following token as a value —
@@ -403,6 +473,7 @@ function parseArgs(argv) {
403
473
  // positional. `o._[0]` is the command, already pushed by the time `--check` is seen in normal use.
404
474
  else if (a === '--check') { const v = argv[i + 1]; o.check = (o._[0] === 'next' && v !== undefined && !v.startsWith('-')) ? argv[++i] : true; }
405
475
  else if (a === '--all') o.all = true;
476
+ else if (a === '--brief') o.brief = true;
406
477
  else if (a === '--open') o.open = true;
407
478
  else if (a === '--done') o.done = true;
408
479
  else if (a === '--undo') o.undo = true;
@@ -432,6 +503,13 @@ function parseArgs(argv) {
432
503
  else if (a === '-v' || a === '--version') o.version = true;
433
504
  else if (a.startsWith('--scope=')) o.scope = a.slice('--scope='.length);
434
505
  else if (a === '-m' || a === '--message') o.message = takeValue(argv, ++i, a);
506
+ // Repeatable (`yad build trust … --signal a=true --signal b=false`, `yad build ship … --approver x --approver y`).
507
+ else if (LIST_FLAGS.has(a)) (o[a.slice(2)] ||= []).push(takeValue(argv, ++i, a));
508
+ else if (a.startsWith('--') && a.includes('=') && LIST_FLAGS.has(a.slice(0, a.indexOf('=')))) {
509
+ const value = a.slice(a.indexOf('=') + 1);
510
+ if (!value) throw new Error(`${a.slice(0, a.indexOf('='))} expects a value`);
511
+ (o[a.slice(2, a.indexOf('='))] ||= []).push(value);
512
+ }
435
513
  else if (VALUE_FLAGS.has(a)) o[a.replace(/^--/, '')] = takeValue(argv, ++i, a);
436
514
  // `--flag=value` for the same flags. Without it the token matched nothing and fell through to the
437
515
  // positionals, where it was silently ignored — and for `yad hook ledger-guard --format=cursor`
@@ -466,7 +544,7 @@ const ACTIONS = {
466
544
  epic: { known: ['new'] },
467
545
  foundation: { known: ['new', 'status'] },
468
546
  skill: { known: ['list', 'bind', 'unbind', 'recommend'], default: 'list' },
469
- gate: { known: ['open', 'sync', 'comments', 'status', 'repair', 'review', 'walkthrough', 'trailer', 'ci', 'approve', 'comment', 'advance'] },
547
+ gate: { known: ['open', 'sync', 'comments', 'status', 'repair', 'reopen', 'review', 'walkthrough', 'trailer', 'ci', 'approve', 'comment', 'advance'] },
470
548
  review: { known: ['trailer', 'context', 'chat', 'cards', 'walkthrough', 'nudge', 'reconcile'] },
471
549
  tidy: { known: ['up'] },
472
550
  history: { known: ['list', 'show', 'search'], default: 'list' },
@@ -478,6 +556,9 @@ const ACTIONS = {
478
556
  hook: { known: ['ledger-guard'] },
479
557
  toolbox: { known: ['list', 'check', 'add', 'remove'], default: 'list' },
480
558
  member: { known: ['add', 'list', 'remove'], default: 'list' },
559
+ worktree: { known: ['add', 'list', 'remove'], default: 'list' },
560
+ run: { known: ['checks'] },
561
+ build: { known: ['start', 'step', 'trust', 'ship', 'merged', 'done', 'sync'] },
481
562
  };
482
563
  // E80 — how each command finds its folder. A PRODUCT command works on the Product; a REPO command works
483
564
  // on the code repo it runs in and reads the Product beside it. The rest take their folder as given:
@@ -486,20 +567,24 @@ const PRODUCT_CMDS = new Set([
486
567
  'check', 'update', 'doctor', 'migrate', 'usage', 'sync-status', 'epic', 'foundation', 'skill', 'next',
487
568
  'skip', 'unskip', 'defer', 'undefer', 'dial', 'mode', 'kill', 'unkill', 'unblock', 'gate', 'checkpoint',
488
569
  'capture', 'claims', 'assign', 'unassign', 'owners', 'fold', 'tidy', 'index', 'history', 'repo',
489
- 'risk-map', 'codeowners', 'docs', 'thread', 'reconcile', 'member', 'standup',
570
+ 'risk-map', 'codeowners', 'docs', 'thread', 'reconcile', 'member', 'standup', 'build', 'worktree',
490
571
  ]);
491
- const REPO_CMDS = new Set(['commit', 'open-pr', 'ship', 'review']);
572
+ // `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']);
492
574
  // The Product commands that WRITE its files without first checking it is one. Run from a code repo they
493
575
  // wrote an epic, a dial or the module into it; they refuse instead (E80). The rest either only read, or
494
576
  // already refuse a folder that is not a Product.
495
577
  function writesProduct(cmd, o) {
496
578
  const action = o._[1];
497
579
  if (cmd === 'update' || cmd === 'kill' || cmd === 'unkill') return true;
580
+ // `build merged` only asks the platform, unless --ship records what it found.
581
+ if (cmd === 'build') return action === 'sync' ? !o.dryRun : action !== 'merged' || !!o.ship;
498
582
  if (cmd === 'check') return !!o.fix;
499
583
  if (cmd === 'epic' || cmd === 'foundation') return action === 'new';
500
584
  if (cmd === 'skill') return action === 'bind' || action === 'unbind';
501
585
  if (cmd === 'dial') return o.to !== undefined;
502
586
  if (cmd === 'member') return o._[1] === 'add' || o._[1] === 'remove';
587
+ if (cmd === 'worktree') return o._[1] === 'add' || o._[1] === 'remove';
503
588
  // `--wire` writes a CI workflow; `--refresh` only rebuilds sites the folder already holds.
504
589
  if (cmd === 'docs') return action === 'sync' && !!o.wire;
505
590
  return false;
@@ -594,10 +679,11 @@ async function main() {
594
679
  // The workspace folder itself, or a repo the Product does not register: no Product here, but the
595
680
  // person is one `cd` away from it — say so, rather than let "run yad setup" make a second one.
596
681
  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);
597
683
  } else if (found?.root && REPO_CMDS.has(cmd)) o.product = found.root;
598
684
  else if (found?.root && !dirGiven && found.via !== 'here') {
599
685
  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`));
686
+ 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
687
  // Run from inside one code repo, the per-repo commands work on THAT repo, not on every one the
602
688
  // Product registers (they take the repo's name as their second word).
603
689
  // The CHECKOUT must be the registered repo (a worktree or nested repo inside it is another one).
@@ -785,6 +871,18 @@ async function main() {
785
871
  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
872
  break;
787
873
  }
874
+ case 'status': {
875
+ if (o._[1] !== undefined) { refuse(`yad status takes no ${o._[1]}`, 'usage: yad status [--brief] [--no-fetch] [--json]'); break; }
876
+ const root = o.product || (commands.hasProduct(o.dir) ? o.dir : null);
877
+ if (!root) {
878
+ refuse(`no Product here (${o.dir}) — yad status reads the Product`, o.productElsewhere
879
+ ? `this folder is not in a repo the Product registers — the Product is ${o.productElsewhere}: cd there, or pass --dir ${o.productElsewhere}`
880
+ : 'run it from the Product, from inside a repo it registers, or pass --dir <the Product>; `yad new` / `yad init` start one');
881
+ break;
882
+ }
883
+ result = await commands.runStatus(root, { cwd: o.dir, json: o.json, fetch: !o.noFetch });
884
+ break;
885
+ }
788
886
  case 'next': {
789
887
  const [, epic] = o._;
790
888
  // `--check` with no step is a malformed guard call — fail loudly rather than silently print.
@@ -851,7 +949,7 @@ async function main() {
851
949
  const [, action, epic, artifact] = o._;
852
950
  // `gate ci` takes no positionals — epic/artifact come from --branch (or a sweep of all PRs).
853
951
  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; }
952
+ if (!epic) { refuse('usage: yad gate <open|sync|comments|status|repair|reopen|review|walkthrough|trailer|ci|approve|comment|advance> <epic> [artifact]'); break; }
855
953
  // The epic id becomes a path segment under epics/ — reject anything but EP-<slug> outright.
856
954
  if (!commands.isValidEpicId(epic)) { refuse(`invalid epic id: ${epic} (expected EP-<slug>, [a-z0-9-] only)`); break; }
857
955
  // In verified mode CI is the sole ledger writer: `open` only opens the PR, and local `sync` is
@@ -862,6 +960,8 @@ async function main() {
862
960
  else if (action === 'comments') result = await commands.gateComments(o.dir, { epic, artifact, today });
863
961
  else if (action === 'status') result = await commands.gateStatus(o.dir, { epic });
864
962
  else if (action === 'repair') result = await commands.gateRepair(o.dir, { epic, push: o.push, allowBranch: o.allowBranch, dryRun: o.dryRun, today });
963
+ // The third word is a STEP here (`architecture`), not an artifact file.
964
+ 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
965
  else if (action === 'review') result = await commands.gateReview(o.dir, { epic, artifact });
866
966
  else if (action === 'walkthrough') result = await commands.gateWalkthrough(o.dir, { epic, artifact });
867
967
  else if (action === 'trailer') result = await commands.gateTrailer(o.dir, { epic, artifact, body: o.body || o.message, number: o.pr });
@@ -869,7 +969,7 @@ async function main() {
869
969
  else if (action === 'approve') result = await commands.gateApprove(o.dir, { epic, artifact, by: o.by, engagement: o.engagement ?? null, today });
870
970
  else if (action === 'comment') result = await commands.gateComment(o.dir, { epic, artifact, by: o.by, count: o.count ?? null, newRound: !!o.newRound, today });
871
971
  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)`); }
972
+ else { refuse(`unknown gate action: ${action} (open|sync|comments|status|repair|reopen|review|walkthrough|trailer|ci|approve|comment|advance)`); }
873
973
  break;
874
974
  }
875
975
  case 'review': {
@@ -887,15 +987,51 @@ async function main() {
887
987
  break;
888
988
  }
889
989
  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 });
990
+ 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 });
991
+ break;
992
+ case 'build': {
993
+ const [, action, story, a3, a4] = o._;
994
+ const known = ACTIONS.build.known;
995
+ if (!known.includes(action)) { refuse(`unknown build action: ${action ?? '(none)'} (${known.join('|')})`, '`yad build start <story> --repo <name>` begins a story\'s lane'); break; }
996
+ // `sync` takes an optional epic, not a story.
997
+ if (action === 'sync') {
998
+ if (a3 !== undefined) { refuse(`yad build sync takes one epic at most (got ${o._.slice(2).join(' ')})`, 'yad build sync [<epic>]'); break; }
999
+ if (noProduct()) break;
1000
+ result = await commands.buildSync(o.dir, { epic: story || null, dryRun: !!o.dryRun, today, fetch: !o.noFetch });
1001
+ break;
1002
+ }
1003
+ if (!story) { refuse(`usage: yad build ${action} <story> …`, 'the story id, such as EP-checkout-S01'); break; }
1004
+ if (noProduct()) break;
1005
+ // Every --signal is name=value.
1006
+ const signals = {};
1007
+ const badSignal = (o.signal || []).find((sgl) => sgl.indexOf('=') < 1);
1008
+ if (badSignal) { refuse(`--signal ${badSignal}: expected name=value`, '--signal checks=pass'); break; }
1009
+ for (const sgl of o.signal || []) signals[sgl.slice(0, sgl.indexOf('='))] = sgl.slice(sgl.indexOf('=') + 1);
1010
+ if (action === 'start') result = await commands.buildStart(o.dir, { story, repo: o.repo, today });
1011
+ 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 });
1012
+ 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 });
1013
+ 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 });
1014
+ 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 });
1015
+ else result = await commands.buildDone(o.dir, { story, today, fetch: !o.noFetch });
1016
+ break;
1017
+ }
1018
+ case 'run': {
1019
+ const [, action] = o._;
1020
+ if (action !== 'checks') { refuse(`unknown run action: ${action ?? '(none)'} (checks)`, '`yad run checks` runs every pull request gate here before you push'); break; }
1021
+ result = await commands.runChecks(o.dir, { product: o.product, base: o.base, title: o.title, body: o.body, build: !o.noBuild, fetch: !o.noFetch });
891
1022
  break;
1023
+ }
892
1024
  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 });
1025
+ 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
1026
  break;
895
1027
  case 'ship':
896
1028
  // The ledger override is its own act (E49): recorded in its own commit, never folded into a
897
1029
  // commit-and-open-PR run. Refused, never ignored.
898
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; }
1031
+ // Opening on the standing approval follows the checks, not the commit (#356): its own command.
1032
+ if (o.via !== undefined) { refuse('yad ship takes no --via: commit, run the checks, then `yad open-pr --via auto`'); break; }
1033
+ // A commit body (#357: the Decisions: paragraph) is written by `yad commit`; ship never drops it unseen.
1034
+ if (o.body !== undefined) { refuse('yad ship takes no --body: commit with `yad commit --body "<text>" …`, then `yad open-pr`'); break; }
899
1035
  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
1036
  break;
901
1037
  case 'checkpoint': {
@@ -934,6 +1070,22 @@ async function main() {
934
1070
  else result = await commands.runMemberRemove(o.dir, { login: who ?? null, reason: o.reason ?? null });
935
1071
  break;
936
1072
  }
1073
+ case 'worktree': {
1074
+ // #115. One git worktree per epic, beside the Product and each code repo.
1075
+ const [, action = 'list', epic, extra] = o._;
1076
+ const usage = 'usage: yad worktree add <epic> [--repo <name>|--all] [--dry-run] | yad worktree list [<epic>] [--json] | yad worktree remove <epic> [--repo <name>|--all]';
1077
+ if (!['add', 'list', 'remove'].includes(action)) { refuse(`unknown worktree action: ${action} (add, list, remove)`, usage); break; }
1078
+ if (extra) { refuse(`unexpected word: ${extra}`, usage); break; }
1079
+ if (action !== 'list' && !epic) { refuse(`yad worktree ${action} needs an epic`, usage); break; }
1080
+ if (o.repo !== undefined && o.all) { refuse('--repo and --all name different targets — pass one', usage); break; }
1081
+ if (o.repo === true || o.repo === '') { refuse('--repo needs a repo name', usage); break; }
1082
+ if (action === 'list' && (o.repo !== undefined || o.all)) { refuse('yad worktree list lists every repo; it takes no --repo or --all', usage); break; }
1083
+ if (noProduct()) break;
1084
+ if (action === 'add') result = await commands.runWorktreeAdd(o.dir, { epic, repo: o.repo ?? null, all: !!o.all, dryRun: !!o.dryRun, today });
1085
+ else if (action === 'list') result = await commands.runWorktreeList(o.dir, { epic: epic ?? null });
1086
+ else result = await commands.runWorktreeRemove(o.dir, { epic, repo: o.repo ?? null, all: !!o.all, cwd: shellCwd() });
1087
+ break;
1088
+ }
937
1089
  case 'standup': {
938
1090
  // E132. Read-only; every flag that is not standup's own is refused, as history refuses them.
939
1091
  const foreign = commands.standupForeignFlags(process.argv.slice(2));
@@ -66,7 +66,94 @@ export function setFrontmatterStatus(file, status) {
66
66
  return cur;
67
67
  }
68
68
 
69
+ // A story's Build status (`yad build ship` / `yad build done`, #346), forward only, and only the `status:`
70
+ // line of the frontmatter. Every Shape value (`draft`, `in-review`, `approved`) is before Build: a story
71
+ // whose stories review passed may still say `draft` when nobody ran `yad sync-status`. The Shape ladder
72
+ // above never writes the Build values (PRESERVE); this is the one writer of them. The value is read as YAML
73
+ // reads it — quotes and a trailing `# comment` aside. Returns { prior, changed }, or { prior, unknown: true }
74
+ // for a value this cannot place (the caller refuses rather than leave the line behind).
75
+ const BUILD_LADDER = { draft: 0, 'in-review': 0, approved: 0, 'in-build': 1, shipped: 2 };
76
+ export const statusValue = (raw) => String(raw ?? '').replace(/\s+#.*$/, '').trim().replace(/^(['"])(.*)\1$/, '$2').trim();
77
+ // Two `status:` lines are read differently by different readers (the first by epic-open.sh, the last by
78
+ // parseFrontmatter), so a block with two is never read or written here.
79
+ const statusLines = (block) => [...block.matchAll(/^status:\s*(.*)$/gm)];
80
+ export function readStoryStatus(file) {
81
+ if (!fs.existsSync(file)) return null;
82
+ const fm = fs.readFileSync(file, 'utf8').match(FRONTMATTER_BLOCK);
83
+ const lines = fm ? statusLines(fm[1]) : [];
84
+ return lines.length === 1 ? statusValue(lines[0][1]) : null;
85
+ }
86
+ export function setBuildStatus(file, status) {
87
+ if (!['in-build', 'shipped'].includes(status) || !fs.existsSync(file)) return { prior: null, unknown: true };
88
+ const text = fs.readFileSync(file, 'utf8');
89
+ const fm = text.match(FRONTMATTER_BLOCK);
90
+ const lines = fm ? statusLines(fm[1]) : [];
91
+ if (lines.length !== 1) return { prior: null, unknown: true };
92
+ const prior = statusValue(lines[0][1]);
93
+ if (!(prior in BUILD_LADDER)) return { prior, unknown: true };
94
+ // Already there, and written as every reader reads it (no quotes, no comment): nothing to do. Written
95
+ // another way (`"shipped"`, `shipped # done`), the line is rewritten, because the epic seal and
96
+ // `yad tidy` compare the raw value.
97
+ if (BUILD_LADDER[status] < BUILD_LADDER[prior]) return { prior, changed: false };
98
+ if (BUILD_LADDER[status] === BUILD_LADDER[prior] && lines[0][0] === `status: ${status}`) return { prior, changed: false };
99
+ const block = fm[1].replace(/^status:\s*.*$/m, () => `status: ${status}`);
100
+ fs.writeFileSync(file, text.replace(fm[1], () => block));
101
+ return { prior, changed: true };
102
+ }
103
+
69
104
  // Sweep one epic (or every epic under epics/) and reconcile artifact frontmatter with state.json.
105
+ // The artifact files of one epic, each with the step base it is keyed to.
106
+ function artifactFiles(dir) {
107
+ // Single-file artifacts + each story file (all keyed to the stories step pair).
108
+ const files = ARTIFACT_FILES.map((f) => ({ base: artifactBase(f), file: path.join(dir, f) }));
109
+ const storiesDir = path.join(dir, 'stories');
110
+ if (fs.existsSync(storiesDir)) {
111
+ for (const f of fs.readdirSync(storiesDir).filter((x) => x.endsWith('.md'))) {
112
+ files.push({ base: 'stories', file: path.join(storiesDir, f) });
113
+ }
114
+ }
115
+ // Discovery ("epic zero") set: the project-discovery files all key to the single discovery /
116
+ // discovery-review step pair, so they reconcile together (mirrors the stories/ set above).
117
+ for (const f of DISCOVERY_FILES) {
118
+ if (fs.existsSync(path.join(dir, f))) files.push({ base: 'discovery', file: path.join(dir, f) });
119
+ }
120
+ // The Foundation's sections key to its one foundation / foundation-review pair the same way. Both
121
+ // spellings are offered; `desiredStatus` answers null for the base the chain does not carry, so
122
+ // a converted Foundation holding the six old files still reconciles them under `discovery`.
123
+ for (const f of FOUNDATION_FILES) {
124
+ if (fs.existsSync(path.join(dir, f))) files.push({ base: 'foundation', file: path.join(dir, f) });
125
+ }
126
+ return files;
127
+ }
128
+
129
+ // The one writer that moves a status DOWN the ladder: `yad gate reopen` (#322) withdraws an approval, so a
130
+ // file that says `approved` (or `in-review`) over a step walked back says what is now true. Like
131
+ // `setFrontmatterStatus`, only the `status:` line changes and a build-owned value is never touched.
132
+ // Returns the prior status when a change was written, else null.
133
+ export function lowerFrontmatterStatus(file, status) {
134
+ if (!fs.existsSync(file)) return null;
135
+ const text = fs.readFileSync(file, 'utf8');
136
+ const fm = text.match(FRONTMATTER_BLOCK);
137
+ if (!fm) return null;
138
+ const cur = (fm[1].match(/^status:\s*(.*)$/m) || [])[1]?.trim();
139
+ if (cur === undefined || PRESERVE.has(cur)) return null;
140
+ if (!(cur in RANK) || !(status in RANK) || RANK[status] >= RANK[cur]) return null;
141
+ const block = fm[1].replace(/^status:\s*.*$/m, () => `status: ${status}`);
142
+ fs.writeFileSync(file, text.replace(fm[1], () => block));
143
+ return cur;
144
+ }
145
+
146
+ // Lower every artifact of one epic to what its walked-back `state` now says (`yad gate reopen`, #322).
147
+ // Returns the root-relative paths it rewrote, so the reopen commit holds exactly those.
148
+ export function lowerStatuses(root, epic, state) {
149
+ const written = [];
150
+ for (const { base, file } of artifactFiles(epicRoot(root, epic))) {
151
+ const want = desiredStatus(state, base);
152
+ if (want && lowerFrontmatterStatus(file, want)) written.push(path.relative(root, file));
153
+ }
154
+ return written;
155
+ }
156
+
70
157
  export async function syncStatuses(root, { epic, dryRun = false } = {}) {
71
158
  // `epicIds` — the Foundation included (E75), and only VALID ids: a backup directory or any other
72
159
  // folder left under `epics/` is not an epic, and rewriting frontmatter inside it would be a write to
@@ -86,26 +173,7 @@ export async function syncStatuses(root, { epic, dryRun = false } = {}) {
86
173
  const state = readJSONStrict(epicFiles(dir).state, null);
87
174
  if (!state?.steps) { info(`${e}: no state.json — skipping`); continue; }
88
175
 
89
- // Single-file artifacts + each story file (all keyed to the stories step pair).
90
- const files = ARTIFACT_FILES.map((f) => ({ base: artifactBase(f), file: path.join(dir, f) }));
91
- const storiesDir = path.join(dir, 'stories');
92
- if (fs.existsSync(storiesDir)) {
93
- for (const f of fs.readdirSync(storiesDir).filter((x) => x.endsWith('.md'))) {
94
- files.push({ base: 'stories', file: path.join(storiesDir, f) });
95
- }
96
- }
97
- // Discovery ("epic zero") set: the project-discovery files all key to the single discovery /
98
- // discovery-review step pair, so they reconcile together (mirrors the stories/ set above).
99
- for (const f of DISCOVERY_FILES) {
100
- if (fs.existsSync(path.join(dir, f))) files.push({ base: 'discovery', file: path.join(dir, f) });
101
- }
102
- // The Foundation's sections key to its one foundation / foundation-review pair the same way. Both
103
- // spellings are offered; `desiredStatus` answers null for the base the chain does not carry, so
104
- // a converted Foundation holding the six old files still reconciles them under `discovery`.
105
- for (const f of FOUNDATION_FILES) {
106
- if (fs.existsSync(path.join(dir, f))) files.push({ base: 'foundation', file: path.join(dir, f) });
107
- }
108
-
176
+ const files = artifactFiles(dir);
109
177
  for (const { base, file } of files) {
110
178
  if (!fs.existsSync(file)) continue;
111
179
  const want = desiredStatus(state, base);