yadflow 4.5.2 → 4.6.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.
package/CHANGELOG.md CHANGED
@@ -1,3 +1,39 @@
1
+ # [4.6.0](https://github.com/abdelrahmannasr/yadflow/compare/v4.5.2...v4.6.0) (2026-10-19)
2
+
3
+
4
+ ### Bug Fixes
5
+
6
+ * **checks:** a quote is checked whole, in order, from the commit ([#344](https://github.com/abdelrahmannasr/yadflow/issues/344), [#363](https://github.com/abdelrahmannasr/yadflow/issues/363) review 1) ([b7156ba](https://github.com/abdelrahmannasr/yadflow/commit/b7156ba03c9ae8a2d9890a6b27a2ae00888a6650))
7
+ * **checks:** a quote proof under rebase-merge needs a rebased branch ([#344](https://github.com/abdelrahmannasr/yadflow/issues/344), [#363](https://github.com/abdelrahmannasr/yadflow/issues/363) review 6) ([ba09ee4](https://github.com/abdelrahmannasr/yadflow/commit/ba09ee4e096882e34dc1fc3f6c019ae11ffe8ca4)), closes [#363-style](https://github.com/abdelrahmannasr/yadflow/issues/363-style)
8
+ * **checks:** contract-check reads the change from the merge base, and passes an exact quote ([#363](https://github.com/abdelrahmannasr/yadflow/issues/363), [#344](https://github.com/abdelrahmannasr/yadflow/issues/344)) ([d255fd6](https://github.com/abdelrahmannasr/yadflow/commit/d255fd681b54dfe82fbc3ec9b51f775f2f806900))
9
+ * **checks:** one quote block per file under a fixed title ([#344](https://github.com/abdelrahmannasr/yadflow/issues/344), [#363](https://github.com/abdelrahmannasr/yadflow/issues/363) review 2) ([d3345e3](https://github.com/abdelrahmannasr/yadflow/commit/d3345e3820595bed3e532340b51506241a1b7aae))
10
+ * **checks:** own slice commits count, and the old-git guard has no rename limit ([#344](https://github.com/abdelrahmannasr/yadflow/issues/344), [#363](https://github.com/abdelrahmannasr/yadflow/issues/363) review 5) ([f9ed54c](https://github.com/abdelrahmannasr/yadflow/commit/f9ed54cfde47f45003ca608f0b8c3a1c29399735))
11
+ * **checks:** read every change as the merge into the base ([#363](https://github.com/abdelrahmannasr/yadflow/issues/363) review 4) ([c2858b5](https://github.com/abdelrahmannasr/yadflow/commit/c2858b5fbbf6977ed0f8fc905e5d682eaa1f3438))
12
+ * **checks:** read several merge bases as the merge into the base ([#363](https://github.com/abdelrahmannasr/yadflow/issues/363) review 3) ([260f41b](https://github.com/abdelrahmannasr/yadflow/commit/260f41b1eec8d177407a434ccd3341f61cfe8a69))
13
+ * **gate:** a quiet, honest trial read and a fresh pointer on a new number ([#362](https://github.com/abdelrahmannasr/yadflow/issues/362) review 2) ([70f13aa](https://github.com/abdelrahmannasr/yadflow/commit/70f13aa78db1475201c9547cea02f0cbb79f636b))
14
+ * **gate:** let an older approved review advance past a held newer one ([#362](https://github.com/abdelrahmannasr/yadflow/issues/362) review 1) ([a558ccc](https://github.com/abdelrahmannasr/yadflow/commit/a558ccc2dfe991c6fec3d71fd1df7150d18cf213)), closes [#9](https://github.com/abdelrahmannasr/yadflow/issues/9) [#7](https://github.com/abdelrahmannasr/yadflow/issues/7)
15
+ * **gate:** stop the merge sweep re-committing a settled review ([#362](https://github.com/abdelrahmannasr/yadflow/issues/362)) ([57666d3](https://github.com/abdelrahmannasr/yadflow/commit/57666d3984bfb53b05a946ba6ed7e5a7f9517603)), closes [#156](https://github.com/abdelrahmannasr/yadflow/issues/156)
16
+ * **gate:** warn on an unconfirmed --pr; keep the check on ([#362](https://github.com/abdelrahmannasr/yadflow/issues/362) review 3) ([f1078c6](https://github.com/abdelrahmannasr/yadflow/commit/f1078c66da786f99326e47f5f358bf0618bbf8e9)), closes [#N](https://github.com/abdelrahmannasr/yadflow/issues/N)
17
+ * **lifecycle:** a newer yadflow step is unusable under every file rule (E134 review 6) ([3617a08](https://github.com/abdelrahmannasr/yadflow/commit/3617a08b48a7ae031b7811f3ce93e15b0b228753))
18
+ * **lifecycle:** claim a set's member files; ".sdlc" is the ledger too (E134 review 4) ([0a1ca78](https://github.com/abdelrahmannasr/yadflow/commit/0a1ca78e49fdb66d8a0352fdbb33224821a221b9))
19
+ * **lifecycle:** close the validator gaps review round 1 found (E134) ([23dc3d9](https://github.com/abdelrahmannasr/yadflow/commit/23dc3d918e340db18265da37816523dea2f77555))
20
+ * **lifecycle:** close the validator gaps review round 2 found (E134) ([d2e6f4c](https://github.com/abdelrahmannasr/yadflow/commit/d2e6f4c4a0cbef291fb77eede39028991741ed51))
21
+ * **lifecycle:** empty names, same-step twins, folder levels (E134 review 5) ([7484fd1](https://github.com/abdelrahmannasr/yadflow/commit/7484fd10f6db97186978fab405c4018cde6ec73b))
22
+ * **lifecycle:** one data-driven claims rule for yadflow's files (E134 review 3) ([1b8b972](https://github.com/abdelrahmannasr/yadflow/commit/1b8b9724f76e8d4fb350814b9c1a9b3eadb4a71e))
23
+ * **lifecycle:** the ledger exception is the exact shipped path (E134 review 7) ([b34a115](https://github.com/abdelrahmannasr/yadflow/commit/b34a115ed823b7196572f701590696ea106e0387))
24
+ * **reconcile:** git's "Merge commit/tag ... into" subjects are not read for a task ([#365](https://github.com/abdelrahmannasr/yadflow/issues/365) review 6) ([6dfdb57](https://github.com/abdelrahmannasr/yadflow/commit/6dfdb57cea872f21065b72c96a87dc180e391fd1))
25
+ * **reconcile:** guard the repos read, and no all-clear over what was not read ([#365](https://github.com/abdelrahmannasr/yadflow/issues/365) review 1) ([0a3f37d](https://github.com/abdelrahmannasr/yadflow/commit/0a3f37d5c16639d9252d179e854d6b77e5a82660))
26
+ * **reconcile:** judge each monorepo merge by what its side changed ([#365](https://github.com/abdelrahmannasr/yadflow/issues/365) review 4) ([6a3e5d6](https://github.com/abdelrahmannasr/yadflow/commit/6a3e5d64d28be4dc6b39f04939cbb8e77d9d2ddc))
27
+ * **reconcile:** monorepo folders read their own commits only; shallow clones are not read ([#365](https://github.com/abdelrahmannasr/yadflow/issues/365) review 5) ([30c4f15](https://github.com/abdelrahmannasr/yadflow/commit/30c4f155dba2761cadfcb4c24e94fec9a4b1044a))
28
+ * **reconcile:** monorepo merges, branch names and stories with no repo ([#365](https://github.com/abdelrahmannasr/yadflow/issues/365) review 3) ([d88ef4f](https://github.com/abdelrahmannasr/yadflow/commit/d88ef4f69ef88773b1a8b9f6f6c1c8c41fb52493))
29
+ * **reconcile:** no all-clear over a registry, repo or commit not read in full ([#365](https://github.com/abdelrahmannasr/yadflow/issues/365) review 2) ([32e0ad1](https://github.com/abdelrahmannasr/yadflow/commit/32e0ad1090de188671c69054375ec6df53715056))
30
+
31
+
32
+ ### Features
33
+
34
+ * **lifecycle:** ship the lifecycle as a versioned JSON default (E134) ([9b86025](https://github.com/abdelrahmannasr/yadflow/commit/9b86025e5ab21ae2e89a4e346db99f94ff53ff1e))
35
+ * **reconcile:** report merged work the build ledger does not record ([#365](https://github.com/abdelrahmannasr/yadflow/issues/365)) ([b8173ec](https://github.com/abdelrahmannasr/yadflow/commit/b8173ec26acfe97f12b0fb3ca2fd858464910d67)), closes [#346](https://github.com/abdelrahmannasr/yadflow/issues/346)
36
+
1
37
  ## [4.5.2](https://github.com/abdelrahmannasr/yadflow/compare/v4.5.1...v4.5.2) (2026-10-16)
2
38
 
3
39
 
package/bin/yad.mjs CHANGED
@@ -325,8 +325,9 @@ ${c.bold('Build helpers')}
325
325
  ${c.bold('Feature threads (post-lock change management)')}
326
326
  yad thread List every feature thread (genesis → changes → defects)
327
327
  yad thread <epic> [--json] Show one thread: its epics, the resolved current truth, open debt
328
- yad reconcile [check|refresh|wire] Flag orphan drift + open hotfix debt across threads (advisory,
329
- never a gate — the gates block at merge)
328
+ yad reconcile [check|refresh|wire] Flag orphan drift + open hotfix debt across threads, and merged
329
+ tasks with no build-log ship (advisory, never a gate — the gates
330
+ block at merge)
330
331
 
331
332
  ${c.bold('Interactive docs (generated sites)')}
332
333
  yad docs list Show the docs target + per-site freshness
@@ -906,7 +907,10 @@ async function main() {
906
907
  // own epic) so a `..` or a slash can never traverse out of the epic's stories dir, and a typo'd
907
908
  // cross-epic id is caught here rather than failing obscurely later.
908
909
  if (!story || !/^EP-[a-z0-9-]+-S\d+$/.test(story) || !story.startsWith(`${epic}-S`)) { refuse(`invalid --retro-ship: expected <epic>/<story> with story <epic>-S<NN> (got ${o['retro-ship']})`); break; }
909
- retroShip = { epic, story, repo: o.repo, task: o.task, mergeCommit: o['merge-commit'], today };
910
+ // A SHA, never a ref or a search (`main`, `HEAD`, `:/text`): `yad reconcile check` reads a retro ship's
911
+ // merge commit as the point it covers up to (#365 review 2), and a ref would cover every later merge.
912
+ if (o['merge-commit'] != null && !/^[0-9a-f]{7,64}$/i.test(String(o['merge-commit']))) { refuse('invalid --merge-commit: expected a commit SHA (7 to 64 hex characters), never a branch name or a ref'); break; }
913
+ retroShip = { epic, story, repo: o.repo, task: o.task, mergeCommit: o['merge-commit'] == null ? undefined : String(o['merge-commit']).toLowerCase(), today };
910
914
  }
911
915
  result = await commands.runCheckpoint(o.dir, { push: o.push, allowBranch: o.allowBranch, dryRun: o.dryRun, retroShip });
912
916
  break;
@@ -10,6 +10,9 @@ import {
10
10
  ADVANCE_FROM_AUTOMATION, AUTOMATION_FROM_ADVANCE, DRIVER_FROM_ASSISTANCE, epicFiles, mirrorDrift, preferring,
11
11
  productDrift, PROJECT_FILES, SCHEMA_VERSION, stepAdvance,
12
12
  } from './manifest.mjs';
13
+ import {
14
+ DEFAULT_LIFECYCLE, expandRoutes, expandSteps, featurePhases, laneOrder, productPhases, SENTINELS,
15
+ } from './lifecycle.mjs';
13
16
 
14
17
  const RISK_ESCALATORS = ['contract', 'auth', 'payments'];
15
18
 
@@ -2284,6 +2287,12 @@ export function markInReview(state, step, close = null) {
2284
2287
  // skill files — so "which phase is `stories` in", "which skill authors it", "what does it produce"
2285
2288
  // and "what reviews it" were four separate lookups that nothing held together.
2286
2289
  //
2290
+ // THE DATA IS IN JSON NOW (E134). The rows are no longer written here: they are built from the shipped
2291
+ // lifecycle default, `cli/lifecycle/defaults/1.json`, by `expandSteps` (cli/lifecycle.mjs). In that file
2292
+ // an author step names its gate once (`gate: { riskTags }`) and its gate row is derived from that.
2293
+ // The rows, their fields and their order are exactly what this table held before; a test compares them
2294
+ // with a frozen copy (`cli/fixtures/lifecycle-v4-catalogue.json`).
2295
+ //
2287
2296
  // Everything below this constant is DERIVED from it. `STEP_SKILL`, `BUILD_STEP_SKILL`,
2288
2297
  // `BUILD_STEP_ORDER`, `SHAPE_STEP_PHASE` and `BUILD_STEP_PHASE` are still exported under the names
2289
2298
  // they had, because ~20 call sites and the golden test use them — but they are now VIEWS of this
@@ -2303,8 +2312,8 @@ export function markInReview(state, step, close = null) {
2303
2312
  // `yad foundation new` (E75), and `yad-change` runs `yad epic new --parent` for a threaded change-epic
2304
2313
  // (E42).
2305
2314
  //
2306
- // IT IS CODE, NOT A FILE. Nothing here is written to disk, so no file shape changes and there is
2307
- // nothing to migrate. When a project's `state.json` disagrees with the catalogue, THE FILE WINS for
2315
+ // NOTHING IS WRITTEN TO A PROJECT. The default ships inside the package and no project file holds
2316
+ // these rows, so no file shape changes and there is nothing to migrate. When a project's `state.json` disagrees with the catalogue, THE FILE WINS for
2308
2317
  // this whole major (rule 3): a project may hold a step from a newer yadflow, and a hand-written chain
2309
2318
  // is allowed to be ahead of the tool reading it. `yad doctor` reports the disagreement and changes
2310
2319
  // nothing — the same discipline as `workItemType`.
@@ -2324,7 +2333,7 @@ export function markInReview(state, step, close = null) {
2324
2333
  // placed in the Foundation phase, which belongs to no Part (E75)). This field was called
2325
2334
  // `chain` when E4 landed and was renamed before any release carried it — `chain` is the
2326
2335
  // word for an ordered LIST of steps, which is what a lifecycle profile holds (E5).
2327
- // risk_tags the DEFAULT tags a seed gives this step, copied into the epic's `state.json` where a team
2336
+ // risk_tags the DEFAULT tags a seed gives this step (from its author step's `gate.riskTags`), copied into the epic's `state.json` where a team
2328
2337
  // may add to them by hand. `architecture-review` carries `contract`, which does two separate
2329
2338
  // things: it marks the step escalated (`isEscalated`, so its review PR names the touched
2330
2339
  // repos), and it sets the step's E7 RISK STEP — `contract` +2,
@@ -2335,40 +2344,7 @@ export function markInReview(state, step, close = null) {
2335
2344
  // `spec` and `tasks` are two legs of the same yad-spec ceremony (run-loop.md) and share a skill; the
2336
2345
  // chain renderer collapses the consecutive duplicate. `ready-for-build` and the other SENTINELS are
2337
2346
  // not steps and are not here.
2338
- export const STEPS = [
2339
- // Foundation — the Product level (E75). `yad-discovery` stays the skill name: renaming a skill folder
2340
- // is its own change, with an install migration of its own (LEGACY_SKILLS), and it is not this one.
2341
- { id: 'foundation', phase: 'foundation', kind: 'author', artifact: 'foundation/', skill: 'yad-discovery', level: 'product', risk_tags: [] },
2342
- { id: 'foundation-review', phase: 'foundation', kind: 'review', artifact: 'foundation/', reviews: 'foundation', level: 'product', risk_tags: [] },
2343
- // The OLD spelling of the same level, kept for this whole major (rule 3): a project that has not
2344
- // converted still carries these ids, and dropping the rows would report every step of it as
2345
- // `phase:unknown`. They move into the Foundation phase with the level they always were.
2346
- { id: 'discovery', phase: 'foundation', kind: 'author', artifact: 'discovery/', skill: 'yad-discovery', level: 'product', risk_tags: [] },
2347
- { id: 'discovery-review', phase: 'foundation', kind: 'review', artifact: 'discovery/', reviews: 'discovery', level: 'product', risk_tags: [] },
2348
- // Discover
2349
- { id: 'analysis', phase: 'discover', kind: 'author', artifact: 'analysis.md', skill: 'yad-analysis', level: 'feature', risk_tags: [] },
2350
- { id: 'analysis-review', phase: 'discover', kind: 'review', artifact: 'analysis.md', reviews: 'analysis', level: 'feature', risk_tags: [] },
2351
- { id: 'epic', phase: 'discover', kind: 'author', artifact: 'epic.md', skill: 'yad-epic', level: 'feature', risk_tags: [] },
2352
- { id: 'epic-review', phase: 'discover', kind: 'review', artifact: 'epic.md', reviews: 'epic', level: 'feature', risk_tags: [] },
2353
- // Design
2354
- { id: 'architecture', phase: 'design', kind: 'author', artifact: 'architecture.md', skill: 'yad-architecture', level: 'feature', risk_tags: [] },
2355
- { id: 'architecture-review', phase: 'design', kind: 'review', artifact: 'architecture.md', reviews: 'architecture', level: 'feature', risk_tags: ['contract'] },
2356
- { id: 'ui-design', phase: 'design', kind: 'author', artifact: 'ui-design.md', skill: 'yad-ui', level: 'feature', risk_tags: [] },
2357
- { id: 'ui-design-review', phase: 'design', kind: 'review', artifact: 'ui-design.md', reviews: 'ui-design', level: 'feature', risk_tags: [] },
2358
- // Plan
2359
- { id: 'stories', phase: 'plan', kind: 'author', artifact: 'stories/', skill: 'yad-stories', level: 'feature', risk_tags: [] },
2360
- { id: 'stories-review', phase: 'plan', kind: 'review', artifact: 'stories/', reviews: 'stories', level: 'feature', risk_tags: [] },
2361
- { id: 'test-cases', phase: 'plan', kind: 'author', artifact: 'test-cases.md', skill: 'yad-test-cases', level: 'feature', risk_tags: [] },
2362
- { id: 'test-cases-review', phase: 'plan', kind: 'review', artifact: 'test-cases.md', reviews: 'test-cases', level: 'feature', risk_tags: [] },
2363
- // Build — these run per story per code repo, recorded in build-state/, not in the epic's steps[]
2364
- { id: 'spec', phase: 'build', kind: 'author', artifact: null, skill: 'yad-spec', level: 'feature', risk_tags: [] },
2365
- { id: 'tasks', phase: 'build', kind: 'author', artifact: null, skill: 'yad-spec', level: 'feature', risk_tags: [] },
2366
- { id: 'implement', phase: 'build', kind: 'author', artifact: null, skill: 'yad-implement', level: 'feature', risk_tags: [] },
2367
- { id: 'checks', phase: 'build', kind: 'author', artifact: null, skill: 'yad-checks', level: 'feature', risk_tags: [] },
2368
- // Not the review of a step called `engineer` — a step in its own right, and the one Build step that
2369
- // is a gate. It carries no `reviews`, which is what keeps `checks-review` from resolving.
2370
- { id: 'engineer-review', phase: 'build', kind: 'review', artifact: null, skill: 'yad-engineer-review', level: 'feature', risk_tags: [] },
2371
- ];
2347
+ export const STEPS = expandSteps(DEFAULT_LIFECYCLE);
2372
2348
 
2373
2349
  // ---- lifecycle profiles (E5) ---------------------------------------------------------------------
2374
2350
  //
@@ -2383,6 +2359,13 @@ export const STEPS = [
2383
2359
  // code, and `next.mjs` reads the other one through `setupProfileOf`. Two different things under one
2384
2360
  // word is a trap for whoever reads this next; two clearly different names is not.
2385
2361
  //
2362
+ // THE DATA IS IN JSON NOW (E134). The profiles are built from the `routes` of the shipped lifecycle
2363
+ // default, `cli/lifecycle/defaults/1.json`, by `expandRoutes` (cli/lifecycle.mjs). There, a route lists
2364
+ // only its author steps and the engine adds each step's gate; a route's `name` is the `title` here. The
2365
+ // default also holds one more route, `lane` — the Build order one story walks in one repo — which is not
2366
+ // a profile, because an epic never walks it; it is `BUILD_STEP_ORDER` below. A test compares the
2367
+ // profiles with a frozen copy of the list as it stood before.
2368
+ //
2386
2369
  // THE FIRST THREE WERE NOT NEW ROUTES. They predate this table — they were seeded by hand, in five
2387
2370
  // skill files, until `yad epic new` took over the two feature ones. `yad-analysis`'s own description already calls them "the 12-step chain" and "the 10-step
2388
2371
  // chain". E5 wrote them down in one place and checks projects against them; it did not change what
@@ -2442,68 +2425,11 @@ export const STEPS = [
2442
2425
  // WHAT IS AND IS NOT HERE. Seeding a chain from a profile is `seedState` below, driven by
2443
2426
  // `yad epic new` (E17, cli/epic.mjs); shape 6 is where an epic first RECORDS which profile it is on,
2444
2427
  // and an epic seeded before that field existed still has its route derived by matching its chain
2445
- // (`matchLifecycleProfile`). Which steps are optional per route already lives here and is read per
2428
+ // (`matchLifecycleProfile`). Which steps are optional per route lives in the routes too and is read per
2446
2429
  // EPIC (E35, `optionalStepsFor`); the short chore and spike lanes are E40. Which skill runs a step
2447
2430
  // is bound per project (E6, below) and, more specifically, per route (E51) — both in
2448
2431
  // `.sdlc/skills.json`, never here, so two routes can run different skills for the same step.
2449
- export const LIFECYCLE_PROFILES = [
2450
- {
2451
- id: 'classic',
2452
- title: 'the 10-step chain',
2453
- level: 'feature',
2454
- steps: [
2455
- 'epic', 'epic-review',
2456
- 'architecture', 'architecture-review',
2457
- { id: 'ui-design', optional: true }, { id: 'ui-design-review', optional: true },
2458
- 'stories', 'stories-review',
2459
- 'test-cases', 'test-cases-review',
2460
- ],
2461
- },
2462
- {
2463
- id: 'analysis-first',
2464
- title: 'the 12-step chain',
2465
- level: 'feature',
2466
- steps: [
2467
- 'analysis', 'analysis-review',
2468
- 'epic', 'epic-review',
2469
- 'architecture', 'architecture-review',
2470
- { id: 'ui-design', optional: true }, { id: 'ui-design-review', optional: true },
2471
- 'stories', 'stories-review',
2472
- 'test-cases', 'test-cases-review',
2473
- ],
2474
- },
2475
- {
2476
- id: 'chore',
2477
- title: 'the upkeep lane',
2478
- level: 'feature',
2479
- steps: [
2480
- 'epic', 'epic-review',
2481
- 'stories', 'stories-review',
2482
- ],
2483
- },
2484
- {
2485
- id: 'spike',
2486
- title: 'the investigation lane',
2487
- level: 'feature',
2488
- steps: [
2489
- 'analysis', 'analysis-review',
2490
- 'epic', 'epic-review',
2491
- 'stories', 'stories-review',
2492
- ],
2493
- },
2494
- {
2495
- id: 'discovery',
2496
- title: 'the product front-zero',
2497
- level: 'product',
2498
- steps: ['discovery', 'discovery-review'],
2499
- },
2500
- {
2501
- id: 'foundation',
2502
- title: 'the Product Foundation',
2503
- level: 'product',
2504
- steps: ['foundation', 'foundation-review'],
2505
- },
2506
- ];
2432
+ export const LIFECYCLE_PROFILES = expandRoutes(DEFAULT_LIFECYCLE);
2507
2433
 
2508
2434
  // One profile's steps as plain rows: `{ id, optional }`, in chain order.
2509
2435
  //
@@ -2857,8 +2783,9 @@ export const STEP_SKILL = catalogueSkills(false);
2857
2783
  export const BUILD_STEP_SKILL = catalogueSkills(true);
2858
2784
 
2859
2785
  // The fixed Build order. Used to derive the "remaining chain" from the active step onward even if a
2860
- // repo's `steps` array is partial or out of order. The catalogue's own order IS this order.
2861
- const BUILD_STEP_ORDER = STEPS.filter((s) => s.phase === 'build').map((s) => s.id);
2786
+ // repo's `steps` array is partial or out of order. It is the `lane` route of the lifecycle default
2787
+ // (E134), which lists the same five steps in the catalogue's own order.
2788
+ const BUILD_STEP_ORDER = laneOrder(DEFAULT_LIFECYCLE);
2862
2789
 
2863
2790
  // ---- skill binding (E6) --------------------------------------------------------------------------
2864
2791
  //
@@ -3092,7 +3019,8 @@ export const skillFields = (ids) => ({
3092
3019
  //
3093
3020
  // Release and Operate are NAMED and not built. No step, skill or gate exists for either, and none is
3094
3021
  // invented: `built: false` is the whole of what is known about them. (`skills/sdlc/config.yaml`
3095
- // carries the same table for the skills to read, and a test holds the two together row for row.) They are listed
3022
+ // carries the same table for the skills to read, generated from the lifecycle default by
3023
+ // `scripts/lifecycle-config.mjs`, and a test fails when the two differ.) They are listed
3096
3024
  // rather than left out because a person has to be able to see that the lifecycle does not stop at
3097
3025
  // merge — and a renderer that shows them as planned tells the truth, while one that hides them
3098
3026
  // implies the work ends at Build.
@@ -3108,23 +3036,18 @@ export const skillFields = (ids) => ({
3108
3036
  // * `docs/phase-N-build-plan.md` are the development phases of yadflow itself.
3109
3037
  // So the phase NUMBER is deliberately never printed: "Phase 4" already means something else to anyone
3110
3038
  // who has read those. The name is what is shown.
3111
- export const PHASES = [
3112
- { id: 'discover', name: 'Discover', part: 'Shape', built: true },
3113
- { id: 'design', name: 'Design', part: 'Shape', built: true },
3114
- { id: 'plan', name: 'Plan', part: 'Shape', built: true },
3115
- { id: 'build', name: 'Build', part: 'Build', built: true },
3116
- { id: 'release', name: 'Release', part: 'Run', built: false },
3117
- { id: 'operate', name: 'Operate', part: 'Run', built: false },
3118
- ];
3039
+ //
3040
+ // Built from the `phases` of the lifecycle default (`cli/lifecycle/defaults/1.json`, E134) by
3041
+ // `featurePhases`. There each phase also says whether it runs once or in a loop (`runs`, `over`); those
3042
+ // fields are not part of this view, which keeps exactly the fields it always had.
3043
+ export const PHASES = featurePhases(DEFAULT_LIFECYCLE);
3119
3044
 
3120
3045
  // The PRODUCT level's phase (E75). Kept out of `PHASES` on purpose, because the roadmap's two levels
3121
3046
  // are two different ladders: a feature epic walks the six phases above, once per epic, and the
3122
3047
  // Foundation runs once per product, before any of them. It belongs to no Part — Shape, Build and Run
3123
3048
  // are the rhythms of FEATURE work — so it has no `part`, and a renderer printing the six-phase strip
3124
- // for a Foundation would claim a journey it never takes.
3125
- export const PRODUCT_PHASES = [
3126
- { id: 'foundation', name: 'Foundation', level: 'product', built: true },
3127
- ];
3049
+ // for a Foundation would claim a journey it never takes. Built from the default by `productPhases`.
3050
+ export const PRODUCT_PHASES = productPhases(DEFAULT_LIFECYCLE);
3128
3051
 
3129
3052
  // Which phase each step belongs to. Split in two on purpose, because the `-review` rule differs.
3130
3053
  //
@@ -3140,7 +3063,8 @@ export const PRODUCT_PHASES = [
3140
3063
  //
3141
3064
  // The roadmap also names a `feasibility` step in Discover. Nothing implements it — no skill, no step
3142
3065
  // id, no gate — so it is deliberately absent from the catalogue rather than declared and dead. A new
3143
- // step is added by adding a row to `STEPS`; RENAMING one means adding the new row beside the old and
3066
+ // step is added by adding it to the lifecycle default (a new default file, since a shipped one never
3067
+ // changes); RENAMING one means adding the new row beside the old and
3144
3068
  // keeping both for a major (rule 3), because a project still carrying the old id would otherwise trip
3145
3069
  // `phase:unknown` on every `yad doctor` run until it is migrated.
3146
3070
  //
@@ -3156,8 +3080,9 @@ const STEP_PHASE = { ...SHAPE_STEP_PHASE, ...BUILD_STEP_PHASE };
3156
3080
 
3157
3081
  // `currentStep` markers that are NOT steps: they never appear in `steps[]`, and no phase claims them.
3158
3082
  // `ready-for-build` is the one with a phase anyway — see `currentPhase` below, which is where an epic's
3159
- // position is decided rather than a step's.
3160
- export const SENTINELS = ['ready-for-build', 'backfill-pending', 'backfill-done', 'discovery-done', 'foundation-done'];
3083
+ // position is decided rather than a step's. Defined in cli/lifecycle.mjs, whose validator refuses a
3084
+ // step that takes one of these names, and re-exported here under the name every reader imports.
3085
+ export { SENTINELS };
3161
3086
 
3162
3087
  // The phase a STEP id belongs to, or null for anything this engine does not recognise — a sentinel, a
3163
3088
  // step from a future profile, a typo. Null, never a guess: a renderer showing the wrong phase is worse
package/cli/gate.mjs CHANGED
@@ -5,7 +5,7 @@
5
5
  import fs from 'node:fs';
6
6
  import path from 'node:path';
7
7
  import {
8
- c, log, ok, info, warn, hand, fail, note, readJSON, readJSONStrict, writeJSON, run, pushWithRebase, isPlainObject, writeMirrored, emitJSON, refuse, collectWarning,
8
+ c, log, ok, info, warn, hand, fail, note, quietly, readJSON, readJSONStrict, writeJSON, run, pushWithRebase, isPlainObject, writeMirrored, emitJSON, refuse, collectWarning,
9
9
  } from './lib.mjs';
10
10
  import { OWNING_COMMIT_ENV } from './hook.mjs';
11
11
  import { PROJECT_FILES, isVerifiedLedger , productConfigPath, settingsEditHint } from './manifest.mjs';
@@ -633,7 +633,7 @@ function stageIndexIfClean(root, git, commits = null) {
633
633
  return !git('diff', '--cached', '--quiet', '--', INDEX_FILE).ok;
634
634
  }
635
635
 
636
- export async function gateSync(root, { epic, artifact, today, reader = readPr, finder = findPrForBranch, branchOf = prBranch, poster = postComment, number = null, local = false, dryRun = false, headCount = null } = {}) {
636
+ export async function gateSync(root, { epic, artifact, today, reader = readPr, finder = findPrForBranch, branchOf = prBranch, poster = postComment, number = null, local = false, dryRun = false, headCount = null, probe = null } = {}) {
637
637
  const { productConfig } = loadProduct(root);
638
638
  if (!productConfig?.platform) { warn(`no Product platform configured (${settingsEditHint(root)}) — local gate, nothing to sync`); return { epic, synced: 0, advanced: 0, written: false, gates: [] }; }
639
639
  const platform = productConfig.platform;
@@ -688,7 +688,12 @@ export async function gateSync(root, { epic, artifact, today, reader = readPr, f
688
688
  const s = findReviewStep(state, p.artifact);
689
689
  return s ? state.steps.indexOf(s) : Number.MAX_SAFE_INTEGER;
690
690
  };
691
- const targets = [...resolved.targets].sort((a, b) => stepIndex(a) - stepIndex(b));
691
+ // `probe` (gateCi only, dry runs only): read this PR/MR in place of the recorded pointer, to ask whether
692
+ // an OLDER merged review passes the gate before the pointer is moved back to it (issue #362). A copy, so
693
+ // nothing about the recorded pointer changes.
694
+ if (probe != null && !dryRun) throw new Error('gateSync: probe is for dry runs only');
695
+ const targets = [...resolved.targets].map((p) => (probe != null && p.artifact === artifact ? { ...p, number: probe } : p))
696
+ .sort((a, b) => stepIndex(a) - stepIndex(b));
692
697
  if (!targets.length) {
693
698
  // The stamp still lands (E64): an epic with no review PR on file is exactly one no later sync would
694
699
  // write, so `yad doctor`'s "run `yad gate sync <epic>`" would otherwise repeat for ever.
@@ -747,6 +752,9 @@ export async function gateSync(root, { epic, artifact, today, reader = readPr, f
747
752
  warnUnlockedContract(epicDir, pr.artifact);
748
753
  warnIncompleteDiscovery(epicDir, pr.artifact);
749
754
  const approvalsBefore = JSON.stringify(approvals);
755
+ const commentsBefore = JSON.stringify(comments);
756
+ const stateBefore = JSON.stringify(state);
757
+ const nudgedBefore = JSON.stringify(pr.nudged || []);
750
758
  const recs = mapApprovers(pull.reviews, { headOid: pull.headOid });
751
759
  approvals = upsertBridge(approvals, recs, { stepId: step.id, artifact: pr.artifact, curHash, today, prNumber: pr.number ?? null, closed: alreadyDone, aliases, clashed, accepted: acceptedHashes(epicDir, pr.artifact) });
752
760
 
@@ -769,8 +777,11 @@ export async function gateSync(root, { epic, artifact, today, reader = readPr, f
769
777
  // `chore(gate): advance … [skip ci]` commit on the default branch — every 15 minutes for a week.
770
778
  // That is the same churn the resource_group fix exists to stop, so it must not be reintroduced here.
771
779
  if (!alreadyDone) {
772
- if (!readOnly) writeComments(epicDir, base(pr.artifact), today, blocking);
773
780
  comments = recordComments(comments, { artifact: pr.artifact, stepId: step.id, today, blocking, aliases, clashed });
781
+ // The dated side file only when the round really changed (issue #362): a merged review held by one
782
+ // unresolved thread is re-read every 15 minutes for a week, and the same threads re-written under
783
+ // each new day's name was a daily commit with nothing new in it.
784
+ if (!readOnly && JSON.stringify(comments) !== commentsBefore) writeComments(epicDir, base(pr.artifact), today, blocking);
774
785
  }
775
786
 
776
787
  // Social nudge: a bare APPROVE (no verified engagement) still counts (soft default), but the bot
@@ -857,12 +868,19 @@ export async function gateSync(root, { epic, artifact, today, reader = readPr, f
857
868
  state = markInReview(state, step, { by, date: today, pr: pr.number ?? null, hash: curHash });
858
869
  for (const m of pred.missing) hand(`still needed: ${m}`);
859
870
  }
860
- // Stamp when this run actually learned something: an open step every time, and a closed one only
861
- // when the approval record genuinely changed (a re-opened review that was re-approved). Otherwise
862
- // an identical re-sync would rewrite the date daily and churn the ledger, while a real re-review
863
- // would leave no trace of when it was reconciled.
864
- if (!alreadyDone) { pr.lastSyncedAt = today; open.push(pr); }
865
- else if (JSON.stringify(approvals) !== approvalsBefore) pr.lastSyncedAt = today;
871
+ // Stamp only when this run actually learned something. A closed step: when the approval record
872
+ // genuinely changed (a re-opened review that was re-approved). An open step: when its approvals,
873
+ // comment rounds, state or nudges changed, or it was never synced. Otherwise an identical re-sync
874
+ // rewrote the date — and a fresh dated approval record — every day: a merged review the gate still
875
+ // holds is re-read by the sweep for a week, one commit a day with nothing new (issue #362), while a
876
+ // real change would leave no trace of when it was reconciled.
877
+ const learned = JSON.stringify(approvals) !== approvalsBefore;
878
+ if (!alreadyDone) {
879
+ if (learned || pr.lastSyncedAt == null || JSON.stringify(comments) !== commentsBefore
880
+ || JSON.stringify(state) !== stateBefore || JSON.stringify(pr.nudged || []) !== nudgedBefore) {
881
+ pr.lastSyncedAt = today; open.push(pr);
882
+ }
883
+ } else if (learned) pr.lastSyncedAt = today;
866
884
  synced++;
867
885
  }
868
886
 
@@ -957,7 +975,7 @@ export function convertProductLevel(root, productConfig, { git = (...a) => run('
957
975
  }
958
976
  }
959
977
 
960
- export async function gateCi(root, { branch, pr, merged = false, today, push = true, reader = readPr } = {}) {
978
+ export async function gateCi(root, { branch, pr, merged = false, today, push = true, reader = readPr, branchOf = prBranch } = {}) {
961
979
  const { productConfig } = loadProduct(root);
962
980
  if (!productConfig?.platform) { warn(`no Product platform configured (${settingsEditHint(root)}) — nothing to sync`); return { synced: 0, committed: false, pushed: false }; }
963
981
  const git = (...args) => run('git', args, { cwd: root });
@@ -1049,7 +1067,49 @@ export async function gateCi(root, { branch, pr, merged = false, today, push = t
1049
1067
  // The merge event may fire before any hub-prs record exists (Path B never wrote one pre-merge) —
1050
1068
  // build the entry from the event itself so the advance commit carries it onto the default branch.
1051
1069
  const existing = (ledger.productPrs || []).find((x) => x.artifact === job.artifact);
1052
- const number = Number(job.pr) || existing?.number || null;
1070
+ // Issue #362: a merge run moves the pointer BACK to an older PR/MR only when that review passes the
1071
+ // gate. The scheduled sweep revisits EVERY review merged in its window, and several can share one
1072
+ // artifact (a re-review on a fresh MR; `stories-S01`, `stories-S02` all map to `stories/`). Moving
1073
+ // the one pointer to each in turn was a real diff on every visit — committed and pushed every 15
1074
+ // minutes for 7 days, done step or not. Numbers only grow within one repo, so the newest review wins
1075
+ // and the sweep settles; a newer review still moves it forward, so a re-review of a done step is read
1076
+ // (#156). But an older merged review that PASSES while the newer one is held must still advance the
1077
+ // gate — that is also the manual recovery — so an open step asks first, in a dry run: once it
1078
+ // passes, the step is done and every later visit is quiet.
1079
+ // A pointer from another platform (the Product moved, and numbering started again) is not newer.
1080
+ let older = merged && existing?.number != null && Number(job.pr) > 0 && Number(job.pr) < existing.number
1081
+ && (existing.platform == null || existing.platform === productConfig.platform);
1082
+ let unread = false;
1083
+ if (older && !isPassed(step)) {
1084
+ // Silenced: its verdict is only this decision's input, and would read as a second verdict in the
1085
+ // CI log. Its exit code is this decision's too — a failed read is said, and failed, below.
1086
+ const code = process.exitCode;
1087
+ const trial = await quietly(() => gateSync(root, { epic: job.epic, artifact: job.artifact, today, reader, dryRun: true, probe: Number(job.pr), headCount: sweepCount }));
1088
+ process.exitCode = code;
1089
+ if (trial.gates.some((g) => g.passed)) older = false;
1090
+ else if (!trial.gates.length) {
1091
+ // A failed platform read is not "does not pass": the gate cannot tell, so the run goes red.
1092
+ fail(`${job.epic}: could not read PR #${job.pr} to check it against the gate — syncing #${existing.number}, the review recorded for ${job.artifact}`);
1093
+ process.exitCode = 1;
1094
+ unread = true;
1095
+ }
1096
+ }
1097
+ if (older && !unread) info(`${job.epic}: PR #${job.pr} is older than #${existing.number}, the review recorded for ${job.artifact}, and ${isPassed(step) ? `the step is already ${stepStatus(step) === 'deferred' ? 'deferred' : stepStatus(step) === 'skipped' ? 'skipped' : 'done'}` : 'does not pass the gate'} — syncing #${existing.number}`);
1098
+ // Before the pointer moves to a number other than the one it holds, ask the platform that the PR/MR is on
1099
+ // this review branch: a mistyped `--pr` on the manual recovery would otherwise become the pointer,
1100
+ // and with numbers that only grow it could stay there (issue #362 review). A platform that cannot
1101
+ // answer is not evidence against it — the same rule `gate sync --pr` follows.
1102
+ if (merged && !older && Number(job.pr) > 0 && existing?.number !== Number(job.pr)) {
1103
+ const head = branchOf(productConfig.platform, Number(job.pr), { cwd: root });
1104
+ if (head.ok && head.branch !== job.branch) {
1105
+ fail(`${job.epic}: #${job.pr} is on '${head.branch}', not the review branch '${job.branch}' — check the --pr number`);
1106
+ process.exitCode = 1;
1107
+ continue;
1108
+ }
1109
+ // Said, as `gate sync --pr` says it: an unconfirmed number is used as given, never silently.
1110
+ if (!head.ok) warn(`could not confirm #${job.pr} belongs to ${job.branch} (${head.reason}) — using it as given`);
1111
+ }
1112
+ const number = older ? existing.number : Number(job.pr) || existing?.number || null;
1053
1113
  // Same migration as gateSync, at the one point CI knows the OLD pointer: stamp the approvals it
1054
1114
  // recorded before replacing it, or a re-review on the replacement PR can never be told from a
1055
1115
  // re-read of the old one and stays permanently stale.
@@ -1068,10 +1128,13 @@ export async function gateCi(root, { branch, pr, merged = false, today, push = t
1068
1128
  info(`${job.epic}: recorded PR #${existing.number} on ${stamped} approval(s) that predate PR provenance`);
1069
1129
  }
1070
1130
  }
1071
- if (!existing || existing.number !== number || existing.branch !== job.branch) {
1131
+ if (!older && (!existing || existing.number !== number || existing.branch !== job.branch)) {
1072
1132
  ledger.productPrs = upsertProductPr(ledger.productPrs, {
1133
+ // A new number is a new review: its URL, nudges and sync date are not the old one's.
1073
1134
  step: step.id, artifact: job.artifact, platform: productConfig.platform, number,
1074
- url: existing?.url ?? null, branch: job.branch, lastSyncedAt: existing?.lastSyncedAt ?? null,
1135
+ ...(existing?.number === number
1136
+ ? { url: existing?.url ?? null, branch: job.branch, lastSyncedAt: existing?.lastSyncedAt ?? null, ...(existing?.nudged ? { nudged: existing.nudged } : {}) }
1137
+ : { url: null, branch: job.branch, lastSyncedAt: null }),
1075
1138
  });
1076
1139
  writeMirrored(ledger.files.productPrs, ledger.files.productPrsLegacy, ledger.productPrs);
1077
1140
  }
@@ -1225,7 +1288,11 @@ export async function gateCi(root, { branch, pr, merged = false, today, push = t
1225
1288
  ? 'rebuild the Product index'
1226
1289
  : !branch
1227
1290
  ? 'scheduled gate sync' // sweep is a batch; one subject for the run
1228
- : `advance ${jobs[0].epic}/${jobs[0].base} on merge`;
1291
+ // Say "advance" only when a step really advanced (issue #362): a re-read of a done step that
1292
+ // still changed the ledger is a sync, and a log full of repeated "advance" lines hides the real one.
1293
+ : advancedEpics.size
1294
+ ? `advance ${jobs[0].epic}/${jobs[0].base} on merge`
1295
+ : `sync ${jobs[0].epic}/${jobs[0].base} after merge`;
1229
1296
  // The move, when there is one, is the subject: it is the change a reader of the default branch most
1230
1297
  // needs to find, and a sync subject would name a folder the same commit deletes. The sync goes in the body.
1231
1298
  const subject = moved
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)}`); };