yadflow 4.5.2 → 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 (101) hide show
  1. package/CHANGELOG.md +206 -0
  2. package/README.md +4 -1
  3. package/bin/commands.mjs +5 -1
  4. package/bin/yad.mjs +174 -18
  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 +396 -123
  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 +442 -33
  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/lib.mjs +12 -1
  23. package/cli/lifecycle/defaults/1.json +96 -0
  24. package/cli/lifecycle/lifecycle.schema.json +121 -0
  25. package/cli/lifecycle.mjs +695 -0
  26. package/cli/next.mjs +34 -11
  27. package/cli/openpr.mjs +81 -5
  28. package/cli/platform.mjs +21 -0
  29. package/cli/pr-list.mjs +49 -3
  30. package/cli/product-index.mjs +6 -3
  31. package/cli/product-token.mjs +186 -0
  32. package/cli/productcommit.mjs +33 -0
  33. package/cli/recommend.mjs +3 -1
  34. package/cli/repo-publish.mjs +2 -2
  35. package/cli/run-checks.mjs +586 -0
  36. package/cli/ship-drift.mjs +384 -0
  37. package/cli/standup.mjs +1 -1
  38. package/cli/status.mjs +282 -0
  39. package/cli/test-build.mjs +1559 -0
  40. package/cli/test-run-checks.mjs +603 -0
  41. package/cli/test-worktree.mjs +520 -0
  42. package/cli/thread.mjs +50 -3
  43. package/cli/tidy.mjs +2 -2
  44. package/cli/toolbox.mjs +36 -5
  45. package/cli/workspace.mjs +4 -1
  46. package/cli/worktree-record.mjs +53 -0
  47. package/cli/worktree.mjs +379 -0
  48. package/package.json +4 -3
  49. package/skills/sdlc/config.yaml +28 -20
  50. package/skills/sdlc/module-help.csv +1 -1
  51. package/skills/yad-backfill/references/backfill.md +8 -1
  52. package/skills/yad-backfill/templates/checks/backfill-check.sh +54 -6
  53. package/skills/yad-change/SKILL.md +3 -0
  54. package/skills/yad-checks/SKILL.md +47 -5
  55. package/skills/yad-checks/references/check-gates.md +124 -12
  56. package/skills/yad-checks/templates/checks/build-test-lint.sh +22 -3
  57. package/skills/yad-checks/templates/checks/commit-message.sh +8 -2
  58. package/skills/yad-checks/templates/checks/contract-check.sh +354 -48
  59. package/skills/yad-checks/templates/checks/epic-open.sh +87 -14
  60. package/skills/yad-checks/templates/checks/ledger-guard.sh +3 -3
  61. package/skills/yad-checks/templates/checks/lineage-check.sh +88 -15
  62. package/skills/yad-checks/templates/checks/member-check.mjs +206 -35
  63. package/skills/yad-checks/templates/checks/package-manager.sh +41 -4
  64. package/skills/yad-checks/templates/checks/product-checkout.sh +161 -13
  65. package/skills/yad-checks/templates/checks/reconcile-debt-check.sh +94 -15
  66. package/skills/yad-checks/templates/checks/risk-map-check.sh +2 -2
  67. package/skills/yad-checks/templates/checks/spec-link.sh +63 -4
  68. package/skills/yad-checks/templates/checks/verified-commits.sh +23 -5
  69. package/skills/yad-checks/templates/github/yad-checks.yml +8 -8
  70. package/skills/yad-checks/templates/gitlab/.gitlab-ci.yml +3 -0
  71. package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml +4 -4
  72. package/skills/yad-checks/templates/gitlab/yad-product-checks.gitlab-ci.yml +16 -3
  73. package/skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml +5 -1
  74. package/skills/yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml +5 -1
  75. package/skills/yad-commit/SKILL.md +4 -2
  76. package/skills/yad-docs/templates/app/package-lock.json +395 -106
  77. package/skills/yad-docs/templates/app/package.json +2 -2
  78. package/skills/yad-engineer-review/SKILL.md +45 -20
  79. package/skills/yad-engineer-review/references/ship-and-record.md +42 -8
  80. package/skills/yad-epic/references/state-schema.md +83 -20
  81. package/skills/yad-implement/SKILL.md +75 -13
  82. package/skills/yad-implement/references/implement-conventions.md +8 -1
  83. package/skills/yad-implement/templates/.gitmessage +3 -0
  84. package/skills/yad-open-pr/SKILL.md +21 -0
  85. package/skills/yad-pr-template/SKILL.md +6 -2
  86. package/skills/yad-pr-template/templates/checks/pr-template.sh +85 -4
  87. package/skills/yad-pr-template/templates/checks/pr-title.sh +1 -1
  88. package/skills/yad-pr-template/templates/github/pull_request_template.md +1 -1
  89. package/skills/yad-pr-template/templates/gitlab/merge_request_templates/Default.md +1 -1
  90. package/skills/yad-product-bridge/SKILL.md +14 -1
  91. package/skills/yad-product-bridge/references/bridge.md +29 -5
  92. package/skills/yad-product-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml +9 -4
  93. package/skills/yad-reconcile/SKILL.md +30 -0
  94. package/skills/yad-review-gate/SKILL.md +8 -2
  95. package/skills/yad-review-gate/references/gating.md +26 -1
  96. package/skills/yad-run/SKILL.md +52 -28
  97. package/skills/yad-run/references/run-loop.md +42 -21
  98. package/skills/yad-spec/SKILL.md +142 -17
  99. package/skills/yad-spec/references/spec-handoff.md +68 -5
  100. package/skills/yad-status/SKILL.md +7 -0
  101. 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
@@ -325,8 +391,9 @@ ${c.bold('Build helpers')}
325
391
  ${c.bold('Feature threads (post-lock change management)')}
326
392
  yad thread List every feature thread (genesis → changes → defects)
327
393
  yad thread <epic> [--json] Show one thread: its epics, the resolved current truth, open debt
328
- yad reconcile [check|refresh|wire] Flag orphan drift + open hotfix debt across threads (advisory,
329
- never a gate — the gates block at merge)
394
+ yad reconcile [check|refresh|wire] Flag orphan drift + open hotfix debt across threads, and merged
395
+ tasks with no build-log ship (advisory, never a gate — the gates
396
+ block at merge)
330
397
 
331
398
  ${c.bold('Interactive docs (generated sites)')}
332
399
  yad docs list Show the docs target + per-site freshness
@@ -377,7 +444,8 @@ ${c.bold('Environment')}
377
444
 
378
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]';
379
446
 
380
- 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']);
381
449
 
382
450
  function parseArgs(argv) {
383
451
  const o = { _: [], dir: process.cwd(), fix: false, force: false, scope: 'all' };
@@ -391,10 +459,13 @@ function parseArgs(argv) {
391
459
  else if (a === '--me') o.me = true;
392
460
  else if (a === '--no-push') o.noPush = true;
393
461
  else if (a === '--no-fetch') o.noFetch = true;
462
+ else if (a === '--no-build') o.noBuild = true;
394
463
  else if (a === '--push') o.push = true;
395
464
  else if (a === '--allow-branch') o.allowBranch = true;
396
465
  else if (a === '--overwrite-local') o.overwriteLocal = true;
397
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;
398
469
  else if (a === '--overview') o.overview = true;
399
470
  // `--check` is a bare boolean for `docs sync --check`, but takes a value for
400
471
  // `next <epic> --check <step>`. Only the `next` command consumes the following token as a value —
@@ -402,6 +473,7 @@ function parseArgs(argv) {
402
473
  // positional. `o._[0]` is the command, already pushed by the time `--check` is seen in normal use.
403
474
  else if (a === '--check') { const v = argv[i + 1]; o.check = (o._[0] === 'next' && v !== undefined && !v.startsWith('-')) ? argv[++i] : true; }
404
475
  else if (a === '--all') o.all = true;
476
+ else if (a === '--brief') o.brief = true;
405
477
  else if (a === '--open') o.open = true;
406
478
  else if (a === '--done') o.done = true;
407
479
  else if (a === '--undo') o.undo = true;
@@ -431,6 +503,13 @@ function parseArgs(argv) {
431
503
  else if (a === '-v' || a === '--version') o.version = true;
432
504
  else if (a.startsWith('--scope=')) o.scope = a.slice('--scope='.length);
433
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
+ }
434
513
  else if (VALUE_FLAGS.has(a)) o[a.replace(/^--/, '')] = takeValue(argv, ++i, a);
435
514
  // `--flag=value` for the same flags. Without it the token matched nothing and fell through to the
436
515
  // positionals, where it was silently ignored — and for `yad hook ledger-guard --format=cursor`
@@ -465,7 +544,7 @@ const ACTIONS = {
465
544
  epic: { known: ['new'] },
466
545
  foundation: { known: ['new', 'status'] },
467
546
  skill: { known: ['list', 'bind', 'unbind', 'recommend'], default: 'list' },
468
- 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'] },
469
548
  review: { known: ['trailer', 'context', 'chat', 'cards', 'walkthrough', 'nudge', 'reconcile'] },
470
549
  tidy: { known: ['up'] },
471
550
  history: { known: ['list', 'show', 'search'], default: 'list' },
@@ -477,6 +556,9 @@ const ACTIONS = {
477
556
  hook: { known: ['ledger-guard'] },
478
557
  toolbox: { known: ['list', 'check', 'add', 'remove'], default: 'list' },
479
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'] },
480
562
  };
481
563
  // E80 — how each command finds its folder. A PRODUCT command works on the Product; a REPO command works
482
564
  // on the code repo it runs in and reads the Product beside it. The rest take their folder as given:
@@ -485,20 +567,24 @@ const PRODUCT_CMDS = new Set([
485
567
  'check', 'update', 'doctor', 'migrate', 'usage', 'sync-status', 'epic', 'foundation', 'skill', 'next',
486
568
  'skip', 'unskip', 'defer', 'undefer', 'dial', 'mode', 'kill', 'unkill', 'unblock', 'gate', 'checkpoint',
487
569
  'capture', 'claims', 'assign', 'unassign', 'owners', 'fold', 'tidy', 'index', 'history', 'repo',
488
- 'risk-map', 'codeowners', 'docs', 'thread', 'reconcile', 'member', 'standup',
570
+ 'risk-map', 'codeowners', 'docs', 'thread', 'reconcile', 'member', 'standup', 'build', 'worktree',
489
571
  ]);
490
- 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']);
491
574
  // The Product commands that WRITE its files without first checking it is one. Run from a code repo they
492
575
  // wrote an epic, a dial or the module into it; they refuse instead (E80). The rest either only read, or
493
576
  // already refuse a folder that is not a Product.
494
577
  function writesProduct(cmd, o) {
495
578
  const action = o._[1];
496
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;
497
582
  if (cmd === 'check') return !!o.fix;
498
583
  if (cmd === 'epic' || cmd === 'foundation') return action === 'new';
499
584
  if (cmd === 'skill') return action === 'bind' || action === 'unbind';
500
585
  if (cmd === 'dial') return o.to !== undefined;
501
586
  if (cmd === 'member') return o._[1] === 'add' || o._[1] === 'remove';
587
+ if (cmd === 'worktree') return o._[1] === 'add' || o._[1] === 'remove';
502
588
  // `--wire` writes a CI workflow; `--refresh` only rebuilds sites the folder already holds.
503
589
  if (cmd === 'docs') return action === 'sync' && !!o.wire;
504
590
  return false;
@@ -593,10 +679,11 @@ async function main() {
593
679
  // The workspace folder itself, or a repo the Product does not register: no Product here, but the
594
680
  // person is one `cd` away from it — say so, rather than let "run yad setup" make a second one.
595
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);
596
683
  } else if (found?.root && REPO_CMDS.has(cmd)) o.product = found.root;
597
684
  else if (found?.root && !dirGiven && found.via !== 'here') {
598
685
  o.dir = found.root;
599
- 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`));
600
687
  // Run from inside one code repo, the per-repo commands work on THAT repo, not on every one the
601
688
  // Product registers (they take the repo's name as their second word).
602
689
  // The CHECKOUT must be the registered repo (a worktree or nested repo inside it is another one).
@@ -784,6 +871,18 @@ async function main() {
784
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]');
785
872
  break;
786
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
+ }
787
886
  case 'next': {
788
887
  const [, epic] = o._;
789
888
  // `--check` with no step is a malformed guard call — fail loudly rather than silently print.
@@ -850,7 +949,7 @@ async function main() {
850
949
  const [, action, epic, artifact] = o._;
851
950
  // `gate ci` takes no positionals — epic/artifact come from --branch (or a sweep of all PRs).
852
951
  if (action === 'ci') { result = await commands.gateCi(o.dir, { branch: o.branch, pr: o.pr, merged: o.merged, push: !o.noPush, today }); break; }
853
- 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; }
854
953
  // The epic id becomes a path segment under epics/ — reject anything but EP-<slug> outright.
855
954
  if (!commands.isValidEpicId(epic)) { refuse(`invalid epic id: ${epic} (expected EP-<slug>, [a-z0-9-] only)`); break; }
856
955
  // In verified mode CI is the sole ledger writer: `open` only opens the PR, and local `sync` is
@@ -861,6 +960,8 @@ async function main() {
861
960
  else if (action === 'comments') result = await commands.gateComments(o.dir, { epic, artifact, today });
862
961
  else if (action === 'status') result = await commands.gateStatus(o.dir, { epic });
863
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 });
864
965
  else if (action === 'review') result = await commands.gateReview(o.dir, { epic, artifact });
865
966
  else if (action === 'walkthrough') result = await commands.gateWalkthrough(o.dir, { epic, artifact });
866
967
  else if (action === 'trailer') result = await commands.gateTrailer(o.dir, { epic, artifact, body: o.body || o.message, number: o.pr });
@@ -868,7 +969,7 @@ async function main() {
868
969
  else if (action === 'approve') result = await commands.gateApprove(o.dir, { epic, artifact, by: o.by, engagement: o.engagement ?? null, today });
869
970
  else if (action === 'comment') result = await commands.gateComment(o.dir, { epic, artifact, by: o.by, count: o.count ?? null, newRound: !!o.newRound, today });
870
971
  else if (action === 'advance') result = await commands.gateAdvance(o.dir, { epic, artifact, today });
871
- 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)`); }
872
973
  break;
873
974
  }
874
975
  case 'review': {
@@ -886,15 +987,51 @@ async function main() {
886
987
  break;
887
988
  }
888
989
  case 'commit':
889
- 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 });
890
1022
  break;
1023
+ }
891
1024
  case 'open-pr':
892
- 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 });
893
1026
  break;
894
1027
  case 'ship':
895
1028
  // The ledger override is its own act (E49): recorded in its own commit, never folded into a
896
1029
  // commit-and-open-PR run. Refused, never ignored.
897
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; }
898
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 });
899
1036
  break;
900
1037
  case 'checkpoint': {
@@ -906,7 +1043,10 @@ async function main() {
906
1043
  // own epic) so a `..` or a slash can never traverse out of the epic's stories dir, and a typo'd
907
1044
  // cross-epic id is caught here rather than failing obscurely later.
908
1045
  if (!story || !/^EP-[a-z0-9-]+-S\d+$/.test(story) || !story.startsWith(`${epic}-S`)) { refuse(`invalid --retro-ship: expected <epic>/<story> with story <epic>-S<NN> (got ${o['retro-ship']})`); break; }
909
- retroShip = { epic, story, repo: o.repo, task: o.task, mergeCommit: o['merge-commit'], today };
1046
+ // A SHA, never a ref or a search (`main`, `HEAD`, `:/text`): `yad reconcile check` reads a retro ship's
1047
+ // merge commit as the point it covers up to (#365 review 2), and a ref would cover every later merge.
1048
+ if (o['merge-commit'] != null && !/^[0-9a-f]{7,64}$/i.test(String(o['merge-commit']))) { refuse('invalid --merge-commit: expected a commit SHA (7 to 64 hex characters), never a branch name or a ref'); break; }
1049
+ retroShip = { epic, story, repo: o.repo, task: o.task, mergeCommit: o['merge-commit'] == null ? undefined : String(o['merge-commit']).toLowerCase(), today };
910
1050
  }
911
1051
  result = await commands.runCheckpoint(o.dir, { push: o.push, allowBranch: o.allowBranch, dryRun: o.dryRun, retroShip });
912
1052
  break;
@@ -930,6 +1070,22 @@ async function main() {
930
1070
  else result = await commands.runMemberRemove(o.dir, { login: who ?? null, reason: o.reason ?? null });
931
1071
  break;
932
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
+ }
933
1089
  case 'standup': {
934
1090
  // E132. Read-only; every flag that is not standup's own is refused, as history refuses them.
935
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);