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/doctor.mjs CHANGED
@@ -3,11 +3,12 @@
3
3
  // real repos), shape (what schemaVersion the files are on vs the engine), epics (each ledger loads),
4
4
  // and threads (feature-thread lineage). Pure reporting: exit 1 on any FAIL, 0 with warnings.
5
5
  // `--json` emits the checks for CI / bug reports.
6
+ import os from 'node:os';
6
7
  import path from 'node:path';
7
8
  import fs from 'node:fs';
8
- import { c, log, ok, info, warn, fail, hand, run, has, exists, isPlainObject, readJSON, readJSONStrict, emitJSON, asArg } from './lib.mjs';
9
+ import { c, log, ok, info, warn, fail, hand, run, has, exists, isPlainObject, readJSON, readJSONStrict, emitJSON, asArg, nodeSupport, nodeEndOfLife, NODE_FLOOR, NODE_SUPPORTED } from './lib.mjs';
9
10
  import { VERSION, BACKUP_SUFFIX, MIRRORED_FILES, mirrorDrift, PROJECT_FILES, MODULE_CONFIG, epicFiles, DESIGN_TOOLS, TESTING_TOOLS, LEARNING_TOOLS, HOOK_ADAPTERS, CAPTURE_ADAPTERS, HOOK_WIRING, CAPTURE_WIRING, PROTECTION_GUIDE_URL, isVerifiedLedger , productConfigPath, settingsEditHint, PRODUCT_LINK, ADVANCE_FROM_AUTOMATION, DRIVER_FROM_ASSISTANCE } from './manifest.mjs';
10
- import { mergeHookSettings, hookMatcherFires, ideTargetsFor, safeIdeTargetStateFor, hookScriptReady, miswiredGuardCommand, gitHookState, legacyModuleActions, legacyProductActions, renamedNameHits, PRODUCT_CHECK_WORKFLOWS, productProfileEffect, workflowsPassingProduct, productGateBlockers, oldProfileAdvice, gateProfileFix } from './plan.mjs';
11
+ import { mergeHookSettings, hookMatcherFires, ideTargetsFor, agentFilesState, safeIdeTargetStateFor, hookScriptReady, miswiredGuardCommand, gitHookState, legacyModuleActions, legacyProductActions, renamedNameHits, PRODUCT_CHECK_WORKFLOWS, productProfileEffect, workflowsPassingProduct, productGateBlockers, oldProfileAdvice, gateProfileFix } from './plan.mjs';
11
12
  import { hasSiblingRepo, workspaceFileState, WORKSPACE_FILE } from './find-product.mjs';
12
13
  import { planMigration } from './migrate.mjs';
13
14
  import { ACTION_DIALS, ADVANCE_VALUES, isGateStep, killSwitchOn, loadAutomation, stepDef as catalogueStep, loadLedger, owedSteps, epicIds, epicRel, epicRoot, FOUNDATION_DIR, FOUNDATION_EPIC, DISCOVERY_EPIC, staleFoundationGuards, unwrittenSections, artifactBase, artifactAgrees, epicStories, laneStarted, isValidEpicId, epicLineage, isGenesisType, readFrontmatter, resolveThread, stateInvariants, contractSurfaceHash, doneStepUnapproved, workItemType, WORK_ITEM_TYPES, themeOf, themeKey, stepPhase, stepDef, matchLifecycleProfile, lifecycleProfile, LIFECYCLE_PROFILES, SENTINELS, normalizeBindings, stepsReadingBinding, optionalStepsFor, isSkippableStep, recordedRouteDisagrees, isPassed, stepStatus, claimsSkipped, STEP_STATES, isStepRecord, RECORDED_STEP_STATES, productDriftPairs } from './epic-state.mjs';
@@ -29,6 +30,10 @@ import { productGit, resolveDefaultBranch } from './productcommit.mjs';
29
30
  import { readOwners } from './owners.mjs';
30
31
  import { readMembers, judgedMemberFiles } from './members.mjs';
31
32
  import { loadChoices, readToolboxFile } from './toolbox.mjs';
33
+ import { signingDoctorLine } from './signing.mjs';
34
+ import { nodePins, satisfies, nodeFix, dockerReasons, dockerState, glabConfigs } from './machine.mjs';
35
+ import { allStoryFrames, FRAMES_KEY } from './story-frames.mjs';
36
+ import { previewPattern, PREVIEW_KEY } from './preview.mjs';
32
37
 
33
38
  // A registered path doctor may run git in (E81): a checkout the judgement accepts — never a refused
34
39
  // entry (git run in a folder the Product shaped as a repo reads its `config`, which can run a command),
@@ -39,7 +44,7 @@ const isCheckout = (root, repo) => runnable(judgeRepo(root, repo));
39
44
  // `;`, `|`, `$(` or start a path part with `-` (E81 review 11), so only a plain one is printed.
40
45
  const branchArg = (b) => (typeof b === 'string' && /^\w[\w./-]*$/.test(b) && !b.includes('..') ? b : '<default-branch>');
41
46
 
42
- const MIN_NODE = 18;
47
+ const MIN_NODE = NODE_FLOOR;
43
48
 
44
49
  // Solo mode (a lone developer): approval waived, merge + resolved threads still gate. Persisted in
45
50
  // hub.json. Mirrors gate.mjs / next.mjs.
@@ -84,10 +89,12 @@ export function hasBash({ platform = process.platform, env = process.env, runner
84
89
  return where.stdout.split(/\r?\n/).some((gitExe) => exists(path.join(path.dirname(path.dirname(gitExe.trim())), 'bin', 'bash.exe')));
85
90
  }
86
91
 
87
- export function envChecks(checks) {
88
- const major = Number(process.versions.node.split('.')[0]);
89
- if (major >= MIN_NODE) check(checks, 'node', 'environment', 'ok', `node ${process.versions.node}`);
90
- else check(checks, 'node', 'environment', 'fail', `node ${process.versions.node} is below the supported range [YAD-ENV-003]`, `install Node.js >= ${MIN_NODE}`);
92
+ export function envChecks(checks, { nodeVersion = process.versions.node } = {}) {
93
+ const support = nodeSupport(nodeVersion);
94
+ if (support === 'ok') check(checks, 'node', 'environment', 'ok', `node ${nodeVersion}`);
95
+ // E161: end of life still runs yadflow 4, so a warning, not a failure.
96
+ else if (support === 'end-of-life') check(checks, 'node', 'environment', 'warn', `${nodeEndOfLife(nodeVersion)} [YAD-ENV-004]`, `install Node.js ${NODE_SUPPORTED} or newer (an LTS line)`);
97
+ else check(checks, 'node', 'environment', 'fail', `node ${nodeVersion} is below the supported range [YAD-ENV-003]`, `install Node.js ${NODE_SUPPORTED} or newer (yadflow 4 runs on ${MIN_NODE} and later)`);
91
98
 
92
99
  if (has('git')) check(checks, 'git', 'environment', 'ok', 'git present');
93
100
  else check(checks, 'git', 'environment', 'fail', 'git not found on PATH [YAD-ENV-001]', 'install git — every yad command needs it');
@@ -100,6 +107,67 @@ export function envChecks(checks) {
100
107
  }
101
108
  }
102
109
 
110
+ // E160a: whether commits made here are signed — this machine's git config only, so doctor makes no network
111
+ // call for it. `yad signing check` reads the account too.
112
+ export function signingChecks(checks, root) {
113
+ const line = signingDoctorLine(root);
114
+ check(checks, 'signing', 'environment', line.status, line.message, line.hint, { alwaysHint: true });
115
+ }
116
+
117
+ // #352 — the machine setup local work depends on (cli/machine.mjs): the active Node against each repo's
118
+ // pinned version, Docker where a repo asks for it, and duplicate glab config files. The Product folder and
119
+ // every registered repo cloned here are read; the rest is not this machine's to judge.
120
+ export function machineChecks(checks, root, { nodeVersion = process.versions.node, env = process.env, home = os.homedir(), platform = process.platform, runner } = {}) {
121
+ const tilde = (p) => (p.startsWith(home + path.sep) ? `~${p.slice(home.length)}` : p);
122
+ const folders = [];
123
+ if (exists(productConfigPath(root))) folders.push({ name: 'the Product', dir: root, id: 'product' });
124
+ const registry = readJSON(path.join(root, PROJECT_FILES.reposRegistry), { repos: [] });
125
+ for (const repo of Array.isArray(registry?.repos) ? registry.repos : []) {
126
+ if (!repo || typeof repo.name !== 'string' || typeof repo.path !== 'string' || !repo.path) continue;
127
+ const dir = path.resolve(root, repo.path);
128
+ if (path.resolve(dir) === path.resolve(root) || !isCheckout(root, repo)) continue;
129
+ folders.push({ name: forTerminal(repo.name), dir, id: `repo:${forTerminal(repo.name)}` });
130
+ }
131
+
132
+ // Node: one warning per folder with the pins the running Node does not meet; one ok line when every pin
133
+ // read is met. A pin yad cannot read as a version is counted as skipped, never judged.
134
+ let read = 0;
135
+ let skipped = 0;
136
+ let wrong = 0;
137
+ for (const { name, dir, id } of folders) {
138
+ const unmet = [];
139
+ for (const { source, want } of nodePins(dir)) {
140
+ const meets = satisfies(nodeVersion, want);
141
+ if (meets === null) { skipped += 1; continue; }
142
+ read += 1;
143
+ if (!meets) unmet.push({ source, want });
144
+ }
145
+ if (!unmet.length) continue;
146
+ wrong += 1;
147
+ check(checks, `node-version:${id}`, 'environment', 'warn',
148
+ `node ${nodeVersion} does not meet what ${name} pins: ${unmet.map((u) => `${forTerminal(u.want)} (${u.source})`).join(', ')}`,
149
+ `${nodeFix(unmet[0].want, { env, home })} — the Node that runs yad is the active one (your version manager's default in a new shell)`);
150
+ }
151
+ if (read && !wrong) check(checks, 'node-version', 'environment', 'ok', `node ${nodeVersion} meets every Node version the repos pin (${read} read${skipped ? `, ${skipped} not a version yad reads` : ''})`);
152
+
153
+ // Docker: asked only where a repo names it.
154
+ const needs = folders.map((f) => ({ ...f, why: dockerReasons(f.dir) })).filter((f) => f.why.length);
155
+ if (needs.length) {
156
+ const who = needs.map((f) => `${f.name} (${f.why.join('; ')})`).join(', ');
157
+ const state = dockerState(runner ? { runner } : {});
158
+ if (state === 'running') check(checks, 'docker', 'environment', 'ok', `Docker is running, as ${who} needs`);
159
+ else check(checks, 'docker', 'environment', 'warn', state === 'missing' ? `Docker is not installed, and ${who} asks for it` : `Docker is not running, and ${who} asks for it`,
160
+ state === 'missing' ? 'install Docker (Docker Desktop, or the docker engine), start it, then run those local checks again' : 'start Docker (Docker Desktop, or the docker service), then run those local checks again — the CI runs them either way');
161
+ }
162
+
163
+ // glab: more than one config file.
164
+ const confs = glabConfigs({ env, home, platform });
165
+ if (confs.length > 1) {
166
+ check(checks, 'glab-config', 'environment', 'warn', `glab has ${confs.length} config files: ${confs.map((f) => forTerminal(tilde(f))).join(', ')}`,
167
+ 'glab reads only one of them and ignores the other (a login saved there is not used), and warns about it on every run, which also breaks JSON for any tool that reads glab\'s output and errors together — keep the file glab\'s warning says it uses, copy into it any host it lacks from the other, then delete the other');
168
+ }
169
+ }
170
+
103
171
  // `headCount` is a count of people the caller already read (E74); the CLI passes none, a test passes one.
104
172
  export function projectChecks(checks, root, { headCount = null } = {}) {
105
173
  const productPath = productConfigPath(root);
@@ -452,6 +520,7 @@ export function projectChecks(checks, root, { headCount = null } = {}) {
452
520
  // `project` check added after the `shape` section prints the word "project" a second time.
453
521
  skillBindingChecks(checks, root);
454
522
  toolboxFileChecks(checks, root);
523
+ agentFileChecks(checks, root);
455
524
 
456
525
  // repos.json: parse + every entry is a live git repo; staleness vs syncedHead
457
526
  let registry = { repos: [] };
@@ -502,6 +571,7 @@ export function projectChecks(checks, root, { headCount = null } = {}) {
502
571
  else check(checks, `repo:${repo.name}`, 'project', 'ok', `${nm}: git repo, context fresh`);
503
572
  }
504
573
  if (!registry.repos.length) check(checks, 'repos', 'project', 'warn', 'no code repos registered', 'run `yad setup` to connect one');
574
+ previewChecks(checks, repoEntries);
505
575
  // Per-repo owners went with the roster (E62). Named only where a repo actually lists someone: every
506
576
  // repo an older setup connected carries an EMPTY `domain_owner`, which says nothing.
507
577
  const owned = repoEntries.filter((r) => (Array.isArray(r.domain_owners) && r.domain_owners.length) || (typeof r.domain_owner === 'string' && r.domain_owner));
@@ -1592,6 +1662,35 @@ export function themeChecks(checks, root) {
1592
1662
  }
1593
1663
  }
1594
1664
 
1665
+ // #354 — the design frames each story records (`design-frames: [id, …]`). The rule is `frameFindings` in
1666
+ // cli/story-frames.mjs, the same one `yad story frames` prints, and every finding is a warning there too,
1667
+ // so the two never disagree. No row at all when no story records frames: most Products have no design
1668
+ // tool, and a line saying so on every run would teach people to skip the section.
1669
+ export function storyFrameChecks(checks, root) {
1670
+ const epicsDir = path.join(root, 'epics');
1671
+ if (!exists(epicsDir)) return;
1672
+ const stories = allStoryFrames(root, epicIds(root).sort());
1673
+ if (!stories.length) return;
1674
+ const problems = stories.flatMap((s) => s.findings.map((f) => `${forTerminal(s.story)}: ${f.message}`));
1675
+ if (!problems.length) {
1676
+ const withFrames = stories.filter((s) => s.frames > 0).length;
1677
+ const noScreens = stories.length - withFrames;
1678
+ const parts = [
1679
+ ...(withFrames ? [`${withFrames} story(ies) record design frames, and every frame ID is in its epic's design-links.json`] : []),
1680
+ ...(noScreens ? [`${noScreens} story(ies) say they have no screens (\`${FRAMES_KEY}: []\`)`] : []),
1681
+ ];
1682
+ check(checks, 'stories:design-frames', 'shape', 'ok', parts.join('; '));
1683
+ return;
1684
+ }
1685
+ const shownN = 3;
1686
+ const list = `${problems.slice(0, shownN).join('; ')}${problems.length > shownN ? ` (+${problems.length - shownN} more)` : ''}`;
1687
+ check(
1688
+ checks, 'stories:design-frames', 'shape', 'warn',
1689
+ `${problems.length} problem(s) with the design frames stories record: ${list}`,
1690
+ `run \`yad story frames <story>\` for one story's frames and findings, and rename a story file whose name is not \`<epic>-S<n>.md\` (the command cannot read it). Fixing \`${FRAMES_KEY}\` changes the story file, so a stories review that already passed must approve it again`,
1691
+ );
1692
+ }
1693
+
1595
1694
  // A project's chain against the step catalogue (E4). `phaseChecks` below asks whether a step id is
1596
1695
  // KNOWN; this asks whether a known step is set up the way the catalogue says it is.
1597
1696
  //
@@ -2245,6 +2344,27 @@ function profileBindingChecks(checks, rel, profiles) {
2245
2344
  return bound;
2246
2345
  }
2247
2346
 
2347
+ // E158: the rules block an AI agent reads first, in AGENTS.md (and CLAUDE.md importing it, for Claude Code).
2348
+ // Only the Product's own files: a connected repo's short block is `yad check`'s to report.
2349
+ export function agentFileChecks(checks, root) {
2350
+ let files;
2351
+ try { files = agentFilesState(root); } catch (e) {
2352
+ check(checks, 'agent-files', 'project', 'warn', `the yadflow rules for AI agents could not be checked: ${e?.message || e}`, 'run `yad check` to see why');
2353
+ return;
2354
+ }
2355
+ const bad = files.filter((f) => f.state === 'refused' || f.state === 'unreadable');
2356
+ const behind = files.filter((f) => f.state === 'missing' || f.state === 'outdated');
2357
+ if (bad.length) {
2358
+ check(checks, 'agent-files', 'project', 'warn', `${bad.map((f) => `${f.file}: ${f.refused}`).join('; ')} — the yadflow rules for AI agents are not written there`,
2359
+ 'fix the markers by hand (or delete both, to have the block added again), then run `yad check --fix`');
2360
+ } else if (behind.length) {
2361
+ check(checks, 'agent-files', 'project', 'warn', `${behind.map((f) => (f.state === 'outdated' ? `${f.file} has an older yadflow rules block` : f.exists ? `${f.file} has no yadflow rules block` : `${f.file} is missing`)).join('; ')} — an AI agent may not follow the rules`,
2362
+ 'run `yad update --open-pr` (or `yad check --fix`) to write it; your own text in the file is kept');
2363
+ } else {
2364
+ check(checks, 'agent-files', 'project', 'ok', `${files.map((f) => f.file).join(' and ')}: the yadflow rules for AI agents are current`);
2365
+ }
2366
+ }
2367
+
2248
2368
  // `.sdlc/toolbox.json`: which toolbox tools this Product uses or skips, and its own tools (E86). Absent is
2249
2369
  // the normal case. THE FILE ONLY: whether a tool is installed is `yad toolbox check`'s answer, and a
2250
2370
  // missing tool is never a doctor line (decided with E86 — no tool is required). A broken file fails, as
@@ -2685,6 +2805,8 @@ export function indexChecks(checks, root) {
2685
2805
  export function collectDoctor(root, { headCount = null } = {}) {
2686
2806
  const checks = [];
2687
2807
  envChecks(checks);
2808
+ signingChecks(checks, root);
2809
+ machineChecks(checks, root);
2688
2810
  projectChecks(checks, root, { headCount });
2689
2811
  riskMapChecks(checks, root);
2690
2812
  codeownersChecks(checks, root);
@@ -2699,6 +2821,7 @@ export function collectDoctor(root, { headCount = null } = {}) {
2699
2821
  legacyModuleChecks(checks, root);
2700
2822
  typeChecks(checks, root);
2701
2823
  themeChecks(checks, root);
2824
+ storyFrameChecks(checks, root);
2702
2825
  catalogueChecks(checks, root);
2703
2826
  profileChecks(checks, root);
2704
2827
  skipChecks(checks, root);
@@ -2936,6 +3059,9 @@ function gitHookCheck(root, checks) {
2936
3059
  } else if (st.state === 'outdated' && st.why === 'not-executable') {
2937
3060
  check(checks, 'git-hook', 'project', 'warn', `git pre-commit ledger guard installed but not executable (${where}) — git skips it`,
2938
3061
  'run `yad check --fix`, which restores the execute bit');
3062
+ } else if (st.state === 'outdated' && st.why === 'earlier') {
3063
+ check(checks, 'git-hook', 'project', 'warn', `git pre-commit ledger guard out of date (${where}) — written by an earlier yad version and not edited since`,
3064
+ 'run `yad check --fix` — it replaces it without saving a copy');
2939
3065
  } else if (st.state === 'outdated') {
2940
3066
  check(checks, 'git-hook', 'project', 'warn', `git pre-commit ledger guard out of date (${where})`,
2941
3067
  'run `yad check --fix` — it saves the current file beside it before replacing it');
@@ -2943,3 +3069,18 @@ function gitHookCheck(root, checks) {
2943
3069
  check(checks, 'git-hook', 'project', 'ok', `git pre-commit ledger guard installed in this clone (${where})`);
2944
3070
  }
2945
3071
  }
3072
+
3073
+ // The preview address patterns (#359), by the same rule `yad repo preview` writes with. Said only when
3074
+ // some repo records one: a repo with no pattern is the normal case, and its review says "locally only".
3075
+ export function previewChecks(checks, repoEntries) {
3076
+ const withPreview = repoEntries.filter((r) => PREVIEW_KEY in r && r[PREVIEW_KEY] != null);
3077
+ if (!withPreview.length) return;
3078
+ const bad = withPreview.map((r) => ({ r, problems: previewPattern(r).problems })).filter((x) => x.problems);
3079
+ if (bad.length) {
3080
+ check(checks, 'repos:preview', 'project', 'warn',
3081
+ `${bad.length} preview address pattern${bad.length > 1 ? 's' : ''} in ${PROJECT_FILES.reposRegistry} cannot be used: ${bad.map((x) => `${forTerminal(x.r.name || '(unnamed)')}: it ${x.problems.join('; ')}`).join(', ')}`,
3082
+ `set ${bad.length > 1 ? 'each' : 'it'} again with \`yad repo preview ${bad.length === 1 ? asArg(bad[0].r.name) : '<name>'} <pattern>\` (or --clear) — until then its review checks the page locally only`);
3083
+ } else {
3084
+ check(checks, 'repos:preview', 'project', 'ok', `${withPreview.length} repo${withPreview.length > 1 ? 's record' : ' records'} a preview address pattern`);
3085
+ }
3086
+ }
@@ -2589,7 +2589,7 @@ export function markInReview(state, step, close = null) {
2589
2589
  // and "what reviews it" were four separate lookups that nothing held together.
2590
2590
  //
2591
2591
  // THE DATA IS IN JSON NOW (E134). The rows are no longer written here: they are built from the shipped
2592
- // lifecycle default, `cli/lifecycle/defaults/1.json`, by `expandSteps` (cli/lifecycle.mjs). In that file
2592
+ // lifecycle default, `cli/lifecycle/defaults/2.json`, by `expandSteps` (cli/lifecycle.mjs). In that file
2593
2593
  // an author step names its gate once (`gate: { riskTags }`) and its gate row is derived from that.
2594
2594
  // The rows, their fields and their order are exactly what this table held before; a test compares them
2595
2595
  // with a frozen copy (`cli/fixtures/lifecycle-v4-catalogue.json`).
@@ -2661,7 +2661,7 @@ export const STEPS = expandSteps(DEFAULT_LIFECYCLE);
2661
2661
  // word is a trap for whoever reads this next; two clearly different names is not.
2662
2662
  //
2663
2663
  // THE DATA IS IN JSON NOW (E134). The profiles are built from the `routes` of the shipped lifecycle
2664
- // default, `cli/lifecycle/defaults/1.json`, by `expandRoutes` (cli/lifecycle.mjs). There, a route lists
2664
+ // default, `cli/lifecycle/defaults/2.json`, by `expandRoutes` (cli/lifecycle.mjs). There, a route lists
2665
2665
  // only its author steps and the engine adds each step's gate; a route's `name` is the `title` here. The
2666
2666
  // default also holds one more route, `lane` — the Build order one story walks in one repo — which is not
2667
2667
  // a profile, because an epic never walks it; it is `BUILD_STEP_ORDER` below. A test compares the
@@ -3338,7 +3338,7 @@ export const skillFields = (ids) => ({
3338
3338
  // So the phase NUMBER is deliberately never printed: "Phase 4" already means something else to anyone
3339
3339
  // who has read those. The name is what is shown.
3340
3340
  //
3341
- // Built from the `phases` of the lifecycle default (`cli/lifecycle/defaults/1.json`, E134) by
3341
+ // Built from the `phases` of the lifecycle default (`cli/lifecycle/defaults/2.json`, E134; the step facts of E157) by
3342
3342
  // `featurePhases`. There each phase also says whether it runs once or in a loop (`runs`, `over`); those
3343
3343
  // fields are not part of this view, which keeps exactly the fields it always had.
3344
3344
  export const PHASES = featurePhases(DEFAULT_LIFECYCLE);
package/cli/errors.mjs CHANGED
@@ -16,6 +16,7 @@ export const CODES = {
16
16
  'YAD-ENV-001': 'git is not installed or not on PATH',
17
17
  'YAD-ENV-002': 'the platform CLI (gh/glab) is missing or not authenticated',
18
18
  'YAD-ENV-003': 'Node.js is older than the supported range (>=18)',
19
+ 'YAD-ENV-004': 'Node.js is end of life (18 to 21): yadflow 4 still runs on it, but it gets no security fixes, and yadflow 5 needs Node 22 or newer',
19
20
  'YAD-STATE-001': 'a ledger/config JSON file exists but does not parse',
20
21
  'YAD-STATE-002': 'a ledger/config JSON file parses but has the wrong shape',
21
22
  'YAD-STATE-003': 'a registered repo path is missing or not a git repository',