yadflow 4.8.0 → 4.10.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 (107) hide show
  1. package/CHANGELOG.md +114 -0
  2. package/README.md +4 -3
  3. package/bin/commands.mjs +7 -0
  4. package/bin/yad.mjs +123 -8
  5. package/cli/agent-guard.mjs +793 -65
  6. package/cli/agent-rules.mjs +40 -5
  7. package/cli/argv-flags.mjs +1 -1
  8. package/cli/build.mjs +1 -1
  9. package/cli/ci-check.mjs +45 -1
  10. package/cli/codeowners-command.mjs +72 -6
  11. package/cli/commit.mjs +17 -3
  12. package/cli/docs.mjs +2 -0
  13. package/cli/doctor.mjs +176 -12
  14. package/cli/epic-state.mjs +94 -4
  15. package/cli/epic.mjs +11 -7
  16. package/cli/fold.mjs +31 -6
  17. package/cli/guide.mjs +3 -1
  18. package/cli/hook.mjs +50 -7
  19. package/cli/issue-links.mjs +61 -0
  20. package/cli/issues-act.mjs +327 -0
  21. package/cli/issues-write.mjs +428 -0
  22. package/cli/issues.mjs +474 -0
  23. package/cli/lifecycle.mjs +7 -0
  24. package/cli/machine.mjs +141 -0
  25. package/cli/manifest.mjs +9 -3
  26. package/cli/openpr.mjs +69 -9
  27. package/cli/plan.mjs +2 -0
  28. package/cli/platform.mjs +157 -2
  29. package/cli/preview.mjs +253 -0
  30. package/cli/protection.mjs +21 -3
  31. package/cli/reconcile.mjs +1 -1
  32. package/cli/repo.mjs +64 -3
  33. package/cli/review.mjs +4 -0
  34. package/cli/run-checks.mjs +10 -2
  35. package/cli/scan.mjs +314 -0
  36. package/cli/setup.mjs +12 -3
  37. package/cli/standup.mjs +33 -7
  38. package/cli/story-frames.mjs +307 -0
  39. package/cli/test-agents-file.mjs +378 -11
  40. package/cli/test-build.mjs +25 -0
  41. package/cli/test-ci-check.mjs +469 -10
  42. package/cli/test-guide.mjs +7 -0
  43. package/cli/test-machine.mjs +140 -0
  44. package/cli/test-node.mjs +15 -0
  45. package/cli/test-preview.mjs +511 -0
  46. package/cli/test-run-checks.mjs +17 -0
  47. package/cli/test-setup-agent.mjs +14 -0
  48. package/cli/test-story-frames.mjs +409 -0
  49. package/cli/toolbox-connect.mjs +244 -0
  50. package/cli/toolbox.mjs +159 -5
  51. package/package.json +7 -3
  52. package/skills/sdlc/config.yaml +1 -1
  53. package/skills/sdlc/module-help.csv +3 -1
  54. package/skills/yad-analysis/SKILL.md +4 -0
  55. package/skills/yad-backfill/SKILL.md +4 -0
  56. package/skills/yad-change/SKILL.md +4 -0
  57. package/skills/yad-checks/SKILL.md +13 -7
  58. package/skills/yad-checks/references/check-gates.md +62 -30
  59. package/skills/yad-checks/templates/checks/member-check.mjs +3 -2
  60. package/skills/yad-checks/templates/checks/risk-map-check.sh +2 -2
  61. package/skills/yad-checks/templates/checks/verified-commits.sh +3 -3
  62. package/skills/yad-checks/templates/github/yad-checks.yml +357 -69
  63. package/skills/yad-checks/templates/github/yad-pr-text.yml +118 -0
  64. package/skills/yad-checks/templates/github/yad-product-checks.yml +130 -54
  65. package/skills/yad-checks/templates/github/yad-product-pr-text.yml +131 -0
  66. package/skills/yad-checks/templates/github/yad-update-guard.yml +2 -1
  67. package/skills/yad-checks/templates/github/yad-verified-commits.yml +49 -3
  68. package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml +79 -20
  69. package/skills/yad-checks/templates/gitlab/yad-product-checks.gitlab-ci.yml +59 -9
  70. package/skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml +1 -0
  71. package/skills/yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml +49 -1
  72. package/skills/yad-checks/templates/hooks/agent-guard.mjs +44 -10
  73. package/skills/yad-checks/templates/hooks/ledger-guard-cursor.mjs +12 -6
  74. package/skills/yad-commit/SKILL.md +3 -1
  75. package/skills/yad-connect-design/SKILL.md +48 -13
  76. package/skills/yad-connect-design/references/design-context.md +56 -3
  77. package/skills/yad-connect-design/references/design-registry.md +4 -4
  78. package/skills/yad-connect-learning/SKILL.md +12 -2
  79. package/skills/yad-connect-repos/SKILL.md +12 -0
  80. package/skills/yad-connect-testing/SKILL.md +22 -5
  81. package/skills/yad-connect-testing/references/testing-context.md +1 -1
  82. package/skills/yad-engineer-review/SKILL.md +13 -0
  83. package/skills/yad-epic/SKILL.md +4 -0
  84. package/skills/yad-epic/references/state-schema.md +21 -0
  85. package/skills/yad-guide/SKILL.md +8 -4
  86. package/skills/yad-implement/SKILL.md +69 -3
  87. package/skills/yad-implement/references/implement-conventions.md +2 -1
  88. package/skills/yad-issues/SKILL.md +53 -0
  89. package/skills/yad-learn/SKILL.md +4 -0
  90. package/skills/yad-open-pr/SKILL.md +10 -1
  91. package/skills/yad-pair-review/SKILL.md +5 -0
  92. package/skills/yad-pr-template/SKILL.md +2 -1
  93. package/skills/yad-pr-template/templates/checks/pr-title.sh +34 -2
  94. package/skills/yad-pr-template/templates/github/pull_request_template.md +1 -0
  95. package/skills/yad-pr-template/templates/gitlab/merge_request_templates/Default.md +1 -0
  96. package/skills/yad-product-bridge/references/bridge.md +28 -0
  97. package/skills/yad-product-bridge/templates/github/yad-gate-sync.yml +25 -11
  98. package/skills/yad-product-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml +38 -14
  99. package/skills/yad-review-companion/SKILL.md +4 -1
  100. package/skills/yad-run/SKILL.md +5 -0
  101. package/skills/yad-scan/SKILL.md +51 -0
  102. package/skills/yad-spec/SKILL.md +32 -0
  103. package/skills/yad-stories/SKILL.md +22 -0
  104. package/skills/yad-stories/references/story-schema.md +1 -0
  105. package/skills/yad-test-cases/SKILL.md +18 -2
  106. package/skills/yad-ui/SKILL.md +48 -8
  107. package/skills/yad-checks/templates/gitlab/.gitlab-ci.yml +0 -49
package/cli/doctor.mjs CHANGED
@@ -3,6 +3,7 @@
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
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';
@@ -18,7 +19,7 @@ import { judgeRepo, runnable, shown as forTerminal } from './workspace.mjs';
18
19
  import { cliFor, hostFromGitUrl, ambiguousLegacyNames, plainHost, detectPlatform } from './platform.mjs';
19
20
  import { legacyLogins, stampLegacyLogins } from './gate.mjs';
20
21
  import { checkRepo } from './riskmap-command.mjs';
21
- import { checkCodeowners, codeownersFindings } from './codeowners-command.mjs';
22
+ import { checkCodeowners, codeownersFindings, unguardedHint, unguardedWords } from './codeowners-command.mjs';
22
23
  import { RISK_MAP_FILE } from './riskmap.mjs';
23
24
  import { readProtection, protectionLine, protectionJSON, hideAddresses, repoPathFromGitUrl, shown } from './protection.mjs';
24
25
  import { readTokenPlacement, tokenLine, readExpiringProductTokens, TOKEN_NAME } from './product-token.mjs';
@@ -30,6 +31,18 @@ import { readOwners } from './owners.mjs';
30
31
  import { readMembers, judgedMemberFiles } from './members.mjs';
31
32
  import { loadChoices, readToolboxFile } from './toolbox.mjs';
32
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';
37
+
38
+ // The design, testing and learning rows (E165 follow-up). The files are the team's, committed: `source` says
39
+ // what was found on the machine of whoever refreshed last, so a row says what was RECORDED, and the refresh
40
+ // checks this machine. A refresh with no `tool` checks the skill's default tool, not the team's, so every
41
+ // hint names it. The tool is one of DESIGN_TOOLS / TESTING_TOOLS / LEARNING_TOOLS by the time these run,
42
+ // each with a connect recipe; one that is installed but cannot be reached (signed out, its app closed)
43
+ // needs the person, not a connect step.
44
+ const connectThenRefresh = (skill, tool) => `if ${tool} is not on this machine, your agent can connect it: \`yad toolbox connect ${tool} --json\` (it asks you first); if it is, make sure it can be reached (signed in, its app open). Then run \`${skill}\` with \`action: refresh\` and \`tool: ${tool}\``;
45
+ const confirmByRefresh = (skill, tool) => `run \`${skill}\` with \`action: refresh\` and \`tool: ${tool}\` in your AI agent to check it on this machine`;
33
46
 
34
47
  // A registered path doctor may run git in (E81): a checkout the judgement accepts — never a refused
35
48
  // entry (git run in a folder the Product shaped as a repo reads its `config`, which can run a command),
@@ -110,6 +123,60 @@ export function signingChecks(checks, root) {
110
123
  check(checks, 'signing', 'environment', line.status, line.message, line.hint, { alwaysHint: true });
111
124
  }
112
125
 
126
+ // #352 — the machine setup local work depends on (cli/machine.mjs): the active Node against each repo's
127
+ // pinned version, Docker where a repo asks for it, and duplicate glab config files. The Product folder and
128
+ // every registered repo cloned here are read; the rest is not this machine's to judge.
129
+ export function machineChecks(checks, root, { nodeVersion = process.versions.node, env = process.env, home = os.homedir(), platform = process.platform, runner } = {}) {
130
+ const tilde = (p) => (p.startsWith(home + path.sep) ? `~${p.slice(home.length)}` : p);
131
+ const folders = [];
132
+ if (exists(productConfigPath(root))) folders.push({ name: 'the Product', dir: root, id: 'product' });
133
+ const registry = readJSON(path.join(root, PROJECT_FILES.reposRegistry), { repos: [] });
134
+ for (const repo of Array.isArray(registry?.repos) ? registry.repos : []) {
135
+ if (!repo || typeof repo.name !== 'string' || typeof repo.path !== 'string' || !repo.path) continue;
136
+ const dir = path.resolve(root, repo.path);
137
+ if (path.resolve(dir) === path.resolve(root) || !isCheckout(root, repo)) continue;
138
+ folders.push({ name: forTerminal(repo.name), dir, id: `repo:${forTerminal(repo.name)}` });
139
+ }
140
+
141
+ // Node: one warning per folder with the pins the running Node does not meet; one ok line when every pin
142
+ // read is met. A pin yad cannot read as a version is counted as skipped, never judged.
143
+ let read = 0;
144
+ let skipped = 0;
145
+ let wrong = 0;
146
+ for (const { name, dir, id } of folders) {
147
+ const unmet = [];
148
+ for (const { source, want } of nodePins(dir)) {
149
+ const meets = satisfies(nodeVersion, want);
150
+ if (meets === null) { skipped += 1; continue; }
151
+ read += 1;
152
+ if (!meets) unmet.push({ source, want });
153
+ }
154
+ if (!unmet.length) continue;
155
+ wrong += 1;
156
+ check(checks, `node-version:${id}`, 'environment', 'warn',
157
+ `node ${nodeVersion} does not meet what ${name} pins: ${unmet.map((u) => `${forTerminal(u.want)} (${u.source})`).join(', ')}`,
158
+ `${nodeFix(unmet[0].want, { env, home })} — the Node that runs yad is the active one (your version manager's default in a new shell)`);
159
+ }
160
+ 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` : ''})`);
161
+
162
+ // Docker: asked only where a repo names it.
163
+ const needs = folders.map((f) => ({ ...f, why: dockerReasons(f.dir) })).filter((f) => f.why.length);
164
+ if (needs.length) {
165
+ const who = needs.map((f) => `${f.name} (${f.why.join('; ')})`).join(', ');
166
+ const state = dockerState(runner ? { runner } : {});
167
+ if (state === 'running') check(checks, 'docker', 'environment', 'ok', `Docker is running, as ${who} needs`);
168
+ 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`,
169
+ 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');
170
+ }
171
+
172
+ // glab: more than one config file.
173
+ const confs = glabConfigs({ env, home, platform });
174
+ if (confs.length > 1) {
175
+ check(checks, 'glab-config', 'environment', 'warn', `glab has ${confs.length} config files: ${confs.map((f) => forTerminal(tilde(f))).join(', ')}`,
176
+ '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');
177
+ }
178
+ }
179
+
113
180
  // `headCount` is a count of people the caller already read (E74); the CLI passes none, a test passes one.
114
181
  export function projectChecks(checks, root, { headCount = null } = {}) {
115
182
  const productPath = productConfigPath(root);
@@ -410,8 +477,8 @@ export function projectChecks(checks, root, { headCount = null } = {}) {
410
477
  else if (design.tool === 'none') check(checks, 'design', 'project', 'ok', 'design: markdown-only');
411
478
  else if (!DESIGN_TOOLS.includes(design.tool)) check(checks, 'design', 'project', 'fail', `${PROJECT_FILES.designConfig}: unknown or missing design tool '${design.tool}' [YAD-CFG-002]`, `expected one of ${DESIGN_TOOLS.join(', ')}, or none`);
412
479
  else if (design.source && design.source !== 'unavailable') check(checks, 'design', 'project', 'ok', `design: ${design.tool} (${design.source})`);
413
- else if (design.source === 'unavailable') check(checks, 'design', 'project', 'warn', `design: ${design.tool} MCP unavailable — yad-ui runs markdown-only`, 'connect the MCP, then run `yad-connect-design` (action: refresh)');
414
- else check(checks, 'design', 'project', 'warn', `design: ${design.tool} recorded but the MCP is not confirmed`, 'run `yad-connect-design` in your AI agent to detect the MCP');
480
+ else if (design.source === 'unavailable') check(checks, 'design', 'project', 'warn', `design: ${design.tool} recorded as not found when last checked — yad-ui runs markdown-only`, connectThenRefresh('yad-connect-design', design.tool));
481
+ else check(checks, 'design', 'project', 'warn', `design: ${design.tool} recorded but not confirmed`, confirmByRefresh('yad-connect-design', design.tool));
415
482
  }
416
483
 
417
484
  // testing.json: parse + shape + tool + MCP confirmation (absent is the normal artifacts-only default —
@@ -430,8 +497,8 @@ export function projectChecks(checks, root, { headCount = null } = {}) {
430
497
  else if (testing.tool === 'none') check(checks, 'testing', 'project', 'ok', 'testing: artifacts-only');
431
498
  else if (!TESTING_TOOLS.includes(testing.tool)) check(checks, 'testing', 'project', 'fail', `${PROJECT_FILES.testingConfig}: unknown or missing testing tool '${testing.tool}' [YAD-CFG-003]`, `expected one of ${TESTING_TOOLS.join(', ')}, or none`);
432
499
  else if (testing.source && testing.source !== 'unavailable') check(checks, 'testing', 'project', 'ok', `testing: ${testing.tool} (${testing.source})`);
433
- else if (testing.source === 'unavailable') check(checks, 'testing', 'project', 'warn', `testing: ${testing.tool} MCP unavailable — yad-test-cases runs artifacts-only`, 'connect the MCP, then run `yad-connect-testing` (action: refresh)');
434
- else check(checks, 'testing', 'project', 'warn', `testing: ${testing.tool} recorded but the MCP is not confirmed`, 'run `yad-connect-testing` in your AI agent to detect the MCP');
500
+ else if (testing.source === 'unavailable') check(checks, 'testing', 'project', 'warn', `testing: ${testing.tool} recorded as not found when last checked — yad-test-cases runs artifacts-only`, connectThenRefresh('yad-connect-testing', testing.tool));
501
+ else check(checks, 'testing', 'project', 'warn', `testing: ${testing.tool} recorded but not confirmed`, confirmByRefresh('yad-connect-testing', testing.tool));
435
502
  }
436
503
 
437
504
  // learning.json: parse + shape + tool + CLI confirmation (absent is the normal harness-native default —
@@ -451,8 +518,8 @@ export function projectChecks(checks, root, { headCount = null } = {}) {
451
518
  else if (learning.tool === 'none') check(checks, 'learning', 'project', 'ok', 'learning: harness-native');
452
519
  else if (!LEARNING_TOOLS.includes(learning.tool)) check(checks, 'learning', 'project', 'fail', `${PROJECT_FILES.learningConfig}: unknown or missing learning tool '${learning.tool}' [YAD-CFG-004]`, `expected one of ${LEARNING_TOOLS.join(', ')}, or none`);
453
520
  else if (learning.source === 'deeptutor-cli') check(checks, 'learning', 'project', 'ok', `learning: ${learning.tool} (${learning.source})`);
454
- else if (learning.source === 'harness-native') check(checks, 'learning', 'project', 'warn', `learning: ${learning.tool} CLI unavailable — yad-learn tutors harness-native`, 'install the deeptutor CLI, then run `yad-connect-learning` (action: refresh)');
455
- else if (learning.source == null) check(checks, 'learning', 'project', 'warn', `learning: ${learning.tool} recorded but the CLI is not confirmed`, 'run `yad-connect-learning` in your AI agent to detect the CLI');
521
+ else if (learning.source === 'harness-native') check(checks, 'learning', 'project', 'warn', `learning: ${learning.tool} recorded as not found when last checked — yad-learn tutors harness-native`, connectThenRefresh('yad-connect-learning', learning.tool));
522
+ else if (learning.source == null) check(checks, 'learning', 'project', 'warn', `learning: ${learning.tool} recorded but not confirmed`, confirmByRefresh('yad-connect-learning', learning.tool));
456
523
  else check(checks, 'learning', 'project', 'fail', `${PROJECT_FILES.learningConfig}: unknown source '${learning.source}' [YAD-STATE-002]`, 'expected deeptutor-cli, harness-native, or null');
457
524
  }
458
525
 
@@ -513,6 +580,7 @@ export function projectChecks(checks, root, { headCount = null } = {}) {
513
580
  else check(checks, `repo:${repo.name}`, 'project', 'ok', `${nm}: git repo, context fresh`);
514
581
  }
515
582
  if (!registry.repos.length) check(checks, 'repos', 'project', 'warn', 'no code repos registered', 'run `yad setup` to connect one');
583
+ previewChecks(checks, repoEntries);
516
584
  // Per-repo owners went with the roster (E62). Named only where a repo actually lists someone: every
517
585
  // repo an older setup connected carries an EMPTY `domain_owner`, which says nothing.
518
586
  const owned = repoEntries.filter((r) => (Array.isArray(r.domain_owners) && r.domain_owners.length) || (typeof r.domain_owner === 'string' && r.domain_owner));
@@ -597,12 +665,13 @@ export function projectChecks(checks, root, { headCount = null } = {}) {
597
665
  const blindGates = gateRoots.flatMap((x) => PRODUCT_PATH_GATES.map((rel) => ({ ...x, rel })))
598
666
  .filter((x) => productRecordBlindGate(path.join(x.root, x.rel)))
599
667
  .map((x) => `${x.rel} in ${x.where}`);
600
- // A `#` line naming the script is prose, not a step that runs it (review 1).
668
+ // A `#` line naming the script is prose, not a step that runs it (review 1). Since #426 the shipped
669
+ // workflow runs the base branch's copy, `"$YAD_CHECKS/product-checkout.sh"`; an older one, `checks/…`.
601
670
  const blindFlows = gateRoots.filter((x) => x.where !== 'the Product').flatMap((x) => CHECK_WORKFLOWS.map((rel) => ({ ...x, rel })))
602
671
  .filter((x) => {
603
672
  let src;
604
673
  try { src = fs.readFileSync(path.join(x.root, x.rel), 'utf8'); } catch { return false; }
605
- return !src.split('\n').some((l) => !/^\s*#/.test(l) && /checks\/product-checkout\.sh/.test(l));
674
+ return !src.split('\n').some((l) => !/^\s*#/.test(l) && /(?:\bchecks|\$\{?YAD_CHECKS\}?)\/product-checkout\.sh/.test(l));
606
675
  })
607
676
  .map((x) => `${x.rel} in ${x.where}`);
608
677
  const said = [
@@ -613,6 +682,17 @@ export function projectChecks(checks, root, { headCount = null } = {}) {
613
682
  check(checks, 'checks:product-record-blind', 'project', 'warn', said.join('; '),
614
683
  'run `yad check --fix` (it refreshes wired files nobody changed by hand); otherwise copy the shipped gate or workflow over it from skills/yad-checks/templates/');
615
684
  }
685
+ // #425. A gate workflow that still starts on `edited`: its gate jobs skip that run, a skipped job counts as
686
+ // passed, and the newer run turns a failed gate green. The shipped copies no longer start on it; one the
687
+ // team changed by hand is kept by `yad update`, so name it.
688
+ const editRun = gateRoots.flatMap((x) => EDIT_RUN_WORKFLOWS.map((rel) => ({ ...x, rel })))
689
+ .filter((x) => editRunWorkflow(path.join(x.root, x.rel)))
690
+ .map((x) => `${x.rel} in ${x.where}`);
691
+ if (editRun.length) {
692
+ check(checks, 'checks:edit-run', 'project', 'warn',
693
+ `${editRun.join(', ')} ${editRun.length > 1 ? 'start' : 'starts'} on an edit of the PR text (\`edited\`) — the gate jobs skip that run, GitHub counts a skipped job as passed, so editing the title or description can turn a failed gate green`,
694
+ 'run `yad update --overwrite-local` — it replaces every hand-edited managed file, keeping a `.yad-orig` copy of each; the PR-text checks now run from yad-pr-text.yml / yad-product-pr-text.yml. Or, by hand, remove `edited` from that file\'s `types:` and delete its `pr-title` and `pr-template` jobs: the PR-text file runs them now, and two runs under one check name let either decide');
695
+ }
616
696
  // E120. A wired code repo (not the Product's own git repo) whose record is not COMMITTED: its gates
617
697
  // fall back to link.md, and CI has nothing to check the Product out from. Committed, not on disk
618
698
  // (review 1): the gates read it from the default branch, and one that setup wrote and nobody
@@ -1603,6 +1683,35 @@ export function themeChecks(checks, root) {
1603
1683
  }
1604
1684
  }
1605
1685
 
1686
+ // #354 — the design frames each story records (`design-frames: [id, …]`). The rule is `frameFindings` in
1687
+ // cli/story-frames.mjs, the same one `yad story frames` prints, and every finding is a warning there too,
1688
+ // so the two never disagree. No row at all when no story records frames: most Products have no design
1689
+ // tool, and a line saying so on every run would teach people to skip the section.
1690
+ export function storyFrameChecks(checks, root) {
1691
+ const epicsDir = path.join(root, 'epics');
1692
+ if (!exists(epicsDir)) return;
1693
+ const stories = allStoryFrames(root, epicIds(root).sort());
1694
+ if (!stories.length) return;
1695
+ const problems = stories.flatMap((s) => s.findings.map((f) => `${forTerminal(s.story)}: ${f.message}`));
1696
+ if (!problems.length) {
1697
+ const withFrames = stories.filter((s) => s.frames > 0).length;
1698
+ const noScreens = stories.length - withFrames;
1699
+ const parts = [
1700
+ ...(withFrames ? [`${withFrames} story(ies) record design frames, and every frame ID is in its epic's design-links.json`] : []),
1701
+ ...(noScreens ? [`${noScreens} story(ies) say they have no screens (\`${FRAMES_KEY}: []\`)`] : []),
1702
+ ];
1703
+ check(checks, 'stories:design-frames', 'shape', 'ok', parts.join('; '));
1704
+ return;
1705
+ }
1706
+ const shownN = 3;
1707
+ const list = `${problems.slice(0, shownN).join('; ')}${problems.length > shownN ? ` (+${problems.length - shownN} more)` : ''}`;
1708
+ check(
1709
+ checks, 'stories:design-frames', 'shape', 'warn',
1710
+ `${problems.length} problem(s) with the design frames stories record: ${list}`,
1711
+ `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`,
1712
+ );
1713
+ }
1714
+
1606
1715
  // A project's chain against the step catalogue (E4). `phaseChecks` below asks whether a step id is
1607
1716
  // KNOWN; this asks whether a known step is set up the way the catalogue says it is.
1608
1717
  //
@@ -2013,6 +2122,16 @@ export function productRecordBlindGate(file) {
2013
2122
  try { src = fs.readFileSync(file, 'utf8'); } catch { return false; }
2014
2123
  return productRecordBlindText(src);
2015
2124
  }
2125
+ // #425. The GitHub gate workflows that must never start on `edited` (the Product's under the old name too).
2126
+ export const EDIT_RUN_WORKFLOWS = Object.freeze(['.github/workflows/yad-checks.yml', '.github/workflows/yad-product-checks.yml', '.github/workflows/yad-hub-checks.yml']);
2127
+ // `edited` in a `types:` list, inline or as a block item; a `#` comment is prose, not a trigger.
2128
+ export const editRunText = (src) => src.split('\n').map((l) => l.replace(/(^|\s)#.*$/, '')).some((l) =>
2129
+ /^\s*types:.*(?:^|[\s[,'"])edited(?:$|[\s\],'"])/.test(l) || /^\s*-\s*(['"]?)edited\1\s*$/.test(l));
2130
+ export function editRunWorkflow(file) {
2131
+ let src;
2132
+ try { src = fs.readFileSync(file, 'utf8'); } catch { return false; }
2133
+ return editRunText(src);
2134
+ }
2016
2135
  // The checks workflows a connected repo may carry (one per platform).
2017
2136
  export const CHECK_WORKFLOWS = ['.github/workflows/yad-checks.yml', '.gitlab/ci/yad-checks.yml'];
2018
2137
  // E117: a Product-reading gate that does not read link.md from the base (`git show`) or a tracked Product
@@ -2489,20 +2608,31 @@ export function riskMapChecks(checks, root) {
2489
2608
  // a guess, and it prints only in `yad codeowners check`, never here. Advisory — a warning, never a
2490
2609
  // failure: CODEOWNERS is a hint (Part 3). No file at all is a note; a repo with no review rules at all is
2491
2610
  // E70's to warn about. A repo not on disk, or not a git repo, is the repos check's to report.
2611
+ // #426: gate files (checks/, every CI file) with no owner whose review the platform can require are a warning
2612
+ // too, with or without a CODEOWNERS file — on each code repo and on the Product, which runs its own gates (once:
2613
+ // a Product registered as one of its own repos is not said twice). The hint gives the lines.
2492
2614
  export function codeownersChecks(checks, root) {
2493
2615
  const registry = readJSON(path.join(root, PROJECT_FILES.reposRegistry), { repos: [] });
2494
2616
  const repos = Array.isArray(registry?.repos) ? registry.repos : [];
2617
+ const real = (d) => { try { return fs.realpathSync.native(d); } catch { return d; } };
2618
+ const seen = new Set();
2619
+ const can = { github: 'GitHub', gitlab: 'GitLab' };
2495
2620
  for (const repo of repos) {
2496
2621
  if (!repo || typeof repo.name !== 'string' || typeof repo.path !== 'string' || !repo.path) continue;
2497
2622
  const repoRoot = path.resolve(root, repo.path);
2498
2623
  if (!isCheckout(root, repo) || !gitHead(repoRoot)) continue;
2624
+ seen.add(real(repoRoot));
2499
2625
  const r = checkCodeowners(repoRoot, { platform: repo.platform || null });
2500
2626
  if (!r.git) continue;
2501
2627
  const id = `codeowners:${repo.name}`;
2502
2628
  const nm = forTerminal(repo.name); // printed as in riskMapChecks (E81 review 11)
2503
2629
  const more = `\`yad codeowners check ${asArg(repo.name)}\``;
2504
2630
  if (r.unknown) { check(checks, id, 'codeowners', 'warn', `${nm}: CODEOWNERS could not be checked — ${forTerminal(r.unknown)}`, more); continue; }
2505
- if (r.none) { check(checks, id, 'codeowners', 'ok', `${nm}: no CODEOWNERS — nothing to check`); continue; }
2631
+ if (r.none && !r.unguarded) { check(checks, id, 'codeowners', 'ok', `${nm}: no CODEOWNERS — nothing to check`); continue; }
2632
+ if (r.none) {
2633
+ check(checks, id, 'codeowners', 'warn', `${nm}: no CODEOWNERS, so ${unguardedWords(r.unguarded)} have no code owner`, unguardedHint(r.platform, r.unguarded), { findings: codeownersFindings(r) });
2634
+ continue;
2635
+ }
2506
2636
  const findings = codeownersFindings(r);
2507
2637
  if (!findings.length) { check(checks, id, 'codeowners', 'ok', `${nm}: every ${r.path} line yad can read matches a file`); continue; }
2508
2638
  const lines = (code) => findings.filter((f) => f.code === code).map((f) => f.line);
@@ -2514,10 +2644,27 @@ export function codeownersChecks(checks, root) {
2514
2644
  if (dead.length) said.push(`in ${r.path}, ${dead.length === 1 ? '1 line matches' : `${dead.length} lines match`} no file (line${dead.length === 1 ? '' : 's'} ${listed(dead)})`);
2515
2645
  const unread = lines('not-read');
2516
2646
  if (unread.length) said.push(`in ${r.path}, ${unread.length === 1 ? '1 line' : `${unread.length} lines`} yad could not read (line${unread.length === 1 ? '' : 's'} ${listed(unread)})`);
2517
- check(checks, id, 'codeowners', 'warn', `${nm}: CODEOWNERS may be out of date — ${said.join('; ')}`,
2518
- `${more} lists each one; fix it in ${nm} through a PR (advisory — CODEOWNERS is a hint, and yad never enforces it)`,
2647
+ const stale = said.length ? [`${nm}: CODEOWNERS may be out of date — ${said.join('; ')}`] : [];
2648
+ const gates = r.unguarded ? [`${stale.length ? '' : `${nm}: `}no line in ${r.path} that yad can read gives ${unguardedWords(r.unguarded)} an owner whose review ${can[r.platform] || 'the platform'} can require`] : [];
2649
+ check(checks, id, 'codeowners', 'warn', [...stale, ...gates].join('; '),
2650
+ [...(stale.length ? [`${more} lists each one; fix it in ${nm} through a PR (advisory — CODEOWNERS is a hint, and yad never enforces it)`] : []),
2651
+ ...(r.unguarded ? [unguardedHint(r.platform, r.unguarded)] : [])].join('; '),
2519
2652
  { findings });
2520
2653
  }
2654
+ // The Product's own gates (#426). Only the gate-file finding: the stale-line facts above are for code repos.
2655
+ const productConfig = readJSON(productConfigPath(root), null);
2656
+ if (!isPlainObject(productConfig) || !gitHead(root) || seen.has(real(root))) return;
2657
+ const platform = ['github', 'gitlab'].includes(productConfig.platform) ? productConfig.platform : null;
2658
+ const p = checkCodeowners(root, { platform });
2659
+ if (!p.git || p.unknown || p.tooBig || !p.platform) return;
2660
+ if (!p.unguarded) {
2661
+ // No CODEOWNERS and nothing unguarded means no gate files at all: nothing to say.
2662
+ if (!p.none && fs.existsSync(path.join(root, 'checks'))) check(checks, 'codeowners:(the Product)', 'codeowners', 'ok', `the Product: checks/ and the CI files have a code owner in ${p.path}`);
2663
+ return;
2664
+ }
2665
+ check(checks, 'codeowners:(the Product)', 'codeowners', 'warn',
2666
+ `the Product: ${p.none ? 'no CODEOWNERS, so ' : `no line in ${p.path} that yad can read gives `}${unguardedWords(p.unguarded)}${p.none ? ' have no code owner' : ` an owner whose review ${can[p.platform] || 'the platform'} can require`}`,
2667
+ unguardedHint(p.platform, p.unguarded), { findings: codeownersFindings(p).filter((f) => f.code === 'unguarded') });
2521
2668
  }
2522
2669
 
2523
2670
  // E70 — what the platform holds on the Product's branch and on each connected repo's: branch
@@ -2718,6 +2865,7 @@ export function collectDoctor(root, { headCount = null } = {}) {
2718
2865
  const checks = [];
2719
2866
  envChecks(checks);
2720
2867
  signingChecks(checks, root);
2868
+ machineChecks(checks, root);
2721
2869
  projectChecks(checks, root, { headCount });
2722
2870
  riskMapChecks(checks, root);
2723
2871
  codeownersChecks(checks, root);
@@ -2732,6 +2880,7 @@ export function collectDoctor(root, { headCount = null } = {}) {
2732
2880
  legacyModuleChecks(checks, root);
2733
2881
  typeChecks(checks, root);
2734
2882
  themeChecks(checks, root);
2883
+ storyFrameChecks(checks, root);
2735
2884
  catalogueChecks(checks, root);
2736
2885
  profileChecks(checks, root);
2737
2886
  skipChecks(checks, root);
@@ -2979,3 +3128,18 @@ function gitHookCheck(root, checks) {
2979
3128
  check(checks, 'git-hook', 'project', 'ok', `git pre-commit ledger guard installed in this clone (${where})`);
2980
3129
  }
2981
3130
  }
3131
+
3132
+ // The preview address patterns (#359), by the same rule `yad repo preview` writes with. Said only when
3133
+ // some repo records one: a repo with no pattern is the normal case, and its review says "locally only".
3134
+ export function previewChecks(checks, repoEntries) {
3135
+ const withPreview = repoEntries.filter((r) => PREVIEW_KEY in r && r[PREVIEW_KEY] != null);
3136
+ if (!withPreview.length) return;
3137
+ const bad = withPreview.map((r) => ({ r, problems: previewPattern(r).problems })).filter((x) => x.problems);
3138
+ if (bad.length) {
3139
+ check(checks, 'repos:preview', 'project', 'warn',
3140
+ `${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(', ')}`,
3141
+ `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`);
3142
+ } else {
3143
+ check(checks, 'repos:preview', 'project', 'ok', `${withPreview.length} repo${withPreview.length > 1 ? 's record' : ' records'} a preview address pattern`);
3144
+ }
3145
+ }
@@ -440,6 +440,8 @@ export function artifactFromBase(base) {
440
440
  // The files (relative to the epic dir) a review of this artifact covers — what `gate open` commits
441
441
  // on the review branch (the owner's artifact), and what CI re-reads to bind the approval at merge.
442
442
  // Architecture mirrors artifactHash(): the approval is bound to the locked contract surface too.
443
+ // E164: the folder beside ui-design.md that holds the epic's design file.
444
+ export const UI_DESIGN_DIR = 'design';
443
445
  export function artifactPaths(base) {
444
446
  if (base === 'architecture') return ['architecture.md', 'contract.md', '.sdlc/contract-lock.json'];
445
447
  if (base === 'stories') return ['stories'];
@@ -447,6 +449,10 @@ export function artifactPaths(base) {
447
449
  // Every section, optional ones included: this names what a Foundation review COVERS, and a section
448
450
  // that is absent today is still one a reviewer may be asked to look at tomorrow.
449
451
  if (base === 'foundation') return [...FOUNDATION_FILES];
452
+ // E164: the UI step's design file lives in the epic's `design/` folder (an OpenPencil file in the repo),
453
+ // so the UI review covers it: `yad fold` commits it, and a change to it after approval needs a fresh
454
+ // review. A folder, so `fold` and `artifactHashAt` take everything under it.
455
+ if (base === 'ui-design') return ['ui-design.md', UI_DESIGN_DIR];
450
456
  return [`${base}.md`];
451
457
  }
452
458
 
@@ -595,6 +601,85 @@ export function storiesHash(epicDir, sha = reviewedSha) {
595
601
  return 'sha256:' + createHash('sha256').update(parts.join('\n')).digest('hex');
596
602
  }
597
603
 
604
+ // E164: the UI design's fingerprint. With no file under `design/`, it is the fingerprint of ui-design.md
605
+ // alone — byte for byte what every release before E164 recorded, so no approval of a Figma or Pencil
606
+ // design moves. With design files, it covers them too: ui-design.md as reviewed (`sha`), then each design
607
+ // file (`designSha`, never with a status line left out), sorted by path.
608
+ //
609
+ // Which files count is decided here, and the copy `artifactHashAt` makes of a commit is read by the same
610
+ // walk, so the disk and the approved commit agree:
611
+ // - regular files only (a link is skipped; so is a `design` folder that is itself a link — a commit
612
+ // holds it as a link, not a folder);
613
+ // - never a file the system or an editor drops beside a design (`isDesignJunk`: `.DS_Store`, macOS's
614
+ // `._<name>` copies, a `.~lock.<name>#` lock file, a name ending in `~`, `Thumbs.db`, `desktop.ini`)
615
+ // — git often does not ignore those, and counting one would make every approval look changed on that
616
+ // machine only. Any other name, a dot-name included, is a design file;
617
+ // - never inside a folder holding `.git` (a submodule or a nested repository: a commit holds it as one
618
+ // entry, not its files).
619
+ const DESIGN_JUNK = /^(?:\.ds_store|\._.*|\.~lock\..*|.*~|thumbs\.db|desktop\.ini)$/i;
620
+ export const isDesignJunk = (rel) => rel.split('/').some((seg) => DESIGN_JUNK.test(seg));
621
+ function designFiles(dir, rel = '') {
622
+ if (rel === '') {
623
+ try { if (!fs.lstatSync(dir).isDirectory()) return []; } catch { return []; }
624
+ }
625
+ let entries;
626
+ try { entries = fs.readdirSync(path.join(dir, rel), { withFileTypes: true }); } catch { return []; }
627
+ if (entries.some((e) => e.name === '.git')) return [];
628
+ const out = [];
629
+ for (const e of entries) {
630
+ if (DESIGN_JUNK.test(e.name)) continue;
631
+ const r = rel ? `${rel}/${e.name}` : e.name;
632
+ if (e.isDirectory()) out.push(...designFiles(dir, r));
633
+ else if (e.isFile()) out.push(r);
634
+ }
635
+ return out;
636
+ }
637
+ // One design file's fingerprint: the SHA-256 of its content. A Git LFS pointer (the small text file a
638
+ // checkout without LFS leaves in place of a large file) names that same SHA-256 as its `oid`, so the
639
+ // pointer and the real file give one fingerprint — CI checks out pointers, `artifactHashAt` may read
640
+ // the real file through the LFS filter, and the two must agree.
641
+ // Only the exact pointer format git-lfs writes counts — its version line, any `ext-` lines, the oid, the
642
+ // size and nothing else — so no other text can ride in a file whose fingerprint is its oid alone.
643
+ const LFS_POINTER = /^version https:\/\/git-lfs\.github\.com\/spec\/v1\r?\n(?:ext-[^\r\n]*\r?\n)*oid sha256:([0-9a-f]{64})\r?\nsize \d+\r?\n?$/;
644
+ function designSha(p) {
645
+ const bytes = fs.readFileSync(p);
646
+ if (bytes.length < 1024) {
647
+ const oid = bytes.toString('utf8').match(LFS_POINTER);
648
+ if (oid) return `sha256:${oid[1]}`;
649
+ }
650
+ return shaOf(bytes);
651
+ }
652
+ // The files under `design/` that git ignores here (an exports folder in .gitignore, an editor's settings
653
+ // folder): no commit holds them, so counting them would make the approval look changed on this machine
654
+ // only. Never asked for the scratch copy `artifactHashAt` makes (`askGit: false`): it holds only committed
655
+ // files, and a temporary folder inside some checkout would be judged by that checkout's rules. A tracked
656
+ // file is never reported, even when a pattern matches it. The variables that point git at another
657
+ // repository (set inside a git hook, or by a script) are dropped, so git finds the Product's checkout from
658
+ // the folder itself — the same list hook.mjs drops. Names are compared in one Unicode form, because git
659
+ // on macOS may print a name precomposed that it was given decomposed.
660
+ const REPO_ENV = /^GIT_(DIR|WORK_TREE|PREFIX|INDEX_FILE|COMMON_DIR|OBJECT_DIRECTORY|ALTERNATE_OBJECT_DIRECTORIES)$/;
661
+ function ignoredByGit(dir, files) {
662
+ if (!files.length) return new Set();
663
+ const env = { ...Object.fromEntries(Object.entries(process.env).filter(([k]) => !REPO_ENV.test(k))), GIT_OPTIONAL_LOCKS: '0' };
664
+ const r = spawnSync('git', ['check-ignore', '-z', '--stdin'], { cwd: dir, input: files.map((f) => `${f}\0`).join(''), env, maxBuffer: 64 * 1024 * 1024 });
665
+ return r.status === 0 ? new Set(r.stdout.toString('utf8').split('\0').filter(Boolean).map((f) => f.normalize('NFC'))) : new Set();
666
+ }
667
+ // The design files' part of the fingerprint, read once: `acceptedHashes` combines it with each form of
668
+ // ui-design.md, so a large design file is not read again for every form.
669
+ function designParts(epicDir, { askGit = true } = {}) {
670
+ const dir = path.join(epicDir, UI_DESIGN_DIR);
671
+ const all = designFiles(dir);
672
+ const ignored = askGit ? ignoredByGit(dir, all) : new Set();
673
+ return all.filter((f) => !ignored.has(f.normalize('NFC'))).sort().map((f) => `${UI_DESIGN_DIR}/${f}:${designSha(path.join(dir, ...f.split('/')))}`);
674
+ }
675
+ export function uiDesignHash(epicDir, sha = reviewedSha, parts = null, { askGit = true } = {}) {
676
+ const doc = sha(path.join(epicDir, 'ui-design.md'));
677
+ if (doc === null) return null;
678
+ parts ??= designParts(epicDir, { askGit });
679
+ if (!parts.length) return doc;
680
+ return 'sha256:' + createHash('sha256').update([`ui-design.md:${doc}`, ...parts].join('\n')).digest('hex');
681
+ }
682
+
598
683
  // The reserved id of the Product level in its OLD spelling ("epic zero", `epics/EP-discovery/`), written
599
684
  // by every release before E75 and still read. yad-epic / yad-analysis must never pick this slug — or
600
685
  // `EP-foundation` — for a feature.
@@ -940,12 +1025,14 @@ export function discoveryHash(epicDir, sha = reviewedSha) {
940
1025
  // the whole discovery file set; for every other artifact it is the file. Every file is fingerprinted
941
1026
  // without its frontmatter `status:` line (see `reviewedSha`). `sha` swaps that for a legacy form —
942
1027
  // only `acceptedHashes` passes one.
943
- export function artifactHash(epicDir, artifact, sha = reviewedSha) {
1028
+ // `askGit: false` is for a scratch copy of a commit (`artifactHashAt`): see `ignoredByGit`.
1029
+ export function artifactHash(epicDir, artifact, sha = reviewedSha, { askGit = true } = {}) {
944
1030
  const b = artifactBase(artifact);
945
1031
  if (b === 'architecture') return contractSurfaceHash(epicDir);
946
1032
  if (b === 'stories') return storiesHash(epicDir, sha);
947
1033
  if (b === 'discovery') return discoveryHash(epicDir, sha);
948
1034
  if (b === 'foundation') return foundationHash(epicDir, FOUNDATION_SECTIONS, sha);
1035
+ if (b === 'ui-design') return uiDesignHash(epicDir, sha, null, { askGit });
949
1036
  return sha(path.join(epicDir, artifact.replace(/\/$/, '')));
950
1037
  }
951
1038
 
@@ -953,9 +1040,12 @@ export function artifactHash(epicDir, artifact, sha = reviewedSha) {
953
1040
  // legacy forms (see LEGACY_FORMS). Empty when there is nothing to fingerprint — the same "no claim"
954
1041
  // answer a null `artifactHash` gives. What is WRITTEN is always `artifactHash`; this is for reading.
955
1042
  export function acceptedHashes(epicDir, artifact) {
956
- const current = artifactHash(epicDir, artifact);
1043
+ // The UI design's files are read once and combined with each form of ui-design.md (E164).
1044
+ const parts = artifactBase(artifact) === 'ui-design' ? designParts(epicDir) : null;
1045
+ const hashWith = parts ? (sha) => uiDesignHash(epicDir, sha, parts) : (sha) => artifactHash(epicDir, artifact, sha);
1046
+ const current = hashWith(reviewedSha);
957
1047
  if (current === null) return [];
958
- return [...new Set([current, ...LEGACY_FORMS.map((sha) => artifactHash(epicDir, artifact, sha))].filter(Boolean))];
1048
+ return [...new Set([current, ...LEGACY_FORMS.map(hashWith)].filter(Boolean))];
959
1049
  }
960
1050
 
961
1051
  // Is a recorded fingerprint stale against the accepted ones? Never when nothing was recorded (a manual
@@ -1017,7 +1107,7 @@ export function artifactHashAt(root, epicDir, artifact, rev) {
1017
1107
  copied++;
1018
1108
  }
1019
1109
  } catch (e) { return { ok: false, reason: `the files at ${rev.slice(0, 12)} could not be copied (${e.code || e.message})` }; }
1020
- return { ok: true, hash: artifactHash(dir, artifact), copied };
1110
+ return { ok: true, hash: artifactHash(dir, artifact, reviewedSha, { askGit: false }), copied };
1021
1111
  } finally {
1022
1112
  fs.rmSync(tmp, { recursive: true, force: true });
1023
1113
  }
package/cli/epic.mjs CHANGED
@@ -51,11 +51,15 @@ export function epicIdFrom(slug) {
51
51
 
52
52
  // `type` defaults to null rather than `feature` so an explicit `--type` is distinguishable from no
53
53
  // flag at all — which is what lets an existing `epic.md` supply the answer without overriding the user.
54
- export async function runEpicNew(root, { slug, type = null, profile = null, stub = false, parent = null, inherits = null, today, json = false } = {}) {
54
+ export async function runEpicNew(root, { slug, type = null, profile = null, stub = false, parent = null, inherits = null, today, json = false, returnResult = false } = {}) {
55
+ // `returnResult` (E170, with json): a caller that seeds as one part of its work gets the answer back, and
56
+ // it alone speaks, so stdout stays one JSON document.
57
+ const answer = returnResult ? (payload) => payload : emitJSON;
55
58
  const bail = (message, hint) => {
56
- if (json) emitJSON({ ok: false, error: message, hint });
57
- else { fail(message); if (hint) hand(hint); }
58
59
  process.exitCode = 1;
60
+ if (json) return answer({ ok: false, error: message, hint });
61
+ fail(message); if (hint) hand(hint);
62
+ return undefined;
59
63
  };
60
64
 
61
65
  const epic = epicIdFrom(slug);
@@ -169,7 +173,7 @@ export async function runEpicNew(root, { slug, type = null, profile = null, stub
169
173
  if (parent) {
170
174
  return seedThreaded(root, {
171
175
  epic, dir, files, mdPath, fm, type, parent, profile,
172
- inherits: flagInherits ?? declaredInherits ?? [], headerLists: declaredInherits !== null, today, json, bail,
176
+ inherits: flagInherits ?? declaredInherits ?? [], headerLists: declaredInherits !== null, today, json, bail, answer,
173
177
  });
174
178
  }
175
179
  profile = profile || 'classic';
@@ -230,7 +234,7 @@ export async function runEpicNew(root, { slug, type = null, profile = null, stub
230
234
  // `nextSkills` appears only for a bound chain, the same rule `yad next --json` follows — a key that
231
235
  // showed up on every seed would be one more always-null field for every reader to ignore.
232
236
  if (json) {
233
- return emitJSON({
237
+ return answer({
234
238
  ok: true, epic, type, profile, stub, currentStep: state.currentStep,
235
239
  steps: state.steps.map((s) => s.id), next: skill,
236
240
  ...(skills.length > 1 ? { nextSkills: skills } : {}),
@@ -266,7 +270,7 @@ const listOf = (v) => (Array.isArray(v) ? v : String(v ?? '').replace(/^\s*\[|\]
266
270
  // The threaded half of `yad epic new` (E42): a change, defect or hotfix off an epic that exists. The
267
271
  // engine plans the chain from the parent (`planThreadedSeed`) and this writes it — the ledger, one
268
272
  // provenance record per inherited gate, and the pointer-lock when the contract is carried.
269
- function seedThreaded(root, { epic, dir, files, mdPath, fm, type, parent, profile, inherits, headerLists, today, json, bail }) {
273
+ function seedThreaded(root, { epic, dir, files, mdPath, fm, type, parent, profile, inherits, headerLists, today, json, bail, answer }) {
270
274
  const plan = planThreadedSeed(root, { epic, parent, inherits, type, today });
271
275
  if (!plan.ok) return bail(plan.message, plan.hint);
272
276
  // The route is the parent's. A flag naming the same one is harmless; a different one is refused
@@ -319,7 +323,7 @@ function seedThreaded(root, { epic, dir, files, mdPath, fm, type, parent, profil
319
323
  const skills = stepSkills(first.id, bindingsForEpic(loadSkillBindings(root), state));
320
324
  const carried = state.steps.filter((s) => s.inherited);
321
325
  if (json) {
322
- return emitJSON({
326
+ return answer({
323
327
  ok: true, epic, type, profile: plan.profile, stub: false, parent, thread: plan.thread,
324
328
  inherits, inheritedFrom: plan.owners, pointerLock: plan.lock ? plan.lock.ref : null, anchor: plan.anchor,
325
329
  currentStep: state.currentStep, steps: state.steps.map((s) => s.id), next: skills[0] || null,
package/cli/fold.mjs CHANGED
@@ -30,7 +30,7 @@ import os from 'node:os';
30
30
  import path from 'node:path';
31
31
  import { ok, info, warn, fail, hand, readJSON } from './lib.mjs';
32
32
  import { productConfigPath, isVerifiedLedger } from './manifest.mjs';
33
- import { STEPS, FOUNDATION_EPIC, FOUNDATION_DIR, DISCOVERY_EPIC, artifactBase, artifactPaths, epicRoot, isValidEpicId } from './epic-state.mjs';
33
+ import { STEPS, FOUNDATION_EPIC, FOUNDATION_DIR, DISCOVERY_EPIC, artifactBase, artifactPaths, epicRoot, isValidEpicId, isDesignJunk, UI_DESIGN_DIR } from './epic-state.mjs';
34
34
  import { capturedEpic, gitIn, isOwnerPath, statusEntries, wipName, wipBranch, runCapture } from './capture.mjs';
35
35
  import { resolveDefaultBranch, preflightGuardReadiness } from './productcommit.mjs';
36
36
 
@@ -53,7 +53,32 @@ export function stepPaths(epic, stepId) {
53
53
  if (!step) return null;
54
54
  return [...artifactPaths(artifactBase(step.artifact)), ...(STEP_EXTRAS[stepId] || [])].map((p) => `${epicRel(epic)}/${p}`);
55
55
  }
56
- const covers = (paths, p) => paths.some((s) => p === s || p.startsWith(`${s}/`));
56
+ // A file the system or an editor drops in the UI design's `design/` folder (`.DS_Store`, `x.fig~`) is not
57
+ // the step's: the fingerprint leaves it out (`isDesignJunk`), so a fold that committed it would put a file
58
+ // in the review that no approval covers. It is left on disk like any other file. So is a nested repository
59
+ // there — git lists an untracked one as a folder (`design/kit/`) and a committed submodule by its folder
60
+ // name (`design/kit`), and `isRepo` (a folder holding `.git`) tells the second: `git add` would record a
61
+ // link to another repository, and the fingerprint skips it.
62
+ const covers = (paths, p, isRepo = null) => paths.some((s) => p === s
63
+ || (p.startsWith(`${s}/`) && !(s.endsWith(`/${UI_DESIGN_DIR}`) && (isDesignJunk(p.slice(s.length + 1)) || p.endsWith('/') || !!isRepo?.(p)))));
64
+ // Is this Product-relative path a nested repository or a submodule — a folder holding `.git`, or a gitlink
65
+ // in the index (a submodule never initialised here has no `.git`)? The index's gitlinks are read once, on
66
+ // the first path that needs them, so many changed design files cost one git call. `GIT_LITERAL_PATHSPECS`
67
+ // is cleared so git reads the `:(glob)` pattern as a pattern.
68
+ export const repoAt = (root, env = process.env) => {
69
+ let gitlinks = null;
70
+ const links = () => {
71
+ if (gitlinks) return gitlinks;
72
+ const rest = Object.fromEntries(Object.entries(env).filter(([k]) => k !== 'GIT_LITERAL_PATHSPECS'));
73
+ const r = gitIn(root, rest, { GIT_OPTIONAL_LOCKS: '0' })(['ls-files', '-s', '-z', '--', `:(glob)**/${UI_DESIGN_DIR}/**`]);
74
+ gitlinks = new Set(r.ok ? r.out.split('\0').filter((e) => e.startsWith('160000 ')).map((e) => e.slice(e.indexOf('\t') + 1)) : []);
75
+ return gitlinks;
76
+ };
77
+ return (p) => {
78
+ const bare = p.replace(/\/$/, '');
79
+ return fs.existsSync(path.join(root, ...bare.split('/'), '.git')) || links().has(bare);
80
+ };
81
+ };
57
82
 
58
83
  // The scope is the epic ID in lowercase (#413): the commit-message gate takes a lowercase scope
59
84
  // (`[a-z0-9._-]`), so `docs(EP-x)` failed every review PR. The exact ID stays in the Yad-Epic trailer.
@@ -73,7 +98,7 @@ export const foldMessage = ({ epic, step, folded }) =>
73
98
  // only while its state.json is off the base ref (#162))
74
99
  // ci — ledger changes left for CI (verified mode, every other case)
75
100
  // other — the epic's other changed artifacts, left on disk
76
- export function sortChanges(entries, { epic, step, verified, seeding = false }) {
101
+ export function sortChanges(entries, { epic, step, verified, seeding = false, isRepo = null }) {
77
102
  const own = stepPaths(epic, step) || [];
78
103
  const dir = `${epicRel(epic)}/`;
79
104
  const out = { step: [], seed: [], ledger: [], ci: [], other: [] };
@@ -83,7 +108,7 @@ export function sortChanges(entries, { epic, step, verified, seeding = false })
83
108
  // `??` is untracked, `A` in the first column is added to the index: both are a file being created.
84
109
  // ` A` is a file marked with `git add -N` (intent to add): new too.
85
110
  const creating = xy === '??' || xy[0] === 'A' || xy === ' A';
86
- if (covers(own, p)) out.step.push(p);
111
+ if (covers(own, p, isRepo)) out.step.push(p);
87
112
  // A step owner file (E47) is never folded: an assignment is not authoring, and a fold that carried one
88
113
  // alone would be a "docs: author <step>" commit with nothing authored. It is committed on its own.
89
114
  else if (isOwnerPath(p)) out.other.push(p);
@@ -108,7 +133,7 @@ export function unfoldedPaths(root, epic, base, env = process.env) {
108
133
  const own = stepPaths(epic, authorStepOf(base)) || [];
109
134
  // A per-story branch (`stories-S01`) reviews that one story: another story's edit is not its business.
110
135
  const story = /^stories-S\d+$/i.test(base) ? base.toLowerCase() : null;
111
- return entries.map((e) => e.path).filter((p) => covers(own, p) && (!story || artifactBase(p).toLowerCase() === story));
136
+ return entries.map((e) => e.path).filter((p) => covers(own, p, repoAt(root, env)) && (!story || artifactBase(p).toLowerCase() === story));
112
137
  }
113
138
 
114
139
  // `yad fold <epic> <step>`. Returns a plain object (E1 turns it into the `--json` answer); a refusal
@@ -170,7 +195,7 @@ export async function runFold(root, { epic, step, env = process.env, capture = r
170
195
  const seededAt = (e) => git(['cat-file', '-e', `HEAD:./${epicRel(e)}/.sdlc/state.json`]).ok;
171
196
  const productLevel = epic === FOUNDATION_EPIC || epic === DISCOVERY_EPIC;
172
197
  const seeding = productLevel ? !seededAt(FOUNDATION_EPIC) && !seededAt(DISCOVERY_EPIC) : !seededAt(epic);
173
- const sorted = sortChanges(entries, { epic, step, verified, seeding });
198
+ const sorted = sortChanges(entries, { epic, step, verified, seeding, isRepo: repoAt(root, env) });
174
199
  // What `git add` can take: a path on disk or in the index. A deletion already staged (`D `, from `git rm`
175
200
  // or the old half of a `git mv`) is in neither, and `git add` would refuse it — but it is in HEAD, so
176
201
  // `commit --only` commits the deletion. A path added and then deleted (`AD`) is in none of the three and
package/cli/guide.mjs CHANGED
@@ -32,6 +32,7 @@ import { RULES, HUMAN_ONLY_ACTS, NEVER, classify, askFor, reaches } from './agen
32
32
  import { seededSlugs } from './hook.mjs';
33
33
  import { setupQuestions } from './setup.mjs';
34
34
  import { reposBeside, insideGitRepo, PRODUCT_DIR } from './workspace.mjs';
35
+ import { PREAPPROVED } from './agent-guard.mjs';
35
36
 
36
37
  export const GUIDE_VERSION = 1;
37
38
 
@@ -422,7 +423,8 @@ const thenFor = (person, epic) => (person.some((p) => p.verify)
422
423
  // Build the guide. `root` is the Product, or null when there is none here. `cwd` is where the agent is.
423
424
  // `productElsewhere`: no Product here, but one is a `cd` away (bin/yad.mjs finds it).
424
425
  export function buildGuide(root, { epic = null, cwd = root ?? process.cwd(), runner, productElsewhere = null } = {}) {
425
- const base = { guideVersion: GUIDE_VERSION, rules: RULES, humanOnly: HUMAN_ONLY_ACTS, never: NEVER };
426
+ // `preapproved` (E167): what the agent guard lets run with no permission prompt, and what it never does.
427
+ const base = { guideVersion: GUIDE_VERSION, rules: RULES, humanOnly: HUMAN_ONLY_ACTS, never: NEVER, preapproved: PREAPPROVED };
426
428
  if (!root && productElsewhere) {
427
429
  const where = clean(productElsewhere);
428
430
  const q = shellPath(where);