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
@@ -0,0 +1,53 @@
1
+ // The record that marks a git worktree as one yad made for an epic (issue #115).
2
+ //
3
+ // `yad worktree add` writes `yad-worktree.json` into the worktree's OWN git folder
4
+ // (`<repo>/.git/worktrees/<name>/`), so the record is never tracked, never shared with another worktree,
5
+ // and goes away with `git worktree remove`. A folder's name alone is never trusted: only a record whose
6
+ // common git folder is the expected repo's says "this is that repo's worktree for that epic".
7
+ //
8
+ // Reads files only and runs no git, like the Product lookup (cli/find-product.mjs) that uses it.
9
+ import fs from 'node:fs';
10
+ import path from 'node:path';
11
+ import { isPlainObject } from './lib.mjs';
12
+
13
+ export const WORKTREE_RECORD = 'yad-worktree.json';
14
+ const EPIC_RE = /^EP-[a-z0-9-]+$/;
15
+ const real = (p) => { try { return fs.realpathSync.native(p); } catch { return null; } };
16
+ const fold = (p) => (process.platform === 'win32' ? p.toLowerCase() : p);
17
+ export const sameDir = (a, b) => { const [x, y] = [a && real(a), b && real(b)]; return !!x && !!y && fold(x) === fold(y); };
18
+
19
+ // A linked worktree's own git folder, from the `gitdir:` line of its `.git` FILE. Null for a main checkout
20
+ // (`.git` is a folder), for no checkout, or for a file that does not point at a `worktrees/<name>` folder
21
+ // (a submodule's `.git` file points into `modules/`).
22
+ export function linkedGitDir(top) {
23
+ let text;
24
+ try {
25
+ if (!fs.lstatSync(path.join(top, '.git')).isFile()) return null;
26
+ text = fs.readFileSync(path.join(top, '.git'), 'utf8');
27
+ } catch { return null; }
28
+ const m = text.match(/^gitdir:\s*(.+?)\s*$/m);
29
+ if (!m) return null;
30
+ const dir = path.resolve(top, m[1]);
31
+ return path.basename(path.dirname(dir)) === 'worktrees' ? dir : null;
32
+ }
33
+
34
+ // The common git folder a linked worktree shares with its main checkout (`<main>/.git`).
35
+ export function commonDirOf(gitDir) {
36
+ try { return path.resolve(gitDir, fs.readFileSync(path.join(gitDir, 'commondir'), 'utf8').trim()); } catch { return null; }
37
+ }
38
+
39
+ // → { epic, repo, base, created, by, gitDir, commonDir, main } for a worktree yad made, else null.
40
+ // `repo` is null for the Product's worktree, or the registered repo's name. `main` is the main checkout
41
+ // (the folder holding the common `.git`).
42
+ export function worktreeAt(top) {
43
+ if (!top) return null;
44
+ const gitDir = linkedGitDir(top);
45
+ if (!gitDir) return null;
46
+ let rec;
47
+ try { rec = JSON.parse(fs.readFileSync(path.join(gitDir, WORKTREE_RECORD), 'utf8')); } catch { return null; }
48
+ if (!isPlainObject(rec) || typeof rec.epic !== 'string' || !EPIC_RE.test(rec.epic)) return null;
49
+ if (!(rec.repo === null || (typeof rec.repo === 'string' && rec.repo))) return null;
50
+ const commonDir = commonDirOf(gitDir);
51
+ if (!commonDir || path.basename(commonDir) !== '.git') return null;
52
+ return { ...rec, gitDir, commonDir, main: path.dirname(commonDir) };
53
+ }
@@ -0,0 +1,379 @@
1
+ // `yad worktree add|list|remove <epic>` (issue #115): one git worktree per epic, so AI agents working
2
+ // different epics at the same time each have their own folder and HEAD, and cannot change each other's
3
+ // files. The user's decisions (2026-10-25):
4
+ // - the worktree sits BESIDE the checkout it is made from: `<workspace>/<product>--EP-x/` and
5
+ // `<workspace>/<repo>--EP-x/`, so the `../<repo>` paths in repos.json and the workspace file still work;
6
+ // - it starts DETACHED at origin/<default>; the step skills make their usual branches inside it, so the
7
+ // Product stays trunk-based (E133);
8
+ // - the Product and the code repos both; a code repo's ignored node_modules are linked, not reinstalled;
9
+ // - `remove` refuses while the worktree holds work (changes, untracked files, commits on no remote, a
10
+ // lock, an operation half done, or the person standing in it), with no override: the fix is printed,
11
+ // and plain `git worktree remove --force` stays the person's own choice.
12
+ //
13
+ // A worktree is yad's when its own git folder holds the record (cli/worktree-record.mjs). The rules are
14
+ // the PURE planners below (`worktreePath`, `planAdd`, `planRemove`); the commands read git, call them,
15
+ // and act.
16
+ import fs from 'node:fs';
17
+ import path from 'node:path';
18
+ import { spawnSync } from 'node:child_process';
19
+ import { ok, info, warn, hand, run, readJSON, writeJSON, isPlainObject, forTerminal } from './lib.mjs';
20
+ import { err } from './errors.mjs';
21
+ import { epicRoot, readFrontmatter, isValidEpicId } from './epic-state.mjs';
22
+ import { PROJECT_FILES, productConfigPath } from './manifest.mjs';
23
+ import { resolveDefaultBranch } from './productcommit.mjs';
24
+ import { WORKTREE_RECORD, worktreeAt, sameDir, linkedGitDir, commonDirOf } from './worktree-record.mjs';
25
+
26
+ const CODE = 'YAD-STATE-010';
27
+ const git = (cwd, ...args) => run('git', args, { cwd });
28
+ // Untrimmed: `run` trims, which eats the leading space of a porcelain entry (` M file`).
29
+ const gitRawResult = (cwd, ...args) => {
30
+ const r = spawnSync('git', args, { cwd, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, env: { ...process.env, GIT_OPTIONAL_LOCKS: '0' } });
31
+ return { ok: r.status === 0, stdout: String(r.stdout || '') };
32
+ };
33
+ const gitRaw = (cwd, ...args) => gitRawResult(cwd, ...args).stdout;
34
+ // Files yad itself writes into a checkout as local working state: named apart when they keep a worktree
35
+ // from being removed, so a finished epic does not look dirty for a reason nobody can see.
36
+ export const YAD_LOCAL_FILES = ['.specify/feature.json', '.gitmessage'];
37
+ const BUSY = ['MERGE_HEAD', 'CHERRY_PICK_HEAD', 'REVERT_HEAD', 'BISECT_LOG', 'rebase-merge', 'rebase-apply'];
38
+
39
+ // PURE: where a checkout's worktree for an epic goes — beside it, named after it.
40
+ export const worktreePath = (main, epic) => path.join(path.dirname(main), `${path.basename(main)}--${epic}`);
41
+
42
+ // PURE: what `add` does for one target, from the facts the command read.
43
+ // facts: { main, epic, repo, hasOrigin, pathTaken, existing ({ path, missing } of this epic's yad
44
+ // worktree, or null), mainIsLinked (the checkout is itself a linked worktree), nested (a code
45
+ // repo kept inside the Product's folder) }
46
+ // → { path, skip (already there: a re-run goes on with the rest), refuse: null | { message, hint } }
47
+ export function planAdd({ main, epic, repo, hasOrigin, pathTaken, existing, mainIsLinked, nested = false }) {
48
+ const where = worktreePath(main, epic);
49
+ const name = repo ?? 'the Product';
50
+ const no = (message, hint) => ({ path: where, skip: false, refuse: { message, hint } });
51
+ if (mainIsLinked) return no(`${name}'s registered folder is itself a worktree`, 'register the main checkout, then run this again');
52
+ // Its worktree would sit inside the Product's own checkout, and could not find the Product or its repos.
53
+ if (nested) return no(`${name} is kept inside the Product's folder, and a worktree is only made for a repo beside it`, 'keep the repo beside the Product (`../<repo>` in repos.json) to give it worktrees');
54
+ if (existing?.missing) return no(`${epic}'s worktree for ${name} is gone (${existing.path}), but git still lists it`, 'run `git worktree prune` in the main checkout, then run this again');
55
+ if (existing) return { path: existing.path, skip: true, refuse: null };
56
+ if (pathTaken) return no(`${where} is already there`, 'move it away (a worktree yad did not record: `git worktree remove` it), then run this again');
57
+ if (!hasOrigin) return no(`${name} has no origin remote, so a worktree's work could not reach the default branch`, 'add the remote (`git remote add origin <url>`), then run this again');
58
+ return { path: where, skip: false, refuse: null };
59
+ }
60
+
61
+ // PURE: why `remove` must not remove one worktree; [] means it may.
62
+ // facts: { path, missing, inside, locked, busy, changes: [paths], unpushed: n }
63
+ export function planRemove({ path: where, missing, inside, locked, busy, changes = [], unpushed = 0, readable = true, product = false }) {
64
+ const why = [];
65
+ if (missing) return [{ reason: `${where} is gone, but git still lists it`, fix: 'run `git worktree prune` in the main checkout' }];
66
+ if (inside) why.push({ reason: 'you are inside it', fix: `cd out of ${where} first` });
67
+ if (!readable) why.push({ reason: 'git could not read its status', fix: `check \`git -C ${where} status\`` });
68
+ if (locked) why.push({ reason: `it is locked${locked === true ? '' : ` (${locked})`}`, fix: `git worktree unlock ${where}, once whoever locked it is done` });
69
+ if (busy) why.push({ reason: `a ${busy} is half done in it`, fix: `finish or abort it in ${where}` });
70
+ const own = changes.filter((f) => YAD_LOCAL_FILES.includes(f));
71
+ const others = changes.filter((f) => !YAD_LOCAL_FILES.includes(f));
72
+ if (others.length) {
73
+ why.push({ reason: `${others.length} uncommitted or untracked file(s): ${others.slice(0, 5).join(', ')}${others.length > 5 ? ', …' : ''}`, fix: `commit and push them, or \`git -C ${where} stash -u\`` });
74
+ }
75
+ if (own.length) why.push({ reason: `yad's own working file(s) are there: ${own.join(', ')}`, fix: `they are local state, safe to delete: ${own.map((f) => `rm ${path.join(where, f)}`).join('; ')}` });
76
+ if (unpushed === null) why.push({ reason: 'git could not count its commits that are on no remote', fix: `check \`git -C ${where} log --not --remotes\`` });
77
+ else if (unpushed) why.push({ reason: `${unpushed} commit(s) are on no remote`, fix: product ? `yad's own commits: \`yad checkpoint --push\` there; a step's: push its branch (\`git -C ${where} push origin HEAD:<branch>\`)` : `push them (\`git -C ${where} push origin HEAD:<branch>\`), or \`yad capture\`` });
78
+ return why;
79
+ }
80
+
81
+ // ---- reading ---------------------------------------------------------------------------------------
82
+
83
+ function productMain(root) {
84
+ const rec = worktreeAt(root);
85
+ return rec && rec.repo === null && fs.existsSync(productConfigPath(rec.main)) ? rec.main : root;
86
+ }
87
+
88
+ // The checkouts an epic's worktrees can be made from: the Product, and every registered code repo.
89
+ // → [{ repo: null|name, main, defaultBranch, missing, nested }]
90
+ function targetsOf(productRoot) {
91
+ const main = productMain(productRoot);
92
+ const config = readJSON(productConfigPath(main), null) || {};
93
+ const out = [{ repo: null, main, defaultBranch: resolveDefaultBranch((...a) => git(main, ...a), config) }];
94
+ const reg = readJSON(path.join(main, PROJECT_FILES.reposRegistry), { repos: [] });
95
+ for (const r of Array.isArray(reg?.repos) ? reg.repos : []) {
96
+ if (!isPlainObject(r) || typeof r.name !== 'string' || typeof r.path !== 'string') continue;
97
+ const at = path.resolve(main, r.path);
98
+ if (sameDir(at, main)) continue; // the Product's own entry (a monorepo): its worktree is the Product's
99
+ const named = typeof r.default_branch === 'string' && r.default_branch ? r.default_branch : null;
100
+ const nested = within(at, main) && !sameDir(at, main); // on disk, as the disk spells it
101
+ out.push({ repo: r.name, main: at, defaultBranch: named, missing: !fs.existsSync(path.join(at, '.git')), nested });
102
+ }
103
+ return out;
104
+ }
105
+
106
+ // Every yad worktree of one checkout, read from its git folder (so one whose folder is gone still shows).
107
+ export function yadWorktrees(main) {
108
+ const common = path.join(main, '.git');
109
+ const dir = path.join(common, 'worktrees');
110
+ let names;
111
+ try { names = fs.readdirSync(dir); } catch { return []; }
112
+ const out = [];
113
+ for (const name of names) {
114
+ const gitDir = path.join(dir, name);
115
+ const rec = readJSON(path.join(gitDir, WORKTREE_RECORD), null);
116
+ if (!isPlainObject(rec) || typeof rec.epic !== 'string' || !isValidEpicId(rec.epic)) continue;
117
+ let where;
118
+ try { where = path.dirname(path.resolve(gitDir, fs.readFileSync(path.join(gitDir, 'gitdir'), 'utf8').trim())); } catch { continue; }
119
+ let locked = false;
120
+ try { locked = fs.readFileSync(path.join(gitDir, 'locked'), 'utf8').trim() || true; } catch { /* not locked */ }
121
+ out.push({ ...rec, gitDir, path: where, missing: !fs.existsSync(path.join(where, '.git')), locked });
122
+ }
123
+ return out;
124
+ }
125
+
126
+ function stateOf(w, { ignored: wantIgnored = false } = {}) {
127
+ if (w.missing) return { branch: null, changes: [], ignored: [], unpushed: 0, readable: true };
128
+ const head = git(w.path, 'rev-parse', '--abbrev-ref', 'HEAD');
129
+ // As capture reads it: no rename pairs to unpick, and no index refresh in a tree an agent may be using.
130
+ const status = gitRawResult(w.path, 'status', '--porcelain=v1', '-z', '--untracked-files=all', ...(wantIgnored ? ['--ignored'] : []), '--no-renames');
131
+ const links = new Set(Array.isArray(w.links) ? w.links : []);
132
+ const changes = [];
133
+ const ignored = [];
134
+ for (const e of status.stdout.split('\0')) {
135
+ if (e.length < 4) continue;
136
+ const file = e.slice(3);
137
+ const bare = file.replace(/\/$/, '');
138
+ if (links.has(bare) && isLinkTo(path.join(w.path, bare))) continue; // yad's own node_modules link
139
+ (e.startsWith('!!') ? ignored : changes).push(file);
140
+ }
141
+ const count = git(w.path, 'rev-list', '--count', 'HEAD', '--not', '--remotes');
142
+ const unpushed = count.ok && /^\d+$/.test(count.stdout) ? Number(count.stdout) : null; // unknown is not 0
143
+ const busy = BUSY.find((f) => fs.existsSync(path.join(w.gitDir, f))) || null;
144
+ return { branch: head.ok && head.stdout !== 'HEAD' ? head.stdout : null, changes, ignored, unpushed, busy, readable: status.ok };
145
+ }
146
+ const isLinkTo = (p) => { try { return fs.lstatSync(p).isSymbolicLink(); } catch { return false; } };
147
+ // Is `dir` the folder `top`, or inside it — compared on disk, as the disk spells it (find-product's rule).
148
+ function within(dir, top) {
149
+ const real = (p) => { try { return fs.realpathSync.native(p); } catch { return null; } };
150
+ const fold = (p) => (process.platform === 'win32' ? p.toLowerCase() : p);
151
+ const [d, t] = [real(dir), real(top)];
152
+ return !!d && !!t && (fold(d) === fold(t) || fold(d).startsWith(fold(t) + path.sep));
153
+ }
154
+
155
+ // The node_modules folders of the main checkout that git ignores, at the repo root and beside each tracked
156
+ // package.json — linked into the worktree where it has none. Relative paths, POSIX form.
157
+ export function nodeModulesLinks(main) {
158
+ const listed = gitRaw(main, 'ls-files', '-z', '--', 'package.json', '*/package.json');
159
+ const dirs = new Set(['.']);
160
+ for (const f of listed.split('\0')) if (f) dirs.add(path.posix.dirname(f));
161
+ const out = [];
162
+ for (const d of [...dirs].sort()) {
163
+ const rel = d === '.' ? 'node_modules' : `${d}/node_modules`;
164
+ const src = path.join(main, rel);
165
+ let st;
166
+ try { st = fs.statSync(src); } catch { continue; }
167
+ if (!st.isDirectory()) continue;
168
+ if (!git(main, 'check-ignore', '-q', '--', rel).ok) continue; // tracked or not ignored: not ours to link
169
+ out.push(rel);
170
+ }
171
+ return out;
172
+ }
173
+
174
+ function epicRepos(main, epic) {
175
+ const fm = readFrontmatter(path.join(epicRoot(main, epic), 'epic.md'));
176
+ return Array.isArray(fm.repos) ? fm.repos : [];
177
+ }
178
+
179
+ function pickTargets(productRoot, epic, { repo = null, all = false }) {
180
+ if (!isValidEpicId(epic)) throw err(CODE, `${forTerminal(epic)} is not an epic id`, 'an epic id looks like EP-checkout');
181
+ const targets = targetsOf(productRoot);
182
+ const product = targets[0];
183
+ if (!fs.existsSync(path.join(epicRoot(product.main, epic), '.sdlc', 'state.json'))) throw err(CODE, `no epic ${epic} on the Product`, '`yad next` lists the epics');
184
+ if (repo && repo !== true) {
185
+ const t = targets.find((x) => x.repo === repo);
186
+ if (!t) throw err(CODE, `${forTerminal(repo)} is not a registered repo`, '`yad repo list` shows them');
187
+ return [t];
188
+ }
189
+ if (!all) return [product];
190
+ const wanted = epicRepos(product.main, epic);
191
+ return [product, ...targets.filter((t) => t.repo && wanted.includes(t.repo))];
192
+ }
193
+
194
+ // ---- the commands ----------------------------------------------------------------------------------
195
+
196
+ export async function runWorktreeAdd(productRoot, { epic, repo = null, all = false, dryRun = false, today = null } = {}) {
197
+ const targets = pickTargets(productRoot, epic, { repo, all });
198
+ const plans = [];
199
+ // Every target is checked — and fetched — before any worktree is made, so a refusal makes nothing.
200
+ for (const t of targets) {
201
+ const name = t.repo ?? 'the Product';
202
+ if (t.missing) throw err(CODE, `${t.repo} is not cloned here (${t.main})`, `\`yad repo clone ${t.repo}\` fetches it`);
203
+ const mine = yadWorktrees(t.main).find((w) => w.epic === epic && (w.repo ?? null) === t.repo);
204
+ const where = worktreePath(t.main, epic);
205
+ const plan = planAdd({
206
+ main: t.main, epic, repo: t.repo, nested: !!t.nested, mainIsLinked: !!linkedGitDir(t.main),
207
+ hasOrigin: git(t.main, 'remote', 'get-url', 'origin').ok, pathTaken: fs.existsSync(where),
208
+ existing: mine ? { path: mine.path, missing: mine.missing } : null,
209
+ });
210
+ if (plan.refuse) throw err(CODE, plan.refuse.message, plan.refuse.hint);
211
+ const branch = t.defaultBranch || resolveDefaultBranch((...a) => git(t.main, ...a), {});
212
+ plans.push({ ...t, name, path: plan.path, skip: plan.skip, branch, links: t.repo && !plan.skip ? nodeModulesLinks(t.main) : [] });
213
+ }
214
+ if (dryRun) {
215
+ for (const p of plans) info(p.skip ? `${p.name}: ${p.path} is already there` : `would add ${p.path} for ${p.name}, detached at origin/${p.branch}${p.links.length ? `, linking ${p.links.join(', ')}` : ''}`);
216
+ return { epic, dryRun: true, worktrees: plans.map((p) => ({ repo: p.repo, path: p.path, base: p.branch, links: p.links, added: false, existing: p.skip })) };
217
+ }
218
+ for (const p of plans.filter((x) => !x.skip)) {
219
+ if (!git(p.main, 'fetch', '--quiet', 'origin', `+refs/heads/${p.branch}:refs/remotes/origin/${p.branch}`).ok) {
220
+ throw err(CODE, `could not fetch ${p.branch} for ${p.name}`, `check the network and your login, and that ${p.branch} is its default branch — nothing was made`);
221
+ }
222
+ }
223
+ const by = git(plans[0].main, 'config', 'user.name').stdout || null;
224
+ const done = [];
225
+ const made = [];
226
+ try {
227
+ for (const p of plans) {
228
+ if (p.skip) {
229
+ info(`${p.name}: ${p.path} is already there`);
230
+ done.push({ repo: p.repo, path: p.path, base: p.branch, links: [], added: false, existing: true });
231
+ continue;
232
+ }
233
+ const added = git(p.main, 'worktree', 'add', '--detach', p.path, `origin/${p.branch}`);
234
+ // git keeps a worktree whose post-checkout hook failed, and still fails: that one is taken back too.
235
+ if (!added.ok && sameDir(commonDirOf(linkedGitDir(p.path) || ''), path.join(p.main, '.git'))) made.push(p);
236
+ if (!added.ok) throw err(CODE, `git could not add ${p.path}: ${added.stderr || added.stdout}`, 'fix what git says, then run this again — the worktrees this run made were taken back');
237
+ made.push(p);
238
+ const linked = linkNodeModules(p);
239
+ writeJSON(path.join(linkedGitDir(p.path), WORKTREE_RECORD), { epic, repo: p.repo, base: p.branch, created: today, by, links: linked });
240
+ done.push({ repo: p.repo, path: p.path, base: p.branch, links: linked, added: true, existing: false });
241
+ }
242
+ } catch (e) {
243
+ // Take back what this run made, so a re-run starts clean: each is fresh, holding only checked-out files.
244
+ // Only the links yad made (`p.linked`, filled as each is made): a planned path can hold a symlink git
245
+ // tracks at origin/<default>. Every planned path's exclude pair, though — only yad's marked pairs go.
246
+ for (const p of made.reverse()) {
247
+ for (const rel of p.linked || []) {
248
+ const at = path.join(p.path, rel);
249
+ try { if (isLinkTo(at)) fs.unlinkSync(at); } catch (u) { warn(`could not unlink ${at}: ${u.message}`); }
250
+ }
251
+ if (git(p.main, 'worktree', 'remove', p.path).ok) dropExcludeLines(p.main, p.links);
252
+ else warn(`could not take back ${p.path} — remove it with \`git worktree remove ${p.path}\``);
253
+ }
254
+ throw e;
255
+ }
256
+ for (const p of made) {
257
+ ok(`${p.name}: ${p.path} (detached at origin/${p.branch})`);
258
+ if (p.linked.length) warn(`${p.name}: ${p.linked.join(', ')} ${p.linked.length > 1 ? 'are links' : 'is a link'} to the main checkout's — do not \`npm install\` in the worktree, or delete the link first`);
259
+ if (p.repo && (fs.existsSync(path.join(p.main, '.husky')) || git(p.main, 'config', 'core.hooksPath').stdout)) {
260
+ info(`${p.name}: its git hooks run in the worktree too — a hook that rewrites files adds them to your commits`);
261
+ }
262
+ }
263
+ if (made.length) hand(`open each agent's session IN its worktree folder (the capture hook watches the folder the session started in), then make the step's usual branch there`);
264
+ return { epic, dryRun: false, worktrees: done };
265
+ }
266
+
267
+ // Link each planned node_modules into the new worktree. A `node_modules/` ignore line matches folders only,
268
+ // and git sees a link as a file — so a link it would not ignore is excluded in the repo's own
269
+ // `info/exclude` (local, never committed), or taken back: it must never be staged by a `git add -A`.
270
+ // `p.linked` holds each link the moment it is made, so a rollback takes back exactly yad's own. Never throws.
271
+ function linkNodeModules(p) {
272
+ const linked = (p.linked = []);
273
+ for (const rel of p.links) {
274
+ const dst = path.join(p.path, rel);
275
+ if (fs.existsSync(dst)) continue;
276
+ try { fs.symlinkSync(path.join(p.main, rel), dst, process.platform === 'win32' ? 'junction' : 'dir'); } catch (e) { warn(`could not link ${rel}: ${e.message}`); continue; }
277
+ linked.push(rel);
278
+ if (!git(p.path, 'check-ignore', '-q', '--', rel).ok) {
279
+ const file = excludeFile(p.path);
280
+ try {
281
+ fs.mkdirSync(path.dirname(file), { recursive: true });
282
+ const had = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
283
+ if (!had.split(/\r?\n/).includes(`/${rel}`)) fs.appendFileSync(file, `${had && !had.endsWith('\n') ? '\n' : ''}${EXCLUDE_MARK}\n/${rel}\n`);
284
+ } catch { /* checked below */ }
285
+ if (!git(p.path, 'check-ignore', '-q', '--', rel).ok) {
286
+ try { fs.unlinkSync(dst); } catch (e) { warn(`${p.name}: could not take back the link ${dst}: ${e.message} — delete it before any \`git add -A\``); continue; }
287
+ linked.pop();
288
+ warn(`${p.name}: ${rel} was not linked — git would not ignore the link, so a \`git add -A\` would commit it`);
289
+ }
290
+ }
291
+ }
292
+ return linked;
293
+ }
294
+
295
+ // `info/exclude` is a common-dir file: the main checkout and every worktree of the repo share it.
296
+ const EXCLUDE_MARK = '# yad worktree (#115): the node_modules link';
297
+ const excludeFile = (dir) => path.resolve(dir, git(dir, 'rev-parse', '--git-path', 'info/exclude').stdout || '.git/info/exclude');
298
+ // After a worktree is gone: drop yad's own pair (the mark, then `/<rel>`) for each link no other yad
299
+ // worktree of the repo still has — another epic's link must stay unstageable. Only a pair under yad's mark
300
+ // goes; a line the person wrote stays.
301
+ export function dropExcludeLines(main, rels) {
302
+ const kept = new Set(yadWorktrees(main).flatMap((w) => (Array.isArray(w.links) ? w.links : [])));
303
+ const gone = new Set(rels.filter((rel) => !kept.has(rel)).map((rel) => `/${rel}`));
304
+ if (!gone.size) return;
305
+ const file = excludeFile(main);
306
+ let lines;
307
+ try { lines = fs.readFileSync(file, 'utf8').split('\n'); } catch { return; }
308
+ const out = [];
309
+ for (let i = 0; i < lines.length; i++) {
310
+ if (lines[i].replace(/\r$/, '') === EXCLUDE_MARK && gone.has((lines[i + 1] ?? '').replace(/\r$/, ''))) { i++; continue; }
311
+ out.push(lines[i]);
312
+ }
313
+ if (out.length === lines.length) return;
314
+ try { fs.writeFileSync(file, out.join('\n')); } catch (e) { warn(`could not tidy ${file}: ${e.message} — yad's lines there are harmless`); }
315
+ }
316
+
317
+ export async function runWorktreeList(productRoot, { epic = null } = {}) {
318
+ const rows = [];
319
+ for (const t of targetsOf(productRoot)) {
320
+ if (t.missing) continue;
321
+ for (const w of yadWorktrees(t.main)) {
322
+ if (epic && w.epic !== epic) continue;
323
+ const s = stateOf(w);
324
+ rows.push({ epic: w.epic, repo: w.repo ?? null, path: w.path, branch: s.branch, changes: s.changes.length, unpushed: s.unpushed, locked: w.locked !== false, missing: w.missing });
325
+ }
326
+ }
327
+ if (!rows.length) info(epic ? `no yad worktrees for ${epic}` : 'no yad worktrees');
328
+ for (const r of rows) {
329
+ const bits = [r.branch ? `on ${r.branch}` : 'detached'];
330
+ if (r.missing) bits.push('folder gone');
331
+ if (r.changes) bits.push(`${r.changes} changed`);
332
+ if (r.unpushed) bits.push(`${r.unpushed} unpushed`);
333
+ if (r.locked) bits.push('locked');
334
+ info(`${r.epic} ${r.repo ?? 'Product'} ${r.path} (${bits.join(', ')})`);
335
+ }
336
+ return { worktrees: rows };
337
+ }
338
+
339
+ export async function runWorktreeRemove(productRoot, { epic, repo = null, all = false, cwd = process.cwd() } = {}) {
340
+ // --all: every checkout's worktree for the epic, also one of a repo the epic no longer names.
341
+ const picked = pickTargets(productRoot, epic, { repo, all });
342
+ const targets = all ? targetsOf(productRoot) : picked;
343
+ const found = [];
344
+ for (const t of targets) {
345
+ if (t.missing) continue;
346
+ const w = yadWorktrees(t.main).find((x) => x.epic === epic && (x.repo ?? null) === t.repo);
347
+ if (w) found.push({ t, w });
348
+ }
349
+ if (!found.length) throw err(CODE, `no yad worktree for ${epic}${repo && repo !== true ? ` in ${repo}` : ''}`, '`yad worktree list` shows them');
350
+ // Every one is checked before any is removed: with --all, one refusal removes nothing.
351
+ const refused = [];
352
+ for (const f of found) {
353
+ const s = stateOf(f.w, { ignored: true });
354
+ const inside = !f.w.missing && within(cwd, f.w.path);
355
+ const why = planRemove({ path: f.w.path, missing: f.w.missing, inside, locked: f.w.locked, busy: s.busy, changes: s.changes, unpushed: s.unpushed, readable: s.readable, product: f.t.repo === null });
356
+ if (why.length) refused.push({ repo: f.t.repo, path: f.w.path, why });
357
+ f.ignored = s.ignored;
358
+ }
359
+ if (refused.length) {
360
+ for (const r of refused) for (const y of r.why) warn(`${r.repo ?? 'Product'}: ${r.path} — ${y.reason}; ${y.fix}`);
361
+ throw err(CODE, `${epic}'s worktree${found.length > 1 ? 's were' : ' was'} not removed: ${refused.length} still hold${refused.length === 1 ? 's' : ''} work`, 'fix what is listed above, then run this again — nothing was removed');
362
+ }
363
+ const removed = [];
364
+ for (const f of found) {
365
+ // Files git ignores (an .env, build output) go with the folder, as `git worktree remove` does: said first.
366
+ if (f.ignored?.length) warn(`${f.t.repo ?? 'Product'}: removed with it, as git ignores them: ${f.ignored.slice(0, 8).join(', ')}${f.ignored.length > 8 ? ', …' : ''}`);
367
+ const links = (Array.isArray(f.w.links) ? f.w.links : []).filter((rel) => isLinkTo(path.join(f.w.path, rel)));
368
+ for (const rel of links) fs.unlinkSync(path.join(f.w.path, rel)); // the link only — never what it points at
369
+ const r = git(f.t.main, 'worktree', 'remove', f.w.path);
370
+ if (!r.ok) {
371
+ for (const rel of links) { try { fs.symlinkSync(path.join(f.t.main, rel), path.join(f.w.path, rel), process.platform === 'win32' ? 'junction' : 'dir'); } catch { /* said below */ } }
372
+ throw err(CODE, `git could not remove ${f.w.path}: ${r.stderr || r.stdout}`, `fix what git says, then run this again${removed.length ? ` (already removed: ${removed.map((x) => x.path).join(', ')})` : ''}`);
373
+ }
374
+ dropExcludeLines(f.t.main, Array.isArray(f.w.links) ? f.w.links : []); // also a link the person deleted
375
+ ok(`removed ${f.w.path}`);
376
+ removed.push({ repo: f.t.repo, path: f.w.path });
377
+ }
378
+ return { epic, removed };
379
+ }
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "yadflow",
3
- "version": "4.6.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-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-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:
@@ -219,7 +219,7 @@ build:
219
219
  # unfolded ship, e.g. a `yad checkpoint --retro-ship` backfill or any ship on an `in-build` story.
220
220
  build_log: "epics/EP-<slug>/.sdlc/build-log.json" # folded ships
221
221
  build_log_dir: "epics/EP-<slug>/.sdlc/build-log/" # one <story>-<task>-<repo>.json shard per ship
222
- story_build_states: [in-build, shipped] # in-build = some tasks shipped; shipped = all tasks in tasks.md shipped
222
+ story_build_states: [in-build, shipped] # in-build = some tasks shipped; shipped = all tasks in tasks.md (or a light spec's tasks block) shipped
223
223
  # Backfill (yad-backfill) — specs for already-built features in an existing repo.
224
224
  backfill:
225
225
  tool: repomix # the one true CLI subprocess: `npx repomix@1.18.1` (Phase 0 / RESEARCH-NOTES §3)
@@ -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
@@ -15,7 +15,7 @@ SDLC Workflow,yad-connect-design,Connect Design Tool,CD,"Setup/maintenance: conn
15
15
  SDLC Workflow,yad-connect-testing,Connect Testing Tool,CT,"Setup/maintenance: connect a testing tool (Playwright-first, pluggable) to the Product so the test-cases step can implement the actual automation tests in it, alongside test-cases.md. Records the tool + project/suite references in .sdlc/testing.json (local-user / MCP-session auth, no stored tokens), detecting whether a testing-tool MCP is available and degrading to artifacts-only when absent. Idempotent and refreshable; one connection per project. Not a gated state — never touches epic state or approvals.",,{action: connect|refresh|list|disconnect} {tool: playwright|cypress|pytest|none} {project_url: <project/config reference>} {suites: {<repo>}},0-setup,,yad-test-cases,false,.sdlc/,testing.json
16
16
  SDLC Workflow,yad-connect-learning,Connect Learning Tool,CL,"Setup/maintenance: connect a learning/tutoring tool (DeepTutor-first, pluggable) so the cross-cutting learning layer can tutor any team member, at any SDLC stage, in the context of what is being built. Records the tool + an optional grounded knowledge base in .sdlc/learning.json (local-user auth, no stored tokens), detecting whether the DeepTutor CLI is on PATH (a subprocess like Repomix, not an MCP) and degrading to harness-native tutoring when absent. Idempotent and refreshable; one connection per project. Not a gated state — never touches epic state or approvals.",,{action: connect|refresh|list|disconnect} {tool: deeptutor|none} {kb: <name>} {ground: true|false},0-setup,,yad-learn,false,.sdlc/,learning.json
17
17
  SDLC Workflow,yad-learn,Learn (Tutor),LN,"Cross-cutting learning layer: at ANY SDLC stage a team member can ask to learn a concept and be tutored in the context of what the team is building. Routes to the connected learning tool (.sdlc/learning.json, DeepTutor-first) grounded in the project knowledge base, or degrades to harness-native tutoring (the harness model reading the artifacts). Renders a tutorial artifact and appends to a per-member learning ledger kept LOCAL-ONLY (gitignored, never committed/pushed to the Product or any code repo) so it stays a private, personal skills log (yad-status rolls up the local records). Purely opt-in — never blocks a gate, never touches epic state, approvals, or the contract lock.",,{concept: <idea>} {context: <focus>} {epic: EP-<slug>} {stage: <sdlc stage>} {member: <who>} {mode: explain|deep|quiz} {action: learn|list|complete},anytime,,,false,epics/EP-<slug>/,learning-records.json learning/<member>--<concept>.md
18
- SDLC Workflow,yad-spec,Author Spec,SP,"Build Step A: for one ready-for-build story and one of its repos, run the heavy Spec Kit ceremony once (specify→clarify→plan→analyze→checklist→tasks) inside that code repo, writing specs/<story-id>/ in Spec Kit's layout (drives /speckit.* when installed, else hand-authors and records speckit: not-installed). References the locked contract; never re-invents the surface. Writes link.md back to the story. Never auto-advances.",,{epic: EP-<slug>} {story: EP-<slug>-S0N} {repo: <one of story.repos>},3-build,yad-review-gate,,false,demo-repos/<repo>/specs/<story-id>/,spec.md research.md data-model.md contracts/ plan.md tasks.md link.md
18
+ SDLC Workflow,yad-spec,Author Spec,SP,"Build Step A: for one ready-for-build story and one of its repos, run the heavy Spec Kit ceremony once (specify→clarify→plan→analyze→checklist→tasks) inside that code repo, writing specs/<story-id>/ in Spec Kit's layout (drives /speckit.* when installed, else hand-authors and records speckit: not-installed; a light spec for a small story with no contract surface is one spec.md, confirmed by a human, #348). References the locked contract; never re-invents the surface. Writes link.md back to the story. Never auto-advances.",,{epic: EP-<slug>} {story: EP-<slug>-S0N} {repo: <one of story.repos>},3-build,yad-review-gate,,false,demo-repos/<repo>/specs/<story-id>/,spec.md research.md data-model.md contracts/ plan.md tasks.md link.md
19
19
  SDLC Workflow,yad-implement,Implement Task,IM,"Build Step B: with the dev lens, implement ONE atomic task from a story's tasks.md as a small diff (<=3 files) on its own branch feat/<story>-<task>-<slug> in the code repo. Diff stays inside the task's declared files (flag and STOP if it grows beyond them). Commit ends with a Task: <story>-<task> trailer; add Contract-Change: yes only when the locked contract surface is touched (routes back to the architecture gate). Never auto-advances.",,{epic: EP-<slug>} {story: EP-<slug>-S0N} {repo: <one of story.repos>} {task: T0N},3-build,yad-spec,,false,demo-repos/<repo>/,branch+commit per atomic task
20
20
  SDLC Workflow,yad-checks,Check Gates,CK,"Build Step C: wire and run the production-safety CI gates on a code repo (and Product) — spec-link (every change links a real story/spec via its Task trailer), contract-check (a contract-surface change without Contract-Change + an updated re-locked contract FAILS and routes back to the architecture gate), build/test/lint, verified-commits (every commit carries a platform-Verified signature), and the pattern gates commit-message / pr-title / pr-template (profile-aware code|product). CI-agnostic bash invoked by GitHub Actions and GitLab CI. Blocking in CI; the human still owns the merge. Never auto-advances.",,{repo: <one of an epic's repos | product>} {action: wire|run} {base: target branch},3-build,yad-implement,,false,demo-repos/<repo>/,checks/*.sh .github/workflows/yad-checks.yml .gitlab/ci/yad-checks.yml
21
21
  SDLC Workflow,yad-pr-template,PR/MR Template,PT,"Build Step D: detect a code repo's platform and commit the matching PR/MR template (.github/pull_request_template.md or .gitlab/merge_request_templates/Default.md) with an Impact & Risk block. A high risk level (or a touched contract surface) raises the approver count — the same count yad-review-gate prints. Ships the routing helper risk-route.sh plus the pattern-gate scripts pr-title.sh and pr-template.sh (used by yad-checks). Never auto-advances.",,{repo: <one of an epic's repos | product>} {action: wire|route} {body: PR description file},3-build,yad-checks,,false,demo-repos/<repo>/,.github/pull_request_template.md .gitlab/merge_request_templates/Default.md checks/risk-route.sh checks/pr-title.sh checks/pr-template.sh
@@ -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
@@ -24,7 +24,7 @@ product_config() {
24
24
  if [ -n "${SDLC_PRODUCT_CONFIG:-}" ]; then printf '%s' "$SDLC_PRODUCT_CONFIG"; return 0; fi
25
25
  if [ -n "${SDLC_HUB_CONFIG:-}" ]; then printf '%s' "$SDLC_HUB_CONFIG"; return 0; fi
26
26
  if [ -f .sdlc/product.json ] && [ -f .sdlc/hub.json ] && ! cmp -s .sdlc/product.json .sdlc/hub.json; then
27
- echo "FAIL [product-settings]: .sdlc/product.json and .sdlc/hub.json say different things — they are one file under two names until v5. Run \`yad migrate\` in the Product to choose the copy to keep, and commit both." >&2
27
+ echo "FAIL [product-settings]: .sdlc/product.json and .sdlc/hub.json say different things — they are one file under two names until v5. In the Product, run \`yad migrate --apply --keep product\` (or \`--keep hub\`) to choose the copy to keep, then commit both files." >&2
28
28
  return 1
29
29
  fi
30
30
  if [ -f .sdlc/product.json ]; then printf '%s' .sdlc/product.json; else printf '%s' .sdlc/hub.json; fi
@@ -61,7 +61,7 @@ resolve_base() {
61
61
  BASE="${1:-${SDLC_BASE:-$(resolve_base)}}"
62
62
  [ -n "${1:-}" ] || [ -n "${SDLC_BASE:-}" ] || echo "note [backfill]: no base given — diffing against '${BASE}'."
63
63
  if ! git rev-parse --verify --quiet "${BASE}^{commit}" >/dev/null; then
64
- echo "FAIL [backfill]: base ref '${BASE}' not found — fetch full history / check the base branch."
64
+ echo "FAIL [backfill]: base ref '${BASE}' not found — check the code out with full history (GitHub: actions/checkout with fetch-depth: 0; GitLab: GIT_DEPTH: \"0\"), and give a base that names a fetched branch (the first argument, or SDLC_BASE)."
65
65
  exit 1
66
66
  fi
67
67
  # What this branch changes is what MERGING it into BASE would change (#363 reviews 1, 3 and 4). A diff
@@ -76,7 +76,7 @@ fi
76
76
  # closed. No merge base at all (a shallow clone, unrelated history) fails closed too.
77
77
  _mbs="$(git merge-base --all "$BASE" HEAD 2>/dev/null)" || _mbs=""
78
78
  if [ -z "$_mbs" ]; then
79
- echo "FAIL [backfill]: '${BASE}' and HEAD share no history — fetch full history (a shallow clone has no merge base) or check the base branch."
79
+ echo "FAIL [backfill]: '${BASE}' and HEAD share no history — a shallow clone has no merge base: check the code out with full history (GitHub: actions/checkout with fetch-depth: 0; GitLab: GIT_DEPTH: \"0\"), or give the branch this change targets as the base."
80
80
  exit 1
81
81
  fi
82
82
  _mb_count="$(printf '%s\n' "$_mbs" | wc -l | tr -d ' ')"
@@ -92,7 +92,7 @@ elif [ "$_mt" = 1 ]; then
92
92
  echo "FAIL [backfill]: this branch does not merge cleanly into ${BASE}, so what it changes there cannot be read. Merge ${BASE} into the branch, resolve the conflicts, then push again."
93
93
  exit 1
94
94
  elif [ "$_mt" != 129 ]; then
95
- echo "FAIL [backfill]: git could not build the merge of this branch into ${BASE} (git merge-tree exit ${_mt}) — fetch the full history of both, then run again."
95
+ echo "FAIL [backfill]: git could not build the merge of this branch into ${BASE} (git merge-tree exit ${_mt}) — check the code out again, fresh and with full history (GitHub: actions/checkout with fetch-depth: 0; GitLab: GIT_DEPTH: \"0\"), then run again."
96
96
  exit 1
97
97
  elif [ "$_mb_count" != 1 ]; then
98
98
  echo "FAIL [backfill]: '${BASE}' and HEAD have ${_mb_count} merge bases, and this git (older than 2.38) cannot build the merge into ${BASE}. Merge ${BASE} into the branch, then push again."
@@ -103,8 +103,8 @@ else
103
103
  # the rename into the merge unseen (review 4). Rename detection itself has limits the real merge does
104
104
  # not share (review 5: `diff.renameLimit`), so it is not used: a path the base REMOVED — deleted or
105
105
  # moved away — that the branch MODIFIES fails closed. Both deleting it is a clean merge, and passes.
106
- _gone="$(git diff --no-renames --diff-filter=D --name-status -z "$_mbs" "$BASE" | tr '\n\0' '?\n' | awk 'NR % 2 == 0')" || { echo "FAIL [backfill]: git could not list what ${BASE} removed since the branch split off."; exit 1; }
107
- _mine="$(git diff --no-renames --name-status -z "$_mbs" HEAD | tr '\n\0' '?\n' | awk 'NR % 2 == 1 { s = $0; next } s == "M" || s == "T"')" || { echo "FAIL [backfill]: git could not list what this branch changes."; exit 1; }
106
+ _gone="$(git diff --no-renames --diff-filter=D --name-status -z "$_mbs" "$BASE" | tr '\n\0' '?\n' | awk 'NR % 2 == 0')" || { echo "FAIL [backfill]: git could not list what '${BASE}' removed since the branch split off — check the code out again, fresh and with full history (GitHub: actions/checkout with fetch-depth: 0; GitLab: GIT_DEPTH: \"0\"), then run again. Git 2.38 or newer on the runner builds the merge instead and skips this step."; exit 1; }
107
+ _mine="$(git diff --no-renames --name-status -z "$_mbs" HEAD | tr '\n\0' '?\n' | awk 'NR % 2 == 1 { s = $0; next } s == "M" || s == "T"')" || { echo "FAIL [backfill]: git could not list what this branch changes since it split off from '${BASE}' — check the code out again, fresh and with full history (GitHub: actions/checkout with fetch-depth: 0; GitLab: GIT_DEPTH: \"0\"), then run again. Git 2.38 or newer on the runner builds the merge instead and skips this step."; exit 1; }
108
108
  # A here-string, not a pipe: `grep -q` stops at the first match, and a large list written into a pipe
109
109
  # it has left would end in SIGPIPE — read as "no match" under pipefail (review 5).
110
110
  if [ -n "$_gone" ] && [ -n "$_mine" ] && grep -Fxq -f <(printf '%s\n' "$_mine") <<<"$_gone"; then
@@ -140,7 +140,7 @@ FOLD='function fold(x) { x = tolower(x)
140
140
  # `tr '\n\0' '?\n'`: one record per line, and a newline inside a path becomes `?` — split on newlines
141
141
  # alone, a file named `notes<newline>100644 blob 0<TAB>src/Billing/y` added a record nobody made (review 2).
142
142
  base_tree="$(git ls-tree -r -z --full-tree "$BASE" | tr '\n\0' '?\n')" || {
143
- echo "FAIL [backfill]: git could not read the tree of '${BASE}' — the gate cannot tell which features are being backfilled."
143
+ echo "FAIL [backfill]: git could not read the tree of '${BASE}', so the gate cannot tell which features are being backfilled — check the code out again, fresh and with full history (GitHub: actions/checkout with fetch-depth: 0; GitLab: GIT_DEPTH: \"0\"), then run again."
144
144
  exit 1
145
145
  }
146
146
  # One line each: `S <oid> <path>` a spec to read, `U - <path>` a link where a spec goes, `A - <path>` a
@@ -173,7 +173,7 @@ bf="$(printf '%s\n' "$specs" | sed -n 's/^[SU] [^ ]* //p' | awk "$FOLD"'{ split(
173
173
  # empty.
174
174
  tagged() { printf '%s\n' "$2" | awk -v t="$1" 'length($0) { print t "\t" $0 }'; }
175
175
  head_tree="$(git ls-tree -r -z --full-tree HEAD | tr '\n\0' '?\n')" || {
176
- echo "FAIL [backfill]: git could not read the tree at HEAD — the gate cannot check src/ for links."
176
+ echo "FAIL [backfill]: git could not read the tree at HEAD, so the gate cannot check src/ for links — check the code out again, fresh and with full history (GitHub: actions/checkout with fetch-depth: 0; GitLab: GIT_DEPTH: \"0\"), then run again."
177
177
  exit 1
178
178
  }
179
179
  if [ -n "$bf" ] || [ -n "$blind" ]; then
@@ -218,7 +218,7 @@ fi
218
218
  changed="$(git diff --no-renames --raw -z "$DIFF_FROM" "$DIFF_TO" | while IFS= read -r -d '' h && IFS= read -r -d '' p; do
219
219
  printf '%s\t%s\n' "$h" "${p//$'\n'/?}"
220
220
  done)" || {
221
- echo "FAIL [backfill]: git could not list what this branch changes in '${BASE}'."
221
+ echo "FAIL [backfill]: git could not list what this branch changes in '${BASE}' — check the code out again, fresh and with full history (GitHub: actions/checkout with fetch-depth: 0; GitLab: GIT_DEPTH: \"0\"), then run again."
222
222
  exit 1
223
223
  }
224
224
  # The spellings of each src/<feature> folder, on the base and at HEAD: `<top>/<feature>`, once each.