yadflow 4.5.2 → 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 (101) hide show
  1. package/CHANGELOG.md +206 -0
  2. package/README.md +4 -1
  3. package/bin/commands.mjs +5 -1
  4. package/bin/yad.mjs +174 -18
  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 +396 -123
  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 +442 -33
  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/lib.mjs +12 -1
  23. package/cli/lifecycle/defaults/1.json +96 -0
  24. package/cli/lifecycle/lifecycle.schema.json +121 -0
  25. package/cli/lifecycle.mjs +695 -0
  26. package/cli/next.mjs +34 -11
  27. package/cli/openpr.mjs +81 -5
  28. package/cli/platform.mjs +21 -0
  29. package/cli/pr-list.mjs +49 -3
  30. package/cli/product-index.mjs +6 -3
  31. package/cli/product-token.mjs +186 -0
  32. package/cli/productcommit.mjs +33 -0
  33. package/cli/recommend.mjs +3 -1
  34. package/cli/repo-publish.mjs +2 -2
  35. package/cli/run-checks.mjs +586 -0
  36. package/cli/ship-drift.mjs +384 -0
  37. package/cli/standup.mjs +1 -1
  38. package/cli/status.mjs +282 -0
  39. package/cli/test-build.mjs +1559 -0
  40. package/cli/test-run-checks.mjs +603 -0
  41. package/cli/test-worktree.mjs +520 -0
  42. package/cli/thread.mjs +50 -3
  43. package/cli/tidy.mjs +2 -2
  44. package/cli/toolbox.mjs +36 -5
  45. package/cli/workspace.mjs +4 -1
  46. package/cli/worktree-record.mjs +53 -0
  47. package/cli/worktree.mjs +379 -0
  48. package/package.json +4 -3
  49. package/skills/sdlc/config.yaml +28 -20
  50. package/skills/sdlc/module-help.csv +1 -1
  51. package/skills/yad-backfill/references/backfill.md +8 -1
  52. package/skills/yad-backfill/templates/checks/backfill-check.sh +54 -6
  53. package/skills/yad-change/SKILL.md +3 -0
  54. package/skills/yad-checks/SKILL.md +47 -5
  55. package/skills/yad-checks/references/check-gates.md +124 -12
  56. package/skills/yad-checks/templates/checks/build-test-lint.sh +22 -3
  57. package/skills/yad-checks/templates/checks/commit-message.sh +8 -2
  58. package/skills/yad-checks/templates/checks/contract-check.sh +354 -48
  59. package/skills/yad-checks/templates/checks/epic-open.sh +87 -14
  60. package/skills/yad-checks/templates/checks/ledger-guard.sh +3 -3
  61. package/skills/yad-checks/templates/checks/lineage-check.sh +88 -15
  62. package/skills/yad-checks/templates/checks/member-check.mjs +206 -35
  63. package/skills/yad-checks/templates/checks/package-manager.sh +41 -4
  64. package/skills/yad-checks/templates/checks/product-checkout.sh +161 -13
  65. package/skills/yad-checks/templates/checks/reconcile-debt-check.sh +94 -15
  66. package/skills/yad-checks/templates/checks/risk-map-check.sh +2 -2
  67. package/skills/yad-checks/templates/checks/spec-link.sh +63 -4
  68. package/skills/yad-checks/templates/checks/verified-commits.sh +23 -5
  69. package/skills/yad-checks/templates/github/yad-checks.yml +8 -8
  70. package/skills/yad-checks/templates/gitlab/.gitlab-ci.yml +3 -0
  71. package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml +4 -4
  72. package/skills/yad-checks/templates/gitlab/yad-product-checks.gitlab-ci.yml +16 -3
  73. package/skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml +5 -1
  74. package/skills/yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml +5 -1
  75. package/skills/yad-commit/SKILL.md +4 -2
  76. package/skills/yad-docs/templates/app/package-lock.json +395 -106
  77. package/skills/yad-docs/templates/app/package.json +2 -2
  78. package/skills/yad-engineer-review/SKILL.md +45 -20
  79. package/skills/yad-engineer-review/references/ship-and-record.md +42 -8
  80. package/skills/yad-epic/references/state-schema.md +83 -20
  81. package/skills/yad-implement/SKILL.md +75 -13
  82. package/skills/yad-implement/references/implement-conventions.md +8 -1
  83. package/skills/yad-implement/templates/.gitmessage +3 -0
  84. package/skills/yad-open-pr/SKILL.md +21 -0
  85. package/skills/yad-pr-template/SKILL.md +6 -2
  86. package/skills/yad-pr-template/templates/checks/pr-template.sh +85 -4
  87. package/skills/yad-pr-template/templates/checks/pr-title.sh +1 -1
  88. package/skills/yad-pr-template/templates/github/pull_request_template.md +1 -1
  89. package/skills/yad-pr-template/templates/gitlab/merge_request_templates/Default.md +1 -1
  90. package/skills/yad-product-bridge/SKILL.md +14 -1
  91. package/skills/yad-product-bridge/references/bridge.md +29 -5
  92. package/skills/yad-product-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml +9 -4
  93. package/skills/yad-reconcile/SKILL.md +30 -0
  94. package/skills/yad-review-gate/SKILL.md +8 -2
  95. package/skills/yad-review-gate/references/gating.md +26 -1
  96. package/skills/yad-run/SKILL.md +52 -28
  97. package/skills/yad-run/references/run-loop.md +42 -21
  98. package/skills/yad-spec/SKILL.md +142 -17
  99. package/skills/yad-spec/references/spec-handoff.md +68 -5
  100. package/skills/yad-status/SKILL.md +7 -0
  101. package/skills/yad-stories/references/story-schema.md +1 -1
package/cli/history.mjs CHANGED
@@ -133,7 +133,7 @@ const fold = (s) => s.normalize('NFKC').toLowerCase();
133
133
  // and a digit or two does not match half the hashes in the Product.
134
134
  // Only text is matched, and a PR only as a whole number: `String()` of any other value would match text
135
135
  // that is not in the file (`[object Object]`).
136
- export function searchMatches(item, steps, text) {
136
+ export function searchMatches(item, steps, text, reopens = null) {
137
137
  const needle = fold(String(text).trim());
138
138
  // `12`, `#12`, `PR 12`, `pr12` and `PR #12` all name PR 12.
139
139
  const prWanted = needle.replace(/^(pr\s*#?|#)\s*/, '');
@@ -156,6 +156,13 @@ export function searchMatches(item, steps, text) {
156
156
  if (pr !== null && prQuery !== null && Number(pr) === prQuery) hit('closed.pr', pr, id);
157
157
  if (typeof k.commit === 'string' && needle.length >= 4 && fold(k.commit).startsWith(needle)) hit('closed.commit', k.commit, id);
158
158
  }
159
+ // A reopen (#322) is found by its reason and by who made it.
160
+ for (const r of Array.isArray(reopens) ? reopens : []) {
161
+ if (!isPlainObject(r)) continue;
162
+ const step = typeof r.step === 'string' ? r.step : null;
163
+ words('reopen.reason', r.reason, step);
164
+ words('reopen.by', r.by, step);
165
+ }
159
166
  return hits;
160
167
  }
161
168
 
@@ -322,8 +329,17 @@ export function itemHistory(root, item, { productConfig = null, productConfigWhy
322
329
  thread = { root: null, broken: `the thread could not be walked (${e.code || e.message})` };
323
330
  }
324
331
  }
332
+ // Each `yad gate reopen` (#322): what walked back, and the approvals it revoked — kept here, no longer counted.
333
+ const reopens = (Array.isArray(stateRead.state?.reopens) ? stateRead.state.reopens : []).filter(isPlainObject).map((x) => ({
334
+ step: typeof x.step === 'string' ? x.step : null, date: typeof x.date === 'string' ? x.date : null,
335
+ by: typeof x.by === 'string' ? x.by : null, reason: typeof x.reason === 'string' ? x.reason : null,
336
+ walkedBack: (Array.isArray(x.steps) ? x.steps : []).map((w) => (typeof w?.id === 'string' ? w.id : null)).filter(Boolean),
337
+ revoked: (Array.isArray(x.revokedApprovals) ? x.revokedApprovals : []).filter(isPlainObject)
338
+ .map((a) => ({ step: typeof a.step === 'string' ? a.step : null, approver: typeof a.approver === 'string' ? a.approver : null })),
339
+ }));
325
340
  return {
326
341
  thread,
342
+ reopens,
327
343
  steps: stateRead.steps ? out : null,
328
344
  stepsWhy: stateRead.steps ? null : stateRead.why,
329
345
  approvalsWhy,
@@ -426,7 +442,7 @@ function searchCmd(root, read, keep, text, { json, thread, threadNote }) {
426
442
  for (const item of newestFirst(read.items.filter(keep))) {
427
443
  const r = readState(root, item.id);
428
444
  if (!r.steps) summaryOnly.push({ id: item.id, why: r.why });
429
- const matches = searchMatches(item, r.steps || null, text);
445
+ const matches = searchMatches(item, r.steps || null, text, r.state?.reopens ?? null);
430
446
  if (matches.length) found.push({ ...withShapeDone(item), matches });
431
447
  }
432
448
  if (json) {
@@ -493,6 +509,10 @@ function showCmd(root, read, id, { json }) {
493
509
  for (const a of s.approvals || []) log(` ${c.dim(approvalLine(a))}`);
494
510
  if (s.staleUnknown) log(` ${c.dim(`whether these approvals are stale cannot be told — ${printable(s.staleUnknown)}`)}`);
495
511
  }
512
+ for (const x of story.reopens || []) {
513
+ log(` ${c.dim(`reopened ${printable(x.step) ?? '?'}${x.date ? ` on ${printable(x.date)}` : ''}${x.by ? ` by ${printable(x.by)}` : ''}${x.reason ? ` — ${printable(x.reason)}` : ''}`)}`);
514
+ log(` ${c.dim(`walked back: ${x.walkedBack.map((id) => printable(id)).join(', ') || 'none'}; revoked (not counted): ${x.revoked.length ? x.revoked.map((a) => `${printable(a.approver) ?? '?'} on ${printable(a.step) ?? '?'}`).join(', ') : 'none'}`)}`);
515
+ }
496
516
  const closedCount = story.steps.filter((s) => s.closed).length;
497
517
  info(`${plural(closedCount, 'step')} of ${story.steps.length} ${closedCount === 1 ? 'has' : 'have'} a closing record`);
498
518
  }
package/cli/hook.mjs CHANGED
@@ -292,7 +292,7 @@ export function guardConfig(productRoot) {
292
292
  }
293
293
 
294
294
  const driftLine = (productRoot) =>
295
- `note: ${path.join(productRoot, PROJECT_FILES.productConfig)} and ${PROJECT_FILES.productConfigLegacy} say different things, and one of them is verified, so this edit is guarded — run \`yad migrate\` to choose the copy to keep`;
295
+ `note: ${path.join(productRoot, PROJECT_FILES.productConfig)} and ${PROJECT_FILES.productConfigLegacy} say different things, and one of them is verified, so this edit is guarded — run \`yad migrate --apply --keep product\` (or \`--keep hub\`) to choose the copy to keep`;
296
296
 
297
297
  // What the agent is told when the edit is refused. Names the command that owns each transition —
298
298
  // the whole point of #171 was that the ledger write had no command behind it.
@@ -308,6 +308,7 @@ export function denyMessage({ epic, rel, productRoot }) {
308
308
  ` author step done → review opened yad gate open ${epic} <artifact>`,
309
309
  ' the full advance at merge CI runs `yad gate ci --merged` — nothing to do locally',
310
310
  ` a genuinely broken ledger yad gate repair ${epic} --push`,
311
+ ` an approved step to change yad gate reopen ${epic} <step> --reason "<why>" --push`,
311
312
  '',
312
313
  'Commit the ARTIFACT only (the .md you authored) and hand off to `yad-review-gate`; the ledger',
313
314
  'follows on merge.',
@@ -457,6 +458,7 @@ export function commitDenyMessage({ hits, top }) {
457
458
  ` author step done → review opened yad gate open ${epic} <artifact>`,
458
459
  ' the full advance at merge CI runs `yad gate ci --merged` — nothing to do locally',
459
460
  ` a genuinely broken ledger yad gate repair ${epic} --push`,
461
+ ` an approved step to change yad gate reopen ${epic} <step> --reason "<why>" --push`,
460
462
  ] : []),
461
463
  ...(index ? [' the Product index CI rebuilds it at merge; read it with `yad index --json`'] : []),
462
464
  '',
@@ -15,7 +15,7 @@ import { c, log, ok, info, warn, fail, hand, exists, emitJSON } from './lib.mjs'
15
15
  import path from 'node:path';
16
16
  import { productConfigPath, isVerifiedLedger, SCHEMA_VERSION, settingsEditHint } from './manifest.mjs';
17
17
  import { loadProduct } from './gate.mjs';
18
- import { productGit, resolveDefaultBranch } from './productcommit.mjs';
18
+ import { productGit, resolveDefaultBranch, branchToCommitOn } from './productcommit.mjs';
19
19
  import { buildIndex, writeIndex, indexFreshness, INDEX_FILE } from './product-index.mjs';
20
20
  import { printable } from './epic-state.mjs';
21
21
 
@@ -58,8 +58,8 @@ export async function runIndex(root, { json = false } = {}) {
58
58
  return;
59
59
  }
60
60
  const git = productGit(root);
61
- const branch = git('rev-parse', '--abbrev-ref', 'HEAD').stdout;
62
61
  const defaultBranch = resolveDefaultBranch(git, productConfig);
62
+ const branch = branchToCommitOn(root, git, defaultBranch); // an epic worktree's detached trunk counts (#115)
63
63
  if (branch !== defaultBranch) {
64
64
  fail(`on '${branch}', not the default branch '${defaultBranch}' — ${INDEX_FILE} is written on the default branch only, so a branch never carries it`);
65
65
  hand(`switch to '${defaultBranch}' and re-run (if '${defaultBranch}' is wrong, set default_branch in ${settingsEditHint(root)}); \`yad index --json\` prints it here without writing`);
package/cli/ledger.mjs CHANGED
@@ -241,6 +241,66 @@ export function writeRetroShip(epicDir, { story, repo, task = 'retro', mergeComm
241
241
  }, lockOpts);
242
242
  }
243
243
 
244
+ // Why a ship of (story, task, repo) cannot be written now — `{ reason: 'exists' | 'collision', repo?, file? }` —
245
+ // or null. `yad build merged` asks it too, so it never answers "merged" for a ship this would refuse.
246
+ export function shipBlocked(epicDir, { story, task, repo }) {
247
+ const ships = readShips(epicDir).filter((s) => s.story === story && s.task === task);
248
+ if (ships.some((s) => s.repo === repo)) return { reason: 'exists' };
249
+ const clash = ships.find((s) => safe(s.repo) === safe(repo));
250
+ if (clash) return { reason: 'collision', repo: clash.repo };
251
+ const file = path.join(epicFiles(epicDir).buildLogDir, buildShardName({ story, task, repo }));
252
+ if (fs.existsSync(file)) return { reason: 'collision', file };
253
+ return null;
254
+ }
255
+
256
+ // Record a ship (`yad build ship`, #346): one shard per (story, task, repo), refused when that ship is
257
+ // already recorded, or when another repo's ship shares its file name (`safe()` folds `api.v2` and `api_v2`
258
+ // into one name, and writing the second would overwrite the first). The guard, the collision check and the
259
+ // write are one critical section, as in `writeRetroShip`. Returns { written, reason?, file?, ship? }.
260
+ export function writeShip(epicDir, ship, lockOpts = {}) {
261
+ const { story, task, repo } = ship;
262
+ if (!story || !task || !repo) throw new Error('writeShip: story, task and repo are required');
263
+ return withLedgerLock(buildLogLock(epicDir), () => {
264
+ const blocked = shipBlocked(epicDir, ship);
265
+ if (blocked) return { written: false, ...blocked };
266
+ const file = path.join(epicFiles(epicDir).buildLogDir, buildShardName(ship));
267
+ writeJSON(file, ship);
268
+ return { written: true, file, ship };
269
+ }, lockOpts);
270
+ }
271
+
272
+ // Record one trust run (`yad build trust`, #346): a new shard under its own `uid`, never over another file.
273
+ export function writeTrustRun(epicDir, entry, lockOpts = {}) {
274
+ if (!entry?.story || !entry.repo || !entry.step || !entry.uid) throw new Error('writeTrustRun: story, repo, step and uid are required');
275
+ return withLedgerLock(trustLogLock(epicDir), () => {
276
+ const file = path.join(epicFiles(epicDir).trustLogDir, trustShardName(entry));
277
+ if (fs.existsSync(file)) return { written: false, reason: 'collision', file };
278
+ writeJSON(file, entry);
279
+ return { written: true, file };
280
+ }, lockOpts);
281
+ }
282
+
283
+ // Finalize a trust run's verdict where it lives: its own shard, or its entry in the folded trust-log.json
284
+ // once `yad tidy up` folded it — the human gate's word on a run the orchestrator recorded.
285
+ export function updateTrustRun(epicDir, match, update, lockOpts = {}) {
286
+ return withLedgerLock(trustLogLock(epicDir), () => {
287
+ const f = epicFiles(epicDir);
288
+ // Both copies when a half-applied tidy left the run in each: readers take the folded one then.
289
+ const foldedObj = readJSONStrict(f.trustLog, null);
290
+ const run = Array.isArray(foldedObj?.runs) ? foldedObj.runs.find(match) : null;
291
+ if (run) { update(run); writeJSON(f.trustLog, foldedObj); }
292
+ for (const { name, obj } of readShardDir(f.trustLogDir)) {
293
+ if (match(obj)) {
294
+ update(obj);
295
+ const file = path.join(f.trustLogDir, name);
296
+ writeJSON(file, obj);
297
+ return { found: true, where: 'shard', file, run: obj };
298
+ }
299
+ }
300
+ return run ? { found: true, where: 'folded', file: f.trustLog, run } : { found: false };
301
+ }, lockOpts);
302
+ }
303
+
244
304
  // Find the ship matching `match(ship)` across loose shards (authoritative until folded) then the
245
305
  // folded file, apply `update(ship)`, and write back ONLY the file that holds it. Returns
246
306
  // { found, where, file, ship }; found:false writes nothing (the caller warns). The find and the
package/cli/lib.mjs CHANGED
@@ -103,7 +103,15 @@ export const c = {
103
103
  red: (s) => paint('31', s),
104
104
  cyan: (s) => paint('36', s),
105
105
  };
106
+ // `quietly(fn)`: run `fn` with every line below silenced — for a dry run whose verdict is only an
107
+ // input to the caller's own decision, and would read as a second verdict in a CI log (issue #362).
108
+ let muted = 0;
109
+ export async function quietly(fn) {
110
+ muted++;
111
+ try { return await fn(); } finally { muted--; }
112
+ }
106
113
  export const log = (s = '') => {
114
+ if (muted) return;
107
115
  if (!jsonRun) return console.log(s);
108
116
  jsonRun.afterFail = false;
109
117
  console.error(s);
@@ -112,22 +120,25 @@ export const step = (n, total, title) => log(`\n${c.cyan(`[${n}/${total}]`)} ${c
112
120
  export const ok = (s) => log(` ${c.green('✓')} ${s}`);
113
121
  export const info = (s) => log(` ${c.dim('•')} ${s}`);
114
122
  export const warn = (s) => {
123
+ if (muted) return;
115
124
  if (jsonRun) jsonRun.warnings.push(stripAnsi(s));
116
125
  log(` ${c.yellow('!')} ${s}`);
117
126
  };
118
127
  export const fail = (s) => {
128
+ if (muted) return;
119
129
  log(` ${c.red('✗')} ${s}`);
120
130
  if (jsonRun) { jsonRun.failures.push({ error: stripAnsi(s), hint: null }); jsonRun.afterFail = true; }
121
131
  };
122
132
  // A hint belongs to a failure only when it is the very next line under it — never a later `hand`.
123
133
  export const hand = (s) => {
134
+ if (muted) return;
124
135
  const attach = jsonRun?.afterFail ? jsonRun.failures.at(-1) : null;
125
136
  log(` ${c.yellow('→')} ${s}`);
126
137
  if (attach) attach.hint = stripAnsi(s);
127
138
  };
128
139
  // Like `info`, but to STDERR — for diagnostics emitted by commands whose STDOUT must stay pure (e.g. a
129
140
  // JSON bundle a tool parses). Keeps the human hint visible without corrupting machine-readable output.
130
- export const note = (s) => console.error(` ${c.dim('•')} ${s}`);
141
+ export const note = (s) => { if (!muted) console.error(` ${c.dim('•')} ${s}`); };
131
142
  // Dimmed, indented guidance under a step — what it does / why / what to enter / what skipping means.
132
143
  // Accepts a string or an array of lines so a knowledgeable user can skim past it.
133
144
  export const guide = (lines) => { for (const l of (Array.isArray(lines) ? lines : [lines])) log(` ${c.dim(l)}`); };
@@ -0,0 +1,96 @@
1
+ {
2
+ "schemaVersion": 10,
3
+ "extends": "yadflow-default@1",
4
+ "phases": [
5
+ { "id": "foundation", "name": "Foundation", "level": "product", "runs": "once", "built": true },
6
+ { "id": "discover", "name": "Discover", "part": "Shape", "level": "feature", "runs": "once", "built": true },
7
+ { "id": "design", "name": "Design", "part": "Shape", "level": "feature", "runs": "once", "built": true },
8
+ { "id": "plan", "name": "Plan", "part": "Shape", "level": "feature", "runs": "once", "built": true },
9
+ { "id": "build", "name": "Build", "part": "Build", "level": "feature", "runs": "loop", "over": ["story", "repo"], "built": true },
10
+ { "id": "release", "name": "Release", "part": "Run", "level": "feature", "runs": "loop", "over": ["release"], "built": false },
11
+ { "id": "operate", "name": "Operate", "part": "Run", "level": "feature", "runs": "once", "built": false }
12
+ ],
13
+ "steps": [
14
+ { "id": "foundation", "name": "Foundation", "phase": "foundation", "kind": "author",
15
+ "artifact": { "type": "set", "path": "foundation/",
16
+ "files": ["purpose.md", "market.md", "scope.md", "mvp.md", "roadmap.md", "stack.md", "repos.md", "risks.md"],
17
+ "optional": ["market.md", "risks.md"] },
18
+ "optional": false, "gate": { "riskTags": [] }, "skills": ["yad-discovery"], "behaviours": ["product-level"],
19
+ "extraPaths": [], "inputs": [], "replaces": "discovery",
20
+ "provider": { "id": "yadflow", "version": 1, "origin": "foundation" } },
21
+ { "id": "discovery", "name": "Discovery", "phase": "foundation", "kind": "author",
22
+ "artifact": { "type": "set", "path": "discovery/",
23
+ "files": ["market-research.md", "competitor-analysis.md", "current-state.md", "feasibility.md", "requirements.md", "roadmap.md"],
24
+ "optional": [] },
25
+ "optional": false, "gate": { "riskTags": [] }, "skills": ["yad-discovery"], "behaviours": ["product-level"],
26
+ "extraPaths": [], "inputs": [], "retired": true,
27
+ "provider": { "id": "yadflow", "version": 1, "origin": "discovery" } },
28
+ { "id": "analysis", "name": "Analysis", "phase": "discover", "kind": "author",
29
+ "artifact": { "type": "file", "path": "analysis.md" },
30
+ "optional": false, "gate": { "riskTags": [] }, "skills": ["yad-analysis"], "behaviours": [],
31
+ "extraPaths": [], "inputs": [],
32
+ "provider": { "id": "yadflow", "version": 1, "origin": "analysis" } },
33
+ { "id": "epic", "name": "Epic", "phase": "discover", "kind": "author",
34
+ "artifact": { "type": "file", "path": "epic.md" },
35
+ "optional": false, "gate": { "riskTags": [] }, "skills": ["yad-epic"], "behaviours": ["work-item-source"],
36
+ "extraPaths": [], "inputs": ["analysis"],
37
+ "provider": { "id": "yadflow", "version": 1, "origin": "epic" } },
38
+ { "id": "architecture", "name": "Architecture", "phase": "design", "kind": "author",
39
+ "artifact": { "type": "file", "path": "architecture.md" },
40
+ "optional": false, "gate": { "riskTags": ["contract"] }, "skills": ["yad-architecture"], "behaviours": ["locks-contract"],
41
+ "extraPaths": ["contract.md", ".sdlc/contract-lock.json"], "inputs": ["epic"],
42
+ "provider": { "id": "yadflow", "version": 1, "origin": "architecture" } },
43
+ { "id": "ui-design", "name": "UI design", "phase": "design", "kind": "author",
44
+ "artifact": { "type": "file", "path": "ui-design.md" },
45
+ "optional": false, "gate": { "riskTags": [] }, "skills": ["yad-ui"], "behaviours": [],
46
+ "extraPaths": ["DESIGN.md", ".sdlc/design-links.json"], "inputs": ["epic", "architecture"],
47
+ "provider": { "id": "yadflow", "version": 1, "origin": "ui-design" } },
48
+ { "id": "stories", "name": "Stories", "phase": "plan", "kind": "author",
49
+ "artifact": { "type": "folder", "path": "stories/", "unit": "story" },
50
+ "optional": false, "gate": { "riskTags": [] }, "skills": ["yad-stories"], "behaviours": ["ends-shape"],
51
+ "extraPaths": [], "inputs": ["epic", "architecture", "ui-design"],
52
+ "provider": { "id": "yadflow", "version": 1, "origin": "stories" } },
53
+ { "id": "test-cases", "name": "Test cases", "phase": "plan", "kind": "author",
54
+ "artifact": { "type": "file", "path": "test-cases.md" },
55
+ "optional": false, "gate": { "riskTags": [] }, "skills": ["yad-test-cases"], "behaviours": ["parallel-with-build"],
56
+ "extraPaths": [".sdlc/test-links.json"], "inputs": ["stories"],
57
+ "provider": { "id": "yadflow", "version": 1, "origin": "test-cases" } },
58
+ { "id": "spec", "name": "Spec", "phase": "build", "kind": "author",
59
+ "artifact": null,
60
+ "optional": false, "gate": null, "skills": ["yad-spec"], "behaviours": ["spec-source"],
61
+ "extraPaths": [], "inputs": ["stories"],
62
+ "provider": { "id": "yadflow", "version": 1, "origin": "spec" } },
63
+ { "id": "tasks", "name": "Tasks", "phase": "build", "kind": "author",
64
+ "artifact": null,
65
+ "optional": false, "gate": null, "skills": ["yad-spec"], "behaviours": [],
66
+ "extraPaths": [], "inputs": ["spec"],
67
+ "provider": { "id": "yadflow", "version": 1, "origin": "tasks" } },
68
+ { "id": "implement", "name": "Implement", "phase": "build", "kind": "author",
69
+ "artifact": null,
70
+ "optional": false, "gate": null, "skills": ["yad-implement"], "behaviours": ["code-change"],
71
+ "extraPaths": [], "inputs": ["tasks"],
72
+ "provider": { "id": "yadflow", "version": 1, "origin": "implement" } },
73
+ { "id": "checks", "name": "Checks", "phase": "build", "kind": "author",
74
+ "artifact": null,
75
+ "optional": false, "gate": null, "skills": ["yad-checks"], "behaviours": ["ci-gates"],
76
+ "extraPaths": [], "inputs": ["implement"],
77
+ "provider": { "id": "yadflow", "version": 1, "origin": "checks" } },
78
+ { "id": "engineer-review", "name": "Engineer review", "phase": "build", "kind": "review",
79
+ "artifact": null,
80
+ "optional": false, "gate": null, "skills": ["yad-engineer-review"], "behaviours": ["merge-gate"],
81
+ "extraPaths": [], "inputs": ["checks"],
82
+ "provider": { "id": "yadflow", "version": 1, "origin": "engineer-review" } }
83
+ ],
84
+ "routes": [
85
+ { "id": "classic", "name": "the 10-step chain",
86
+ "steps": ["epic", "architecture", { "id": "ui-design", "optional": true }, "stories", "test-cases"] },
87
+ { "id": "analysis-first", "name": "the 12-step chain",
88
+ "steps": ["analysis", "epic", "architecture", { "id": "ui-design", "optional": true }, "stories", "test-cases"] },
89
+ { "id": "chore", "name": "the upkeep lane", "steps": ["epic", "stories"] },
90
+ { "id": "spike", "name": "the investigation lane", "steps": ["analysis", "epic", "stories"] },
91
+ { "id": "discovery", "name": "the product front-zero", "steps": ["discovery"], "retired": true },
92
+ { "id": "foundation", "name": "the Product Foundation", "steps": ["foundation"] },
93
+ { "id": "lane", "name": "the Build lane", "steps": ["spec", "tasks", "implement", "checks", "engineer-review"] }
94
+ ],
95
+ "plugins": []
96
+ }
@@ -0,0 +1,121 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://github.com/abdelrahmannasr/yadflow/cli/lifecycle/lifecycle.schema.json",
4
+ "title": "yadflow lifecycle definition, version 1",
5
+ "description": "The phases, steps and routes of a yadflow lifecycle. For editors only: yadflow checks a file with its own validator (lifecycleProblems in cli/lifecycle.mjs), which also applies rules a schema cannot express — the behaviour rules; a Build phase runs in a loop and a loop names what it loops \"over\"; a \"set\" artifact lists its \"files\"; a step whose id yadflow ships keeps \"provider\": { \"id\": \"yadflow\", \"origin\": <its id> } and the files it shipped with; no two steps claim files a review branch finds by one name; a Build-loop step has no gate and is never optional. Unknown keys are allowed so a file from a newer yadflow still loads.",
6
+ "type": "object",
7
+ "required": ["schemaVersion", "phases", "steps", "routes"],
8
+ "properties": {
9
+ "$schema": { "type": "string", "description": "Optional: binds this schema in an editor." },
10
+ "schemaVersion": { "type": "integer", "description": "The project's file shape when the file was written." },
11
+ "extends": { "type": "string", "pattern": "^yadflow-default@[1-9][0-9]*$", "description": "The shipped default this file was copied from." },
12
+ "phases": { "type": "array", "items": { "$ref": "#/$defs/phase" } },
13
+ "steps": { "type": "array", "items": { "$ref": "#/$defs/step" } },
14
+ "routes": { "type": "array", "items": { "$ref": "#/$defs/route" } },
15
+ "plugins": { "type": "array", "description": "Reserved for plugins (E142)." }
16
+ },
17
+ "$defs": {
18
+ "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
19
+ "phase": {
20
+ "type": "object",
21
+ "required": ["id", "name", "level"],
22
+ "properties": {
23
+ "id": { "$ref": "#/$defs/id" },
24
+ "name": { "type": "string", "minLength": 1 },
25
+ "description": { "type": "string" },
26
+ "part": { "enum": ["Shape", "Build", "Run"], "description": "Feature phases only; a product phase belongs to no part." },
27
+ "level": { "enum": ["feature", "product"] },
28
+ "runs": { "enum": ["once", "loop"], "default": "once" },
29
+ "over": { "type": "array", "items": { "type": "string" }, "description": "For a loop: what it loops over, such as story and repo." },
30
+ "built": { "type": "boolean", "default": true }
31
+ }
32
+ },
33
+ "artifact": {
34
+ "oneOf": [
35
+ { "type": "null" },
36
+ {
37
+ "type": "object",
38
+ "required": ["type", "path"],
39
+ "properties": {
40
+ "type": { "enum": ["file", "folder", "set"] },
41
+ "path": { "type": "string", "minLength": 1, "description": "Relative to the epic folder. For a \"set\", the path is the set's name, written like a folder (\"foundation/\"); it is the key its review branch uses, not a folder on disk: the set's files sit directly in the set's epic folder." },
42
+ "unit": { "type": "string", "description": "A folder: the word for one item in it, such as story." },
43
+ "files": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1, "pattern": "^(?!\\.\\.?$)[^/\\\\]+$" }, "description": "A set: every file in it, by name; the files sit directly in the set's epic folder." },
44
+ "optional": { "type": "array", "items": { "type": "string" }, "description": "A set: the files it may leave out." },
45
+ "in": { "enum": ["product", "repo"], "description": "Reserved." }
46
+ }
47
+ }
48
+ ]
49
+ },
50
+ "gate": {
51
+ "oneOf": [
52
+ { "type": "null" },
53
+ {
54
+ "type": "object",
55
+ "properties": {
56
+ "riskTags": { "type": "array", "items": { "type": "string" } },
57
+ "skills": { "type": "array", "items": { "type": "string" } }
58
+ }
59
+ }
60
+ ]
61
+ },
62
+ "provider": {
63
+ "type": "object",
64
+ "properties": {
65
+ "id": { "type": "string" },
66
+ "version": { "type": "integer" },
67
+ "origin": { "type": "string", "description": "The step's original id, so a rename is not a removal." }
68
+ }
69
+ },
70
+ "step": {
71
+ "type": "object",
72
+ "required": ["id", "name", "phase", "kind"],
73
+ "properties": {
74
+ "id": { "$ref": "#/$defs/id" },
75
+ "name": { "type": "string", "minLength": 1 },
76
+ "description": { "type": "string" },
77
+ "phase": { "type": "string" },
78
+ "kind": { "enum": ["author", "review"] },
79
+ "artifact": { "$ref": "#/$defs/artifact" },
80
+ "optional": { "type": "boolean", "default": false },
81
+ "gate": { "$ref": "#/$defs/gate" },
82
+ "skills": { "type": "array", "items": { "type": "string", "minLength": 1 } },
83
+ "behaviours": {
84
+ "type": "array",
85
+ "items": { "enum": ["work-item-source", "locks-contract", "ends-shape", "parallel-with-build", "product-level", "spec-source", "code-change", "ci-gates", "merge-gate"] }
86
+ },
87
+ "extraPaths": { "type": "array", "items": { "type": "string", "minLength": 1, "pattern": "[^/]$" } },
88
+ "inputs": { "type": "array", "items": { "type": "string", "minLength": 1 } },
89
+ "retired": { "type": "boolean", "default": false },
90
+ "replaces": { "type": "string" },
91
+ "provider": { "$ref": "#/$defs/provider" }
92
+ }
93
+ },
94
+ "route": {
95
+ "type": "object",
96
+ "required": ["id", "name", "steps"],
97
+ "properties": {
98
+ "id": { "$ref": "#/$defs/id" },
99
+ "name": { "type": "string", "minLength": 1 },
100
+ "description": { "type": "string" },
101
+ "steps": {
102
+ "type": "array",
103
+ "minItems": 1,
104
+ "items": {
105
+ "oneOf": [
106
+ { "type": "string" },
107
+ {
108
+ "type": "object",
109
+ "required": ["id"],
110
+ "properties": { "id": { "type": "string" }, "optional": { "type": "boolean" } }
111
+ }
112
+ ]
113
+ }
114
+ },
115
+ "bindings": { "type": "object" },
116
+ "retired": { "type": "boolean", "default": false },
117
+ "provider": { "$ref": "#/$defs/provider" }
118
+ }
119
+ }
120
+ }
121
+ }