yadflow 4.7.0 → 4.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (96) hide show
  1. package/CHANGELOG.md +116 -0
  2. package/README.md +43 -4
  3. package/bin/commands.mjs +5 -1
  4. package/bin/yad.mjs +169 -22
  5. package/cli/agent-guard.mjs +511 -0
  6. package/cli/agent-guide.mjs +83 -0
  7. package/cli/agent-rules.mjs +388 -0
  8. package/cli/argv-flags.mjs +7 -0
  9. package/cli/build.mjs +1 -1
  10. package/cli/ci-check.mjs +492 -0
  11. package/cli/docs.mjs +1 -1
  12. package/cli/doctor.mjs +148 -7
  13. package/cli/epic-state.mjs +3 -3
  14. package/cli/errors.mjs +1 -0
  15. package/cli/guide.mjs +549 -0
  16. package/cli/hook.mjs +32 -3
  17. package/cli/lib.mjs +46 -0
  18. package/cli/lifecycle/defaults/2.json +124 -0
  19. package/cli/lifecycle/lifecycle.schema.json +5 -2
  20. package/cli/lifecycle.mjs +16 -3
  21. package/cli/machine.mjs +141 -0
  22. package/cli/manifest.mjs +75 -0
  23. package/cli/marked-block.mjs +48 -0
  24. package/cli/members.mjs +19 -5
  25. package/cli/migrate.mjs +17 -19
  26. package/cli/next.mjs +1 -1
  27. package/cli/openpr.mjs +46 -6
  28. package/cli/plan.mjs +326 -22
  29. package/cli/preview.mjs +253 -0
  30. package/cli/protection.mjs +50 -0
  31. package/cli/reconcile.mjs +187 -26
  32. package/cli/repo.mjs +64 -3
  33. package/cli/report.mjs +62 -14
  34. package/cli/review.mjs +4 -0
  35. package/cli/setup.mjs +244 -25
  36. package/cli/signing.mjs +377 -0
  37. package/cli/story-frames.mjs +296 -0
  38. package/cli/test-agents-file.mjs +993 -0
  39. package/cli/test-ci-check.mjs +616 -0
  40. package/cli/test-guide.mjs +1267 -0
  41. package/cli/test-machine.mjs +140 -0
  42. package/cli/test-node.mjs +129 -0
  43. package/cli/test-preview.mjs +511 -0
  44. package/cli/test-setup-agent.mjs +352 -0
  45. package/cli/test-signing.mjs +524 -0
  46. package/cli/test-story-frames.mjs +339 -0
  47. package/cli/toolbox.mjs +35 -1
  48. package/cli/update-commit.mjs +313 -11
  49. package/cli/workspace.mjs +37 -12
  50. package/package.json +6 -4
  51. package/skills/sdlc/config.yaml +4 -4
  52. package/skills/sdlc/module-help.csv +1 -0
  53. package/skills/yad-change/SKILL.md +3 -2
  54. package/skills/yad-checks/SKILL.md +29 -9
  55. package/skills/yad-checks/references/check-gates.md +9 -4
  56. package/skills/yad-checks/templates/checks/package-manager.sh +1 -1
  57. package/skills/yad-checks/templates/github/yad-checks.yml +1 -1
  58. package/skills/yad-checks/templates/gitlab/.gitlab-ci.yml +1 -1
  59. package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml +1 -1
  60. package/skills/yad-checks/templates/gitlab/yad-product-checks.gitlab-ci.yml +1 -1
  61. package/skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml +1 -1
  62. package/skills/yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml +1 -1
  63. package/skills/yad-checks/templates/hooks/agent-guard.mjs +116 -0
  64. package/skills/yad-commit/SKILL.md +4 -3
  65. package/skills/yad-connect-design/SKILL.md +7 -4
  66. package/skills/yad-connect-design/references/design-context.md +23 -0
  67. package/skills/yad-connect-design/references/design-registry.md +3 -3
  68. package/skills/yad-connect-repos/SKILL.md +13 -3
  69. package/skills/yad-connect-repos/references/code-context.md +2 -1
  70. package/skills/yad-connect-repos/references/repos-registry.md +2 -1
  71. package/skills/yad-docs-overview/references/pipeline-model.md +2 -2
  72. package/skills/yad-engineer-review/SKILL.md +25 -7
  73. package/skills/yad-engineer-review/references/ship-and-record.md +7 -4
  74. package/skills/yad-epic/SKILL.md +2 -1
  75. package/skills/yad-epic/references/state-schema.md +7 -1
  76. package/skills/yad-guide/SKILL.md +192 -0
  77. package/skills/yad-implement/SKILL.md +14 -0
  78. package/skills/yad-open-pr/SKILL.md +5 -2
  79. package/skills/yad-pair-review/SKILL.md +19 -5
  80. package/skills/yad-pr-template/templates/github/pull_request_template.md +1 -0
  81. package/skills/yad-pr-template/templates/gitlab/merge_request_templates/Default.md +1 -0
  82. package/skills/yad-product-bridge/SKILL.md +32 -13
  83. package/skills/yad-product-bridge/references/bridge.md +6 -3
  84. package/skills/yad-product-bridge/templates/github/yad-gate-sync.yml +2 -2
  85. package/skills/yad-product-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml +1 -1
  86. package/skills/yad-report/SKILL.md +15 -0
  87. package/skills/yad-review-companion/SKILL.md +9 -4
  88. package/skills/yad-review-gate/SKILL.md +13 -9
  89. package/skills/yad-review-gate/references/gating.md +1 -1
  90. package/skills/yad-run/SKILL.md +10 -6
  91. package/skills/yad-run/references/run-loop.md +2 -1
  92. package/skills/yad-spec/SKILL.md +21 -0
  93. package/skills/yad-stories/SKILL.md +22 -0
  94. package/skills/yad-stories/references/story-schema.md +1 -0
  95. package/skills/yad-sync-repos/SKILL.md +2 -1
  96. package/skills/yad-ui/SKILL.md +7 -2
package/cli/migrate.mjs CHANGED
@@ -17,7 +17,7 @@
17
17
  import fs from 'node:fs';
18
18
  import path from 'node:path';
19
19
 
20
- import { ask, c, exists, fail, hand, info, isPlainObject, log, ok, readJSON, warn, writeFileAtomic, writeJSON, writeProductConfig, emitJSON, collectWarning } from './lib.mjs';
20
+ import { ask, c, exists, fail, hand, info, isPlainObject, log, ok, readJSON, warn, writeFileAtomic, writeJSON, writeProductConfig, emitJSON, collectWarning, cpMerge, rmTree } from './lib.mjs';
21
21
  import { err } from './errors.mjs';
22
22
  import {
23
23
  ADVANCE_FROM_AUTOMATION, BACKUP_SUFFIX, DRIVER_FROM_ASSISTANCE, epicFiles, isVerifiedLedger,
@@ -468,23 +468,18 @@ export function planProductMove(root, { verified = false, ci = false, migrations
468
468
  // `copy` is a seam for the tests, which need a copy that fails or corrupts on demand.
469
469
  // `backup: false` is for the gate bot. In CI the old folder is in git history, a `.yad-orig` copy would be
470
470
  // an untracked directory on a throwaway runner, and `yad migrate` is not there to add it to .gitignore.
471
- export function applyProductMove(root, move, { migrations = MIGRATIONS, copy = fs.cpSync, backup: keepBackup = true } = {}) {
471
+ export function applyProductMove(root, move, { migrations = MIGRATIONS, copy = cpMerge, backup: keepBackup = true } = {}) {
472
472
  const from = path.join(root, move.from);
473
473
  const to = path.join(root, move.to);
474
474
  const backup = path.join(root, move.backup);
475
- // The folders under `foundation/` the copy will create, deepest first — computed BEFORE copying.
476
- const made = new Set();
477
- for (const m of move.moves) {
478
- for (let d = path.posix.dirname(m.to); d !== move.to && d !== '.'; d = path.posix.dirname(d)) {
479
- if (!exists(path.join(root, d))) made.add(d);
480
- }
481
- }
482
475
  const toExisted = exists(to);
476
+ const created = []; // every path the copy into `to` made: a failure removes these, and only these
483
477
  try {
484
478
  const before = artifactHash(from, 'discovery/');
485
- if (keepBackup) copy(from, backup, { recursive: true, errorOnExist: true, force: false });
486
- fs.mkdirSync(to, { recursive: true });
487
- copy(from, to, { recursive: true, errorOnExist: true, force: false });
479
+ // Folders are joined and a file that is already there is refused (cpMerge: Node 24's cpSync refuses
480
+ // a folder that exists, even with the user's own files in it).
481
+ if (keepBackup) copy(from, backup);
482
+ copy(from, to, created);
488
483
  if (artifactHash(to, 'discovery/') !== before) {
489
484
  throw new Error(`the copy in ${move.to}/ does not fingerprint like the original`);
490
485
  }
@@ -505,17 +500,20 @@ export function applyProductMove(root, move, { migrations = MIGRATIONS, copy = f
505
500
  writeJSON(file, stamped(obj, version));
506
501
  }
507
502
  } catch (e) {
503
+ // rmTree: a folder this copy made may carry a read-only mode copied from the source.
508
504
  if (!toExisted) {
509
- fs.rmSync(to, { recursive: true, force: true });
505
+ rmTree(to);
510
506
  } else {
511
- for (const m of move.moves) fs.rmSync(path.join(root, m.to), { force: true });
512
- for (const d of [...made].sort((a, b) => b.length - a.length)) fs.rmSync(path.join(root, d), { recursive: true, force: true });
507
+ // Only what this copy made: a file that came into foundation/ after the plan is the user's, and stays.
508
+ // Its folders are opened first: a file inside a read-only folder it made goes before that folder does.
509
+ for (const p of created) { try { if (fs.lstatSync(p).isDirectory()) fs.chmodSync(p, 0o700); } catch { /* gone */ } }
510
+ for (const p of [...created].reverse()) rmTree(p);
513
511
  }
514
512
  // Only a backup THIS run made. Without one, the path may still hold an earlier run's copy — the user's.
515
- if (keepBackup) fs.rmSync(backup, { recursive: true, force: true });
513
+ if (keepBackup) rmTree(backup);
516
514
  throw new Error(`nothing was moved — ${e.message}`, { cause: e });
517
515
  }
518
- fs.rmSync(from, { recursive: true, force: true });
516
+ rmTree(from);
519
517
  return productMoveFiles(move);
520
518
  }
521
519
 
@@ -1010,7 +1008,7 @@ function printNotRenamedHere(root) {
1010
1008
  // which means no backup, no row in the report, and a preview that under-reports what an apply does. It
1011
1009
  // would also be free to overwrite the one file the same run had just declared corrupt or newer than
1012
1010
  // this engine. What shape a file is in is recorded in that file, which is the whole point of rule 1.
1013
- export async function runMigrate(root, { apply = false, json = false, keep = null } = {}, { migrations = MIGRATIONS, copy = fs.cpSync, choose = null } = {}) {
1011
+ export async function runMigrate(root, { apply = false, json = false, keep = null } = {}, { migrations = MIGRATIONS, copy = cpMerge, choose = null } = {}) {
1014
1012
  if (keep != null && !KEEP_CHOICES.includes(keep)) {
1015
1013
  throw err('YAD-STATE-008', `--keep takes product or hub, not "${keep}"`, '`--keep product` keeps .sdlc/product.json (and each product-prs.json); `--keep hub` keeps the old names');
1016
1014
  }
@@ -1042,7 +1040,7 @@ export async function runMigrate(root, { apply = false, json = false, keep = nul
1042
1040
  // way to commit it is named: a drift there came from a hand edit that got past the guard already.
1043
1041
  const ciOwnedSettled = plan.verified ? settledFiles.filter((f) => !f.startsWith('.sdlc/')) : [];
1044
1042
  if (ciOwnedSettled.length) {
1045
- warn(`${ciOwnedSettled.join(', ')} ${ciOwnedSettled.length === 1 ? 'is' : 'are'} CI-owned on this verified Product: the ledger-guard check refuses a hand commit of ${ciOwnedSettled.length === 1 ? 'it' : 'them'} — commit the repair with \`yad commit --manual --reason "<why>" --type chore -m "<subject>"\`, which records the reason the check quotes`);
1043
+ warn(`${ciOwnedSettled.join(', ')} ${ciOwnedSettled.length === 1 ? 'is' : 'are'} CI-owned on this verified Product: the ledger-guard check refuses a hand commit of ${ciOwnedSettled.length === 1 ? 'it' : 'them'} — the person commits the repair with \`yad commit --manual --reason "<why>" --type chore -m "<subject>"\` (an AI agent hands it to them, \`!\` in front in Claude Code), which records the reason the check quotes`);
1046
1044
  }
1047
1045
  const move = plan.product?.action === 'move' ? plan.product : null;
1048
1046
  const pending = plan.rows.filter((r) => r.changes);
package/cli/next.mjs CHANGED
@@ -1,6 +1,6 @@
1
1
  // `yad next` — the unified next-step driver. Read-only: it never writes state or acts. It reads the
2
2
  // file ledger and prints the ONE concrete, copy-pasteable next action (and a one-line why), so a user
3
- // never has to remember which of the 38 skills / gate commands comes next. "Guide, don't act" — the
3
+ // never has to remember which of the 39 skills / gate commands comes next. "Guide, don't act" — the
4
4
  // Shape still never auto-advances. Once an epic is `ready-for-build`, it reads each story's
5
5
  // build-state and prints the next BUILD sub-step per repo (spec → tasks → implement → checks → engineer-review)
6
6
  // plus the remaining chain — so Build is guided too, not just hinted at.
package/cli/openpr.mjs CHANGED
@@ -7,7 +7,7 @@ import fs from 'node:fs';
7
7
  import { c, log, ok, info, warn, hand, fail, run, exists, readJSON } from './lib.mjs';
8
8
  import { PROJECT_FILES , productConfigPath, settingsEditHint } from './manifest.mjs';
9
9
  import {
10
- detectPlatform, createPr, platformLogin, resolveBaseBranch, prNumberFromUrl,
10
+ detectPlatform, createPr, platformLogin, resolveBaseBranch, prNumberFromUrl, editPrBody,
11
11
  } from './platform.mjs';
12
12
  import { taskFromBranch } from './commit.mjs';
13
13
  import { parseReviewBranch, artifactFromBase, gateCapFor, capLimit, peopleWord, gateRuleSum, gateRuleEnforced, legacyLogins } from './epic-state.mjs';
@@ -22,6 +22,7 @@ import { autoOpenCheck, recordAutoOpen, branchTasks, rangeTasks, groupWarnings }
22
22
  import { productDriftError } from './epic-state.mjs';
23
23
  import { err } from './errors.mjs';
24
24
  import { recordActor } from './skip.mjs';
25
+ import { previewLine, previewPattern, fillPattern, needs } from './preview.mjs';
25
26
 
26
27
  // Resolve the target code repo: --repo <name> from the registry, else --dir, else cwd. `product` (E80) is
27
28
  // the Product found from a code repo beside it: the registry is read there, and a repo run without
@@ -81,7 +82,7 @@ function codeTaskTemplate(platform) {
81
82
  }
82
83
  }
83
84
 
84
- export function templateBody(repoRoot, platform, { task, summary, risk, contract, domains, stage }) {
85
+ export function templateBody(repoRoot, platform, { task, summary, risk, contract, domains, stage, preview }) {
85
86
  // product-tooling: the Product's own template is artifact-review — use the bundled code-task template so the
86
87
  // body matches the shape the Product `pr-template` gate demands for a non-review head.
87
88
  let base;
@@ -100,7 +101,9 @@ export function templateBody(repoRoot, platform, { task, summary, risk, contract
100
101
  // Fill the obvious fields; leave the rest of the committed template intact for the author.
101
102
  // Function replacers (not string replacements) so a `$` in interpolated free text — a commit-derived
102
103
  // summary or a repo name — is inserted verbatim, never read as a `$1`/`$&` replacement token.
103
- let out = base
104
+ // The Preview line first, while the template is the only text: the summary, inserted below, is
105
+ // free text from the commit and may hold a `## Testing` of its own.
106
+ let out = (preview != null ? withPreviewLine(base, preview) : base)
104
107
  .replace(/EP-<slug>-S0N-T0N/g, () => task || 'EP-<slug>-S0N-T0N')
105
108
  .replace(/specs\/EP-<slug>-S0N\//g, () => `specs/${story || 'EP-<slug>-S0N'}/`)
106
109
  .replace(/(\*\*Risk level:\*\*)\s*\w+/i, (_m, g1) => `${g1} ${risk}`)
@@ -114,6 +117,24 @@ export function templateBody(repoRoot, platform, { task, summary, risk, contract
114
117
  return out;
115
118
  }
116
119
 
120
+ // The PR/MR description with its Preview line set (#359), looked for only in the `## Testing` section
121
+ // (the Summary, taken from the commit, may hold a line of its own that reads the same): the template's
122
+ // `**Preview:**` line there, else a line added at the top of that section (a template committed before
123
+ // #359). A template with no `## Testing` is the team's own shape and is left as it is.
124
+ export function withPreviewLine(body, preview) {
125
+ const eol = body.includes('\r\n') ? '\r\n' : '\n';
126
+ const head = /^## Testing[ \t]*\r?\n/m.exec(body);
127
+ if (!head) return body;
128
+ const start = head.index + head[0].length;
129
+ const next = body.slice(start).search(/^## /m);
130
+ const end = next < 0 ? body.length : start + next;
131
+ const section = body.slice(start, end);
132
+ const line = /^([-*][ \t]+)?(\*\*Preview:\*\*)[^\r\n]*/m;
133
+ if (line.test(section)) return body.slice(0, start) + section.replace(line, (_m, b, g) => `${b || ''}${g} ${preview}`) + body.slice(end);
134
+ const lead = /^(?:<!--[\s\S]*?-->[ \t]*\r?\n)?/.exec(section)[0];
135
+ return `${body.slice(0, start)}${lead}- **Preview:** ${preview}${eol}${section.slice(lead.length)}${body.slice(end)}`;
136
+ }
137
+
117
138
  // E66 — how many approvers this PR asks for, printed once it is open: the body's own level and contract
118
139
  // answer (what `--risk` / `--contract-change` put there), and the risk map on the BASE branch — a change
119
140
  // touching a `high` directory adds the high step. The largest step wins, so the map can raise what the
@@ -389,9 +410,13 @@ export async function runOpenPr(root, opts = {}) {
389
410
  .join('\n')
390
411
  .trim();
391
412
  const summary = [subjectText, bodyText].filter(Boolean).join('\n\n') || undefined;
392
- const body = templateBody(repoRoot, platform, {
393
- task: bodyTask, summary, risk: opts.risk || 'low', contract: !!opts.contractChange, domains: meta?.name, stage,
394
- });
413
+ // The Preview line (#359), on a code task only: the repo's pattern filled now, or a note. A pattern
414
+ // that needs the PR number is filled once the PR exists (below).
415
+ const pp = stage === 'code-repo' ? previewPattern(meta) : {};
416
+ const preview = stage === 'code-repo' ? previewLine(meta, { branch }) : undefined;
417
+ if (pp.problems) warn(`this repo's preview_url pattern cannot be used: it ${pp.problems.join('; ')} — set it again with \`yad repo preview <repo> <pattern>\``);
418
+ const bodyOpts = { task: bodyTask, summary, risk: opts.risk || 'low', contract: !!opts.contractChange, domains: meta?.name, stage };
419
+ const body = templateBody(repoRoot, platform, { ...bodyOpts, preview });
395
420
 
396
421
  // Assignee = the committer: `@me` on GitHub (buildPrArgs sends it when no assignee is named, and `gh`
397
422
  // resolves it on the repo's own host), the login `glab` reports on GitLab. No reviewers are requested (E62): the roster that named them is gone. The team requests them
@@ -405,6 +430,21 @@ export async function runOpenPr(root, opts = {}) {
405
430
  const r = creator(platform, { title, body, base: baseBranch, head: branch, assignees, cwd: repoRoot });
406
431
  if (!r.ok) { fail(`could not open PR/MR — ${r.reason || 'unknown'}`); process.exitCode = 1; return; }
407
432
  ok(`opened ${r.url}`);
433
+ // A {pr} pattern can only be filled now the PR has a number: the description is edited once. The PR
434
+ // is open whatever happens here — a failed edit is said, never a failure.
435
+ const pat = pp.pattern || null;
436
+ if (pat && needs(pat, 'pr')) {
437
+ const n = Number(prNumberFromUrl(r.url)) || null;
438
+ const url = n ? fillPattern(pat, { pr: n, branch, repo: meta?.name }) : null;
439
+ // The same body, built again with the address: only the Preview line can differ.
440
+ const filled = url ? templateBody(repoRoot, platform, { ...bodyOpts, preview: `<${url}>` }) : null;
441
+ if (url && filled === body) info(`this repo's PR/MR template has no ## Testing section, so the preview address was not written: ${url}`);
442
+ else if (url) {
443
+ const edit = (opts.editBody || editPrBody)(platform, n, filled, { cwd: repoRoot });
444
+ if (edit?.ok) ok(`preview ${url}`);
445
+ else warn(`the PR/MR is open, but its Preview line could not be filled (${String(edit?.reason || 'unknown').split('\n')[0]}) — the preview should be at ${url}`);
446
+ } else warn('the PR/MR is open, but its number could not be read from the URL, so the Preview line was left unfilled (`yad review context --pr <n>` gives the address)');
447
+ }
408
448
  if (auto) {
409
449
  // The PR is open whatever happens next: a record that cannot be written is said, never a failure.
410
450
  try {