yadflow 4.9.0 → 4.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (155) hide show
  1. package/CHANGELOG.md +184 -0
  2. package/README.md +15 -5
  3. package/bin/commands.mjs +11 -1
  4. package/bin/yad.mjs +203 -14
  5. package/cli/agent-guard-worker.mjs +13 -0
  6. package/cli/agent-guard.mjs +1797 -73
  7. package/cli/agent-rules.mjs +64 -5
  8. package/cli/argv-flags.mjs +2 -2
  9. package/cli/brain/vendor/LICENSE-graphology-library.txt +21 -0
  10. package/cli/brain/vendor/LICENSE-graphology.txt +21 -0
  11. package/cli/brain/vendor/LICENSE-sigma.txt +12 -0
  12. package/cli/brain/vendor/graphology-library.min.js +2 -0
  13. package/cli/brain/vendor/graphology.umd.min.js +2 -0
  14. package/cli/brain/vendor/sigma.min.js +1369 -0
  15. package/cli/brain/view/app.js +382 -0
  16. package/cli/brain/view/index.html +63 -0
  17. package/cli/brain/view/live.css +228 -0
  18. package/cli/brain/view/live.html +110 -0
  19. package/cli/brain/view/live.js +884 -0
  20. package/cli/brain/view/style.css +141 -0
  21. package/cli/brain-about.mjs +206 -0
  22. package/cli/brain-activity.mjs +285 -0
  23. package/cli/brain-skills.mjs +118 -0
  24. package/cli/brain-vendor.mjs +71 -0
  25. package/cli/brain-view.mjs +344 -0
  26. package/cli/brain.mjs +810 -0
  27. package/cli/ci-check.mjs +48 -4
  28. package/cli/codeowners-command.mjs +72 -6
  29. package/cli/commit.mjs +17 -3
  30. package/cli/docs.mjs +2 -0
  31. package/cli/doctor.mjs +151 -25
  32. package/cli/epic-state.mjs +186 -4
  33. package/cli/epic.mjs +26 -10
  34. package/cli/errors.mjs +2 -1
  35. package/cli/find-product.mjs +69 -15
  36. package/cli/fold.mjs +31 -6
  37. package/cli/foundation-publish.mjs +256 -0
  38. package/cli/gate.mjs +29 -3
  39. package/cli/git-read.mjs +38 -0
  40. package/cli/guard-stream.mjs +409 -0
  41. package/cli/guide.mjs +3 -1
  42. package/cli/hook.mjs +102 -9
  43. package/cli/issue-links.mjs +61 -0
  44. package/cli/issues-act.mjs +371 -0
  45. package/cli/issues-write.mjs +441 -0
  46. package/cli/issues.mjs +513 -0
  47. package/cli/lib.mjs +37 -2
  48. package/cli/lifecycle.mjs +7 -0
  49. package/cli/local-page.mjs +138 -0
  50. package/cli/machine.mjs +1 -1
  51. package/cli/manifest.mjs +59 -3
  52. package/cli/map/view/app.js +712 -0
  53. package/cli/map/view/index.html +50 -0
  54. package/cli/map/view/style.css +142 -0
  55. package/cli/map-view.mjs +186 -0
  56. package/cli/map.mjs +637 -0
  57. package/cli/members.mjs +9 -15
  58. package/cli/next.mjs +1 -1
  59. package/cli/openpr.mjs +26 -6
  60. package/cli/plan.mjs +127 -0
  61. package/cli/platform.mjs +159 -4
  62. package/cli/product-index.mjs +1 -1
  63. package/cli/protection.mjs +53 -3
  64. package/cli/reconcile.mjs +9 -3
  65. package/cli/report.mjs +9 -3
  66. package/cli/reports-dir.mjs +391 -0
  67. package/cli/reports.mjs +65 -0
  68. package/cli/run-checks.mjs +15 -4
  69. package/cli/scan.mjs +314 -0
  70. package/cli/setup.mjs +42 -8
  71. package/cli/standup.mjs +120 -78
  72. package/cli/status.mjs +6 -5
  73. package/cli/story-frames.mjs +17 -6
  74. package/cli/test-agents-file.mjs +985 -12
  75. package/cli/test-brain-activity.mjs +753 -0
  76. package/cli/test-brain-view.mjs +381 -0
  77. package/cli/test-brain.mjs +795 -0
  78. package/cli/test-build.mjs +25 -0
  79. package/cli/test-ci-check.mjs +469 -10
  80. package/cli/test-guide.mjs +218 -0
  81. package/cli/test-machine.mjs +59 -0
  82. package/cli/test-map.mjs +615 -0
  83. package/cli/test-node.mjs +15 -0
  84. package/cli/test-reports.mjs +382 -0
  85. package/cli/test-run-checks.mjs +21 -0
  86. package/cli/test-setup-agent.mjs +14 -0
  87. package/cli/test-story-frames.mjs +74 -4
  88. package/cli/test-worktree.mjs +24 -3
  89. package/cli/toolbox-connect.mjs +259 -0
  90. package/cli/toolbox.mjs +187 -12
  91. package/cli/update-commit.mjs +101 -9
  92. package/cli/usage.mjs +8 -4
  93. package/package.json +12 -4
  94. package/skills/sdlc/config.yaml +1 -1
  95. package/skills/sdlc/module-help.csv +3 -1
  96. package/skills/yad-analysis/SKILL.md +4 -0
  97. package/skills/yad-architecture/SKILL.md +22 -4
  98. package/skills/yad-backfill/SKILL.md +4 -0
  99. package/skills/yad-change/SKILL.md +7 -1
  100. package/skills/yad-change/references/triage.md +2 -0
  101. package/skills/yad-checks/SKILL.md +15 -7
  102. package/skills/yad-checks/references/check-gates.md +70 -35
  103. package/skills/yad-checks/templates/checks/build-test-lint.sh +7 -0
  104. package/skills/yad-checks/templates/checks/install-deps.sh +6 -0
  105. package/skills/yad-checks/templates/checks/member-check.mjs +3 -2
  106. package/skills/yad-checks/templates/checks/package-manager.sh +42 -0
  107. package/skills/yad-checks/templates/checks/risk-map-check.sh +2 -2
  108. package/skills/yad-checks/templates/checks/verified-commits.sh +3 -3
  109. package/skills/yad-checks/templates/github/yad-checks.yml +358 -69
  110. package/skills/yad-checks/templates/github/yad-pr-text.yml +118 -0
  111. package/skills/yad-checks/templates/github/yad-product-checks.yml +130 -54
  112. package/skills/yad-checks/templates/github/yad-product-pr-text.yml +131 -0
  113. package/skills/yad-checks/templates/github/yad-update-guard.yml +2 -1
  114. package/skills/yad-checks/templates/github/yad-verified-commits.yml +49 -3
  115. package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml +80 -20
  116. package/skills/yad-checks/templates/gitlab/yad-product-checks.gitlab-ci.yml +59 -9
  117. package/skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml +1 -0
  118. package/skills/yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml +49 -1
  119. package/skills/yad-checks/templates/hooks/agent-guard.mjs +44 -10
  120. package/skills/yad-checks/templates/hooks/ledger-guard-cursor.mjs +12 -6
  121. package/skills/yad-checks/templates/hooks/yad-activity.mjs +238 -0
  122. package/skills/yad-commit/SKILL.md +3 -1
  123. package/skills/yad-connect-design/SKILL.md +42 -10
  124. package/skills/yad-connect-design/references/design-context.md +35 -5
  125. package/skills/yad-connect-design/references/design-registry.md +3 -3
  126. package/skills/yad-connect-learning/SKILL.md +12 -2
  127. package/skills/yad-connect-repos/SKILL.md +18 -0
  128. package/skills/yad-connect-testing/SKILL.md +22 -5
  129. package/skills/yad-connect-testing/references/testing-context.md +1 -1
  130. package/skills/yad-discovery/SKILL.md +11 -0
  131. package/skills/yad-discovery/references/foundation-schema.md +11 -0
  132. package/skills/yad-docs/templates/app/package-lock.json +18 -10
  133. package/skills/yad-docs/templates/app/package.json +6 -1
  134. package/skills/yad-epic/SKILL.md +7 -0
  135. package/skills/yad-epic/references/state-schema.md +50 -1
  136. package/skills/yad-guide/SKILL.md +8 -4
  137. package/skills/yad-implement/SKILL.md +117 -4
  138. package/skills/yad-implement/references/implement-conventions.md +2 -1
  139. package/skills/yad-issues/SKILL.md +54 -0
  140. package/skills/yad-learn/SKILL.md +4 -0
  141. package/skills/yad-open-pr/SKILL.md +6 -0
  142. package/skills/yad-pr-template/SKILL.md +2 -1
  143. package/skills/yad-pr-template/templates/checks/pr-template.sh +8 -4
  144. package/skills/yad-pr-template/templates/checks/pr-title.sh +42 -6
  145. package/skills/yad-product-bridge/references/bridge.md +28 -0
  146. package/skills/yad-product-bridge/templates/github/yad-gate-sync.yml +25 -11
  147. package/skills/yad-product-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml +38 -14
  148. package/skills/yad-run/SKILL.md +5 -0
  149. package/skills/yad-scan/SKILL.md +51 -0
  150. package/skills/yad-spec/SKILL.md +32 -2
  151. package/skills/yad-stories/SKILL.md +22 -4
  152. package/skills/yad-stories/references/story-schema.md +1 -1
  153. package/skills/yad-test-cases/SKILL.md +18 -2
  154. package/skills/yad-ui/SKILL.md +43 -8
  155. package/skills/yad-checks/templates/gitlab/.gitlab-ci.yml +0 -49
package/cli/epic.mjs CHANGED
@@ -40,6 +40,7 @@ import {
40
40
  } from './epic-state.mjs';
41
41
  import { epicFiles, isVerifiedLedger, productConfigPath } from './manifest.mjs';
42
42
  import { refreshIndexAfterWrite } from './product-index.mjs';
43
+ import { foundationChanged, foundationReviewAgain, publishedItems } from './foundation-publish.mjs';
43
44
 
44
45
  // `foo`, `EP-foo` and `epics/EP-foo` all name the same epic. Accepting only one spelling would make the
45
46
  // command reject the id the user just read out of `yad next`.
@@ -51,11 +52,15 @@ export function epicIdFrom(slug) {
51
52
 
52
53
  // `type` defaults to null rather than `feature` so an explicit `--type` is distinguishable from no
53
54
  // flag at all — which is what lets an existing `epic.md` supply the answer without overriding the user.
54
- export async function runEpicNew(root, { slug, type = null, profile = null, stub = false, parent = null, inherits = null, today, json = false } = {}) {
55
+ export async function runEpicNew(root, { slug, type = null, profile = null, stub = false, parent = null, inherits = null, today, json = false, returnResult = false } = {}) {
56
+ // `returnResult` (E170, with json): a caller that seeds as one part of its work gets the answer back, and
57
+ // it alone speaks, so stdout stays one JSON document.
58
+ const answer = returnResult ? (payload) => payload : emitJSON;
55
59
  const bail = (message, hint) => {
56
- if (json) emitJSON({ ok: false, error: message, hint });
57
- else { fail(message); if (hint) hand(hint); }
58
60
  process.exitCode = 1;
61
+ if (json) return answer({ ok: false, error: message, hint });
62
+ fail(message); if (hint) hand(hint);
63
+ return undefined;
59
64
  };
60
65
 
61
66
  const epic = epicIdFrom(slug);
@@ -169,7 +174,7 @@ export async function runEpicNew(root, { slug, type = null, profile = null, stub
169
174
  if (parent) {
170
175
  return seedThreaded(root, {
171
176
  epic, dir, files, mdPath, fm, type, parent, profile,
172
- inherits: flagInherits ?? declaredInherits ?? [], headerLists: declaredInherits !== null, today, json, bail,
177
+ inherits: flagInherits ?? declaredInherits ?? [], headerLists: declaredInherits !== null, today, json, bail, answer,
173
178
  });
174
179
  }
175
180
  profile = profile || 'classic';
@@ -230,7 +235,7 @@ export async function runEpicNew(root, { slug, type = null, profile = null, stub
230
235
  // `nextSkills` appears only for a bound chain, the same rule `yad next --json` follows — a key that
231
236
  // showed up on every seed would be one more always-null field for every reader to ignore.
232
237
  if (json) {
233
- return emitJSON({
238
+ return answer({
234
239
  ok: true, epic, type, profile, stub, currentStep: state.currentStep,
235
240
  steps: state.steps.map((s) => s.id), next: skill,
236
241
  ...(skills.length > 1 ? { nextSkills: skills } : {}),
@@ -266,7 +271,7 @@ const listOf = (v) => (Array.isArray(v) ? v : String(v ?? '').replace(/^\s*\[|\]
266
271
  // The threaded half of `yad epic new` (E42): a change, defect or hotfix off an epic that exists. The
267
272
  // engine plans the chain from the parent (`planThreadedSeed`) and this writes it — the ledger, one
268
273
  // provenance record per inherited gate, and the pointer-lock when the contract is carried.
269
- function seedThreaded(root, { epic, dir, files, mdPath, fm, type, parent, profile, inherits, headerLists, today, json, bail }) {
274
+ function seedThreaded(root, { epic, dir, files, mdPath, fm, type, parent, profile, inherits, headerLists, today, json, bail, answer }) {
270
275
  const plan = planThreadedSeed(root, { epic, parent, inherits, type, today });
271
276
  if (!plan.ok) return bail(plan.message, plan.hint);
272
277
  // The route is the parent's. A flag naming the same one is harmless; a different one is refused
@@ -319,7 +324,7 @@ function seedThreaded(root, { epic, dir, files, mdPath, fm, type, parent, profil
319
324
  const skills = stepSkills(first.id, bindingsForEpic(loadSkillBindings(root), state));
320
325
  const carried = state.steps.filter((s) => s.inherited);
321
326
  if (json) {
322
- return emitJSON({
327
+ return answer({
323
328
  ok: true, epic, type, profile: plan.profile, stub: false, parent, thread: plan.thread,
324
329
  inherits, inheritedFrom: plan.owners, pointerLock: plan.lock ? plan.lock.ref : null, anchor: plan.anchor,
325
330
  currentStep: state.currentStep, steps: state.steps.map((s) => s.id), next: skills[0] || null,
@@ -484,8 +489,18 @@ export async function runFoundationStatus(root, { json = false } = {}) {
484
489
  } catch { return false; }
485
490
  });
486
491
 
492
+ // E174: whether the Foundation changed after its review, so a reader is told before `publish` refuses.
493
+ let checkFailed = false;
494
+ let foundationLedger = null;
495
+ const changed = productId === FOUNDATION_EPIC && approved ? (() => { try { foundationLedger = loadLedger(dir); return foundationChanged(dir, foundationLedger); } catch { checkFailed = true; return true; } })() : false;
496
+ if (checkFailed) warnings.push('whether the Foundation changed after its review could not be checked — run `yad doctor`');
497
+ else if (changed) warnings.push(`the Foundation changed after its review, so \`yad foundation publish\` refuses until it is reviewed again — ${foundationReviewAgain(root, foundationLedger)}`);
498
+ // E174: the item each row was published as, from the record only. Null when the record cannot be read.
499
+ const items = productId === FOUNDATION_EPIC ? publishedItems(root) : new Map();
500
+ for (const f of features) f.item = items ? (items.get(f.epicId) ?? null) : null;
501
+ if (items === null) warnings.push('foundation/.sdlc/roadmap-items.json cannot be read, so no row shows its item');
487
502
  if (json) {
488
- return emitJSON({ ok: true, epic: productId, roadmap: rel, approved, features, unlisted, ...(warnings.length ? { warnings } : {}) });
503
+ return emitJSON({ ok: true, epic: productId, roadmap: rel, approved, changed, features, unlisted, ...(warnings.length ? { warnings } : {}) });
489
504
  }
490
505
  for (const w of warnings) warn(w);
491
506
  log(`\n ${c.bold(`${productId} roadmap`)} ${c.dim(`${rel} — each status is read from the epic ledgers`)}`);
@@ -497,12 +512,13 @@ export async function runFoundationStatus(root, { json = false } = {}) {
497
512
  const name = `${f.feature || '(no name)'} ${c.dim(f.epicId || '(no id)')}`;
498
513
  if (f.problem) { log(` ${c.yellow('!')} ${name} ${c.yellow(f.problem)}`); continue; }
499
514
  const mark = f.status === 'shipped' ? c.green('✓') : f.status === 'planned' ? c.dim('·') : c.cyan('•');
500
- log(` ${mark} ${name} ${f.status}`);
515
+ log(` ${mark} ${name} ${f.status}${f.item ? c.dim(` #${f.item.number}`) : ''}`);
501
516
  if (f.disagrees) log(` ${c.dim(`the row says "${f.written}" — that column is no longer kept by hand; the ledger's answer is shown`)}`);
502
517
  }
503
518
  if (unlisted.length) {
504
519
  info(`not on the roadmap: ${unlisted.join(', ')} ${c.dim('(feature epics no row proposes — an epic may have been given a different id)')}`);
505
520
  }
506
521
  const next = features.find((f) => f.status === 'planned');
507
- if (next) hand(`next planned feature: ${next.feature || next.epicId} — seed it with the yad-epic skill (proposed id ${next.epicId})`);
522
+ if (next) hand(`next planned feature: ${next.feature || next.epicId} — seed it with the yad-epic skill (proposed id ${next.epicId}${next.item ? `, from item #${next.item.number}` : ''})`);
523
+ if (productId === FOUNDATION_EPIC && approved && !items?.size && features.length && !changed) info('the roadmap is approved: `yad foundation publish` opens one issue / work item per feature in the Product repo');
508
524
  }
package/cli/errors.mjs CHANGED
@@ -27,11 +27,12 @@ export const CODES = {
27
27
  'YAD-STATE-008': 'a file kept under two names (product.json + hub.json, or product-prs.json + hub-prs.json) says different things under each',
28
28
  'YAD-STATE-009': 'a Build record cannot be written in its current state (no lane yet, a step out of order, a PR not merged, a task not shipped)',
29
29
  'YAD-STATE-010': 'an epic worktree cannot be added or removed in its current state (a path taken, no origin, uncommitted or unpushed work, a lock)',
30
+ 'YAD-STATE-011': 'the project brain (.sdlc/brain/graph.json) or a Graphify graph cannot be read, or names a format this yadflow does not read',
30
31
  'YAD-CFG-001': 'the Product settings (product.json, or hub.json on a Product that has only that name) name an unknown platform (expected github, gitlab, or null)',
31
32
  'YAD-CFG-002': 'design.json names an unknown design tool (expected one of config.yaml design.tools, or none)',
32
33
  'YAD-CFG-003': 'testing.json names an unknown testing tool (expected one of config.yaml testing.tools, or none)',
33
34
  'YAD-CFG-004': 'learning.json names an unknown learning tool (expected one of config.yaml learning.tools, or none)',
34
- 'YAD-CFG-005': 'the Product settings (product.json, or hub.json on a Product that has only that name) set a platform but are missing git_url (required to scope auth + open PRs)',
35
+ 'YAD-CFG-005': 'the Product settings (product.json, or hub.json on a Product that has only that name) set a platform but are missing git_url, or name only a host in it with no repo path (required to scope auth + open PRs)',
35
36
  'YAD-CFG-006': 'skills.json binds a step to something that is not a skill name (expected a string, or a non-empty list of strings)',
36
37
  'YAD-CFG-007': 'toolbox.json has a line that does nothing — a tool this yadflow does not ship, a choice other than use or skip, or a custom tool that is incomplete, malformed, listed twice or uses a shipped tool\'s id',
37
38
  'YAD-CLI-001': 'a --json run needed an answer that only a prompt could give',
@@ -11,7 +11,8 @@
11
11
  // - a folder that is a Product (it has `.sdlc/hub.json` or `.sdlc/product.json`) — so any subfolder of
12
12
  // the Product finds it;
13
13
  // - a folder holding `.yad-workspace.json` — its `product` names the Product folder beside the repos.
14
- // It is used ONLY when `start` is inside a repo that Product registers in its `repos.json`. A
14
+ // It is used ONLY when `start` is inside a repo that Product registers in its `repos.json`, or in a git
15
+ // worktree of one (yad's own, #115, or a plain one, #515). A
15
16
  // workspace can be a shared folder (`~/Projects`, holding many teams' repos — setup always allowed
16
17
  // that), and a file there must not send an unrelated repo's `yad epic new` or `yad kill` to this
17
18
  // Product (E80 review 1). Anywhere else in the workspace there is no Product.
@@ -26,7 +27,7 @@ import os from 'node:os';
26
27
  import path from 'node:path';
27
28
  import { exists, readJSON, writeJSON } from './lib.mjs';
28
29
  import { productConfigPath, PROJECT_FILES } from './manifest.mjs';
29
- import { worktreeAt, sameDir } from './worktree-record.mjs';
30
+ import { worktreeAt, sameDir, linkedGitDir, commonDirOf } from './worktree-record.mjs';
30
31
 
31
32
  export const WORKSPACE_FILE = '.yad-workspace.json';
32
33
  export const WORKSPACE_VERSION = 1;
@@ -83,7 +84,11 @@ export function findProduct(start) {
83
84
  for (let d = from; ; d = path.dirname(d)) {
84
85
  if (exists(productConfigPath(d))) {
85
86
  if (d === from) return { root: d, via: 'here' };
86
- const repo = registeredRepoHolding(d, from);
87
+ // A worktree of a registered repo is that repo (#115, #515 review 1), wherever it sits: a repo inside
88
+ // the Product's folder can have one beside it (`product/backend-wt`), past which the walk crossed.
89
+ // No epic routing here, unlike the workspace branch below: `yad worktree add` refuses a repo kept
90
+ // inside the Product's folder, so no epic worktree of one exists to route to.
91
+ const repo = registeredRepoHolding(d, from) ?? (codeWorktreeOf(d, from) || linkedRepoWorktreeOf(d, from))?.meta ?? null;
87
92
  if (crossedRepo && !repo) return null;
88
93
  return { root: d, via: 'above', ...(repo ? { repo } : {}) };
89
94
  }
@@ -103,6 +108,9 @@ export function findProduct(start) {
103
108
  const epicTree = epicProductWorktree(ws.product, wt.epic);
104
109
  return { root: epicTree ?? ws.product, via: 'workspace', workspace: d, repo: wt.meta, ...(epicTree ? { worktree: wt.epic } : {}) };
105
110
  }
111
+ // A plain git worktree of a registered repo (#515): that repo. It has no epic, so the main Product.
112
+ const plain = linkedRepoWorktreeOf(ws.product, from);
113
+ if (plain) return { root: ws.product, via: 'workspace', workspace: d, repo: plain.meta };
106
114
  return { elsewhere: ws.product };
107
115
  }
108
116
  if (fs.existsSync(path.join(d, '.git'))) crossedRepo = true;
@@ -130,19 +138,49 @@ export function registeredRepoHolding(productRoot, dir) {
130
138
  return best;
131
139
  }
132
140
 
141
+ // Is `top` the worktree git knows by `gitDir`? Git keeps a back-link (`<gitDir>/gitdir`, absolute, or
142
+ // relative under `worktree.useRelativePaths`) to the worktree's `.git` file. A `.git` file written by hand
143
+ // that points at another worktree's git folder fails it, and so borrows nothing (#515).
144
+ function backLinked(top, gitDir) {
145
+ let back;
146
+ try { back = fs.readFileSync(path.join(gitDir, 'gitdir'), 'utf8').trim(); } catch { return false; }
147
+ return !!back && sameDir(path.resolve(gitDir, back), path.join(top, '.git'));
148
+ }
149
+
133
150
  // The registered repo whose epic worktree (#115) holds `dir`: yad made it (its record names the repo), and
134
- // its common git folder IS that repo's — a record copied into some other clone maps nothing.
151
+ // its common git folder IS that repo's — a record copied into some other clone maps nothing, and a `.git`
152
+ // file pointing at the worktree from another folder is not it (`backLinked`, #515 review 2).
135
153
  // → { meta, epic, top } or null.
136
154
  export function codeWorktreeOf(productRoot, dir) {
137
155
  const top = gitTopOf(dir);
138
156
  const rec = worktreeAt(top);
139
- if (!rec || typeof rec.repo !== 'string') return null;
157
+ if (!rec || typeof rec.repo !== 'string' || !backLinked(top, rec.gitDir)) return null;
140
158
  const reg = readJSON(path.join(productRoot, PROJECT_FILES.reposRegistry), null);
141
159
  const meta = (Array.isArray(reg?.repos) ? reg.repos : []).find((r) => r?.name === rec.repo && typeof r.path === 'string');
142
160
  if (!meta || !sameDir(rec.main, path.resolve(productRoot, meta.path))) return null;
143
161
  return { meta, epic: rec.epic, top };
144
162
  }
145
163
 
164
+ // The registered repo a plain git worktree belongs to (#515): one made by `git worktree add` or by an agent
165
+ // tool (Claude Code's `.claude/worktrees/<name>`), with no yad record. Its main checkout — the folder holding
166
+ // the common `.git` — must BE the registered repo, not a folder inside it or another clone. And git's own
167
+ // back-link (`<common>/.git/worktrees/<id>/gitdir`) must name this worktree's `.git` file: a `.git` file
168
+ // written by hand could otherwise point at a registered repo's worktree folder and borrow its entry.
169
+ // → { meta, top } with `top` the worktree's own top (worked there, never swapped for the repo's), or null.
170
+ // Never the Product's own entry (`registeredRepoHolding` refuses it).
171
+ export function linkedRepoWorktreeOf(productRoot, dir) {
172
+ if (!productRoot) return null;
173
+ const top = gitTopOf(dir);
174
+ const gitDir = top && linkedGitDir(top);
175
+ if (!gitDir) return null;
176
+ if (!backLinked(top, gitDir)) return null;
177
+ const common = commonDirOf(gitDir);
178
+ if (!common || path.basename(common) !== '.git') return null;
179
+ const main = path.dirname(common);
180
+ const meta = registeredRepoHolding(productRoot, main);
181
+ return meta && sameDir(main, path.resolve(productRoot, meta.path)) ? { meta, top } : null;
182
+ }
183
+
146
184
  // The epic's Product worktree beside the Product, when yad made one; else null.
147
185
  export function epicProductWorktree(productRoot, epic) {
148
186
  const root = path.resolve(productRoot);
@@ -235,21 +273,37 @@ export function toolsFolder(found, from) {
235
273
  return best ?? from;
236
274
  }
237
275
 
238
- // The registry entry for the code repo a code-repo command runs in (E80), with the folder to work in.
239
- // It is the CHECKOUT that must be the registered repo — not merely a folder inside it: a worktree or a
240
- // repo nested in `backend/` is another checkout, on another branch, and must never be swapped for
241
- // backend's own (E80 review 3). → { meta, top } or null. Never the Product's own entry.
242
- export function registryEntryFor(productRoot, dir) {
276
+ // The registered repo whose OWN checkout `dir` is in — never a worktree of it, never a nested repo. For the
277
+ // commands that work on the repo's files from its registered folder (`risk-map`, `codeowners`, `ci check`,
278
+ // which resolve `<Product>/<path>`): from a worktree they would act on the main checkout, on another
279
+ // branch, so they keep covering every repo there (E80 review 3, #515 review 1). → { meta, top } or null.
280
+ export function registeredCheckoutFor(productRoot, dir) {
243
281
  if (!productRoot) return null;
244
282
  const top = gitTopOf(dir);
245
283
  if (!top) return null;
246
284
  const meta = registeredRepoHolding(productRoot, top);
247
- if (!meta) {
248
- // The one worktree that IS the registered repo's: an epic worktree yad made of it (#115).
249
- const wt = codeWorktreeOf(productRoot, dir);
250
- return wt && sameDir(wt.top, top) ? { meta: wt.meta, top } : null;
251
- }
285
+ if (!meta) return null;
252
286
  const at = real(path.resolve(productRoot, meta.path));
253
287
  const topAt = real(top);
254
288
  return at && topAt && fold(at) === fold(topAt) ? { meta, top } : null;
255
289
  }
290
+
291
+ // The registry entry for the code repo a code-repo command runs in (E80), with the folder to work in.
292
+ // It is the CHECKOUT that must be the registered repo — not merely a folder inside it: a repo nested in
293
+ // `backend/` is another repo, and gets nothing. A git worktree of backend is backend on another branch: it
294
+ // gets backend's entry (its name, platform and default branch, #515), and `top` stays the worktree's own,
295
+ // so a command works where it runs and is never swapped for backend's checkout (E80 review 3).
296
+ // → { meta, top } or null. Never the Product's own entry.
297
+ export function registryEntryFor(productRoot, dir) {
298
+ if (!productRoot) return null;
299
+ const top = gitTopOf(dir);
300
+ if (!top) return null;
301
+ const own = registeredCheckoutFor(productRoot, dir);
302
+ if (own) return own;
303
+ // Not the registered checkout itself — a folder inside one, or beside it. Only a worktree of it counts: an
304
+ // epic worktree yad made (#115), or a plain git worktree, wherever it sits (#515), inside the repo
305
+ // (`.claude/worktrees/x`) or beside it. A repo nested inside one is neither, and gets nothing.
306
+ const wt = codeWorktreeOf(productRoot, dir);
307
+ if (wt && sameDir(wt.top, top)) return { meta: wt.meta, top };
308
+ return linkedRepoWorktreeOf(productRoot, dir);
309
+ }
package/cli/fold.mjs CHANGED
@@ -30,7 +30,7 @@ import os from 'node:os';
30
30
  import path from 'node:path';
31
31
  import { ok, info, warn, fail, hand, readJSON } from './lib.mjs';
32
32
  import { productConfigPath, isVerifiedLedger } from './manifest.mjs';
33
- import { STEPS, FOUNDATION_EPIC, FOUNDATION_DIR, DISCOVERY_EPIC, artifactBase, artifactPaths, epicRoot, isValidEpicId } from './epic-state.mjs';
33
+ import { STEPS, FOUNDATION_EPIC, FOUNDATION_DIR, DISCOVERY_EPIC, artifactBase, artifactPaths, epicRoot, isValidEpicId, isDesignJunk, UI_DESIGN_DIR } from './epic-state.mjs';
34
34
  import { capturedEpic, gitIn, isOwnerPath, statusEntries, wipName, wipBranch, runCapture } from './capture.mjs';
35
35
  import { resolveDefaultBranch, preflightGuardReadiness } from './productcommit.mjs';
36
36
 
@@ -53,7 +53,32 @@ export function stepPaths(epic, stepId) {
53
53
  if (!step) return null;
54
54
  return [...artifactPaths(artifactBase(step.artifact)), ...(STEP_EXTRAS[stepId] || [])].map((p) => `${epicRel(epic)}/${p}`);
55
55
  }
56
- const covers = (paths, p) => paths.some((s) => p === s || p.startsWith(`${s}/`));
56
+ // A file the system or an editor drops in the UI design's `design/` folder (`.DS_Store`, `x.fig~`) is not
57
+ // the step's: the fingerprint leaves it out (`isDesignJunk`), so a fold that committed it would put a file
58
+ // in the review that no approval covers. It is left on disk like any other file. So is a nested repository
59
+ // there — git lists an untracked one as a folder (`design/kit/`) and a committed submodule by its folder
60
+ // name (`design/kit`), and `isRepo` (a folder holding `.git`) tells the second: `git add` would record a
61
+ // link to another repository, and the fingerprint skips it.
62
+ const covers = (paths, p, isRepo = null) => paths.some((s) => p === s
63
+ || (p.startsWith(`${s}/`) && !(s.endsWith(`/${UI_DESIGN_DIR}`) && (isDesignJunk(p.slice(s.length + 1)) || p.endsWith('/') || !!isRepo?.(p)))));
64
+ // Is this Product-relative path a nested repository or a submodule — a folder holding `.git`, or a gitlink
65
+ // in the index (a submodule never initialised here has no `.git`)? The index's gitlinks are read once, on
66
+ // the first path that needs them, so many changed design files cost one git call. `GIT_LITERAL_PATHSPECS`
67
+ // is cleared so git reads the `:(glob)` pattern as a pattern.
68
+ export const repoAt = (root, env = process.env) => {
69
+ let gitlinks = null;
70
+ const links = () => {
71
+ if (gitlinks) return gitlinks;
72
+ const rest = Object.fromEntries(Object.entries(env).filter(([k]) => k !== 'GIT_LITERAL_PATHSPECS'));
73
+ const r = gitIn(root, rest, { GIT_OPTIONAL_LOCKS: '0' })(['ls-files', '-s', '-z', '--', `:(glob)**/${UI_DESIGN_DIR}/**`]);
74
+ gitlinks = new Set(r.ok ? r.out.split('\0').filter((e) => e.startsWith('160000 ')).map((e) => e.slice(e.indexOf('\t') + 1)) : []);
75
+ return gitlinks;
76
+ };
77
+ return (p) => {
78
+ const bare = p.replace(/\/$/, '');
79
+ return fs.existsSync(path.join(root, ...bare.split('/'), '.git')) || links().has(bare);
80
+ };
81
+ };
57
82
 
58
83
  // The scope is the epic ID in lowercase (#413): the commit-message gate takes a lowercase scope
59
84
  // (`[a-z0-9._-]`), so `docs(EP-x)` failed every review PR. The exact ID stays in the Yad-Epic trailer.
@@ -73,7 +98,7 @@ export const foldMessage = ({ epic, step, folded }) =>
73
98
  // only while its state.json is off the base ref (#162))
74
99
  // ci — ledger changes left for CI (verified mode, every other case)
75
100
  // other — the epic's other changed artifacts, left on disk
76
- export function sortChanges(entries, { epic, step, verified, seeding = false }) {
101
+ export function sortChanges(entries, { epic, step, verified, seeding = false, isRepo = null }) {
77
102
  const own = stepPaths(epic, step) || [];
78
103
  const dir = `${epicRel(epic)}/`;
79
104
  const out = { step: [], seed: [], ledger: [], ci: [], other: [] };
@@ -83,7 +108,7 @@ export function sortChanges(entries, { epic, step, verified, seeding = false })
83
108
  // `??` is untracked, `A` in the first column is added to the index: both are a file being created.
84
109
  // ` A` is a file marked with `git add -N` (intent to add): new too.
85
110
  const creating = xy === '??' || xy[0] === 'A' || xy === ' A';
86
- if (covers(own, p)) out.step.push(p);
111
+ if (covers(own, p, isRepo)) out.step.push(p);
87
112
  // A step owner file (E47) is never folded: an assignment is not authoring, and a fold that carried one
88
113
  // alone would be a "docs: author <step>" commit with nothing authored. It is committed on its own.
89
114
  else if (isOwnerPath(p)) out.other.push(p);
@@ -108,7 +133,7 @@ export function unfoldedPaths(root, epic, base, env = process.env) {
108
133
  const own = stepPaths(epic, authorStepOf(base)) || [];
109
134
  // A per-story branch (`stories-S01`) reviews that one story: another story's edit is not its business.
110
135
  const story = /^stories-S\d+$/i.test(base) ? base.toLowerCase() : null;
111
- return entries.map((e) => e.path).filter((p) => covers(own, p) && (!story || artifactBase(p).toLowerCase() === story));
136
+ return entries.map((e) => e.path).filter((p) => covers(own, p, repoAt(root, env)) && (!story || artifactBase(p).toLowerCase() === story));
112
137
  }
113
138
 
114
139
  // `yad fold <epic> <step>`. Returns a plain object (E1 turns it into the `--json` answer); a refusal
@@ -170,7 +195,7 @@ export async function runFold(root, { epic, step, env = process.env, capture = r
170
195
  const seededAt = (e) => git(['cat-file', '-e', `HEAD:./${epicRel(e)}/.sdlc/state.json`]).ok;
171
196
  const productLevel = epic === FOUNDATION_EPIC || epic === DISCOVERY_EPIC;
172
197
  const seeding = productLevel ? !seededAt(FOUNDATION_EPIC) && !seededAt(DISCOVERY_EPIC) : !seededAt(epic);
173
- const sorted = sortChanges(entries, { epic, step, verified, seeding });
198
+ const sorted = sortChanges(entries, { epic, step, verified, seeding, isRepo: repoAt(root, env) });
174
199
  // What `git add` can take: a path on disk or in the index. A deletion already staged (`D `, from `git rm`
175
200
  // or the old half of a `git mv`) is in neither, and `git add` would refuse it — but it is in HEAD, so
176
201
  // `commit --only` commits the deletion. A path added and then deleted (`AD`) is in none of the three and
@@ -0,0 +1,256 @@
1
+ // E174 — the approved roadmap becomes work items in the Product repo. After the Foundation review passes,
2
+ // `yad foundation publish` opens one GitHub issue or GitLab work item per roadmap feature: type feature, a
3
+ // priority by phase (the first phase is the MVP: P1, then P2, then P3), the label `epic: EP-x`, and the
4
+ // phase as its milestone. A "parked" phase is a decision not to build yet, so it is left out.
5
+ //
6
+ // The record of what was published is `foundation/.sdlc/roadmap-items.json`. It is outside the Foundation's
7
+ // fingerprint (only the section files count), so publishing never makes the review stale. A lost record does
8
+ // not cause duplicates: each item's body carries `<!-- yad-roadmap: EP-x -->`, and those are read first.
9
+ import fs from 'node:fs';
10
+ import path from 'node:path';
11
+ import { run, forTerminal, readJSON, readJSONStrict, writeJSON, c, log, fail, hand, info, warn, emitJSON } from './lib.mjs';
12
+ import { err } from './errors.mjs';
13
+ import { isVerifiedLedger, productConfigPath, epicFiles } from './manifest.mjs';
14
+ import { acceptedHashes, artifactBase, doneStepUnapproved, epicRoot, isStaleHash, FOUNDATION_EPIC, isValidEpicId, loadLedger, PRODUCT_DONE, PRODUCT_EPICS, reviewAsItStands, roadmapFeatures, soloRereviewCovers } from './epic-state.mjs';
15
+ import { productGit, resolveDefaultBranch } from './productcommit.mjs';
16
+ import { isSolo } from './gate.mjs';
17
+ import { createLabel, labelRules, readLabels } from './issues.mjs';
18
+ import { linkAndWriteBack, readItem, recordRoute } from './issues-write.mjs';
19
+ import { readLinks, itemKey } from './issue-links.mjs';
20
+ import { targetOf } from './issues-act.mjs';
21
+ import { readMilestones, safeTitle } from './scan.mjs';
22
+ import { api } from './protection.mjs';
23
+ import { createMilestone, newItem } from './platform.mjs';
24
+
25
+ const RECORD = path.join('.sdlc', 'roadmap-items.json');
26
+ const MARKER = /<!-- yad-roadmap: (EP-[a-z0-9-]+) -->/g;
27
+ const PAGE = 100;
28
+ // The template's own heading for deferred work, exactly: a phase that merely contains the word ("Car park finder") counts.
29
+ const PARKED = /^(later\s*\/\s*)?parked?$/i;
30
+
31
+ // Whether the Foundation as it stands is not what its review passed. A solo re-review that merged this very
32
+ // content answers first (`rereviews`, written by `yad gate sync`/`gate ci`): it is newer than any approval or
33
+ // close, and a Product that switched to solo after a team review keeps its old, now stale, approvals. Then
34
+ // approvals answer when there are any. With none (a solo Product passes on the merge alone), the fingerprint
35
+ // the step was closed with answers. Neither: no claim.
36
+ export function foundationChanged(dir, ledger) {
37
+ const review = ledger.state?.steps?.find((st) => st.type === 'review+approve');
38
+ if (!review) return false;
39
+ if (Array.isArray(review.rereviews) && review.rereviews.length && soloRereviewCovers(review, acceptedHashes(dir, review.artifact))) return false;
40
+ const approved = (Array.isArray(ledger.approvals) ? ledger.approvals : []).filter((a) => a?.step === review.id && a.status === 'approved');
41
+ // Approvals with no fingerprint make no claim, so the closing fingerprint decides for them too.
42
+ const hashed = approved.filter((a) => a.artifactHash);
43
+ if (hashed.length) return !!doneStepUnapproved(dir, review, hashed);
44
+ const hash = review.closed?.hash;
45
+ return !!hash && isStaleHash(hash, acceptedHashes(dir, review.artifact));
46
+ }
47
+
48
+ // How a changed Foundation gets reviewed again. Not `yad gate reopen`: that refuses the Foundation
49
+ // (reopenStep, "it runs once per product"). Each arm says the step that really clears `foundationChanged`:
50
+ // - no platform: `yad gate approve` records an approval bound to today's content, on a passed step too
51
+ // (gate-local) — the person's command, never the agent's;
52
+ // - a platform: the review as it stands on a fresh PR/MR (#418), the steps `yad next` prints. In team mode
53
+ // its approvals clear it; in solo mode its merge does (`rereviews`), recorded by `yad gate sync` on a
54
+ // local ledger and by CI at the merge on a verified one.
55
+ export function foundationReviewAgain(root, ledger) {
56
+ const review = ledger?.state?.steps?.find((st) => st.type === 'review+approve');
57
+ const artifact = review?.artifact ?? 'foundation/';
58
+ const productConfig = readJSON(productConfigPath(root), null);
59
+ const platform = productConfig?.platform;
60
+ if (platform !== 'github' && platform !== 'gitlab') {
61
+ return `review it again on this machine (your command, not the agent's): \`yad gate approve ${FOUNDATION_EPIC} ${artifact} --by <your name>\``;
62
+ }
63
+ const fresh = reviewAsItStands(FOUNDATION_EPIC, artifact, resolveDefaultBranch(productGit(root), productConfig));
64
+ if (!isSolo(productConfig)) return `${fresh}; once it is approved and merged, its approvals cover the Foundation`;
65
+ return isVerifiedLedger(productConfig)
66
+ ? `${fresh}; merge it yourself (solo mode) — CI records the merge as the new review (CI must run this yadflow release or later; if that run failed, run it again: \`yad gate ci --branch review/${FOUNDATION_EPIC}/${artifactBase(artifact)} --pr <n> --merged\`)`
67
+ : `${fresh}; merge it yourself (solo mode), then \`yad gate sync ${FOUNDATION_EPIC}\` records the merge as the new review`;
68
+ }
69
+
70
+ export const priorityForPhase = (index) => (index === 0 ? 'P1' : index === 1 ? 'P2' : 'P3');
71
+ const recordPath = (root) => path.join(epicRoot(root, FOUNDATION_EPIC), RECORD);
72
+
73
+ const validEntry = (e) => !!e && typeof e === 'object' && !Array.isArray(e) && isValidEpicId(e.epicId) && !!e.host && !!e.repo && Number.isInteger(e.number);
74
+ // Strict, as every read before a write is: a record that cannot be understood is refused, never replaced.
75
+ export function readRecord(root) {
76
+ const p = recordPath(root);
77
+ const doc = readJSONStrict(p, { items: [] });
78
+ if (!doc || typeof doc !== 'object' || !Array.isArray(doc.items) || !doc.items.every(validEntry)) throw err('YAD-STATE-001', `${p} is not a roadmap-items file`, 'fix the file or restore it from git');
79
+ return doc.items;
80
+ }
81
+ const writeRecord = (root, items) => { fs.mkdirSync(path.dirname(recordPath(root)), { recursive: true }); writeJSON(recordPath(root), { items }); };
82
+
83
+ // The rows to publish, with each one's phase, priority and milestone title. The first table row of an id wins.
84
+ export function roadmapRows(text, skipped = [], nearMiss = []) {
85
+ const phases = [];
86
+ const seen = new Set();
87
+ const rows = [];
88
+ for (const r of roadmapFeatures(text)) {
89
+ const phase = (r.phase ?? 'Roadmap').trim();
90
+ if (PARKED.test(phase)) { if (!skipped.includes(phase)) skipped.push(phase); continue; }
91
+ if (/\b(later|parked?)\b/i.test(phase) && !nearMiss.includes(phase)) nearMiss.push(phase);
92
+ if (!isValidEpicId(r.epicId) || PRODUCT_EPICS.includes(r.epicId) || seen.has(r.epicId)) continue;
93
+ seen.add(r.epicId);
94
+ if (!phases.includes(phase)) phases.push(phase);
95
+ rows.push({ epicId: r.epicId, feature: forTerminal(r.feature).replace(/\s+/g, ' ').trim() || r.epicId, phase, priority: priorityForPhase(phases.indexOf(phase)) });
96
+ }
97
+ return rows;
98
+ }
99
+
100
+ // The item already published for one row: open or closed, carrying both the row's `epic: EP-x` label and its body
101
+ // marker. The label matters: a person who can only open issues cannot set one, so a stranger's issue that copies
102
+ // the marker does not claim the row. Asked per row, so a busy repo is never too big to read.
103
+ // `{ found: {number,url} | null }`, or `{ unread: true }`.
104
+ function publishedOn(t, epicId, runner) {
105
+ const gh = t.platform === 'github';
106
+ const label = encodeURIComponent(`epic: ${epicId}`);
107
+ const at = gh ? `repos/${t.repo}/issues?labels=${label}&state=all&per_page=${PAGE}` : `projects/${encodeURIComponent(t.repo)}/issues?labels=${label}&scope=all&per_page=${PAGE}`;
108
+ // An epic's defects and changes may carry its label too, so the pages are followed until the marker turns up.
109
+ for (let page = 1; page <= 10; page++) {
110
+ const res = api(runner, t.cli, t.host, `${at}&page=${page}`);
111
+ if (!res.ok || !Array.isArray(res.body)) return { unread: true };
112
+ for (const it of res.body) {
113
+ if (gh && it?.pull_request) continue;
114
+ const n = gh ? it?.number : it?.iid;
115
+ const marks = [...String((gh ? it?.body : it?.description) ?? '').matchAll(MARKER)].map((m) => m[1]);
116
+ if (Number.isInteger(n) && marks.includes(epicId)) return { found: { number: n, url: (gh ? it?.html_url : it?.web_url) ?? null } };
117
+ }
118
+ if (res.body.length < PAGE) return { found: null };
119
+ }
120
+ return { unread: true };
121
+ }
122
+
123
+ // The phase is the team's heading; `safeTitle` breaks a mention or reference so one publish notifies nobody.
124
+ const bodyFor = (row) => `A feature on the approved roadmap, phase: ${safeTitle(row.phase.replace(/[*_`<>[\]]/g, ''))}. Its proposed epic is \`${row.epicId}\`.\n\nStart the epic with \`yad epic new ${row.epicId} --issue <this item's number>\` to link it here, so this item's status follows the epic. \`yad foundation publish\` also links an epic that already exists.\n\n<!-- yad-roadmap: ${row.epicId} -->`;
125
+ // GitLab allows 255 characters in a title; cut by character, never inside one.
126
+ const titleFor = (feature) => [...feature].slice(0, 255).join('');
127
+
128
+ export async function runFoundationPublish(root, { dryRun = false, json = false, env = process.env, runner = run, now = Date.now() } = {}) {
129
+ const refuse = (message, hint) => {
130
+ process.exitCode = 1;
131
+ if (json) return emitJSON({ ok: false, error: message, hint: hint ?? null });
132
+ fail(message); if (hint) hand(hint);
133
+ return undefined;
134
+ };
135
+ if (!fs.existsSync(productConfigPath(root))) return refuse('not a Product (no .sdlc/product.json here)', 'run it from the Product, or pass --dir');
136
+ const dir = epicRoot(root, FOUNDATION_EPIC);
137
+ if (!fs.existsSync(epicFiles(dir).state)) return refuse('this product has no Foundation', 'run `yad foundation new`, then the yad-discovery skill');
138
+ let ledger;
139
+ try { ledger = loadLedger(dir); } catch { return refuse('the Foundation\'s ledger cannot be read', 'run `yad doctor`'); }
140
+ // Only an approved roadmap: a draft could still lose or rename features.
141
+ if (!PRODUCT_DONE.includes(ledger.state?.currentStep)) return refuse('the Foundation has not passed its review yet, so the roadmap is not final', 'publish it after the review: the backlog should hold only approved features');
142
+ // Approved once is not enough: a roadmap edited since its review holds rows nobody approved.
143
+ let changed;
144
+ try { changed = foundationChanged(dir, ledger); } catch { return refuse('the Foundation\'s review could not be checked', 'run `yad doctor`'); }
145
+ if (changed) return refuse('the Foundation changed after its review, so the review no longer covers the roadmap', `have the Foundation reviewed again, then publish — ${foundationReviewAgain(root, ledger)}`);
146
+ const file = path.join(dir, 'roadmap.md');
147
+ if (!fs.existsSync(file)) return refuse('foundation/roadmap.md does not exist');
148
+ const skipped = [];
149
+ const nearMiss = [];
150
+ const rows = roadmapRows(fs.readFileSync(file, 'utf8'), skipped, nearMiss);
151
+ const record = readRecord(root);
152
+ if (env.YAD_PLATFORM_READ === '0') return refuse('platform reads are turned off (YAD_PLATFORM_READ=0)');
153
+ let where;
154
+ try { where = targetOf(root, null, { env, runner }); } catch (e) { return refuse(e.message, e.hint); }
155
+ const { t, productConfig } = where;
156
+ const rules = labelRules(productConfig);
157
+ const out = { ok: true, dryRun, created: [], recovered: [], alreadyPublished: 0, linked: [], failed: [], notes: [...skipped.map((p) => `the phase "${forTerminal(p)}" is parked, so its rows were left out`), ...nearMiss.map((p) => `the phase "${forTerminal(p)}" is published; only a heading of "Parked" or "Later / parked" is left out`)] };
158
+ // Whether the record file changed (#512 review 2): an item is recorded before its labels are checked, so a row
159
+ // in `failed` may still have been written. Not in `out`: the --json envelope keeps its keys.
160
+ let wroteRecord = false;
161
+ const known = new Map(record.filter((e) => e.host === t.host && e.repo === t.repo).map((e) => [e.epicId, e]));
162
+ const todo = rows.filter((r) => !known.has(r.epicId));
163
+ out.alreadyPublished = rows.length - todo.length;
164
+
165
+ if (todo.length) {
166
+ // A lost or uncommitted record must not mean a second item for the same feature.
167
+ const markers = new Map();
168
+ for (const r of todo) {
169
+ const p = publishedOn(t, r.epicId, runner);
170
+ if (p.unread) return refuse(`the items labelled "epic: ${r.epicId}" could not be read, so nothing was created`, 'run it again; already published features are never created twice');
171
+ if (p.found) markers.set(r.epicId, p.found);
172
+ }
173
+ const fresh = [];
174
+ for (const r of todo) {
175
+ const m = markers.get(r.epicId);
176
+ if (m) { out.recovered.push({ epicId: r.epicId, number: m.number, url: m.url }); if (!dryRun) record.push({ epicId: r.epicId, platform: t.platform, host: t.host, repo: t.repo, number: m.number, url: m.url, publishedAt: new Date(now).toISOString() }); }
177
+ else fresh.push(r);
178
+ }
179
+ if (out.recovered.length && !dryRun) { writeRecord(root, record); wroteRecord = true; }
180
+ const labelsOf = (r) => [rules.type.feature[0], rules.priority[r.priority][0], `epic: ${r.epicId}`];
181
+ if (t.platform === 'gitlab' && fresh.some((r) => labelsOf(r).some((l) => l.includes(',')))) return refuse('a GitLab label name with a comma cannot be sent', 'rename that label in the issues settings of .sdlc/product.json');
182
+ if (dryRun) for (const r of fresh) out.created.push({ epicId: r.epicId, feature: r.feature, phase: r.phase, priority: r.priority, number: null, url: null, wouldCreate: true });
183
+ else if (fresh.length) {
184
+ const have = readLabels(t, runner);
185
+ if (have.ok) for (const name of new Set(fresh.flatMap(labelsOf))) if (!have.names.has(name.toLowerCase())) createLabel(t, name, name.startsWith('epic: ') ? 'c5def5' : '1d76db', runner);
186
+ const milestones = readMilestones(t, runner);
187
+ if (!milestones) out.notes.push('the milestones could not be read, so these items have none');
188
+ const idOf = new Map();
189
+ const milestoneFor = (phase) => {
190
+ if (!milestones) return null;
191
+ if (idOf.has(phase)) return idOf.get(phase);
192
+ let id = milestones.get(phase) ?? null;
193
+ if (id === null) {
194
+ const r = createMilestone(t, phase, { runner });
195
+ try { id = r.ok ? (t.platform === 'github' ? JSON.parse(r.stdout).number : JSON.parse(r.stdout).id) ?? null : null; } catch { id = null; }
196
+ if (id === null) out.notes.push(`the milestone "${forTerminal(phase)}" could not be created`);
197
+ }
198
+ idOf.set(phase, id);
199
+ return id;
200
+ };
201
+ for (const r of fresh) {
202
+ const labels = labelsOf(r);
203
+ const milestone = milestoneFor(r.phase);
204
+ const res = newItem(t, { title: titleFor(r.feature), body: bodyFor(r), labels, milestone }, { runner });
205
+ if (!res.ok) { out.failed.push({ epicId: r.epicId, why: 'the platform refused to create it' }); continue; }
206
+ let b = {};
207
+ try { b = JSON.parse(res.stdout); } catch { /* checked below */ }
208
+ const number = t.platform === 'github' ? b.number : b.iid;
209
+ if (!Number.isInteger(number)) { out.failed.push({ epicId: r.epicId, why: 'the answer named no item number' }); continue; }
210
+ const url = b.html_url ?? b.web_url ?? null;
211
+ record.push({ epicId: r.epicId, platform: t.platform, host: t.host, repo: t.repo, number, url, publishedAt: new Date(now).toISOString() });
212
+ writeRecord(root, record);
213
+ wroteRecord = true;
214
+ const got = (Array.isArray(b.labels) ? b.labels : []).map((l) => String(typeof l === 'string' ? l : l?.name).toLowerCase());
215
+ const missing = labels.filter((l) => !got.includes(l.toLowerCase()));
216
+ const row = { epicId: r.epicId, feature: r.feature, phase: r.phase, priority: r.priority, number, url };
217
+ if (missing.length) out.failed.push({ ...row, why: `created, but the labels ${missing.join(', ')} were not set: add them on #${number}, or a later publish cannot recognise it` });
218
+ else if (milestone !== null && !b.milestone) out.failed.push({ ...row, why: 'created, but the milestone was not set' });
219
+ else out.created.push(row);
220
+ }
221
+ }
222
+ }
223
+
224
+ // A feature whose epic already exists is linked, so its status flows back to the item.
225
+ for (const e of record.filter((x) => x.host === t.host && x.repo === t.repo)) {
226
+ if (!rows.some((r) => r.epicId === e.epicId) || !fs.existsSync(epicFiles(epicRoot(root, e.epicId)).state)) continue;
227
+ let links;
228
+ try { links = readLinks(root, e.epicId); } catch { out.notes.push(`${e.epicId}: its .sdlc/issue-links.json could not be read, so it was not linked`); continue; }
229
+ if (links.some((l) => itemKey(l) === itemKey(e))) continue;
230
+ if (dryRun) { out.linked.push({ epicId: e.epicId, number: e.number, wouldLink: true }); continue; }
231
+ const item = readItem(t, e.number, { runner });
232
+ if (!item.ok) { out.notes.push(`${e.epicId}: item ${e.number} could not be read, so it was not linked`); continue; }
233
+ const epicType = (() => { try { return loadLedger(epicRoot(root, e.epicId)).state?.type ?? null; } catch { return null; } })();
234
+ try {
235
+ const { back } = linkAndWriteBack(root, e.epicId, t, item, { rules, epicType, now, runner });
236
+ out.linked.push({ epicId: e.epicId, number: e.number, failed: back.failed });
237
+ } catch (x) { out.notes.push(`${e.epicId}: it could not be linked (${forTerminal(x?.message ?? String(x))})`); }
238
+ }
239
+
240
+ if (out.failed.length) { out.ok = false; process.exitCode = 1; }
241
+ if (json) return out;
242
+ for (const x of out.created) log(` ${x.priority} ${forTerminal(x.feature)} ${c.dim(`(${x.epicId}, ${forTerminal(x.phase)})`)} ${dryRun ? c.dim('would be created') : x.url ?? `#${x.number}`}`);
243
+ for (const x of out.recovered) info(`${x.epicId} was already on the Product repo as #${x.number}; ${dryRun ? 'it would be recorded' : 'recorded it'}`);
244
+ for (const x of out.linked) info(`${x.epicId} ${x.wouldLink ? 'would be linked' : 'linked'} to #${x.number}`);
245
+ for (const x of out.failed) warn(`${x.epicId}: ${forTerminal(x.why)}${x.url ? ` ${x.url}` : ''}`);
246
+ for (const n of out.notes) info(n);
247
+ info(`${out.created.length} ${dryRun ? 'would be created' : 'created'}, ${out.alreadyPublished} already published`);
248
+ const records = [wroteRecord && 'foundation/.sdlc/roadmap-items.json', out.linked.length && 'the epics\' .sdlc/issue-links.json'].filter(Boolean);
249
+ if (!dryRun && records.length) info(`${recordRoute(root, records.join(' and '))}, so the team keeps the record`);
250
+ return undefined;
251
+ }
252
+
253
+ // For `yad foundation status`: the item each row was published as, read from the record only (no network).
254
+ export function publishedItems(root) {
255
+ try { return new Map(readRecord(root).map((e) => [e.epicId, { number: e.number, url: e.url ?? null }])); } catch { return null; }
256
+ }