yadflow 4.10.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 (106) hide show
  1. package/CHANGELOG.md +97 -0
  2. package/README.md +12 -3
  3. package/bin/commands.mjs +5 -1
  4. package/bin/yad.mjs +109 -15
  5. package/cli/agent-guard-worker.mjs +13 -0
  6. package/cli/agent-guard.mjs +1053 -57
  7. package/cli/agent-rules.mjs +34 -3
  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 +3 -3
  28. package/cli/doctor.mjs +80 -13
  29. package/cli/epic-state.mjs +93 -1
  30. package/cli/epic.mjs +15 -3
  31. package/cli/errors.mjs +2 -1
  32. package/cli/find-product.mjs +69 -15
  33. package/cli/foundation-publish.mjs +256 -0
  34. package/cli/gate.mjs +29 -3
  35. package/cli/git-read.mjs +38 -0
  36. package/cli/guard-stream.mjs +409 -0
  37. package/cli/hook.mjs +59 -9
  38. package/cli/issues-act.mjs +57 -13
  39. package/cli/issues-write.mjs +19 -6
  40. package/cli/issues.mjs +62 -23
  41. package/cli/lib.mjs +37 -2
  42. package/cli/local-page.mjs +138 -0
  43. package/cli/machine.mjs +1 -1
  44. package/cli/manifest.mjs +50 -0
  45. package/cli/map/view/app.js +712 -0
  46. package/cli/map/view/index.html +50 -0
  47. package/cli/map/view/style.css +142 -0
  48. package/cli/map-view.mjs +186 -0
  49. package/cli/map.mjs +637 -0
  50. package/cli/members.mjs +9 -15
  51. package/cli/next.mjs +1 -1
  52. package/cli/openpr.mjs +2 -2
  53. package/cli/plan.mjs +125 -0
  54. package/cli/platform.mjs +5 -5
  55. package/cli/product-index.mjs +1 -1
  56. package/cli/protection.mjs +32 -0
  57. package/cli/reconcile.mjs +8 -2
  58. package/cli/report.mjs +9 -3
  59. package/cli/reports-dir.mjs +391 -0
  60. package/cli/reports.mjs +65 -0
  61. package/cli/run-checks.mjs +5 -2
  62. package/cli/scan.mjs +1 -1
  63. package/cli/setup.mjs +30 -5
  64. package/cli/standup.mjs +87 -71
  65. package/cli/status.mjs +6 -5
  66. package/cli/test-agents-file.mjs +614 -8
  67. package/cli/test-brain-activity.mjs +753 -0
  68. package/cli/test-brain-view.mjs +381 -0
  69. package/cli/test-brain.mjs +795 -0
  70. package/cli/test-guide.mjs +211 -0
  71. package/cli/test-machine.mjs +59 -0
  72. package/cli/test-map.mjs +615 -0
  73. package/cli/test-reports.mjs +382 -0
  74. package/cli/test-run-checks.mjs +4 -0
  75. package/cli/test-worktree.mjs +24 -3
  76. package/cli/toolbox-connect.mjs +21 -6
  77. package/cli/toolbox.mjs +59 -4
  78. package/cli/update-commit.mjs +101 -9
  79. package/cli/usage.mjs +8 -4
  80. package/package.json +8 -4
  81. package/skills/yad-architecture/SKILL.md +22 -4
  82. package/skills/yad-change/SKILL.md +3 -1
  83. package/skills/yad-change/references/triage.md +2 -0
  84. package/skills/yad-checks/SKILL.md +2 -0
  85. package/skills/yad-checks/references/check-gates.md +8 -5
  86. package/skills/yad-checks/templates/checks/build-test-lint.sh +7 -0
  87. package/skills/yad-checks/templates/checks/install-deps.sh +6 -0
  88. package/skills/yad-checks/templates/checks/package-manager.sh +42 -0
  89. package/skills/yad-checks/templates/github/yad-checks.yml +3 -2
  90. package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml +3 -2
  91. package/skills/yad-checks/templates/hooks/yad-activity.mjs +238 -0
  92. package/skills/yad-connect-repos/SKILL.md +14 -0
  93. package/skills/yad-discovery/SKILL.md +11 -0
  94. package/skills/yad-discovery/references/foundation-schema.md +11 -0
  95. package/skills/yad-docs/templates/app/package-lock.json +18 -10
  96. package/skills/yad-docs/templates/app/package.json +6 -1
  97. package/skills/yad-epic/SKILL.md +3 -0
  98. package/skills/yad-epic/references/state-schema.md +35 -1
  99. package/skills/yad-guide/SKILL.md +4 -4
  100. package/skills/yad-implement/SKILL.md +76 -15
  101. package/skills/yad-issues/SKILL.md +2 -1
  102. package/skills/yad-pr-template/templates/checks/pr-template.sh +8 -4
  103. package/skills/yad-pr-template/templates/checks/pr-title.sh +8 -4
  104. package/skills/yad-spec/SKILL.md +19 -0
  105. package/skills/yad-stories/SKILL.md +22 -4
  106. package/skills/yad-stories/references/story-schema.md +1 -1
@@ -0,0 +1,382 @@
1
+ // E180 — the local reports folder: where it is, how a file is named, the catalog, and `yad reports`.
2
+ import { test } from 'node:test';
3
+ import assert from 'node:assert/strict';
4
+ import { spawnSync } from 'node:child_process';
5
+ import fs from 'node:fs';
6
+ import os from 'node:os';
7
+ import path from 'node:path';
8
+ import { fileURLToPath } from 'node:url';
9
+
10
+ if (process.env.NODE_TEST_CONTEXT) {
11
+ const write = process.stdout.write;
12
+ for (const k of ['log', 'info']) {
13
+ const orig = console[k];
14
+ console[k] = (...a) => (process.stdout.write === write ? console.error(...a) : orig(...a));
15
+ }
16
+ }
17
+ process.env.YAD_NO_UPDATE_NOTIFIER = '1';
18
+
19
+ const { withCatalogLock, reportsDir, mainCheckout, reportName, slug, stamp, saveReport, readCatalog, listReports, pruneReports, freshness, renderIndex, writeOrSave, REPORTS_ENV, CATALOG_FILE } = await import('./reports-dir.mjs');
20
+ const { runReports } = await import('./reports.mjs');
21
+ const { classify } = await import('./agent-rules.mjs');
22
+ const { endJSON } = await import('./lib.mjs');
23
+
24
+ const HERE = path.dirname(fileURLToPath(import.meta.url));
25
+ const YAD = path.join(HERE, '..', 'bin', 'yad.mjs');
26
+
27
+ const tmp = () => fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'yad-reports-')));
28
+ const put = (file, data) => { fs.mkdirSync(path.dirname(file), { recursive: true }); fs.writeFileSync(file, typeof data === 'string' ? data : JSON.stringify(data)); };
29
+ const done = (...dirs) => dirs.forEach((d) => fs.rmSync(d, { recursive: true, force: true }));
30
+ const git = (cwd, ...a) => spawnSync('git', ['-c', 'user.email=t@example.com', '-c', 'user.name=t', '-c', 'commit.gpgsign=false', ...a], { cwd, encoding: 'utf8' });
31
+ const noEnv = {};
32
+ const AT = new Date(2026, 10, 14, 9, 5); // local time, 2026-11-14 09:05
33
+
34
+ // A Product checkout with one commit, inside a fresh workspace folder.
35
+ function product() {
36
+ const ws = tmp();
37
+ const root = path.join(ws, 'product');
38
+ put(path.join(root, '.sdlc', 'product.json'), { name: 'demo' });
39
+ put(path.join(root, 'epics', 'EP-x', 'epic.md'), '# x\n');
40
+ git(root, 'init', '-q', '-b', 'main');
41
+ git(root, 'add', '-A');
42
+ git(root, 'commit', '-q', '-m', 'start');
43
+ return { ws, root };
44
+ }
45
+
46
+ async function captured(fn) {
47
+ const out = []; const orig = console.log;
48
+ console.log = (s) => out.push(String(s));
49
+ try { await fn(); } finally { console.log = orig; endJSON(); }
50
+ return JSON.parse(out.join('\n'));
51
+ }
52
+
53
+ test('the folder sits beside the main checkout — also from a worktree — and the env var wins', () => {
54
+ const { ws, root } = product();
55
+ try {
56
+ assert.equal(reportsDir(root, { env: noEnv }).dir, path.join(ws, 'product--reports'));
57
+ const wt = path.join(ws, 'product--EP-x');
58
+ assert.equal(git(root, 'worktree', 'add', '-q', '--detach', wt).status, 0);
59
+ assert.equal(mainCheckout(wt), root, 'a worktree finds its main checkout');
60
+ assert.equal(reportsDir(wt, { env: noEnv }).dir, path.join(ws, 'product--reports'), 'and saves into the same folder');
61
+ const mine = path.join(ws, 'elsewhere');
62
+ assert.deepEqual(reportsDir(root, { env: { [REPORTS_ENV]: mine } }), { dir: mine, via: 'env' });
63
+ assert.equal(reportsDir(root, { env: { [REPORTS_ENV]: ' ' } }).via, 'beside', 'a blank value is not a choice');
64
+ // A Product folder inside another repo (not its top) keeps its reports beside itself.
65
+ const inner = path.join(root, 'nested');
66
+ fs.mkdirSync(inner);
67
+ assert.equal(mainCheckout(inner), inner);
68
+ // Not a repo at all: beside the folder.
69
+ const plain = path.join(ws, 'plain');
70
+ fs.mkdirSync(plain);
71
+ assert.equal(reportsDir(plain, { env: noEnv }).dir, path.join(ws, 'plain--reports'));
72
+ } finally { done(ws); }
73
+ });
74
+
75
+ test('a name says the time, kind, scope and state, in characters every system accepts', () => {
76
+ assert.equal(stamp(AT), '2026-11-14-0905');
77
+ assert.equal(reportName({ kind: 'standup', scope: 'Ahmed Zaki', state: '3 waiting', at: AT, ext: 'md' }), '2026-11-14-0905--standup--ahmed-zaki--3-waiting.md');
78
+ assert.equal(reportName({ kind: 'usage', scope: 'team', state: '2026-10-01 → 2026-11-14', at: AT, ext: 'html' }), '2026-11-14-0905--usage--team--2026-10-01-2026-11-14.html');
79
+ assert.equal(slug('Ünïcödé: a/b\\c*?"<>|'), 'unicode-a-b-c');
80
+ assert.equal(slug(''), 'none');
81
+ assert.equal(slug('-'.repeat(9)), 'none');
82
+ assert.ok(slug('x'.repeat(200)).length <= 40);
83
+ assert.ok(!slug('ab '.repeat(30), 10).endsWith('-'), 'a cut never ends on a dash');
84
+ const long = reportName({ kind: 'progress-map', scope: 'y'.repeat(300), state: 'z'.repeat(300), at: AT, ext: 'html' });
85
+ assert.ok(long.length <= 120, long.length);
86
+ assert.throws(() => reportName({ kind: '../x', scope: 'a', state: 'b', at: AT, ext: 'md' }), /unknown report kind/);
87
+ assert.throws(() => reportName({ kind: 'usage', scope: 'a', state: 'b', at: AT, ext: 'h/tml' }), /bad report extension/);
88
+ });
89
+
90
+ test('saving writes the file, the ignore file, the catalog and its page; a clash gets -2', () => {
91
+ const { ws, root } = product();
92
+ try {
93
+ const a = saveReport(root, { kind: 'standup', scope: 'team', state: '2 waiting', ext: 'md', content: '# one\n', command: 'standup', at: AT, env: noEnv });
94
+ const dir = path.join(ws, 'product--reports');
95
+ assert.equal(a.file, path.join(dir, 'standup', '2026-11-14-0905--standup--team--2-waiting.md'));
96
+ assert.equal(fs.readFileSync(a.file, 'utf8'), '# one\n');
97
+ assert.match(fs.readFileSync(path.join(dir, '.gitignore'), 'utf8'), /^\*$/m);
98
+ const b = saveReport(root, { kind: 'standup', scope: 'team', state: '2 waiting', ext: 'md', content: '# two\n', at: AT, env: noEnv });
99
+ assert.equal(path.basename(b.file), '2026-11-14-0905--standup--team--2-waiting-2.md');
100
+ const cat = readCatalog(dir);
101
+ assert.equal(cat.entries.length, 2);
102
+ const sha = git(root, 'rev-parse', 'HEAD').stdout.trim();
103
+ assert.deepEqual(cat.entries[0], { file: 'standup/2026-11-14-0905--standup--team--2-waiting.md', kind: 'standup', scope: 'team', state: '2 waiting', createdAt: AT.toISOString(), productSha: sha, productBranch: 'main', anonymous: false, command: 'standup' });
104
+ const page = fs.readFileSync(path.join(dir, 'index.html'), 'utf8');
105
+ assert.match(page, /href="standup\/2026-11-14-0905--standup--team--2-waiting\.md"/);
106
+ assert.match(page, /default-src 'none'/, 'the catalog page runs no script');
107
+ // Inside a git tree, the folder's own ignore file keeps every report out of it.
108
+ git(ws, 'init', '-q');
109
+ assert.equal(git(ws, 'check-ignore', '-q', path.join('product--reports', 'standup', path.basename(a.file))).status, 0);
110
+ } finally { done(ws); }
111
+ });
112
+
113
+ test('a broken catalog is never overwritten: the report is still saved, and the problem is said', () => {
114
+ const { ws, root } = product();
115
+ try {
116
+ const dir = path.join(ws, 'product--reports');
117
+ put(path.join(dir, CATALOG_FILE), '{ not json');
118
+ const r = saveReport(root, { kind: 'usage', scope: 'team', state: 'all time', ext: 'html', content: '<p>x</p>', at: AT, env: noEnv });
119
+ assert.ok(fs.existsSync(r.file));
120
+ assert.match(r.warnings[0], /cannot be read .* the catalog was not changed/);
121
+ assert.equal(fs.readFileSync(path.join(dir, CATALOG_FILE), 'utf8'), '{ not json');
122
+ put(path.join(dir, CATALOG_FILE), { version: 9, entries: [] });
123
+ assert.match(readCatalog(dir).problem, /version 9/);
124
+ put(path.join(dir, CATALOG_FILE), [1, 2]);
125
+ assert.match(readCatalog(dir).problem, /not a reports catalog/);
126
+ // A file where the folder should be is refused, not written through.
127
+ const other = product();
128
+ put(path.join(other.ws, 'product--reports'), 'a file');
129
+ assert.match(saveReport(other.root, { kind: 'usage', scope: 't', state: 's', ext: 'md', content: 'x', env: noEnv }).problem, /not a plain folder/);
130
+ done(other.ws);
131
+ } finally { done(ws); }
132
+ });
133
+
134
+ test('fresh until the Product\'s epics or .sdlc change; a missing or foreign sha is unknown', () => {
135
+ const { ws, root } = product();
136
+ try {
137
+ saveReport(root, { kind: 'standup', scope: 'team', state: '0 waiting', ext: 'md', content: 'x', at: AT, env: noEnv });
138
+ assert.equal(listReports(root, { env: noEnv }).entries[0].freshness, 'fresh');
139
+ put(path.join(root, 'README.md'), 'not the record\n');
140
+ git(root, 'add', '-A'); git(root, 'commit', '-q', '-m', 'readme');
141
+ assert.equal(listReports(root, { env: noEnv }).entries[0].freshness, 'fresh', 'a change outside the record does not make it stale');
142
+ put(path.join(root, 'epics', 'EP-x', 'epic.md'), '# x moved\n');
143
+ assert.equal(listReports(root, { env: noEnv }).entries[0].freshness, 'fresh', 'an uncommitted change is not the record yet');
144
+ git(root, 'add', '-A'); git(root, 'commit', '-q', '-m', 'move');
145
+ assert.equal(listReports(root, { env: noEnv }).entries[0].freshness, 'stale');
146
+ assert.equal(freshness(root, null), 'unknown');
147
+ assert.equal(freshness(root, 'f'.repeat(40)), 'unknown');
148
+ assert.equal(freshness(root, '--output=x'), 'unknown', 'never passed to git as an option');
149
+ } finally { done(ws); }
150
+ });
151
+
152
+ test('prune is a dry run until --apply, and only ever deletes what the catalog lists inside the folder', () => {
153
+ const { ws, root } = product();
154
+ try {
155
+ const old = saveReport(root, { kind: 'usage', scope: 'team', state: 'old', ext: 'md', content: 'x', at: new Date(2026, 0, 1), env: noEnv });
156
+ const recent = saveReport(root, { kind: 'usage', scope: 'team', state: 'new', ext: 'md', content: 'y', at: AT, env: noEnv });
157
+ const dir = path.join(ws, 'product--reports');
158
+ const outside = path.join(ws, 'keep-me.txt');
159
+ put(outside, 'keep');
160
+ const cat = JSON.parse(fs.readFileSync(path.join(dir, CATALOG_FILE), 'utf8'));
161
+ cat.entries.push({ file: '../keep-me.txt', kind: 'usage', scope: 'x', state: 'x', createdAt: '2000-01-01T00:00:00.000Z' });
162
+ fs.writeFileSync(path.join(dir, CATALOG_FILE), JSON.stringify(cat));
163
+ const now = AT.getTime() + 864e5;
164
+ const dry = pruneReports(root, { days: 30, now, env: noEnv });
165
+ assert.deepEqual(dry.removed.map((e) => [e.file, e.reason]).sort(), [['../keep-me.txt', 'outside'], [path.posix.join('usage', path.basename(old.file)), 'old']].sort());
166
+ assert.ok(fs.existsSync(old.file), 'a dry run deletes nothing');
167
+ const applied = pruneReports(root, { days: 30, now, apply: true, env: noEnv });
168
+ assert.equal(applied.removed.find((e) => e.reason === 'old').file, path.posix.join('usage', path.basename(old.file)), 'review 1: the reason is decided before the delete, so a removed file reads "old"');
169
+ assert.equal(fs.existsSync(old.file), false);
170
+ assert.ok(fs.existsSync(recent.file));
171
+ assert.equal(fs.readFileSync(outside, 'utf8'), 'keep', 'a path that leaves the folder is dropped from the catalog, never deleted');
172
+ assert.equal(readCatalog(dir).entries.length, 1);
173
+ } finally { done(ws); }
174
+ });
175
+
176
+ test('--out still writes exactly the file named, and leaves the catalog alone', () => {
177
+ const { ws, root } = product();
178
+ try {
179
+ const out = path.join(ws, 'sub', 'mine.md');
180
+ const r = writeOrSave(root, { out, kind: 'standup', scope: 'team', state: 's', ext: 'md', content: 'z', env: noEnv });
181
+ assert.equal(r.file, out);
182
+ assert.equal(fs.readFileSync(out, 'utf8'), 'z');
183
+ assert.equal(fs.existsSync(path.join(ws, 'product--reports')), false);
184
+ } finally { done(ws); }
185
+ });
186
+
187
+ test('the catalog page escapes what it shows', () => {
188
+ const page = renderIndex([{ file: 'usage/a"b<c>.md', kind: 'usage', scope: '<script>', state: '"x"', createdAt: AT.toISOString(), productSha: null, anonymous: true }]);
189
+ assert.equal(page.includes('<script>'), false);
190
+ assert.match(page, /&lt;script&gt;/);
191
+ assert.match(page, /anonymous/);
192
+ assert.match(renderIndex([]), /No reports saved yet/);
193
+ });
194
+
195
+ test('yad reports list | open | prune answer in JSON, and refuse what they do not take', async () => {
196
+ const { ws, root } = product();
197
+ try {
198
+ const env = { [REPORTS_ENV]: path.join(ws, 'chosen') };
199
+ saveReport(root, { kind: 'issues', scope: 'all repos', state: '4 items', ext: 'md', content: 'x', at: AT, env });
200
+ const list = await captured(() => runReports(root, { action: 'list', json: true, env }));
201
+ assert.equal(list.command, null);
202
+ assert.equal(list.via, 'env');
203
+ assert.equal(list.entries[0].n, 1);
204
+ assert.equal(list.entries[0].present, true);
205
+ let opened = null;
206
+ const open = await captured(() => runReports(root, { action: 'open', args: ['1'], json: true, env, opener: (f) => { opened = f; return true; } }));
207
+ assert.equal(open.opened, true);
208
+ assert.equal(opened, path.join(ws, 'chosen', list.entries[0].file));
209
+ assert.equal((await captured(() => runReports(root, { action: 'open', args: ['9'], json: true, env }))).ok, false);
210
+ const bad = await captured(() => runReports(root, { action: 'prune', olderThan: 'soon', json: true, env }));
211
+ assert.match(bad.error, /--older-than <days>/);
212
+ const prune = await captured(() => runReports(root, { action: 'prune', olderThan: '0', json: true, env }));
213
+ assert.equal(prune.applied, false);
214
+ // review 2: --missing drops only entries whose file is gone, and deletes no report.
215
+ const kept = path.join(ws, 'chosen', list.entries[0].file);
216
+ saveReport(root, { kind: 'issues', scope: 'all repos', state: 'gone', ext: 'md', content: 'x', at: AT, env });
217
+ const goner = listReports(root, { env }).entries.find((e) => e.state === 'gone');
218
+ fs.rmSync(path.join(ws, 'chosen', goner.file));
219
+ const miss = await captured(() => runReports(root, { action: 'prune', missing: true, apply: true, json: true, env }));
220
+ assert.deepEqual(miss.removed.map((e) => e.reason), ['missing']);
221
+ assert.ok(fs.existsSync(kept), 'the report whose file is there stays');
222
+ assert.equal((await captured(() => runReports(root, { action: 'prune', missing: true, olderThan: '3', json: true, env }))).ok, false, 'not both');
223
+ assert.equal((await captured(() => runReports(root, { action: 'frob', json: true, env }))).ok, false);
224
+ process.exitCode = 0;
225
+ } finally { done(ws); }
226
+ });
227
+
228
+ test('yad reports runs from the CLI, and agents may list but must be asked to delete', () => {
229
+ const { ws, root } = product();
230
+ try {
231
+ const r = spawnSync(process.execPath, [YAD, 'reports', '--json'], { cwd: root, encoding: 'utf8', env: { ...process.env, NO_COLOR: '1', SDLC_NONINTERACTIVE: '1', YAD_NO_REPORT: '1', [REPORTS_ENV]: '' } });
232
+ assert.equal(r.status, 0, r.stderr);
233
+ const out = JSON.parse(r.stdout);
234
+ assert.equal(out.command, 'reports list');
235
+ assert.deepEqual(out.entries, []);
236
+ assert.equal(classify(['reports', 'list']), 'read');
237
+ assert.equal(classify(['reports', 'prune']), 'read', 'a dry run');
238
+ assert.equal(classify(['reports', 'prune'], ['apply']), 'on-request');
239
+ } finally { done(ws); }
240
+ });
241
+
242
+ test('review 1: a linked kind folder, a linked reports folder or a bare file name never lets prune, list or open leave the folder', { skip: process.platform === 'win32' && 'making a folder link needs extra rights on Windows' }, () => {
243
+ const { ws, root } = product();
244
+ try {
245
+ const dir = path.join(ws, 'product--reports');
246
+ saveReport(root, { kind: 'usage', scope: 'team', state: 's', ext: 'md', content: 'x', at: AT, env: noEnv });
247
+ const outside = path.join(ws, 'outside');
248
+ put(path.join(outside, 'keep.txt'), 'keep');
249
+ fs.symlinkSync(outside, path.join(dir, 'standup'));
250
+ const cat = JSON.parse(fs.readFileSync(path.join(dir, CATALOG_FILE), 'utf8'));
251
+ cat.entries.push({ file: 'standup/keep.txt', kind: 'standup', scope: 'x', state: 'x', createdAt: '2000-01-01T00:00:00.000Z' });
252
+ cat.entries.push({ file: '.gitignore', kind: 'usage', scope: 'x', state: 'x', createdAt: '2000-01-01T00:00:00.000Z' });
253
+ cat.entries.push({ file: 'catalog.json', kind: 'usage', scope: 'x', state: 'x', createdAt: '2000-01-01T00:00:00.000Z' });
254
+ fs.writeFileSync(path.join(dir, CATALOG_FILE), JSON.stringify(cat));
255
+ const listed = listReports(root, { env: noEnv }).entries;
256
+ assert.equal(listed.find((e) => e.file === 'standup/keep.txt').present, false, 'a file through a linked folder is not "present"');
257
+ const r = pruneReports(root, { days: 1, now: AT.getTime() + 864e5, apply: true, env: noEnv });
258
+ assert.deepEqual(r.removed.map((e) => e.reason).sort(), ['outside', 'outside', 'outside']);
259
+ assert.equal(fs.readFileSync(path.join(outside, 'keep.txt'), 'utf8'), 'keep', 'never deleted through the link');
260
+ assert.ok(fs.existsSync(path.join(dir, '.gitignore')), 'the folder\'s own files are never pruned');
261
+ assert.equal(readCatalog(dir).entries.length, 1);
262
+ // The reports folder itself a link: said, and nothing read or changed through it.
263
+ const real = path.join(ws, 'real-reports');
264
+ fs.mkdirSync(real);
265
+ const env = { [REPORTS_ENV]: path.join(ws, 'linked-reports') };
266
+ fs.symlinkSync(real, env[REPORTS_ENV]);
267
+ assert.match(listReports(root, { env }).problem, /not a plain folder/);
268
+ assert.match(pruneReports(root, { days: 0, apply: true, env }).problem, /not a plain folder/);
269
+ assert.match(saveReport(root, { kind: 'usage', scope: 't', state: 's', ext: 'md', content: 'x', env }).problem, /not a plain folder/);
270
+ } finally { done(ws); }
271
+ });
272
+
273
+ test('review 1: a folder that cannot be written is a refusal with the way out, never a crash', { skip: process.platform === 'win32' || process.getuid?.() === 0 }, () => {
274
+ const { ws, root } = product();
275
+ try {
276
+ const locked = path.join(ws, 'locked');
277
+ fs.mkdirSync(locked);
278
+ fs.chmodSync(locked, 0o500);
279
+ try {
280
+ const r = saveReport(root, { kind: 'usage', scope: 't', state: 's', ext: 'md', content: 'x', env: { [REPORTS_ENV]: path.join(locked, 'reports') } });
281
+ assert.match(r.problem, /cannot save the report .* set YAD_REPORTS_DIR .* or pass --out/);
282
+ } finally { fs.chmodSync(locked, 0o700); }
283
+ } finally { done(ws); }
284
+ });
285
+
286
+ test('review 1: a name already taken is never overwritten, and a held catalog lock waits, then is said', () => {
287
+ const { ws, root } = product();
288
+ try {
289
+ const dir = path.join(ws, 'product--reports');
290
+ const a = saveReport(root, { kind: 'usage', scope: 'team', state: 's', ext: 'md', content: 'first', at: AT, env: noEnv });
291
+ const b = saveReport(root, { kind: 'usage', scope: 'team', state: 's', ext: 'md', content: 'second', at: AT, env: noEnv });
292
+ assert.equal(fs.readFileSync(a.file, 'utf8'), 'first');
293
+ assert.equal(fs.readFileSync(b.file, 'utf8'), 'second');
294
+ // A lock held by a run that is still going (this test's own pid): the report is saved, the catalog is
295
+ // left, and the warning says where the report is — never "try again", which would save a second copy.
296
+ fs.writeFileSync(path.join(dir, 'catalog.lock'), `${process.pid} ${'a'.repeat(16)}`);
297
+ const held = saveReport(root, { kind: 'usage', scope: 'team', state: 'held', ext: 'md', content: 'x', at: AT, env: noEnv, lockWaitMs: 200 });
298
+ assert.ok(fs.existsSync(held.file));
299
+ assert.match(held.warnings[0], /the report was saved at .*held.*not added to the catalog: .*catalog\.lock is held by another yad run that is still going/);
300
+ assert.equal(readCatalog(dir).entries.length, 2);
301
+ assert.equal(fs.readFileSync(path.join(dir, 'catalog.lock'), 'utf8'), `${process.pid} ${'a'.repeat(16)}`, 'a lock that is not ours is never removed');
302
+ // A lock whose run is gone (no such process) is taken over at once, and ours is removed after.
303
+ fs.writeFileSync(path.join(dir, 'catalog.lock'), `2147483646 ${'b'.repeat(16)}`);
304
+ saveReport(root, { kind: 'usage', scope: 'team', state: 'after', ext: 'md', content: 'x', at: AT, env: noEnv });
305
+ assert.equal(readCatalog(dir).entries.length, 3);
306
+ assert.equal(fs.existsSync(path.join(dir, 'catalog.lock')), false);
307
+ assert.deepEqual(fs.readdirSync(dir).filter((n) => n.includes('.stale')), [], 'the set-aside lock is gone too');
308
+ } finally { done(ws); }
309
+ });
310
+
311
+ test('review 3: a young lock yad cannot judge is waited on, never taken; a lock it cannot read ends at the deadline', () => {
312
+ const ws = tmp();
313
+ try {
314
+ const lock = path.join(ws, 'catalog.lock');
315
+ let ran = 0;
316
+ for (const odd of ['', 'half', '0 x']) {
317
+ fs.writeFileSync(lock, odd);
318
+ const r = withCatalogLock(ws, () => { ran++; return {}; }, { waitMs: 150 });
319
+ assert.equal(r.held, true, `${JSON.stringify(odd)} is not taken over while young`);
320
+ assert.equal(fs.readFileSync(lock, 'utf8'), odd);
321
+ }
322
+ // The same content, older than 5 minutes: taken over, used, and released.
323
+ const old = new Date(Date.now() - 6 * 60 * 1000);
324
+ fs.utimesSync(lock, old, old);
325
+ assert.deepEqual(withCatalogLock(ws, () => { ran++; return { ok: 1 }; }, { waitMs: 150 }), { ok: 1 });
326
+ assert.equal(ran, 1);
327
+ assert.equal(fs.existsSync(lock), false);
328
+ // A folder where the lock should be: the loop ends, with the reason.
329
+ fs.mkdirSync(lock);
330
+ const t0 = Date.now();
331
+ const r = withCatalogLock(ws, () => { ran++; return {}; }, { waitMs: 150 });
332
+ assert.ok(Date.now() - t0 < 3000, 'no endless spin');
333
+ assert.equal(r.held, true);
334
+ assert.equal(ran, 1);
335
+ assert.deepEqual(fs.readdirSync(ws).filter((n) => /\.(new|stale)$/.test(n)), [], 'no temp lock files left');
336
+ } finally { done(ws); }
337
+ });
338
+
339
+ test('review 4: on a disk with no hard links the lock falls back to a plain create, and the catalog still updates', () => {
340
+ const { ws, root } = product();
341
+ const link = fs.linkSync;
342
+ fs.linkSync = () => { const e = new Error('operation not permitted'); e.code = 'EPERM'; throw e; };
343
+ try {
344
+ saveReport(root, { kind: 'usage', scope: 'team', state: 'a', ext: 'md', content: 'x', at: AT, env: noEnv });
345
+ const b = saveReport(root, { kind: 'usage', scope: 'team', state: 'b', ext: 'md', content: 'y', at: AT, env: noEnv });
346
+ assert.deepEqual(b.warnings, []);
347
+ const dir = path.join(ws, 'product--reports');
348
+ assert.equal(readCatalog(dir).entries.length, 2);
349
+ assert.equal(fs.existsSync(path.join(dir, 'catalog.lock')), false);
350
+ assert.deepEqual(fs.readdirSync(dir).filter((n) => /\.(new|stale)$/.test(n)), [], 'no temp lock file left');
351
+ assert.equal(pruneReports(root, { days: 0, now: AT.getTime() + 864e5, apply: true, env: noEnv }).removed.length, 2, 'prune works there too');
352
+ } finally { fs.linkSync = link; done(ws); }
353
+ });
354
+
355
+ test('review 5: a takeover that moved a fresh lock puts it back, also on a disk with no hard links', () => {
356
+ const ws = tmp();
357
+ const link = fs.linkSync, rename = fs.renameSync;
358
+ try {
359
+ const lock = path.join(ws, 'catalog.lock');
360
+ const fresh = `${process.pid} ${'c'.repeat(16)}`;
361
+ fs.writeFileSync(lock, `2147483646 ${'d'.repeat(16)}`); // judged stale (its run is gone)…
362
+ fs.renameSync = (from, to) => { fs.writeFileSync(from, fresh); fs.renameSync = rename; return rename(from, to); }; // …but replaced before the move
363
+ fs.linkSync = () => { const e = new Error('no links'); e.code = 'ENOTSUP'; throw e; };
364
+ const r = withCatalogLock(ws, () => ({ ran: true }), { waitMs: 150 });
365
+ assert.equal(r.held, true, 'the live lock is waited on, never taken');
366
+ assert.equal(fs.readFileSync(lock, 'utf8'), fresh, 'and it is back in place');
367
+ } finally { fs.linkSync = link; fs.renameSync = rename; done(ws); }
368
+ });
369
+
370
+ test('E181: prune removes a report\'s digest side file with it, and nothing else', () => {
371
+ const { ws, root } = product();
372
+ try {
373
+ const r = saveReport(root, { kind: 'progress-map', scope: 'all epics', state: '1 of 2', ext: 'html', content: 'x', at: new Date(2026, 0, 1), env: noEnv });
374
+ fs.writeFileSync(`${r.file}.digest.json`, '{}');
375
+ const other = path.join(path.dirname(r.file), 'keep.digest.json');
376
+ fs.writeFileSync(other, '{}');
377
+ pruneReports(root, { days: 30, now: AT.getTime(), apply: true, env: noEnv });
378
+ assert.equal(fs.existsSync(r.file), false);
379
+ assert.equal(fs.existsSync(`${r.file}.digest.json`), false);
380
+ assert.ok(fs.existsSync(other));
381
+ } finally { done(ws); }
382
+ });
@@ -460,6 +460,10 @@ test('yad run checks: the base follows the registry like yad open-pr, and GitLab
460
460
  const r = yad(backend, ['run', 'checks', '--no-build', '--body', body]);
461
461
  assert.match(r.out, /base origin\/develop/);
462
462
  assert.match(r.out, /the description is \d+ characters; GitLab hands CI only the first 2700/);
463
+ // From a plain git worktree of backend, beside it, too: it is backend, so the registry's base (#515).
464
+ git(backend, 'worktree', 'add', '-q', path.join(W, 'backend-wt'), '-b', 'feat/wt');
465
+ const wt = yad(path.join(W, 'backend-wt'), ['run', 'checks', '--no-build', '--body', body]);
466
+ assert.match(wt.out, /base origin\/develop/, wt.out);
463
467
  } finally { fs.rmSync(W, { recursive: true, force: true }); }
464
468
  });
465
469
 
@@ -188,7 +188,7 @@ test('yad worktree: an epic that is not there, a repo not registered, and a repo
188
188
  } finally { fs.rmSync(W, { recursive: true, force: true }); }
189
189
  });
190
190
 
191
- test('from an epic\'s code worktree: the registry knows the repo, and Product commands go to the epic\'s Product worktree (#115)', () => {
191
+ test('from an epic\'s code worktree: the registry knows the repo, and Product commands go to the epic\'s Product worktree (#115); a plain worktree is the repo too (#515)', () => {
192
192
  const { W, P, api, pwt, awt } = workspace();
193
193
  try {
194
194
  assert.equal(yad(P, 'worktree', 'add', 'EP-x', '--repo', 'api').code, 0);
@@ -199,9 +199,30 @@ test('from an epic\'s code worktree: the registry knows the repo, and Product co
199
199
  assert.deepEqual([found.root, found.worktree, found.repo?.name], [pwt, 'EP-x', 'api']);
200
200
  const r = yad(awt, 'worktree', 'list');
201
201
  assert.match(r.stderr, /Product: \.\.\/product--EP-x \(EP-x's worktree\)/);
202
- // A worktree yad did not make maps nothing: E80 review 3 still holds for it.
202
+ // A plain worktree yad did not make is api too (#515), worked in its own folder (E80 review 3).
203
203
  git(api, 'worktree', 'add', '-q', '--detach', path.join(W, 'api-other'));
204
- assert.equal(registryEntryFor(P, path.join(W, 'api-other')), null);
204
+ const plain = registryEntryFor(P, path.join(W, 'api-other', 'src'));
205
+ assert.deepEqual([plain?.meta?.name, plain && fs.realpathSync(plain.top)], ['api', fs.realpathSync(path.join(W, 'api-other'))]);
206
+ assert.equal(findProduct(path.join(W, 'api-other')).repo?.name, 'api', 'beside the Product, it finds it');
207
+ // A `.git` file written by hand that points at api's worktree folder is not that worktree: git's back-link
208
+ // names another folder.
209
+ const wtGit = fs.readFileSync(path.join(W, 'api-other', '.git'), 'utf8');
210
+ fs.mkdirSync(path.join(W, 'fake'));
211
+ fs.writeFileSync(path.join(W, 'fake', '.git'), wtGit.replace(/gitdir:\s*(.+)/, (_, p) => `gitdir: ${path.resolve(path.join(W, 'api-other'), p.trim())}`));
212
+ assert.equal(registryEntryFor(P, path.join(W, 'fake')), null, 'the back-link names api-other');
213
+ // Nor a `.git` file pointing at yad's own epic worktree of api, with its record (#515 review 2).
214
+ const awtGit = fs.readFileSync(path.join(awt, '.git'), 'utf8');
215
+ fs.mkdirSync(path.join(W, 'fake-epic'));
216
+ fs.writeFileSync(path.join(W, 'fake-epic', '.git'), awtGit.replace(/gitdir:\s*(.+)/, (_, p) => `gitdir: ${path.resolve(awt, p.trim())}`));
217
+ assert.equal(registryEntryFor(P, path.join(W, 'fake-epic')), null, 'the back-link names api--EP-x');
218
+ assert.equal(findProduct(path.join(W, 'fake-epic')).repo, undefined, 'and it borrows no repo from the workspace file');
219
+ // A worktree of another clone of api is not the registered checkout.
220
+ git(W, 'clone', '-q', path.join(W, 'api.git'), 'api-clone');
221
+ git(path.join(W, 'api-clone'), 'worktree', 'add', '-q', '--detach', path.join(W, 'api-clone-wt'));
222
+ assert.equal(registryEntryFor(P, path.join(W, 'api-clone-wt')), null, 'another clone');
223
+ // Nor is a plain worktree of the Product a registered code repo.
224
+ git(P, 'worktree', 'add', '-q', '--detach', path.join(W, 'product-plain'));
225
+ assert.equal(registryEntryFor(P, path.join(W, 'product-plain')), null, 'never the Product\'s own entry');
205
226
  // Nor does a record copied into some other repo's worktree.
206
227
  const other = repoWithOrigin(W, 'other', { f: 'x\n' });
207
228
  git(other, 'worktree', 'add', '-q', '--detach', path.join(W, 'other--EP-x'));
@@ -23,10 +23,13 @@ import {
23
23
  import { registerDesign, registerLearning, registerTesting } from './setup.mjs';
24
24
 
25
25
  // Each shipped tool's recipe. `null`: nothing to install here (the person's app, account or service — the
26
- // tool's `manual` says how). An agent step is a package-manager or plugin install, pinned to the vetted version
27
- // wherever one is vetted; `recipeProblems` checks it. The `claude` steps are Claude Code's: with another agent,
28
- // the connect-tool rule hands every step to the person.
26
+ // tool's `manual` says how). An agent step is a package-manager or plugin install, or the tool's own config
27
+ // writer, pinned to the vetted version wherever one is vetted; `recipeProblems` checks it. A step that names
28
+ // `claude` or `claude-code` is Claude Code's: with another agent, the connect-tool rule hands every step to the
29
+ // person.
29
30
  const A = (run) => ({ who: 'agent', run, scope: 'user' });
31
+ // An agent step that changes the project folder it runs in, not the user account (E175: a Unity plugin).
32
+ const AP = (run) => ({ who: 'agent', run, scope: 'project' });
30
33
  const P = (run, why) => ({ who: 'person', run, why });
31
34
  // A person step that is a thing to do, not a command to type.
32
35
  const PT = (run, why) => ({ who: 'person', run, why, text: true });
@@ -42,11 +45,23 @@ export const RECIPES = Object.freeze({
42
45
  'bmad-method': [P('npx bmad-method install', INTERACTIVE)],
43
46
  ecc: [P('npx ecc-universal install --guided', INTERACTIVE)],
44
47
  'mattpocock-skills': [P('claude plugin install mattpocock-skills', 'it comes from its own plugin marketplace, which you add in your agent first')],
48
+ graphify: [A('uv tool install graphifyy==0.9.108')],
45
49
  'docker-mcp': [PT('set up the MCP Toolkit in Docker Desktop: https://docs.docker.com/ai/mcp-catalog-and-toolkit/toolkit/', 'it is a feature of the Docker Desktop app')],
46
50
  'unity-mcp': [
47
51
  PT('in the Unity Editor, open the Package Manager (Window → Package Manager), choose + → Add (in Unity 6: Install) package from git URL, and enter https://github.com/CoplayDev/unity-mcp.git?path=/MCPForUnity#v10.3.0', 'it is set up inside the Unity Editor, in your project'),
48
52
  PT('then open Window → MCP for Unity → Toggle MCP Window; under Per-client setup, with Claude Code chosen, set Client Project Dir to the folder your agent starts in (the Unity repo, unless you start it elsewhere); press Configure All Detected Clients, and restart your agent', 'the Editor writes the server into your agent\'s settings for that folder only, and an agent loads a new MCP server when it starts'),
49
53
  ],
54
+ // E175: the default Unity tool. The agent installs the plugin (CLI and plugin both at the vetted version) and
55
+ // writes a local stdio server (no cloud endpoint, no project key) for Claude Code, from the Unity repo; the
56
+ // connection mode and transport are set in the Editor only, so Custom + stdio is the person's step: with the
57
+ // plugin's default transport (streamableHttp) the Editor starts its own server on the project's port, and the
58
+ // agent's stdio server cannot start ("address already in use").
59
+ 'ai-game-developer': [
60
+ AP('npx unity-mcp-cli@1.11.1 install-plugin . --plugin-version 1.11.1'),
61
+ AP('npx unity-mcp-cli@1.11.1 setup-mcp claude-code . --transport stdio'),
62
+ PT('open the repo in the Unity Editor, then Window → AI Game Dev; set the connection mode to Custom, not Cloud, and the transport to stdio', 'Custom runs the server on this machine (Cloud sends your Editor data to ai-game.dev after a sign-in, and that choice is yours); stdio lets your agent start that server, which the Editor\'s own server would otherwise block'),
63
+ PT('restart your agent, and approve the ai-game-developer server when it asks', 'an agent loads a new MCP server when it starts, and asks before it uses one a project folder adds'),
64
+ ],
50
65
  figma: [
51
66
  A('claude plugin install figma@claude-plugins-official'),
52
67
  PT('sign in to Figma in your agent (its Figma MCP server)', 'a sign-in is yours: it is your Figma account'),
@@ -140,12 +155,12 @@ function askText(tool, steps, { found, file, replaces, productRoot }) {
140
155
  const parts = [];
141
156
  for (const s of steps) {
142
157
  const last = parts[parts.length - 1];
143
- if (last && last.who === s.who) last.runs.push(s);
144
- else parts.push({ who: s.who, runs: [s] });
158
+ if (last && last.who === s.who && last.scope === s.scope) last.runs.push(s);
159
+ else parts.push({ who: s.who, scope: s.scope, runs: [s] });
145
160
  }
146
161
  const said = parts.map((p, i) => {
147
162
  const lead = i === 0 ? (p.who === 'person' ? 'first, ' : '') : 'then ';
148
- if (p.who === 'agent') return `${lead}I will run ${p.runs.map((r) => `\`${r.run}\``).join(', then ')} (for your user account on this machine)`;
163
+ if (p.who === 'agent') return `${lead}I will run ${p.runs.map((r) => `\`${r.run}\``).join(', then ')} (${p.scope === 'project' ? 'in this project folder: it changes the project\'s files and this folder\'s agent settings' : 'for your user account on this machine'})`;
149
164
  return `${lead}you ${p.runs.map((r) => `${r.text ? r.run : `run \`${r.run}\``} (${r.why})`).join(', then ')}`;
150
165
  });
151
166
  said[0] = said[0][0].toUpperCase() + said[0].slice(1);
package/cli/toolbox.mjs CHANGED
@@ -215,6 +215,32 @@ export const TOOLBOX = Object.freeze([
215
215
  records: null, note: 'About 8 contributors: fine as an option, risky as a default.',
216
216
  usedBy: ['yad skill bind'],
217
217
  },
218
+ {
219
+ // E176: the code half of the project brain. `yad brain build` runs it in each connected code repo, at the
220
+ // vetted version only (GRAPHIFY_VERSION in cli/brain.mjs), with its LLM pass off (GRAPHIFY_BACKEND=none):
221
+ // only the local tree-sitter parse runs, so no source leaves the machine. yadflow reads the work items
222
+ // itself. Recommended, not core: the brain works without it, as the work-item layer alone.
223
+ id: 'graphify', name: 'Graphify', tier: 'recommended', role: 'maps each code repo into a knowledge graph (files, symbols, calls, imports) for the project brain (`yad brain`)',
224
+ licence: 'Apache-2.0', source: 'https://github.com/Graphify-Labs/graphify', checked: '2026-11-13',
225
+ vetted: {
226
+ on: '2026-11-13', licenceFrom: 'https://github.com/Graphify-Labs/graphify/blob/v8/LICENSE',
227
+ source: 'https://github.com/Graphify-Labs/graphify', release: 'v0.9.108',
228
+ packages: [{ registry: 'pypi', name: 'graphifyy', version: '0.9.108' }],
229
+ note: 'The PyPI name has two y\'s (`graphifyy`); its project links name https://github.com/Graphify-Labs/graphify, and the README says it is the only official package. Other graphify* packages on PyPI are not this tool. The repository moved from safishamsi/graphify, which redirects. Its default branch is `v8`.',
230
+ },
231
+ install: [
232
+ { type: 'python', command: 'uv tool install graphifyy' },
233
+ { type: 'python', command: 'pipx install graphifyy' },
234
+ ],
235
+ manual: null,
236
+ detect: { bins: ['graphify'] },
237
+ versions: null,
238
+ fallback: 'no code graph. yad brain build writes the work-item layer alone (epics, stories, tasks, contract surfaces, ships), with a file node for each file a task declares',
239
+ // No skill writes a line when it is missing: `yad brain build` says so on the terminal.
240
+ records: null,
241
+ note: 'yad never runs `graphify install`, `hook install` or `watch`, and never starts its MCP server or its query commands: yad brain reads the graph file itself.',
242
+ usedBy: ['yad brain build'],
243
+ },
218
244
  {
219
245
  // Not a pool of skills (#361): a gateway that runs other MCP servers, so no yad skill or command uses
220
246
  // it, and `yad skill recommend` never names it as a pool (recommend.mjs: POOLS).
@@ -240,7 +266,8 @@ export const TOOLBOX = Object.freeze([
240
266
  {
241
267
  // #321 (E168): a Unity code repo's editor, for yad-implement. Recommended, not a connector: it is set up in
242
268
  // the Unity Editor of one repo, with no Product file, and yad-implement's "In a Unity repo" section says
243
- // when to use it (a recommended tool has no generated "When a tool is missing" section).
269
+ // when to use it (a recommended tool has no generated "When a tool is missing" section). Since E175 it is the
270
+ // fallback: used only where it is installed and ai-game-developer (the default) is not.
244
271
  id: 'unity-mcp', name: 'Unity MCP (MCP for Unity)', tier: 'recommended', role: 'drives the Unity Editor in a Unity code repo: compile errors, the console, tests',
245
272
  licence: 'MIT', source: 'https://github.com/CoplayDev/unity-mcp', checked: '2026-11-08',
246
273
  vetted: {
@@ -260,6 +287,29 @@ export const TOOLBOX = Object.freeze([
260
287
  note: 'Needs Unity 2021.3 or newer, Python 3.10 or newer with uv, and the Unity Editor open on the repo while the agent works. Unity registers it for Claude Code for the Unity project folder only, so its tools load in an agent started there. Found by its server name only (yad never reads a server\'s settings).',
261
288
  usedBy: ['yad-implement'],
262
289
  },
290
+ {
291
+ // E175: the default Unity Editor server (the user, 2026-11-13), with MCP for Unity kept as the fallback.
292
+ // Recommended for the same reasons as unity-mcp; yad-implement's "In a Unity repo" section uses one of the
293
+ // two — this one when it is installed — and offers to connect this one when neither is.
294
+ id: 'ai-game-developer', name: 'Unity MCP (AI Game Developer)', tier: 'recommended', role: 'drives the Unity Editor in a Unity code repo: the console, tests',
295
+ licence: 'Apache-2.0', source: 'https://github.com/IvanMurzak/Unity-MCP', checked: '2026-11-13',
296
+ vetted: {
297
+ on: '2026-11-13', licenceFrom: 'https://github.com/IvanMurzak/Unity-MCP/blob/main/LICENSE',
298
+ source: 'https://github.com/IvanMurzak/Unity-MCP', release: '1.11.1',
299
+ packages: [{ registry: 'npm', name: 'unity-mcp-cli', version: '1.11.1' }],
300
+ note: 'The Unity package is com.ivanmurzak.unity.mcp on OpenUPM (not a registry the toolbox names); unity-mcp-cli on npm adds it to a project (pinned with --plugin-version, since its default is the latest), and the plugin downloads its own server binary into Library/mcp-server/. Its connection mode is Cloud by default: the Editor connects to https://ai-game.dev/mcp after a sign-in, so Editor data leaves the machine. Custom mode runs the server locally and keeps it there: yadflow recommends Custom. The server\'s analytics and authorization webhooks are off unless set.',
301
+ },
302
+ // It is set up in the Unity project and its Editor: none of the four install types fits.
303
+ install: [],
304
+ manual: 'https://github.com/IvanMurzak/Unity-MCP#quick-start',
305
+ // Its setup registers the server as ai-game-developer, for every agent: matched whatever its case.
306
+ detect: { mcp: ['ai-game-developer'] },
307
+ versions: null,
308
+ fallback: 'files only: yad-implement edits the C# and asks the person to open Unity and report its console errors',
309
+ records: 'Unity not reachable: console checked by <person>',
310
+ note: 'The default Unity tool. Needs the Unity Editor open on the repo while the agent works, and a project path with no spaces. Its connect writes a local stdio server for the agent; use its Custom (local) connection mode, since Cloud mode sends Editor data to ai-game.dev. Found by its server name only (yad never reads a server\'s settings).',
311
+ usedBy: ['yad-implement'],
312
+ },
263
313
 
264
314
  // ---- connectors: what a Product connects (skills/sdlc/config.yaml names the same adapters) -------
265
315
  {
@@ -680,7 +730,12 @@ export function versionInRange(version, range) {
680
730
 
681
731
  // Is a program on PATH — by reading the PATH folders, never by starting one. On Windows a program is
682
732
  // `name` plus one of PATHEXT's endings (`.EXE`, `.CMD`, …); elsewhere it must be an executable file.
683
- export function onPath(bin, { env = process.env, platform = process.platform } = {}) {
733
+ // Whether a program is on PATH. `whereOnPath` gives the file itself, so a caller can start THAT file: a bare
734
+ // name started without a shell is looked for in the current folder first on Windows (E176 review 1).
735
+ export function onPath(bin, opts = {}) {
736
+ return whereOnPath(bin, opts) !== null;
737
+ }
738
+ export function whereOnPath(bin, { env = process.env, platform = process.platform } = {}) {
684
739
  // Only absolute folders: an empty or relative entry means "the current folder", which is not where a
685
740
  // tool is installed, and would make the answer depend on where `yad` happened to run.
686
741
  // On Windows that means a drive and a root (C:\x) or a share (\\server\share): \x is on whatever drive
@@ -696,11 +751,11 @@ export function onPath(bin, { env = process.env, platform = process.platform } =
696
751
  try {
697
752
  if (!fs.statSync(full).isFile()) continue;
698
753
  if (platform !== 'win32') fs.accessSync(full, fs.constants.X_OK);
699
- return true;
754
+ return full;
700
755
  } catch { /* not here */ }
701
756
  }
702
757
  }
703
- return false;
758
+ return null;
704
759
  }
705
760
 
706
761
  const lower = (s) => String(s).toLowerCase();