yadflow 4.6.0 → 4.7.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 +170 -0
  2. package/README.md +4 -1
  3. package/bin/commands.mjs +5 -1
  4. package/bin/yad.mjs +167 -15
  5. package/cli/artifact-status.mjs +88 -20
  6. package/cli/build.mjs +1372 -0
  7. package/cli/checkpoint.mjs +2 -2
  8. package/cli/commit.mjs +1 -0
  9. package/cli/dial.mjs +21 -1
  10. package/cli/docs.mjs +6 -1
  11. package/cli/doctor.mjs +133 -26
  12. package/cli/epic-state.mjs +357 -9
  13. package/cli/errors.mjs +2 -0
  14. package/cli/find-product.mjs +36 -2
  15. package/cli/fold.mjs +9 -5
  16. package/cli/gate-local.mjs +9 -1
  17. package/cli/gate.mjs +364 -22
  18. package/cli/history.mjs +22 -2
  19. package/cli/hook.mjs +3 -1
  20. package/cli/index-command.mjs +2 -2
  21. package/cli/ledger.mjs +60 -0
  22. package/cli/next.mjs +34 -11
  23. package/cli/openpr.mjs +81 -5
  24. package/cli/platform.mjs +21 -0
  25. package/cli/pr-list.mjs +5 -3
  26. package/cli/product-index.mjs +6 -3
  27. package/cli/product-token.mjs +186 -0
  28. package/cli/productcommit.mjs +33 -0
  29. package/cli/recommend.mjs +3 -1
  30. package/cli/repo-publish.mjs +2 -2
  31. package/cli/run-checks.mjs +586 -0
  32. package/cli/ship-drift.mjs +49 -18
  33. package/cli/standup.mjs +1 -1
  34. package/cli/status.mjs +282 -0
  35. package/cli/test-build.mjs +1559 -0
  36. package/cli/test-run-checks.mjs +603 -0
  37. package/cli/test-worktree.mjs +520 -0
  38. package/cli/thread.mjs +4 -0
  39. package/cli/tidy.mjs +2 -2
  40. package/cli/toolbox.mjs +36 -5
  41. package/cli/workspace.mjs +4 -1
  42. package/cli/worktree-record.mjs +53 -0
  43. package/cli/worktree.mjs +379 -0
  44. package/package.json +3 -3
  45. package/skills/sdlc/config.yaml +1 -1
  46. package/skills/sdlc/module-help.csv +1 -1
  47. package/skills/yad-backfill/templates/checks/backfill-check.sh +9 -9
  48. package/skills/yad-change/SKILL.md +3 -0
  49. package/skills/yad-checks/SKILL.md +34 -5
  50. package/skills/yad-checks/references/check-gates.md +69 -10
  51. package/skills/yad-checks/templates/checks/build-test-lint.sh +22 -3
  52. package/skills/yad-checks/templates/checks/commit-message.sh +8 -2
  53. package/skills/yad-checks/templates/checks/contract-check.sh +61 -33
  54. package/skills/yad-checks/templates/checks/epic-open.sh +87 -14
  55. package/skills/yad-checks/templates/checks/ledger-guard.sh +3 -3
  56. package/skills/yad-checks/templates/checks/lineage-check.sh +88 -15
  57. package/skills/yad-checks/templates/checks/member-check.mjs +206 -35
  58. package/skills/yad-checks/templates/checks/package-manager.sh +41 -4
  59. package/skills/yad-checks/templates/checks/product-checkout.sh +161 -13
  60. package/skills/yad-checks/templates/checks/reconcile-debt-check.sh +94 -15
  61. package/skills/yad-checks/templates/checks/risk-map-check.sh +2 -2
  62. package/skills/yad-checks/templates/checks/spec-link.sh +63 -4
  63. package/skills/yad-checks/templates/checks/verified-commits.sh +23 -5
  64. package/skills/yad-checks/templates/github/yad-checks.yml +8 -8
  65. package/skills/yad-checks/templates/gitlab/.gitlab-ci.yml +3 -0
  66. package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml +4 -4
  67. package/skills/yad-checks/templates/gitlab/yad-product-checks.gitlab-ci.yml +16 -3
  68. package/skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml +5 -1
  69. package/skills/yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml +5 -1
  70. package/skills/yad-commit/SKILL.md +4 -2
  71. package/skills/yad-docs/templates/app/package-lock.json +395 -106
  72. package/skills/yad-docs/templates/app/package.json +2 -2
  73. package/skills/yad-engineer-review/SKILL.md +45 -20
  74. package/skills/yad-engineer-review/references/ship-and-record.md +42 -8
  75. package/skills/yad-epic/references/state-schema.md +75 -16
  76. package/skills/yad-implement/SKILL.md +75 -13
  77. package/skills/yad-implement/references/implement-conventions.md +8 -1
  78. package/skills/yad-implement/templates/.gitmessage +3 -0
  79. package/skills/yad-open-pr/SKILL.md +21 -0
  80. package/skills/yad-pr-template/SKILL.md +6 -2
  81. package/skills/yad-pr-template/templates/checks/pr-template.sh +85 -4
  82. package/skills/yad-pr-template/templates/checks/pr-title.sh +1 -1
  83. package/skills/yad-pr-template/templates/github/pull_request_template.md +1 -1
  84. package/skills/yad-pr-template/templates/gitlab/merge_request_templates/Default.md +1 -1
  85. package/skills/yad-product-bridge/SKILL.md +14 -1
  86. package/skills/yad-product-bridge/references/bridge.md +5 -2
  87. package/skills/yad-product-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml +9 -4
  88. package/skills/yad-reconcile/SKILL.md +9 -3
  89. package/skills/yad-review-gate/SKILL.md +4 -0
  90. package/skills/yad-review-gate/references/gating.md +26 -1
  91. package/skills/yad-run/SKILL.md +52 -28
  92. package/skills/yad-run/references/run-loop.md +42 -21
  93. package/skills/yad-spec/SKILL.md +137 -16
  94. package/skills/yad-spec/references/spec-handoff.md +50 -3
  95. package/skills/yad-status/SKILL.md +7 -0
  96. package/skills/yad-stories/references/story-schema.md +1 -1
@@ -26,7 +26,7 @@ import { c, log, ok, info, fail, hand, exists, readJSON, readJSONStrict, pushWit
26
26
  import { PROJECT_FILES , productConfigPath } from './manifest.mjs';
27
27
  import { loadProduct } from './gate.mjs';
28
28
  import { platformLogin } from './platform.mjs';
29
- import { productGit, resolveDefaultBranch, guardDefaultBranch } from './productcommit.mjs';
29
+ import { productGit, resolveDefaultBranch, guardDefaultBranch, branchToCommitOn } from './productcommit.mjs';
30
30
  import { readShips, writeRetroShip } from './ledger.mjs';
31
31
  import { readFrontmatter, declaredRepos } from './epic-state.mjs';
32
32
 
@@ -314,8 +314,8 @@ export async function runCheckpoint(root, opts = {}) {
314
314
 
315
315
  const { productConfig } = loadProduct(root);
316
316
  const git = productGit(root);
317
- const branch = git('rev-parse', '--abbrev-ref', 'HEAD').stdout;
318
317
  const defaultBranch = resolveDefaultBranch(git, productConfig);
318
+ const branch = branchToCommitOn(root, git, defaultBranch);
319
319
 
320
320
  // Default-branch guard (invariant 2) — shared with `yad tidy up`.
321
321
  if (!guardDefaultBranch(branch, defaultBranch, { allowBranch: opts.allowBranch, cmd: 'yad checkpoint', root })) return;
package/cli/commit.mjs CHANGED
@@ -109,6 +109,7 @@ export async function runCommit(root, opts = {}) {
109
109
  type: opts.type, subject: opts.message, task,
110
110
  contractChange: !!opts.contractChange, ai: opts.ai || 'none',
111
111
  override: opts.manual ? String(opts.reason) : null,
112
+ body: typeof opts.body === 'string' ? opts.body : '',
112
113
  });
113
114
  } catch (e) { fail(e.message); process.exitCode = 1; return; }
114
115
 
package/cli/dial.mjs CHANGED
@@ -16,7 +16,7 @@ import path from 'node:path';
16
16
 
17
17
  import { c, fail, hand, info, ok, readJSONStrict, warn, writeJSON, emitJSON } from './lib.mjs';
18
18
  import {
19
- effectiveAdvance, epicRel, epicRoot, epicStories, isGateStep, killSwitchOn, loadAutomation, loadLedger, planKill,
19
+ ACTION_DIALS, effectiveAction, effectiveAdvance, epicRel, epicRoot, epicStories, isGateStep, killSwitchOn, loadAutomation, loadLedger, planKill,
20
20
  planLaneDial, planShapeDial, serializeAutomation, stepDef,
21
21
  } from './epic-state.mjs';
22
22
  import { epicFiles, PROJECT_FILES } from './manifest.mjs';
@@ -77,6 +77,7 @@ function dialShape(root, { step, to, json, bail, automation }) {
77
77
  if (!plan.ok) return bail(plan.message, plan.hint);
78
78
  const after = to ? plan.automation : automation;
79
79
  if (to && plan.changed) writeJSON(path.join(root, PROJECT_FILES.automationConfig), serializeAutomation(plan.automation));
80
+ if (ACTION_DIALS.includes(step)) return actionAnswer({ step, to, json, plan, automation, after });
80
81
  const eff = effectiveAdvance({ id: step }, { ...after, error: automation.error });
81
82
  if (json) {
82
83
  return emitJSON({
@@ -96,6 +97,25 @@ function dialShape(root, { step, to, json, bail, automation }) {
96
97
  if (to && plan.changed) hand(`commit ${PROJECT_FILES.automationConfig} (reverse with \`yad dial ${step} --to ${to === 'auto' ? 'human' : 'auto'}\`)`);
97
98
  }
98
99
 
100
+ // An action's dial (#356): `open-pr` lets the yad-run skill open a task's PR/MR once its checks pass,
101
+ // without asking. The answer has the same keys as a step's, with `scope: 'action'`.
102
+ function actionAnswer({ step, to, json, plan, automation, after }) {
103
+ const eff = effectiveAction({ ...after, error: automation.error }, step);
104
+ if (json) {
105
+ return emitJSON({
106
+ ok: true, scope: 'action', step, set: eff.set, advance: eff.advance, why: eff.why,
107
+ changed: !!to && plan.changed, kill: automation.kill, trust: null, ...errorKey(automation),
108
+ });
109
+ }
110
+ const label = c.bold(step);
111
+ if (!to) ok(`${label} — advance: ${eff.set}${eff.why === 'kill' ? ' (held at human)' : ''}`);
112
+ else if (plan.changed) ok(`${label} set to advance: ${to} for this project`);
113
+ else ok(`${label} was already advance: ${to} — nothing changed`);
114
+ if (eff.set === 'auto') info('a task\'s PR/MR is opened without asking once its checks pass (`yad open-pr --via auto`); the merge is always a person\'s');
115
+ if (killSwitchOn(automation)) warn(heldLine(automation));
116
+ if (to && plan.changed) hand(`commit ${PROJECT_FILES.automationConfig} (reverse with \`yad dial ${step} --to ${to === 'auto' ? 'human' : 'auto'}\`)`);
117
+ }
118
+
99
119
  function dialLane(root, { epic, story, repo, step, to, json, bail, automation }) {
100
120
  if (!story || !repo) return bail(`usage: yad dial ${epic} <story> --repo <name> ${step} [--to auto|human]`);
101
121
  const epicDir = epicRoot(root, epic);
package/cli/docs.mjs CHANGED
@@ -173,7 +173,12 @@ export function pagesWorkflow(platform) {
173
173
  # Edit the skill, not this file.
174
174
  pages:
175
175
  stage: deploy
176
- image: node:20
176
+ # Set the YAD_RUNNER_TAGS / YAD_NODE_VERSION CI/CD variables to route this job to a tag-locked runner or
177
+ # change its Node line; a shell-executor runner ignores \`image:\` and needs Node on its host.
178
+ tags: [$YAD_RUNNER_TAGS]
179
+ image: node:\${YAD_NODE_VERSION}
180
+ variables:
181
+ YAD_NODE_VERSION: "22"
177
182
  rules:
178
183
  - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
179
184
  script:
package/cli/doctor.mjs CHANGED
@@ -10,17 +10,18 @@ import { VERSION, BACKUP_SUFFIX, MIRRORED_FILES, mirrorDrift, PROJECT_FILES, MOD
10
10
  import { mergeHookSettings, hookMatcherFires, ideTargetsFor, 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';
@@ -743,39 +744,65 @@ export function projectChecks(checks, root, { headCount = null } = {}) {
743
744
  return { productConfig, registry };
744
745
  }
745
746
 
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.
747
+ // GitLab CI runner tags and Node line: the wired fragments run docker-image jobs. On instances whose
748
+ // runners are all tag-locked (run_untagged: false), an untagged image job matches no runner and sits
749
+ // `pending` forever — silently blocking the gates (issue #50). A current fragment carries
750
+ // `tags: [$YAD_RUNNER_TAGS]`; warn on any wired GitLab fragment that sets an `image:` but has no `tags:`
751
+ // (an old install, or one hand-reverted by a sync). A current fragment also takes its Node line from the
752
+ // `YAD_NODE_VERSION` CI/CD variable; one that still names a fixed `node:<n>` image is an install from
753
+ // before that (#364), whose Node line can only be changed by editing a file `yad` rewrites. Pure local
754
+ // read — no API calls, so neither the variables' values nor the runner's executor are known here.
751
755
  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
- };
756
+ const read = (p) => { try { return fs.readFileSync(p, 'utf8'); } catch { return null; } }; // absent: not this check's concern
757
+ // A plain update replaces an outdated copy but leaves a hand-edited (`modified`) one alone — and a copy
758
+ // edited to fit a runner is the case #364 is about, so the hint names both (review 1).
759
+ 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
760
  const fragments = [];
759
761
  if (productConfig?.platform === 'gitlab' && isVerifiedLedger(productConfig)) {
760
762
  fragments.push(
761
763
  { scope: 'product', file: '.gitlab/ci/yad-gate-sync.yml', path: path.join(root, '.gitlab/ci/yad-gate-sync.yml') },
762
764
  { scope: 'product', file: '.gitlab/ci/yad-verified-commits.yml', path: path.join(root, '.gitlab/ci/yad-verified-commits.yml') },
763
765
  { scope: 'product', file: '.gitlab/ci/yad-product-checks.yml', path: path.join(root, '.gitlab/ci/yad-product-checks.yml') },
766
+ { scope: 'product', file: '.gitlab/ci/yad-update-guard.yml', path: path.join(root, '.gitlab/ci/yad-update-guard.yml') },
764
767
  // Its old name (E123), while it is still there — `renamed:` says to run `yad update`.
765
768
  { scope: 'product', file: '.gitlab/ci/yad-hub-checks.yml', path: path.join(root, '.gitlab/ci/yad-hub-checks.yml') },
766
769
  );
767
770
  }
771
+ // The Pages job `yad docs sync --wire` writes for a GitLab Pages target. Only that command rewrites it,
772
+ // and only a file that carries its header is ours (a team's own file is left to the team).
773
+ const docsRel = pagesWorkflowPath(wiredPagesPlatform(readJSON(path.join(root, PROJECT_FILES.docsConfig), null)));
774
+ if (docsRel.startsWith('.gitlab/')) {
775
+ fragments.push({ scope: 'product', file: docsRel, path: path.join(root, docsRel), ours: (t) => t.startsWith('# yad-managed — built by `yad docs sync --wire`'),
776
+ 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)' });
777
+ }
768
778
  for (const repo of Array.isArray(registry?.repos) ? registry.repos : []) {
769
779
  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') });
780
+ for (const file of ['.gitlab/ci/yad-checks.yml', '.gitlab/ci/yad-update-guard.yml']) {
781
+ fragments.push({ scope: forTerminal(repo.name), repo: true, file, path: path.join(path.resolve(root, repo.path), file) });
782
+ }
771
783
  }
784
+ // A repo kept at the Product's own root (a monorepo) shares its files: one warning per file (review 1).
785
+ const seen = new Set();
772
786
  for (const f of fragments) {
773
- if (untagged(f.path)) {
787
+ const at = path.resolve(f.path);
788
+ if (seen.has(at)) continue;
789
+ seen.add(at);
790
+ const txt = read(f.path);
791
+ if (txt === null || (f.ours && !f.ours(txt))) continue;
792
+ // The id cannot tell the Product from a repo named `product`; this key can (E124 review 1).
793
+ const extra = { product: f.scope === 'product' && !f.repo };
794
+ if (/^\s*image:/m.test(txt) && !/^\s*tags:/m.test(txt)) {
774
795
  check(checks, `ci-tags:${f.scope}`, 'project', 'warn',
775
796
  `${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 });
797
+ `tag-locked runners (run_untagged: false) will strand it at \`pending\` — ${f.fix || UPDATE}, then set the \`YAD_RUNNER_TAGS\` CI/CD variable`,
798
+ extra);
799
+ }
800
+ const pinned = txt.match(/^\s*image:\s*["']?node:(\d[\w.-]*)/m);
801
+ if (pinned) {
802
+ check(checks, `ci-node:${f.scope}`, 'project', 'warn',
803
+ `${f.scope}: ${f.file} runs a fixed \`node:${forTerminal(pinned[1])}\` image [YAD-CI-002]`,
804
+ `${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`,
805
+ extra);
779
806
  }
780
807
  }
781
808
  }
@@ -904,16 +931,15 @@ function staleGateCheck(checks, root, epic, ledger, { solo = false } = {}) {
904
931
  if (solo) continue;
905
932
  const records = ledger.approvals.filter((a) => a.step === s.id).length;
906
933
  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)` : ''}`,
934
+ `${epic}: ${forTerminal(s.id)} is done but holds no approval${records ? ` (${records} record(s), none of them live)` : ''}`,
908
935
  '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
936
  continue;
910
937
  }
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;
938
+ // The shared rule (#418): nothing to fingerprint is no staleness claim, and one live approval clears it.
939
+ const changed = doneStepUnapproved(epicDir, s, ledger.approvals);
940
+ if (!changed) continue;
915
941
  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}`,
942
+ `${epic}: ${forTerminal(s.id)} is done, but all ${changed.count} approval(s) are bound to an older ${forTerminal(s.artifact)}`,
917
943
  'the artifact changed after it was approved — re-open the review (a fresh PR/MR) so the record matches what shipped');
918
944
  }
919
945
  }
@@ -1361,10 +1387,14 @@ export function automationChecks(checks, root) {
1361
1387
  `${rel} lists Build step(s) nothing reads here: ${build.join(', ')}`,
1362
1388
  'a Build step\'s dial is set per lane — `yad dial <epic> <story> --repo <name> <step> --to auto`');
1363
1389
  }
1390
+ for (const [id, v] of Object.entries(a.actions || {})) {
1391
+ if (!ACTION_DIALS.includes(id)) unknown.push(`actions.${id}: not an action this release knows`);
1392
+ else if (!ADVANCE_VALUES.includes(v)) unknown.push(`actions.${id}: ${JSON.stringify(v)} is not human or auto`);
1393
+ }
1364
1394
  if (unknown.length) {
1365
1395
  check(checks, 'automation:unknown', 'project', 'warn',
1366
1396
  `${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');
1397
+ 'only `auto` on a Shape author step, or on an action under `actions` (`open-pr`), is read; everything else is ignored');
1368
1398
  }
1369
1399
  }
1370
1400
  // The switch's OLD home. Before E34 it was `kill_switch: true` in the module config `yad update` installs.
@@ -2501,6 +2531,82 @@ export function protectionChecks(checks, root, { runner, env } = {}) {
2501
2531
  }
2502
2532
  }
2503
2533
 
2534
+ // #345 — does each connected code repo's CI get YAD_PRODUCT_TOKEN, the token checks/product-checkout.sh
2535
+ // clones the Product with? Only when the Product names its git_url (otherwise the record names no Product
2536
+ // to clone, and the checkout says so itself), and never for a repo that IS the Product's git repo (a
2537
+ // monorepo reads its Product from the base, with no token). Names only — see cli/product-token.mjs.
2538
+ export function productTokenChecks(checks, root, { runner, env, today } = {}) {
2539
+ const productConfig = readJSON(productConfigPath(root), null);
2540
+ if (!isPlainObject(productConfig) || typeof productConfig.git_url !== 'string' || !productConfig.git_url.trim()) return;
2541
+ const opts = { ...(runner ? { runner } : {}), ...(env ? { env } : {}), authCache: new Map() };
2542
+ const where = (url) => {
2543
+ const host = plainHost(hostFromGitUrl(url || ''));
2544
+ const repo = repoPathFromGitUrl(url || '');
2545
+ return host && repo ? { host, repo: repo.toLowerCase() } : null;
2546
+ };
2547
+ const product = where(productConfig.git_url);
2548
+ const registry = readJSON(path.join(root, PROJECT_FILES.reposRegistry), { repos: [] });
2549
+ const repos = (Array.isArray(registry?.repos) ? registry.repos : []).map((repo, i) => ({ repo, i }))
2550
+ .filter(({ repo }) => isPlainObject(repo) && typeof repo.name === 'string' && repo.name);
2551
+ const urlOf = (repo) => {
2552
+ if (typeof repo.git_url === 'string' && repo.git_url) return repo.git_url;
2553
+ const repoRoot = typeof repo.path === 'string' && repo.path ? path.resolve(root, repo.path) : null;
2554
+ return repoRoot && isCheckout(root, repo) && gitHead(repoRoot) ? (run('git', ['remote', 'get-url', 'origin'], { cwd: repoRoot }).stdout || null) : null;
2555
+ };
2556
+ const listed = repos.map(({ repo, i }) => ({ repo, i, url: urlOf(repo), at: where(urlOf(repo)) }));
2557
+ let checked = 0;
2558
+ const topOf = (dir) => {
2559
+ const r = run('git', ['rev-parse', '--show-toplevel'], { cwd: dir });
2560
+ if (!r.ok || !r.stdout) return null;
2561
+ try { return fs.realpathSync(r.stdout.trim()); } catch { return r.stdout.trim(); }
2562
+ };
2563
+ const rootTop = topOf(root);
2564
+ for (const { repo, i, url, at } of listed) {
2565
+ // The Product's own repo (a monorepo) needs no token: on disk, the record writer's own test — the same
2566
+ // git top as the Product (review 1); else the same host and path.
2567
+ const repoRoot = typeof repo.path === 'string' && repo.path ? path.resolve(root, repo.path) : null;
2568
+ const onDisk = repoRoot && exists(repoRoot) ? topOf(repoRoot) : null;
2569
+ if (onDisk && rootTop && onDisk === rootTop) continue;
2570
+ if (!onDisk && at && product && at.host === product.host && at.repo === product.repo) continue;
2571
+ // A repo on disk with no product-link record has no checkout that reads the token (review 1): CI only
2572
+ // speaks where the record is, and so does this. CI reads it from the default branch, so a record
2573
+ // committed there counts though this clone sits on a branch without it (review 2) — as E120's check.
2574
+ if (onDisk && !exists(path.join(repoRoot, PRODUCT_LINK))) {
2575
+ const branch = typeof repo.default_branch === 'string' && repo.default_branch ? repo.default_branch : 'main';
2576
+ const ref = run('git', ['rev-parse', '--verify', '--quiet', `refs/remotes/origin/${branch}`], { cwd: repoRoot }).ok ? `origin/${branch}` : 'HEAD';
2577
+ if (!run('git', ['cat-file', '-e', `${ref}:${PRODUCT_LINK}`], { cwd: repoRoot }).ok) continue;
2578
+ }
2579
+ const platform = repo.platform || detectPlatform(url || '') || null;
2580
+ if (platform !== 'github' && platform !== 'gitlab') continue;
2581
+ checked++;
2582
+ const others = (group) => listed
2583
+ .filter((o) => o.repo !== repo && o.at && at && o.at.host === at.host && o.at.repo.startsWith(`${group.toLowerCase()}/`))
2584
+ .map((o) => shown(o.repo.name));
2585
+ const line = tokenLine(readTokenPlacement({ platform, gitUrl: url }, opts), { name: forTerminal(repo.name), others });
2586
+ const id = hideAddresses(repo.name) === repo.name ? `product-token:${repo.name}` : `product-token:#${i + 1}`;
2587
+ check(checks, id, 'product-token', line.status, line.message, line.hint || '');
2588
+ }
2589
+ const productPlatform = productConfig.platform || detectPlatform(productConfig.git_url) || null;
2590
+ // Whatever platform the code repos are on (review 2): a GitHub repo can hold a GitLab Product's token.
2591
+ if (checked && productPlatform === 'gitlab') {
2592
+ const r = readExpiringProductTokens({ gitUrl: productConfig.git_url }, { ...opts, ...(today ? { today } : {}) });
2593
+ if (!r.known) {
2594
+ 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}`);
2595
+ } else {
2596
+ for (const [k, t] of r.soon.entries()) {
2597
+ const when = t.days < 0 ? `expired on ${t.expires}` : `expires on ${t.expires} (in ${t.days} day(s))`;
2598
+ // One id per token (review 1): GitLab's own token id, since two tokens may share a name (a rotation
2599
+ // often keeps it, review 2); its place in the list when GitLab gave none.
2600
+ check(checks, Number.isInteger(t.id) ? `product-token-expiry:${t.id}` : `product-token-expiry:#${k + 1}`, 'product-token', 'warn',
2601
+ `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`,
2602
+ t.days < 0
2603
+ ? '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'
2604
+ : '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');
2605
+ }
2606
+ }
2607
+ }
2608
+ }
2609
+
2504
2610
  // Phase 6 — feature-thread integrity. A change-epic must thread to a real parent and its denormalized
2505
2611
  // `thread` cache must equal the computed root; an open hotfix reconcile-debt is a warn (the next change
2506
2612
  // on that thread is blocked at the gate until it is paid). Pure reporting, like the other sections.
@@ -2583,6 +2689,7 @@ export function collectDoctor(root, { headCount = null } = {}) {
2583
2689
  riskMapChecks(checks, root);
2584
2690
  codeownersChecks(checks, root);
2585
2691
  protectionChecks(checks, root);
2692
+ productTokenChecks(checks, root);
2586
2693
  foundationChecks(checks, root);
2587
2694
  shapeChecks(checks, root);
2588
2695
  indexChecks(checks, root);