yadflow 4.6.0 → 4.8.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 (136) hide show
  1. package/CHANGELOG.md +259 -0
  2. package/README.md +46 -4
  3. package/bin/commands.mjs +9 -2
  4. package/bin/yad.mjs +309 -30
  5. package/cli/agent-guard.mjs +511 -0
  6. package/cli/agent-guide.mjs +83 -0
  7. package/cli/agent-rules.mjs +381 -0
  8. package/cli/argv-flags.mjs +7 -0
  9. package/cli/artifact-status.mjs +88 -20
  10. package/cli/build.mjs +1372 -0
  11. package/cli/checkpoint.mjs +2 -2
  12. package/cli/ci-check.mjs +492 -0
  13. package/cli/commit.mjs +1 -0
  14. package/cli/dial.mjs +21 -1
  15. package/cli/docs.mjs +7 -2
  16. package/cli/doctor.mjs +176 -33
  17. package/cli/epic-state.mjs +360 -12
  18. package/cli/errors.mjs +3 -0
  19. package/cli/find-product.mjs +36 -2
  20. package/cli/fold.mjs +9 -5
  21. package/cli/gate-local.mjs +9 -1
  22. package/cli/gate.mjs +364 -22
  23. package/cli/guide.mjs +549 -0
  24. package/cli/history.mjs +22 -2
  25. package/cli/hook.mjs +35 -4
  26. package/cli/index-command.mjs +2 -2
  27. package/cli/ledger.mjs +60 -0
  28. package/cli/lib.mjs +46 -0
  29. package/cli/lifecycle/defaults/2.json +124 -0
  30. package/cli/lifecycle/lifecycle.schema.json +5 -2
  31. package/cli/lifecycle.mjs +16 -3
  32. package/cli/manifest.mjs +75 -0
  33. package/cli/marked-block.mjs +48 -0
  34. package/cli/members.mjs +19 -5
  35. package/cli/migrate.mjs +17 -19
  36. package/cli/next.mjs +35 -12
  37. package/cli/openpr.mjs +81 -5
  38. package/cli/plan.mjs +326 -22
  39. package/cli/platform.mjs +21 -0
  40. package/cli/pr-list.mjs +5 -3
  41. package/cli/product-index.mjs +6 -3
  42. package/cli/product-token.mjs +186 -0
  43. package/cli/productcommit.mjs +33 -0
  44. package/cli/protection.mjs +50 -0
  45. package/cli/recommend.mjs +3 -1
  46. package/cli/reconcile.mjs +187 -26
  47. package/cli/repo-publish.mjs +2 -2
  48. package/cli/report.mjs +62 -14
  49. package/cli/run-checks.mjs +586 -0
  50. package/cli/setup.mjs +244 -25
  51. package/cli/ship-drift.mjs +49 -18
  52. package/cli/signing.mjs +377 -0
  53. package/cli/standup.mjs +1 -1
  54. package/cli/status.mjs +282 -0
  55. package/cli/test-agents-file.mjs +993 -0
  56. package/cli/test-build.mjs +1559 -0
  57. package/cli/test-ci-check.mjs +616 -0
  58. package/cli/test-guide.mjs +1267 -0
  59. package/cli/test-node.mjs +129 -0
  60. package/cli/test-run-checks.mjs +603 -0
  61. package/cli/test-setup-agent.mjs +352 -0
  62. package/cli/test-signing.mjs +524 -0
  63. package/cli/test-worktree.mjs +520 -0
  64. package/cli/thread.mjs +4 -0
  65. package/cli/tidy.mjs +2 -2
  66. package/cli/toolbox.mjs +37 -6
  67. package/cli/update-commit.mjs +313 -11
  68. package/cli/workspace.mjs +38 -10
  69. package/cli/worktree-record.mjs +53 -0
  70. package/cli/worktree.mjs +379 -0
  71. package/package.json +6 -4
  72. package/skills/sdlc/config.yaml +5 -5
  73. package/skills/sdlc/module-help.csv +2 -1
  74. package/skills/yad-backfill/templates/checks/backfill-check.sh +9 -9
  75. package/skills/yad-change/SKILL.md +5 -1
  76. package/skills/yad-checks/SKILL.md +61 -12
  77. package/skills/yad-checks/references/check-gates.md +78 -14
  78. package/skills/yad-checks/templates/checks/build-test-lint.sh +22 -3
  79. package/skills/yad-checks/templates/checks/commit-message.sh +8 -2
  80. package/skills/yad-checks/templates/checks/contract-check.sh +61 -33
  81. package/skills/yad-checks/templates/checks/epic-open.sh +87 -14
  82. package/skills/yad-checks/templates/checks/ledger-guard.sh +3 -3
  83. package/skills/yad-checks/templates/checks/lineage-check.sh +88 -15
  84. package/skills/yad-checks/templates/checks/member-check.mjs +206 -35
  85. package/skills/yad-checks/templates/checks/package-manager.sh +42 -5
  86. package/skills/yad-checks/templates/checks/product-checkout.sh +161 -13
  87. package/skills/yad-checks/templates/checks/reconcile-debt-check.sh +94 -15
  88. package/skills/yad-checks/templates/checks/risk-map-check.sh +2 -2
  89. package/skills/yad-checks/templates/checks/spec-link.sh +63 -4
  90. package/skills/yad-checks/templates/checks/verified-commits.sh +23 -5
  91. package/skills/yad-checks/templates/github/yad-checks.yml +9 -9
  92. package/skills/yad-checks/templates/gitlab/.gitlab-ci.yml +4 -1
  93. package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml +5 -5
  94. package/skills/yad-checks/templates/gitlab/yad-product-checks.gitlab-ci.yml +16 -3
  95. package/skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml +5 -1
  96. package/skills/yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml +5 -1
  97. package/skills/yad-checks/templates/hooks/agent-guard.mjs +116 -0
  98. package/skills/yad-commit/SKILL.md +8 -5
  99. package/skills/yad-connect-repos/SKILL.md +5 -3
  100. package/skills/yad-connect-repos/references/code-context.md +2 -1
  101. package/skills/yad-connect-repos/references/repos-registry.md +2 -1
  102. package/skills/yad-docs/templates/app/package-lock.json +395 -106
  103. package/skills/yad-docs/templates/app/package.json +2 -2
  104. package/skills/yad-docs-overview/references/pipeline-model.md +2 -2
  105. package/skills/yad-engineer-review/SKILL.md +55 -25
  106. package/skills/yad-engineer-review/references/ship-and-record.md +49 -12
  107. package/skills/yad-epic/SKILL.md +2 -1
  108. package/skills/yad-epic/references/state-schema.md +76 -17
  109. package/skills/yad-guide/SKILL.md +192 -0
  110. package/skills/yad-implement/SKILL.md +75 -13
  111. package/skills/yad-implement/references/implement-conventions.md +8 -1
  112. package/skills/yad-implement/templates/.gitmessage +3 -0
  113. package/skills/yad-open-pr/SKILL.md +21 -0
  114. package/skills/yad-pair-review/SKILL.md +14 -5
  115. package/skills/yad-pr-template/SKILL.md +6 -2
  116. package/skills/yad-pr-template/templates/checks/pr-template.sh +85 -4
  117. package/skills/yad-pr-template/templates/checks/pr-title.sh +1 -1
  118. package/skills/yad-pr-template/templates/github/pull_request_template.md +1 -1
  119. package/skills/yad-pr-template/templates/gitlab/merge_request_templates/Default.md +1 -1
  120. package/skills/yad-product-bridge/SKILL.md +44 -12
  121. package/skills/yad-product-bridge/references/bridge.md +11 -5
  122. package/skills/yad-product-bridge/templates/github/yad-gate-sync.yml +2 -2
  123. package/skills/yad-product-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml +9 -4
  124. package/skills/yad-reconcile/SKILL.md +9 -3
  125. package/skills/yad-report/SKILL.md +15 -0
  126. package/skills/yad-review-companion/SKILL.md +5 -3
  127. package/skills/yad-review-gate/SKILL.md +16 -8
  128. package/skills/yad-review-gate/references/gating.md +26 -1
  129. package/skills/yad-run/SKILL.md +61 -33
  130. package/skills/yad-run/references/run-loop.md +44 -22
  131. package/skills/yad-spec/SKILL.md +137 -16
  132. package/skills/yad-spec/references/spec-handoff.md +50 -3
  133. package/skills/yad-status/SKILL.md +7 -0
  134. package/skills/yad-stories/references/story-schema.md +1 -1
  135. package/skills/yad-sync-repos/SKILL.md +2 -1
  136. package/skills/yad-ui/SKILL.md +2 -2
package/cli/toolbox.mjs CHANGED
@@ -18,7 +18,8 @@
18
18
  //
19
19
  // THREE TIERS:
20
20
  // core offered at setup (E85) — repomix, spec-kit, impeccable
21
- // recommended listed, never pushed — pools of skills and agents a team may choose (Part 7)
21
+ // recommended listed, never pushed — pools of skills and agents a team may choose (Part 7),
22
+ // and other optional tools such as Docker MCP Toolkit (#361)
22
23
  // connector the tools a Product connects for design, testing and learning (`yad-connect-*`); the
23
24
  // same adapters `skills/sdlc/config.yaml` names, with the same fallbacks
24
25
  //
@@ -78,7 +79,8 @@ const VET_REGISTRIES = Object.freeze(['npm', 'pypi']);
78
79
  // (Docker, Homebrew, a VS Code extension) are in its own README, which `source` links. `versions` is null
79
80
  // everywhere: no bound has been tested, and E88 vets licence and source, not a version range. `records`
80
81
  // is the exact line a skill writes when the tool is absent. Each skill in
81
- // `usedBy` quotes `fallback` and `records` word for word in its "When a tool is missing" section (E87):
82
+ // `usedBy` quotes `fallback` and `records` word for word in its "When a tool is missing" section (E87),
83
+ // and `recordsElse`, when set, names the one case that records another line (#348):
82
84
  // change the words here, then rewrite the sections with `skillFallbackSection`.
83
85
  export const TOOLBOX = Object.freeze([
84
86
  // ---- core: offered at setup --------------------------------------------------------------------
@@ -126,6 +128,7 @@ export const TOOLBOX = Object.freeze([
126
128
  versions: null,
127
129
  fallback: "yad-spec writes the same spec files by hand, in Spec Kit's layout",
128
130
  records: 'speckit: not-installed', note: 'A program named specify on PATH also counts; another tool by that name would too.',
131
+ recordsElse: 'a light spec, which never runs Spec Kit and records `speckit: not-used` (#348)',
129
132
  usedBy: ['yad-spec'],
130
133
  },
131
134
  {
@@ -212,6 +215,28 @@ export const TOOLBOX = Object.freeze([
212
215
  records: null, note: 'About 8 contributors: fine as an option, risky as a default.',
213
216
  usedBy: ['yad skill bind'],
214
217
  },
218
+ {
219
+ // Not a pool of skills (#361): a gateway that runs other MCP servers, so no yad skill or command uses
220
+ // it, and `yad skill recommend` never names it as a pool (recommend.mjs: POOLS).
221
+ id: 'docker-mcp', name: 'Docker MCP Toolkit', tier: 'recommended', role: "a gateway that runs MCP servers from Docker's catalogue as containers",
222
+ licence: 'MIT', source: 'https://github.com/docker/mcp-gateway', checked: '2026-10-26',
223
+ vetted: {
224
+ on: '2026-10-26', licenceFrom: 'https://github.com/docker/mcp-gateway/blob/main/LICENSE',
225
+ source: 'https://github.com/docker/mcp-gateway', release: 'v0.44.2',
226
+ packages: [],
227
+ note: 'The gateway and its `docker mcp` CLI plugin are MIT; Docker Desktop, which ships them, is under Docker\'s own terms. v0.44.2 is the newest tag, published as a GitHub pre-release, as every release there is, so GitHub names no latest release.',
228
+ },
229
+ // It comes with Docker Desktop: none of the four install types fits.
230
+ install: [],
231
+ manual: 'https://docs.docker.com/ai/mcp-catalog-and-toolkit/toolkit/',
232
+ // The plugin is not on PATH, so the one server a client connects through is the signal.
233
+ detect: { mcp: ['MCP_DOCKER'] },
234
+ versions: null,
235
+ fallback: 'nothing changes: agents use the MCP servers they already have',
236
+ records: null,
237
+ note: 'The first gateway start pulls every server image and can outlast a client\'s 30-second timeout: warm it once with `docker mcp gateway run --profile <id> --dry-run`. A server\'s secrets (an access token) are set with `docker mcp secret set`, never in yad.',
238
+ usedBy: [],
239
+ },
215
240
 
216
241
  // ---- connectors: what a Product connects (skills/sdlc/config.yaml names the same adapters) -------
217
242
  {
@@ -375,6 +400,8 @@ export function toolProblems(t) {
375
400
  need(typeof t?.fallback !== 'string' || !/[.\s]$/.test(t.fallback), 'fallback ends without a full stop or a space');
376
401
  need(t?.records === null || (typeof t?.records === 'string' && t.records.length > 0), 'records is null or the line a skill writes');
377
402
  need(t?.note === null || (typeof t?.note === 'string' && t.note.length > 0), 'note is null or a sentence');
403
+ need(t?.recordsElse === undefined || (typeof t.recordsElse === 'string' && t.recordsElse.length > 0 && t.records !== null && !/\.$/.test(t.recordsElse)),
404
+ 'recordsElse is absent, or the one other case, with records set and no full stop (the section adds it)');
378
405
  need(t?.manual === null || (typeof t?.manual === 'string' && /^https:\/\//.test(t.manual)), 'manual is null or an https URL');
379
406
  need(isStringList(t?.usedBy), 'usedBy lists the skills or commands that use it');
380
407
  need(t?.tier !== 'connector' || !isStringList(t?.usedBy) || connectorFile(t) !== null, 'a connector names the yad-connect-* skill that connects it');
@@ -467,7 +494,7 @@ export function parseVersion(v) {
467
494
 
468
495
  // The semantic-versioning order: numbers first; then a pre-release is below its release, and two
469
496
  // pre-releases compare label by label — a number below a word, numbers as numbers, a shorter list first.
470
- function compare(a, b) {
497
+ export function compare(a, b) {
471
498
  for (let i = 0; i < 3; i++) if (a.parts[i] !== b.parts[i]) return a.parts[i] < b.parts[i] ? -1 : 1;
472
499
  if (!a.pre || !b.pre) return a.pre === b.pre ? 0 : a.pre ? -1 : 1;
473
500
  const x = a.pre.split('.');
@@ -729,7 +756,7 @@ export function toolUse(tool, { shipped, connected }) {
729
756
  // tool is installed.
730
757
  // connector used when the Product's design, testing or learning file connects it. The connect skill
731
758
  // writes that file and the step skill follows it, as before E87.
732
- // Recommended tools are bound with `yad skill bind`, so no skill names one.
759
+ // Recommended tools are bound with `yad skill bind`, or, like Docker MCP, used by no skill, so no skill names one.
733
760
  export const SKILL_FALLBACK_HEADING = '## When a tool is missing';
734
761
  // The section's last line. The section is exactly the lines from its heading to this marker, so a
735
762
  // rewrite never has to guess from the Markdown where the section ends (rounds 5 to 9 of the E87 review
@@ -746,6 +773,10 @@ export function connectorFile(tool) {
746
773
  // The skills (folders under skills/, not `yad <command>`s) that use a tool.
747
774
  export const skillsUsing = (tool) => tool.usedBy.filter((u) => !u.startsWith('yad '));
748
775
 
776
+ // The line a skill writes when the tool was not used. `recordsElse` is the one case where the skill chose
777
+ // not to use it and records another line (yad-spec's light spec, #348), so the two never read against each other.
778
+ const recordLine = (t) => ` - Record \`${t.records}\`. It means the tool was not used, whatever the reason${t.recordsElse ? ` — except ${t.recordsElse}` : ''}.`;
779
+
749
780
  export function skillFallbackSection(skill, tools = TOOLBOX) {
750
781
  const mine = tools.filter((t) => t.tier !== 'recommended' && skillsUsing(t).includes(skill));
751
782
  if (!mine.length) return null;
@@ -784,7 +815,7 @@ export function skillFallbackSection(skill, tools = TOOLBOX) {
784
815
  for (const t of core) {
785
816
  lines.push(`- **${t.name}** (\`${t.id}\`). 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 ${t.id}\`) — use the fallback.`);
786
817
  lines.push(` - Fallback — ${t.fallback}.`);
787
- if (t.records) lines.push(` - Record \`${t.records}\`. It means the tool was not used, whatever the reason.`);
818
+ if (t.records) lines.push(recordLine(t));
788
819
  }
789
820
  for (const t of connectors) {
790
821
  const file = connectorFile(t);
@@ -794,7 +825,7 @@ export function skillFallbackSection(skill, tools = TOOLBOX) {
794
825
  ? `- **${t.name}** (\`${t.id}\`, a connector). This skill connects it, by writing \`${file}\` as the steps below say. The other skills follow that file, not yad's toolbox answer.`
795
826
  : `- **${t.name}** (\`${t.id}\`, a connector). Used when \`${file}\` connects it. ${connect} writes that file; follow it, not yad's toolbox answer.`);
796
827
  lines.push(` - Fallback — ${t.fallback}.`);
797
- if (t.records) lines.push(` - Record \`${t.records}\`. It means the tool was not used, whatever the reason.`);
828
+ if (t.records) lines.push(recordLine(t));
798
829
  }
799
830
  lines.push('', SKILL_FALLBACK_END);
800
831
  return lines.join('\n');
@@ -22,7 +22,8 @@
22
22
  import fs from 'node:fs';
23
23
  import path from 'node:path';
24
24
  import { c, log, ok, info, warn, fail, hand, run, pushWithRebase, samePath } from './lib.mjs';
25
- import { VERSION } from './manifest.mjs';
25
+ import { VERSION, PROJECT_FILES, MANAGED_LEDGER, productConfigPath } from './manifest.mjs';
26
+ import { parseVersion, compare as compareVersions } from './toolbox.mjs';
26
27
  import { productGit, resolveDefaultBranch } from './productcommit.mjs';
27
28
 
28
29
  // Collapse whitespace/newline runs to a single space — keeps a stray path or hostile value from
@@ -77,18 +78,51 @@ export function buildUpdateMessage({ version = VERSION, items = [] } = {}) {
77
78
  // .gitlab-ci.yml a github repo never has) that would otherwise abort `git add`.
78
79
  // Returns the pathspecs actually staged.
79
80
  function stageAllowlist(git, root, paths) {
80
- const keep = paths.filter((p) => {
81
- if (run('git', ['check-ignore', '-q', '--', p], { cwd: root }).ok) return false;
82
- if (fs.existsSync(path.join(root, p))) return true;
83
- return run('git', ['ls-files', '--error-unmatch', '--', p], { cwd: root }).ok;
84
- });
81
+ // Every path list goes to git on stdin, never as arguments: `--open-pr` hands over every file of every skill
82
+ // folder, hundreds of paths, which overflowed Windows' 32K command line (E157 update review 7); and one
83
+ // spawn per path took minutes (review 6).
84
+ if (!paths.length) return { staged: [] };
85
+ // Whole-repo lists can pass Node's 1 MB default in a big repo, which cuts them short: a cut list would drop a
86
+ // deletion from staging without a word. Room is made, and a list that still fails is said, never used.
87
+ const big = { cwd: root, maxBuffer: 1024 * 1024 * 1024 };
88
+ const ignoredRun = run('git', ['check-ignore', '-z', '--stdin'], { ...big, input: paths.join('\0') });
89
+ const trackedRun = run('git', ['ls-files', '-z'], big);
90
+ // check-ignore exits 1 when nothing is ignored; only a spawn error is a failed read there.
91
+ const unread = ignoredRun.error || trackedRun.error || !trackedRun.ok;
92
+ if (unread) return { staged: [], addError: `could not list the repo's files (${(ignoredRun.error || trackedRun.error)?.code || trackedRun.stderr.split('\n')[0] || `exit ${trackedRun.code}`})` };
93
+ const ignored = new Set(ignoredRun.stdout.split('\0').filter(Boolean));
94
+ const tracked = trackedRun.stdout.split('\0').filter(Boolean);
95
+ const trackedSet = new Set(tracked);
96
+ // A folder path covers every file under it.
97
+ const under = (p, f) => f === p || f.startsWith(`${p.replace(/\/$/, '')}/`);
98
+ const isTracked = (p) => trackedSet.has(p) || tracked.some((t) => under(p, t));
99
+ const keep = paths.filter((p) => !ignored.has(p) && (fs.existsSync(path.join(root, p)) || isTracked(p)));
85
100
  if (!keep.length) return { staged: [] };
86
101
  // `git add` can exit non-zero (index lock, permissions) yet run() never throws — surface it rather
87
102
  // than silently reporting "nothing to commit". (A directory pathspec whose contents are ALL ignored
88
103
  // also exits 1 after staging the rest; the empty-diff below then correctly drops it.)
89
- const add = git('add', '--', ...keep);
90
- const staged = git('diff', '--cached', '--name-only', '--', ...keep).stdout.split('\n').filter(Boolean);
91
- return { staged, addError: !add.ok ? (add.stderr.split('\n')[0] || `exit ${add.code}`) : null };
104
+ const add = withPaths(root, ['add'], keep);
105
+ const diff = run('git', ['diff', '--cached', '--name-only', '-z'], big);
106
+ const staged = diff.ok ? diff.stdout.split('\0').filter((f) => f && keep.some((p) => under(p, f))) : [];
107
+ const addError = !add.ok ? (add.stderr.split('\n')[0] || `exit ${add.code}`)
108
+ : !diff.ok ? `could not read what was staged (${diff.error?.code || diff.stderr.split('\n')[0] || `exit ${diff.code}`})` : null;
109
+ // Nothing of ours may stay staged when the list of it could not be read.
110
+ if (!diff.ok) withPaths(root, ['reset', '-q'], keep);
111
+ return { staged, addError };
112
+ }
113
+
114
+ // `git <args>` over a list of literal paths read from stdin (NUL-separated), not the command line.
115
+ function withPaths(root, args, paths) {
116
+ return run('git', [...args, '--pathspec-from-file=-', '--pathspec-file-nul'], { cwd: root, input: paths.join('\0') });
117
+ }
118
+
119
+ // Network git that never waits on a question an agent cannot answer: no password prompt (HTTPS), and no SSH
120
+ // passphrase or host-key question unless the person set their own ssh command, which is left alone.
121
+ function quietGit(root) {
122
+ const env = { ...process.env, GIT_TERMINAL_PROMPT: '0' };
123
+ const own = process.env.GIT_SSH_COMMAND || process.env.GIT_SSH || run('git', ['config', '--get', 'core.sshCommand'], { cwd: root }).ok;
124
+ if (!own) env.GIT_SSH_COMMAND = 'ssh -o BatchMode=yes';
125
+ return (...args) => run('git', args, { cwd: root, env });
92
126
  }
93
127
 
94
128
  // Commit (and, with push, push) one repo group. `defaultBranch` is the repo's configured default
@@ -140,9 +174,9 @@ export function commitAndPush(group, { push = false, allowBranch = false, produc
140
174
  }
141
175
 
142
176
  const message = buildUpdateMessage({ items });
143
- const cm = git('commit', '-m', message, '--', ...staged);
177
+ const cm = withPaths(root, ['commit', '-m', message], staged);
144
178
  if (!cm.ok) {
145
- git('reset', '-q', '--', ...staged); // don't leave our allowlist staged for an unrelated commit to sweep up
179
+ withPaths(root, ['reset', '-q'], staged); // don't leave our allowlist staged for an unrelated commit to sweep up
146
180
  fail(`${label}: git commit failed — ${cm.stderr.split('\n')[0] || cm.code}`);
147
181
  process.exitCode = 1;
148
182
  return { label, product: isProduct, committed: false, pushed: false, skipped: false, error: true };
@@ -196,3 +230,271 @@ export function commitUpdates(productRoot, groups, { push = false, allowBranch =
196
230
  } else ok(`update committed locally — ${committed}/${groups.length} repo(s); push with \`yad update --push\``);
197
231
  return results;
198
232
  }
233
+
234
+ // ---- `yad update --open-pr` / `yad check --fix --open-pr`: the same commit, reviewed ----------------
235
+ // The other way to publish an update (2026-10-27, the agent-first feature E157): each repo's changes go on
236
+ // their own branch, which is pushed, and a PR/MR is opened against the default branch. A person merges it,
237
+ // so the pull_request gates check the new files first, and it works where branch protection blocks a direct
238
+ // push. The branch is the update's own, so an AI agent opens it without asking (cli/agent-rules.mjs).
239
+ // Afterwards the repo is back on its default branch: the update lands there when the PR/MR merges.
240
+
241
+ export const updateBranchName = (version = VERSION) => `chore/yad-update-v${oneLine(version).replace(/[^0-9A-Za-z.-]/g, '-')}`;
242
+
243
+ // PURE — the PR/MR body. It carries the code template's required sections (`## Summary`, `## Impact &
244
+ // Risk` with a filled `Risk level:`, `## Checklist`), so the pr-template gate passes it on a code repo and
245
+ // on the Product (a non-review branch there is read as a tooling change). The file list comes last.
246
+ export function buildUpdatePrBody({ version = VERSION, items = [] } = {}) {
247
+ const list = items.length ? items.map((i) => `- ${oneLine(i)}`).join('\n') : '- the version stamp only';
248
+ return [
249
+ '## Summary',
250
+ '',
251
+ `\`yad update\` brought the files yadflow manages here up to yadflow v${oneLine(version)}. The files are listed at the end.`,
252
+ '',
253
+ '## Impact & Risk',
254
+ '',
255
+ 'Risk level: low',
256
+ '',
257
+ 'Only files yadflow installs and manages changed. The checks on this PR/MR run them before they land.',
258
+ '',
259
+ '## Checklist',
260
+ '',
261
+ '- [x] Only yadflow-managed files are in this change',
262
+ '- [ ] After the merge, each person pulls the default branch',
263
+ '',
264
+ // Last: a long list must never push a required section past GitLab's description cut.
265
+ '## Files',
266
+ '',
267
+ list,
268
+ ].join('\n');
269
+ }
270
+
271
+ // The repos `--open-pr` reaches, and so the ones it checks: the Product and every connected repo that is
272
+ // cloned here (one that is not is `yad repo clone`'s business, not the update's). ONE list for both
273
+ // readers — reconcile, which refuses a run, and the guide, which must never advise a run that is refused.
274
+ export function updateTargets(productRoot) {
275
+ const settings = readJSONSafe(productConfigPath(productRoot)) ?? {};
276
+ const registry = readJSONSafe(path.join(productRoot, '.sdlc/repos.json'));
277
+ const repos = (Array.isArray(registry?.repos) ? registry.repos : [])
278
+ .filter((x) => typeof x?.path === 'string' && x.path)
279
+ .map((x) => ({ root: path.resolve(productRoot, x.path), name: typeof x.name === 'string' ? x.name : x.path, defaultBranch: x.default_branch ?? null, platform: x.platform ?? null, file: MANAGED_LEDGER }))
280
+ .filter((x) => x.root !== productRoot && fs.existsSync(path.join(x.root, '.git')));
281
+ // `file`: where each records the yadflow version that last wrote it.
282
+ return [{ root: productRoot, name: 'product', defaultBranch: settings.default_branch ?? null, platform: settings.platform ?? null, product: true, file: PROJECT_FILES.version }, ...repos];
283
+ }
284
+ const isRoot = (a, b) => path.resolve(a) === path.resolve(b);
285
+ const readJSONSafe = (f) => { try { return JSON.parse(fs.readFileSync(f, 'utf8')); } catch { return null; } };
286
+
287
+ // Where one repo stands against its default branch, from git alone (origin as last fetched, no network):
288
+ // the branch checked out (null when detached or unborn), whether it has an origin, and how far HEAD is
289
+ // ahead of and behind origin/<base>. Every pull or push hint below is decided from this table.
290
+ export function branchTable(root, { defaultBranch } = {}) {
291
+ const git = productGit(root);
292
+ const top = git('rev-parse', '--show-toplevel');
293
+ if (!(top.ok && samePath(top.stdout, root))) return { repo: false };
294
+ const base = defaultBranch || resolveDefaultBranch(git);
295
+ const sym = git('symbolic-ref', '--short', '-q', 'HEAD');
296
+ const born = git('rev-parse', '--verify', '--quiet', 'HEAD').ok;
297
+ const here = sym.ok && sym.stdout ? sym.stdout : null;
298
+ const origin = git('remote', 'get-url', 'origin').ok;
299
+ const tracked = origin && git('rev-parse', '--verify', '--quiet', `refs/remotes/origin/${base}`).ok;
300
+ const count = (range) => { const r = git('rev-list', '--count', range); return r.ok ? Number(r.stdout) : null; };
301
+ return { repo: true, base, here, born, detached: !sym.ok, origin, tracked,
302
+ ahead: tracked && born ? count(`origin/${base}..HEAD`) : null,
303
+ behind: tracked && born ? count(`HEAD..origin/${base}`) : null };
304
+ }
305
+
306
+ // Why a repo cannot take the update as a PR/MR now, or null. Asked BEFORE anything is applied (reconcile),
307
+ // so a repo that cannot take it is never left with the update written into its working tree: a dirty
308
+ // default branch would stop the person's own `git pull` once the PR/MR merges.
309
+ // kind `merged`: the update of this version is already on origin's default branch — pull it, never a
310
+ // second PR/MR. kind `open`: the update is on review (its branch is here, or on origin from another clone)
311
+ // — a person merges it. Both are HELD: nothing is written there. Every other kind needs the person to fix
312
+ // something first, and stops the run.
313
+ // With `network` (the default), origin's default branch and the update branch are fetched first, so a stale
314
+ // clone sees what already happened. `file` is the version record to compare: the Product's stamp, or a
315
+ // connected repo's managed ledger.
316
+ export const HELD_KINDS = ['merged', 'open'];
317
+ export function updatePrBlocker(root, { defaultBranch, version = VERSION, productRoot = root, network = true, table = null, file = null } = {}) {
318
+ const label = repoLabel(productRoot, root);
319
+ // `table`: the caller's own read of `branchTable`, so it is not asked twice.
320
+ const t = table ?? branchTable(root, { defaultBranch });
321
+ if (!t.repo) return { kind: 'not-a-repo', label, message: 'not its own git repo (missing or renamed clone?)' };
322
+ if (!t.born) return { kind: 'unborn', label, message: `has no commit yet — commit and push '${t.base}' first` };
323
+ if (t.detached) return { kind: 'detached', label, message: `a detached HEAD — check out '${t.base}' first` };
324
+ if (t.here !== t.base) return { kind: 'branch', label, message: `on '${t.here}', not the default branch '${t.base}' — switch to '${t.base}' first` };
325
+ if (!t.origin) return { kind: 'no-origin', label, message: 'no origin remote to push the update branch to' };
326
+ const git = productGit(root);
327
+ const head = updateBranchName(version);
328
+ const rel = isRoot(productRoot, root) ? '.' : repoLabel(productRoot, root);
329
+ if (network) {
330
+ // What origin already has. Never a prompt (an agent cannot answer one), and a fetch that fails is said:
331
+ // what follows is then read from origin as last fetched.
332
+ const quiet = quietGit(root);
333
+ if (!quiet('fetch', '-q', 'origin', t.base).ok) warn(`${label}: could not fetch origin's '${t.base}' — reading it as last fetched`);
334
+ // Exit 0: the update branch is on origin; fetch it, so later reads (the guide's too) see it. Exit 2: it is
335
+ // NOT on origin (deleted there, with the web page's button), so this clone's copy of it is dropped — kept,
336
+ // it would read as "on review" for good. Any other exit is a failed read: the copy is trusted as it is.
337
+ const lr = quiet('ls-remote', '--exit-code', '--heads', 'origin', head);
338
+ if (lr.ok) quiet('fetch', '-q', 'origin', `+refs/heads/${head}:refs/remotes/origin/${head}`);
339
+ else if (lr.code === 2) git('update-ref', '-d', `refs/remotes/origin/${head}`);
340
+ }
341
+ const versionAt = (ref) => { const s = file ? git('show', `${ref}:${file}`) : { ok: false }; try { return s.ok ? JSON.parse(s.stdout)?.version ?? null : null; } catch { return null; } };
342
+ const want = parseVersion(version);
343
+ const here = parseVersion(versionAt('HEAD'));
344
+ // This clone already has a NEWER install than this yadflow: running it would write the older templates and
345
+ // stamp over it — a downgrade PR/MR. The person updates yadflow first.
346
+ if (here && want && compareVersions(here, want) > 0) {
347
+ const v = String(versionAt('HEAD')).trim();
348
+ return { kind: 'newer', label, message: `'${t.base}' here has the update to v${v}, newer than this yadflow (v${version}) — update yadflow itself to v${v} or later, then run this again` };
349
+ }
350
+ if (file && git('rev-parse', '--verify', '--quiet', `refs/remotes/origin/${t.base}`).ok) {
351
+ const there = parseVersion(versionAt(`refs/remotes/origin/${t.base}`));
352
+ // Held only while THIS clone's commit is behind what origin has: once pulled, the run goes on as usual,
353
+ // so a same-version repair (a deleted managed file) is still possible.
354
+ if (there && want && compareVersions(there, want) >= 0 && (!here || compareVersions(here, there) < 0)) {
355
+ const newer = compareVersions(there, want) > 0;
356
+ return { kind: 'merged', label, message: `origin's '${t.base}' already has the update to v${versionAt(`refs/remotes/origin/${t.base}`)} — pull it: \`git -C ${rel} pull --ff-only origin ${t.base}\`${newer ? `; it is newer than this yadflow (v${version}), so update yadflow here too` : ''}` };
357
+ }
358
+ }
359
+ const onReview = (where) => ({ kind: 'open', label, branch: head, message: `the update is on review from '${head}'${where}: a person merges its PR/MR, then run this again. If no PR/MR was opened from it, open one into '${t.base}'; if it was closed without merging, delete the branch (here and on origin), then run this again` });
360
+ // Once this clone's commit has the update (merged and pulled), an update branch left behind is not "on
361
+ // review": the run goes on, so a same-version repair still works, and `openUpdatePr` deals with the leftover.
362
+ const landed = here && want && compareVersions(here, want) >= 0;
363
+ if (!landed && git('rev-parse', '--verify', '--quiet', `refs/heads/${head}`).ok) return onReview('');
364
+ if (!landed && git('rev-parse', '--verify', '--quiet', `refs/remotes/origin/${head}`).ok) return onReview(' (on origin)');
365
+ // `ahead` is null when origin/<base> was never fetched: the branch is then cut from the local base as it
366
+ // is, and the push says the rest.
367
+ if (t.ahead > 0) return { kind: 'ahead', label, message: `${t.ahead} local commit(s) on '${t.base}' are not on origin — push or drop them first, so the update PR/MR carries only the update` };
368
+ return null;
369
+ }
370
+
371
+ // One repo group: branch, commit exactly the allowlist, push the branch, open the PR/MR, switch back.
372
+ // Never throws; sets process.exitCode on a hard error. `creator(platform, opts)` opens the PR/MR (createPr).
373
+ export function openUpdatePr(group, { productRoot, defaultBranch, platform, creator, version = VERSION, checked = false } = {}) {
374
+ const { root, paths, items } = group;
375
+ const label = repoLabel(productRoot ?? root, root);
376
+ const isProduct = root === (productRoot ?? root);
377
+ const git = productGit(root);
378
+ const out = (o) => ({ label, product: isProduct, branch: null, committed: false, pushed: false, opened: false, pr: null, skipped: false, error: false, ...o });
379
+ // `checked`: reconcile already asked, before it wrote anything; asking again would be a second network read.
380
+ const blocked = checked ? null : updatePrBlocker(root, { defaultBranch, version, productRoot: productRoot ?? root });
381
+ if (blocked) {
382
+ (blocked.kind === 'open' ? info : warn)(`${label}: ${blocked.message}${blocked.kind === 'open' ? '' : ' — skipped'}`);
383
+ return out({ skipped: true, branch: blocked.branch ?? null, reason: blocked.kind, hint: blocked.message });
384
+ }
385
+ const base = defaultBranch || resolveDefaultBranch(git);
386
+ const head = updateBranchName(version);
387
+ const where = isProduct ? '.' : label;
388
+ // Staged on the default branch first, so a repo with nothing to commit never gets a branch, and a
389
+ // staging problem is said before anything else moves.
390
+ const { staged, addError } = stageAllowlist(git, root, paths);
391
+ const unstage = () => { if (staged.length) withPaths(root, ['reset', '-q'], staged); };
392
+ if (addError) {
393
+ unstage();
394
+ fail(`${label}: git add failed — ${addError}`);
395
+ process.exitCode = 1;
396
+ return out({ error: true, reason: 'add-failed', hint: `git could not stage the update in ${where} (${oneLine(addError).slice(0, 160)}) — often a leftover index.lock or file permissions; fix it and run this again: the update is in the working tree, and the next run carries it` });
397
+ }
398
+ if (!staged.length) { info(`${label}: nothing to commit (unchanged or ignored)`); return out({}); }
399
+ // An update branch left from an update that already merged (`updatePrBlocker` lets the run on once this
400
+ // clone has it). Dropped only when it holds nothing but the update's own commit; anything else is a person's.
401
+ const leftover = (why) => {
402
+ unstage();
403
+ fail(`${label}: ${why}`);
404
+ process.exitCode = 1;
405
+ return out({ error: true, reason: 'leftover-branch', hint: why });
406
+ };
407
+ if (git('rev-parse', '--verify', '--quiet', `refs/heads/${head}`).ok) {
408
+ const extra = git('log', '--format=%s', `${base}..${head}`);
409
+ const subjects = extra.ok ? extra.stdout.split('\n').filter(Boolean) : null;
410
+ const ours = subjects && subjects.every((x) => x === buildUpdateMessage({ version, items: [] }));
411
+ if (!ours || !git('branch', '-q', '-D', head).ok) {
412
+ return leftover(`the branch '${head}' is left from the update that already merged, and holds other commits: look at it (\`git -C ${where} log ${base}..${head}\`), delete it (\`git -C ${where} branch -D ${head}\`), then run this again`);
413
+ }
414
+ }
415
+ if (git('rev-parse', '--verify', '--quiet', `refs/remotes/origin/${head}`).ok) {
416
+ return leftover(`the branch '${head}' is still on origin, left from the update that already merged: delete it on origin (\`git -C ${where} push origin --delete ${head}\`), then run this again`);
417
+ }
418
+ if (!git('switch', '-q', '-c', head).ok) {
419
+ unstage();
420
+ fail(`${label}: could not create the branch '${head}'`);
421
+ process.exitCode = 1;
422
+ return out({ error: true, reason: 'branch-failed', hint: `git could not create '${head}' in ${where} — see what \`git switch -c ${head}\` says there, fix it, and run this again` });
423
+ }
424
+ // Back to the default branch. A switch that fails (a hook rewrote a committed file) leaves the repo on the
425
+ // update branch: said, never silent.
426
+ const stuck = `${where} is still on '${head}': run \`git switch ${base}\` there (the changes come with it), then \`git branch -D ${head}\``;
427
+ const back = () => {
428
+ const r = git('switch', '-q', base);
429
+ if (!r.ok) {
430
+ fail(`${label}: could not switch back to '${base}' — ${r.stderr.split('\n')[0] || 'see git'}; run \`git switch ${base}\` in ${where}`);
431
+ process.exitCode = 1;
432
+ }
433
+ return r.ok;
434
+ };
435
+ const cm = withPaths(root, ['commit', '-m', buildUpdateMessage({ version, items })], staged);
436
+ if (!cm.ok) {
437
+ unstage();
438
+ const home = back();
439
+ if (home) git('branch', '-q', '-D', head);
440
+ const why = cm.stderr.split('\n')[0] || `exit ${cm.code}`;
441
+ fail(`${label}: git commit failed — ${why}`);
442
+ process.exitCode = 1;
443
+ return out({ error: true, branch: home ? null : head, reason: 'commit-failed', hint: `the commit failed (${oneLine(why).slice(0, 160)}) — often signing or a hook; fix it and run this again: the update is still in the working tree, and the next run carries it${home ? '' : `. First: ${stuck}`}` });
444
+ }
445
+ ok(`${label}: committed ${staged.length} file(s) on ${head}`);
446
+ const pushed = quietGit(root)('push', '-q', '-u', 'origin', head);
447
+ if (!pushed.ok) {
448
+ // The branch is dropped, so a run after the push problem is fixed tries again rather than reading it as
449
+ // "already on review". The update stays in the working tree, unstaged, deletions included: the branch is
450
+ // moved back to the base with the files left as they are, then the switch to the base carries them.
451
+ // Only the update's own paths are unstaged: anything the person had staged before the run stays staged.
452
+ // Two steps, said apart: once the soft reset is done the commit is gone from the branch, whatever follows.
453
+ const soft = git('reset', '-q', '--soft', base).ok;
454
+ const unstaged = soft && withPaths(root, ['reset', '-q'], staged).ok;
455
+ const home = soft && back();
456
+ if (home) git('branch', '-q', '-D', head);
457
+ fail(`${label}: could not push ${head} — ${pushed.stderr.split('\n')[0] || 'see git'}`);
458
+ const still = unstaged ? '' : ' (still staged)';
459
+ const hint = home
460
+ ? `fix the push (access, network) and run this again; the update is left uncommitted${still} in ${where}'s working tree, and the next run carries it`
461
+ : soft
462
+ ? `the update is left uncommitted${still} in ${where}, which is still on ${head}: run \`git switch ${base}\` there (the changes come with it), then \`git branch -D ${head}\`, fix the push and run the update again`
463
+ : `the update is committed on ${head} in ${where}; fix the push, then push that branch (\`git push -u origin ${head}\`) and open a PR/MR from it`;
464
+ hand(hint);
465
+ process.exitCode = 1;
466
+ return out({ committed: !soft, branch: home ? null : head, error: true, reason: 'push-failed', hint });
467
+ }
468
+ let opened = false;
469
+ let pr = null;
470
+ let left = null;
471
+ if (platform === 'github' || platform === 'gitlab') {
472
+ const r = creator(platform, { title: buildUpdateMessage({ version, items: [] }), body: buildUpdatePrBody({ version, items }), base, head, cwd: root });
473
+ if (r?.ok) { opened = true; pr = r.url || null; ok(`${label}: opened ${pr ?? 'the PR/MR (no URL came back)'}`); }
474
+ else {
475
+ warn(`${label}: pushed ${head}, but the PR/MR did not open — ${oneLine(r?.reason || 'no reason given').slice(0, 200)}`);
476
+ left = { reason: 'pr-not-opened', hint: `the branch '${head}' is pushed, but its PR/MR did not open (${oneLine(r?.reason || 'no reason given').slice(0, 160)}): open one from '${head}' into '${base}' by hand, or log the platform CLI in and run this again` };
477
+ hand(left.hint);
478
+ }
479
+ } else {
480
+ left = { reason: 'no-platform', hint: `the branch '${head}' is pushed, but no platform is recorded for this repo: open a PR/MR from '${head}' into '${base}' by hand` };
481
+ hand(`${label}: ${left.hint}`);
482
+ }
483
+ const home = back();
484
+ // Said together with what is left of the PR/MR, never in place of it.
485
+ if (!home) left = left ? { reason: left.reason, hint: `${left.hint}. Also: ${where} is still on '${head}': run \`git switch ${base}\` there` } : { reason: 'switch-back-failed', hint: `${where} is still on '${head}': run \`git switch ${base}\` there` };
486
+ return out({ branch: head, committed: true, pushed: true, opened, pr, error: !home, ...(left ?? {}) });
487
+ }
488
+
489
+ // Every repo the update changed, one PR/MR each.
490
+ export function openUpdatePrs(productRoot, groups, { defaultBranchFor, platformFor, creator, version = VERSION, checked = false } = {}) {
491
+ if (!groups.length) { info('no committable changes were applied'); return []; }
492
+ log('');
493
+ log(c.bold(`yad update — a branch and a PR/MR in each repo (${updateBranchName(version)})`));
494
+ const results = groups.map((g) => openUpdatePr(g, { productRoot, defaultBranch: defaultBranchFor?.(g.root), platform: platformFor?.(g.root), creator, version, checked }));
495
+ const opened = results.filter((r) => r.pushed).length;
496
+ log('');
497
+ if (results.some((r) => r.error || r.skipped)) warn(`update not fully published — ${opened}/${groups.length} repo(s) have a branch pushed; finish the rest (see above).`);
498
+ else ok(`update on review — ${opened}/${groups.length} repo(s); merge each PR/MR, then pull the default branch`);
499
+ return results;
500
+ }
package/cli/workspace.mjs CHANGED
@@ -29,13 +29,15 @@ import path from 'node:path';
29
29
  import fs from 'node:fs';
30
30
  import { spawnSync } from 'node:child_process';
31
31
  import { fileURLToPath } from 'node:url';
32
- import { c, log, ok, info, warn, hand, fail, run, exists, readJSON, readJSONStrict, forTerminal } from './lib.mjs';
32
+ import { c, log, ok, info, warn, hand, fail, run, exists, readJSON, readJSONStrict, forTerminal, inJSON } from './lib.mjs';
33
+ import { err } from './errors.mjs';
33
34
  import { productConfigPath, PROJECT_FILES } from './manifest.mjs';
34
- import { runSetup, insideWorkspace, throughGitDir, selectIdeTargets } from './setup.mjs';
35
- import { moduleActions, gitHookActions } from './plan.mjs';
35
+ import { runSetup, insideWorkspace, throughGitDir, selectIdeTargets, assertSetupAnswered, ideTargetsQuestion, checkSetupFlags } from './setup.mjs';
36
+ import { moduleActions, gitHookActions, agentFileActions } from './plan.mjs';
36
37
  import { writeWorkspaceFile, WORKSPACE_FILE } from './find-product.mjs';
37
38
  import { offerToolbox } from './toolbox.mjs';
38
39
  import { runMemberAdd } from './members.mjs';
40
+ import { linkedGitDir } from './worktree-record.mjs';
39
41
 
40
42
  // E80: the file that lets yad find the Product from inside the repos it registers. Written by all three.
41
43
  function noteWorkspaceFile(product) {
@@ -83,7 +85,7 @@ function throughLink(productRoot, target) {
83
85
  }
84
86
  return false;
85
87
  }
86
- const insideGitRepo = (dir) => run('git', ['rev-parse', '--show-toplevel'], { cwd: dir });
88
+ export const insideGitRepo = (dir) => run('git', ['rev-parse', '--show-toplevel'], { cwd: dir });
87
89
 
88
90
  // The folder `join` makes from a remote URL: its last path segment without `.git`. So the remote
89
91
  // `new acme` tells you to create (`acme`) joins back into `acme/`.
@@ -363,6 +365,8 @@ export async function runNew(cwd, name, opts = {}) {
363
365
  const workspace = path.join(cwd, name);
364
366
  if (exists(workspace) && !isEmptyDir(workspace)) return refuse(`${workspace} already exists and is not empty — pick another name, or run \`yad init\` inside it to connect what is there`);
365
367
  const product = path.join(workspace, PRODUCT_DIR);
368
+ // E159: setup's answers are checked before the folder is made — `new` runs git init itself, so that is no question.
369
+ assertSetupAnswered(product, { ...opts, greenfield: !opts.brownfield, gitInit: true });
366
370
  fs.mkdirSync(product, { recursive: true });
367
371
  if (!gitInit(product)) return refuse(`git init failed in ${product}`);
368
372
  ok(`created ${path.join(name, PRODUCT_DIR)}/ (git, branch main)`);
@@ -388,6 +392,15 @@ export async function runNew(cwd, name, opts = {}) {
388
392
  }
389
393
 
390
394
  // ---- yad init ------------------------------------------------------------------------------------
395
+ // The repos `yad init` offers: each git repo in `cwd` beside the Product folder. A linked worktree (an epic's,
396
+ // #115: `.git` is a file pointing into another repo's `worktrees/`) is a second folder of a repo already here,
397
+ // never a repo of its own. Shared with `yad guide`, which lists init's questions for them (E159).
398
+ export function reposBeside(cwd, productName = PRODUCT_DIR) {
399
+ const children = fs.readdirSync(cwd, { withFileTypes: true }).filter((d) => d.isDirectory() && !d.name.startsWith('.')).map((d) => d.name).sort();
400
+ const repos = children.filter((n) => n !== productName && exists(path.join(cwd, n, '.git')) && !linkedGitDir(path.join(cwd, n)));
401
+ const found = repos.filter(validFolderName);
402
+ return { found, odd: repos.filter((n) => !validFolderName(n)), discovered: found.map((n) => ({ name: n, rpath: `../${n}` })) };
403
+ }
391
404
  export async function runInit(cwd, opts = {}) {
392
405
  log(c.bold('\nyad init'));
393
406
  const inside = insideGitRepo(cwd);
@@ -409,20 +422,20 @@ export async function runInit(cwd, opts = {}) {
409
422
  if (exists(product) && !exists(productConfigPath(product)) && !isBareStart(product)) {
410
423
  return refuse(`${productName}/ already holds files and is not a Product — name a new folder for the Product with --path <folder>`);
411
424
  }
425
+
426
+ const { found, odd, discovered } = reposBeside(cwd, productName);
427
+ const layout = opts.monorepo ? {} : { separate: true };
428
+ // E159: setup's answers are checked before anything is made here (init runs git init itself).
429
+ assertSetupAnswered(product, { ...opts, brownfield: !opts.greenfield, ...layout, discovered, gitInit: true });
412
430
  if (!exists(product)) {
413
431
  fs.mkdirSync(product);
414
432
  if (!gitInit(product)) return refuse(`git init failed in ${product}`);
415
433
  ok(`created ${productName}/ (git, branch main)`);
416
434
  } else info(`Product folder: ${productName}/`);
417
435
 
418
- const repos = children.filter((n) => n !== productName && exists(path.join(cwd, n, '.git')));
419
- const found = repos.filter(validFolderName);
420
- const odd = repos.filter((n) => !validFolderName(n));
421
436
  if (odd.length) warn(`not offered (a repo name must be letters, digits, ".", "_" or "-"): ${odd.map(shown).join(', ')} — connect them with \`yad setup\` under another name`);
422
437
  if (found.length) info(`found ${found.length} repo(s) beside it: ${found.join(', ')}`);
423
438
  else info('found no repos beside it — connect them later with `yad setup`');
424
- const discovered = found.map((n) => ({ name: n, rpath: `../${n}` }));
425
- const layout = opts.monorepo ? {} : { separate: true };
426
439
  const setup = await runSetup(product, { ...opts, brownfield: !opts.greenfield, ...layout, discovered });
427
440
  if (process.exitCode) return null;
428
441
  noteWorkspaceFile(product);
@@ -448,12 +461,26 @@ function installLocalSkills(product, ideTargets) {
448
461
  if (local && (a.status === 'new' || a.status === 'missing')) { a.apply(); res.installed.push(rel); }
449
462
  else (local ? res.stale : res.shared).push(rel || `${a.scope}/${a.item}`);
450
463
  }
464
+ // E158: the rules block in AGENTS.md and CLAUDE.md is the team's shared file too: named, never written here.
465
+ // A block yad cannot write (`writesNothing`: markers it cannot trust) is not one `yad update` brings up to date.
466
+ for (const a of agentFileActions(product, ideTargets)) if (a.status !== 'ok' && !a.writesNothing) res.shared.push(a.item);
451
467
  return res;
452
468
  }
453
469
 
454
470
  export async function runJoin(cwd, url, folder, opts = {}) {
455
471
  log(c.bold('\nyad join'));
456
472
  if (typeof url !== 'string' || !url.trim() || url.startsWith('-')) return refuse('usage: yad join <the Product\'s clone URL> [folder]');
473
+ // E159: join's one question, the AI tools to install for, is answered by flag under --json — checked
474
+ // before anything is cloned.
475
+ // A bad --ide-targets is refused here too, never after the clone.
476
+ if (opts.ideTargets !== undefined) checkSetupFlags(cwd, { ideTargets: opts.ideTargets });
477
+ if (inJSON() && !process.env.SDLC_NONINTERACTIVE && opts.ideTargets === undefined) {
478
+ const e = err('YAD-CLI-001', 'join needs 1 answer before it can run: ide-targets', 'ask the person, then run it again with --ide-targets <a,b>');
479
+ const q = ideTargetsQuestion(path.join(cwd, folder ?? workspaceNameFromUrl(url) ?? '', PRODUCT_DIR));
480
+ delete q.given;
481
+ e.questions = [q];
482
+ throw e;
483
+ }
457
484
  const wsName = folder ?? workspaceNameFromUrl(url);
458
485
  if (!validFolderName(wsName)) return refuse(`cannot make a folder name from ${JSON.stringify(shown(url))} — pass one: yad join <url> <folder>`);
459
486
  const inside = insideGitRepo(cwd);
@@ -496,7 +523,8 @@ export async function runJoin(cwd, url, folder, opts = {}) {
496
523
  // E131: the person's member file — proven by the platform, on its own branch and PR/MR. Never fatal.
497
524
  log('');
498
525
  let member = null;
499
- try { member = await runMemberAdd(product, { soft: true, noPush: !!opts.noPush }) ?? null; }
526
+ // Under --json the platform login is never started here: a missing one comes back as the person's step (E159).
527
+ try { member = await runMemberAdd(product, { soft: true, noPush: !!opts.noPush, noLogin: inJSON() }) ?? null; }
500
528
  catch (e) { warn(`member file not written: ${shown(e.message)} — run \`yad member add\` from the Product later`); }
501
529
 
502
530
  // Under a heading of its own, so these lines do not read as part of the toolbox list above.