yadflow 4.6.0 → 4.8.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 (136) hide show
  1. package/CHANGELOG.md +259 -0
  2. package/README.md +46 -4
  3. package/bin/commands.mjs +9 -2
  4. package/bin/yad.mjs +309 -30
  5. package/cli/agent-guard.mjs +511 -0
  6. package/cli/agent-guide.mjs +83 -0
  7. package/cli/agent-rules.mjs +381 -0
  8. package/cli/argv-flags.mjs +7 -0
  9. package/cli/artifact-status.mjs +88 -20
  10. package/cli/build.mjs +1372 -0
  11. package/cli/checkpoint.mjs +2 -2
  12. package/cli/ci-check.mjs +492 -0
  13. package/cli/commit.mjs +1 -0
  14. package/cli/dial.mjs +21 -1
  15. package/cli/docs.mjs +7 -2
  16. package/cli/doctor.mjs +176 -33
  17. package/cli/epic-state.mjs +360 -12
  18. package/cli/errors.mjs +3 -0
  19. package/cli/find-product.mjs +36 -2
  20. package/cli/fold.mjs +9 -5
  21. package/cli/gate-local.mjs +9 -1
  22. package/cli/gate.mjs +364 -22
  23. package/cli/guide.mjs +549 -0
  24. package/cli/history.mjs +22 -2
  25. package/cli/hook.mjs +35 -4
  26. package/cli/index-command.mjs +2 -2
  27. package/cli/ledger.mjs +60 -0
  28. package/cli/lib.mjs +46 -0
  29. package/cli/lifecycle/defaults/2.json +124 -0
  30. package/cli/lifecycle/lifecycle.schema.json +5 -2
  31. package/cli/lifecycle.mjs +16 -3
  32. package/cli/manifest.mjs +75 -0
  33. package/cli/marked-block.mjs +48 -0
  34. package/cli/members.mjs +19 -5
  35. package/cli/migrate.mjs +17 -19
  36. package/cli/next.mjs +35 -12
  37. package/cli/openpr.mjs +81 -5
  38. package/cli/plan.mjs +326 -22
  39. package/cli/platform.mjs +21 -0
  40. package/cli/pr-list.mjs +5 -3
  41. package/cli/product-index.mjs +6 -3
  42. package/cli/product-token.mjs +186 -0
  43. package/cli/productcommit.mjs +33 -0
  44. package/cli/protection.mjs +50 -0
  45. package/cli/recommend.mjs +3 -1
  46. package/cli/reconcile.mjs +187 -26
  47. package/cli/repo-publish.mjs +2 -2
  48. package/cli/report.mjs +62 -14
  49. package/cli/run-checks.mjs +586 -0
  50. package/cli/setup.mjs +244 -25
  51. package/cli/ship-drift.mjs +49 -18
  52. package/cli/signing.mjs +377 -0
  53. package/cli/standup.mjs +1 -1
  54. package/cli/status.mjs +282 -0
  55. package/cli/test-agents-file.mjs +993 -0
  56. package/cli/test-build.mjs +1559 -0
  57. package/cli/test-ci-check.mjs +616 -0
  58. package/cli/test-guide.mjs +1267 -0
  59. package/cli/test-node.mjs +129 -0
  60. package/cli/test-run-checks.mjs +603 -0
  61. package/cli/test-setup-agent.mjs +352 -0
  62. package/cli/test-signing.mjs +524 -0
  63. package/cli/test-worktree.mjs +520 -0
  64. package/cli/thread.mjs +4 -0
  65. package/cli/tidy.mjs +2 -2
  66. package/cli/toolbox.mjs +37 -6
  67. package/cli/update-commit.mjs +313 -11
  68. package/cli/workspace.mjs +38 -10
  69. package/cli/worktree-record.mjs +53 -0
  70. package/cli/worktree.mjs +379 -0
  71. package/package.json +6 -4
  72. package/skills/sdlc/config.yaml +5 -5
  73. package/skills/sdlc/module-help.csv +2 -1
  74. package/skills/yad-backfill/templates/checks/backfill-check.sh +9 -9
  75. package/skills/yad-change/SKILL.md +5 -1
  76. package/skills/yad-checks/SKILL.md +61 -12
  77. package/skills/yad-checks/references/check-gates.md +78 -14
  78. package/skills/yad-checks/templates/checks/build-test-lint.sh +22 -3
  79. package/skills/yad-checks/templates/checks/commit-message.sh +8 -2
  80. package/skills/yad-checks/templates/checks/contract-check.sh +61 -33
  81. package/skills/yad-checks/templates/checks/epic-open.sh +87 -14
  82. package/skills/yad-checks/templates/checks/ledger-guard.sh +3 -3
  83. package/skills/yad-checks/templates/checks/lineage-check.sh +88 -15
  84. package/skills/yad-checks/templates/checks/member-check.mjs +206 -35
  85. package/skills/yad-checks/templates/checks/package-manager.sh +42 -5
  86. package/skills/yad-checks/templates/checks/product-checkout.sh +161 -13
  87. package/skills/yad-checks/templates/checks/reconcile-debt-check.sh +94 -15
  88. package/skills/yad-checks/templates/checks/risk-map-check.sh +2 -2
  89. package/skills/yad-checks/templates/checks/spec-link.sh +63 -4
  90. package/skills/yad-checks/templates/checks/verified-commits.sh +23 -5
  91. package/skills/yad-checks/templates/github/yad-checks.yml +9 -9
  92. package/skills/yad-checks/templates/gitlab/.gitlab-ci.yml +4 -1
  93. package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml +5 -5
  94. package/skills/yad-checks/templates/gitlab/yad-product-checks.gitlab-ci.yml +16 -3
  95. package/skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml +5 -1
  96. package/skills/yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml +5 -1
  97. package/skills/yad-checks/templates/hooks/agent-guard.mjs +116 -0
  98. package/skills/yad-commit/SKILL.md +8 -5
  99. package/skills/yad-connect-repos/SKILL.md +5 -3
  100. package/skills/yad-connect-repos/references/code-context.md +2 -1
  101. package/skills/yad-connect-repos/references/repos-registry.md +2 -1
  102. package/skills/yad-docs/templates/app/package-lock.json +395 -106
  103. package/skills/yad-docs/templates/app/package.json +2 -2
  104. package/skills/yad-docs-overview/references/pipeline-model.md +2 -2
  105. package/skills/yad-engineer-review/SKILL.md +55 -25
  106. package/skills/yad-engineer-review/references/ship-and-record.md +49 -12
  107. package/skills/yad-epic/SKILL.md +2 -1
  108. package/skills/yad-epic/references/state-schema.md +76 -17
  109. package/skills/yad-guide/SKILL.md +192 -0
  110. package/skills/yad-implement/SKILL.md +75 -13
  111. package/skills/yad-implement/references/implement-conventions.md +8 -1
  112. package/skills/yad-implement/templates/.gitmessage +3 -0
  113. package/skills/yad-open-pr/SKILL.md +21 -0
  114. package/skills/yad-pair-review/SKILL.md +14 -5
  115. package/skills/yad-pr-template/SKILL.md +6 -2
  116. package/skills/yad-pr-template/templates/checks/pr-template.sh +85 -4
  117. package/skills/yad-pr-template/templates/checks/pr-title.sh +1 -1
  118. package/skills/yad-pr-template/templates/github/pull_request_template.md +1 -1
  119. package/skills/yad-pr-template/templates/gitlab/merge_request_templates/Default.md +1 -1
  120. package/skills/yad-product-bridge/SKILL.md +44 -12
  121. package/skills/yad-product-bridge/references/bridge.md +11 -5
  122. package/skills/yad-product-bridge/templates/github/yad-gate-sync.yml +2 -2
  123. package/skills/yad-product-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml +9 -4
  124. package/skills/yad-reconcile/SKILL.md +9 -3
  125. package/skills/yad-report/SKILL.md +15 -0
  126. package/skills/yad-review-companion/SKILL.md +5 -3
  127. package/skills/yad-review-gate/SKILL.md +16 -8
  128. package/skills/yad-review-gate/references/gating.md +26 -1
  129. package/skills/yad-run/SKILL.md +61 -33
  130. package/skills/yad-run/references/run-loop.md +44 -22
  131. package/skills/yad-spec/SKILL.md +137 -16
  132. package/skills/yad-spec/references/spec-handoff.md +50 -3
  133. package/skills/yad-status/SKILL.md +7 -0
  134. package/skills/yad-stories/references/story-schema.md +1 -1
  135. package/skills/yad-sync-repos/SKILL.md +2 -1
  136. package/skills/yad-ui/SKILL.md +2 -2
@@ -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
  }
@@ -56,8 +56,8 @@ auto-seeds epics. A product created before E75 may still hold the old spelling,
56
56
  yad-run and the docs skills; `6-change` holds yad-change, yad-stub, yad-timeline, yad-defects and
57
57
  yad-reconcile; yad-status (a read-only view) and yad-learn (a tutor for any stage) are `anytime`, the
58
58
  value for a skill available at every stage — they are listed under
59
- Automation below only because the site needs one place to draw them. yad-report has no phase: it is
60
- a CLI helper, not a pipeline step.
59
+ Automation below only because the site needs one place to draw them. yad-report and yad-guide have no
60
+ phase: one is a CLI helper and the other the rules an AI agent follows, not pipeline steps.
61
61
  Moving three of these from `1-front` needed no migration, and that does not contradict the note
62
62
  above: module-help.csv is catalogue content the tool ships, read from the package's skills/sdlc/ folder
63
63
  and never installed into a project. It is not state a user's project stores. The note above is about
@@ -126,37 +126,67 @@ the gate talks only through files; refuse to treat AI review as a human approval
126
126
  ### Step 3 — `ship` (merge + record + update state)
127
127
  Ship **iff ALL hold**: the check gates pass (Step C), the AI review has run (advisory), and the
128
128
  engineer-review rule is satisfied (Step 2). Then:
129
- - **Merge** the task branch into the repo's default branch (the human performs/authorises the merge).
129
+ - **Merge** the task branch into the repo's default branch. The person merges it, never you, even when
130
+ your login could (E158): give them the PR/MR link, wait, then confirm by reading
131
+ (`yad build merged … --ship`).
130
132
  - **Check the lane is not skipped (E39)** — read `build-state/<story>.json`. If this repo's lane is
131
- `status: skipped`, it was set aside as needing no change: stop, and run
132
- `yad unskip <epic> <story> --repo <repo>` before recording a ship, so the two records never say opposite
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
133
+ `status: skipped`, it was set aside as needing no change: stop and tell the person. Only when they say
134
+ the lane is owed after all, run `yad unskip <epic> <story> --repo <repo>` before recording a ship
135
+ (E158), so the two records never say opposite things (`yad doctor` fails that as `lane:…:contradiction`; `yad checkpoint --retro-ship` refuses it).
136
+ - **See whether it merged — ask, do not wait (#355).** The merge is a person's, but you do not need them
137
+ to tell you it happened: run `yad build merged <story> --task <task> --repo <repo> --ship`. It asks the
138
+ platform about the task's PR/MR (found by its branch; `--pr <n>` names it) and answers one `state`
139
+ (`--json`): `merged` — the ship is recorded (through `yad build ship`), go on; `shipped` — it already was;
140
+ `open` — stop and report "waiting for PR/MR #<n> to merge", and run it again when you resume; `closed`
141
+ — closed without a merge: stop and report it; `none` — no PR/MR carries the task yet: open one with
142
+ `yad open-pr`. It asks once and returns; it never waits. It refuses where the platform cannot be read
143
+ (no platform, the repo not cloned here, `gh`/`glab` not logged in), when two PRs/MRs that are not
144
+ closed carry the task, or when a merged PR's merge commit is not on the default branch or names
145
+ another task, or its ship file cannot be written — stop and report what it says.
146
+ - **A follow-up to a shipped task (#350)** — open it from `fix/<story>-<task>-followup-<words>`, its commits
147
+ keeping the task's `Task:` line. Ask about it with `yad build merged <story> --task <task> --repo <repo>
148
+ --follow-up --ship`: the same states, and once merged its merge is added to the task's ship
149
+ (`followUps`), never a second ship. Shape: `references/ship-and-record.md`.
150
+ - **Catch up on merges (#365)** — `yad build sync [<epic>]` records every ship the code repos already show
151
+ (what `yad reconcile check` finds merged with no ship), through `yad build ship`, then `yad build done`
152
+ for each story now fully shipped; it lists what it cannot record. Then ask the person before
153
+ `yad checkpoint --push`: it pushes to the default branch, which is asked about every time (E158).
154
+ - **Record the ship** — `yad build ship <story> --task <task> --repo <repo> --pr <n>` (what `--ship` runs),
155
+ once the PR/MR has merged. A grouped PR (#350) — several small tasks of one story — ships each task it
156
+ 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
157
+ engagement signal), the body's `Risk level:` and the merge date from the platform, refuses a PR that is
158
+ not merged or that comes from another task's branch, and writes the ship to its own shard
159
+ `epics/<epic>/.sdlc/build-log/<story>-<task>-<repo>.json` (shape: `references/ship-and-record.md`). A
160
+ repo whose platform cannot be read records it by hand: `--merge-commit <sha> --approver <login>`, only with
161
+ the merge commit and approvers the person gave you, never guessed (E158). A
162
+ task merged with no PR/MR: `--merge-commit <sha>` and no `--pr` (the commit must be on the default
163
+ branch and name the task in its `Task:` trailer or subject; the platform is asked whether a PR merged it,
164
+ and a PR that did is named instead). It moves the story to `in-build`. Never write the shard by hand.
165
+ - **Update the story state** — when **every** task in each repo's `specs/<story>/tasks.md` (a light spec: the marked tasks block of its
166
+ `spec.md`, #348) has a ship,
167
+ run `yad build done <story>`: it checks that, closes the `engineer-review` step in each lane, and sets
168
+ the story `status: shipped`, so `yad next`, the epic seal and `yad tidy` all read it shipped. It needs
169
+ 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
170
+ each repo whose earlier steps are done (a story that never ran through `yad-run`: `yad build start`,
171
+ then `yad build step … done` for each step; one shipped before the Build ledger existed:
172
+ `yad checkpoint --retro-ship`). It refuses, writing nothing, and says what is missing. The chain
145
173
  **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).
154
- - **Commit the machine-written ledgers.** Run `yad checkpoint --push` from `{project-root}` to commit
174
+ - **Finalize the trust verdict (Phase 4).** If this story ran through `yad-run`, the engineer **confirms or
175
+ overrides** the provisional trust verdict the orchestrator recorded for the `implement` run:
176
+ `yad build trust <story> --repo <repo> implement --uid <uid> --verdict <v>`, where `<uid>` is the run of
177
+ this task on the `implement` step in `build-state/<story>.json`: `closed.run` when `closed.task` is this
178
+ task, else the `run` of the entry in its `runs` list whose `task` is this task. It updates that run where it lives
179
+ (its shard, or its entry in the folded `trust-log.json` after `yad tidy up`). The human has the last
180
+ word on the trust signal: a diff merged as authored is `approved-unchanged`; one the engineer edited
181
+ before merge is `approved-with-edits`; a rejected one is `rejected`. This is the run record `yad dial`
182
+ shows the team beside a step's dial (it never weakens the merge gate — the engineer still owns the merge).
183
+ - **Commit the machine-written ledgers.** Ask the person, then run `yad checkpoint --push` from `{project-root}`
184
+ (a push to the default branch is asked about every time, E158) to commit
155
185
  the Build ledgers just written (the `build-log/` shard, and the `trust-log/` shard /
156
186
  `build-state/<story>.json` if the story ran through `yad-run`) as one `chore(product): …` audit-trail
157
187
  commit — default branch only, staging the shard dirs (`yad tidy up` folds finished shards later),
158
188
  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`,
189
+ same commit also **carries the story `status:` flip** the commands wrote (`approved → in-build/shipped`,
160
190
  #112) — because that story now has a build-log ship, checkpoint stages `stories/<story>.md` alongside
161
191
  the ledgers, so the artifact never drifts from build-log and you never fall back to a raw git-to-main
162
192
  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,26 +61,49 @@ 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),
72
- not by hand: after recording the ship, `yad checkpoint --push` lands the new `build-log/` shard as a
106
+ not by hand: after recording the ship, `yad checkpoint --push` (after the person's yes, E158) lands the new `build-log/` shard as a
73
107
  `chore(product): …` audit-trail commit on the default branch (allowlist-scoped to the Build ledgers,
74
108
  never a Shape gate file); `yad tidy up` folds finished shards into `build-log.json` later.
75
109
 
@@ -79,7 +113,8 @@ A story that was merged and shipped **before** the Build ledger existed has no b
79
113
  `yad checkpoint` can't carry its `status: shipped` flip (the flip is only carried when a ship backs it,
80
114
  #112) — leaving a raw `git push origin main` as the only way to land it, against the never-raw-git
81
115
  convention. To reconcile it through yad, record a **retroactive** ship, then checkpoint carries the flip
82
- in the same commit:
116
+ in the same commit. Record one only when the person asked for a retroactive ship, and ask every time
117
+ before `--push`: it lands on the default branch (E158).
83
118
 
84
119
  ```
85
120
  yad checkpoint --retro-ship <epic>/<story> --repo <r> [--task <t>] [--merge-commit <sha>] [--push]
@@ -102,7 +137,8 @@ indefinitely — which is precisely why reading the folded file alone is never s
102
137
 
103
138
  **One repo per run (#166).** A ship is recorded per `(story, task, repo)`, so a story that shipped in
104
139
  several repos needs one retroactive shard **per repo** — the guard is keyed on `(story, repo)`, not on
105
- the story alone, so recording the first repo never locks out the rest. Re-run once per repo:
140
+ the story alone, so recording the first repo never locks out the rest. Re-run once per repo, asking
141
+ before each `--push`:
106
142
 
107
143
  ```
108
144
  yad checkpoint --retro-ship EP-foo/EP-foo-S01 --repo web --push
@@ -146,13 +182,14 @@ decides machine safety, the merge is still the human act.
146
182
 
147
183
  The story frontmatter `status` reflects build progress:
148
184
 
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.
185
+ - `in-build` — at least one, but not all, of the story's tasks (from `specs/<story>/tasks.md`, or the
186
+ marked tasks block of a light spec's `spec.md`, #348) have ship records.
187
+ - `shipped` — **every** task in `tasks.md` (or the light spec's tasks block) has a ship record.
152
188
 
153
189
  You write this flip into `stories/<story>.md`, but **do not hand-commit it** — the next
154
190
  `yad checkpoint --push` carries it in the same `chore(product)` commit as the ledgers (the story now has a
155
- build-log ship, so checkpoint stages it; #112). This is what keeps the story artifact from drifting
191
+ build-log ship, so checkpoint stages it; #112; it pushes to the default branch, so an AI agent asks the
192
+ person first, every time, E158). This is what keeps the story artifact from drifting
156
193
  from the build ledger, so there is never a reason to fall back to a raw `git push origin main`.
157
194
 
158
195
  So the chain is traceable both ways: from the epic down (`epic.md` → `stories/<story>.md` →
@@ -229,7 +229,8 @@ Notes:
229
229
  every later change to it is CI's. See `references/state-schema.md`, "Authoring branches".
230
230
  - **No UI?** Seed the chain **as-is** (the two `ui-design` steps are always in it). If this epic has no
231
231
  user-facing surface (a backend/API service, data pipeline, infra), the `ui-design` step is optional
232
- and can be marked N/A now with `yad skip EP-<slug> ui-design --reason "<why>"` — it stays visible,
232
+ and can be marked N/A now: offer it, and on the person's yes run `yad skip EP-<slug> ui-design --reason "<why>"` (a
233
+ skip is the person's decision, E158) — it stays visible,
233
234
  short-circuits its gate, and advances straight to `stories` when architecture is approved. It is
234
235
  reversible with `yad unskip EP-<slug> ui-design` until the stories review opens. **On a verified Product, now is the only time:** once this epic's first review PR merges, CI owns `state.json` and `yad skip` refuses. Don't hand-edit the chain to drop the steps;
235
236
  the skip is the single, auditable mechanism (see `references/state-schema.md` → "ui-design is optional").
@@ -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
 
@@ -96,7 +96,7 @@ Each `steps[]` entry:
96
96
  ### The step catalogue
97
97
 
98
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):
99
+ `cli/lifecycle/defaults/2.json` (E134; 2.json added each step's description and driver, E157). The engine reads it as `STEPS` in `cli/epic-state.mjs` (E4):
100
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
101
101
  writes, which skill runs it, and — for a gate — which step it reviews. The phase table, the skill
102
102
  tables and the Build order are all views of it, held to it by tests, so a step cannot exist in one and
@@ -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):