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.
@@ -102,9 +102,10 @@ repository access decides who may approve. A review with no login is not counted
102
102
  (there is no per-comment id). A new round is opened only when the commenters or their counts change;
103
103
  an unchanged re-read rewrites the latest round in place, keeping its date. Comment rounds are recorded
104
104
  for an **open** step only, so re-visiting a merged review does not append a new round per pass.
105
- - Update the step's PR-ledger `lastSyncedAt` (`product-prs.json` + `hub-prs.json`, same bytes) when the sync **learned something** — every sync on
106
- an open step, and on a closed one only when the approval record actually changed (a re-opened review
107
- that was re-approved). An identical re-sync leaves it alone, so the ledger does not churn.
105
+ - Update the step's PR-ledger `lastSyncedAt` (`product-prs.json` + `hub-prs.json`, same bytes) when the sync **learned something** — on an open
106
+ step when its approvals, comment rounds, step state or nudges changed (or it was never synced), and on
107
+ a closed one only when the approval record actually changed (a re-opened review that was re-approved).
108
+ An identical re-sync leaves it alone, so the ledger does not churn (issue #362).
108
109
  - **Write the ledgers in a canonical order.** `approvals.json`, `comments.json` and the PR ledger
109
110
  (`product-prs.json` + `hub-prs.json`, written together) are
110
111
  sorted on write, so the bytes are a function of the record *set* and never of which step was synced
@@ -115,8 +116,28 @@ repository access decides who may approve. A review with no login is not counted
115
116
  every hop commits and pushes, and the pass ends where it began — an unbounded commit loop with zero
116
117
  semantic change. That is issue #163: ~1,800 bot commits/day on the Product that reported it. Sorting is
117
118
  what makes the "nothing staged → nothing to commit" guard in `gate ci` actually hold.
118
- - Running `sync` twice on the same day with no platform change is a no-op on the ledger — byte-identical, including
119
- `comments.json` and the dated `reviews/*.md` side files.
119
+ - **Move the PR pointer back to an older review only when it passes the gate.** The PR ledger holds ONE pointer per
120
+ artifact, but the sweep can find several merged reviews for one artifact: a re-review on a fresh
121
+ PR/MR, or per-story `review/<epic>/stories-S01`, `stories-S02` branches, which all map to `stories/`.
122
+ On a merge run, `gate ci` keeps the pointer when the PR/MR it was given has a lower number than the
123
+ recorded one (numbers only grow within one repo), and syncs the recorded one instead. A newer review
124
+ still moves it forward, so a re-review of a done step is still read (#156). Merges happen in any
125
+ order, so on a step that is still open the older review is first read in a dry run: if it passes the
126
+ gate, the pointer moves back to it once and the step advances (a held newer review cannot block an
127
+ approved older one, and the manual recovery still works). A pointer from another platform never
128
+ counts as newer, and before the pointer moves to a number other than the one it holds, `gate ci` asks the
129
+ platform that the PR/MR is on the review branch — a mistyped `--pr` the platform places on another
130
+ branch is refused, not recorded (one the platform cannot place is used as given, with a warning). A
131
+ pointer moved to a new number starts with no URL, nudges or sync date of the old review's. The dry run prints nothing; if its platform read fails, the run
132
+ goes red and says the older review could not be checked. Before this, each visit
133
+ moved the pointer to its own PR/MR — done step or not — a real diff every 15 minutes for 7 days,
134
+ committed as "advance … on merge" (issue #362: about 24,400 such commits on the Product that reported it). The commit subject now says
135
+ `advance … on merge` only when a step really advanced; any other merge-run change says `sync … after merge`.
136
+ - Running `sync` again with no platform change is a no-op on the ledger — byte-identical, including
137
+ `comments.json` and the dated `reviews/*.md` side files — on the same day or a later one. A review's
138
+ `lastSyncedAt` and its dated side files move only when its approvals, comment rounds, step state or
139
+ nudges changed (issue #362: a merged review the gate still held used to commit a new date and a new
140
+ dated file every day of the 7-day sweep window).
120
141
 
121
142
  **Upgrading past #163.** The first sweep on a yadflow carrying the fix writes one canonicalizing
122
143
  reorder commit per epic (the records are the same; only their order changes), then converges
@@ -39,6 +39,30 @@ Run `yad reconcile check` (optionally `--thread EP-<genesis>`). For each thread
39
39
  production that no epic in the thread describes. Name the repo (`<repo>: <old>→<new>`).
40
40
  - **Open hotfix debt** — a `reconcile-debt.json` entry still `open`; the next normal change on that
41
41
  thread is blocked until it is paid.
42
+ - **Build records (issue #365, `check` only)** — merged work the build ledger does not record, read from
43
+ each registered repo's clone (its default branch as the clone last saw it; nothing is fetched) and, when
44
+ `gh` / `glab` answers, the source branch names of PRs/MRs merged into the default branch (a squash merge
45
+ keeps only the title, so the branch is where a squashed task still shows). It lists:
46
+ - a **merged task with no ship record** — a `Task:` trailer, a merge commit naming a task branch, a full
47
+ task ID in a commit subject (not a revert), or a merged task branch. For a story that has no ship in
48
+ that repo it offers `yad checkpoint --retro-ship …` once, for a story that predates ledger tracking
49
+ (its status must be `in-build` or `shipped` first); otherwise record the ship as `yad-engineer-review`
50
+ does. A retroactive ship covers only the tasks merged up to it (by its merge commit or date);
51
+ - a story whose every repo holds merged work or a ship, but whose `status:` is not `shipped` — a hint,
52
+ not counted: if no task is left, set `status: shipped`;
53
+ - a **possible match** to check by hand, for a story not yet shipped or recorded in that repo: a full
54
+ story ID in a commit subject with no task, or a short scope tag such as `feat(s06):`. Never counted. A
55
+ story ID only in a commit body is not evidence.
56
+ git runs only in a repo `yad repo clone` would accept as present, or the Product itself for `path: "."`
57
+ (a committed folder shaped like a bare repo would have git read its config), and never fetches; a
58
+ shallow clone is not read. A folder inside a shared checkout reads only its own non-merge commits — never
59
+ a merge title, and never the platform, since neither can be told to belong to one folder (the output
60
+ says so). A repo,
61
+ ledger or `repos.json` that cannot be read in full — including a repo a story names that is not
62
+ registered — says why, and then there is no all-clear. It also lists a merged task whose story no file
63
+ holds (a typo in a `Task:` trailer), and a story that is not compared: it names no repo while more than
64
+ one is registered, or two story files claim its ID even after each falls back to its file name. Only SHAs, PR/MR numbers
65
+ and IDs are printed, never a commit message or a branch name.
42
66
 
43
67
  Writes nothing. This is the read-only sweep a human (or CI) runs to see the picture.
44
68
 
@@ -221,8 +221,10 @@ has the same commenters and counts, it is rewritten in place, so re-running `syn
221
221
  it. **Manual approvals (no `source` tag) are never touched.** For the architecture+contract step, the
222
222
  fingerprint a bridge approval is bound to is the contract surface, so a re-lock makes every approval of
223
223
  the old surface stale: it stays on disk and no longer counts (re-lock invalidates platform approvals
224
- too). Then refresh the `approved.md`
225
- record, set the PR ledger's `lastSyncedAt`, and **re-evaluate Step 3**. **Never hand-write either PR-ledger file.** It lives under two names until v5 — `product-prs.json` (read first) and `hub-prs.json` — and the engine writes both together. Writing one leaves the pair disagreeing, and then every yad command refuses (YAD-STATE-008) until `yad migrate --apply` settles it. Use `yad gate`, which keeps them in step. Under the PR-driven CLI (`yad
224
+ too). Then, when the sync learned
225
+ something (an approval, a comment round, the step state or a nudge changed, or the review was never
226
+ synced), refresh the `approved.md` record and set the PR ledger's `lastSyncedAt`; an unchanged re-sync
227
+ writes neither (issue #362). Always **re-evaluate Step 3**. **Never hand-write either PR-ledger file.** It lives under two names until v5 — `product-prs.json` (read first) and `hub-prs.json` — and the engine writes both together. Writing one leaves the pair disagreeing, and then every yad command refuses (YAD-STATE-008) until `yad migrate --apply` settles it. Use `yad gate`, which keeps them in step. Under the PR-driven CLI (`yad
226
228
  gate sync`), `sync` advances the step when Step 3 passes on a **merged**, fully-resolved, approved PR
227
229
  (the merge is the human act); otherwise it records state and holds the step `in_review`.
228
230
 
@@ -86,7 +86,11 @@ Map `repo` → `{project-root}/demo-repos/<repo>/`. Confirm it exists and is its
86
86
  ### Step 3 — Read the contract (reference, do NOT re-invent)
87
87
  Read `epics/<epic>/contract.md` and `epics/<epic>/.sdlc/contract-lock.json`. The spec's contract
88
88
  inputs (the API shapes, data-model entities, and events the story touches) are **quoted from the
89
- locked surface**, not re-authored. The spec MUST stay within that surface. If the story needs surface
89
+ locked surface**, not re-authored. Each `contracts/` file is Markdown holding the quoted lines, copied
90
+ whole and word for word as ONE consecutive run, in one `<!-- CONTRACT-QUOTE:BEGIN -->` …
91
+ `<!-- CONTRACT-QUOTE:END -->` block, and nothing else but blank lines and, as the first line, the title
92
+ `# Contract slice — <story ID>` (one file per run; notes go in `spec.md` or `plan.md`), so the contract-check gate
93
+ can prove it is a quote and needs no `Contract-Change` trailer (see `references/spec-handoff.md`). The spec MUST stay within that surface. If the story needs surface
90
94
  the contract does not define, STOP and route back to the **architecture gate** — never extend the
91
95
  contract here. (On a route that HAS one; the short lanes do not — see below.)
92
96
 
@@ -53,8 +53,24 @@ comes from the story's acceptance criteria and the **locked contract surface**
53
53
  `OrderStatus`) are **quoted from the contract** and marked as contract-owned; repo-private fields
54
54
  are marked as local.
55
55
  - **`contracts/`** — the slice of the API/event surface this repo implements, **quoted from the locked
56
- `contract.md`** (e.g. `POST /orders` request/response). Add a one-line note that this is a quote of
57
- the locked surface, not a new definition.
56
+ `contract.md`** (e.g. `POST /orders` request/response). Put the quoted lines, **copied whole and word
57
+ for word** from the `CONTRACT-SURFACE` block, between ONE pair of markers per file, under the fixed
58
+ title:
59
+ ```
60
+ # Contract slice — EP-checkout-S01
61
+
62
+ <!-- CONTRACT-QUOTE:BEGIN -->
63
+ - `POST /orders` — place an order from the cart.
64
+ - request: `{ items: { sku: string, qty: number }[], address: string, payment: string, note?: string }`
65
+ <!-- CONTRACT-QUOTE:END -->
66
+ ```
67
+ The block is one **unbroken run** of consecutive surface lines, in their order; to quote two parts of
68
+ the surface, write two files, one block each. The file holds nothing else but blank lines and, first,
69
+ the title `# Contract slice — <story ID>` exactly as shown (or no title) — notes (for example, which
70
+ endpoints this story builds) go in `spec.md` or `plan.md`. Write the slice as
71
+ Markdown (`.md`). The contract-check gate then passes the slice with **no** `Contract-Change` trailer,
72
+ because it can prove every quoted line is in the lock (issue #344). Never reword, reorder or skip a line
73
+ inside a block: that is a surface change, and it needs the trailer.
58
74
  **Do NOT create this folder on a short-lane epic** (`profile: chore` or `spike`). Those routes have
59
75
  no architecture step, so there is no locked `contract.md` to quote and no lock for CI to check the
60
76
  quote against — the gate refuses a slice under a lockless epic. A short-lane story consumes the