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.
- package/CHANGELOG.md +206 -0
- package/README.md +4 -1
- package/bin/commands.mjs +5 -1
- package/bin/yad.mjs +174 -18
- package/cli/artifact-status.mjs +88 -20
- package/cli/build.mjs +1372 -0
- package/cli/checkpoint.mjs +2 -2
- package/cli/commit.mjs +1 -0
- package/cli/dial.mjs +21 -1
- package/cli/docs.mjs +6 -1
- package/cli/doctor.mjs +133 -26
- package/cli/epic-state.mjs +396 -123
- package/cli/errors.mjs +2 -0
- package/cli/find-product.mjs +36 -2
- package/cli/fold.mjs +9 -5
- package/cli/gate-local.mjs +9 -1
- package/cli/gate.mjs +442 -33
- package/cli/history.mjs +22 -2
- package/cli/hook.mjs +3 -1
- package/cli/index-command.mjs +2 -2
- package/cli/ledger.mjs +60 -0
- 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/next.mjs +34 -11
- package/cli/openpr.mjs +81 -5
- package/cli/platform.mjs +21 -0
- package/cli/pr-list.mjs +49 -3
- package/cli/product-index.mjs +6 -3
- package/cli/product-token.mjs +186 -0
- package/cli/productcommit.mjs +33 -0
- package/cli/recommend.mjs +3 -1
- package/cli/repo-publish.mjs +2 -2
- package/cli/run-checks.mjs +586 -0
- package/cli/ship-drift.mjs +384 -0
- package/cli/standup.mjs +1 -1
- package/cli/status.mjs +282 -0
- package/cli/test-build.mjs +1559 -0
- package/cli/test-run-checks.mjs +603 -0
- package/cli/test-worktree.mjs +520 -0
- package/cli/thread.mjs +50 -3
- package/cli/tidy.mjs +2 -2
- package/cli/toolbox.mjs +36 -5
- package/cli/workspace.mjs +4 -1
- package/cli/worktree-record.mjs +53 -0
- package/cli/worktree.mjs +379 -0
- package/package.json +4 -3
- package/skills/sdlc/config.yaml +28 -20
- package/skills/sdlc/module-help.csv +1 -1
- package/skills/yad-backfill/references/backfill.md +8 -1
- package/skills/yad-backfill/templates/checks/backfill-check.sh +54 -6
- package/skills/yad-change/SKILL.md +3 -0
- package/skills/yad-checks/SKILL.md +47 -5
- package/skills/yad-checks/references/check-gates.md +124 -12
- package/skills/yad-checks/templates/checks/build-test-lint.sh +22 -3
- package/skills/yad-checks/templates/checks/commit-message.sh +8 -2
- package/skills/yad-checks/templates/checks/contract-check.sh +354 -48
- package/skills/yad-checks/templates/checks/epic-open.sh +87 -14
- package/skills/yad-checks/templates/checks/ledger-guard.sh +3 -3
- package/skills/yad-checks/templates/checks/lineage-check.sh +88 -15
- package/skills/yad-checks/templates/checks/member-check.mjs +206 -35
- package/skills/yad-checks/templates/checks/package-manager.sh +41 -4
- package/skills/yad-checks/templates/checks/product-checkout.sh +161 -13
- package/skills/yad-checks/templates/checks/reconcile-debt-check.sh +94 -15
- package/skills/yad-checks/templates/checks/risk-map-check.sh +2 -2
- package/skills/yad-checks/templates/checks/spec-link.sh +63 -4
- package/skills/yad-checks/templates/checks/verified-commits.sh +23 -5
- package/skills/yad-checks/templates/github/yad-checks.yml +8 -8
- package/skills/yad-checks/templates/gitlab/.gitlab-ci.yml +3 -0
- package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml +4 -4
- package/skills/yad-checks/templates/gitlab/yad-product-checks.gitlab-ci.yml +16 -3
- package/skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml +5 -1
- package/skills/yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml +5 -1
- package/skills/yad-commit/SKILL.md +4 -2
- package/skills/yad-docs/templates/app/package-lock.json +395 -106
- package/skills/yad-docs/templates/app/package.json +2 -2
- package/skills/yad-engineer-review/SKILL.md +45 -20
- package/skills/yad-engineer-review/references/ship-and-record.md +42 -8
- package/skills/yad-epic/references/state-schema.md +83 -20
- package/skills/yad-implement/SKILL.md +75 -13
- package/skills/yad-implement/references/implement-conventions.md +8 -1
- package/skills/yad-implement/templates/.gitmessage +3 -0
- package/skills/yad-open-pr/SKILL.md +21 -0
- package/skills/yad-pr-template/SKILL.md +6 -2
- package/skills/yad-pr-template/templates/checks/pr-template.sh +85 -4
- package/skills/yad-pr-template/templates/checks/pr-title.sh +1 -1
- package/skills/yad-pr-template/templates/github/pull_request_template.md +1 -1
- package/skills/yad-pr-template/templates/gitlab/merge_request_templates/Default.md +1 -1
- package/skills/yad-product-bridge/SKILL.md +14 -1
- package/skills/yad-product-bridge/references/bridge.md +29 -5
- package/skills/yad-product-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml +9 -4
- package/skills/yad-reconcile/SKILL.md +30 -0
- package/skills/yad-review-gate/SKILL.md +8 -2
- package/skills/yad-review-gate/references/gating.md +26 -1
- package/skills/yad-run/SKILL.md +52 -28
- package/skills/yad-run/references/run-loop.md +42 -21
- package/skills/yad-spec/SKILL.md +142 -17
- package/skills/yad-spec/references/spec-handoff.md +68 -5
- package/skills/yad-status/SKILL.md +7 -0
- package/skills/yad-stories/references/story-schema.md +1 -1
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "yadflow-docs-site",
|
|
3
3
|
"private": true,
|
|
4
|
-
"version": "0.0.
|
|
4
|
+
"version": "0.0.4",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"scripts": {
|
|
7
7
|
"dev": "vite",
|
|
@@ -30,6 +30,6 @@
|
|
|
30
30
|
"tailwindcss": "^4.2.1",
|
|
31
31
|
"typescript": "~5.9.3",
|
|
32
32
|
"typescript-eslint": "^8.48.0",
|
|
33
|
-
"vite": "^8.
|
|
33
|
+
"vite": "^8.3.5"
|
|
34
34
|
}
|
|
35
35
|
}
|
|
@@ -131,32 +131,57 @@ engineer-review rule is satisfied (Step 2). Then:
|
|
|
131
131
|
`status: skipped`, it was set aside as needing no change: stop, and run
|
|
132
132
|
`yad unskip <epic> <story> --repo <repo>` before recording a ship, so the two records never say opposite
|
|
133
133
|
things (`yad doctor` fails that as `lane:…:contradiction`; `yad checkpoint --retro-ship` refuses it).
|
|
134
|
-
- **
|
|
135
|
-
`
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
134
|
+
- **See whether it merged — ask, do not wait (#355).** The merge is a person's, but you do not need them
|
|
135
|
+
to tell you it happened: run `yad build merged <story> --task <task> --repo <repo> --ship`. It asks the
|
|
136
|
+
platform about the task's PR/MR (found by its branch; `--pr <n>` names it) and answers one `state`
|
|
137
|
+
(`--json`): `merged` — the ship is recorded (through `yad build ship`), go on; `shipped` — it already was;
|
|
138
|
+
`open` — stop and report "waiting for PR/MR #<n> to merge", and run it again when you resume; `closed`
|
|
139
|
+
— closed without a merge: stop and report it; `none` — no PR/MR carries the task yet: open one with
|
|
140
|
+
`yad open-pr`. It asks once and returns; it never waits. It refuses where the platform cannot be read
|
|
141
|
+
(no platform, the repo not cloned here, `gh`/`glab` not logged in), when two PRs/MRs that are not
|
|
142
|
+
closed carry the task, or when a merged PR's merge commit is not on the default branch or names
|
|
143
|
+
another task, or its ship file cannot be written — stop and report what it says.
|
|
144
|
+
- **A follow-up to a shipped task (#350)** — open it from `fix/<story>-<task>-followup-<words>`, its commits
|
|
145
|
+
keeping the task's `Task:` line. Ask about it with `yad build merged <story> --task <task> --repo <repo>
|
|
146
|
+
--follow-up --ship`: the same states, and once merged its merge is added to the task's ship
|
|
147
|
+
(`followUps`), never a second ship. Shape: `references/ship-and-record.md`.
|
|
148
|
+
- **Catch up on merges (#365)** — `yad build sync [<epic>]` records every ship the code repos already show
|
|
149
|
+
(what `yad reconcile check` finds merged with no ship), through `yad build ship`, then `yad build done`
|
|
150
|
+
for each story now fully shipped; it lists what it cannot record. Commit with `yad checkpoint --push`.
|
|
151
|
+
- **Record the ship** — `yad build ship <story> --task <task> --repo <repo> --pr <n>` (what `--ship` runs),
|
|
152
|
+
once the PR/MR has merged. A grouped PR (#350) — several small tasks of one story — ships each task it
|
|
153
|
+
carries from the same `--pr`; a task that is not the branch's is found with `--pr`, as its commits carry it. It reads the merge commit, the branch, the checks that passed, the approvers (with the
|
|
154
|
+
engagement signal), the body's `Risk level:` and the merge date from the platform, refuses a PR that is
|
|
155
|
+
not merged or that comes from another task's branch, and writes the ship to its own shard
|
|
156
|
+
`epics/<epic>/.sdlc/build-log/<story>-<task>-<repo>.json` (shape: `references/ship-and-record.md`). A
|
|
157
|
+
repo whose platform cannot be read records it by hand: `--merge-commit <sha> --approver <login>`. A
|
|
158
|
+
task merged with no PR/MR: `--merge-commit <sha>` and no `--pr` (the commit must be on the default
|
|
159
|
+
branch and name the task in its `Task:` trailer or subject; the platform is asked whether a PR merged it,
|
|
160
|
+
and a PR that did is named instead). It moves the story to `in-build`. Never write the shard by hand.
|
|
161
|
+
- **Update the story state** — when **every** task in each repo's `specs/<story>/tasks.md` (a light spec: the marked tasks block of its
|
|
162
|
+
`spec.md`, #348) has a ship,
|
|
163
|
+
run `yad build done <story>`: it checks that, closes the `engineer-review` step in each lane, and sets
|
|
164
|
+
the story `status: shipped`, so `yad next`, the epic seal and `yad tidy` all read it shipped. It needs
|
|
165
|
+
every repo the story declares cloned here, its `tasks.md` (or light `spec.md` and `link.md`) merged on the default branch, and a lane in
|
|
166
|
+
each repo whose earlier steps are done (a story that never ran through `yad-run`: `yad build start`,
|
|
167
|
+
then `yad build step … done` for each step; one shipped before the Build ledger existed:
|
|
168
|
+
`yad checkpoint --retro-ship`). It refuses, writing nothing, and says what is missing. The chain
|
|
145
169
|
**epic → story → task → PR → mergeCommit** is now traceable end to end.
|
|
146
|
-
- **Finalize the trust verdict (Phase 4).** If this story
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
`
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
170
|
+
- **Finalize the trust verdict (Phase 4).** If this story ran through `yad-run`, the engineer **confirms or
|
|
171
|
+
overrides** the provisional trust verdict the orchestrator recorded for the `implement` run:
|
|
172
|
+
`yad build trust <story> --repo <repo> implement --uid <uid> --verdict <v>`, where `<uid>` is the run of
|
|
173
|
+
this task on the `implement` step in `build-state/<story>.json`: `closed.run` when `closed.task` is this
|
|
174
|
+
task, else the `run` of the entry in its `runs` list whose `task` is this task. It updates that run where it lives
|
|
175
|
+
(its shard, or its entry in the folded `trust-log.json` after `yad tidy up`). The human has the last
|
|
176
|
+
word on the trust signal: a diff merged as authored is `approved-unchanged`; one the engineer edited
|
|
177
|
+
before merge is `approved-with-edits`; a rejected one is `rejected`. This is the run record `yad dial`
|
|
178
|
+
shows the team beside a step's dial (it never weakens the merge gate — the engineer still owns the merge).
|
|
154
179
|
- **Commit the machine-written ledgers.** Run `yad checkpoint --push` from `{project-root}` to commit
|
|
155
180
|
the Build ledgers just written (the `build-log/` shard, and the `trust-log/` shard /
|
|
156
181
|
`build-state/<story>.json` if the story ran through `yad-run`) as one `chore(product): …` audit-trail
|
|
157
182
|
commit — default branch only, staging the shard dirs (`yad tidy up` folds finished shards later),
|
|
158
183
|
never a Shape gate file. It is the Build analogue of the Shape `yad gate` sync. The
|
|
159
|
-
same commit also **carries the story `status:` flip**
|
|
184
|
+
same commit also **carries the story `status:` flip** the commands wrote (`approved → in-build/shipped`,
|
|
160
185
|
#112) — because that story now has a build-log ship, checkpoint stages `stories/<story>.md` alongside
|
|
161
186
|
the ledgers, so the artifact never drifts from build-log and you never fall back to a raw git-to-main
|
|
162
187
|
push. (The code-repo `tasks.md` is committed in its own repo as usual.)
|
|
@@ -24,7 +24,18 @@ ship. Shipping records the merge and updates the story state so the whole chain
|
|
|
24
24
|
|
|
25
25
|
## The build ledger — shard-then-fold (`epics/<epic>/.sdlc/build-log/` → `build-log.json`)
|
|
26
26
|
|
|
27
|
-
Append-only, one record per shipped task
|
|
27
|
+
Append-only, one record per shipped task, written by **`yad build ship <story> --task <T> --repo <r> --pr <n>`**
|
|
28
|
+
(#346) from the merged PR/MR — never by hand. It fills `branch`, `pr`, `mergeCommit`, `gates` (the checks
|
|
29
|
+
that passed on GitHub; the passing job names of the MR's head pipeline on GitLab, one page, child pipelines
|
|
30
|
+
not included), `engineer_review` (approvers bound to the merged head, with the engagement signal), `risk`
|
|
31
|
+
(the body's `Risk level:`, or `null`), `companion.trailer` (the body's `<!-- yad:trailer -->` marker; `cards`
|
|
32
|
+
and `chat` are `false`), `ai_review` (`null`: the platform does not say) and `shippedAt` (the merge date).
|
|
33
|
+
With no platform to read, `--merge-commit <sha>` and `--approver <login>` record the commit and the
|
|
34
|
+
approvers, and the rest is empty. **`yad build merged <story> --task <T> --repo <r> [--pr <n>] --ship`**
|
|
35
|
+
(#355) asks the platform whether the task's PR/MR has merged — found by the task id in its source branch,
|
|
36
|
+
among the repo's newest 100 — and, once it has, records the ship by running `yad build ship` for it; its
|
|
37
|
+
`state` is `shipped`, `merged`, `open`, `closed` or `none`, so the agent checks by itself instead of waiting
|
|
38
|
+
to be told the PR merged. **Storage mirrors the trust log's "loose objects + `git gc`"
|
|
28
39
|
model** so two people shipping different tasks of the same epic never collide on one file:
|
|
29
40
|
- **Per-ship shard:** each ship is its own file `epics/<epic>/.sdlc/build-log/<story>-<task>-<repo>.json`
|
|
30
41
|
= ONE ship object (the record below). `(story, task, repo)` is already unique, so no `uid` is needed;
|
|
@@ -50,22 +61,45 @@ without the `{ epic, ships }` wrapper):
|
|
|
50
61
|
"task": "T01",
|
|
51
62
|
"repo": "backend",
|
|
52
63
|
"branch": "feat/EP-checkout-S01-T01-create-order",
|
|
53
|
-
"pr": "<url|#|local>",
|
|
64
|
+
"pr": "<url|#|none|local>",
|
|
54
65
|
"mergeCommit": "<sha>",
|
|
55
66
|
"gates": ["spec-link", "contract-check", "build-test-lint"],
|
|
56
|
-
"ai_review":
|
|
67
|
+
"ai_review": null,
|
|
57
68
|
"engineer_review": [
|
|
58
69
|
{ "approver": "amelia-dev", "engagement": "verified" },
|
|
59
70
|
{ "approver": "carol-k", "engagement": "none" }
|
|
60
71
|
],
|
|
61
|
-
"companion": { "trailer": true, "cards":
|
|
72
|
+
"companion": { "trailer": true, "cards": false, "chat": false },
|
|
62
73
|
"risk": "low",
|
|
63
|
-
"shippedAt": "2026-06-06"
|
|
74
|
+
"shippedAt": "2026-06-06",
|
|
75
|
+
"followUps": [
|
|
76
|
+
{ "pr": "<url|#|local>", "branch": "fix/EP-checkout-S01-T01-followup-null-check", "mergeCommit": "<sha>", "date": "2026-06-09" }
|
|
77
|
+
]
|
|
64
78
|
}
|
|
65
79
|
]
|
|
66
80
|
}
|
|
67
81
|
```
|
|
68
82
|
|
|
83
|
+
**Grouped PRs (#350).** Several small tasks of one story may share a PR/MR, each commit keeping its own
|
|
84
|
+
`Task:` line. Each task ships from it with `yad build ship <story> --task <T> --repo <r> --pr <n>`: the PR
|
|
85
|
+
carries a task when its branch names it **or** its commits' `Task:` trailers do (each commit's first, read by git's own trailer parser as spec-link reads it; asked of the platform), so
|
|
86
|
+
every ship of the group records the same PR and merge commit. By hand, where the platform cannot be read,
|
|
87
|
+
the merge commit's own merged range (`<sha>^1..<sha>^2`) is read for the `Task:` lines; a squash merge has
|
|
88
|
+
none, so only the task it names ships that way.
|
|
89
|
+
|
|
90
|
+
**Follow-ups (#350).** A fix to a task that has already shipped goes on a **follow-up branch**,
|
|
91
|
+
`fix/<story>-<task>-followup-<words>` (for example `fix/EP-checkout-S01-T01-followup-null-check`). Its
|
|
92
|
+
commits keep the task's `Task:` line, so spec-link passes unchanged. Once it merges, its merge is **added to
|
|
93
|
+
the task's ship** — never a second ship — by `yad build ship <story> --task <T> --repo <r> --pr <n> --follow-up`,
|
|
94
|
+
or by `yad build merged … --follow-up --ship`, which asks the platform about the task's follow-up PRs/MRs.
|
|
95
|
+
`followUps` is optional (absent until the first one) and lists `{ pr, branch, mergeCommit, date }` in the
|
|
96
|
+
order they merged. The ship itself, `yad build done`, tidy and the epic seal are unchanged. Once the task has shipped,
|
|
97
|
+
`yad build merged` answers `shipped` for it, so a follow-up never competes with the task's own PR/MR, and
|
|
98
|
+
`yad build ship` refuses a follow-up PR as the task's ship. Before the task ships, a branch named like a
|
|
99
|
+
follow-up is the task's own only when no plain-named PR/MR for the task is open or merged — a task may be
|
|
100
|
+
about follow-ups (`…-T03-followup-reminders`). A follow-up is opened by a person:
|
|
101
|
+
`yad open-pr --via auto` refuses a task that has shipped.
|
|
102
|
+
|
|
69
103
|
This is the Build analogue of Shape's `approvals.json` — files only, no hidden state, so a
|
|
70
104
|
future service can drive ship by writing the same records. Like the trust log and build-state, it is a
|
|
71
105
|
machine-written ledger committed by **`yad checkpoint`** (the Build analogue of `yad gate` sync),
|
|
@@ -146,9 +180,9 @@ decides machine safety, the merge is still the human act.
|
|
|
146
180
|
|
|
147
181
|
The story frontmatter `status` reflects build progress:
|
|
148
182
|
|
|
149
|
-
- `in-build` — at least one, but not all, of the story's tasks (from `specs/<story>/tasks.md
|
|
150
|
-
records.
|
|
151
|
-
- `shipped` — **every** task in `tasks.md` has a ship record.
|
|
183
|
+
- `in-build` — at least one, but not all, of the story's tasks (from `specs/<story>/tasks.md`, or the
|
|
184
|
+
marked tasks block of a light spec's `spec.md`, #348) have ship records.
|
|
185
|
+
- `shipped` — **every** task in `tasks.md` (or the light spec's tasks block) has a ship record.
|
|
152
186
|
|
|
153
187
|
You write this flip into `stories/<story>.md`, but **do not hand-commit it** — the next
|
|
154
188
|
`yad checkpoint --push` carries it in the same `chore(product)` commit as the ledgers (the story now has a
|
|
@@ -11,8 +11,8 @@ a future release can recognise an older file and upgrade it instead of guessing.
|
|
|
11
11
|
|
|
12
12
|
**When you author one of these files by hand, include the key**, exactly as the examples below show.
|
|
13
13
|
Several kinds here — `state.json` on the seeding path, `change.json`, `contract-lock.json`,
|
|
14
|
-
`
|
|
15
|
-
the
|
|
14
|
+
`design-links.json`, `test-links.json` — are written by skills, not by the CLI. (`build-state/<story-id>.json`
|
|
15
|
+
and the trust-log and build-log shards are written by the `yad build` commands since #346 — never by hand.) `state.json` is the one both write, so omitting the key there makes the file flip between two
|
|
16
16
|
byte forms: the skill writes it without, the next `yad gate sync` adds it back. Write it and there is
|
|
17
17
|
nothing to flip.
|
|
18
18
|
|
|
@@ -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
|
|
@@ -132,18 +134,22 @@ also absent by default:
|
|
|
132
134
|
|
|
133
135
|
```json
|
|
134
136
|
{ "schemaVersion": 10, "kill": { "on": true, "reason": "bad deploy", "by": "al", "date": "2026-09-15" },
|
|
135
|
-
"steps": { "architecture": "auto" } }
|
|
137
|
+
"steps": { "architecture": "auto" }, "actions": { "open-pr": "auto" } }
|
|
136
138
|
```
|
|
137
139
|
|
|
138
140
|
`kill` is written by `yad kill --reason "<why>"` / `yad unkill`; while `on`, every step is held at
|
|
139
141
|
`advance: human`; the record a `yad unkill` or a second `yad kill` replaces is kept as `kill.previous`, one level
|
|
140
142
|
deep. `steps` lists the feature Shape AUTHOR steps (not the Foundation's) the project set to `auto` with `yad dial <step> --to
|
|
141
|
-
auto` — `human` is the key's absence.
|
|
143
|
+
auto` — `human` is the key's absence. `actions` (#356) lists the ACTIONS the project allows without asking,
|
|
144
|
+
the same way: today only `"open-pr": "auto"`, written by `yad dial open-pr --to auto` — the standing approval
|
|
145
|
+
for `yad open-pr --via auto` to open a task's PR/MR once its checks pass. It is the one Build-time dial kept
|
|
146
|
+
here, because it is set for the whole project, not per lane; the kill switch holds it at human too. An older
|
|
147
|
+
yadflow that rewrites this file drops `actions`, which turns the approval off (the safe direction). A Shape `auto` is **recorded, not acted on**: nothing drives a Shape
|
|
142
148
|
step on its own until the engine runs agents (E26). A Build step's dial is not here; it is on its lane in
|
|
143
149
|
`build-state`. A review gate is never `auto`. A file that will not parse is read as the kill switch ON,
|
|
144
150
|
and nothing writes over it. `yad doctor` reports a broken file (`automation`), an active switch
|
|
145
151
|
(`automation:kill`), a gate set to auto (`automation:gate`), a Build step listed here
|
|
146
|
-
(`automation:build-step`), an unknown id or value (`automation:unknown`), and a `kill_switch: true` left in
|
|
152
|
+
(`automation:build-step`), an unknown id or value (`automation:unknown`, under `actions` too), and a `kill_switch: true` left in
|
|
147
153
|
`_bmad/sdlc/config.yaml`, which nothing reads any more (`automation:legacy-kill`).
|
|
148
154
|
|
|
149
155
|
**When a chain disagrees with the catalogue, the chain wins.** A change-epic seeded by hand before E42
|
|
@@ -161,7 +167,9 @@ marked N/A that this epic's route does not mark optional. An id the catalogue do
|
|
|
161
167
|
### Lifecycle profiles
|
|
162
168
|
|
|
163
169
|
A **profile** is a named, ordered chain of catalogue steps — the route an epic takes. Six are
|
|
164
|
-
defined,
|
|
170
|
+
defined, as the `routes` of the same lifecycle default, and the engine reads them as `LIFECYCLE_PROFILES`
|
|
171
|
+
(`cli/epic-state.mjs`, E5). The default holds one more route, `lane` — the Build order one story walks
|
|
172
|
+
in one repo — which is not a profile. `classic`, `analysis-first` and `discovery`
|
|
165
173
|
are routes the skills already seeded by hand; the two short lanes (E40) and `foundation` (E75) came later:
|
|
166
174
|
|
|
167
175
|
| Profile | Steps | Seeded by |
|
|
@@ -360,7 +368,7 @@ step is *not* done, and `blocked` is read by whether it has one, so the two neve
|
|
|
360
368
|
| `review-passed` | `yad gate sync` / `yad gate ci`, or that skill | Its author step, closed when its gate passed because nothing closed it earlier |
|
|
361
369
|
| `review-opened` | `yad gate open` (local ledger) / `yad gate sync` | An author step, closed when its review opened |
|
|
362
370
|
| `repair` | `yad gate repair` | A stranded author step — an escape hatch, so it says so |
|
|
363
|
-
| `auto` / `human` |
|
|
371
|
+
| `auto` / `human` | `yad build step … done [--via auto --run <uid>]`, in `build-state` | A Build lane step: the dial let the run go on by itself, or it stopped for a person |
|
|
364
372
|
|
|
365
373
|
- **Optional keys are left out**, never written as `null`: a close with no PR has no `pr`.
|
|
366
374
|
- **The first close wins.** A step that already has a `closed` keeps it; a re-sync never rewrites it.
|
|
@@ -381,7 +389,7 @@ No release before shape 7 ever wrote a record, so that is exact. The converse is
|
|
|
381
389
|
has a verb: `yad unblock EP-<slug> <step>` (E37) moves `status` off `blocked` **and** removes the record
|
|
382
390
|
in one write, because deleting only the record would turn the step silently into a `todo`. An author
|
|
383
391
|
step whose earlier steps have all passed goes to `in_progress`; anything else, a review gate included,
|
|
384
|
-
goes to `todo`. It never touches `build-state/<story>.json`, which the `yad
|
|
392
|
+
goes to `todo`. It never touches `build-state/<story>.json`, which the `yad build` commands write. On a verified
|
|
385
393
|
Product it refuses once the epic's ledger is on the default branch: CI owns `state.json` there and has no
|
|
386
394
|
step for it yet.
|
|
387
395
|
|
|
@@ -543,6 +551,43 @@ Step debt is **not** `reconcile-debt.json`. That file is a hotfix's whole change
|
|
|
543
551
|
thread and is enforced by the `reconcile-debt` CI gate. Step debt is one step of one epic, and it is a
|
|
544
552
|
reminder, never a gate.
|
|
545
553
|
|
|
554
|
+
### Reopening an approved step (`yad gate reopen`, #322)
|
|
555
|
+
|
|
556
|
+
`yad gate reopen EP-<slug> <step> --reason "<why>"` is the one writer that moves a `done` Shape step back.
|
|
557
|
+
It is allowed only before Build begins: no story has a Build lane (`yad build start` writes one; a lane
|
|
558
|
+
skipped whole does not count) and nothing has shipped. The parallel `test-cases` track may be reopened while
|
|
559
|
+
Build runs, and keeps `currentStep` at `ready-for-build`. The step goes to `in_progress`, and every later step that had started (`in_progress`,
|
|
560
|
+
`in_review`, `done`) goes to `todo`. Each loses its `closed` record. A later step that is skipped,
|
|
561
|
+
deferred, `satisfied` or blocked keeps its state (a blocked review still loses its approvals and review PRs:
|
|
562
|
+
it is a wait, not a decision that the step does not apply). `currentStep` becomes the step (the `test-cases` track
|
|
563
|
+
excepted, as above).
|
|
564
|
+
|
|
565
|
+
What it undid is kept in one list on the epic, which only grows:
|
|
566
|
+
|
|
567
|
+
```json
|
|
568
|
+
"reopens": [{
|
|
569
|
+
"step": "architecture", "date": "2026-10-24", "by": "@al", "reason": "auth model changed",
|
|
570
|
+
"from": "ready-for-build",
|
|
571
|
+
"steps": [{ "id": "architecture-review", "status": "done", "closed": { "by": "@al", "via": "merge", "pr": 4 } }],
|
|
572
|
+
"kept": [{ "id": "ui-design", "status": "skipped" }],
|
|
573
|
+
"revokedApprovals": [{ "artifact": "architecture.md", "step": "architecture-review", "approver": "bo", "status": "approved" }],
|
|
574
|
+
"retiredPrs": [{ "step": "architecture-review", "artifact": "architecture.md", "platform": "github", "number": 4, "branch": "review/EP-x/architecture", "url": null }],
|
|
575
|
+
"contractLock": "sha256:…",
|
|
576
|
+
"laterArtifacts": ["architecture", "ui-design", "stories", "test-cases"],
|
|
577
|
+
"retiredUpTo": { "platform": "github", "number": 30, "artifacts": ["architecture", "ui-design", "stories", "test-cases"] },
|
|
578
|
+
"passes": [{ "step": "architecture-review", "platform": "github", "number": 33, "artifacts": ["ui-design", "stories", "test-cases"] }]
|
|
579
|
+
}]
|
|
580
|
+
```
|
|
581
|
+
|
|
582
|
+
| Rule | Detail |
|
|
583
|
+
|------|--------|
|
|
584
|
+
| Revoked approvals | MOVED out of `approvals.json` into `revokedApprovals`, unchanged. Every reader counts only the records in `approvals.json`, so no yad version counts them, and the platform sync cannot write them back |
|
|
585
|
+
| In order again | on an epic with a reopen, a review is held while any earlier step has not passed: `yad gate open` refuses it, `gate sync` / `gate ci` neither read nor record its PR/MR, and `gate advance` refuses it (`heldByReopen`). Each time a review after the reopened step passes (walked back or not), a row in `passes[]` (`{ step, platform, number, artifacts }`) retires every later review PR/MR numbered up to the platform's newest then (that review's own number when the platform cannot answer), so each later step is reviewed afresh. A walked-back step cannot be skipped or deferred until its review passes again |
|
|
586
|
+
| Retired review PRs | MOVED out of `product-prs.json` / `hub-prs.json` into `retiredPrs`. `retiredUpTo` (`{ platform, number, artifacts }`) also retires every review PR/MR of the reopened step and the later steps numbered up to the platform's newest at the reopen, so one the ledger never recorded is covered. `yad gate sync` and `yad gate ci` never pass a gate on a retired PR/MR, or on an older one for the same artifact (numbers only grow in one repo). A fresh `yad gate open` has a higher number |
|
|
587
|
+
| `contract-lock.json` | kept; its hash at the reopen is recorded. The new architecture review re-locks it |
|
|
588
|
+
| Comments and `reviews/` | kept as they are; the new review's comments continue from the next round |
|
|
589
|
+
| No shape change | an older yad ignores `reopens`; nothing it reads changes meaning |
|
|
590
|
+
|
|
546
591
|
### `test-cases` is a parallel, non-blocking track
|
|
547
592
|
|
|
548
593
|
`test-cases` (and its `test-cases-review` gate) sit in `steps[]` after `stories-review`, but they are a
|
|
@@ -573,12 +618,23 @@ The shared procedure (run once the `EP-<slug>` is known):
|
|
|
573
618
|
2. Branch name = `<step>/EP-<slug>`. If it already exists, check it out; otherwise create it from the
|
|
574
619
|
Product's default branch (`git checkout -b <step>/EP-<slug>`).
|
|
575
620
|
3. Author the step's artifact(s) on that branch, and end the step with `yad fold EP-<slug> <step>` (E44): one
|
|
576
|
-
commit, `docs(
|
|
621
|
+
commit, `docs(ep-<slug>): author <step>` (the epic ID in lowercase: the commit-message gate takes a lowercase
|
|
622
|
+
scope), of that step's files only. The drafts stay on the private
|
|
577
623
|
`yad/wip/…` capture branch. With `ledger: local` the epic's ledger changes ride in the same commit;
|
|
578
624
|
with `ledger: verified` only a brand-new epic's seed does (its ledger is not in HEAD yet), together with
|
|
579
625
|
its new person-written `.sdlc/` files such as a change-epic's `change.json`. The verified ledger's `review/…` branch is created
|
|
580
626
|
separately at review time and is untouched by this step.
|
|
581
627
|
|
|
628
|
+
**Parallel agents: one worktree per epic (#115).** When several agents work at once, each on its own
|
|
629
|
+
epic, none of them branches in the shared checkout: `yad worktree add EP-<slug> --all` makes the epic's own
|
|
630
|
+
folder beside the Product (`<product>--EP-<slug>/`) and beside each code repo the epic names
|
|
631
|
+
(`<repo>--EP-<slug>/`), detached at `origin/<default>`. The agent's session starts IN that folder, and the
|
|
632
|
+
procedure above runs there unchanged (step 2 creates the branch from `origin/<default>`, since the default
|
|
633
|
+
branch itself is checked out in the main tree). To get back to the trunk there, `git fetch origin <default>`
|
|
634
|
+
then `git switch --detach origin/<default>`; `yad checkpoint` and the other default-branch commands work
|
|
635
|
+
from that detached HEAD. When the epic's work is merged and pushed, `yad worktree remove EP-<slug> --all`;
|
|
636
|
+
it refuses while anything there is not saved.
|
|
637
|
+
|
|
582
638
|
**How the seed reaches the default branch.** The `.sdlc/` ledger is seeded once — by `yad epic new`
|
|
583
639
|
(or `yad foundation new` for the Product level) — on the **entry** step's authoring branch (`analysis/…`,
|
|
584
640
|
`epic/…`, `change/…`, `foundation/…`, or `discovery/…` for a product level still in its old spelling).
|
|
@@ -591,7 +647,8 @@ gate the ledger is already on the default branch: cut the review branch from the
|
|
|
591
647
|
artifact only, and leave `.sdlc/{state,approvals,comments,product-prs,hub-prs}.json` and `reviews/*.md` to CI.
|
|
592
648
|
|
|
593
649
|
## `approvals.json`
|
|
594
|
-
Append-only ledger (an array)
|
|
650
|
+
Append-only ledger (an array) — except that `yad gate reopen` (#322) moves the records of the reviews it
|
|
651
|
+
walks back into `state.json`'s `reopens[]`, where they are kept and no longer counted. Each entry:
|
|
595
652
|
|
|
596
653
|
```json
|
|
597
654
|
{ "artifact": "epic.md", "step": "epic-review", "approver": "<platform login>", "status": "approved", "date": "<YYYY-MM-DD>", "source": "<bridge, optional>" }
|
|
@@ -651,7 +708,8 @@ PR/MR opened on the Product (sibling of `approvals.json`, so the locked `state.j
|
|
|
651
708
|
The same array is written under two names, with identical bytes: `product-prs.json` (the name from shape 3,
|
|
652
709
|
read first) and `hub-prs.json` (the old name, written until v5 and read only when `product-prs.json` is
|
|
653
710
|
absent — E122). `yad gate sync` may add `nudged`, the logins it has already asked to
|
|
654
|
-
use the review companion, so it never asks them twice.
|
|
711
|
+
use the review companion, so it never asks them twice. `yad gate reopen` (#322) moves the entries of the
|
|
712
|
+
reviews it walks back into `state.json`'s `reopens[].retiredPrs`; a retired PR/MR never passes its gate again.
|
|
655
713
|
|
|
656
714
|
## `design-links.json`
|
|
657
715
|
Present only when the `ui-design` step materialized the design in a connected design tool
|
|
@@ -700,7 +758,8 @@ steps to carry their own advance dial so the orchestrator (`yad-run`) can read i
|
|
|
700
758
|
whether to advance on its own. Two new files under `.sdlc/` do this.
|
|
701
759
|
|
|
702
760
|
> **Who commits these.** `build-state/<story-id>.json`, `trust-log.json`, and `build-log.json` are
|
|
703
|
-
> **machine-written** by
|
|
761
|
+
> **machine-written** by the `yad build` commands (#346: `start`, `step`, `trust`, `ship`, `done`, which
|
|
762
|
+
> the `yad-run` and `yad-engineer-review` skills run — never written by hand) and committed by
|
|
704
763
|
> **`yad checkpoint`** — the Build analogue of the Shape `yad gate ci` sync. It lands them as
|
|
705
764
|
> one `chore(product): sync Build state — <epic>/<story> by @<login>` audit-trail commit, on the
|
|
706
765
|
> default branch, staging **only** these three ledgers by an explicit allowlist (never a Shape
|
|
@@ -737,8 +796,10 @@ Each `steps[]` entry:
|
|
|
737
796
|
| `id` | `spec`, `tasks`, `implement`, `checks`, `engineer-review` | Build step identity (the `back_steps` from `config.yaml` + the human merge gate). |
|
|
738
797
|
| `automation` / `advance` | `human_approve`/`human` \| `machine_advance`/`auto` | Dial 2, written under both names (the OLD one is read). Defaults to `human_approve`; `yad dial <epic> <story> --repo <r> <step> --to auto` flips it (E34 — nothing to earn), never on the `engineer-review` gate. |
|
|
739
798
|
| `locked` | `true` \| `false` | `engineer-review` is `true` — it never auto-advances (build plan §E). |
|
|
740
|
-
| `closed` | `{ by, date, via, run }` | Written by
|
|
741
|
-
| `
|
|
799
|
+
| `closed` | `{ by, date, via, run, task? }` | Written by `yad build step <story> --repo <r> <step> done` when the lane moves past the step (the `engineer-review` step by `yad build done`): `via` is `auto` or `human`, `run` names the trust-log run (E18), and `task` the task it closed for, when given. See "Closing records". |
|
|
800
|
+
| `opened` | `[{ task, pr, url, via, run, by, date }]` | On the **lane** (beside `steps`), not on a step: each task PR/MR opened on the project's standing approval, `yad open-pr --via auto` (#356). `via` is `auto`; `run` is the `checks` trust run that allowed it: that task's newest close. A grouped PR (#350) is listed once per task it carries, each with its own run. `yad build merged` reads the number from here before it searches. A PR/MR a person opened is not listed. |
|
|
801
|
+
| `runs` | `[{ by, date, via, run, task }]` | `implement` and the steps after it are walked once per task: `yad build step … implement in_progress --task <T>` reopens them for the next task once the lane is at `engineer-review`, and keeps each earlier close here, so the engineer review finds the run of the task it finalizes. |
|
|
802
|
+
| `status` | the same **step states** as the Shape chain | Lifecycle. This file is **not** migrated to shape 7 — the `yad build` commands write it, not the engine, so a rewrite would be undone by their next write. `yad-run` advances `done` steps and marks a halted lane `blocked` **with a `record`** naming the halt cause (a failed check, a scope overrun, a contract touch): that record is what separates a halted lane from one nobody started, because a bare `blocked` is the pre-shape-7 spelling of `todo` and still reads that way here. A lane halted by an older `yad-run` carries no record and reads as `todo` until the next run rewrites it — nothing advances past it either way. |
|
|
742
803
|
|
|
743
804
|
`currentStep` is the `id` the orchestrator is waiting on / about to run for that repo. The file is
|
|
744
805
|
created when a story enters Build; all dials start `advance: human` (`automation: human_approve`) (the `config.yaml`
|
|
@@ -803,11 +864,12 @@ back:
|
|
|
803
864
|
{
|
|
804
865
|
"story": "EP-<slug>-S0N",
|
|
805
866
|
"repo": "backend",
|
|
806
|
-
"step": "
|
|
867
|
+
"step": "implement",
|
|
807
868
|
"uid": "<short-unique-token>",
|
|
869
|
+
"task": "T01",
|
|
808
870
|
"automation": "human_approve", "advance": "human",
|
|
809
871
|
"verdict": "approved-unchanged",
|
|
810
|
-
"signals": { "
|
|
872
|
+
"signals": { "human_edited_diff": false, "scope_overrun": false, "contract_touch": false },
|
|
811
873
|
"ranBy": "machine",
|
|
812
874
|
"date": "<YYYY-MM-DD>",
|
|
813
875
|
"note": "<optional>"
|
|
@@ -822,6 +884,7 @@ back:
|
|
|
822
884
|
| `verdict` | `approved-unchanged` \| `approved-with-edits` \| `rejected` | The trust signal. **Provisional verdict is derived** (below); the human gate for that step confirms or overrides it and finalizes the entry. |
|
|
823
885
|
| `signals` | object | The raw inputs the provisional verdict was derived from. The fields present depend on the step (table below). |
|
|
824
886
|
| `ranBy` | `machine` \| `human` | Whether the orchestrator advanced it or a human did. |
|
|
887
|
+
| `task` | a task id, optional | The task the run was for, on the `implement`/`checks` legs (`yad build trust … --task <T>`). |
|
|
825
888
|
|
|
826
889
|
**Per-step `signals` fields** (only the relevant ones are set; others may be omitted or `n/a`):
|
|
827
890
|
|
|
@@ -830,7 +893,7 @@ back:
|
|
|
830
893
|
| `spec` | `human_edited_spec` | the human who accepts `specs/<story>/` (`yad-spec` Step 8) |
|
|
831
894
|
| `tasks` | `task_rescoped` | first consume by `yad-implement` (Step 8) |
|
|
832
895
|
| `implement` | `human_edited_diff`, `scope_overrun`, `contract_touch` | engineer review at `yad-engineer-review` |
|
|
833
|
-
| `checks` | `checks` (`pass`\|`fail`) | the gate run itself (objective) |
|
|
896
|
+
| `checks` | `checks` (`pass`\|`fail`\|`n/a`) | the gate run itself (objective) |
|
|
834
897
|
|
|
835
898
|
**Deriving the provisional verdict** (build plan Step A; extended for `spec`/`tasks` in Phase 4b — the
|
|
836
899
|
same three-way shape, anchored to each step's human gate, never self-graded):
|
|
@@ -39,17 +39,61 @@ declares; it does not redesign, does not widen the contract, and does not pick u
|
|
|
39
39
|
- `repo` — the code repo the story's spec lives in (one of the story's `repos`).
|
|
40
40
|
- `task` — the ONE atomic task ID to implement, e.g. `T01` (ask if not provided).
|
|
41
41
|
|
|
42
|
+
## Ask the human-only questions first, in one batch
|
|
43
|
+
|
|
44
|
+
<!-- The same section is in yad-spec and yad-implement: a test holds the two copies equal (#357). -->
|
|
45
|
+
|
|
46
|
+
Some decisions belong to the human alone. If one turns up late, the long work stops and waits for it.
|
|
47
|
+
So before the long work starts, list every such decision together with every open question, and ask
|
|
48
|
+
them all in **one** message.
|
|
49
|
+
|
|
50
|
+
**Human-only decisions** — never decide these yourself, and never pick a default just to keep going:
|
|
51
|
+
- **Security trade-offs.** Who may call or see what, what data is stored, logged or shown, how
|
|
52
|
+
people sign in, and any check made weaker on purpose.
|
|
53
|
+
- **Secrets and tokens.** Which secret or token the work needs, who creates it, where it is kept,
|
|
54
|
+
and what it may access.
|
|
55
|
+
- **Contract changes.** The work needs the shared cross-repo surface (the locked `contract.md`) to
|
|
56
|
+
change. Nobody decides this here, and no answer lets the step go on: it goes back to the
|
|
57
|
+
architecture gate, or, on a short lane, to a new epic on `classic`. Name it in the batch so the
|
|
58
|
+
person learns it now, not halfway through. Then end the step with this skill's own contract STOP
|
|
59
|
+
(`yad-spec` Step 3, `yad-implement` Step 5), and its `contract touch` halt under `yad-run`.
|
|
60
|
+
- **Changes that cannot be undone.** Deleting data, or a data migration with no way back.
|
|
61
|
+
|
|
62
|
+
**How to ask:**
|
|
63
|
+
1. Number each item. For each one, say what must be decided, why only a human can decide it, and the
|
|
64
|
+
options, with your recommendation where a safe one exists.
|
|
65
|
+
2. Wait for the answers, then record them where the step below says, so no later step asks again.
|
|
66
|
+
`yad-implement` first reads the answers `yad-spec` recorded in `spec.md`, and asks only what is
|
|
67
|
+
still open.
|
|
68
|
+
3. If nothing is open, say "no human-only decisions or open questions" and go on.
|
|
69
|
+
4. If a new one still turns up later, stop, collect any others that are open at that point, and ask
|
|
70
|
+
them together. In the report, say the first batch missed it.
|
|
71
|
+
5. **Run by the orchestrator (`yad-run`):** a stop to ask — the first batch or a later one — is its
|
|
72
|
+
own halt, **waiting on human decisions**. Run `yad build step <story> --repo <repo> <step> blocked
|
|
73
|
+
--reason "waiting on human decisions: <the questions, short>"` (add `--task <task>` on the
|
|
74
|
+
implement leg). Write **no** trust entry: the step's output is not finished, and files already
|
|
75
|
+
drafted (such as `spec.md`) are not output to judge. Then stop. Once a person answers, the step
|
|
76
|
+
runs again and goes on from what is already drafted. That is a resume, not a re-run, so it is not
|
|
77
|
+
graded `rejected` for being run again.
|
|
78
|
+
|
|
79
|
+
<!-- end: Ask the human-only questions first -->
|
|
80
|
+
|
|
42
81
|
## On Activation
|
|
43
82
|
|
|
44
83
|
### Step 1 — Resolve the spec and the task
|
|
45
|
-
Read `demo-repos/<repo>/specs/<story>/tasks.md
|
|
84
|
+
Read `demo-repos/<repo>/specs/<story>/tasks.md` — or, for a **light spec** (`link.md` says
|
|
85
|
+
`spec-mode: light`, #348), the lines between `<!-- yad:tasks -->` and `<!-- /yad:tasks -->` in its
|
|
86
|
+
`spec.md`, and nothing outside them. Find the block for `<task>` (`## <task> — …`). Read
|
|
46
87
|
its one-line goal and its **Files:** list (the declared file boundary) and the acceptance criterion it
|
|
47
|
-
satisfies. If the task ID is not in `tasks.md
|
|
88
|
+
satisfies. If the task ID is not in `tasks.md` (or the light block), STOP. Confirm the spec exists (Step A ran); if not,
|
|
48
89
|
STOP and point at `yad-spec`.
|
|
49
90
|
|
|
50
91
|
### Step 2 — Resolve the code repo and branch
|
|
51
92
|
Confirm `demo-repos/<repo>/` is its own git repo (`.git` present). From its default branch, create the
|
|
52
|
-
task branch `feat/<story>-<task>-<short-slug>`.
|
|
93
|
+
task branch `feat/<story>-<task>-<short-slug>`. When agents work in parallel, work in the epic's own
|
|
94
|
+
worktree of the repo instead (`yad worktree add <epic> --repo <repo>` makes `<repo>--<epic>/` beside it,
|
|
95
|
+
#115): create the task branch there from `origin/<default>`, since the default branch is checked out in
|
|
96
|
+
the main tree. If a branch for this task already exists, reuse it
|
|
53
97
|
rather than forking a second one (one task = one branch).
|
|
54
98
|
|
|
55
99
|
**On the first implement in a repo, install the commit template** (idempotent): copy this skill's
|
|
@@ -59,10 +103,21 @@ choices (`config.yaml` `build.ai_coauthor.allowed`). Do the same at the Product
|
|
|
59
103
|
already configured.
|
|
60
104
|
|
|
61
105
|
### Step 3 — Read the spec inputs (do NOT re-derive the contract)
|
|
62
|
-
Read the story's `spec.md`, `plan.md`, `data-model.md`, and `contracts/` for this task's context.
|
|
106
|
+
Read the story's `spec.md`, `plan.md`, `data-model.md`, and `contracts/` for this task's context. A
|
|
107
|
+
light spec has only `spec.md`: its `## Plan` section is the plan, and it has no contract slice. The
|
|
63
108
|
contract slice is **quoted** from the product repo's locked `contract.md` — implement to it, never
|
|
64
109
|
change it here.
|
|
65
110
|
|
|
111
|
+
**Then ask the batch (#357)** that **Ask the human-only questions first** above describes, before
|
|
112
|
+
writing any code. Read `spec.md`'s `## Clarifications` first: `yad-spec` recorded its answers there.
|
|
113
|
+
Ask only what is still open for THIS task, from its block in `tasks.md`, `plan.md` and the contract
|
|
114
|
+
slice (on a light spec: its block and `## Plan` in `spec.md`). Record the answers in the commit body (Step 6), in a `Decisions:` paragraph above the trailer
|
|
115
|
+
block — not in `spec.md`, which is outside the task's declared files. Until that commit they are on
|
|
116
|
+
no disk, so after a question halt the person gives the answers to the resumed run, which uses them
|
|
117
|
+
and does not ask again. If an answer changes what
|
|
118
|
+
`spec.md`, `plan.md` or `tasks.md` says (a light spec: anything in `spec.md`), that is a spec gap: STOP and re-run `yad-spec`, as for a file
|
|
119
|
+
outside the declared list in Step 4.
|
|
120
|
+
|
|
66
121
|
### Step 4 — Implement the task (dev lens), inside the declared files ONLY
|
|
67
122
|
Adopt the **dev** lens. Implement the task's goal so it satisfies its acceptance criterion, touching
|
|
68
123
|
**only the files in the task's `Files:` list** (≤3 where possible). Write real, working code — tests
|
|
@@ -77,8 +132,8 @@ declared files are wrong is a spec bug, not an implementation decision.
|
|
|
77
132
|
|
|
78
133
|
This stop is a **scope overrun** — a halt condition that pulls in a human regardless of any automation
|
|
79
134
|
dial. When this step is driven by the orchestrator (`yad-run`, Phase 4), the stop must be legible to
|
|
80
|
-
it:
|
|
81
|
-
|
|
135
|
+
it: `yad build step <story> --repo <repo> implement blocked --task <task> --reason "scope overrun: <which file>"`
|
|
136
|
+
(it writes the step's `record`) — and
|
|
82
137
|
surface `scope_overrun: true` so the run records a `rejected` trust entry and halts (it never advances
|
|
83
138
|
past a boundary breach). The same applies to the Step 5 contract-surface stop (`contract_touch: true`).
|
|
84
139
|
|
|
@@ -108,7 +163,9 @@ A contract change means the diff alters the agreed cross-repo shape itself.
|
|
|
108
163
|
to a human**: the work belongs to a new epic on `classic`.
|
|
109
164
|
|
|
110
165
|
### Step 6 — Commit on the task branch
|
|
111
|
-
Stage only the declared files. Commit with the convention: a conventional subject, a short body
|
|
166
|
+
Stage only the declared files. Commit with the convention: a conventional subject, a short body (with
|
|
167
|
+
the `Decisions:` paragraph when Step 3 asked anything — pass the body with `yad commit --body`, as
|
|
168
|
+
`yad ship` takes no body), and a
|
|
112
169
|
`Task: <story>-<task>` trailer (plus `Contract-Change: yes` if Step 5 applies). The human author owns the
|
|
113
170
|
commit; **no `Co-Authored-By:` footer by default** — add one only when the human explicitly asks
|
|
114
171
|
(`yad commit --ai <id>` / the `.gitmessage` choices from `config.yaml` `build.ai_coauthor.allowed`),
|
|
@@ -120,7 +177,8 @@ the result of any test/smoke run, and the next action — the **check gates** (S
|
|
|
120
177
|
then the PR and review (Steps D–E). Do **not** open a PR, merge, or hand-edit the epic's Shape
|
|
121
178
|
`state.json`. Step B ends at a committed task branch.
|
|
122
179
|
|
|
123
|
-
- **Run standalone:** stop here; a human triggers the gates.
|
|
180
|
+
- **Run standalone:** stop here; a human triggers the gates. Before the push, `yad run checks` runs every
|
|
181
|
+
gate on this machine, as CI will.
|
|
124
182
|
- **Run by the orchestrator** (`yad-run`): this skill still just produces the committed branch and
|
|
125
183
|
signals success (or a scope/contract halt). The orchestrator records the `implement` step's status
|
|
126
184
|
and trust entry and, when `implement` is set to `advance: auto` (`yad dial`), **auto-runs
|
|
@@ -135,19 +193,23 @@ finalize a `tasks` trust entry, anchored to what the human/dev actually did with
|
|
|
135
193
|
- the task is **re-scoped** first (its `Files:`/boundary edited) → `approved-with-edits`
|
|
136
194
|
(signal `task_rescoped: true`);
|
|
137
195
|
- the task list is discarded / regenerated → `rejected`.
|
|
138
|
-
|
|
139
|
-
`
|
|
140
|
-
|
|
141
|
-
half-applied `yad tidy up` — so entries are never double-counted). Schema: `../yad-epic/references/state-schema.md`. The record is advice: the `tasks` dial
|
|
196
|
+
Under `yad-run` the run is already recorded: finalize it with
|
|
197
|
+
`yad build trust <story> --repo <repo> tasks --uid <uid> --verdict <v>`, where `<uid>` is `closed.run` on the
|
|
198
|
+
`tasks` step in `build-state/<story>.json`. Never write the shard by hand. Schema: `../yad-epic/references/state-schema.md`. The record is advice: the `tasks` dial
|
|
142
199
|
is whatever the team sets with `yad dial`. (The `implement` step's own verdict is finalized later,
|
|
143
200
|
at the engineer review in `yad-engineer-review`: merged as authored → `approved-unchanged`; edited first →
|
|
144
201
|
`approved-with-edits`; scope/contract/checks halt → `rejected`.)
|
|
145
202
|
|
|
146
203
|
## Hard rules (build plan §B, Cross-cutting)
|
|
147
204
|
|
|
148
|
-
- **One atomic task = one branch = one PR/MR.** Never bundle tasks; never exceed the declared files.
|
|
205
|
+
- **One atomic task = one branch = one PR/MR.** Never bundle tasks; never exceed the declared files. The one
|
|
206
|
+
exception (#350): several SMALL tasks of the same story may share one branch and PR/MR, each commit
|
|
207
|
+
keeping its own `Task:` line, under the Product's `group_limit` (default 200 lines, 10 files) — `yad open-pr`
|
|
208
|
+
warns when a group is over it.
|
|
149
209
|
- **Light loop per task.** Do not re-run the heavy spec ceremony; that already ran once in Step A.
|
|
150
210
|
- **Never widen the contract here.** Surface changes go back to the architecture gate (Step 5).
|
|
211
|
+
- **Human-only decisions are asked first, in one batch** (#357), before any code — never decided by
|
|
212
|
+
the agent.
|
|
151
213
|
- **The step never advances itself.** A scope overrun or contract touch always halts. The
|
|
152
214
|
`implement → checks` hand-off advances only when the orchestrator's `implement` dial is
|
|
153
215
|
`advance: auto` (`yad dial`) — and never past the engineer review, which is always human.
|
|
@@ -25,11 +25,17 @@ for the same task.
|
|
|
25
25
|
|
|
26
26
|
<body — what and why, 1–3 lines>
|
|
27
27
|
|
|
28
|
+
[Decisions:
|
|
29
|
+
- Q: <question> → A: <answer>]
|
|
30
|
+
|
|
28
31
|
Task: <story-id>-<task-id>
|
|
29
32
|
[Contract-Change: yes]
|
|
30
33
|
[Co-Authored-By: <AI name> <email>]
|
|
31
34
|
```
|
|
32
35
|
|
|
36
|
+
- **`Decisions:`** (#357) holds the answers to the human-only questions the skill asked before any
|
|
37
|
+
code (`yad-implement` Step 3). Leave it out when nothing was asked. It is its own paragraph, above
|
|
38
|
+
the trailers, so git never reads it as a trailer.
|
|
33
39
|
- The **`<type>` is lowercase** (`feat`, `fix`, `docs`, `refactor`, `test`, `perf`, `build`, `ci`,
|
|
34
40
|
`chore`, `revert`) and the **`<subject>` starts lowercase**, is **imperative**, and has **no trailing
|
|
35
41
|
period** — Conventional Commits (see `CONTRIBUTING.md` and `config.yaml` `build.commit_subject_style`).
|
|
@@ -68,7 +74,8 @@ Co-Authored-By: CodeRabbit <noreply@coderabbit.ai>
|
|
|
68
74
|
|
|
69
75
|
## File-boundary rule (hard stop)
|
|
70
76
|
|
|
71
|
-
Each task in `tasks.md`
|
|
77
|
+
Each task in `tasks.md` (a light spec: its block between `<!-- yad:tasks -->` and `<!-- /yad:tasks -->`
|
|
78
|
+
in `spec.md`, #348) declares a `Files:` list (≤3 where possible). The implementation diff must stay
|
|
72
79
|
**inside that list**. If the task genuinely needs a file not listed:
|
|
73
80
|
|
|
74
81
|
1. **Stop.** Do not widen the diff silently.
|