yadflow 4.6.0 → 4.7.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 (96) hide show
  1. package/CHANGELOG.md +170 -0
  2. package/README.md +4 -1
  3. package/bin/commands.mjs +5 -1
  4. package/bin/yad.mjs +167 -15
  5. package/cli/artifact-status.mjs +88 -20
  6. package/cli/build.mjs +1372 -0
  7. package/cli/checkpoint.mjs +2 -2
  8. package/cli/commit.mjs +1 -0
  9. package/cli/dial.mjs +21 -1
  10. package/cli/docs.mjs +6 -1
  11. package/cli/doctor.mjs +133 -26
  12. package/cli/epic-state.mjs +357 -9
  13. package/cli/errors.mjs +2 -0
  14. package/cli/find-product.mjs +36 -2
  15. package/cli/fold.mjs +9 -5
  16. package/cli/gate-local.mjs +9 -1
  17. package/cli/gate.mjs +364 -22
  18. package/cli/history.mjs +22 -2
  19. package/cli/hook.mjs +3 -1
  20. package/cli/index-command.mjs +2 -2
  21. package/cli/ledger.mjs +60 -0
  22. package/cli/next.mjs +34 -11
  23. package/cli/openpr.mjs +81 -5
  24. package/cli/platform.mjs +21 -0
  25. package/cli/pr-list.mjs +5 -3
  26. package/cli/product-index.mjs +6 -3
  27. package/cli/product-token.mjs +186 -0
  28. package/cli/productcommit.mjs +33 -0
  29. package/cli/recommend.mjs +3 -1
  30. package/cli/repo-publish.mjs +2 -2
  31. package/cli/run-checks.mjs +586 -0
  32. package/cli/ship-drift.mjs +49 -18
  33. package/cli/standup.mjs +1 -1
  34. package/cli/status.mjs +282 -0
  35. package/cli/test-build.mjs +1559 -0
  36. package/cli/test-run-checks.mjs +603 -0
  37. package/cli/test-worktree.mjs +520 -0
  38. package/cli/thread.mjs +4 -0
  39. package/cli/tidy.mjs +2 -2
  40. package/cli/toolbox.mjs +36 -5
  41. package/cli/workspace.mjs +4 -1
  42. package/cli/worktree-record.mjs +53 -0
  43. package/cli/worktree.mjs +379 -0
  44. package/package.json +3 -3
  45. package/skills/sdlc/config.yaml +1 -1
  46. package/skills/sdlc/module-help.csv +1 -1
  47. package/skills/yad-backfill/templates/checks/backfill-check.sh +9 -9
  48. package/skills/yad-change/SKILL.md +3 -0
  49. package/skills/yad-checks/SKILL.md +34 -5
  50. package/skills/yad-checks/references/check-gates.md +69 -10
  51. package/skills/yad-checks/templates/checks/build-test-lint.sh +22 -3
  52. package/skills/yad-checks/templates/checks/commit-message.sh +8 -2
  53. package/skills/yad-checks/templates/checks/contract-check.sh +61 -33
  54. package/skills/yad-checks/templates/checks/epic-open.sh +87 -14
  55. package/skills/yad-checks/templates/checks/ledger-guard.sh +3 -3
  56. package/skills/yad-checks/templates/checks/lineage-check.sh +88 -15
  57. package/skills/yad-checks/templates/checks/member-check.mjs +206 -35
  58. package/skills/yad-checks/templates/checks/package-manager.sh +41 -4
  59. package/skills/yad-checks/templates/checks/product-checkout.sh +161 -13
  60. package/skills/yad-checks/templates/checks/reconcile-debt-check.sh +94 -15
  61. package/skills/yad-checks/templates/checks/risk-map-check.sh +2 -2
  62. package/skills/yad-checks/templates/checks/spec-link.sh +63 -4
  63. package/skills/yad-checks/templates/checks/verified-commits.sh +23 -5
  64. package/skills/yad-checks/templates/github/yad-checks.yml +8 -8
  65. package/skills/yad-checks/templates/gitlab/.gitlab-ci.yml +3 -0
  66. package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml +4 -4
  67. package/skills/yad-checks/templates/gitlab/yad-product-checks.gitlab-ci.yml +16 -3
  68. package/skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml +5 -1
  69. package/skills/yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml +5 -1
  70. package/skills/yad-commit/SKILL.md +4 -2
  71. package/skills/yad-docs/templates/app/package-lock.json +395 -106
  72. package/skills/yad-docs/templates/app/package.json +2 -2
  73. package/skills/yad-engineer-review/SKILL.md +45 -20
  74. package/skills/yad-engineer-review/references/ship-and-record.md +42 -8
  75. package/skills/yad-epic/references/state-schema.md +75 -16
  76. package/skills/yad-implement/SKILL.md +75 -13
  77. package/skills/yad-implement/references/implement-conventions.md +8 -1
  78. package/skills/yad-implement/templates/.gitmessage +3 -0
  79. package/skills/yad-open-pr/SKILL.md +21 -0
  80. package/skills/yad-pr-template/SKILL.md +6 -2
  81. package/skills/yad-pr-template/templates/checks/pr-template.sh +85 -4
  82. package/skills/yad-pr-template/templates/checks/pr-title.sh +1 -1
  83. package/skills/yad-pr-template/templates/github/pull_request_template.md +1 -1
  84. package/skills/yad-pr-template/templates/gitlab/merge_request_templates/Default.md +1 -1
  85. package/skills/yad-product-bridge/SKILL.md +14 -1
  86. package/skills/yad-product-bridge/references/bridge.md +5 -2
  87. package/skills/yad-product-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml +9 -4
  88. package/skills/yad-reconcile/SKILL.md +9 -3
  89. package/skills/yad-review-gate/SKILL.md +4 -0
  90. package/skills/yad-review-gate/references/gating.md +26 -1
  91. package/skills/yad-run/SKILL.md +52 -28
  92. package/skills/yad-run/references/run-loop.md +42 -21
  93. package/skills/yad-spec/SKILL.md +137 -16
  94. package/skills/yad-spec/references/spec-handoff.md +50 -3
  95. package/skills/yad-status/SKILL.md +7 -0
  96. package/skills/yad-stories/references/story-schema.md +1 -1
package/cli/toolbox.mjs CHANGED
@@ -18,7 +18,8 @@
18
18
  //
19
19
  // THREE TIERS:
20
20
  // core offered at setup (E85) — repomix, spec-kit, impeccable
21
- // recommended listed, never pushed — pools of skills and agents a team may choose (Part 7)
21
+ // recommended listed, never pushed — pools of skills and agents a team may choose (Part 7),
22
+ // and other optional tools such as Docker MCP Toolkit (#361)
22
23
  // connector the tools a Product connects for design, testing and learning (`yad-connect-*`); the
23
24
  // same adapters `skills/sdlc/config.yaml` names, with the same fallbacks
24
25
  //
@@ -78,7 +79,8 @@ const VET_REGISTRIES = Object.freeze(['npm', 'pypi']);
78
79
  // (Docker, Homebrew, a VS Code extension) are in its own README, which `source` links. `versions` is null
79
80
  // everywhere: no bound has been tested, and E88 vets licence and source, not a version range. `records`
80
81
  // is the exact line a skill writes when the tool is absent. Each skill in
81
- // `usedBy` quotes `fallback` and `records` word for word in its "When a tool is missing" section (E87):
82
+ // `usedBy` quotes `fallback` and `records` word for word in its "When a tool is missing" section (E87),
83
+ // and `recordsElse`, when set, names the one case that records another line (#348):
82
84
  // change the words here, then rewrite the sections with `skillFallbackSection`.
83
85
  export const TOOLBOX = Object.freeze([
84
86
  // ---- core: offered at setup --------------------------------------------------------------------
@@ -126,6 +128,7 @@ export const TOOLBOX = Object.freeze([
126
128
  versions: null,
127
129
  fallback: "yad-spec writes the same spec files by hand, in Spec Kit's layout",
128
130
  records: 'speckit: not-installed', note: 'A program named specify on PATH also counts; another tool by that name would too.',
131
+ recordsElse: 'a light spec, which never runs Spec Kit and records `speckit: not-used` (#348)',
129
132
  usedBy: ['yad-spec'],
130
133
  },
131
134
  {
@@ -212,6 +215,28 @@ export const TOOLBOX = Object.freeze([
212
215
  records: null, note: 'About 8 contributors: fine as an option, risky as a default.',
213
216
  usedBy: ['yad skill bind'],
214
217
  },
218
+ {
219
+ // Not a pool of skills (#361): a gateway that runs other MCP servers, so no yad skill or command uses
220
+ // it, and `yad skill recommend` never names it as a pool (recommend.mjs: POOLS).
221
+ id: 'docker-mcp', name: 'Docker MCP Toolkit', tier: 'recommended', role: "a gateway that runs MCP servers from Docker's catalogue as containers",
222
+ licence: 'MIT', source: 'https://github.com/docker/mcp-gateway', checked: '2026-10-26',
223
+ vetted: {
224
+ on: '2026-10-26', licenceFrom: 'https://github.com/docker/mcp-gateway/blob/main/LICENSE',
225
+ source: 'https://github.com/docker/mcp-gateway', release: 'v0.44.2',
226
+ packages: [],
227
+ note: 'The gateway and its `docker mcp` CLI plugin are MIT; Docker Desktop, which ships them, is under Docker\'s own terms. v0.44.2 is the newest tag, published as a GitHub pre-release, as every release there is, so GitHub names no latest release.',
228
+ },
229
+ // It comes with Docker Desktop: none of the four install types fits.
230
+ install: [],
231
+ manual: 'https://docs.docker.com/ai/mcp-catalog-and-toolkit/toolkit/',
232
+ // The plugin is not on PATH, so the one server a client connects through is the signal.
233
+ detect: { mcp: ['MCP_DOCKER'] },
234
+ versions: null,
235
+ fallback: 'nothing changes: agents use the MCP servers they already have',
236
+ records: null,
237
+ note: 'The first gateway start pulls every server image and can outlast a client\'s 30-second timeout: warm it once with `docker mcp gateway run --profile <id> --dry-run`. A server\'s secrets (an access token) are set with `docker mcp secret set`, never in yad.',
238
+ usedBy: [],
239
+ },
215
240
 
216
241
  // ---- connectors: what a Product connects (skills/sdlc/config.yaml names the same adapters) -------
217
242
  {
@@ -375,6 +400,8 @@ export function toolProblems(t) {
375
400
  need(typeof t?.fallback !== 'string' || !/[.\s]$/.test(t.fallback), 'fallback ends without a full stop or a space');
376
401
  need(t?.records === null || (typeof t?.records === 'string' && t.records.length > 0), 'records is null or the line a skill writes');
377
402
  need(t?.note === null || (typeof t?.note === 'string' && t.note.length > 0), 'note is null or a sentence');
403
+ need(t?.recordsElse === undefined || (typeof t.recordsElse === 'string' && t.recordsElse.length > 0 && t.records !== null && !/\.$/.test(t.recordsElse)),
404
+ 'recordsElse is absent, or the one other case, with records set and no full stop (the section adds it)');
378
405
  need(t?.manual === null || (typeof t?.manual === 'string' && /^https:\/\//.test(t.manual)), 'manual is null or an https URL');
379
406
  need(isStringList(t?.usedBy), 'usedBy lists the skills or commands that use it');
380
407
  need(t?.tier !== 'connector' || !isStringList(t?.usedBy) || connectorFile(t) !== null, 'a connector names the yad-connect-* skill that connects it');
@@ -729,7 +756,7 @@ export function toolUse(tool, { shipped, connected }) {
729
756
  // tool is installed.
730
757
  // connector used when the Product's design, testing or learning file connects it. The connect skill
731
758
  // writes that file and the step skill follows it, as before E87.
732
- // Recommended tools are bound with `yad skill bind`, so no skill names one.
759
+ // Recommended tools are bound with `yad skill bind`, or, like Docker MCP, used by no skill, so no skill names one.
733
760
  export const SKILL_FALLBACK_HEADING = '## When a tool is missing';
734
761
  // The section's last line. The section is exactly the lines from its heading to this marker, so a
735
762
  // rewrite never has to guess from the Markdown where the section ends (rounds 5 to 9 of the E87 review
@@ -746,6 +773,10 @@ export function connectorFile(tool) {
746
773
  // The skills (folders under skills/, not `yad <command>`s) that use a tool.
747
774
  export const skillsUsing = (tool) => tool.usedBy.filter((u) => !u.startsWith('yad '));
748
775
 
776
+ // The line a skill writes when the tool was not used. `recordsElse` is the one case where the skill chose
777
+ // not to use it and records another line (yad-spec's light spec, #348), so the two never read against each other.
778
+ const recordLine = (t) => ` - Record \`${t.records}\`. It means the tool was not used, whatever the reason${t.recordsElse ? ` — except ${t.recordsElse}` : ''}.`;
779
+
749
780
  export function skillFallbackSection(skill, tools = TOOLBOX) {
750
781
  const mine = tools.filter((t) => t.tier !== 'recommended' && skillsUsing(t).includes(skill));
751
782
  if (!mine.length) return null;
@@ -784,7 +815,7 @@ export function skillFallbackSection(skill, tools = TOOLBOX) {
784
815
  for (const t of core) {
785
816
  lines.push(`- **${t.name}** (\`${t.id}\`). Use it when its entry has \`used: true\` and \`status.state\` is \`installed\` or \`available\`. Otherwise — not found, its plugin turned off in Claude Code, or the team chose not to use it (\`yad toolbox remove ${t.id}\`) — use the fallback.`);
786
817
  lines.push(` - Fallback — ${t.fallback}.`);
787
- if (t.records) lines.push(` - Record \`${t.records}\`. It means the tool was not used, whatever the reason.`);
818
+ if (t.records) lines.push(recordLine(t));
788
819
  }
789
820
  for (const t of connectors) {
790
821
  const file = connectorFile(t);
@@ -794,7 +825,7 @@ export function skillFallbackSection(skill, tools = TOOLBOX) {
794
825
  ? `- **${t.name}** (\`${t.id}\`, a connector). This skill connects it, by writing \`${file}\` as the steps below say. The other skills follow that file, not yad's toolbox answer.`
795
826
  : `- **${t.name}** (\`${t.id}\`, a connector). Used when \`${file}\` connects it. ${connect} writes that file; follow it, not yad's toolbox answer.`);
796
827
  lines.push(` - Fallback — ${t.fallback}.`);
797
- if (t.records) lines.push(` - Record \`${t.records}\`. It means the tool was not used, whatever the reason.`);
828
+ if (t.records) lines.push(recordLine(t));
798
829
  }
799
830
  lines.push('', SKILL_FALLBACK_END);
800
831
  return lines.join('\n');
package/cli/workspace.mjs CHANGED
@@ -36,6 +36,7 @@ import { moduleActions, gitHookActions } from './plan.mjs';
36
36
  import { writeWorkspaceFile, WORKSPACE_FILE } from './find-product.mjs';
37
37
  import { offerToolbox } from './toolbox.mjs';
38
38
  import { runMemberAdd } from './members.mjs';
39
+ import { linkedGitDir } from './worktree-record.mjs';
39
40
 
40
41
  // E80: the file that lets yad find the Product from inside the repos it registers. Written by all three.
41
42
  function noteWorkspaceFile(product) {
@@ -415,7 +416,9 @@ export async function runInit(cwd, opts = {}) {
415
416
  ok(`created ${productName}/ (git, branch main)`);
416
417
  } else info(`Product folder: ${productName}/`);
417
418
 
418
- const repos = children.filter((n) => n !== productName && exists(path.join(cwd, n, '.git')));
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)));
419
422
  const found = repos.filter(validFolderName);
420
423
  const odd = repos.filter((n) => !validFolderName(n));
421
424
  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`);
@@ -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,6 +1,6 @@
1
1
  {
2
2
  "name": "yadflow",
3
- "version": "4.6.0",
3
+ "version": "4.7.0",
4
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.",
5
5
  "type": "module",
6
6
  "author": "AbdelRahman Nasr",
@@ -46,10 +46,10 @@
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-fuzz.js",
50
50
  "test:e2e": "bash test/e2e/run.sh",
51
51
  "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",
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",
53
53
  "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
54
  "prepublishOnly": "npm test"
55
55
  },
@@ -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)
@@ -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