yadflow 4.6.0 → 4.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (96) hide show
  1. package/CHANGELOG.md +170 -0
  2. package/README.md +4 -1
  3. package/bin/commands.mjs +5 -1
  4. package/bin/yad.mjs +167 -15
  5. package/cli/artifact-status.mjs +88 -20
  6. package/cli/build.mjs +1372 -0
  7. package/cli/checkpoint.mjs +2 -2
  8. package/cli/commit.mjs +1 -0
  9. package/cli/dial.mjs +21 -1
  10. package/cli/docs.mjs +6 -1
  11. package/cli/doctor.mjs +133 -26
  12. package/cli/epic-state.mjs +357 -9
  13. package/cli/errors.mjs +2 -0
  14. package/cli/find-product.mjs +36 -2
  15. package/cli/fold.mjs +9 -5
  16. package/cli/gate-local.mjs +9 -1
  17. package/cli/gate.mjs +364 -22
  18. package/cli/history.mjs +22 -2
  19. package/cli/hook.mjs +3 -1
  20. package/cli/index-command.mjs +2 -2
  21. package/cli/ledger.mjs +60 -0
  22. package/cli/next.mjs +34 -11
  23. package/cli/openpr.mjs +81 -5
  24. package/cli/platform.mjs +21 -0
  25. package/cli/pr-list.mjs +5 -3
  26. package/cli/product-index.mjs +6 -3
  27. package/cli/product-token.mjs +186 -0
  28. package/cli/productcommit.mjs +33 -0
  29. package/cli/recommend.mjs +3 -1
  30. package/cli/repo-publish.mjs +2 -2
  31. package/cli/run-checks.mjs +586 -0
  32. package/cli/ship-drift.mjs +49 -18
  33. package/cli/standup.mjs +1 -1
  34. package/cli/status.mjs +282 -0
  35. package/cli/test-build.mjs +1559 -0
  36. package/cli/test-run-checks.mjs +603 -0
  37. package/cli/test-worktree.mjs +520 -0
  38. package/cli/thread.mjs +4 -0
  39. package/cli/tidy.mjs +2 -2
  40. package/cli/toolbox.mjs +36 -5
  41. package/cli/workspace.mjs +4 -1
  42. package/cli/worktree-record.mjs +53 -0
  43. package/cli/worktree.mjs +379 -0
  44. package/package.json +3 -3
  45. package/skills/sdlc/config.yaml +1 -1
  46. package/skills/sdlc/module-help.csv +1 -1
  47. package/skills/yad-backfill/templates/checks/backfill-check.sh +9 -9
  48. package/skills/yad-change/SKILL.md +3 -0
  49. package/skills/yad-checks/SKILL.md +34 -5
  50. package/skills/yad-checks/references/check-gates.md +69 -10
  51. package/skills/yad-checks/templates/checks/build-test-lint.sh +22 -3
  52. package/skills/yad-checks/templates/checks/commit-message.sh +8 -2
  53. package/skills/yad-checks/templates/checks/contract-check.sh +61 -33
  54. package/skills/yad-checks/templates/checks/epic-open.sh +87 -14
  55. package/skills/yad-checks/templates/checks/ledger-guard.sh +3 -3
  56. package/skills/yad-checks/templates/checks/lineage-check.sh +88 -15
  57. package/skills/yad-checks/templates/checks/member-check.mjs +206 -35
  58. package/skills/yad-checks/templates/checks/package-manager.sh +41 -4
  59. package/skills/yad-checks/templates/checks/product-checkout.sh +161 -13
  60. package/skills/yad-checks/templates/checks/reconcile-debt-check.sh +94 -15
  61. package/skills/yad-checks/templates/checks/risk-map-check.sh +2 -2
  62. package/skills/yad-checks/templates/checks/spec-link.sh +63 -4
  63. package/skills/yad-checks/templates/checks/verified-commits.sh +23 -5
  64. package/skills/yad-checks/templates/github/yad-checks.yml +8 -8
  65. package/skills/yad-checks/templates/gitlab/.gitlab-ci.yml +3 -0
  66. package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml +4 -4
  67. package/skills/yad-checks/templates/gitlab/yad-product-checks.gitlab-ci.yml +16 -3
  68. package/skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml +5 -1
  69. package/skills/yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml +5 -1
  70. package/skills/yad-commit/SKILL.md +4 -2
  71. package/skills/yad-docs/templates/app/package-lock.json +395 -106
  72. package/skills/yad-docs/templates/app/package.json +2 -2
  73. package/skills/yad-engineer-review/SKILL.md +45 -20
  74. package/skills/yad-engineer-review/references/ship-and-record.md +42 -8
  75. package/skills/yad-epic/references/state-schema.md +75 -16
  76. package/skills/yad-implement/SKILL.md +75 -13
  77. package/skills/yad-implement/references/implement-conventions.md +8 -1
  78. package/skills/yad-implement/templates/.gitmessage +3 -0
  79. package/skills/yad-open-pr/SKILL.md +21 -0
  80. package/skills/yad-pr-template/SKILL.md +6 -2
  81. package/skills/yad-pr-template/templates/checks/pr-template.sh +85 -4
  82. package/skills/yad-pr-template/templates/checks/pr-title.sh +1 -1
  83. package/skills/yad-pr-template/templates/github/pull_request_template.md +1 -1
  84. package/skills/yad-pr-template/templates/gitlab/merge_request_templates/Default.md +1 -1
  85. package/skills/yad-product-bridge/SKILL.md +14 -1
  86. package/skills/yad-product-bridge/references/bridge.md +5 -2
  87. package/skills/yad-product-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml +9 -4
  88. package/skills/yad-reconcile/SKILL.md +9 -3
  89. package/skills/yad-review-gate/SKILL.md +4 -0
  90. package/skills/yad-review-gate/references/gating.md +26 -1
  91. package/skills/yad-run/SKILL.md +52 -28
  92. package/skills/yad-run/references/run-loop.md +42 -21
  93. package/skills/yad-spec/SKILL.md +137 -16
  94. package/skills/yad-spec/references/spec-handoff.md +50 -3
  95. package/skills/yad-status/SKILL.md +7 -0
  96. 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.3",
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.1.3"
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
- - **Record the ship** — write the ship to its own shard
135
- `epics/<epic>/.sdlc/build-log/<story>-<task>-<repo>.json` (readers union the folded `build-log.json` +
136
- the loose shards, deduping by (story, task, repo) so a shard wins over a stale folded ship):
137
- ```json
138
- { "story": "<story>", "task": "<task>", "repo": "<repo>", "branch": "feat/<story>-<task>-…",
139
- "pr": "<url|#>", "mergeCommit": "<sha>", "gates": ["spec-link","contract-check","build-test-lint"],
140
- "ai_review": "coderabbit (advisory)", "engineer_review": [{"approver":"<platform login>","engagement":"<verified|none>"}],
141
- "companion": {"trailer":true,"cards":true,"chat":false}, "risk": "<low|medium|high — the BODY's level>", "shippedAt": "<YYYY-MM-DD>" }
142
- ```
143
- - **Update the story state** — when **every** task in `specs/<story>/tasks.md` has a ship record, set
144
- the story frontmatter `status: shipped`; otherwise `status: in-build`. The chain
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 has a `build-state/<story>.json` (it ran
147
- through `yad-run`), the engineer **confirms or overrides** the provisional trust verdict that the
148
- orchestrator derived for this run, and the final verdict is written back into that run's trust shard
149
- `epics/<epic>/.sdlc/trust-log/<story>-<repo>-implement-<uid>.json` (or, if the run was already folded
150
- by `yad tidy up`, into its entry in the folded `trust-log.json`). The human has the last word on the trust signal: a diff merged
151
- as authored is `approved-unchanged`; one the engineer edited before merge is `approved-with-edits`;
152
- a rejected one is `rejected`. This is the run record `yad dial` shows the team beside a step's dial
153
- (it never weakens the merge gate — the engineer still owns the merge).
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** you just wrote (`approved → in-build/shipped`,
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. **Storage mirrors the trust log's "loose objects + `git gc`"
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": "coderabbit (advisory)",
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": true, "chat": false },
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`) have ship
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
- `build-state/<story-id>.json`, `design-links.json`, `test-links.json` — are written by skills, not by
15
- the CLI. `state.json` is the one both write, so omitting the key there makes the file flip between two
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
 
@@ -134,18 +134,22 @@ also absent by default:
134
134
 
135
135
  ```json
136
136
  { "schemaVersion": 10, "kill": { "on": true, "reason": "bad deploy", "by": "al", "date": "2026-09-15" },
137
- "steps": { "architecture": "auto" } }
137
+ "steps": { "architecture": "auto" }, "actions": { "open-pr": "auto" } }
138
138
  ```
139
139
 
140
140
  `kill` is written by `yad kill --reason "<why>"` / `yad unkill`; while `on`, every step is held at
141
141
  `advance: human`; the record a `yad unkill` or a second `yad kill` replaces is kept as `kill.previous`, one level
142
142
  deep. `steps` lists the feature Shape AUTHOR steps (not the Foundation's) the project set to `auto` with `yad dial <step> --to
143
- auto` — `human` is the key's absence. A Shape `auto` is **recorded, not acted on**: nothing drives a Shape
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
144
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
145
149
  `build-state`. A review gate is never `auto`. A file that will not parse is read as the kill switch ON,
146
150
  and nothing writes over it. `yad doctor` reports a broken file (`automation`), an active switch
147
151
  (`automation:kill`), a gate set to auto (`automation:gate`), a Build step listed here
148
- (`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
149
153
  `_bmad/sdlc/config.yaml`, which nothing reads any more (`automation:legacy-kill`).
150
154
 
151
155
  **When a chain disagrees with the catalogue, the chain wins.** A change-epic seeded by hand before E42
@@ -364,7 +368,7 @@ step is *not* done, and `blocked` is read by whether it has one, so the two neve
364
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 |
365
369
  | `review-opened` | `yad gate open` (local ledger) / `yad gate sync` | An author step, closed when its review opened |
366
370
  | `repair` | `yad gate repair` | A stranded author step — an escape hatch, so it says so |
367
- | `auto` / `human` | the `yad-run` skill, in `build-state` | A Build lane step: the dial let the run go on by itself, or it stopped for a person |
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 |
368
372
 
369
373
  - **Optional keys are left out**, never written as `null`: a close with no PR has no `pr`.
370
374
  - **The first close wins.** A step that already has a `closed` keeps it; a re-sync never rewrites it.
@@ -385,7 +389,7 @@ No release before shape 7 ever wrote a record, so that is exact. The converse is
385
389
  has a verb: `yad unblock EP-<slug> <step>` (E37) moves `status` off `blocked` **and** removes the record
386
390
  in one write, because deleting only the record would turn the step silently into a `todo`. An author
387
391
  step whose earlier steps have all passed goes to `in_progress`; anything else, a review gate included,
388
- goes to `todo`. It never touches `build-state/<story>.json`, which the `yad-run` skill writes. On a verified
392
+ goes to `todo`. It never touches `build-state/<story>.json`, which the `yad build` commands write. On a verified
389
393
  Product it refuses once the epic's ledger is on the default branch: CI owns `state.json` there and has no
390
394
  step for it yet.
391
395
 
@@ -547,6 +551,43 @@ Step debt is **not** `reconcile-debt.json`. That file is a hotfix's whole change
547
551
  thread and is enforced by the `reconcile-debt` CI gate. Step debt is one step of one epic, and it is a
548
552
  reminder, never a gate.
549
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
+
550
591
  ### `test-cases` is a parallel, non-blocking track
551
592
 
552
593
  `test-cases` (and its `test-cases-review` gate) sit in `steps[]` after `stories-review`, but they are a
@@ -577,12 +618,23 @@ The shared procedure (run once the `EP-<slug>` is known):
577
618
  2. Branch name = `<step>/EP-<slug>`. If it already exists, check it out; otherwise create it from the
578
619
  Product's default branch (`git checkout -b <step>/EP-<slug>`).
579
620
  3. Author the step's artifact(s) on that branch, and end the step with `yad fold EP-<slug> <step>` (E44): one
580
- commit, `docs(EP-<slug>): author <step>`, of that step's files only. The drafts stay on the private
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
581
623
  `yad/wip/…` capture branch. With `ledger: local` the epic's ledger changes ride in the same commit;
582
624
  with `ledger: verified` only a brand-new epic's seed does (its ledger is not in HEAD yet), together with
583
625
  its new person-written `.sdlc/` files such as a change-epic's `change.json`. The verified ledger's `review/…` branch is created
584
626
  separately at review time and is untouched by this step.
585
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
+
586
638
  **How the seed reaches the default branch.** The `.sdlc/` ledger is seeded once — by `yad epic new`
587
639
  (or `yad foundation new` for the Product level) — on the **entry** step's authoring branch (`analysis/…`,
588
640
  `epic/…`, `change/…`, `foundation/…`, or `discovery/…` for a product level still in its old spelling).
@@ -595,7 +647,8 @@ gate the ledger is already on the default branch: cut the review branch from the
595
647
  artifact only, and leave `.sdlc/{state,approvals,comments,product-prs,hub-prs}.json` and `reviews/*.md` to CI.
596
648
 
597
649
  ## `approvals.json`
598
- Append-only ledger (an array). Each entry:
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:
599
652
 
600
653
  ```json
601
654
  { "artifact": "epic.md", "step": "epic-review", "approver": "<platform login>", "status": "approved", "date": "<YYYY-MM-DD>", "source": "<bridge, optional>" }
@@ -655,7 +708,8 @@ PR/MR opened on the Product (sibling of `approvals.json`, so the locked `state.j
655
708
  The same array is written under two names, with identical bytes: `product-prs.json` (the name from shape 3,
656
709
  read first) and `hub-prs.json` (the old name, written until v5 and read only when `product-prs.json` is
657
710
  absent — E122). `yad gate sync` may add `nudged`, the logins it has already asked to
658
- 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.
659
713
 
660
714
  ## `design-links.json`
661
715
  Present only when the `ui-design` step materialized the design in a connected design tool
@@ -704,7 +758,8 @@ steps to carry their own advance dial so the orchestrator (`yad-run`) can read i
704
758
  whether to advance on its own. Two new files under `.sdlc/` do this.
705
759
 
706
760
  > **Who commits these.** `build-state/<story-id>.json`, `trust-log.json`, and `build-log.json` are
707
- > **machine-written** by Build (`yad-run`, `yad-engineer-review`) and committed 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
708
763
  > **`yad checkpoint`** — the Build analogue of the Shape `yad gate ci` sync. It lands them as
709
764
  > one `chore(product): sync Build state — <epic>/<story> by @<login>` audit-trail commit, on the
710
765
  > default branch, staging **only** these three ledgers by an explicit allowlist (never a Shape
@@ -741,8 +796,10 @@ Each `steps[]` entry:
741
796
  | `id` | `spec`, `tasks`, `implement`, `checks`, `engineer-review` | Build step identity (the `back_steps` from `config.yaml` + the human merge gate). |
742
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. |
743
798
  | `locked` | `true` \| `false` | `engineer-review` is `true` — it never auto-advances (build plan §E). |
744
- | `closed` | `{ by, date, via, run }` | Written by the `yad-run` skill when it moves the lane past the step: `via` is `auto` or `human`, and `run` names the trust-log run (E18). See "Closing records". |
745
- | `status` | the same **step states** as the Shape chain | Lifecycle. This file is **not** migrated to shape 7 — the `yad-run` / `yad-implement` skills 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. |
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. |
746
803
 
747
804
  `currentStep` is the `id` the orchestrator is waiting on / about to run for that repo. The file is
748
805
  created when a story enters Build; all dials start `advance: human` (`automation: human_approve`) (the `config.yaml`
@@ -807,11 +864,12 @@ back:
807
864
  {
808
865
  "story": "EP-<slug>-S0N",
809
866
  "repo": "backend",
810
- "step": "checks",
867
+ "step": "implement",
811
868
  "uid": "<short-unique-token>",
869
+ "task": "T01",
812
870
  "automation": "human_approve", "advance": "human",
813
871
  "verdict": "approved-unchanged",
814
- "signals": { "checks": "pass", "human_edited_diff": false, "scope_overrun": false, "contract_touch": false },
872
+ "signals": { "human_edited_diff": false, "scope_overrun": false, "contract_touch": false },
815
873
  "ranBy": "machine",
816
874
  "date": "<YYYY-MM-DD>",
817
875
  "note": "<optional>"
@@ -826,6 +884,7 @@ back:
826
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. |
827
885
  | `signals` | object | The raw inputs the provisional verdict was derived from. The fields present depend on the step (table below). |
828
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>`). |
829
888
 
830
889
  **Per-step `signals` fields** (only the relevant ones are set; others may be omitted or `n/a`):
831
890
 
@@ -834,7 +893,7 @@ back:
834
893
  | `spec` | `human_edited_spec` | the human who accepts `specs/<story>/` (`yad-spec` Step 8) |
835
894
  | `tasks` | `task_rescoped` | first consume by `yad-implement` (Step 8) |
836
895
  | `implement` | `human_edited_diff`, `scope_overrun`, `contract_touch` | engineer review at `yad-engineer-review` |
837
- | `checks` | `checks` (`pass`\|`fail`) | the gate run itself (objective) |
896
+ | `checks` | `checks` (`pass`\|`fail`\|`n/a`) | the gate run itself (objective) |
838
897
 
839
898
  **Deriving the provisional verdict** (build plan Step A; extended for `spec`/`tasks` in Phase 4b — the
840
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`. Find the block for `<task>` (`## <task> — …`). Read
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`, STOP. Confirm the spec exists (Step A ran); if not,
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>`. If a branch for this task already exists, reuse it
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. The
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: mark the `implement` step `status: blocked` in `build-state/<story>.json` — **with a `record`**,
81
- `{ "reason": "scope overrun: <which file>", "by": "<login or null>", "date": "<YYYY-MM-DD>" }` — and
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, and a
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
- Write the entry to its own shard `epics/<epic>/.sdlc/trust-log/<story>-<repo>-tasks-<uid>.json` (a fresh
139
- `uid` per run, so concurrent writers never conflict; readers union the folded `trust-log.json` + the
140
- loose shards, skipping any shard whose full `(story, repo, step, uid)` already appears folded — a
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` declares a `Files:` list (≤3 where possible). The implementation diff must stay
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.
@@ -3,6 +3,9 @@
3
3
  #
4
4
  # <body — what changed and why, 1–3 lines. Wrap at ~72 cols.>
5
5
  #
6
+ # Decisions: # ONLY if the skill asked human-only questions first (#357) —
7
+ # - Q: <question> → A: <answer> # its own paragraph, above the trailers
8
+ #
6
9
  # --- Trailers (keep them in ONE contiguous block below, no blank lines between) ---
7
10
  # Task: is REQUIRED — it anchors the spec-link gate. Order: Task -> Contract-Change -> Co-Authored-By.
8
11
  Task: <EP-slug-S0N-T0N>