yadflow 4.6.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 (136) hide show
  1. package/CHANGELOG.md +259 -0
  2. package/README.md +46 -4
  3. package/bin/commands.mjs +9 -2
  4. package/bin/yad.mjs +309 -30
  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/artifact-status.mjs +88 -20
  10. package/cli/build.mjs +1372 -0
  11. package/cli/checkpoint.mjs +2 -2
  12. package/cli/ci-check.mjs +492 -0
  13. package/cli/commit.mjs +1 -0
  14. package/cli/dial.mjs +21 -1
  15. package/cli/docs.mjs +7 -2
  16. package/cli/doctor.mjs +176 -33
  17. package/cli/epic-state.mjs +360 -12
  18. package/cli/errors.mjs +3 -0
  19. package/cli/find-product.mjs +36 -2
  20. package/cli/fold.mjs +9 -5
  21. package/cli/gate-local.mjs +9 -1
  22. package/cli/gate.mjs +364 -22
  23. package/cli/guide.mjs +549 -0
  24. package/cli/history.mjs +22 -2
  25. package/cli/hook.mjs +35 -4
  26. package/cli/index-command.mjs +2 -2
  27. package/cli/ledger.mjs +60 -0
  28. package/cli/lib.mjs +46 -0
  29. package/cli/lifecycle/defaults/2.json +124 -0
  30. package/cli/lifecycle/lifecycle.schema.json +5 -2
  31. package/cli/lifecycle.mjs +16 -3
  32. package/cli/manifest.mjs +75 -0
  33. package/cli/marked-block.mjs +48 -0
  34. package/cli/members.mjs +19 -5
  35. package/cli/migrate.mjs +17 -19
  36. package/cli/next.mjs +35 -12
  37. package/cli/openpr.mjs +81 -5
  38. package/cli/plan.mjs +326 -22
  39. package/cli/platform.mjs +21 -0
  40. package/cli/pr-list.mjs +5 -3
  41. package/cli/product-index.mjs +6 -3
  42. package/cli/product-token.mjs +186 -0
  43. package/cli/productcommit.mjs +33 -0
  44. package/cli/protection.mjs +50 -0
  45. package/cli/recommend.mjs +3 -1
  46. package/cli/reconcile.mjs +187 -26
  47. package/cli/repo-publish.mjs +2 -2
  48. package/cli/report.mjs +62 -14
  49. package/cli/run-checks.mjs +586 -0
  50. package/cli/setup.mjs +244 -25
  51. package/cli/ship-drift.mjs +49 -18
  52. package/cli/signing.mjs +377 -0
  53. package/cli/standup.mjs +1 -1
  54. package/cli/status.mjs +282 -0
  55. package/cli/test-agents-file.mjs +993 -0
  56. package/cli/test-build.mjs +1559 -0
  57. package/cli/test-ci-check.mjs +616 -0
  58. package/cli/test-guide.mjs +1267 -0
  59. package/cli/test-node.mjs +129 -0
  60. package/cli/test-run-checks.mjs +603 -0
  61. package/cli/test-setup-agent.mjs +352 -0
  62. package/cli/test-signing.mjs +524 -0
  63. package/cli/test-worktree.mjs +520 -0
  64. package/cli/thread.mjs +4 -0
  65. package/cli/tidy.mjs +2 -2
  66. package/cli/toolbox.mjs +37 -6
  67. package/cli/update-commit.mjs +313 -11
  68. package/cli/workspace.mjs +38 -10
  69. package/cli/worktree-record.mjs +53 -0
  70. package/cli/worktree.mjs +379 -0
  71. package/package.json +6 -4
  72. package/skills/sdlc/config.yaml +5 -5
  73. package/skills/sdlc/module-help.csv +2 -1
  74. package/skills/yad-backfill/templates/checks/backfill-check.sh +9 -9
  75. package/skills/yad-change/SKILL.md +5 -1
  76. package/skills/yad-checks/SKILL.md +61 -12
  77. package/skills/yad-checks/references/check-gates.md +78 -14
  78. package/skills/yad-checks/templates/checks/build-test-lint.sh +22 -3
  79. package/skills/yad-checks/templates/checks/commit-message.sh +8 -2
  80. package/skills/yad-checks/templates/checks/contract-check.sh +61 -33
  81. package/skills/yad-checks/templates/checks/epic-open.sh +87 -14
  82. package/skills/yad-checks/templates/checks/ledger-guard.sh +3 -3
  83. package/skills/yad-checks/templates/checks/lineage-check.sh +88 -15
  84. package/skills/yad-checks/templates/checks/member-check.mjs +206 -35
  85. package/skills/yad-checks/templates/checks/package-manager.sh +42 -5
  86. package/skills/yad-checks/templates/checks/product-checkout.sh +161 -13
  87. package/skills/yad-checks/templates/checks/reconcile-debt-check.sh +94 -15
  88. package/skills/yad-checks/templates/checks/risk-map-check.sh +2 -2
  89. package/skills/yad-checks/templates/checks/spec-link.sh +63 -4
  90. package/skills/yad-checks/templates/checks/verified-commits.sh +23 -5
  91. package/skills/yad-checks/templates/github/yad-checks.yml +9 -9
  92. package/skills/yad-checks/templates/gitlab/.gitlab-ci.yml +4 -1
  93. package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml +5 -5
  94. package/skills/yad-checks/templates/gitlab/yad-product-checks.gitlab-ci.yml +16 -3
  95. package/skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml +5 -1
  96. package/skills/yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml +5 -1
  97. package/skills/yad-checks/templates/hooks/agent-guard.mjs +116 -0
  98. package/skills/yad-commit/SKILL.md +8 -5
  99. package/skills/yad-connect-repos/SKILL.md +5 -3
  100. package/skills/yad-connect-repos/references/code-context.md +2 -1
  101. package/skills/yad-connect-repos/references/repos-registry.md +2 -1
  102. package/skills/yad-docs/templates/app/package-lock.json +395 -106
  103. package/skills/yad-docs/templates/app/package.json +2 -2
  104. package/skills/yad-docs-overview/references/pipeline-model.md +2 -2
  105. package/skills/yad-engineer-review/SKILL.md +55 -25
  106. package/skills/yad-engineer-review/references/ship-and-record.md +49 -12
  107. package/skills/yad-epic/SKILL.md +2 -1
  108. package/skills/yad-epic/references/state-schema.md +76 -17
  109. package/skills/yad-guide/SKILL.md +192 -0
  110. package/skills/yad-implement/SKILL.md +75 -13
  111. package/skills/yad-implement/references/implement-conventions.md +8 -1
  112. package/skills/yad-implement/templates/.gitmessage +3 -0
  113. package/skills/yad-open-pr/SKILL.md +21 -0
  114. package/skills/yad-pair-review/SKILL.md +14 -5
  115. package/skills/yad-pr-template/SKILL.md +6 -2
  116. package/skills/yad-pr-template/templates/checks/pr-template.sh +85 -4
  117. package/skills/yad-pr-template/templates/checks/pr-title.sh +1 -1
  118. package/skills/yad-pr-template/templates/github/pull_request_template.md +1 -1
  119. package/skills/yad-pr-template/templates/gitlab/merge_request_templates/Default.md +1 -1
  120. package/skills/yad-product-bridge/SKILL.md +44 -12
  121. package/skills/yad-product-bridge/references/bridge.md +11 -5
  122. package/skills/yad-product-bridge/templates/github/yad-gate-sync.yml +2 -2
  123. package/skills/yad-product-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml +9 -4
  124. package/skills/yad-reconcile/SKILL.md +9 -3
  125. package/skills/yad-report/SKILL.md +15 -0
  126. package/skills/yad-review-companion/SKILL.md +5 -3
  127. package/skills/yad-review-gate/SKILL.md +16 -8
  128. package/skills/yad-review-gate/references/gating.md +26 -1
  129. package/skills/yad-run/SKILL.md +61 -33
  130. package/skills/yad-run/references/run-loop.md +44 -22
  131. package/skills/yad-spec/SKILL.md +137 -16
  132. package/skills/yad-spec/references/spec-handoff.md +50 -3
  133. package/skills/yad-status/SKILL.md +7 -0
  134. package/skills/yad-stories/references/story-schema.md +1 -1
  135. package/skills/yad-sync-repos/SKILL.md +2 -1
  136. package/skills/yad-ui/SKILL.md +2 -2
package/cli/doctor.mjs CHANGED
@@ -5,22 +5,23 @@
5
5
  // `--json` emits the checks for CI / bug reports.
6
6
  import path from 'node:path';
7
7
  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';
8
+ 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
9
  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';
10
+ import { mergeHookSettings, hookMatcherFires, ideTargetsFor, agentFilesState, safeIdeTargetStateFor, hookScriptReady, miswiredGuardCommand, gitHookState, legacyModuleActions, legacyProductActions, renamedNameHits, PRODUCT_CHECK_WORKFLOWS, productProfileEffect, workflowsPassingProduct, productGateBlockers, oldProfileAdvice, gateProfileFix } from './plan.mjs';
11
11
  import { hasSiblingRepo, workspaceFileState, WORKSPACE_FILE } from './find-product.mjs';
12
12
  import { planMigration } from './migrate.mjs';
13
- import { 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, acceptedHashes, isStaleHash, 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';
13
+ 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';
14
14
  import { loadDebt } from './thread.mjs';
15
15
  import { readShips } from './ledger.mjs';
16
16
  import { gitHead, insideWorkspace } from './setup.mjs';
17
17
  import { judgeRepo, runnable, shown as forTerminal } from './workspace.mjs';
18
- import { cliFor, hostFromGitUrl, ambiguousLegacyNames, plainHost } from './platform.mjs';
18
+ import { cliFor, hostFromGitUrl, ambiguousLegacyNames, plainHost, detectPlatform } from './platform.mjs';
19
19
  import { legacyLogins, stampLegacyLogins } from './gate.mjs';
20
20
  import { checkRepo } from './riskmap-command.mjs';
21
21
  import { checkCodeowners, codeownersFindings } from './codeowners-command.mjs';
22
22
  import { RISK_MAP_FILE } from './riskmap.mjs';
23
- import { readProtection, protectionLine, protectionJSON, hideAddresses } from './protection.mjs';
23
+ import { readProtection, protectionLine, protectionJSON, hideAddresses, repoPathFromGitUrl, shown } from './protection.mjs';
24
+ import { readTokenPlacement, tokenLine, readExpiringProductTokens, TOKEN_NAME } from './product-token.mjs';
24
25
  import { soloTeamHint, TEAM_CMD } from './people.mjs';
25
26
  import { pagesWorkflowPath, pagesWorkflowFailsOnBuild, wiredPagesPlatform } from './docs.mjs';
26
27
  import { indexFreshness, INDEX_FILE } from './product-index.mjs';
@@ -28,6 +29,7 @@ import { productGit, resolveDefaultBranch } from './productcommit.mjs';
28
29
  import { readOwners } from './owners.mjs';
29
30
  import { readMembers, judgedMemberFiles } from './members.mjs';
30
31
  import { loadChoices, readToolboxFile } from './toolbox.mjs';
32
+ import { signingDoctorLine } from './signing.mjs';
31
33
 
32
34
  // A registered path doctor may run git in (E81): a checkout the judgement accepts — never a refused
33
35
  // entry (git run in a folder the Product shaped as a repo reads its `config`, which can run a command),
@@ -38,7 +40,7 @@ const isCheckout = (root, repo) => runnable(judgeRepo(root, repo));
38
40
  // `;`, `|`, `$(` or start a path part with `-` (E81 review 11), so only a plain one is printed.
39
41
  const branchArg = (b) => (typeof b === 'string' && /^\w[\w./-]*$/.test(b) && !b.includes('..') ? b : '<default-branch>');
40
42
 
41
- const MIN_NODE = 18;
43
+ const MIN_NODE = NODE_FLOOR;
42
44
 
43
45
  // Solo mode (a lone developer): approval waived, merge + resolved threads still gate. Persisted in
44
46
  // hub.json. Mirrors gate.mjs / next.mjs.
@@ -83,10 +85,12 @@ export function hasBash({ platform = process.platform, env = process.env, runner
83
85
  return where.stdout.split(/\r?\n/).some((gitExe) => exists(path.join(path.dirname(path.dirname(gitExe.trim())), 'bin', 'bash.exe')));
84
86
  }
85
87
 
86
- export function envChecks(checks) {
87
- const major = Number(process.versions.node.split('.')[0]);
88
- if (major >= MIN_NODE) check(checks, 'node', 'environment', 'ok', `node ${process.versions.node}`);
89
- else check(checks, 'node', 'environment', 'fail', `node ${process.versions.node} is below the supported range [YAD-ENV-003]`, `install Node.js >= ${MIN_NODE}`);
88
+ export function envChecks(checks, { nodeVersion = process.versions.node } = {}) {
89
+ const support = nodeSupport(nodeVersion);
90
+ if (support === 'ok') check(checks, 'node', 'environment', 'ok', `node ${nodeVersion}`);
91
+ // E161: end of life still runs yadflow 4, so a warning, not a failure.
92
+ 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)`);
93
+ 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)`);
90
94
 
91
95
  if (has('git')) check(checks, 'git', 'environment', 'ok', 'git present');
92
96
  else check(checks, 'git', 'environment', 'fail', 'git not found on PATH [YAD-ENV-001]', 'install git — every yad command needs it');
@@ -99,6 +103,13 @@ export function envChecks(checks) {
99
103
  }
100
104
  }
101
105
 
106
+ // E160a: whether commits made here are signed — this machine's git config only, so doctor makes no network
107
+ // call for it. `yad signing check` reads the account too.
108
+ export function signingChecks(checks, root) {
109
+ const line = signingDoctorLine(root);
110
+ check(checks, 'signing', 'environment', line.status, line.message, line.hint, { alwaysHint: true });
111
+ }
112
+
102
113
  // `headCount` is a count of people the caller already read (E74); the CLI passes none, a test passes one.
103
114
  export function projectChecks(checks, root, { headCount = null } = {}) {
104
115
  const productPath = productConfigPath(root);
@@ -451,6 +462,7 @@ export function projectChecks(checks, root, { headCount = null } = {}) {
451
462
  // `project` check added after the `shape` section prints the word "project" a second time.
452
463
  skillBindingChecks(checks, root);
453
464
  toolboxFileChecks(checks, root);
465
+ agentFileChecks(checks, root);
454
466
 
455
467
  // repos.json: parse + every entry is a live git repo; staleness vs syncedHead
456
468
  let registry = { repos: [] };
@@ -743,39 +755,65 @@ export function projectChecks(checks, root, { headCount = null } = {}) {
743
755
  return { productConfig, registry };
744
756
  }
745
757
 
746
- // GitLab CI runner tags: the wired fragments run docker-image jobs. On instances whose runners are
747
- // all tag-locked (run_untagged: false), an untagged image job matches no runner and sits `pending`
748
- // forever — silently blocking the gates (issue #50). A current fragment carries
749
- // `tags: [$YAD_RUNNER_TAGS]`; warn on any wired GitLab fragment that sets an `image:` but has no
750
- // `tags:` (an old install, or one hand-reverted by a sync). Pure local read — no API calls.
758
+ // GitLab CI runner tags and Node line: the wired fragments run docker-image jobs. On instances whose
759
+ // runners are all tag-locked (run_untagged: false), an untagged image job matches no runner and sits
760
+ // `pending` forever — silently blocking the gates (issue #50). A current fragment carries
761
+ // `tags: [$YAD_RUNNER_TAGS]`; warn on any wired GitLab fragment that sets an `image:` but has no `tags:`
762
+ // (an old install, or one hand-reverted by a sync). A current fragment also takes its Node line from the
763
+ // `YAD_NODE_VERSION` CI/CD variable; one that still names a fixed `node:<n>` image is an install from
764
+ // before that (#364), whose Node line can only be changed by editing a file `yad` rewrites. Pure local
765
+ // read — no API calls, so neither the variables' values nor the runner's executor are known here.
751
766
  export function ciTagsChecks(checks, root, productConfig, registry) {
752
- const untagged = (p) => {
753
- try {
754
- const txt = fs.readFileSync(p, 'utf8');
755
- return /^\s*image:/m.test(txt) && !/^\s*tags:/m.test(txt);
756
- } catch { return false; } // absent fragment is not this check's concern
757
- };
767
+ const read = (p) => { try { return fs.readFileSync(p, 'utf8'); } catch { return null; } }; // absent: not this check's concern
768
+ // A plain update replaces an outdated copy but leaves a hand-edited (`modified`) one alone — and a copy
769
+ // edited to fit a runner is the case #364 is about, so the hint names both (review 1).
770
+ const UPDATE = 'run `yad update` (if `yad check` lists the file as `modified`, move your change into the `YAD_RUNNER_TAGS` / `YAD_NODE_VERSION` CI/CD variables, then run `yad update --overwrite-local` — it replaces every hand-edited managed file, keeping a `.yad-orig` copy of each)';
758
771
  const fragments = [];
759
772
  if (productConfig?.platform === 'gitlab' && isVerifiedLedger(productConfig)) {
760
773
  fragments.push(
761
774
  { scope: 'product', file: '.gitlab/ci/yad-gate-sync.yml', path: path.join(root, '.gitlab/ci/yad-gate-sync.yml') },
762
775
  { scope: 'product', file: '.gitlab/ci/yad-verified-commits.yml', path: path.join(root, '.gitlab/ci/yad-verified-commits.yml') },
763
776
  { scope: 'product', file: '.gitlab/ci/yad-product-checks.yml', path: path.join(root, '.gitlab/ci/yad-product-checks.yml') },
777
+ { scope: 'product', file: '.gitlab/ci/yad-update-guard.yml', path: path.join(root, '.gitlab/ci/yad-update-guard.yml') },
764
778
  // Its old name (E123), while it is still there — `renamed:` says to run `yad update`.
765
779
  { scope: 'product', file: '.gitlab/ci/yad-hub-checks.yml', path: path.join(root, '.gitlab/ci/yad-hub-checks.yml') },
766
780
  );
767
781
  }
782
+ // The Pages job `yad docs sync --wire` writes for a GitLab Pages target. Only that command rewrites it,
783
+ // and only a file that carries its header is ours (a team's own file is left to the team).
784
+ const docsRel = pagesWorkflowPath(wiredPagesPlatform(readJSON(path.join(root, PROJECT_FILES.docsConfig), null)));
785
+ if (docsRel.startsWith('.gitlab/')) {
786
+ fragments.push({ scope: 'product', file: docsRel, path: path.join(root, docsRel), ours: (t) => t.startsWith('# yad-managed — built by `yad docs sync --wire`'),
787
+ fix: 'run `yad docs sync --wire` and commit the file (it rewrites the whole file, so re-apply any change your team made to it)' });
788
+ }
768
789
  for (const repo of Array.isArray(registry?.repos) ? registry.repos : []) {
769
790
  if (!isPlainObject(repo) || repo.platform !== 'gitlab' || !repo.path) continue;
770
- fragments.push({ scope: forTerminal(repo.name), repo: true, file: '.gitlab/ci/yad-checks.yml', path: path.join(path.resolve(root, repo.path), '.gitlab/ci/yad-checks.yml') });
791
+ for (const file of ['.gitlab/ci/yad-checks.yml', '.gitlab/ci/yad-update-guard.yml']) {
792
+ fragments.push({ scope: forTerminal(repo.name), repo: true, file, path: path.join(path.resolve(root, repo.path), file) });
793
+ }
771
794
  }
795
+ // A repo kept at the Product's own root (a monorepo) shares its files: one warning per file (review 1).
796
+ const seen = new Set();
772
797
  for (const f of fragments) {
773
- if (untagged(f.path)) {
798
+ const at = path.resolve(f.path);
799
+ if (seen.has(at)) continue;
800
+ seen.add(at);
801
+ const txt = read(f.path);
802
+ if (txt === null || (f.ours && !f.ours(txt))) continue;
803
+ // The id cannot tell the Product from a repo named `product`; this key can (E124 review 1).
804
+ const extra = { product: f.scope === 'product' && !f.repo };
805
+ if (/^\s*image:/m.test(txt) && !/^\s*tags:/m.test(txt)) {
774
806
  check(checks, `ci-tags:${f.scope}`, 'project', 'warn',
775
807
  `${f.scope}: ${f.file} runs a docker job with no \`tags:\` [YAD-CI-001]`,
776
- 'tag-locked runners (run_untagged: false) will strand it at `pending` — run `yad update`, then set the `YAD_RUNNER_TAGS` CI/CD variable',
777
- // The id cannot tell the Product from a repo named `product`; this key can (E124 review 1).
778
- { product: f.scope === 'product' && !f.repo });
808
+ `tag-locked runners (run_untagged: false) will strand it at \`pending\` — ${f.fix || UPDATE}, then set the \`YAD_RUNNER_TAGS\` CI/CD variable`,
809
+ extra);
810
+ }
811
+ const pinned = txt.match(/^\s*image:\s*["']?node:(\d[\w.-]*)/m);
812
+ if (pinned) {
813
+ check(checks, `ci-node:${f.scope}`, 'project', 'warn',
814
+ `${f.scope}: ${f.file} runs a fixed \`node:${forTerminal(pinned[1])}\` image [YAD-CI-002]`,
815
+ `${f.fix || UPDATE}; the Node line then comes from the \`YAD_NODE_VERSION\` CI/CD variable (default 22), set in project settings so it survives every sync`,
816
+ extra);
779
817
  }
780
818
  }
781
819
  }
@@ -904,16 +942,15 @@ function staleGateCheck(checks, root, epic, ledger, { solo = false } = {}) {
904
942
  if (solo) continue;
905
943
  const records = ledger.approvals.filter((a) => a.step === s.id).length;
906
944
  check(checks, `epic:${epic}:${s.id}:unapproved`, 'epics', 'fail',
907
- `${epic}: ${s.id} is done but holds no approval${records ? ` (${records} record(s), none of them live)` : ''}`,
945
+ `${epic}: ${forTerminal(s.id)} is done but holds no approval${records ? ` (${records} record(s), none of them live)` : ''}`,
908
946
  'the step advanced without the record the gate exists to keep — re-open the review (a fresh PR/MR) and re-approve, or run `yad gate sync` if the approvals are on the PR but never reached the ledger');
909
947
  continue;
910
948
  }
911
- const accepted = acceptedHashes(epicDir, s.artifact);
912
- if (!accepted.length) continue; // nothing to bind to (no locked surface / incomplete set) — not a staleness claim
913
- const live = forStep.filter((a) => !isStaleHash(a.artifactHash, accepted));
914
- if (live.length) continue;
949
+ // The shared rule (#418): nothing to fingerprint is no staleness claim, and one live approval clears it.
950
+ const changed = doneStepUnapproved(epicDir, s, ledger.approvals);
951
+ if (!changed) continue;
915
952
  check(checks, `epic:${epic}:${s.id}:stale`, 'epics', 'warn',
916
- `${epic}: ${s.id} is done, but all ${forStep.length} approval(s) are bound to an older ${s.artifact}`,
953
+ `${epic}: ${forTerminal(s.id)} is done, but all ${changed.count} approval(s) are bound to an older ${forTerminal(s.artifact)}`,
917
954
  'the artifact changed after it was approved — re-open the review (a fresh PR/MR) so the record matches what shipped');
918
955
  }
919
956
  }
@@ -1361,10 +1398,14 @@ export function automationChecks(checks, root) {
1361
1398
  `${rel} lists Build step(s) nothing reads here: ${build.join(', ')}`,
1362
1399
  'a Build step\'s dial is set per lane — `yad dial <epic> <story> --repo <name> <step> --to auto`');
1363
1400
  }
1401
+ for (const [id, v] of Object.entries(a.actions || {})) {
1402
+ if (!ACTION_DIALS.includes(id)) unknown.push(`actions.${id}: not an action this release knows`);
1403
+ else if (!ADVANCE_VALUES.includes(v)) unknown.push(`actions.${id}: ${JSON.stringify(v)} is not human or auto`);
1404
+ }
1364
1405
  if (unknown.length) {
1365
1406
  check(checks, 'automation:unknown', 'project', 'warn',
1366
1407
  `${rel}: ${unknown.slice(0, 3).join('; ')}${unknown.length > 3 ? ` (+${unknown.length - 3} more)` : ''}`,
1367
- 'only `auto` on a Shape author step is read; everything else is ignored');
1408
+ 'only `auto` on a Shape author step, or on an action under `actions` (`open-pr`), is read; everything else is ignored');
1368
1409
  }
1369
1410
  }
1370
1411
  // The switch's OLD home. Before E34 it was `kill_switch: true` in the module config `yad update` installs.
@@ -2215,6 +2256,27 @@ function profileBindingChecks(checks, rel, profiles) {
2215
2256
  return bound;
2216
2257
  }
2217
2258
 
2259
+ // E158: the rules block an AI agent reads first, in AGENTS.md (and CLAUDE.md importing it, for Claude Code).
2260
+ // Only the Product's own files: a connected repo's short block is `yad check`'s to report.
2261
+ export function agentFileChecks(checks, root) {
2262
+ let files;
2263
+ try { files = agentFilesState(root); } catch (e) {
2264
+ 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');
2265
+ return;
2266
+ }
2267
+ const bad = files.filter((f) => f.state === 'refused' || f.state === 'unreadable');
2268
+ const behind = files.filter((f) => f.state === 'missing' || f.state === 'outdated');
2269
+ if (bad.length) {
2270
+ check(checks, 'agent-files', 'project', 'warn', `${bad.map((f) => `${f.file}: ${f.refused}`).join('; ')} — the yadflow rules for AI agents are not written there`,
2271
+ 'fix the markers by hand (or delete both, to have the block added again), then run `yad check --fix`');
2272
+ } else if (behind.length) {
2273
+ 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`,
2274
+ 'run `yad update --open-pr` (or `yad check --fix`) to write it; your own text in the file is kept');
2275
+ } else {
2276
+ check(checks, 'agent-files', 'project', 'ok', `${files.map((f) => f.file).join(' and ')}: the yadflow rules for AI agents are current`);
2277
+ }
2278
+ }
2279
+
2218
2280
  // `.sdlc/toolbox.json`: which toolbox tools this Product uses or skips, and its own tools (E86). Absent is
2219
2281
  // the normal case. THE FILE ONLY: whether a tool is installed is `yad toolbox check`'s answer, and a
2220
2282
  // missing tool is never a doctor line (decided with E86 — no tool is required). A broken file fails, as
@@ -2501,6 +2563,82 @@ export function protectionChecks(checks, root, { runner, env } = {}) {
2501
2563
  }
2502
2564
  }
2503
2565
 
2566
+ // #345 — does each connected code repo's CI get YAD_PRODUCT_TOKEN, the token checks/product-checkout.sh
2567
+ // clones the Product with? Only when the Product names its git_url (otherwise the record names no Product
2568
+ // to clone, and the checkout says so itself), and never for a repo that IS the Product's git repo (a
2569
+ // monorepo reads its Product from the base, with no token). Names only — see cli/product-token.mjs.
2570
+ export function productTokenChecks(checks, root, { runner, env, today } = {}) {
2571
+ const productConfig = readJSON(productConfigPath(root), null);
2572
+ if (!isPlainObject(productConfig) || typeof productConfig.git_url !== 'string' || !productConfig.git_url.trim()) return;
2573
+ const opts = { ...(runner ? { runner } : {}), ...(env ? { env } : {}), authCache: new Map() };
2574
+ const where = (url) => {
2575
+ const host = plainHost(hostFromGitUrl(url || ''));
2576
+ const repo = repoPathFromGitUrl(url || '');
2577
+ return host && repo ? { host, repo: repo.toLowerCase() } : null;
2578
+ };
2579
+ const product = where(productConfig.git_url);
2580
+ const registry = readJSON(path.join(root, PROJECT_FILES.reposRegistry), { repos: [] });
2581
+ const repos = (Array.isArray(registry?.repos) ? registry.repos : []).map((repo, i) => ({ repo, i }))
2582
+ .filter(({ repo }) => isPlainObject(repo) && typeof repo.name === 'string' && repo.name);
2583
+ const urlOf = (repo) => {
2584
+ if (typeof repo.git_url === 'string' && repo.git_url) return repo.git_url;
2585
+ const repoRoot = typeof repo.path === 'string' && repo.path ? path.resolve(root, repo.path) : null;
2586
+ return repoRoot && isCheckout(root, repo) && gitHead(repoRoot) ? (run('git', ['remote', 'get-url', 'origin'], { cwd: repoRoot }).stdout || null) : null;
2587
+ };
2588
+ const listed = repos.map(({ repo, i }) => ({ repo, i, url: urlOf(repo), at: where(urlOf(repo)) }));
2589
+ let checked = 0;
2590
+ const topOf = (dir) => {
2591
+ const r = run('git', ['rev-parse', '--show-toplevel'], { cwd: dir });
2592
+ if (!r.ok || !r.stdout) return null;
2593
+ try { return fs.realpathSync(r.stdout.trim()); } catch { return r.stdout.trim(); }
2594
+ };
2595
+ const rootTop = topOf(root);
2596
+ for (const { repo, i, url, at } of listed) {
2597
+ // The Product's own repo (a monorepo) needs no token: on disk, the record writer's own test — the same
2598
+ // git top as the Product (review 1); else the same host and path.
2599
+ const repoRoot = typeof repo.path === 'string' && repo.path ? path.resolve(root, repo.path) : null;
2600
+ const onDisk = repoRoot && exists(repoRoot) ? topOf(repoRoot) : null;
2601
+ if (onDisk && rootTop && onDisk === rootTop) continue;
2602
+ if (!onDisk && at && product && at.host === product.host && at.repo === product.repo) continue;
2603
+ // A repo on disk with no product-link record has no checkout that reads the token (review 1): CI only
2604
+ // speaks where the record is, and so does this. CI reads it from the default branch, so a record
2605
+ // committed there counts though this clone sits on a branch without it (review 2) — as E120's check.
2606
+ if (onDisk && !exists(path.join(repoRoot, PRODUCT_LINK))) {
2607
+ const branch = typeof repo.default_branch === 'string' && repo.default_branch ? repo.default_branch : 'main';
2608
+ const ref = run('git', ['rev-parse', '--verify', '--quiet', `refs/remotes/origin/${branch}`], { cwd: repoRoot }).ok ? `origin/${branch}` : 'HEAD';
2609
+ if (!run('git', ['cat-file', '-e', `${ref}:${PRODUCT_LINK}`], { cwd: repoRoot }).ok) continue;
2610
+ }
2611
+ const platform = repo.platform || detectPlatform(url || '') || null;
2612
+ if (platform !== 'github' && platform !== 'gitlab') continue;
2613
+ checked++;
2614
+ const others = (group) => listed
2615
+ .filter((o) => o.repo !== repo && o.at && at && o.at.host === at.host && o.at.repo.startsWith(`${group.toLowerCase()}/`))
2616
+ .map((o) => shown(o.repo.name));
2617
+ const line = tokenLine(readTokenPlacement({ platform, gitUrl: url }, opts), { name: forTerminal(repo.name), others });
2618
+ const id = hideAddresses(repo.name) === repo.name ? `product-token:${repo.name}` : `product-token:#${i + 1}`;
2619
+ check(checks, id, 'product-token', line.status, line.message, line.hint || '');
2620
+ }
2621
+ const productPlatform = productConfig.platform || detectPlatform(productConfig.git_url) || null;
2622
+ // Whatever platform the code repos are on (review 2): a GitHub repo can hold a GitLab Product's token.
2623
+ if (checked && productPlatform === 'gitlab') {
2624
+ const r = readExpiringProductTokens({ gitUrl: productConfig.git_url }, { ...opts, ...(today ? { today } : {}) });
2625
+ if (!r.known) {
2626
+ check(checks, 'product-token-expiry', 'product-token', 'warn', `whether one of the Product's access tokens that can clone it expires soon is not known — ${r.why}`);
2627
+ } else {
2628
+ for (const [k, t] of r.soon.entries()) {
2629
+ const when = t.days < 0 ? `expired on ${t.expires}` : `expires on ${t.expires} (in ${t.days} day(s))`;
2630
+ // One id per token (review 1): GitLab's own token id, since two tokens may share a name (a rotation
2631
+ // often keeps it, review 2); its place in the list when GitLab gave none.
2632
+ check(checks, Number.isInteger(t.id) ? `product-token-expiry:${t.id}` : `product-token-expiry:#${k + 1}`, 'product-token', 'warn',
2633
+ `the Product's access token ${shown(t.name)} (${t.scopes.map(shown).join(', ')}) ${when} — if it is the ${TOKEN_NAME} of a code repo, the Product-reading gates there will fail their checkout`,
2634
+ t.days < 0
2635
+ ? 'make a new token that can read the Product and set it as YAD_PRODUCT_TOKEN on each code repo that used the expired one (yad cannot see which token a variable holds); this line stops 30 days after the expiry date'
2636
+ : 'make a new token that can read the Product and set it as YAD_PRODUCT_TOKEN on each code repo that used the old one (yad cannot see which token a variable holds); revoking the old one in the Product\'s Settings → Access tokens once it is replaced clears this line');
2637
+ }
2638
+ }
2639
+ }
2640
+ }
2641
+
2504
2642
  // Phase 6 — feature-thread integrity. A change-epic must thread to a real parent and its denormalized
2505
2643
  // `thread` cache must equal the computed root; an open hotfix reconcile-debt is a warn (the next change
2506
2644
  // on that thread is blocked at the gate until it is paid). Pure reporting, like the other sections.
@@ -2579,10 +2717,12 @@ export function indexChecks(checks, root) {
2579
2717
  export function collectDoctor(root, { headCount = null } = {}) {
2580
2718
  const checks = [];
2581
2719
  envChecks(checks);
2720
+ signingChecks(checks, root);
2582
2721
  projectChecks(checks, root, { headCount });
2583
2722
  riskMapChecks(checks, root);
2584
2723
  codeownersChecks(checks, root);
2585
2724
  protectionChecks(checks, root);
2725
+ productTokenChecks(checks, root);
2586
2726
  foundationChecks(checks, root);
2587
2727
  shapeChecks(checks, root);
2588
2728
  indexChecks(checks, root);
@@ -2829,6 +2969,9 @@ function gitHookCheck(root, checks) {
2829
2969
  } else if (st.state === 'outdated' && st.why === 'not-executable') {
2830
2970
  check(checks, 'git-hook', 'project', 'warn', `git pre-commit ledger guard installed but not executable (${where}) — git skips it`,
2831
2971
  'run `yad check --fix`, which restores the execute bit');
2972
+ } else if (st.state === 'outdated' && st.why === 'earlier') {
2973
+ 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`,
2974
+ 'run `yad check --fix` — it replaces it without saving a copy');
2832
2975
  } else if (st.state === 'outdated') {
2833
2976
  check(checks, 'git-hook', 'project', 'warn', `git pre-commit ledger guard out of date (${where})`,
2834
2977
  'run `yad check --fix` — it saves the current file beside it before replacing it');