yadflow 4.5.1 → 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 +43 -0
- package/bin/yad.mjs +7 -3
- package/cli/docs.mjs +1 -1
- package/cli/epic-state.mjs +39 -114
- package/cli/gate.mjs +82 -15
- package/cli/lib.mjs +12 -1
- package/cli/lifecycle/defaults/1.json +96 -0
- package/cli/lifecycle/lifecycle.schema.json +121 -0
- package/cli/lifecycle.mjs +695 -0
- package/cli/pr-list.mjs +44 -0
- package/cli/ship-drift.mjs +353 -0
- package/cli/thread.mjs +46 -3
- package/package.json +4 -3
- package/skills/sdlc/config.yaml +27 -19
- package/skills/yad-backfill/references/backfill.md +8 -1
- package/skills/yad-backfill/templates/checks/backfill-check.sh +50 -2
- package/skills/yad-checks/SKILL.md +13 -0
- package/skills/yad-checks/references/check-gates.md +55 -2
- package/skills/yad-checks/templates/checks/contract-check.sh +313 -35
- package/skills/yad-docs/templates/app/package-lock.json +5 -5
- package/skills/yad-docs/templates/app/package.json +1 -1
- package/skills/yad-epic/references/state-schema.md +8 -4
- package/skills/yad-product-bridge/references/bridge.md +26 -5
- package/skills/yad-product-bridge/templates/github/yad-gate-sync.yml +2 -2
- package/skills/yad-reconcile/SKILL.md +24 -0
- package/skills/yad-review-gate/SKILL.md +4 -2
- package/skills/yad-spec/SKILL.md +5 -1
- package/skills/yad-spec/references/spec-handoff.md +18 -2
|
@@ -95,13 +95,15 @@ Each `steps[]` entry:
|
|
|
95
95
|
|
|
96
96
|
### The step catalogue
|
|
97
97
|
|
|
98
|
-
Every one of those ids is defined in **one place
|
|
99
|
-
|
|
98
|
+
Every one of those ids is defined in **one place** — the lifecycle default that ships with yadflow,
|
|
99
|
+
`cli/lifecycle/defaults/1.json` (E134). The engine reads it as `STEPS` in `cli/epic-state.mjs` (E4):
|
|
100
|
+
there, each author step with a gate becomes two rows, the step and its `<id>-review` gate. A row says which phase the step is in, whether it authors an artifact or gates one, which file it
|
|
100
101
|
writes, which skill runs it, and — for a gate — which step it reviews. The phase table, the skill
|
|
101
102
|
tables and the Build order are all views of it, held to it by tests, so a step cannot exist in one and
|
|
102
103
|
be missing from another.
|
|
103
104
|
|
|
104
|
-
The catalogue
|
|
105
|
+
The catalogue ships inside the package. Nothing about it is written into `state.json`, so no file
|
|
106
|
+
shape changed. A shipped default never changes: a new default is a new file (`2.json`).
|
|
105
107
|
|
|
106
108
|
**The one column a project overrides is the skill.** Which skill runs a step is not a fact about the
|
|
107
109
|
lifecycle — it depends on what a team installed — so it lives in `.sdlc/skills.json`, a Product-level
|
|
@@ -161,7 +163,9 @@ marked N/A that this epic's route does not mark optional. An id the catalogue do
|
|
|
161
163
|
### Lifecycle profiles
|
|
162
164
|
|
|
163
165
|
A **profile** is a named, ordered chain of catalogue steps — the route an epic takes. Six are
|
|
164
|
-
defined,
|
|
166
|
+
defined, as the `routes` of the same lifecycle default, and the engine reads them as `LIFECYCLE_PROFILES`
|
|
167
|
+
(`cli/epic-state.mjs`, E5). The default holds one more route, `lane` — the Build order one story walks
|
|
168
|
+
in one repo — which is not a profile. `classic`, `analysis-first` and `discovery`
|
|
165
169
|
are routes the skills already seeded by hand; the two short lanes (E40) and `foundation` (E75) came later:
|
|
166
170
|
|
|
167
171
|
| Profile | Steps | Seeded by |
|
|
@@ -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** —
|
|
106
|
-
|
|
107
|
-
|
|
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
|
-
-
|
|
119
|
-
|
|
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
|
|
@@ -85,7 +85,7 @@ jobs:
|
|
|
85
85
|
with:
|
|
86
86
|
ref: ${{ github.event.pull_request.base.ref }}
|
|
87
87
|
fetch-depth: 0
|
|
88
|
-
- uses: actions/setup-node@
|
|
88
|
+
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
|
|
89
89
|
with:
|
|
90
90
|
node-version: "20"
|
|
91
91
|
- name: Resolve the yadflow pin
|
|
@@ -168,7 +168,7 @@ jobs:
|
|
|
168
168
|
with:
|
|
169
169
|
ref: ${{ github.event.repository.default_branch }}
|
|
170
170
|
fetch-depth: 0
|
|
171
|
-
- uses: actions/setup-node@
|
|
171
|
+
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
|
|
172
172
|
with:
|
|
173
173
|
node-version: "20"
|
|
174
174
|
- name: Resolve the yadflow pin
|
|
@@ -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
|
|
225
|
-
|
|
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
|
|
package/skills/yad-spec/SKILL.md
CHANGED
|
@@ -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.
|
|
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).
|
|
57
|
-
the
|
|
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
|