yadflow 4.8.0 → 4.9.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.
@@ -27,7 +27,10 @@ the Product.
27
27
  `.gitlab/merge_request_templates/Default.md`) with the Summary (from the commit), the story/task id and
28
28
  its `specs/` path, `Risk level:`, `Contract surface touched:`, and `Domains` (the repo name when
29
29
  `--repo` is passed) prefilled; the rest is left for the author. This satisfies the `pr-template`
30
- gate.
30
+ gate. The `**Preview:**` line under `## Testing` (#359) gets the repo's preview address, filled from
31
+ its `yad repo preview` pattern (a `{pr}` pattern once the PR has its number), or a note: none is
32
+ recorded (a live design check runs locally only), the recorded pattern cannot be used (fix it with
33
+ `yad repo preview`), or it cannot be filled yet (`yad review context --pr <n>` gives the address).
31
34
  - **Stage-aware on the Product** — `open-pr` mirrors the `--head` split the Product gates apply:
32
35
  - a **`review/EP-*/<artifact>`** branch is a Shape artifact-review PR → it **delegates to
33
36
  `yad gate open`** (artifact-review title `review: <artifact> (EP-<slug>)`, the Product artifact-review
@@ -53,6 +53,11 @@ Run the walkthrough grounding for the half you're on:
53
53
  `step.gateRule` carries the step's full approver count (`needed` distinct people, and the `risk`
54
54
  tier that set it), and `step.cap` — an object `{ active, limit, to, capped }`: `to` is the count capped by the active people (E72), `capped` is true when the cap lowered it, and the whole field is `null` when the people were not counted — useful context for how hard a step is being reviewed, never a pass/fail input.
55
55
 
56
+ For a UI change, the Build bundle's `preview` field (#359) says where a live design check (the page at
57
+ several screen widths) runs: at `preview.url` when set (a page that does not load or does not show
58
+ this change yet counts as local-only); on `source: local-only`, check on the engineer's
59
+ machine and say at that stop that the design check ran locally only (`preview.why` says why).
60
+
56
61
  **Read the real material yourself** — run the bundle's `diffCmd`, and read the named `codeMap` / `pack` /
57
62
  `contract` / `artifactPath` / `specs/<story>/` files. Never invent content. If a stop's material isn't
58
63
  available, say so at that stop (a gap is a finding — see Hard rules).
@@ -23,6 +23,7 @@
23
23
 
24
24
  ## Testing
25
25
  <!-- How the acceptance criteria were exercised. Tests must exercise behavior, not just pass. -->
26
+ - **Preview:** none
26
27
 
27
28
  ## Checklist
28
29
  - [ ] Commits carry a `Task: <story>-<task>` trailer (spec-link gate)
@@ -27,6 +27,7 @@
27
27
 
28
28
  ## Testing
29
29
  <!-- How the acceptance criteria were exercised. Tests must exercise behavior, not just pass. -->
30
+ - **Preview:** none
30
31
 
31
32
  ## Checklist
32
33
  - [ ] Commits carry a `Task: <story>-<task>` trailer (spec-link gate)
@@ -55,7 +55,10 @@ Inputs: `epic` + `artifact` (Shape) **or** `repo` + `pr` (Build); and the `actio
55
55
  `needed`, `risk`) — with `step.cap`, an object `{ active, limit, to, capped }` (E72): `to` is the count
56
56
  capped by the active people, `capped` is true when the cap lowered it, and the field is `null` when
57
57
  the people could not be counted, which is worth naming in the trailer on a high-risk step and never a blocker. Build: `yad review context --repo <r> --pr <n>` (see `yad-engineer-review`) provides the
58
- diff + code-map grounding. Read the named files yourself — never invent content.
58
+ diff + code-map grounding. Read the named files yourself — never invent content. For a UI change its
59
+ `preview` field (#359) says where a live design check runs: at `preview.url` when set (if that page
60
+ does not load or does not show this change yet, treat it as local-only), else
61
+ (`source: local-only`) say in the trailer that the design check ran locally only, with `preview.why`.
59
62
  2. **Trailer.** Generate ≤6 lines (what / risk / read-time), grounded only in the bundle. Post it:
60
63
  `yad gate trailer <epic> <artifact> --body "<text>" [--pr <n>]` (idempotent; re-run after edits).
61
64
  3. **Cards.** Produce atomic claims, each citing real lines. Post the deck as a single comment carrying
@@ -117,6 +117,27 @@ The **`test-cases` track may still be `in_progress`**: it is parallel and non-bl
117
117
  and point the user at `yad-status`. **Do not mutate Shape state** — `ready-for-build` semantics
118
118
  stay intact.
119
119
 
120
+ **Read the story's design frames (#354).** From the Product, run `yad story frames <story> --json`. Its
121
+ `frames` list holds each design-tool frame the story builds: `id`, `name`, `platform` and `url`, read
122
+ from the epic's `design-links.json`. When it has frames, `spec.md` (full or light) gets a
123
+ `## Design frames` section with one line per frame — `- <name> (<platform>) — <id> — <url>` — so the
124
+ spec and the tasks name the screens and nobody has to ask which ones belong to this story. A finding it
125
+ prints (an ID it cannot find, say) is a warning: copy it into that section as an open question, and do
126
+ not guess a frame. `recorded: false` or an empty list means no frames: write no section.
127
+
128
+ **Check the design tool can be reached (#358), before anything else for a story with frames.** The same
129
+ answer carries `preflight`. When `preflight.reachable` is `check`, make the MCP call `preflight.probe`
130
+ describes, now, before the ceremony starts. Some design tools (Pencil, Figma's desktop server) are read
131
+ through the running app, so a closed app or the wrong file open is found here and not half way through.
132
+ - **It answers, with the right file open:** go on.
133
+ - **It fails, or another file is open: STOP.** Print `preflight.stop` word for word and wait. Go on
134
+ without the design tool only when the person says so, and record that in `spec.md`'s
135
+ `## Clarifications` as `- Q: design tool not reachable → A: continue without it, from the frame links`
136
+ (when `spec.md` is not written yet, add the line as soon as it is).
137
+ - **`not-checkable`** (nothing to probe — `preflight.why` says why: for example no design tool, one yad has
138
+ no check for, or design-links.json missing or recorded for another tool): go on from the frame links, and say
139
+ `preflight.why` once. **`preflight: null`** (no frames): nothing to check.
140
+
120
141
  ### Step 2 — Resolve the target code repo
121
142
  Map `repo` → `{project-root}/demo-repos/<repo>/`. Confirm it exists and is its own git repo
122
143
  (`demo-repos/<repo>/.git` present). If missing, STOP and point the user at `demo-repos/README.md`
@@ -74,6 +74,19 @@ Phase 3 build (Spec Kit per repo) accurate anchors instead of invented ones.
74
74
  `code-context: stale` in the story frontmatter.
75
75
  - **Traceability:** record the loaded maps in each story's `code-context:` frontmatter field.
76
76
 
77
+ ### Step 2c — Load the design frames (so no one has to ask which screens a story builds)
78
+ When the UI step drew the screens in a design tool, it recorded them in
79
+ `{project-root}/epics/EP-<slug>/.sdlc/design-links.json`: a `screens` list, each with `name`, `platform`,
80
+ `nodeId` and `url`. Read it. In Step 5 each story lists the `nodeId`s of the screens it builds in its
81
+ `design-frames:` field, so the spec and implement steps read them with `yad story frames <story>`.
82
+
83
+ - **No file, no field:** with no `design-links.json` (no design tool, or the UI step skipped), leave
84
+ the `design-frames:` line out of every story and name the screens in "Notes for build" as before.
85
+ `[]` means "this story has no screens", which is not the same as "no frames were recorded".
86
+ - **IDs only, copied exactly, no quotes.** Copy each `nodeId` character for character, without quote
87
+ marks. The name and link stay in `design-links.json`, so they are written down once. A frame ID holding a comma, a space, `#` or a
88
+ bracket cannot be read back: ask for that frame to get a plain ID in the design tool.
89
+
77
90
  ### Step 3 — Break down the epic (assist: pm)
78
91
  Adopt the **pm** lens. Decompose the epic into the smallest set of
79
92
  independently reviewable, independently buildable stories. For each story decide which repos it touches
@@ -96,6 +109,7 @@ status: draft
96
109
  owner: <inherit from epic.md owner> # the epic owner carries through; not retyped
97
110
  repos: [<subset of epic.repos this story implements>]
98
111
  code-context: { repos: [], loaded: <YYYY-MM-DD or none> } # code-maps anchoring "Notes for build" (Step 2b)
112
+ design-frames: []
99
113
  ---
100
114
 
101
115
  ## Story
@@ -112,6 +126,14 @@ As a <role>, I want <capability>, so that <outcome>.
112
126
 
113
127
  `repos` is the field the later build phase reads to know where to scaffold specs — set it precisely.
114
128
 
129
+ `design-frames` lists the design-tool frame IDs (`nodeId`s from `design-links.json`, Step 2c) of the
130
+ screens this story builds, on ONE line: `design-frames: [12:34, 56:78]`. Leave it `[]` for a story with
131
+ no screens, and take the line out when the epic has no `design-links.json` (Step 2c). **Never put a `# comment` after it**, and never write it as a `- id` list on the lines
132
+ below: this frontmatter reader keeps the rest of the line, so either one makes the list unreadable.
133
+ Before the review, run `yad story frames <story>` for each story: it prints every frame's name and link,
134
+ and warns on an ID it cannot find. The field is part of the story, so the stories review approves it
135
+ like `repos`, and changing it after that review passed means the review must approve it again.
136
+
115
137
  ### Step 6 — Advance the authoring step (NOT the gate)
116
138
  **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):
117
139
  **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.
@@ -13,6 +13,7 @@ Each story authored at Shape step 7 is one Markdown file under `epics/EP-<slug>/
13
13
  | `status` | `draft` \| `in-review` \| `approved`, then `in-build` \| `shipped` | Story lifecycle: the first three within the stories gate (`yad sync-status` moves them), the last two in Build (`yad build ship` sets `in-build`, `yad build done` sets `shipped`). |
14
14
  | `repos` | subset of the epic's `repos` | Which repos must implement this story. **Labels the stories review PR with the touched repos now and (Phase 3) decides where specs are scaffolded.** |
15
15
  | `code-context` | `{ repos: [<name@sha>], loaded: <date> }` | Optional. Which connected-repo code-maps anchored "Notes for build" (Shape step 7 Step 2b). The `@sha` (a repo's `syncedHead`) is recommended so freshness is recorded but may be omitted; the SKILL templates show the empty placeholder `{ repos: [], loaded: <date or none> }`. `none` / `[]` when no repos are connected. |
16
+ | `design-frames` | `[<nodeId>, …]` or `[]` | The design-tool frames (Pencil, Figma) of the screens this story builds: each one a `nodeId` from the epic's `.sdlc/design-links.json`, copied exactly. `[]` = the story has no screens; no field = not recorded (also the case for every story of an epic with no `design-links.json`). IDs only: the name, platform and link are read from `design-links.json` by `yad story frames <story>`, which the spec and implement steps run (issue #354). Write it on one line, the IDs without quotes, with no `# comment` after it. Part of the reviewed story: changing it after the stories review passed needs that review again. `yad doctor` warns (`stories:design-frames`) on an ID it cannot find. |
16
17
 
17
18
  ## Body
18
19
 
@@ -216,6 +216,11 @@ When Step 3b generated or linked a design, write the machine-readable screen→f
216
216
  Keep the `## Design (<tool>)` section of `ui-design.md` in step with this file. When Step 3b degraded
217
217
  (`design: none`), do **not** write `design-links.json`.
218
218
 
219
+ Each `nodeId` is what a story records later: the stories step lists the frame IDs each story builds in
220
+ its `design-frames:` field, and the spec and implement steps read them with `yad story frames <story>`
221
+ (#354). So record every screen with its real `nodeId`, keep a frame's ID the same when you edit it, and
222
+ give a frame a plain ID — one with a comma, a space, `#` or a bracket cannot be read back from a story.
223
+
219
224
  ### Step 5 — Advance the authoring step (NOT the gate)
220
225
  **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
226
  **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.