yadflow 4.9.0 → 4.11.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 (155) hide show
  1. package/CHANGELOG.md +184 -0
  2. package/README.md +15 -5
  3. package/bin/commands.mjs +11 -1
  4. package/bin/yad.mjs +203 -14
  5. package/cli/agent-guard-worker.mjs +13 -0
  6. package/cli/agent-guard.mjs +1797 -73
  7. package/cli/agent-rules.mjs +64 -5
  8. package/cli/argv-flags.mjs +2 -2
  9. package/cli/brain/vendor/LICENSE-graphology-library.txt +21 -0
  10. package/cli/brain/vendor/LICENSE-graphology.txt +21 -0
  11. package/cli/brain/vendor/LICENSE-sigma.txt +12 -0
  12. package/cli/brain/vendor/graphology-library.min.js +2 -0
  13. package/cli/brain/vendor/graphology.umd.min.js +2 -0
  14. package/cli/brain/vendor/sigma.min.js +1369 -0
  15. package/cli/brain/view/app.js +382 -0
  16. package/cli/brain/view/index.html +63 -0
  17. package/cli/brain/view/live.css +228 -0
  18. package/cli/brain/view/live.html +110 -0
  19. package/cli/brain/view/live.js +884 -0
  20. package/cli/brain/view/style.css +141 -0
  21. package/cli/brain-about.mjs +206 -0
  22. package/cli/brain-activity.mjs +285 -0
  23. package/cli/brain-skills.mjs +118 -0
  24. package/cli/brain-vendor.mjs +71 -0
  25. package/cli/brain-view.mjs +344 -0
  26. package/cli/brain.mjs +810 -0
  27. package/cli/ci-check.mjs +48 -4
  28. package/cli/codeowners-command.mjs +72 -6
  29. package/cli/commit.mjs +17 -3
  30. package/cli/docs.mjs +2 -0
  31. package/cli/doctor.mjs +151 -25
  32. package/cli/epic-state.mjs +186 -4
  33. package/cli/epic.mjs +26 -10
  34. package/cli/errors.mjs +2 -1
  35. package/cli/find-product.mjs +69 -15
  36. package/cli/fold.mjs +31 -6
  37. package/cli/foundation-publish.mjs +256 -0
  38. package/cli/gate.mjs +29 -3
  39. package/cli/git-read.mjs +38 -0
  40. package/cli/guard-stream.mjs +409 -0
  41. package/cli/guide.mjs +3 -1
  42. package/cli/hook.mjs +102 -9
  43. package/cli/issue-links.mjs +61 -0
  44. package/cli/issues-act.mjs +371 -0
  45. package/cli/issues-write.mjs +441 -0
  46. package/cli/issues.mjs +513 -0
  47. package/cli/lib.mjs +37 -2
  48. package/cli/lifecycle.mjs +7 -0
  49. package/cli/local-page.mjs +138 -0
  50. package/cli/machine.mjs +1 -1
  51. package/cli/manifest.mjs +59 -3
  52. package/cli/map/view/app.js +712 -0
  53. package/cli/map/view/index.html +50 -0
  54. package/cli/map/view/style.css +142 -0
  55. package/cli/map-view.mjs +186 -0
  56. package/cli/map.mjs +637 -0
  57. package/cli/members.mjs +9 -15
  58. package/cli/next.mjs +1 -1
  59. package/cli/openpr.mjs +26 -6
  60. package/cli/plan.mjs +127 -0
  61. package/cli/platform.mjs +159 -4
  62. package/cli/product-index.mjs +1 -1
  63. package/cli/protection.mjs +53 -3
  64. package/cli/reconcile.mjs +9 -3
  65. package/cli/report.mjs +9 -3
  66. package/cli/reports-dir.mjs +391 -0
  67. package/cli/reports.mjs +65 -0
  68. package/cli/run-checks.mjs +15 -4
  69. package/cli/scan.mjs +314 -0
  70. package/cli/setup.mjs +42 -8
  71. package/cli/standup.mjs +120 -78
  72. package/cli/status.mjs +6 -5
  73. package/cli/story-frames.mjs +17 -6
  74. package/cli/test-agents-file.mjs +985 -12
  75. package/cli/test-brain-activity.mjs +753 -0
  76. package/cli/test-brain-view.mjs +381 -0
  77. package/cli/test-brain.mjs +795 -0
  78. package/cli/test-build.mjs +25 -0
  79. package/cli/test-ci-check.mjs +469 -10
  80. package/cli/test-guide.mjs +218 -0
  81. package/cli/test-machine.mjs +59 -0
  82. package/cli/test-map.mjs +615 -0
  83. package/cli/test-node.mjs +15 -0
  84. package/cli/test-reports.mjs +382 -0
  85. package/cli/test-run-checks.mjs +21 -0
  86. package/cli/test-setup-agent.mjs +14 -0
  87. package/cli/test-story-frames.mjs +74 -4
  88. package/cli/test-worktree.mjs +24 -3
  89. package/cli/toolbox-connect.mjs +259 -0
  90. package/cli/toolbox.mjs +187 -12
  91. package/cli/update-commit.mjs +101 -9
  92. package/cli/usage.mjs +8 -4
  93. package/package.json +12 -4
  94. package/skills/sdlc/config.yaml +1 -1
  95. package/skills/sdlc/module-help.csv +3 -1
  96. package/skills/yad-analysis/SKILL.md +4 -0
  97. package/skills/yad-architecture/SKILL.md +22 -4
  98. package/skills/yad-backfill/SKILL.md +4 -0
  99. package/skills/yad-change/SKILL.md +7 -1
  100. package/skills/yad-change/references/triage.md +2 -0
  101. package/skills/yad-checks/SKILL.md +15 -7
  102. package/skills/yad-checks/references/check-gates.md +70 -35
  103. package/skills/yad-checks/templates/checks/build-test-lint.sh +7 -0
  104. package/skills/yad-checks/templates/checks/install-deps.sh +6 -0
  105. package/skills/yad-checks/templates/checks/member-check.mjs +3 -2
  106. package/skills/yad-checks/templates/checks/package-manager.sh +42 -0
  107. package/skills/yad-checks/templates/checks/risk-map-check.sh +2 -2
  108. package/skills/yad-checks/templates/checks/verified-commits.sh +3 -3
  109. package/skills/yad-checks/templates/github/yad-checks.yml +358 -69
  110. package/skills/yad-checks/templates/github/yad-pr-text.yml +118 -0
  111. package/skills/yad-checks/templates/github/yad-product-checks.yml +130 -54
  112. package/skills/yad-checks/templates/github/yad-product-pr-text.yml +131 -0
  113. package/skills/yad-checks/templates/github/yad-update-guard.yml +2 -1
  114. package/skills/yad-checks/templates/github/yad-verified-commits.yml +49 -3
  115. package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml +80 -20
  116. package/skills/yad-checks/templates/gitlab/yad-product-checks.gitlab-ci.yml +59 -9
  117. package/skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml +1 -0
  118. package/skills/yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml +49 -1
  119. package/skills/yad-checks/templates/hooks/agent-guard.mjs +44 -10
  120. package/skills/yad-checks/templates/hooks/ledger-guard-cursor.mjs +12 -6
  121. package/skills/yad-checks/templates/hooks/yad-activity.mjs +238 -0
  122. package/skills/yad-commit/SKILL.md +3 -1
  123. package/skills/yad-connect-design/SKILL.md +42 -10
  124. package/skills/yad-connect-design/references/design-context.md +35 -5
  125. package/skills/yad-connect-design/references/design-registry.md +3 -3
  126. package/skills/yad-connect-learning/SKILL.md +12 -2
  127. package/skills/yad-connect-repos/SKILL.md +18 -0
  128. package/skills/yad-connect-testing/SKILL.md +22 -5
  129. package/skills/yad-connect-testing/references/testing-context.md +1 -1
  130. package/skills/yad-discovery/SKILL.md +11 -0
  131. package/skills/yad-discovery/references/foundation-schema.md +11 -0
  132. package/skills/yad-docs/templates/app/package-lock.json +18 -10
  133. package/skills/yad-docs/templates/app/package.json +6 -1
  134. package/skills/yad-epic/SKILL.md +7 -0
  135. package/skills/yad-epic/references/state-schema.md +50 -1
  136. package/skills/yad-guide/SKILL.md +8 -4
  137. package/skills/yad-implement/SKILL.md +117 -4
  138. package/skills/yad-implement/references/implement-conventions.md +2 -1
  139. package/skills/yad-issues/SKILL.md +54 -0
  140. package/skills/yad-learn/SKILL.md +4 -0
  141. package/skills/yad-open-pr/SKILL.md +6 -0
  142. package/skills/yad-pr-template/SKILL.md +2 -1
  143. package/skills/yad-pr-template/templates/checks/pr-template.sh +8 -4
  144. package/skills/yad-pr-template/templates/checks/pr-title.sh +42 -6
  145. package/skills/yad-product-bridge/references/bridge.md +28 -0
  146. package/skills/yad-product-bridge/templates/github/yad-gate-sync.yml +25 -11
  147. package/skills/yad-product-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml +38 -14
  148. package/skills/yad-run/SKILL.md +5 -0
  149. package/skills/yad-scan/SKILL.md +51 -0
  150. package/skills/yad-spec/SKILL.md +32 -2
  151. package/skills/yad-stories/SKILL.md +22 -4
  152. package/skills/yad-stories/references/story-schema.md +1 -1
  153. package/skills/yad-test-cases/SKILL.md +18 -2
  154. package/skills/yad-ui/SKILL.md +43 -8
  155. package/skills/yad-checks/templates/gitlab/.gitlab-ci.yml +0 -49
@@ -0,0 +1,238 @@
1
+ // yad-activity HARNESS HOOK — the live activity record behind `yad brain view --live` (E178).
2
+ //
3
+ // Runs AFTER an agent uses a tool, and appends ONE line to `<git common dir>/yad-activity.jsonl`: what kind
4
+ // of thing it did (read, search, edit, run), which files of this repo it touched, and when. The live view
5
+ // tails that file and lights up the brain as the agent works.
6
+ //
7
+ // Wired by `yad check --fix` only when the Product sets `"activity": true` (off by default), in the Product
8
+ // and in each cloned code repo:
9
+ // Claude Code a `PostToolUse` hook in `.claude/settings.json`:
10
+ // node "$CLAUDE_PROJECT_DIR/hooks/yad-activity.mjs" --format claude
11
+ // Cursor `afterFileEdit` and `afterShellExecution` hooks in `.cursor/hooks.json`:
12
+ // node hooks/yad-activity.mjs --format cursor
13
+ // (in a code repo the file is `checks/yad-activity.mjs`, since a repo's own `hooks/` is often the app's).
14
+ //
15
+ // IT NEVER STARTS YAD: it fires on every file the agent reads, so it writes the line itself, with nothing
16
+ // but `node:` modules, in a few milliseconds.
17
+ //
18
+ // WHAT A LINE HOLDS — and nothing else, whatever the harness sends:
19
+ // { v: 1, ts, s, h, op, tool, paths, yad? }
20
+ // s the first 12 hex characters of sha256(session id) — sessions told apart, never named
21
+ // h 'claude' or 'cursor'
22
+ // op 'read' | 'search' | 'edit' | 'run'
23
+ // tool the harness's tool name (Read, Grep, Edit, Bash, afterFileEdit, …)
24
+ // paths up to 20 paths, relative to this repo; a path outside it, absolute, or reached through a link
25
+ // that leaves it is dropped
26
+ // yad for a shell command that is a yad command: '<command> [<action>]' from yad's own list — never the
27
+ // rest of the line
28
+ // NEVER STORED: search patterns, command text, prompts, file content, tool output, absolute paths.
29
+ //
30
+ // THE CONTRACT: it ALWAYS exits 0 and prints nothing on stdout, so it can never block or slow the agent. A
31
+ // problem is at most one line on stderr. A line is at most 4 KB, so an append lands whole even when two
32
+ // agents write at once. Above 5 MB the file is renamed to `yad-activity.1.jsonl` (one old file is kept).
33
+ import { createHash } from 'node:crypto';
34
+ import { spawnSync } from 'node:child_process';
35
+ import fs from 'node:fs';
36
+ import path from 'node:path';
37
+ import { fileURLToPath, pathToFileURL } from 'node:url';
38
+
39
+ export const LOG_NAME = 'yad-activity.jsonl';
40
+ export const OLD_LOG_NAME = 'yad-activity.1.jsonl';
41
+ export const ROTATE_AT = 5 * 1024 * 1024;
42
+ export const MAX_LINE = 4096;
43
+ export const MAX_PATHS = 20;
44
+
45
+ // The yad commands a `run` may name: every key of COMMAND_CLASS (cli/agent-rules.mjs), frozen here because a
46
+ // hook imports nothing of yad's. A test holds the two lists equal.
47
+ export const YAD_COMMANDS = Object.freeze([
48
+ 'assign', 'brain build', 'brain file', 'brain query', 'brain status', 'brain story', 'brain view', 'build done', 'build merged',
49
+ 'build ship', 'build start', 'build step', 'build sync', 'build trust', 'capture', 'check', 'checkpoint',
50
+ 'ci check', 'claims', 'codeowners check', 'commit', 'defer', 'detect', 'dial', 'docs build', 'docs deploy',
51
+ 'docs list', 'docs sync', 'doctor', 'epic new', 'fold', 'foundation new', 'foundation publish',
52
+ 'foundation status', 'gate advance', 'gate approve', 'gate ci', 'gate comment', 'gate comments',
53
+ 'gate open', 'gate reopen', 'gate repair', 'gate review', 'gate status', 'gate sync', 'gate trailer',
54
+ 'gate walkthrough', 'guide', 'help', 'history list', 'history search', 'history show', 'hook agent-guard',
55
+ 'hook ledger-guard', 'index', 'init', 'issues assign', 'issues close', 'issues comment', 'issues edit',
56
+ 'issues label', 'issues labels', 'issues link', 'issues list', 'issues new', 'issues reopen',
57
+ 'issues show', 'issues sync', 'issues unlink', 'join', 'kill', 'map', 'member add', 'member list',
58
+ 'member remove', 'migrate', 'mode', 'mode solo', 'mode team', 'new', 'next', 'open-pr', 'owners',
59
+ 'reconcile check', 'reconcile refresh', 'reconcile wire', 'repo clone', 'repo list', 'repo preview',
60
+ 'repo refresh', 'repo sync', 'report', 'reports list', 'reports open', 'reports prune', 'review cards', 'review chat', 'review context', 'review nudge',
61
+ 'review reconcile', 'review trailer', 'review walkthrough', 'risk-map check', 'risk-map draft', 'roster',
62
+ 'run checks', 'scan file', 'setup', 'ship', 'signing check', 'skill bind', 'skill list', 'skill recommend',
63
+ 'skill unbind', 'skip', 'standup', 'status', 'story frames', 'sync-status', 'thread', 'tidy up',
64
+ 'toolbox add', 'toolbox check', 'toolbox connect', 'toolbox list', 'toolbox remove', 'unassign', 'unblock',
65
+ 'undefer', 'unkill', 'unskip', 'update', 'usage', 'worktree add', 'worktree list', 'worktree remove',
66
+ ]);
67
+ const KNOWN = new Set(YAD_COMMANDS);
68
+
69
+ const CLAUDE_OPS = new Map([
70
+ ['Read', 'read'], ['Grep', 'search'], ['Glob', 'search'],
71
+ ['Edit', 'edit'], ['Write', 'edit'], ['MultiEdit', 'edit'], ['NotebookEdit', 'edit'],
72
+ ['Bash', 'run'],
73
+ ]);
74
+ const CURSOR_OPS = new Map([['afterFileEdit', 'edit'], ['afterShellExecution', 'run']]);
75
+
76
+ const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
77
+ const short = (v, n) => (typeof v === 'string' ? v.slice(0, n) : null);
78
+
79
+ // The real path of `abs`: its nearest part that exists, resolved through its links, with the rest (not
80
+ // written yet, or deleted) added back by name. Null when nothing on the way exists.
81
+ function realOf(abs) {
82
+ let head = abs;
83
+ const tail = [];
84
+ for (;;) {
85
+ try { return path.join(fs.realpathSync(head), ...tail); } catch { /* go up one */ }
86
+ const up = path.dirname(head);
87
+ if (up === head) return null;
88
+ tail.unshift(path.basename(head));
89
+ head = up;
90
+ }
91
+ }
92
+
93
+ // Text no harness sends as a file path, but that would read as a relative name: a home (`~`), a variable
94
+ // (`$HOME`, `%USERPROFILE%`), a URL (`file://…`), and — off Windows — a drive or a backslash path.
95
+ const NOT_A_PATH = process.platform === 'win32' ? /^[~$%]|^[a-z][a-z0-9+.-]*:\/\//i : /^[~$%]|[:\\]/;
96
+
97
+ // A path the harness gave, as a path relative to the repo, or null when it is not inside it. Judged on the
98
+ // REAL path (links resolved), against the repo's real root: a link inside the repo that points out is not the
99
+ // repo's, and a repo opened through a link (macOS /tmp, a linked projects folder, a Windows junction) still
100
+ // matches what the agent typed (E178 review 1).
101
+ export function repoPath(given, root, realRoot = root) {
102
+ if (typeof given !== 'string' || !given || given.length > 1024 || given.includes('\0') || NOT_A_PATH.test(given)) return null;
103
+ const real = realOf(path.resolve(root, given));
104
+ if (real === null) return null;
105
+ const rel = path.relative(realRoot, real);
106
+ if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return null;
107
+ return rel.split(path.sep).join('/');
108
+ }
109
+
110
+ // The yad command a shell line runs, as '<command> [<action>]', or null. Only a line that IS a yad command
111
+ // (optionally through npx) counts, and only words yad itself names are kept.
112
+ export function yadCommand(line) {
113
+ if (typeof line !== 'string') return null;
114
+ const m = /^\s*(?:npx\s+(?:--no-install\s+)?)?yad\s+([a-z][a-z-]{0,30})(?:\s+([a-z][a-z-]{0,30}))?(?=\s|$)/.exec(line);
115
+ if (!m) return null;
116
+ if (m[2] && KNOWN.has(`${m[1]} ${m[2]}`)) return `${m[1]} ${m[2]}`;
117
+ return KNOWN.has(m[1]) || YAD_COMMANDS.some((k) => k.startsWith(`${m[1]} `)) ? m[1] : null;
118
+ }
119
+
120
+ // The record for one payload, or null when the tool is not one this records.
121
+ export function recordOf(payload, { root, realRoot = root, now = Date.now(), format = 'claude' } = {}) {
122
+ if (!isObject(payload) || !root) return null;
123
+ const claude = format === 'claude';
124
+ const tool = claude ? short(payload.tool_name, 40) : short(payload.hook_event_name, 40);
125
+ const op = tool && (claude ? CLAUDE_OPS : CURSOR_OPS).get(tool);
126
+ if (!op) return null;
127
+ const input = claude ? (isObject(payload.tool_input) ? payload.tool_input : {}) : payload;
128
+ const given = [];
129
+ for (const key of ['file_path', 'notebook_path', 'path']) if (typeof input[key] === 'string') given.push(input[key]);
130
+ if (Array.isArray(input.edits)) for (const e of input.edits) if (isObject(e) && typeof e.file_path === 'string') given.push(e.file_path);
131
+ const paths = [];
132
+ for (const g of given) {
133
+ const p = repoPath(g, root, realRoot);
134
+ if (p && !paths.includes(p) && paths.length < MAX_PATHS) paths.push(p);
135
+ }
136
+ const session = short(claude ? payload.session_id : payload.conversation_id, 200);
137
+ const rec = {
138
+ v: 1,
139
+ ts: new Date(now).toISOString(),
140
+ s: session ? createHash('sha256').update(session).digest('hex').slice(0, 12) : null,
141
+ h: claude ? 'claude' : 'cursor',
142
+ op,
143
+ tool,
144
+ paths,
145
+ };
146
+ if (op === 'run') {
147
+ const y = yadCommand(input.command);
148
+ if (y) rec.yad = y;
149
+ }
150
+ return rec;
151
+ }
152
+
153
+ // One line, never longer than MAX_LINE: paths are dropped from the end until it fits.
154
+ export function lineOf(rec) {
155
+ const r = { ...rec, paths: [...rec.paths] };
156
+ let line = `${JSON.stringify(r)}\n`;
157
+ while (Buffer.byteLength(line) > MAX_LINE && r.paths.length) { r.paths.pop(); line = `${JSON.stringify(r)}\n`; }
158
+ return Buffer.byteLength(line) > MAX_LINE ? null : line;
159
+ }
160
+
161
+ // The folder git keeps this repo's shared data in. `<root>/.git` when it is a folder (the usual case, with
162
+ // no process started); for a worktree or a submodule, where `.git` is a file, git is asked.
163
+ export function gitCommonDir(root) {
164
+ const dotGit = path.join(root, '.git');
165
+ let here = null;
166
+ try { here = fs.lstatSync(dotGit); } catch { /* none here */ }
167
+ if (here && here.isDirectory()) return dotGit;
168
+ // No `.git` here: a repo whose root is ABOVE this folder (a Product in a subfolder, a monorepo app) —
169
+ // but only one that TRACKS files under it. A folder that merely sits inside some other repo (a home folder
170
+ // kept in git) is not that repo's, and its activity is written nowhere (E178 review 2). With no `.git`
171
+ // anywhere above, git is never started.
172
+ if (!here) {
173
+ let up = path.dirname(root);
174
+ let found = false;
175
+ for (;;) {
176
+ try { fs.lstatSync(path.join(up, '.git')); found = true; break; } catch { /* keep going */ }
177
+ const next = path.dirname(up);
178
+ if (next === up) break;
179
+ up = next;
180
+ }
181
+ if (!found) return null;
182
+ // One tracked file is the answer; a big folder's full list overflows a small buffer, and that is a yes
183
+ // too (E178 review 3), never a no.
184
+ const tracked = spawnSync('git', ['-C', root, 'ls-files', '-z', '--', '.'], { encoding: 'utf8', timeout: 2000, maxBuffer: 4096 });
185
+ const listed = String(tracked.stdout || '').length > 0;
186
+ if (!listed || (tracked.status !== 0 && tracked.error?.code !== 'ENOBUFS')) return null;
187
+ }
188
+ const r = spawnSync('git', ['-C', root, 'rev-parse', '--path-format=absolute', '--git-common-dir'], { encoding: 'utf8', timeout: 2000 });
189
+ const out = r.status === 0 ? String(r.stdout).trim() : '';
190
+ return out && path.isAbsolute(out) ? out : null;
191
+ }
192
+
193
+ // Append one line, renaming a full log aside first.
194
+ export function appendLine(dir, line) {
195
+ const file = path.join(dir, LOG_NAME);
196
+ let size = 0;
197
+ try { const st = fs.lstatSync(file); if (!st.isFile()) return; size = st.size; } catch { /* first line */ }
198
+ if (size + Buffer.byteLength(line) > ROTATE_AT) {
199
+ try { fs.renameSync(file, path.join(dir, OLD_LOG_NAME)); } catch { /* another agent rotated it first */ }
200
+ }
201
+ fs.appendFileSync(file, line, { flag: 'a' });
202
+ }
203
+
204
+ // Read the payload: never from a terminal, at most a second, at most 1 MB.
205
+ function readStdin() {
206
+ if (process.stdin.isTTY) return Promise.resolve('');
207
+ return new Promise((resolve) => {
208
+ const chunks = [];
209
+ let size = 0;
210
+ const done = () => { clearTimeout(timer); process.stdin.pause(); resolve(Buffer.concat(chunks).toString('utf8')); };
211
+ const timer = setTimeout(done, 1000);
212
+ process.stdin.on('data', (d) => { size += d.length; if (size <= 1024 * 1024) chunks.push(d); });
213
+ process.stdin.on('end', done);
214
+ process.stdin.on('error', done);
215
+ process.stdin.resume();
216
+ });
217
+ }
218
+
219
+ async function main() {
220
+ const text = await readStdin();
221
+ const argv = process.argv.slice(2);
222
+ const i = argv.indexOf('--format');
223
+ const format = i >= 0 && argv[i + 1] === 'cursor' ? 'cursor' : 'claude';
224
+ // The repo is this script's grandparent: `<repo>/hooks/yad-activity.mjs` or `<repo>/checks/yad-activity.mjs`.
225
+ const root = path.dirname(path.dirname(fs.realpathSync(fileURLToPath(import.meta.url))));
226
+ let payload;
227
+ try { payload = JSON.parse(text); } catch { return; }
228
+ const rec = recordOf(payload, { root, realRoot: fs.realpathSync(root), format });
229
+ if (!rec) return;
230
+ const line = lineOf(rec);
231
+ const dir = line && gitCommonDir(root);
232
+ if (dir) appendLine(dir, line);
233
+ }
234
+
235
+ // Run only as the hook itself; a test imports the functions above.
236
+ if (process.argv[1] && import.meta.url === pathToFileURL(fs.realpathSync(process.argv[1])).href) {
237
+ main().catch((e) => { process.stderr.write(` • yad activity: ${String(e?.message || e).slice(0, 200)}\n`); }).finally(() => process.exit(0));
238
+ }
@@ -16,7 +16,9 @@ and `yad-ship` use. It **never auto-advances**; it just commits.
16
16
  - Run **inside the repo holding the staged change** — a code repo under
17
17
  `{project-root}/demo-repos/<repo>/`, or the Product itself. Use absolute paths.
18
18
  - **Stage first.** Only the staged (`git add`) atomic change is committed. The guard refuses more than
19
- `ATOMIC_FILE_LIMIT` (3) staged files unless `--force` — split the change instead.
19
+ `ATOMIC_FILE_LIMIT` (3) staged files unless `--force` — split the change instead. In a Unity repo
20
+ (`ProjectSettings/ProjectVersion.txt` and `Assets/`), a staged `.meta` whose own file or folder is staged
21
+ too is not counted (#321).
20
22
  - **Subject** — `<type>: <lowercase imperative description, no trailing period>`; types are
21
23
  `feat|fix|docs|refactor|test|perf|build|ci|chore|revert`; proper nouns/acronyms keep their case.
22
24
  - **Task trailer** — required on a code repo (anchors the `spec-link` + `commit-message` gates). Given
@@ -23,12 +23,18 @@ markdown-only exactly as before.
23
23
  No tool below is required. When one is missing, this skill still finishes, using the fallback written
24
24
  beside it.
25
25
 
26
+ Before you fall back because a tool the team uses is not on this machine (not turned off, not removed
27
+ by the team), offer to connect it, once: run `yad toolbox connect <id> --json` and follow the
28
+ connect-tool rule. On a no, or when a step fails, use the fallback.
29
+
26
30
  Tell the person which tools you used and which fallbacks, and why.
27
31
 
28
32
  - **Figma** (`figma`, a connector). This skill connects it, by writing `.sdlc/design.json` as the steps below say. The other skills follow that file, not yad's toolbox answer.
29
33
  - Fallback — markdown-only: yad-ui writes ui-design.md and DESIGN.md only.
30
34
  - **Pencil (pen.dev)** (`pencil`, a connector). This skill connects it, by writing `.sdlc/design.json` as the steps below say. The other skills follow that file, not yad's toolbox answer.
31
35
  - Fallback — markdown-only: yad-ui writes ui-design.md and DESIGN.md only.
36
+ - **OpenPencil** (`openpencil`, a connector). This skill connects it, by writing `.sdlc/design.json` as the steps below say. The other skills follow that file, not yad's toolbox answer.
37
+ - Fallback — markdown-only: yad-ui writes ui-design.md and DESIGN.md only.
32
38
 
33
39
  <!-- end: When a tool is missing -->
34
40
 
@@ -37,10 +43,14 @@ Tell the person which tools you used and which fallbacks, and why.
37
43
  - `{project-root}` resolves from the project working directory (the **Product**).
38
44
  - The integration is **Figma-first but pluggable** (`config.yaml` `design.tools`): a design-tool
39
45
  *adapter*, like the GitHub/GitLab platform adapter. Figma is the primary provider; `pencil`
40
- (the `.pen` web/mobile editor) is a second, write-capable provider; `none` → markdown-only.
41
- - **The design tool is reached through its MCP** (a harness MCP server), NOT a subprocess CLI — the same
42
- shape as Impeccable's slash-commands, not Repomix's `npx`. The skill detects the MCP and degrades when
43
- it is absent; it never installs an MCP server.
46
+ (the `.pen` web/mobile editor) is a second, write-capable provider; `openpencil` (OpenPencil, an
47
+ open-source editor whose CLI writes a design file in the repo with no account and no app open, E164)
48
+ is a third; `none` → markdown-only.
49
+ - **The design tool is reached through its MCP** (a harness MCP server) — the same shape as Impeccable's
50
+ slash-commands, not Repomix's `npx`. **One exception: OpenPencil** is reached through its CLI
51
+ (`openpencil` on PATH) first, and its MCP only while its desktop app is open. The skill detects the MCP
52
+ (or, for OpenPencil, the CLI) and, when it is absent, offers to connect it with `yad toolbox connect`
53
+ (E165) before it degrades; it never installs anything another way.
44
54
  - Registry: `{project-root}/.sdlc/design.json` (project-wide, shared across all epics — NOT per-epic),
45
55
  the sibling of `.sdlc/repos.json` and `.sdlc/product.json`.
46
56
  - Per-epic screen→frame links are written later by `yad-ui` (`epics/EP-<slug>/.sdlc/design-links.json`),
@@ -50,7 +60,7 @@ Tell the person which tools you used and which fallbacks, and why.
50
60
  ## Inputs
51
61
 
52
62
  - `action` — `connect` (default) | `refresh` | `list` | `disconnect`.
53
- - `tool` — `figma` | `pencil` | another adapter id (`config.yaml` `design.tools`). `none` records a
63
+ - `tool` — `figma` | `pencil` | `openpencil` | another adapter id (`config.yaml` `design.tools`). `none` records a
54
64
  deliberate markdown-only project.
55
65
  - `project_url` — the design tool's team/project/file reference (e.g. a Figma project or file URL).
56
66
  Optional — a connection with no file yet is valid; `yad-ui` can create one on first generate.
@@ -65,18 +75,37 @@ Determine which tool is being connected from `tool` (default `figma`); reject a
65
75
 
66
76
  - **figma** → a Figma MCP server (Dev Mode MCP for read/link; html.to.design for HTML→Figma *generate*).
67
77
  - **pencil** → the `pencil` MCP (`batch_design` writes `.pen` web/mobile screens — generate-capable).
78
+ - **openpencil** → its **CLI** first (`openpencil`, found on PATH): `openpencil eval <file> --code … --write`
79
+ runs Figma Plugin API code on the design file and saves it, with no app open — generate-capable. Its MCP
80
+ server (`open-pencil`, `openpencil-mcp`) is only a bridge to the running desktop app, so it is used only
81
+ when the app is open with the file; it reads only files inside `OPENPENCIL_MCP_ROOT` (the folder it
82
+ starts in by default; the home folder on Windows). Each epic keeps its design file in its own folder,
83
+ `epics/EP-<slug>/design/` (for example `epics/EP-<slug>/design/screens.fig`), so `project_url` may stay
84
+ empty. No account: `auth` stays `"user"` and there is nothing to sign in to. Record `provider`
85
+ `openpencil-cli` when the CLI is found, `openpencil-mcp` when only the MCP is.
68
86
  - another adapter → its named MCP.
69
87
 
70
88
  Record `provider` (the concrete MCP) and whether it is available. For Figma, say which server it is,
71
89
  because a UI task checks it before it starts (#358): `figma-desktop` (the Dev Mode MCP server inside the
72
90
  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
91
+ `html-to-design` (writes screens only, cannot read a frame). For Pencil, `pencil-mcp`. For OpenPencil, `openpencil-cli` (or `openpencil-mcp`, above). The older value
74
92
  `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
75
93
  **stores no tokens**; `project_url`/`files` are plain references, never credentials.
76
94
 
77
- **Graceful degradation:** if no design-tool MCP is available, record `source: "unavailable"` and report
95
+ **Offer to connect it first (E165):** when the tool is not found, run `yad toolbox connect <tool> --json`
96
+ and follow the connect-tool rule: show its `ask` word for word, ask once, and on a yes run only its `agent`
97
+ steps, hand over its `person` steps, then run the `verify` command it gives (`yad toolbox connect <tool> --verify --json`,
98
+ with `--replace` only when its question said which tool it replaces). Never install
99
+ it any other way. When `--verify` passes, detect again — you can reach the tool when you find
100
+ its MCP server in your session (in Claude Code, `/mcp`), or for OpenPencil its CLI on PATH. **If you can**, go on to Step 2 and record what you found. **If you cannot**, the server is
101
+ most likely just added: a new MCP server is loaded when the agent starts. Then do **not** write the file:
102
+ skip the degrade below and Step 2, and in Step 3 tell the person to restart the agent and run this skill
103
+ again with `action: refresh` and the same `tool`. On a no, or when a step fails, degrade:
104
+
105
+ **Graceful degradation** (never right after a `--verify` that passed — see above)**:** if no design-tool MCP is available (for OpenPencil: neither its CLI on PATH nor
106
+ its MCP), record `source: "unavailable"` and report
78
107
  that `yad-ui` will run **markdown-only** until an MCP is connected (no error — the design tool is purely
79
- additive, exactly like Impeccable being absent). Do **not** install an MCP server as part of this step.
108
+ additive, exactly like Impeccable being absent).
80
109
 
81
110
  ### Step 2 — Record the connection in the registry
82
111
  Upsert into `{project-root}/.sdlc/design.json` (create the file + parent `.sdlc/` if absent):
@@ -102,11 +131,14 @@ Upsert into `{project-root}/.sdlc/design.json` (create the file + parent `.sdlc/
102
131
  ### Step 3 — Report (never auto-advance)
103
132
  Report the connected `tool`, its `provider`, whether the MCP is available (or that `yad-ui` will degrade
104
133
  to markdown-only), the `project_url`, and that **`yad-ui` will now generate/link the design here**.
105
- Nothing auto-advances; this is setup.
134
+ Nothing auto-advances; this is setup. **Right after a `--verify` that passed but could not reach the
135
+ tool yet:** report only that it is installed and recorded as the team's tool, that its server loads when the
136
+ agent starts, and that the person restarts the agent and runs this skill again with `action: refresh` and the same `tool` —
137
+ not what `yad-ui` will do, which that refresh decides.
106
138
 
107
139
  ## Other actions
108
140
 
109
- - **`refresh`** — re-detect the MCP and update `lastSyncedAt` (after the user authenticates a session or
141
+ - **`refresh`** — re-detect the MCP (for OpenPencil, the CLI first) and update `lastSyncedAt` (after the user authenticates a session or
110
142
  changes tools). Same machinery as `connect`. Re-detection may flip `source` between an MCP id and
111
143
  `unavailable` — report the change.
112
144
  - **`list`** — print the current connection: `tool`, `provider`, `project_url`, the file mapping, and a
@@ -8,18 +8,20 @@ analogue of `yad-connect-repos`'s code-context.
8
8
  ## Provider detection
9
9
 
10
10
  `connect`/`refresh` records `provider` (the concrete MCP) and `source` (the MCP id, or `unavailable`).
11
- Detection is best-effort against the user's own authenticated MCP session:
11
+ Detection is best-effort against the user's own authenticated MCP session (for OpenPencil, its CLI on
12
+ PATH first):
12
13
 
13
14
  | `tool` | MCP / provider | Capability |
14
15
  |--------|----------------|------------|
15
16
  | `figma` | a Figma Dev Mode MCP | **read/link** — reference a file, read frames back into `ui-design.md` |
16
17
  | `figma` | html.to.design MCP (`import-html`) | **generate** — render HTML/CSS screens into a Figma file |
17
18
  | `pencil` | the `pencil` MCP (`batch_design`) | **generate** — author `.pen` web/mobile screens directly |
19
+ | `openpencil` | its CLI (`openpencil eval … --write`), or its MCP while the desktop app is open | **generate** — create frames in the epic's design file in the repo, then save it |
18
20
  | other | the adapter's named MCP | per that adapter |
19
21
 
20
22
  **Honest capability note:** not every design-tool MCP can *write*. A read-only Figma Dev Mode MCP
21
23
  supports **link + read-back** only; *generate* needs a write-capable provider (html.to.design for Figma,
22
- or `pencil`). `yad-ui` picks the direction the connected provider actually supports and records which one
24
+ `pencil` or `openpencil`). `yad-ui` picks the direction the connected provider actually supports and records which one
23
25
  it used (`direction: generated | linked`). It never claims to have generated screens a read-only MCP
24
26
  cannot produce.
25
27
 
@@ -32,6 +34,19 @@ tool, covering the screens/states `ui-design.md` enumerates and the user flows t
32
34
  then imports it into the Figma file via the MCP's `import-html`, one frame per screen.
33
35
  - **pencil** — the lens calls `batch_design` to author the screens as `.pen` frames directly (mobile
34
36
  and/or web per the epic).
37
+ - **openpencil** — the lens writes the screens into the epic's design file, `epics/EP-<slug>/design/<name>.fig`,
38
+ one frame per screen. `eval` cannot create a file: the first time, make it with
39
+ `openpencil import <seed.html> -o epics/EP-<slug>/design/<name>.fig` (a small HTML page, such as the first
40
+ screen), then add each frame with `openpencil eval <file> --stdin --write` (Figma
41
+ Plugin API code, run on the file with no app open). With the desktop app open on the file, the
42
+ `open-pencil` MCP may be used instead. **Give each frame yad's own ID:** OpenPencil numbers nodes in the
43
+ order it loads them, so its own node IDs change when the file is reopened after a frame is deleted or
44
+ added — and an old ID can then name another frame. Store a plain, unique ID on each frame with
45
+ `frame.setSharedPluginData('yad', 'nodeId', '<id>')` (for example `checkout-mobile`), and record that as
46
+ the screen's `nodeId`. Every read finds the frame by it:
47
+ `figma.root.findAll((n) => n.getSharedPluginData('yad', 'nodeId') === '<id>')`. `yad fold` commits the
48
+ `design/` folder with the UI review, and the review covers it: a change to the design file after
49
+ approval needs a fresh review.
35
50
 
36
51
  Reuse what already exists: load the connected code repos' code-maps (`yad-ui` Step 2b) and any
37
52
  Impeccable `DESIGN.md` tokens so generated screens match built components, not invented ones.
@@ -58,8 +73,10 @@ purely additive.
58
73
 
59
74
  ## Reachable before Build (#358)
60
75
 
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
76
+ A design tool read through its running desktop app — Pencil, Figma's `figma-desktop` server, or
77
+ OpenPencil's MCP server — cannot be read while the app is closed or the design file is not open; a
78
+ hosted server needs a sign-in; and a CLI that works on the file (OpenPencil's) needs the file and the
79
+ program. So before a UI task, `yad-spec` and
63
80
  `yad-implement` check it first, and stop early when it fails. yad itself cannot call an MCP server (it
64
81
  belongs to the agent's session), so `yad story frames <story> --json` returns a `preflight` block that says
65
82
  how to check and what to tell the person; the text for each tool is the toolbox entry's `reach` field.
@@ -71,17 +88,30 @@ how to check and what to tell the person; the text for each tool is the toolbox
71
88
  | `figma`, provider `figma` (hosted) | `get_metadata` on one recorded frame | sign in to Figma in your agent; no app is needed |
72
89
  | `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
90
  | `figma`, provider `html-to-design` | nothing: it writes screens and cannot read a frame | not checked; build from the frame links |
91
+ | `openpencil`, provider `openpencil-cli` | the design file is in the Product checkout, `openpencil --version` runs, and `openpencil eval` on the file finds the frame whose shared plugin data `yad`/`nodeId` is the recorded ID. No app, no sign-in | pull the Product so the file is there with the frame in it, and make sure `openpencil` runs |
92
+ | `openpencil`, provider `openpencil-mcp` | the MCP's `eval` tool finds the frame by its stored `yad`/`nodeId` | open the OpenPencil desktop app with the file loaded (inside `OPENPENCIL_MCP_ROOT`) |
93
+ | `openpencil`, no provider or another name | the CLI check above, and the MCP check when that does not find the frame | either of the two above |
74
94
 
75
95
  Also not checked (build from the frame links): no `design.json`, tool `none`, source `unavailable`; no
76
96
  `design-links.json`, one that cannot be read, or one recorded for another tool (re-run the UI step); and a
77
97
  story whose recorded frame IDs are all missing from `design-links.json` — the bad IDs are the problem then.
78
98
 
99
+ When the check fails because the tool is not on this machine at all (no such MCP server in the agent's
100
+ session), the skill first offers `preflight.connect` — `yad toolbox connect <tool> --json`, under the
101
+ connect-tool rule — and checks again once it is found (E165). A closed app, the wrong file or a sign-in
102
+ is never offered: those are the person's. Nor is Figma's `figma-desktop` provider: it is the desktop app's
103
+ own server, and Figma's connect step sets up the hosted one, so the person opens the app instead
104
+ (OpenPencil's MCP server is offered: its connect step adds it). An
105
+ older `design.json` that names no provider (or `figma-mcp`) is still offered the hosted one: the question
106
+ names what it installs, so a person who uses the desktop app says no. A server just added is seen only
107
+ after the agent restarts (check `/mcp`); until then the skill says so and stops.
108
+
79
109
  A failed check stops the step. The person may choose to go on from the frame links only; that choice is
80
110
  recorded (in `spec.md`'s Clarifications, or the commit's Decisions paragraph).
81
111
 
82
112
  ## Staleness / refresh
83
113
 
84
114
  A re-generated or designer-edited file is like a moved code repo: `yad-ui` **flags** a divergence and
85
- lets a human decide (re-run the step, or `yad-connect-design` action: refresh). It never silently
115
+ lets a human decide (re-run the step, or `yad-connect-design` with `action: refresh` and the same `tool`). It never silently
86
116
  overwrites a designer's frames — refreshing the design is a human decision, the same discipline as
87
117
  `code_context.refresh: human`.
@@ -14,8 +14,8 @@ root, not under any `epics/EP-<slug>/.sdlc/`.
14
14
 
15
15
  ```json
16
16
  {
17
- "tool": "figma", // figma | pencil | <adapter id> | none (markdown-only)
18
- "provider": "figma-desktop", // the concrete MCP: figma-desktop | figma | html-to-design | pencil-mcp | null (figma-mcp: older, either Figma server)
17
+ "tool": "figma", // figma | pencil | openpencil | <adapter id> | none (markdown-only)
18
+ "provider": "figma-desktop", // the concrete MCP: figma-desktop | figma | html-to-design | pencil-mcp | openpencil-cli | openpencil-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
@@ -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-desktop` / `figma` / `pencil-mcp` / …) means
39
+ - **`source`** is the authority for availability: an MCP id (`figma-desktop` / `figma` / `pencil-mcp` / `openpencil-cli` / `openpencil-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`
@@ -24,6 +24,10 @@ explains the concept. The learning layer is **purely opt-in and never blocks a g
24
24
  No tool below is required. When one is missing, this skill still finishes, using the fallback written
25
25
  beside it.
26
26
 
27
+ Before you fall back because a tool the team uses is not on this machine (not turned off, not removed
28
+ by the team), offer to connect it, once: run `yad toolbox connect <id> --json` and follow the
29
+ connect-tool rule. On a no, or when a step fails, use the fallback.
30
+
27
31
  Tell the person which tools you used and which fallbacks, and why.
28
32
 
29
33
  - **DeepTutor** (`deeptutor`, a connector). This skill connects it, by writing `.sdlc/learning.json` as the steps below say. The other skills follow that file, not yad's toolbox answer.
@@ -39,7 +43,8 @@ Tell the person which tools you used and which fallbacks, and why.
39
43
  harness model).
40
44
  - **DeepTutor is reached as a CLI SUBPROCESS** (`deeptutor …`), the same shape as Repomix's `npx` — NOT
41
45
  an MCP like the design/testing tools (DeepTutor ships no MCP server). The skill detects the **binary on
42
- PATH** and degrades when it is absent; it never installs DeepTutor.
46
+ PATH** and, when it is absent, offers to connect it with `yad toolbox connect deeptutor` (E165) before it
47
+ degrades; it never installs DeepTutor another way.
43
48
  - Registry: `{project-root}/.sdlc/learning.json` (project-wide, shared across all epics — NOT per-epic),
44
49
  the sibling of `.sdlc/repos.json`, `.sdlc/product.json`, `.sdlc/design.json`, and `.sdlc/testing.json`.
45
50
  - Per-epic, per-member learning records + rendered tutorials are written later by `yad-learn`
@@ -70,10 +75,15 @@ way `registerRepo`/`registerDesign` fall back). Then **detect the tool's CLI on
70
75
  **Auth is the local user's own** — DeepTutor's own config (`deeptutor init`, `data/user/settings/`) and
71
76
  the user's LLM provider keys. The skill **stores no tokens**; `kb`/`kb_sources` are plain references.
72
77
 
78
+ **Offer to connect it first (E165):** when DeepTutor is not found, run `yad toolbox connect deeptutor --json`
79
+ and follow the connect-tool rule: show its `ask` word for word, ask once, hand over its `person` steps (its
80
+ install and `deeptutor init` are the person's), then run the `verify` command it gives (`yad toolbox connect deeptutor --verify --json`).
81
+ On a no, or when a step fails, degrade:
82
+
73
83
  **Graceful degradation:** if the `deeptutor` binary is not on PATH, record `source: "harness-native"`
74
84
  and report that `yad-learn` will still tutor **using the harness model reading the project artifacts**
75
85
  (no error — the learning layer is additive and always works; DeepTutor only adds knowledge-base
76
- grounding, quizzes, and deep research). Do **not** install DeepTutor as part of this step.
86
+ grounding, quizzes, and deep research).
77
87
 
78
88
  ### Step 2 — Ground it in the project (optional, when DeepTutor is available)
79
89
  When `ground: true` and DeepTutor is available, build or refresh a project **knowledge base** so tutoring
@@ -34,6 +34,10 @@ there are found.
34
34
  - **When yad cannot answer** (yad is not installed here, or the command fails), use the check in the
35
35
  steps below.
36
36
 
37
+ Before you fall back because a tool the team uses is not on this machine (not turned off, not removed
38
+ by the team), offer to connect it, once: run `yad toolbox connect <id> --json` and follow the
39
+ connect-tool rule. On a no, or when a step fails, use the fallback.
40
+
37
41
  Tell the person which tools you used and which fallbacks, and why.
38
42
 
39
43
  - **Repomix** (`repomix`). 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 repomix`) — use the fallback.
@@ -192,6 +196,20 @@ locally only.
192
196
  Report the connected repo, its `platform`, the pack + code-map paths, the secret-scan result, and that
193
197
  the Shape phases will now load this repo's code-map. Nothing auto-advances; this is setup.
194
198
 
199
+ Optionally, offer to build the **project brain** (E176) — one knowledge graph of the code and the work
200
+ items, on this machine only: **`yad brain build`**. It runs Graphify in each connected repo with its LLM
201
+ pass off (code is parsed locally; nothing leaves the machine), writes `.sdlc/brain/`, which ignores
202
+ itself, and commits nothing. Without Graphify it builds the work items alone and says how to install it
203
+ (`yad toolbox connect graphify`). Then `yad brain query <text>` answers "which story touches this file?",
204
+ and `yad brain view --open` draws the graph in the person's browser (E177): a local page only this machine
205
+ can reach, until Ctrl-C. It keeps running, so start it for the person to open rather than waiting on it; or
206
+ use `yad brain view --html --open`, which writes one offline file and returns.
207
+ To watch an agent work through the brain live (E178), the Product sets `"activity": true` and runs
208
+ `yad check --fix`; then `yad brain view --live --open` shows each file the agent reads, searches or edits
209
+ against the task's declared files. It records what the agent did, never why.
210
+ Once built, the planning and building skills ask it themselves (E179): `yad brain file <repo>/<path>`
211
+ (who declares a file, what uses it) and `yad brain story <id>` (a story's tasks and their files).
212
+
195
213
  ## Other actions
196
214
 
197
215
  - **`refresh`** — re-run Steps 2–4 (including Step 3b) for an already-connected repo (after its code moves). A new directory gets an `unset` line and a guess; a `confirmed` line is only ever suggested against. Updates
@@ -23,6 +23,10 @@ connected, `yad-test-cases` runs artifacts-only exactly as before.
23
23
  No tool below is required. When one is missing, this skill still finishes, using the fallback written
24
24
  beside it.
25
25
 
26
+ Before you fall back because a tool the team uses is not on this machine (not turned off, not removed
27
+ by the team), offer to connect it, once: run `yad toolbox connect <id> --json` and follow the
28
+ connect-tool rule. On a no, or when a step fails, use the fallback.
29
+
26
30
  Tell the person which tools you used and which fallbacks, and why.
27
31
 
28
32
  - **Playwright MCP** (`playwright`, a connector). This skill connects it, by writing `.sdlc/testing.json` as the steps below say. The other skills follow that file, not yad's toolbox answer.
@@ -44,7 +48,8 @@ Tell the person which tools you used and which fallbacks, and why.
44
48
  primary provider; `cypress`, `pytest` and `maestro` are second providers; `none` → artifacts-only.
45
49
  - **The testing tool is reached through its MCP** (a harness MCP server), NOT a subprocess CLI — the
46
50
  same shape as the design tool's MCP, not Repomix's `npx`. The skill detects the MCP and degrades when
47
- it is absent; it never installs an MCP server.
51
+ it is absent, offering first to connect it with `yad toolbox connect` (E165); it never installs anything
52
+ another way.
48
53
  - Registry: `{project-root}/.sdlc/testing.json` (project-wide, shared across all epics — NOT per-epic),
49
54
  the sibling of `.sdlc/repos.json`, `.sdlc/product.json`, and `.sdlc/design.json`.
50
55
  - Per-epic test→suite links are written later by `yad-test-cases`
@@ -81,10 +86,19 @@ Record `provider` (the concrete MCP, e.g. `playwright-mcp` | `cypress-mcp` | `py
81
86
  it is available. **Auth is the local user's own** — the user's authenticated MCP session. The skill
82
87
  **stores no tokens**; `project_url`/`suites` are plain references, never credentials.
83
88
 
84
- **Graceful degradation:** if no testing-tool MCP is available, record `source: "unavailable"` and report
89
+ **Offer to connect it first (E165):** when the tool is not found, run `yad toolbox connect <tool> --json`
90
+ and follow the connect-tool rule: show its `ask` word for word, ask once, and on a yes run only its `agent`
91
+ steps, hand over its `person` steps, then run the `verify` command it gives (`yad toolbox connect <tool> --verify --json`,
92
+ with `--replace` only when its question said which tool it replaces). Never install
93
+ it any other way. When `--verify` passes, detect again — you can reach the tool when you find
94
+ its MCP server in your session (in Claude Code, `/mcp`). **If you can**, go on to Step 2 and record what you found. **If you cannot**, the server is
95
+ most likely just added: a new MCP server is loaded when the agent starts. Then do **not** write the file:
96
+ skip the degrade below and Step 2, and in Step 3 tell the person to restart the agent and run this skill
97
+ again with `action: refresh` and the same `tool`. On a no, or when a step fails, degrade:
98
+
99
+ **Graceful degradation** (never right after a `--verify` that passed — see above)**:** if no testing-tool MCP is available, record `source: "unavailable"` and report
85
100
  that `yad-test-cases` will run **artifacts-only** until an MCP is connected (no error — the testing tool
86
- is purely additive, exactly like the design tool being absent). Do **not** install an MCP server as part
87
- of this step.
101
+ is purely additive, exactly like the design tool being absent).
88
102
 
89
103
  ### Step 2 — Record the connection in the registry
90
104
  Upsert into `{project-root}/.sdlc/testing.json` (create the file + parent `.sdlc/` if absent):
@@ -110,7 +124,10 @@ Upsert into `{project-root}/.sdlc/testing.json` (create the file + parent `.sdlc
110
124
  ### Step 3 — Report (never auto-advance)
111
125
  Report the connected `tool`, its `provider`, whether the MCP is available (or that `yad-test-cases` will
112
126
  degrade to artifacts-only), the `project_url`, and that **`yad-test-cases` will now generate/link the
113
- automation tests here**. Nothing auto-advances; this is setup.
127
+ automation tests here**. Nothing auto-advances; this is setup. **Right after a `--verify` that passed but could not reach the
128
+ tool yet:** report only that it is installed and recorded as the team's tool, that its server loads when the
129
+ agent starts, and that the person restarts the agent and runs this skill again with `action: refresh` and the same `tool` —
130
+ not what `yad-test-cases` will do, which that refresh decides.
114
131
 
115
132
  ## Other actions
116
133
 
@@ -67,6 +67,6 @@ purely additive.
67
67
  ## Staleness / refresh
68
68
 
69
69
  A re-generated or hand-edited suite is like a moved code repo: `yad-test-cases` **flags** a divergence
70
- and lets a human decide (re-run the step, or `yad-connect-testing` action: refresh). It never silently
70
+ and lets a human decide (re-run the step, or `yad-connect-testing` with `action: refresh` and the same `tool`). It never silently
71
71
  overwrites a hand-written suite — refreshing the automation is a human decision, the same discipline as
72
72
  `code_context.refresh: human`.
@@ -162,6 +162,17 @@ each `yad-epic` reads (its "Step 2c"). When the Product has a platform, the gate
162
162
  Product (via `yad-product-bridge`) and `yad-review-gate action: sync` pulls platform approvals and comments
163
163
  into the ledger; otherwise the review is recorded locally.
164
164
 
165
+ **Once the review has passed and the Product has a platform, offer to publish the roadmap** (E174). Ask the
166
+ person, then run `yad foundation publish --dry-run` to show what it would create, then `yad foundation publish`.
167
+ It opens one issue or work item per roadmap feature in the Product repo: type feature, a priority by phase
168
+ (the first phase, the MVP, is P1; the next P2; later ones P3), the label `epic: EP-x`, and the phase as its
169
+ milestone. The `Later / parked` phase is left out. If the Foundation changed after its review, the command refuses:
170
+ the changed roadmap needs a new review first. Report the links, and remind the person to commit
171
+ `foundation/.sdlc/roadmap-items.json` on a branch of its own, not a `review/…` one, and open a pull request
172
+ (`chore: record tracker links`). A review branch would advance a step. On a verified Product, the Product
173
+ checks let a pull request of that file, the epics' `.sdlc/issue-links.json` files and step owner files alone
174
+ through from any branch (#512), once a `yad update` carrying that rule has merged on the default branch.
175
+
165
176
  ## Reference
166
177
  - Foundation section templates: `references/foundation-schema.md`.
167
178
  - The older spelling of the Product level (`EP-discovery`, its six files, and how it converts):