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.
@@ -0,0 +1,339 @@
1
+ // #354: each story records its design frames (`design-frames: [id, …]`), `yad story frames` reads them
2
+ // with their names and links from the epic's design-links.json, and `yad doctor` warns on any it cannot
3
+ // read. One rule (`frameFindings`) decides for both, and every finding is a warning in both.
4
+ import { test } from 'node:test';
5
+ import assert from 'node:assert/strict';
6
+ import { spawnSync } from 'node:child_process';
7
+ import fs from 'node:fs';
8
+ import os from 'node:os';
9
+ import path from 'node:path';
10
+ import { fileURLToPath } from 'node:url';
11
+
12
+ if (process.env.NODE_TEST_CONTEXT) {
13
+ const write = process.stdout.write;
14
+ for (const k of ['log', 'info']) {
15
+ const orig = console[k];
16
+ console[k] = (...a) => (process.stdout.write === write ? console.error(...a) : orig(...a));
17
+ }
18
+ }
19
+ process.env.YAD_NO_UPDATE_NOTIFIER = '1';
20
+
21
+ const { frameFindings, readDesignLinks, readStoryFrames, allStoryFrames, FRAMES_KEY } = await import('./story-frames.mjs');
22
+ const { storyFrameChecks } = await import('./doctor.mjs');
23
+
24
+ const HERE = path.dirname(fileURLToPath(import.meta.url));
25
+ const YAD = path.join(HERE, '..', 'bin', 'yad.mjs');
26
+ const REPO = path.join(HERE, '..');
27
+
28
+ const tmp = () => fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'yad-frames-')));
29
+ const put = (file, data) => { fs.mkdirSync(path.dirname(file), { recursive: true }); fs.writeFileSync(file, typeof data === 'string' ? data : JSON.stringify(data)); };
30
+ const done = (T) => fs.rmSync(T, { recursive: true, force: true });
31
+ const story = (id, line) => `---\nid: ${id}\nepic: ${id.replace(/-S\d+$/, '')}\nstatus: draft\nrepos: [web]\n${line === null ? '' : `${line}\n`}---\n\n## Story\n`;
32
+ const LINKS = {
33
+ tool: 'pencil', fileUrl: 'https://design.example/f', direction: 'generate', source: 'pencil',
34
+ screens: [
35
+ { name: 'Cart', platform: 'web', nodeId: '12:34', url: 'https://design.example/f?node=12:34' },
36
+ { name: 'Pay', platform: 'mobile', nodeId: 'aB3xQ', url: 'https://design.example/f?node=aB3xQ' },
37
+ ],
38
+ };
39
+ const ok = { state: 'ok', tool: 'pencil', fileUrl: LINKS.fileUrl, screens: LINKS.screens };
40
+ const kinds = (r) => r.findings.map((f) => f.kind);
41
+ const BOM = String.fromCharCode(0xfeff);
42
+
43
+ // A Product with one epic: its design-links.json (or none) and the given stories.
44
+ function product(stories, links = LINKS) {
45
+ const T = tmp();
46
+ const epic = path.join(T, 'epics', 'EP-shop');
47
+ fs.mkdirSync(epic, { recursive: true });
48
+ if (links !== null) put(path.join(epic, '.sdlc', 'design-links.json'), links);
49
+ for (const [id, line] of Object.entries(stories)) put(path.join(epic, 'stories', `${id}.md`), story(id, line));
50
+ return T;
51
+ }
52
+ const yad = (T, ...args) => spawnSync(process.execPath, [YAD, ...args, '--dir', T], { encoding: 'utf8', env: { ...process.env, NO_COLOR: '1', SDLC_NONINTERACTIVE: '1' } });
53
+
54
+ test('#354: frameFindings — no key, an empty list, and IDs that all resolve', () => {
55
+ assert.deepEqual(frameFindings({}, ok), { recorded: false, ids: [], frames: [], findings: [] });
56
+ const none = frameFindings({ [FRAMES_KEY]: [] }, { state: 'missing' });
57
+ assert.equal(none.recorded, true);
58
+ assert.deepEqual(none.findings, [], '`[]` needs no design-links.json — a story with no screens');
59
+ const r = frameFindings({ [FRAMES_KEY]: ['12:34', 'aB3xQ'] }, ok);
60
+ assert.deepEqual(r.findings, []);
61
+ assert.deepEqual(r.frames, [
62
+ { id: '12:34', found: true, name: 'Cart', platform: 'web', url: LINKS.screens[0].url },
63
+ { id: 'aB3xQ', found: true, name: 'Pay', platform: 'mobile', url: LINKS.screens[1].url },
64
+ ], 'a Figma 12:34 ID and a Pencil-style ID both resolve');
65
+ });
66
+
67
+ test('#354: frameFindings — every problem is a finding, never a silent "no frames"', () => {
68
+ assert.deepEqual(kinds(frameFindings({ [FRAMES_KEY]: ['12:34', '99:99'] }, ok)), ['not-found']);
69
+ assert.deepEqual(kinds(frameFindings({ [FRAMES_KEY]: '[12:34] # the cart' }, ok)), ['commented'], 'the comment trap');
70
+ assert.deepEqual(kinds(frameFindings({ [FRAMES_KEY]: '' }, ok)), ['not-a-list'], 'blank — what a `- id` block list reads as');
71
+ assert.deepEqual(kinds(frameFindings({ [FRAMES_KEY]: '12:34' }, ok)), ['not-a-list']);
72
+ assert.deepEqual(kinds(frameFindings({ [FRAMES_KEY]: ['12 34'] }, ok)), ['bad-id', 'not-found']);
73
+ assert.deepEqual(kinds(frameFindings({ [FRAMES_KEY]: ['12:34', '12:34'] }, ok)), ['duplicate']);
74
+ assert.deepEqual(kinds(frameFindings({ [FRAMES_KEY]: ['12:34'] }, { state: 'missing' })), ['no-design-links']);
75
+ assert.deepEqual(kinds(frameFindings({ [FRAMES_KEY]: ['12:34'] }, { state: 'unreadable', why: 'x' })), ['design-links-unreadable']);
76
+ });
77
+
78
+ test('#354: frameFindings — text from the files reaches the terminal cleaned', () => {
79
+ const r = frameFindings({ [FRAMES_KEY]: ['\x1b[31m1:2'] }, ok);
80
+ for (const f of r.findings) assert.ok(!f.message.includes('\x1b'), f.message);
81
+ });
82
+
83
+ test('#354: readDesignLinks — missing, not JSON, no screens list, and ok', () => {
84
+ const T = tmp();
85
+ try {
86
+ assert.equal(readDesignLinks(T).state, 'missing');
87
+ put(path.join(T, '.sdlc', 'design-links.json'), '{ nope');
88
+ assert.equal(readDesignLinks(T).state, 'unreadable');
89
+ put(path.join(T, '.sdlc', 'design-links.json'), { tool: 'figma' });
90
+ assert.equal(readDesignLinks(T).state, 'unreadable');
91
+ put(path.join(T, '.sdlc', 'design-links.json'), LINKS);
92
+ const r = readDesignLinks(T);
93
+ assert.equal(r.state, 'ok');
94
+ assert.equal(r.screens.length, 2);
95
+ } finally { done(T); }
96
+ });
97
+
98
+ test('#354: the frontmatter reader round-trips the key the stories step writes', () => {
99
+ const T = product({ 'EP-shop-S01': `${FRAMES_KEY}: [12:34, aB3xQ]`, 'EP-shop-S02': `${FRAMES_KEY}: []`, 'EP-shop-S03': null });
100
+ try {
101
+ assert.deepEqual(readStoryFrames(T, 'EP-shop-S01').frames.map((f) => f.found), [true, true]);
102
+ const s2 = readStoryFrames(T, 'EP-shop-S02');
103
+ assert.deepEqual([s2.recorded, s2.ids, s2.findings], [true, [], []]);
104
+ assert.equal(readStoryFrames(T, 'EP-shop-S03').recorded, false);
105
+ assert.throws(() => readStoryFrames(T, 'EP-shop-S09'), /no story file/);
106
+ assert.throws(() => readStoryFrames(T, 'shop'), /not a story id/);
107
+ assert.throws(() => readStoryFrames(T, undefined), /needs a story id/);
108
+ } finally { done(T); }
109
+ });
110
+
111
+ test('#354: yad story frames — text, --json, and the exit code', () => {
112
+ const T = product({ 'EP-shop-S01': `${FRAMES_KEY}: [12:34, 99:99]` });
113
+ try {
114
+ const text = yad(T, 'story', 'frames', 'EP-shop-S01');
115
+ assert.equal(text.status, 0, text.stderr);
116
+ assert.match(text.stdout, /12:34 {2}Cart {2}\[web\]/);
117
+ assert.match(text.stdout, /99:99 — not found/);
118
+ const j = yad(T, 'story', 'frames', 'EP-shop-S01', '--json');
119
+ assert.equal(j.status, 0, j.stderr);
120
+ const out = JSON.parse(j.stdout);
121
+ assert.equal(out.command, 'story frames');
122
+ assert.equal(out.ok, true);
123
+ assert.equal(out.tool, 'pencil');
124
+ assert.deepEqual(out.frames.map((f) => [f.id, f.found]), [['12:34', true], ['99:99', false]]);
125
+ assert.deepEqual(out.findings.map((f) => f.kind), ['not-found']);
126
+ assert.equal(out.warnings.length, 1, 'a missing frame is a warning, and the exit code stays 0');
127
+
128
+ const gone = yad(T, 'story', 'frames', 'EP-shop-S09', '--json');
129
+ assert.equal(gone.status, 1);
130
+ const g = JSON.parse(gone.stdout);
131
+ assert.equal(g.ok, false);
132
+ assert.match(g.hint, /story id/);
133
+ assert.equal(yad(T, 'story', 'paint').status, 1, 'an unknown action is refused');
134
+ } finally { done(T); }
135
+ });
136
+
137
+ test('#354: doctor — no row without frames, an ok row with a count, one warn row naming the problems', () => {
138
+ const run = (T) => { const checks = []; storyFrameChecks(checks, T); return checks; };
139
+ let T = product({ 'EP-shop-S01': null });
140
+ try { assert.deepEqual(run(T), []); } finally { done(T); }
141
+
142
+ T = product({ 'EP-shop-S01': `${FRAMES_KEY}: [12:34]`, 'EP-shop-S02': `${FRAMES_KEY}: []` }, LINKS);
143
+ try {
144
+ const [row, ...rest] = run(T);
145
+ assert.equal(rest.length, 0);
146
+ assert.deepEqual([row.id, row.status], ['stories:design-frames', 'ok']);
147
+ assert.match(row.message, /^1 story\(ies\) record design frames.*; 1 story\(ies\) say they have no screens/);
148
+ } finally { done(T); }
149
+
150
+ T = product({ 'EP-shop-S01': `${FRAMES_KEY}: [12:34] # cart`, 'EP-shop-S02': `${FRAMES_KEY}: [77:1]` });
151
+ try {
152
+ const rows = run(T);
153
+ assert.equal(rows.length, 1);
154
+ assert.deepEqual([rows[0].id, rows[0].status], ['stories:design-frames', 'warn']);
155
+ assert.match(rows[0].message, /^2 problem/);
156
+ assert.match(rows[0].message, /EP-shop-S01: .*#/);
157
+ assert.match(rows[0].message, /EP-shop-S02: .*77:1/);
158
+ assert.deepEqual(allStoryFrames(T, ['EP-shop']).map((s) => s.findings[0].kind), ['commented', 'not-found']);
159
+ } finally { done(T); }
160
+ });
161
+
162
+ test('#354 review 1: Windows line endings, a byte-order mark and a trailing space still read the list', () => {
163
+ const T = product({});
164
+ try {
165
+ const dir = path.join(T, 'epics', 'EP-shop', 'stories');
166
+ put(path.join(dir, 'EP-shop-S01.md'), story('EP-shop-S01', `${FRAMES_KEY}: [12:34]`).replace(/\n/g, '\r\n'));
167
+ put(path.join(dir, 'EP-shop-S02.md'), BOM + story('EP-shop-S02', `${FRAMES_KEY}: [12:34]`));
168
+ put(path.join(dir, 'EP-shop-S03.md'), story('EP-shop-S03', `${FRAMES_KEY}: [12:34] `));
169
+ for (const id of ['EP-shop-S01', 'EP-shop-S02', 'EP-shop-S03']) {
170
+ const r = readStoryFrames(T, id);
171
+ assert.deepEqual([r.recorded, r.frames.map((f) => f.found), r.findings], [true, [true], []], id);
172
+ }
173
+ assert.deepEqual(allStoryFrames(T, ['EP-shop']).map((s) => s.findings.length), [0, 0, 0], 'doctor reads them the same way');
174
+ } finally { done(T); }
175
+ });
176
+
177
+ test('#354 review 1: a misspelled key and quoted IDs are said, not read as "no frames" or "not found"', () => {
178
+ for (const k of ['Design-Frames', 'designFrames', 'design_frames']) {
179
+ const r = frameFindings({ [k]: ['12:34'] }, ok);
180
+ assert.deepEqual([r.recorded, kinds(r)], [false, ['key-spelling']], k);
181
+ }
182
+ const q = frameFindings({ [FRAMES_KEY]: ['"12:34"', "'aB3xQ'"] }, ok);
183
+ assert.deepEqual(kinds(q), ['quoted']);
184
+ assert.deepEqual(q.frames.map((f) => [f.id, f.found]), [['12:34', true], ['aB3xQ', true]]);
185
+ assert.doesNotMatch(frameFindings({ [FRAMES_KEY]: 'x y' }, ok).findings[0].message, /\[\[/, 'never advice to double the brackets');
186
+ });
187
+
188
+ test('#354 review 1: doctor never points at a command that would refuse the story', () => {
189
+ const T = product({ 'EP-shop-S01': `${FRAMES_KEY}: []` });
190
+ try {
191
+ const dir = path.join(T, 'epics', 'EP-shop', 'stories');
192
+ put(path.join(dir, 'EP-Shop-S04.md'), story('EP-Shop-S04', `${FRAMES_KEY}: [12:34]`));
193
+ put(path.join(dir, 'EP-other-S01.md'), story('EP-other-S01', `${FRAMES_KEY}: [12:34]`));
194
+ fs.mkdirSync(path.join(dir, 'EP-shop-S07.md'));
195
+ const rows = allStoryFrames(T, ['EP-shop']);
196
+ assert.deepEqual(rows.map((s) => [s.story, kinds(s)]), [['EP-Shop-S04', ['not-a-story-file']], ['EP-other-S01', ['not-a-story-file']], ['EP-shop-S01', []]]);
197
+ for (const s of rows.filter((x) => x.findings.length)) assert.match(s.findings[0].message, /rename the file/);
198
+ assert.throws(() => readStoryFrames(T, 'EP-shop-S07'), /no story file/, 'a folder named like a story is refused, not a crash');
199
+ const checks = [];
200
+ storyFrameChecks(checks, T);
201
+ assert.equal(checks[0].status, 'warn');
202
+ } finally { done(T); }
203
+ });
204
+
205
+ test('#354 review 1: the ok row tells stories with frames from stories with no screens', () => {
206
+ const T = product({ 'EP-shop-S01': `${FRAMES_KEY}: []` }, null);
207
+ try {
208
+ const checks = [];
209
+ storyFrameChecks(checks, T);
210
+ assert.equal(checks[0].status, 'ok');
211
+ assert.match(checks[0].message, /^1 story\(ies\) say they have no screens/);
212
+ assert.equal(yad(T, 'story', 'frames', 'EP-shop-S01', 'EP-shop-S02').status, 1, 'one story at a time');
213
+ } finally { done(T); }
214
+ });
215
+
216
+ test('#354 review 2: doctor reads what the command reads — a symlinked story, a misspelled key', () => {
217
+ const T = product({ 'EP-shop-S02': 'designFrames: [12:34]' });
218
+ try {
219
+ const dir = path.join(T, 'epics', 'EP-shop', 'stories');
220
+ put(path.join(T, 'elsewhere.md'), story('EP-shop-S01', `${FRAMES_KEY}: [9:9]`));
221
+ fs.symlinkSync(path.join(T, 'elsewhere.md'), path.join(dir, 'EP-shop-S01.md'));
222
+ assert.deepEqual(kinds(readStoryFrames(T, 'EP-shop-S01')), ['not-found']);
223
+ assert.deepEqual(allStoryFrames(T, ['EP-shop']).map((s) => [s.story, kinds(s)]), [['EP-shop-S01', ['not-found']], ['EP-shop-S02', ['key-spelling']]]);
224
+ const checks = [];
225
+ storyFrameChecks(checks, T);
226
+ assert.equal(checks[0].status, 'warn');
227
+ assert.match(checks[0].hint, /rename a story file/);
228
+ } finally { done(T); }
229
+ });
230
+
231
+ test('#354 review 2: a misspelled key beside the right one is said; `""` is not an empty ID', () => {
232
+ const both = frameFindings({ [FRAMES_KEY]: ['12:34'], designFrames: ['56:78'] }, ok);
233
+ assert.deepEqual(kinds(both), ['key-spelling']);
234
+ assert.match(both.findings[0].message, /move its IDs/);
235
+ const empty = frameFindings({ [FRAMES_KEY]: ['""'] }, ok);
236
+ assert.deepEqual(kinds(empty), ['not-found'], '`""` is left as it is, never turned into an empty ID');
237
+ assert.deepEqual(empty.ids, ['""']);
238
+ assert.match(frameFindings({ [FRAMES_KEY]: ['"12:34"'] }, ok).findings[0].message, /should be written without quotes/);
239
+ });
240
+
241
+ const { designPreflight, readDesignConfig } = await import('./story-frames.mjs');
242
+ const { TOOLBOX, toolProblems, reachFor } = await import('./toolbox.mjs');
243
+
244
+ test('#358: designPreflight — Pencil is read through the app; Figma only through its desktop server', () => {
245
+ const frames = [{ id: '99:1', found: false }, { id: '12:34', found: true }];
246
+ const links = { state: 'ok', fileUrl: 'design/app.pen', screens: [] };
247
+ const pencil = designPreflight({ state: 'ok', data: { tool: 'pencil', provider: 'pencil-mcp' } }, links, frames);
248
+ assert.deepEqual([pencil.reachable, pencil.appBound, pencil.frame, pencil.file], ['check', true, '12:34', 'design/app.pen'], 'the first frame that resolves is the one probed');
249
+ assert.match(pencil.stop, /^Open the Pencil desktop app with `design\/app\.pen` loaded/);
250
+ assert.match(pencil.probe, /get_app_state/);
251
+ const desk = designPreflight({ state: 'ok', data: { tool: 'figma', provider: 'figma-desktop' } }, links, frames);
252
+ assert.deepEqual([desk.appBound, /desktop app/.test(desk.stop)], [true, true]);
253
+ const cloud = designPreflight({ state: 'ok', data: { tool: 'figma', provider: 'figma' } }, links, frames);
254
+ assert.deepEqual([cloud.appBound, /^Sign in to Figma/.test(cloud.stop)], [false, true]);
255
+ assert.match(cloud.probe, /`12:34`/);
256
+ const old = designPreflight({ state: 'ok', data: { tool: 'figma', provider: 'figma-mcp' } }, links, frames);
257
+ assert.deepEqual([old.appBound, /desktop app.*or sign in/.test(old.stop)], [null, true], 'the older figma-mcp: yad cannot tell, so both');
258
+ const viaSource = designPreflight({ state: 'ok', data: { tool: 'figma', source: 'figma-desktop' } }, links, frames);
259
+ assert.deepEqual([viaSource.provider, viaSource.appBound], ['figma-desktop', true], 'no provider: source names the server');
260
+ const noFile = designPreflight({ state: 'ok', data: { tool: 'pencil', project_url: 'https://team/project' } }, { state: 'ok', tool: 'pencil', fileUrl: null, screens: [] }, frames);
261
+ assert.match(noFile.stop, /the design file/, 'no file: said plainly — a project_url is a project, never compared as the file');
262
+ const switched = designPreflight({ state: 'ok', data: { tool: 'pencil' } }, { state: 'ok', tool: 'figma', fileUrl: 'https://figma/f', screens: [] }, frames);
263
+ assert.deepEqual([switched.reachable, /recorded for figma.*re-run the UI step/.test(switched.why)], ['not-checkable', true], 'frames of another tool are never probed through this one');
264
+ const odd = designPreflight({ state: 'ok', data: { tool: 'figma', source: 'figma-dev-mode-mcp-server' } }, links, frames);
265
+ assert.deepEqual([odd.reachable, odd.appBound], ['check', null], 'an MCP id yad does not know is still probed, with both messages');
266
+ assert.equal(designPreflight({ state: 'ok', data: { tool: 'figma', provider: 'Figma-Desktop' } }, links, frames).appBound, true, 'names are compared in lower case');
267
+ for (const provider of ['HTML-to-Design', 'html.to.design', ' html_to_design ']) {
268
+ assert.equal(designPreflight({ state: 'ok', data: { tool: 'figma', provider } }, links, frames).reachable, 'not-checkable', provider);
269
+ }
270
+ assert.equal(designPreflight({ state: 'ok', data: { tool: 'figma' } }, { ...links, tool: 'Figma' }, frames).reachable, 'check', 'the same tool in other letters is not a switch');
271
+ });
272
+
273
+ test('#358: designPreflight — nothing to probe is not-checkable, and no frame means no preflight', () => {
274
+ const frames = [{ id: '12:34', found: true }];
275
+ const links = { state: 'ok', fileUrl: 'f', screens: [] };
276
+ for (const design of [{ state: 'missing' }, { state: 'unreadable' }, { state: 'ok', data: { tool: 'none' } }, { state: 'ok', data: { tool: 'pencil', source: 'unavailable' } }, { state: 'ok', data: { tool: 'sketch' } }]) {
277
+ assert.equal(designPreflight(design, links, frames).reachable, 'not-checkable', JSON.stringify(design));
278
+ }
279
+ assert.equal(designPreflight({ state: 'ok', data: { tool: 'pencil' } }, links, []), null);
280
+ const writer = designPreflight({ state: 'ok', data: { tool: 'figma', provider: 'html-to-design' } }, links, frames);
281
+ assert.deepEqual([writer.reachable, /cannot read a frame/.test(writer.why)], ['not-checkable', true]);
282
+ const gone = designPreflight({ state: 'ok', data: { tool: 'pencil' } }, { state: 'missing' }, [{ id: '9:9', found: false }]);
283
+ assert.match(gone.why, /no design-links\.json/, 'a missing file is named, not blamed on the IDs');
284
+ assert.match(designPreflight({ state: 'ok', data: { tool: 'pencil' } }, { state: 'unreadable', why: 'it does not parse as JSON' }, [{ id: '9:9', found: false }]).why, /cannot be read/);
285
+ const unresolved = designPreflight({ state: 'ok', data: { tool: 'pencil' } }, links, [{ id: '9:9', found: false }]);
286
+ assert.deepEqual([unresolved.reachable, /fix the frame IDs/.test(unresolved.why)], ['not-checkable', true]);
287
+ for (const data of [{ tool: 123 }, { tool: 'figma', provider: {} }, { tool: 'pencil', source: ['unavailable'] }]) {
288
+ const r = designPreflight({ state: 'ok', data }, links, frames);
289
+ assert.ok(r && ['check', 'not-checkable'].includes(r.reachable), JSON.stringify(data));
290
+ }
291
+ const dirty = designPreflight({ state: 'ok', data: { tool: 'pencil' } }, { state: 'ok', fileUrl: 'a\x1b[31mb', screens: [] }, frames);
292
+ assert.ok(!dirty.stop.includes('\x1b') && !dirty.probe.includes('\x1b'));
293
+ });
294
+
295
+ test('#358: readDesignConfig, the reach data, and preflight through the command', () => {
296
+ for (const t of TOOLBOX.filter((x) => x.reach)) assert.deepEqual(toolProblems(t), [], t.id);
297
+ const figma = TOOLBOX.find((x) => x.id === 'figma');
298
+ assert.deepEqual(toolProblems({ ...figma, reach: { app: 'F', probe: 'p', open: 'o', readers: true, appBound: ['x'] } }), ['reach.signIn and reach.either say what to do when the provider needs no app, or yad cannot tell']);
299
+ assert.ok(toolProblems({ ...figma, reach: { readers: true, appBound: true } }).includes('reach has app, probe and open'));
300
+ assert.ok(toolProblems({ ...figma, reach: null }).length > 0);
301
+ assert.ok(toolProblems({ ...figma, reach: { ...figma.reach, appBound: false } }).includes('reach.appBound is true, or the providers read through the app'));
302
+ assert.equal(reachFor('repomix'), null);
303
+ const T = product({ 'EP-shop-S01': `${FRAMES_KEY}: [12:34]`, 'EP-shop-S02': `${FRAMES_KEY}: []` });
304
+ try {
305
+ assert.equal(readDesignConfig(T).state, 'missing');
306
+ put(path.join(T, '.sdlc', 'design.json'), '{ nope');
307
+ assert.equal(readDesignConfig(T).state, 'unreadable');
308
+ put(path.join(T, '.sdlc', 'design.json'), { tool: 'pencil', provider: 'pencil-mcp', source: 'pencil-mcp', auth: 'user' });
309
+ const j = JSON.parse(yad(T, 'story', 'frames', 'EP-shop-S01', '--json').stdout);
310
+ assert.deepEqual([j.preflight.reachable, j.preflight.tool, j.preflight.appBound], ['check', 'pencil', true]);
311
+ assert.match(yad(T, 'story', 'frames', 'EP-shop-S01').stdout, /before UI work: .* if that fails, stop: Open the Pencil desktop app/);
312
+ assert.equal(JSON.parse(yad(T, 'story', 'frames', 'EP-shop-S02', '--json').stdout).preflight, null, 'no screens, no probe');
313
+ } finally { done(T); }
314
+ });
315
+
316
+ test('#354: the stories, spec and implement skills all name `yad story frames`', () => {
317
+ for (const skill of ['yad-stories', 'yad-spec', 'yad-implement']) {
318
+ const body = fs.readFileSync(path.join(REPO, 'skills', skill, 'SKILL.md'), 'utf8');
319
+ assert.ok(body.includes('yad story frames'), `${skill} does not read the story's frames`);
320
+ }
321
+ const schema = fs.readFileSync(path.join(REPO, 'skills', 'yad-stories', 'references', 'story-schema.md'), 'utf8');
322
+ assert.ok(schema.includes(FRAMES_KEY), 'the story schema names the key');
323
+ const template = fs.readFileSync(path.join(REPO, 'skills', 'yad-stories', 'SKILL.md'), 'utf8');
324
+ assert.match(template, new RegExp(`^${FRAMES_KEY}: \\[\\]$`, 'm'), 'the template ships the key bare, with no trailing comment');
325
+ });
326
+
327
+ test('#358: spec and implement probe the design tool first, stop on a failure, and record an override', () => {
328
+ for (const [skill, where] of [['yad-spec', '## Clarifications'], ['yad-implement', 'Decisions:']]) {
329
+ const body = fs.readFileSync(path.join(REPO, 'skills', skill, 'SKILL.md'), 'utf8');
330
+ for (const word of ['preflight.probe', 'not-checkable', where]) assert.ok(body.includes(word), `${skill} lacks ${word}`);
331
+ assert.match(body, /STOP\W+print `preflight\.stop` word for word/i, `${skill} does not stop with the message`);
332
+ }
333
+ const ctx = fs.readFileSync(path.join(REPO, 'skills', 'yad-connect-design', 'references', 'design-context.md'), 'utf8');
334
+ assert.ok(ctx.includes('Reachable before Build (#358)'));
335
+ const connect = fs.readFileSync(path.join(REPO, 'skills', 'yad-connect-design', 'SKILL.md'), 'utf8');
336
+ for (const p of ['figma-desktop', '`figma`', 'html-to-design']) assert.ok(connect.includes(p), `yad-connect-design does not name the ${p} provider`);
337
+ const example = connect.slice(connect.indexOf('### Step 2'), connect.indexOf('### Step 3'));
338
+ assert.ok(example.includes('"provider": "figma-desktop"') && !example.includes('figma-mcp'), 'the registry example records a provider the preflight can read');
339
+ });
package/cli/toolbox.mjs CHANGED
@@ -254,6 +254,18 @@ export const TOOLBOX = Object.freeze([
254
254
  versions: null,
255
255
  fallback: 'markdown-only: yad-ui writes ui-design.md and DESIGN.md only',
256
256
  records: null, note: 'Sign-in is your own (OAuth); yadflow stores no token. The desktop server is named figma-desktop.',
257
+ // #358: how a UI task checks the tool can be reached before it starts. `provider` in design.json says
258
+ // which server: `figma-desktop` reads through the running app; `figma` (the hosted server) needs the
259
+ // person signed in, not an app; the older `figma-mcp` could be either, so its message names both.
260
+ // `html-to-design` only writes (import-html) and cannot read a frame. Any other provider name — the
261
+ // MCP id is free text — is probed, with the message that names both servers.
262
+ reach: {
263
+ app: 'Figma', writers: ['html-to-design'], appBound: ['figma-desktop'], signInOnly: ['figma'],
264
+ probe: 'read frame <frame> through the Figma MCP (get_metadata, with that node ID)',
265
+ open: 'Open the Figma desktop app with <file> loaded and its Dev Mode MCP server on, then continue',
266
+ signIn: 'Sign in to Figma in your agent (its Figma MCP server), check that you can open <file>, then continue',
267
+ either: 'Open the Figma desktop app with <file> loaded (if you use its desktop MCP server), or sign in to Figma in your agent (the hosted server), then continue',
268
+ },
257
269
  usedBy: ['yad-connect-design', 'yad-ui'],
258
270
  },
259
271
  {
@@ -271,6 +283,12 @@ export const TOOLBOX = Object.freeze([
271
283
  versions: null,
272
284
  fallback: 'markdown-only: yad-ui writes ui-design.md and DESIGN.md only',
273
285
  records: null, note: 'Set up inside the desktop app: open a .pen file, then Settings → MCP → enable your agent.',
286
+ // #358: Pencil is read through the running desktop app, so the app must be open with the file loaded.
287
+ reach: {
288
+ app: 'Pencil', appBound: true,
289
+ probe: 'read the app state through the Pencil MCP (get_app_state, or get_editor_state): the active canvas editor must be <file> — compare by file name, as the app shows the full path. Frame <frame> may sit inside a container frame, so if it is not in the top-level list, read it by its ID (batch_get, or the node-read tool your Pencil MCP has) before calling it missing',
290
+ open: 'Open the Pencil desktop app with <file> loaded, then continue',
291
+ },
274
292
  usedBy: ['yad-connect-design', 'yad-ui'],
275
293
  },
276
294
  {
@@ -405,6 +423,19 @@ export function toolProblems(t) {
405
423
  need(t?.manual === null || (typeof t?.manual === 'string' && /^https:\/\//.test(t.manual)), 'manual is null or an https URL');
406
424
  need(isStringList(t?.usedBy), 'usedBy lists the skills or commands that use it');
407
425
  need(t?.tier !== 'connector' || !isStringList(t?.usedBy) || connectorFile(t) !== null, 'a connector names the yad-connect-* skill that connects it');
426
+ // #358 reach: `appBound` is `true` (every provider) or a list of providers; `writers` (optional) lists the
427
+ // providers that cannot read a frame. Provider names are compared in lower case. A tool whose
428
+ // providers need no app writes `appBound: []`; then `signIn` (a provider in `signInOnly`) and `either`
429
+ // (a provider in neither list, so yad cannot tell) say what to do instead.
430
+ const r = t?.reach;
431
+ if (r !== undefined) {
432
+ const text = (v) => typeof v === 'string' && v.length > 0;
433
+ need(r && typeof r === 'object' && text(r.app) && text(r.probe) && text(r.open), 'reach has app, probe and open');
434
+ need(r?.writers === undefined || isStringList(r?.writers), 'reach.writers is absent or the providers that cannot read a frame');
435
+ need(r?.appBound === true || isStringList(r?.appBound), 'reach.appBound is true, or the providers read through the app');
436
+ need(r?.signInOnly === undefined || isStringList(r?.signInOnly), 'reach.signInOnly is absent or a list of providers');
437
+ need(r?.appBound === true || (text(r?.signIn) && text(r?.either)), 'reach.signIn and reach.either say what to do when the provider needs no app, or yad cannot tell');
438
+ }
408
439
  return out;
409
440
  }
410
441
 
@@ -771,6 +802,9 @@ export function connectorFile(tool) {
771
802
  }
772
803
 
773
804
  // The skills (folders under skills/, not `yad <command>`s) that use a tool.
805
+ // #358 — how a UI task checks a design tool can be reached, or null when yad has no check for it.
806
+ export const reachFor = (id) => TOOLBOX.find((t) => t.id === id)?.reach ?? null;
807
+
774
808
  export const skillsUsing = (tool) => tool.usedBy.filter((u) => !u.startsWith('yad '));
775
809
 
776
810
  // The line a skill writes when the tool was not used. `recordsElse` is the one case where the skill chose
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "yadflow",
3
- "version": "4.8.0",
3
+ "version": "4.9.0",
4
4
  "description": "Shared project memory and workflows for teams building with AI: a versioned record of plans, decisions, contracts and reviews across repos, human-approved review gates, and a zero-dependency `yad` CLI plus 39 skills for your AI assistant.",
5
5
  "type": "module",
6
6
  "author": "AbdelRahman Nasr",
@@ -46,12 +46,12 @@
46
46
  "scripts": {
47
47
  "yad": "node bin/yad.mjs",
48
48
  "lint": "eslint cli bin",
49
- "test": "node --test cli/test.mjs cli/test-checks.mjs cli/test-threads.mjs cli/test-golden.mjs cli/test-migrate.mjs cli/test-hooks.mjs cli/test-detect.mjs cli/test-members.mjs cli/test-standup.mjs cli/test-lifecycle.mjs cli/test-run-checks.mjs cli/test-build.mjs cli/test-worktree.mjs cli/test-guide.mjs cli/test-agents-file.mjs cli/test-setup-agent.mjs cli/test-signing.mjs cli/test-ci-check.mjs cli/test-node.mjs cli/test-fuzz.js",
49
+ "test": "node --test cli/test.mjs cli/test-checks.mjs cli/test-threads.mjs cli/test-golden.mjs cli/test-migrate.mjs cli/test-hooks.mjs cli/test-detect.mjs cli/test-members.mjs cli/test-standup.mjs cli/test-lifecycle.mjs cli/test-run-checks.mjs cli/test-build.mjs cli/test-worktree.mjs cli/test-guide.mjs cli/test-agents-file.mjs cli/test-setup-agent.mjs cli/test-signing.mjs cli/test-ci-check.mjs cli/test-node.mjs cli/test-machine.mjs cli/test-story-frames.mjs cli/test-preview.mjs cli/test-fuzz.js",
50
50
  "test:e2e": "bash test/e2e/run.sh",
51
51
  "test:agents": "bash test/agent-acceptance/run.sh",
52
52
  "test:agents:selftest": "bash test/agent-acceptance/run.sh selftest",
53
53
  "release-check": "bash scripts/release-check.sh",
54
- "coverage": "node --test --test-reporter=tap --experimental-test-coverage --test-coverage-exclude='cli/test*.mjs' --test-coverage-exclude='cli/test*.js' --test-coverage-lines=70 --test-coverage-branches=70 cli/test.mjs cli/test-checks.mjs cli/test-threads.mjs cli/test-golden.mjs cli/test-migrate.mjs cli/test-hooks.mjs cli/test-detect.mjs cli/test-members.mjs cli/test-standup.mjs cli/test-lifecycle.mjs cli/test-run-checks.mjs cli/test-build.mjs cli/test-worktree.mjs cli/test-guide.mjs cli/test-agents-file.mjs cli/test-setup-agent.mjs cli/test-signing.mjs cli/test-ci-check.mjs cli/test-node.mjs cli/test-fuzz.js",
54
+ "coverage": "node --test --test-reporter=tap --experimental-test-coverage --test-coverage-exclude='cli/test*.mjs' --test-coverage-exclude='cli/test*.js' --test-coverage-lines=70 --test-coverage-branches=70 cli/test.mjs cli/test-checks.mjs cli/test-threads.mjs cli/test-golden.mjs cli/test-migrate.mjs cli/test-hooks.mjs cli/test-detect.mjs cli/test-members.mjs cli/test-standup.mjs cli/test-lifecycle.mjs cli/test-run-checks.mjs cli/test-build.mjs cli/test-worktree.mjs cli/test-guide.mjs cli/test-agents-file.mjs cli/test-setup-agent.mjs cli/test-signing.mjs cli/test-ci-check.mjs cli/test-node.mjs cli/test-machine.mjs cli/test-story-frames.mjs cli/test-preview.mjs cli/test-fuzz.js",
55
55
  "diagrams": "npx -y @mermaid-js/mermaid-cli@11.15.0 -i docs/diagrams/sdlc-overview.mmd -o docs/diagrams/sdlc-overview.svg -b transparent && npx -y @mermaid-js/mermaid-cli@11.15.0 -i docs/diagrams/review-loop.mmd -o docs/diagrams/review-loop.svg -b transparent && npx -y @mermaid-js/mermaid-cli@11.15.0 -i docs/diagrams/work-and-memory.mmd -o docs/diagrams/work-and-memory.svg -b transparent && npx -y @mermaid-js/mermaid-cli@11.15.0 -i docs/diagrams/feature-evolution.mmd -o docs/diagrams/feature-evolution.svg -b transparent",
56
56
  "prepublishOnly": "npm test"
57
57
  },
@@ -67,8 +67,11 @@ Determine which tool is being connected from `tool` (default `figma`); reject a
67
67
  - **pencil** → the `pencil` MCP (`batch_design` writes `.pen` web/mobile screens — generate-capable).
68
68
  - another adapter → its named MCP.
69
69
 
70
- Record `provider` (the concrete MCP, e.g. `figma-mcp` | `html-to-design` | `pencil-mcp`) and whether it
71
- is available. **Auth is the local user's own** — the user's authenticated MCP session. The skill
70
+ Record `provider` (the concrete MCP) and whether it is available. For Figma, say which server it is,
71
+ because a UI task checks it before it starts (#358): `figma-desktop` (the Dev Mode MCP server inside the
72
+ running desktop app — the app must be open), `figma` (Figma's hosted server — a sign-in, no app), or
73
+ `html-to-design` (writes screens only, cannot read a frame). For Pencil, `pencil-mcp`. The older value
74
+ `figma-mcp` does not say which Figma server it is: on a refresh, record the exact one. **Auth is the local user's own** — the user's authenticated MCP session. The skill
72
75
  **stores no tokens**; `project_url`/`files` are plain references, never credentials.
73
76
 
74
77
  **Graceful degradation:** if no design-tool MCP is available, record `source: "unavailable"` and report
@@ -81,13 +84,13 @@ Upsert into `{project-root}/.sdlc/design.json` (create the file + parent `.sdlc/
81
84
  ```json
82
85
  {
83
86
  "tool": "figma",
84
- "provider": "figma-mcp",
87
+ "provider": "figma-desktop",
85
88
  "project_url": "https://www.figma.com/files/project/<id>/<name>",
86
89
  "auth": "user",
87
90
  "files": { "web": null, "mobile": null },
88
91
  "connectedAt": "<YYYY-MM-DD>",
89
92
  "lastSyncedAt": "<YYYY-MM-DD>",
90
- "source": "figma-mcp"
93
+ "source": "figma-desktop"
91
94
  }
92
95
  ```
93
96
 
@@ -56,6 +56,29 @@ it authors `ui-design.md` / `DESIGN.md` exactly as before and records `design: n
56
56
  with a one-line note (mirroring the `impeccable: not-installed` degrade). No error — the design tool is
57
57
  purely additive.
58
58
 
59
+ ## Reachable before Build (#358)
60
+
61
+ A design tool read through its running desktop app — Pencil, or Figma's `figma-desktop` server — cannot be
62
+ read while the app is closed or the design file is not open. So before a UI task, `yad-spec` and
63
+ `yad-implement` check it first, and stop early when it fails. yad itself cannot call an MCP server (it
64
+ belongs to the agent's session), so `yad story frames <story> --json` returns a `preflight` block that says
65
+ how to check and what to tell the person; the text for each tool is the toolbox entry's `reach` field.
66
+
67
+ | `tool` | What the agent checks | When it fails |
68
+ |--------|-----------------------|---------------|
69
+ | `pencil` | `get_app_state` (or `get_editor_state`): the active canvas editor is the design file, compared by file name (the app shows the full path). A frame inside a container is not in the top-level list, so it is read by its ID before it counts as missing | open the Pencil desktop app with the file loaded, then continue |
70
+ | `figma`, provider `figma-desktop` | `get_metadata` on one recorded frame | open the Figma desktop app with the file loaded and its Dev Mode MCP server on |
71
+ | `figma`, provider `figma` (hosted) | `get_metadata` on one recorded frame | sign in to Figma in your agent; no app is needed |
72
+ | `figma`, provider `figma-mcp` (older value), any other name, or none | `get_metadata` on one recorded frame | either of the two above — yad cannot tell which server it is |
73
+ | `figma`, provider `html-to-design` | nothing: it writes screens and cannot read a frame | not checked; build from the frame links |
74
+
75
+ Also not checked (build from the frame links): no `design.json`, tool `none`, source `unavailable`; no
76
+ `design-links.json`, one that cannot be read, or one recorded for another tool (re-run the UI step); and a
77
+ story whose recorded frame IDs are all missing from `design-links.json` — the bad IDs are the problem then.
78
+
79
+ A failed check stops the step. The person may choose to go on from the frame links only; that choice is
80
+ recorded (in `spec.md`'s Clarifications, or the commit's Decisions paragraph).
81
+
59
82
  ## Staleness / refresh
60
83
 
61
84
  A re-generated or designer-edited file is like a moved code repo: `yad-ui` **flags** a divergence and
@@ -15,13 +15,13 @@ root, not under any `epics/EP-<slug>/.sdlc/`.
15
15
  ```json
16
16
  {
17
17
  "tool": "figma", // figma | pencil | <adapter id> | none (markdown-only)
18
- "provider": "figma-mcp", // the concrete MCP: figma-mcp | html-to-design | pencil-mcp | null
18
+ "provider": "figma-desktop", // the concrete MCP: figma-desktop | figma | html-to-design | pencil-mcp | null (figma-mcp: older, either Figma server)
19
19
  "project_url": "https://www.figma.com/files/project/123/feature", // team/project/file reference; null if none yet
20
20
  "auth": "user", // ALWAYS the user's own MCP session — never a token
21
21
  "files": { "web": null, "mobile": null }, // optional default file refs per platform
22
22
  "connectedAt": "2026-06-13", // first connect (YYYY-MM-DD)
23
23
  "lastSyncedAt": "2026-06-13", // last connect/refresh
24
- "source": "figma-mcp" // the MCP detected at connect | unavailable (degraded)
24
+ "source": "figma-desktop" // the MCP detected at connect | unavailable (degraded)
25
25
  }
26
26
  ```
27
27
 
@@ -36,7 +36,7 @@ root, not under any `epics/EP-<slug>/.sdlc/`.
36
36
  session.
37
37
  - **`connect` overwrites in place** — a project carries exactly one design connection at a time;
38
38
  switching tools is just another `connect`. There is no array (unlike `repos.json`).
39
- - **`source`** is the authority for availability: an MCP id (`figma-mcp` / `pencil-mcp` / …) means
39
+ - **`source`** is the authority for availability: an MCP id (`figma-desktop` / `figma` / `pencil-mcp` / …) means
40
40
  `yad-ui` can generate/link; `unavailable` means `yad-ui` degrades to markdown-only. `refresh`
41
41
  re-detects and may flip it.
42
42
  - **`tool: "none"`** is a valid, deliberate state: a project that has chosen markdown-only. `yad-ui`
@@ -180,6 +180,14 @@ new repo later is the same `connect` action. Write no `domain_owner`/`domain_own
180
180
  release wrote with them is left as it is (nothing reads them, and `yad doctor` warns
181
181
  `people:domain-owners-unused`).
182
182
 
183
+ **Preview address (optional, #359).** A repo whose PRs/MRs get a live preview deployment (Vercel,
184
+ Netlify, a GitLab review app) can record its address pattern as `preview_url`, for example
185
+ `"https://pr-{pr}.myapp.dev"` (placeholders `{pr}`, `{branch}`, `{repo}`; https only, or
186
+ `http://localhost`). Ask the person for it; never guess one. Write it with
187
+ `yad repo preview <repo> <pattern>` (it checks the pattern; `--clear` removes it), not by hand. With no
188
+ pattern, review steps ask the platform for the PR's deployment, and else say the design check ran
189
+ locally only.
190
+
183
191
  ### Step 5 — Report
184
192
  Report the connected repo, its `platform`, the pack + code-map paths, the secret-scan result, and that
185
193
  the Shape phases will now load this repo's code-map. Nothing auto-advances; this is setup.
@@ -59,6 +59,19 @@ asking questions, answering theirs, until both are satisfied — then records th
59
59
  growth in the local-only learning log. Still soft: it rides the same `engagement: verified` signal and
60
60
  never gates. When a pair session backs the approve, you may set `companion.pair: true` on the ship record.
61
61
 
62
+ **Live design check (a UI change only, #359).** A live design check opens the running page and looks
63
+ at it at several screen widths (phone, tablet, desktop). `yad review context --repo <r> --pr <n> --json`
64
+ carries a `preview` field that says where to run it:
65
+ - `preview.url` set (`source: pattern` from the repo's `yad repo preview` pattern, or `source: platform`
66
+ from the deployment GitHub/GitLab records for the PR): run the check against `preview.url`, and name it
67
+ in the review ("checked live on <url> at 375, 768 and 1280 px"). The address is where the preview
68
+ should be, not proof that it is there: if the page does not load, or does not show this PR's change
69
+ yet, treat it as `local-only` and say so.
70
+ - `source: local-only`: there is no preview deployment. Run the check on the developer's machine if you
71
+ can, and say plainly, in the review and in a PR comment, **"design check ran locally only: <preview.why>"**.
72
+ Never present a local check as a check of the deployed page. `preview.why` names the fix
73
+ (`yad repo preview <repo> <pattern>`); offer it, never run it unasked.
74
+
62
75
  ### Step 2 — `approve` (the engineer review — the human gate)
63
76
  A human engineer reads the diff **against the spec** (`specs/<story>/`) and the acceptance criteria,
64
77
  and records an approval. Determine the count with `bash checks/risk-route.sh <pr-body-file> origin/<base>`,
@@ -724,6 +724,12 @@ chain is unchanged — this is an *output enrichment*, mirrored by the `design:`
724
724
  "source": "<mcp id>" }
725
725
  ```
726
726
 
727
+ **Who reads it (#354):** each story lists the `nodeId`s of the screens it builds in its own
728
+ `design-frames: [<id>, …]` frontmatter field (written by `yad-stories`). `yad story frames <story>` looks
729
+ each ID up here for its name, platform and link; `yad-spec` and `yad-implement` run it, and `yad doctor`
730
+ warns (`stories:design-frames`) on an ID this file does not hold. So keep a frame's `nodeId` the same when
731
+ the design changes.
732
+
727
733
  ## `test-links.json`
728
734
  Present only when the `test-cases` step materialized automation in a connected testing tool
729
735
  (`yad-connect-testing` → `.sdlc/testing.json`). Written by `yad-test-cases`, the machine-readable
@@ -69,8 +69,8 @@ Only the person does these:
69
69
 
70
70
  `yad guide --json` gives each command its `class` and `ask`. In short:
71
71
 
72
- - **read** — run it without asking. `yad guide`, `yad help`, `yad check` (not with `--fix`, `--push`, `--open-pr`, `--overwrite-local`, `--allow-branch`), `yad doctor`, `yad migrate` (not with `--apply`), `yad detect`, `yad signing check`, `yad ci check`, `yad toolbox list`, `yad toolbox check`, `yad skill list`, `yad skill recommend`, `yad report` (not with `--post`), `yad foundation status`, `yad status`, `yad next`, `yad dial` (not with `--to`), `yad mode`, `yad gate status`, `yad gate review`, `yad gate walkthrough`, `yad review context`, `yad review chat`, `yad review cards`, `yad review walkthrough`, `yad build merged` (not with `--ship`), `yad member list`, `yad worktree list`, `yad standup`, `yad claims`, `yad owners`, `yad history list`, `yad history show`, `yad history search`, `yad repo list`, `yad risk-map check`, `yad codeowners check`, `yad docs list`, `yad thread`, `yad reconcile check`.
73
- - **local-write** — run it without asking. `yad check --fix`, `yad update` (not with `--push`, `--open-pr`, `--overwrite-local`, `--allow-branch`), `yad migrate --apply`, `yad usage`, `yad sync-status`, `yad epic new`, `yad foundation new`, `yad gate comments`, `yad gate repair` (not with `--push`, `--allow-branch`), `yad review reconcile`, `yad commit` (not with `--manual`, `--force`, `--ai`), `yad build start`, `yad build step`, `yad build trust` (not with `--uid`), `yad build ship` (not with `--merge-commit`, `--approver`), `yad build merged --ship`, `yad build done`, `yad build sync`, `yad run checks`, `yad checkpoint` (not with `--push`, `--retro-ship`, `--allow-branch`), `yad member remove` (not with `--reason`), `yad worktree add`, `yad worktree remove`, `yad assign` (not with `--force`), `yad unassign` (not with `--force`), `yad fold`, `yad tidy up` (not with `--push`, `--allow-branch`), `yad index`, `yad repo refresh` (not with `--push`, `--allow-branch`), `yad repo sync`, `yad repo clone`, `yad risk-map draft`, `yad docs build`, `yad docs sync`, `yad docs deploy`, `yad reconcile refresh`, `yad reconcile wire`.
72
+ - **read** — run it without asking. `yad guide`, `yad help`, `yad check` (not with `--fix`, `--push`, `--open-pr`, `--overwrite-local`, `--allow-branch`), `yad doctor`, `yad migrate` (not with `--apply`), `yad detect`, `yad signing check`, `yad ci check`, `yad toolbox list`, `yad toolbox check`, `yad skill list`, `yad skill recommend`, `yad report` (not with `--post`), `yad foundation status`, `yad status`, `yad next`, `yad dial` (not with `--to`), `yad mode`, `yad gate status`, `yad gate review`, `yad gate walkthrough`, `yad review context`, `yad review chat`, `yad review cards`, `yad review walkthrough`, `yad build merged` (not with `--ship`), `yad member list`, `yad worktree list`, `yad standup`, `yad claims`, `yad owners`, `yad history list`, `yad history show`, `yad history search`, `yad repo list`, `yad risk-map check`, `yad codeowners check`, `yad story frames`, `yad docs list`, `yad thread`, `yad reconcile check`.
73
+ - **local-write** — run it without asking. `yad check --fix`, `yad update` (not with `--push`, `--open-pr`, `--overwrite-local`, `--allow-branch`), `yad migrate --apply`, `yad usage`, `yad sync-status`, `yad epic new`, `yad foundation new`, `yad gate comments`, `yad gate repair` (not with `--push`, `--allow-branch`), `yad review reconcile`, `yad commit` (not with `--manual`, `--force`, `--ai`), `yad build start`, `yad build step`, `yad build trust` (not with `--uid`), `yad build ship` (not with `--merge-commit`, `--approver`), `yad build merged --ship`, `yad build done`, `yad build sync`, `yad run checks`, `yad checkpoint` (not with `--push`, `--retro-ship`, `--allow-branch`), `yad member remove` (not with `--reason`), `yad worktree add`, `yad worktree remove`, `yad assign` (not with `--force`), `yad unassign` (not with `--force`), `yad fold`, `yad tidy up` (not with `--push`, `--allow-branch`), `yad index`, `yad repo refresh` (not with `--push`, `--allow-branch`), `yad repo sync`, `yad repo clone`, `yad repo preview`, `yad risk-map draft`, `yad docs build`, `yad docs sync`, `yad docs deploy`, `yad reconcile refresh`, `yad reconcile wire`.
74
74
  - **open-pr** — run it without asking. `yad join`, `yad check --open-pr`, `yad update --open-pr`, `yad gate open`, `yad gate sync`, `yad gate trailer`, `yad review trailer`, `yad review nudge`, `yad capture`, `yad member add`.
75
75
  - **task-pr** — ask first, unless `yad dial open-pr` is `auto`. `yad open-pr`, `yad ship` (not with `--force`, `--ai`).
76
76
  - **default-push** — ask the person every time, naming what it will do; run it only on a yes. `yad check --push`, `yad update --push`, `yad gate repair --push`, `yad checkpoint --push`, `yad tidy up --push`, `yad repo refresh --push`.
@@ -108,6 +108,20 @@ light spec has only `spec.md`: its `## Plan` section is the plan, and it has no
108
108
  contract slice is **quoted** from the product repo's locked `contract.md` — implement to it, never
109
109
  change it here.
110
110
 
111
+ **For a task with UI, read its design frames (#354).** Run `yad story frames <story> --json` (yad finds
112
+ the Product from the code repo). Its `frames` list names each design-tool frame the story builds, with
113
+ its `name`, `platform` and `url`; `spec.md`'s `## Design frames` section, when there is one, says the
114
+ same. Build to those frames: open them through the connected design tool's MCP when there is one, and
115
+ read them from their `url` otherwise. Never pick a frame by its look or its name alone. An ID it cannot
116
+ find is an open question for the batch below, not a guess.
117
+
118
+ **Before any code for a task with UI, check the design tool can be reached (#358).** When that answer's
119
+ `preflight.reachable` is `check`, make the MCP call `preflight.probe` describes. If it fails, or another
120
+ file is open, **STOP**: print `preflight.stop` word for word and wait. Go on without the design tool, from
121
+ the frame links only, only when the person says so, and record that in the commit's `Decisions:`
122
+ paragraph (Step 6) as `design tool not reachable: continued from the frame links, on <person>'s word`.
123
+ `not-checkable` means there is nothing to probe: go on from the links. `preflight: null` means no frames.
124
+
111
125
  **Then ask the batch (#357)** that **Ask the human-only questions first** above describes, before
112
126
  writing any code. Read `spec.md`'s `## Clarifications` first: `yad-spec` recorded its answers there.
113
127
  Ask only what is still open for THIS task, from its block in `tasks.md`, `plan.md` and the contract