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
@@ -30,6 +30,10 @@ the Markdown artifact only — the testing tool is additive, exactly like the de
30
30
  No tool below is required. When one is missing, this skill still finishes, using the fallback written
31
31
  beside it.
32
32
 
33
+ Before you fall back because a tool the team uses is not on this machine (not turned off, not removed
34
+ by the team), offer to connect it, once: run `yad toolbox connect <id> --json` and follow the
35
+ connect-tool rule. On a no, or when a step fails, use the fallback.
36
+
33
37
  Tell the person which tools you used and which fallbacks, and why.
34
38
 
35
39
  - **Playwright MCP** (`playwright`, a connector). Used when `.sdlc/testing.json` connects it. yad-connect-testing writes that file; follow it, not yad's toolbox answer.
@@ -112,9 +116,21 @@ story / user flow shape risk-based test cases:
112
116
  ### Step 3b — Materialize the automation in the connected tool (generate or link)
113
117
  Read `{project-root}/.sdlc/testing.json` (`config.yaml` `testing.registry`). Decide the path:
114
118
 
115
- - **No tool / `tool: "none"` / `source: "unavailable"`** (or the file is absent): **degrade** — author
119
+ - **No tool / `tool: "none"`** (or the file is absent): **degrade** — author
116
120
  the Markdown artifact only and record `testing: none` in the frontmatter with a one-line note
117
- (mirrors the `design: none` degrade). Skip to Step 4.
121
+ (mirrors the `design: none` degrade). Skip to Step 4. (Choosing a testing tool for the team is the
122
+ `yad-connect-testing` skill's step, which offers to connect one.)
123
+ - **A tool is named, but it is not on this machine** (`source: "unavailable"`, or its MCP server is not
124
+ found): **Offer to connect it first (E165):** run `yad toolbox connect <tool> --json` and follow the
125
+ connect-tool rule: show its `ask` word for word, ask once, and on a yes run only its `agent` steps, hand
126
+ over its `person` steps, then run the `verify` command it gives (`yad toolbox connect <tool> --verify --json`,
127
+ with `--replace` only when its question said which tool it replaces). Never install it any other way.
128
+ When `--verify` passes, first check that you can reach the tool: its MCP server in your session (in Claude Code, `/mcp`). A new MCP
129
+ server is loaded when the agent starts, so it may not be there yet. If you cannot reach it, do not
130
+ refresh — it would record the tool as unavailable: tell the person to restart the agent, run
131
+ `yad-connect-testing` with `action: refresh` and the same `tool`, and then run this step again; degrade for this run with that note. If you can, run `yad-connect-testing` with
132
+ `action: refresh` and the same `tool`, so `testing.json` records what it now finds (its `source`), then go on with the next bullet. On a no, or when a step fails, degrade as
133
+ in the bullet above.
118
134
  - **A tool is connected and its MCP is available:** adopt the `test architect` lens and, using the
119
135
  provider recorded in `testing.json` (Playwright via a Playwright MCP, Cypress/pytest/Maestro via
120
136
  theirs — Maestro authors mobile flows where Playwright has no reach) write the
@@ -41,6 +41,10 @@ there are found.
41
41
  - **When yad cannot answer** (yad is not installed here, or the command fails), use the check in the
42
42
  steps below.
43
43
 
44
+ Before you fall back because a tool the team uses is not on this machine (not turned off, not removed
45
+ by the team), offer to connect it, once: run `yad toolbox connect <id> --json` and follow the
46
+ connect-tool rule. On a no, or when a step fails, use the fallback.
47
+
44
48
  Tell the person which tools you used and which fallbacks, and why.
45
49
 
46
50
  - **Impeccable** (`impeccable`). Use it when its entry has `used: true` and `status.state` is `installed` or `available`. Otherwise — not found, its plugin turned off in Claude Code, or the team chose not to use it (`yad toolbox remove impeccable`) — use the fallback.
@@ -50,6 +54,8 @@ Tell the person which tools you used and which fallbacks, and why.
50
54
  - Fallback — markdown-only: yad-ui writes ui-design.md and DESIGN.md only.
51
55
  - **Pencil (pen.dev)** (`pencil`, a connector). Used when `.sdlc/design.json` connects it. yad-connect-design writes that file; follow it, not yad's toolbox answer.
52
56
  - Fallback — markdown-only: yad-ui writes ui-design.md and DESIGN.md only.
57
+ - **OpenPencil** (`openpencil`, a connector). Used when `.sdlc/design.json` connects it. yad-connect-design writes that file; follow it, not yad's toolbox answer.
58
+ - Fallback — markdown-only: yad-ui writes ui-design.md and DESIGN.md only.
53
59
 
54
60
  <!-- end: When a tool is missing -->
55
61
 
@@ -138,22 +144,45 @@ components/tokens into the design system; `/impeccable craft` is shape-then-buil
138
144
  yad cannot answer, it is not used when no `/impeccable …` commands are available), the
139
145
  `ux-designer` lens authors `ui-design.md` and `DESIGN.md` directly, and you **note in `ui-design.md`
140
146
  that Impeccable was not used**. Do not run `npx impeccable skills install` as part of this step — tool
141
- installation is out of scope for Shape.
147
+ installation is out of scope for Shape, except the one connect offer in **When a tool is missing**
148
+ (E165), which hands Impeccable's interactive installer to the person.
142
149
 
143
150
  ### Step 3b — Materialize the design in the connected tool (generate or link)
144
151
  Read `{project-root}/.sdlc/design.json` (`config.yaml` `design.registry`). Decide the path:
145
152
 
146
- - **No tool / `tool: "none"` / `source: "unavailable"`** (or the file is absent): **degrade** —
153
+ - **No tool / `tool: "none"`** (or the file is absent): **degrade** —
147
154
  author the Markdown artifacts only and record `design: none` in the frontmatter with a one-line note
148
- (mirrors the `impeccable: not-installed` degrade). Skip to Step 4.
149
- - **A tool is connected and its MCP is available:** adopt the `ux-designer` lens and, using the provider
150
- recorded in `design.json` (Figma via a Figma/html.to.design MCP, `pencil` via its MCP, etc.):
155
+ (mirrors the `impeccable: not-installed` degrade). Skip to Step 4. (Choosing a design tool for the team
156
+ is the `yad-connect-design` skill's step, which offers to connect one.)
157
+ - **A tool is named, but it is not on this machine** (`source: "unavailable"`, or its MCP server or CLI is
158
+ not found): **Offer to connect it first (E165):** run `yad toolbox connect <tool> --json` and follow the
159
+ connect-tool rule: show its `ask` word for word, ask once, and on a yes run only its `agent` steps, hand
160
+ over its `person` steps, then run the `verify` command it gives (`yad toolbox connect <tool> --verify --json`,
161
+ with `--replace` only when its question said which tool it replaces). Never install it any other way.
162
+ When `--verify` passes, first check that you can reach the tool: its MCP server in your session (in Claude Code, `/mcp`), or for OpenPencil its CLI on PATH. A new MCP
163
+ server is loaded when the agent starts, so it may not be there yet. If you cannot reach it, do not
164
+ refresh — it would record the tool as unavailable: tell the person to restart the agent, run
165
+ `yad-connect-design` with `action: refresh` and the same `tool`, and then run this step again; degrade for this run with that note. If you can, run `yad-connect-design` with
166
+ `action: refresh` and the same `tool`, so `design.json` records what it now finds (its `source`), then go on with the next bullet. On a no, or when a step fails, degrade as
167
+ in the bullet above.
168
+ - **A tool is connected and its provider is available** (`source` is not `unavailable`): adopt the `ux-designer` lens and, using the provider
169
+ recorded in `design.json` (Figma via a Figma/html.to.design MCP, `pencil` via its MCP, `openpencil` through its CLI —
170
+ `openpencil eval <file> --stdin --write` on the epic's design file, `epics/EP-<slug>/design/<name>.fig`,
171
+ with no app open (the first time, create the file with `openpencil import <seed.html> -o <file>`:
172
+ `eval` cannot create one) (or its MCP while the desktop app is open on the file) — etc.):
151
173
  - **Generate** — when the provider is write-capable, produce one frame per screen the design covers,
152
174
  for the platforms in `epic.repos` (mobile and/or web), reusing the code-maps (Step 2b) and
153
175
  `DESIGN.md` tokens so screens match built components rather than inventing parallel ones.
154
176
  - **Link** — when the user points at an existing design file (or the provider is read-only), reference
155
177
  it and **read the frames back** so `ui-design.md` reflects the real design.
156
178
 
179
+ **OpenPencil: give each frame yad's own ID.** Its own node IDs change when the file is reopened after a
180
+ frame is deleted or added, and an old one can then name another frame. So store a plain, unique ID on
181
+ each frame — `frame.setSharedPluginData('yad', 'nodeId', '<id>')`, for example `checkout-mobile` — and
182
+ record that ID as the screen's `nodeId`. Find a frame by it, never by OpenPencil's ID:
183
+ `figma.root.findAll((n) => n.getSharedPluginData('yad', 'nodeId') === '<id>')`. A linked OpenPencil file
184
+ whose frames carry no such ID gets one per frame, written back with `--write`.
185
+
157
186
  Capture each screen's `name`, `platform`, `nodeId`, and `url`. Record which direction was used
158
187
  (`generated | linked`). Honest-capability rule: a read-only MCP supports **link** only — never claim a
159
188
  screen was generated that the provider cannot produce. See
@@ -171,7 +200,7 @@ owner: <inherit from epic.md owner> # the epic owner carries through; not rety
171
200
  repos: [<inherit from epic>]
172
201
  impeccable: <used | not-installed>
173
202
  code-context: { repos: [], loaded: <YYYY-MM-DD or none> } # code-maps that informed component reuse (Step 2b)
174
- design: <none | { tool: <figma|pencil|…>, direction: <generated|linked>, file: <url>, screens: <N> }> # the connected design tool (Step 3b)
203
+ design: <none | { tool: <figma|pencil|openpencil|…>, direction: <generated|linked>, file: <url or repo path>, screens: <N> }> # the connected design tool (Step 3b)
175
204
  ---
176
205
 
177
206
  ## Screens & states
@@ -213,9 +242,19 @@ When Step 3b generated or linked a design, write the machine-readable screen→f
213
242
  }
214
243
  ```
215
244
 
245
+ For OpenPencil, `fileUrl` is the design file's path from the Product root
246
+ (`epics/EP-<slug>/design/<name>.fig`), each screen's `nodeId` is the ID yad stored on its frame (above),
247
+ its `url` is `null` (a file on disk has no link to one frame), and `source` is `openpencil-cli` or
248
+ `openpencil-mcp`.
249
+
216
250
  Keep the `## Design (<tool>)` section of `ui-design.md` in step with this file. When Step 3b degraded
217
251
  (`design: none`), do **not** write `design-links.json`.
218
252
 
253
+ Each `nodeId` is what a story records later: the stories step lists the frame IDs each story builds in
254
+ its `design-frames:` field, and the spec and implement steps read them with `yad story frames <story>`
255
+ (#354). So record every screen with its real `nodeId`, keep a frame's ID the same when you edit it, and
256
+ give a frame a plain ID — one with a comma, a space, `#` or a bracket cannot be read back from a story.
257
+
219
258
  ### Step 5 — Advance the authoring step (NOT the gate)
220
259
  **Check the mode first — the two modes have opposite instructions here.** Read `.sdlc/product.json` (`.sdlc/hub.json` on an older Product that has only that name):
221
260
  **verified mode** is `platform` set AND `ledger: "verified"` — or, on a project that has not run `yad migrate` yet, `bridge_enabled` (or legacy `bridge`) `true`. `ledger` wins whenever it is present.
@@ -227,8 +266,9 @@ any non-bot commit touching `epics/*/.sdlc/{state,approvals,comments,product-prs
227
266
  fails the gate if it rides the review PR, and desynchronises the ledger CI is about to rewrite if it
228
267
  is pushed around the gate. Commit the artifact set — **`ui-design.md`, `DESIGN.md`, and, when a
229
268
  design tool was used, `.sdlc/design-links.json`** (artifact-side, not ledger) — with `yad fold EP-<slug> ui-design`,
230
- which takes exactly these and leaves the ledger to CI — then hand off to
231
- `yad-review-gate`.
269
+ which takes exactly these and leaves the ledger to CI. An OpenPencil design file in `epics/EP-<slug>/design/`
270
+ is part of the same set: `yad fold` takes that folder too, and the review's fingerprint covers it, so a
271
+ change to the design file after approval needs a fresh review. Then hand off to `yad-review-gate`.
232
272
 
233
273
  **Otherwise — local, or a platform with no gate-sync CI — the engine makes this edit, not you.**
234
274
  `yad gate open <epic> ui-design.md` marks `ui-design-review` `in_review`, closes `ui-design` as `done`, and moves `currentStep` to the gate
@@ -1,49 +0,0 @@
1
- # SDLC check gates (Phase 3 build plan §C). The team's GitLab CI runs the same gates as
2
- # pipeline stages on every merge request; they must pass before merge. The gates are CI-agnostic
3
- # bash in checks/ — these stages just invoke them with the MR target as base.
4
- stages: [spec-link, contract-check, build-test-lint, verified-commits]
5
-
6
- default:
7
- image: node:${YAD_NODE_VERSION}
8
- # Runner selection on tag-locked instances (run_untagged: false): set the YAD_RUNNER_TAGS CI/CD variable.
9
- # When unset, current GitLab (>=15) runs the jobs untagged.
10
- tags: [$YAD_RUNNER_TAGS]
11
-
12
- .mr_only:
13
- rules:
14
- - if: $CI_PIPELINE_SOURCE == "merge_request_event"
15
-
16
- variables:
17
- GIT_DEPTH: "0" # full history so the gates can diff against the target branch
18
- YAD_NODE_VERSION: "22" # override with a project/group CI variable (a current 22 or 24 line; Node 25+ has no Corepack; 18 and 20 are end of life)
19
- NX_BASE: $CI_MERGE_REQUEST_DIFF_BASE_SHA
20
- NX_HEAD: $CI_COMMIT_SHA
21
-
22
- spec-link:
23
- stage: spec-link
24
- extends: .mr_only
25
- script:
26
- - bash checks/spec-link.sh "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
27
-
28
- contract-check:
29
- stage: contract-check
30
- extends: .mr_only
31
- script:
32
- - bash checks/contract-check.sh "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
33
-
34
- build-test-lint:
35
- stage: build-test-lint
36
- extends: .mr_only
37
- variables:
38
- YAD_TEST_MAX_WORKERS: "2" # cap jest/vitest test workers in CI; ignored by other runners
39
- script:
40
- - bash checks/install-deps.sh
41
- - bash checks/build-test-lint.sh
42
-
43
- # Needs a CI/CD variable GITLAB_TOKEN (or SDLC_API_TOKEN) with read_api scope — CI_JOB_TOKEN cannot
44
- # read the commit-signature API.
45
- verified-commits:
46
- stage: verified-commits
47
- extends: .mr_only
48
- script:
49
- - bash checks/verified-commits.sh "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"