yadflow 4.8.0 → 4.10.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 (107) hide show
  1. package/CHANGELOG.md +114 -0
  2. package/README.md +4 -3
  3. package/bin/commands.mjs +7 -0
  4. package/bin/yad.mjs +123 -8
  5. package/cli/agent-guard.mjs +793 -65
  6. package/cli/agent-rules.mjs +40 -5
  7. package/cli/argv-flags.mjs +1 -1
  8. package/cli/build.mjs +1 -1
  9. package/cli/ci-check.mjs +45 -1
  10. package/cli/codeowners-command.mjs +72 -6
  11. package/cli/commit.mjs +17 -3
  12. package/cli/docs.mjs +2 -0
  13. package/cli/doctor.mjs +176 -12
  14. package/cli/epic-state.mjs +94 -4
  15. package/cli/epic.mjs +11 -7
  16. package/cli/fold.mjs +31 -6
  17. package/cli/guide.mjs +3 -1
  18. package/cli/hook.mjs +50 -7
  19. package/cli/issue-links.mjs +61 -0
  20. package/cli/issues-act.mjs +327 -0
  21. package/cli/issues-write.mjs +428 -0
  22. package/cli/issues.mjs +474 -0
  23. package/cli/lifecycle.mjs +7 -0
  24. package/cli/machine.mjs +141 -0
  25. package/cli/manifest.mjs +9 -3
  26. package/cli/openpr.mjs +69 -9
  27. package/cli/plan.mjs +2 -0
  28. package/cli/platform.mjs +157 -2
  29. package/cli/preview.mjs +253 -0
  30. package/cli/protection.mjs +21 -3
  31. package/cli/reconcile.mjs +1 -1
  32. package/cli/repo.mjs +64 -3
  33. package/cli/review.mjs +4 -0
  34. package/cli/run-checks.mjs +10 -2
  35. package/cli/scan.mjs +314 -0
  36. package/cli/setup.mjs +12 -3
  37. package/cli/standup.mjs +33 -7
  38. package/cli/story-frames.mjs +307 -0
  39. package/cli/test-agents-file.mjs +378 -11
  40. package/cli/test-build.mjs +25 -0
  41. package/cli/test-ci-check.mjs +469 -10
  42. package/cli/test-guide.mjs +7 -0
  43. package/cli/test-machine.mjs +140 -0
  44. package/cli/test-node.mjs +15 -0
  45. package/cli/test-preview.mjs +511 -0
  46. package/cli/test-run-checks.mjs +17 -0
  47. package/cli/test-setup-agent.mjs +14 -0
  48. package/cli/test-story-frames.mjs +409 -0
  49. package/cli/toolbox-connect.mjs +244 -0
  50. package/cli/toolbox.mjs +159 -5
  51. package/package.json +7 -3
  52. package/skills/sdlc/config.yaml +1 -1
  53. package/skills/sdlc/module-help.csv +3 -1
  54. package/skills/yad-analysis/SKILL.md +4 -0
  55. package/skills/yad-backfill/SKILL.md +4 -0
  56. package/skills/yad-change/SKILL.md +4 -0
  57. package/skills/yad-checks/SKILL.md +13 -7
  58. package/skills/yad-checks/references/check-gates.md +62 -30
  59. package/skills/yad-checks/templates/checks/member-check.mjs +3 -2
  60. package/skills/yad-checks/templates/checks/risk-map-check.sh +2 -2
  61. package/skills/yad-checks/templates/checks/verified-commits.sh +3 -3
  62. package/skills/yad-checks/templates/github/yad-checks.yml +357 -69
  63. package/skills/yad-checks/templates/github/yad-pr-text.yml +118 -0
  64. package/skills/yad-checks/templates/github/yad-product-checks.yml +130 -54
  65. package/skills/yad-checks/templates/github/yad-product-pr-text.yml +131 -0
  66. package/skills/yad-checks/templates/github/yad-update-guard.yml +2 -1
  67. package/skills/yad-checks/templates/github/yad-verified-commits.yml +49 -3
  68. package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml +79 -20
  69. package/skills/yad-checks/templates/gitlab/yad-product-checks.gitlab-ci.yml +59 -9
  70. package/skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml +1 -0
  71. package/skills/yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml +49 -1
  72. package/skills/yad-checks/templates/hooks/agent-guard.mjs +44 -10
  73. package/skills/yad-checks/templates/hooks/ledger-guard-cursor.mjs +12 -6
  74. package/skills/yad-commit/SKILL.md +3 -1
  75. package/skills/yad-connect-design/SKILL.md +48 -13
  76. package/skills/yad-connect-design/references/design-context.md +56 -3
  77. package/skills/yad-connect-design/references/design-registry.md +4 -4
  78. package/skills/yad-connect-learning/SKILL.md +12 -2
  79. package/skills/yad-connect-repos/SKILL.md +12 -0
  80. package/skills/yad-connect-testing/SKILL.md +22 -5
  81. package/skills/yad-connect-testing/references/testing-context.md +1 -1
  82. package/skills/yad-engineer-review/SKILL.md +13 -0
  83. package/skills/yad-epic/SKILL.md +4 -0
  84. package/skills/yad-epic/references/state-schema.md +21 -0
  85. package/skills/yad-guide/SKILL.md +8 -4
  86. package/skills/yad-implement/SKILL.md +69 -3
  87. package/skills/yad-implement/references/implement-conventions.md +2 -1
  88. package/skills/yad-issues/SKILL.md +53 -0
  89. package/skills/yad-learn/SKILL.md +4 -0
  90. package/skills/yad-open-pr/SKILL.md +10 -1
  91. package/skills/yad-pair-review/SKILL.md +5 -0
  92. package/skills/yad-pr-template/SKILL.md +2 -1
  93. package/skills/yad-pr-template/templates/checks/pr-title.sh +34 -2
  94. package/skills/yad-pr-template/templates/github/pull_request_template.md +1 -0
  95. package/skills/yad-pr-template/templates/gitlab/merge_request_templates/Default.md +1 -0
  96. package/skills/yad-product-bridge/references/bridge.md +28 -0
  97. package/skills/yad-product-bridge/templates/github/yad-gate-sync.yml +25 -11
  98. package/skills/yad-product-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml +38 -14
  99. package/skills/yad-review-companion/SKILL.md +4 -1
  100. package/skills/yad-run/SKILL.md +5 -0
  101. package/skills/yad-scan/SKILL.md +51 -0
  102. package/skills/yad-spec/SKILL.md +32 -0
  103. package/skills/yad-stories/SKILL.md +22 -0
  104. package/skills/yad-stories/references/story-schema.md +1 -0
  105. package/skills/yad-test-cases/SKILL.md +18 -2
  106. package/skills/yad-ui/SKILL.md +48 -8
  107. package/skills/yad-checks/templates/gitlab/.gitlab-ci.yml +0 -49
package/CHANGELOG.md CHANGED
@@ -1,3 +1,117 @@
1
+ # [4.10.0](https://github.com/abdelrahmannasr/yadflow/compare/v4.9.0...v4.10.0) (2026-11-10)
2
+
3
+
4
+ ### Bug Fixes
5
+
6
+ * **agent-guard:** judge the CR-dropping reading at every depth, not only the raw line ([#353](https://github.com/abdelrahmannasr/yadflow/issues/353)) ([5a6d912](https://github.com/abdelrahmannasr/yadflow/commit/5a6d912b5ad9ac9772c7c6c6e904820c6d267ad5))
7
+ * **agent-guard:** keep reading a CRLF heredoc's end line as before, and never pre-approve more secret-bearing paths ([#353](https://github.com/abdelrahmannasr/yadflow/issues/353)) ([d8a5a09](https://github.com/abdelrahmannasr/yadflow/commit/d8a5a09a81b068752d14b61e4d76b74ca65eab77))
8
+ * **agent-guard:** never pre-approve what the shell expands, shortened git options, -R, jq -f or gh --cache ([#353](https://github.com/abdelrahmannasr/yadflow/issues/353)) ([1d784ac](https://github.com/abdelrahmannasr/yadflow/commit/1d784ac903e47dddf74c360364b89f0b27b208f6))
9
+ * **agent-guard:** no comment exception, and only space, tab and newline break words ([#353](https://github.com/abdelrahmannasr/yadflow/issues/353)) ([c5869ef](https://github.com/abdelrahmannasr/yadflow/commit/c5869ef7ed3398289fa25c642a6df7a1ee861f2c))
10
+ * **agent-guard:** read \\ + CR + LF and a CR on a heredoc's end line as bash and zsh do ([#353](https://github.com/abdelrahmannasr/yadflow/issues/353)) ([20391d0](https://github.com/abdelrahmannasr/yadflow/commit/20391d0b845392e573378a711aba61cc751528df))
11
+ * **agent-guard:** refuse a \\-CRLF line under either reading; decode an API path before testing its parts ([#353](https://github.com/abdelrahmannasr/yadflow/issues/353)) ([561a102](https://github.com/abdelrahmannasr/yadflow/commit/561a10222d3a09686a5e4905f6f8dd105a2c1996))
12
+ * **agent-guard:** unquoted text is held to an allow list of characters; git diff paths inside the project ([#353](https://github.com/abdelrahmannasr/yadflow/issues/353)) ([9fec042](https://github.com/abdelrahmannasr/yadflow/commit/9fec042a45f84dcf777f6798db11beeeee8f52e1))
13
+ * **ci-check:** review 1 — the merge queue is read through GraphQL, an unreported merge-train setting is not known, and the new rows are listed when nothing can be read ([#433](https://github.com/abdelrahmannasr/yadflow/issues/433)) ([4812250](https://github.com/abdelrahmannasr/yadflow/commit/4812250f4b82ceb8a0ce513e6213ee6bcda75acd))
14
+ * **ci-check:** review 2 — the merge-queue query sends the names as plain strings ([#433](https://github.com/abdelrahmannasr/yadflow/issues/433)) ([e599f47](https://github.com/abdelrahmannasr/yadflow/commit/e599f47e53c1534fc8eca620a5626b78cf9be00e))
15
+ * **ci-check:** yad ci check warns when the merge queue or merge trains are on, and reports the other merge settings ([#433](https://github.com/abdelrahmannasr/yadflow/issues/433)) ([237da2c](https://github.com/abdelrahmannasr/yadflow/commit/237da2c54167a6dc90e22d78235b8f72abea634f))
16
+ * **ci:** an edit of the PR text never re-runs the gate jobs, so a skipped gate cannot turn a failed one green ([#425](https://github.com/abdelrahmannasr/yadflow/issues/425)) ([207c6a1](https://github.com/abdelrahmannasr/yadflow/commit/207c6a1a515848255e20c83bc8a6874b46bc1aa8))
17
+ * **ci:** every CI job yad installs, and every job here, stops after a set time ([#424](https://github.com/abdelrahmannasr/yadflow/issues/424)) ([b6d45c7](https://github.com/abdelrahmannasr/yadflow/commit/b6d45c76b5c3b6768d1823e63f0c2ffa37ef5bd5)), closes [#420](https://github.com/abdelrahmannasr/yadflow/issues/420)
18
+ * **ci:** every gate job runs the base branch's checks/, never the PR's own, and keeps no token in the checkout ([#426](https://github.com/abdelrahmannasr/yadflow/issues/426)) ([b4c92e6](https://github.com/abdelrahmannasr/yadflow/commit/b4c92e6b6b2ac93c1da548a12b79141bf7fd170f))
19
+ * **ci:** GitLab gate-sync checks glab and jq against a pinned SHA-256 before installing them ([#431](https://github.com/abdelrahmannasr/yadflow/issues/431)) ([c521f13](https://github.com/abdelrahmannasr/yadflow/commit/c521f1302a4be6e4e4e70aa2f3bfdef017317ea6)), closes [#327](https://github.com/abdelrahmannasr/yadflow/issues/327)
20
+ * **ci:** review 1 — every CI file needs an owner, a code owner guards the merge not the run, GitLab keeps the host's before_script ([#426](https://github.com/abdelrahmannasr/yadflow/issues/426)) ([2838ccb](https://github.com/abdelrahmannasr/yadflow/commit/2838ccb6dc744e30567b9afccdbc9f6d0cbbd00b))
21
+ * **ci:** review 1 — tests read the Product's diff lines from yad-product-pr-text.yml; the doctor hint and the gate reference follow the move ([#425](https://github.com/abdelrahmannasr/yadflow/issues/425)) ([f072be7](https://github.com/abdelrahmannasr/yadflow/commit/f072be7452d238e9654cb5b4ad3cc2b277eab748))
22
+ * **ci:** review 1 — the chain comment says the install is skipped, not run; the test refuses any download not saved with -o ([#431](https://github.com/abdelrahmannasr/yadflow/issues/431)) ([8077636](https://github.com/abdelrahmannasr/yadflow/commit/8077636f5c29b52d297871a55a892ecf3c0331af))
23
+ * **ci:** review 1 — the docs say what yad update does to an edited limit; the test reads this repo's workflows and odd job names ([#424](https://github.com/abdelrahmannasr/yadflow/issues/424)) ([6b46910](https://github.com/abdelrahmannasr/yadflow/commit/6b46910c6c63097b2ae0ea5e201acd5bb215a8c3))
24
+ * **ci:** review 1 — the PR-text group names the commit, and the docs say what a cancel can block ([#428](https://github.com/abdelrahmannasr/yadflow/issues/428)) ([49e0cd6](https://github.com/abdelrahmannasr/yadflow/commit/49e0cd65f645990dde5c55ee7f8943a81e3e8622))
25
+ * **ci:** review 2 — control characters swapped the same in any locale; the gate-file warning only where yad's gates are installed ([#426](https://github.com/abdelrahmannasr/yadflow/issues/426)) ([0446802](https://github.com/abdelrahmannasr/yadflow/commit/0446802e34832d99873faefc1c99b7ceaad2932b))
26
+ * **ci:** review 2 — the docs name which runs each file cancels and how to add the GitLab rule safely; a job's own interruptible: false fails the test ([#428](https://github.com/abdelrahmannasr/yadflow/issues/428)) ([b229fd7](https://github.com/abdelrahmannasr/yadflow/commit/b229fd7e27f8f2d8eb73a1c7fa9dfe7dd535db83))
27
+ * **ci:** the CI templates pin the same action versions as the repo — checkout v7.0.1, setup-node v7.1.0, cache v6.1.0 ([#429](https://github.com/abdelrahmannasr/yadflow/issues/429)) ([96cbfe9](https://github.com/abdelrahmannasr/yadflow/commit/96cbfe9688efb1fd062cf007f97c5ca9df8b038d))
28
+ * **ci:** the PR gate files cancel their older run; GitLab's merge request jobs are interruptible ([#428](https://github.com/abdelrahmannasr/yadflow/issues/428)) ([e9e255d](https://github.com/abdelrahmannasr/yadflow/commit/e9e255d1f14eb742d716ceadd19ac9778d4a6203))
29
+ * **doctor:** review 1 — the rows say what was recorded, the hint covers a signed-out or closed tool, and the connect-tool rule names doctor (E165 follow-up) ([03d433c](https://github.com/abdelrahmannasr/yadflow/commit/03d433c2e76ca3d4b79055bb5c93b39df597ad1a))
30
+ * **doctor:** review 2 — the hint asks that the tool can be reached, not that it has an app to open, so it fits a CLI tool too (E165 follow-up) ([3a45a8b](https://github.com/abdelrahmannasr/yadflow/commit/3a45a8be21cbb5ff740e2c9e80d045e3e7064ae8))
31
+ * **doctor:** the design, testing and learning refresh hints name the tool and its connect command (E165 follow-up) ([051fd19](https://github.com/abdelrahmannasr/yadflow/commit/051fd192e45bb8997cc5c607c435f946582766c1))
32
+ * **frames:** review 1 — with no provider, OpenPencil's check tries the CLI, then the MCP, as its stop text says (E164) ([6888ebd](https://github.com/abdelrahmannasr/yadflow/commit/6888ebd1b2e576fc8a0de0833b21363d101a5043))
33
+ * **frames:** review 2 — with no provider, the check falls back to the MCP whenever the CLI does not find the frame (E164) ([786ac04](https://github.com/abdelrahmannasr/yadflow/commit/786ac04feb57f695e4339fc14b1dc2d2d3d52521))
34
+ * **gate:** review 1 — the UI design's fingerprint skips junk, links and nested repos, reads LFS pointers, and drops the doc-only pass (E164) ([40d7f81](https://github.com/abdelrahmannasr/yadflow/commit/40d7f817c4d4b641d0790268d2be576dd0ae5d6b))
35
+ * **gate:** review 2 — only the exact LFS pointer format counts, the junk list is named, and a nested repo is never folded (E164) ([5f27c3f](https://github.com/abdelrahmannasr/yadflow/commit/5f27c3fbb19b2421c51aa93eba229376e16d8c6f))
36
+ * **gate:** review 3 — a git-ignored design file is not counted on disk, and a committed submodule is never folded (E164) ([c06c221](https://github.com/abdelrahmannasr/yadflow/commit/c06c221d298337e09a7f7b9c8891838053285373))
37
+ * **gate:** review 4 — the ignore check finds git from the folder, never runs on a commit's scratch copy, and fold sees an uninitialised submodule (E164) ([994a5b8](https://github.com/abdelrahmannasr/yadflow/commit/994a5b86a35e9c644f678ff92f76eef059efb789))
38
+ * **gates:** pr-title ignores a GitLab draft marker in the title ([#451](https://github.com/abdelrahmannasr/yadflow/issues/451)) ([6a34f4b](https://github.com/abdelrahmannasr/yadflow/commit/6a34f4b257f2ee2e1137c0e309b86e39900cc8b2)), closes [#426](https://github.com/abdelrahmannasr/yadflow/issues/426)
39
+ * **gates:** review 1 — match the draft mark by pattern, not tr; docs say a GitLab title edit starts no pipeline, and why the mark is ignored ([#451](https://github.com/abdelrahmannasr/yadflow/issues/451)) ([17ff8e8](https://github.com/abdelrahmannasr/yadflow/commit/17ff8e81530683659504b04039a3885f8b31db5b))
40
+ * **hooks:** read the payload even when the pipe is not ready, and exit only after the verdict is written (macOS) ([5cc3087](https://github.com/abdelrahmannasr/yadflow/commit/5cc30879935528985e260c5c28ee6f85a19563b0))
41
+ * **hooks:** review 1 — name the real cause: asking process.stdin.isTTY makes stdin non-blocking; the last write-then-exit goes (macOS) ([82f00eb](https://github.com/abdelrahmannasr/yadflow/commit/82f00ebbef130edbeb884edbedde52237ee9445a)), closes [#459](https://github.com/abdelrahmannasr/yadflow/issues/459) [#460](https://github.com/abdelrahmannasr/yadflow/issues/460)
42
+ * **open-pr:** review 1 — only other tasks' commits count, so a teammate's branch is never named; main merged in is still found; a real --via auto test ([#450](https://github.com/abdelrahmannasr/yadflow/issues/450)) ([e1f38fd](https://github.com/abdelrahmannasr/yadflow/commit/e1f38fd0166b205503237b495cb2b6a3d1d64a38))
43
+ * **open-pr:** review 2 — a branch holding this task's own commit is a teammate's copy, never named, even when cut from develop ([#450](https://github.com/abdelrahmannasr/yadflow/issues/450)) ([32d76d1](https://github.com/abdelrahmannasr/yadflow/commit/32d76d16a99239adb69eac884088866d2668ea2d))
44
+ * **open-pr:** review 3 — name every branch that could be the fork, most likely first, and let the person pick ([#450](https://github.com/abdelrahmannasr/yadflow/issues/450)) ([664a0ab](https://github.com/abdelrahmannasr/yadflow/commit/664a0ab31265ff9a37e9830545b2e25bfce5f422)), closes [#350](https://github.com/abdelrahmannasr/yadflow/issues/350)
45
+ * **open-pr:** review 4 — list the possible bases in the form each command's --base takes, so one can be copied as it is ([#450](https://github.com/abdelrahmannasr/yadflow/issues/450)) ([cc94fff](https://github.com/abdelrahmannasr/yadflow/commit/cc94fffb2c03d6f05bcdacf0168a0206ebd2e188))
46
+ * **open-pr:** stop before pushing when the branch was cut from another branch and no base was chosen ([#450](https://github.com/abdelrahmannasr/yadflow/issues/450)) ([eba292a](https://github.com/abdelrahmannasr/yadflow/commit/eba292a8052c3e369ddcb3249a6452f48acde474))
47
+ * **run-checks:** warn once when the branch was cut from another branch and no base was chosen ([#450](https://github.com/abdelrahmannasr/yadflow/issues/450)) ([7c7c07b](https://github.com/abdelrahmannasr/yadflow/commit/7c7c07bdec5640b7d1df2b8835ed8dac389e5fb7))
48
+ * **skills:** review 2 — the first OpenPencil file comes from import, the hand commit has a gate-ready message, and the MCP-only rules name the CLI exception (E164) ([0688503](https://github.com/abdelrahmannasr/yadflow/commit/06885036f31b35c85564a9a1edbc3bcf7ab462cd))
49
+ * **toolbox:** review 1 — --verify only after the yes, and --replace to change the team's tool; MCP servers for the user account, cmd /c on Windows (E165) ([92091ae](https://github.com/abdelrahmannasr/yadflow/commit/92091aefdf39e338d48c28fc3a9f29890a886944))
50
+ * **toolbox:** review 1 — offer only a missing tool, refresh the connection after a connect, no hosted recipe for Figma's desktop server (E165) ([af28e07](https://github.com/abdelrahmannasr/yadflow/commit/af28e07bdc83e6ce49b180309bef67253a8aa741))
51
+ * **toolbox:** review 1 — OpenPencil's MCP needs its desktop app; yad-ui writes through the CLI first, into the epic's design/ folder (E164) ([8c64c3f](https://github.com/abdelrahmannasr/yadflow/commit/8c64c3f55f001eb73b53e76ef10a691bdec693ab))
52
+ * **toolbox:** review 1 — the node-ID script reads frames the skills' way, runs npm without a shell, and cleans up on every exit (E164) ([9fdcdd7](https://github.com/abdelrahmannasr/yadflow/commit/9fdcdd7a2e5977b042887befc68ce18ab3a51417))
53
+ * **toolbox:** review 2 — a server just added is seen after the agent restarts: say so, never record it unavailable (E165) ([338bdb3](https://github.com/abdelrahmannasr/yadflow/commit/338bdb333e8f194a8955acbc7d21d39e1f4f806f))
54
+ * **toolbox:** review 2 — the node-ID script takes only npm-cli.js, says "stopped" on Ctrl-C, and words what it withholds exactly (E164) ([ecdd606](https://github.com/abdelrahmannasr/yadflow/commit/ecdd6068d87fbc2539edb79fa2c66fbd2d0ecbc0))
55
+ * **toolbox:** review 2 — the person block's verify carries --replace too, and a tool name in other letters is not a replacement (E165) ([c5e4d80](https://github.com/abdelrahmannasr/yadflow/commit/c5e4d80abecb5d22cf4f44d85387ade68ea9ca1e))
56
+ * **toolbox:** review 3 — check the tool is reachable before the refresh; the CLI path and the connect skills too (E165) ([173241d](https://github.com/abdelrahmannasr/yadflow/commit/173241dc852807eaea7403dc8cdd8d4af524203d))
57
+ * **toolbox:** review 3 — the node-ID script says "stopped" on Ctrl-C during an openpencil run too (E164) ([8ec6d59](https://github.com/abdelrahmannasr/yadflow/commit/8ec6d59d75add1c316af5ad8bb20cc2fcb87de49))
58
+ * **toolbox:** review 4 — the restart branch writes nothing and skips Step 2; after a restart, refresh first (E165) ([1d88aa0](https://github.com/abdelrahmannasr/yadflow/commit/1d88aa072da0399e7c25e35add9a71a3d281c51d))
59
+ * **toolbox:** review 5 — the connect skills record what they find when the tool is reachable; the report fits the restart case (E165) ([adf1841](https://github.com/abdelrahmannasr/yadflow/commit/adf1841c484161f82b6a79746412c3d88242d34f))
60
+ * **toolbox:** review 6 — every refresh after a connect names the same tool, so it never checks the default one (E165) ([671fe0e](https://github.com/abdelrahmannasr/yadflow/commit/671fe0e99f555be427dc3fb8e585796ede47d564))
61
+ * **toolbox:** the node-ID script hands OpenPencil fixed code, nothing pasted in — CodeQL js/bad-code-sanitization (E164) ([f1f1ab0](https://github.com/abdelrahmannasr/yadflow/commit/f1f1ab00cc6ae7761c245b5db77cd742c0fe3803))
62
+
63
+
64
+ ### Features
65
+
66
+ * **agent-guard:** pre-approve read-only command lines — API GETs, git reads, jq, unchanged read gates ([#353](https://github.com/abdelrahmannasr/yadflow/issues/353)) ([a41880f](https://github.com/abdelrahmannasr/yadflow/commit/a41880f66086db3faf0e1bc609201f44ff8c5ca8))
67
+ * **agent:** the connect-tool rule — ask once with the command's own question, run only its agent steps, hand over the rest, then verify (E165) ([093213a](https://github.com/abdelrahmannasr/yadflow/commit/093213a4d9f397c41ee09157491aa59c013e161d))
68
+ * **agent:** the connect-tool rule names where an offer comes from — a toolbox finding's or a preflight's `connect`, or a skill; one tool, one question (E165) ([cdee8f5](https://github.com/abdelrahmannasr/yadflow/commit/cdee8f5ab5b882c7252b24df42ebe7a26bda8a13))
69
+ * an issue or work item seeds and links an epic (E170) ([#502](https://github.com/abdelrahmannasr/yadflow/issues/502)) ([fd169a1](https://github.com/abdelrahmannasr/yadflow/commit/fd169a18a77955936b4f92d71acb42fd754692a9)), closes [#501](https://github.com/abdelrahmannasr/yadflow/issues/501)
70
+ * **codeowners:** warn when checks/ and yad's CI files have no code owner whose review can be required ([#426](https://github.com/abdelrahmannasr/yadflow/issues/426)) ([e83699d](https://github.com/abdelrahmannasr/yadflow/commit/e83699d9857407fd864b17cec5f057cbc9fd4890))
71
+ * every implementation is scanned, and the findings are filed (E172) ([#504](https://github.com/abdelrahmannasr/yadflow/issues/504)) ([7bd2bfe](https://github.com/abdelrahmannasr/yadflow/commit/7bd2bfe27417237f84578acd6f981b472adb0513))
72
+ * **frames:** the design preflight checks OpenPencil — its CLI needs no app and no sign-in (E164) ([e226b7c](https://github.com/abdelrahmannasr/yadflow/commit/e226b7cfcc973c3cfa03ac76b7d22fc9907fa8dd)), closes [#358](https://github.com/abdelrahmannasr/yadflow/issues/358)
73
+ * **frames:** the design preflight names the connect command — for a tool not on this machine at all (E165) ([54f595a](https://github.com/abdelrahmannasr/yadflow/commit/54f595aa2594f2f219f6f167a87718b488c23ee6))
74
+ * **gate:** the UI review covers the epic's design/ folder — fold commits it, a change revokes (E164) ([8cd9f3a](https://github.com/abdelrahmannasr/yadflow/commit/8cd9f3a671094b8ccc617c46b4604ff6789bec66))
75
+ * linked items follow their epics, standup lists them, agents know them (E171) ([#503](https://github.com/abdelrahmannasr/yadflow/issues/503)) ([2428727](https://github.com/abdelrahmannasr/yadflow/commit/24287278c4d964975d96c8300717b2e17bf7f21b))
76
+ * read GitHub issues and GitLab work items, with an HTML report (E169) ([#501](https://github.com/abdelrahmannasr/yadflow/issues/501)) ([6849016](https://github.com/abdelrahmannasr/yadflow/commit/6849016594387356e3c44d43decac9dd59d0eaad))
77
+ * **setup:** show what the agent guard pre-approves, and give it to agents in yad guide ([#353](https://github.com/abdelrahmannasr/yadflow/issues/353)) ([81d41f9](https://github.com/abdelrahmannasr/yadflow/commit/81d41f9a1a33f87b91af9190a0fece469d6c229a))
78
+ * the agent acts on issues and work items when an engineer asks (E173) ([#506](https://github.com/abdelrahmannasr/yadflow/issues/506)) ([2324502](https://github.com/abdelrahmannasr/yadflow/commit/2324502bebfb4da8358428c5a7e4a40759dfa048))
79
+ * **toolbox:** OpenPencil as a third design tool — vetted, MCP and CLI pinned to 0.16.0 (E164) ([9a3453a](https://github.com/abdelrahmannasr/yadflow/commit/9a3453a37f0448ac290e882c55980d4b75108235)), closes [#358](https://github.com/abdelrahmannasr/yadflow/issues/358)
80
+ * **toolbox:** setup, check, update and join offer to connect a tool — `connect` on each finding (E165) ([9756639](https://github.com/abdelrahmannasr/yadflow/commit/97566399d653e0cd4f27fc410bc21742da93f80a))
81
+ * **toolbox:** yad toolbox connect — what the agent may run to connect a tool, after one yes; --verify records the team's choice (E165) ([bd6fd10](https://github.com/abdelrahmannasr/yadflow/commit/bd6fd10793569b4de66f69dc752d6af6edb5a0a9))
82
+
83
+
84
+ ### Performance Improvements
85
+
86
+ * **fold:** review 5 — the index's gitlinks are read once per fold, not once per design file; a literal-pathspec setting cannot hide them (E164) ([ce2a894](https://github.com/abdelrahmannasr/yadflow/commit/ce2a894a9a4e3f8b1b8cdf5d78b6035d987b095a))
87
+
88
+ # [4.9.0](https://github.com/abdelrahmannasr/yadflow/compare/v4.8.0...v4.9.0) (2026-11-04)
89
+
90
+
91
+ ### Bug Fixes
92
+
93
+ * **doctor:** [#352](https://github.com/abdelrahmannasr/yadflow/issues/352) review 1 — '>22' and '>= 22' read as npm reads them, glab duplicates only where glab looks, repo text cleaned, one Node row per folder ([5474a05](https://github.com/abdelrahmannasr/yadflow/commit/5474a052012a1bf7e2322d53e998654e171bb90f))
94
+ * **doctor:** [#352](https://github.com/abdelrahmannasr/yadflow/issues/352) review 2 — look for glab's config only where glab is known to look on Windows ([35b9d67](https://github.com/abdelrahmannasr/yadflow/commit/35b9d67a93f5b7639f07492ac7bd63f503265134))
95
+ * **preview:** review 1 — a {branch} pattern never fills from the wrong branch, one hard time budget, no false 'none recorded' ([#359](https://github.com/abdelrahmannasr/yadflow/issues/359)) ([d1688b0](https://github.com/abdelrahmannasr/yadflow/commit/d1688b0d23d9b88f6709b7a9921091e760b49f86))
96
+ * **preview:** review 2 — the Preview line is set before the summary, GitLab environments asked for their state, the default branch is no PR's ([#359](https://github.com/abdelrahmannasr/yadflow/issues/359)) ([aa8b8b7](https://github.com/abdelrahmannasr/yadflow/commit/aa8b8b7b56222a2f9047691a3f7019ad30e44d94))
97
+ * **preview:** review 3 — one next step in the why, GitLab merge-request pipeline deployments count ([#359](https://github.com/abdelrahmannasr/yadflow/issues/359)) ([98089df](https://github.com/abdelrahmannasr/yadflow/commit/98089dfeebc7ca590b71c883208f4bace61d178d))
98
+ * **preview:** review 4 — GitLab without --pr and a non-number --pr both say pass --pr; the MR ref counts with no source branch ([#359](https://github.com/abdelrahmannasr/yadflow/issues/359)) ([86d65ae](https://github.com/abdelrahmannasr/yadflow/commit/86d65aea2a8b47d7f4a6fa3a2b3b3ec35534b8d2))
99
+ * **preview:** review 5 — a broken pattern is named before --pr on GitLab, and --pr is never offered for a GitLab that cannot be asked ([#359](https://github.com/abdelrahmannasr/yadflow/issues/359)) ([04c4379](https://github.com/abdelrahmannasr/yadflow/commit/04c43798e2d6b4e97f7c6e4b5f27047fa654f55d))
100
+ * **preview:** review 6 — the GitLab MR-pipeline step reads a flag, not the wording ([#359](https://github.com/abdelrahmannasr/yadflow/issues/359)) ([42fa00d](https://github.com/abdelrahmannasr/yadflow/commit/42fa00d8779f655eaeada77082c60ca02d3d25bd))
101
+ * **story:** review 1 — the preflight never stops a person for the wrong reason ([#358](https://github.com/abdelrahmannasr/yadflow/issues/358)) ([5dcd98b](https://github.com/abdelrahmannasr/yadflow/commit/5dcd98b3244309b7ce2bb4a72c6504c357cf91eb))
102
+ * **story:** review 1 — Windows line endings, misspelled keys and odd story files never read as "no frames" ([#354](https://github.com/abdelrahmannasr/yadflow/issues/354)) ([b130a56](https://github.com/abdelrahmannasr/yadflow/commit/b130a56c397d2ee6851ff9264bb93e950633eb2c))
103
+ * **story:** review 2 — doctor follows symlinks like the command; a second, misspelled key is said ([#354](https://github.com/abdelrahmannasr/yadflow/issues/354)) ([c4a0570](https://github.com/abdelrahmannasr/yadflow/commit/c4a0570db90c28ec59d8d931fb81555ac450615c))
104
+ * **story:** review 2 — frames of another tool, unknown MCP ids and a missing design-links.json never stop a person wrongly ([#358](https://github.com/abdelrahmannasr/yadflow/issues/358)) ([041c368](https://github.com/abdelrahmannasr/yadflow/commit/041c36867198a62843f4daf643b366f910e632d1))
105
+ * **story:** review 3 — provider and tool names compared on their letters and digits ([#358](https://github.com/abdelrahmannasr/yadflow/issues/358)) ([edd1145](https://github.com/abdelrahmannasr/yadflow/commit/edd1145833792700a787b5c0795ddf441364321b))
106
+
107
+
108
+ ### Features
109
+
110
+ * **doctor:** [#352](https://github.com/abdelrahmannasr/yadflow/issues/352) — check the machine: the Node each repo pins, Docker where a repo asks for it, duplicate glab config files ([fdabafc](https://github.com/abdelrahmannasr/yadflow/commit/fdabafc166d8fce0216023c885650b6362ca1de6))
111
+ * **repo:** a preview address per PR/MR for live design checks ([#359](https://github.com/abdelrahmannasr/yadflow/issues/359)) ([225b646](https://github.com/abdelrahmannasr/yadflow/commit/225b646bbed8fd1422368279e2c03e1c348a95c5))
112
+ * **story:** yad story frames reads a story's design frames; doctor warns on any it cannot read ([#354](https://github.com/abdelrahmannasr/yadflow/issues/354)) ([fda0a46](https://github.com/abdelrahmannasr/yadflow/commit/fda0a468b9c7213b308ad60bcabd653fd5bf231d))
113
+ * **story:** yad story frames says how to check the design tool can be reached ([#358](https://github.com/abdelrahmannasr/yadflow/issues/358)) ([dd9bd94](https://github.com/abdelrahmannasr/yadflow/commit/dd9bd94c0a35b62e62416c9b5999c966de4bccb6))
114
+
1
115
  # [4.8.0](https://github.com/abdelrahmannasr/yadflow/compare/v4.7.0...v4.8.0) (2026-11-02)
2
116
 
3
117
 
package/README.md CHANGED
@@ -17,7 +17,7 @@ where it matters.
17
17
 
18
18
  - **The `yad` command-line tool.** It is written in Node and has no dependencies. It sets up a
19
19
  project, tells you the next action, runs reviews, and reads the project history.
20
- - **39 workflow skills.** A skill is a set of instructions that your AI assistant loads for one task,
20
+ - **41 workflow skills.** A skill is a set of instructions that your AI assistant loads for one task,
21
21
  such as "write the architecture". The skills run in Claude Code, Codex CLI, Cursor, Gemini CLI,
22
22
  GitHub Copilot, Zencoder and opencode.
23
23
  - **Plain files in git.** Every plan, decision, approval and link lives as a readable file in a
@@ -298,8 +298,9 @@ The record is worth trusting because people approve what goes into it.
298
298
  - `yad guide`, the step brief an AI coding agent reads before each step — what the step is for, whether it can be skipped, who does it, the skills that fit, what the agent runs, and what only the person can do
299
299
  - `yad status --brief`, where the work stands in about 20 lines — this checkout's task, each open epic's next action, your open PRs/MRs and what is owed — for picking up after a break or an AI context reset
300
300
  - `yad standup`, a daily status for each team member — what they did since the last working day, what they are on now, and what is waiting — rebuilt live from git, the ledgers and the platform, facts only
301
+ - `yad issues`, the team's GitHub issues and GitLab issues and tasks, with priority, type, status and assignee, as a list or an HTML page you can sort and filter. Items link to epics, update from epic status, and appear in `yad standup`. Ask the agent to open, assign, label, edit, comment on, close or reopen an item, and it does. `yad-run` and `yad-implement` also scan each implementation and file security findings, technical debt and suggestions there
301
302
  - `yad detect`, which lists the skills, agents, MCP servers and plugins installed for each AI agent
302
- - `yad toolbox list`, which shows the external tools yadflow can use, which ones you have, and what happens without each; `yad toolbox add` / `remove` record the tools your team uses, and `yad toolbox check` lists the ones not ready on your machine (`yad setup`, `check`, `update` and `join` print the same list, and never install anything); each skill that uses a tool reads the same answer and says what it does without it
303
+ - `yad toolbox list`, which shows the external tools yadflow can use, which ones you have, and what happens without each; `yad toolbox add` / `remove` record the tools your team uses, and `yad toolbox check` lists the ones not ready on your machine (`yad setup`, `check`, `update` and `join` print the same list, and never install anything without asking: your agent can connect a tool after one yes, with `yad toolbox connect`); each skill that uses a tool reads the same answer and says what it does without it
303
304
  - `yad skill recommend`, which lists hand-picked skills from the recommended skill collections for each step, why each fits, and the command to bind one; it binds nothing, and every pick was checked against its source
304
305
  - draft saving, claims and owners
305
306
  - the CI checks
@@ -323,7 +324,7 @@ The record is worth trusting because people approve what goes into it.
323
324
  - [working together: capture, claims, owners, fold](docs/CLI.md#working-together-capture-claims-owners-and-fold)
324
325
  - [troubleshooting and error codes](docs/CLI.md#troubleshooting-yad-doctor--error-codes)
325
326
  - [every CI gate: rules, exemptions and failures](docs/GATES.md)
326
- - [all 39 skills](docs/SKILLS.md)
327
+ - [all 41 skills](docs/SKILLS.md)
327
328
  - [the by-hand walkthrough](docs/WALKTHROUGH.md)
328
329
  - **Upgrade:** [staying up to date](docs/CLI.md#staying-up-to-date) ·
329
330
  [upgrading to 4.0](docs/migrations/upgrading-to-4.md) ·
package/bin/commands.mjs CHANGED
@@ -36,14 +36,21 @@ export { runAssign, runUnassign, runOwners } from '../cli/owners.mjs';
36
36
  export { runMemberAdd, runMemberList, runMemberRemove } from '../cli/members.mjs';
37
37
  export { runWorktreeAdd, runWorktreeList, runWorktreeRemove } from '../cli/worktree.mjs';
38
38
  export { runStandup, foreignFlags as standupForeignFlags } from '../cli/standup.mjs';
39
+ export { runIssuesNew, runIssuesAssign, runIssuesLabel, runIssuesEdit, runIssuesComment, runIssuesClose, runIssuesReopen, ACT_ACTIONS, actForeignFlags } from '../cli/issues-act.mjs';
40
+ export { runScanFile } from '../cli/scan.mjs';
41
+ export { runIssuesSync, syncAfterGate } from '../cli/issues-write.mjs';
42
+ export { runIssuesShow, runIssuesLink, runIssuesUnlink, runEpicNewFromIssue, seedForeignFlags as seedForeign } from '../cli/issues-write.mjs';
43
+ export { runIssuesList, runIssuesLabels, foreignFlags as issuesForeignFlags } from '../cli/issues.mjs';
39
44
  export { runIndex } from '../cli/index-command.mjs';
40
45
  export { runHistory, HISTORY_FLAGS } from '../cli/history.mjs';
41
46
  export { runRepo } from '../cli/repo.mjs';
42
47
  export { runRiskMap } from '../cli/riskmap-command.mjs';
43
48
  export { runCodeowners } from '../cli/codeowners-command.mjs';
49
+ export { runStory } from '../cli/story-frames.mjs';
44
50
  export { runDocs } from '../cli/docs.mjs';
45
51
  export { runDetect } from '../cli/detect.mjs';
46
52
  export { runToolboxAdd, runToolboxCheck, runToolboxList, runToolboxRemove } from '../cli/toolbox.mjs';
53
+ export { runToolboxConnect } from '../cli/toolbox-connect.mjs';
47
54
  export { runDoctor } from '../cli/doctor.mjs';
48
55
  export { runSigningCheck } from '../cli/signing.mjs';
49
56
  export { runCiCheck } from '../cli/ci-check.mjs';
package/bin/yad.mjs CHANGED
@@ -133,6 +133,22 @@ ${c.bold('Team members')} ${c.dim('(identity only — no roles, no reviewers, no
133
133
  yad member remove [<login>] [--reason <why>]
134
134
  Delete a member file — your own, or anyone's with --reason
135
135
 
136
+ ${c.bold('Issues and work items')} ${c.dim('(read live from GitHub issues and GitLab issues, tasks and incidents)')}
137
+ yad issues [list] Items of the Product and every registered repo, with priority,
138
+ type, status and assignee. Filter with --priority --type --status
139
+ --assignee --me --repo --since --until --date; order with --sort.
140
+ --format html writes a page you can sort and filter; titles are
141
+ included, so check it before sharing it outside the team
142
+ yad issues labels [--dry-run] Create the predefined priority, type and status labels each repo lacks
143
+ yad scan file <f> --repo <r> File a scan's findings on the repo's tracker, by category and priority (the yad-scan skill runs it)
144
+ yad issues new --title <t> [--body-file <f>] [--type <t>] [--priority P1] [--assignee <login>|--me] [--repo <r>]
145
+ Open an issue / work item (in the Product repo unless --repo names one)
146
+ yad issues assign <ref> <login>|--me|--none · label <ref> --priority P1 --type bug
147
+ yad issues edit <ref> [--title] [--body-file] · comment <ref> --body-file <f> · close <ref> · reopen <ref>
148
+ yad issues sync [--dry-run] Update linked items: status and type labels, and close once every epic shipped
149
+ yad issues show <ref> One item in full. <ref> is 12 (Product repo) or <repo>#12
150
+ yad issues link|unlink <ref> <EP> Link an item to an epic: comments on it and sets its type and status labels
151
+
136
152
  ${c.bold('Daily standup')} ${c.dim('(derived live, read-only, facts only — no score, no ranking)')}
137
153
  yad standup Each member on the team list: done since the last standup
138
154
  (commits, approvals, comments, closed steps, ships, merged
@@ -154,6 +170,7 @@ ${c.bold('Team usage (EM adoption & behavior report)')}
154
170
  --member <name>, --format html|json|md, --repos (code commits)
155
171
 
156
172
  ${c.bold('Where am I / what next')}
173
+ yad epic new <slug> --issue <ref> Seed from an item: its label sets the type; a defect or change finds its parent or gets a stub
157
174
  yad epic new <slug> [--type <t>] [--profile <p>] [--stub] [--parent <epic> --inherits <bases>] [--json]
158
175
  Seed a new epic's lifecycle: writes its step chain from a
159
176
  profile, plus empty approval/comment ledgers and reviews/.
@@ -219,7 +236,7 @@ ${c.bold('Where am I / what next')}
219
236
  command (pool skill first, yadflow's skill last). Binds nothing
220
237
  yad toolbox list [--json] [--dir <folder>]
221
238
  The external tools yadflow can use — core (offered at setup),
222
- recommended (skill pools, Docker MCP), the connectors and
239
+ recommended (skill pools, Docker MCP, Unity MCP), the connectors and
223
240
  this project's own — whether each is found here, whether this
224
241
  project uses it, and what yadflow does without it. Installs nothing
225
242
  yad toolbox check [--json] The tools this project uses that are not ready here, each with
@@ -229,6 +246,12 @@ ${c.bold('Where am I / what next')}
229
246
  --role "<text>" --fallback "<text>" --detect <kind>:<name>[,…]
230
247
  [--install "<type>: <command>"] [--source <https URL>]
231
248
  yad toolbox remove <id> Stop using a tool in this Product, or drop one of your own
249
+ yad toolbox connect <id> [--verify [--replace]]
250
+ What putting a tool on this machine takes (E165): the steps the
251
+ agent may run after your yes (pinned installs), the ones that
252
+ are yours, and the question to ask. Runs nothing. --verify
253
+ checks it is found here, then records it as the team's choice;
254
+ --replace when that replaces the team's current tool
232
255
  yad detect [--json] [--dir <folder>] Which skills, agents, MCP servers and plugins are installed
233
256
  for the agents that work here — in this folder and in your
234
257
  home folder, and which agents read each place. Read-only;
@@ -319,6 +342,9 @@ ${c.bold('Build helpers')}
319
342
  Commit by convention (trailers, atomic guard); --body adds a
320
343
  body above the trailers; --manual is
321
344
  the door past the Product's ledger hook, reason recorded
345
+ yad story frames <story> [--json] Show the design frames a story records (its design-frames
346
+ list), with each frame's name, platform and link from the
347
+ epic's design-links.json; warns on an ID it cannot find
322
348
  yad build start <story> --repo <r> ${c.dim('(on the Product)')} Begin a story's Build lane in one repo
323
349
  yad build step <story> --repo <r> <step> in_progress|in_review|done|blocked [--reason <text>] [--run <uid>] [--via auto|human] [--task <T>]
324
350
  Move the lane's current step; done records how it closed.
@@ -421,6 +447,10 @@ ${c.bold('Build helpers')}
421
447
  yad repo refresh [name] [--push] Re-pack a stale repo (a human decision). --push commits the
422
448
  refreshed code-maps + registry as a chore(product): sync code-context … [skip ci]
423
449
  audit commit and pushes it to the Product default branch (--allow-branch to override)
450
+ yad repo preview <name> [<pattern>] [--clear]
451
+ Show, set or clear a repo's preview address pattern (#359), e.g.
452
+ 'https://pr-{pr}.myapp.dev' ({pr} {branch} {repo}). Review steps
453
+ check the live page there; with none, they say "locally only"
424
454
  yad risk-map check [repo] [--json] Warn where a code repo's .sdlc/risk-map (a risk level per
425
455
  directory, no names) has gone stale — advisory, never blocks
426
456
  yad risk-map draft [repo] Add an 'unset' line for every directory the map does not cover
@@ -487,6 +517,7 @@ ${c.bold('Environment')}
487
517
  YAD_PLATFORM_LOGIN=0 Name a record's author by git user.name; never ask gh/glab who is logged in`;
488
518
 
489
519
  const REPORT_USAGE = 'usage: yad report [-m <text>] [--kind bug|enhancement] [--json] | yad report -m <text> [--kind …] --post --confirm <value>';
520
+ const ISSUES_USAGE = 'usage: yad issues new --title <t> [--body-file <f>] [--type <t>] [--priority P0-P3] [--assignee <login>|--me] [--repo <name>] | assign <ref> <login>|--me|--none | label <ref> [--priority P0-P3] [--type <t>] | edit <ref> [--title <t>] [--body-file <f>] | comment <ref> --body-file <f> | close <ref> | reopen <ref> | show <ref> | link <ref> <EP-id> | unlink <ref> <EP-id> | sync [--dry-run] | labels [--dry-run] | [list] [--priority P0,P1] [--type bug,feature,enhancement,security,tech-debt,suggestion] [--status todo,"in progress",done] [--assignee <login>|none|--me] [--repo <name>] [--since <date>] [--until <date>] [--date created|updated|due] [--sort priority|type|status|due|updated] [--closed-since <date>|<N>d] [--format md|html] [--out <file>] [--json] | yad issues labels [--dry-run] [--json]';
490
521
  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]';
491
522
 
492
523
 
@@ -500,6 +531,7 @@ function parseArgs(argv) {
500
531
  else if (a === '--contract-change') o.contractChange = true;
501
532
  else if (a === '--manual') o.manual = true;
502
533
  else if (a === '--me') o.me = true;
534
+ else if (a === '--none') o.none = true;
503
535
  else if (a === '--no-push') o.noPush = true;
504
536
  else if (a === '--no-fetch') o.noFetch = true;
505
537
  else if (a === '--no-build') o.noBuild = true;
@@ -507,6 +539,7 @@ function parseArgs(argv) {
507
539
  else if (a === '--open-pr') o.openPr = true;
508
540
  else if (a === '--post') o.post = true;
509
541
  else if (a === '--allow-branch') o.allowBranch = true;
542
+ else if (a === '--clear') o.clear = true;
510
543
  else if (a === '--overwrite-local') o.overwriteLocal = true;
511
544
  else if (a === '--merged') o.merged = true;
512
545
  else if (a === '--ship') o.ship = true;
@@ -549,6 +582,8 @@ function parseArgs(argv) {
549
582
  // say what it means rather than relying on the absence of a flag.
550
583
  else if (a === '--preview') o.apply = false;
551
584
  else if (a === '--custom') o.custom = true;
585
+ else if (a === '--verify') o.verify = true;
586
+ else if (a === '--replace') o.replace = true;
552
587
  else if (a === '--json') o.json = true;
553
588
  else if (a === '-h' || a === '--help') o.help = true;
554
589
  else if (a === '-v' || a === '--version') o.version = true;
@@ -609,16 +644,19 @@ const ACTIONS = {
609
644
  review: { known: ['trailer', 'context', 'chat', 'cards', 'walkthrough', 'nudge', 'reconcile'] },
610
645
  tidy: { known: ['up'] },
611
646
  history: { known: ['list', 'show', 'search'], default: 'list' },
612
- repo: { known: ['list', 'refresh', 'sync', 'clone'], default: 'list' },
647
+ repo: { known: ['list', 'refresh', 'sync', 'clone', 'preview'], default: 'list' },
613
648
  'risk-map': { known: ['check', 'draft'], default: 'check' },
614
649
  codeowners: { known: ['check'], default: 'check' },
650
+ story: { known: ['frames'] },
615
651
  docs: { known: ['list', 'build', 'deploy', 'sync'], default: 'list' },
616
652
  reconcile: { known: ['check', 'refresh', 'wire'] },
617
653
  hook: { known: ['ledger-guard', 'agent-guard'] },
618
- toolbox: { known: ['list', 'check', 'add', 'remove'], default: 'list' },
654
+ toolbox: { known: ['list', 'check', 'add', 'remove', 'connect'], default: 'list' },
619
655
  signing: { known: ['check'], default: 'check' },
620
656
  ci: { known: ['check'], default: 'check' },
621
657
  member: { known: ['add', 'list', 'remove'], default: 'list' },
658
+ scan: { known: ['file'] },
659
+ issues: { known: ['list', 'labels', 'show', 'link', 'unlink', 'sync', 'new', 'assign', 'label', 'edit', 'comment', 'close', 'reopen'], default: 'list' },
622
660
  worktree: { known: ['add', 'list', 'remove'], default: 'list' },
623
661
  run: { known: ['checks'] },
624
662
  build: { known: ['start', 'step', 'trust', 'ship', 'merged', 'done', 'sync'] },
@@ -630,7 +668,8 @@ const PRODUCT_CMDS = new Set([
630
668
  'check', 'update', 'doctor', 'migrate', 'usage', 'sync-status', 'epic', 'foundation', 'skill', 'next',
631
669
  'skip', 'unskip', 'defer', 'undefer', 'dial', 'mode', 'kill', 'unkill', 'unblock', 'gate', 'checkpoint',
632
670
  'capture', 'claims', 'assign', 'unassign', 'owners', 'fold', 'tidy', 'index', 'history', 'repo',
633
- 'risk-map', 'codeowners', 'docs', 'thread', 'reconcile', 'member', 'standup', 'build', 'worktree', 'ci',
671
+ 'risk-map', 'codeowners', 'docs', 'thread', 'reconcile', 'member', 'standup', 'issues', 'scan', 'build', 'worktree', 'ci',
672
+ 'story',
634
673
  ]);
635
674
  // `status` reads the Product but must keep the folder it ran in: "here" is that checkout's task branch (#349).
636
675
  const REPO_CMDS = new Set(['commit', 'open-pr', 'ship', 'review', 'run', 'status', 'guide']);
@@ -883,8 +922,8 @@ async function main() {
883
922
  // team's choices are the Product's `.sdlc/toolbox.json`, found the way every Product command finds
884
923
  // it. So `toolbox` is not in PRODUCT_CMDS: that would move the finding to the Product's folder.
885
924
  const [, action = 'list', id, extra] = o._;
886
- const usage = 'usage: yad toolbox list | check | add <id> [--custom …] | remove <id> [--json] [--dir <folder>]';
887
- if (!['list', 'check', 'add', 'remove'].includes(action)) { refuse(`unknown toolbox action: ${action} (list, check, add, remove)`, usage); break; }
925
+ const usage = 'usage: yad toolbox list | check | add <id> [--custom …] | remove <id> | connect <id> [--verify] [--json] [--dir <folder>]';
926
+ if (!['list', 'check', 'add', 'remove', 'connect'].includes(action)) { refuse(`unknown toolbox action: ${action} (list, check, add, remove, connect)`, usage); break; }
888
927
  const found = commands.findProduct(dirGiven ? o.dir : shellCwd());
889
928
  const rel = (p) => path.relative(process.cwd(), p) || '.';
890
929
  if (action === 'list' || action === 'check') {
@@ -900,6 +939,12 @@ async function main() {
900
939
  break;
901
940
  }
902
941
  if (extra) { refuse(`yad toolbox ${action} takes one tool id (got also: ${extra})`, usage); break; }
942
+ // E165. Without --verify it only reads (the steps, the question, what will be recorded), so it needs no
943
+ // Product; --verify records the team's choice, so it is a writer like add.
944
+ if (action === 'connect' && !o.verify) {
945
+ result = commands.runToolboxConnect(commands.toolsFolder(found, o.dir || process.cwd()), found?.root ?? null, { id, json: o.json });
946
+ break;
947
+ }
903
948
  // A writer: the Product's file, never a code repo's, and the same refusals every writer has. With
904
949
  // --dir it is the Product itself, as for every other Product command (`yad skill bind --dir`) —
905
950
  // never a folder a walk up from it happens to reach.
@@ -916,7 +961,9 @@ async function main() {
916
961
  commands.warnIfProjectAhead(productRoot);
917
962
  const drift = commands.productDriftError(productRoot);
918
963
  if (drift) throw drift;
919
- result = action === 'add'
964
+ result = action === 'connect'
965
+ ? commands.runToolboxConnect(commands.toolsFolder(found, o.dir || process.cwd()), productRoot, { id, verify: true, replace: o.replace, json: o.json })
966
+ : action === 'add'
920
967
  ? commands.runToolboxAdd(productRoot, { id, custom: o.custom, role: o.role, fallback: o.fallback, detect: o.detect, install: o.install, source: o.source, json: o.json })
921
968
  : commands.runToolboxRemove(productRoot, { id, custom: o.custom, role: o.role, fallback: o.fallback, detect: o.detect, install: o.install, source: o.source, json: o.json });
922
969
  break;
@@ -962,6 +1009,12 @@ async function main() {
962
1009
  break;
963
1010
  }
964
1011
  if (noProduct()) break;
1012
+ if (o.issue !== undefined) {
1013
+ const foreign = commands.seedForeign(process.argv.slice(2));
1014
+ if (foreign.length) { refuse(`yad epic new --issue does not take ${foreign.join(', ')}`); break; }
1015
+ result = await commands.runEpicNewFromIssue(o.dir, { slug, issue: o.issue, type: o.type, profile: o.profile, stub: o.stub, parent: o.parent, inherits: o.inherits, today, json: o.json });
1016
+ break;
1017
+ }
965
1018
  result = await commands.runEpicNew(o.dir, { slug, type: o.type, profile: o.profile, stub: o.stub, parent: o.parent, inherits: o.inherits, today, json: o.json });
966
1019
  break;
967
1020
  }
@@ -1096,6 +1149,8 @@ async function main() {
1096
1149
  else if (action === 'comment') result = await commands.gateComment(o.dir, { epic, artifact, by: o.by, count: o.count ?? null, newRound: !!o.newRound, today });
1097
1150
  else if (action === 'advance') result = await commands.gateAdvance(o.dir, { epic, artifact, today });
1098
1151
  else { refuse(`unknown gate action: ${action} (open|sync|comments|status|repair|reopen|review|walkthrough|trailer|ci|approve|comment|advance)`); }
1152
+ // E171: a gate that really advanced here updates its linked items. `gate ci` is left out: CI cannot write to issues.
1153
+ if ((action === 'sync' && result?.written && result?.advanced > 0) || (action === 'advance' && result?.advanced === true)) commands.syncAfterGate(o.dir, epic);
1099
1154
  break;
1100
1155
  }
1101
1156
  case 'review': {
@@ -1212,6 +1267,56 @@ async function main() {
1212
1267
  else result = await commands.runWorktreeRemove(o.dir, { epic, repo: o.repo ?? null, all: !!o.all, cwd: shellCwd() });
1213
1268
  break;
1214
1269
  }
1270
+ case 'issues': {
1271
+ // E169. `list` reads and may write the --out file; `labels` adds the predefined labels to the repos.
1272
+ if (noProduct()) break;
1273
+ const action = o._[1] ?? 'list';
1274
+ if (!ACTIONS.issues.known.includes(action)) { refuse(`unknown issues action: ${action} (list, labels, show, link, unlink, sync, new, assign, label, edit, comment, close, reopen)`, ISSUES_USAGE); break; }
1275
+ if (commands.ACT_ACTIONS.includes(action)) {
1276
+ // E173: the agent acts on an item when an engineer asks. Before the older checks: these take a <ref> and their own flags.
1277
+ const foreign = commands.actForeignFlags(process.argv.slice(2), action);
1278
+ if (foreign.length) { refuse(`yad issues ${action} does not take ${foreign.join(', ')}`, ISSUES_USAGE); break; }
1279
+ const words = o._.slice(2);
1280
+ const wants = action === 'new' ? 0 : action === 'assign' ? (o.me || o.none ? 1 : 2) : 1;
1281
+ if (words.length !== wants) { refuse(`yad issues ${action} takes ${action === 'new' ? 'no words (use --title)' : action === 'assign' ? '<ref> <login>, or <ref> --me|--none' : '<ref>'}`, ISSUES_USAGE); break; }
1282
+ const common = { json: !!o.json };
1283
+ if (action === 'new') result = await commands.runIssuesNew(o.dir, { ...common, title: o.title, body: o.body ?? null, bodyFile: o['body-file'] ?? null, type: o.type ?? null, priority: o.priority ?? null, assignee: o.assignee ?? null, me: !!o.me, repo: o.repo ?? null });
1284
+ else if (action === 'assign') result = await commands.runIssuesAssign(o.dir, { ...common, ref: words[0], assignee: words[1] ?? null, me: !!o.me, none: !!o.none });
1285
+ else if (action === 'label') result = await commands.runIssuesLabel(o.dir, { ...common, ref: words[0], priority: o.priority ?? null, type: o.type ?? null });
1286
+ else if (action === 'edit') result = await commands.runIssuesEdit(o.dir, { ...common, ref: words[0], title: o.title ?? null, body: o.body ?? null, bodyFile: o['body-file'] ?? null });
1287
+ else if (action === 'comment') result = await commands.runIssuesComment(o.dir, { ...common, ref: words[0], body: o.body ?? null, bodyFile: o['body-file'] ?? null });
1288
+ else result = await (action === 'close' ? commands.runIssuesClose : commands.runIssuesReopen)(o.dir, { ...common, ref: words[0] });
1289
+ break;
1290
+ }
1291
+ const foreign = commands.issuesForeignFlags(process.argv.slice(2), action);
1292
+ if (foreign.length) { refuse(`yad issues ${action} does not take ${foreign.join(', ')}`, ISSUES_USAGE); break; }
1293
+ if (['show', 'link', 'unlink'].includes(action)) {
1294
+ const words = o._.slice(2);
1295
+ const want = action === 'show' ? 1 : 2;
1296
+ if (words.length !== want) { refuse(`yad issues ${action} takes ${action === 'show' ? '<ref>' : '<ref> <EP-id>'}`, ISSUES_USAGE); break; }
1297
+ result = action === 'show' ? await commands.runIssuesShow(o.dir, { ref: words[0], json: !!o.json })
1298
+ : await (action === 'link' ? commands.runIssuesLink : commands.runIssuesUnlink)(o.dir, { ref: words[0], epic: words[1], json: !!o.json });
1299
+ break;
1300
+ }
1301
+ if (o._[2]) { refuse(`yad issues ${action} takes no more words (got: ${o._[2]})`, ISSUES_USAGE); break; }
1302
+ if (action === 'sync') { result = await commands.runIssuesSync(o.dir, { dryRun: !!o.dryRun, json: !!o.json }); break; }
1303
+ if (action === 'labels') { result = await commands.runIssuesLabels(o.dir, { dryRun: !!o.dryRun, json: !!o.json }); break; }
1304
+ result = await commands.runIssuesList(o.dir, {
1305
+ priority: o.priority ?? null, type: o.type ?? null, status: o.status ?? null, assignee: o.assignee ?? null, me: !!o.me, repo: o.repo ?? null,
1306
+ since: o.since ?? null, until: o.until ?? null, date: o.date ?? null, sort: o.sort ?? null, closedSince: o['closed-since'] ?? null,
1307
+ format: o.format ?? null, out: o.out ?? null, json: !!o.json,
1308
+ });
1309
+ break;
1310
+ }
1311
+ case 'scan': {
1312
+ // E172. The yad-scan skill judges; this files.
1313
+ const action = o._[1];
1314
+ if (action !== 'file') { refuse(`unknown scan action: ${action ?? '(none)'} (file)`, 'usage: yad scan file <findings.json> --repo <name> [--task <id>] [--dry-run] [--json]'); break; }
1315
+ if (noProduct()) break;
1316
+ if (o._[3]) { refuse(`yad scan file takes one file (got also: ${o._[3]})`); break; }
1317
+ result = await commands.runScanFile(o.dir, { file: o._[2], repo: o.repo, task: o.task ?? null, dryRun: !!o.dryRun, json: !!o.json });
1318
+ break;
1319
+ }
1215
1320
  case 'standup': {
1216
1321
  // E132. Read-only; every flag that is not standup's own is refused, as history refuses them.
1217
1322
  const foreign = commands.standupForeignFlags(process.argv.slice(2));
@@ -1291,7 +1396,11 @@ async function main() {
1291
1396
  }
1292
1397
  case 'repo': {
1293
1398
  const [, action, name] = o._;
1294
- result = await commands.runRepo(o.dir, { action: action || 'list', name, today, push: o.push, allowBranch: o.allowBranch });
1399
+ // `yad repo preview <name> [<pattern>]` (#359): the one action with a third word.
1400
+ const pattern = action === 'preview' ? o._[3] : undefined;
1401
+ if (action === 'preview' && o._.length > 4) { refuse(`unexpected argument(s): ${o._.slice(4).join(' ')}`, 'use: yad repo preview <name> [<pattern>] [--clear] — quote the pattern'); break; }
1402
+ result = await commands.runRepo(o.dir, { action: action || 'list', name, pattern, clear: !!o.clear, today,
1403
+ push: o.push, allowBranch: o.allowBranch });
1295
1404
  break;
1296
1405
  }
1297
1406
  case 'risk-map': {
@@ -1305,6 +1414,12 @@ async function main() {
1305
1414
  result = await commands.runCodeowners(o.dir, { action: action || 'check', name, json: o.json, platform: o.platform, write: o._.some((a) => a === '--write' || a.startsWith('--write=')) });
1306
1415
  break;
1307
1416
  }
1417
+ case 'story': {
1418
+ if (o._.length > 3) { refuse(`unexpected argument(s): ${o._.slice(3).join(' ')}`, 'use: yad story frames <story-id> — one story at a time'); break; }
1419
+ const [, action, story] = o._;
1420
+ result = await commands.runStory(o.dir, { action, story, json: o.json });
1421
+ break;
1422
+ }
1308
1423
  case 'roster':
1309
1424
  // Removed in E62. Kept as a word for one major so a script or a habit gets told where it went
1310
1425
  // instead of "unknown command".