yadflow 4.10.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 (106) hide show
  1. package/CHANGELOG.md +97 -0
  2. package/README.md +12 -3
  3. package/bin/commands.mjs +5 -1
  4. package/bin/yad.mjs +109 -15
  5. package/cli/agent-guard-worker.mjs +13 -0
  6. package/cli/agent-guard.mjs +1053 -57
  7. package/cli/agent-rules.mjs +34 -3
  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 +3 -3
  28. package/cli/doctor.mjs +80 -13
  29. package/cli/epic-state.mjs +93 -1
  30. package/cli/epic.mjs +15 -3
  31. package/cli/errors.mjs +2 -1
  32. package/cli/find-product.mjs +69 -15
  33. package/cli/foundation-publish.mjs +256 -0
  34. package/cli/gate.mjs +29 -3
  35. package/cli/git-read.mjs +38 -0
  36. package/cli/guard-stream.mjs +409 -0
  37. package/cli/hook.mjs +59 -9
  38. package/cli/issues-act.mjs +57 -13
  39. package/cli/issues-write.mjs +19 -6
  40. package/cli/issues.mjs +62 -23
  41. package/cli/lib.mjs +37 -2
  42. package/cli/local-page.mjs +138 -0
  43. package/cli/machine.mjs +1 -1
  44. package/cli/manifest.mjs +50 -0
  45. package/cli/map/view/app.js +712 -0
  46. package/cli/map/view/index.html +50 -0
  47. package/cli/map/view/style.css +142 -0
  48. package/cli/map-view.mjs +186 -0
  49. package/cli/map.mjs +637 -0
  50. package/cli/members.mjs +9 -15
  51. package/cli/next.mjs +1 -1
  52. package/cli/openpr.mjs +2 -2
  53. package/cli/plan.mjs +125 -0
  54. package/cli/platform.mjs +5 -5
  55. package/cli/product-index.mjs +1 -1
  56. package/cli/protection.mjs +32 -0
  57. package/cli/reconcile.mjs +8 -2
  58. package/cli/report.mjs +9 -3
  59. package/cli/reports-dir.mjs +391 -0
  60. package/cli/reports.mjs +65 -0
  61. package/cli/run-checks.mjs +5 -2
  62. package/cli/scan.mjs +1 -1
  63. package/cli/setup.mjs +30 -5
  64. package/cli/standup.mjs +87 -71
  65. package/cli/status.mjs +6 -5
  66. package/cli/test-agents-file.mjs +614 -8
  67. package/cli/test-brain-activity.mjs +753 -0
  68. package/cli/test-brain-view.mjs +381 -0
  69. package/cli/test-brain.mjs +795 -0
  70. package/cli/test-guide.mjs +211 -0
  71. package/cli/test-machine.mjs +59 -0
  72. package/cli/test-map.mjs +615 -0
  73. package/cli/test-reports.mjs +382 -0
  74. package/cli/test-run-checks.mjs +4 -0
  75. package/cli/test-worktree.mjs +24 -3
  76. package/cli/toolbox-connect.mjs +21 -6
  77. package/cli/toolbox.mjs +59 -4
  78. package/cli/update-commit.mjs +101 -9
  79. package/cli/usage.mjs +8 -4
  80. package/package.json +8 -4
  81. package/skills/yad-architecture/SKILL.md +22 -4
  82. package/skills/yad-change/SKILL.md +3 -1
  83. package/skills/yad-change/references/triage.md +2 -0
  84. package/skills/yad-checks/SKILL.md +2 -0
  85. package/skills/yad-checks/references/check-gates.md +8 -5
  86. package/skills/yad-checks/templates/checks/build-test-lint.sh +7 -0
  87. package/skills/yad-checks/templates/checks/install-deps.sh +6 -0
  88. package/skills/yad-checks/templates/checks/package-manager.sh +42 -0
  89. package/skills/yad-checks/templates/github/yad-checks.yml +3 -2
  90. package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml +3 -2
  91. package/skills/yad-checks/templates/hooks/yad-activity.mjs +238 -0
  92. package/skills/yad-connect-repos/SKILL.md +14 -0
  93. package/skills/yad-discovery/SKILL.md +11 -0
  94. package/skills/yad-discovery/references/foundation-schema.md +11 -0
  95. package/skills/yad-docs/templates/app/package-lock.json +18 -10
  96. package/skills/yad-docs/templates/app/package.json +6 -1
  97. package/skills/yad-epic/SKILL.md +3 -0
  98. package/skills/yad-epic/references/state-schema.md +35 -1
  99. package/skills/yad-guide/SKILL.md +4 -4
  100. package/skills/yad-implement/SKILL.md +76 -15
  101. package/skills/yad-issues/SKILL.md +2 -1
  102. package/skills/yad-pr-template/templates/checks/pr-template.sh +8 -4
  103. package/skills/yad-pr-template/templates/checks/pr-title.sh +8 -4
  104. package/skills/yad-spec/SKILL.md +19 -0
  105. package/skills/yad-stories/SKILL.md +22 -4
  106. package/skills/yad-stories/references/story-schema.md +1 -1
@@ -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
+ }
package/cli/gate.mjs CHANGED
@@ -14,7 +14,7 @@ import {
14
14
  advanceState, closingRecord, markInReview, isEscalated, gateRuleFor, gateCapFor, gateReach, uniqueReach, peopleWord, capSeat, gateRuleSum, gateRuleEnforced, parseReviewBranch, artifactFromBase, legacyLogins,
15
15
  upsertProductPr, stateInvariants, repairState, DISCOVERY_FILES, FOUNDATION_REQUIRED, unwrittenSections,
16
16
  canonicalApprovals, canonicalComments, canonicalProductPrs, optionalStepsFor, isSkippableStep, writeState, routeLacksStep,
17
- isPassed, stepStatus, claimsSkipped, claimsInherited, DISCOVERY_EPIC, FOUNDATION_DIR, FOUNDATION_EPIC, staleFoundationGuards,
17
+ isPassed, stepStatus, claimsSkipped, claimsInherited, DISCOVERY_EPIC, FOUNDATION_DIR, FOUNDATION_EPIC, staleFoundationGuards, recordSoloRereview, soloRereviewDue,
18
18
  reopenStep, retiredPr, epicLineage, heldByReopen, reopenStampDue, stampPassed, isGateStep,
19
19
  } from './epic-state.mjs';
20
20
  import { readShips } from './ledger.mjs';
@@ -823,6 +823,17 @@ export async function gateSync(root, { epic, artifact, today, reader = readPr, f
823
823
  // New approvals bind to what the review approved (#366); see headContentHash. Unknown is never
824
824
  // taken as approved: nothing is bound, and the run goes red so CI tries again.
825
825
  const at = approvedContent(contentAt, { root, epic, epicDir, artifact: pr.artifact, platform, number: pr.number, headOid: pull.headOid });
826
+ if (!at?.ok && alreadyDone && !readOnly && solo && epic === FOUNDATION_EPIC && pull.merged
827
+ && soloRereviewDue(step, { pr: Number(pr.number), platform, commit: pull.mergeCommit || null })) {
828
+ // A solo Foundation's fresh review merged and is still waiting to be recorded, and this run is the only
829
+ // one that records it: the sweep never reads a passed step. So the read failing is a failed run, as for
830
+ // an open step. A merge already on file (the first close, an earlier re-review) keeps the warning below,
831
+ // and so does a read-only run, which could not record it anyway.
832
+ fail(`${pr.artifact}: could not read what PR #${pr.number} merged (${at?.reason || 'no answer'}) — the Foundation's solo re-review was not recorded`);
833
+ hand(`run it again with the full history (fetch-depth: 0, or GIT_DEPTH: "0"), able to fetch the PR/MR: \`yad gate ci --branch review/${FOUNDATION_EPIC}/${artifactBase(step.artifact)} --pr ${pr.number} --merged\` in CI, or \`yad gate sync ${FOUNDATION_EPIC}\` on a local ledger`);
834
+ process.exitCode = 1;
835
+ continue;
836
+ }
826
837
  if (!at?.ok && alreadyDone) {
827
838
  // A done step only records what arrives: nothing is bound, and the run is not failed for it.
828
839
  warn(`${pr.artifact}: could not read what PR #${pr.number} approved (${at?.reason || 'no answer'}) — ${step.id} is already done; no approval was recorded this time — a later sweep tries again`);
@@ -837,7 +848,9 @@ export async function gateSync(root, { epic, artifact, today, reader = readPr, f
837
848
  const approvedHash = at.hash ?? (curHash ? NOTHING_AT_HEAD : null);
838
849
  // Merged, and the default branch holds something else: another merge changed it after this review.
839
850
  // Solo mode counts no approvals, so there is nothing to say there.
840
- const differs = !!pull.merged && approvedHash !== curHash;
851
+ // Judged against every form that still means the same content (#499: an epic's genesis lineage lines
852
+ // added after the merge are not "something else"), never against today's form alone.
853
+ const differs = !!pull.merged && approvedHash !== curHash && !acceptedHashes(epicDir, pr.artifact).includes(approvedHash);
841
854
  // Not on a step already done: the gate decided it, and a re-sync only records what arrives.
842
855
  if (differs && !solo && !alreadyDone) {
843
856
  const trunk = resolveDefaultBranch(productGit(root), productConfig);
@@ -946,7 +959,20 @@ export async function gateSync(root, { epic, artifact, today, reader = readPr, f
946
959
  // done … the rule no longer holds" would describe a pass that never happened. Say what is true: the
947
960
  // review is still owed, and what it still needs (E37). The approvals themselves are kept either way:
948
961
  // a sync of a step that reads as passed only ever adds to its record (`upsertBridge`'s `closed`).
949
- if (stepStatus(step) === 'deferred') {
962
+ // A solo Foundation reviewed again on a fresh PR/MR (E174 follow-up): solo mode counts no approvals, so
963
+ // without this record nothing could ever clear "changed after its review", and `yad foundation publish`
964
+ // would refuse for good. Bound to what the PR/MR merged (`approvedHash`), never to the default branch
965
+ // as it stands: an edit merged after this review is not covered by it. Not on a read-only run.
966
+ const rereviewed = !readOnly && solo && epic === FOUNDATION_EPIC && stepStatus(step) === 'done' && !!pull.merged && pred.passed
967
+ && typeof approvedHash === 'string' && approvedHash !== NOTHING_AT_HEAD
968
+ && recordSoloRereview(state, step.id, {
969
+ pr: Number.isInteger(pr.number) ? pr.number : Number(pr.number), platform, hash: approvedHash, by,
970
+ date: (typeof pull.mergedAt === 'string' && pull.mergedAt.slice(0, 10)) || today,
971
+ commit: pull.mergeCommit || null, mergedBy: pull.mergedBy || null,
972
+ });
973
+ if (rereviewed) {
974
+ ok(`${step.id}: PR #${pr.number} merged in solo mode — recorded as a review of ${step.artifact} as that PR merged it (the first close is kept)`);
975
+ } else if (stepStatus(step) === 'deferred') {
950
976
  info(`${step.id} is deferred — approvals re-synced, chain not re-advanced; its review is still owed`);
951
977
  for (const m of pred.missing) hand(`still owed: ${m}`);
952
978
  } else if (changedSinceApproved) {
@@ -0,0 +1,38 @@
1
+ // Read files straight from a git ref, without a checkout (E181; the reader E131 wrote for member files).
2
+ // readBlobsAt(repo, specs) one `git cat-file --batch` for every `<ref>:<path>` → Map(spec → Buffer | null)
3
+ // readFilesAt(repo, ref, paths) the same for one ref, as text → Map(path → string | null)
4
+ // listTreeAt(repo, ref, dirs) every file under `dirs` at `ref` (NUL-separated, so any name is read whole)
5
+ // Only blobs come back; a missing path, a tree or a submodule is null. Nothing is written.
6
+ import { spawnSync } from 'node:child_process';
7
+
8
+ export function readBlobsAt(repo, specs, { runner = spawnSync } = {}) {
9
+ const res = new Map(specs.map((s) => [s, null]));
10
+ if (!specs.length) return res;
11
+ // A spec with a newline would split the batch: it is never read.
12
+ const asked = specs.filter((s) => !/[\n\r]/.test(s));
13
+ const batch = runner('git', ['cat-file', '--batch'], { cwd: repo, input: asked.map((s) => `${s}\n`).join(''), maxBuffer: 1 << 28 });
14
+ const out = batch.status === 0 && batch.stdout ? Buffer.from(batch.stdout) : Buffer.alloc(0);
15
+ let at = 0;
16
+ for (const s of asked) {
17
+ const nl = out.indexOf(10, at);
18
+ if (nl < 0) break;
19
+ const header = out.subarray(at, nl).toString();
20
+ at = nl + 1;
21
+ const m = header.match(/^[0-9a-f]+ (\w+) (\d+)$/);
22
+ if (!m) continue; // `<spec> missing` (or ambiguous): no body follows
23
+ const body = out.subarray(at, at + Number(m[2]));
24
+ at += Number(m[2]) + 1; // every body is skipped, whatever its type
25
+ if (m[1] === 'blob') res.set(s, body);
26
+ }
27
+ return res;
28
+ }
29
+
30
+ export function readFilesAt(repo, ref, paths, opts = {}) {
31
+ const got = readBlobsAt(repo, paths.map((p) => `${ref}:./${p}`), opts);
32
+ return new Map(paths.map((p) => { const b = got.get(`${ref}:./${p}`); return [p, b ? b.toString('utf8') : null]; }));
33
+ }
34
+
35
+ export function listTreeAt(repo, ref, dirs, { runner = spawnSync } = {}) {
36
+ const r = runner('git', ['ls-tree', '-r', '-z', '--name-only', ref, '--', ...dirs], { cwd: repo, encoding: 'utf8', maxBuffer: 1 << 28 });
37
+ return r.status === 0 ? String(r.stdout).split('\0').filter(Boolean) : [];
38
+ }