yadflow 4.7.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 (77) hide show
  1. package/CHANGELOG.md +89 -0
  2. package/README.md +43 -4
  3. package/bin/commands.mjs +4 -1
  4. package/bin/yad.mjs +147 -20
  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/ci-check.mjs +492 -0
  10. package/cli/docs.mjs +1 -1
  11. package/cli/doctor.mjs +43 -7
  12. package/cli/epic-state.mjs +3 -3
  13. package/cli/errors.mjs +1 -0
  14. package/cli/guide.mjs +549 -0
  15. package/cli/hook.mjs +32 -3
  16. package/cli/lib.mjs +46 -0
  17. package/cli/lifecycle/defaults/2.json +124 -0
  18. package/cli/lifecycle/lifecycle.schema.json +5 -2
  19. package/cli/lifecycle.mjs +16 -3
  20. package/cli/manifest.mjs +75 -0
  21. package/cli/marked-block.mjs +48 -0
  22. package/cli/members.mjs +19 -5
  23. package/cli/migrate.mjs +17 -19
  24. package/cli/next.mjs +1 -1
  25. package/cli/plan.mjs +326 -22
  26. package/cli/protection.mjs +50 -0
  27. package/cli/reconcile.mjs +187 -26
  28. package/cli/report.mjs +62 -14
  29. package/cli/setup.mjs +244 -25
  30. package/cli/signing.mjs +377 -0
  31. package/cli/test-agents-file.mjs +993 -0
  32. package/cli/test-ci-check.mjs +616 -0
  33. package/cli/test-guide.mjs +1267 -0
  34. package/cli/test-node.mjs +129 -0
  35. package/cli/test-setup-agent.mjs +352 -0
  36. package/cli/test-signing.mjs +524 -0
  37. package/cli/toolbox.mjs +1 -1
  38. package/cli/update-commit.mjs +313 -11
  39. package/cli/workspace.mjs +37 -12
  40. package/package.json +6 -4
  41. package/skills/sdlc/config.yaml +4 -4
  42. package/skills/sdlc/module-help.csv +1 -0
  43. package/skills/yad-change/SKILL.md +3 -2
  44. package/skills/yad-checks/SKILL.md +29 -9
  45. package/skills/yad-checks/references/check-gates.md +9 -4
  46. package/skills/yad-checks/templates/checks/package-manager.sh +1 -1
  47. package/skills/yad-checks/templates/github/yad-checks.yml +1 -1
  48. package/skills/yad-checks/templates/gitlab/.gitlab-ci.yml +1 -1
  49. package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml +1 -1
  50. package/skills/yad-checks/templates/gitlab/yad-product-checks.gitlab-ci.yml +1 -1
  51. package/skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml +1 -1
  52. package/skills/yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml +1 -1
  53. package/skills/yad-checks/templates/hooks/agent-guard.mjs +116 -0
  54. package/skills/yad-commit/SKILL.md +4 -3
  55. package/skills/yad-connect-repos/SKILL.md +5 -3
  56. package/skills/yad-connect-repos/references/code-context.md +2 -1
  57. package/skills/yad-connect-repos/references/repos-registry.md +2 -1
  58. package/skills/yad-docs-overview/references/pipeline-model.md +2 -2
  59. package/skills/yad-engineer-review/SKILL.md +12 -7
  60. package/skills/yad-engineer-review/references/ship-and-record.md +7 -4
  61. package/skills/yad-epic/SKILL.md +2 -1
  62. package/skills/yad-epic/references/state-schema.md +1 -1
  63. package/skills/yad-guide/SKILL.md +192 -0
  64. package/skills/yad-open-pr/SKILL.md +1 -1
  65. package/skills/yad-pair-review/SKILL.md +14 -5
  66. package/skills/yad-product-bridge/SKILL.md +32 -13
  67. package/skills/yad-product-bridge/references/bridge.md +6 -3
  68. package/skills/yad-product-bridge/templates/github/yad-gate-sync.yml +2 -2
  69. package/skills/yad-product-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml +1 -1
  70. package/skills/yad-report/SKILL.md +15 -0
  71. package/skills/yad-review-companion/SKILL.md +5 -3
  72. package/skills/yad-review-gate/SKILL.md +13 -9
  73. package/skills/yad-review-gate/references/gating.md +1 -1
  74. package/skills/yad-run/SKILL.md +10 -6
  75. package/skills/yad-run/references/run-loop.md +2 -1
  76. package/skills/yad-sync-repos/SKILL.md +2 -1
  77. package/skills/yad-ui/SKILL.md +2 -2
@@ -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,10 +29,11 @@ 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';
@@ -84,7 +85,7 @@ function throughLink(productRoot, target) {
84
85
  }
85
86
  return false;
86
87
  }
87
- const insideGitRepo = (dir) => run('git', ['rev-parse', '--show-toplevel'], { cwd: dir });
88
+ export const insideGitRepo = (dir) => run('git', ['rev-parse', '--show-toplevel'], { cwd: dir });
88
89
 
89
90
  // The folder `join` makes from a remote URL: its last path segment without `.git`. So the remote
90
91
  // `new acme` tells you to create (`acme`) joins back into `acme/`.
@@ -364,6 +365,8 @@ export async function runNew(cwd, name, opts = {}) {
364
365
  const workspace = path.join(cwd, name);
365
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`);
366
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 });
367
370
  fs.mkdirSync(product, { recursive: true });
368
371
  if (!gitInit(product)) return refuse(`git init failed in ${product}`);
369
372
  ok(`created ${path.join(name, PRODUCT_DIR)}/ (git, branch main)`);
@@ -389,6 +392,15 @@ export async function runNew(cwd, name, opts = {}) {
389
392
  }
390
393
 
391
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
+ }
392
404
  export async function runInit(cwd, opts = {}) {
393
405
  log(c.bold('\nyad init'));
394
406
  const inside = insideGitRepo(cwd);
@@ -410,22 +422,20 @@ export async function runInit(cwd, opts = {}) {
410
422
  if (exists(product) && !exists(productConfigPath(product)) && !isBareStart(product)) {
411
423
  return refuse(`${productName}/ already holds files and is not a Product — name a new folder for the Product with --path <folder>`);
412
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 });
413
430
  if (!exists(product)) {
414
431
  fs.mkdirSync(product);
415
432
  if (!gitInit(product)) return refuse(`git init failed in ${product}`);
416
433
  ok(`created ${productName}/ (git, branch main)`);
417
434
  } else info(`Product folder: ${productName}/`);
418
435
 
419
- // A linked worktree (an epic's, #115: `.git` is a file pointing into another repo's `worktrees/`) is a
420
- // second folder of a repo already here, never a repo of its own.
421
- const repos = children.filter((n) => n !== productName && exists(path.join(cwd, n, '.git')) && !linkedGitDir(path.join(cwd, n)));
422
- const found = repos.filter(validFolderName);
423
- const odd = repos.filter((n) => !validFolderName(n));
424
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`);
425
437
  if (found.length) info(`found ${found.length} repo(s) beside it: ${found.join(', ')}`);
426
438
  else info('found no repos beside it — connect them later with `yad setup`');
427
- const discovered = found.map((n) => ({ name: n, rpath: `../${n}` }));
428
- const layout = opts.monorepo ? {} : { separate: true };
429
439
  const setup = await runSetup(product, { ...opts, brownfield: !opts.greenfield, ...layout, discovered });
430
440
  if (process.exitCode) return null;
431
441
  noteWorkspaceFile(product);
@@ -451,12 +461,26 @@ function installLocalSkills(product, ideTargets) {
451
461
  if (local && (a.status === 'new' || a.status === 'missing')) { a.apply(); res.installed.push(rel); }
452
462
  else (local ? res.stale : res.shared).push(rel || `${a.scope}/${a.item}`);
453
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);
454
467
  return res;
455
468
  }
456
469
 
457
470
  export async function runJoin(cwd, url, folder, opts = {}) {
458
471
  log(c.bold('\nyad join'));
459
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
+ }
460
484
  const wsName = folder ?? workspaceNameFromUrl(url);
461
485
  if (!validFolderName(wsName)) return refuse(`cannot make a folder name from ${JSON.stringify(shown(url))} — pass one: yad join <url> <folder>`);
462
486
  const inside = insideGitRepo(cwd);
@@ -499,7 +523,8 @@ export async function runJoin(cwd, url, folder, opts = {}) {
499
523
  // E131: the person's member file — proven by the platform, on its own branch and PR/MR. Never fatal.
500
524
  log('');
501
525
  let member = null;
502
- 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; }
503
528
  catch (e) { warn(`member file not written: ${shown(e.message)} — run \`yad member add\` from the Product later`); }
504
529
 
505
530
  // Under a heading of its own, so these lines do not read as part of the toolbox list above.
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "yadflow",
3
- "version": "4.7.0",
4
- "description": "Shared project memory and workflows for teams building with AI: a versioned record of plans, decisions, contracts and reviews across repos, human-approved review gates, and a zero-dependency `yad` CLI plus 38 skills for your AI assistant.",
3
+ "version": "4.8.0",
4
+ "description": "Shared project memory and workflows for teams building with AI: a versioned record of plans, decisions, contracts and reviews across repos, human-approved review gates, and a zero-dependency `yad` CLI plus 39 skills for your AI assistant.",
5
5
  "type": "module",
6
6
  "author": "AbdelRahman Nasr",
7
7
  "license": "MIT",
@@ -46,10 +46,12 @@
46
46
  "scripts": {
47
47
  "yad": "node bin/yad.mjs",
48
48
  "lint": "eslint cli bin",
49
- "test": "node --test cli/test.mjs cli/test-checks.mjs cli/test-threads.mjs cli/test-golden.mjs cli/test-migrate.mjs cli/test-hooks.mjs cli/test-detect.mjs cli/test-members.mjs cli/test-standup.mjs cli/test-lifecycle.mjs cli/test-run-checks.mjs cli/test-build.mjs cli/test-worktree.mjs cli/test-fuzz.js",
49
+ "test": "node --test cli/test.mjs cli/test-checks.mjs cli/test-threads.mjs cli/test-golden.mjs cli/test-migrate.mjs cli/test-hooks.mjs cli/test-detect.mjs cli/test-members.mjs cli/test-standup.mjs cli/test-lifecycle.mjs cli/test-run-checks.mjs cli/test-build.mjs cli/test-worktree.mjs cli/test-guide.mjs cli/test-agents-file.mjs cli/test-setup-agent.mjs cli/test-signing.mjs cli/test-ci-check.mjs cli/test-node.mjs cli/test-fuzz.js",
50
50
  "test:e2e": "bash test/e2e/run.sh",
51
+ "test:agents": "bash test/agent-acceptance/run.sh",
52
+ "test:agents:selftest": "bash test/agent-acceptance/run.sh selftest",
51
53
  "release-check": "bash scripts/release-check.sh",
52
- "coverage": "node --test --experimental-test-coverage --test-coverage-exclude='cli/test*.mjs' --test-coverage-exclude='cli/test*.js' --test-coverage-lines=70 --test-coverage-branches=70 cli/test.mjs cli/test-checks.mjs cli/test-threads.mjs cli/test-golden.mjs cli/test-migrate.mjs cli/test-hooks.mjs cli/test-detect.mjs cli/test-members.mjs cli/test-standup.mjs cli/test-lifecycle.mjs cli/test-run-checks.mjs cli/test-build.mjs cli/test-worktree.mjs cli/test-fuzz.js",
54
+ "coverage": "node --test --test-reporter=tap --experimental-test-coverage --test-coverage-exclude='cli/test*.mjs' --test-coverage-exclude='cli/test*.js' --test-coverage-lines=70 --test-coverage-branches=70 cli/test.mjs cli/test-checks.mjs cli/test-threads.mjs cli/test-golden.mjs cli/test-migrate.mjs cli/test-hooks.mjs cli/test-detect.mjs cli/test-members.mjs cli/test-standup.mjs cli/test-lifecycle.mjs cli/test-run-checks.mjs cli/test-build.mjs cli/test-worktree.mjs cli/test-guide.mjs cli/test-agents-file.mjs cli/test-setup-agent.mjs cli/test-signing.mjs cli/test-ci-check.mjs cli/test-node.mjs cli/test-fuzz.js",
53
55
  "diagrams": "npx -y @mermaid-js/mermaid-cli@11.15.0 -i docs/diagrams/sdlc-overview.mmd -o docs/diagrams/sdlc-overview.svg -b transparent && npx -y @mermaid-js/mermaid-cli@11.15.0 -i docs/diagrams/review-loop.mmd -o docs/diagrams/review-loop.svg -b transparent && npx -y @mermaid-js/mermaid-cli@11.15.0 -i docs/diagrams/work-and-memory.mmd -o docs/diagrams/work-and-memory.svg -b transparent && npx -y @mermaid-js/mermaid-cli@11.15.0 -i docs/diagrams/feature-evolution.mmd -o docs/diagrams/feature-evolution.svg -b transparent",
54
56
  "prepublishOnly": "npm test"
55
57
  },
@@ -42,7 +42,7 @@ document_output_language: English
42
42
  #
43
43
  # A phase is DERIVED from a step's id and is never written into `state.json` — there is nothing to
44
44
  # author here, nothing to keep in step, and no way for it to disagree with the step it describes.
45
- # The phase of each step is set in the lifecycle default (`cli/lifecycle/defaults/1.json`), which
45
+ # The phase of each step is set in the lifecycle default (`cli/lifecycle/defaults/2.json`), which
46
46
  # `stepPhase` in cli/epic-state.mjs reads; this block is generated from it for people to read. A review gate takes the phase of the artifact it reviews, so `epic-review` is Discover.
47
47
  #
48
48
  # Release and Operate are NAMED and not built. No step, skill or gate exists for either yet.
@@ -50,7 +50,7 @@ document_output_language: English
50
50
  # NOTE the word: "phase" here means one of these six. It does NOT mean the numbered development
51
51
  # phases of yadflow itself (docs/phase-N-build-plan.md), which is what "Phase 4a/4b" means elsewhere
52
52
  # in these files, nor a gate's internal merge phase.
53
- # The step CATALOGUE is the lifecycle default that ships with yadflow, `cli/lifecycle/defaults/1.json`
53
+ # The step CATALOGUE is the lifecycle default that ships with yadflow, `cli/lifecycle/defaults/2.json`
54
54
  # (E134; the engine reads it as `STEPS` in `cli/epic-state.mjs`). It is the one place that says what a
55
55
  # step is: its phase, whether it authors or gates, what artifact it writes, which skill runs it, and
56
56
  # which step a gate reviews. The lines between the `generated` markers below are written from it by
@@ -77,7 +77,7 @@ lifecycle:
77
77
  # any epic, and part of no Part. `discovery` is listed because it is the old spelling of the same level.
78
78
  # Release and Operate are planned: E32 builds Release, E33 builds Operate.
79
79
  # `sentinels` are `currentStep` markers that are NOT steps: they never appear in `steps[]` and have no phase.
80
- # >>> generated: lifecycle — from cli/lifecycle/defaults/1.json by scripts/lifecycle-config.mjs; do not edit by hand
80
+ # >>> generated: lifecycle — from cli/lifecycle/defaults/2.json by scripts/lifecycle-config.mjs; do not edit by hand
81
81
  parts: [Shape, Build, Run]
82
82
  profiles: [classic, analysis-first, chore, spike, discovery, foundation]
83
83
  product_phases:
@@ -356,7 +356,7 @@ product:
356
356
  automation:
357
357
  # The only steps that MAY be automated, safest-end first (phase-4-build-plan.md build order).
358
358
  # The Build lane's author steps — every lane step but the merge gate, `engineer-review`.
359
- # >>> generated: back_steps — from cli/lifecycle/defaults/1.json by scripts/lifecycle-config.mjs; do not edit by hand
359
+ # >>> generated: back_steps — from cli/lifecycle/defaults/2.json by scripts/lifecycle-config.mjs; do not edit by hand
360
360
  back_steps: [spec, tasks, implement, checks]
361
361
  # <<< generated: back_steps
362
362
  default: human_approve # = `advance: human`. Every lane step starts manual; `yad dial` turns one to auto
@@ -28,6 +28,7 @@ SDLC Workflow,yad-backfill,Backfill Specs,BF,"Build Step G: generate specs for a
28
28
  SDLC Workflow,yad-run,Run (Automation),RN,"Phase 4 orchestrator: drive a story's Build loop (spec→tasks→implement→checks) in one code repo, reading each step's advance dial through the engine (yad dial --json) — on auto it advances on its own, on human it stops for a human. Records every run in the trust log, the run record yad dial shows as advice. A clean checks pass on auto advances to the engineer review; any FAIL / scope overrun / contract touch HALTS. set-dial runs yad dial (no trust threshold since E34; a gate is refused); kill/unkill run yad kill / yad unkill, recorded in .sdlc/automation.json. Never drives a Shape step; the human merge gate never auto-advances.",,{epic: EP-<slug>} {story: EP-<slug>-S0N} {repo: <repo>} {action: run|set-dial|kill|unkill} {step: <back-step>} {to: human|auto},4-automate,yad-spec,yad-engineer-review,false,epics/EP-<slug>/.sdlc/,build-state/<story-id>.json trust-log.json
29
29
  SDLC Workflow,yad-status,SDLC Status,SS,"Read-only: print the full Shape step chain, per-step dials, contract lock, story repo tags, and pending approvals at the active gate. For stories in Build, also print each Build step's automation dial and status, the run record (runs / % approved-unchanged, as advice), the Shape author dials and the kill switch from .sdlc/automation.json.",,{epic: EP-<slug>},anytime,,,false,,
30
30
  SDLC Workflow,yad-report,Report Issue,RP,"Self issue reporter: when a yad flow breaks, file a well-formed bug in the upstream yadflow repo with AUTO-SCRUBBED diagnostics (yadflow/node/os version, tool present+authenticated booleans, Product platform enum, the YadError code/hint, a path-scrubbed message, and the failing command + flag NAMES only) — never absolute paths, hostnames, git URLs, repo names, logins/emails, epic/story IDs, branch names, or flag values. Searches open issues first to avoid duplicates, previews the exact payload, and asks before posting to the public repo; files via an authenticated gh (the upstream repo is on GitHub) or a prefilled issues/new URL fallback. Also offered automatically after an unexpected failure (interactive only; YAD_NO_REPORT=1 disables). Never a gate, never touches epic state.",,{message: one-line summary},,,,false,,
31
+ SDLC Workflow,yad-guide,Agent Guide,AG,"The yadflow rules for an AI coding agent: run `yad guide --json` before each step, brief the person (what the step is for, mandatory or skippable, who does it, the skill or tool), do the agent's part, hand the person's part over with the exact command or steps and confirm by reading. Holds the class of every yad command (run, ask every time, the person's), the human-only acts, the push rules (never a force push), keeping the install current with `yad update --open-pr`, and reporting a yadflow bug or idea with `yad report` after the person's yes. Load before any yadflow work. Never a gate, never touches epic state.",,,,,,false,,
31
32
  SDLC Workflow,yad-connect-docs,Connect Docs Target,DX,"Setup/maintenance: connect a docs/Pages publishing target so the interactive-docs steps can deploy the generated site (not just commit its source). Auto-detects the platform from .sdlc/product.json (github->github-pages, gitlab->gitlab-pages, null->build-only), resolves the Vite base path, and records the target in .sdlc/docs.json (local-user auth, no stored tokens). Degrades to build-only when gh/glab is absent. Idempotent and refreshable; one connection per project. Not a gated state — never touches epic state or approvals.",,{action: connect|refresh|list|disconnect} {target: github-pages|gitlab-pages|none} {scope: product|<repo>|dedicated} {base_path: <override>},0-setup,,yad-docs,false,.sdlc/,docs.json
32
33
  SDLC Workflow,yad-docs,Author Docs Site,DS,"Generate the per-epic interactive documentation SPA (animated flow canvas + role-based stakeholder doc pages) from the epic's approved artifacts (epic, architecture, locked contract, ui-design, stories, code-context, test-cases), themed by the connected design system, into epics/EP-<slug>/docs-site/. Copies the vendored React/Vite/Tailwind shell verbatim and generates src/data/*.ts deterministically; drives the yad docs build/deploy CLI to publish to Pages (or build-only). An OUTPUT ENRICHMENT — never a gate; never mutates state.json, approvals, or the contract lock.",,{epic: EP-<slug>} {action: generate|refresh|deploy} {login_gate: true|false},4-automate,yad-review-gate,,false,epics/EP-<slug>/docs-site/,docs-site/ docs-build.json
33
34
  SDLC Workflow,yad-docs-overview,Docs Overview Site,DO,"Generate the project SDLC-overview interactive site (docs/sdlc-site/) — every stage from setup to ship modeled as flow paths, system components, and stakeholder roles — reusing the same vendored shell, themed with yadflow's brand palette. Reads config.yaml + module-help.csv + the overview diagram as the pipeline source. Folds the hand-maintained docs/index.html report into the site as report.html (linked from the nav). Not a gate — a project-level enrichment that regenerates whenever the skill set / pipeline changes.",,{action: generate|deploy},4-automate,,,false,docs/sdlc-site/,sdlc-site/ .docs-build.json
@@ -181,7 +181,7 @@ The engine writes everything this step used to spell out by hand (E42):
181
181
 
182
182
  | The command says | Why | What to do |
183
183
  |---|---|---|
184
- | `<owner> skipped <step>` | a skip is a decision, not an artifact — carrying it would claim a review nobody did | leave that base out of `inherits`, then `yad skip` it on this epic if it does not apply here either |
184
+ | `<owner> skipped <step>` | a skip is a decision, not an artifact — carrying it would claim a review nobody did | leave that base out of `inherits`, then, if it does not apply here either, offer to `yad skip` it on this epic: skipping is the person's decision, so run it only on their yes |
185
185
  | `<owner> deferred <step>` | that work is still owed | leave the base out and author it on this epic, so the owed work follows the thread |
186
186
  | `<owner> has not finished <step>` | nothing approved exists yet | finish it on the owner, or author it here |
187
187
  | `holds no usable contract lock` / `surface no longer matches its lock` | you may skip authoring a contract, never having one | lock (or re-lock) the owner's surface first (`yad-architecture` Step 5) |
@@ -258,7 +258,8 @@ again. Unbound, that command names `yad-architecture` for a contract-surface cha
258
258
 
259
259
  - **Never mutate a locked artifact.** A change is a new threaded epic, not an edit to a shipped one.
260
260
  The one exception is BEFORE Build begins — no story has a Build lane and nothing has shipped: then
261
- reopen the approved step with `yad gate reopen <epic> <step> --reason "<why>"` (#322) instead of
261
+ the person reopens the approved step with `yad gate reopen <epic> <step> --reason "<why>"` (#322; theirs
262
+ to run, E158: give them the command, then confirm with `yad gate status <epic>`) instead of
262
263
  threading a change epic; every gate from that step is approved again.
263
264
  - **A change MUST thread to a real parent.** Validate the parent + thread first; STOP on a broken lineage.
264
265
  - **Inherit by reference, never copy.** `yad epic new --parent` carries inherited steps as `satisfied` with