yadflow 4.7.0 → 4.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (77) hide show
  1. package/CHANGELOG.md +89 -0
  2. package/README.md +43 -4
  3. package/bin/commands.mjs +4 -1
  4. package/bin/yad.mjs +147 -20
  5. package/cli/agent-guard.mjs +511 -0
  6. package/cli/agent-guide.mjs +83 -0
  7. package/cli/agent-rules.mjs +381 -0
  8. package/cli/argv-flags.mjs +7 -0
  9. package/cli/ci-check.mjs +492 -0
  10. package/cli/docs.mjs +1 -1
  11. package/cli/doctor.mjs +43 -7
  12. package/cli/epic-state.mjs +3 -3
  13. package/cli/errors.mjs +1 -0
  14. package/cli/guide.mjs +549 -0
  15. package/cli/hook.mjs +32 -3
  16. package/cli/lib.mjs +46 -0
  17. package/cli/lifecycle/defaults/2.json +124 -0
  18. package/cli/lifecycle/lifecycle.schema.json +5 -2
  19. package/cli/lifecycle.mjs +16 -3
  20. package/cli/manifest.mjs +75 -0
  21. package/cli/marked-block.mjs +48 -0
  22. package/cli/members.mjs +19 -5
  23. package/cli/migrate.mjs +17 -19
  24. package/cli/next.mjs +1 -1
  25. package/cli/plan.mjs +326 -22
  26. package/cli/protection.mjs +50 -0
  27. package/cli/reconcile.mjs +187 -26
  28. package/cli/report.mjs +62 -14
  29. package/cli/setup.mjs +244 -25
  30. package/cli/signing.mjs +377 -0
  31. package/cli/test-agents-file.mjs +993 -0
  32. package/cli/test-ci-check.mjs +616 -0
  33. package/cli/test-guide.mjs +1267 -0
  34. package/cli/test-node.mjs +129 -0
  35. package/cli/test-setup-agent.mjs +352 -0
  36. package/cli/test-signing.mjs +524 -0
  37. package/cli/toolbox.mjs +1 -1
  38. package/cli/update-commit.mjs +313 -11
  39. package/cli/workspace.mjs +37 -12
  40. package/package.json +6 -4
  41. package/skills/sdlc/config.yaml +4 -4
  42. package/skills/sdlc/module-help.csv +1 -0
  43. package/skills/yad-change/SKILL.md +3 -2
  44. package/skills/yad-checks/SKILL.md +29 -9
  45. package/skills/yad-checks/references/check-gates.md +9 -4
  46. package/skills/yad-checks/templates/checks/package-manager.sh +1 -1
  47. package/skills/yad-checks/templates/github/yad-checks.yml +1 -1
  48. package/skills/yad-checks/templates/gitlab/.gitlab-ci.yml +1 -1
  49. package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml +1 -1
  50. package/skills/yad-checks/templates/gitlab/yad-product-checks.gitlab-ci.yml +1 -1
  51. package/skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml +1 -1
  52. package/skills/yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml +1 -1
  53. package/skills/yad-checks/templates/hooks/agent-guard.mjs +116 -0
  54. package/skills/yad-commit/SKILL.md +4 -3
  55. package/skills/yad-connect-repos/SKILL.md +5 -3
  56. package/skills/yad-connect-repos/references/code-context.md +2 -1
  57. package/skills/yad-connect-repos/references/repos-registry.md +2 -1
  58. package/skills/yad-docs-overview/references/pipeline-model.md +2 -2
  59. package/skills/yad-engineer-review/SKILL.md +12 -7
  60. package/skills/yad-engineer-review/references/ship-and-record.md +7 -4
  61. package/skills/yad-epic/SKILL.md +2 -1
  62. package/skills/yad-epic/references/state-schema.md +1 -1
  63. package/skills/yad-guide/SKILL.md +192 -0
  64. package/skills/yad-open-pr/SKILL.md +1 -1
  65. package/skills/yad-pair-review/SKILL.md +14 -5
  66. package/skills/yad-product-bridge/SKILL.md +32 -13
  67. package/skills/yad-product-bridge/references/bridge.md +6 -3
  68. package/skills/yad-product-bridge/templates/github/yad-gate-sync.yml +2 -2
  69. package/skills/yad-product-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml +1 -1
  70. package/skills/yad-report/SKILL.md +15 -0
  71. package/skills/yad-review-companion/SKILL.md +5 -3
  72. package/skills/yad-review-gate/SKILL.md +13 -9
  73. package/skills/yad-review-gate/references/gating.md +1 -1
  74. package/skills/yad-run/SKILL.md +10 -6
  75. package/skills/yad-run/references/run-loop.md +2 -1
  76. package/skills/yad-sync-repos/SKILL.md +2 -1
  77. package/skills/yad-ui/SKILL.md +2 -2
package/cli/reconcile.mjs CHANGED
@@ -1,10 +1,11 @@
1
1
  // `yad check` (report) and `yad check --fix` (reconcile) — and `yad update`
2
2
  // as a thin alias (--scope=changed). Inspects actual project state against the
3
3
  // manifest: missing setup, drifted files, stale code-context.
4
+ import { spawnSync } from 'node:child_process';
4
5
  import fs from 'node:fs';
5
6
  import path from 'node:path';
6
7
  import {
7
- c, log, ok, info, warn, hand, readJSON, writeJSON, exists, forTerminal,
8
+ c, log, ok, info, warn, fail, hand, readJSON, writeJSON, exists, forTerminal, run, samePath,
8
9
  } from './lib.mjs';
9
10
 
10
11
  const readFileSafe = (p) => { try { return fs.readFileSync(p, 'utf8'); } catch { return ''; } };
@@ -12,12 +13,13 @@ const readFileSafe = (p) => { try { return fs.readFileSync(p, 'utf8'); } catch {
12
13
  import { preflightGuardReadiness } from './productcommit.mjs';
13
14
  import { VERSION, PROJECT_FILES, MANAGED_LEDGER, BACKUP_SUFFIX , productConfigPath, PRODUCT_LINK } from './manifest.mjs';
14
15
  import {
15
- moduleActions, repoActions, productActions, hookActions,
16
+ moduleActions, repoActions, productActions, hookActions, agentFileActions, agentGuardActions, orphanAgentGuardActions, allowListActions, orphanAllowListActions, repoOrphanAgentGuardActions,
16
17
  legacyModuleActions, removedModuleActions, orphanHookActions, captureHookActions, orphanCaptureHookActions, legacyHookScriptActions, legacyRepoActions, legacyProductActions,
17
18
  ideTargetStateFor, recordManagedWrites, gitHookActions, orphanGitHookActions, gitHookState, gitHookAdvice, renamedNameHits, withoutKeptRenames, PRODUCT_PROFILE_GATES, productProfileGap, productProfileEffect, PRODUCT_PROFILE_FIX, workflowsPassingProduct, productGateBlockers, oldProfileAdvice,
18
19
  } from './plan.mjs';
19
20
  import { gitHead, packRepo } from './setup.mjs';
20
- import { groupByRoot, commitUpdates, repoLabel } from './update-commit.mjs';
21
+ import { groupByRoot, commitUpdates, openUpdatePrs, repoLabel, updatePrBlocker, updateTargets, HELD_KINDS } from './update-commit.mjs';
22
+ import { createPr } from './platform.mjs';
21
23
  import { hasSiblingRepo, workspaceFileState, writeWorkspaceFile, WORKSPACE_FILE } from './find-product.mjs';
22
24
  import { offerToolbox } from './toolbox.mjs';
23
25
 
@@ -31,7 +33,7 @@ const repoShown = (repo) => `product (the code repo at ${forTerminal(repo.path)}
31
33
  const shown = (a) => a.shownScope ?? a.scope;
32
34
  const itemsOf = (actions) => actions.map((a) => ({ scope: a.scope, item: a.item, status: a.status, product: !a.fromRepo }));
33
35
 
34
- export async function reconcile(root, { fix = false, scope = 'all', force = false, push = false, allowBranch = false, overwriteLocal = false, toolbox: toolboxAt = null } = {}) {
36
+ export async function reconcile(root, { fix = false, scope = 'all', force = false, push = false, openPr = false, allowBranch = false, overwriteLocal = false, toolbox: toolboxAt = null, creator = createPr } = {}) {
35
37
  log(c.bold(`\nSDLC reconcile ${c.dim('v' + VERSION)}`));
36
38
  log(c.dim(`target: ${root}\n`));
37
39
 
@@ -60,6 +62,12 @@ export async function reconcile(root, { fix = false, scope = 'all', force = fals
60
62
  ...moduleActions(root, ideTargets), ...legacyModuleActions(root, ideTargets), ...removedModuleActions(root, ideTargets),
61
63
  // E123: a renamed CI file the team edited is kept, and its new name is not installed beside it.
62
64
  ...withoutKeptRenames([...productActions(root), ...legacyProductActions(root)]), ...hookActions(root, ideTargets),
65
+ // E158: the rules block in AGENTS.md (and CLAUDE.md importing it), which every agent reads first.
66
+ ...agentFileActions(root, ideTargets),
67
+ // E158: the agent guard, before every shell command the agent runs.
68
+ ...agentGuardActions(root, ideTargets), ...orphanAgentGuardActions(root, ideTargets),
69
+ // E158 (#353): the read-only yad commands, pre-approved for Claude Code.
70
+ ...allowListActions(root, ideTargets), ...orphanAllowListActions(root, ideTargets),
63
71
  ...orphanHookActions(root, ideTargets),
64
72
  // E48: this clone's git pre-commit hook — the person's half of the ledger guard.
65
73
  ...gitHookActions(root), ...orphanGitHookActions(root),
@@ -80,7 +88,10 @@ export async function reconcile(root, { fix = false, scope = 'all', force = fals
80
88
  });
81
89
  }
82
90
  for (const repo of registry.repos) {
83
- const own = withoutKeptRenames([...repoActions(root, repo), ...legacyRepoActions(root, repo)]);
91
+ const repoRoot = path.resolve(root, repo.path);
92
+ // E158b: a target that left takes yad's guard and allow-list entries out of the repo's own settings too.
93
+ const orphans = samePath(repoRoot, path.resolve(root)) ? [] : repoOrphanAgentGuardActions(repoRoot, ideTargets, { scope: repo.name });
94
+ const own = withoutKeptRenames([...repoActions(root, repo), ...legacyRepoActions(root, repo)]).concat(orphans);
84
95
  // Set on the action itself: later steps compare actions by identity. `true`, not the name, which may be empty.
85
96
  for (const a of own) { a.fromRepo = true; if (repo.name === 'product') a.shownScope = repoShown(repo); }
86
97
  actions.push(...own);
@@ -169,7 +180,10 @@ export async function reconcile(root, { fix = false, scope = 'all', force = fals
169
180
  // A managed file the team edited is NEVER rewritten by a plain update — that silent clobber is what
170
181
  // #164 reported. It is reported on every run (honest drift) until either the edit is dropped or
171
182
  // `--overwrite-local` replaces it, which still saves the previous content beside it.
172
- const modified = actions.filter((a) => a.status === 'modified');
183
+ // An action that writes nothing (`writesNothing`: a settings file that does not parse, rules-block markers yad
184
+ // cannot trust) has said why at plan time, and `--overwrite-local` cannot fix it either: it is left out here
185
+ // and from what --fix applies, so no run says it was fixed.
186
+ const modified = actions.filter((a) => a.status === 'modified' && !a.writesNothing);
173
187
  for (const m of modified) {
174
188
  // The product-link record has no template: it is `modified` only when it is not a JSON object (E120).
175
189
  warn(m.item === PRODUCT_LINK
@@ -224,8 +238,9 @@ export async function reconcile(root, { fix = false, scope = 'all', force = fals
224
238
  hand(`keep the edits (reported as \`modified\` on every check), or replace them with \`yad update --overwrite-local\` — each previous version is saved beside the file as <file>${BACKUP_SUFFIX}`);
225
239
  }
226
240
 
227
- const fixable = actions.filter((a) =>
241
+ let fixable = actions.filter((a) =>
228
242
  a.status !== 'ok'
243
+ && !a.writesNothing
229
244
  && (a.status !== 'modified' || overwriteLocal)
230
245
  && (scope === 'all' ? true : a.status !== 'missing'),
231
246
  );
@@ -238,21 +253,110 @@ export async function reconcile(root, { fix = false, scope = 'all', force = fals
238
253
  let workspaceFile = wsNeeded ? workspaceFileState(root) : null;
239
254
  if (!fix) {
240
255
  if (workspaceFile === 'missing') info(`no ${WORKSPACE_FILE} beside the Product — \`yad check --fix\` writes it, so yad finds the Product from its code repos`);
241
- if (push) warn('--push has no effect without --fix (there is nothing applied to commit).');
256
+ if (push || openPr) warn(`${push ? '--push' : '--open-pr'} has no effect without --fix (there is nothing applied to commit).`);
242
257
  if (fixable.length || gaps.length) hand('run `yad check --fix` to reconcile (or `yad setup` for missing one-time setup).');
243
258
  // After the --fix hint, never above it: --fix installs no tool, and must not read as if it did.
244
259
  const toolbox = toolboxSection(root, toolboxAt);
245
260
  return { fix: false, counts, gaps, items: itemsOf(actions), applied: 0, modified: modified.length, commits: [], workspaceFile, toolbox };
246
261
  }
247
262
 
263
+ // Each repo's default branch and platform, for --push and --open-pr.
264
+ const productSettings = readJSON(productConfigPath(root), {});
265
+ const defByRoot = new Map([[root, productSettings?.default_branch]]);
266
+ const platformByRoot = new Map([[root, productSettings?.platform]]);
267
+ for (const repo of registry.repos) {
268
+ const repoRoot = path.resolve(root, repo.path);
269
+ // A monorepo entry (`path: "."`) is the Product itself: its settings are the Product's.
270
+ if (repoRoot === root) continue;
271
+ defByRoot.set(repoRoot, repo.default_branch);
272
+ platformByRoot.set(repoRoot, repo.platform);
273
+ }
274
+
275
+ // --open-pr is all or nothing (E157 update reviews 2 and 3). The Product and every connected repo cloned
276
+ // here (`updateTargets`, the one list the guide reads too) are checked BEFORE anything is written: each must
277
+ // be on its default branch, not detached, with an origin and no local commits origin lacks. One that is not
278
+ // stops the whole run with nothing written, so no repo is left half updated, no one's feature work rides an
279
+ // update PR/MR, and no one is moved off their branch: the person fixes it and runs it again. A repo whose
280
+ // update is already on review (`open`) is left alone (`held`): nothing is written there until it merges.
281
+ let held = new Set();
282
+ let heldRows = [];
283
+ let reached = null;
284
+ if (openPr) {
285
+ const targets = updateTargets(root);
286
+ reached = new Set(targets.map((t) => t.root));
287
+ const checks = targets.map((t) => [t.root, updatePrBlocker(t.root, { defaultBranch: t.defaultBranch ?? defByRoot.get(t.root), productRoot: root, file: t.file })]);
288
+ const stop = checks.filter(([, b]) => b && !HELD_KINDS.includes(b.kind));
289
+ // Every row says why, in `reason` (a word) and `hint` (what to do): the agent relays it to the person.
290
+ const row = (r, b) => ({ label: b.label, product: r === root, branch: b.branch ?? null, committed: false, pushed: false, opened: false, pr: null, skipped: true, error: !HELD_KINDS.includes(b.kind), reason: b.kind, hint: b.message });
291
+ if (stop.length) {
292
+ log('');
293
+ for (const [, b] of stop) fail(`${b.label}: ${b.message}`);
294
+ fail(`--open-pr: ${stop.length} repo(s) cannot take the update as a PR/MR now — nothing was written; fix the above, then run it again`);
295
+ process.exitCode = 1;
296
+ const toolbox = toolboxSection(root, toolboxAt);
297
+ return { fix: true, counts, gaps, items: itemsOf(actions), applied: 0, modified: modified.length, commits: stop.map(([r, b]) => row(r, b)), workspaceFile, toolbox };
298
+ }
299
+ held = new Set(checks.filter(([, b]) => b).map(([r]) => r));
300
+ heldRows = checks.filter(([, b]) => b).map(([r, b]) => row(r, b));
301
+ for (const [, b] of checks) if (b) info(`${b.label}: ${b.message}`);
302
+ if (held.size === checks.length) {
303
+ info('every repo\'s update is already merged or on review — nothing written');
304
+ const toolbox = toolboxSection(root, toolboxAt);
305
+ return { fix: true, counts, gaps, items: itemsOf(actions), applied: 0, modified: modified.length, commits: checks.map(([r, b]) => row(r, b)), workspaceFile, toolbox };
306
+ }
307
+ fixable = fixable.filter((a) => (!a.root || reached.has(a.root)) && !held.has(a.root) && (!a.managed?.root || reached.has(a.managed.root)) && !held.has(a.managed?.root));
308
+ }
309
+ // Under --open-pr, only a repo it checked and did not hold is written (a registered repo not cloned here is
310
+ // `yad repo clone`'s business).
311
+ const reaches = (r) => !r || ((!reached || reached.has(r)) && !held.has(r));
312
+ const live = (a) => reaches(a.root) && reaches(a.managed?.root);
313
+
314
+ // A file the team co-owns (the agent settings that run yad's hooks) is never staged by `--push`. Under
315
+ // --open-pr it rides the PR/MR when it is yad's alone: exactly what is committed (or nothing) with yad's
316
+ // entries merged in — so a file this run creates rides too, and so does one a failed push left behind.
317
+ // Otherwise the person has their own edits in it, which never ride an update: said in a row of its own.
318
+ // Read BEFORE anything is applied. Several adapters can share one file, so it is one entry per file
319
+ // (E157 update review 11).
320
+ const shared = new Map();
321
+ const sharedText = (f) => (exists(f) ? fs.readFileSync(f, 'utf8') : null);
322
+ if (openPr) {
323
+ for (const a of actions) {
324
+ // Only a file this run writes, or one already right: a rules block `yad update` leaves out (an unwired
325
+ // repo's AGENTS.md is `missing`) or one it cannot write (`writesNothing`) is never staged or reported
326
+ // (E158 review 4).
327
+ if (!a.shared || !a.root || !live(a) || (a.status !== 'ok' && !fixable.includes(a))) continue;
328
+ const file = path.join(a.root, a.shared);
329
+ if (!shared.has(file)) {
330
+ // A text file is read as committed, not trimmed (`run` trims): its trailing lines are part of the text
331
+ // yad's block is merged into (E158 review 1).
332
+ let head;
333
+ if (a.kind === 'text') {
334
+ const r = spawnSync('git', ['show', `HEAD:${a.shared}`], { cwd: a.root, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, windowsHide: true });
335
+ head = r.status === 0 ? r.stdout : null;
336
+ } else {
337
+ const r = run('git', ['show', `HEAD:${a.shared}`], { cwd: a.root, maxBuffer: 64 * 1024 * 1024 });
338
+ head = r.ok ? r.stdout : null;
339
+ }
340
+ shared.set(file, { a, merges: [], disk: sharedText(file), head });
341
+ }
342
+ shared.get(file).merges.push(a.mergeShared);
343
+ }
344
+ }
248
345
  // --- apply --- (collect the applied actions so --push can stage each repo's exact allowlist) ---
249
346
  log('');
250
347
  let applied = 0;
251
348
  const appliedActions = [];
349
+ // Under --open-pr a skill folder keeps a person's own files and is staged by the template's files only, so
350
+ // nothing of theirs is deleted from disk or rides the PR/MR (E157 update review 7).
351
+ const keepOwn = (a) => {
352
+ if (!openPr || typeof a.applyKeepingOwn !== 'function') { a.apply(); return a; }
353
+ const kept = a.applyKeepingOwn();
354
+ if (kept.length) info(`kept ${kept.length} file(s) the template does not have in ${shown(a)}/${a.item} — delete any that an older yadflow shipped`);
355
+ return { ...a, paths: a.ownPaths() };
356
+ };
252
357
  for (const a of fixable) {
253
- a.apply();
358
+ appliedActions.push(keepOwn(a));
254
359
  applied++;
255
- appliedActions.push(a);
256
360
  // A backup means the replaced content was not provably ours (a pre-ledger install, or an edit
257
361
  // --overwrite-local was told to discard). Never report that as an ordinary template adoption.
258
362
  info(`${a.status} → fixed: ${shown(a)}/${a.item}${a.backup ? ` ${c.yellow(`(previous content saved to ${path.basename(a.backup)})`)}` : ''}`);
@@ -260,19 +364,80 @@ export async function reconcile(root, { fix = false, scope = 'all', force = fals
260
364
  if (force) {
261
365
  // --force re-copies what is already correct; it deliberately does NOT reach a `modified` file —
262
366
  // only --overwrite-local discards a local edit, and only after backing it up.
263
- for (const a of actions.filter((a) => a.status === 'ok')) { a.apply(); appliedActions.push(a); }
367
+ for (const a of actions.filter((a) => a.status === 'ok' && live(a))) appliedActions.push(keepOwn(a));
264
368
  }
265
369
  // A file that is right on disk but not committed as it stands, which --push must still commit: the
266
370
  // product-link record (E120) — the gates read it from the default branch, not from anyone's disk.
267
- if (push) for (const a of actions) if (a.pendingCommit && !appliedActions.includes(a)) appliedActions.push(a);
371
+ if (push || openPr) for (const a of actions) if (a.pendingCommit && live(a) && !appliedActions.includes(a)) appliedActions.push(a);
372
+ // --open-pr also stages every managed file already right on disk: `stageAllowlist` keeps only what differs
373
+ // from the commit, so an update a failed commit or push left in the working tree is carried by the next run.
374
+ // A folder is staged by its template's own files only, never the folder: a person's own file beside them
375
+ // (notes in a skill folder) must not ride an update PR/MR.
376
+ if (openPr) {
377
+ for (const a of actions) {
378
+ if (a.status !== 'ok' || !a.root || !Array.isArray(a.paths) || !live(a) || appliedActions.includes(a)) continue;
379
+ appliedActions.push(typeof a.ownPaths === 'function' ? { ...a, paths: a.ownPaths() } : a);
380
+ }
381
+ }
382
+ const sharedRows = [];
383
+ const lf = (t) => t.replace(/\r\n/g, '\n');
384
+ const parse = (t) => { try { const v = JSON.parse(t); return v && typeof v === 'object' && !Array.isArray(v) ? v : null; } catch { return null; } };
385
+ // A settings file is JSON, merged as objects; a rules file (AGENTS.md, CLAUDE.md, E158) is text, with yad's
386
+ // block put into it. Each kind: how to read it, merge yad's part in, and compare.
387
+ const KINDS = {
388
+ // `eq` compares a file's text with what is committed: JSON trimmed (`run` trims git's output), text with its
389
+ // line endings evened out, since git may store LF where the disk holds CRLF (`core.autocrlf`).
390
+ json: { read: (t) => parse(t), empty: {}, merge: (o, m) => { if (!o) return undefined; const r = m(o); return r.unreadable ? undefined : r.settings; }, same: (a, b) => JSON.stringify(a) === JSON.stringify(b), eq: (a, b) => a.trim() === b.trim(), what: 'its entries (hooks, the read-only allow list)', reason: 'settings-uncommitted' },
391
+ text: { read: (t) => t, empty: null, merge: (t, m) => { const r = m(t); return r.refused ? undefined : r.text; }, same: (a, b) => lf(a) === lf(b), eq: (a, b) => lf(a) === lf(b), what: 'its yadflow rules block', reason: 'agents-uncommitted' },
392
+ };
393
+ for (const [file, e] of shared) {
394
+ const k = KINDS[e.a.kind ?? 'json'];
395
+ const now = sharedText(file);
396
+ if (now === null || (e.head !== null && k.eq(now, e.head))) continue;
397
+ const base = e.head === null ? k.empty : k.read(e.head);
398
+ // What yad alone would make of it: each adapter's part merged into what is committed.
399
+ // `undefined` when yad's part cannot be merged (a file that does not parse, markers it cannot trust).
400
+ const ours = e.merges.reduce((o, merge) => (o === undefined ? undefined : k.merge(o, merge)), base);
401
+ // yad's parts are all committed already: nothing of yad's is left out, and the person's own edits in the
402
+ // file are theirs to keep or share — no row (E157 update review 12).
403
+ if (ours !== undefined && base !== null && k.same(ours, base)) continue;
404
+ const was = e.disk === null ? null : k.read(e.disk);
405
+ const yadsAlone = e.disk === null ? e.head === null
406
+ : e.head !== null && k.eq(e.disk, e.head) ? true
407
+ : !!(ours !== undefined && was !== null && k.same(was, ours));
408
+ if (yadsAlone) { appliedActions.push({ ...e.a, paths: [e.a.shared] }); continue; }
409
+ const hint = `${e.a.shared} has changes that are not committed, so the update left ${k.what} out of the PR/MR: commit ${e.a.shared} as it now stands, through review on a branch of your own`;
410
+ info(`${repoLabel(root, e.a.root)}: ${hint}`);
411
+ sharedRows.push({ label: repoLabel(root, e.a.root), product: e.a.root === root, branch: null, committed: false, pushed: false, opened: false, pr: null, skipped: true, error: false, reason: k.reason, hint });
412
+ }
268
413
  // Refresh the version stamp and persist only the canonical targets used to build actions. This also
269
414
  // completes legacy/corrupt target migration even when no skill content itself needed an update.
270
- writeCanonicalStamp();
271
- appliedActions.push({ scope: 'product', item: PROJECT_FILES.version, status: 'stamp', root, paths: [PROJECT_FILES.version] });
415
+ if (!held.has(root)) {
416
+ writeCanonicalStamp();
417
+ appliedActions.push({ scope: 'product', item: PROJECT_FILES.version, status: 'stamp', root, paths: [PROJECT_FILES.version] });
418
+ }
272
419
  // Record what we wrote (and what was already correct) so the NEXT update can tell a stale managed
273
420
  // file from an edited one. Seeding the already-correct files is what migrates a pre-ledger install.
274
421
  // A file left as `modified` records nothing — it differs from the template by definition.
275
- for (const ledgerRoot of recordManagedWrites(actions)) {
422
+ const ledgerRoots = recordManagedWrites(actions.filter(live));
423
+ // A connected repo whose every managed file is the team's own (`modified`) records nothing above, so its
424
+ // ledger would name an older yadflow for good — and read as behind on every `yad guide`. Its version is
425
+ // brought up all the same: this release did look at it.
426
+ for (const repo of registry.repos) {
427
+ const repoRoot = path.resolve(root, repo.path);
428
+ const ledgerFile = path.join(repoRoot, MANAGED_LEDGER);
429
+ if (repoRoot === root || ledgerRoots.includes(repoRoot) || !reaches(repoRoot) || !exists(ledgerFile)) continue;
430
+ const ledger = readJSON(ledgerFile, null);
431
+ if (ledger && typeof ledger === 'object' && !Array.isArray(ledger) && ledger.version !== VERSION) {
432
+ writeJSON(ledgerFile, { ...ledger, version: VERSION });
433
+ ledgerRoots.push(repoRoot);
434
+ } else if (ledger && (push || openPr)) {
435
+ // Already restamped on disk by a run whose commit or push failed: still staged, so the next run carries
436
+ // it (staging keeps only what differs from the commit).
437
+ ledgerRoots.push(repoRoot);
438
+ }
439
+ }
440
+ for (const ledgerRoot of ledgerRoots) {
276
441
  appliedActions.push({
277
442
  scope: repoLabel(root, ledgerRoot), item: MANAGED_LEDGER, status: 'stamp',
278
443
  root: ledgerRoot, paths: [MANAGED_LEDGER],
@@ -293,17 +458,13 @@ export async function reconcile(root, { fix = false, scope = 'all', force = fals
293
458
  // Each repo's `{ label, committed, pushed }`, for the --json answer (E1): a push that failed after a
294
459
  // commit landed is said per repo.
295
460
  let commits = [];
296
- if (push) {
297
- preflightGuardReadiness(root);
298
- const productConfig = readJSON(productConfigPath(root), {});
299
- const defByRoot = new Map([[root, productConfig?.default_branch]]);
300
- const platformByRoot = new Map([[root, productConfig?.platform]]);
301
- for (const repo of registry.repos) {
302
- const repoRoot = path.resolve(root, repo.path);
303
- defByRoot.set(repoRoot, repo.default_branch);
304
- platformByRoot.set(repoRoot, repo.platform);
305
- }
306
- commits = commitUpdates(root, groupByRoot(appliedActions), {
461
+ if (push || openPr) {
462
+ // Both commit: an unsigned commit fails the verified-commits check, on the default branch or on the PR/MR.
463
+ preflightGuardReadiness(root, openPr ? 'the PR/MR\'s verified-commits check requires a platform-Verified signature; an unsigned update commit fails it' : undefined);
464
+ // --open-pr: each repo's changes on their own branch, with a PR/MR a person merges.
465
+ // Every repo has a row: the held ones (with their reason and hint) first, then what was opened.
466
+ if (openPr) commits = heldRows.concat(openUpdatePrs(root, groupByRoot(appliedActions), { defaultBranchFor: (r) => defByRoot.get(r), platformFor: (r) => platformByRoot.get(r), creator, checked: true }), sharedRows);
467
+ else commits = commitUpdates(root, groupByRoot(appliedActions), {
307
468
  push: true, allowBranch,
308
469
  defaultBranchFor: (r) => defByRoot.get(r),
309
470
  // GitLab's yad-update-guard is an includable fragment: unlike a GitHub workflow it does nothing
package/cli/report.mjs CHANGED
@@ -7,6 +7,7 @@
7
7
  // no absolute paths, hostnames, git URLs, repo names, logins/emails, epic/story IDs, branch
8
8
  // names, or flag values ever leave the machine. The user sees the exact payload and confirms before
9
9
  // anything is posted. See memory: no-private-data-in-reports.
10
+ import { createHash } from 'node:crypto';
10
11
  import { c, log, info, ok, warn, note, ask, askYesNo, has, readJSON, run, inJSON } from './lib.mjs';
11
12
  import { VERSION, UPSTREAM_REPO , productConfigPath } from './manifest.mjs';
12
13
  import { createIssue, searchIssues, issueUrl, platformAuthed } from './platform.mjs';
@@ -107,8 +108,13 @@ export function sanitizeContext(dir, { error = null, argv = process.argv.slice(2
107
108
 
108
109
  // ---- body assembly ------------------------------------------------------------------------------
109
110
 
111
+ // What a report is (E158): a `bug` (something broke) or an `enhancement` (yadflow could do better). It sets
112
+ // the label, and an enhancement's title and body.
113
+ export const REPORT_KINDS = ['bug', 'enhancement'];
114
+
110
115
  // Title: prefer the error code + command; fall back to the (scrubbed) summary.
111
- export function buildTitle(ctx, summary) {
116
+ export function buildTitle(ctx, summary, kind = 'bug') {
117
+ if (kind === 'enhancement') return `[report] Enhancement: ${summary ? summary.slice(0, 72) : 'yad idea'}`;
112
118
  const code = ctx.error?.code ? ` [${ctx.error.code}]` : '';
113
119
  const cmd = ctx.command && ctx.command !== '(none)' ? `\`yad ${ctx.command}\`` : 'yad';
114
120
  if (ctx.error) return `[report] ${cmd} failed${code}`;
@@ -116,10 +122,12 @@ export function buildTitle(ctx, summary) {
116
122
  }
117
123
 
118
124
  // Body mirrors the fields of .github/ISSUE_TEMPLATE/bug_report.yml — but only the safe subset.
119
- export function buildBody(ctx, summary) {
125
+ export function buildBody(ctx, summary, kind = 'bug') {
120
126
  const lines = [];
121
- lines.push('### What happened?', '', summary || '_(no summary provided)_', '');
122
- lines.push(`Command: \`yad ${ctx.command}\``, '');
127
+ if (kind === 'enhancement') lines.push('### What would help?', '', summary || '_(no summary provided)_', '');
128
+ else lines.push('### What happened?', '', summary || '_(no summary provided)_', '');
129
+ // An idea is not about a command line; a bug is.
130
+ if (kind !== 'enhancement') lines.push(`Command: \`yad ${ctx.command}\``, '');
123
131
  lines.push('### Environment');
124
132
  lines.push(`- yadflow: \`${ctx.version}\``);
125
133
  lines.push(`- node: \`${ctx.node}\``);
@@ -129,7 +137,7 @@ export function buildBody(ctx, summary) {
129
137
  if (ctx.glab) lines.push(`- glab: ${ctx.glab}`);
130
138
  lines.push(`- platform: ${ctx.platform}`);
131
139
  lines.push('');
132
- if (ctx.error) {
140
+ if (ctx.error && kind !== 'enhancement') {
133
141
  lines.push('### Error');
134
142
  if (ctx.error.code) lines.push(`- code: \`${ctx.error.code}\``);
135
143
  lines.push(`- message: ${ctx.error.message}`);
@@ -140,6 +148,16 @@ export function buildBody(ctx, summary) {
140
148
  return lines.join('\n');
141
149
  }
142
150
 
151
+ // The check value for `--post --confirm` (E158): a hash of exactly what would be posted. `--json` returns it
152
+ // with the preview; `--post` posts only when the text it builds again hashes the same, so what goes up is
153
+ // exactly what the person saw.
154
+ export const confirmHash = ({ title, body, labels }) => createHash('sha256').update(JSON.stringify([title, body, labels])).digest('hex');
155
+
156
+ // The report's own flags never reach the posted command line: the preview and the post must build the same
157
+ // text, and they are run with different flags.
158
+ const OWN_FLAGS = new Set(['--json', '--post', '--confirm', '--kind']);
159
+ const withoutOwnFlags = (argv) => argv.filter((a) => !OWN_FLAGS.has(String(a).split('=')[0]));
160
+
143
161
  // ---- open a URL (best-effort) -------------------------------------------------------------------
144
162
  function openUrl(url, { runner = run } = {}) {
145
163
  const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
@@ -154,6 +172,10 @@ export async function runReport(dir, opts = {}) {
154
172
  const {
155
173
  error = null,
156
174
  message = null,
175
+ // E158: `bug` or `enhancement`; and `post` with `confirm`, for an agent posting the preview the person saw.
176
+ kind = 'bug',
177
+ post = false,
178
+ confirm = null,
157
179
  // injectable seams (tests never shell out or prompt)
158
180
  filer = createIssue,
159
181
  searcher = searchIssues,
@@ -163,11 +185,13 @@ export async function runReport(dir, opts = {}) {
163
185
  authed = () => platformAuthed(UPSTREAM_PLATFORM),
164
186
  argv = process.argv.slice(2),
165
187
  // A --json run never prompts, and so never posts (E1): it answers with the payload and the prefilled URL.
166
- interactive = !process.env.SDLC_NONINTERACTIVE && !inJSON(),
188
+ // Nor does a run with no terminal (E158 review 1): an agent's `yad report` would otherwise read its "yes"
189
+ // from a pipe and post text no person saw. An agent posts only through --post --confirm.
190
+ interactive = !process.env.SDLC_NONINTERACTIVE && !inJSON() && !!process.stdin.isTTY && !!process.stdout.isTTY,
167
191
  } = opts;
168
192
 
169
193
  try {
170
- const ctx = sanitizeContext(dir, { error, argv });
194
+ const ctx = sanitizeContext(dir, { error, argv: withoutOwnFlags(argv) });
171
195
 
172
196
  // Summary — the user's own description (scrubbed for stray paths/urls). Ask if interactive.
173
197
  let summary = message ? scrub(message) : '';
@@ -176,9 +200,33 @@ export async function runReport(dir, opts = {}) {
176
200
  summary = a ? scrub(a) : '';
177
201
  }
178
202
 
179
- const title = buildTitle(ctx, summary);
180
- const body = buildBody(ctx, summary);
181
- const labels = ['bug'];
203
+ const title = buildTitle(ctx, summary, kind);
204
+ const body = buildBody(ctx, summary, kind);
205
+ const labels = [kind === 'enhancement' ? 'enhancement' : 'bug'];
206
+ const check = confirmHash({ title, body, labels });
207
+
208
+ // --post --confirm: post with no prompt, but only the text the person saw (its hash). Anything else posts
209
+ // nothing: the agent shows the new preview and asks again.
210
+ if (post) {
211
+ if (confirm !== check) {
212
+ warn('not posted: this report is not the text that was shown (it changed, or --confirm is not the value its --json preview gave) — preview it again with --json, show it, and ask again');
213
+ process.exitCode = 1;
214
+ return { filed: false, url: null, kind, title, body, labels, related: [], confirm: check, refused: 'confirm-mismatch' };
215
+ }
216
+ if (authed()) {
217
+ const r = filer(UPSTREAM_PLATFORM, UPSTREAM_REPO, { title, body, labels });
218
+ if (r.ok) {
219
+ ok(`Issue filed: ${c.cyan(r.url)}`);
220
+ return { filed: true, url: r.url, kind, title, body, labels, related: [], confirm: check };
221
+ }
222
+ warn(`Could not file automatically: ${r.reason || 'unknown error'}`);
223
+ } else {
224
+ note('gh is not logged in — file it here instead (prefilled); the person opens the link:');
225
+ }
226
+ const url = issueUrl(UPSTREAM_PLATFORM, UPSTREAM_REPO, { title, body, labels });
227
+ log(` → ${c.cyan(url)}`);
228
+ return { filed: false, url, kind, title, body, labels, related: [], confirm: check };
229
+ }
182
230
 
183
231
  // Dedup — search open issues by the error code (or the first summary word). Advisory: a failed
184
232
  // search just skips this step, it never blocks filing.
@@ -193,7 +241,7 @@ export async function runReport(dir, opts = {}) {
193
241
  if (interactive && await prompter('Open an existing issue instead of filing a new one?', true)) {
194
242
  opener(matches[0].url);
195
243
  log(`\n → ${c.cyan(matches[0].url)}`);
196
- return { filed: false, url: matches[0].url, deduped: true, title, body, labels, related };
244
+ return { filed: false, url: matches[0].url, deduped: true, kind, title, body, labels, related, confirm: check };
197
245
  }
198
246
  }
199
247
  }
@@ -213,7 +261,7 @@ export async function runReport(dir, opts = {}) {
213
261
  note(interactive ? 'Not posted. You can file it yourself here (prefilled):' : 'Non-interactive — not posted. File it here (prefilled):');
214
262
  log(` → ${c.cyan(url)}`);
215
263
  // The payload exactly as it would be posted, for a --json caller to show or file itself.
216
- return { filed: false, url, title, body, labels, related };
264
+ return { filed: false, url, kind, title, body, labels, related, confirm: check };
217
265
  }
218
266
 
219
267
  // File directly when the CLI is authenticated; otherwise fall back to the prefilled URL.
@@ -221,7 +269,7 @@ export async function runReport(dir, opts = {}) {
221
269
  const r = filer(UPSTREAM_PLATFORM, UPSTREAM_REPO, { title, body, labels });
222
270
  if (r.ok) {
223
271
  ok(`Issue filed: ${c.cyan(r.url)}`);
224
- return { filed: true, url: r.url, title, body, labels, related };
272
+ return { filed: true, url: r.url, kind, title, body, labels, related, confirm: check };
225
273
  }
226
274
  warn(`Could not file automatically: ${r.reason || 'unknown error'}`);
227
275
  } else {
@@ -230,7 +278,7 @@ export async function runReport(dir, opts = {}) {
230
278
  const url = issueUrl(UPSTREAM_PLATFORM, UPSTREAM_REPO, { title, body, labels });
231
279
  opener(url);
232
280
  log(` → ${c.cyan(url)}`);
233
- return { filed: false, url, title, body, labels, related };
281
+ return { filed: false, url, kind, title, body, labels, related, confirm: check };
234
282
  } catch (e) {
235
283
  // Reporting itself must never crash the CLI.
236
284
  note(`could not complete the report (${e?.message || e}) — please file manually at https://github.com/${UPSTREAM_REPO}/issues`);